Design/contract lock

.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
+

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.1.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

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)