Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,9 @@ Protected source `src/agent-runtime/procedural-current-lifecycle.ts` provides a

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 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.
Protected source also binds paired evaluation receipts and evaluator/profile context into canonical evaluation identities, verifies a separately authenticated P-256 ECDSA evaluator handoff selected by the composition root, and binds rejection/disposition semantics into the signed claim identity. The verifier does not discover, rotate, store, or administer signer keys. Protected #597 adds bounded durable evaluation/rejection history under the existing State / Checkpoint boundary with monotonic CAS, exact replay, digest-chain integrity, duplicate-handoff refusal, restart reconstruction, and fail-closed bounded capacity. The retained history is evidence state only; it does not become Policy / Approval, graph publication, lifecycle, or activation authority.

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 and live signer trust selection to Keyverse/owner composition, and graph content/evaluation outcome truth to the owning product. Mutable sibling PR heads are not consumed. ADR 0017 remains `Proposed`; protected source integration does not establish live trust selection, non-workflow current-lifecycle revocation, Policy / Approval CAS, deployed Durable Object behavior/performance, graph publication, canary/rollback evidence, production activation, or organization-wide self-evolution.

## 5. Evidence and authority separation

Expand Down Expand Up @@ -142,7 +144,9 @@ 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. 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.
Procedural graph/session and candidate-decision authority remain process-local immutable values. In contrast, protected #597 owns bounded durable evaluation/rejection history under the existing State / Checkpoint boundary. It persists only admitted graph/evaluation/authenticated signed-claim identities and payload-minimized rejection evidence, validates monotonic CAS and exact replay, verifies the retained digest chain, reconstructs after restart, rejects duplicate handoff identity, and fails closed at its bounded capacity instead of silently evicting evidence. A retained history event is not retained activation authority: live signer trust, Policy / Approval promotion/revocation, graph publication, non-workflow lifecycle freshness/revocation, canary/rollback and product-owner outcome evidence remain separate owner-controlled boundaries.

Protected #589 separately reuses the existing durable Workflow / Task Execution state only as current task/cancellation evidence for workflow-backed advisory gating. It does not create another lifecycle store and does not turn Workflow / Task Execution into procedural-history authority. This separation keeps State / Checkpoint evidence retention, Workflow / Task current execution truth, Policy / Approval, and product-domain ownership distinct.

## 9. Standalone and modular MSA contract

Expand All @@ -161,7 +165,7 @@ The protected procedural-graph source itself remains intentionally non-durable.
| OIDC/GitHub App | issuer/audience/repository/workflow-ref, immutable workflow-source SHA when configured, malformed token/JWKS, replay, redirect/egress, secret non-disclosure regressions |
| Durable Objects | cross-instance semantics, delayed/retried alarm, current-state reschedule, malformed backend/storage-failure tests |
| External-extension lifecycle | legal-edge validation; restart/replay/CAS races; exact Policy / Approval and foreign-owner reference binding; corruption/truncation/cross-stream rejection; >128-transition auditability; O(1) verified current projection; full audit/recovery rehearsal; actual Durable Object p95/contention/storage-growth evidence before runtime acceptance |
| Procedural graph guidance | exact schema/identity bounds; graph/session local admission; canonical digest behavior; cycle-safe bounded neighborhood extraction; unknown/budget abstention; paired holdout separation and exact candidate/base/context binding; safety and measured-score non-regression; `activationAuthorized: false`; pure same-execution fresh lifecycle projection; workflow-backed plan/session identity rejection before durable lookup plus fresh current Workflow / Task Execution read per decision; later authenticated receipt/durable graph/non-workflow revocation/approval/canary/deployed-DO evidence before activation |
| Procedural graph guidance | exact schema/identity bounds; graph/session local admission; canonical digest behavior; cycle-safe bounded neighborhood extraction; unknown/budget abstention; paired holdout separation and exact candidate/base/context binding; safety and measured-score non-regression; `activationAuthorized: false`; exact receipt/envelope and authenticated evaluator-handoff binding; durable history CAS/replay/integrity/restart/capacity; pure same-execution fresh lifecycle projection; workflow-backed plan/session identity rejection before durable lookup plus fresh current Workflow / Task Execution read per decision; live trust selection/non-workflow revocation/Policy-Approval/deployed-DO/graph-publication/canary evidence before activation |
| GitHub Actions/control plane | least privilege, exact-head/live-base binding, full pagination, stale-head refusal, evidence-class separation |
| LLM integration | gateway contract, provider-key isolation, deterministic gates independent of model judgement |
| release/acquisition | protected source, CI/security/coverage, package/SBOM/provenance/reproducibility, licensing/NOTICE, rollback/recovery, later operational/buyer evidence |
Expand All @@ -174,7 +178,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, 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.
Protected procedural-graph source can authenticate the supplied evaluator assertion and retain bounded evaluation/rejection history, but it cannot establish live signer/trust selection, cross-language/released digest semantics, non-workflow current-lifecycle revocation, Policy / Approval promotion/revocation, deployed Workflow / Task or history-store behavior/performance, graph publication, canary operation, rollback success, or production outcome improvement. Those remain later owner, contract, Policy / Approval, operational, and product-owner evidence.

## 12. Canonical documentation graph

Expand All @@ -199,6 +203,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. 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.
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 over the existing canonical Workflow / Task Execution owner. Protected #597 adds a separate bounded State / Checkpoint history for evaluation/rejection evidence, not a second Workflow / Task or lifecycle truth. Any future release, live signer-trust selection, Policy / Approval promotion/revocation, graph publication, 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.
Loading
Loading