@gregiteen/ssss-cli 0.7.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@gregiteen/ssss-cli",
+  "version": "0.7.0",
+  "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
+  "main": "src/engine.mjs",
+  "exports": {
+    ".": "./src/engine.mjs",
+    "./engine": "./src/engine.mjs",
+    "./runtime": "./src/runtime.mjs",
+    "./registry": "./src/registry.mjs",
+    "./frontmatter": "./src/frontmatter.mjs",
+    "./bundle": "./src/bundle.mjs",
+    "./conformance/fixtures.json": "./conformance/fixtures.json",
+    "./conformance/reference-bundle.ucw.json": "./conformance/reference-bundle.ucw.json",
+    "./registry/core.json": "./registry/core.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "ssss": "./scripts/ssss.mjs"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "registry",
+    "conformance",
+    "docs/ssss-spec.md",
+    "docs/help",
+    "VERSION",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "conformance": "node ./scripts/conformance.mjs conformance",
+    "test": "node ./scripts/conformance.mjs conformance --engine"
+  },
+  "keywords": [
+    "ssss",
+    "agent",
+    "okf",
+    "markdown",
+    "vault",
+    "operation-contract",
+    "ucw",
+    "provisioning"
+  ],
+  "author": "Greg Iteen",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gregiteen/ssss.git"
+  },
+  "homepage": "https://github.com/gregiteen/ssss#readme",
+  "bugs": {
+    "url": "https://github.com/gregiteen/ssss/issues"
+  },
+  "dependencies": {}
+}

package/registry/core.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "https://ssss.dev/registry/v1",
+  "registry": "core",
+  "spec_version": "0.6",
+  "description": "The canonical SSSS core primitive registry. These 14 document primitives and 5 contract primitives are defined by the SSSS specification (docs/ssss-spec.md §5) and are owned by this standard. Every document primitive declares a portability class (§5.5); the registry also defines the workflow runtime contract (§11.8), the `.ucw` bundle format (§16), and the provisioning contract (§17). A conformant host MUST implement any core primitive it uses according to this registry. Applications extend the core with their own primitives via an extension registry (see registry/README.md); extensions MUST NOT redefine a core type.",
+  "conformance": "A host is core-conformant for a primitive if a file of that type validates exactly when all required_fields are present and non-empty, and (for append_only types) writes only append.",
+
+  "document_primitives": {
+    "memory": {
+      "family": "knowledge",
+      "canonical_filename": null,
+      "filename_convention": "kebab-case slug matching the `slug` field",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "slug", "category", "title", "status", "schema_version"],
+      "required_when": {
+        "schema_version==2": ["confidence", "importance", "modality", "subject", "predicate", "object", "sentiment_polarity"]
+      },
+      "enums": {
+        "category": ["invariants", "patterns", "anti-patterns", "preferences", "decisions", "concepts", "facts", "lore"],
+        "modality": ["must", "must_not", "should", "should_not", "descriptive", "preference"],
+        "sentiment_polarity": ["directive_must", "directive_must_not", "descriptive", "preference"],
+        "priority": ["absolute", "high", "normal", "low"]
+      },
+      "spec_ref": "§5.4 memory"
+    },
+    "skill": {
+      "family": "capability",
+      "canonical_filename": "SKILL.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name", "description"],
+      "notes": "Compatible with the open Agent Skills standard (name + description). The `type: skill` discriminator is REQUIRED for SSSS-managed manifests.",
+      "spec_ref": "§5.4 skill"
+    },
+    "rule": {
+      "family": "governance",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name"],
+      "optional_fields": ["description", "scope"],
+      "spec_ref": "§5.4 rule"
+    },
+    "security_role": {
+      "family": "governance",
+      "canonical_filename": "ROLE.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name", "permissions"],
+      "optional_fields": ["description"],
+      "spec_ref": "§5.4 security_role"
+    },
+    "task": {
+      "family": "work",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type", "priority", "category", "status"],
+      "optional_fields": ["workflow_id", "workflow_path", "trigger_id", "trigger_type", "trigger_event_id", "scheduled_for", "dedupe_key", "claim_id", "claimed_by", "claimed_at", "attempts", "next_attempt_at"],
+      "enums": { "status": ["pending", "in_progress", "done", "failed"] },
+      "spec_ref": "§5.4 task"
+    },
+    "assistant": {
+      "family": "actor",
+      "canonical_filename": "ASSISTANT.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name"],
+      "spec_ref": "§5.4 assistant"
+    },
+    "workflow": {
+      "family": "work",
+      "canonical_filename": "WORKFLOW.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name"],
+      "optional_fields": ["workflow_id", "slug", "description", "triggers", "isActive", "priority", "misfire_policy", "concurrency"],
+      "spec_ref": "§5.4 workflow"
+    },
+    "model": {
+      "family": "catalog",
+      "canonical_filename": "MODEL.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "model_id", "provider"],
+      "spec_ref": "§5.4 model"
+    },
+    "conversation": {
+      "family": "transcript",
+      "canonical_filename": "CONVERSATION.md",
+      "append_only": true,
+      "portability": "tenant_private",
+      "required_fields": ["type", "thread_id"],
+      "spec_ref": "§5.4 conversation"
+    },
+    "run": {
+      "family": "transcript",
+      "canonical_filename": "RUN.md",
+      "append_only": true,
+      "portability": "tenant_private",
+      "required_fields": ["type", "run_id", "workflow_id"],
+      "optional_fields": ["task_id", "task_path", "workspace_id", "status", "step_count", "started_at", "ended_at", "claimed_by", "provenance"],
+      "enums": { "status": ["queued", "claimed", "running", "waiting_for_human", "succeeded", "failed", "canceled", "retrying", "dead_letter"] },
+      "spec_ref": "§5.4 run"
+    },
+    "conflict": {
+      "family": "meta",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type", "conflict_id", "status", "new_slug", "existing_slug", "detected_at"],
+      "enums": { "status": ["pending", "resolved"] },
+      "spec_ref": "§5.4 conflict"
+    },
+    "page": {
+      "family": "capability",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "slug", "name", "sandbox_entry"],
+      "spec_ref": "§5.4 page"
+    },
+    "migration": {
+      "family": "meta",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "migration_id", "from_version", "to_version", "status", "description"],
+      "spec_ref": "§5.4 migration"
+    },
+    "release": {
+      "family": "meta",
+      "canonical_filename": null,
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "release_id", "version", "schema_version", "summary", "released_at"],
+      "spec_ref": "§5.4 release"
+    }
+  },
+
+  "contract_primitives": {
+    "operation": { "purpose": "Full atomic file write (create or full replace).", "spec_ref": "§6" },
+    "patch": { "purpose": "Partial merge into an existing file.", "spec_ref": "§6" },
+    "event": { "purpose": "Append-only immutable log entry.", "spec_ref": "§6, §8" },
+    "delete": { "purpose": "Tombstoning removal of a replace-type file; rejects append-type targets; emits a deletion event.", "spec_ref": "§6.2" },
+    "lease": { "purpose": "A file-level write lock.", "spec_ref": "§7" }
+  },
+
+  "universal_frontmatter": {
+    "required": ["type", "title", "description", "timestamp"],
+    "recommended_okf": ["resource", "tags", "aliases"],
+    "spec_ref": "§4.2"
+  },
+
+  "portability": {
+    "description": "Every document primitive declares a portability class. The class governs whether a primitive may leave the workspace in a given export profile (§5.5). Contract primitives (operation/patch/event/lease) are protocol envelopes, not stored documents, and carry no portability. A file MAY override its type's default class with an `x_portability` frontmatter field; a host MUST honor the most restrictive of (type default, instance override).",
+    "classes": {
+      "structural": "The reusable business model — sellable and templatable. Carries no operator- or customer-specific data. Examples: workflow, assistant, page, skill, model, rule, memory, migration, release.",
+      "tenant_private": "The operator's private operational data — customers, transcripts, runtime work. NEVER leaves the workspace in a template or sale bundle; included only in an encrypted backup. Examples: conversation, run, task, conflict, and (via extension) profile / CRM contact / deal.",
+      "resource_bound": "Requires a real external resource bound at provision time (a domain, phone number, mailbox, API connection). NEVER ships the seller's resource value; ships only a requirement declaration the buyer satisfies. Defined by extension registries (e.g. festech domain / phone_number / integration_connection)."
+    },
+    "export_profiles": {
+      "backup": { "includes": ["structural", "tenant_private", "resource_bound"], "note": "Complete fidelity copy. tenant_private MUST be encrypted at rest." },
+      "template": { "includes": ["structural"], "resource_bound": "requirement_declaration_only", "excludes": ["tenant_private"] },
+      "sale": { "includes": ["structural"], "resource_bound": "requirement_declaration_only", "excludes": ["tenant_private"] }
+    },
+    "conformance": "A host MUST resolve every primitive's portability class from this registry (type default, overridable by `x_portability`). An exporter MUST drop every `tenant_private` primitive from a `template` or `sale` bundle, and MUST reduce every `resource_bound` primitive to a requirement declaration (stripping the seller's bound value) in those profiles. A host MUST reject a `template`/`sale` export that would emit a `tenant_private` primitive.",
+    "spec_ref": "§5.5"
+  },
+
+  "bundle": {
+    "description": "The `.ucw` bundle format (§16): a transportable package of a vault's files plus a manifest declaring what they are and what they need to run. Produced by an export under an export profile (§5.5), consumed by provision/import (§17).",
+    "container": "package.ucw.json",
+    "structure": ["manifest", "branding", "files"],
+    "file_sort": "files MUST be sorted by path (byte order) so equal vault state yields a byte-identical, content-hashable bundle.",
+    "manifest_required_fields": ["name", "description", "version", "exported_at", "ssss_core_version", "required_extensions", "export_profile", "primitive_inventory", "provisioning", "file_count", "provenance"],
+    "manifest_optional_fields": ["parameters", "source_workspace_id", "branding"],
+    "provenance_required_fields": ["content_hash", "exporter"],
+    "provenance_optional_fields": ["signature"],
+    "content_hash": "sha256 over the canonical (path-sorted) serialization of files; importer MUST recompute and reject on mismatch.",
+    "parameter_fields": {
+      "required": ["key", "label", "type", "scope", "source"],
+      "optional": ["required", "description", "defaultValue", "options", "dependsOn"],
+      "source_enum": ["user", "llm", "graph", "system"],
+      "note": "Adopted verbatim from ultrachat WorkspaceTemplateVariableDefinition; resource_bound requirements ship as parameters of source user/system."
+    },
+    "conformance": "A host MUST refuse a bundle whose `ssss_core_version` it does not support or that names a `required_extensions` entry it has not loaded. An exporter MUST NOT emit a file whose resolved portability class is excluded by `export_profile`. `primitive_inventory` MUST count every file by its registry `type`.",
+    "spec_ref": "§16"
+  },
+
+  "provisioning": {
+    "description": "The provisioning contract (§17): the deterministic, idempotent verbs that move a bundle between vaults — export, provision, import.",
+    "verbs": {
+      "export": "vault + profile → bundle. Pure: equal vault state and profile yield a byte-identical bundle.",
+      "provision": "bundle + parameters + target → ordered, replayable plan of Operation Contract envelopes plus resource bindings. Supports dry_run.",
+      "import": "plan + target → replay envelopes through the engine (§6.3); idempotent via each envelope's idempotency_key."
+    },
+    "step_required_fields": ["id", "label", "system", "mode", "required"],
+    "step_optional_fields": ["notes"],
+    "system_enum": ["workspace", "branding", "email", "phone", "domains", "accounts", "deployments", "marketplace", "tabs", "automation"],
+    "mode_enum": ["existing", "provision", "install", "generate", "configure"],
+    "edge_relations": ["uses_brand", "owns_domain", "routes_calls_to", "deploys_to", "has_surface", "contains_page", "installs_pack", "authenticates_account", "runs_workflow", "connects_to"],
+    "install_modes": ["optional", "recommended", "required"],
+    "id_remap": "Provision remaps slugs/workspace ids/links into the target; every internal link that resolved in the source MUST resolve post-import or the provision MUST fail.",
+    "upgrade": "Version steps run through a `migration` primitive plus structural-only `patch` envelopes; MUST NOT touch tenant_private data.",
+    "conformance": "import MUST be idempotent (re-run is a no-op via idempotency_key). A step's `mode` and `system` MUST be drawn from the enums above. Each `resource_bound` primitive (§5.5) declares its binding edge relation.",
+    "spec_ref": "§17"
+  },
+
+  "runtime": {
+    "description": "Workflow runtime contract (§11.8). A daemon, cron bridge, webhook worker, or agent host reads workflow triggers from the vault and derives Operation Contract envelopes. Scheduler queues, task dashboards, and cursor indexes are projections; the canonical schedule remains workflow frontmatter and the canonical history remains the event log.",
+    "trigger_types": ["manual", "cron", "interval", "event", "webhook", "file_change", "condition"],
+    "misfire_policies": ["skip", "run_once", "catch_up"],
+    "concurrency_policies": ["allow_parallel", "skip_if_running", "enqueue", "replace"],
+    "task_instantiation_fields": ["workflow_id", "workflow_path", "trigger_id", "trigger_type", "trigger_event_id", "scheduled_for", "dedupe_key"],
+    "run_statuses": ["queued", "claimed", "running", "waiting_for_human", "succeeded", "failed", "canceled", "retrying", "dead_letter"],
+    "idempotency_basis": "workspace_id + workflow_id + trigger_id + scheduled_for",
+    "spec_ref": "§11.8"
+  },
+
+  "reserved_keys": ["type", "slug", "schema_version", "status", "feedback", "confidence"],
+  "host_field_prefix": "x_",
+  "spec_ref_reserved": "Appendix A"
+}

package/registry/extensions/festech.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://ssss.dev/registry/v1",
+  "registry": "festech",
+  "extends": "core",
+  "spec_version": "0.3",
+  "description": "Festech extension registry. Defines the host-specific primitives that festech.live layers on top of the SSSS core (registry/core.json). Lifted from festech's docs/ssss/primitive-registry.json and assigned a portability class (§5.5) so a festech workspace can be exported as a backup/template/sale bundle. Core primitives (assistant, workflow, rule, security_role, skill, model, memory, task, conversation, run, conflict, page, migration, release) are NOT redefined here — they are governed by core.json. An extension MUST NOT redefine a core type.",
+  "conformance": "A festech-conformant host MUST resolve portability for these primitives from this registry. The `resource_bound` primitives MUST ship only a requirement declaration (never the seller's bound value) in a template/sale export; the `tenant_private` primitives MUST be dropped from template/sale entirely (§5.5).",
+
+  "document_primitives": {
+    "domain": {
+      "family": "resource",
+      "canonical_path": "domains/<domain>.md",
+      "append_only": false,
+      "portability": "resource_bound",
+      "resource": { "kind": "domain", "binds": ["domain_name", "registrar"], "provision_relation": "owns_domain" },
+      "required_fields": ["type", "domain_name", "registrar", "status", "payment_status"],
+      "notes": "The seller's domain is NEVER transferred. In template/sale the bundle declares 'this business needs a domain'; the buyer binds their own at provision (§16)."
+    },
+    "phone_number": {
+      "family": "resource",
+      "canonical_path": "telephony/PHONE_SYSTEM.md",
+      "append_only": false,
+      "portability": "resource_bound",
+      "resource": { "kind": "phone", "binds": ["phone_number", "provider"], "provision_relation": "routes_calls_to" },
+      "required_fields": ["type", "phone_number", "provider", "status"]
+    },
+    "integration_connection": {
+      "family": "resource",
+      "canonical_path": "integrations/<provider>.md",
+      "append_only": false,
+      "portability": "resource_bound",
+      "resource": { "kind": "api_connection", "binds": ["provider"], "provision_relation": "connects_to" },
+      "required_fields": ["type", "provider", "status", "capabilities", "verified_at"],
+      "notes": "Carries credentials/tokens to a third-party provider — the seller's connection value MUST be stripped; the buyer supplies their own at provision."
+    },
+    "legal_policy": {
+      "family": "governance",
+      "canonical_path": "contracts/<id>.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "title", "version", "effective_date", "policy_type"]
+    },
+    "extension": {
+      "family": "capability",
+      "canonical_path": "extensions/<id>.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "extension", "display_name", "status"],
+      "notes": "Which extensions a workspace has installed is part of the business model and ships in a sale."
+    },
+    "media_asset": {
+      "family": "asset",
+      "canonical_path": "media/assets/<asset-id>.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "asset_id", "asset_type", "url"],
+      "notes": "Brand/marketing assets are structural. An asset holding customer-uploaded content SHOULD override with x_portability: tenant_private."
+    },
+    "language_convention": {
+      "family": "localization",
+      "canonical_path": "languages/<locale>/CONVENTION.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "locale", "language_name", "keys"]
+    },
+    "knowledge": {
+      "family": "knowledge",
+      "canonical_path": "knowledge/<slug>.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "name", "slug"],
+      "notes": "The curated knowledge base is a core sellable asset of the business model."
+    },
+    "knowledge_source": {
+      "family": "knowledge",
+      "canonical_path": "knowledge/<knowledge-slug>/sources/<slug>.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type", "title", "knowledge_base_slug"],
+      "notes": "A source backing a structural knowledge base. A source ingesting private customer documents SHOULD override with x_portability: tenant_private."
+    },
+    "onboarding_state": {
+      "family": "runtime",
+      "canonical_path": "onboarding_state.md",
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type", "state_version", "collective_id", "completed_steps", "deferred_steps", "dismissed"]
+    },
+    "profile": {
+      "family": "actor",
+      "canonical_path": "PROFILE.md",
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type", "user_id", "locale"]
+    },
+    "personalization": {
+      "family": "actor",
+      "canonical_path": "PERSONALIZATION.md",
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type"]
+    },
+    "model-preferences": {
+      "family": "actor",
+      "canonical_path": "models/preferences/MODEL-PREFERENCES.md",
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type", "user_id", "workspace_id"]
+    },
+    "sharing_group": {
+      "family": "actor",
+      "canonical_path": "sharing-groups/<id>.md",
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type", "name", "color", "owner_user_id"]
+    },
+    "settings": {
+      "family": "config",
+      "canonical_path": "SETTINGS.md",
+      "append_only": false,
+      "portability": "structural",
+      "required_fields": ["type"],
+      "notes": "Workspace settings configure the business model (structural). Account-scoped settings SHOULD override with x_portability: tenant_private."
+    },
+    "system_settings": {
+      "family": "config",
+      "canonical_path": "SYSTEM_SETTINGS.md",
+      "append_only": false,
+      "portability": "tenant_private",
+      "required_fields": ["type"],
+      "notes": "Host/operator-level configuration; never transfers to a buyer."
+    }
+  }
+}

package/scripts/audit-registry-field-usage.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Registry-parity audit: proves every registry field the reference engine is
+ * supposed to enforce at write time is actually referenced in src/engine.mjs.
+ *
+ * Motivation: registry/core.json declared `required_when` and `enums` on the
+ * `memory` primitive for a full release cycle before src/engine.mjs's
+ * validateContent() ever read either one — a memory node could omit a
+ * conditionally-required field or use an out-of-enum value and still pass
+ * conformance. That gap was invisible to normal testing because nothing
+ * cross-checked "declared in the registry" against "consumed by the engine."
+ *
+ * This is deliberately a STATIC, deterministic check (grep the engine source
+ * for a reference to each enforcement-relevant key), not an LLM judgment
+ * call — the whole point is that this class of drift should never again
+ * require a human or an agent to notice it. Wired into every
+ * `ssss conformance` run (see scripts/conformance.mjs), not just an
+ * agent-invoked skill, so it can't silently regress by nobody remembering to
+ * ask.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REGISTRY_DIR = path.resolve(__dirname, '..', 'registry');
+// "The engine" for this audit's purposes is the write-time enforcement path:
+// src/engine.mjs itself plus src/registry.mjs, which engine.mjs delegates
+// type-resolution helpers to (e.g. `append_only` is actually read inside
+// registry.mjs's isAppendType(), not inlined in engine.mjs).
+const ENGINE_FILES = [
+  path.resolve(__dirname, '..', 'src', 'engine.mjs'),
+  path.resolve(__dirname, '..', 'src', 'registry.mjs'),
+];
+
+// Keys the reference engine is expected to enforce at write time (Stage 5,
+// spec §6.3 + §9). If a primitive declares one, the engine source MUST
+// reference it — otherwise the registry is making a promise the engine
+// doesn't keep.
+const ENGINE_ENFORCED_KEYS = ['required_fields', 'required_when', 'enums', 'append_only'];
+
+// Keys that are real and load-bearing but are intentionally consumed
+// elsewhere (export/bundle time, documentation, or the registry loader
+// itself), not by src/engine.mjs's write-time content validation. Extend
+// this list — with a comment saying WHERE the key is actually consumed —
+// rather than silencing a warning by deleting it.
+const KNOWN_NON_ENGINE_KEYS = new Set([
+  'family', 'canonical_filename', 'canonical_path', 'filename_convention', 'notes', 'spec_ref',
+  'optional_fields', 'type', 'registry',
+  'portability', // consumed by src/registry.mjs resolvePortability() + src/bundle.mjs export filtering, not write-time validation
+  'resource', // extension-defined resource_bound metadata, consumed by src/bundle.mjs provisioning
+]);
+
+function loadAllPrimitiveDefs() {
+  const defs = [];
+  const corePath = path.join(REGISTRY_DIR, 'core.json');
+  const core = JSON.parse(fs.readFileSync(corePath, 'utf8'));
+  for (const [name, def] of Object.entries(core.document_primitives || {})) {
+    defs.push({ name, def, source: 'core.json' });
+  }
+  const extDir = path.join(REGISTRY_DIR, 'extensions');
+  if (fs.existsSync(extDir)) {
+    for (const file of fs.readdirSync(extDir).filter((f) => f.endsWith('.json'))) {
+      const ext = JSON.parse(fs.readFileSync(path.join(extDir, file), 'utf8'));
+      for (const [name, def] of Object.entries(ext.document_primitives || {})) {
+        defs.push({ name, def, source: `extensions/${file}` });
+      }
+    }
+  }
+  return defs;
+}
+
+/** Does any engine-path source file reference `def.<key>` (or an equivalent literal access)? */
+function engineReferencesKey(engineSources, key) {
+  const patterns = [
+    new RegExp(`\\bdef\\.${key}\\b`),
+    new RegExp(`\\btypeDef\\.${key}\\b`),
+    new RegExp(`\\['${key}'\\]`),
+    new RegExp(`\\["${key}"\\]`),
+  ];
+  return engineSources.some((src) => patterns.some((re) => re.test(src)));
+}
+
+/**
+ * Returns an array of problem strings. Empty array = clean.
+ */
+export function auditRegistryFieldUsage() {
+  const problems = [];
+  const missing = ENGINE_FILES.filter((f) => !fs.existsSync(f));
+  if (missing.length) return missing.map((f) => `engine source not found at ${f}`);
+  const engineSources = ENGINE_FILES.map((f) => fs.readFileSync(f, 'utf8'));
+
+  const defs = loadAllPrimitiveDefs();
+  const keysSeen = new Set();
+  for (const { name, def, source } of defs) {
+    for (const key of Object.keys(def)) keysSeen.add(key);
+
+    for (const key of ENGINE_ENFORCED_KEYS) {
+      if (def[key] === undefined) continue;
+      if (!engineReferencesKey(engineSources, key)) {
+        problems.push(
+          `${source}: primitive "${name}" declares "${key}" but src/engine.mjs never references it — ` +
+          `the registry is promising enforcement the engine doesn't perform.`
+        );
+      }
+    }
+  }
+
+  // Flag any key the engine-enforced list and the known-elsewhere list both
+  // fail to account for — a new field was added and nobody classified it yet.
+  for (const key of keysSeen) {
+    if (ENGINE_ENFORCED_KEYS.includes(key) || KNOWN_NON_ENGINE_KEYS.has(key)) continue;
+    problems.push(
+      `unclassified registry key "${key}" — add it to ENGINE_ENFORCED_KEYS (if src/engine.mjs should ` +
+      `enforce it at write time) or KNOWN_NON_ENGINE_KEYS (with a comment on where it IS consumed) ` +
+      `in scripts/audit-registry-field-usage.mjs.`
+    );
+  }
+
+  return problems;
+}
+
+async function main() {
+  const problems = auditRegistryFieldUsage();
+  if (problems.length) {
+    console.error('❌ Registry/engine parity audit failed:');
+    for (const p of problems) console.error(`   • ${p}`);
+    process.exitCode = 1;
+  } else {
+    console.log('✅ Registry/engine parity: every enforcement-relevant registry key is referenced in src/engine.mjs.');
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}