{
  "schema_version": "0.1",
  "artifact_type": "architecture",
  "canonical": true,
  "artifact_id": "ARCH-008",
  "agent_summary": {
    "title": "Deterministic workflow execution architecture",
    "status": "approved",
    "summary": "A strict interpreter executes versioned workflow definitions through an allowlisted action registry, persists WFR checkpoints and receipts atomically, and pauses only for validated external judgment or authority.",
    "last_reviewed_at": "2026-07-14",
    "load_notes": "Canonical JSON; generate Markdown only on explicit human request."
  },
  "context": "Existing deterministic components are individually strong but orchestration remains distributed across host prompts, skills, hooks, and repeated LLM decisions. The engine must compose those components without duplicating their authorities or hiding judgment inside mechanical actions.",
  "principles": [
    "Deterministic by construction, not by prompt instruction.",
    "One config authority, one workflow catalog, one run state machine, existing canonical state tools.",
    "No false success: postconditions, receipts, and explicit terminal states.",
    "No arbitrary definition code and no direct LLM project-truth writes.",
    "Provider-neutral judgment bundles; AI-Collab owns optional execution.",
    "Compatibility wrappers may call the engine, but shipped orchestration has one authority."
  ],
  "components": [
    {"id": "ARCH-COMP-039", "summary": "Workflow catalog and schema", "responsibility": "Load shipped plus explicitly allowed custom definitions, normalize them, validate actions/inputs/permissions/postconditions, hash definitions, and audit coverage.", "requirement_ids": ["PRD-REQ-048", "PRD-REQ-053"], "interface_ids": ["ARCH-IF-032", "ARCH-IF-033"]},
    {"id": "ARCH-COMP-040", "summary": "Deterministic interpreter", "responsibility": "Plan and execute ordered steps with conditions, references, postconditions, legal transitions, failure policy, retries, and deterministic outputs.", "requirement_ids": ["PRD-REQ-049", "PRD-NFR-027"], "interface_ids": ["ARCH-IF-034"]},
    {"id": "ARCH-COMP-041", "summary": "Run store and WFR allocator", "responsibility": "Atomically persist runs, checkpoints, receipts, hashes, idempotency keys, and terminal outcomes under the shared lock/registry invariants.", "requirement_ids": ["PRD-REQ-050", "PRD-NFR-028"], "interface_ids": ["ARCH-IF-035"]},
    {"id": "ARCH-COMP-042", "summary": "Allowlisted action registry", "responsibility": "Bind declared action names to typed handlers with determinism, mutation, idempotency, capability, and timeout metadata; reject injected execution.", "requirement_ids": ["PRD-REQ-051", "PRD-NFR-029"], "interface_ids": ["ARCH-IF-033", "ARCH-IF-036"]},
    {"id": "ARCH-COMP-043", "summary": "Judgment gateway", "responsibility": "Build immutable source-bounded requests, pause runs, validate provider-neutral results, and resume without granting model write authority.", "requirement_ids": ["PRD-REQ-052", "PRD-NFR-029", "PRD-NFR-030"], "interface_ids": ["ARCH-IF-037"]},
    {"id": "ARCH-COMP-044", "summary": "Workflow management interfaces", "responsibility": "Expose catalog/action inventory, audit, plan, run, resume, status, cancel, and retry through CLI, MCP, and read-only UTCP surfaces.", "requirement_ids": ["PRD-REQ-054"], "interface_ids": ["ARCH-IF-038"]},
    {"id": "ARCH-COMP-045", "summary": "Lifecycle and hook integration", "responsibility": "Route shipped host events and lifecycle use cases through catalog definitions while retaining specialized deterministic consumers and blocking semantics.", "requirement_ids": ["PRD-REQ-055", "PRD-NFR-032"], "interface_ids": ["ARCH-IF-039"]},
    {"id": "ARCH-COMP-046", "summary": "Delivery, migration, and release layer", "responsibility": "Install workflow runtime/definitions/state/config/tools/skills additively, validate mirrors, document migration, and enforce release completeness.", "requirement_ids": ["PRD-REQ-056", "PRD-REQ-057", "PRD-NFR-031", "PRD-NFR-032"], "interface_ids": ["ARCH-IF-032", "ARCH-IF-038"]}
  ],
  "interfaces": [
    {"id": "ARCH-IF-032", "summary": "Workflow catalog document", "producer": "hub templates and additive installer migration", "consumer": "catalog loader and operators", "contract": "Schema version, unique workflow names, description, enabled/default policy, inputs, ordered typed steps, postconditions, permissions, and failure policy."},
    {"id": "ARCH-IF-033", "summary": "Action descriptor", "producer": "action registry", "consumer": "catalog audit and interpreter", "contract": "Name, determinism class, input/output schema, mutation level, idempotency, capability, timeout, and handler."},
    {"id": "ARCH-IF-034", "summary": "Execution plan", "producer": "interpreter planner", "consumer": "dry-run output and run executor", "contract": "Definition/input hashes, resolved steps, conditions, required capabilities, judgment count, mutation/external summary, and expected terminal postconditions."},
    {"id": "ARCH-IF-035", "summary": "Workflow run record", "producer": "interpreter and run store", "consumer": "resume/status/audit and Substrate", "contract": "WFR ID, workflow/version/hashes, idempotency key, state, current step, receipts, context, pending judgment, timestamps, error, and outcome."},
    {"id": "ARCH-IF-036", "summary": "Action invocation", "producer": "interpreter", "consumer": "registered handler", "contract": "Validated resolved arguments plus immutable run context; returns typed output and receipt or explicit failure without hidden fallback."},
    {"id": "ARCH-IF-037", "summary": "Judgment request/result", "producer": "judgment gateway/external executor", "consumer": "AI-Collab and deterministic validator", "contract": "Request ID, task/profile, prompt/instructions, allowed source refs, JSON result schema, constraints and hash; result must match run/step/hash and source allowlist."},
    {"id": "ARCH-IF-038", "summary": "Management API", "producer": "CLI/MCP/UTCP adapters", "consumer": "operators, agents, and runtimes", "contract": "Bounded list/audit/plan/run/resume/status/cancel/retry/action inventory operations with worker-session mutation guards."},
    {"id": "ARCH-IF-039", "summary": "Hook/lifecycle trigger", "producer": "Codex, Claude, OpenCode, slash commands, or skills", "consumer": "workflow interpreter", "contract": "Named workflow plus validated event/input payload; host-specific block/exit output is preserved."}
  ],
  "data_state_model": {
    "persistent_config_authority": ".prd_plugin/config.json#workflows",
    "shipped_catalog": ".prd_plugin/workflows.json (from templates/workflows.json)",
    "run_store": ".prd_plugin/state/workflow-runs.json",
    "run_ids": "WFR-* allocated under the shared registry lock",
    "judgment_execution": "AI-Collab resolves configured executor/profile; PRD Plugin builds and validates contracts",
    "canonical_mutations": "registered MCP/state actions only; judgment results are data, never direct writes",
    "local_transients": ".prd_plugin/local/workflows for optional non-canonical large receipts; secrets excluded"
  },
  "decisions": [
    {"id": "ARCH-DEC-030", "summary": "Use one strict interpreter over declarative JSON definitions rather than hard-coded workflow functions.", "rationale": "Definitions stay inspectable/configurable and catalog audit can prove every step is registered.", "source_ids": ["PRD-REQ-048", "PRD-REQ-049"]},
    {"id": "ARCH-DEC-031", "summary": "Use registered action names only; never execute code embedded in workflow JSON.", "rationale": "Configuration must select authority, not create new authority or command injection.", "source_ids": ["PRD-REQ-051", "PRD-NFR-029"]},
    {"id": "ARCH-DEC-032", "summary": "Persist resumable WFR records with action receipts and idempotency keys.", "rationale": "Retries and crashes must not duplicate canonical writes or external effects.", "source_ids": ["PRD-REQ-050", "PRD-NFR-028"]},
    {"id": "ARCH-DEC-033", "summary": "Treat judgment as a pause/resume data contract; the engine never calls a model directly.", "rationale": "This preserves provider neutrality, keeps runtime execution in AI-Collab, and makes every model boundary auditable.", "source_ids": ["PRD-REQ-052", "PRD-NFR-029", "PRD-NFR-031"]},
    {"id": "ARCH-DEC-034", "summary": "Define success soundly: completion requires declared postconditions, while unavailable dependencies produce explicit non-success states.", "rationale": "Universal execution success is impossible; false success is preventable.", "source_ids": ["PRD-NFR-027"]},
    {"id": "ARCH-DEC-035", "summary": "Keep .prd_plugin/config.json as policy authority and workflows.json as versioned definition data.", "rationale": "Policy and executable declarations have different ownership while avoiding a second settings authority.", "source_ids": ["PRD-REQ-048", "PRD-REQ-053"]},
    {"id": "ARCH-DEC-036", "summary": "Route existing hooks and lifecycle entrypoints through engine definitions while retaining specialized action implementations.", "rationale": "One orchestration authority avoids competing workflows without rewriting proven consumers.", "source_ids": ["PRD-REQ-055", "PRD-NFR-032"]},
    {"id": "ARCH-DEC-037", "summary": "Default custom definitions and mutation-capable external actions off; enable only through explicit config policy and action allowlists.", "rationale": "Configurability must not silently widen execution authority.", "source_ids": ["PRD-REQ-053", "PRD-NFR-029"]}
  ],
  "risks": [
    {"id": "ARCH-RISK-025", "summary": "Definitions and handlers drift.", "mitigation": "Catalog audit, definition hashes, action coverage tests, and release gate.", "status": "mitigated"},
    {"id": "ARCH-RISK-026", "summary": "A replay duplicates a mutation.", "mitigation": "WFR idempotency key, per-step receipts, shared locks, and handler idempotency declarations.", "status": "mitigated"},
    {"id": "ARCH-RISK-027", "summary": "Judgment output fabricates sources.", "mitigation": "Exact allowed-source validation and run/step/request hashes.", "status": "mitigated"},
    {"id": "ARCH-RISK-028", "summary": "External commands gain excess authority.", "mitigation": "No arbitrary definition code, mutation class policy, trusted shipped definitions, and explicit config gates.", "status": "mitigated"},
    {"id": "ARCH-RISK-029", "summary": "Large outputs bloat canonical state.", "mitigation": "Bounded receipts, hashes, summaries, and optional ignored local detail files.", "status": "mitigated"},
    {"id": "ARCH-RISK-030", "summary": "Host block semantics change.", "mitigation": "Characterization and cross-host integration tests around engine-triggered hooks.", "status": "mitigated"},
    {"id": "ARCH-RISK-031", "summary": "Installer overwrites downstream workflows or history.", "mitigation": "Shipped definitions refresh as managed files; config and workflow-runs remain protected and migrated additively.", "status": "mitigated"},
    {"id": "ARCH-RISK-032", "summary": "An LLM is invoked for deterministic work despite the catalog.", "mitigation": "Determinism-class audit, judgment-count planning, runtime receipts, and workflow coverage reporting.", "status": "mitigated"}
  ],
  "validation_strategy": [
    "RED/GREEN unit tests for schema, action registry, planner, state machine, persistence, idempotency, references, judgment validation, and terminal postconditions.",
    "Integration tests for CLI/MCP/UTCP parity, hooks, existing deterministic components, lifecycle definitions, worker guards, and additive installation.",
    "Catalog coverage audit requires all shipped workflows/actions/config controls classified and all supported use cases represented.",
    "Focused verification per independently committed track, then one release-wide suite and repeated CHML review/fix/re-audit to zero."
  ],
  "traceability": {
    "source_ids": ["REQ-096", "PRD-REQ-048", "PRD-REQ-049", "PRD-REQ-050", "PRD-REQ-051", "PRD-REQ-052", "PRD-REQ-053", "PRD-REQ-054", "PRD-REQ-055", "PRD-REQ-056", "PRD-REQ-057"],
    "implementation_task_ids": ["IMP-TASK-058", "IMP-TASK-059", "IMP-TASK-060", "IMP-TASK-061", "IMP-TASK-062", "IMP-TASK-063", "IMP-TASK-064", "IMP-TASK-065", "IMP-TASK-066", "IMP-TASK-067"],
    "tracking_ids": ["TRK-101", "TRK-102", "TRK-103", "TRK-104", "TRK-105"],
    "health_ids": []
  }
}