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.

Visual understanding · Workflow diagrams

These are information-flow diagrams, not import graphs. Arrows mean a caller passes or records information; they do not imply automatic dispatch. Contracts own exact field names and bounds; the build review owns current acceptance.

Calendar

Input supplier: Caller with validated civil dates and zone data. Input: Gregorian date or ISO week, local time, canonical zone and epoch milliseconds. Calendar: Convert dates and instants using fixed fold and gap rules. Output: Civil-date arithmetic or a classified invalid input. Consumer: Owner policy, Lifecycle schedule and planning modules. Boundary: Internal pure foundation with no public package entry. Host ICU data supplies zone rules; it reads no clock and starts no schedule.

Feed it: Gregorian date or ISO week, local time, canonical zone and epoch milliseconds. Supplier: Caller with validated civil dates and zone data.

Use its result: Civil-date arithmetic or a classified invalid input. Consumer: Owner policy, Lifecycle schedule and planning modules.

Boundary: Internal pure foundation with no public package entry. Host ICU data supplies zone rules; it reads no clock and starts no schedule.

Human guide · Exact contract · Open full-size diagram

Command journal

Input supplier: Application commands. Input: Stable command ID, payload, expected version and aggregate ID. Command journal: Commit one decision atomically; replay the original answer. Output: State, command receipt, Events and outbox rows. Consumer: Execution and other journal-backed modules. Boundary: Replay covers the journal decision. External effects are separate; the outbox has no delivery worker.

Feed it: Stable command ID, payload, expected version and aggregate ID. Supplier: Application commands.

Use its result: State, command receipt, Events and outbox rows. Consumer: Execution and other journal-backed modules.

Boundary: Replay covers the journal decision. External effects are separate; the outbox has no delivery worker.

Human guide · Exact contract · Open full-size diagram

Execution

Input supplier: Controller through the journal. Input: Run pins, fixed Budget, owner and Attempt epoch. Execution: Record Run ownership, cancellation and bounded Attempts. Output: Run and Attempt states, versions and recorded outcomes. Consumer: Guarded verification controller. Boundary: Starts no process, measures no time and issues no Verdict. Completion means the recipe ended.

Feed it: Run pins, fixed Budget, owner and Attempt epoch. Supplier: Controller through the journal.

Use its result: Run and Attempt states, versions and recorded outcomes. Consumer: Guarded verification controller.

Boundary: Starts no process, measures no time and issues no Verdict. Completion means the recipe ended.

Human guide · Exact contract · Open full-size diagram

Attempt fence / workspace

Input supplier: Controller with Execution identity. Input: Run, Attempt epoch, owner token and caller-owned local storage. Attempt fence / workspace: Hold one ownership fence and create one private workspace. Output: Fence identity, workspace reference and closing proof. Consumer: Fixture worker, collector and recovery. Boundary: A closed fence prevents protected work resuming. It does not prove process exit or provide a sandbox.

Feed it: Run, Attempt epoch, owner token and caller-owned local storage. Supplier: Controller with Execution identity.

Use its result: Fence identity, workspace reference and closing proof. Consumer: Fixture worker, collector and recovery.

Boundary: A closed fence prevents protected work resuming. It does not prove process exit or provide a sandbox.

Human guide · Exact contract · Open full-size diagram

Local fixture worker

Input supplier: Guarded verification. Input: Built-in fixture, exact resource pins, bounds and held fence. Local fixture worker: Run one trusted fixture process and observe it. Output: Stored Evidence and bounded process report. Consumer: Guarded verification and Assurance. Boundary: Runs fixed synthetic fixtures. It never judges results and is not an arbitrary-code sandbox.

Feed it: Built-in fixture, exact resource pins, bounds and held fence. Supplier: Guarded verification.

Use its result: Stored Evidence and bounded process report. Consumer: Guarded verification and Assurance.

Boundary: Runs fixed synthetic fixtures. It never judges results and is not an arbitrary-code sandbox.

Human guide · Exact contract · Open full-size diagram

Evidence / assurance

Input supplier: Worker or trusted local collector. Input: Observed bytes and exact pins; complete stored references for judgement. Evidence / Assurance: Store immutable observations; judge a pinned fixture expectation. Output: Evidence references; Verified, Failed or Inconclusive Verdict. Consumer: Guarded verification; repository modules use the Evidence store. Boundary: Printed claims are not proof. Missing evidence is Inconclusive; fixture Verdicts cannot become repository Verdicts.

Feed it: Observed bytes and exact pins; complete stored references for judgement. Supplier: Worker or trusted local collector.

Use its result: Evidence references; Verified, Failed or Inconclusive Verdict. Consumer: Guarded verification; repository modules use the Evidence store.

Boundary: Printed claims are not proof. Missing evidence is Inconclusive; fixture Verdicts cannot become repository Verdicts.

Human guide · Exact contract · Open full-size diagram

Guarded verification / recovery

Input supplier: Fixture CLI or application controller. Input: Fixture name, Run identity, pins, Budget and durable state. Guarded verification / recovery: Prepare, claim, dispatch and settle; reconcile orphaned Attempts. Output: Historical Verdict, current validity and recovery outcome. Consumer: Fixture CLI and its caller. Boundary: Working local fixture composition. Recovery stays bounded; a held fence can mean wait, not takeover.

Feed it: Fixture name, Run identity, pins, Budget and durable state. Supplier: Fixture CLI or application controller.

Use its result: Historical Verdict, current validity and recovery outcome. Consumer: Fixture CLI and its caller.

Boundary: Working local fixture composition. Recovery stays bounded; a held fence can mean wait, not takeover.

Human guide · Exact contract · Open full-size diagram

Source: docs/explanation/visual-foundations.md