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.

This bounded E28 draft adds three private ESM entry points to the same software-factory artefact as the command journal. Independent Astra review passed; it 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 establishes no worker, provider, complete Workflow or live scheduled job.

Follow the journal installation guide to obtain and install the local tarball. It stays private at draft version 0.1.0; every draft build keeps that version, so pin the exact artefact integrity because draft builds differ. Node.js ≥26.8.1 is required. The external proof uses Node.js 26.8.1 on macOS 27 arm64, with local SQLite storage and the host's ICU time-zone data. Other hosts remain unverified. There are no npm runtime dependencies.

Record a Run

import { CommandJournal } from 'software-factory/command-journal';
import { Execution } from 'software-factory/execution';

const journal = CommandJournal.open('./caller.sqlite');
try {
  const execution = new Execution(journal);
  execution.submit({
    commandId: 'submit:one', runId: 'one',
    pins: {
      candidateDigest: `sha256:${'a'.repeat(64)}`,
      recipeRevision: 'caller.recipe/1', scenarioRevision: 'caller.scenario/1',
    },
    budget: { maxAttempts: 2, attemptTimeoutMs: 60000 },
  });
  const claim = execution.claim({
    commandId: 'claim:one', runId: 'one', expectedVersion: 1, worker: 'caller:worker',
  });
  console.log(claim.run.status, claim.attempt.epoch, claim.replayed);
} finally {
  journal.close();
}

Execution records ownership; the host starts and stops work. Never launch from a replayed claim. Reopen the caller's file with openExisting and read current ownership first. submit, claim, complete, fail, interrupt, requestCancel, cancel, read and history retain the source contract. Run pins and Budget are fixed at submission. Attempts have increasing epochs, at most 20; stale epochs and terminal transitions are refused. Cancellation stays pending until an allowed cleanup confirmation settles it. The host owns truthful cleanup confirmation and timeout enforcement. Completion is not a Verdict.

The entry point exports Execution, EXECUTION_LIMITS, typed commands, Runs, Attempts, Budget and its coded error classes. ExecutionError.code distinguishes missing/existing/terminal Runs, active/stale Attempts, pending cancellation and corrupt state. Journal errors pass through. IDs, evidence references and strict object validation retain existing bounds; rejected commands write nothing.

Drive a schedule with a caller clock

import { LifecycleSchedule, proposedCommission } from 'software-factory/lifecycle-schedule';

// Use the same package's CommandJournal and a clock owned by the host.
const schedule = new LifecycleSchedule(journal, { now: () => Date.now() });
const proposal = proposedCommission({
  products: ['example'], effectiveFrom: '2026-09-29', weeklyTokens: 10000,
});
// Review the proposal before recording it as the host's commission.

The host supplies the commission, account statements, time and observations. proposedCommission is a proposal, not authority. recordCommission, recordAccount, start, admitCall, endCall, defer, reconcile, settle, read, plan and status retain their typed contracts. Only admitted: true with dispatch: true permits one contact. A replay never does; an uncertain dispatch is recorded as lost and cannot be retried as new work. Account records are trusted statements, not authenticated sign-in evidence.

Usage stops defer the same occurrence until its permitted slot. Unknown calls keep their bound debited. A new commission cannot extend the current week's ceiling. Another runner cannot take ownership merely because time passed; reconciliation needs truthful confirmation that the previous runner stopped. ScheduleError.code reports malformed or corrupt inputs, conflicts, ownership, state and bound refusals; call admission returns a typed refusal instead. A caller clock can be substituted through Clock.now(); the module never starts a scheduler or contacts a provider.

The entry point also exports the versioned commission/schedule protocols, bounded types, SCHEDULE_LIMITS, occurrence and time helpers, and LaunchAgent text renderers. Rendering text installs nothing. The legacy LifecycleSchedule keeps its fixed discovery/schedule aggregate and Account = "claude" | "chatgpt". For caller-owned instances use the additive /2 API below; existing default types and records keep their meaning. Neither Schedule nor Execution owns the journal lifecycle; the caller closes it.

Caller-owned schedule instances

LifecycleScheduleV2(journal, clock, identity) takes ScheduleIdentity: {protocol: 'sf-schedule-identity/1', aggregateId, accounts}. The aggregate is a bounded ASCII ID other than discovery/schedule; accounts are one to sixteen sorted, distinct ASCII IDs. Supply a ScheduleCommissionV2 with protocol: 'sf-schedule-commission/2', that exact identity and rhythm calls naming only those accounts. parseCommissionV2 and commissionDigestV2 validate and hash it. proposedCommission remains a legacy proposal; converting its account assignments requires the caller's explicit commission.

Identity is frozen, stored and digest-bound. All receipts use instance-specific schedule-command/<sha256> IDs; occurrences also carry an instance digest. Multiple instances can share a journal without borrowing commands or budgets. Reopening the same aggregate with different accounts refuses; no records migrate. The caller must coordinate any real shared subscription ceiling: separate ledgers do not combine account budgets. Replay never grants another dispatch, and unknown effects retain their bound.

lanesOfV2, the versioned occurrence lookup and ID parser, and scheduleIdentityDigest support the explicit identity. Their public declarations specify the exact caller types. launchIntervals and the LaunchAgent convenience path remain /1 helpers; rendering them installs nothing. The shared engine preserves legacy raw receipts and refusal ordering.

Inspect deterministic model policy

import { REGISTRY, chooseModel, taskPolicyDigest } from 'software-factory/intelligence';

const task = REGISTRY.modules.flatMap(module => module.tasks)
  .find(task => task.id === 'producer/propose');
const selection = chooseModel({
  taskId: task.id,
  requested: {
    provider: task.pin.provider, model: task.pin.model,
    effort: task.pin.effort, transport: task.pin.transport,
    commission: `sha256:${'0'.repeat(64)}`,
    policy: taskPolicyDigest(task.id),
  },
});
console.log(selection); // Refused: the bundled Claude route is unavailable for the Factory's model roles, and no model is qualified.

// A task may list several approved entries. Choose once, before contact, with the policy only,
// and record the whole result with your frozen work and admission.
const chosen = chooseModel({ taskId: task.id, requested: { policy: taskPolicyDigest(task.id) } });
// chosen.choice.entry says which entry (1-based) was taken; chosen.choice.skipped lists every entry
// ahead of it that a recorded fact refused, each with its code and reason. Nothing is chosen outside the list.

Intelligence is pure policy data and selection. Its declarations, registry, bounds, renderers and typed chooseModel/taskPolicyDigest contracts are exported. Malformed requests or registries throw TypeError; other refusals are values. It never substitutes models or effort, retries or makes provider calls. A caller may supply a conforming registry, but that supplies policy data, not authenticated qualification or authority. The host remains responsible for trusted provenance, independent verification and any later dispatch.

Priority lists. A task names its pin, then up to three then entries, in order. chooseModel has two forms. With the policy digest only (the choose form), it takes the first entry no recorded fact refuses and records each entry it passed over with its code (proposed, not-qualified, implicit-retries or not-independent); if none is eligible it refuses no-eligible-entry with every reason. With one entry named in full (the verify form, as every request was before), it accepts that entry only if it is the first eligible one now. Record the choose form's result with the frozen work and admission, then use the verify form naming the recorded entry at dispatch and on resume, so a resumed call runs that entry or refuses and never walks on. A host that chooses again at dispatch has not frozen anything. A partial naming group is a TypeError. The policy digest covers the whole list, so editing any entry, its fact or the order makes work frozen under the task refuse policy-mismatch.

Declaring a route. A route is data: { id, provider, tools, note } in registry.tiers.transports (one to sixteen; absent means the frozen TRANSPORTS_V1, the three routes the package has always allowed). Provider and route ids are lowercase words with digits and hyphens, and predetermined is refused. A fact's provider must be its route's, and only a drafter may use a route with tools: 'research'. A list holds at most four entries (INTELLIGENCE_LIMITS), and a malformed route or list is refused when the registry loads, never cut. A request naming a well-formed route or provider the registry does not declare matches no entry and is refused as a value; only a malformed name is a TypeError. A caller-declared provider selects through this contract with no edit to the package, but selecting is all it does: the Producers contract's closed ProviderId means nothing can qualify it, and declaring a caller schedule account does not establish a provider or model qualification. Dispatch still needs independently reviewed admission and transport authority.

Composition with the schedule. The accepted schedule maps tasks to accounts statically and records no model. A task with then is therefore not admissible through it until its admission records the chosen entry and checks that provider's account; this guide does not close that gap, and nothing dispatches today.

Compatibility. The package is a draft at 0.1.0, so its types may widen: Provider and Transport became strings, ModelRequest.requested is a union of the two forms, ModelChoice gained entry and skipped, ModelSelection gained a no-eligible-entry variant, and RefusalCode gained proposed and no-eligible-entry. Task ids, existing refusal codes and the sf-intelligence/1 policy encoding keep their meaning, and a one-entry task digests as it did. A request, producer identity or failed escalation that names a well-formed route or provider the registry does not declare was a TypeError and is now a refusal value. On 1 October 2026 the bundled registry also marked every Claude model unavailable for the Factory's model roles and gave discovery's triage and weekly synthesis an OpenAI entry first (proposed, so never selectable); the repository's docs/intelligence-priority-receipt.json records every changed policy digest.

Verify the artefact

Source distribution checks pack the artefact and install it into a disposable application outside Factory. They retain every journal check and add all three public imports, declarations, exact packaged closure, ownership/Budget/cancellation, commission/usage/unknown-effect bounds, caller clock and registry substitution, and source/package state compatibility. Intelligence runs with filesystem writes, network and child processes denied.

The foundations entry points' combined runtime closure is exactly eight files: journal, canonical-json, errors, execution, lifecycle-schedule, calendar, schedule-error and intelligence, using only Node's built-in sqlite, fs, perf_hooks, url, buffer and crypto. For the packaging increment, source behaviour, stored schemas, command IDs and existing receipts were unchanged; the 1 October 2026 Intelligence change above alters that entry's behaviour and types, and its own receipt records it. Future incompatible storage changes need the journal guide's explicit migration and compatibility proof; draft builds are identified by tarball integrity, not version. Packaging executable resources, proving other platforms and completing the remaining adoption gates are separate work.

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