@gregiteen/ssss-cli 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.
+- **Deterministic ID, slug, and link remapping (D3)**: Target workspace and path isolation with automatic Markdown link and typed references rewriting.
+- **Topological dependency resolution (D5)**: Bundles declare dependencies via `manifest.dependencies.bundles` (`required`, `recommended`, `optional`). Dependencies are resolved in topological order with circular dependency detection.
+- **Base-version precondition & conflict protection (D8)**: `importBundle` assigns `expected_before_hash`; kernel enforces match at Stage 3, preventing regression of concurrent local edits.
+- **Structural bundle upgrade (D6)**: `upgradeBundle` and `ssss upgrade` CLI produce structural patches and `migration` primitive records; engine fail-closed refusal of `tenant_private` targets for upgrade envelopes.
+- **Cross-language HTTP wire protocol & reference server (G3)**: Spec §6.8 HTTP wire transport, `ssss serve` reference server with bearer token authentication (`Authorization: Bearer <token>`), health check (`GET /health`), and canonical HTTP status mapping matching `ERROR_STATUS`.
+- **Subprocess stdin-JSON bridge (G3)**: `ssss bridge` command for non-JS hosts (e.g. Python Dabber CRM), supporting single JSON object, JSON array batch, and streaming NDJSON with `--stream`.
+- **Projection adapter conformance suite (G4)**: `runProjectionContract` in `@gregiteen/ssss-cli/projections` and `projection_memory` in `ssss adapter conformance`, covering log rebuild, incremental apply parity, drift detection, and replay idempotency.
+- **Path-scoped capability grants (G5)**: Capability authorizer supports `<capability>@<glob>` format (e.g. `ssss:rule:*@rules/marketing/**`) enforced at Stage 5 authorization.
+
+### Behavior changes hosts should check
+- `provisionBundle` returns `{ manifest, envelopes, bindings, dependencies, unmappedLinks }`. An unbound required resource fails provisioning unless `dryRun: true`.
+- Envelopes with `envelope.intent === 'upgrade'` targeting `tenant_private` documents are rejected with `forbidden`.
+- `importBundle` envelopes include `expected_before_hash` when the source document existed at export time.
+
 ## [0.13.1] - 2026-11-02
 ### Changed
 - No change to the package's code, registry, spec or bundled skill. This

package/VERSION

@@ -1 +1 @@
-0.13.1
+0.14.0

package/conformance/reference-bundle.ucw.json

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

package/docs/ssss-spec.md

@@ -957,6 +957,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 +971,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 +1025,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 +1190,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 +1229,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
@@ -1868,6 +1949,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 +2014,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 +2050,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gregiteen/ssss-cli",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "CLI tools and the reference engine for the Structured Semantic Syntax System",
   "main": "src/engine.mjs",
   "exports": {

package/scripts/cmd-adapter.mjs

@@ -6,6 +6,7 @@ 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 { MemoryIntentJournal, FileIntentJournal, runIntentJournalContract } from '../src/intents.mjs';
+import { createSqlProjectionAdapter, runProjectionContract } from '../src/projections.mjs';
 import { parseArgs, die, wantsHelp } from './lib/cli.mjs';
 
 export async function run(argv) {
@@ -23,6 +24,7 @@ export async function run(argv) {
       idempotency_filesystem: await runIdempotencyContract(new FileIdempotencyStore(path.join(root, 'idempotency'))),
       intent_journal_memory: await runIntentJournalContract(new MemoryIntentJournal()),
       intent_journal_filesystem: await runIntentJournalContract(new FileIntentJournal(path.join(root, 'intents'))),
+      projection_memory: await runProjectionContract(createSqlProjectionAdapter),
     };
     const report = { version: 1, passed: Object.values(suites).every((suite) => suite.passed), suites };
     const text = `${JSON.stringify(report, null, 2)}\n`;

package/scripts/cmd-bridge.mjs

@@ -0,0 +1,113 @@
+/**
+ * ssss bridge — stdin-to-stdout JSON bridge for the SSSS Operation Contract (spec §6.8).
+ * Enables non-JavaScript hosts (e.g. Python, Ruby, Go, shell) to execute operations
+ * without running an HTTP server or maintaining custom node runners.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { createEngine } from '../src/engine.mjs';
+import { parseArgs, wantsHelp } from './lib/cli.mjs';
+
+export async function run(argv) {
+  if (wantsHelp(argv)) {
+    console.log(`Usage: ssss bridge [options]
+
+Execute Operation Contract requests from stdin and emit JSON responses to stdout.
+Accepts a single JSON object, a JSON array of requests, or newline-delimited JSON (NDJSON).
+
+Options:
+  --vault <dir>       Path to the target vault directory (default: '.')
+  --registry <dir>    Path to registry directory
+  --extension <file>  Path to extension registry file
+  --stream            Process input as continuous newline-delimited JSON stream
+  --help, -h          Show help`);
+    return;
+  }
+
+  const { flags } = parseArgs(argv, { booleans: ['stream'] });
+  const vaultRoot = path.resolve(flags.vault || '.');
+  const engine = createEngine({
+    registryDir: flags.registry,
+    extensionFile: flags.extension,
+  });
+
+  const processOne = async (payload) => {
+    const envelope = payload?.envelope || payload;
+    const callOptions = {};
+    if (payload?.principal) callOptions.principal = payload.principal;
+    try {
+      return await engine.processOperation(envelope, vaultRoot, callOptions);
+    } catch (err) {
+      return {
+        success: false,
+        error: { code: 'internal_error', message: err.message },
+      };
+    }
+  };
+
+  if (flags.stream) {
+    const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const payload = JSON.parse(trimmed);
+        const res = await processOne(payload);
+        process.stdout.write(`${JSON.stringify(res)}\n`);
+      } catch (err) {
+        process.stdout.write(`${JSON.stringify({ success: false, error: { code: 'invalid_request', message: `Malformed JSON: ${err.message}` } })}\n`);
+      }
+    }
+    return;
+  }
+
+  // Buffered mode (EOF-terminated)
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return;
+
+  // Case 1: JSON array
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    let list;
+    try {
+      list = JSON.parse(raw);
+    } catch (err) {
+      process.stdout.write(`${JSON.stringify({ success: false, error: { code: 'invalid_request', message: `Malformed JSON array: ${err.message}` } })}\n`);
+      return;
+    }
+    const results = [];
+    for (const item of list) {
+      results.push(await processOne(item));
+    }
+    process.stdout.write(`${JSON.stringify(results)}\n`);
+    return;
+  }
+
+  // Case 2: single JSON object
+  if (raw.startsWith('{') && raw.endsWith('}')) {
+    try {
+      const payload = JSON.parse(raw);
+      const res = await processOne(payload);
+      process.stdout.write(`${JSON.stringify(res)}\n`);
+      return;
+    } catch {
+      // If parsing failed, fall through to NDJSON check
+    }
+  }
+
+  // Case 3: NDJSON
+  const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
+  for (const line of lines) {
+    try {
+      const payload = JSON.parse(line);
+      const res = await processOne(payload);
+      process.stdout.write(`${JSON.stringify(res)}\n`);
+    } catch (err) {
+      process.stdout.write(`${JSON.stringify({ success: false, error: { code: 'invalid_request', message: `Malformed JSON line: ${err.message}` } })}\n`);
+    }
+  }
+}

package/scripts/cmd-import.mjs

@@ -16,6 +16,7 @@ const HELP = usage({
     ['--vault <dir>', 'Target vault directory (created if missing). Required.'],
     ['--plan <file>', 'Import a pre-built plan (from `ssss provision`) instead of the bundle.'],
     ['--param <k=v>', 'Bind a bundle parameter (repeatable).'],
+    ['--dependency <id=file>', 'Provide a dependency bundle (repeatable).'],
     ['--workspace <id>', 'Target workspace id (default: ws-provision).'],
     ['--prefix <path>', 'Place every file under this path prefix (id-remap).'],
     ['--dry-run', 'Validate every envelope without committing.'],
@@ -30,7 +31,7 @@ const HELP = usage({
 
 export async function run(argv) {
   if (wantsHelp(argv)) { console.log(HELP); return; }
-  const { positionals, flags } = parseArgs(argv, { booleans: ['dry-run'], multi: ['param'] });
+  const { positionals, flags } = parseArgs(argv, { booleans: ['dry-run'], multi: ['param', 'dependency'] });
   // Extension namespaces this import must resolve. Seeded from the bundle's own
   // `required_extensions` so the engine loads exactly the namespace the vault was
   // exported against, rather than every extension in the registry directory.
@@ -51,11 +52,30 @@ export async function run(argv) {
     const bundle = JSON.parse(fs.readFileSync(file, 'utf8'));
     const declared = bundle?.manifest?.required_extensions;
     if (Array.isArray(declared) && declared.length) registryNames = declared;
+
+    const dependencies = {};
+    for (const dep of flags.dependency || []) {
+      const eq = dep.indexOf('=');
+      let id = null;
+      let depPath = dep;
+      if (eq !== -1) {
+        id = dep.slice(0, eq);
+        depPath = dep.slice(eq + 1);
+      }
+      if (!fs.existsSync(depPath)) die(`no such dependency file: ${depPath}`);
+      let depBundle;
+      try { depBundle = JSON.parse(fs.readFileSync(depPath, 'utf8')); }
+      catch (err) { die(`dependency ${depPath} is not valid JSON: ${err.message}`); }
+      id = id || depBundle.manifest?.name || depBundle.manifest?.id || path.basename(depPath, '.json');
+      dependencies[id] = depBundle;
+    }
+
     const prov = provisionBundle(bundle, {
       parameters: parseKeyValues(flags.param),
       workspaceId: flags.workspace || 'ws-provision',
       pathPrefix: flags.prefix || '',
       dryRun: !!flags['dry-run'],
+      dependencies,
     });
     if (!prov.ok) {
       if (prov.unresolved.length) console.error(`✗ unresolved parameter(s): ${prov.unresolved.join(', ')}`);

package/scripts/cmd-provision.mjs

@@ -5,6 +5,7 @@
  * deterministic idempotency keys so a later `import` is a no-op on re-run.
  */
 import fs from 'node:fs';
+import path from 'node:path';
 import { provisionBundle } from '../src/bundle.mjs';
 import { parseArgs, parseKeyValues, usage, die, wantsHelp } from './lib/cli.mjs';
 
@@ -13,13 +14,16 @@ const HELP = usage({
   usage: 'ssss provision <bundle.ucw.json> [options]',
   options: [
     ['--param <k=v>', 'Bind a bundle parameter (repeatable).'],
+    ['--dependency <id=file>', 'Provide a dependency bundle (repeatable).'],
     ['--workspace <id>', 'Target workspace id (default: ws-provision).'],
     ['--prefix <path>', 'Place every file under this path prefix (id-remap).'],
     ['--out <file>', 'Write the envelope plan here (default: stdout).'],
     ['--dry-run', 'Mark every envelope dry_run (import will validate, not commit).'],
+    ['--json', 'Emit complete JSON plan including bindings and dependency summary.'],
   ],
   examples: [
     'ssss provision festival.ucw.json --param business_name="Acme Fest" --param domain=acme.live',
+    'ssss provision festival.ucw.json --dependency ticketing=./ticketing.ucw.json',
     'ssss provision festival.ucw.json --workspace ws-42 --out plan.json',
   ],
   seeAlso: ['ssss import', 'ssss inspect', 'ssss help provisioning'],
@@ -27,7 +31,7 @@ const HELP = usage({
 
 export async function run(argv) {
   if (wantsHelp(argv)) { console.log(HELP); return; }
-  const { positionals, flags } = parseArgs(argv, { booleans: ['dry-run'], multi: ['param'] });
+  const { positionals, flags } = parseArgs(argv, { booleans: ['dry-run', 'json'], multi: ['param', 'dependency'] });
   const file = positionals[0];
   if (!file) die('provision needs a bundle file.\n\n' + HELP);
   if (!fs.existsSync(file)) die(`no such file: ${file}`);
@@ -36,11 +40,29 @@ export async function run(argv) {
   try { bundle = JSON.parse(fs.readFileSync(file, 'utf8')); }
   catch (err) { die(`not valid JSON: ${err.message}`); }
 
+  const dependencies = {};
+  for (const dep of flags.dependency || []) {
+    const eq = dep.indexOf('=');
+    let id = null;
+    let depPath = dep;
+    if (eq !== -1) {
+      id = dep.slice(0, eq);
+      depPath = dep.slice(eq + 1);
+    }
+    if (!fs.existsSync(depPath)) die(`no such dependency file: ${depPath}`);
+    let depBundle;
+    try { depBundle = JSON.parse(fs.readFileSync(depPath, 'utf8')); }
+    catch (err) { die(`dependency ${depPath} is not valid JSON: ${err.message}`); }
+    id = id || depBundle.manifest?.name || depBundle.manifest?.id || path.basename(depPath, '.json');
+    dependencies[id] = depBundle;
+  }
+
   const result = provisionBundle(bundle, {
     parameters: parseKeyValues(flags.param),
     workspaceId: flags.workspace || 'ws-provision',
     pathPrefix: flags.prefix || '',
     dryRun: !!flags['dry-run'],
+    dependencies,
   });
 
   if (result.unresolved.length) {
@@ -55,8 +77,17 @@ export async function run(argv) {
     console.error(`✗ ${result.errors.length} bundle validation error(s):`);
     for (const e of result.errors) console.error(`  - ${e}`);
   }
+  if (result.dependencies?.suggested?.length) {
+    console.error(`ℹ suggested optional/recommended dependencies: ${result.dependencies.suggested.map((d) => d.id).join(', ')}`);
+  }
 
-  const plan = { workspace_id: flags.workspace || 'ws-provision', steps: result.steps, envelopes: result.plan };
+  const plan = {
+    workspace_id: flags.workspace || 'ws-provision',
+    steps: result.steps,
+    bindings: result.bindings,
+    dependencies: result.dependencies,
+    envelopes: result.plan,
+  };
   const json = JSON.stringify(plan, null, 2);
   if (flags.out) {
     fs.writeFileSync(flags.out, json + '\n');

package/scripts/cmd-serve.mjs

@@ -0,0 +1,155 @@
+/**
+ * ssss serve — reference HTTP server for the SSSS Operation Contract (spec §6.8).
+ * Dependency-free implementation using Node's built-in http module.
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createEngine } from '../src/engine.mjs';
+import { statusForResponse } from '../src/http.mjs';
+import { parseArgs, wantsHelp } from './lib/cli.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const VERSION = (() => {
+  try { return fs.readFileSync(path.resolve(HERE, '..', 'VERSION'), 'utf8').trim(); }
+  catch { return '0.0.0'; }
+})();
+
+export function createServer(options = {}) {
+  const vaultRoot = path.resolve(options.vault || '.');
+  const engine = options.engine || createEngine({
+    registryDir: options.registryDir,
+    extensionFile: options.extensionFile,
+  });
+
+  let expectedToken = null;
+  if (options.token) {
+    expectedToken = options.token.trim();
+  } else if (options.tokenFile) {
+    expectedToken = fs.readFileSync(path.resolve(options.tokenFile), 'utf8').trim();
+  }
+
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+
+    if (req.method === 'GET' && (req.url === '/health' || req.url === '/healthz')) {
+      res.writeHead(200);
+      res.end(JSON.stringify({ ok: true, version: VERSION }));
+      return;
+    }
+
+    const hostHeader = req.headers.host || 'localhost';
+    const parsedUrl = new URL(req.url, `http://${hostHeader}`);
+
+    if (req.method !== 'POST' || (parsedUrl.pathname !== '/v1/operations' && parsedUrl.pathname !== '/')) {
+      res.writeHead(404);
+      res.end(JSON.stringify({
+        success: false,
+        error: { code: 'not_found', message: `Route '${req.method} ${parsedUrl.pathname}' not found.` },
+      }));
+      return;
+    }
+
+    if (expectedToken) {
+      const authHeader = req.headers.authorization || '';
+      const match = authHeader.match(/^Bearer\s+(.+)$/i);
+      const token = match ? match[1].trim() : null;
+      if (!token || token !== expectedToken) {
+        res.writeHead(401);
+        res.end(JSON.stringify({
+          success: false,
+          error: { code: 'unauthorized', message: 'Missing or invalid bearer token.' },
+        }));
+        return;
+      }
+    }
+
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', async () => {
+      let payload;
+      try {
+        const text = Buffer.concat(chunks).toString('utf8');
+        payload = JSON.parse(text);
+      } catch (err) {
+        res.writeHead(400);
+        res.end(JSON.stringify({
+          success: false,
+          error: { code: 'invalid_request', message: `Malformed JSON: ${err.message}` },
+        }));
+        return;
+      }
+
+      const envelope = payload?.envelope || payload;
+      const callOptions = {};
+      if (payload?.principal) callOptions.principal = payload.principal;
+
+      try {
+        const response = await engine.processOperation(envelope, vaultRoot, callOptions);
+        const status = statusForResponse(response);
+        res.writeHead(status);
+        res.end(JSON.stringify(response));
+      } catch (err) {
+        res.writeHead(500);
+        res.end(JSON.stringify({
+          success: false,
+          error: { code: 'internal_error', message: err.message },
+        }));
+      }
+    });
+
+    req.on('error', (err) => {
+      if (!res.headersSent) {
+        res.writeHead(500);
+        res.end(JSON.stringify({ success: false, error: { code: 'internal_error', message: err.message } }));
+      }
+    });
+  });
+
+  return server;
+}
+
+export async function run(argv) {
+  if (wantsHelp(argv)) {
+    console.log(`Usage: ssss serve [options]
+
+Start a reference HTTP server exposing the SSSS Operation Contract (POST /v1/operations).
+
+Options:
+  --vault <dir>       Path to vault directory (default: '.')
+  --port <num>        Port to listen on (default: 8443, 0 for dynamic)
+  --host <ip>         Host address to bind to (default: 127.0.0.1)
+  --token <pat>       Optional bearer token required for requests
+  --token-file <file> Optional path to bearer token file
+  --registry <dir>    Path to registry directory
+  --extension <file>  Path to extension registry file
+  --quiet             Suppress listening message
+  --help, -h          Show help`);
+    return;
+  }
+
+  const { flags } = parseArgs(argv, { booleans: ['quiet'] });
+  const vault = flags.vault || '.';
+  const port = flags.port != null ? parseInt(flags.port, 10) : 8443;
+  const host = flags.host || '127.0.0.1';
+  const token = flags.token;
+  const tokenFile = flags['token-file'];
+  const registryDir = flags.registry;
+  const extensionFile = flags.extension;
+
+  const server = createServer({ vault, token, tokenFile, registryDir, extensionFile });
+  server.listen(port, host, () => {
+    const addr = server.address();
+    const actualPort = typeof addr === 'object' ? addr.port : port;
+    if (!flags.quiet) {
+      console.log(`SSSS reference server listening on http://${host}:${actualPort} (vault: ${path.resolve(vault)})`);
+    }
+  });
+
+  const close = () => {
+    server.close(() => process.exit(0));
+  };
+  process.on('SIGINT', close);
+  process.on('SIGTERM', close);
+}