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.

Additive profiles: Verified local snapshot. Historical receipts retain their recorded scope; live qualification and customer delivery require separate evidence. Three E28 draft entries expose the existing local modules: software-factory/repository, software-factory/product-gate and software-factory/delivery-records. Independent Astra review passed; they were 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. They do not provide a complete Implementation or Verification Workflow.

Use the private tarball from Journal adoption and the explicit Node development declarations in executor adoption. Imports are passive; compiled JavaScript has no runtime package dependency or TypeScript sidecar. This proof covers the existing macOS arm64 host, Node 26.8.1 and the pinned Xcode Git executable. It does not qualify another platform. Each module can be imported separately; the gate and ledger receive a caller-owned CommandJournal.

Seal a Candidate and observe an honest refusal

Save this entire example as repository-demo.mjs beside the installed package and run node --no-experimental-strip-types repository-demo.mjs. It creates and removes only its own temporary directory. A sealed Candidate grants no integration authority: the unbound gate withholds the effect. The retained claim subsequently reads as unknown, and the target remains unchanged.

import assert from 'node:assert/strict';
import {createHash,randomUUID} from 'node:crypto';
import {mkdtempSync,realpathSync,rmSync} from 'node:fs';
import {tmpdir} from 'node:os';
import {join} from 'node:path';
import {createRepository,openRepository} from 'software-factory/repository';
import {ProductGate,actionIdOf,ownerIdOf,currentCheck,seamAnswer,storeDigestOf} from 'software-factory/product-gate';
import {DeliveryLedger} from 'software-factory/delivery-records';
import {CommandJournal} from 'software-factory/command-journal';

const root=realpathSync(mkdtempSync(join(tmpdir(),'repository-demo-')));
const journal=CommandJournal.open(join(root,'journal.sqlite'));
const digest=text=>'sha256:'+createHash('sha256').update(text).digest('hex');
try {
  const identity=await createRepository({path:join(root,'owned.git'),productId:'demo',targetRef:'refs/heads/delivered',files:[{path:'hello.txt',text:'before\n'}]});
  const repository=openRepository(identity),base=await repository.target();
  const source=await repository.snapshot(base),slice={id:'greeting',revision:1};
  // These declared pins demonstrate sealing only. They are not a verified proof.
  const candidate=await repository.seal({base,slice,scope:['hello.txt'],acceptance:digest('demo acceptance'),recipe:digest('demo recipe'),environment:digest('demo environment')},{edits:[{path:'hello.txt',prior:source.files[0].sha256,text:'hello\n'}]});
  assert.equal((await openRepository(identity).exportCandidate(candidate.digest)).digest,candidate.digest);
  const owner={id:ownerIdOf(randomUUID()),generation:1};
  const prepared=await repository.prepareIntegration({action:{id:actionIdOf('demo','greeting/1'),occurrence:1},product:'demo',slice,repository:identity,ref:identity.targetRef,base,commit:candidate.manifest.commit,candidate:candidate.digest,proof:digest('no collected evidence'),owner});
  const ledger=new DeliveryLedger(journal),gate=new ProductGate(journal);
  const record={prepared,storeDigest:storeDigestOf(identity),sliceRef:'greeting/1',recordedAt:new Date().toISOString()};
  assert.equal(ledger.recordPrepared(record).replayed,false);
  assert.equal(ledger.recordPrepared(record).replayed,true);
  const observation=await repository.invokeOnce(prepared,()=>seamAnswer(currentCheck(gate.read('demo'),'0'.repeat(32),owner,new Date().toISOString())));
  const recovered=await openRepository(identity).inspectIntegration(prepared);
  console.log(JSON.stringify({candidateRetained:true,invocation:observation.invocation,recovered:recovered.invocation,targetUnchanged:await repository.target()===base}));
} finally {
  journal.close();
  rmSync(root,{recursive:true,force:true});
}

Compose a real admitted integration

The caller owns the registry input, protected local repository, journal, Evidence, fence, snapshots, clock, grants and effect ordering. Repository supports fresh module-owned bare stores with bounded ordinary UTF-8 files. It never imports an existing checkout, fetches, pushes, runs repository content or grants permission. Preserve its returned path/device/inode/nonce identity; a replacement is refused, never adopted.

Record a canonical Product binding with DeliveryLedger.recordBinding, then bind the same store through ProductGate.bindStore. Registry and checkout fields retain the caller's provenance; they are not a Portfolio dependency. Explicitly grant operations and limits, acquire real fenced ownership and freeze the Slice's base, scope and acceptance/recipe/environment pins. The gate validates supplied fence identities; the caller must actually hold and retire fences correctly. A token or timeout alone is not proof of ownership.

Admit and retain production/check commands, seal the Candidate, then use the repository collector with the gate's check dispatch and an actual fence hold. Gather Evidence from the same public Evidence module and derive judgeRepository. Freeze collectorClosure() and currentEnvironment() before sealing. Retain the Slice, Verdict and prepared intent in the ledger. Only a successful admitDispatch for integrate-local, with that Verdict and its genuine gathered Evidence, permits the caller to proceed. Admission rederives the Verdict and checks the Product, owner generation, Candidate, scope, base, pins, grant and allowance. A shaped success object, cloned Evidence or proof digest does not qualify.

Immediately before the target move, use invokeOnceGuarded(prepared, () => seamAnswer(currentCheck(gate.read(productId), dispatchId, owner, now()))). It refuses a missing guard before claiming the occurrence. invokeOnceUnguarded(prepared) explicitly performs the low-level effect under caller authority. The optional-guard invokeOnce is a deprecated compatibility facade; all three retain claim, unknown and replay semantics and supply no authority. These effect contracts apply to both gate profiles. Record the sender's dispatched observation in the ledger before recording its gate outcome through observedIntegrationOutcome.

Keep history separate from permission

Gate commands use gateCommandIds, the current journal version and the original command payload. An exact dispatch replay returns admitted: false, reason: 'REPLAYED'; it is history, never a fresh permit. Ledger records are create-once: exact repeats replay, changes conflict, and malformed stored records refuse. The gate and records share the public Journal and Evidence class identities with other entries.

Retain the original Repository identity, prepared intent, Slice, Verdict and receipt. Open the same journal with CommandJournal.openExisting; re-gather Evidence to rejudge historical proof. A fresh process can read retained receipts and inspect the local target without dispatching. Missing or corrupt Evidence is inconclusive. Changed pins require newly commissioned work, not relabelling old records.

A moved base, foreign Product or replaced store refuses. A durable claim without a receipt is unknown even when no target effect occurred. A target observed at the desired commit does not prove who moved it. Never turn unknown into a retry: invokeOnce will not submit again; unsettled or unknown gate integration blocks later integration. A successor needs actual fenced ownership and must reconcile through the existing outcome rules. Lost acknowledgement after a successful move is recovered from retained Repository/ledger receipts when available.

Existing Repository, Candidate, integration, gate, binding, Slice and snapshot /1 identities and digest formulas remain unchanged. The additive neutral gate/binding /2 is selected explicitly below. Source collector /1 and compiled collector /2 remain distinct as described in the collector guide; historical receipts are not migrated or repinned. Storage is trusted local storage: self-consistent forgery by a privileged writer, cross-ref crash atomicity, power-loss durability and hostile concurrent filesystem writers are outside the established guarantee. Native Git locking and the existing protected object rules remain unchanged.

Factory-specific parts

The legacy Product gate and Product binding /1 retain Portfolio-shaped provenance. Source citations here refer to 85a5472:

  • A binding carries registry: {version, bindingDigest} and checkout: {root, headRef, headOid, capturedAt} (src/product-gate.ts:106-111), mirroring Portfolio facts (src/portfolio.ts:239, src/portfolio.ts:245).
  • parseProductBinding requires the exact fields, sf-product-binding/1, a positive registry version, a 64-character lowercase-hex registry bindingDigest, a tagged SHA-256 storeDigest, an absolute checkout root and matching Git head (src/delivery-records.ts:418-429, src/delivery-records.ts:443-444). Attribution grants no authority.
  • Legacy bindStore takes registry: {productIds, checkouts} (src/product-gate.ts:309-314). An unlisted Product refuses NOT_REGISTERED; the owned store must remain outside listed checkout roots (src/product-gate.ts:601-617).
  • The /1 ledger retains the whole binding under its Product identity (src/delivery-records.ts:190-192, src/product-gate.ts:617).

Changing stored fields requires a new protocol version, not reinterpretation of existing /1 records. The explicit binding/gate /2 below is separate; DeliveryLedger keeps its legacy binding contract.

Product binding without Portfolio

ProductGateV2(journal) accepts ProductBindingV2 under sf-product-binding/2: {productId, protocol, provenance, source, store, storeDigest}. provenance is {sourceId, revision, digest} with a bounded ASCII ID, positive revision and tagged SHA-256. source keeps the original Git head and disjoint, sorted copied/authored file inventories. parseProductBindingV2 validates it. There are no registry or checkout-shaped provenance fields; attribution grants no authority.

bindStore requires registration: {productIds, protectedRoots}. Product membership remains mandatory, and the owned Git store must lie outside every listed protected root. The caller supplies truthful registration and canonical absolute source roots. Subsequent grant, fenced ownership, freeze, production/check/integration, stop and allowance rules share the legacy implementation.

Both facades use the same Product aggregate and command identity: choosing /2 never creates a second owner or allowance. Each facade refuses the other's stored schema, including an unbound stop record; no automatic migration or reinterpretation occurs. The existing ProductBinding and DeliveryLedger retain sf-product-binding/1; the worker-capable ProductGate records the W30/W31 aggregate as sf-product-gate/2 while still using that legacy binding. ProductGateV2 requires the distinct sf-product-binding/2 shape. Matching aggregate version text does not permit cross-facade reopening. The ledger does not accept /2 binding records. A caller using the neutral gate owns any additional provenance retention; that attribution cannot substitute for a Slice, Evidence, Verdict or qualified dispatch.

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