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.

This E28 draft packages fixed trusted fixtures, their worker, ownership fence, workspace, Evidence store, Assurance and guarded recovery policy. It was accepted locally on 1 October 2026 (owner-designated acceptance reviewer, after independent Opus 5.5 and Fable 5.1 reviews). It adds no general process sandbox, production authority or provider access. The confined executor remains the separate boundary for ordinary caller programs.

Install the private tarball as described in Journal adoption, with caller development @types/node 26.6.3 (tested with its undici-types 8.9.0 dependency). The fixture subpaths explicitly reference Node declarations. There are no runtime dependencies. Node 26.8.1 on the tested macOS arm64 host is the current proof; this adds no platform qualification.

Public contracts

ImportContract
software-factory/fixture-manifestCurrent manifest, exact historical parsing, declared resource mode and launched URLs
software-factory/fixture-workerLocalFixtureWorker, fixed fixture names and guarded observations
software-factory/attempt-fenceCreate, hold and close ownership under SQLite exclusion
software-factory/attempt-workspaceProvision and dispose the exact workspace under its fence
software-factory/evidenceCaller-owned immutable content-addressed observations
software-factory/assuranceGather store-written Evidence and judge against exact expected pins
software-factory/guarded-verificationBuild/parse requests; verify, inspect, cancel and recover using a caller-owned GuardedContext

The caller supplies the Journal, Execution instance, Evidence store, canonical state paths and Run ID through GuardedContext. Importing starts no Factory, process or file access. This example constructs a disposable caller context and submits one Run:

import { mkdtempSync, realpathSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { CommandJournal } from 'software-factory/command-journal';
import { Execution } from 'software-factory/execution';
import { EvidenceStore } from 'software-factory/evidence';
import { guardedFixtureManifest } from 'software-factory/fixture-manifest';
import { buildGuardedRequest, runPinsOf, verifyGuarded } from 'software-factory/guarded-verification';

const root = realpathSync(mkdtempSync(join(tmpdir(), 'caller-guarded-')));
const paths = {
  root, journal: join(root, 'caller.sqlite'), evidence: join(root, 'evidence'),
  fences: join(root, 'fences'), workspaces: join(root, 'workspaces'),
};
const journal = CommandJournal.open(paths.journal);
try {
  const ctx = {
    runId: 'caller-run', stateDir: root, paths, journal,
    execution: new Execution(journal), store: new EvidenceStore(paths.evidence),
  };
  const environment = `node-${process.version} ${process.platform}-${process.arch}`;
  const request = buildGuardedRequest({
    runId: ctx.runId, fixture: 'pass', timeoutMs: 2000,
    maxOutputBytes: 4096, maxAttempts: 2,
    execution: guardedFixtureManifest(), environment,
  });
  ctx.execution.submit({
    commandId: 'caller:submit:' + ctx.runId, runId: ctx.runId,
    pins: runPinsOf(request), budget: request.budget,
  });
  const result = await verifyGuarded(ctx, request, environment, undefined);
  console.log(result);
} finally {
  journal.close();
}

The example leaves its disposable journal and Evidence for inspection. For durable use, persist request with the caller's command handling before dispatch, and recover it through storedGuardedRequest. Keep its original pins and Budget. A retry uses that request and Run ID. The recipe functions do not create a request ledger for the caller; Factory's CLI is one separate composition. Low-level worker consumers must create and hold the fence before provisioning the workspace and retain the hold until settlement.

Use one journal for the whole context

Build execution as new Execution(journal) over the context's own journal, and submit the Run through it. A second handle on the same file also works. Nothing in GuardedContext checks this. The Factory source test test/guarded-verification-context.test.ts measures what happens otherwise:

  • Run only in the Execution's journal. verifyGuarded launches the fixture once and completes the Run as Verified. The Run lands in that journal, but the Attempt's preparation and report land in ctx.journal. A later context over either file alone loses part of the account. Over the Run's file, inspectGuarded shows invalidated, cleanup unknown and report missing; over the other file, it throws run <id> was not submitted. This split is an open defect, not a supported mode.
  • Run only in ctx.journal. verifyGuarded and inspectGuarded throw run <id> was not submitted. No fixture runs and neither journal changes. Verify has already created its empty fence and workspace directories.
  • Two handles on the same file. These act as one journal: the Run, preparation and report share that file, and verify and inspect report verified.

Factory's own CLI always builds the Execution from its context's journal, so only a caller-built context can split state.

Source and compiled identities

Source mode remains manifest sf-guarded-fixture/1, collector sf-guarded-fixture-worker/1, Candidate /2 and Recipe sf-local-fixture-verify/2. It hashes the seven explicitly listed src/*.ts resources. The compiled package uses manifest /2, collector /2, Candidate /3 and Recipe /3, hashing the corresponding seven actual dist/*.js resources. The worker launches those declared JavaScript child, gate and fence paths. There are no TypeScript runtime sidecars.

Only the exact fixture-manifest.ts or fixture-manifest.js entry selects its declared mode. The parser recognises both exact layouts; it never relabels a source manifest as compiled. Historical /2 request reconstruction, stored state and Evidence remain unchanged. Their historical Verdict remains visible when changed current resources invalidate it. Old or mismatching pins cannot dispatch new code. Source edits also change the source-mode digest; restoring old bytes or creating an explicitly new Run are caller decisions, never automatic repinning.

The manifest rejects missing, symbolic-linked, multiply-linked, non-regular or concurrently replaced resource files. Installers that hard-link package files into a shared store (for example pnpm without copy-on-write) therefore fail the manifest check and are refused; install with one that copies the files. The compiler-derived closure and actual spawned paths are tested. This protects the declared installed resources under the existing trusted-controller assumption. It does not authenticate a hostile installation, freeze already-loaded JavaScript, or claim protection from filesystem mutation after the final check. The runtime environment remains a separate caller pin.

Recovery and trust

Cancellation is recorded in Execution before stopping the worker. A live hold prevents takeover; a closed fence proves no protected work can resume, without inventing a process exit or Verdict. A restarted controller may settle an immutable valid report or fence an orphan, then use a new epoch within the original Budget. Missing or damaged identity remains unresolved. inspectGuarded reports existing records without changing them.

Evidence is trusted only within the existing local store/collector boundary. An Evidence reference, collector label or child's output is not authentication. Assurance rejects wrong Run/epoch/pins and malformed or corrupted records. These fixed fixtures run with Node permission restrictions; SQLite bypasses those file flags, so this is not arbitrary-code confinement.

The draft evidence records exact artefact hashes and external proof: useful execution, historical replay, every resource's drift/missing/link refusal, ownership loss, durable cancellation, controller death and fenced restart recovery. Worker and recipe receipts remain immutable historical evidence. This draft passed independent Astra review and was merged on 1 October 2026 after an Opus 5.5 review and accepted locally the same day by the owner-designated acceptance reviewer after a Fable 5.1 review. Repository-collector resource packaging and all broader adoption gates remain open.

Source: docs/how-to/adopt-fixture-resources.md