Skip to content
synthetosPublic

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,081 Commits

Folders and files

Repository files navigation

run

run.synthetos.com

The browser workspace for Synthetos CNC controllers: configure the board, draw and check wiring, flash vetted firmware, and send G-code to run real jobs, from desktop Chrome or Edge over Web Serial, tied to a Synthetos account.

Status: Phase 0 (foundations). Nothing in this repository can open a serial port or move a machine. Packages are filled in task by task; so far protocol has inbound framing and classification (P0-07) and the dialect data, read-only capability probe, capability classifier and reviewed supported-version list (P0-08), and schema has the board definition schema and board selection (P0-08) and, from the vendored TinyG HIL tables, the per-dialect status tables and settings schemas, the read allowlists, the forbidden writes, the edge-next settings overlay, validate and the write-plan gate (P0-09); safety has the job sanitiser with long-move splitting, the allow-matrix, the overrun bound and the host-gate rule (P0-10); testkit has the virtual clock, the edge-next and 440.21 firmware models, fault plans, MockSerialPort and ReplayTransport (P0-11, dev only); machine has the Transport interface, GuardedTransport and the open policy, with no Web Serial transport yet (P0-12); the bundle scan refuses test-kit code, transport= handling, URL schemes and Web Serial in the build (P0-13); and machine.worker runs under Playwright through a test-only fake-serial build (P0-14). The repository, gates, CI workflow, Worker, pages and E2E job (P0-01 to P0-06) are in place locally. The findings of the independent Phase 0 review have fix commits with regressions; the sanitiser, firmware-model and probe fixes are independently re-verified, and the gate and deploy fixes are awaiting re-verification. P0-15 (first deploy and the run-v0.1.0 tag) is not done: there is no GitHub remote or Cloudflare deployment yet, and the owner decisions D39 and D40 are still to be carried into the gates. The owner's steps are on the ops pages (docs/ops/): the account (account.md), branch protection (branch-protection.md), the public staging host (access.md), the Worker (worker.md) and firmware sources (firmware-sources.md).

This software is not an emergency stop. Any machine it drives must have a hardwired, latching E-stop that removes motor and spindle power in hardware. Read the safety contract before connecting a machine: it is SAFETY.md in this repository, and is the /safety/ page of the app.

Contributor rule: keep modules small and focused. See modularity limits and the ratchet before changing source.

Layout

Path Role
packages/protocol Framing, inbound classification, dialect data, capability probe and classifier, reviewed supported-version list
packages/safety Allow-matrix, sanitiser, preflight, jog plan, flash gate, fault policy, overrun bound, warning strings
packages/machine Transport interface, MachineSession (the single writer), flow engines, streamer, watchdog, stop sequences
packages/schema Units, generated settings schemas and status tables, read allowlists and forbidden writes (keyed by DialectId), the edge-next overlay, board definitions; MachineProfile v2 and the fact engine later
packages/gcode G-code parser and dialect-aware interpreter and analyser
packages/flasher Firmware manifest, HEX validation, xboot client
packages/wiring Board data, components, rules engine, renderers
packages/provenance Device-local trust anchor and authorship decisions (pure)
packages/contracts API types and valibot schemas shared by the web app and the Worker
packages/library Tool, material, stock, fixture and store-product records: schemas and validation, external link sanitising, versioning and forking, built-in seed data (docs/design/MACHINING_ASSISTANT.md §2-§4)
packages/advisor Feeds and speeds: the deterministic rules model, achievable-feed estimate, live chipload estimator, the override envelope, and the AdvisorEngine seam with RulesEngine and MockAiEngine (§5, §6)
packages/testkit Dev only. Firmware models and fakes for tests; never in a production bundle
apps/web The workspace UI (Preact, Vite multi-page app)
apps/cli Bench tooling (Node)
workers/run The Cloudflare Worker serving the app, /api/* and /auth/*, and the single source of the security headers (src/headers.ts)
firmware Local simulator images and legacy release fixtures; live releases come from GitHub through the Worker (docs/ops/firmware-sources.md)
vendor firmware-pins.json: the firmware commits every protocol citation is pinned to (PIN-1); tinyg-hil-tables/: the TinyG token and status tables generated by the HIL harness (den.json edge-next, d440.json 440.21, d449.json stock edge-0.97 for the read-only dialect), the single source of the generated schema tables (pnpm gen:schema; see its README)
test-fixtures Captured controller output used by tests: forum-json/ (lines quoted in the archived forum, with source URLs) and en-hil/ (TinyG edge-next HIL harness transcripts)
tools/gates Dev only. The repository's lint rules, the licence gate, the gate acceptance tests, and the deploy tools (preflight, asset retention, smoke test)
tools/e2e Dev only. Playwright against wrangler dev, serving the local build (pnpm e2e) or the attested artifact (pnpm e2e:artifact, the CI e2e job): exact headers, CSP enforcement, Trusted Types, and the origin guard on every test, plus the third-party canary. fake-serial/ is the test-only replacement for the machine worker's transport seam, and *.fake-serial.ts specs run against that build (pnpm e2e:fake-serial, P0-14)

Dependency rules

  • protocol, safety, machine, schema, flasher and provenance have no runtime npm dependencies and never import network APIs, contracts or the cloud client.
  • library and advisor (the machining assistant, docs/design/MACHINING_ASSISTANT.md §9) have no runtime npm dependencies, use no network API, are deterministic (no Math.random, no clock) and never reach machine, protocol, safety, contracts, the cloud client or any app.
  • The cloud client (apps/web/src/cloud) imports only contracts and provenance, so never machine, protocol or safety, and the safety path never imports it.
  • workers/run imports only contracts. The server holds no machine logic.
  • No production entry may import testkit.
  • Packages are layered (RUN_PLAN §5.3): protocol imports no other workspace package; safety imports protocol; schema imports protocol and safety; machine imports protocol, safety, schema and the flasher entry; flasher imports protocol; gcode, wiring and provenance import safety and protocol; contracts imports no workspace package; testkit imports protocol and flasher. No import cycle anywhere in packages/. library imports only schema's JSON Schema validator; advisor imports library and that validator. Runtime workspace edges are dependencies (workspace:*), so the production build graph (--filter-prod) never includes the test kit.
  • Panels act only through typed intents checked by safety.allowed; no code outside MachineSession writes to the port, and nothing is loaded at runtime.

These rules are enforced by the gates below (P0-02, P0-03, P0-13).

Gate Command What it enforces
Boundaries pnpm deps .dependency-cruiser.cjs: the package layering above (layer-* rules) and no-circular; no npm (direct or transitive) and no Node built-ins in the safety path; no contracts or cloud client in the safety path; the cloud client imports only its own modules, contracts and provenance, and no chain of imports from it reaches machine, flasher, schema, gcode, wiring, testkit or any other web-app module (protocol and safety only through provenance); workers/run imports only contracts; library and advisor have no npm or Node built-in and reach no machine-path package, contracts, app or Worker (assistant-*); no entry reaches testkit; nothing imports from outside the repository; every import resolves. Then tools/gates/src/source/cli.ts parses every runtime source file and refuses what dependency-cruiser cannot see: a computed or reflective capability lookup (capability-lookup) and an import() with a computed specifier (dynamic-import)
Lint pnpm lint eslint.config.js with the repository's own rules in tools/gates/src/eslint/: no eval/new Function; no HTML sinks (innerHTML, outerHTML, insertAdjacentHTML, dangerouslySetInnerHTML) outside apps/web/src/security/tt.ts; no abort in machine; no Math.random in safety and protocol, and no Math.random, Date.now or performance.now in library and advisor; no network identifiers in protocol, safety, machine, flasher, provenance, schema, library and advisor; in runtime source, navigator only as a static read of a reviewed data property, window aliases only with static keys, no Reflect (run/no-capability-lookup; the test kit is exempt) and no import() with a computed specifier (run/no-dynamic-import); no navigator.serial, requestPort or getPorts anywhere except packages/machine/src/webSerialTransport.ts, which may read navigator.serial statically and nothing more (P1-00; its tests are not exempt); no WARNING —, DANGER — or NOTICE — strings outside packages/safety/src/strings.ts. Inline eslint-disable comments are ignored (noInlineConfig), so a rule can be relaxed only in eslint.config.js
Licences pnpm licence Production dependencies: MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0 or OFL-1.1. Dev dependencies may also be MPL-2.0, or carry a reviewed exception in tools/gates/src/licence/exceptions.ts. GPL and AGPL dependencies are never allowed (run itself is AGPL-3.0-or-later; see Licence)
CI policy pnpm ci-policy Workflows: only the deploy jobs touch secrets or the Cloudflare token; deploy jobs run only on a push to main behind protected environments; actions pinned by SHA; no pull_request_target; no ${{ }} in scripts. CODEOWNERS covers every SAFETY §8 path. The PR template carries the SAFETY §8 checklist verbatim
Bundle scan pnpm scan (after a build) No origin literal, //host, javascript: URL or network identifier in apps/web/dist outside the cloud-client chunks (assets/cloud/, decided by content in apps/web/build/chunks.ts); the static-assets _headers file present and identical to what workers/run/src/headers.ts renders. Anywhere in the bundle (P0-13, T-S40): no test-kit marker, MockSerialPort, transport= query handling, URL scheme other than relative, data: and blob:, or Web Serial (navigator.serial, requestPort, getPorts); in code, no computed or reflective capability lookup and no import() with a computed specifier; see docs/ops/ci.md
Reproducible build pnpm repro Clones HEAD twice, installs only the build toolchain, builds both and fails unless they are byte-identical, then scans

pnpm gates runs lint, boundaries, licences and the CI policy. tools/gates/test/acceptance.test.ts proves each gate fails on a violation: it copies the working tree, introduces one violation, runs the real gate command and checks which rule caught it.

A change to .dependency-cruiser.cjs, eslint.config.js, tools/gates/, .github/ or apps/web/build/ changes the safety boundary and needs safety-path review (.github/CODEOWNERS).

CI and deploys

.github/workflows/ci.yml runs these jobs:

  • verify, secret-free;
  • build, secret-free: the minimal build toolchain, two clean builds that must match byte for byte, and the bundle scan;
  • e2e;
  • e2e-fake-serial: the fake-serial test build, checked against the artifact, then its own Playwright suite (docs/testing/fake-serial.md);
  • attest, which signs build provenance;
  • deploy-staging and deploy-production, which run on main only, behind protected environments, and deploy only the attested artifact, then run the post-deploy smoke test.

The Worker, its headers, the public staging host (OD-40) and the locked-down Cloudflare account (D39): docs/ops/worker.md, docs/ops/access.md, docs/ops/account.md.

Pull requests that touch safety paths must carry the SAFETY §8 checklist and a recorded independent review bound to the head commit (safety-review, D40: no approvals while there is a single maintainer, two once a second one joins; docs/safety/reviews/README.md).

See docs/ops/ci.md for how it works, and docs/ops/branch-protection.md for the GitHub settings the owner must enable. SAFETY.md is the in-repo copy of the safety case.

Development

Requirements: Node.js 22.18 or later (it runs the TypeScript gate and bench scripts directly, with type stripping), and pnpm via Corepack (the exact version is pinned in package.json packageManager).

corepack enable            # or prefix commands with `corepack`
pnpm install --frozen-lockfile --ignore-scripts
pnpm -r typecheck
pnpm gates                 # lint, dependency-cruiser, licences
pnpm -r test
pnpm --filter web build

pnpm check runs typecheck, the gates, tests, the build and the bundle scan in that order, then the fake-serial test build and its diff against the production build, then the localhost bench build and its check (bench scan, and "only the build-channel chunk differs"; P1-00). pnpm e2e builds and runs the Playwright suite against wrangler dev (RUN_SCREENSHOTS=1 also writes the review screenshots to docs/design/screenshots/p0-05/). pnpm e2e:artifact does what the CI e2e job does: it assembles and verifies an artifact, runs the suite against wrangler dev serving it, and runs the third-party canary (docs/ops/ci.md). pnpm e2e:fake-serial builds the production and fake-serial builds, checks that they differ only in the transport seam chunk, and runs the fake-serial suite, in which machine.worker opens a mock port (docs/testing/fake-serial.md). pnpm e2e:staging runs the staging headers suite (wrangler dev --env staging, serial=(self)). The localhost bench build for a real TinyG (pnpm build:bench, pnpm bench:serve, never deployed) is described in docs/bench/README.md.

Pages and theme (P0-05): every page (index.html, safety/, privacy/, 404.html) is prerendered at build time from the Preact components in apps/web/src/shell/ and apps/web/src/pages/, so the safety bar and its W1 warning are in the HTML before any script runs. Every W and C string comes from packages/safety/src/strings.ts, tested byte for byte against SAFETY.md §5–§6 (T-S32). The bundle's version chip uses the commit SHA (git rev-parse HEAD, or RUN_BUILD_SHA). Theme tokens, the token drift check (pnpm tokens:drift --site <synthetos.com clone>), the contrast table (pnpm gen:contrast) and the icons (pnpm gen:icons) are described in docs/design/tokens.md. Its nested pnpm calls need pnpm on PATH (corepack enable).

Protocol (P0-07): packages/protocol turns serial bytes into typed events. createInboundDecoder() frames lines (CR/LF tolerant, UTF-8 safe, XON/XOFF removed into FlowSignal events, 4 KB line cap) and classifies each one as Response, StatusReport, QueueReport, RxReport, Exception, Banner, Ack, Text or Garbled, with a relaxed-JSON parser that has depth and size caps and never throws. Anything ambiguous is Garbled, never guessed. Its tests run with coverage, and frame.ts, classify.ts, json.ts and inbound.ts must stay at 100% branch coverage (packages/protocol/vitest.config.ts).

Safety (P0-10): packages/safety decides what may be sent and when. sanitizeJob(lines, dialect, options) applies SAFETY §4.7 step by step and returns the exact SentLine[] the streamer will write (LF-terminated, host N numbers, barrier and holdback marks, long moves split under the queued-motion ceiling) plus a report; a blocked report must never be armed. allowed(snapshot, intent) is the declarative allow-matrix (SAFETY §4.1): the stop class is allowed in every state with the port open, and in Phase 0 every motion, write and connect intent is denied with "Not available in this release". overrunBound(queue) gives the distance bound and the time estimate of SAFETY §4.3, and effectiveHostGates applies only tightening host-gate changes until C19 (T-S69). The package is held to 100% coverage (pnpm --filter @synthetos/safety test) and a 90% Stryker mutation score (pnpm --filter @synthetos/safety mutation). Design notes and the places where the code had to interpret the design: docs/safety/sanitiser.md.

Dependency hygiene: versions are pinned exactly (save-exact), install scripts never run (ignore-scripts), and pnpm refuses versions published less than seven days ago (minimumReleaseAge).

Licence

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE and NOTICE. Anyone who modifies run and distributes it, or serves it to users over a network, must offer those users the corresponding source under the same licence (owner decision OD-7, docs/ops/owner-decisions.md).

The production dependency policy is unchanged: dependencies must be permissive (MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0 or OFL-1.1). Permissive licences are compatible with AGPL-3.0, so they can be combined with run and distributed under its terms. GPL and AGPL dependencies stay disallowed by the licence gate; that rule governs what run depends on, not run's own licence.

Controller firmware (TinyG, g2core) is GPL-2.0 and lives in its own repositories. Tables generated from TinyG source and the TinyG logo files are listed with their provenance in THIRD_PARTY_NOTICES.md.

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages