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.

Keep a project's values as immutable, digest-bound revisions without creating a Portfolio or registering a Git checkout. The private software-factory distribution exposes software-factory/project-guidance alongside software-factory/command-journal. This E29 increment 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. It does not close the other project/operations adoption gaps.

Install the private artefact

Follow the command-journal package guide to obtain and install the tarball into a separate application. Its named public imports need Node.js ≥26.8.1 and built-in SQLite, with no npm runtime dependencies. The initial proof covers Node.js 26.8.1 on macOS 27 arm64 only. The caller owns a local journal file and the filesystem permissions SQLite needs; network filesystems remain unsupported.

The guidance entry point loads only the core, Journal, canonical JSON and errors. It excludes the Factory adapter and Portfolio. The same artefact also offers the separate Execution, Schedule and Intelligence contracts; importing guidance does not load them. Importing either public entry point starts no service, scheduler, authentication flow, process or filesystem write. TypeScript declarations are included; a compiler is unnecessary at runtime. The package root and private source/compiled paths are not exported.

Supply your project's identity

Save the following as values.mjs in the consuming application:

import { CommandJournal } from 'software-factory/command-journal';
import { ProductGuidance } from 'software-factory/project-guidance';

const projects = new Set(['my-project']);
const identities = { hasProduct: id => projects.has(id) };
const journal = CommandJournal.open('./values.sqlite');
try {
  const guidance = new ProductGuidance(journal, identities);
  const saved = guidance.setValues({
    commandId: 'guidance-first',
    productId: 'my-project',
    expectedRevision: 0,
    values: [{
      id: 'privacy',
      statement: 'Private by default',
      application: 'Keep personal data on the device.',
    }],
  });
  const pin = {
    productId: saved.productId,
    revision: saved.revision,
    digest: saved.digest,
  };
  console.log(guidance.resolvePin(pin));
} finally {
  journal.close();
}

Run node values.mjs. Running it again returns the same recorded revision: the command ID and complete input are unchanged. Later saves use a new guidance- command ID and the current expected revision. A pin always resolves its original values, even after later edits or clearing the list.

The core constructor is ProductGuidance(journal, identities, options?); options.now may supply a clock. The existing Factory source constructor still uses Portfolio through its compatibility adapter. The package exposes the core, so caller-owned registration is always explicit.

Identity and lifecycle contract

GuidanceIdentityRegistry has one method: hasProduct(productId: string): boolean. It must be a synchronous data method returning exactly true or false. Methods on a normal class prototype work, including private-field receivers. Accessor methods, cyclic or more than 32 inspected prototype objects, and non-boolean results such as Promises are refused as INVALID; no thenable is awaited. The method is captured at construction, so change its backing data or construct another reader when substituting the method.

Each operation validates the canonical Product ID, then checks membership once. Product IDs use 1–63 lowercase letters, digits or hyphens, starting with a letter or digit. false means NOT_FOUND; a thrown registry error passes through. Removing membership denies current/history/revision/pin reads and command replay as well as new saves. It never deletes or rewrites stored guidance. Reintroducing an ID exposes its existing history, so the host must never reuse that ID for a different project.

Registration is trusted caller scope, not authentication or delivery authority. The host owns persistence and synchronisation; a separate registry and journal are not one transaction. Use one owning process or supply stronger host coordination if membership must remain unchanged throughout a save. Guidance owns no registry mutation, journal creation or close lifecycle.

Values, failures and compatibility

The entry point exports ProductGuidance, GuidanceError, GUIDANCE_PROTOCOL, LEGACY_GUIDANCE_PROTOCOL, GUIDANCE_LIMITS, DIRECT_ENTRY, guidanceDigest and the input, result, snapshot, pin, history and identity types. The shipped declarations define their exact shapes:

OperationResult
current(productId)Frozen GuidanceSnapshot; revision zero when unset
revision(productId, revision)That immutable snapshot, or NOT_FOUND
history(productId, { before?, limit? }?)Current revision, newest-first snapshots and nextBefore cursor
resolvePin({ productId, revision, digest })The exact named snapshot, or refusal
setValues({ commandId, productId, expectedRevision, values, provenance? }){ productId, revision, digest, recordedAt, replayed }

A snapshot contains { protocol, productId, revision, digest, recordedAt, provenance, values }. Unset revision zero has an empty list and null time/provenance. Each value is { id, statement, application }; IDs use 1–40 lowercase letters, digits or hyphens, starting with a letter or digit. Provenance is { origin: "direct-entry" | "document-summary", note: string | null }, defaulting to direct entry with no note. History defaults to ten entries; before is a positive integer and selects strictly older revisions. GuidanceError.currentRevision is numeric for stale saves and otherwise null.

New saves use product-guidance/2: 0–8 ordered values, each with a unique stable ID, a statement and an application rule of 1–280 well-formed UTF-16 code units, without outer whitespace, controls, line separators, directional overrides/isolates or a byte-order mark. Saves are bounded to 16,384 canonical payload bytes, history to 500 revisions and pages to 20. Excess input is refused, never truncated. Revision zero is unset. Every accepted command, including clearing values, records one new revision with provenance. A document-summary must name its source; provenance is attribution, not authenticated authorship. Digests bind the protocol, Product, ordered values and provenance; pins retain revision and digest.

GuidanceError.code is INVALID, NOT_FOUND, STALE, CONFLICT, LIMIT or CORRUPT. Stale saves expose currentRevision; a changed request under a recorded command ID or a mismatched pin conflicts. Reads reconcile stored state with its history; disagreement refuses that Product instead of repairing it. Journal, registry and clock errors may also propagate. After an uncertain acknowledgement, retry exactly the same command ID and input to resolve its outcome. Never substitute a fresh command ID merely because the response was lost. If the registry has revoked the Product meanwhile, that replay returns NOT_FOUND, which says nothing about whether the earlier save committed: restore membership and replay the same command ID to settle it.

The Factory adapter and package core preserve existing aggregates, command receipts, immutable revisions, digests and pins. V1 records keep their six-value parser, digest and immutable revision. New saves append guidance.values-set.v2 with product-guidance-state/2; mixed history remains readable by the new reader. Revision zero always stays v1. Old readers refuse recorded guidance and writes after v2 appears; they cannot be used for rollback on that Product. Import, construction and installation write no guidance records. No live journal migration is part of this increment. When recomputing a historical digest, call guidanceDigest(snapshot.productId, snapshot.values, snapshot.provenance, snapshot.protocol); the default protocol is now v2. Existing pins stay {productId, revision, digest}. The versioned-save reference details the compatibility boundary and actual old-package fixture. Package-version compatibility follows the journal guide.

Verify the external consumer

Source distribution checks pack once, install into a temporary external application and check both public entry points and their declarations. Its guidance consumer runs with an empty executable search path and uses only named package imports. It changes from an object registry to a class registry across a real process restart, resolves historical pins, replays recorded commands, pages history, denies malformed and withdrawn identities, and checks corrupt state/history/receipts and cross-Product isolation. It creates only disposable consumer storage, without a Portfolio or Git setup.

The package proof and source/Factory compatibility checks are implementation evidence; independent Astra review passed, and it was accepted locally on 1 October 2026. No planner consumes guidance, no permission or acceptance criterion changes, and no release or customer-value claim follows from saving values.

Rehearse an atomic owner rationale

The separately authored v3 candidate is available through the existing project-guidance entry. Supply ProductGuidance with an explicitly qualified editFence, build a complete SetValuesWithRationaleInput using the canonical parser, and resolve the actual current owner decision for guidanceEditRequestDigest(input). The physical synchronous fence covers registry/authority writers and the Guidance commit, invokes once and returns its exact callback result. Tokens, summaries and input authority references alone are insufficient.

Use disposable verified copies only. Read exact v1/v2 pins and receipts before and after the first explicit v3 command; the same old IDs replay unchanged while fresh legacy writes refuse MIGRATION_REQUIRED. transition(pin) returns full v3 rationale or explicit rationale-not-recorded for older revisions. guidanceTransitionDigest is distinct from the unchanged default v2 digest.

The legacy Dashboard editor, CLI rehearsal, same-fence milestone writer, Ownership target /2, Acceptance and Guidance Tools support migrated reads/inspection and recorded replay. They do not authorise new v3 edits. No adapter invents a rationale or retargets an offered generation; unknown earlier exposure remains unresolved until reconciled. Exact grammar and inventory. Installed/final qualification and live execution remain separate gates.

For an explicitly commissioned later recollection, supply the separate supplementFence and GuidanceSupplementInput to appendRationaleSupplement. Authenticate current READ and the exact current owner request including permission to retain its text. Keep the original Guidance pin unchanged. Use rationaleSupplements(original) for minimal references and rationaleSupplement(ref) for a complete dated record. A legacy transition(pin) still reports its original rationale absent; the supplement is never inserted into it. The sixteen-record bound refuses whole overflow and no history is removed. Exact supplement profile.

Source: docs/how-to/adopt-project-guidance.md