Merge pull request #14 from engineeredsoftware/v28/gate-9-depository-evidence

Gate 9 project depository evidence through Reading

Author: geraldarthurdavis

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

@@ -45,6 +45,7 @@ jobs:
           node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V27 --draft-target V28
           node scripts/check-bitcode-canonical-inputs.mjs --current-target V27
           node scripts/check-v28-metadevelopment-readiness.mjs --skip-branch-check
+          node scripts/check-v28-gate9-depository-evidence.mjs
           node scripts/promote-bitcode-canon.mjs --version V28 --commit HEAD --dry-run
 
       - name: Validate source casing and imports

BITCODE_SPEC_V28.md

@@ -794,6 +794,31 @@ repository inventory, deposit admission, depository evidence storage,
 measurement vectors, wallet/depositor boundaries, search-index population, and
 Terminal visibility for deposited source materials.
 
+Gate 9 acceptance closes only when a deposited repository revision produces a
+single evidence spine usable by later Reading gates:
+
+- the deposit route returns and persists a source-bound depository evidence
+  envelope containing repository, branch, commit, asset id, content root, proof
+  root, measurement root, reconciliation readback root, lexical search document
+  root, vector search document root, and aggregate depository search document
+  root;
+- the depositor boundary is explicit as a wallet/signer ownership boundary,
+  with the deposited asset owned by the depositor before any Reader settlement
+  or read-license transfer;
+- the vector document contract names the embedding policy
+  `text-embedding-3-small`, 1536 dimensions, and the `deliverable_vectors` /
+  `match_deliverable_vectors` store/RPC boundary, while lexical search remains
+  deterministic and source-rooted;
+- Terminal execution-history rows retain the deposit evidence roots and replay
+  them into the latest deposited source revision so the Read/Fit harness can
+  pass proof, measurement, and readback roots into Finding Fits;
+- Terminal Deposit + Read surfaces show the deposit asset id, depositor wallet,
+  source proof roots, search document roots, and index state without requiring
+  operators to inspect raw JSON;
+- the Gate 9 SQL/readback query checks recent deposit rows for repository
+  alignment, candidate asset id, source proof roots, depository search document
+  roots, depositor boundary, and vector embedding policy posture.
+
 ### Gate 10: Read Request To Read-Need Comprehension
 
 Gate 10 owns the enterprise Reading start: request Read, synthesize a

BITCODE_SPEC_V28_DELTA.md

@@ -190,6 +190,14 @@ Read Request, Read-Need synthesis/review/resynthesis, Finding Fits, AssetPack
 preview, BTC settlement, read-license/right transfer, protected-source unlock,
 PR delivery, Terminal UX, documentation, proof coverage, and live validation.
 
+Gate 9 introduces the deposited-source evidence spine that later gates consume.
+Depositing now produces proof, measurement, reconciliation readback, lexical
+document, vector document, and aggregate depository search roots; projects those
+roots through Terminal execution history; and carries them into the Read/Fit
+harness deposit reference. The vector document policy is explicit:
+`text-embedding-3-small`, 1536 dimensions, `deliverable_vectors`, and
+`match_deliverable_vectors`.
+
 ## Later Version Handoff
 
 - V29: deeper Terminal workflows and transaction operation beyond V28 MVP QA.

BITCODE_SPEC_V28_NOTES.md

@@ -553,6 +553,23 @@ Need synthesis/review/resynthesis, Finding Fits over the depository, source-safe
 AssetPack preview, BTC settlement, read-license/right transfer, pull-request
 delivery, Terminal usability, proof coverage, and local/live validation.
 
+## Gate 9 depository evidence closure notes
+
+Gate 9 closes the first product gate after metadevelopment by making Deposit
+evidence reusable by later Reading gates. A deposited repository revision must
+emit proof, measurement, reconciliation readback, lexical document, vector
+document, and aggregate depository search roots. Terminal activity history must
+persist those roots and project them back into the latest deposited source
+revision. The Read/Fit harness must receive the same roots in its deposit
+reference so Finding Fits can distinguish real proof-bearing deposited supply
+from local placeholders.
+
+The vector search document policy for V28 Gate 9 is `text-embedding-3-small`,
+1536 dimensions, `deliverable_vectors`, `match_deliverable_vectors`, and cosine
+distance. Gate 9 records the vector document as ready for embedding generation;
+later Finding Fits and live validation gates own provider execution, ranking,
+settlement, and protected-source disclosure boundaries.
+
 ## Non-Goals For V28
 
 - V28 does not implement or QA Exchange product behavior, broad order-book depth, external market routing, wrapper liquidity, or third-party marketplace integration.

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -172,7 +172,7 @@ by a later V28 gate before `version/v28` can be promoted to `main`.
 
 | Carryforward surface | Next gate | Required commercial implementation | Required proof/test coverage | Carryforward closure requirement |
 | --- | --- | --- | --- | --- |
-| Source Depositing and depository evidence | Gate 9 | Repository inventory, deposit admission, source measurement, depository asset rows, vector/lexical search documents, depositor wallet boundary, source proof roots, and Terminal deposit history. | Deposit API/ORM tests, depository-search tests, staging-testnet SQL/readback queries, Terminal UX tests, and no demonstration runtime imports. | A user can deposit real source material and see source-bound evidence persisted, searchable, journaled, and owned by the depositor boundary. |
+| Source Depositing and depository evidence | Gate 9 | Repository inventory, deposit admission, source measurement, depository asset rows, lexical/vector search documents, depositor wallet boundary, source proof roots, execution-history projection, and Terminal deposit history. | Protocol deposit evidence tests, depository-search tests, pipeline harness deposit-root propagation tests, staging-testnet SQL/readback queries, Terminal UX tests, and no demonstration runtime imports. | A user can deposit real source material and see source-bound evidence persisted, searchable, journaled, root-projected into Finding Fits, and owned by the depositor boundary. |
 | Read Request capture | Gate 10 | Enterprise Read Request form/state, repository target, source branch/commit context, constraints, non-goals, desired artifact types, and feedback history. | UAPI route tests, Terminal form tests, typed Read Request schema tests, prompt/context interpolation tests. | Raw requests are persisted as requests only; they do not directly trigger Finding Fits until a reviewed Need exists. |
 | Read-Need synthesis, review, and resynthesis | Gate 10 | `ReadNeedComprehensionSynthesis` execution over PTRR agents and ThricifiedGenerations, reviewable Need object, operator feedback, resynthesis attempts, acceptance root, and blocked-readiness reasons. | Pipeline contract tests, prompt/return audits, mocked typed-envelope tests, live local OpenAI validation, Terminal stream/accordion tests. | A Reader can accept or resynthesize the Need; accepted Need truth becomes the only input admitted to Finding Fits. |
 | Finding Fits over the depository | Gate 11 | `ReadFindingFitsSynthesis.discovery` searches lexical/vector deposits, ranks all threshold-passing fits, records fit deposits, query/ranking roots, blockers, and no-worthy-fit outcomes. | Depository search tests, embedding policy tests, tool telemetry tests, staging-testnet readback verifier, mock/live parity tests. | Discovery returns all fit deposits above threshold and never invents source outside the depository. |

package.json

@@ -39,6 +39,7 @@
     "check:canon-posture-drift": "node scripts/check-bitcode-canon-posture-drift.mjs",
     "check:spec-family": "node scripts/check-bitcode-spec-family.mjs",
     "check:v28-metadevelopment": "node scripts/check-v28-metadevelopment-readiness.mjs",
+    "check:v28-gate9": "node scripts/check-v28-gate9-depository-evidence.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/pipelines/asset-pack/src/__tests__/depository-search.test.ts

@@ -249,13 +249,21 @@ describe('AssetPack depository search', () => {
         assetId: 'asset-1',
         hasWalletOrAttestationProof: true,
         hasAssetMeasurementEvidence: true,
+        proofRoot: 'sha256:manifest-proof',
+        measurementRoot: 'sha256:manifest-measurement',
+        reconciliationReadbackRoot: 'sha256:manifest-readback',
       },
     });
 
     expect(normalized).toHaveLength(1);
     expect(normalized[0].assetId).toBe('asset-1');
     expect(normalized[0].repositoryFullName).toBe('engineeredsoftware/ENGI');
     expect(normalized[0].hasWalletOrAttestationProof).toBe(true);
+    expect(normalized[0].verificationEvidence).toMatchObject({
+      proofRoot: 'sha256:manifest-proof',
+      measurementRoot: 'sha256:manifest-measurement',
+      reconciliationReadbackRoot: 'sha256:manifest-readback',
+    });
   });
 
   it('stores depository search and fit result evidence during pipeline preprocess', async () => {

packages/pipelines/asset-pack/src/depository-search.ts

@@ -1258,6 +1258,11 @@ export function normalizePipelineDepositoryAssets(input: unknown): DepositoryAss
         mutableInBranch: false,
         materializationRoot: `.bitcode/source-material/${assetId}`,
       },
+      verificationEvidence: {
+        proofRoot: firstString(depositRecord.proofRoot),
+        measurementRoot: firstString(depositRecord.measurementRoot),
+        reconciliationReadbackRoot: firstString(depositRecord.reconciliationReadbackRoot),
+      },
       hasWalletOrAttestationProof: depositRecord.hasWalletOrAttestationProof === true,
       hasAssetMeasurementEvidence: depositRecord.hasAssetMeasurementEvidence === true,
     },

packages/protocol/server.js

@@ -804,8 +804,15 @@ export function createAppContext({
 
     state.assets.unshift(asset);
     state.ledger.accounts[`supplier:${asset.assetId}:pending_claims`] = '0';
+    if (asset.depositoryEvidence?.depositorBoundary?.walletId) {
+      const depositorAssetsKey = `depositor:${asset.depositoryEvidence.depositorBoundary.walletId}:deposited_assets`;
+      const priorDepositorAssetCount = Number(state.ledger.accounts[depositorAssetsKey] || '0');
+      state.ledger.accounts[depositorAssetsKey] = String(
+        Number.isFinite(priorDepositorAssetCount) ? priorDepositorAssetCount + 1 : 1
+      );
+    }
     writeState(state);
-    return { ok: true, asset };
+    return { ok: true, asset, depositoryEvidence: asset.depositoryEvidence || null };
   }
 
   /**

packages/protocol/src/bitcode-demo.js

@@ -460,6 +460,156 @@ function stableHashObject(value) {
   return `sha256:${sha256(canonicalJson(value))}`;
 }
 
+/**
+ * @param {any} input
+ * @param {{
+ *   assetId: string,
+ *   title: string,
+ *   artifactKind: string,
+ *   artifactType: string,
+ *   contentRoot: string,
+ *   contentUnits: any[],
+ *   addressingSurface: any,
+ *   artifactSelectionSurface: any,
+ *   signingSurface: any,
+ *   githubAppAuthSurface: any,
+ *   assetMeasurement: any,
+ *   measurementProvenance: any[]
+ * }} inputState
+ * @returns {any}
+ */
+function buildDepositoryEvidence(input, inputState) {
+  const repositoryFullName = inputState.addressingSurface.repo || input.sourceRepo || input.authSession?.repo || null;
+  const sourceBranch = inputState.addressingSurface.ref || input.sourceRef || input.sourceBranch || input.authSession?.defaultRef || null;
+  const sourceCommit = inputState.addressingSurface.commit || input.sourceCommit || null;
+  const signerAddress = inputState.signingSurface.signerAddress || input.signerAddress || null;
+  const walletId = signerAddress ? `wallet:${signerAddress}` : null;
+  const proofRoot = stableHashObject({
+    kind: 'deposit-proof',
+    assetId: inputState.assetId,
+    contentRoot: inputState.contentRoot,
+    signerAddress,
+    signatureChecksPass: inputState.signingSurface.signatureChecksPass,
+    attestationHash: inputState.signingSurface.attestationHash,
+    authPayloadHash: inputState.githubAppAuthSurface.authPayloadHash
+  });
+  const measurementRoot = stableHashObject({
+    kind: 'deposit-measurement',
+    assetId: inputState.assetId,
+    contentRoot: inputState.contentRoot,
+    staticReceiptIds: (inputState.assetMeasurement.staticExecutionReceipts || []).map((receipt) => receipt.receiptId),
+    contentUnitHashes: inputState.contentUnits.map((unit) => unit.unitHash)
+  });
+  const reconciliationReadbackRoot = stableHashObject({
+    kind: 'deposit-reconciliation-readback',
+    assetId: inputState.assetId,
+    repositoryFullName,
+    sourceBranch,
+    sourceCommit,
+    proofRoot,
+    measurementRoot,
+    addressingRoot: inputState.addressingSurface.addressingRoot,
+    selectedInventoryRoot: inputState.artifactSelectionSurface.selectedInventoryRoot
+  });
+  const lexicalDocument = {
+    schema: 'bitcode.depository.lexical-document',
+    documentId: `lexical:${inputState.assetId}`,
+    assetId: inputState.assetId,
+    title: inputState.title,
+    artifactKind: inputState.artifactKind,
+    artifactType: inputState.artifactType,
+    repositoryFullName,
+    sourceBranch,
+    sourceCommit,
+    contentRoot: inputState.contentRoot,
+    contentUnitIds: inputState.contentUnits.map((unit) => unit.unitId),
+    contentUnitRoots: inputState.contentUnits.map((unit) => unit.unitHash),
+    searchableTermsRoot: stableHashObject({
+      title: inputState.title,
+      artifactKind: inputState.artifactKind,
+      repositoryFullName,
+      sourceBranch,
+      sourceCommit,
+      paths: inputState.addressingSurface.sourcePaths || []
+    })
+  };
+  const vectorDocument = {
+    schema: 'bitcode.depository.vector-document',
+    documentId: `vector:${inputState.assetId}`,
+    assetId: inputState.assetId,
+    sourceTextRoot: stableHashObject({
+      assetId: inputState.assetId,
+      contentRoot: inputState.contentRoot,
+      contentUnitRoots: inputState.contentUnits.map((unit) => unit.unitHash)
+    }),
+    embeddingPolicy: {
+      model: 'text-embedding-3-small',
+      dimensions: 1536,
+      inputKind: 'source-bound-depository-document',
+      vectorStore: {
+        table: 'deliverable_vectors',
+        rpc: 'match_deliverable_vectors',
+        distanceMetric: 'cosine'
+      }
+    },
+    indexState: 'ready_for_embedding_generation'
+  };
+  const lexicalDocumentRoot = stableHashObject(lexicalDocument);
+  const vectorDocumentRoot = stableHashObject(vectorDocument);
+  const depositorySearchDocumentRoot = stableHashObject({
+    schema: 'bitcode.depository.search-document-set',
+    assetId: inputState.assetId,
+    lexicalDocumentRoot,
+    vectorDocumentRoot,
+    proofRoot,
+    measurementRoot,
+    reconciliationReadbackRoot
+  });
+
+  return {
+    schema: 'bitcode.depository.deposit-evidence',
+    assetId: inputState.assetId,
+    repositoryFullName,
+    sourceBranch,
+    sourceCommit,
+    contentRoot: inputState.contentRoot,
+    proofRoot,
+    measurementRoot,
+    reconciliationReadbackRoot,
+    depositorySearchDocumentRoot,
+    lexicalDocumentRoot,
+    vectorDocumentRoot,
+    searchDocuments: {
+      lexical: {
+        ...lexicalDocument,
+        documentRoot: lexicalDocumentRoot
+      },
+      vector: {
+        ...vectorDocument,
+        documentRoot: vectorDocumentRoot
+      }
+    },
+    depositorBoundary: {
+      walletId,
+      signerAddress,
+      signerClass: 'depositor',
+      ownershipState: 'depositor-owned-before-read-settlement',
+      readerVisibilityBeforeSettlement: 'measurements-and-non-source-metadata-only'
+    },
+    indexState: {
+      lexical: 'ready',
+      vector: vectorDocument.indexState,
+      table: 'deliverable_vectors',
+      rpc: 'match_deliverable_vectors'
+    },
+    sourceProofRoots: {
+      addressingRoot: inputState.addressingSurface.addressingRoot,
+      selectedInventoryRoot: inputState.artifactSelectionSurface.selectedInventoryRoot,
+      authPayloadHash: inputState.githubAppAuthSurface.authPayloadHash
+    }
+  };
+}
+
 /**
  * @param {string} surfaceId
  * @param {readonly unknown[]} [values=[]]
@@ -3025,13 +3175,40 @@ export function makeCandidateAsset(input) {
     ],
     staticExecutionReceipts: [assetCodeAnalysisReceipt, ...collectStaticExecutionReceipts(contentUnits)]
   };
+  const depositoryEvidence = buildDepositoryEvidence(input, {
+    assetId,
+    title: input.title,
+    artifactKind,
+    artifactType,
+    contentRoot,
+    contentUnits,
+    addressingSurface,
+    artifactSelectionSurface,
+    signingSurface,
+    githubAppAuthSurface,
+    assetMeasurement,
+    measurementProvenance: assetMeasurement.provenance
+  });
 
   return {
     assetId,
     depositedAt: input.depositedAt || nowIso(),
     title: input.title,
     artifactKind,
     artifactType,
+    repositoryFullName: depositoryEvidence.repositoryFullName,
+    sourceBranch: depositoryEvidence.sourceBranch,
+    sourceCommit: depositoryEvidence.sourceCommit,
+    hasWalletOrAttestationProof: true,
+    hasAssetMeasurementEvidence: true,
+    proofRoot: depositoryEvidence.proofRoot,
+    measurementRoot: depositoryEvidence.measurementRoot,
+    reconciliationReadbackRoot: depositoryEvidence.reconciliationReadbackRoot,
+    depositorySearchDocumentRoot: depositoryEvidence.depositorySearchDocumentRoot,
+    lexicalDocumentRoot: depositoryEvidence.lexicalDocumentRoot,
+    vectorDocumentRoot: depositoryEvidence.vectorDocumentRoot,
+    depositorWalletId: depositoryEvidence.depositorBoundary.walletId,
+    depositoryEvidence,
     sourceMaterialBinding: {
       mode: input.bindingMode || 'read-only-mounted-copy',
       confidentiality: 'private-required',
@@ -3101,7 +3278,13 @@ export function makeCandidateAsset(input) {
       benchmarkRunId: input.benchmarkRunId || 'gha_run_auth_001',
       reproSteps: input.reproSteps || ['rerun benchmark workflow', 'inspect issuer compatibility logs'],
       pinnedEnvironment: input.pinnedEnvironment || 'ubuntu-24.04 + node 22 + rust stable',
-      proofLogs: input.proofLogs || []
+      proofLogs: input.proofLogs || [],
+      proofRoot: depositoryEvidence.proofRoot,
+      measurementRoot: depositoryEvidence.measurementRoot,
+      reconciliationReadbackRoot: depositoryEvidence.reconciliationReadbackRoot,
+      depositorySearchDocumentRoot: depositoryEvidence.depositorySearchDocumentRoot,
+      lexicalDocumentRoot: depositoryEvidence.lexicalDocumentRoot,
+      vectorDocumentRoot: depositoryEvidence.vectorDocumentRoot
     },
     metadata: {
       author: input.author,