DecapodLabs · alexhraber · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026
diff --git a/.decapod/generated/artifacts/provenance/artifact_manifest.json b/.decapod/generated/artifacts/provenance/artifact_manifest.json
@@ -2,7 +2,7 @@
   "artifacts": [
     {
       "path": "README.md",
-      "sha256": "50c89e477e08d9f4d96f06b5a4961c7119856e6481f4102b299fc63fd1f057a6"
+      "sha256": "661b34c00d5be075a55d08f8e200d4b0896769f52d073c8e65c7c5ab14c9155e"
     }
   ],
   "kind": "artifact_manifest",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- tolerate empty capsule files in release check and manifest schema/interface validation
+
 ## [0.46.3](https://github.com/DecapodLabs/decapod/compare/v0.46.2...v0.46.3) - 2026-03-01
 
 ### Added

diff --git a/README.md b/README.md
@@ -88,11 +88,15 @@ Override any constitution default with plain English in `.decapod/OVERRIDE.md`.
 
 ## Why this exists
 
-AI coding agents are extraordinarily good at generating code. They are extraordinarily bad at knowing when to stop, what not to touch, and whether the thing they built is the thing you asked for.
+Coding agents suck. But it's not their fault.
 
-The failure mode isn't "bad code." It's unaccountable code: no intent recorded, no boundaries enforced, no proof that completion criteria were met. You get a PR that compiles. You have no idea if it's right.
+You can't solve the world inside the agent. Like any serious technology, agents need infrastructure — a way to interface with the host machine (files, repos, terminals, policies) in a way that's intelligent, bounded, and provable.
 
-Decapod closes that gap. Agents call it mid-run to lock intent, enforce boundaries, and prove completion. It shapes what goes into inference without doing inference itself.
+The Unix philosophy ("do one thing well") breaks down the moment the "one thing" becomes: reason over ambiguous intent, plan work, write code, validate it, manage state, coordinate tools, and ship safely. We expect agents to generate great code. They mostly can. But the gaps aren't something you patch by making the agent fatter. The gaps exist because the agent isn't the right place for control-plane responsibilities.
+
+Right now, agent makers keep stuffing more into the agent: task management, memory, rules, planning, codegen, toolchains, browsers — until it's mediocre at everything. Agents shouldn't be responsible for control-plane work. They shouldn't be your TODO database. They shouldn't be the place you encode a team's behavioral expectations. They shouldn't be the system of record for "what got done" or "what's allowed." That belongs in infrastructure.
+
+Decapod is a repo-native governance kernel that agents call into — like a device driver for agent work. It makes intent explicit, boundaries explicit, and completion provable. The agent stays the brain. Decapod becomes the control plane that turns agent output into something shippable.
 
 State is local and durable in `.decapod/`. Context, decisions, and traces persist across sessions and stay retrievable over time. Nothing hides. Nothing phones home.
 
@@ -125,7 +129,7 @@ AI Agent(s)  <---->  Decapod  <---->  Repository + Policy
 - **Parallel-safe.** Multiple agents, one repo, no collisions.
 - **Proof-gated completion.** `VERIFIED` requires passing proof-plan results, not narrative.
 - **Fully auditable.** Every decision, trace, and proof artifact lives in `.decapod/` as plain files.
-- **Context internalization.** Turn long documents into mountable, verifiable context adapters so agents stop re-ingesting the same 50-page spec every session.
+- **Context internalization.** Turn long documents into mountable, verifiable context adapters with explicit source hashes, determinism labels, session-scoped attach leases, and explicit detach so agents stop re-ingesting the same 50-page spec every session.
 
 The deep surface area — interfaces, capsules, eval kernel, knowledge promotions, obligation graphs — lives in the embedded constitution. Ask your agent to explore it.
 

diff --git a/constitution/core/INTERFACES.md b/constitution/core/INTERFACES.md
@@ -27,6 +27,7 @@ This registry defines the canonical binding interface surfaces.
 | `interfaces/DEMANDS_SCHEMA.md` | User-demand schema + precedence rules | Yes |
 | `interfaces/RISK_POLICY_GATE.md` | Deterministic PR risk-policy gate semantics | Yes |
 | `interfaces/INTERNALIZATION_SCHEMA.md` | Internalized context artifact schema + lifecycle contract | Yes |
+| `interfaces/jsonschema/internalization/*.json` | Stable JSON Schemas for internalization manifests and CLI results | Yes |
 | `interfaces/AGENT_CONTEXT_PACK.md` | Agent context-pack layout and mutation contract | Yes |
 | `interfaces/PROJECT_SPECS.md` | Canonical local `specs/*.md` contract and constitution mapping | Yes |
 
@@ -43,6 +44,12 @@ This registry defines the canonical binding interface surfaces.
 - Agent memory/context pack semantics: `interfaces/AGENT_CONTEXT_PACK.md`
 - Canonical local project specs contract: `interfaces/PROJECT_SPECS.md`
 - Internalized context artifact lifecycle: `interfaces/INTERNALIZATION_SCHEMA.md`
+- Internalization JSON schemas:
+- `interfaces/jsonschema/internalization/InternalizationManifest.schema.json`
+- `interfaces/jsonschema/internalization/InternalizationCreateResult.schema.json`
+- `interfaces/jsonschema/internalization/InternalizationAttachResult.schema.json`
+- `interfaces/jsonschema/internalization/InternalizationDetachResult.schema.json`
+- `interfaces/jsonschema/internalization/InternalizationInspectResult.schema.json`
 
 ---
 

diff --git a/constitution/interfaces/CLAIMS.md b/constitution/interfaces/CLAIMS.md
@@ -43,6 +43,8 @@ Columns:
 | claim.foundation.daemonless_repo_native_canonicality | Decapod remains daemonless and repo-native for promotion-relevant state and evidence. | `specs/SYSTEM.md` | partially_enforced | `decapod validate` + repo-native manifest/provenance gates | Operationally enforced in current control plane; hardening continues through gate expansion. |
 | claim.foundation.proof_gated_promotion | Promotion-relevant outcomes are invalid without executable proof and machine-verifiable artifacts. | `specs/SYSTEM.md` | partially_enforced | `decapod validate` + workspace publish proof gates | Publish paths enforce this today; broader policy coupling is still evolving. |
 | claim.doc.readme_human_only | README is human-facing product documentation; agent-operational rules must live in entrypoint and constitution surfaces. | `core/DECAPOD.md` | not_enforced | planned: docs-surface partition gate | Prevents README from becoming implicit agent policy. |
+| claim.internalize.explicit_attach_lease | Internalized context may affect inference only through an explicit session-scoped attach lease; ambient reuse is forbidden. | `interfaces/INTERNALIZATION_SCHEMA.md` | partially_enforced | `decapod internalize attach` + `decapod internalize detach` + `decapod validate` internalization gate | Lease files and provenance logs are enforced; downstream inference callers must honor the contract. |
+| claim.internalize.best_effort_not_replayable | Best-effort internalizer profiles must never claim replayability and must record binary/runtime fingerprints. | `interfaces/INTERNALIZATION_SCHEMA.md` | enforced | `decapod internalize create` + `decapod internalize inspect` + `decapod validate` internalization gate | Prevents fake reproducibility claims for non-deterministic profiles. |
 | claim.agent.invocation_checkpoints_required | Agents must call Decapod before plan commitment, before mutation, and after mutation for proof. | `interfaces/CONTROL_PLANE.md` | partially_enforced | `decapod todo` ownership records + `decapod validate` + required tests | Enforcement is partly procedural until explicit checkpoint trace gate exists. |
 | claim.agent.no_capability_hallucination | Agents must not claim capabilities absent from the Decapod command surface. | `interfaces/CONTROL_PLANE.md` | not_enforced | planned: capability-claim consistency gate | Missing surfaces must be reported as gaps, not fabricated behavior. |
 | claim.proof.executable_check | A "proof" is an executable check that can fail loudly (tests, linters, validators, etc). No new DSL. | `core/PLUGINS.md` | enforced | `decapod validate` | Definition is normative; proof registry (Epoch 1) will formalize. |

diff --git a/constitution/interfaces/INTERNALIZATION_SCHEMA.md b/constitution/interfaces/INTERNALIZATION_SCHEMA.md
@@ -3,169 +3,143 @@
 **Authority:** interface (machine-readable contract)
 **Layer:** Interfaces
 **Binding:** Yes
-**Scope:** schema, invariants, and lifecycle for internalized context artifacts
-**Non-goals:** internalizer implementation details, model training
+**Scope:** schema, invariants, CLI lifecycle, and proof gates for internalized context artifacts
+**Non-goals:** model training, hidden memory, background services
 
 ---
 
 ## 1. Purpose
 
-Internalized context artifacts let agents convert long documents into mountable, verifiable context adapters. This eliminates redundant long-context ingestion across sessions while maintaining full auditability.
+Internalized context artifacts let agents reuse long-document context without re-sending the full document on every call.
 
-An internalization is **not training**. It is a governed artifact produced by a pluggable external tool (an "internalizer profile") and managed by Decapod's artifact lifecycle.
+An internalization is **not training** and **not hidden state**. It is a governed repo-local artifact produced on demand by a pluggable profile tool, bound to exact source bytes, and attachable only through an explicit lease-bearing mount step.
 
 ---
 
-## 2. Artifact Layout
+## 2. Capability Decision + Scope
+
+### Added
+
+One capability family: `internalize.*`
+
+- `internalize.create` creates or reuses a content-addressed internalization artifact.
+- `internalize.attach` creates a session-scoped mount lease with explicit expiry.
+- `internalize.detach` revokes the mount explicitly before lease expiry.
+- `internalize.inspect` proves exact bindings, integrity status, and determinism labeling.
+
+### Not Added
+
+- No background daemon or auto-mounting.
+- No silent GPU dependency.
+- No implicit session reuse across tools.
+- No claim that best-effort profiles are replayable.
+- No general-purpose ambient memory layer.
+
+---
+
+## 3. Artifact Layout
 
 ```text
 .decapod/generated/artifacts/internalizations/<artifact_id>/
-  manifest.json       # InternalizationManifest (see schema below)
-  adapter.bin          # adapter payload (or pointer)
+  manifest.json
+  adapter.bin
 ```
 
----
+Session-scoped active mount leases are stored at:
 
-## 3. InternalizationManifest Schema (v1.0.0)
-
-```json
-{
-  "schema_version": "1.0.0",
-  "id": "<ULID>",
-  "source_hash": "<SHA-256 of source document>",
-  "source_path": "<original path or URI>",
-  "extraction_method": "<profile name>",
-  "chunking_params": {},
-  "base_model_id": "<model identifier>",
-  "internalizer_profile": "<profile name>",
-  "internalizer_version": "<semver>",
-  "adapter_format": "<format string>",
-  "created_at": "<ISO 8601>",
-  "ttl_seconds": 0,
-  "expires_at": "<ISO 8601 | null>",
-  "provenance": [
-    {
-      "op": "internalize.create",
-      "timestamp": "<ISO 8601>",
-      "actor": "<actor id>",
-      "inputs_hash": "<SHA-256>"
-    }
-  ],
-  "replay_recipe": {
-    "command": "decapod",
-    "args": ["internalize", "create", "--source", "..."],
-    "env": {}
-  },
-  "adapter_hash": "<SHA-256 of adapter payload>",
-  "adapter_path": "adapter.bin",
-  "capabilities_contract": {
-    "allowed_scopes": ["qa", "summarization"],
-    "permitted_tools": ["*"],
-    "allow_code_gen": false
-  },
-  "risk_tier": {
-    "creation": "compute-risky",
-    "attach": "behavior-changing",
-    "inspect": "read-only"
-  }
-}
+```text
+.decapod/generated/sessions/<session_id>/internalize_mounts/
+  mount_<artifact_id>.json
 ```
 
 ---
 
-## 4. Result Schemas
+## 4. Manifest Contract
 
-### InternalizationCreateResult
+Schema version: `1.2.0`
 
-```json
-{
-  "schema_version": "1.0.0",
-  "success": true,
-  "artifact_id": "<ULID>",
-  "artifact_path": "<absolute path>",
-  "manifest": { "...InternalizationManifest..." },
-  "source_hash": "<SHA-256>",
-  "adapter_hash": "<SHA-256>"
-}
-```
+Required fields include:
 
-### InternalizationAttachResult
-
-```json
-{
-  "schema_version": "1.0.0",
-  "success": true,
-  "artifact_id": "<ULID>",
-  "session_id": "<session identifier>",
-  "attached_at": "<ISO 8601>",
-  "expires_at": "<ISO 8601 | null>",
-  "capabilities_contract": { "...CapabilitiesContract..." },
-  "risk_classification": "behavior-changing",
-  "provenance_entry": { "...ProvenanceEntry..." }
-}
-```
+- `source_hash`
+- `base_model_id`
+- `internalizer_profile`
+- `internalizer_version`
+- `adapter_hash`
+- `determinism_class`
+- `binary_hash`
+- `runtime_fingerprint`
+- `replay_recipe`
+- `capabilities_contract`
 
-### InternalizationInspectResult
-
-```json
-{
-  "schema_version": "1.0.0",
-  "artifact_id": "<ULID>",
-  "manifest": { "...InternalizationManifest..." },
-  "integrity": {
-    "source_hash_valid": true,
-    "adapter_hash_valid": true,
-    "manifest_consistent": true,
-    "expired": false
-  },
-  "status": "valid"
-}
-```
+Determinism rules:
 
----
+- `determinism_class` is `deterministic` or `best_effort`
+- only deterministic profiles may claim `replay_recipe.mode=replayable`
+- best-effort profiles must be `non_replayable`
+- best-effort manifests must carry `binary_hash` and `runtime_fingerprint`
 
-## 5. Invariants
+Capabilities rules:
 
-1. **Source binding:** `source_hash` must be the SHA-256 of the document at creation time. No silent changes.
-2. **Base model binding:** `base_model_id` must be recorded; adapters are model-specific.
-3. **Reproducibility:** `internalizer_profile` + `internalizer_version` + `replay_recipe` must be sufficient to reproduce the artifact.
-4. **Explicit attach:** Agents cannot reference an internalization without a logged `internalize.attach` operation.
-5. **TTL enforcement:** If `expires_at` is set and in the past, `attach` MUST fail.
-6. **Adapter integrity:** `adapter_hash` must match the SHA-256 of the payload file at attach time.
-7. **Provenance logging:** Every `attach` operation appends a provenance entry to the session directory.
+- default scope is `qa`
+- `allow_code_gen=false` by default
+- attach must enforce `permitted_tools`
 
 ---
 
-## 6. Risk Classification
+## 5. CLI Surface
 
-| Operation | Risk Level | Rationale |
-|-----------|-----------|-----------|
-| `create` | compute-risky | Invokes external tool; no repo mutation beyond artifact dir |
-| `attach` | behavior-changing | Affects inference behavior; logged as dependency |
-| `inspect` | read-only | No side effects |
+### `decapod internalize create`
 
----
+Creates or reuses a content-addressed artifact from:
+- `--source`
+- `--model`
+- `--profile`
+- `--ttl`
+- `--scope`
 
-## 7. Internalizer Profiles
+### `decapod internalize attach`
 
-Profiles are pluggable external tools stored in `.decapod/generated/profiles/internalizers/<name>.json`.
+Creates a session-scoped mount lease from:
+- `--id`
+- `--session`
+- `--tool`
+- `--lease-seconds`
 
-Profile schema:
-```json
-{
-  "name": "<profile name>",
-  "version": "<semver>",
-  "executable": "<path or builtin:noop>",
-  "default_params": {},
-  "adapter_format": "<format string>"
-}
-```
+### `decapod internalize detach`
+
+Revokes the session-scoped mount lease:
+- `--id`
+- `--session`
+
+### `decapod internalize inspect`
+
+Proves artifact status:
+- `valid`
+- `best-effort`
+- `expired`
+- `integrity-failed`
+
+---
+
+## 6. Provable Acceptance Criteria
+
+An internalization is provable only if:
 
-The built-in `noop` profile produces an empty adapter for pipeline testing without GPU dependencies.
+1. `source_hash` binds to exact source bytes.
+2. `base_model_id` is recorded.
+3. `adapter_hash` matches the adapter payload.
+4. replayability claims match determinism policy.
+5. use requires a successful attach lease.
+6. expired artifacts cannot be attached.
+7. expired mount leases fail validation if left active.
+8. the attach tool is allowed by `permitted_tools`.
 
 ---
 
-## Links
+## 7. Stable JSON Schemas
 
-- `core/PLUGINS.md` - Subsystem registry
-- `core/INTERFACES.md` - Interface contracts registry
+- `constitution/interfaces/jsonschema/internalization/InternalizationManifest.schema.json`
+- `constitution/interfaces/jsonschema/internalization/InternalizationCreateResult.schema.json`
+- `constitution/interfaces/jsonschema/internalization/InternalizationAttachResult.schema.json`
+- `constitution/interfaces/jsonschema/internalization/InternalizationDetachResult.schema.json`
+- `constitution/interfaces/jsonschema/internalization/InternalizationInspectResult.schema.json`
diff --git a/constitution/interfaces/jsonschema/internalization/InternalizationAttachResult.schema.json b/constitution/interfaces/jsonschema/internalization/InternalizationAttachResult.schema.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://decapod.dev/schemas/internalization/attach-result-1.2.0.json",
+  "title": "InternalizationAttachResult",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "success",
+    "artifact_id",
+    "session_id",
+    "tool",
+    "attached_at",
+    "lease_id",
+    "lease_seconds",
+    "lease_expires_at"
+  ]
+}
diff --git a/constitution/interfaces/jsonschema/internalization/InternalizationCreateResult.schema.json b/constitution/interfaces/jsonschema/internalization/InternalizationCreateResult.schema.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://decapod.dev/schemas/internalization/create-result-1.2.0.json",
+  "title": "InternalizationCreateResult",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "success",
+    "artifact_id",
+    "artifact_path",
+    "cache_hit",
+    "manifest",
+    "source_hash",
+    "adapter_hash"
+  ]
+}
diff --git a/constitution/interfaces/jsonschema/internalization/InternalizationDetachResult.schema.json b/constitution/interfaces/jsonschema/internalization/InternalizationDetachResult.schema.json
@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://decapod.dev/schemas/internalization/detach-result-1.2.0.json",
+  "title": "InternalizationDetachResult",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "success",
+    "artifact_id",
+    "session_id",
+    "detached_at",
+    "lease_id",
+    "detached"
+  ]
+}