Revisions, Evidence, & Artifacts
Relevant source files
The following files were used as context for generating this wiki page:
The Noesis system utilizes a specialized persistence model where every piece of data has a single declared authority to ensure immutability and auditability. The core of this system is the WorkspaceStore, which manages the transition of ordinary work into byte-stable snapshots. This architecture ensures that experiments, turns, and activation pins always resolve to fixed content, even if the user or an agent subsequently edits the underlying working files.
Revisions represent immutable snapshots of definition files (prompts, skills, tools), while Evidence covers the append-only data used to justify system adaptations. Artifacts are the large-scale outputs and traces produced during execution, referenced by SQLite metadata but stored as content-addressed files. Together, these components form the substrate for the system's "autonomous compounding" loop, where later work is provably improved based on evidenced insights from earlier interactions.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:13-20, plans/noesis-high-leverage-correction-plan.html:43-55, AGENTS.md:21-25
File Revisions and Versioning
Revisions in Noesis are immutable, byte-stable snapshots of declarative definitions. When a file—such as a prompt module or a skill—is edited, the WorkspaceStore snapshots its bytes into a revisions area, generating a content digest and recording its predecessor. This allows the system to pin specific versions of capabilities during an execution turn, preventing behavioral drift caused by mid-turn file modifications.
Architecture of a Revision
A FileRevision is identified by a unique ID and contains metadata linking it to its physical location, content hash, and history.
The diagram above illustrates how high-level Capability Revisions aggregate individual file-level revisions for prompts, skills, and tools.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:565-580, packages/workspace/src/store.ts:601-620
Recording Logic
The recordDefinitionBytes function in WorkspaceStore handles the lifecycle of creating a revision. It verifies provenance references, calculates a SHA-256 digest, and ensures the content is persisted atomically in both the working directory and the snapshot storage.
| Step | Action | Description |
|---|---|---|
| 1 | Verification | Asserts that all provenance references exist in the database. |
| 2 | Hashing | Computes a sha256 digest of the input bytes. |
| 3 | Atomic Write | Persists content to a temporary file before renaming it to the final destination to prevent partial writes. |
| 4 | DB Registration | Records metadata in the file_revisions table and logs the activity in activity_log. |
Sources: packages/workspace/src/store.ts:182-210, packages/workspace/src/store.ts:133-154
Evidence and Provenance
Evidence revisions are a specialized kind of file revision used specifically for evaluation and learning. Unlike definitions, evidence is strictly append-only. Once a piece of evidence—such as a tool trace or a judge's report—is used to make a system decision (like activating a new capability), it cannot be overwritten.
Evidence Kinds
Evidence is categorized by its role in the learning lifecycle:
- input: The original request or context.
- output: The result of a trial or turn.
- tool_trace: Detailed execution logs of external effects.
- judgment: Blinded comparison results from an LLM judge.
- report: The final preflight summary.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:573-577, packages/workspace/src/store.ts:258-265
Data Flow for Evidence Appending
The following diagram shows how appendEvidence integrates content storage with transactional metadata.
This flow ensures that evidence snapshots are immutable and cited correctly in the database.
Sources: packages/workspace/src/store.ts:258-293
Artifacts and Substrate Storage
Artifacts are large outputs produced by the model or external tools. While revisions track the code and prompts, artifacts track the results. Artifacts are stored as content-addressed files, meaning the system checks for existing identical content before performing a write.
Artifact Metadata
Each artifact is associated with metadata in SQLite that tracks:
- Path: The workspace-relative location.
- Media Type: For rendering and inspection (e.g.,
application/json). - Relationships: References to the specific turn, tool call, or revision that produced it.
Sources: packages/workspace/src/store.ts:295-310, plans/noesis-autonomous-compounding-implementation-plan.html:435-445
Workspace Authority Map
The project enforces a strict "one authority per datum" rule to prevent divergence.
| Datum | Single Authority | Change Mechanism |
|---|---|---|
| Sessions / Messages | SQLite | Repository APIs inside transactions. |
| Definition Files | Editable Working Files | Watcher records new stable revisions on edit. |
| Recorded Snapshots | Byte Snapshots (Disk) | Immutable once registered; keyed by Digest. |
| Artifacts | Artifact Files (Disk) | Content-addressed write; metadata in SQLite. |
| Evidence | Evidence Files (Disk) | Append-only revisions. |
Sources: plans/noesis-autonomous-compounding-implementation-plan.html:430-460, packages/domain/test/architecture.test.ts:168-175
Staging and Publication
The WorkspaceStore provides a staging mechanism to prepare adaptations before they are committed to the active system. This is critical for the "Autonomous Compounding" process, where candidates are preflighted in a sandbox before activation.
Staging Process
- Stage:
stageDefinitionwrites bytes to a temporary staging area and records astaged_definitionsrow. - Register:
registerStagedDefinitionmoves the staged content into a permanent file revision. - Activate: A separate protected transaction updates the activation pointer in SQLite to reference the new revision.
Sources: packages/workspace/src/store.ts:373-435, plans/noesis-autonomous-compounding-implementation-plan.html:530-540
Staging and Registration Flow
The staging area allows for safe evaluation of changes without affecting the current active behavior.
Sources: packages/workspace/src/store.ts:373-435, plans/noesis-autonomous-compounding-implementation-plan.html:775-785
Summary
The system of Revisions, Evidence, and Artifacts provides the rigorous data integrity required for autonomous self-improvement. By treating code, context, and outcomes as immutable snapshots, Noesis ensures that every adaptation is backed by verifiable history. This prevents the "hallucination" of system state and provides a dependable substrate for auditing, reverting, or pinning specific agent behaviors.
Sources: plans/noesis-high-leverage-correction-plan.html:25-35, AGENTS.md:21-30