Merge pull request #162 from engineeredsoftware/v41/gate-3-registry-interpolation-contracts

V41 Gate 3: Registry Interpolation Contracts

Author: geraldarthurdavis

.bitcode/v41-registry-interpolation-contracts.json

@@ -265,6 +265,9 @@ jobs:
               if [ -f scripts/check-v41-gate2-promptpart-prompt-inventory.mjs ]; then
                 node scripts/check-v41-gate2-promptpart-prompt-inventory.mjs --skip-branch-check --skip-package-tests
               fi
+              if [ -f scripts/check-v41-gate3-registry-interpolation-contracts.mjs ]; then
+                node scripts/check-v41-gate3-registry-interpolation-contracts.mjs --skip-branch-check --skip-package-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

.github/workflows/bitcode-canon-quality.yml

@@ -394,6 +394,9 @@ jobs:
               if [ -f scripts/check-v41-gate2-promptpart-prompt-inventory.mjs ]; then
                 node scripts/check-v41-gate2-promptpart-prompt-inventory.mjs --skip-branch-check --skip-package-tests
               fi
+              if [ -f scripts/check-v41-gate3-registry-interpolation-contracts.mjs ]; then
+                node scripts/check-v41-gate3-registry-interpolation-contracts.mjs --skip-branch-check --skip-package-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

.github/workflows/bitcode-gate-quality.yml

@@ -8,7 +8,7 @@
 - Prior canonical anchor: `BITCODE_SPEC_V40.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V40`
-- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, planned prompt-program catalogue artifacts, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
+- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, Gate 2 `.bitcode/v41-promptpart-prompt-inventory.json`, Gate 3 `.bitcode/v41-registry-interpolation-contracts.json`, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
 - Source parity state: V41 opens prompt-program parity over V40 exhaustive testing, V38 inference correctness, and V39 commercial Reading readiness; source-side prompt and PromptPart rewrites are blocked until catalogue, benchmark, interpolation, registry, callsite, and return-type surfaces are specified and checked
 - Notes companion: `BITCODE_SPEC_V41_NOTES.md`
 - Delta companion: `BITCODE_SPEC_V41_DELTA.md`
@@ -116,6 +116,8 @@ Gate 2 also preserves V41 scope and prepares draft V42 only as forward roadmap t
 
 Gate 3 must prove the composition chain from phase and pipeline context through PTRR agents, PTRR steps, FailsafeGenerationSequence, and ThricifiedGeneration final prompt resolution.
 Rows must bind registry ids, execution ancestry frames, interpolation keys, missing-key behavior, tool doc-comment prompt injection, context-size handling, and parser targets.
+Gate 3 is closed by the package-backed `buildV41RegistryInterpolationContracts` source, deterministic `.bitcode/v41-registry-interpolation-contracts.json` artifact, `generate:v41-registry-interpolation-contracts`, `check:v41-registry-interpolation-contracts`, `check:v41-gate3`, protocol tests, and gate/canon workflow wiring.
+The current source-safe contract covers 12 rows, 65 passing source predicates, Prompt registry totality, TemplatedPromptPart interpolation, PTRR agent prompt composition, PTRR step prompt composition, FailsafeGenerationSequence context handling, ThricifiedGeneration final prompt resolution, execution ancestry overlays, tool doc-code prompt injection, `ReadNeedComprehensionSynthesis` parser targets, `ReadFitsFindingSynthesis` search/parser targets, AssetPack synthesis/finishing parser targets, and Gate 2 prompt inventory binding.
 
 ## V41 Gate 4 Reading Pipeline Prompt Benchmark Baselines
 
@@ -449,6 +451,7 @@ Generation must fail closed when artifact freshness, source-safety, benchmark co
 
 V41 Gate 1 validates with `pnpm run check:v41-gate1`, `node scripts/check-bitcode-spec-family.mjs --version V41 --mode draft --current-target V40`, `node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V40 --draft-target V41`, and `node scripts/check-bitcode-canonical-inputs.mjs --current-target V40`.
 V41 Gate 2 validates with `pnpm run generate:v41-prompt-inventory`, `pnpm run check:v41-prompt-inventory`, `pnpm run check:v41-gate2`, and `node --test --test-force-exit packages/protocol/test/v41-promptpart-prompt-inventory.test.js`.
+V41 Gate 3 validates with `pnpm run generate:v41-registry-interpolation-contracts`, `pnpm run check:v41-registry-interpolation-contracts`, `pnpm run check:v41-gate3`, and `node --test --test-force-exit packages/protocol/test/v41-registry-interpolation-contracts.test.js`.
 Later gates add focused generator, checker, package, benchmark, and workflow commands.
 
 ## V41 promotion canon

BITCODE_SPEC_V41.md

@@ -7,8 +7,8 @@
 - Current canonical/latest target: `V40`
 - Prior canonical anchor: `BITCODE_SPEC_V40.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, planned prompt-program catalogue artifacts, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
-- Source parity state: V41 source parity begins at specification and workflow posture; prompt rewrites are explicitly deferred until catalogue and benchmark gates close
+- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, Gate 2 `.bitcode/v41-promptpart-prompt-inventory.json`, Gate 3 `.bitcode/v41-registry-interpolation-contracts.json`, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
+- Source parity state: V41 source parity now includes prompt inventory plus registry/interpolation contracts; prompt rewrites are explicitly deferred until catalogue, contract, and benchmark gates close
 - Scope: V41 draft delta for Prompt and PromptPart excellence over promoted V40
 
 ## Why V41 exists
@@ -39,6 +39,8 @@ It also records V42 as the subsequent MVP experience version for shortest-path D
 ### Gate 3: Registry Composition And Interpolation Contracts
 
 Prove registry composition, prompt context interpolation, execution ancestry, tool prompt injection, and parsed return type bindings.
+Gate 3 is package-backed by `buildV41RegistryInterpolationContracts`, emits `.bitcode/v41-registry-interpolation-contracts.json`, and currently covers 12 source-safe contract rows with 65 passing source predicates across Prompt registry totality, PromptPart interpolation, PTRR agent/step composition, FailsafeGenerationSequence context handling, ThricifiedGeneration final prompt resolution, execution ancestry overlays, tool doc-code prompt injection, Reading parser targets, Finding Fits search contracts, and AssetPack synthesis/finishing parser targets.
+It preserves V42 as subsequent reliable MVP experience planning while keeping V41 focused on prompt-program correctness.
 
 ### Gate 4: Reading Pipeline Prompt Benchmark Baselines
 

BITCODE_SPEC_V41_DELTA.md

@@ -8,7 +8,7 @@
 - Canonical pointer: `BITCODE_SPEC.txt` -> `V40`
 - Prior canonical anchor: `BITCODE_SPEC_V40.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, Gate 2 `.bitcode/v41-promptpart-prompt-inventory.json`, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
+- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, Gate 2 `.bitcode/v41-promptpart-prompt-inventory.json`, Gate 3 `.bitcode/v41-registry-interpolation-contracts.json`, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
 - Source parity state: V41 notes track prompt-program planning, catalogue, benchmark, rewrite, telemetry, and promotion parity over active V40
 - Draft target posture: V41 Gate 1 creates the full SPEC, DELTA, NOTES, and PARITY family.
 - Scope: Prompt and PromptPart excellence over the promoted V40 exhaustive testing base.
@@ -29,8 +29,16 @@ This is an inventory and admission artifact, not a rewrite artifact.
 
 V42 is re-roadmapped as the MVP experience version after V41.
 Its focus is shortest-path Depositing, shortest-path Reading, and a strong AI-reading dominant demonstration where any deposit source can contribute proprietary or otherwise non-public training, prompt, context, or evaluation material to an AssetPack that measurably improves an AI system beyond public-data-only performance.
+Depositing must minimize the path to admitting source material and later receiving BTC compensation when the deposit participates in a synthesized AssetPack.
+Reading must minimize the path from Read Request to synthesized Need review/resynthesis, Finding Fits, source-safe AssetPack preview, BTD/BTC purchase and settlement, and repository delivery.
 V42 must keep depositor compensation, reader purchase, BTD/AssetPack rights, and repository delivery visible in the shortest path without widening V41 beyond Prompt and PromptPart excellence.
 
+## Gate 3 registry and interpolation contract note
+
+Gate 3 makes the prompt registry call chain source-checkable before prompt rewrites.
+The package-backed contract currently emits 12 rows and 65 source predicates for Prompt registry totality, TemplatedPromptPart interpolation, PTRR agent and step prompt composition, FailsafeGenerationSequence context handling, ThricifiedGeneration final prompt resolution, execution ancestry overlays, tool doc-code prompt injection, Reading parser targets, Finding Fits search and embedding contracts, AssetPack synthesis and finishing parser targets, and Gate 2 inventory binding.
+The artifact records ids, source paths, hashes, predicate verdicts, parser target ids, interpolation key ids, and ancestry frame ids only; it does not serialize raw prompt text, provider responses, private context, credentials, or unpaid AssetPack source.
+
 ## Concise current-system reading
 
 Bitcode is active at V40.

BITCODE_SPEC_V41_NOTES.md

@@ -7,8 +7,8 @@
 - Current canonical/latest target: `V40`
 - Prior canonical anchor: `BITCODE_SPEC_V40.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, Gate 2 `.bitcode/v41-promptpart-prompt-inventory.json`, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
-- Source parity state: Gate 1 closes spec, roadmap, docs, package script, workflow posture, and checker parity; Gate 2 closes source-safe prompt inventory parity; later gates own registry contracts, rewrite, benchmark, telemetry, and promotion parity
+- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, Gate 2 `.bitcode/v41-promptpart-prompt-inventory.json`, Gate 3 `.bitcode/v41-registry-interpolation-contracts.json`, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
+- Source parity state: Gate 1 closes spec, roadmap, docs, package script, workflow posture, and checker parity; Gate 2 closes source-safe prompt inventory parity; Gate 3 closes source-safe registry/interpolation contract parity; later gates own rewrite, benchmark, telemetry, and promotion parity
 - Scope: V41 draft parity ledger for Prompt and PromptPart excellence
 - Last fully realized canonical target preserved in source: `V40`
 
@@ -35,7 +35,7 @@ This matrix records the prompt-program surfaces that must become promotion-grade
 | Gate workflow | Gate quality knows active V40 and draft V41 Gate 1 | `.github/workflows/bitcode-gate-quality.yml` | drafted |
 | Canon workflow | Canon quality knows active V40 and draft V41 Gate 1 | `.github/workflows/bitcode-canon-quality.yml` | drafted |
 | Prompt inventory | Every raw PromptPart and composed Prompt catalogued | `.bitcode/v41-promptpart-prompt-inventory.json` | implemented |
-| Registry/interpolation | Registry composition and interpolation contracts proven | planned V41 Gate 3 artifact | pending |
+| Registry/interpolation | Registry composition and interpolation contracts proven | `.bitcode/v41-registry-interpolation-contracts.json` | implemented |
 | Reading baselines | Reading prompt benchmarks captured before rewrites | planned V41 Gate 4 artifact | pending |
 | ReadNeed rewrite | ReadNeedComprehensionSynthesis prompts rewritten and type-hardened | planned V41 Gate 5 artifact | pending |
 | Finding Fits rewrite | ReadFitsFindingSynthesis prompts rewritten for search and AssetPack context | planned V41 Gate 6 artifact | pending |
@@ -49,7 +49,7 @@ This matrix records the prompt-program surfaces that must become promotion-grade
 | --- | --- | --- |
 | Gate 1 | Open V41 family, roadmap, docs, workflow posture, package script, and checker | closed |
 | Gate 2 | PromptPart and Prompt inventory artifact | implemented |
-| Gate 3 | Registry composition and interpolation artifact | pending |
+| Gate 3 | Registry composition and interpolation artifact | implemented |
 | Gate 4 | Reading prompt benchmark baseline artifact | pending |
 | Gate 5 | ReadNeedComprehensionSynthesis rewrite artifact | pending |
 | Gate 6 | ReadFitsFindingSynthesis rewrite artifact | pending |
@@ -67,6 +67,10 @@ V41 Gate 2 may catalogue PromptPart and Prompt metadata, hashes, registry owners
 It may not serialize raw prompt text, raw provider responses, protected source, secrets, or unpaid AssetPack source.
 It also may record the V42 MVP roadmap posture as forward planning while preserving V41 as the active prompt-program draft target.
 
+V41 Gate 3 may catalogue registry ids, interpolation key ids, missing-key behavior ids, context-handling ids, tool prompt injection ids, execution ancestry frame ids, parser target ids, source hashes, and predicate verdicts.
+It may not serialize raw prompt text, raw provider responses, protected source, private context, credentials, settlement-private payloads, or unpaid AssetPack source.
+It closes prompt rewrites' precondition that prompt composition and interpolation contracts are observable before semantic PromptPart or Prompt rewrite work proceeds.
+
 ## V41 completion condition
 
 V41 closes when prompt-program quality is fully specified, implemented, benchmarked, source-safe, tested, documented, generated, workflow-checked, and promotion-ready across Reading, Conversation, tool-definition, and interface inference surfaces.

BITCODE_SPEC_V41_PARITY_MATRIX.md

@@ -24,8 +24,19 @@ generated source-safe artifact `.bitcode/v41-promptpart-prompt-inventory.json`.
 The inventory currently covers 1,459 raw PromptPart rows and 105 composed Prompt
 rows across Reading, Conversation, tool-definition, interface, and benchmark
 surfaces, with `generate:v41-prompt-inventory`, `check:v41-prompt-inventory`,
-and `check:v41-gate2`. V42 is now roadmapped as the next MVP experience version:
-shortest-path Depositing, shortest-path Reading, and an AI-reading dominant
+and `check:v41-gate2`.
+V41 Gate 3 adds the package-backed `buildV41RegistryInterpolationContracts` and
+generated source-safe artifact `.bitcode/v41-registry-interpolation-contracts.json`.
+The contract currently covers 12 registry/interpolation rows and 65 source
+predicates for Prompt registry totality, PromptPart interpolation, PTRR
+agent/step composition, Failsafe and Thricified prompt resolution, execution
+ancestry overlays, tool doc-code prompt injection, Reading parser targets,
+Finding Fits search contracts, AssetPack synthesis/finishing parser targets,
+and Gate 2 inventory binding with `check:v41-gate3`.
+V42 is now roadmapped as the next MVP experience version: shortest-path
+Depositing with later BTC compensation, shortest-path Reading through
+Need review/resynthesis, Finding Fits, source-safe AssetPack preview,
+BTD/BTC settlement, repository delivery, and an AI-reading dominant
 demonstration whose AssetPack measurably improves an AI system beyond
 public-data-only performance.