@gregiteen/ssss-cli 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to the SSSS (Structured Semantic Syntax System) spec will be
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.8.0] - 2026-07-10
+### Changed
+- Core registry/spec version is now `0.7`. Registry `patterns`,
+  `immutable_fields`, and `references` are enforced by the reference engine and
+  covered by the parity auditor.
+- Bundle import now preflights the complete envelope plan before committing, so a
+  late invalid document cannot leave a partial installation.
+- Bundle validation now applies all registry field constraints and returns
+  structured errors for malformed file entries instead of throwing.
+
+### Fixed
+- Bundle provenance now uses the real published package identity,
+  `@gregiteen/ssss-cli`, instead of an unavailable package alias. The
+  reference bundle derives its exporter name and version from `package.json`.
+
+### Added
+- A tracked, first-class `ssss` skill package with evidence-first canon routing,
+  a dependency-free document validator, contract reference, evals, and audit
+  prompt. The skill is included in the npm package allowlist.
+- Conformance checks that pin default and reference-bundle exporter identities
+  to current package metadata.
+- The `translation` document primitive and spec §11.9 semantic/localization
+  contract: exact-hash structural sources, immutable overlay identity, and
+  natural-language-only translated fields.
+- `@gregiteen/ssss-cli/semantic`, `ssss semantic`, and `ssss localize` for
+  deterministic Unicode search/graph projections and non-destructive localized
+  materialization through a whole-projection staging directory.
+- Fail-closed extension registry composition for malformed fields, invalid
+  regular expressions, symlinks, reserved ids, and core/sibling collisions.
+- Privacy-safe semantic defaults that exclude `tenant_private` and
+  `resource_bound` data unless explicitly requested in an authorized context.
+- Conformance fixtures 024–026 plus dedicated extension-registry,
+  semantic/localization, and expanded CLI smoke groups.
+- Offline help for semantic search and localization, plus a security/UX impact
+  report for downstream host implementers.
+
 ## [0.7.1] - 2026-07-08
 ### Fixed
 - Reduced `resource_bound` primitives to requirement declarations in `template`
@@ -62,7 +100,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   trigger evaluation across daemon, cron, webhook, file-change, event, condition,
   and manual runtimes. Workflows own `triggers[]`; external schedulers are only
   wake-up mechanisms.
-- **`@ssss/cli/runtime` helpers** — deterministic `planWorkflowTrigger()` and
+- **`@gregiteen/ssss-cli/runtime` helpers** — deterministic `planWorkflowTrigger()` and
   `createRunEnvelope()` helpers derive `workflow_triggered` events, task
   documents, and run documents through the Operation Contract.
 - **Runtime conformance metadata/checks** — `conformance/fixtures.json` v1.3.0
@@ -79,7 +117,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a starter `vault/` of core primitives (incl. a `tenant_private` task to demonstrate
   the sale-drop), a dependency-free conformance test (`node --test`) that replays the
   canonical fixtures through the engine and round-trips the vault as a `sale` bundle,
-  plus `package.json` (pinned to the matching `@ssss/cli` tag), `CLAUDE.md`, `README`,
+  plus `package.json` (pinned to the matching `@gregiteen/ssss-cli` tag), `CLAUDE.md`, `README`,
   and `.gitignore`. Flags: `--with-total-recall` (wire the Total Recall memory OS),
   `--install` (npm install + Total Recall init + verify), `--ref`, `--name`, `--force`,
   `--no-git`. All shelling-out uses `execFileSync` with fixed argv (no shell). Docs:
@@ -114,7 +152,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `ssss help [topic]` serving offline docs from `docs/help/` and `ssss version`. Each
   command has its own `--help`. Shared parsing/formatting in `scripts/lib/cli.mjs`.
 - **Open-source packaging** — `README.md`, `LICENSE` (ISC), `.gitignore`, and
-  `package.json` metadata (`engines`, `repository`, `files`) so `@ssss/cli` is
+  `package.json` metadata (`engines`, `repository`, `files`) so `@gregiteen/ssss-cli` is
   publishable and the runtime-read paths (`VERSION`, `docs/help`) ship in the tarball.
 
 ### Changed
@@ -133,7 +171,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the canonical Operation Contract as the fourth envelope type. Removes a replace-type file,
   rejects append-type targets, and emits a deletion event for audit. Idempotent.
 - **Reference engine (`src/engine.mjs`, `src/registry.mjs`, `src/frontmatter.mjs`)** — the
-  canonical, dependency-free `@ssss/cli` Operation Contract engine. Harvested from total-recall
+  canonical, dependency-free `@gregiteen/ssss-cli` Operation Contract engine. Harvested from total-recall
   (§6.3 pipeline, idempotency replay from the audit log, `buildRepair`/§9 repair blocks) and
   festech (`delete` envelope, `resolveContainedPath` path-traversal guard, registry-driven
   content validation). Validates content against `registry/core.json` + `registry/extensions/*`

package/README.md

@@ -4,7 +4,7 @@
 > Turn a running business into a single tradeable file — *a festival in a box.*
 
 [![conformance](https://img.shields.io/badge/conformance-fixtures%20%2B%20runtime%20%2B%20bundle-brightgreen)](conformance/)
-[![spec](https://img.shields.io/badge/spec-v0.6%20draft-blue)](docs/ssss-spec.md)
+[![spec](https://img.shields.io/badge/spec-v0.9%20draft-blue)](docs/ssss-spec.md)
 [![OKF](https://img.shields.io/badge/OKF-v0.1%20compatible-blue)](docs/ssss-spec.md)
 
 SSSS is the vendor-neutral standard and reference implementation shared by
@@ -16,6 +16,8 @@ SSSS is the vendor-neutral standard and reference implementation shared by
   `event` / `delete`) for mutating a vault, with idempotency replay and audit.
 - **The Workflow Runtime Contract** (§11.8) — workflows own triggers; daemons,
   crons, and webhooks derive idempotent event/task/run envelopes from the vault.
+- **Multilingual semantic runtime** (§11.9) — deterministic lexical evidence,
+  injected multilingual embeddings, and runtime rendering with symbolic controls fixed.
 - **Portability classification** (§5.5) — the keystone: every primitive is
   `structural`, `tenant_private`, or `resource_bound`, so a vault can be *sold*
   without leaking the operator's private data.
@@ -77,6 +79,7 @@ ssss import festival.ucw.json --vault ./new-tenant \
 | `ssss inspect <bundle>` | Human-readable summary (manifest, inventory, params, steps). |
 | `ssss provision <bundle>` | Plan an install: params + link integrity → envelopes (§17). |
 | `ssss import <bundle>` | Replay a bundle/plan into a vault via the engine (idempotent). |
+| `ssss semantic <vault>` | Build or query a deterministic, privacy-safe semantic index (§11.9). |
 | `ssss autolink [dir]` | Generate OKF wiki-links across a vault. |
 | `ssss conformance` | Run the canonical conformance suite (§12). |
 | `ssss help [topic]` | Local docs: `runtime`, `portability`, `bundle`, `provisioning`, `leases`, … |
@@ -89,6 +92,7 @@ Run `ssss <command> --help` for flags, or `ssss help <topic>` for concepts.
 import { createEngine } from '@gregiteen/ssss-cli/engine';
 import { exportBundle, validateBundle, provisionBundle, importBundle } from '@gregiteen/ssss-cli/bundle';
 import { planWorkflowTrigger } from '@gregiteen/ssss-cli/runtime';
+import { buildSemanticIndex, searchSemanticIndex, renderSemanticRecord } from '@gregiteen/ssss-cli/semantic';
 
 const bundle = exportBundle('./my-vault', { profile: 'sale', name: 'Festival in a Box' });
 const { valid, errors } = validateBundle(bundle);
@@ -113,11 +117,20 @@ const runtimePlan = planWorkflowTrigger({
   trigger: { type: 'cron', id: 'daily-0800', cron: '0 8 * * *' },
   scheduledFor: '2026-07-02T14:00:00.000Z',
 });
+
+const index = buildSemanticIndex('./my-vault');
+const matches = searchSemanticIndex(index, 'política de reembolsos');
+const rendered = await renderSemanticRecord(matches[0].document, { language: 'es', render: renderer });
 ```
 
 Exports: `@gregiteen/ssss-cli` / `@gregiteen/ssss-cli/engine` (Operation Contract engine),
 `@gregiteen/ssss-cli/bundle` (export/provision/import), `@gregiteen/ssss-cli/registry`,
-`@gregiteen/ssss-cli/runtime`, `@gregiteen/ssss-cli/frontmatter`.
+`@gregiteen/ssss-cli/runtime`, `@gregiteen/ssss-cli/semantic`,
+`@gregiteen/ssss-cli/frontmatter`.
+
+Canonical content is authored once in any language. Multilingual embedding and render
+adapters handle cross-language retrieval and presentation at runtime; primitive IDs,
+field IDs, enum codes, permissions, paths, hashes, and relations never change.
 
 ## Portability — why a vault is safe to sell
 
@@ -144,17 +157,19 @@ npm test                    # == ssss conformance --engine
 ## Repository layout
 
 ```
-docs/ssss-spec.md          The normative specification (v0.6 draft).
+docs/ssss-spec.md          The normative specification (v0.9 draft).
 docs/help/                 Topic docs surfaced by `ssss help`.
-registry/core.json         14 document + 5 contract primitives; bundle & provisioning schemas.
+registry/core.json         15 document + 5 contract primitives; semantic, bundle & provisioning schemas.
 registry/extensions/       Application extension registries (e.g. festech).
 src/engine.mjs             Operation Contract engine (§6).
 src/runtime.mjs            Workflow trigger → event/task/run envelope planning (§11.8).
+src/semantic.mjs           Multilingual semantic retrieval + runtime rendering (§11.9).
 src/bundle.mjs             export / validate / provision / import (§16–§17).
 src/registry.mjs           Registry-driven type + portability resolution.
 src/frontmatter.mjs        Zero-dependency YAML frontmatter.
 scripts/ssss.mjs           The `ssss` CLI dispatcher.
 conformance/               Canonical fixtures + reference bundle.
+skills/ssss/               Packaged SSSS system skill and dependency-free validator.
 ```
 
 ## License

package/VERSION

@@ -1 +1 @@
-0.7.1
+0.9.0

package/conformance/README.md

@@ -11,13 +11,13 @@ shared test suite every implementation MUST pass to claim conformance (spec §12
 |------|---------|
 | [`fixtures.json`](fixtures.json) | Canonical request/response fixtures for the Operation Contract (spec §6). |
 | [`reference-bundle.ucw.json`](reference-bundle.ucw.json) | The canonical `.ucw` reference bundle (spec §16, "Festival in a Box"). A `sale`-profile export, content-hashed; round-tripped by the runner. Rebuild with `node scripts/build-reference-bundle.mjs`. |
-| `../registry/core.json` | The 14 core document primitives + 5 contract primitives, plus the `runtime` (§11.8), `bundle` (§16), and `provisioning` (§17) schemas the standard owns. |
+| `../registry/core.json` | The 15 core document primitives + 5 contract primitives, plus `runtime` (§11.8), `semantic` (§11.9), `bundle` (§16), and `provisioning` (§17) contracts. |
 
 ## Implementations under test
 
 | Implementation | SSSS surface | Core primitives | Extensions |
 |----------------|--------------|-----------------|------------|
-| **festech.live** | `SsssOperationService` + `SsssLeaseService`, Postgres event log, ~4,024 vault files | all 14 ✓ | 118 app primitives |
+| **festech.live** | `SsssOperationService` + `SsssLeaseService`, Postgres event log, ~4,024 vault files | integration audit required for core v0.7 | 118 app primitives |
 | **ultrachat** | SQL `ssss_core_contract` + hardening migrations, `SsssApiClient`, ~1,110 vault files | (audit pending) | app primitives |
 | **total-recall** | Markdown-native kernel, `validate-schema.mjs`, memory vault | memory-centric subset | memory categories |
 
@@ -32,8 +32,10 @@ npx ssss conformance --endpoint <url> --token <pat>   # run fixtures against a l
 The runner validates that the fixture file is well-formed and that every
 `expected_response` is internally consistent with the envelope rules. With
 `--engine`, it replays every fixture through the reference engine (`src/engine.mjs`),
-checks workflow runtime planning (`src/runtime.mjs`, spec §11.8), runs regression
-coverage for patch serialization and leases (§6/§7), and round-trips the
+checks workflow runtime planning (`src/runtime.mjs`, spec §11.8), extension-registry
+collision/schema/symlink safety and multilingual semantic retrieval/rendering (`src/semantic.mjs`,
+§11.9), runs regression coverage for patch serialization and leases (§6/§7), and
+round-trips the
 reference bundle (validate → provision → import → re-import, spec §16/§17)
 against a temp vault — proving idempotency, strict bundle shape validation, and
 that no `tenant_private` or seller-bound `resource_bound` value ever lands. With
@@ -42,18 +44,20 @@ endpoint and diffs the response.
 
 ## Core vs. extension registry
 
-The standard owns only the **core**: the 14 document primitives and 5 contract
+The standard owns only the **core**: the 15 document primitives and 5 contract
 primitives in [`../registry/core.json`](../registry/core.json), plus the `runtime`
-(§11.8), `bundle` (§16), and `provisioning` (§17) schemas. Every conformant
+(§11.8), `semantic` (§11.9), `bundle` (§16), and `provisioning` contracts. Every conformant
 implementation maps to the same core.
 
 Applications **extend** the core with their own primitives (festech has 118 —
 `meeting`, `phone_number`, `inventory_item`, `language_convention`, …). Extensions:
 
 - MUST NOT redefine or shadow a core type.
+- MUST NOT redefine a type from a sibling extension.
+- MUST be regular, non-symlinked JSON files with valid regex patterns and field lists.
 - Live in the application's own extension registry, not here.
 - SHOULD follow the same schema shape as core entries (`required_fields`,
-  `append_only`, enums) so the same validator handles them.
+  `append_only`, enums, patterns, immutable fields, references) so the same validator handles them.
 
 ## ⚠️ Open reconciliation items (spec ⇄ implementation drift)
 

package/conformance/fixtures.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://ssss.dev/conformance/v1",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Canonical SSSS Operation Contract conformance fixtures. These define the canonical request/response shapes for the Operation Contract (spec §6) and are the shared test contract every SSSS implementation MUST pass. A host is conformant only if, for every fixture, it produces the expected response and status code (spec §12).",
   "spec_url": "../docs/ssss-spec.md",
   "operation_types": {
@@ -86,6 +86,9 @@
       "Required fields for each primitive type must be present and non-empty",
       "required_when-conditional fields must be present when their condition matches (spec §9)",
       "Fields with a registry-declared enum must take one of the declared values",
+      "Fields with a registry-declared pattern must match it",
+      "Registry-declared immutable fields cannot change through operation replacement or patch",
+      "Registry-declared document references must be safe, resolvable, type/portability-compatible, and hash-valid",
       "See /api/v1/ssss/schema for the full type schema definitions"
     ],
     "authorization": [
@@ -741,6 +744,25 @@
         }
       },
       "expected_http_status": 409
+    },
+    {
+      "id": "fixture-024",
+      "name": "Multilingual source — valid Spanish structural rule",
+      "description": "Natural-language fields may be authored in any language while symbolic controls remain stable.",
+      "request": {
+        "type": "operation",
+        "idempotency_key": "35353535-3535-3535-3535-353535353535",
+        "path": "rules/translatable-refund-rule.md",
+        "workspace_id": "TEST_WORKSPACE_ID",
+        "actor": { "role": "system" },
+        "content": "---\ntype: rule\ntitle: \"Política de reembolsos\"\ndescription: \"Explica cuándo están disponibles los reembolsos.\"\ntimestamp: \"2026-07-10T00:00:00Z\"\nname: refund-policy\nlanguage: es\n---\nLos reembolsos están disponibles antes de la fecha límite.",
+        "intent": "Conformance fixture: create a non-English structural source"
+      },
+      "expected_response": {
+        "success": true,
+        "type": "operation",
+        "validation": { "valid": true, "type": "rule", "errors": [] }
+      }
     }
   ],
   "error_codes": {
@@ -759,5 +781,5 @@
   ],
   "maintained_by": "SSSS standard (canonical: this repo)",
   "provenance": "Seeded from the festech.live reference implementation, which authored the original shared contract; canonicalized here as the vendor-neutral source of truth.",
-  "last_updated": "2026-07-02"
+  "last_updated": "2026-07-10"
 }

package/conformance/reference-bundle.ucw.json

@@ -4,7 +4,7 @@
     "description": "A complete music-festival operation as a tradeable SSSS bundle.",
     "version": "1.0.0",
     "exported_at": "1970-01-01T00:00:00.000Z",
-    "ssss_core_version": "0.6",
+    "ssss_core_version": "0.9",
     "required_extensions": [
       "festech"
     ],
@@ -88,7 +88,7 @@
     "file_count": 14,
     "provenance": {
       "content_hash": "sha256:7febd673938a3dc04c068e0bf08097a9783c09e612606d2df9a4db8dcb8907f5",
-      "exporter": "@ssss/cli@0.7.0"
+      "exporter": "@gregiteen/ssss-cli@0.9.0"
     }
   },
   "files": [

package/docs/help/bundle.md

@@ -13,7 +13,7 @@ integrity. The container file is conventionally named `*.ucw.json`.
     "description": "...",
     "version": "0.1.0",
     "exported_at": "1970-01-01T00:00:00.000Z",   // frozen → deterministic export
-    "ssss_core_version": "0.6",
+    "ssss_core_version": "0.7",
     "required_extensions": ["festech"],
     "export_profile": "sale",                      // backup | template | sale
     "primitive_inventory": { "workflow": 1, "page": 1, "rule": 1, "assistant": 1, "domain": 1 },
@@ -22,7 +22,7 @@ integrity. The container file is conventionally named `*.ucw.json`.
     "file_count": 5,
     "provenance": {
       "content_hash": "sha256:…",                  // over the canonical file serialization
-      "exporter": "@ssss/cli"
+      "exporter": "@gregiteen/ssss-cli"
     }
   },
   "files": [ { "path": "rules/refund-policy.md", "content": "---\n…" } ]
@@ -36,6 +36,10 @@ of `files`. `ssss validate` recomputes it and rejects any mismatch — a bundle
 be silently edited. `primitive_inventory` is registry-driven (a count per `type`),
 not a closed category enum.
 
+Bundle validation also applies registry patterns and document-reference rules.
+Primitive, extension, and migration dependencies must resolve against the effective
+registry before any file is committed.
+
 ## Parameters
 
 Each entry in `parameters[]` is a template variable resolved at provision time:

package/docs/help/import.md

@@ -12,6 +12,8 @@ ssss import --plan plan.json   --vault <dir>     # replay a plan from `ssss prov
 - `--vault <dir>` is required and is created if missing.
 - Without `--plan`, import provisions inline first (resolving `--param` flags); a
   failed provision (unresolved params / dangling links) aborts before any write.
+- The engine preflights every envelope in the plan before the first commit. A
+  late schema, reference, or authorization failure cannot leave a partial import.
 - `--dry-run` validates every envelope without committing and reports
   `would commit` instead of `committed`.
 - The normal summary reports `committed`, `unchanged (idempotent)`, and `failed`

package/docs/help/overview.md

@@ -5,16 +5,18 @@ and mutation contract for AI-agent state. A vault is a directory of Markdown fil
 with YAML frontmatter; every file declares a `type` defined in the registry.
 
 `@gregiteen/ssss-cli` is the reference implementation: a dependency-free Operation Contract
-engine, a registry-driven validator, and the `.ucw` bundle/provisioning tooling.
+kernel, a registry-driven validator, multilingual semantic adapters, and the
+`.ucw` bundle/provisioning tooling.
 
 ## The pieces
 
 | Piece | Where | What it is |
 |-------|-------|------------|
 | Spec | `docs/ssss-spec.md` | The normative standard. |
-| Core registry | `registry/core.json` | The 14 document primitives + 5 contract primitives, plus the bundle (§16) and provisioning (§17) schemas. |
+| Core registry | `registry/core.json` | The 15 document primitives + 5 contract primitives, plus semantic (§11.9), bundle (§16), and provisioning (§17) contracts. |
 | Engine | `src/engine.mjs` | The §6 Operation Contract pipeline (operation/patch/event/delete). |
 | Runtime | `src/runtime.mjs` | The §11.8 workflow trigger → event/task/run envelope planner. |
+| Semantic | `src/semantic.mjs` | Lexical evidence, multilingual embeddings, privacy filters, and runtime rendering (§11.9). |
 | Bundle | `src/bundle.mjs` | export / validate / provision / import (§16–§17). |
 | Conformance | `conformance/` | Fixtures every host must pass. |
 
@@ -28,6 +30,8 @@ vault ──export──▶ .ucw bundle ──provision──▶ envelope plan
 ## Commands
 
 Run `ssss help <topic>` for any of:
-`runtime`, `portability`, `bundle`, `provisioning`, `export`, `provision`, `import`, `conformance`, `autolink`.
+`runtime`, `semantic`, `portability`, `bundle`, `provisioning`,
+`export`, `provision`, `import`, `conformance`, `autolink`.
 
-Run `ssss <command> --help` for: `export`, `validate`, `inspect`, `provision`, `import`, `autolink`, `conformance`.
+Run `ssss <command> --help` for: `export`, `validate`, `inspect`, `provision`,
+`import`, `semantic`, `autolink`, `conformance`.

package/docs/help/semantic.md

@@ -0,0 +1,38 @@
+# Semantic projection (spec §11.9)
+
+SSSS builds a deterministic search and graph projection directly from validated
+Markdown. The projection is disposable: the vault remains the only source of truth.
+
+```bash
+ssss semantic ./vault
+ssss semantic ./vault --query "refund policy" --limit 5
+ssss semantic ./vault --query "política de reembolsos"
+ssss semantic ./vault --out ./derived/semantic.json
+```
+
+Records include stable identity, source path and hash, type, portability, surface
+text, normalized Unicode tokens, and graph edges derived from `relations`, wiki
+links, and Markdown links. Results use deterministic weighted lexical ranking; hosts
+may fuse embeddings without replacing this interoperable baseline.
+
+## Privacy and output safety
+
+Only `structural` documents are indexed by default. `tenant_private` and
+`resource_bound` sources require the explicit `--include-private` option and an
+authorized caller. This option can expose customer or operational data; never enable
+it for a public index.
+
+`--out` must point to a regular file outside the source vault. Writes are atomic.
+Symlinked vault entries and unsafe paths fail closed.
+
+## Library API
+
+```js
+import { buildSemanticIndex, searchSemanticIndex } from '@gregiteen/ssss-cli/semantic';
+
+const index = buildSemanticIndex('./vault');
+const results = searchSemanticIndex(index, 'reembolsos', { limit: 10 });
+```
+
+Hosts may inject a multilingual embedding adapter and runtime renderer. Presentation
+may change language and formatting, but never symbolic controls or authorization.

package/docs/ssss-spec.md

@@ -1,6 +1,6 @@
 # SSSS — Structured Semantic Syntax System
 
-**Specification v0.6 — Draft**
+**Specification v0.7 — Draft**
 
 > 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
@@ -31,6 +31,10 @@ 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 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,
 a chat runtime, and a workflow orchestrator is *which primitive types they read and
@@ -124,6 +128,17 @@ For OKF-compatible discovery, SSSS document primitives SHOULD also include:
 | `tags` | array | Array of string tags for categorization and routing. |
 | `aliases` | array | Array of alternative names for this concept, used for wiki autolinking. |
 
+For stable semantic identity and graph projection, documents SHOULD also include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `semantic_id` | string | Stable concept identity that survives file moves and localized presentation. |
+| `relations` | array | Explicit semantic edges to other vault-relative document paths or semantic ids. |
+| `locale` | string | BCP-47-style locale of the authored natural-language surface, when known. |
+
+`resource`, `tags`, and `aliases` serve both OKF discovery and the semantic layer.
+These fields are recommendations, not new universal requirements.
+
 Every primitive type defines its own additional REQUIRED and OPTIONAL fields
 (§5.4). To maintain forward compatibility and allow agents scratchpad space, hosts MUST NOT reject documents containing unknown frontmatter keys. Unknown fields MUST be preserved.
 
@@ -180,6 +195,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. |
+| `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
@@ -201,7 +217,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`).
+  `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`).
 
@@ -545,6 +561,14 @@ released_at: 2026-05-16T12:00:00Z
 ---
 ```
 
+#### `primitive`
+
+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
 
 A workspace is not one undifferentiated blob. Some of it is the **reusable business
@@ -1042,11 +1066,41 @@ run, plus an event explaining the terminal failure.
 
 #### Runtime Helpers
 
-The reference package exposes `@ssss/cli/runtime`, including deterministic helpers
+The reference package exposes `@gregiteen/ssss-cli/runtime`, including deterministic helpers
 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 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, 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,
+primitive type, portability class, surface text, normalized search tokens, and graph
+edges. Identity is resolved from `semantic_id`, then `resource`, then the source path.
+Edges are derived from explicit `relations`, wiki links, and Markdown links. Hosts MAY
+add embeddings or richer ranking, but the exact lexical/graph projection MUST remain
+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. 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.
+
 ---
 
 ## 12. Conformance
@@ -1061,6 +1115,11 @@ Fixtures are distributed as a JSON document carrying:
 - `idempotency` — TTL and replay behavior.
 - `validation_rules` — envelope and content rules.
 - `runtime_contract` — trigger vocabulary and daemon idempotency rules (§11.8).
+- registry-extension checks — schema shape, regex validity, symlink rejection, and
+  core/sibling collision rejection.
+- 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`.
 - `error_codes` — the canonical code table.
@@ -1068,7 +1127,8 @@ Fixtures are distributed as a JSON document carrying:
 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 `@ssss/cli/runtime`.
+  runtime checks exposed by `@gregiteen/ssss-cli/runtime`. Hosts exposing semantic
+  search or runtime rendering MUST also pass the §11.9 checks.
 
 ---
 
@@ -1096,7 +1156,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.6 — Draft**).
+- The spec version is stated in the document header (currently **v0.9 — Draft**).
 - 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.
@@ -1208,7 +1268,7 @@ them without a spec change.
   serialization of `files` (path-sorted, §16.1). An importer MUST recompute it and reject
   a bundle whose files do not match. This is what makes a bundle tamper-evident and what a
   marketplace lists against.
-- `exporter` — an identifier for the tool/host that produced the bundle (`"@ssss/cli@0.3.0"`).
+- `exporter` — an identifier for the tool/host that produced the bundle (`"@gregiteen/ssss-cli@0.8.0"`).
 - `signature` — OPTIONAL detached signature over `content_hash` for a sold bundle, so a
   buyer can verify authorship. Unsigned bundles are valid; signing is a marketplace concern.
 
@@ -1313,7 +1373,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`.
+`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.7.1",
+  "version": "0.9.0",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {
@@ -10,13 +10,31 @@
     "./registry": "./src/registry.mjs",
     "./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",
     "./package.json": "./package.json"
   },
   "bin": {
-    "ssss": "./scripts/ssss.mjs"
+    "ssss": "scripts/ssss.mjs"
   },
   "type": "module",
   "engines": {
@@ -24,11 +42,13 @@
   },
   "files": [
     "src",
+    "types",
     "scripts",
     "registry",
     "conformance",
     "docs/ssss-spec.md",
     "docs/help",
+    "skills/ssss",
     "VERSION",
     "README.md",
     "CHANGELOG.md",
@@ -46,7 +66,11 @@
     "vault",
     "operation-contract",
     "ucw",
-    "provisioning"
+    "provisioning",
+    "semantic-search",
+    "multilingual",
+    "generative-ui",
+    "application-kernel"
   ],
   "author": "Greg Iteen",
   "license": "ISC",