From eddf383652406a8786890a5a950884216a72ab30 Mon Sep 17 00:00:00 2001 From: Raskolnikoff Date: Wed, 11 Feb 2026 15:53:06 +0900 Subject: [PATCH 1/2] =?UTF-8?q?EPIC=200:=20Contract=20Lock=20=E2=80=94=20a?= =?UTF-8?q?dd=20formal=20API,=20constraint,=20and=20authority=20contracts?= =?UTF-8?q?=20(v1.0.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 19 ++ docs/adr/adr-0006.md | 349 ++++++++++++++++++++++++++ docs/contracts/README.md | 16 ++ docs/contracts/api-schema.md | 91 +++++++ docs/contracts/authority-model.md | 39 +++ docs/contracts/constraint-contract.md | 60 +++++ docs/contracts/invocation-boundary.md | 0 7 files changed, 574 insertions(+) create mode 100644 docs/adr/adr-0006.md create mode 100644 docs/contracts/README.md create mode 100644 docs/contracts/api-schema.md create mode 100644 docs/contracts/authority-model.md create mode 100644 docs/contracts/constraint-contract.md create mode 100644 docs/contracts/invocation-boundary.md diff --git a/.gitignore b/.gitignore index 18e0bd3..4b51b29 100644 --- a/.gitignore +++ b/.gitignore @@ -81,3 +81,22 @@ fabric.properties .DS_Store *.swp artifacts/ + +# Prevent accidental runtime additions +node_modules/ +dist/ +build/ +coverage/ + +# Prevent accidental JS/TS toolchain +package.json +package-lock.json +tsconfig.json +jest.config.js +.eslintrc.js + +# Prevent accidental source files +*.ts +*.tsx +*.jsx + diff --git a/docs/adr/adr-0006.md b/docs/adr/adr-0006.md new file mode 100644 index 0000000..e025909 --- /dev/null +++ b/docs/adr/adr-0006.md @@ -0,0 +1,349 @@ +# ADR-0006: Contract Lock — Architectural Invariants Frozen + +## Status +Accepted + +## Date +2026-02-11 + +## Context + +The RAGfish / Noema ecosystem has matured through several architectural decision records: + +- **ADR-0001**: Established RAGpack ZIP format and removed tokenizer dependencies +- **ADR-0004**: Introduced the Architecture Constitution defining three-layer architecture +- **ADR-0005**: Established client-side routing as a first-class architectural principle + +These ADRs collectively define a stable architectural foundation. However, the critical contracts that bind these layers together—the invocation boundary, API schema, constraint model, and authority distribution—have existed only as implicit agreements or scattered across documentation. + +As implementations of this architecture begin (Noesis Noema client, noema-agent execution service), the need for **explicit, immutable contract specifications** has become critical. + +### Problem + +Without formalized contracts: +- Implementations may drift from architectural intent +- Boundary violations may go undetected until deployment +- Authority distribution may become ambiguous +- Constraint enforcement may become inconsistent +- Human accountability may erode through convenience-driven compromises + +The risk of implicit contracts is that they encourage "pragmatic" shortcuts that incrementally violate core principles without triggering architectural review. + +### Need for Immutability + +Early-stage architectural flexibility is valuable, but RAGfish has now reached a point where core contracts must stabilize to enable: +- Parallel implementation across multiple components +- Automated compliance testing +- Long-term architectural governance +- Human accountability preservation + +Treating contracts as mutable invites gradual erosion. Treating them as immutable forces deliberate, reviewed changes. + +## Decision + +We establish a **Contract Lock** on the architectural invariants of the RAGfish / Noema system. + +Specifically, we freeze the following as **canonical specifications** at version 1.0.0: + +### 1. Invocation Boundary Specification + +The boundary between client and execution layers is formally defined and locked. + +**Document**: `docs/contracts/invocation-boundary.md` + +**Invariants**: +- Client constructs RoutingDecision +- noema-agent executes only given ExecutionContext +- RAGpack returns KnowledgeReference only +- No upward or lateral decision authority + +**Enforcement**: These invariants must be preserved in all implementations. Any violation is an architectural failure requiring immediate remediation. + +### 2. API Schema Specification + +The conceptual data structures that cross layer boundaries are formally defined and locked. + +**Document**: `docs/contracts/api-schema.md` + +**Structures**: +- InvocationRequest +- InvocationResponse +- RoutingDecision +- ExecutionContext +- ExecutionResult / ExecutionError +- ExecutionMetadata +- KnowledgeReference + +**Version**: 1.0.0 + +**Immutability**: The schema is immutable. Any change to required fields or field semantics constitutes a breaking change requiring a new ADR. + +### 3. Constraint Contract Specification + +The rules governing constraint creation, propagation, and enforcement are formally defined and locked. + +**Document**: `docs/contracts/constraint-contract.md` + +**Rules**: +- Constraints flow downward only +- Execution layer must not mutate constraints +- Routing decision must originate from client layer +- Stateless execution is mandatory +- Evidence attachment required + +**Enforcement**: Constraint violations must abort execution immediately and generate incident reports. + +### 4. Authority Model Specification + +The distribution of decision-making authority across all actors is formally defined and locked. + +**Document**: `docs/contracts/authority-model.md` + +**Authority Hierarchy**: +- Human = Ultimate Authority +- Client = Decision Authority +- noema-agent = Execution Authority +- RAGpack = Knowledge Authority + +**Principle**: Human accountability is inviolate. No authority may be delegated to autonomous AI systems. + +## Rationale + +### Why Lock These Contracts Now? + +1. **Prevent Architectural Drift**: Once implementations begin, incremental changes accumulate without review. Locking contracts early prevents architectural erosion through convenience. + +2. **Enable Parallel Development**: Multiple teams can implement different components against a stable contract without constant coordination or synchronization. + +3. **Ensure Testability**: Formal contracts enable automated validation that implementations comply with architectural intent, catching violations before deployment. + +4. **Preserve Accountability**: Explicit authority model prevents ambiguity about who is responsible for decisions, maintaining human accountability. + +5. **Support Governance**: Clear contracts make it possible to audit compliance with architectural principles objectively. + +6. **Force Discipline**: Immutability ensures contract changes receive deliberate review rather than slipping through as "minor fixes." + +### Why Markdown Specifications? + +This repository is **documentation-only** by design. We deliberately avoid executable code to prevent this repository from becoming an implementation that ossifies the architecture. + +**Markdown specifications**: +- Are human-readable and human-reviewable +- Can be versioned independently of implementations +- Do not impose language or framework choices +- Remain stable across technology changes +- Are accessible to non-technical stakeholders +- Support governance and audit processes + +**Avoids**: +- Language lock-in (TypeScript, Java, etc.) +- Framework dependencies +- Build tool requirements +- Version compatibility issues +- Technical debt accumulation + +### Why "Lock" (Immutability)? + +Treating these contracts as **immutable** serves several purposes: + +1. **Architectural Stability**: Implementations can depend on contract invariants without fear of breaking changes mid-development. + +2. **Change Discipline**: Forcing a new ADR for contract changes ensures changes are deliberate, well-justified, and receive appropriate review. + +3. **Human Review**: Immutability ensures all contract changes receive human scrutiny rather than being merged as "minor improvements" or "refactoring." + +4. **Accountability Preservation**: Making contracts hard to change protects against convenience-driven erosion of human accountability principles. + +5. **Documentation Quality**: Immutability incentivizes getting contracts right initially, leading to more thorough specification. + +## Consequences + +### Positive Consequences + +1. **Clear Implementation Guidance**: Implementers have explicit, unambiguous contracts to implement against, reducing interpretation ambiguity. + +2. **Automated Validation**: Contracts enable automated tests that verify implementations comply with architecture, catching violations early. + +3. **Stable Interfaces**: Parallel development can proceed without coordination bottlenecks or breaking changes. + +4. **Governance Support**: Contracts provide objective basis for compliance audits and architectural reviews. + +5. **Human Accountability**: Explicit authority model prevents responsibility diffusion to autonomous systems. + +6. **Long-term Stability**: Immutability creates architectural foundation that remains stable across technology evolution. + +### Trade-offs and Costs + +1. **Reduced Flexibility**: Changes require ADR overhead even for what might seem like "minor" improvements. This is intentional—forcing review is the point. + +2. **Verbosity**: Formal specifications are longer and more detailed than informal descriptions, requiring more effort to write and read. + +3. **Maintenance Burden**: Keeping specifications aligned with evolving understanding requires ongoing effort and discipline. + +4. **Process Overhead**: ADR process for changes adds time and coordination cost, potentially slowing rapid iteration. + +### Mitigations + +1. **Version Clarity**: Schema version (1.0.0) makes compatibility explicit. Future versions (2.0.0, etc.) clearly signal breaking changes. + +2. **Extension Points**: API schema includes optional fields and "additionalData" maps that allow extension without breaking changes. + +3. **Implementation Guidance**: Each specification includes notes on adapting to language-specific types, easing implementation burden. + +4. **Regular Review**: Annual review cycle ensures specifications remain relevant and aligned with operational experience. + +5. **Minor Updates Allowed**: Typo corrections, clarifying examples, and formatting improvements don't require ADR, reducing overhead. + +## Change Policy + +Changes to locked contracts follow this procedure: + +### Minor Documentation Updates (No ADR Required) + +**Allowed**: +- Typo corrections +- Clarifying examples +- Formatting improvements +- Cross-reference updates +- Adding explanatory notes + +**Constraints**: +- No semantic changes to fields +- No field additions or removals +- No constraint modifications +- No authority redistributions + +**Process**: +- Direct commit to documentation +- Note in commit message: "Documentation improvement only" + +### Breaking Changes (ADR Required) + +**Require new ADR**: +- Field semantic changes +- Required field additions/removals +- New constraints +- Authority redistribution +- Boundary modifications +- Schema version major increment + +**Process**: +1. Draft new ADR explaining rationale for change +2. 90-day public review and comment period +3. Multiple stakeholder approvals required +4. Full UAT validation cycle +5. Explicit human authorization before adoption +6. Schema version major increment (2.0.0) +7. Migration guide for existing implementations + +### Emergency Changes + +If a critical security or safety issue requires immediate contract change: + +1. **Emergency ADR** drafted with justification +2. **Minimal viable fix** implemented +3. **Expedited review** (7 days minimum, not 90 days) +4. **Temporary "emergency" status** assigned to ADR +5. **Full ADR review cycle** initiated in parallel +6. **Permanent resolution** implemented within 90 days +7. **Post-mortem** conducted to prevent recurrence + +## Verification and Compliance + +Compliance with this ADR is verified through multiple mechanisms: + +### Design-Time Verification + +**Requirements**: +- Contract specifications exist and are complete +- All four documents present in `docs/contracts/` +- Cross-references between documents are valid +- Version numbers are consistent + +**Responsibility**: Architecture team + +### Implementation-Time Verification + +**Requirements**: +- Implementations reference contract specifications +- Automated tests validate contract compliance +- Type systems enforce boundary restrictions (where applicable) +- Documentation explains how implementation maps to contracts + +**Responsibility**: Implementation teams + +### Runtime Verification + +**Requirements**: +- Validation functions detect contract violations +- Monitoring alerts on boundary breaches +- Incident logs capture authority violations +- Performance metrics track constraint compliance + +**Responsibility**: Operations team + +### Audit-Time Verification + +**Requirements**: +- Human review of execution traces +- Compliance spot-checks on random samples +- Annual architecture review +- Incident post-mortems examine contract violations + +**Responsibility**: Architecture team and human reviewers + +## Related ADRs + +- [ADR-0004: Architecture Constitution](./adr-0004.md) — Establishes three-layer architecture that these contracts formalize +- [ADR-0005: Client-side Routing](./adr-0005.md) — Establishes routing authority that RoutingDecision contract enforces + +## Contract Documents + +The following documents are locked by this ADR: + +- [Invocation Boundary](../contracts/invocation-boundary.md) +- [API Schema](../contracts/api-schema.md) +- [Constraint Contract](../contracts/constraint-contract.md) +- [Authority Model](../contracts/authority-model.md) +- [Contracts README](../contracts/README.md) — Overview and usage guidance + +## Implementation Notes + +This ADR does **not** mandate: +- Specific implementation languages +- Specific frameworks or libraries +- Specific type systems +- Specific validation approaches +- Specific serialization formats +- Specific deployment architectures + +Implementations may use any technology stack as long as they preserve contract semantics and enforce architectural invariants. + +## Success Criteria + +This ADR is successful if: + +1. **Implementations converge** on consistent contract interpretation +2. **Boundary violations** are detected before production deployment +3. **Human accountability** remains demonstrable in audit +4. **Parallel development** proceeds without breaking changes +5. **Governance processes** can objectively assess compliance + +## Failure Modes + +This ADR fails if: + +1. **Contracts become stale**: Specifications drift from operational reality +2. **Process becomes burdensome**: ADR overhead discourages legitimate evolution +3. **Implementations diverge**: Different interpretations emerge despite specifications +4. **Accountability erodes**: Convenience compromises bypass formal process + +Regular review cycles and post-mortem analysis will monitor for these failure modes. + +--- + +**Status**: Accepted +**Supersedes**: None +**Date**: February 11, 2026 +**Authors**: RAGfish Architecture Team +**Reviewers**: All contract changes require architecture team review diff --git a/docs/contracts/README.md b/docs/contracts/README.md new file mode 100644 index 0000000..34aa2a4 --- /dev/null +++ b/docs/contracts/README.md @@ -0,0 +1,16 @@ +# Contract Specifications + +This directory defines the immutable contract layer of Noema Agent. + +Documents: + +- invocation-boundary.md +- api-schema.md +- constraint-contract.md +- authority-model.md + +These contracts define the invariant execution structure. + +No runtime logic may violate these contracts. + +Status: Locked (v1.0.0) \ No newline at end of file diff --git a/docs/contracts/api-schema.md b/docs/contracts/api-schema.md new file mode 100644 index 0000000..81cdd05 --- /dev/null +++ b/docs/contracts/api-schema.md @@ -0,0 +1,91 @@ +# API Schema Contract +Version: 1.0.0 +Status: Locked + +This document defines the canonical API structures for Noema Agent. + +--- + +## InvocationRequest + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| request_id | string | yes | Unique request identifier | +| input | string | yes | Natural language input | +| context | object | no | Additional structured context | +| constraints | array | no | Execution constraints | +| metadata | object | no | Trace and routing metadata | + +--- + +## InvocationResponse + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| request_id | string | yes | Mirrors request | +| output | string | yes | Final generated response | +| references | array | no | Grounding references | +| execution | ExecutionMetadata | yes | Execution trace metadata | +| error | ExecutionError | no | Error if occurred | + +--- + +## RoutingDecision + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| strategy | string | yes | local | cloud | hybrid | +| model | string | yes | Model selected | +| reason | string | yes | Decision explanation | +| cost_estimate | number | no | Estimated token cost | + +--- + +## ExecutionContext + +| Field | Type | Required | +|-------|------|----------| +| user_role | string | yes | +| privacy_level | string | yes | +| environment | string | yes | +| timestamp | ISO8601 | yes | + +--- + +## ExecutionMetadata + +| Field | Type | Required | +|-------|------|----------| +| duration_ms | number | yes | +| token_input | number | yes | +| token_output | number | yes | +| route | RoutingDecision | yes | + +--- + +## ExecutionError + +| Field | Type | Required | +|-------|------|----------| +| code | string | yes | +| message | string | yes | +| recoverable | boolean | yes | + +--- + +## KnowledgeReference + +| Field | Type | Required | +|-------|------|----------| +| source_id | string | yes | +| title | string | no | +| uri | string | no | +| confidence | number | yes | + +--- + +# Change Policy + +- Backward incompatible changes require major version increment. +- Additive changes require minor version increment. +- Editorial changes require patch increment. \ No newline at end of file diff --git a/docs/contracts/authority-model.md b/docs/contracts/authority-model.md new file mode 100644 index 0000000..510c048 --- /dev/null +++ b/docs/contracts/authority-model.md @@ -0,0 +1,39 @@ +# Authority Model +Version: 1.0.0 +Status: Locked + +Defines authority hierarchy. + +--- + +## Levels + +1. SYSTEM +2. USER +3. AGENT +4. MODEL + +--- + +## Hierarchy + +SYSTEM +└── USER +└── AGENT +└── MODEL + +--- + +## Rules + +- Lower authority cannot override higher authority. +- Model cannot self-elevate authority. +- Agent must verify user intent before execution. + +--- + +## Verification Procedure + +1. Validate user role. +2. Confirm constraint compatibility. +3. Log authority chain. \ No newline at end of file diff --git a/docs/contracts/constraint-contract.md b/docs/contracts/constraint-contract.md new file mode 100644 index 0000000..e0eeb4a --- /dev/null +++ b/docs/contracts/constraint-contract.md @@ -0,0 +1,60 @@ +# Constraint Contract +Version: 1.0.0 +Status: Locked + +This document defines execution constraints. + +--- + +## Fundamental Principles + +1. Deterministic routing +2. Explicit privacy boundaries +3. Authority verification +4. Observable execution +5. Reproducibility + +--- + +## Constraint Types + +### PrivacyConstraint +Defines whether data may leave local boundary. + +### CostConstraint +Maximum allowed token or monetary cost. + +### LatencyConstraint +Maximum allowed response time. + +### AuthorityConstraint +Defines required authority level. + +### SafetyConstraint +Defines prohibited output domains. + +--- + +## Validation Rules + +- All constraints must be validated before routing. +- Conflicting constraints must cause immediate rejection. +- AuthorityConstraint overrides CostConstraint. + +--- + +## Composition Rules + +Constraints are evaluated in this order: + +1. Authority +2. Privacy +3. Safety +4. Cost +5. Latency + +--- + +# Enforcement + +Violation results in ExecutionError. \ No newline at end of file diff --git a/docs/contracts/invocation-boundary.md b/docs/contracts/invocation-boundary.md new file mode 100644 index 0000000..e69de29 From d8723ab6d867c7bd2d4e549ab13b372c773b12ec Mon Sep 17 00:00:00 2001 From: Raskolnikoff Date: Wed, 11 Feb 2026 17:13:34 +0900 Subject: [PATCH 2/2] EPIC 0: completed the documentation --- docs/adr/adr-0006.md | 2 +- docs/contracts/api-schema.md | 94 +++++++++----- docs/contracts/invocation-boundary.md | 177 ++++++++++++++++++++++++++ 3 files changed, 237 insertions(+), 36 deletions(-) diff --git a/docs/adr/adr-0006.md b/docs/adr/adr-0006.md index e025909..762b474 100644 --- a/docs/adr/adr-0006.md +++ b/docs/adr/adr-0006.md @@ -74,7 +74,7 @@ The conceptual data structures that cross layer boundaries are formally defined - ExecutionMetadata - KnowledgeReference -**Version**: 1.0.0 +**Version**: 1.1.0 **Immutability**: The schema is immutable. Any change to required fields or field semantics constitutes a breaking change requiring a new ADR. diff --git a/docs/contracts/api-schema.md b/docs/contracts/api-schema.md index 81cdd05..b25a0e1 100644 --- a/docs/contracts/api-schema.md +++ b/docs/contracts/api-schema.md @@ -1,8 +1,9 @@ -# API Schema Contract -Version: 1.0.0 -Status: Locked +# API Schema Contract +Version: 1.1.0 +Status: Locked -This document defines the canonical API structures for Noema Agent. +This document defines the canonical API structures for Noema Agent. +All structures MUST comply with Invocation Boundary v1.0.0. --- @@ -11,8 +12,12 @@ This document defines the canonical API structures for Noema Agent. | Field | Type | Required | Description | |-------|------|----------|-------------| | request_id | string | yes | Unique request identifier | -| input | string | yes | Natural language input | -| context | object | no | Additional structured context | +| user_intent | string | yes | Declared user objective | +| input_payload | string | yes | Natural language or structured input | +| authority_level | string | yes | Declared authority scope | +| privacy_scope | string | yes | Data privacy boundary | +| execution_mode | string | yes | local | cloud | hybrid | +| knowledge_scope | array | no | Explicit knowledge sources allowed | | constraints | array | no | Execution constraints | | metadata | object | no | Trace and routing metadata | @@ -23,9 +28,11 @@ This document defines the canonical API structures for Noema Agent. | Field | Type | Required | Description | |-------|------|----------|-------------| | request_id | string | yes | Mirrors request | -| output | string | yes | Final generated response | -| references | array | no | Grounding references | -| execution | ExecutionMetadata | yes | Execution trace metadata | +| execution_status | string | yes | success | failure | +| output_payload | string | yes | Final generated response | +| routing_trace | RoutingDecision | yes | Full routing trace | +| confidence_score | number | yes | Model confidence estimation | +| metadata | ExecutionMetadata | yes | Execution trace metadata | | error | ExecutionError | no | Error if occurred | --- @@ -38,54 +45,71 @@ This document defines the canonical API structures for Noema Agent. | model | string | yes | Model selected | | reason | string | yes | Decision explanation | | cost_estimate | number | no | Estimated token cost | +| privacy_compliance | boolean | yes | Privacy boundary respected | +| authority_validated | boolean | yes | Authority verified | --- ## ExecutionContext -| Field | Type | Required | -|-------|------|----------| -| user_role | string | yes | -| privacy_level | string | yes | -| environment | string | yes | -| timestamp | ISO8601 | yes | +**Note**: ExecutionContext provides runtime environment metadata. This complements (does not replace) the InvocationRequest fields defined in Invocation Boundary v1.0.0 section 4. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| user_role | string | yes | Role classification | +| privacy_level | string | yes | Privacy boundary | +| environment | string | yes | Execution environment | +| timestamp | ISO8601 | yes | Invocation timestamp | --- ## ExecutionMetadata -| Field | Type | Required | -|-------|------|----------| -| duration_ms | number | yes | -| token_input | number | yes | -| token_output | number | yes | -| route | RoutingDecision | yes | +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| duration_ms | number | yes | Total execution time | +| token_input | number | yes | Input token count | +| token_output | number | yes | Output token count | +| route | RoutingDecision | yes | Routing decision object | + +**Note**: The `route` field provides observability of the routing decision made for *this specific invocation*. It does NOT imply stateful routing history across invocations. Each invocation is independent per Invocation Boundary v1.0.0 section 2.4. --- ## ExecutionError -| Field | Type | Required | -|-------|------|----------| -| code | string | yes | -| message | string | yes | -| recoverable | boolean | yes | +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| code | string | yes | Error classification code | +| message | string | yes | Human-readable explanation | +| recoverable | boolean | yes | Indicates retry possibility | --- ## KnowledgeReference -| Field | Type | Required | -|-------|------|----------| -| source_id | string | yes | -| title | string | no | -| uri | string | no | -| confidence | number | yes | +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| source_id | string | yes | Unique source identifier | +| title | string | no | Source title | +| uri | string | no | Source location | +| confidence | number | yes | Relevance confidence | + +--- + +# Contract Enforcement Rules + +1. All executions MUST originate from InvocationRequest. +2. Router mediation is mandatory. +3. Authority escalation is forbidden. +4. Stateless execution is required. +5. Implicit memory injection is prohibited. --- # Change Policy -- Backward incompatible changes require major version increment. -- Additive changes require minor version increment. -- Editorial changes require patch increment. \ No newline at end of file +- Backward incompatible changes require major version increment. +- Additive changes require minor version increment. +- Editorial changes require patch increment. +- Contract-breaking changes require ADR approval. \ No newline at end of file diff --git a/docs/contracts/invocation-boundary.md b/docs/contracts/invocation-boundary.md index e69de29..fab173c 100644 --- a/docs/contracts/invocation-boundary.md +++ b/docs/contracts/invocation-boundary.md @@ -0,0 +1,177 @@ +# Invocation Boundary Specification +Version: 1.0.0 +Status: LOCKED +Owner: Noema Core Architecture + +--- + +## 1. Purpose + +The Invocation Boundary defines the strict interface between: + +- Client (Noesis Noema App) +- Router Layer +- Execution Engine (Local or Cloud LLM) +- Knowledge / RAG Layer + +This boundary prevents architectural drift, implicit coupling, and hidden state mutation. + +No component may bypass this contract. + +--- + +## 2. Architectural Invariants + +The following invariants are absolute and must never be violated. + +### 2.1 Deterministic Invocation + +All executions MUST originate from a structured `InvocationRequest`. + +No execution may: +- Pull implicit global state +- Access undeclared memory +- Mutate external systems without declaration + +--- + +### 2.2 Explicit Authority Declaration + +Every invocation MUST declare: + +- authority_level +- privacy_scope +- execution_mode + +Implicit authority escalation is forbidden. + +--- + +### 2.3 Router Mediation Rule + +All LLM execution MUST pass through the Router. + +Client → Router → Execution + +Direct execution from Client to LLM is prohibited. + +--- + +### 2.4 Stateless Execution Core + +Execution engines MUST be stateless. + +All required context must be provided via: + +- ExecutionContext +- KnowledgeReference +- InvocationRequest metadata + +--- + +## 3. Invocation Flow + +Client +↓ +InvocationRequest +↓ +Router +↓ +RoutingDecision +↓ +Execution Engine (Local or Cloud) +↓ +ExecutionResult +↓ +InvocationResponse + +No component may skip a stage. + +--- + +## 4. InvocationRequest (Conceptual Structure) + +An InvocationRequest MUST contain: + +- request_id +- user_intent +- input_payload +- authority_level +- privacy_scope +- execution_mode +- knowledge_scope +- constraints + +No optional implicit parameters allowed. + +--- + +## 5. InvocationResponse (Conceptual Structure) + +An InvocationResponse MUST contain: + +- request_id +- execution_status +- routing_trace (RoutingDecision object, not array) +- output_payload +- confidence_score +- metadata + +Errors must be explicit and typed. + +--- + +## 6. Boundary Enforcement Rules + +1. No hidden memory injection +2. No system prompt mutation outside contract +3. No execution without router mediation +4. No authority escalation inside execution layer +5. No cross-layer state leakage + +Violation of these rules requires ADR update. + +--- + +## 7. Change Policy + +This file is LOCKED under EPIC 0. + +Changes require: + +- New ADR document +- Version increment +- Architectural review + +Minor wording fixes allowed. +Structural modifications require governance approval. + +--- + +## 8. Rationale + +The Invocation Boundary exists to: + +- Prevent uncontrolled AI execution +- Guarantee reproducibility +- Enable auditability +- Support hybrid routing (Edge / Cloud) +- Preserve human authority over system behavior + +Without this boundary, Noema collapses into prompt spaghetti. + +--- + +## 9. Non-Goals + +This document does NOT define: + +- Concrete API serialization format +- Network transport protocol +- LLM provider specifics + +Those belong to API Schema contract. + +--- + +END OF FILE \ No newline at end of file