Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

Toolchain

  • Node.js 26.8.1 or later and npm 11. TypeScript runs directly through Node's built-in type stripping, so there is no build step.
  • The only dependencies are exact dev dependencies: typescript (type checking) and @types/node. SQLite comes from node:sqlite, and nothing needs a network service.
npm ci              # install the locked dev dependencies
npm test            # node:test suite; every test uses real SQLite files in a temporary directory
npm run typecheck   # tsc against tsconfig.json: strict settings, no emit
npm run check       # both

The dashboard is a separate package with its own lockfile: npm --prefix apps/dashboard ci, then npm --prefix apps/dashboard run check (typecheck, build, rendered tests). The root check never needs its dependencies.

Source code has to use erasable TypeScript syntax only (no enums, namespaces or parameter properties), and relative imports include the .ts extension.

Start with the fixture tutorial for a complete exercise. Exact module APIs and limits live in the references below.

Command journal (src/journal.ts)

See the command journal reference for the contract, limits and focused tests.

Evidence and Assurance

See the evidence assurance reference for the contract, limits and focused tests.

Execution

See the execution reference for the contract, limits and focused tests.

Attempt fence (src/attempt-fence.ts)

See the attempt fence reference for the contract, limits and focused tests.

Local fixture worker

See the local fixture worker reference for the contract, limits and focused tests.

Guarded runs (runGuarded, src/fixture-gate.ts, src/attempt-workspace.ts, src/fixture-manifest.ts)

See Local fixture worker for the guarded worker contract.

Local factory CLI (src/cli.ts, src/local-factory.ts, src/guarded-verification.ts, src/attempt-ledger.ts)

See the guarded verification reference for the contract, limits and focused tests.

Confined executor (src/confined-executor.ts)

See the confined executor reference for the contract, limits and focused tests.

Repository (src/repository.ts)

See the repository reference for the contract, limits and focused tests.

Producers (src/producer.ts, src/claude-producer.ts, src/openai-producer.ts)

See the producer reference for the contract, limits and focused tests.

Private module artefacts

Use the staged package command to build a tarball with consumer documentation. Plain root npm pack refuses; source README and development configuration remain untouched.

Proposal ownership candidate

Proposal ownership uses the existing Journal and a caller-qualified local current-authority fence. Import, constructor, read and replay are passive; explicit mutations retain immutable generations and unknown ownership. Follow the installed guide. Component review, final integration and later delivery contracts remain separate gates.

Source: docs/local-development.md