@gregiteen/ssss-cli 0.14.0 → 0.14.2

package/skills/ssss/SKILL.md

@@ -3,8 +3,8 @@ type: skill
 title: SSSS Protocol Reference
 name: ssss
 description: Validate or change SSSS documents, operations, registries, workflows and portable host adapters.
-timestamp: 2026-11-02T00:00:00Z
-version: 0.13.0
+timestamp: 2026-11-02T19:00:00Z
+version: 0.14.2
 repo_scoped: false
 ---
 

package/skills/ssss/core/SKILL.md

@@ -1,4 +1,4 @@
-# SSSS portable core — 0.13.0
+# 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.
 
@@ -10,9 +10,9 @@ Read only the relevant sections of the [normative spec](references/ssss-spec.md)
 Workflow triggers and standalone trigger documents are distinct canonical primitives. A standalone trigger targets a workflow template with parameters; workflows may own inline trigger definitions. Inspect the current registry/spec for required fields and enums. Use the installed runtime adapter to derive deterministic trigger/task/run operations; duplicate ticks replay through idempotency. A cron/interval/webhook/watcher is a wake-up mechanism, not a second scheduling database. Record observed task/run outcomes separately from declaration, enabled state and scheduler handled slots. Explicitly report unsupported host trigger types and missing execution capability.
 
 ## Bundles and adapters
-Preserve portability classes: structural definitions, tenant-private data and resource-bound requirements. Validate the complete import plan and references before commit, including forward references; missing references reject the import rather than weakening constraints. Check actual host authorization and adapter conformance; local fixtures do not prove provider execution. Use source-owned CLI help for flags and inspect structured validity, not process exit alone.
+Preserve portability classes: structural definitions, tenant-private data and resource-bound requirements. Validate the complete import plan and references before commit, including forward references and `x_bind` provisioning bindings (`--bind` / `--remap-ids`); missing references or unbound requirements reject the import rather than weakening constraints. Check actual host authorization (`@<glob>` path grants, core aliases `role` ↔ `security_role` and `thread` ↔ `conversation`), optimistic CAS (`expected_before_hash`), schema upgrades (`ssss upgrade`), and wire/MCP transport (`ssss serve`, `ssss bridge`); local fixtures do not prove provider execution. Use source-owned CLI help for flags and inspect structured validity, not process exit alone.
 
 ## 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.13.0 (`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.",
@@ -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/skills/ssss/core/references/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`.
 
@@ -957,6 +958,7 @@ An envelope is a JSON object:
   "path": "assistants/bot/ASSISTANT.md", // vault-relative, no leading "/", no "." or ".." segments
   "content": "---\ntype: …",       // operation: full document; event: JSON payload string
   "patches": { },                  // patch only
+  "expected_before_hash": "sha256:…", // OPTIONAL — asserts target content hash before mutation (§6.1)
   "primitive_type": "assistant",   // OPTIONAL — asserts the target's type
   "operation_id": "uuid",          // OPTIONAL — client-chosen; generated if absent
   "lease_id": "uuid",              // OPTIONAL — §7
@@ -970,6 +972,14 @@ verified principal, next to the envelope and never inside it (§6.6). A kernel
 MUST ignore any identity-bearing field a client places in the envelope, including
 the pre-0.9 `actor` object.
 
+A client or bundle provisioner MAY include `expected_before_hash` on an
+`operation` or `patch` envelope to assert that the target document has not been
+modified locally since the intended baseline was read. For a new document creation,
+`expected_before_hash` is `null`. For an update, it is the `sha256:...` digest of
+the baseline content. If the target document's current hash diverges from
+`expected_before_hash` (and its content is not already equal to the intended write),
+the kernel rejects the mutation with `version_conflict`.
+
 A `path` MUST be rejected with `invalid_request` if it is empty, absolute, contains
 a backslash or NUL, or has an empty, `.`, or `..` segment. A host MUST also refuse
 to follow a symbolic link out of the vault.
@@ -1016,7 +1026,7 @@ Kernels MUST NOT reorder or skip stages. Adapters (§6.7) implement mechanics on
 |---|-------|------------|
 | 1 | **Envelope & identity** — known `type`, required fields present and well-typed (§6.2); a principal with an `id` and `kind` is attached. Nothing is read before this passes, so an anonymous caller learns nothing about the vault. | `invalid_request`, `unauthorized` |
 | 2 | **Idempotency** — look up (`workspace_id`, `idempotency_key`). Same request hash: return the stored response with `replay: true` and stop. Different hash: stop (§6.4). | `idempotency_conflict` |
-| 3 | **Read current state** — load the target, if any, and its version. An unsafe path fails here. | `invalid_request`, or `internal_error` for unreadable stored state |
+| 3 | **Read current state & base-version check** — load the target, if any, and its version. An unsafe path fails here with `invalid_request`. If `expected_before_hash` is specified: if the target is absent and `expected_before_hash !== null`, or if the target exists and its hash does not match `expected_before_hash` (and its content differs from the intended write), reject with `version_conflict`. | `invalid_request`, `version_conflict`, or `internal_error` for unreadable stored state |
 | 4 | **Content validation** — resolve the primitive and validate the resulting document (§9). Enforce type immutability, `immutable_fields`, patch/delete target existence, and append-only rules. | `not_found`, `validation_failed` |
 | 5 | **Authorization** — the verified principal must be complete (§6.6), scoped to `workspace_id`, and hold every capability the primitive and action require. | `unauthorized`, `forbidden` |
 | 6 | **Lease** — if the primitive is `lease_required` or the host requires a lease for this path, verify it (§7). | `lease_conflict` |
@@ -1181,6 +1191,11 @@ envelope, after authenticating the caller:
   it ends in `:*` and the required capability starts with everything before that
   `*`. So `ssss:*` covers every core primitive and `ssss:assistant:*` covers every
   action on assistants.
+- A granted capability string MAY include an optional path selector separated by `@`:
+  `<capability>@<glob>` (for example, `ssss:rule:*@rules/marketing/**` or
+  `*:*@capabilities/messaging/**`). When a selector is present, the capability grants
+  permission only when the envelope's target path matches the glob pattern. When omitted,
+  the capability applies workspace-wide.
 - A `system` principal bypasses capability checks. It exists for trusted internal
   callers such as import (§17). A host MUST NOT grant `system` to anything a remote
   caller controls.
@@ -1215,6 +1230,73 @@ each with a shared contract test in the conformance suite (§12):
 "Across every writer" means across threads, processes, and hosts sharing the same
 storage, not just within one instance.
 
+### 6.8 HTTP/JSON Wire Protocol & Subprocess Bridge
+
+To enable portable, cross-language interoperation across diverse runtimes (Node.js, Python,
+Ruby, Go, Rust), SSSS defines a normative HTTP/JSON wire transport contract and a standard
+subprocess bridge. A host or engine that exposes SSSS over a network MUST conform to this
+wire contract.
+
+#### Endpoint & HTTP Headers
+
+- **Endpoint**: `POST /v1/operations` (hosts MAY also route `POST /` to this handler for convenience).
+- **Request Content-Type**: `application/json`.
+- **Response Content-Type**: `application/json`.
+- **Authentication**: When remote authentication is required, the client MUST present
+  a bearer token via the `Authorization: Bearer <token>` HTTP header. The host verifies
+  the token and resolves it out-of-band to a verified principal (§6.6). The envelope body
+  itself carries no secret credentials.
+- **Health check**: A host exposing the HTTP interface SHOULD expose `GET /health`, returning
+  HTTP 200 with `{ "ok": true, "version": "<version>" }`.
+
+#### Request and Response Wire Contract
+
+- **Request Body**: An Operation Contract envelope (§6.1, §6.2) as a JSON object:
+  ```json
+  {
+    "type": "operation",
+    "idempotency_key": "00000000-0000-0000-0000-000000000001",
+    "path": "assistants/support-bot.md",
+    "workspace_id": "ws-main",
+    "content": "---\ntype: assistant\nname: Support Bot\ntitle: Support Bot\ndescription: Customer support assistant\ntimestamp: 2026-07-02T00:00:00Z\n---\nHelp customers.\n"
+  }
+  ```
+  Callers attaching an explicit principal context MAY submit:
+  ```json
+  {
+    "envelope": {
+      "type": "operation",
+      "idempotency_key": "00000000-0000-0000-0000-000000000001",
+      "path": "assistants/support-bot.md",
+      "workspace_id": "ws-main",
+      "content": "---\ntype: assistant\nname: Support Bot\ntitle: Support Bot\ndescription: Customer support assistant\ntimestamp: 2026-07-02T00:00:00Z\n---\nHelp customers.\n"
+    },
+    "principal": {
+      "id": "agent-1",
+      "kind": "agent",
+      "workspaceIds": ["ws-main"],
+      "capabilities": ["*:*"],
+      "authentication": { "provider": "token", "assurance": "verified" }
+    }
+  }
+  ```
+- **Response Body**: The kernel response object (§6.5) serialized as JSON:
+  - On commit: `201 Created` with `{ "success": true, "type": "operation", ... }`.
+  - On idempotent replay or dry run: `200 OK` with `{ "success": true, "replay": true, ... }`.
+  - On error: status mapped from `ERROR_STATUS` (§6.5) with `{ "success": false, "error": { "code": "...", "message": "..." } }`.
+
+#### Subprocess Bridge Contract (`ssss bridge`)
+
+For local process orchestration without opening network ports (for example, Python hosts
+integrating SSSS as a subprocess), the reference CLI provides `ssss bridge`:
+
+- Reads JSON from standard input (`stdin`). Supports:
+  1. A single JSON request object.
+  2. A JSON array of requests (`[...]`).
+  3. Newline-delimited JSON (`NDJSON`), with one request per line when running with `--stream`.
+- Writes JSON response objects to standard output (`stdout`) matching the wire contract shape.
+- Does not alter envelope semantics, schema validation, or error status mappings.
+
 ---
 
 ## 7. Leases — Concurrency Control
@@ -1788,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
 
@@ -1868,6 +1952,23 @@ of `source: user` or `source: system` — e.g. the phone number, domain, and mai
 must bind. This is how the standard guarantees a sold business says exactly what real-world
 resources it needs without shipping the seller's own.
 
+#### 16.5.1 Frontmatter Parameter Binding (`x_bind`)
+
+Values bind exclusively through **frontmatter**, never through free-text string substitution in Markdown body text. A template document declares frontmatter parameter bindings using the reserved `x_bind` mapping:
+
+```yaml
+x_bind:
+  channel_id: support_channel_id
+  notify_email: primary_admin_email
+```
+
+During `provisionBundle` (§17.1):
+1. For each `field: parameter_key` entry in `x_bind`, the provisioner resolves the value from the supplied `parameters` dictionary, or the parameter's `defaultValue` if omitted.
+2. If a parameter is `required: true` and has no supplied value or default, provisioning fails with `unresolved`.
+3. The resolved value MUST match the parameter's declared `type` (`string`, `boolean`, `number`, etc.).
+4. The target frontmatter field is assigned the resolved value, and the `x_bind` property is stripped from the provisioned output document.
+5. In `template` and `sale` export profiles (§5.5), when `reduceResourceBoundFile()` strips sensitive infrastructure values from `resource.binds` (such as domain names or phone numbers), it automatically emits corresponding `x_bind` bindings targeting the synthesized resource requirement parameters.
+
 ---
 
 ## 17. The Provisioning Contract
@@ -1916,12 +2017,18 @@ binding each requires.
 ### 17.3 Determinism, Id-Remap & Link Integrity
 
 When a bundle is provisioned into a target vault, identifiers (slugs, workspace ids,
-cross-file links) are **remapped** so the imported business is a fresh, self-consistent
-instance rather than a clone aliasing the seller's ids. Remapping MUST preserve link
-integrity: every internal `[[link]]` / relative reference that resolved in the source bundle
-MUST resolve to the remapped target after import. This is the same rewrite engine the
-semantic layer's autolink (§11) uses, run with a bundle-relative id map. An importer that
-cannot resolve a link MUST fail the provision rather than emit a dangling reference.
+cross-file links, and typed references) are **remapped** so the imported business is a fresh, self-consistent
+instance rather than a clone aliasing the seller's ids.
+
+Given a target `workspaceId` and optional `pathPrefix`:
+1. **Deterministic ID Map:** Every source identifier or slug derives a deterministic target identifier:
+   `newId = "<pathPrefix>-" + sha256(workspaceId + ":" + sourceId).slice(0, 12)`
+2. **Path Prefixing:** Target file paths are placed under the path prefix:
+   `targetPath = pathPrefix ? `${pathPrefix}/${sourcePath}` : sourcePath`
+3. **Identifier Fields:** Frontmatter identifier fields (`slug`, `id`, `workflow_id`, `run_id`, `task_id`, `migration_id`) are mapped to their derived `newId`.
+4. **Link Rewriting:** Body wiki-links `[[source-slug]]` and relative Markdown links `[title](source-path.md)` are rewritten to the target slug and target relative path.
+5. **Registry-Declared Typed References (§9):** Frontmatter fields constrained by `references` (e.g. `asset.resource_ref`, `trigger.target_workflow`) that point to relative paths within the bundle MUST be rewritten to point to their remapped target paths under `pathPrefix`.
+6. **Link & Reference Integrity:** Remapping MUST preserve link integrity: every internal `[[link]]`, relative markdown link, and typed frontmatter reference that resolved in the source bundle MUST resolve to the remapped target after import. An importer that cannot resolve a link or reference MUST fail the provision (`danglingLinks`) rather than emit a dangling reference.
 
 ### 17.4 Composition & Upgrade
 
@@ -1946,6 +2053,7 @@ MUST NOT be repurposed by hosts:
   `aliases`, `feedback`, `confidence`.
 - Lifecycle: `slug`, `schema_version`, `status`.
 - Portability (§5.5): `x_portability`.
+- Parameter Binding (§16.5): `x_bind`.
 
 The patch key `__body__` (§6.2) is reserved and can never be a frontmatter key.
 

package/src/authorization.mjs

@@ -65,17 +65,45 @@ export function createCapabilityAuthorizer(options = {}) {
     if (principal.kind !== 'system' && !principal.workspaceIds.includes(workspaceId)) {
       return { allowed: false, reason: `Principal '${principal.id}' is not scoped to workspace '${workspaceId}'.` };
     }
-    const floorKey = definition?.qualified_type || definition?.primitive_id || definition?.type;
+    const namespace = definition?.namespace || 'ssss';
+    const aliases = Array.isArray(definition?.aliases) ? definition.aliases : [];
+    const floorKeys = new Set(
+      [
+        definition?.qualified_type,
+        definition?.primitive_id,
+        definition?.type,
+        ...aliases.flatMap((alias) => [
+          alias,
+          alias.includes(':') ? alias : `${namespace}:${alias}`,
+        ]),
+      ].filter(Boolean),
+    );
+    const floorCapabilities = [...floorKeys].flatMap((key) => policyFloors[key]?.[action] || []);
     const required = new Set([
       ...requiredCapabilities(definition, action),
-      ...(policyFloors[floorKey]?.[action] || []),
+      ...floorCapabilities,
       ...(context.policyFloor || []),
     ]);
     const granted = new Set(principal.capabilities || []);
     if (principal.kind === 'system' && options.systemBypass !== false) return { allowed: true, required: [...required] };
     const targetPath = context.path || null;
+    const defPrefixes = [...new Set([definition?.qualified_type, definition?.primitive_id, definition?.type].filter(Boolean))];
     const missing = [...required].filter((capability) =>
-      ![...granted].some((grant) => capabilityCovers(grant, capability, targetPath)));
+      ![...granted].some((grant) => {
+        if (capabilityCovers(grant, capability, targetPath)) return true;
+        if (!aliases.length) return false;
+        const matchedPrefix = defPrefixes.find((prefix) => capability.startsWith(`${prefix}:`));
+        if (!matchedPrefix) return false;
+        const actionTail = capability.slice(matchedPrefix.length + 1);
+        return aliases.some((alias) => {
+          const qualifiedAlias = alias.includes(':') ? alias : `${namespace}:${alias}`;
+          const bareAlias = alias.includes(':') ? alias.slice(alias.indexOf(':') + 1) : alias;
+          return (
+            capabilityCovers(grant, `${qualifiedAlias}:${actionTail}`, targetPath) ||
+            capabilityCovers(grant, `${bareAlias}:${actionTail}`, targetPath)
+          );
+        });
+      }));
     if (missing.length) return { allowed: false, required: [...required], missing, reason: `Missing capabilities: ${missing.join(', ')}.` };
     if (context.requiresHumanConfirmation && principal.kind !== 'human') {
       return { allowed: false, required: [...required], reason: 'A verified human confirmation is required.' };

package/src/engine.mjs

@@ -39,7 +39,17 @@ export function legacyRoleCapabilities(permissions, registrySet) {
     if (permission === 'write:*' || permission === '*:*') { capabilities.add('*:*'); continue; }
     const match = permission.match(/^(write|\*):(.+)$/);
     const definition = match && resolvePrimitiveDefinition(registrySet, match[2]);
-    if (definition?.qualified_type) capabilities.add(`${definition.qualified_type}:*`);
+    if (definition?.qualified_type) {
+      capabilities.add(`${definition.qualified_type}:*`);
+      const prefix = definition.qualified_type.includes(':')
+        ? definition.qualified_type.split(':')[0]
+        : 'ssss';
+      for (const alias of definition.aliases || []) {
+        capabilities.add(`${prefix}:${alias}:*`);
+        capabilities.add(`write:${alias}`);
+        capabilities.add(`*:${alias}`);
+      }
+    }
   }
   return [...capabilities];
 }

package/src/kernel.mjs

@@ -5,7 +5,7 @@
 import crypto from 'node:crypto';
 import { parseDocument, serializeDocument } from './frontmatter.mjs';
 import { createValidator } from './validator.mjs';
-import { isAppendType, isSafeDocumentPath, resolvePortability, resolvePrimitiveDefinition } from './registry.mjs';
+import { isAppendType, isSafeDocumentPath, resolvePortability, resolvePrimitiveDefinition, isSamePrimitiveType } from './registry.mjs';
 import { createCapabilityAuthorizer, validateVerifiedPrincipal } from './authorization.mjs';
 import { createCanonicalEvent, idempotentEventId } from './events.mjs';
 import { MemoryIdempotencyStore } from './idempotency.mjs';
@@ -284,7 +284,7 @@ export function createKernel(options = {}) {
         nextContent = envelope.content;
         nextData = validation.data;
       }
-      if (currentData?.type && currentData.type !== nextData.type) {
+      if (currentData?.type && !isSamePrimitiveType(registrySet, currentData.type, nextData.type)) {
         return failure('validation_failed', envelope, operationId, ['Operation may not change an existing document type.'], [{ field: 'type', issue: 'Use an explicit migration.' }]);
       }
       // Replaying an identical full operation is a no-op, not a replace. This must
@@ -317,7 +317,7 @@ export function createKernel(options = {}) {
       if (!current) return failure('not_found', envelope, operationId, ['Patch target does not exist.'], [{ field: 'path', issue: 'Target not found.' }]);
       definition = resolvePrimitiveDefinition(registrySet, declaredType);
       if (!definition) return failure('validation_failed', envelope, operationId, [`Unknown SSSS primitive '${declaredType}'.`], [{ field: 'type', issue: 'Unknown primitive.' }]);
-      if (Object.hasOwn(envelope.patches, 'type') && envelope.patches.type !== currentData.type) {
+      if (Object.hasOwn(envelope.patches, 'type') && !isSamePrimitiveType(registrySet, envelope.patches.type, currentData.type)) {
         return failure('validation_failed', envelope, operationId, ['Patch may not change document type.'], [{ field: 'type', issue: 'Use an explicit migration.' }]);
       }
       nextData = { ...currentData, ...Object.fromEntries(Object.entries(envelope.patches).filter(([key]) => key !== '__body__')) };

package/src/registry.mjs

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_REGISTRY_DIR = path.resolve(__dirname, '..', 'registry');
 
-const APPEND_TYPES = new Set(['conversation', 'run']);
+const APPEND_TYPES = new Set(['conversation', 'run', 'thread']);
 const SAFE_REGISTRY_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
 const SAFE_TYPE_NAME = /^(?:[a-z][a-z0-9_-]{0,63}:)?[a-z][a-z0-9_-]{0,127}$/;
 const SAFE_FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
@@ -52,6 +52,13 @@ function validatePrimitiveDefinition(name, def, source, portabilityClasses) {
   assertStringArray(def.required_fields, `${source}: primitive '${name}' required_fields`);
   assertStringArray(def.optional_fields, `${source}: primitive '${name}' optional_fields`);
   assertStringArray(def.immutable_fields, `${source}: primitive '${name}' immutable_fields`);
+  assertStringArray(def.aliases, `${source}: primitive '${name}' aliases`);
+  if (def.deprecated !== undefined && typeof def.deprecated !== 'boolean') {
+    throw new Error(`${source}: primitive '${name}' deprecated must be a boolean.`);
+  }
+  if (def.deprecation_notice !== undefined && typeof def.deprecation_notice !== 'string') {
+    throw new Error(`${source}: primitive '${name}' deprecation_notice must be a string.`);
+  }
 
   assertRecord(def.required_when, `${source}: primitive '${name}' required_when`);
   for (const [condition, fields] of Object.entries(def.required_when || {})) {
@@ -157,6 +164,33 @@ export function composeRegistries({ core, extensions: extensionInputs = [] } = {
     aliases.set(`ssss:${name}`, name);
   }
 
+  for (const [name, def] of Object.entries(core.document_primitives || {})) {
+    for (const alias of def.aliases || []) {
+      if (!isPrimitiveTypeName(alias)) {
+        throw new Error(`core registry: primitive '${name}' has unsafe alias '${alias}'.`);
+      }
+      const bareAlias = alias.startsWith('ssss:') ? alias.slice('ssss:'.length) : alias;
+      const qualifiedAlias = alias.includes(':') ? alias : `ssss:${alias}`;
+      if (bareAlias === name) {
+        throw new Error(`core registry: primitive '${name}' cannot alias itself.`);
+      }
+      if (types.has(bareAlias)) {
+        const peer = types.get(bareAlias);
+        const peerAliases = (peer.aliases || []).map((a) => (a.startsWith('ssss:') ? a.slice('ssss:'.length) : a));
+        if (!peerAliases.includes(name)) {
+          throw new Error(`core registry: primitive alias '${alias}' on '${name}' collides with existing primitive '${bareAlias}'.`);
+        }
+        continue;
+      }
+      if ((aliases.has(bareAlias) && aliases.get(bareAlias) !== name) ||
+          (aliases.has(qualifiedAlias) && aliases.get(qualifiedAlias) !== name)) {
+        throw new Error(`core registry: primitive alias '${alias}' collides with an existing primitive.`);
+      }
+      aliases.set(bareAlias, name);
+      aliases.set(qualifiedAlias, name);
+    }
+  }
+
   for (const [index, item] of extensionInputs.entries()) {
     const { source, value: ext } = normalizeExtensionInput(item, index);
     if (!SAFE_REGISTRY_NAME.test(ext.registry || '')) {
@@ -232,6 +266,14 @@ export function composeRegistries({ core, extensions: extensionInputs = [] } = {
           );
         }
       }
+      const aliasOverlap = (constraint.allowed_types || []).filter((allowed) =>
+        (constraint.disallowed_types || []).some((disallowed) => isSamePrimitiveType(registrySet, allowed, disallowed))
+      );
+      if (aliasOverlap.length) {
+        throw new Error(
+          `registry '${def.registry}' primitive '${def.type}' reference '${field}' both allows and forbids (via alias): ${aliasOverlap.join(', ')}.`
+        );
+      }
     }
   }
 
@@ -297,6 +339,42 @@ export function resolvePrimitiveDefinition(registrySet, type) {
   return local ? registrySet.types.get(local) || null : null;
 }
 
+/**
+ * Return all equivalent primitive definitions for a type or definition
+ * (the definition itself plus any definitions linked via `aliases`).
+ */
+export function resolveEquivalentDefinitions(registrySet, typeOrDef) {
+  const base = typeof typeOrDef === 'string'
+    ? resolvePrimitiveDefinition(registrySet, typeOrDef)
+    : typeOrDef;
+  if (!base) return [];
+  const seen = new Map([[base.qualified_type || base.type, base]]);
+  for (const alias of base.aliases || []) {
+    const target = resolvePrimitiveDefinition(registrySet, alias);
+    if (target && !seen.has(target.qualified_type || target.type)) {
+      seen.set(target.qualified_type || target.type, target);
+    }
+  }
+  return [...seen.values()];
+}
+
+/**
+ * Return true if two primitive type identifiers resolve to the same canonical
+ * primitive definition (either exact match, qualified match, or mutual alias).
+ */
+export function isSamePrimitiveType(registrySet, typeA, typeB) {
+  if (typeA === typeB) return true;
+  if (!typeA || !typeB) return false;
+  const defA = resolvePrimitiveDefinition(registrySet, typeA);
+  const defB = resolvePrimitiveDefinition(registrySet, typeB);
+  if (!defA || !defB) return false;
+  if (defA.qualified_type === defB.qualified_type) return true;
+  const equivalentsA = resolveEquivalentDefinitions(registrySet, defA);
+  if (equivalentsA.some((d) => d.qualified_type === defB.qualified_type)) return true;
+  const equivalentsB = resolveEquivalentDefinitions(registrySet, defB);
+  return equivalentsB.some((d) => d.qualified_type === defA.qualified_type);
+}
+
 /**
  * Names of the extensions loaded when a caller does not scope the load.
  *
@@ -472,14 +550,15 @@ export function validateReferenceConstraints(typeDef, data, resolveReference, ty
       continue;
     }
     const referencedType = referenced.data?.type;
+    const registrySurface = { types, aliases: types.aliases };
     if (!lookupType(referencedType)) {
       issues.push({ field, issue: `Referenced document declares unknown type '${referencedType || '(missing)'}'.` });
       continue;
     }
-    if (constraint.allowed_types && !constraint.allowed_types.includes(referencedType)) {
+    if (constraint.allowed_types && !constraint.allowed_types.some((allowed) => isSamePrimitiveType(registrySurface, allowed, referencedType))) {
       issues.push({ field, issue: `Referenced type '${referencedType}' is not allowed.` });
     }
-    if (constraint.disallowed_types?.includes(referencedType)) {
+    if (constraint.disallowed_types?.some((disallowed) => isSamePrimitiveType(registrySurface, disallowed, referencedType))) {
       issues.push({ field, issue: `Referenced type '${referencedType}' is forbidden.` });
     }
     const referencedPortability = resolvePortability(lookupType(referencedType), referenced.data);