Factory docs, home
Page navigation

Reference document, shown as written except that local paths appear as placeholders. Where it describes the Factory as intended, read it as design, not current state: only local infrastructure is accepted, no release, customer value or scheduled automation is established, and all 27 customer-value epics remain open. Current state: Factory model.

Six views, from broad to detailed. All are proposals; the contracts they rely on are in design.

1. Value lifecycle

Customer availability is distinct from assessment, the recorded comparison of observed results with the intended outcome. Supported, rejected and inconclusive assessments all guide the next decision; only an outcome assessed as supported counts as a value win.

Diagram source (Mermaid), shown as text
flowchart LR
  OB[Business objective] --> PB[Customer problem]
  PB --> SL[Validated slice]
  SL --> CA[Candidate]
  CA --> VD{Independent verdict}
  VD -->|failed or inconclusive| CA
  VD -->|verified| RL[Safe release and confirmed availability]
  RL --> OC[Assessment]
  OC -->|feedback signals| PB
  OC --> KR{Keep, renew or retire}
  KR -->|renew| SL
  KR -->|retire| RT[Retire with migration]

2. Domains and recovery

Five domains own decisions and three shared foundations serve them. Recovery lives outside the factory.

Diagram source (Mermaid), shown as text
flowchart TB
  subgraph FA[Factory application]
  PR[Planning: value, priority, retirement] -->|slice| DL[Delivery: build and repair]
  DL -->|candidate| AS[Assurance: independent verdict]
  AS -->|verdict| OP[Operations: release, health, recovery]
  OP -->|confirmed release facts| GR[Growth: docs, site, launch]
  OP -->|health and usage signals| PR
  GR -->|acquisition results| PR
  subgraph FD[Foundations shared by every domain]
    EX[Execution]
    EV[Evidence store]
    AG[Action gateway]
  end
  end
  RC[Independent Operations recovery] -->|restores healthy release and compatible state| FA
  RC -->|availability and recovery without factory| PA[Customer-facing products]

3. Durable runtime

The proposed stack is one modular TypeScript application with PostgreSQL, Temporal and an artefact store. PostgreSQL owns business facts and public run state. One transaction records command results, owned state and events, projections and outbox messages. Temporal owns the execution cursor and deduplicates delivered messages. Terminal runs stay terminal; incomplete runs reconcile against durable step results.

Diagram source (Mermaid), shown as text
flowchart LR
  C[Command with stable ID] --> D[Owner validates current version]
  D --> TX[Atomic database commit]
  TX --> F[Facts, run state, result and projections]
  TX --> O[Outbox]
  O --> W[Temporal: cursor and timers]
  W -->|Retry-safe next command| D
  F -.->|Views only, no actions| R[Projection rebuild]

Small interfaces, deep implementations

FoundationInterface, hidden detail and first proof
ExecutionStart, inspect or cancel a pinned recipe; hides durable cursor, isolation and worker ownership. Prove crash recovery and stale-worker rejection.
Evidence storeCollect and retrieve attributable evidence; hides storage, integrity and retention. Prove tampering is rejected and deletion survives restore.
Action gatewayRequest or reconcile an authorised effect; hides provider protocols and effect uncertainty. Prove a lost acknowledgement cannot cause a blind repeat.

One application does not mean one privilege identity. Isolated builders cannot write authoritative assurance records or obtain release credentials. Enforce these boundaries through execution identities and protected storage, not import rules alone.

4. Protected release

Independent verdicts gate each exposure, and customer health decides promotion. A manifest links source revision, build inputs and artefact digest, each checked against its own identity.

Diagram source (Mermaid), shown as text
flowchart LR
  CA[Prospective merge-queue candidate] --> AS{Protected scenarios, security, privacy, UI}
  AS -->|failed| RP[Repair]
  RP --> CA
  AS -->|verified| IQ[Integrate exact verified revision]
  IQ --> AV{Risk and product policy}
  AV -->|potentially unsafe| AL[Alpha]
  AV -->|permitted direct release| ST[Stable]
  AL --> HG{Customer health}
  HG -->|harm| RB[Rollback, disable or forward repair]
  RB --> RP
  HG -->|healthy| ST[Stable]
  ST -->|post-release harm| RB
  ST --> AP[Channel receipt and customer-path probe]
  AP --> MS[Assessment]
  AP --> DC[Docs and launch from confirmed availability]
  MS -->|signals| PR[Planning]

5. Capability disposition and health

Retirement and health are independent. Healing restores safe required behaviour, or its approved replacement, and leaves any retirement decision intact.

Diagram source (Mermaid), shown as text
flowchart LR
  R[Required] -->|Planning decision within authority and policy| T[Retiring]
  T -->|Migration verified, data handled| X[Retired]
  T -->|Retirement reconsidered| R
  H[Healthy] -->|Observed regression| D[Degraded]
  D -->|Safe behaviour re-proved| H
  U[Unknown] -->|Independent observation| H
  U -->|Regression confirmed| D

6. Uncertain external effect

A lost acknowledgement leads to reconciliation, never to a blind second write.

Diagram source (Mermaid), shown as text
sequenceDiagram
  participant D as Owning domain
  participant G as Action gateway
  participant X as External system
  D->>G: Request action with domain occurrence key
  G->>G: Record requested, check current authority, policy, epoch and verdict
  G->>X: Dispatch
  X--xG: Acknowledgement lost
  G->>G: Mark unknown, no blind retry
  G->>X: Reconcile by key
  alt Confirmed
    G->>D: Receipt
  else Proven not applied
    G->>G: Back to requested, recheck guards
  else Still unknown
    G->>G: Durable wait, other work continues
  end

Source: docs/architecture.md