@mcptoolshop/style-dataset-lab 3.4.0 → 3.5.0

package/lib/verify-chain.js

@@ -0,0 +1,367 @@
+/**
+ * End-to-end offline provenance chain verifier (G9, §2.2–§2.3).
+ *
+ * Walks every link required for CC-BY-4.0 release eligibility:
+ *   1. owner_and_licence (G5): owner === "mcp-tool-shop", licence === "CC-BY-4.0", ai_assisted_disclosure === true
+ *   2. canon_link (G6): canon_sha, entry_id, entry_sha256 match canon-build/<canon_sha>/manifest.json per_entity_hashes
+ *   3. run_manifest_link (§2.2.1): run_id, seed, prompt/prompt_sha256, comfy_workflow_sha match runs/<run_id>/manifest.json, and image exists
+ *   4. model_licences (G4): all models and LoRAs in pinning have cleared SPDX licence_id, non-empty licence_url, and date_read
+ *   5. quarantine_guard (§2.2.5): no reference to held Portlight data (`plsvessel`, `nano-banana`)
+ *   6. verdict_separation (§2.2.6): approved records cite a reviewer/judge distinct from the generator model
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { STUDIO_OWNER, STUDIO_LICENCE } from './records.js';
+import {
+  isClearedLicenceEntry,
+  isQuarantinedName,
+  hasModelSha256,
+  normalizeModelFamilyKey,
+} from './model-licences.js';
+
+function isSafeRelativeAssetPath(projectRoot, assetPath) {
+  if (!assetPath || typeof assetPath !== 'string') return false;
+  const absRoot = resolve(projectRoot);
+  const absAsset = resolve(projectRoot, assetPath);
+  const rel = relative(absRoot, absAsset);
+  return Boolean(rel && !rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/**
+ * Verify all provenance links for a single record object against on-disk manifests.
+ */
+export function verifyRecordProvenance(projectRoot, record) {
+  const recordId = record?.id || record?.record_id || '<unknown>';
+  const failures = [];
+  const links = {
+    owner_and_licence: 'pass',
+    canon_link: 'pass',
+    run_manifest_link: 'pass',
+    model_licences: 'pass',
+    quarantine_guard: 'pass',
+    verdict_separation: 'pass',
+  };
+
+  function fail(link, code, message) {
+    links[link] = 'fail';
+    failures.push({ record_id: recordId, link, code, message });
+  }
+
+  // 1. G5: Owner and CC-BY-4.0 licence stamp
+  const owner = record?.owner ?? record?.rights?.owner ?? null;
+  const licence = record?.licence ?? record?.rights?.licence ?? null;
+  const disclosure = record?.rights?.ai_assisted_disclosure === true;
+  if (owner !== STUDIO_OWNER || licence !== STUDIO_LICENCE || !disclosure) {
+    fail(
+      'owner_and_licence',
+      'MISSING_OWNER_OR_LICENCE',
+      `Record "${recordId}" must carry owner="${STUDIO_OWNER}", licence="${STUDIO_LICENCE}", and rights.ai_assisted_disclosure=true (got owner=${JSON.stringify(owner)}, licence=${JSON.stringify(licence)}, disclosure=${JSON.stringify(disclosure)})`,
+    );
+  }
+
+  const genProv =
+    record?.generation_provenance ||
+    record?.provenance?.generation_provenance ||
+    record?.provenance ||
+    {};
+
+  // 2. G6: Canon link (canon_sha, entry_id, entry_sha256 -> canon-build/<canon_sha>/manifest.json)
+  const canonSha = record?.canon?.canon_sha ?? genProv?.canon_sha ?? null;
+  const entryId = record?.canon?.entry_id ?? genProv?.entry_id ?? null;
+  const entrySha256 = record?.canon?.entry_sha256 ?? genProv?.entry_sha256 ?? null;
+
+  if (!canonSha || !entryId || !entrySha256) {
+    fail(
+      'canon_link',
+      'BROKEN_CANON_LINK',
+      `Record "${recordId}" is missing canon link fields (canon_sha=${canonSha}, entry_id=${entryId}, entry_sha256=${entrySha256})`,
+    );
+  } else {
+    const dirName = String(canonSha).replace(/:/g, '-');
+    const canonManifestPath = existsSync(join(projectRoot, 'canon-build', String(canonSha), 'manifest.json'))
+      ? join(projectRoot, 'canon-build', String(canonSha), 'manifest.json')
+      : join(projectRoot, 'canon-build', dirName, 'manifest.json');
+    if (!existsSync(canonManifestPath)) {
+      fail(
+        'canon_link',
+        'BROKEN_CANON_LINK',
+        `Canon build manifest not found at canon-build/${canonSha}/manifest.json for record "${recordId}"`,
+      );
+    } else {
+      try {
+        const canonManifest = JSON.parse(readFileSync(canonManifestPath, 'utf-8'));
+        const hashes = canonManifest?.per_entity_hashes || {};
+        const bareId = String(entryId).includes('/') ? String(entryId).split('/').pop() : null;
+        const expectedSha = hashes[entryId] ?? (bareId ? hashes[bareId] : undefined);
+        if (!expectedSha || expectedSha !== entrySha256) {
+          fail(
+            'canon_link',
+            'BROKEN_CANON_LINK',
+            `Record "${recordId}" entry_sha256 (${entrySha256}) does not match canon-build/${canonSha}/manifest.json per_entity_hashes["${entryId}"] (${expectedSha || 'missing'})`,
+          );
+        }
+      } catch (err) {
+        fail(
+          'canon_link',
+          'BROKEN_CANON_LINK',
+          `Canon build manifest canon-build/${canonSha}/manifest.json could not be parsed: ${err.message}`,
+        );
+      }
+    }
+  }
+
+  // 3. §2.2.1: Run manifest link + workflow sha + image existence
+  const runId = genProv?.run_id ?? null;
+  const recWorkflowSha = genProv?.comfy_workflow_sha ?? record?.provenance?.pinning?.comfy_workflow_sha ?? null;
+  const hasSeed = Number.isFinite(genProv?.seed);
+  const hasPrompt =
+    (typeof genProv?.prompt === 'string' && genProv.prompt.length > 0) ||
+    (typeof genProv?.prompt_sha256 === 'string' && genProv.prompt_sha256.length > 0);
+
+  let runManifest = null;
+  if (!runId || !recWorkflowSha || !hasSeed || !hasPrompt) {
+    fail(
+      'run_manifest_link',
+      'BROKEN_RUN_MANIFEST_LINK',
+      `Record "${recordId}" provenance is missing run_id (${runId}), comfy_workflow_sha (${recWorkflowSha}), seed (${genProv?.seed}), or prompt`,
+    );
+  } else {
+    const runManifestPath = join(projectRoot, 'runs', String(runId), 'manifest.json');
+    if (!existsSync(runManifestPath)) {
+      fail(
+        'run_manifest_link',
+        'BROKEN_RUN_MANIFEST_LINK',
+        `Run manifest runs/${runId}/manifest.json not found for record "${recordId}"`,
+      );
+    } else {
+      try {
+        runManifest = JSON.parse(readFileSync(runManifestPath, 'utf-8'));
+        const manifestWfSha = runManifest?.pinning?.comfy_workflow_sha ?? null;
+        if (!manifestWfSha || manifestWfSha !== recWorkflowSha) {
+          fail(
+            'run_manifest_link',
+            'BROKEN_RUN_MANIFEST_LINK',
+            `Record "${recordId}" comfy_workflow_sha (${recWorkflowSha}) does not match runs/${runId}/manifest.json (${manifestWfSha})`,
+          );
+        }
+      } catch (err) {
+        fail(
+          'run_manifest_link',
+          'BROKEN_RUN_MANIFEST_LINK',
+          `Run manifest runs/${runId}/manifest.json could not be parsed: ${err.message}`,
+        );
+      }
+    }
+  }
+
+  const assetPath = record?.asset_path ?? record?.image_path ?? null;
+  if (!isSafeRelativeAssetPath(projectRoot, assetPath) || !existsSync(join(projectRoot, assetPath))) {
+    fail(
+      'run_manifest_link',
+      'BROKEN_RUN_MANIFEST_LINK',
+      `Record "${recordId}" asset_path (${assetPath}) does not exist inside the project`,
+    );
+  }
+
+  // 4. G4: Model and LoRA licences and sha256 digests
+  const pinning = runManifest?.pinning ?? record?.provenance?.pinning ?? null;
+  const modelEntries = Object.entries(pinning?.models || {}).map(([role, entry]) => ({ role, ...entry }));
+  const loraEntries = (pinning?.loras || []).map((entry, idx) => ({ role: `lora[${idx}]`, ...entry }));
+  const allWeightEntries = [...modelEntries, ...loraEntries];
+
+  const recModelLicences =
+    record?.generation_provenance?.model_licences ?? genProv?.model_licences ?? null;
+  const recModelEntries = recModelLicences
+    ? Object.entries(recModelLicences.models || {}).map(([role, entry]) => ({
+        role: `generation_provenance.model_licences.models.${role}`,
+        ...entry,
+      }))
+    : [];
+  const recLoraEntries = recModelLicences
+    ? (recModelLicences.loras || []).map((entry, idx) => ({
+        role: `generation_provenance.model_licences.loras[${idx}]`,
+        ...entry,
+      }))
+    : [];
+  const allCheckedEntries = [...allWeightEntries, ...recModelEntries, ...recLoraEntries];
+
+  if (!pinning || allWeightEntries.length === 0) {
+    fail(
+      'model_licences',
+      'UNLICENSED_OR_EXCLUDED_MODEL',
+      `Record "${recordId}" has no pinned model weights to verify licences against`,
+    );
+  } else {
+    const missingShaWeights = allCheckedEntries.filter((entry) => !hasModelSha256(entry));
+    if (
+      record?.generation_provenance &&
+      (!recModelLicences || recModelEntries.length < modelEntries.length || recLoraEntries.length < loraEntries.length)
+    ) {
+      missingShaWeights.push({
+        role: 'generation_provenance.model_licences',
+        name: '<missing>',
+      });
+    }
+    if (missingShaWeights.length > 0) {
+      const shaDesc = missingShaWeights
+        .map((w) => `${w.role}:${w.name || '<unnamed>'}`)
+        .join(', ');
+      fail(
+        'model_licences',
+        'MISSING_MODEL_SHA256',
+        `Record "${recordId}" is missing a non-empty sha256 for model/LoRA weights: ${shaDesc}`,
+      );
+    }
+
+    const invalidLicenceWeights = allCheckedEntries.filter(
+      (entry) => !isClearedLicenceEntry(entry, { requireSha256: false }),
+    );
+    if (
+      invalidLicenceWeights.length > 0 ||
+      (missingShaWeights.length === 0 &&
+        (pinning.cc_by_4_eligible === false || recModelLicences?.cc_by_4_eligible === false))
+    ) {
+      const desc = invalidLicenceWeights
+        .map((w) => `${w.role}:${w.name || '<unnamed>'}(licence=${w.licence_id || 'missing'})`)
+        .join(', ');
+      fail(
+        'model_licences',
+        'UNLICENSED_OR_EXCLUDED_MODEL',
+        `Record "${recordId}" uses unlicensed or excluded model/LoRA weights: ${desc || 'cc_by_4_eligible=false'}`,
+      );
+    }
+  }
+
+  // 5. §2.2.5: Quarantine guard (no held Portlight data / plsvessel / nano-banana)
+  const serializedChain = JSON.stringify({ record, runManifest });
+  if (isQuarantinedName(serializedChain)) {
+    fail(
+      'quarantine_guard',
+      'QUARANTINED_SOURCE_REFERENCED',
+      `Record "${recordId}" or its run manifest references quarantined/held data (plsvessel / nano-banana)`,
+    );
+  }
+
+  // 6. §2.2.6 / §12.5: Verdict separation (judge family != generator family on approved records)
+  if (record?.judgment && record.judgment.status === 'approved') {
+    const judge = record.judgment.judged_by_model || record.judgment.reviewed_by || null;
+    const generator =
+      record.judgment.generator_model ||
+      (pinning?.models?.unet?.name ? `qwen-image:${pinning.models.unet.name}` : null);
+    const judgeFamily = normalizeModelFamilyKey(judge);
+    const generatorFamily = normalizeModelFamilyKey(generator);
+    const sameFamily =
+      Boolean(judgeFamily && generatorFamily) &&
+      judgeFamily !== 'human' &&
+      judgeFamily !== 'rule-based' &&
+      judgeFamily === generatorFamily;
+    if (!judge || (generator && (judge === generator || sameFamily))) {
+      fail(
+        'verdict_separation',
+        'INVALID_VERDICT_PROVENANCE',
+        `Record "${recordId}" has an invalid approval verdict (judge=${judge} [${judgeFamily || 'none'}], generator=${generator} [${generatorFamily || 'none'}])`,
+      );
+    }
+  }
+
+  return {
+    record_id: recordId,
+    ok: failures.length === 0,
+    links,
+    failures,
+  };
+}
+
+/**
+ * Verify the provenance chain across a project (or a single record / snapshot).
+ */
+export async function verifyProvenanceChain(
+  projectRoot,
+  { recordId = null, snapshotId = null, allowEmpty = false } = {},
+) {
+  const recordsDir = join(projectRoot, 'records');
+  const recordsToCheck = [];
+  const globalFailures = [];
+
+  if (recordId) {
+    const recPath = join(recordsDir, `${recordId}.json`);
+    if (!existsSync(recPath)) {
+      globalFailures.push({
+        record_id: recordId,
+        link: 'scope',
+        code: 'RECORD_NOT_FOUND',
+        message: `Record "${recordId}" not found at records/${recordId}.json`,
+      });
+    } else {
+      recordsToCheck.push(JSON.parse(readFileSync(recPath, 'utf-8')));
+    }
+  } else if (snapshotId) {
+    const incPath = join(projectRoot, 'snapshots', snapshotId, 'included.jsonl');
+    if (!existsSync(incPath)) {
+      globalFailures.push({
+        record_id: null,
+        link: 'scope',
+        code: 'SNAPSHOT_NOT_FOUND',
+        message: `Snapshot "${snapshotId}" included.jsonl not found`,
+      });
+    } else {
+      const lines = readFileSync(incPath, 'utf-8')
+        .split('\n')
+        .filter((l) => l.trim())
+        .map((l) => JSON.parse(l));
+      for (const item of lines) {
+        const rid = item.record_id || item.id;
+        const recPath = join(recordsDir, `${rid}.json`);
+        if (!existsSync(recPath)) {
+          globalFailures.push({
+            record_id: rid,
+            link: 'scope',
+            code: 'RECORD_NOT_FOUND',
+            message: `Snapshot record "${rid}" not found at records/${rid}.json`,
+          });
+        } else {
+          recordsToCheck.push(JSON.parse(readFileSync(recPath, 'utf-8')));
+        }
+      }
+    }
+  } else if (existsSync(recordsDir)) {
+    const files = readdirSync(recordsDir)
+      .filter((f) => f.endsWith('.json'))
+      .sort();
+    for (const file of files) {
+      recordsToCheck.push(JSON.parse(readFileSync(join(recordsDir, file), 'utf-8')));
+    }
+  }
+
+  if (recordsToCheck.length === 0 && globalFailures.length === 0 && !allowEmpty) {
+    globalFailures.push({
+      record_id: null,
+      link: 'scope',
+      code: 'NO_RECORDS_IN_SCOPE',
+      message: 'No records found in scope to verify',
+    });
+  }
+
+  const results = [];
+  const failures = [...globalFailures];
+
+  for (const rec of recordsToCheck) {
+    const res = verifyRecordProvenance(projectRoot, rec);
+    results.push(res);
+    failures.push(...res.failures);
+  }
+
+  const passedCount = results.filter((r) => r.ok).length;
+  const failedCount = results.length - passedCount;
+
+  return {
+    ok: failures.length === 0,
+    project_root: projectRoot,
+    records_checked: results.length,
+    passed_count: passedCount,
+    failed_count: failedCount,
+    results,
+    failures,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/style-dataset-lab",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Canon-aligned dataset production and generation workbench — define visual rules, build versioned training data, compile production briefs, run local workflows, batch-produce, select winners, and re-ingest into your corpus",
   "type": "module",
   "bin": {
@@ -82,7 +82,7 @@
   "author": "mcp-tool-shop",
   "license": "MIT",
   "devDependencies": {
-    "c8": "^10.1.3"
+    "c8": "^12.0.0"
   },
   "dependencies": {
     "yaml": "^2.8.3"

package/scripts/asset-ingest.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * asset-ingest.js — `sdlab asset ingest <dir>`: register a provenance-carrying
+ * asset export (asset-source.json + renders + masks + channels) into a
+ * project, through the full contract of lib/asset-source.js and the
+ * receiving-dock gates of lib/asset-ingest.js.
+ *
+ * The manifest-driven, gated sibling of `sdlab ingest` (which takes bare
+ * images with no contract). See docs/asset-lane-design.md.
+ *
+ * PATH NOTE (deliberate deviation from resolveSafeProjectPath): the export
+ * directory is allowed to live OUTSIDE the sdlab workspace — asset exports
+ * live where the asset pipeline puts them (e.g. a training area on another
+ * part of the disk). The source is READ-ONLY here; every path the manifest
+ * references is contained to the export directory by lib/asset-source.js,
+ * and every WRITE stays inside the project. Containment where it protects,
+ * reach where the user explicitly points.
+ *
+ * Usage:
+ *   sdlab asset ingest <dir> --project <name>
+ *   sdlab asset ingest <dir> --project <name> --dry-run
+ *   sdlab asset ingest <dir> --project <name> --json
+ */
+
+import { resolve } from 'node:path';
+import { parseArgs, getProjectName } from '../lib/args.js';
+import { getProjectRoot } from '../lib/paths.js';
+import { inputError, handleCliError } from '../lib/errors.js';
+import { ingestAssetSource } from '../lib/asset-ingest.js';
+import { result } from '../lib/log.js';
+
+const USAGE = `Usage: sdlab asset ingest <dir> --project <name> [--dry-run] [--json]
+
+Validate an asset export's asset-source.json (schema, containment, encoding
+proofs, categorical palette proofs, the acceptance verdict) and register its
+renders as candidate records. Refuses loudly on any contract violation —
+nothing registers on a bad manifest.
+
+Positional:
+  dir                  Asset export directory containing asset-source.json.
+                       May live outside the workspace (read-only source).
+
+Flags:
+  --project <name>     Project to register into
+  --dry-run            Validate + run gates + report the plan; write nothing
+  --json               Emit the result as JSON on stdout
+
+What lands on success:
+  records/<asset>__<render>.json     uncurated records (judgment: null),
+                                     provenance.source: "asset", hashes,
+                                     camera/facing, gate measurements
+  outputs/candidates/<asset>__<render>.png
+  assets/<asset>/                    manifest copy, silhouettes, channel
+                                     instances, pairs, ingest-receipt.json
+                                     (the receipt lists every written path —
+                                     it is the undo checklist)
+
+Next steps after ingesting:
+  1. Review: sdlab curate <id> approved/rejected "explanation"
+  2. Bind:   sdlab bind --project <name>`;
+
+export async function run(argv = process.argv.slice(2)) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(USAGE);
+    return;
+  }
+
+  const { flags, positionals } = parseArgs(argv, {
+    flags: {
+      project: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+    deprecated: { game: 'project' },
+  });
+
+  const dirArg = positionals[0];
+  if (!dirArg) {
+    throw inputError('INPUT_MISSING_ARGS', 'An asset export directory is required.', USAGE);
+  }
+
+  const projectName = flags.project || getProjectName(argv);
+  const projectRoot = getProjectRoot(projectName);
+  const dryRun = flags['dry-run'] || flags.dryRun;
+  const sourceDir = resolve(dirArg);
+
+  if (!flags.json) {
+    console.log(`\x1b[1msdlab asset ingest\x1b[0m — ${projectName}`);
+    console.log(`  Source: ${sourceDir}`);
+    if (dryRun) console.log(`  Mode:   DRY RUN (no files written)`);
+    console.log('');
+  }
+
+  const report = await ingestAssetSource(projectRoot, sourceDir, { dryRun });
+
+  if (flags.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (report.alreadyIngested) {
+    console.log(`  ○ Asset "${report.assetId}" is already ingested (same manifest hash) — nothing to do.`);
+    console.log(`    Receipt: ${report.receiptPath}`);
+    return;
+  }
+
+  console.log(`  \x1b[32m✓\x1b[0m Registered: ${report.created.length} render record(s)${dryRun ? ' (dry run — nothing written)' : ''}`);
+  for (const id of report.created) {
+    const gate = report.gates[id];
+    console.log(`    ✓ ${id}  (off-palette ${gate.offpalette_pct}%${gate.withdrawn_pct_bound ? ' [diagnostic]' : ''}, blob ${gate.largest_blob_px}px)`);
+  }
+
+  if (report.skipped.length > 0) {
+    console.log(`  Skipped: ${report.skipped.length} (already registered by this ingest)`);
+    for (const id of report.skipped) console.log(`    ○ ${id}`);
+  }
+
+  if (report.rejected.length > 0) {
+    console.log(`  \x1b[33m⚠\x1b[0m Rejected by the asset's own palette gate: ${report.rejected.length}`);
+    for (const r of report.rejected) {
+      const d = r.gate.dominant;
+      console.log(`    ✗ ${r.render_id}: blob ${r.gate.largest_blob_px}px (limit ${'≤'} manifest gate)` +
+        (d ? ` — dominant hue ${d.hue_lo}-${d.hue_hi}°, median C* ${d.median_chroma}, rgb(${d.median_rgb})` : ''));
+    }
+  }
+
+  // Provenance notices — what the manifest left undeclared. Not failures:
+  // the ingest succeeded. These are facts about the training data that only
+  // the manifest could have supplied, printed so they are not discovered
+  // later by a split or a training run that quietly assumed them.
+  if (report.notices?.length > 0) {
+    const gaps = report.notices.filter((n) => n.kind === 'gap');
+    const infos = report.notices.filter((n) => n.kind !== 'gap');
+    console.log('');
+    console.log(`  \x1b[36mProvenance notices\x1b[0m (${report.notices.length}) — the ingest SUCCEEDED; these describe the records it created:`);
+    if (gaps.length > 0) {
+      console.log(`  \x1b[33m  gaps\x1b[0m (${gaps.length}) — declarations the manifest did not make; closing them is export-side work:`);
+      for (const n of gaps) console.log(`    • [${n.code}] ${n.message}`);
+    }
+    if (infos.length > 0) {
+      console.log(`    info (${infos.length}) — declarations it DID make that change how these records read:`);
+      for (const n of infos) console.log(`    • [${n.code}] ${n.message}`);
+    }
+  }
+
+  if (!dryRun && report.created.length > 0) {
+    console.log('');
+    result(`Receipt: ${report.receiptPath}`);
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. Review: sdlab curate <id> approved/rejected "explanation"');
+    console.log('    2. Bind:   sdlab bind --project ' + projectName);
+  }
+}
+
+// Direct execution guard
+if (process.argv[1] && (process.argv[1].endsWith('asset-ingest.js') || process.argv[1].endsWith('asset-ingest'))) {
+  run().catch(handleCliError);
+}

package/scripts/canon-draft.js

@@ -0,0 +1,82 @@
+/**
+ * `sdlab canon draft <class_id> --endpoint <url> --brief "<text>" --out <path>`
+ *
+ * CLI wrapper for the Lane 2 canon and prompt authoring adapter (DESIGN-v3 §3.2,
+ * §11, G10). Calls a loopback-only OpenAI-compatible server (e.g., llama-server
+ * serving Muse-Glimmer-30B-A3B under Apache-2.0) and writes `prompts.jsonl`
+ * (+ `prompts.jsonl.sha256`) with `status: "draft"` and `judgment: null`.
+ */
+
+import { parseArgs } from 'node:util';
+import {
+  draftCanonClassViaEndpoint,
+  verifyGlimmerRuntime,
+  writePromptsJsonl,
+} from '../lib/canon-author.js';
+import { inputError } from '../lib/errors.js';
+import { assertKnownOptions } from './_shared-args.js';
+
+export async function run(argv) {
+  const options = {
+    endpoint:    { type: 'string', default: 'http://127.0.0.1:8080/v1/chat/completions' },
+    brief:       { type: 'string' },
+    out:         { type: 'string' },
+    build:       { type: 'string', default: 'b10353' },
+    vision:      { type: 'boolean', default: false },
+    mmproj:      { type: 'string' },
+    'mmproj-sha': { type: 'string' },
+    json:        { type: 'boolean', default: false },
+  };
+  const parsed = parseArgs({
+    args: argv,
+    options,
+    allowPositionals: true,
+    strict: false,
+  });
+  assertKnownOptions(parsed.values, options, { command: 'canon draft' });
+
+  const classId = parsed.positionals?.[0];
+  if (!classId) {
+    throw inputError(
+      'INPUT_MISSING_ARG',
+      'sdlab canon draft requires a <class_id> positional argument.'
+    );
+  }
+  if (!parsed.values.brief) {
+    throw inputError(
+      'INPUT_MISSING_FLAG',
+      'sdlab canon draft requires --brief "<description>".'
+    );
+  }
+
+  verifyGlimmerRuntime({
+    llamaServerBuild: parsed.values.build,
+    vision: Boolean(parsed.values.vision),
+    mmprojPath: parsed.values.mmproj || null,
+    mmprojSha256: parsed.values['mmproj-sha'] || null,
+    verifyFiles: false,
+  });
+
+  const draft = await draftCanonClassViaEndpoint({
+    endpoint: parsed.values.endpoint,
+    classId,
+    brief: parsed.values.brief,
+  });
+
+  let written = null;
+  if (parsed.values.out) {
+    written = writePromptsJsonl(parsed.values.out, [draft]);
+  }
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify({ ok: true, draft, written }, null, 2));
+    return;
+  }
+
+  console.log(`drafted "${classId}" (status=${draft.status}, judgment=${draft.judgment})`);
+  console.log(`  draft_sha256:    ${draft.draft_sha256}`);
+  console.log(`  messages_sha256: ${draft.messages_sha256}`);
+  if (written) {
+    console.log(`  prompts.jsonl:   ${written.promptsPath} (${written.sha256})`);
+  }
+}

package/scripts/canon-freeze.js

@@ -17,6 +17,7 @@ import { loadBuildConfig } from '../lib/canon-build/load-config.js';
 import { loadCanonEntriesInDir, entryId } from '../lib/canon-build/load-entry.js';
 import { buildFreezeBlock, FREEZE_STATUSES, resolveWatchFields } from '../lib/freeze-stamp.js';
 import { appendEvent } from '../lib/freeze-events.js';
+import { assertDirectorRatifiedForFreeze } from '../lib/canon-review-gate.js';
 import { inputError } from '../lib/errors.js';
 import { getProjectRoot } from '../lib/paths.js';
 import { assertKnownOptions } from './_shared-args.js';
@@ -102,6 +103,9 @@ export async function run(argv) {
     );
   }
 
+  // G11: Refuse to freeze a model-drafted canon entry unless explicitly ratified by the Director
+  assertDirectorRatifiedForFreeze(resolved.entry.frontmatter);
+
   // Resolve the witness build hash
   const lockedAtBuild = parsed.values.build || await findLatestBuildHash(projectRoot);
   if (!lockedAtBuild) {

package/scripts/colab/REAL_SERVICE_ASSUMPTIONS.md

@@ -0,0 +1,14 @@
+# Real-Service Assumption Audit (`scripts/colab/colab_window.sh`, `scripts/colab/launch_lane1_stub.sh`, `scripts/colab/launch_lane3_stub.sh`, `scripts/colab/remote_runner.py`, & `scripts/colab/launch_guards.py`)
+
+This document audits every interaction the style-dataset-lab Colab kits (`scripts/colab/colab_window.sh`, `scripts/colab/launch_lane1_stub.sh`, `scripts/colab/launch_lane3_stub.sh`, `scripts/colab/remote_runner.py`, and `scripts/colab/launch_guards.py`) have with the `colab` CLI (`google-colab-cli` v0.7.4, captured in `tests/colab/fixtures/colab_help.txt` and `tests/colab/fixtures/colab-cli-contract.json`) and the remote Colab IPython runtime.
+
+| # | Subcommand / Area | Help Line Relied On (`tests/colab/fixtures/colab_help.txt`) | Where Code Calls / Relies On It (`path:line`) | Fake Enforcement (`tests/colab/fixtures/fake_colab.py`) |
+|---:|---|---|---|---|
+| 1 | `usage` (text format, balance, and burn rate) | `Usage: colab usage [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:143`); live output lines `Current balance: <float> compute units`, `Usage rate: <float>/hr` (or `/h`), `Active assignments: <int>`. | `scripts/colab/colab_window.sh:43-128`, `scripts/colab/launch_guards.py:122-177`, `scripts/colab/launch_guards.py:180-217`, `scripts/colab/launch_lane1_stub.sh:109`, `scripts/colab/launch_lane3_stub.sh:110` | **Enforced** (`tests/colab/fixtures/fake_colab.py:390-416`): rejects any positionals or unknown flags; prints the 3-line text format; supports `usage_fail_start`, `usage_fail_midrun`, and `cap_burn` modes. `launch_guards.py:122-177` parses with anchored regexes (`CURRENT_BALANCE_RE`, `USAGE_RATE_RE`), removes any `10.0` fallback, records `null` plus `usage_parse_error` in `window.json`, and refuses/stops with `COLAB_USAGE_PARSE_FAILED` (including before `colab new` if the initial read fails). |
+| 2 | `new` (session open under lock) | `Usage: colab new [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:54`); options `--session -s <str>`, `--gpu <str>`, `--high-mem` (`tests/colab/fixtures/colab_help.txt:59-67`). | `scripts/colab/colab_window.sh:292-327`, `scripts/colab/launch_lane1_stub.sh:125-126`, `scripts/colab/launch_lane3_stub.sh:126-127` | **Enforced** (`tests/colab/fixtures/fake_colab.py:424-441`): validates options against `colab-cli-contract.json`, rejects any positional arguments, requires `-s/--session`, and records whether `/tmp/colab-window-open.lock` was held. |
+| 3 | `upload` (stage scripts and overrides to `/content/`) | `Usage: colab upload [OPTIONS] {local_path} {remote_path}` (`tests/colab/fixtures/colab_help.txt:95`); option `--session -s <str>` (`tests/colab/fixtures/colab_help.txt:104`). | `scripts/colab/launch_lane1_stub.sh:248-250`, `scripts/colab/launch_lane3_stub.sh:308-310` | **Enforced** (`tests/colab/fixtures/fake_colab.py:443-467`): requires `-s/--session` and exactly 2 positional arguments (`{local_path}` `{remote_path}`), verifies the local file exists and `{remote_path}` starts with `/content/`, and copies the file into the fake `/content` directory. |
+| 4 | `exec` (execute local `.py` file via `-f` with `--timeout` and `--env`) | `Usage: colab exec [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:80`); options `--session -s <str>`, `--file -f <str>`, `--timeout <float>`, `--env <str>` (`KEY=VALUE`, repeatable), `--output-image <str>` (`tests/colab/fixtures/colab_help.txt:85-90`). | `scripts/colab/colab_window.sh:181-282`, `scripts/colab/remote_runner.py:16-47`, `scripts/colab/launch_lane1_stub.sh:252-260`, `scripts/colab/launch_lane3_stub.sh:312-319` | **Enforced** (`tests/colab/fixtures/fake_colab.py:368-373` & `498-563`): refuses any positional command (`expected 0 positional arguments`), requires `-s/--session` and an existing `.py` file for `-f/--file`, validates `--timeout > 0` and `--env KEY=VALUE`, strips rig `PINNED_*` / `SDLAB_*` variables so only `--env` values reach the remote kernel, and executes the `.py` source with `cwd` set to the fake `/content` directory and `__file__` undefined. |
+| 5 | `exec` (unreliable CLI exit code; marker and bundle verification) | Inside `colab exec -f`, `__file__` is undefined, `cwd` is `/content`, and the CLI exit code is not reliable on remote exceptions or `sys.exit`. | `scripts/colab/remote_runner.py:30-46`, `scripts/colab/colab_window.sh:259-272`, `scripts/colab/launch_lane1_stub.sh:263-267`, `scripts/colab/launch_lane3_stub.sh:322-326` | **Enforced** (`tests/colab/fixtures/fake_colab.py:559-561`): `FAKE_COLAB_FORCE_EXEC_RC_ZERO` defaults to `"1"` (returning `0` from `colab exec` even when the remote script exits non-zero), so `colab_window.sh` and the kits decide success strictly from the streamed `SDLAB_REMOTE_RC=<rc>` marker line and the downloaded non-empty result bundle. |
+| 6 | `download` (fetch result bundle from `/content/` to rig) | `Usage: colab download [OPTIONS] {remote_path} {local_path}` (`tests/colab/fixtures/colab_help.txt:109`); option `--session -s <str>` (`tests/colab/fixtures/colab_help.txt:118`). | `scripts/colab/launch_lane1_stub.sh:263`, `scripts/colab/launch_lane3_stub.sh:322` | **Enforced** (`tests/colab/fixtures/fake_colab.py:469-486`): requires `-s/--session` and exactly 2 positional arguments (`{remote_path}` `{local_path}`), verifies `{remote_path}` is under `/content/`, and copies the artifact to `{local_path}`. |
+| 7 | `stop` (close session in `EXIT` trap) | `Usage: colab stop [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:123`); option `--session -s <str>` (`tests/colab/fixtures/colab_help.txt:128`). | `scripts/colab/colab_window.sh:284-290`, `scripts/colab/launch_lane1_stub.sh:93`, `scripts/colab/launch_lane3_stub.sh:94` | **Enforced** (`tests/colab/fixtures/fake_colab.py:488-496`): rejects any positional arguments, requires `-s/--session`, and logs `STOP -s <session>` to `stops.log`. |
+| 8 | `sessions` (verify active sessions after stop) | `Usage: colab sessions [OPTIONS]` (`tests/colab/fixtures/colab_help.txt:71`); options `--help -h` (`tests/colab/fixtures/colab_help.txt:76`). | `scripts/colab/colab_window.sh:288` | **Enforced** (`tests/colab/fixtures/fake_colab.py:418-422`): rejects any positional arguments or unknown options and prints `[colab] No active sessions found on server.`. |