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.

Historical local qualification: Source 7cf4b26e focused Core 22/22 and Dashboard 26/26 checks passed. The historical bounded local record keeps their exact scope. Historical source 7cf4b26e passed the 3,286/3,286 full checks and all 36 installed families. Independent bounded local evidence acceptance passed; exact-final-head CI is recorded separately from this frozen local proof. Module-specific and broader limits remain below.

This E28 draft offers two private package subpaths: software-factory/repository-collector and software-factory/repository-assurance. Independent Astra review passed, and it was accepted locally on 1 October 2026 (owner-designated acceptance reviewer, after independent Opus 5.5 and Fable 5.1 reviews); the package remains a private draft. It makes no new platform, provider or production claim.

Install the private tarball using Journal adoption, with the Node development declarations described in executor adoption. Imports are passive. There are no runtime package dependencies. The earlier package proof used the existing macOS arm64 host with Node 26.8.1; Node TypeScript stripping is disabled in the external consumer.

Supply the protected inputs

Create the executor's canonical private root directory with mode 0700 before collection; its constructor never provisions caller storage. Run IDs keep the ver- plus 48 hexadecimal characters grammar, and Attempt IDs are <runId>/<epoch>.

The caller supplies a sealed Candidate's canonical manifest and byte snapshots, its exact base snapshot, frozen acceptance/recipe/environment, fixture inputs, an active Product fence, a bounded deadline, an abort signal and a CollectGate. SnapshotStore persists and verifies the caller's input snapshots. RepositoryCollector passes only the stage's program and named input to the confined executor. Expected output remains a protected digest.

import { RepositoryCollector, collectorClosure, currentEnvironment } from 'software-factory/repository-collector';
import { RECIPE_PROTOCOL, REPOSITORY_COLLECTOR, judgeRepository } from 'software-factory/repository-assurance';
import { gatherEvidence } from 'software-factory/assurance';

const collector = new RepositoryCollector({ store, executor, protectedPaths });
const result = await collector.collect(request, gate, hold, signal);
const expectation = {
  pins: request.pins,
  evidence: result.runs.flatMap(run => run.evidence === null ? [] : [{ ref: run.evidence, check: run.check }]),
};
const gathered = await gatherEvidence(store, result.evidence);
const verdict = judgeRepository(expectation, request.sealed.manifest, baseListing, gathered);

Here every input is caller-owned. Freeze collectorClosure(), currentEnvironment() and the declared recipe/collector identities before sealing the Candidate. materialiseBase verifies the base bytes and reconstructs its listing. Include every protected directory in protectedPaths: repository/store, journal, snapshots, Evidence, fence, executor and answer key. Hold ownership until collection settles. Storage failure means no complete proof for that Attempt.

The neutral Candidate/snapshot interfaces are exported through the collector. Supplying canonical Candidate bytes does not grant Repository ownership or integration authority. These modules never read or write Git, start Factory or alter a target ref. The separate Repository/gate/records draft provides their own adoption contract; the collector still grants no integration authority.

Preserve identities and old proof

Source mode uses recipe sf-repository-verify/1 and collector sf-repository-scenario-collector/1, hashing the eight explicit src/*.ts resources with the historical formula. Compiled mode uses recipe /2 and collector /2, hashing the eight actual emitted dist/*.js resources. Only the exact collector and Assurance module basenames select a mode. There are no TypeScript sidecars or inferred path fallbacks.

The parser accepts only the two matching protocol pairs. Evidence pins use each recorded recipe protocol and collector ID. Candidate, repository, snapshots and observations retain their existing formats. Old proof can still parse and rejudge against its original expectation without changing a byte. It is historical proof; its old collector pin cannot dispatch the current compiled collector. Source edits also invalidate old source closure pins: the neutral FileEdit/Proposal types added to repository-protocol.ts changed the source closure, so source recipes pinned before that change are refused. No automatic repinning or migration occurs.

The installed closure is checked before launch and before Evidence storage. Missing, non-regular, symbolic-linked, multiply-linked, mutated or replaced resources refuse. Identical-byte replacement during an operation also invalidates its witness. A change while a process runs prevents new Evidence attribution but cannot undo that process. The Source candidate rejects later revalidation with CollectorResourceDriftError: progress retains original pins, completed runs and acknowledged Evidence IDs, the current unwritten observation if one exists, and only the unentered check suffix. Existing unresolved facts stay unresolved. Nothing further launches or stores; these diagnostics grant no Verdict, retry or resume authority.

The current observation includes copied output and its original facts, which have not completed resource qualification and are not branded Evidence. Read the prior IDs through the genuine store. The public error constructor and shallow-frozen progress are not authenticity evidence. Initial input/resource validation still throws before collection effects; a released hold or caller clock failure can still reject after effects without the resource-progress payload. Never treat an arbitrary TypeError as proof that nothing started.

This runtime correction changes new Source/compiled closure pins. Old recipes, frozen Slices, records and receipts stay unchanged; their original parse/rejudge path remains historical proof. New commissioned work needs freshly qualified code and new pins, not a rewrite of an old Attempt.

These checks assume a trusted installation and controller. They do not authenticate an attacker-modified loader, freeze JavaScript already loaded in memory, or eliminate a filesystem race after the final check. A trusted writer with Evidence-store access can forge records. Assurance uses the shared Evidence module's genuine read brand and verifies bytes/pins; a copied record or a program's own success claim carries no authority.

Restart and cancellation

Persist the original expectation, manifest, base listing and Verdict in caller storage. On restart, gather the same Evidence IDs and use rejudgeRepository or judgeRepository; this performs no dispatch and keeps missing or corrupt observations inconclusive. It does not establish current validity of a changed installation.

Collection is a low-level once-per-check operation, without a journal replay policy. Calling collect again launches again. The caller must retain Attempt ownership, command identity and outcome before deciding whether another Attempt is allowed. Abort stops the current process and prevents later launches. Lost ownership blocks further launch and storage; an in-flight write cannot be undone. No failed, missing or unknown observation authorises a blind retry.

The resource-drift correction passed eight focused native cases, strict typechecking and independent Source review. Historical 7cf integrated installed/full native execution and independent bounded local evidence acceptance passed. Earlier accepted evidence retains its earlier bytes.

Source: docs/how-to/adopt-repository-collector.md