@mcptoolshop/style-dataset-lab 3.1.0 → 3.3.0

package/lib/freeze-events.js

@@ -0,0 +1,109 @@
+/**
+ * Append-only event log for freeze transitions (D4).
+ *
+ * Lives at `<project>/canon-build/freeze-events.jsonl`. One line per event,
+ * JSON, stable key order. The jsonl is the audit source of truth; the
+ * `freeze.overrides[]` denormalization on the entry is a glance cache.
+ *
+ * Atomic append: we write the new event as a line-append operation at the
+ * OS level. Node's `appendFile` is atomic per-line on POSIX but not
+ * guaranteed on Windows when two processes race. For single-operator
+ * workflow this is fine; for a paranoid hardening pass later we can add
+ * a lockfile. Documented as a known hazard.
+ */
+
+import { readFile, appendFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+
+export const FREEZE_EVENT_TYPES = Object.freeze(['freeze', 'unfreeze', 'override', 'bypass']);
+
+export function eventsPath(projectRoot) {
+  return join(projectRoot, 'canon-build', 'freeze-events.jsonl');
+}
+
+/**
+ * Append one event to the log. Creates the parent dir + file on first write.
+ *
+ * @param {string} projectRoot — absolute path to the sdlab project root
+ * @param {Object} event — at minimum: {type, entity_id, by, reason}
+ */
+export async function appendEvent(projectRoot, event) {
+  if (!FREEZE_EVENT_TYPES.includes(event.type)) {
+    throw new Error(`appendEvent: unknown event type "${event.type}" (allowed: ${FREEZE_EVENT_TYPES.join(', ')})`);
+  }
+  if (!event.entity_id) throw new Error('appendEvent: entity_id required');
+  if (!event.by) throw new Error('appendEvent: by required');
+  if (!event.reason) throw new Error('appendEvent: reason required');
+
+  const path = eventsPath(projectRoot);
+  await mkdir(dirname(path), { recursive: true });
+
+  // Serialize with a stable key order so `diff`-style reading stays readable.
+  const ordered = {
+    at: event.at || new Date().toISOString(),
+    build_hash: event.build_hash ?? null,
+    type: event.type,
+    entity_id: event.entity_id,
+    schema_kind: event.schema_kind ?? null,
+    by: event.by,
+    reason: event.reason,
+    prior_status: event.prior_status ?? null,
+    new_status: event.new_status ?? null,
+    watch_fields: event.watch_fields ?? null,
+    prior_build_hash: event.prior_build_hash ?? null,
+  };
+
+  await appendFile(path, JSON.stringify(ordered) + '\n', 'utf-8');
+  return ordered;
+}
+
+/**
+ * Read all events from the log, in append order.
+ */
+export async function readEvents(projectRoot) {
+  const path = eventsPath(projectRoot);
+  if (!existsSync(path)) return [];
+  const text = await readFile(path, 'utf-8');
+  const events = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch (err) {
+      throw new Error(`readEvents: line ${i + 1} of ${path} is not valid JSON (${err.message})`);
+    }
+  }
+  return events;
+}
+
+/**
+ * Return events for a specific entity, in append order.
+ */
+export async function readEventsFor(projectRoot, entityId) {
+  const all = await readEvents(projectRoot);
+  return all.filter((e) => e.entity_id === entityId);
+}
+
+/**
+ * Return events newer than a given build_hash. Used by `sdlab canon drift`
+ * to compute "overrides since last build."
+ *
+ * Semantics: events are "since X" when their `build_hash` field differs
+ * from X. Since the log is append-only, that approximates temporal ordering.
+ */
+export async function readEventsSince(projectRoot, buildHash) {
+  if (!buildHash) return readEvents(projectRoot);
+  const all = await readEvents(projectRoot);
+  // Find last event with matching build_hash; return everything after it.
+  let cutoff = -1;
+  for (let i = all.length - 1; i >= 0; i--) {
+    if (all[i].build_hash === buildHash) {
+      cutoff = i;
+      break;
+    }
+  }
+  return cutoff < 0 ? all : all.slice(cutoff + 1);
+}

package/lib/freeze-gate.js

@@ -0,0 +1,208 @@
+/**
+ * Freeze enforcement gate (D3).
+ *
+ * Called from CLI commands before any write to a canon-bound asset or record.
+ * Semantics:
+ *   - frozen         → block outright (CANON_ENTRY_FROZEN)
+ *   - soft-advisory  → block unless --i-know + --reason; on override, append
+ *                      a 'bypass' event to freeze-events.jsonl and proceed
+ *   - auto           → no block
+ *   - on-canon-change → no block at write time; canon-build surfaces drift
+ *                      in its summary output (enforcement lives at the build
+ *                      boundary, not the CLI boundary, because drift is a
+ *                      build-observable condition)
+ *
+ * The canon reverse-map helpers resolve an action's identifier (subject id,
+ * asset path) to a canon entry so the gate can look up its freeze state.
+ * Actions without a canon binding (prompt-pack-driven generate, reingest of
+ * un-bound generated outputs) skip the gate naturally: no entry = nothing
+ * to protect.
+ */
+
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadBuildConfig } from './canon-build/load-config.js';
+import { loadCanonEntriesInDir, entryId } from './canon-build/load-entry.js';
+import { readFreezeStatus } from './freeze-stamp.js';
+import { appendEvent, readEventsFor } from './freeze-events.js';
+import { inputError } from './errors.js';
+
+/**
+ * Best-effort freeze date for an entry: the `at` of its most recent freeze /
+ * override event. Returns null when the log is absent/unreadable (the freeze
+ * block itself carries no timestamp). Used only to enrich the contrastive
+ * refuse message — never load-bearing for the gate decision.
+ */
+async function latestFreezeAt(projectRoot, id) {
+  try {
+    const events = await readEventsFor(projectRoot, id);
+    for (let i = events.length - 1; i >= 0; i--) {
+      if (events[i].type === 'freeze' || events[i].type === 'override') return events[i].at;
+    }
+  } catch { /* no log / unreadable → no date */ }
+  return null;
+}
+
+/**
+ * Contrastive lead (Horvitz CHI 1999): state the DEFAULT action and the system's
+ * reasoning — who froze it, when, and why — before the override path. This is the
+ * "you probably expected to just regenerate; I'm refusing, here's why" framing.
+ */
+function contrastiveLead(id, status, freeze, frozenAt) {
+  const by = freeze?.frozen_by || 'unknown';
+  const reason = freeze?.frozen_reason || '(no reason recorded)';
+  const when = frozenAt ? ` on ${String(frozenAt).slice(0, 10)}` : '';
+  return `Default: REFUSE — "${id}" is ${status} frozen by ${by}${when}, reason: "${reason}".`;
+}
+
+/** Render the watched-field list for the contrastive override condition. */
+function watchList(freeze) {
+  const w = freeze?.watch_fields || [];
+  return w.length ? `[${w.join(', ')}]` : '[no watched fields]';
+}
+
+/**
+ * Load every canon entry in a project, keyed by schema.
+ *
+ * Returns a flat array of `{ entry, schemaName }` objects.
+ * Returns [] (no-op) when the project has no canon-build config — meaning
+ * the project isn't canon-integrated yet, so the gate has nothing to enforce.
+ */
+export async function loadAllCanonEntries(projectRoot) {
+  const configPath = join(projectRoot, 'canon-build', 'config.json');
+  if (!existsSync(configPath)) return [];
+  let config;
+  try {
+    config = await loadBuildConfig(configPath, projectRoot);
+  } catch {
+    // Invalid config → degrade to "no gate" rather than blocking every write.
+    // The operator will hit the config error on `sdlab canon build`.
+    return [];
+  }
+  const entries = [];
+  for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
+    const dir = join(config.canon_root, subdir);
+    const loaded = await loadCanonEntriesInDir(dir);
+    for (const entry of loaded) {
+      entries.push({ entry, schemaName });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Find the canon entry whose `id` matches the given subject identifier.
+ * Returns { entry, schemaName } or null.
+ */
+export async function resolveEntryBySubject(projectRoot, subjectId) {
+  if (!subjectId) return null;
+  const all = await loadAllCanonEntries(projectRoot);
+  const hit = all.find(({ entry }) => entryId(entry) === subjectId);
+  return hit || null;
+}
+
+/**
+ * Find the canon entry whose `visual.reference_plate_uri` (or top-level
+ * `reference_plate_uri`, for monsters) equals the given asset path.
+ * Returns { entry, schemaName } or null.
+ */
+export async function resolveEntryByAssetPath(projectRoot, assetPath) {
+  if (!assetPath) return null;
+  const all = await loadAllCanonEntries(projectRoot);
+  const normalized = assetPath.replace(/\\/g, '/');
+  const hit = all.find(({ entry }) => {
+    const fm = entry.frontmatter;
+    const plate = (fm.visual?.reference_plate_uri || fm.reference_plate_uri || '').replace(/\\/g, '/');
+    return plate && plate === normalized;
+  });
+  return hit || null;
+}
+
+/**
+ * Core gate. Throws CANON_ENTRY_FROZEN on block; on soft-advisory bypass,
+ * appends a 'bypass' event and returns without throwing.
+ *
+ * @param {Object} args
+ * @param {string} args.projectRoot
+ * @param {Object|null} args.resolved — { entry, schemaName } or null
+ * @param {string} args.action — short verb for error context ("generate", "painterly", "curate", ...)
+ * @param {boolean} [args.allowSoftAdvisoryBypass] — the command supports --i-know
+ * @param {string} [args.bypassReason] — value of --reason when bypassing
+ * @param {string} [args.by] — who is invoking (default 'mike')
+ */
+export async function assertNotFrozen({
+  projectRoot,
+  resolved,
+  action,
+  allowSoftAdvisoryBypass = false,
+  bypassReason = null,
+  by = 'mike',
+}) {
+  if (!resolved || !resolved.entry) return; // nothing canon-bound; no gate
+  const fm = resolved.entry.frontmatter;
+  const status = readFreezeStatus(fm);
+  const id = entryId(resolved.entry);
+
+  // Contrastive refuse messaging (Horvitz CHI 1999): lead with the default
+  // action + the system's reasoning (who/when/why) pulled from the freeze
+  // stamp, then state the override path and its condition (don't touch the
+  // watched fields). frozenAt is best-effort from the event log.
+  if (status === 'frozen' || status === 'soft-advisory') {
+    const frozenAt = await latestFreezeAt(projectRoot, id);
+    const lead = contrastiveLead(id, status, fm.freeze, frozenAt);
+    const watched = watchList(fm.freeze);
+
+    if (status === 'frozen') {
+      throw inputError(
+        'CANON_ENTRY_FROZEN',
+        `${lead} A hard freeze has no inline bypass, so "${action}" will not proceed.`,
+        `Unfreeze with: sdlab canon unfreeze ${id} --reason "<why>" (appended to canon-build/freeze-events.jsonl as an audit record). This freeze watches ${watched}.`,
+      );
+    }
+
+    // soft-advisory
+    if (!allowSoftAdvisoryBypass) {
+      throw inputError(
+        'CANON_ENTRY_FROZEN',
+        `${lead} "${action}" has no --i-know bypass.`,
+        `Run: sdlab canon unfreeze ${id} --reason "<why>" for a proper unfreeze, or pick a command that accepts --i-know. Watched fields: ${watched}.`,
+      );
+    }
+    if (!bypassReason) {
+      throw inputError(
+        'CANON_ENTRY_FROZEN',
+        `${lead} Override requires --i-know AND --reason.`,
+        `Re-run with --i-know --reason "<why>" ONLY if your change does not touch the watched fields ${watched}. The bypass is logged to canon-build/freeze-events.jsonl.`,
+      );
+    }
+    // Bypass allowed — log and proceed.
+    await appendEvent(projectRoot, {
+      type: 'bypass',
+      entity_id: id,
+      schema_kind: resolved.schemaName?.replace('.schema.json', ''),
+      by,
+      reason: bypassReason,
+      prior_status: 'soft-advisory',
+      new_status: 'soft-advisory',
+    });
+    return;
+  }
+
+  // auto and on-canon-change: no write-side block.
+}
+
+/**
+ * Convenience wrapper: resolve by subject id, then gate.
+ */
+export async function assertNotFrozenBySubject(projectRoot, subjectId, options = {}) {
+  const resolved = await resolveEntryBySubject(projectRoot, subjectId);
+  return assertNotFrozen({ projectRoot, resolved, ...options });
+}
+
+/**
+ * Convenience wrapper: resolve by asset_path, then gate.
+ */
+export async function assertNotFrozenByAssetPath(projectRoot, assetPath, options = {}) {
+  const resolved = await resolveEntryByAssetPath(projectRoot, assetPath);
+  return assertNotFrozen({ projectRoot, resolved, ...options });
+}

package/lib/freeze-stamp.js

@@ -0,0 +1,161 @@
+/**
+ * Freeze block helpers — read/write the `freeze` block on a canon entry,
+ * compute watch-field hashes for the witness chain (D1).
+ *
+ * The `freeze` block (schema v2.0.0+) is the sole freeze surface on canon
+ * entries; the legacy `visual_locked_at` + `regen_policy` fields have been
+ * removed per post-research D10. See
+ * memory/freeze-tooling-research-2026-04-24.md for the full contract.
+ */
+
+import { createHash } from 'node:crypto';
+import { getByPath } from './canon-build/load-config.js';
+
+/**
+ * The four legal freeze statuses. Entries without a `freeze` block behave
+ * as `auto` (permissive default — see post-research D8).
+ */
+export const FREEZE_STATUSES = Object.freeze(['auto', 'frozen', 'soft-advisory', 'on-canon-change']);
+
+/**
+ * Read the normalized freeze status for an entry frontmatter.
+ * Missing block / missing status / invalid value all collapse to `auto`.
+ */
+export function readFreezeStatus(frontmatter) {
+  const status = frontmatter?.freeze?.status;
+  if (typeof status !== 'string') return 'auto';
+  if (!FREEZE_STATUSES.includes(status)) return 'auto';
+  return status;
+}
+
+/**
+ * Whether an entry's freeze status blocks a regen-like action outright.
+ * `frozen` blocks. `soft-advisory` blocks unless the caller overrides via
+ * --i-know + --reason. `auto` / `on-canon-change` do not block.
+ */
+export function freezeBlocksAction(status) {
+  return status === 'frozen';
+}
+
+/**
+ * Whether an entry's freeze status warrants a soft-advisory bypass path.
+ */
+export function freezeIsAdvisory(status) {
+  return status === 'soft-advisory';
+}
+
+/**
+ * Stable canonical JSON serialization for an object used as hash input.
+ *
+ * Sorts object keys; arrays preserve order (arrays are meaningful sequences).
+ * Normalizes `undefined` → omitted. Bit-stability matters because the witness
+ * chain compares hashes across builds — the same semantic value must hash
+ * identically regardless of key insertion order or JSON formatting drift.
+ */
+export function canonicalize(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'null';
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalize).join(',') + ']';
+  }
+  if (typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const k of keys) {
+      if (value[k] === undefined) continue;
+      parts.push(JSON.stringify(k) + ':' + canonicalize(value[k]));
+    }
+    return '{' + parts.join(',') + '}';
+  }
+  return 'null';
+}
+
+/**
+ * Compute the watch-hash for an entry given its frontmatter, the list of
+ * watched fields, and the schema version.
+ *
+ * The hash is sha256 of a canonical JSON representation of the watched
+ * field values + the schema version. Any change to a watched field, or a
+ * schema version bump, invalidates the hash.
+ *
+ * @param {Object} frontmatter — entry frontmatter object
+ * @param {Array<string>} watchFields — dotted paths (e.g. "visual.silhouette_cue")
+ * @param {string} schemaVersion — schema `version` string
+ * @returns {string} 64-char hex sha256 digest
+ */
+export function computeWatchHash(frontmatter, watchFields, schemaVersion) {
+  const payload = {
+    schema_version: schemaVersion,
+    watched: {},
+  };
+  for (const field of watchFields) {
+    payload.watched[field] = getByPath(frontmatter, field) ?? null;
+  }
+  return createHash('sha256').update(canonicalize(payload)).digest('hex');
+}
+
+/**
+ * Resolve the effective watch-field list for an entry.
+ *
+ * Precedence (entry override wins over build-config default):
+ *   1. `frontmatter.freeze.watch_fields` if present + non-empty
+ *   2. `buildConfig.freeze_watch_defaults[schemaName]` if present
+ *   3. [] (empty — a freeze with no watch-fields stamps only the schema
+ *      version, useful for "freeze but don't drift-check" intent)
+ */
+export function resolveWatchFields(frontmatter, schemaName, buildConfig) {
+  const entryOverride = frontmatter?.freeze?.watch_fields;
+  if (Array.isArray(entryOverride) && entryOverride.length > 0) {
+    return entryOverride;
+  }
+  const defaults = buildConfig?.freeze_watch_defaults?.[schemaName];
+  if (Array.isArray(defaults) && defaults.length > 0) {
+    return defaults;
+  }
+  return [];
+}
+
+/**
+ * Build a fresh freeze block for writing to an entry (canon freeze command).
+ *
+ * @param {Object} args
+ * @param {string} args.status — 'frozen' | 'soft-advisory' | 'on-canon-change'
+ * @param {string} args.lockedAtBuild — generated_from of the witness build
+ * @param {string} [args.lockedAtCanonVersion]
+ * @param {string} args.frozenBy
+ * @param {string} args.frozenReason
+ * @param {Array<string>} [args.watchFields]
+ * @param {Array} [args.overrides] — existing override history (preserved on re-freeze)
+ */
+export function buildFreezeBlock({
+  status,
+  lockedAtBuild,
+  lockedAtCanonVersion,
+  frozenBy,
+  frozenReason,
+  watchFields,
+  overrides,
+}) {
+  const block = { status };
+  if (lockedAtBuild) block.locked_at_build = lockedAtBuild;
+  if (lockedAtCanonVersion) block.locked_at_canon_version = lockedAtCanonVersion;
+  if (frozenBy) block.frozen_by = frozenBy;
+  if (frozenReason) block.frozen_reason = frozenReason;
+  if (Array.isArray(watchFields) && watchFields.length) block.watch_fields = watchFields;
+  if (Array.isArray(overrides) && overrides.length) block.overrides = overrides;
+  return block;
+}
+
+/**
+ * Append an override record to an entry's freeze.overrides[] list.
+ * Denormalizes the event into the entry for glance-reading; the authoritative
+ * source of truth is the append-only log at canon-build/freeze-events.jsonl.
+ */
+export function appendOverrideToFreezeBlock(freeze, override) {
+  const next = { ...freeze };
+  next.overrides = Array.isArray(freeze?.overrides) ? [...freeze.overrides, override] : [override];
+  return next;
+}