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 component was accepted locally on 1 October 2026; publication and live host qualification remain separate gates. One caller-owned local Journal retains typed proposals, pre-offer revisions and permanent first-offer ownership. It starts no delivery. A receipt records ownership, never permission to contact or receiver acceptance.

Contract and dependencies

Import software-factory/proposal-ownership. Node.js 26.8.1 or later, ESM and a trusted local SQLite filesystem are required; no runtime npm dependencies. Public declarations compile with strict ES2024 and types:[]. Supply an already opened Command Journal, persistent producer/store/namespace/Product scope and a synchronous current-authority fence. Constructors capture methods and call none. Reads, pending pages and fixed-v1 replay are passive.

Exactly two inert targets exist: required Guidance input under guidance-set-values/2, and an actual Branch health notification under branch-health-notification/1. No URL, executable callback, arbitrary command, receipt ingestion or terminal-release API exists. The application validates actual source truth and current authority. Hashes establish byte consistency, not permission.

Journal and fence methods must return synchronously. Native Promise results, including nested own string and symbol data, are observed before the original refusal checks. Observation visits at most 24 nested levels and 1,048,576 descriptor/value steps; it invokes neither generic thenables nor returned data accessors and does not walk prototypes. Observing a native Promise uses Promise.prototype.then, which may still read its constructor and Symbol.species, so a Promise subclass or constructor accessor can run host code. Fulfilment values and rejection reasons share the original observation allowance; they cannot alter the original synchronous refusal. Native Promise own properties are skipped after attaching reactions. A failed observation also leaves outcome classification to the original validation. An asynchronous or malformed reply after possible commit stays UNKNOWN_COMMIT. Reconcile with the same original mutation ID, actor, expected version and payload; the module never retries automatically.

A disposable local example

This example is a deterministic test caller, not a live grant. The caller owns both files and the fixed reviewed rule. Its authority database supplies the local lock and explicit observation; every other authority writer would need that same lock. Re-running preserves the original IDs and receipts. No receiver is contacted.

import { DatabaseSync } from 'node:sqlite';
import { CommandJournal } from 'software-factory/command-journal';
import { ProposalOwnership } from 'software-factory/proposal-ownership';

const journal = CommandJournal.open('./proposals.sqlite');
const authority = new DatabaseSync('./proposal-authority.sqlite');
authority.exec('CREATE TABLE IF NOT EXISTS authority (id INTEGER PRIMARY KEY, allowed INTEGER, observed TEXT)');
authority.prepare('INSERT OR IGNORE INTO authority VALUES (1,1,?)').run('2026-10-01T00:00:00.000Z');
const scope = {producerId:'owner',storeId:'example-store',namespace:'values',productId:'sample'};
const digest = 'sha256:' + 'a'.repeat(64);
const rule = {id:'reviewed-values',revision:1,digest,requiredRoles:['root']};
const source = {producerId:'owner',storeId:'facts',kind:'immutable-record',recordId:'values-request',revision:1,payloadDigest:digest};
const target = {kind:'guidance-set-values/2',receiverId:'guidance',receiverStoreId:'values-store'};
const notBefore = '2026-10-01T00:00:00.000Z', expiresAt = '2026-10-02T00:00:00.000Z';
const fence = {run(request,commit) {
  authority.exec('BEGIN IMMEDIATE');
  try {
    const row = authority.prepare('SELECT allowed,observed FROM authority WHERE id=1').get();
    const result = commit({protocol:'sf-proposal-ownership-admission/1',requestDigest:request.requestDigest,
      scope:request.scope,actorId:request.mutation.actorId,checkedAt:row.observed,
      authorityRevision:1,authorityDigest:digest,decision:row.allowed?'allow':'deny',semanticChecks:'passed'});
    authority.exec('COMMIT'); return result;
  } catch (error) { authority.exec('ROLLBACK'); throw error; }
}};
// This host creates and retains this exact Journal/fence pair together.
const owner = new ProposalOwnership(journal,scope,fence);
const record = (mutationId,expectedVersion,action) => owner.mutate({
  protocol:'sf-proposal-ownership-mutation/1',mutationId,actorId:'owner',expectedVersion,action});
try {
  record('commission',0,{kind:'initialise',commission:{protocol:'sf-proposal-ownership-commission/1',
    scope,policy:rule,notBefore,expiresAt,permittedTargets:[target]}});
  record('proposal',1,{kind:'propose',occurrence:{root:{id:'values-request',source},ruleId:rule.id,
    occurrenceId:'initial-values',notBefore,expiresAt,parentOperations:[]},draft:{rule,
    causes:[{role:'root',source}],intent:{target,body:{productId:'sample',expectedRevision:0,
      values:[{id:'privacy',statement:'Private by default',application:'Keep personal data on the device'}],
      provenance:{origin:'direct-entry',note:null}}}}});
  const generation = owner.read().operations[0].generations[0];
  const {logicalOperationId,commandId,payloadDigest} = generation;
  record('offer',2,{kind:'first-offer',identity:{logicalOperationId,generation:1,commandId,payloadDigest}});
  console.log(owner.read().operations[0].generations[0].firstOffer.effect);
} finally { journal.close(); authority.close(); }

The output is unknown, including on replay. ownershipValues.guidanceInput(generation) validates and copies the retained guidance-sfpc-<64hex> ID and body. Calling the real Guidance receiver is a separate caller action; no delivery or generic inbox contract is implied.

Authority, atomicity and uncertainty

The host must qualify the actual physical Journal and authority-lock owner as one pair. Matching serialised IDs cannot bind two different files. Reject a different opened handle before constructing this module. All ACL, grant and rule writers use the same non-expiring local outer lock, then Journal's write lock. Read current authority after waiting; invoke the commit callback synchronously exactly once, hold the lock through commit or rollback and return that exact result object. No Promise, lease or later callback is supported. The module validates the admission but cannot authenticate a dishonest host.

Every new action requires its own current allow and passed admission. Unknown permission is unavailable. Cancel/expire may use current closure permission after commission expiry. Historical replay bypasses fresh authority and is never contact authority. checkedAt is the locked observation time, not physical commit time; any future sender needs a separate final current-contact fence.

One aggregate atomically serialises first offer and supersession. The stale loser must reread. Once offered, that generation remains permanently owned through cancellation, expiry, lost acknowledgement and process death. No replacement or release exists. UNKNOWN_COMMIT preserves the mutation ID: inspect or repeat the identical request, never invent a new ID. SQLite and any receiver are separate transactions.

Bounds and fixed history

One immutable commission and exact reviewed rule permit at most eight targets, roots and lifetime operations; four generations per operation; eight causes including exactly one root; two parents; depth four; four direct children per parent/root. Notification targets require one exact trigger source in the same eight causes. Source identity includes producer, store, kind, record and revision; conflicting retained bytes refuse.

Maximums intersect: 256 retained pins and 64 KiB catalogue; 22 KiB generation base plus 2 KiB reserved controls; 64 KiB mutation/event; 128 KiB non-frame state and 1 MiB whole state. Frame bytes, the offer and closure are reserved for every admitted operation; a supersede may still be refused (LIMIT) by the shared 64 KiB cause catalogue. The closed grammar requires at most 49 of 64 lifetime transitions; exhaustion cannot recycle ownership or erase originals. Causes, scopes and targets are plain exact-key JSON; timestamps are explicit UTC milliseconds in 2000–2099, positive lifetimes at most 31 days. No clock or expiry default exists.

read() replays the captured version's original event prefix in at most four pages of sixteen and compares the derived state. Concurrent later events do not alter that prefix. Missing or forged history returns CORRUPT; it never repairs. parseState checks self-consistency; replay checks original transitions. Trusted storage and physical identity remain necessary against wholly substituted stores. pending({atVersion,afterOrdinal,limit}) is passive inspection of up to eight retained operations, including closed ones; it advances no delivery cursor.

Factory-specific parts

The ownership lifecycle is neutral, but both targets are the Factory's own receivers, compiled in. You cannot register another target or body codec. Line numbers refer to origin/main at 85a5472.

  • The Target and Intent unions name exactly guidance-set-values/2 and branch-health-notification/1 (src/proposal-ownership-contract.ts:33-38). targetOf refuses any other kind as UNSUPPORTED (src/proposal-ownership-core.ts:61-66).
  • A Guidance body is checked by the Factory's Guidance input parser and a notification body by its provider-event parser (src/proposal-ownership-core.ts:5-6, src/proposal-ownership-core.ts:69-74). A notification target also needs the fixed profile sf-provider-events/branch-health-polled/1 and one trigger cause from the branch-health poll it reports (src/proposal-ownership-core.ts:64, src/proposal-ownership-core.ts:81-86).
  • Guidance command IDs start guidance-sfpc- and all others sfpc: (src/proposal-ownership-core.ts:120).

The target is hashed into each operation's identity (sf-proposal-operation/1, src/proposal-ownership-core.ts:118) and retained in /1 commissions, mutations and state. Adding, renaming or changing a target therefore needs a new protocol version, as the separately selected /2 notification grammar below shows. Existing /1 histories keep their meaning and are never migrated.

Remaining gates

This packet supplies no transport attempts, receiver inbox, domain acceptance, automatic catch-up, model request or live provider qualification. EV3 and T36.5 require separate reviewed extensions. Process-crash proof does not prove power-loss durability or multi-host safety. Review the exact private artefact and source revision; no registry release or production adoption is established.

Additive notification mode

The separate fixed notification mode uses the original aggregate and public entry with a once-selected /2 grammar. Its corrected component source/package retains its separate review; historical 7cf combined native execution and independent bounded local evidence acceptance passed. Existing /1 histories, six-action API and Guidance conversion remain unchanged; no transport sender or receiver acceptance is added to them.

Source: docs/how-to/adopt-proposal-ownership.md