Skip to content
Merged
10 changes: 5 additions & 5 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,11 +90,11 @@ The arrows from foreign owners carry immutable evidence identities only. Noema d

Protected source includes a library-only Agent Runtime aggregate for bounded procedural guidance. `src/agent-runtime/procedural-graph.ts` admits one immutable tenant/task/graph snapshot, canonicalizes nodes and directed relationships, computes local content/structure digests, and pins a module-admitted session to one canonical execution identity. `src/agent-runtime/procedural-evolution.ts` screens a direct child graph against paired held-out evidence but always returns `activationAuthorized: false`; eligibility is evidence for a later independent approval boundary, not permission to publish or execute a graph. `src/agent-runtime/procedural-execution.ts` additionally projects guidance only when its caller supplies a fresh authenticated `running` lifecycle snapshot for the same execution identity; it does not itself become durable lifecycle or revocation authority.

On this active branch, candidate `src/agent-runtime/procedural-current-lifecycle.ts` adds a workflow-backed current-state ACL over the existing execution-scoped Workflow / Task Execution Durable Object. The ACL re-admits the workflow plan and validates the locally admitted procedural session against the same canonical execution identity before it selects or reads any Durable Object. It then performs the existing private workflow-state `read`, validates current execution/plan/task/cancellation evidence, and projects only a conservative Agent Runtime lifecycle state into the already-protected running-only procedural gate. Current cancellation, terminal work and pre-start evidence suppress guidance. The ACL cannot mutate workflow state, create lifecycle transitions or retries, grant tools or Policy / Approval, or authorize graph activation.
Protected source `src/agent-runtime/procedural-current-lifecycle.ts` provides a workflow-backed current-state ACL over the existing execution-scoped Workflow / Task Execution Durable Object. The ACL re-admits the workflow plan and validates the locally admitted procedural session against the same canonical execution identity before it selects or reads any Durable Object. It then performs the existing private workflow-state `read`, validates current execution/plan/task/cancellation evidence, and projects only a conservative Agent Runtime lifecycle state into the already-protected running-only procedural gate. Current cancellation, terminal work and pre-start evidence suppress guidance. The ACL cannot mutate workflow state, create lifecycle transitions or retries, grant tools or Policy / Approval, or authorize graph activation.

The aggregate deliberately owns only Noema runtime mechanics. Procedural text is inert advisory data and is not tool authority, Policy / Approval, a prompt-injection verdict, a secret/PII scrubber, or product-domain truth. Graph/session WeakSet admission prevents structural lookalikes from becoming local runtime capabilities. Unknown procedures and context-budget overflow abstain without a hidden full-graph fallback. Execution identities reuse the canonical Agent Runtime grammar rather than defining a second identity domain.

Cross-product ownership remains outside this protected advisory boundary: released wire contracts belong to `context-graph-contracts`, enterprise adoption/decision records to `enterprise-architecture-core`, model routing to `contextual-orchestrator`, credentials to Keyverse, and graph content/evaluation truth to the owning product. Mutable sibling PR heads are not consumed. ADR 0017 remains `Proposed`; protected source integration plus the active workflow-backed ACL candidate do not establish authenticated evaluation receipts, durable graph history, non-workflow current-lifecycle revocation, Policy / Approval CAS, deployed Durable Object behavior, canary/rollback evidence, production activation, or organization-wide self-evolution.
Cross-product ownership remains outside this protected advisory boundary: released wire contracts belong to `context-graph-contracts`, enterprise adoption/decision records to `enterprise-architecture-core`, model routing to `contextual-orchestrator`, credentials to Keyverse, and graph content/evaluation truth to the owning product. Mutable sibling PR heads are not consumed. ADR 0017 remains `Proposed`; protected source integration does not establish authenticated evaluation receipts, durable graph history, non-workflow current-lifecycle revocation, Policy / Approval CAS, deployed Durable Object behavior, canary/rollback evidence, production activation, or organization-wide self-evolution.

## 5. Evidence and authority separation

Expand Down Expand Up @@ -142,7 +142,7 @@ Durable Object alarms are at-least-once. Handlers reread current deadline/expiry

Protected source includes separate Durable Object storage semantics for external-extension lifecycle evidence. The event log is append-only and is not the bounded Workflow / Task receipt ledger. Event/request digests are computed outside the short transaction; the transaction revalidates expected version, prior state, and prior head digest before atomically writing event + idempotency index + compact head. `readCurrent()` verifies only the head and exact tail for the latency-sensitive path, whereas `readAudit()` verifies every retained version/hash link and final head/tail identity. Corrupt or truncated durable state is a conflict, never an empty stream. Recovery and rollback must preserve acknowledged history and follow `docs/external-extension-lifecycle-recovery.md`.

The protected procedural-graph source itself remains intentionally non-durable. A graph digest or successful held-out screen is not retained activation authority. Candidate #589 reuses the existing durable Workflow / Task Execution state only as current task/cancellation evidence for workflow-backed advisory gating; it does not persist graph history, approval, or activation state and does not replace Agent Runtime lifecycle ownership. Durable graph/rejection history, authenticated evaluation receipts, non-workflow current-lifecycle revocation, approval CAS, canary state, rollback and recovery require later owner-approved boundaries; adding those concerns directly to the library aggregate would collapse State / Checkpoint, Policy / Approval, and product-domain ownership.
The protected procedural-graph source itself remains intentionally non-durable. A graph digest or successful held-out screen is not retained activation authority. Protected #589 reuses the existing durable Workflow / Task Execution state only as current task/cancellation evidence for workflow-backed advisory gating; it does not persist graph history, approval, or activation state and does not replace Agent Runtime lifecycle ownership. Durable graph/rejection history, authenticated evaluation receipts, non-workflow current-lifecycle revocation, approval CAS, canary state, rollback and recovery require later owner-approved boundaries; adding those concerns directly to the library aggregate would collapse State / Checkpoint, Policy / Approval, and product-domain ownership.

## 9. Standalone and modular MSA contract

Expand Down Expand Up @@ -174,7 +174,7 @@ Repository source/docs cannot fabricate stronger live `main` governance than the

Protected external-extension lifecycle source cannot establish actual Durable Object p95, contention/partition behavior, backup/restore success, production recovery, or deployed invocation enforcement by documentation alone. Those remain later exact operational evidence.

Protected procedural-graph source and candidate #589 cannot establish authenticated evaluation provenance, cross-language/released digest semantics, durable graph version history, non-workflow current-lifecycle revocation, approval, deployed workflow-state ACL behavior, canary operation, rollback success, or production outcome improvement. Those remain later contract, Policy / Approval, operational, and product-owner evidence.
Protected procedural-graph source, including #589, cannot establish authenticated evaluation provenance, cross-language/released digest semantics, durable graph version history, non-workflow current-lifecycle revocation, approval, deployed workflow-state ACL behavior, canary operation, rollback success, or production outcome improvement. Those remain later contract, Policy / Approval, operational, and product-owner evidence.

## 12. Canonical documentation graph

Expand All @@ -199,6 +199,6 @@ The default shape is **small credential-exchange service + explicit state coordi

The external-extension lifecycle remains a bounded Tool Capability / State / Checkpoint aggregate rather than a new scanner, quarantine runtime, egress engine, identity provider, or model router. Its synchronous projection path and full audit/recovery path are deliberately separate so buyer/runtime latency does not require scanning retained history while recovery still verifies the complete chain.

The protected procedural-graph advisory remains a bounded Agent Runtime aggregate rather than an execution engine or autonomous policy plane. Its pure execution adapter may project localized context against a caller-supplied fresh authenticated same-execution `running` lifecycle snapshot. On this active branch, candidate #589 adds only a workflow-backed current-state ACL: it reuses the existing canonical Workflow / Task Execution durable owner for fresh task/cancellation evidence and rejects plan/session execution mismatch before durable lookup. Any future graph persistence, release, approval, non-workflow current-lifecycle revocation, canary, or activation path must cross explicit versioned owner contracts and retain `activationAuthorized: false` until those independent authorities are proven.
The protected procedural-graph advisory remains a bounded Agent Runtime aggregate rather than an execution engine or autonomous policy plane. Its pure execution adapter may project localized context against a caller-supplied fresh authenticated same-execution `running` lifecycle snapshot. Protected #589 adds only a workflow-backed current-state ACL: it reuses the existing canonical Workflow / Task Execution durable owner for fresh task/cancellation evidence and rejects plan/session execution mismatch before durable lookup. Any future graph persistence, release, approval, non-workflow current-lifecycle revocation, canary, or activation path must cross explicit versioned owner contracts and retain `activationAuthorized: false` until those independent authorities are proven.

Architecture changes must keep source behavior, realistic regression tests, canonical documentation, traceability, and CHANGELOG semantics consistent without promoting active-PR behavior to protected truth.
6 changes: 3 additions & 3 deletions docs/PRD.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Protected `main` includes a bounded **procedural graph advisory runtime** inside

Protected source also includes the #586 execution-lifecycle adapter. It projects procedural guidance only when the caller supplies a fresh authenticated `running` lifecycle snapshot for the same canonical execution identity and suppresses guidance for accepted, cancellation-requested, or terminal states. The adapter is not itself durable lifecycle/revocation authority and cannot prove that a canonical `running` snapshot has not become stale after the caller obtained it.

On this active branch, candidate #589 adds a workflow-backed current-state ACL without replacing that pure adapter. It re-admits the workflow plan, validates the locally admitted procedural session against the same canonical execution identity before selecting any execution-scoped Durable Object, then re-reads the existing Workflow / Task Execution owner before each guidance decision. Current cancellation, terminal task evidence, and pre-start evidence suppress guidance; only other current nonterminal workflow evidence can reach the existing running-only advisory gate. This candidate does not make Workflow / Task Execution the Agent Runtime lifecycle store and does not grant mutation, retry, Policy / Approval, tool, release, or activation authority. Non-workflow Agent Runtime callers still require their own fresh authenticated lifecycle source, and source/fake-Durable-Object tests do not establish deployed Durable Object compatibility, restart behavior, availability, or synchronous buyer-path p95.
Protected source includes the #589 workflow-backed current-state ACL without replacing that pure adapter. It re-admits the workflow plan, validates the locally admitted procedural session against the same canonical execution identity before selecting any execution-scoped Durable Object, then re-reads the existing Workflow / Task Execution owner before each guidance decision. Current cancellation, terminal task evidence, and pre-start evidence suppress guidance; only other current nonterminal workflow evidence can reach the existing running-only advisory gate. This protected ACL does not make Workflow / Task Execution the Agent Runtime lifecycle store and does not grant mutation, retry, Policy / Approval, tool, release, or activation authority. Non-workflow Agent Runtime callers still require their own fresh authenticated lifecycle source, and source/fake-Durable-Object tests do not establish deployed Durable Object compatibility, restart behavior, availability, or synchronous buyer-path p95.

Procedural graph ownership follows existing CWL boundaries. Any released cross-service schema belongs to `context-graph-contracts`; enterprise adoption/decision records belong to `enterprise-architecture-core`; model discovery/routing remains in `contextual-orchestrator`; credentials remain in Keyverse; graph content and outcome/evaluation truth remain with the consuming product. Noema owns only the execution-local advisory mechanics and deterministic candidate-screening port. Mutable sibling PR heads are not production dependencies.

Expand Down Expand Up @@ -137,7 +137,7 @@ Procedural graph ownership follows existing CWL boundaries. Any released cross-s
| FR-021 | Model discovery, routing, test-time compute, provider failover, and provider credentials remain owned by `contextual-orchestrator`; Noema runtime code must not duplicate direct provider SDKs, credentials, fallback lists, or routing policy. |
| FR-022 | Workflow/task, tool/capability, isolation, policy/approval, observability, recovery, Context Graph, and EA integration must cross explicit versioned ports/contracts; Context Graph integration must use immutable released versioned contracts, reject open or unreleased Draft contracts, and require conformance/admission evidence, canonical object/authority references, provenance, and valid/system time semantics. Arbitrary tool authority, ambient secret propagation, unbounded recursive work, silent side-effect retry, unreleased Context Graph source coupling, and cross-service SQL are forbidden. |
| FR-023 | External-extension lifecycle authority must be append-only, exact-stream partitioned, restart-reconstructable, and CAS-serialized; current projection must be cryptographically bound to its audit tail, full audit must detect sequence/hash/stream truncation or substitution, exact duplicate replay must preserve committed history, and every genuinely new activation must bind a fresh Noema Policy / Approval and owner-evidence re-read without copying foreign-owner truth. |
| FR-024 | Procedural graph guidance must remain tenant/task/execution scoped, immutable and advisory-only; reject forged graph/session identities and unsafe input, return bounded localized context or explicit abstention, bind candidate screening to exact direct-child lineage and paired held-out context, prevent train/holdout leakage, reject safety or measured-score regression, and keep activation unauthorized. The protected pure adapter requires a caller-supplied fresh authenticated same-execution `running` lifecycle snapshot. For workflow-backed guidance on this active branch, the plan/session execution identity must match before any execution-scoped durable lookup and the canonical Workflow / Task Execution owner must be re-read before every decision. Non-workflow lifecycle freshness, released contracts, authenticated evaluation evidence, Policy / Approval, durable graph/rejection history, deployment evidence and rollout authority remain separate prerequisites. |
| FR-024 | Procedural graph guidance must remain tenant/task/execution scoped, immutable and advisory-only; reject forged graph/session identities and unsafe input, return bounded localized context or explicit abstention, bind candidate screening to exact direct-child lineage and paired held-out context, prevent train/holdout leakage, reject safety or measured-score regression, and keep activation unauthorized. The protected pure adapter requires a caller-supplied fresh authenticated same-execution `running` lifecycle snapshot. For protected workflow-backed guidance, the plan/session execution identity must match before any execution-scoped durable lookup and the canonical Workflow / Task Execution owner must be re-read before every decision. Non-workflow lifecycle freshness, released contracts, authenticated evaluation evidence, Policy / Approval, durable graph/rejection history, deployment evidence and rollout authority remain separate prerequisites. |

## 6. Non-functional requirements

Expand Down Expand Up @@ -234,4 +234,4 @@ An earlier stage never proves a later stage.
- `docs/external-extension-lifecycle-recovery.md` — dedicated external-extension restart, audit-chain, corruption, CAS-contention, and rollback recovery contract.
- `docs/DOCUMENTATION_GAP_AUDIT.md` — design sufficiency versus protected-main operational sufficiency.
- runtime and automation threat models — distinct threat surfaces.
- `docs/LICENSING_AND_IP_TRANSFER.md` — owner/legal and exact-release rights boundary.
- `docs/LICENSING_AND_IP_TRANSFER.md` — owner/legal and exact-release rights boundary.
Loading
Loading