@gregiteen/ssss-cli 0.8.0 → 0.9.1

package/docs/ssss-spec.md

@@ -1,14 +1,15 @@
 # SSSS — Structured Semantic Syntax System
 
-**Specification v0.7 — Draft**
+**Specification v0.9**
 
 > This is the canonical, vendor-neutral specification for SSSS. It is the ground
 > truth on which all SSSS implementations are built. It is intended to be vendored
-> byte-for-byte into any repository that implements SSSS (e.g. the UltraChat
+> byte-for-byte into any repository that implements SSSS (e.g. a compatible host
 > Sovereign AI OS, the Total Recall reference kernel).
 >
-> Status: **Draft**. The format, type registry, and conformance contract are under
-> active development. Expect breaking changes until v1.0.
+> Status: **Stable for 0.9**. The format, type registry, and conformance contract
+> are settled for this version; until v1.0 a later version MAY still introduce
+> breaking changes.
 >
 > Implementation-specific detail (routes, services, storage backends, deployment)
 > does **not** belong in this document — it belongs in each implementation's own
@@ -31,9 +32,9 @@ SSSS additionally defines the **Operation Contract**: a single, validated, idemp
 envelope through which all agent-generated mutations must flow. This makes
 AI-generated state changes deterministic, replayable, conflict-safe, and auditable.
 
-Its semantic projection contract turns the same canonical files into a deterministic
-searchable graph, while translation overlays localize natural-language surfaces
-without mutating symbolic control fields or private operational data.
+Its semantic runtime turns the same canonical files into a deterministic searchable
+graph, while multilingual embedding and render adapters localize presentation without
+mutating symbolic control fields or private operational data.
 
 Any tool, IDE, agent framework, daemon, or CLI that can read Markdown can
 interoperate with an SSSS vault. The only thing that distinguishes a memory engine,
@@ -195,7 +196,7 @@ primitive — it implements the subset its product requires — but any primitiv
 | `page` | capability | structural | A VFS-native sandboxed custom workspace page. |
 | `migration` | meta | structural | An SSSS schema migration state record. |
 | `release` | meta | structural | An SSSS system schema version release record. |
-| `translation` | localization | structural | A hash-bound, non-destructive localization overlay for a structural source document. |
+| `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
@@ -217,7 +218,7 @@ Document primitives are either:
 
 - **Replace-type** — the whole file represents current state; a write replaces it
   entirely (`memory`, `skill`, `assistant`, `workflow`, `model`, `task`,
-  `conflict`, `translation`).
+  `conflict`, `primitive`).
 - **Append-type** — the file is an ordered, append-only log; writes add records to
   the body and MUST NOT rewrite prior records (`conversation`, `run`).
 
@@ -561,48 +562,13 @@ released_at: 2026-05-16T12:00:00Z
 ---
 ```
 
-#### `translation`
+#### `primitive`
 
-A non-destructive localization overlay for one structural source document. A
-translation is itself `structural`, but it does not replace or fork the source. The
-source remains authoritative for identity, behavior, permissions, enums, links, and
-all other symbolic control fields.
-
-REQUIRED: `type`, `translation_id`, `source_path`, `source_hash`, `locale`, `status`
-(`draft|reviewed|approved`), and `translated_fields` (a subset of
-`title|description|body`). OPTIONAL: `translated_title`, `translated_description`,
-`translator`, `reviewed_at`. The Markdown body is the translated body when
-`translated_fields` includes `body`.
-
-`translation_id`, `source_path`, and `locale` are immutable after creation.
-`source_path` MUST be a safe, vault-relative path to an existing `structural`
-document whose type is not `translation`. `source_hash` MUST equal the source's
-current SHA-256 content hash, written as `sha256:<64 lowercase hex characters>`.
-A stale, missing, private, resource-bound, recursive, traversing, or symlinked source
-MUST be rejected.
-
-```markdown
----
-type: translation
-title: "Política de reembolsos — español"
-description: "Traducción al español de la política de reembolsos."
-timestamp: 2026-07-10T00:00:00Z
-translation_id: refund-policy-es
-source_path: rules/refund-policy.md
-source_hash: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
-locale: es
-status: approved
-translated_fields: [title, description, body]
-translated_title: "Política de reembolsos"
-translated_description: "Reglas de reembolso para compradores."
----
-
-Los reembolsos están disponibles dentro de los treinta días.
-```
-
-Draft and reviewed translations MAY be stored and previewed, but only approved,
-hash-current overlays are applied by default to canonical localized projections
-(§11.9).
+A governed definition for a namespaced primitive that can be authored in any human
+language without changing the core registry. REQUIRED: `type`, `primitive_id`,
+`namespace`, `version`, `name`, `mutation`, `portability`, `scopes`, and `fields`.
+Stable primitive, field, enum, capability, and action identifiers are symbolic and
+language-independent. Labels and descriptions are multilingual presentation data.
 
 ### 5.5 Portability Classification
 
@@ -1106,10 +1072,10 @@ for planning a workflow trigger into a `workflow_triggered` event envelope and a
 task `operation` envelope. Hosts MAY implement their own daemon, but SHOULD pass the
 runtime conformance checks to prove the same source-of-truth and idempotency rules.
 
-### 11.9 Semantic Projection & Localization Contract
+### 11.9 Multilingual Semantic Runtime Contract
 
 The semantic layer is a **derived projection** over validated vault documents. It
-MUST be deterministic for the same vault bytes, registry set, locale, and projection
+MUST be deterministic for the same vault bytes, registry set, adapter identity, and projection
 options. It MUST NOT become a second source of truth.
 
 Each projected record SHOULD expose a stable identity, source path and content hash,
@@ -1121,29 +1087,20 @@ available as a dependency-free interoperability baseline.
 
 The safe default projection contains only `structural` documents. It MUST exclude
 `tenant_private` and `resource_bound` documents unless the caller explicitly enables
-private indexing in an authorized context. A localized export MUST use the same safe
-default, so requesting a locale can never implicitly disclose conversations, runs,
-tasks, credentials, customer data, or bound resource values.
-
-When a locale is requested, the host MAY apply one eligible `translation` (§5.4) per
-source. Eligibility requires all of the following:
-
-1. The overlay locale normalizes to the requested locale.
-2. Its status is `approved`, unless a caller explicitly opts into draft preview.
-3. The source is an existing, non-symlinked `structural` document.
-4. `source_hash` exactly matches the current source bytes.
-5. There is no second eligible overlay for the same source and locale.
-
-An overlay may replace only `title`, `description`, and body. It MUST preserve `type`,
-paths, ids, enums, status, permissions, portability, relations, and every other
-symbolic field from the source. Stale hashes, duplicate overlays, traversal, symlink
-targets, recursive translations, and translations of non-structural sources MUST
-fail closed.
-
-A materialized locale is a disposable projection, not a translated vault. It MUST be
-written outside the source vault to a new or empty non-symlinked directory, preserve
-source-relative paths, and include enough projection metadata to identify its locale
-and source hashes. It may be deleted and rebuilt at any time.
+private indexing in an authorized context. Language selection MUST NOT widen scope or
+implicitly disclose conversations, runs, tasks, credentials, customer data, or bound
+resource values.
+
+A host MAY inject a multilingual embedding adapter. Every enriched record MUST carry
+the embedding model identity and vector dimension. Search SHOULD report lexical and
+semantic evidence separately before computing a hybrid score.
+
+A host MAY inject an LLM render adapter at presentation time. The render request MUST
+carry an invariant-control block. Rendering MAY change natural-language title,
+description, body, formatting, dates, and units, but MUST NOT change primitive IDs,
+field IDs, enum codes, actions, permissions, paths, versions, hashes, or relations.
+Canonical documents are authored once in any language; SSSS 0.9 neither requires nor
+materializes translation documents or localized vault trees.
 
 ---
 
@@ -1161,8 +1118,8 @@ Fixtures are distributed as a JSON document carrying:
 - `runtime_contract` — trigger vocabulary and daemon idempotency rules (§11.8).
 - registry-extension checks — schema shape, regex validity, symlink rejection, and
   core/sibling collision rejection.
-- semantic/localization checks — deterministic indexing, privacy defaults, graph
-  edges, exact source hashes, immutable overlay identity, and safe materialization
+- multilingual semantic checks — deterministic indexing, privacy defaults, graph
+  edges, embedding provenance, cross-language retrieval, and invariant rendering
   (§11.9).
 - `fixtures[]` — each with a `request`, an `expected_response`, and an
   OPTIONAL `expected_http_status`.
@@ -1172,7 +1129,7 @@ The conformance fixture set is the shared test contract between all SSSS
 implementations. A host MUST NOT claim SSSS conformance without passing the current
 fixture set. Hosts implementing workflow daemons SHOULD also run the reference
   runtime checks exposed by `@gregiteen/ssss-cli/runtime`. Hosts exposing semantic
-  search or localized projections MUST also pass the §11.9 checks.
+  search or runtime rendering MUST also pass the §11.9 checks.
 
 ---
 
@@ -1200,7 +1157,7 @@ opaque ID as the slug and keep the human-readable label in `title` / `name`.
 This document is versioned independently of any host and of the conformance
 fixture set.
 
-- The spec version is stated in the document header (currently **v0.7 — Draft**).
+- The spec version is stated in the document header (currently **v0.9**).
 - Breaking changes to the file format, the type registry, or the Operation
   Contract increment the spec version.
 - Until **v1.0**, any version MAY introduce breaking changes.
@@ -1292,14 +1249,14 @@ inside, the resources it must bind at provision time, and provenance.
 | `ssss_core_version` | yes | The `registry/core.json` `spec_version` the bundle targets (e.g. `"0.3"`). A host MUST refuse a bundle whose core version it does not support. |
 | `required_extensions` | yes | Array of extension registry ids the files rely on (e.g. `["festech"]`). Empty array if the bundle uses only core primitives. A host MUST refuse a bundle naming an extension it has not loaded. |
 | `export_profile` | yes | `backup` \| `template` \| `sale` — the §5.5 profile this bundle was built under. Determines the allowed portability classes. |
-| `primitive_inventory` | yes | Map of primitive `type` → count, over every file in the bundle (replaces ultrachat's hard-coded `categories`; it is registry-driven, so extension types appear automatically). |
+| `primitive_inventory` | yes | Map of primitive `type` → count, over every file in the bundle (replaces the legacy hard-coded `categories`; it is registry-driven, so extension types appear automatically). |
 | `provisioning` | yes | Array of provisioning steps (§17.2) — the ordered, declarative plan for binding this bundle into a live workspace. Empty for a pure `backup` that is restored in place. |
 | `parameters` | no | Array of parameter definitions (§16.5) the importer must resolve (e.g. business name, domain). |
 | `source_workspace_id` | no | Origin workspace; OMITTED or nulled in `template`/`sale` profiles (it is operator-identifying). |
 | `file_count` | yes | Length of `files`; a cheap integrity check. |
 | `provenance` | yes | `{ content_hash, exporter, signature? }` (§16.3). |
 
-`primitive_inventory` supersedes ultrachat's fixed `categories` object and `provisioning`
+`primitive_inventory` supersedes the legacy fixed `categories` object and `provisioning`
 supersedes its `capabilities` booleans: both are now open and registry-driven rather than a
 closed enum, so a bundle full of `festech` extension primitives inventories and provisions
 them without a spec change.
@@ -1328,7 +1285,7 @@ honoring `x_portability`) MUST be permitted by `export_profile`.
 
 `parameters` are the values an importer must supply to turn a template into a running
 instance — the difference between "a festival in a box" and "*this* festival." The schema is
-adopted verbatim from ultrachat's `WorkspaceTemplateVariableDefinition`:
+adopted verbatim from the legacy `WorkspaceTemplateVariableDefinition`:
 
 | Field | Meaning |
 |-------|---------|
@@ -1369,7 +1326,7 @@ restoring an SSSS business are reliable operations rather than bespoke migration
 ### 17.2 Provisioning Steps & Binding Vocabulary
 
 A manifest's `provisioning` array is an ordered list of steps. The step schema and its
-controlled vocabularies are adopted from ultrachat's `WorkspaceProvisioningStep` and
+controlled vocabularies are adopted from the legacy `WorkspaceProvisioningStep` and
 `WorkspaceGraphEdge`:
 
 A **step** is `{ id, label, system, mode, required, notes? }`:
@@ -1402,7 +1359,7 @@ cannot resolve a link MUST fail the provision rather than emit a dangling refere
 ### 17.4 Composition & Upgrade
 
 - **Composition** — a bundle MAY depend on other bundles. A dependency carries an
-  `installMode` of `optional | recommended | required` (adopted from ultrachat's
+  `installMode` of `optional | recommended | required` (adopted from the legacy
   `WorkspaceMarketplaceRecommendation`). `provision` installs `required` dependencies before
   the bundle itself; `optional`/`recommended` are surfaced to the operator.
 - **Upgrade** — moving an installed bundle from `v2` to a `v1`-conformant shape (or any
@@ -1417,8 +1374,7 @@ cannot resolve a link MUST fail the provision rather than emit a dangling refere
 
 The following frontmatter keys are reserved by this spec across all primitives and
 MUST NOT be repurposed by hosts: `type`, `slug`, `schema_version`, `status`,
-`feedback`, `confidence`, `semantic_id`, `relations`, `locale`, `translation_id`,
-`source_path`, `source_hash`, and `translated_fields`.
+`feedback`, `confidence`, `semantic_id`, `relations`, and `language`.
 
 Hosts adding their own frontmatter fields SHOULD prefix them `x_` to remain
 forward-compatible with future spec revisions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {
@@ -11,6 +11,23 @@
     "./frontmatter": "./src/frontmatter.mjs",
     "./bundle": "./src/bundle.mjs",
     "./semantic": "./src/semantic.mjs",
+    "./primitive": "./src/primitive.mjs",
+    "./validator": "./src/validator.mjs",
+    "./kernel": {
+      "types": "./types/kernel.d.ts",
+      "import": "./src/kernel.mjs",
+      "default": "./src/kernel.mjs"
+    },
+    "./vfs": "./src/vfs.mjs",
+    "./identity": "./src/authorization.mjs",
+    "./authorization": "./src/authorization.mjs",
+    "./leases": "./src/leases.mjs",
+    "./idempotency": "./src/idempotency.mjs",
+    "./events": "./src/events.mjs",
+    "./projections": "./src/projections.mjs",
+    "./ui": "./src/ui.mjs",
+    "./http": "./src/http.mjs",
+    "./guard": "./src/guard.mjs",
     "./conformance/fixtures.json": "./conformance/fixtures.json",
     "./conformance/reference-bundle.ucw.json": "./conformance/reference-bundle.ucw.json",
     "./registry/core.json": "./registry/core.json",
@@ -25,6 +42,7 @@
   },
   "files": [
     "src",
+    "types",
     "scripts",
     "registry",
     "conformance",
@@ -50,8 +68,9 @@
     "ucw",
     "provisioning",
     "semantic-search",
-    "localization",
-    "translation"
+    "multilingual",
+    "generative-ui",
+    "application-kernel"
   ],
   "author": "Greg Iteen",
   "license": "ISC",

package/registry/core.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://ssss.dev/registry/v1",
   "registry": "core",
-  "spec_version": "0.7",
-  "description": "The canonical SSSS core primitive registry. These 15 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), semantic/localization contract (§11.9), `.ucw` bundle format (§16), and 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; extensions MUST NOT redefine a core or sibling-extension type.",
+  "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.",
   "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": {
@@ -137,33 +137,26 @@
       "required_fields": ["type", "release_id", "version", "schema_version", "summary", "released_at"],
       "spec_ref": "§5.4 release"
     },
-    "translation": {
-      "family": "localization",
-      "canonical_path": "translations/<locale>/<source-path>.md",
+    "primitive": {
+      "family": "meta",
+      "canonical_path": "primitives/<namespace>/<id>.md",
       "append_only": false,
       "portability": "structural",
-      "required_fields": ["type", "translation_id", "source_path", "source_hash", "locale", "status", "translated_fields"],
-      "optional_fields": ["translated_title", "translated_description", "translator", "reviewed_at"],
-      "immutable_fields": ["translation_id", "source_path", "locale"],
+      "required_fields": ["type", "primitive_id", "namespace", "version", "name", "mutation", "portability", "scopes", "fields"],
+      "optional_fields": ["language", "aliases", "path_template", "capabilities", "events", "projections", "ui", "migrations", "requires"],
+      "immutable_fields": ["primitive_id", "namespace"],
       "enums": {
-        "status": ["draft", "reviewed", "approved"],
-        "translated_fields": ["title", "description", "body"]
+        "mutation": ["replace", "append"],
+        "portability": ["structural", "tenant_private", "resource_bound"],
+        "scopes": ["system", "account", "workspace", "user"]
       },
       "patterns": {
-        "translation_id": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$",
-        "locale": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$",
-        "source_hash": "^sha256:[a-f0-9]{64}$"
-      },
-      "references": {
-        "source_path": {
-          "must_exist": true,
-          "disallowed_types": ["translation"],
-          "allowed_portability": ["structural"],
-          "hash_field": "source_hash"
-        }
+        "primitive_id": "^[a-z][a-z0-9_-]{0,63}:[a-z][a-z0-9_-]{0,127}$",
+        "namespace": "^[a-z][a-z0-9_-]{0,63}$",
+        "language": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
       },
-      "notes": "A non-destructive presentation overlay. Only title, description, and body may be translated; symbolic control fields remain byte-for-byte sourced from the referenced structural document.",
-      "spec_ref": "§5.4 translation"
+      "notes": "A governed, versioned definition for a repository, extension, workspace, or user primitive. Natural-language labels may use any language; stable field, enum, capability, and action identifiers are never translated.",
+      "spec_ref": "§5.4 primitive"
     }
   },
 
@@ -178,7 +171,7 @@
   "universal_frontmatter": {
     "required": ["type", "title", "description", "timestamp"],
     "recommended_okf": ["resource", "tags", "aliases"],
-    "recommended_semantic": ["semantic_id", "resource", "tags", "aliases", "relations", "locale"],
+    "recommended_semantic": ["semantic_id", "resource", "tags", "aliases", "relations", "language"],
     "spec_ref": "§4.2"
   },
 
@@ -212,7 +205,7 @@
       "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."
+      "note": "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"
@@ -253,13 +246,13 @@
     "identity_fields": ["semantic_id", "resource", "type", "path"],
     "surface_fields": ["title", "description", "name", "slug", "aliases", "tags"],
     "relation_fields": ["relations", "wiki_links", "markdown_links"],
-    "translatable_fields": ["title", "description", "body"],
-    "locale_pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$",
-    "safe_default": "Semantic indexes exclude tenant_private and resource_bound documents unless include_private is explicitly enabled. Translation overlays may reference structural sources only.",
+    "renderable_fields": ["title", "description", "body"],
+    "language_pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$",
+    "safe_default": "Semantic adapters exclude tenant_private and resource_bound documents unless an authorized context explicitly includes them. Runtime rendering never changes symbolic controls.",
     "spec_ref": "§11.9"
   },
 
-  "reserved_keys": ["type", "slug", "schema_version", "status", "feedback", "confidence", "semantic_id", "locale", "translation_of", "translation_source_hash"],
+  "reserved_keys": ["type", "slug", "schema_version", "status", "feedback", "confidence", "semantic_id", "language", "relations"],
   "host_field_prefix": "x_",
   "spec_ref_reserved": "Appendix A"
 }

package/scripts/build-reference-bundle.mjs

@@ -15,7 +15,6 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { exportBundle, validateBundle } from '../src/bundle.mjs';
-import { documentHash } from '../src/registry.mjs';
 import { generateIndexes } from './autolink.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -113,25 +112,6 @@ status: pending
 Attendee jane@example.com requested a seat change.`,
 };
 
-// Structural translation overlay — hash-bound to the exact source document and
-// applied only by the semantic/localization projection (§11.9).
-VAULT['translations/es/rules/refund-policy.md'] =
-`---
-type: translation
-title: Spanish Refund Policy Translation
-description: Approved Spanish presentation overlay for the festival refund policy.
-timestamp: 2026-07-10T00:00:00Z
-translation_id: refund-policy-es
-source_path: rules/refund-policy.md
-source_hash: ${documentHash(VAULT['rules/refund-policy.md'])}
-locale: es
-status: approved
-translated_fields: [title, description, body]
-translated_title: Política de reembolsos
-translated_description: Explica cuándo están disponibles los reembolsos para asistentes.
----
-Los reembolsos están disponibles hasta catorce días antes del evento.`;
-
 function buildVault() {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-refvault-'));
   const files = [];

package/scripts/cmd-adapter.mjs

@@ -0,0 +1,29 @@
+/** Machine-readable reference adapter conformance report. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { MemoryVfs, FileSystemVfs, runVfsContract } from '../src/vfs.mjs';
+import { MemoryLeaseStore, FileLeaseStore, runLeaseContract } from '../src/leases.mjs';
+import { MemoryIdempotencyStore, FileIdempotencyStore, runIdempotencyContract } from '../src/idempotency.mjs';
+import { parseArgs, die, wantsHelp } from './lib/cli.mjs';
+
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log('Usage: ssss adapter conformance [--out <file>]'); return; }
+  if (argv[0] !== 'conformance') die('Expected adapter conformance.');
+  const { flags } = parseArgs(argv.slice(1));
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-adapters-'));
+  try {
+    const suites = {
+      vfs_memory: await runVfsContract(new MemoryVfs()),
+      vfs_filesystem: await runVfsContract(new FileSystemVfs(path.join(root, 'vfs'))),
+      lease_memory: await runLeaseContract(new MemoryLeaseStore()),
+      lease_filesystem: await runLeaseContract(new FileLeaseStore(path.join(root, 'leases'))),
+      idempotency_memory: await runIdempotencyContract(new MemoryIdempotencyStore()),
+      idempotency_filesystem: await runIdempotencyContract(new FileIdempotencyStore(path.join(root, 'idempotency'))),
+    };
+    const report = { version: 1, passed: Object.values(suites).every((suite) => suite.passed), suites };
+    const text = `${JSON.stringify(report, null, 2)}\n`;
+    if (flags.out) fs.writeFileSync(path.resolve(flags.out), text, { flag: 'wx', mode: 0o600 }); else process.stdout.write(text);
+    if (!report.passed) process.exitCode = 1;
+  } finally { fs.rmSync(root, { recursive: true, force: true }); }
+}

package/scripts/cmd-import.mjs

@@ -61,7 +61,7 @@ export async function run(argv) {
   }
 
   const engine = createEngine({ registryDir: flags.registry });
-  const result = importBundle(envelopes, vault, engine);
+  const result = await importBundle(envelopes, vault, engine);
   const failed = result.results.filter((r) => !r.success);
   if (flags['dry-run']) {
     console.log(`${result.ok ? '✓' : '✗'} import dry-run — ${result.wouldCommit || 0} would commit, ${envelopes.length - (result.wouldCommit || 0)} unchanged (idempotent), ${failed.length} failed → ${vault}`);

package/scripts/cmd-migrate.mjs

@@ -0,0 +1,26 @@
+/** Non-destructive 0.8 -> 0.9 migration diagnostics and backup manifest. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { parseArgs, die, wantsHelp } from './lib/cli.mjs';
+
+function walk(root, dir = root, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const absolute = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) walk(root, absolute, out); else if (entry.isFile()) out.push(path.relative(root, absolute).split(path.sep).join('/'));
+  }
+  return out.sort();
+}
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log('Usage: ssss migrate 0.8-to-0.9 <vault> [--out <report.json>]'); return; }
+  if (argv[0] !== '0.8-to-0.9' || !argv[1]) die('Expected migrate 0.8-to-0.9 <vault>.');
+  const { flags } = parseArgs(argv.slice(2));
+  const root = fs.realpathSync(path.resolve(argv[1]));
+  const files = walk(root);
+  const translationArtifacts = files.filter((file) => /(^|\/)translations?\//i.test(file) || /translation/i.test(fs.readFileSync(path.join(root, file), 'utf8').slice(0, 2048)));
+  const backup = files.map((file) => ({ path: file, hash: `sha256:${crypto.createHash('sha256').update(fs.readFileSync(path.join(root, file))).digest('hex')}` }));
+  const report = { migration: '0.8-to-0.9', dry_run: true, source: root, backup_manifest: backup, diagnostics: { translation_artifacts: translationArtifacts, required_actions: translationArtifacts.length ? ['Preserve canonical authored content; archive obsolete translation overlays outside the vault.'] : [] }, writes_performed: 0 };
+  const text = `${JSON.stringify(report, null, 2)}\n`;
+  if (flags.out) fs.writeFileSync(path.resolve(flags.out), text, { flag: 'wx', mode: 0o600 }); else process.stdout.write(text);
+}

package/scripts/cmd-new.mjs

@@ -160,12 +160,12 @@ 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');
 
-test('engine implements the canonical Operation Contract (spec §6)', () => {
+test('engine implements the canonical Operation Contract (spec §6)', async () => {
   const vault = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-conf-'));
   const engine = createEngine();
   try {
     for (const f of fixtures) {
-      const res = engine.processOperation(JSON.parse(JSON.stringify(f.request)), vault);
+      const res = await engine.processOperation(JSON.parse(JSON.stringify(f.request)), vault);
       const exp = f.expected_response;
       if (exp.success !== undefined) assert.equal(res.success, exp.success, f.id + ' success');
       if (exp.validation && exp.validation.valid !== undefined) {
@@ -175,7 +175,7 @@ test('engine implements the canonical Operation Contract (spec §6)', () => {
   } finally { fs.rmSync(vault, { recursive: true, force: true }); }
 });
 
-test('this vault exports, validates, and round-trips as a sale bundle (spec §16/§17)', () => {
+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);
   assert.ok(valid, 'bundle invalid: ' + errors.join('; '));
@@ -187,9 +187,9 @@ test('this vault exports, validates, and round-trips as a sale bundle (spec §16
   const target = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-import-'));
   try {
     const engine = createEngine();
-    const r1 = importBundle(plan.plan, target, engine);
+    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 = importBundle(plan.plan, target, engine);
+    const r2 = await importBundle(plan.plan, target, engine);
     assert.equal(r2.committed, 0, 're-import was not idempotent');
   } finally { fs.rmSync(target, { recursive: true, force: true }); }
 });

package/scripts/cmd-primitive.mjs

@@ -0,0 +1,48 @@
+/** Primitive authoring and inspection commands for SSSS 0.9. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { definePrimitive, definitionsToExtensionRegistry } from '../src/primitive.mjs';
+import { parseArgs, die, wantsHelp } from './lib/cli.mjs';
+
+const HELP = `Usage: ssss primitive create|validate|inspect|migrate [file] [options]\n\n` +
+  `create: --namespace <id> --name <text> [--language <tag>] [--fields <json>] [--out <file>]\n` +
+  `validate|inspect: <definition.json> [--typescript] [--out <file>]\n` +
+  `migrate: <definition.json> --to-version <n> [--out <file>]`;
+
+function readJson(file) { return JSON.parse(fs.readFileSync(path.resolve(file), 'utf8')); }
+function emit(value, output) {
+  const text = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
+  if (output) fs.writeFileSync(path.resolve(output), text, { flag: 'wx', mode: 0o600 });
+  else process.stdout.write(text);
+}
+function typeScript(definition) {
+  const name = definition.primitive_id.replace(/[^A-Za-z0-9]+/g, '_').replace(/^\d/, '_$&');
+  const fields = definition.fields.map((field) => {
+    const kind = field.kind === 'boolean' ? 'boolean' : field.kind === 'number' ? 'number' : field.kind === 'enum' ? field.values.map(JSON.stringify).join(' | ') : 'string';
+    return `  ${JSON.stringify(field.id)}${field.required ? '' : '?'}: ${kind};`;
+  }).join('\n');
+  return `export interface ${name} {\n  type: ${JSON.stringify(definition.primitive_id)};\n${fields}\n}\n`;
+}
+
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log(HELP); return; }
+  const verb = argv[0];
+  const { positionals, flags } = parseArgs(argv.slice(1), { booleans: ['typescript'] });
+  try {
+    if (verb === 'create') {
+      if (!flags.namespace || !flags.name) die(`create requires --namespace and --name.\n${HELP}`);
+      const definition = definePrimitive({ namespace: flags.namespace, name: flags.name, language: flags.language, fields: flags.fields ? JSON.parse(flags.fields) : [] });
+      emit(definition, flags.out); return;
+    }
+    if (!positionals[0]) die(`A definition file is required.\n${HELP}`);
+    const definition = definePrimitive(readJson(positionals[0]));
+    if (verb === 'validate') { emit({ valid: true, primitive_id: definition.primitive_id }, flags.out); return; }
+    if (verb === 'inspect') { emit(flags.typescript ? typeScript(definition) : { definition, registry: definitionsToExtensionRegistry(definition.namespace, [definition]) }, flags.out); return; }
+    if (verb === 'migrate') {
+      const version = Number(flags['to-version']);
+      if (!Number.isInteger(version) || version <= definition.version) die('--to-version must be an integer greater than the current version.');
+      emit({ ...definition, version, revision: 1, migrations: [...(definition.migrations || []), { from: definition.version, to: version, strategy: 'explicit' }] }, flags.out); return;
+    }
+    die(`Unknown primitive verb '${verb || ''}'.\n${HELP}`);
+  } catch (error) { die(error.message); }
+}

package/scripts/cmd-registry.mjs

@@ -0,0 +1,25 @@
+/** Effective registry composition and integrity-lock commands. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { composeRegistryLayers, createRegistryLock, loadRegistries, verifyRegistryLock } from '../src/registry.mjs';
+import { parseArgs, die, wantsHelp } from './lib/cli.mjs';
+
+const HELP = 'Usage: ssss registry compose|lock|verify [--extension <file> ...] [--lock <file>] [--out <file>]';
+const read = (file) => JSON.parse(fs.readFileSync(path.resolve(file), 'utf8'));
+function serializable(set) { return { primitives: Object.fromEntries(set.primitives), aliases: Object.fromEntries(set.aliases), extension_versions: Object.fromEntries(set.extensionVersions) }; }
+export async function run(argv) {
+  if (wantsHelp(argv)) { console.log(HELP); return; }
+  const verb = argv[0];
+  const { flags } = parseArgs(argv.slice(1), { multi: ['extension'] });
+  try {
+    const base = loadRegistries();
+    const set = composeRegistryLayers({ core: base.core, repository: (flags.extension || []).map(read) });
+    let result;
+    if (verb === 'compose') result = serializable(set);
+    else if (verb === 'lock') result = createRegistryLock(set);
+    else if (verb === 'verify') { if (!flags.lock) die('verify requires --lock <file>.'); result = verifyRegistryLock(set, read(flags.lock)); }
+    else die(`Unknown registry verb '${verb || ''}'.\n${HELP}`);
+    const text = `${JSON.stringify(result, null, 2)}\n`;
+    if (flags.out) fs.writeFileSync(path.resolve(flags.out), text, { flag: 'wx', mode: 0o600 }); else process.stdout.write(text);
+  } catch (error) { die(error.message); }
+}