Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
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
18 changes: 10 additions & 8 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ These are separate ownership domains. Noema does not duplicate their internal au

This revision adds a candidate Tool / Capability admission port at `src/tool-capability/external-extension-admission.ts` for external Claude community plugins. It is not an HTTP route and does not change `/health`, `/ready`, or `/exchange`. Marketplace discovery, Anthropic review, and plugin packaging are not runtime authority. The port stays a local fail-closed ACL until an immutable `context-graph-contracts` artifact contract exists.

Candidate PR #574 adds a durable lifecycle aggregate behind that admission boundary without expanding foreign ownership. `src/tool-capability/external-extension-lifecycle-store.ts` partitions one event stream by the complete exact extension/source/artifact identity and persists Noema lifecycle transition/version/head authority plus immutable Policy / Approval, AppGuardrail, quarantine/isolation, and Egress references/digests. It does not persist mutable scanner verdicts, quarantine runtime truth, outbound policy bodies, provider routing, raw secrets, product payloads, or hidden reasoning.
Protected source includes the durable lifecycle aggregate behind that admission boundary without expanding foreign ownership. `src/tool-capability/external-extension-lifecycle-store.ts` partitions one event stream by the complete exact extension/source/artifact identity and persists Noema lifecycle transition/version/head authority plus immutable Policy / Approval, AppGuardrail, quarantine/isolation, and Egress references/digests. It does not persist mutable scanner verdicts, quarantine runtime truth, outbound policy bodies, provider routing, raw secrets, product payloads, or hidden reasoning.

```mermaid
flowchart LR
Expand All @@ -90,9 +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.

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 alone does not establish authenticated evaluation receipts, durable graph history, current-lifecycle revocation, Policy / Approval CAS, 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 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.

## 5. Evidence and authority separation

Expand Down Expand Up @@ -138,9 +140,9 @@ Model-facing automation uses the `NOEMA_LLM_*` gateway contract where applicable

Durable Object alarms are at-least-once. Handlers reread current deadline/expiry state and **reschedule** from current state so delayed alarms cannot delete newer state. Storage-class, binding-name, or lifecycle changes require migration/rollback analysis.

Candidate #574 adds 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`.
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 is intentionally non-durable. A graph digest or successful held-out screen is not retained activation authority. Durable history, authenticated evaluation receipts, current-lifecycle revocation, approval CAS, canary state, rollback and recovery require a later owner-approved boundary; 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. 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.

## 9. Standalone and modular MSA contract

Expand All @@ -159,7 +161,7 @@ The protected procedural-graph source is intentionally non-durable. A graph dige
| 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`; fresh authenticated lifecycle snapshot on execution projection; later authenticated receipt/durable revocation/approval/canary 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`; 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 |
| 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 @@ -170,9 +172,9 @@ Owned production remains subject to exact 100% statement/branch/function/line co

Repository source/docs cannot fabricate stronger live `main` governance than the current ruleset, independent approval, App provisioning, reviewer staffing, protected production approval, immutable release/signing/provenance, 30-day KPI evidence, customer/revenue evidence, or legal transfer authority. These remain separate evidence classes and fail closed when required but absent.

Candidate lifecycle source also 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 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 cannot establish authenticated evaluation provenance, cross-language/released digest semantics, durable version history, current-lifecycle revocation, approval, canary operation, rollback success, or production outcome improvement. Those remain later contract, Policy / Approval, operational, and product-owner 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.

## 12. Canonical documentation graph

Expand All @@ -197,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. It may select localized procedural context and screen a direct child candidate, and its execution adapter may project that context only against a caller-supplied fresh authenticated `running` lifecycle snapshot. Any future persistence, release, approval, 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. 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.

Architecture changes must keep source behavior, realistic regression tests, canonical documentation, traceability, and CHANGELOG semantics consistent without promoting active-PR behavior to protected truth.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
- Add a Noema-owned exact-claim evidence receipt contract whose execution and research producers serialize one canonical artifact that binds every receipt semantic field, including command/result/isolation/network or source revision/excerpt/retrieval policy. Admission accepts only a receipt ID from untrusted model output. The owner API first verifies the exact authenticated OpenCode-handoff manifest digest, canonical envelope bytes, reviewed producer-to-kind policy, and repository/head/workflow/run/attempt identity before it can construct an immutable typed index; admission then reconstructs each canonical artifact and verifies time/claim/artifact identity. The version-2 manifest now binds a separate producer-authenticated `ClaimEvidenceRequirement` containing the exact claim, independently required evidence kind, and `context` or `finding` publication authority. Raw current-head source lines are context only: they are withheld from finding-reference prompts and cannot publish a finding or `request_changes`; an explicitly producer-authorized source finding remains usable and retains exact path/line checks. Finding-free model `request_changes` and `blocked` verdicts cannot bypass receipt admission to publish a vacuous blocking review. Requirement/receipt kind mismatch, fixed-artifact semantic substitution, caller-supplied receipt dictionaries, model self-classification, stale identities, cross-kind receipts, marker-only sandbox output, noncanonical artifact bytes, and expired receipts fail closed before the GitHub publisher. This remains the owner prerequisite for ContextualWisdomLab/.github#1641 and issue #555. The reviewed `sandboxed_verify` adapter exists in owner source, but its actual central stdout/stderr/marker-to-manifest wiring and the trusted research producer are not yet integrated; exact-head hosted GREEN, immutable release, and the verified central consumer bump remain required.

## Unreleased
- Agent Runtime의 workflow-backed procedural guidance가 매 판단마다 기존 execution-scoped `NOEMA_WORKFLOW_STATE`의 current Workflow / Task Execution evidence를 다시 읽는다. re-admitted plan과 locally admitted procedural session의 canonical execution identity가 다르면 Durable Object를 선택하거나 읽기 전에 실패-폐쇄하고, 현재 cancellation·terminal·pre-start evidence는 guidance를 억제한다. 이 ACL은 두 번째 lifecycle DB, task/lifecycle mutation, retry, tool, Policy / Approval, provider routing 또는 activation authority를 만들지 않으며 non-workflow lifecycle freshness와 deployed Durable Object compatibility/p95/recovery는 별도 acceptance로 남긴다. issue #584, ADR 0017.
- Agent Runtime에 tenant/task/execution-scoped immutable procedural graph와 bounded advisory context, paired held-out candidate screening을 추가한다. 모든 candidate decision은 `activationAuthorized: false`를 유지하고 tool·retry·Policy/Approval·provider routing·credential·foreign-domain authority를 부여하지 않는다. 그래프/평가 wire contract는 아직 Noema-local이며 cross-service publication은 context-graph-contracts의 immutable release를 기다린다. issue #584, ADR 0017.
- Agent Runtime의 procedural guidance를 locally admitted session brand와 canonical execution lifecycle에 결합한다. 구조만 흉내 낸 session은 callback/property를 읽기 전에 거부하고, guidance는 동일 execution의 `running` 상태에서만 반환하며 accepted·cancellation-requested·terminal 상태에서는 context request를 읽지 않고 억제한다. 결과는 계속 `advisory_only`이고 tool·retry·Policy/Approval·transition authority를 만들지 않는다. issue #584.
- External-extension lifecycle의 private Durable Object command surface에 `read_operability`를 추가해 exact stream-scoped SQLite `ctx.storage.sql.databaseSize`를 `{ database_size_bytes }`로만 노출한다. canonical object-name binding이 다르면 409로 거부하고, 음수·비정수 storage counter는 내부 오류로 실패-폐쇄해 #561의 실제 per-object storage-growth evidence producer가 synthetic fixture나 namespace aggregate 대신 deployed object-local byte counter를 소비할 수 있게 한다. 이 경로는 lifecycle event payload·foreign-owner truth·secret·provider routing을 노출하지 않으며 remote p95/contention/recovery, production activation authority, deployment 또는 immutable release acceptance를 대신하지 않는다. issue #561.
Expand Down
Loading
Loading