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.

Private E28 draft; independent Astra review passed; merged on 1 October 2026 after an Opus 5.5 review; accepted locally the same day by the owner-designated acceptance reviewer after a Fable 5.1 review. The package exposes software-factory/producer, software-factory/claude-producer and software-factory/openai-producer. Node.js ≥26.8.1 is required; Claude remains restricted to the audited macOS arm64 profile; the legacy constructor keeps its existing executable pin, while PinnedClaudeProducer takes an explicit caller pin. The external proof ran on Node.js 26.8.1/macOS 27 arm64. No npm runtime dependencies or Factory startup are required. TypeScript callers supply compatible Node development types (@types/node 26.6.3 in the proof).

Use the journal installation guide to obtain and install the private tarball, and pin its exact hash. Each entry exports its existing source API. Internal files remain unexported. The neutral contract loads only canonical JSON, Repository's pure wire vocabulary and Node builtins; it never constructs Repository, opens Git or starts a process. Adapter imports are passive. The Claude constructor validates caller-owned private directories and reads host identity/default HOME if pins are omitted; neither adapter contacts a provider until produce.

Parse a proposal without a provider

Save this complete example as proposal.mjs in the external application and run node proposal.mjs. It needs no credentials, commission, Git checkout or Product registration.

import assert from 'node:assert/strict';
import {createHash} from 'node:crypto';
import {
  PRODUCER_REQUEST_PROTOCOL, parseProducerRequest, parseProposalText,
} from 'software-factory/producer';
import {OPENAI_MODEL, OpenAiProducer} from 'software-factory/openai-producer';

const brief = 'Add a greeting file under src.';
const request = parseProducerRequest({
  protocol: PRODUCER_REQUEST_PROTOCOL,
  product: 'caller', slice: {id: 'greeting', revision: 1},
  attempt: {runId: 'run', epoch: 1, attemptId: 'run/1', owner: 'caller'},
  base: {commit: 'a'.repeat(40), tree: 'b'.repeat(40)},
  files: [], scope: ['src'],
  brief: {text: brief, digest: 'sha256:' + createHash('sha256').update(brief).digest('hex')},
  provider: 'openai', model: OPENAI_MODEL, effort: 'high', allowance: 'caller/greeting',
  bounds: {inputBytes: 32768, outputBytes: 131072, diagnosticBytes: 16384,
    deadlineMs: 1000, gateMs: 1000, maxEdits: 4, maxEditBytes: 32768,
    maxFiles: 8, maxOutputTokens: 8000, maxCostCents: 50},
  hardBounds: [],
});
const parsed = parseProposalText(JSON.stringify({edits: [
  {path: 'src/greeting.txt', baseSha256: null, content: 'Hello!\n'},
]}), request);
assert.equal(parsed.ok, true);
assert.deepEqual(parsed.proposal.edits, [
  {path: 'src/greeting.txt', prior: null, text: 'Hello!\n'},
]);

const records = [];
const gate = {
  async admit() { throw new Error('No exchange is authorised in this example'); },
  async record(consumption) { records.push(consumption); },
};
const producer = new OpenAiProducer({credential: null, commission: null, gate});
const result = await producer.produce(request);
assert.equal(result.status, 'unavailable');
assert.equal(result.reason, 'not-commissioned');
assert.equal(result.receipt.contact, 'none');
assert.equal(records.length, 1);
console.log('Proposal parsed; transport unavailable; no provider contacted.');

The base hashes above are synthetic request data, not evidence of a repository. The parser returns untrusted Proposal/FileEdit data and a digest. Your downstream application must independently check current bytes, scope and authority before applying anything. Paths, priors, bytes and counts are bounded; invalid inputs refuse rather than truncate.

Supply an adapter deliberately

Both adapters implement Producer.produce(request, signal?). The caller supplies an asynchronous DispatchGate: admit is the last admission before contact; record receives consumption exactly once for each returned status. The gate owns durable admission, allowance and recovery. The existing Factory Product gate does not yet implement this producer dispatch contract. A GateRejection from record means definite refusal; any other error or overdue acknowledgement means allowance.recorded: "unknown".

OpenAI accepts an explicitly created OpenAiCredential and an independently commissioned policy. It does not discover a key or sign in. Production requests use the fixed Responses endpoint. Claude accepts an owned private root, gate and commission; its executable, model, platform, narrowed environment and capability inventory remain pinned. The legacy executable pin is one absolute path and SHA-256 on the Factory's host. The additive production pin API below supports a caller-owned executable without borrowing that qualification. No current live commission is supplied by this package. Claude needs re-qualification and an inventory completeness audit; OpenAI lacks established live qualification. These requirements remain unchanged.

The existing unsafeTestCredential, unsafeOpenAiEndpoint and unsafeClaudeTransportPins seams support deterministic tests. The package proof uses an obvious synthetic credential with a loopback server and a Node executable pinned to run a local fixture. Those synthetic commissions are test data, never live qualification or permission to contact a provider. unsafeQualificationRun is an explicit privileged qualification seam, not ordinary adoption setup; do not use it to bypass an absent commission.

Preserve unknowns and caller recovery

Results are proposal, unavailable, failed or interrupted, with a receipt and separate allowance acknowledgement. Hard bounds unsupported by the chosen transport refuse before contact. Aborting or reaching the deadline after contact can leave remote: "unknown"; it does not prove remote work stopped. Claude's local group observation never proves process-tree containment, and billed spend remains unknown. OpenAI has no enforced monetary ceiling. Do not translate unknowns to zero.

A Producer has no journal, replay method or durable deduplication. Every produce call creates a fresh dispatch identity; repeating a request can contact the provider again. Persist admissions and consumptions in your own store. After a lost record acknowledgement, reconcile the saved dispatch ID before deciding any further action; importing or constructing another adapter does not resume it. The external proof reads a caller-owned consumption record in a fresh process without contacting either transport, while retaining the original unknown acknowledgement.

The draft proves installed JavaScript, strict public declarations, passive imports, byte-compatible pre-extraction protocols, useful local-fixture output, refusals and unknown outcomes. It grants no integration authority and establishes no live provider, complete Workflow, new sandbox or release. Earlier historical qualification receipts remain unchanged.

Caller-owned production Claude pin

PinnedClaudeProducer({root, gate, commission, pin}) takes ClaudeExecutablePin: {protocol: 'sf-claude-executable-pin/1', executable, sha256, version}. The executable is a canonical absolute path, SHA-256 is 64 lowercase hexadecimal characters, and version is the audited 2.1.283. It accepts no argv prefix, model, environment, HOME, platform or managed-source override. The exact darwin/arm64, claude-opus-5-5 model, argument, init-capability and narrowed-environment rules remain fixed. Effort comes from the validated request (low, medium, high, xhigh or max); dispatch still requires a matching model/policy commission and gate admission. The pin cannot override effort.

pinnedClaudeTransportPolicy(pin) captures the complete sf-claude-transport-policy/2, including actual HOME and resolved host-managed configuration paths. pinnedClaudePolicyDigest(pin) hashes that policy. A commission must bind this digest and the observed complete managed-policy inventory. Missing, legacy or mismatched qualification refuses before gate admission or invocation; executable drift, cancellation and bounded cleanup retain the established rules. A pin alone qualifies nothing.

The privileged offline-reviewed qualifier accepts --pin-file <owned JSON file>; it refuses unsupported hosts before a control call and rejects links, excess bytes and malformed inputs. Pin-qualified receipts use content-addressed paths distinct from historical outputs. Running it still requires its separate live commission; the installed consumer uses only a caller-owned fake CLI and synthetic qualification. This change supplies no live credentials, current provider qualification or authority to contact Claude.

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