Engineering Invariants
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- plans/noesis-autonomous-compounding-implementation-plan.html
- plans/noesis-high-leverage-correction-plan.html
- plans/compounding-partnership-product-loop.html
- plans/noesis-first-complete-iteration.html
- packages/domain/test/architecture.test.ts
- packages/tui/test/architecture.test.ts
- biome.json
Engineering Invariants in Noesis represent the core set of immutable rules, architectural boundaries, and product contracts that govern all development activity within the repository. These invariants ensure that the system remains measurable, secure, and aligned with its product thesis—specifically that "later work is better because earlier work happened."
The purpose of these invariants is to prevent the accumulation of "unproven scope" and to maintain a "protection by construction" model where sensitive operations (like self-modification or authority expansion) are isolated from the generative components of the system.
Sources: AGENTS.md:1-5, plans/noesis-high-leverage-correction-plan.html:432-440, plans/compounding-partnership-product-loop.html:432-440
Product Contract Invariants
The product contract defines how Noesis interacts with users and handles learning processes. These rules prioritize user control and evidence-backed changes over silent automation.
- Inferred Posture: Collaboration posture is inferred rather than toggled via modes. Ambiguous work defaults to
work_with_me(collaborative), while explicit execution defaults todo_for_me(autonomous). Conversational instructions always override inference. - Narrow Learning: New learning must start at the narrowest plausible scope. Broadening requires recurring evidence.
- Ambient Reflection: Reflection occurs ambiently after work is completed.
no_changeis a valid result; compounding is not forced on every session. - Inspectability: Every adaptation must be inspectable, contestable, and revertible.
Sources: AGENTS.md:7-12, plans/compounding-partnership-product-loop.html:150-165
Architectural Boundaries
The architecture is strictly partitioned to prevent circular dependencies and to isolate the execution substrate from the product logic.
Dependency Flow and Constraints
The system enforces a unidirectional dependency flow. Specifically, the core runtime and domain logic must remain adapter-neutral and cannot depend on specific runtime implementations like runtime-pi.
The diagram above shows the valid dependency directions. The runtime package is forbidden from importing runtime-pi to maintain neutrality.
Sources: AGENTS.md:19-22, packages/domain/test/architecture.test.ts:161-175, plans/noesis-autonomous-compounding-implementation-plan.html:362-375
Workspace Authority Matrix
A critical invariant is the rule of One Authority per Datum. Every piece of persisted information has exactly one declared authority to prevent synchronization conflicts and dual-write divergence.
| Datum | Single Authority | Change Mechanism |
|---|---|---|
| Sessions, Messages, Tool Calls | SQLite | Operational Repository APIs |
| Search Indexes (FTS, Embeddings) | Rebuildable SQLite Indexes | Derived from DB or file revisions |
| Config, Prompts, Skill Source | Editable Workspace Files | User or Noesis authoring |
| Recorded Definitions | Byte-stable Snapshots | Immutable revisions area |
| Authority/Grants | SQLite | Protected Control Plane only |
| Sources: AGENTS.md:25-27, plans/noesis-autonomous-compounding-implementation-plan.html:410-435, packages/domain/test/architecture.test.ts:177-184 |
Protected Control Plane
The "Protected Control Plane" is a security boundary that separates generative model work from the authoritative state of the system.
Authority and Receipts
Generated content (reflection, candidate authoring) is prohibited from promoting executable behavior or modifying permissions. All sensitive transitions must pass through the AuthorityBoundary and EffectGateway.
- Unforgeable Receipts: Operations requiring authority must present an
AuthorityReceipt. These receipts are closure-private (e.g., usingWeakSet) and verify the issuing boundary, effect class, and resource. - Fail-Closed Reservations: Grant use and costs must be reserved in authoritative state before execution. If a reservation lacks an unambiguous outcome, it must fail closed.
- Principal Isolation: The system distinguishes between multiple principals:
foreground(user-acting),reflector(analyzing),evaluator(testing), andpromoter(activating).
Sources: AGENTS.md:34-44, plans/noesis-high-leverage-correction-plan.html:402-420, plans/noesis-first-complete-iteration.html:750-760
This sequence ensures that no agent can perform an effect without a valid, verified receipt issued by the protected boundary.
Sources: plans/noesis-high-leverage-correction-plan.html:412-425, AGENTS.md:38-42
Data Persistence Invariants
- Immutable Snapshots: Evaluation pins and recorded definition revisions resolve to byte-stable snapshots. The system never depends on mutable working-file bytes for serving turns or running experiments.
- Append-Only Evidence: Evaluation evidence is revisioned and append-only once used by a decision to ensure that the basis of a prior activation cannot be altered.
- SQLite Authority: SQLite is the sole authority for operational state (sessions, turns, grants, receipts). Legacy JSONL support is strictly import-only for the workspace cutover.
- Provenance: Rebuildable search indexes and UI read models must always cite an authoritative SQLite row or recorded file revision.
Sources: AGENTS.md:23-31, plans/noesis-autonomous-compounding-implementation-plan.html:415-430, plans/compounding-partnership-product-loop.html:410-425
Testing and Verification Invariants
Engineering invariants are enforced through a suite of "Architecture Tests" that perform static analysis on the codebase.
| Test Focus | Constraint | Source File |
|---|---|---|
| Import Boundaries | Forbids TUI from importing ledger/workspace/policy internals. | packages/tui/test/architecture.test.ts:11-20 |
| Pi Isolation | Restricts @earendil-works/pi-* imports to specific packages. | packages/domain/test/architecture.test.ts:114-135 |
| God Files | Limits extracted source modules to a maximum of 800 lines. | packages/tui/test/architecture.test.ts:47-55 |
| Error Handling | Restricts native Error subclassing to a specific allowlist. | packages/domain/test/architecture.test.ts:80-100 |
| Build Configuration | Ensures tsc --noEmit and forbids .js emission in source. | packages/domain/test/architecture.test.ts:251-265 |
- Standing Rule: A test whose assertion can be satisfied by a scripted provider response without the mechanism under test being present is not considered evidence. Tests must assert on served-plan identity and recorded decisions.
Sources: plans/noesis-high-leverage-correction-plan.html:485-495, packages/domain/test/architecture.test.ts:1-25
Conclusion
Engineering Invariants in Noesis act as the system's "constitution," providing a stable foundation for an autonomous system that modifies its own components. By strictly separating authority from generation, enforcing a single source of truth for every datum, and guarding architectural boundaries via automated testing, the project ensures that its self-improvement (compounding) remains safe, measurable, and reversible.
Sources: AGENTS.md:50-55, plans/noesis-high-leverage-correction-plan.html:510-520