wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -56,14 +56,14 @@ V28 answers that by specifying:
 ## V28 Terminal Terminology Contract
 
 V28 user-facing Terminal language is Deposit/Depositing and Read/Reading.
-The previous Deposit/Depositing and Read/Reading vocabulary is retired from operator-visible copy, QA instructions, public docs, Terminal labels, tooltip prose, test-visible assertions, and staging walkthroughs.
+Pre-V28 Terminal vocabulary is retired from operator-visible copy, QA instructions, public docs, Terminal labels, tooltip prose, test-visible assertions, staging walkthroughs, and active data-contract carriers.
 
 Deposit means source supply is selected, bound to a repository/branch/commit, signed where required, and submitted as the candidate supply side before any meaningful Read/Fit result is evaluated.
 Read means the demand/query/measurement side that reads against available deposited source posture, then proceeds into Fit, proofs, finalities, ledgerization, and reconciliation.
 
-Implementation may temporarily retain persisted/API compatibility carriers such as enum values, route names, schema fields, artifact IDs, component filenames, and canonical proof IDs containing `deposit`, `read`, or `read-measurement`.
-Those carriers are not operator vocabulary.
-Any active UI, documentation, QA query label, or test-visible copy that surfaces those carriers must translate them to Deposit/Read language until a separate bounded schema/API migration is specified.
+As of the V28 Deposit/Read data-contract closure, active database, ORM, API, QA-query, OpenAPI, demonstration, and protocol carriers use Deposit/Read naming where they are part of the current contract.
+Remaining strings containing `deposit`, `read`, or `read-measurement` are current V28 names, not compatibility vocabulary.
+The live staging migration may use bounded dynamic compatibility references only to upgrade already-deployed data without keeping retired identifiers in the active schema.
 
 ## Real-Deployed Staging-Testnet MVP Target
 

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -113,8 +113,8 @@ It links manual screenshots, console logs, server logs, Supabase SQL checks, and
 | --- | --- | --- | --- |
 | BTC/D identity and wallet-backed session | `uapi/app/api/wallet/_shared.ts`, `uapi/app/api/wallet/authenticate/route.ts`, `uapi/app/api/wallet/oauth/authorization-code/route.ts`, `uapi/app/api/wallet/oauth/token/route.ts`, `uapi/app/api/wallet/oauth/userinfo/route.ts`, `uapi/lib/bitcoin-wallet-client.ts`, `uapi/lib/bitcode-wallet-local.ts`, `packages/btd/src/wallet.ts`, `packages/btd/src/bitcoin-provider.ts`, `supabase/migrations/003_user_connections_provider_scope.sql`, `uapi/tests/bitcoinWalletClient.test.ts` | staging prerequisite pass for Leather; BTC fee signing still pending | May 14 live staging SQL confirmed `auth.users`, `auth.identities`, `user_profiles.settings.bitcodeProfile.walletBinding`, and `user_connections.provider='leather'` for the same wallet-backed user. Xverse/manual-provider parity and Terminal BTC fee signing remain closure evidence before BTC fee usage depends on them. |
 | GitHub App and repository source scope | `uapi/app/api/vcs/_shared.ts`, `uapi/app/api/vcs/[provider]/callback/route.ts`, `uapi/app/api/vcs/[provider]/setup/route.ts`, `uapi/app/api/vcs/[provider]/repositories/route.ts`, `packages/api/src/vcs/github-service.ts`, Auxillaries Externals pane, `supabase/migrations/001_v26_production.sql` `user_connections` and `vcs_repositories` | staging prerequisite pass | May 14 live staging SQL confirmed GitHub installation `132358627`, account `engineeredsoftware`, provider-scoped connection data, and `public.vcs_repositories` rows including `engineeredsoftware/ENGI`. Terminal Deposit/Read must now prove that repository inventory is used as live source scope. |
-| Terminal terminology parity | `BITCODE_SPEC_V28.md` terminology contract, `uapi/app/terminal/terminal-workspace-copy.ts`, `uapi/app/terminal/TerminalDepositComposer.tsx`, `uapi/app/terminal/TerminalReadScenarioPanel.tsx`, `uapi/components/base/bitcode/layout/bitcode-public-copy.ts`, Terminal/public-shell/docs tests | closed for user-visible copy; internal compatibility carriers preserved | Active V28 UI, docs, QA prose, and test-visible assertions use Deposit/Depositing and Read/Reading. Persisted/API carriers such as `deposit`, `read`, `read-measurement`, `/api/read-review`, proof IDs, schema fields, and component filenames are treated as compatibility-only until a bounded migration replaces them. |
-| PSQL/Supabase data reality | `supabase/migrations/001_v26_production.sql`, `002_v27_btd_crypto_registry.sql`, `003_user_connections_provider_scope.sql`, `20260514173000_enable_pipeline_runs_rls.sql`, `20260514175000_enable_pipeline_runtime_rls.sql`, `packages/orm/src/data-health/*`, `packages/orm/scripts/run-data-health.ts`, `packages/orm/scripts/check-schema-types.ts`, `supabase/DATA_HEALTH.md`, `supabase/queries/*` | baseline pass; Terminal Deposit/Read write evidence pending | Staging database has all required auth/profile/connection/repository/BTD registry/journal/telemetry tables, RLS posture does not hide required user-scoped reads, generated schema types cover canonical public tables, automated data-health checks pass, and QA SQL queries match Terminal/Wallet/Externals UI state. Current baseline: `pnpm db:data-health:daily` passes against staging, live data-health/schema E2E passes with `.env.local` loading, wallet/GitHub SQL evidence is green, and the Terminal-specific saved queries now gate Read/Deposit/Fit write-read parity. |
+| Terminal terminology parity | `BITCODE_SPEC_V28.md` terminology contract, `uapi/app/terminal/terminal-workspace-copy.ts`, `uapi/app/terminal/TerminalDepositComposer.tsx`, `uapi/app/terminal/TerminalReadScenarioPanel.tsx`, `uapi/components/base/bitcode/layout/bitcode-public-copy.ts`, Terminal/public-shell/docs tests, `supabase/migrations/20260515143000_v28_deposit_read_data_contract.sql` | closed for UI, docs, tests, API, ORM, demonstration, and data-contract carriers | Active V28 UI, docs, QA prose, OpenAPI, test-visible assertions, BTD journal kinds, ORM types, Supabase queries, and live schema use Deposit/Depositing and Read/Reading. The migration applied to staging renames range linkage to `read_id` and journal writes to `read_submission`; source audit has no exact retired Terminal-domain vocabulary outside excluded legacy/build artifacts. |
+| PSQL/Supabase data reality | `supabase/migrations/001_v26_production.sql`, `002_v27_btd_crypto_registry.sql`, `003_user_connections_provider_scope.sql`, `20260514173000_enable_pipeline_runs_rls.sql`, `20260514175000_enable_pipeline_runtime_rls.sql`, `20260515143000_v28_deposit_read_data_contract.sql`, `packages/orm/src/data-health/*`, `packages/orm/scripts/run-data-health.ts`, `packages/orm/scripts/check-schema-types.ts`, `supabase/DATA_HEALTH.md`, `supabase/queries/*` | data-contract naming closed; Terminal Deposit/Read write evidence pending | Staging database has all required auth/profile/connection/repository/BTD registry/journal/telemetry tables, RLS posture does not hide required user-scoped reads, generated schema types cover canonical public tables, automated data-health checks pass, and QA SQL queries match Terminal/Wallet/Externals UI state. Current baseline: migration `20260515143000` is applied locally and remotely, `btd_asset_pack_ranges` exposes `read_id`, journal kind constraints accept `read_submission`, `pnpm db:data-health:daily` passes against staging, wallet/GitHub SQL evidence is green, and the Terminal-specific saved queries gate Deposit/Read/Fit write-read parity. |
 | Fit-finding | `uapi/app/terminal/TerminalDepositReadWorkbench.tsx`, `TerminalReadScenarioPanel.tsx`, `terminal-deposit-read-workbench.ts`, `terminal-read-scenarios.ts`, `packages/protocol/src/canonical/*`, `protocol-demonstration/src/*` reference witness | partial | Terminal simplest Read produces or reads Fit candidates, review decision, qualities, rejection/block reasons, source roots, proof/dedupe roots, and visible readiness state without relying on demonstration runtime imports. |
 | AssetPack synthesis and deterministic pipeline configuration | `internal-docs/ASSETPACK_EXECUTION.md`, `packages/protocol/src/canonical/run-artifacts.js`, `packages/btd/src/semantic-volume.ts`, `measuremint.ts`, `range.ts`, `receipts.ts`, `replay.ts`, `uapi/app/api/btd/mint-draft/route.ts`, Terminal AssetPack components | partial with blocker | Staging Read/Fit path creates or reads AssetPack evidence, semantic volume, measuremint/range or zero-cell receipt, and access-policy hash using protocol-specified model/pipeline configuration. Any broad user model-selection UI that can affect ledgerized synthesis must be removed or scoped to non-ledgerized conversation UX. |
 | Ledgerized journal and ledger anchors | `packages/btd/src/terminal-journal.ts`, `ledger-anchor.ts`, `reconciliation.ts`, `uapi/app/api/btd/terminal-journal/route.ts`, `asset-pack-ledger-anchor/route.ts`, `ledger-database-reconciliation/route.ts`, `supabase/migrations/002_v27_btd_crypto_registry.sql` | partial | Terminal shows journal rows for Read/Fit/AssetPack/BTC fee/anchor/reconciliation events, ledger anchor or blocked-readiness state is explicit, and SQL evidence in `btd_terminal_journal_entries`, `btd_asset_pack_ledger_anchors`, and reconciliation repair tables matches the UI. |

BITCODE_V28_QA.md

@@ -1128,6 +1128,18 @@ Saved query name: `v28_qa_terminal_04_deposit_repository_alignment`
 
 Use `supabase/queries/v28_qa_terminal_04_deposit_repository_alignment.sql` after Terminal loads and after each Deposit recording. The query confirms live repository inventory belongs to the connected GitHub account and flags any protocol-demo `frontier/*` reference in recent Terminal Deposit activity.
 
+V28 Deposit/Read data-contract closure:
+
+Saved query name: `v28_qa_data_contract_deposit_read_migration`
+
+Use `supabase/queries/v28_qa_data_contract_deposit_read_migration.sql` after migrations or staging resets. Expected `data_contract_state` is `v28_deposit_read_data_contract_closed`.
+
+- Migration `20260515143000_v28_deposit_read_data_contract` is applied to the linked staging Supabase project.
+- `public.btd_asset_pack_ranges` now projects range linkage through `read_id`; the previous live column is absent after migration.
+- `public.btd_terminal_journal_entries` accepts `read_submission` as the Terminal journal transaction kind.
+- ORM schema types, data-health checks, saved QA SQL, OpenAPI conversation payload docs, protocol demonstration fixtures, and API conversation-stream internals use the current Deposit/Read contract.
+- `pnpm db:schema-types:check`, `pnpm db:data-health:daily`, ORM data-health tests, UAPI Terminal/conversation tests, UAPI lint/build, API build, and protocol demonstration V28 QA are the closure evidence for this rename pass.
+
 BTD and ledger projection readback:
 
 Saved query name: `v28_qa_terminal_03_btd_ledger_after_terminal`

docs/api/conversations-openapi.yaml

@@ -714,7 +714,7 @@ paths:
         - `feedback` - Open feedback channels
         
         **Client Commands:**
-        - Pipeline commands (`asset_pack`, `need_measurement`) return execution instructions
+        - Pipeline commands (`asset_pack`, `read_measurement`) return execution instructions
         - Navigation commands (`history`, `runs`) return frontend routing info
         
       requestBody:
@@ -828,7 +828,7 @@ components:
       properties:
         type:
           type: string
-          enum: [asset_pack, need_measurement, attachment, source, command]
+          enum: [asset_pack, read_measurement, attachment, source, command]
           description: Token type determining how it's processed
         value:
           type: string

packages/api/src/routes/conversations.ts

@@ -73,7 +73,7 @@ type ConversationRichInputSummary = {
   source_attachments: ConversationAttachmentReference[];
   output_destinations: ConversationAttachmentReference[];
   asset_pack_references: ConversationRichInputReference[];
-  need_measurement_intents: ConversationRichInputReference[];
+  read_measurement_intents: ConversationRichInputReference[];
   token_counts: ReturnType<typeof countTokenTypes>;
 };
 
@@ -181,7 +181,7 @@ function tokenRequestsReadMeasurement(token: ConversationStreamToken) {
   const pipelineType =
     typeof token.metadata?.pipelineType === 'string' ? normalizeConversationText(token.metadata.pipelineType).toLowerCase() : '';
 
-  return tokenType === 'need_measurement' || tokenType === 'measure' || pipelineType.includes('measure');
+  return tokenType === 'read_measurement' || tokenType === 'measure' || pipelineType.includes('measure');
 }
 
 function buildConversationRichInputSummary(
@@ -198,7 +198,7 @@ function buildConversationRichInputSummary(
         return tokenType === 'asset_pack' || tokenType === 'shippable' || tokenType === 'evidence_document';
       })
       .map(buildRichInputReference),
-    need_measurement_intents: tokens.filter(tokenRequestsReadMeasurement).map(buildRichInputReference),
+    read_measurement_intents: tokens.filter(tokenRequestsReadMeasurement).map(buildRichInputReference),
     token_counts: countTokenTypes(tokens),
   };
 }
@@ -209,7 +209,7 @@ function deriveConversationExecutionType(tokens: ConversationStreamToken[]) {
       typeof token.metadata?.pipelineType === 'string' ? token.metadata.pipelineType : undefined;
     const candidate = metadataPipelineType || normalizeConversationTokenType(token) || resolveConversationTokenValue(token);
 
-    if (candidate === 'need_measurement' || candidate === 'measure') {
+    if (candidate === 'read_measurement' || candidate === 'measure') {
       return normalizeAgenticExecutionType(candidate);
     }
 
@@ -321,7 +321,7 @@ async function createConversationExecution(options: {
         source_attachments: options.richInput.source_attachments,
         output_destinations: options.richInput.output_destinations,
         asset_pack_references: options.richInput.asset_pack_references,
-        need_measurement_intents: options.richInput.need_measurement_intents,
+        read_measurement_intents: options.richInput.read_measurement_intents,
       } as any,
       started_at: nowIso,
       created_at: nowIso,

packages/btd/src/terminal-journal.ts

@@ -1,7 +1,7 @@
 import { assertNonEmptyString } from './constants';
 
 export type TerminalTransactionKind =
-  | 'need_submission'
+  | 'read_submission'
   | 'fit_closure'
   | 'proof_admission'
   | 'asset_pack_mint'
@@ -17,7 +17,7 @@ export type TerminalTransactionKind =
   | 'ledger_database_reconciliation';
 
 export const REQUIRED_TERMINAL_TRANSACTION_KINDS = [
-  'need_submission',
+  'read_submission',
   'fit_closure',
   'proof_admission',
   'asset_pack_mint',

packages/orm/src/data-health/checks.ts

@@ -120,7 +120,7 @@ const REQUIRED_COLUMNS: Record<string, readonly string[]> = {
     'range_end_exclusive',
     'token_count',
     'normalized_bitcode_volume',
-    'need_id',
+    'read_id',
     'source_manifest_root',
     'measurement_receipt_root',
     'fit_receipt_root',

packages/orm/src/types/database.generated.ts

@@ -436,7 +436,7 @@ export type Database = {
           issued_at: string
           measurement_receipt_root: string
           minted_at_exchange_sequence: number
-          need_id: string
+          read_id: string
           normalized_bitcode_volume: number
           proof_root: string
           range_end_exclusive: number
@@ -457,7 +457,7 @@ export type Database = {
           issued_at: string
           measurement_receipt_root: string
           minted_at_exchange_sequence: number
-          need_id: string
+          read_id: string
           normalized_bitcode_volume: number
           proof_root: string
           range_end_exclusive: number
@@ -478,7 +478,7 @@ export type Database = {
           issued_at?: string
           measurement_receipt_root?: string
           minted_at_exchange_sequence?: number
-          need_id?: string
+          read_id?: string
           normalized_bitcode_volume?: number
           proof_root?: string
           range_end_exclusive?: number

packages/orm/src/types/database.ts

@@ -634,7 +634,7 @@ export type Database = {
           issued_at: string
           measurement_receipt_root: string
           minted_at_exchange_sequence: number
-          need_id: string
+          read_id: string
           normalized_bitcode_volume: number
           proof_root: string
           range_end_exclusive: number
@@ -655,7 +655,7 @@ export type Database = {
           issued_at: string
           measurement_receipt_root: string
           minted_at_exchange_sequence: number
-          need_id: string
+          read_id: string
           normalized_bitcode_volume: number
           proof_root: string
           range_end_exclusive: number
@@ -676,7 +676,7 @@ export type Database = {
           issued_at?: string
           measurement_receipt_root?: string
           minted_at_exchange_sequence?: number
-          need_id?: string
+          read_id?: string
           normalized_bitcode_volume?: number
           proof_root?: string
           range_end_exclusive?: number

packages/prompts/src/raw_promptparts/specific/index.ts

@@ -299,7 +299,7 @@ export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_capabili
 export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_identity_definition.d";
 export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_identity_definition";
 export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_output_attachments_spec";
-export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_output_needdefinitionanalysis_spec";
+export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_output_readdefinitionanalysis_spec";
 export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_output_types_spec";
 export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_plan_modality_audio_strategy";
 export * from "./promptpart_specific_agent_assetpacksetupcomprehendread_plan_modality_image_strategy.d";