🏭 Define factory lifecycle records and the validation frontier

[minkimcello]

Parent: #633

Architecture ancestry: PR #630

Planning base: 0479b3b1e6a3de08fb7d9de515a3efde80e7fe91; implementation base is the exact accepted C0 feedback commit recorded before handoff

Stack position: F6; parallel with F1, F3, F4, and F5; protocol prerequisite for L7–L10

Readiness: blocked only until C0's accepted feedback SHA is recorded and present; no lifecycle, identity, schema, compatibility, invalidation, or terminal choice is delegated

Purpose and observable outcome

The factory has one closed durable protocol for stages, active handoffs, exact implementation revisions, iteration, invalidation, evidence, review verdicts, conflict suspension, decisions, and terminal outcomes. Every lifecycle component validates against the same authoritative frontier before opening a remote effect.

Authoritative behavior

• Forward progress is exactly adjacent from Stage 1 User through Stage 8 Closed; same-stage amendment retains history and replaces only the active frontier entry.
• Backward invalidation records the earliest invalidated contract, deactivates every later accepted conclusion, and requires those stages again.
• Workflow definition SHA/run identity remain immutable; implementation identity is evolving { headSha, baseSha }. Any head change returns to Stage 4. Base-only movement returns to Stage 5 only when no synchronization/implementation work is required; otherwise Stage 4.
• Stage 5–7 outcomes bind the exact current revision. Stage 6 alone authorizes ready; Stage 7 alone authorizes merge/change/abandon.
• Project/comments/PR state are projections, never accepted outcome or identity. Durable identities derive from run and authored expansion, not context or Agent/provider text.
• Terminal kinds are exactly merged and abandoned, carrying the retained subjects/results settled in C0.

Current state

The workflow package has retained run/lifecycle/suspension/journal records, strict parsing, durable effect identity, and generated observation records. It has no factory-specific stage/frontier/revision/verdict/terminal schema. The draft factory spec describes the lifecycle but no implementation module enforces it.

Affected modules and public contracts

• Add the provider-neutral factory protocol under packages/workflow/src/factory/**, exported through the workflow public entrypoints, with immutable types, strict parsers, constructors/validators, deterministic identities, and bounded render values.
• Reuse Effection Result<T> for parse/validation outcomes; do not create local success/failure unions or trust type casts.
• Define journal-compatible values without adding a side database/table unless C0 explicitly requires one; accepted records travel through existing filtered durable events.
• Export only the provider-neutral values needed by authored components; runtime adapters receive no authority from them.
• Update the factory spec, workflow specs, architecture inventory, and public-entrypoint tests in the same commit.

Ordered implementation plan

1. Implement strict enums/records for stage, definition/run subject, implementation revision, handoff, amendment, invalidation, evidence, conflict, Planner verdict, Architect verdict, Stage 7 decision, and terminal settlement.
2. Implement deterministic record/effect identities from retained run and expansion subjects, excluding mutable presentation/provider state.
3. Implement the active-frontier reducer/validator for adjacent progress, same-stage replacement, backward invalidation, and exact revision movement without creating a separate controller.
4. Implement pre-effect guards that validate role/stage/revision/active-subject and return narrowed Effection failures.
5. Implement deterministic human rendering inputs for issue/PR handoffs and terminal summaries, excluding credentials/raw provider data.
6. Add strict replay/version refusal and public exports/spec inventory.

Failure, cancellation, teardown, and replay

Malformed, unknown-version, incomplete, contradictory, duplicate-active, skipped-stage, stale-revision, wrong-role, wrong-definition, and terminal-after-terminal records fail closed before any projection operation. Validation is pure/provider-free and allocates no durable resource, so cancellation has no cleanup beyond its caller's scope. Replay accepts only the exact frozen schema and reconstructs the same frontier without contacting GitHub or another provider.

Frozen evidence matrix

• Valid adjacent path records Stages 1–8 in order and refuses every skipped forward transition.
• Two same-stage amendments retain both records while exactly one remains active.
• Invalidation to each of Stages 1–6 deactivates exactly the downstream frontier and requires it again.
• Head-only, base-only/no-work, and base-needs-work observations choose Stages 4, 5, and 4.
• Stale Stage 5, 6, or 7 outcome and wrong active subject refuse before an effect request can be built.
• Project/comment/PR/context/Agent/provider values cannot manufacture identity or acceptance.
• Both terminal kinds parse/replay with exact actor/revision/result/reason requirements and reject reopening/completion contradictions.
• Unknown member/version and malformed retained data fail closed without migration.

Focused feedback evidence

Add explicit files such as packages/workflow/tests/factory-protocol-records.test.ts, factory-frontier.test.ts, factory-revision-invalidation.test.ts, and factory-terminal-records.test.ts, plus public-entrypoint coverage. Run those exact files and deno task test --changed. Commit immediately when they pass and report the exact F6 SHA and commands.

Delivery verification

Run deno task lint, deno task check, and deno task check:jsr because public retained contracts move. CI owns exhaustive suites.

Exclusions

No role prompt, XMD lifecycle control flow, GitHub/Git/process/provider effect, new database authority, permissive migration, context-trusted identity, or TypeScript controller that performs transitions.

Risks and recovery

This schema is a public persistence boundary for every lifecycle story. A structural change after L7 begins requires explicit C0/F6 amendment, a new accepted F6 feedback commit, and descendant restacking; it is never patched privately in one stage component.

Handoff

Record C0's exact feedback SHA, freeze the records and evidence above, and return the exact F6 feedback commit. L7–L10 implement authored control flow against this reviewed protocol and do not add alternate record shapes.