@gregiteen/ssss-cli 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.2] - 2026-11-02
+### Added
+- **Canonical JSON Schema Draft 2020-12 Definitions (`JSON_SCHEMA_EXPORT`)**:
+  - `schemas/core-registry.schema.json`: Formal JSON Schema Draft 2020-12 defining the full structure of `registry/core.json` and extension registries (document primitives, contract primitives, universal frontmatter, portability classes and export profiles, bundle manifest specifications, provisioning steps and relations, runtime contracts, and semantic search fields).
+  - `schemas/bundle.schema.json`: Formal JSON Schema Draft 2020-12 defining the container format for Universal Cloud Workspace (`.ucw`) transport bundles, covering `manifest`, `files`, `dependencies`, `parameters`, `provisioning`, `provenance`, and optional `branding`.
+  - `registry/core.json`: Updated `$schema` URI to point to `https://ssss.dev/schemas/core-registry.schema.json`.
+- **Zero-Dependency Schema Validation**:
+  - `src/schema-validator.mjs`: High-performance, recursive JSON Schema Draft 2020-12 validator in pure Node ESM supporting `type` unions, `properties`, `additionalProperties`, `required`, `items`, `enum`, `pattern`, and local `$defs`/`$ref` pointers.
+  - Exported `./schema-validator` and `./schemas/*` via package exports and added `"schemas"` to npm package distribution files.
+- **CLI Schema Inspection & Export**:
+  - `scripts/cmd-schema.mjs`: Added `ssss schema core`, `ssss schema bundle`, and `ssss schema export [--out <dir>]` subcommands to output and export canonical JSON Schemas.
+- **Automated Conformance Sweeps**:
+  - `scripts/conformance-09.mjs`: Integrated automated schema validation checks into continuous test suites, verifying `registry/core.json` and `conformance/reference-bundle.ucw.json` against canonical schemas with negative mutation testing.
+- **Specification and Backlog Hygiene**:
+  - `docs/ssss-spec.md`: Documented canonical JSON Schema references in §5.1 and §16.1.
+  - Resolved and closed all outstanding host deferral items in `docs/projects/DEFERRED_BACKLOG.md`.
+
+### Behavior changes hosts should check
+- Tools and IDEs may validate `registry/core.json` and `.ucw` bundle files directly against `schemas/core-registry.schema.json` and `schemas/bundle.schema.json`.
+- The CLI command `ssss schema export` is now available to export canonical schema definitions for external consumption.
+
+## [0.14.1] - 2026-11-02
+### Added
+- **Core primitive aliasing (`role` ↔ `security_role`, `thread` ↔ `conversation`)**:
+  - `registry/core.json`: Reciprocal `aliases` declared on `role` (`security_role`) and `thread` (`conversation`).
+  - `src/registry.mjs`: `composeRegistries()` executes two passes to register and validate core primitive aliases, enforcing mutual symmetry when aliasing existing primitives, rejecting self-aliases, and disallowing collisions with unrelated primitives.
+  - `src/registry.mjs`: `resolveEquivalentDefinitions()` and `isSamePrimitiveType()` resolve equivalence across canonical and alias types.
+  - `src/registry.mjs`: `validateReferenceConstraints()` resolves `allowed_types` and `disallowed_types` across primitive aliases.
+  - `src/kernel.mjs`: Operation replace and patch type-mutation guards accept equivalent primitive aliases transparently without requiring an explicit migration.
+  - `src/engine.mjs`: `legacyRoleCapabilities()` expands permissions across declared aliases for `role` and `security_role`.
+  - `src/authorization.mjs`: `createCapabilityAuthorizer()` enforces `policyFloors` across primitive aliases and matches capability grants across aliases for primitive actions.
+- **Core primitive deprecation metadata**:
+  - `registry/core.json`: Declared `"deprecated": true` and `"deprecation_notice"` on inert primitives `release`, `model`, `page`, and `conflict`.
+  - `src/registry.mjs`: `validatePrimitiveDefinition()` validates optional boolean `deprecated` and string `deprecation_notice`.
+  - `docs/ssss-spec.md`: Documented core primitive aliases (§5.1, §5.3, §5.4) and deprecation metadata.
+  - Synchronized managed portable core SSSS skill package (`skills/ssss/`, `.agent/skills/ssss/`) with `0.14.1` reference materials.
+
+### Behavior changes hosts should check
+- Replacing or patching a document from `role` to `security_role` (or `security_role` to `role`), or `thread` to `conversation`, is now accepted by kernel type-mutation guards.
+- Reference constraints with `allowed_types: ["role"]` accept targets of type `security_role`, and `disallowed_types: ["role"]` reject targets of type `security_role`.
+- Policy floors configured on `ssss:role` or `role` are applied when mutating documents of type `security_role`.
+
 ## [0.14.0] - 2026-11-02
 ### Added
 - **Parameter bindings & Resource bindings (D2, D4)**: `provisionBundle` supports `x_bind` in template frontmatter and resource bindings (`bindings` array with `relation`, `field`, `mode`), with type validation and parameter substitution.

package/VERSION

@@ -1 +1 @@
-0.14.0
+0.14.2

package/conformance/reference-bundle.ucw.json

@@ -106,7 +106,7 @@
     "file_count": 14,
     "provenance": {
       "content_hash": "sha256:7febd673938a3dc04c068e0bf08097a9783c09e612606d2df9a4db8dcb8907f5",
-      "exporter": "@gregiteen/ssss-cli@0.14.0"
+      "exporter": "@gregiteen/ssss-cli@0.14.2"
     }
   },
   "files": [

package/docs/ssss-spec.md

@@ -250,19 +250,20 @@ primitive — it implements the subset its product requires — but any primitiv
 | `assistant` | actor | structural | The definition of an AI assistant/persona. |
 | `workflow` | work | structural | A reusable **task template**: a defined procedure. Firing a workflow submits a `task`. |
 | `trigger` | work | structural | A standalone schedule or event-driven trigger that fires a workflow. |
-| `model` | catalog | structural | The definition of an inference model. |
+| `model` | catalog | structural | The definition of an inference model (deprecated). |
 | `thread` | transcript | tenant_private | An append-only chat transcript. |
 | `conversation` | transcript | tenant_private | An append-only chat transcript. Legacy alias of `thread`. |
 | `run` | transcript | tenant_private | An append-only workflow execution record. |
-| `conflict` | meta | tenant_private | A record of two contradicting primitives, blocking promotion. |
-| `page` | capability | structural | A VFS-native sandboxed custom workspace page. |
+| `conflict` | meta | tenant_private | A record of two contradicting primitives, blocking promotion (deprecated). |
+| `page` | capability | structural | A VFS-native sandboxed custom workspace page (deprecated). |
 | `migration` | meta | structural | An SSSS schema migration state record. |
-| `release` | meta | structural | An SSSS system schema version release record. |
+| `release` | meta | structural | An SSSS system schema version release record (deprecated). |
 | `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
 
@@ -282,7 +283,7 @@ Document primitives are either:
   entirely (`memory`, `skill`, `rule`, `security_role`, `task`, `assistant`,
   `workflow`, `model`, `conflict`, `page`, `migration`, `release`, `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`).
+  the body and MUST NOT rewrite prior records (`thread`, `conversation`, `run`).
 
 Append-type documents MUST be mutated only by appending. A host MUST reject an
 operation that would rewrite or remove existing records of an append-type document.
@@ -629,7 +630,7 @@ Maintains support assistants and records support events.
 
 #### `model`
 
-The definition of an inference model.
+The definition of an inference model. Deprecated: inert catalog primitive; modern hosts configure models through provider runtime settings.
 
 REQUIRED: `type`, `model_id`, `provider`.
 
@@ -731,7 +732,7 @@ Collected 12 messages.
 
 #### `conflict`
 
-A record of two contradicting primitives. Blocks promotion until resolved.
+A record of two contradicting primitives. Blocks promotion until resolved. Deprecated: inert meta primitive; memory collision handling is managed by host memory kernels.
 
 REQUIRED: `type`, `conflict_id`, `status` (`pending|resolved`), `new_slug`,
 `existing_slug`, `detected_at`.
@@ -752,7 +753,7 @@ detected_at: 2026-05-16T18:30:00Z
 
 #### `page`
 
-A VFS-native sandboxed custom workspace page.
+A VFS-native sandboxed custom workspace page. Deprecated: inert sandbox primitive with iframe assumptions; superseded by asset and modern UI primitives.
 
 REQUIRED: `type`, `slug`, `name`, `sandbox_entry`.
 
@@ -791,7 +792,7 @@ description: "Add vector_embedding field"
 
 #### `release`
 
-An SSSS system schema version release.
+An SSSS system schema version release. Deprecated: inert meta primitive; release tracking is managed by bundle and package manifests.
 
 REQUIRED: `type`, `release_id`, `version`, `schema_version`, `summary`, `released_at`.
 
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {
@@ -32,6 +32,8 @@
     "./conformance/fixtures.json": "./conformance/fixtures.json",
     "./conformance/reference-bundle.ucw.json": "./conformance/reference-bundle.ucw.json",
     "./registry/core.json": "./registry/core.json",
+    "./schema-validator": "./src/schema-validator.mjs",
+    "./schemas/*": "./schemas/*",
     "./package.json": "./package.json"
   },
   "bin": {
@@ -43,6 +45,7 @@
   },
   "files": [
     "src",
+    "schemas",
     "types",
     "scripts",
     "registry",

package/registry/core.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.",
@@ -87,6 +87,7 @@
       "portability": "structural",
       "required_fields": ["type", "name", "permissions"],
       "optional_fields": ["description"],
+      "aliases": ["security_role"],
       "notes": "A named set of capabilities used for role-based access control (RBAC). Canonical form of security_role.",
       "spec_ref": "§5.4 role"
     },
@@ -97,6 +98,8 @@
       "portability": "structural",
       "required_fields": ["type", "name", "permissions"],
       "optional_fields": ["description"],
+      "aliases": ["role"],
+      "notes": "A named set of capabilities used for role-based access control (RBAC). Legacy alias of role.",
       "spec_ref": "§5.4 security_role"
     },
     "task": {
@@ -149,6 +152,8 @@
       "append_only": false,
       "portability": "structural",
       "required_fields": ["type", "model_id", "provider"],
+      "deprecated": true,
+      "deprecation_notice": "Inert catalog primitive. Modern hosts configure models through provider runtime settings.",
       "spec_ref": "§5.4 model"
     },
     "thread": {
@@ -158,6 +163,7 @@
       "portability": "tenant_private",
       "required_fields": ["type", "thread_id"],
       "optional_fields": ["workspace_id", "user_id", "status", "turn_count", "created_at"],
+      "aliases": ["conversation"],
       "notes": "An append-only multi-turn chat transcript. Canonical form of conversation.",
       "spec_ref": "§5.4 thread"
     },
@@ -167,6 +173,8 @@
       "append_only": true,
       "portability": "tenant_private",
       "required_fields": ["type", "thread_id"],
+      "aliases": ["thread"],
+      "notes": "An append-only multi-turn chat transcript. Legacy alias of thread.",
       "spec_ref": "§5.4 conversation"
     },
     "run": {
@@ -186,6 +194,8 @@
       "portability": "tenant_private",
       "required_fields": ["type", "conflict_id", "status", "new_slug", "existing_slug", "detected_at"],
       "enums": { "status": ["pending", "resolved"] },
+      "deprecated": true,
+      "deprecation_notice": "Inert meta primitive. Memory collision handling is managed by host memory kernels.",
       "spec_ref": "§5.4 conflict"
     },
     "page": {
@@ -194,6 +204,8 @@
       "append_only": false,
       "portability": "structural",
       "required_fields": ["type", "slug", "name", "sandbox_entry"],
+      "deprecated": true,
+      "deprecation_notice": "Inert sandbox primitive with iframe assumptions. Superseded by asset and modern UI primitives.",
       "spec_ref": "§5.4 page"
     },
     "migration": {
@@ -210,6 +222,8 @@
       "append_only": false,
       "portability": "structural",
       "required_fields": ["type", "release_id", "version", "schema_version", "summary", "released_at"],
+      "deprecated": true,
+      "deprecation_notice": "Inert meta primitive. Release tracking is managed by bundle and package manifests.",
       "spec_ref": "§5.4 release"
     },
     "primitive": {

package/schemas/bundle.schema.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ssss.dev/schemas/bundle.schema.json",
+  "title": "SSSS Universal Cloud Workspace (.ucw) Bundle Schema",
+  "description": "JSON Schema for SSSS transport bundles and manifests (spec §16).",
+  "type": "object",
+  "required": [
+    "manifest",
+    "files"
+  ],
+  "properties": {
+    "manifest": {
+      "$ref": "#/$defs/bundleManifest"
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/bundleFile"
+      }
+    },
+    "branding": {
+      "type": "object"
+    }
+  },
+  "$defs": {
+    "bundleFile": {
+      "type": "object",
+      "required": [
+        "path",
+        "content"
+      ],
+      "properties": {
+        "path": {
+          "type": "string"
+        },
+        "content": {
+          "type": "string"
+        }
+      }
+    },
+    "bundleManifest": {
+      "type": "object",
+      "required": [
+        "name",
+        "description",
+        "version",
+        "exported_at",
+        "ssss_core_version",
+        "required_extensions",
+        "export_profile",
+        "primitive_inventory",
+        "provisioning",
+        "file_count",
+        "provenance"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "exported_at": {
+          "type": "string"
+        },
+        "ssss_core_version": {
+          "type": "string"
+        },
+        "required_extensions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "export_profile": {
+          "type": "string",
+          "enum": ["backup", "template", "sale"]
+        },
+        "primitive_inventory": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer"
+          }
+        },
+        "dependencies": {
+          "type": "object",
+          "properties": {
+            "primitives": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "extensions": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "migrations": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "integrity": {
+              "type": "object",
+              "properties": {
+                "content_hash": { "type": "string" },
+                "ssss_core_version": { "type": "string" }
+              }
+            },
+            "bundles": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": { "type": "string" },
+                  "name": { "type": "string" },
+                  "version": { "type": "string" },
+                  "installMode": {
+                    "type": "string",
+                    "enum": ["optional", "recommended", "required"]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "provisioning": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/provisioningStep"
+          }
+        },
+        "parameters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/provisioningParameter"
+          }
+        },
+        "file_count": {
+          "type": "integer"
+        },
+        "provenance": {
+          "type": "object",
+          "required": [
+            "content_hash",
+            "exporter"
+          ],
+          "properties": {
+            "content_hash": {
+              "type": "string"
+            },
+            "exporter": {
+              "type": "string"
+            },
+            "signature": {
+              "type": "string"
+            }
+          }
+        },
+        "source_workspace_id": {
+          "type": "string"
+        },
+        "branding": {
+          "type": "object"
+        }
+      }
+    },
+    "provisioningStep": {
+      "type": "object",
+      "required": [
+        "id",
+        "label",
+        "system",
+        "mode",
+        "required"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "system": {
+          "type": "string",
+          "enum": [
+            "workspace",
+            "branding",
+            "email",
+            "phone",
+            "domains",
+            "accounts",
+            "deployments",
+            "marketplace",
+            "tabs",
+            "automation"
+          ]
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "existing",
+            "provision",
+            "install",
+            "generate",
+            "configure"
+          ]
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "provisioningParameter": {
+      "type": "object",
+      "required": [
+        "key",
+        "label",
+        "type",
+        "scope",
+        "source"
+      ],
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "scope": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string",
+          "enum": ["user", "llm", "graph", "system"]
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "description": {
+          "type": "string"
+        },
+        "defaultValue": {},
+        "options": {
+          "type": "array"
+        },
+        "dependsOn": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}