total-recall-brain 3.9.0 → 3.11.0

package/scaffold/.agent/skills/total-recall/skills/{ssss → tr-ssss}/references/ssss-spec.md

@@ -1,6 +1,6 @@
 # SSSS — Structured Semantic Syntax System
 
-**Specification v0.2 — Draft**
+**Specification v0.6 — 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
@@ -22,19 +22,19 @@ SSSS — the Structured Semantic Syntax System — is a **database-free, Markdow
 schema and mutation contract for AI agent state**.
 
 Every unit of agent-relevant state — a memory, a skill, a conversation, a workflow
-run, an assistant definition — is a plain Markdown file with YAML frontmatter. There
-is no relational database of record, no binary format, and no proprietary container.
-A relational store MAY exist, but only as a *disposable projection* rebuildable from
-the Markdown.
+run, an assistant definition, a runtime task — is a plain Markdown file with YAML
+frontmatter. There is no relational database of record, no binary format, and no
+proprietary container. A relational store MAY exist, but only as a *disposable
+projection* rebuildable from the Markdown.
 
 SSSS additionally defines the **Operation Contract**: a single, validated, idempotent
 envelope through which all agent-generated mutations must flow. This makes
 AI-generated state changes deterministic, replayable, conflict-safe, and auditable.
 
-Any tool, IDE, agent framework, 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 write* — the
-underlying file format and mutation contract are identical.
+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
+write* — the underlying file format and mutation contract are identical.
 
 ---
 
@@ -112,13 +112,30 @@ Every SSSS document primitive MUST include:
 | Field | Type | Description |
 |-------|------|-------------|
 | `type` | string | The primitive type. MUST match an entry in the Type Registry (§5). |
+| `title` | string | Human-readable title of the document. |
+| `description` | string | One-sentence summary of the document's purpose. |
+| `timestamp` | string | ISO 8601 timestamp of last modification. |
+
+For OKF-compatible discovery, SSSS document primitives SHOULD also include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `resource` | string | Canonical URI for the underlying asset, when the primitive describes one. |
+| `tags` | array | Array of string tags for categorization and routing. |
+| `aliases` | array | Array of alternative names for this concept, used for wiki autolinking. |
 
 Every primitive type defines its own additional REQUIRED and OPTIONAL fields
-(§5.4). Hosts MUST NOT invent required fields outside this spec; host-specific
-fields are permitted only as OPTIONAL fields and SHOULD be namespaced (e.g.
-`x_host_*`) to avoid collision with future spec 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.
 
-### 4.3 Canonical Filenames
+### 4.3 Linking & Progressive Disclosure
+
+SSSS adopts the OKF standards for hyperlinking and directory indices:
+
+1. **Absolute Bundle-Relative Links**: Links to other primitives SHOULD be absolute paths starting from the vault root (e.g., `[Customer Assistant](/assistants/support.md)`).
+2. **The `# Citations` Section**: If a primitive's body makes claims sourced from other primitives or external data, it SHOULD include a `# Citations` heading at the bottom with numbered reference links.
+3. **Index Files (`index.md`)**: A host MAY generate `index.md` files in directories to provide progressive disclosure of the vault's contents. These files contain no frontmatter and exist solely to serve as a table of contents for agents traversing the VFS.
+
+### 4.4 Canonical Filenames
 
 Document primitives that have a fixed role in a directory use an **uppercase
 canonical filename** that signals the primitive at a glance:
@@ -147,21 +164,26 @@ primitive — it implements the subset its product requires — but any primitiv
 
 ### 5.1 Document Primitives
 
-| `type` | Family | Purpose |
-|--------|--------|---------|
-| `memory` | knowledge | A single unit of agent knowledge (rule, pattern, fact, preference). |
-| `skill` | capability | A skill package manifest. |
-| `rule` | governance | A workspace-scoped behavior rule applied to assistants/agents. |
-| `task` | work | A unit of submitted work — one step or many. The universal work primitive. |
-| `assistant` | actor | The definition of an AI assistant/persona. |
-| `workflow` | work | A reusable **task template**: a defined procedure plus triggers. Firing a workflow submits a `task`. |
-| `model` | catalog | The definition of an inference model. |
-| `conversation` | transcript | An append-only chat transcript. |
-| `run` | transcript | An append-only workflow execution record. |
-| `conflict` | meta | A record of two contradicting primitives, blocking promotion. |
-| `page` | capability | A VFS-native sandboxed custom workspace page. |
-| `migration` | meta | An SSSS schema migration state record. |
-| `release` | meta | An SSSS system schema version release record. |
+| `type` | Family | Portability | Purpose |
+|--------|--------|-------------|---------|
+| `memory` | knowledge | structural | A single unit of agent knowledge (rule, pattern, fact, preference). |
+| `skill` | capability | structural | A skill package manifest. |
+| `rule` | governance | structural | A workspace-scoped behavior rule applied to assistants/agents. |
+| `security_role` | governance | structural | A security role definition for role-based access control (RBAC). |
+| `task` | work | tenant_private | A unit of submitted work — one step or many. The universal work primitive. |
+| `assistant` | actor | structural | The definition of an AI assistant/persona. |
+| `workflow` | work | structural | A reusable **task template**: a defined procedure plus triggers. Firing a workflow submits a `task`. |
+| `model` | catalog | structural | The definition of an inference model. |
+| `conversation` | transcript | tenant_private | An append-only chat transcript. |
+| `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. |
+| `migration` | meta | structural | An SSSS schema migration state record. |
+| `release` | meta | structural | An SSSS system schema version release record. |
+
+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.
 
 ### 5.2 Contract Primitives
 
@@ -170,6 +192,7 @@ primitive — it implements the subset its product requires — but any primitiv
 | `operation` | A full atomic file write (create or full replace) — see §6. |
 | `patch` | A partial merge into an existing file — see §6. |
 | `event` | An append-only immutable log entry — see §6, §8. |
+| `delete` | A tombstoning removal of a replace-type file — see §6. |
 | `lease` | A file-level write lock — see §7. |
 
 ### 5.3 Append-Type vs. Replace-Type Documents
@@ -262,12 +285,21 @@ REQUIRED: `type`, `priority` (integer), `category`, `status`
 (`pending|in_progress|done|failed`). A task instantiated from a template carries an
 OPTIONAL `workflow_id` referencing it.
 
+Runtime-created tasks SHOULD additionally carry `workflow_path`, `trigger_id`,
+`trigger_type`, `trigger_event_id`, `scheduled_for`, and `dedupe_key`. These fields
+make the task reconstructible from the workflow definition plus the trigger event
+and prevent duplicate daemon ticks from creating duplicate work (§11.8).
+
 ```markdown
 ---
 type: task
 priority: 85
 category: skill-engineering
 status: pending
+workflow_id: "research-skill"
+trigger_id: "manual"
+scheduled_for: 2026-05-16T08:00:00Z
+dedupe_key: "runtime:abc123"
 ---
 
 ## Objective
@@ -303,6 +335,20 @@ the submitted instance.
 REQUIRED: `type`, `name`. `triggers` (array) is OPTIONAL — a workflow with no
 triggers is valid and may be invoked manually or by another workflow.
 
+When present, `triggers[]` is the canonical schedule source. OS cron, hosted
+schedulers, queues, and daemon timers are wake-up mechanisms only; they MUST NOT
+become the record of what the workflow schedule means. A trigger entry SHOULD
+include:
+
+| Field | Description |
+|-------|-------------|
+| `type` | `manual`, `cron`, `interval`, `event`, `webhook`, `file_change`, or `condition`. |
+| `id` / `trigger_id` | Stable trigger identity within the workflow. |
+| `cron` / `interval` / `event_type` | Type-specific selector. |
+| `timezone` | Required for wall-clock schedules; UTC is implied if omitted. |
+| `misfire_policy` | `skip`, `run_once`, or `catch_up`; default `run_once`. |
+| `concurrency` | `allow_parallel`, `skip_if_running`, `enqueue`, or `replace`; default `skip_if_running`. |
+
 ```markdown
 ---
 type: workflow
@@ -310,7 +356,11 @@ name: "Daily Digest"
 description: "Sends a daily summary email."
 triggers:
   - type: cron
+    id: daily-0800
     cron: "0 8 * * *"
+    timezone: "America/Denver"
+    misfire_policy: run_once
+    concurrency: skip_if_running
 isActive: true
 ---
 
@@ -339,6 +389,27 @@ scope: support
 Outbound links are stripped from any assistant reply on a support thread.
 ```
 
+#### `security_role`
+
+A definition of a security role used for role-based access control (RBAC).
+It maps a role name to a set of permissions that dictate what an agent or user
+can do within the workspace.
+
+REQUIRED: `type`, `name`, `permissions` (array). OPTIONAL: `description`.
+
+```markdown
+---
+type: security_role
+name: "admin"
+description: "Administrator with full access to all workspace primitives."
+permissions:
+  - "read:*"
+  - "write:*"
+---
+
+Full administrative access to the workspace.
+```
+
 #### `model`
 
 The definition of an inference model.
@@ -386,14 +457,18 @@ Hi — how can I help?
 An append-only workflow execution record. Append-type.
 
 REQUIRED: `type`, `run_id`, `workflow_id`. Typical fields: `workspace_id`, `status`,
-`step_count`, `started_at`.
+`task_id`, `task_path`, `step_count`, `started_at`.
+
+`status` SHOULD be one of: `queued`, `claimed`, `running`, `waiting_for_human`,
+`succeeded`, `failed`, `canceled`, `retrying`, `dead_letter`.
 
 ```markdown
 ---
 type: run
 run_id: "run-001"
 workflow_id: "daily-digest"
-status: running
+task_path: "tasks/daily-digest/daily-0800-20260516T080000Z.md"
+status: queued
 started_at: 2026-05-16T08:00:00Z
 ---
 
@@ -470,6 +545,41 @@ released_at: 2026-05-16T12:00:00Z
 ---
 ```
 
+### 5.5 Portability Classification
+
+A workspace is not one undifferentiated blob. Some of it is the **reusable business
+model** (the workflows, assistants, pages, and rules that make the business run); some is
+the operator's **private operational data** (customer transcripts, runtime work); and some
+is **bound to a real external resource** (a domain, a phone number, a mailbox). Selling,
+templating, and backing up a workspace each need a different slice. SSSS makes that slice
+declarable instead of ad-hoc.
+
+Every **document** primitive declares one **portability class** in its registry entry.
+(Contract primitives — `operation`/`patch`/`event`/`lease` — are protocol envelopes, not
+stored documents, and have no portability class.)
+
+| Class | Meaning | May appear in template/sale? |
+|-------|---------|------------------------------|
+| `structural` | The reusable business model — carries no operator- or customer-specific data. | ✅ verbatim |
+| `tenant_private` | The operator's private operational data (customers, transcripts, runtime work). | ❌ never — backup only, encrypted at rest |
+| `resource_bound` | Requires a real external resource bound at provision time. | ⚠️ as a **requirement declaration** only — the seller's resource value is stripped |
+
+A file MAY override its type's default with an `x_portability` frontmatter field. A host
+MUST honor the **most restrictive** of (type default, instance override) — a file may make
+itself more private than its type, never less.
+
+An **export profile** is simply a filter over portability classes:
+
+- **`backup`** — all three classes. `tenant_private` MUST be encrypted at rest.
+- **`template`** / **`sale`** — `structural` verbatim; `resource_bound` reduced to a
+  requirement declaration (seller's bound value stripped); `tenant_private` **dropped
+  entirely**.
+
+A host MUST reject a `template`/`sale` export that would emit a `tenant_private` primitive.
+This single rule is what lets an operator sell a proven business model without ever
+shipping a customer's data — the data is `tenant_private` by classification, so it
+physically cannot enter a sale bundle.
+
 ---
 
 ## 6. The Operation Contract
@@ -483,7 +593,7 @@ An operation is a JSON envelope:
 
 ```jsonc
 {
-  "type": "operation",          // "operation" | "patch" | "event"
+  "type": "operation",          // "operation" | "patch" | "event" | "delete"
   "idempotency_key": "uuid-v4", // see §6.4
   "path": "assistants/bot/ASSISTANT.md", // relative VFS path, no leading "/"
   "workspace_id": "uuid",       // the vault/workspace scope
@@ -491,7 +601,11 @@ An operation is a JSON envelope:
   "patches": { },               // partial merge (patch only)
   "lease_id": "uuid",           // OPTIONAL — see §7
   "intent": "human description", // OPTIONAL — audit annotation
-  "dry_run": false               // OPTIONAL — validate without committing
+  "dry_run": false,              // OPTIONAL — validate without committing
+  "actor": {                     // OPTIONAL — the cryptographically verified identity.
+    "type": "human",             // "human" | "ai" | "system"
+    "role": "admin"              // role-based access control hook for the host
+  }
 }
 ```
 
@@ -502,29 +616,58 @@ An operation is a JSON envelope:
 | `operation` | Full atomic write — creates or fully replaces a file. | `content` | `type`, `idempotency_key`, `path`, `workspace_id`, `content` |
 | `patch` | Partial merge into an existing file's frontmatter and/or body. | `patches` | `type`, `idempotency_key`, `path`, `workspace_id`, `patches` |
 | `event` | Append-only immutable log entry. Never overwrites. | `content` | `type`, `idempotency_key`, `path`, `workspace_id`, `content` |
+| `delete` | Removes a replace-type file from the vault. | — | `type`, `idempotency_key`, `path`, `workspace_id` |
 
 For `patch`, the `patches` object merges into frontmatter keys; the reserved key
 `__body__` replaces or (for append-type documents) appends the Markdown body. For
 `event`, `content` MUST be a valid JSON string carrying the event payload.
 
+For `delete`, the host removes the file at `path` and appends a deletion event to the log
+(§8) — the removal is itself an auditable, append-only record, so history is never lost. A
+host MUST reject a `delete` targeting an **append-type** document (`conversation`, `run`)
+or a non-existent path. A `delete` of an already-deleted path is an idempotent no-op that
+returns the original result (§6.4). `delete` is the only contract type that removes vault
+state; export and provision (§16) never delete — only a live workspace edit or a migration
+(§5.4 `migration`) does.
+
 ### 6.3 The Processing Pipeline
 
 A host MUST process every operation through these ordered stages. Any stage's
 failure aborts the operation with no commit.
 
-1. **Envelope validation** — `type` is one of the three envelope types; required
-   envelope fields present and well-formed.
-2. **Idempotency check** — if this `idempotency_key` + `workspace_id` was already
-   committed within the TTL, return the original result as a replay (§6.4). Stop.
-3. **Authorization** — the agent has write access to `workspace_id`.
+1. **Envelope validation** — `type` is one of the four envelope types
+   (`operation`/`patch`/`event`/`delete`); required envelope fields present and
+   well-formed.
+2. **Idempotency check** — if this `idempotency_key` + `workspace_id` +
+   request hash was already committed within the TTL, return the original result
+   as a replay (§6.4). If the key and workspace match but the request hash
+   differs, reject the request with `idempotency_conflict`. Stop.
+3. **Authorization & Actor Identity** — the agent has write access to `workspace_id`.
+   *Security Mandate*: If a host exposes the Operation Contract directly to untrusted clients (e.g., a `POST /api/ssss` REST endpoint), the host **MUST** irreversibly overwrite the `actor` payload with the user's cryptographically verified session identity. Hosts MUST use this `actor` field to enforce Role-Based Access Control (RBAC) over sensitive or `resource_bound` primitives.
 4. **Lease check** — if the target path is leased, the operation MUST carry a
    matching, unexpired `lease_id` (§7).
 5. **Content validation** — for `operation`/`patch`, the resulting file is validated
-   against its primitive schema (§9). Append-type rewrite attempts are rejected.
-6. **Commit** — the mutation is applied to the vault atomically.
+   against its primitive schema (§9). Append-type rewrite attempts are rejected. For
+   `delete`, the host verifies the target exists and is a replace-type document (append-type
+   deletes are rejected).
+5.5. **Granular Authorization (RBAC)** — evaluated only if stage 5 passed. Resolve
+   `actor.role` from the (by now host-verified, per stage 3) envelope. `role: "system"`
+   is an unconditional bypass (used by trusted internal callers such as the provisioning
+   pipeline, §17). `role: "admin"` is granted `write:*`/`read:*` unconditionally. Any
+   other named role's permissions are read from that role's `security_role` document
+   (canonical location `roles/<role>/ROLE.md`) and checked against the required
+   permission — `write:<type>` for `operation`/`patch`/`delete` (using the type resolved
+   in stage 5), or the fixed `write:event` for `event` envelopes (which have no resolved
+   document type). A permission list satisfies the requirement via an exact match,
+   `*:<type>`, `write:*`, or `*:*`. **A MISSING `actor.role` MUST be denied, not treated
+   as any default role** — this is the fail-closed complement to stage 3's mandate: a
+   host that forgets to overwrite `actor` gets every write rejected, not silently
+   promoted to admin.
+6. **Commit** — the mutation is applied to the vault atomically. For `delete`, the file is
+   removed.
 7. **Audit** — an audit entry is appended to the event log (§8).
 
-A `dry_run` operation runs stages 1–5 and then stops: it MUST return the validation
+A `dry_run` operation runs stages 1–5.5 and then stops: it MUST return the validation
 verdict with `success` reflecting validity, and MUST NOT commit (`committed_at` is
 `null`).
 
@@ -553,9 +696,11 @@ verdict with `success` reflecting validity, and MUST NOT commit (`committed_at`
 
 | Code | Meaning |
 |------|---------|
+| `400` | Invalid request — malformed envelope, or a path that fails the traversal guard. |
 | `401` | Authentication required. |
 | `403` | Agent lacks write access to the workspace. |
-| `409` | Lease conflict — path is locked, or the supplied lease is invalid/expired. |
+| `404` | The `patch`/`delete` target does not exist. |
+| `409` | Lease conflict, version conflict, or idempotency conflict — path is locked, the supplied lease is invalid/expired, or the same idempotency key was reused for a different request hash. |
 | `422` | Validation failure — see `validation.errors` and `repair`. |
 | `500` | Internal error — the operation was not committed. |
 
@@ -640,6 +785,8 @@ A file is valid if and only if:
 3. Every REQUIRED field for that primitive is present and non-empty.
 4. For append-type documents, the operation does not rewrite existing records.
 
+Hosts MUST NOT reject a file due to the presence of unknown or unrecognized frontmatter keys. Unrecognized keys MUST be silently preserved to support agent scratchpads and forward compatibility with OKF extensions.
+
 On failure, the host MUST return structured **repair feedback** so an agent can
 self-correct without guesswork:
 
@@ -783,6 +930,123 @@ a host MUST remain fully functional with feedback collection disabled, and the
 semantic layer MUST degrade gracefully to its other signals (access frequency, decay,
 embedding similarity).
 
+### 11.7 The `language_convention` Primitive
+
+Because the control vocabulary is symbolic and never translated (§11.1), a workspace
+that wishes to *present* itself in a given human language does so with data, not by
+translating keys. The `language_convention` primitive (a `structural`, extension-owned
+type — festech ships it) records a workspace's presentation conventions: its default
+language/locale, formality, date and currency formatting, and terminology preferences.
+
+It is `structural` and therefore travels in `template`/`sale` bundles (§5.5): a sold
+business carries its voice and locale conventions, but never the operator's private
+content. A host applies a `language_convention` as a **presentation overlay** at the
+semantic/rendering layer; it MUST NOT alter the deterministic layer's symbolic keys or
+enumerated values.
+
+### 11.8 Workflow Runtime & Daemon Contract
+
+SSSS defines the source of truth for workflow runtime behavior, but it does not
+mandate one resident process manager. A host MAY use OS cron, systemd timers,
+serverless schedules, webhooks, message queues, browser alarms, or an always-on
+daemon to wake the runtime. Those systems are **wake-up mechanisms** only. They MUST
+NOT become the canonical schedule, queue, or task history.
+
+The canonical runtime sources are:
+
+| Concern | Source of truth |
+|---------|-----------------|
+| Schedule and trigger meaning | `workflow` frontmatter `triggers[]`. |
+| Submitted work | `task` documents. |
+| Execution transcript | append-only `run` documents. |
+| What happened | append-only event log (§8). |
+| Claim/concurrency safety | leases (§7) plus deterministic idempotency keys (§6.4). |
+| Dashboards, task queues, cursors | projections (§10), rebuildable from the vault and event log. |
+
+A conformant daemon loop is:
+
+1. **Scan** active `workflow` primitives whose `triggers[]` might fire.
+2. **Evaluate** the trigger against wall-clock time, incoming event, webhook, file
+   change, condition, or explicit manual invocation.
+3. **Append** a `workflow_triggered` event via an `event` envelope.
+4. **Instantiate** one `task` via an `operation` envelope.
+5. **Claim** the task using a time-bound lease before execution.
+6. **Create or append** a `run` record for execution steps.
+7. **Patch** task status to `done` or `failed`, or to `pending` with retry metadata.
+8. **Rebuild** derived task queues, run timelines, graph indexes, or UI projections
+   as needed.
+
+Every step that mutates vault state MUST use the Operation Contract (§6). A daemon
+MUST NOT write task, run, cursor, or workflow files directly.
+
+#### Trigger Types
+
+Core trigger types are:
+
+| Type | Fires when |
+|------|------------|
+| `manual` | A human, agent, or another workflow invokes it. |
+| `cron` | A wall-clock cron expression reaches a scheduled instant. |
+| `interval` | A fixed duration elapses after the previous scheduled instant. |
+| `event` | A matching event-log entry appears. |
+| `webhook` | A verified external request arrives. |
+| `file_change` | A matching vault path is created, patched, or deleted. |
+| `condition` | A host-defined predicate over vault/projection state becomes true. |
+
+Trigger entries SHOULD use the fields documented in §5.4 `workflow`. Hosts MAY add
+type-specific `x_` fields, but MUST preserve unknown fields when rewriting the
+workflow document (§4.2).
+
+#### Idempotency & Duplicate Daemons
+
+The idempotency basis for runtime-created work is:
+
+```text
+workspace_id + workflow_id + trigger_id + scheduled_for
+```
+
+Two daemon ticks evaluating the same trigger for the same scheduled instant MUST
+produce the same task idempotency key. Replaying the same envelope MUST NOT create a
+second task. This rule is what lets an SSSS host run multiple scheduler processes
+without a scheduler database becoming the source of truth.
+
+For `event`, `webhook`, and `file_change` triggers, `scheduled_for` SHOULD be the
+canonical event timestamp or the host's normalized receipt timestamp, and the task
+SHOULD also record `trigger_event_id` when one exists.
+
+#### Concurrency, Misfires & Retries
+
+`misfire_policy` determines what happens when a daemon wakes after one or more missed
+schedule instants:
+
+| Policy | Meaning |
+|--------|---------|
+| `skip` | Do not create work for missed instants. |
+| `run_once` | Create one task for the most recent missed instant. |
+| `catch_up` | Create one task per missed instant, each with its own idempotency key. |
+
+`concurrency` determines what happens when a trigger fires while earlier work from
+the same workflow/trigger is still active:
+
+| Policy | Meaning |
+|--------|---------|
+| `allow_parallel` | Create the new task regardless of active runs. |
+| `skip_if_running` | Do not create a new task while a prior run is active. |
+| `enqueue` | Create a pending task, but allow a worker to claim it only after prior work finishes. |
+| `replace` | Cancel or fail the previous task/run before creating the replacement. |
+
+Retries MUST be represented on the `task` and/or `run` (`attempts`,
+`next_attempt_at`, `status: retrying`) and by events. A dead-letter outcome SHOULD be
+represented as `status: failed` on the task and `status: dead_letter` on the final
+run, plus an event explaining the terminal failure.
+
+#### Runtime Helpers
+
+The reference package exposes `@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.
+
 ---
 
 ## 12. Conformance
@@ -796,13 +1060,15 @@ Fixtures are distributed as a JSON document carrying:
 - `operation_types` — the envelope-type schemas.
 - `idempotency` — TTL and replay behavior.
 - `validation_rules` — envelope and content rules.
+- `runtime_contract` — trigger vocabulary and daemon idempotency rules (§11.8).
 - `fixtures[]` — each with a `request`, an `expected_response`, and an
   OPTIONAL `expected_http_status`.
 - `error_codes` — the canonical code table.
 
 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.
+fixture set. Hosts implementing workflow daemons SHOULD also run the reference
+runtime checks exposed by `@ssss/cli/runtime`.
 
 ---
 
@@ -830,7 +1096,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.2 — Draft**).
+- The spec version is stated in the document header (currently **v0.6 — 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.
@@ -878,6 +1144,171 @@ the determinism the contract layer depends on.
 
 ---
 
+## 16. The `.ucw` Bundle Format
+
+A **bundle** is a single transportable file that packages a portion of a vault — its
+files plus a manifest describing what they are and what they need to run. A bundle is
+how an SSSS business or template is **backed up, shared, sold, and re-provisioned**. The
+canonical container is `package.ucw.json` (a "universal containerized workspace"); a host
+MAY additionally wrap it in a `.ucw` archive (the JSON plus any binary branding assets),
+but the JSON document is the normative artifact and is self-contained.
+
+A bundle is produced by an **export** (§17) under one of the export profiles of §5.5
+(`backup | template | sale`). The profile a bundle was built under is recorded in its
+manifest and governs which portability classes (§5.5) its files may contain. A conformant
+exporter MUST NOT emit a `tenant_private` file into a `template` or `sale` bundle.
+
+### 16.1 Structure
+
+A bundle is a JSON object with three top-level members:
+
+```jsonc
+{
+  "manifest": { /* §16.2 — what this bundle is and needs */ },
+  "branding": { /* OPTIONAL — binary assets, base64 (logo, favicon, colors, fonts) */ },
+  "files":    [ /* §16.4 — the SSSS files, in deterministic path order */ ]
+}
+```
+
+`files` MUST be sorted by `path` (byte order) so that two exports of the same vault state
+are identical and content-hashable (§16.3, `provenance.content_hash`).
+
+### 16.2 The Manifest
+
+The manifest is the bundle's contract. It declares the bundle's identity, the SSSS version
+and extensions a host needs to consume it, the export profile, an inventory of what is
+inside, the resources it must bind at provision time, and provenance.
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `name` | yes | Human name of the bundle. |
+| `description` | yes | One-line summary. |
+| `version` | yes | The bundle's own semver, independent of the spec. |
+| `exported_at` | yes | ISO-8601 timestamp of export. |
+| `ssss_core_version` | yes | The `registry/core.json` `spec_version` the bundle targets (e.g. `"0.3"`). A host MUST refuse a bundle whose core version it does not support. |
+| `required_extensions` | yes | Array of extension registry ids the files rely on (e.g. `["festech"]`). Empty array if the bundle uses only core primitives. A host MUST refuse a bundle naming an extension it has not loaded. |
+| `export_profile` | yes | `backup` \| `template` \| `sale` — the §5.5 profile this bundle was built under. Determines the allowed portability classes. |
+| `primitive_inventory` | yes | Map of primitive `type` → count, over every file in the bundle (replaces ultrachat's hard-coded `categories`; it is registry-driven, so extension types appear automatically). |
+| `provisioning` | yes | Array of provisioning steps (§17.2) — the ordered, declarative plan for binding this bundle into a live workspace. Empty for a pure `backup` that is restored in place. |
+| `parameters` | no | Array of parameter definitions (§16.5) the importer must resolve (e.g. business name, domain). |
+| `source_workspace_id` | no | Origin workspace; OMITTED or nulled in `template`/`sale` profiles (it is operator-identifying). |
+| `file_count` | yes | Length of `files`; a cheap integrity check. |
+| `provenance` | yes | `{ content_hash, exporter, signature? }` (§16.3). |
+
+`primitive_inventory` supersedes ultrachat's fixed `categories` object and `provisioning`
+supersedes its `capabilities` booleans: both are now open and registry-driven rather than a
+closed enum, so a bundle full of `festech` extension primitives inventories and provisions
+them without a spec change.
+
+### 16.3 Provenance & Integrity
+
+`provenance` makes a bundle verifiable and attributable:
+
+- `content_hash` — a hash (SHA-256, hex, prefixed `sha256:`) over the canonical
+  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"`).
+- `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.
+
+### 16.4 Files
+
+Each entry of `files` is `{ path, content }`, where `content` is the full SSSS file text
+(frontmatter + body, §4). A host MAY also carry a parsed `frontmatter` object for
+convenience, but `content` is normative — on import the host re-parses `content`, so a
+divergent cached `frontmatter` is ignored. Every file's resolved portability class (§5.5,
+honoring `x_portability`) MUST be permitted by `export_profile`.
+
+### 16.5 Parameters
+
+`parameters` are the values an importer must supply to turn a template into a running
+instance — the difference between "a festival in a box" and "*this* festival." The schema is
+adopted verbatim from ultrachat's `WorkspaceTemplateVariableDefinition`:
+
+| Field | Meaning |
+|-------|---------|
+| `key` | Stable identifier, referenced by provisioning steps and link rewriting. |
+| `label` | Human prompt. |
+| `type` | Value type (`string`, `boolean`, `surfaces`, …). |
+| `scope` | Where the value applies (`workspace`, `automation`, `data`, …). |
+| `source` | Who supplies it: `user` \| `llm` \| `graph` \| `system`. |
+| `required` | Whether provisioning may proceed without it. |
+| `defaultValue`, `options`, `dependsOn` | Optional default, enumerated choices, and dependency keys. |
+
+A `sale`/`template` bundle declares its `resource_bound` requirements (§5.5) as `parameters`
+of `source: user` or `source: system` — e.g. the phone number, domain, and mailbox a buyer
+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.
+
+---
+
+## 17. The Provisioning Contract
+
+Export, provision, and import are the three verbs that move a bundle (§16) between vaults.
+They are specified to be **deterministic** and **idempotent** so that selling, cloning, and
+restoring an SSSS business are reliable operations rather than bespoke migrations.
+
+### 17.1 The Three Verbs
+
+- **export(vault, profile) → bundle** — Walk the vault, filter by the §5.5 portability rules
+  for `profile`, sort files by path, compute `provenance.content_hash`, and emit a §16
+  bundle. Export is **pure**: the same vault state and profile yield a byte-identical bundle.
+- **provision(bundle, parameters, target) → plan** — Resolve `parameters` (§16.5), bind the
+  bundle's `resource_bound` requirements to real resources in `target`, and produce an
+  ordered, replayable plan of Operation Contract envelopes (§6) plus resource bindings. A
+  `dry_run` provision (mirroring §6 `dry_run`) validates and plans without committing.
+- **import(plan, target)** — Replay the plan's envelopes through the target's engine (§6.3).
+  Because each envelope carries an `idempotency_key`, a re-run is a safe no-op: import is
+  idempotent.
+
+### 17.2 Provisioning Steps & Binding Vocabulary
+
+A manifest's `provisioning` array is an ordered list of steps. The step schema and its
+controlled vocabularies are adopted from ultrachat's `WorkspaceProvisioningStep` and
+`WorkspaceGraphEdge`:
+
+A **step** is `{ id, label, system, mode, required, notes? }`:
+
+- `system` — the subsystem the step acts on: `workspace | branding | email | phone |
+  domains | accounts | deployments | marketplace | tabs | automation`.
+- `mode` — the canonical **binding verb**: `existing` (bind to a resource the target
+  already has), `provision` (allocate a new real resource — a domain, a phone number),
+  `install` (add a dependency bundle), `generate` (synthesize content), `configure` (set
+  values). `mode` is how a bundle distinguishes "needs a *new* phone number" from "route to
+  the operator's existing line."
+
+Dependency and resource relationships between primitives are expressed with the canonical
+**edge relations**: `uses_brand | owns_domain | routes_calls_to | deploys_to | has_surface
+| contains_page | installs_pack | authenticates_account | runs_workflow`. The
+`resource_bound` primitives of §5.5 each declare which relation binds them (festech's
+`domain` → `owns_domain`, `phone_number` → `routes_calls_to`, `integration_connection` →
+`connects_to`), so an importer knows exactly what real-world 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.
+
+### 17.4 Composition & Upgrade
+
+- **Composition** — a bundle MAY depend on other bundles. A dependency carries an
+  `installMode` of `optional | recommended | required` (adopted from ultrachat's
+  `WorkspaceMarketplaceRecommendation`). `provision` installs `required` dependencies before
+  the bundle itself; `optional`/`recommended` are surfaced to the operator.
+- **Upgrade** — moving an installed bundle from `v2` to a `v1`-conformant shape (or any
+  version step) is performed through a `migration` primitive (§5) plus **structural-only**
+  `patch` envelopes (§6.2). An upgrade MUST NOT touch `tenant_private` data: it rewrites the
+  structural model, never the operator's private records. This is what lets a sold business
+  receive standard updates without the vendor reaching into customer data.
+
+---
+
 ## Appendix A — Reserved Frontmatter Keys
 
 The following frontmatter keys are reserved by this spec across all primitives and