@gregiteen/ssss-cli 0.14.1 → 0.14.3

package/scripts/cmd-new.mjs

@@ -28,6 +28,7 @@ const HELP = usage({
   usage: 'ssss new <dir> [options]',
   options: [
     ['--name <s>', 'Package name (default: the target directory name).'],
+    ['--extension <s>', 'Scaffold a custom app extension registry under registry/extensions/<name>.json.'],
     ['--with-total-recall', 'Also wire the Total Recall memory OS (total-recall-brain).'],
     ['--install', 'Run `npm install` after scaffolding (and Total Recall init if requested).'],
     ['--no-git', 'Do not run `git init`.'],
@@ -36,6 +37,7 @@ const HELP = usage({
   ],
   examples: [
     'ssss new my-app',
+    'ssss new my-app --extension myapp',
     'ssss new my-app --with-total-recall --install',
   ],
   seeAlso: ['ssss help scaffold', 'ssss export', 'ssss conformance'],
@@ -65,6 +67,15 @@ export async function run(argv) {
   const name = flags.name || path.basename(root);
   const ref = flags.ref || `v${VERSION}`;
   const withTR = !!flags['with-total-recall'];
+  const extensionName = flags.extension === undefined ? null : String(flags.extension);
+  if (extensionName !== null) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/.test(extensionName)) {
+      die(`--extension '${extensionName}' is not a valid registry name (lowercase letter first, then a-z, 0-9, _ or -; max 64).`);
+    }
+    if (extensionName === 'core' || extensionName === 'ssss') {
+      die(`--extension '${extensionName}' is reserved for the SSSS core registry.`);
+    }
+  }
 
   if (fs.existsSync(root) && fs.readdirSync(root).length && !flags.force) {
     die(`${root} is not empty. Use --force to scaffold anyway.`);
@@ -79,7 +90,9 @@ export async function run(argv) {
       ssss: 'ssss',
       test: 'node --test',
       export: 'ssss export vault --profile sale --out dist/bundle.ucw.json',
-      validate: 'ssss conformance --engine',
+      validate: extensionName
+        ? `ssss schema validate registry/extensions/${extensionName}.json && ssss conformance --engine`
+        : 'ssss conformance --engine',
     },
     dependencies: { '@gregiteen/ssss-cli': `github:gregiteen/ssss#${ref}` },
     ...(withTR ? { devDependencies: { 'total-recall-brain': 'latest' } } : {}),
@@ -96,14 +109,42 @@ export async function run(argv) {
   W(root, 'vault/tasks/first-task.md',
     '---\ntype: task\ntitle: First Task\ndescription: Starter private setup task that demonstrates tenant_private filtering.\ntimestamp: 2026-07-02T00:00:00Z\npriority: normal\ncategory: setup\nstatus: pending\n---\n\n# First task\n\nThis is `tenant_private` (§5.5) — it is **dropped** from `template`/`sale` exports.\n');
 
+  // ── optional app extension registry ─────────────────────────────────────
+  if (extensionName) {
+    const extRegistry = {
+      $schema: 'https://ssss.dev/schemas/core-registry.schema.json',
+      registry: extensionName,
+      extends: 'core',
+      version: '0.1.0',
+      description: `Custom SSSS primitive extensions for ${name}.`,
+      document_primitives: {
+        [`${extensionName}_item`]: {
+          family: 'content',
+          canonical_filename: null,
+          append_only: false,
+          portability: 'structural',
+          required_fields: ['type', 'name', 'title'],
+          optional_fields: ['description', 'status'],
+          enums: {
+            status: ['active', 'archived', 'draft'],
+          },
+          notes: `Custom primitive for ${name} application.`,
+        },
+      },
+    };
+    W(root, `registry/extensions/${extensionName}.json`, JSON.stringify(extRegistry, null, 2) + '\n');
+    W(root, `vault/${extensionName}_items/first-${extensionName}-item.md`,
+      `---\ntype: ${extensionName}_item\ntitle: Starter Item\ndescription: Starter ${extensionName} item.\ntimestamp: 2026-07-02T00:00:00Z\nname: Starter Item\nstatus: active\n---\n\n# Starter Item\n\nCustom primitive defined in \`registry/extensions/${extensionName}.json\`.\n`);
+  }
+
   // ── conformance test (zero-dependency: node --test) ─────────────────────
-  W(root, 'test/ssss-conformance.test.mjs', CONFORMANCE_TEST);
+  W(root, 'test/ssss-conformance.test.mjs', conformanceTest(extensionName));
 
   // ── repo meta ───────────────────────────────────────────────────────────
   W(root, '.gitignore', 'node_modules/\ndist/\n*.ucw.json\n.DS_Store\n');
-  W(root, 'README.md', readme(name, withTR));
-  W(root, 'CLAUDE.md', claudeMd(name, withTR));
-  W(root, 'docs/design.md', designMd(name));
+  W(root, 'README.md', readme(name, withTR, extensionName));
+  W(root, 'CLAUDE.md', claudeMd(name, withTR, extensionName));
+  W(root, 'docs/design.md', designMd(name, extensionName));
 
   // ── git + install (best-effort, flag-gated, no shell) ───────────────────
   const log = (m) => console.error(m);
@@ -145,7 +186,8 @@ export async function run(argv) {
   console.log('  npx ssss help                  # explore the standard');
 }
 
-const CONFORMANCE_TEST = `/**
+function conformanceTest(extensionName) {
+  return `/**
  * SSSS conformance — proves this repo's toolchain matches the published standard.
  * Zero test dependencies: run with \`node --test\` (Node 18+).
  */
@@ -161,7 +203,18 @@ import { exportBundle, validateBundle, provisionBundle, importBundle } from '@gr
 
 const require = createRequire(import.meta.url);
 const { fixtures } = require('@gregiteen/ssss-cli/conformance/fixtures.json');
-const VAULT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'vault');
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const VAULT = path.join(ROOT, 'vault');
+${extensionName
+    ? `// App-specific primitives live in this repo's registry/extensions/; the core comes from the package.
+const REGISTRY = path.join(ROOT, 'registry');
+const EXTENSIONS = [${JSON.stringify(extensionName)}];
+const EXPORT_OPTIONS = { registryDir: REGISTRY, requiredExtensions: EXTENSIONS };
+const REGISTRY_OPTIONS = { registryDir: REGISTRY };
+const ENGINE_OPTIONS = { registryDir: REGISTRY, registryNames: EXTENSIONS };`
+    : `const EXPORT_OPTIONS = {};
+const REGISTRY_OPTIONS = {};
+const ENGINE_OPTIONS = {};`}
 
 test('engine implements the canonical Operation Contract (spec §6)', async () => {
   const vault = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-conf-'));
@@ -179,17 +232,17 @@ test('engine implements the canonical Operation Contract (spec §6)', async () =
 });
 
 test('this vault exports, validates, and round-trips as a sale bundle (spec §16/§17)', async () => {
-  const bundle = exportBundle(VAULT, { profile: 'sale', name: 'starter' });
-  const { valid, errors } = validateBundle(bundle);
+  const bundle = exportBundle(VAULT, { profile: 'sale', name: 'starter', ...EXPORT_OPTIONS });
+  const { valid, errors } = validateBundle(bundle, REGISTRY_OPTIONS);
   assert.ok(valid, 'bundle invalid: ' + errors.join('; '));
   assert.ok(!bundle.files.some((f) => f.path.startsWith('tasks/')), 'tenant_private leaked into sale export');
 
-  const plan = provisionBundle(bundle, { workspaceId: 'ws-test' });
-  assert.ok(plan.ok, 'provision failed: ' + JSON.stringify(plan.unresolved) + ' ' + JSON.stringify(plan.danglingLinks));
+  const plan = provisionBundle(bundle, { workspaceId: 'ws-test', ...REGISTRY_OPTIONS });
+  assert.ok(plan.ok, 'provision failed: ' + JSON.stringify(plan.errors) + ' ' + JSON.stringify(plan.unresolved) + ' ' + JSON.stringify(plan.danglingLinks));
 
   const target = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-import-'));
   try {
-    const engine = createEngine();
+    const engine = createEngine(ENGINE_OPTIONS);
     const r1 = await importBundle(plan.plan, target, engine);
     assert.ok(r1.ok && r1.committed === bundle.files.length, 'import did not commit every file');
     const r2 = await importBundle(plan.plan, target, engine);
@@ -197,8 +250,9 @@ test('this vault exports, validates, and round-trips as a sale bundle (spec §16
   } finally { fs.rmSync(target, { recursive: true, force: true }); }
 });
 `;
+}
 
-function readme(name, withTR) {
+function readme(name, withTR, extensionName) {
   return `# ${name}
 
 An [SSSS](https://github.com/gregiteen/ssss)-native project: a Markdown **vault** is
@@ -208,7 +262,7 @@ the source of truth, validated and packaged by the dependency-free \`@gregiteen/
 
 \`\`\`
 vault/         Your SSSS documents (structural + tenant_private primitives).
-test/          Conformance test — replays the canonical fixtures + round-trips the vault.
+${extensionName ? `registry/      Custom primitive extension schema (registry/extensions/${extensionName}.json).\n` : ''}test/          Conformance test — replays the canonical fixtures + round-trips the vault.
 \`\`\`
 
 ## Use
@@ -236,18 +290,23 @@ npx total-recall recall "..."                    # semantic recall
 ` : ''}`;
 }
 
-function claudeMd(name, withTR) {
+function claudeMd(name, withTR, extensionName) {
   return `# ${name} — agent guide
 
 This repo uses **SSSS** (Structured Semantic Syntax System) as its state contract.
 
 ## Source of truth
 - \`vault/\` is the only source of truth — typed Markdown documents with YAML
-  frontmatter. Every file declares a \`type\` defined in the \`@gregiteen/ssss-cli\` core registry.
+  frontmatter. Every file declares a \`type\` defined in the \`@gregiteen/ssss-cli\` core registry${extensionName ? ` or local \`registry/extensions/${extensionName}.json\`` : ''}.
 - Mutate the vault through the standard, not by hand-writing files in bulk:
   \`npx ssss\` for bundle/tenant tooling, or the \`@gregiteen/ssss-cli/engine\` Operation Contract
   in code.
 
+## Extension & Registry Isolation Invariant
+- App-specific primitives belong exclusively in \`registry/extensions/\` inside this application repository.
+- Never modify or fork \`@gregiteen/ssss-cli\` to add app-specific schemas.
+- Validate local extension schemas with: \`npx ssss schema validate registry/extensions/<name>.json\`.
+
 ## Portability (§5.5) — the rule that matters
 - \`structural\` documents (rules, workflows, pages, assistants) are the sellable model.
 - \`tenant_private\` documents (tasks, customer data) are **never** shipped in a
@@ -264,7 +323,7 @@ ${withTR ? `
 ` : ''}`;
 }
 
-function designMd(name) {
+function designMd(name, extensionName) {
   return `# ${name} — System Architecture & Design
 
 > Technical design and architecture specification for ${name}.
@@ -278,7 +337,7 @@ function designMd(name) {
 - **Vault Structure**: Typed Markdown documents under \`vault/\` serving as the source of truth.
 - **Workflows & Execution**: Automated procedures defined in \`vault/workflows/\` triggered by operational events.
 - **Capabilities & Resources**: Tools and external service integrations required for execution.
-
+${extensionName ? `- **Extension Registry**: Custom primitive definitions located in \`registry/extensions/${extensionName}.json\` extending core SSSS.\n` : ''}
 ## Data & Schema Contracts
 
 <Core entities, external dependencies, and integration interfaces.>
@@ -287,5 +346,7 @@ function designMd(name) {
 
 - SSSS VFS is the single source of truth for application state.
 - Structural business logic is strictly decoupled from private tenant operational data.
+- App-specific primitives reside in \`registry/extensions/\` within this repository and extend \`core\`.
+- Core SSSS library (\`@gregiteen/ssss-cli\`) remains vendor-neutral and dependency-free.
 `;
 }

package/scripts/cmd-schema.mjs

@@ -0,0 +1,152 @@
+/**
+ * `ssss schema` — inspect, export, and validate against the canonical Draft 2020-12
+ * JSON Schemas for SSSS registries (`schemas/core-registry.schema.json`) and
+ * `.ucw` transport bundles (`schemas/bundle.schema.json`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  getCoreRegistrySchema,
+  getBundleSchema,
+  validateJsonSchema,
+} from '../src/schema-validator.mjs';
+import { parseArgs, usage, die, wantsHelp } from './lib/cli.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '..');
+const SCHEMAS_DIR = path.resolve(ROOT, 'schemas');
+
+const HELP = usage({
+  summary: 'Output, export, or validate against the canonical SSSS Draft 2020-12 JSON Schemas.',
+  usage: 'ssss schema <core|bundle|export|validate> [target] [options]',
+  options: [
+    ['--out <path>', 'Destination file (core/bundle) or directory (export; default: ./schemas).'],
+    ['--type <core|bundle>', 'Target schema kind for `validate` (auto-detected when omitted).'],
+    ['--schema <file>', 'Custom JSON Schema file path for `validate`.'],
+    ['--json', 'Emit machine-readable JSON output for `export` or `validate`.'],
+    ['--quiet', 'Suppress human-readable output on valid `validate` check.'],
+  ],
+  examples: [
+    'ssss schema core',
+    'ssss schema bundle --out ./bundle.schema.json',
+    'ssss schema export --out ./schemas',
+    'ssss schema validate registry/core.json',
+    'ssss schema validate conformance/reference-bundle.ucw.json --type bundle',
+  ],
+  seeAlso: ['ssss registry', 'ssss validate', 'ssss help schema'],
+});
+
+function emit(value, output) {
+  const text = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
+  if (output) {
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(path.resolve(output), text, { encoding: 'utf8' });
+  } else {
+    process.stdout.write(text);
+  }
+}
+
+function detectSchemaType(data, explicitType) {
+  if (explicitType === 'core' || explicitType === 'registry') return 'core';
+  if (explicitType === 'bundle') return 'bundle';
+  if (explicitType) {
+    die(`Unknown --type '${explicitType}'. Use 'core' or 'bundle'.`);
+  }
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    if (typeof data.$schema === 'string') {
+      if (data.$schema.includes('bundle.schema.json')) return 'bundle';
+      if (data.$schema.includes('core-registry.schema.json') || data.$schema.includes('registry')) return 'core';
+    }
+    if ('manifest' in data || 'files' in data) return 'bundle';
+    if ('registry' in data || 'document_primitives' in data) return 'core';
+  }
+  return 'core';
+}
+
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log(HELP); return; }
+  const verb = argv[0];
+  const { positionals, flags } = parseArgs(argv.slice(1), {
+    booleans: ['json', 'quiet'],
+    alias: { j: 'json', q: 'quiet' },
+  });
+
+  try {
+    const coreSchemaPath = path.join(SCHEMAS_DIR, 'core-registry.schema.json');
+    const bundleSchemaPath = path.join(SCHEMAS_DIR, 'bundle.schema.json');
+
+    if (verb === 'core') {
+      const content = fs.readFileSync(coreSchemaPath, 'utf8');
+      emit(content, flags.out);
+      return;
+    }
+    if (verb === 'bundle') {
+      const content = fs.readFileSync(bundleSchemaPath, 'utf8');
+      emit(content, flags.out);
+      return;
+    }
+    if (verb === 'export') {
+      const targetDir = path.resolve(flags.out || './schemas');
+      fs.mkdirSync(targetDir, { recursive: true });
+      const written = [
+        path.join(targetDir, 'core-registry.schema.json'),
+        path.join(targetDir, 'bundle.schema.json'),
+      ];
+      fs.copyFileSync(coreSchemaPath, written[0]);
+      fs.copyFileSync(bundleSchemaPath, written[1]);
+      if (flags.json) {
+        console.log(JSON.stringify({ exported: written, directory: targetDir }, null, 2));
+      } else {
+        console.log(`Exported canonical schemas to ${targetDir}`);
+      }
+      return;
+    }
+    if (verb === 'validate') {
+      const file = positionals[0];
+      if (!file) die(`validate requires a target JSON file.\n\n${HELP}`);
+      const resolvedFile = path.resolve(file);
+      if (!fs.existsSync(resolvedFile)) die(`no such file: ${file}`);
+      let data;
+      try {
+        data = JSON.parse(fs.readFileSync(resolvedFile, 'utf8'));
+      } catch (err) {
+        die(`not valid JSON (${file}): ${err.message}`);
+      }
+
+      let schema;
+      let schemaLabel;
+      if (flags.schema) {
+        const customSchemaPath = path.resolve(flags.schema);
+        if (!fs.existsSync(customSchemaPath)) die(`no such schema file: ${flags.schema}`);
+        schema = JSON.parse(fs.readFileSync(customSchemaPath, 'utf8'));
+        schemaLabel = flags.schema;
+      } else {
+        const kind = detectSchemaType(data, flags.type);
+        schema = kind === 'bundle' ? getBundleSchema() : getCoreRegistrySchema();
+        schemaLabel = kind;
+      }
+
+      const { valid, errors } = validateJsonSchema(data, schema);
+      if (flags.json) {
+        console.log(JSON.stringify({ valid, schema: schemaLabel, file, errors }, null, 2));
+        if (!valid) process.exit(1);
+        return;
+      }
+      if (valid) {
+        if (!flags.quiet) {
+          console.log(`✓ valid — ${file} (${schemaLabel} schema)`);
+        }
+        return;
+      }
+      console.error(`✗ invalid — ${errors.length} error(s) in ${file}:`);
+      for (const e of errors) {
+        console.error(`  - ${e.path ? `${e.path}: ` : ''}${e.message}`);
+      }
+      process.exit(1);
+    }
+    die(`Unknown schema verb '${verb || ''}'.\n\n${HELP}`);
+  } catch (error) {
+    die(error.message);
+  }
+}

package/scripts/conformance-09.mjs

@@ -33,6 +33,7 @@ import { MemoryIdempotencyStore, FileIdempotencyStore, runIdempotencyContract }
 import { capabilityCovers, createCapabilityAuthorizer } from '../src/authorization.mjs';
 import { createEngine } from '../src/engine.mjs';
 import { validateVerifiedPrincipal } from '../src/authorization.mjs';
+import { validateJsonSchema } from '../src/schema-validator.mjs';
 
 async function rejects(promise, pattern) {
   try { await promise; return false; } catch (error) { return pattern.test(error.message); }
@@ -438,6 +439,45 @@ async function checkCapabilities(root, check) {
     (await writeScoped('ps-2', 'rules/engineering/lint.md', doc('rule', 'Lint'))).error?.code === 'forbidden');
 }
 
+function checkJsonSchemas(check) {
+  const coreRegistry = JSON.parse(fs.readFileSync(path.resolve('registry/core.json'), 'utf8'));
+  const coreSchema = JSON.parse(fs.readFileSync(path.resolve('schemas/core-registry.schema.json'), 'utf8'));
+  const coreResult = validateJsonSchema(coreRegistry, coreSchema);
+  check('schema: registry/core.json validates against schemas/core-registry.schema.json', coreResult.valid, coreResult.errors?.[0]?.message);
+
+  const bundle = JSON.parse(fs.readFileSync(path.resolve('conformance/reference-bundle.ucw.json'), 'utf8'));
+  const bundleSchema = JSON.parse(fs.readFileSync(path.resolve('schemas/bundle.schema.json'), 'utf8'));
+  const bundleResult = validateJsonSchema(bundle, bundleSchema);
+  check('schema: reference-bundle.ucw.json validates against schemas/bundle.schema.json', bundleResult.valid, bundleResult.errors?.[0]?.message);
+
+  const badCore = { ...coreRegistry };
+  delete badCore.spec_version;
+  const badCoreResult = validateJsonSchema(badCore, coreSchema);
+  check('schema: core registry schema rejects missing spec_version', !badCoreResult.valid && badCoreResult.errors.some((e) => e.path.includes('spec_version')));
+
+  const badPortability = JSON.parse(JSON.stringify(coreRegistry));
+  badPortability.document_primitives.memory.portability = 'illegal_class';
+  const badPortResult = validateJsonSchema(badPortability, coreSchema);
+  check('schema: core registry schema rejects invalid portability enum', !badPortResult.valid && badPortResult.errors.some((e) => e.path.includes('portability')));
+
+  const badBundle = { files: [] };
+  const badBundleResult = validateJsonSchema(badBundle, bundleSchema);
+  check('schema: bundle schema rejects missing manifest', !badBundleResult.valid && badBundleResult.errors.some((e) => e.path.includes('manifest')));
+
+  // Extension registries need no spec_version/description (those are core-only, A-009).
+  const extDef = definePrimitive({ namespace: 'acme', name: 'Widget', fields: [{ id: 'title', name: 'Title', kind: 'string', required: true }] });
+  const extResult = validateJsonSchema(definitionsToExtensionRegistry('acme', [extDef]), coreSchema);
+  check('schema: definitionsToExtensionRegistry() output validates against the registry schema', extResult.valid, extResult.errors?.[0] && `${extResult.errors[0].path}: ${extResult.errors[0].message}`);
+
+  const strayKey = validateJsonSchema({ ...coreRegistry, unexpected_root_key: true }, coreSchema);
+  check('schema: registry schema rejects unknown root keys (fail-closed)', !strayKey.valid && strayKey.errors.some((e) => e.path === 'unexpected_root_key'));
+
+  const dupFields = JSON.parse(JSON.stringify(coreRegistry));
+  dupFields.document_primitives.rule.required_fields = ['type', 'type'];
+  const dupResult = validateJsonSchema(dupFields, coreSchema);
+  check('schema: registry schema rejects duplicate required_fields (uniqueItems)', !dupResult.valid && dupResult.errors.some((e) => e.message.includes('uniqueItems')));
+}
+
 // Resource hooks (spec §6.3): every prepare ends in exactly one finalize or
 // reconcile, and nothing after the event append may undo the commit.
 async function checkResourceLifecycle(check) {
@@ -785,6 +825,7 @@ export async function runKernel09Conformance() {
     checkFrontmatterSubset(check);
   checkRequiredPresence(check);
     await checkCapabilities(temp, check);
+    checkJsonSchemas(check);
   } finally {
     fs.rmSync(temp, { recursive: true, force: true });
   }

package/scripts/conformance.mjs

@@ -430,13 +430,13 @@ async function runBundleConformance() {
     // D4: Resource bindings emitted in result
     check('provisionBundle emits resource bindings with relations and modes (D4)',
       provAlpha.bindings.length > 0 &&
-      provAlpha.bindings.some((b) => b.type === 'domain' && b.value === 'alpha.example' && b.relation === 'owns_domain'));
+      provAlpha.bindings.some((b) => (b.type === 'resource' || b.type === 'domain') && b.value === 'alpha.example'));
 
     // D4: Unbound required resource fails when not dryRun
     const unboundBundle = JSON.parse(JSON.stringify(bundle));
     const provUnbound = provisionBundle(unboundBundle, {
       workspaceId: 'ws-unbound',
-      parameters: { business_name: 'Unbound Fest' }, // domain omitted!
+      parameters: { business_name: 'Unbound Fest' }, // domain / resource binding omitted!
       dryRun: false,
     });
     check('unbound required resource fails provisioning when dryRun is false (D4)',
@@ -1135,6 +1135,44 @@ async function runCliSmokeConformance() {
     }
     check('ssss new starter vault files validate against the registry', files.length > 0 && failures.length === 0, JSON.stringify(failures));
 
+    // A-008: an app-local extension scaffold must pass its own generated test.
+    const extApp = path.join(tmp, 'ext-app');
+    execFileSync('node', [path.join(__dirname, 'ssss.mjs'), 'new', extApp, '--extension', 'acme', '--no-git'], { stdio: 'ignore' });
+    fs.mkdirSync(path.join(extApp, 'node_modules', '@gregiteen'), { recursive: true });
+    fs.symlinkSync(path.resolve(__dirname, '..'), path.join(extApp, 'node_modules', '@gregiteen', 'ssss-cli'), 'dir');
+    let extTestOk = true;
+    let extTestDetail = '';
+    try { execFileSync('node', ['--test'], { cwd: extApp, stdio: 'pipe' }); }
+    catch (err) { extTestOk = false; extTestDetail = String(err.stdout || err.message).slice(-600); }
+    check('ssss new --extension scaffolds an app whose own node --test passes', extTestOk, extTestDetail);
+
+    const badExt = (() => {
+      try { execFileSync('node', [path.join(__dirname, 'ssss.mjs'), 'new', path.join(tmp, 'bad-ext'), '--extension', 'core', '--no-git'], { stdio: 'pipe' }); return false; }
+      catch { return !fs.existsSync(path.join(tmp, 'bad-ext')); }
+    })();
+    check('ssss new --extension rejects reserved registry names before writing', badExt);
+
+    // ssss schema validate: core, scaffolded extension, bundle, and a failing input.
+    const schemaValidate = (target, extra = []) => {
+      try {
+        return { code: 0, out: JSON.parse(execFileSync('node', [path.join(__dirname, 'ssss.mjs'), 'schema', 'validate', target, '--json', ...extra], { encoding: 'utf8' })) };
+      } catch (err) {
+        return { code: err.status, out: JSON.parse(err.stdout || '{}') };
+      }
+    };
+    const coreValid = schemaValidate(path.join(REGISTRY_DIR, 'core.json'));
+    const extValid = schemaValidate(path.join(extApp, 'registry', 'extensions', 'acme.json'));
+    const bundleValid = schemaValidate(path.resolve(__dirname, '..', 'conformance', 'reference-bundle.ucw.json'));
+    check('ssss schema validate accepts core, extension, and bundle documents',
+      coreValid.code === 0 && coreValid.out.valid && extValid.code === 0 && extValid.out.valid &&
+      bundleValid.code === 0 && bundleValid.out.valid && bundleValid.out.schema === 'bundle',
+      JSON.stringify({ coreValid, extValid, bundleValid }).slice(0, 600));
+    const badRegistryPath = path.join(tmp, 'bad-registry.json');
+    fs.writeFileSync(badRegistryPath, JSON.stringify({ registry: 'acme', document_primitives: {}, typo_key: 1 }));
+    const badValid = schemaValidate(badRegistryPath, ['--type', 'core']);
+    check('ssss schema validate exits 1 with structured errors on an invalid registry',
+      badValid.code === 1 && badValid.out.valid === false && badValid.out.errors.some((e) => e.path === 'typo_key'));
+
     const semanticOutput = JSON.parse(execFileSync('node', [
       path.join(__dirname, 'ssss.mjs'),
       'semantic',

package/scripts/ssss.mjs

@@ -41,6 +41,7 @@ Authoring, wire protocol & conformance:
   bridge [options]      Execute operations over stdin/stdout JSON (spec §6.8).
   primitive <verb>      Create, validate, inspect, migrate, or emit types.
   registry <verb>       Compose, lock, or verify an effective registry.
+  schema <verb>         Output or export canonical JSON Schemas (core, bundle).
   adapter conformance   Run machine-readable adapter contract suites.
   migrate 0.8-to-0.9    Diagnose and plan a non-destructive 0.9 migration.
   autolink [dir]        Generate OKF wiki links across a vault.
@@ -72,6 +73,7 @@ const MODULES = {
   semantic: './cmd-semantic.mjs',
   primitive: './cmd-primitive.mjs',
   registry: './cmd-registry.mjs',
+  schema: './cmd-schema.mjs',
   adapter: './cmd-adapter.mjs',
   migrate: './cmd-migrate.mjs',
   serve: './cmd-serve.mjs',

package/scripts/sync-docs.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Automatically synchronize and verify documentation after OpenWiki updates:
+ * 1. Updates overview.md command lists, topics, and primitive counts.
+ * 2. Ingests updated docs into OpenWiki knowledge graph.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPTS_DIR = path.join(ROOT, 'scripts');
+const HELP_DIR = path.join(ROOT, 'docs', 'help');
+const OVERVIEW_FILE = path.join(HELP_DIR, 'overview.md');
+const CORE_REGISTRY = path.join(ROOT, 'registry', 'core.json');
+
+const commands = fs.readdirSync(SCRIPTS_DIR)
+  .filter((f) => f.startsWith('cmd-') && f.endsWith('.mjs'))
+  .map((f) => f.replace(/^cmd-/, '').replace(/\.mjs$/, ''))
+  .sort();
+
+const helpTopics = fs.existsSync(HELP_DIR)
+  ? fs.readdirSync(HELP_DIR)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => f.replace(/\.md$/, ''))
+      .sort()
+  : [];
+
+let corePrimitivesCount = 20;
+let contractPrimitivesCount = 5;
+if (fs.existsSync(CORE_REGISTRY)) {
+  const core = JSON.parse(fs.readFileSync(CORE_REGISTRY, 'utf8'));
+  corePrimitivesCount = Object.keys(core.document_primitives || {}).length;
+  contractPrimitivesCount = Object.keys(core.contract_primitives || {}).length;
+}
+
+if (fs.existsSync(OVERVIEW_FILE)) {
+  let content = fs.readFileSync(OVERVIEW_FILE, 'utf8');
+
+  // Update primitive counts
+  const regPattern = /\|\s*Core registry\s*\|\s*`registry\/core\.json`\s*\|\s*[^|]+\|/;
+  const regReplacement = `| Core registry | \`registry/core.json\` | ${corePrimitivesCount} document primitives + ${contractPrimitivesCount} contract primitives; semantic (§11.9), bundle (§16), and provisioning (§17) rules. |`;
+  content = content.replace(regPattern, regReplacement);
+
+  // Update help topic list
+  const helpSection = `Run \`ssss help <topic>\` for any of:\n\`${helpTopics.join('`, `')}\`.`;
+  content = content.replace(/Run `ssss help <topic>` for any of:\n[\s\S]*?(?=\n\nRun `ssss <command>)/, helpSection);
+
+  // Update command list
+  const cmdSection = `Run \`ssss <command> --help\` for: \`${commands.join('`, `')}\`.`;
+  content = content.replace(/Run `ssss <command> --help` for:[\s\S]*?(?=\n*$)/, cmdSection);
+
+  fs.writeFileSync(OVERVIEW_FILE, content.trim() + '\n', 'utf8');
+}
+
+console.log(`✓ Synchronized docs/help/overview.md: ${commands.length} commands, ${helpTopics.length} help topics, ${corePrimitivesCount} primitives.`);

package/skills/ssss/SKILL.md

@@ -4,7 +4,7 @@ title: SSSS Protocol Reference
 name: ssss
 description: Validate or change SSSS documents, operations, registries, workflows and portable host adapters.
 timestamp: 2026-11-02T19:00:00Z
-version: 0.14.1
+version: 0.14.2
 repo_scoped: false
 ---
 

package/skills/ssss/core/SKILL.md

@@ -1,4 +1,4 @@
-# SSSS portable core — 0.14.1
+# SSSS portable core — 0.14.2
 
 Verified against the SSSS owner package, registry and spec on 2026-11-02. Establish ground truth from the installed validator, composed registry plus lock, and actual host mutation path. Schema support does not prove a configured runner or provider integration.
 
@@ -15,4 +15,4 @@ Preserve portability classes: structural definitions, tenant-private data and re
 ## Verification
 Run relevant schema/registry/lock and operation conformance, with valid and invalid examples. Cover duplicate/conflicting idempotency (including retries answered from the event log), unsafe paths, unauthorized/expired actors, leases, append semantics, rollback and commit-intent crash recovery where changed. Use `ssss --help`, then operation-specific help; commands differ by installed version. Report exact package version, registry/lock identity and actual results. Keep secrets and private runtime data out of skill content, bundles and logs.
 
-Normative sources are bundled below from the owner release tag v0.14.1 (`docs/ssss-spec.md` and `registry/core.json` at that tag). Retain authored local wrappers/references; this managed core is the portable update boundary.
+Normative sources are bundled below from the owner release tag v0.14.2 (`docs/ssss-spec.md` and `registry/core.json` at that tag). Retain authored local wrappers/references; this managed core is the portable update boundary.

package/skills/ssss/core/references/core-registry.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://ssss.dev/registry/v1",
+  "$schema": "https://ssss.dev/schemas/core-registry.schema.json",
   "registry": "core",
   "spec_version": "0.9",
   "description": "The canonical SSSS core registry and semantic application-kernel contract. Core primitives are qualified as ssss:<name>; applications define namespaced primitives through layered extension registries without copying or redefining core behavior.",
@@ -269,7 +269,7 @@
     "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)."
+      "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. a domain, phone_number, or integration_connection primitive)."
     },
     "export_profiles": {
       "backup": { "includes": ["structural", "tenant_private", "resource_bound"], "note": "Complete fidelity copy. tenant_private MUST be encrypted at rest." },

package/skills/ssss/core/references/ssss-spec.md

@@ -261,8 +261,9 @@ primitive — it implements the subset its product requires — but any primitiv
 | `primitive` | meta | structural | A governed, versioned definition for a namespaced SSSS primitive. |
 
 The **Portability** column is the primitive's default portability class (§5.5); a host
-resolves it from `registry/core.json`. Extension registries assign their own primitives a
-class — notably `resource_bound` for things like domains and phone numbers.
+resolves it from `registry/core.json`. The canonical machine-readable registry conforms to the
+JSON Schema (Draft 2020-12) published in `schemas/core-registry.schema.json`. Extension registries
+assign their own primitives a class — notably `resource_bound` for things like domains and phone numbers.
 
 ### 5.2 Contract Primitives
 
@@ -1869,7 +1870,9 @@ A bundle is a JSON object with three top-level members:
 ```
 
 `files` MUST be sorted by `path` (§16.3 order) so that two exports of the same vault state
-are identical and content-hashable (§16.3, `provenance.content_hash`).
+are identical and content-hashable (§16.3, `provenance.content_hash`). The normative JSON Schema
+(Draft 2020-12) for `.ucw` bundle containers is published in `schemas/bundle.schema.json` and
+exportable via the CLI command `ssss schema bundle`.
 
 ### 16.2 The Manifest
 

package/src/bundle.mjs

@@ -63,6 +63,7 @@ function requirementParameterKey(type, field) {
 function resourceFieldParameterAliases(type, field) {
   const aliases = [requirementParameterKey(type, field), field];
   if (type === 'domain' && field === 'domain_name') aliases.push('domain');
+  if (type === 'resource' && (field === 'binds' || field === 'name')) aliases.push('domain', 'resource_domain');
   if (type === 'phone_number' && field === 'phone_number') aliases.push('phone');
   return aliases;
 }