Merge pull request #205 from engineeredsoftware/v45/gate-2-knowledge-commoditization-law

V45 Gate 2: Knowledge Commoditization Law

Author: geraldarthurdavis

BITCODE_SPEC_V45_NOTES.md

@@ -64,8 +64,9 @@ production-grade:
 - `/packs` as the searchable master-detail surface for Bitcode network
   activity, proofs, statements, repairs, and economic state.
 - BTC as settlement money and source of payment truth.
-- BTD as the measured/mined/minted read-right object bound to AssetPack value,
-  rights transfer, source unlock, and ownership boundaries.
+- BTD as the weighted scalar knowledge-volume unit whose settled form carries
+  rights, source unlock authority, ownership boundaries, and source-to-shares
+  allocation context.
 - Proof roots, ledgerized journaling, telemetry, database/storage
   synchronization, and generated canon as auditability rails.
 - Website routes, ChatGPT App, Bitcode Chat conversation overlays, API/MCP,
@@ -79,8 +80,9 @@ production-grade:
 - V44 needed this promotion addendum because canon posture text is protocol law:
   a promoted spec cannot contain stale active/draft hierarchy prose.
 - V44 states the BTD/BTC/source-to-shares roles clearly, but V45 must decide
-  whether BTD measuring, mining, minting, ownership, and lifecycle state are
-  specified precisely enough for enterprise and public protocol comprehension.
+  whether BTD measuring, mining, minting, scalar knowledge-volume, ownership,
+  and lifecycle state are specified precisely enough for enterprise and public
+  protocol comprehension.
 - V44 names BTC settlement, quote, observed payment, final settlement,
   reconciliation, and repair states, but V45 should audit whether the exact
   payment/finality/source-unlock/delivery state machine is complete enough.
@@ -95,8 +97,9 @@ production-grade:
 2. What exact state transitions define an AssetPack from potential deposit
    option through admitted supply, Finding Fits, paid Need-Fit pack, delivery,
    compensation, and repair?
-3. What exact state transitions define BTD measuring, mining, minting,
-   ownership transfer, source unlock, and post-settlement rights?
+3. What exact state transitions define BTD measuring, mining, minting, scalar
+   knowledge-volume, ownership transfer, source unlock, and post-settlement
+   rights?
 4. What exact state transitions define BTC quote, payment observation,
    confirmation/finality, repair, refund/escalation if any, and contributor
    compensation?
@@ -109,6 +112,94 @@ production-grade:
 7. Which V45 gates should be specification-only, proof-only, interface-only,
    implementation, rehearsal, and promotion gates?
 
+## V45 gate sequencing rule
+
+V45 proceeds in three ordered movements:
+
+1. Specification atom gates. Each small protocol specification atom is its own
+   gate and pull request. Each atom must be correct alone before the next atom
+   begins, and every atom must be reconciled into the gestalt of Bitcode as the
+   knowledge commoditization system.
+2. Specification parity matrix gate. After the specification atoms are accepted,
+   one gate builds the V45 parity matrix comparing every accepted specification
+   update against implementation, tests, proofs, generated artifacts,
+   workflows, documentation, and interface surfaces.
+3. Grouped implementation gates. Only after the parity matrix is accepted do
+   implementation gates begin, grouped by coherent protocol/product work rather
+   than by isolated prose atoms.
+
+This ordering is itself V45 protocol-development law: do not start
+implementation work, broad parity claims, or promotion planning while the
+specification atoms remain unsettled.
+
+## V45 protocol atom 1: knowledge commoditization system
+
+Audit classification: V42, V43, and V44 clearly state the commercial path for
+depositing and reading technical knowledge, and V43/V44 clearly establish
+AssetPacks as the object in and out. The remaining gap is precision of the
+one-sentence protocol identity. V45 begins by making that identity exact before
+it expands any state machine, interface, pricing, or proof surface.
+
+Protocol-law statement:
+
+Bitcode is the knowledge commoditization protocol and commercial system for
+turning source-derived technical knowledge into source-safe, measurable
+AssetPacks whose measurements can be weighted and summed into BTD scalar
+knowledge-volume when evaluated against a reviewed Need. That Need-relative BTD
+volume drives deterministic BTC quote/settlement, expresses post-settlement
+rights, controls source unlock, routes contributor shares, and is audited
+through proof roots, ledgerized journals, telemetry, database/storage
+synchronization, and generated canon.
+
+This means:
+
+- The traded commodity is the AssetPack, not raw source, raw prompts, provider
+  responses, loose files, screenshots, telemetry logs, or private repository
+  access.
+- BTC is settlement money and payment truth.
+- BTD is the protocol's weighted scalar knowledge-volume unit. Settled BTD is
+  also rights-bearing: it expresses paid read/use rights, source unlock
+  authority, ownership boundaries, and source-to-shares allocation context. It
+  is not merely a read-right, not a deposit option, and not a replacement for
+  BTC.
+- BTD-relevant measurements may exist before a Need: deposit-time measurements
+  can preview coverage, source criticality, likely utility, BTD potential, and
+  search posture for the depositor and the Depository.
+- Final BTD size can only be calculated against a reviewed Need because the
+  knowledge volume depends on Need-relative measurement weights, admitted fit
+  quality, and the selected Need-Fit AssetPack context.
+- All admissible Need-Fit measurements are weighted and summed to determine the
+  scalar BTD knowledge volume and source-to-shares allocation basis for the
+  settled AssetPack.
+- Depositing forms source-safe AssetPack supply; it does not sell or disclose
+  protected source before paid settlement and rights transfer.
+- Reading forms measured demand, synthesizes Needs, finds fitting Depository
+  supply, previews only source-safe measurements/metadata, and buys full
+  source-bearing delivery only after BTC settlement and BTD rights transfer.
+- Source-to-shares is contributor allocation after paid Need-Fit selection; it
+  is not an estimated earning range and not a quote.
+- `/packs`, `/read`, `/deposit`, API/MCP, ChatGPT App, Bitcode Chat, public
+  docs, and landing pages may present the system differently, but none may
+  change the protocol law or disclose source outside the settlement boundary.
+
+What this atom does not yet decide:
+
+- the exact AssetPack lifecycle state machine;
+- the exact BTD measuring, mining, minting, scalar knowledge-volume,
+  ownership, and transfer state machine;
+- the exact BTC quote, observation, confirmation, finality, repair, refund, or
+  compensation state machine;
+- which non-website interfaces are protocol-authoritative in V45; or
+- whether later V45 gates should broaden from technical knowledge toward
+  all knowledge commodities.
+
+Acceptance for this atom: later V45 specification may refine terms, but it must
+preserve AssetPack as commodity, BTC as settlement money, BTD as weighted scalar
+knowledge-volume unit whose settled form carries rights, final BTD size as
+Need-relative, source-safety before settlement, repository delivery after rights
+proof, and proof/ledger/journal observability as Bitcode's market-infrastructure
+rails.
+
 ## Non-goals during V45 opening
 
 - Do not implement V45 gate behavior before the V45 intent discussion is

package.json

@@ -387,6 +387,7 @@
     "generate:v44-promotion-readiness": "node scripts/generate-v44-promotion-readiness-report.mjs",
     "check:v44-promotion-readiness": "node scripts/generate-v44-promotion-readiness-report.mjs --check",
     "check:v44-gate10": "node scripts/check-v44-gate10-promotion-readiness.mjs",
+    "check:v45-gate2": "node scripts/check-v45-gate2-knowledge-commoditization-law.mjs",
     "generate:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs",
     "check:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs --check",
     "check:v38-gate2": "node scripts/check-v38-gate2-inference-surface-inventory.mjs",

scripts/check-v45-gate2-knowledge-commoditization-law.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const defaultRepoRoot = path.resolve(__dirname, '..');
+
+function read(root, relativePath) {
+  return readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+function exists(root, relativePath) {
+  return existsSync(path.join(root, relativePath));
+}
+
+function git(root, args) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+}
+
+function assertCheck(failures, condition, message) {
+  if (!condition) failures.push(message);
+}
+
+function normalize(content) {
+  return content.replace(/\s+/gu, ' ').trim();
+}
+
+function parseArgs(argv) {
+  const args = { repoRoot: defaultRepoRoot, skipBranchCheck: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--repo-root') args.repoRoot = path.resolve(argv[++index]);
+    else if (arg === '--skip-branch-check') args.skipBranchCheck = true;
+    else if (arg === '--help' || arg === '-h') args.help = true;
+    else throw new Error(`Unknown argument ${arg}`);
+  }
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: node scripts/check-v45-gate2-knowledge-commoditization-law.mjs [--skip-branch-check] [--repo-root <path>]',
+      '',
+      'Checks the V45 opening protocol-law atom for Bitcode as a knowledge commoditization system.',
+    ].join('\n'),
+  );
+  process.stdout.write('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const root = args.repoRoot;
+  const failures = [];
+  const pointer = read(root, 'BITCODE_SPEC.txt').trim();
+
+  assertCheck(failures, pointer === 'V44', `BITCODE_SPEC.txt must remain V44 during V45 opening work. Observed ${pointer || 'empty'}.`);
+
+  if (!args.skipBranchCheck) {
+    const branch = git(root, ['branch', '--show-current']);
+    assertCheck(
+      failures,
+      branch === 'version/v45' || /^v45\/gate-\d+-[a-z0-9][a-z0-9-]*$/u.test(branch),
+      `V45 work must occur on version/v45 or v45/gate-N-* branches. Observed ${branch || 'detached HEAD'}.`,
+    );
+  }
+
+  for (const relativePath of [
+    'BITCODE_SPEC_V45_NOTES.md',
+    'BITCODE_SPEC_V44.md',
+    'BITCODE_SPEC_V44_PROVEN.md',
+    'package.json',
+  ]) {
+    assertCheck(failures, exists(root, relativePath), `Missing required V45 Gate 2 file: ${relativePath}`);
+  }
+
+  const notes = read(root, 'BITCODE_SPEC_V45_NOTES.md');
+  const normalizedNotes = normalize(notes);
+  const packageJson = read(root, 'package.json');
+
+  for (const phrase of [
+    'V45 gate sequencing rule',
+    'Specification atom gates',
+    'Each small protocol specification atom is its own gate and pull request',
+    'Specification parity matrix gate',
+    'comparing every accepted specification update against implementation, tests, proofs, generated artifacts, workflows, documentation, and interface surfaces',
+    'Grouped implementation gates',
+    'Only after the parity matrix is accepted do implementation gates begin',
+    'do not start implementation work, broad parity claims, or promotion planning while the specification atoms remain unsettled',
+    'V45 protocol atom 1: knowledge commoditization system',
+    'Bitcode is the knowledge commoditization protocol and commercial system',
+    'source-safe, measurable AssetPacks whose measurements can be weighted and summed into BTD scalar knowledge-volume',
+    'That Need-relative BTD volume drives deterministic BTC quote/settlement',
+    'expresses post-settlement rights',
+    'controls source unlock',
+    'routes contributor shares',
+    'proof roots, ledgerized journals, telemetry',
+    'The traded commodity is the AssetPack',
+    'BTC is settlement money and payment truth',
+    'BTD is the protocol\'s weighted scalar knowledge-volume unit',
+    'Settled BTD is also rights-bearing',
+    'paid read/use rights',
+    'source unlock authority',
+    'It is not merely a read-right',
+    'BTD-relevant measurements may exist before a Need',
+    'Final BTD size can only be calculated against a reviewed Need',
+    'Need-relative measurement weights',
+    'All admissible Need-Fit measurements are weighted and summed',
+    'scalar BTD knowledge volume and source-to-shares allocation basis',
+    'Depositing forms source-safe AssetPack supply',
+    'Reading forms measured demand',
+    'Source-to-shares is contributor allocation after paid Need-Fit selection',
+    'none may change the protocol law or disclose source outside the settlement boundary',
+    'What this atom does not yet decide',
+    'exact AssetPack lifecycle state machine',
+    'exact BTD measuring, mining, minting, scalar knowledge-volume, ownership, and transfer state machine',
+    'exact BTC quote, observation, confirmation, finality, repair, refund, or compensation state machine',
+    'Acceptance for this atom',
+    'AssetPack as commodity, BTC as settlement money, BTD as weighted scalar knowledge-volume unit whose settled form carries rights',
+    'final BTD size as Need-relative',
+  ]) {
+    assertCheck(failures, normalizedNotes.includes(phrase), `V45 Gate 2 notes must include phrase: ${phrase}`);
+  }
+
+  assertCheck(
+    failures,
+    packageJson.includes('"check:v45-gate2": "node scripts/check-v45-gate2-knowledge-commoditization-law.mjs"'),
+    'package.json must expose check:v45-gate2.',
+  );
+
+  if (failures.length > 0) {
+    process.stderr.write('V45 Gate 2 knowledge commoditization law check failed:\n');
+    for (const failure of failures) process.stderr.write(`- ${failure}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write('V45 Gate 2 knowledge commoditization law check passed.\n');
+}
+
+try {
+  main();
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${detail}\n`);
+  process.exitCode = 1;
+}