@gregiteen/ssss-cli 0.12.1 → 0.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +66 -0
- package/VERSION +1 -1
- package/conformance/reference-bundle.ucw.json +1 -1
- package/docs/ssss-spec.md +50 -7
- package/package.json +3 -2
- package/scripts/check-commit-durability.mjs +392 -0
- package/scripts/cmd-adapter.mjs +3 -0
- package/skills/ssss/SKILL.md +6 -47
- package/skills/ssss/core/SKILL.md +18 -0
- package/skills/ssss/core/references/core-registry.json +333 -0
- package/skills/ssss/core/references/ssss-spec.md +1959 -0
- package/skills/ssss/core/scripts/maintain.mjs +75 -0
- package/skills/ssss/evals/maintain.test.mjs +11 -0
- package/skills/ssss/references/protocol-reference-legacy.md +54 -0
- package/src/bundle.mjs +4 -1
- package/src/durable-fs.mjs +32 -0
- package/src/engine.mjs +4 -0
- package/src/events.mjs +119 -33
- package/src/intents.mjs +217 -0
- package/src/kernel.mjs +175 -54
- package/src/vfs.mjs +22 -3
- package/types/kernel.d.ts +29 -0
package/skills/ssss/SKILL.md
CHANGED
|
@@ -2,53 +2,12 @@
|
|
|
2
2
|
type: skill
|
|
3
3
|
title: SSSS Protocol Reference
|
|
4
4
|
name: ssss
|
|
5
|
-
description:
|
|
6
|
-
timestamp: 2026-
|
|
5
|
+
description: Validate or change SSSS documents, operations, registries, workflows and portable host adapters.
|
|
6
|
+
timestamp: 2026-11-02T00:00:00Z
|
|
7
|
+
version: 0.13.0
|
|
8
|
+
repo_scoped: false
|
|
7
9
|
---
|
|
8
10
|
|
|
9
|
-
# SSSS
|
|
11
|
+
# SSSS
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
This skill provides the normative rules for interacting with an SSSS-compliant vault or host engine (like Total Recall).
|
|
14
|
-
|
|
15
|
-
## ⚠️ The VFS-First Mandate (Absolute Rule)
|
|
16
|
-
|
|
17
|
-
**NEVER use raw database inserts, updates, or deletes to mutate application state in an SSSS environment!**
|
|
18
|
-
|
|
19
|
-
All persistent state (memories, agents, workflows, tasks) lives in the Virtual File System (VFS) as Markdown files with YAML frontmatter. The VFS is the absolute source of truth.
|
|
20
|
-
- If you are interacting via CLI: Use `npx total-recall remember` or `npx total-recall recall`.
|
|
21
|
-
- If you are building host code: You must route mutations through the SSSS **Operation Contract** engine (which handles idempotency, leasing, and semantic indexing), or use the provided API wrappers. Do not bypass the engine to write files directly.
|
|
22
|
-
|
|
23
|
-
## SSSS Core Concepts
|
|
24
|
-
|
|
25
|
-
### 1. Primitives (The Data Model)
|
|
26
|
-
Data in SSSS is defined by standard primitives (e.g. `workflow`, `assistant`, `skill`, `memory`). Each primitive has a defined schema (in `registry/core.json` or extension registries) and belongs to a specific Portability Class:
|
|
27
|
-
- `structural`: Logic and system prompts (e.g. rules, workflows). Included in export templates.
|
|
28
|
-
- `tenant_private`: User data (e.g. chats, tasks). NEVER included in templates.
|
|
29
|
-
- `resource_bound`: Requires external setup (e.g. Twilio numbers). Exported only as a requirement.
|
|
30
|
-
|
|
31
|
-
### 2. The Operation Contract (Envelopes)
|
|
32
|
-
When an SSSS engine processes a write, it receives an **Envelope**:
|
|
33
|
-
- `operation`: Creates or completely replaces a document.
|
|
34
|
-
- `patch`: Merges partial data into a document (e.g. updating task status).
|
|
35
|
-
- `event`: Appends an immutable log entry to a document.
|
|
36
|
-
- `delete`: Tombstones a replace-type document.
|
|
37
|
-
|
|
38
|
-
### 3. Idempotency and Leases
|
|
39
|
-
- **Idempotency**: All mutations must provide an `idempotency_key`. The engine ensures duplicate submissions do not result in duplicate state.
|
|
40
|
-
- **Leases**: Background tasks and workflows use the Lease store to acquire temporary locks on documents to prevent race conditions during execution.
|
|
41
|
-
|
|
42
|
-
### 4. Bundles (.ucw)
|
|
43
|
-
An SSSS vault can be packaged into a `.ucw` (Universal Containerized Workspace) bundle. A bundle is a portable snapshot containing a manifest, deterministic file paths, and content hashes for cryptographic integrity.
|
|
44
|
-
|
|
45
|
-
Bundle import validates the complete plan before committing. Hosts pass planned
|
|
46
|
-
document lookup through the kernel context's `resolveReference` option so valid
|
|
47
|
-
forward references resolve in an empty destination. Missing referenced documents
|
|
48
|
-
must reject the whole import; never weaken constraints to bypass ordering.
|
|
49
|
-
|
|
50
|
-
## Validation
|
|
51
|
-
|
|
52
|
-
If you are writing tests or schemas in a host repository, ensure that:
|
|
53
|
-
1. `MemoryNodeSchema` validations provide all required SSSS v2 properties (`status`, `created`, `updated`, `last_accessed`, `source`, `decay`).
|
|
54
|
-
2. Schema changes maintain strict compatibility with the Open Knowledge Format (OKF) standard if applicable.
|
|
13
|
+
Read the [maintained portable core](core/SKILL.md) before SSSS work. It defines current authority, mutation safety and task-specific references. Repository-specific guidance may extend the core without weakening protocol or authorization contracts.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# SSSS portable core — 0.13.0
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
All canonical state is Markdown/YAML in the VFS. Use the owning CLI/API and validated operation/patch/event/delete envelopes. Preserve universal and primitive fields, identity, unknown fields and timestamps. Validate before atomic commit; enforce actor authority, path containment, idempotency request hashes, leases and append-only constraints. No raw database or filesystem fallback for canonical mutations. Databases and queues are projections; never back them up as the source of truth.
|
|
6
|
+
|
|
7
|
+
Read only the relevant sections of the [normative spec](references/ssss-spec.md): document/frontmatter and registry contracts for schema work; operation contract and safety for mutations; workflow/trigger/task/run for automation; bundles and portability for import/export; adapter/kernel/UI for host integrations. The [core registry](references/core-registry.json) declares actual primitive required fields, constraints and portability; do not invent unsupported operations or blanket host-specific MemoryNode requirements.
|
|
8
|
+
|
|
9
|
+
## Workflow and trigger work
|
|
10
|
+
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.
|
|
11
|
+
|
|
12
|
+
## Bundles and adapters
|
|
13
|
+
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.
|
|
14
|
+
|
|
15
|
+
## Verification
|
|
16
|
+
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.
|
|
17
|
+
|
|
18
|
+
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.
|
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://ssss.dev/registry/v1",
|
|
3
|
+
"registry": "core",
|
|
4
|
+
"spec_version": "0.9",
|
|
5
|
+
"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.",
|
|
6
|
+
"conformance": "A host is core-conformant for a primitive if a file of that type validates exactly when all required_fields are present and non-empty, and (for append_only types) writes only append.",
|
|
7
|
+
|
|
8
|
+
"document_primitives": {
|
|
9
|
+
"memory": {
|
|
10
|
+
"family": "knowledge",
|
|
11
|
+
"canonical_filename": null,
|
|
12
|
+
"filename_convention": "kebab-case slug matching the `slug` field",
|
|
13
|
+
"append_only": false,
|
|
14
|
+
"portability": "structural",
|
|
15
|
+
"required_fields": ["type", "slug", "category", "title", "status", "schema_version"],
|
|
16
|
+
"required_when": {
|
|
17
|
+
"schema_version==2": ["confidence", "importance", "modality", "subject", "predicate", "object", "sentiment_polarity"]
|
|
18
|
+
},
|
|
19
|
+
"enums": {
|
|
20
|
+
"category": ["invariants", "patterns", "anti-patterns", "preferences", "decisions", "concepts", "facts", "lore"],
|
|
21
|
+
"modality": ["must", "must_not", "should", "should_not", "descriptive", "preference"],
|
|
22
|
+
"sentiment_polarity": ["directive_must", "directive_must_not", "descriptive", "preference"],
|
|
23
|
+
"priority": ["absolute", "high", "normal", "low"]
|
|
24
|
+
},
|
|
25
|
+
"spec_ref": "§5.4 memory"
|
|
26
|
+
},
|
|
27
|
+
"skill": {
|
|
28
|
+
"family": "capability",
|
|
29
|
+
"canonical_filename": "SKILL.md",
|
|
30
|
+
"append_only": false,
|
|
31
|
+
"portability": "structural",
|
|
32
|
+
"required_fields": ["type", "name", "description"],
|
|
33
|
+
"notes": "Compatible with the open Agent Skills standard (name + description). The `type: skill` discriminator is REQUIRED for SSSS-managed manifests.",
|
|
34
|
+
"spec_ref": "§5.4 skill"
|
|
35
|
+
},
|
|
36
|
+
"asset": {
|
|
37
|
+
"family": "capability",
|
|
38
|
+
"canonical_filename": null,
|
|
39
|
+
"filename_convention": "kebab-case slug matching the `slug` field",
|
|
40
|
+
"append_only": false,
|
|
41
|
+
"portability": "structural",
|
|
42
|
+
"required_fields": ["type", "name", "mime_type", "encoding"],
|
|
43
|
+
"optional_fields": ["slug", "hash", "size_bytes", "description", "storage_uri", "resource_ref", "x_portability"],
|
|
44
|
+
"required_when": {
|
|
45
|
+
"encoding==none": ["storage_uri", "x_portability"]
|
|
46
|
+
},
|
|
47
|
+
"enums": {
|
|
48
|
+
"encoding": ["base64", "utf-8", "none"],
|
|
49
|
+
"x_portability": ["resource_bound", "tenant_private"]
|
|
50
|
+
},
|
|
51
|
+
"references": {
|
|
52
|
+
"resource_ref": { "allowed_types": ["resource"] }
|
|
53
|
+
},
|
|
54
|
+
"resource": { "kind": "storage", "binds": ["storage_uri"], "provision_relation": "stores_asset" },
|
|
55
|
+
"notes": "A text-encoded asset payload: source code, vector graphics, or base64-encoded binary content. With `encoding: none` the body is empty and the asset is a pointer to a large file: `storage_uri` locates the object, `resource_ref` optionally names the `resource` document (bucket, store) that holds it, and `hash`/`size_bytes` pin its content. A pointer MUST be marked `x_portability: resource_bound` (or `tenant_private`), so template/sale exports replace `storage_uri` with `REQUIREMENT` instead of shipping the seller's storage location.",
|
|
56
|
+
"spec_ref": "§5.4 asset"
|
|
57
|
+
},
|
|
58
|
+
"resource": {
|
|
59
|
+
"family": "capability",
|
|
60
|
+
"canonical_filename": null,
|
|
61
|
+
"append_only": false,
|
|
62
|
+
"portability": "resource_bound",
|
|
63
|
+
"required_fields": ["type", "name", "kind", "status"],
|
|
64
|
+
"optional_fields": ["slug", "description", "binds", "provisioning"],
|
|
65
|
+
"enums": {
|
|
66
|
+
"status": ["bound", "unbound", "pending", "error"]
|
|
67
|
+
},
|
|
68
|
+
"resource": {
|
|
69
|
+
"binds": ["binds"]
|
|
70
|
+
},
|
|
71
|
+
"notes": "An external infrastructure, cloud asset, domain, database, or API dependency bound to the workspace.",
|
|
72
|
+
"spec_ref": "§5.4 resource"
|
|
73
|
+
},
|
|
74
|
+
"rule": {
|
|
75
|
+
"family": "governance",
|
|
76
|
+
"canonical_filename": null,
|
|
77
|
+
"append_only": false,
|
|
78
|
+
"portability": "structural",
|
|
79
|
+
"required_fields": ["type", "name"],
|
|
80
|
+
"optional_fields": ["description", "scope"],
|
|
81
|
+
"spec_ref": "§5.4 rule"
|
|
82
|
+
},
|
|
83
|
+
"role": {
|
|
84
|
+
"family": "governance",
|
|
85
|
+
"canonical_filename": "ROLE.md",
|
|
86
|
+
"append_only": false,
|
|
87
|
+
"portability": "structural",
|
|
88
|
+
"required_fields": ["type", "name", "permissions"],
|
|
89
|
+
"optional_fields": ["description"],
|
|
90
|
+
"notes": "A named set of capabilities used for role-based access control (RBAC). Canonical form of security_role.",
|
|
91
|
+
"spec_ref": "§5.4 role"
|
|
92
|
+
},
|
|
93
|
+
"security_role": {
|
|
94
|
+
"family": "governance",
|
|
95
|
+
"canonical_filename": "ROLE.md",
|
|
96
|
+
"append_only": false,
|
|
97
|
+
"portability": "structural",
|
|
98
|
+
"required_fields": ["type", "name", "permissions"],
|
|
99
|
+
"optional_fields": ["description"],
|
|
100
|
+
"spec_ref": "§5.4 security_role"
|
|
101
|
+
},
|
|
102
|
+
"task": {
|
|
103
|
+
"family": "work",
|
|
104
|
+
"canonical_filename": null,
|
|
105
|
+
"append_only": false,
|
|
106
|
+
"portability": "tenant_private",
|
|
107
|
+
"required_fields": ["type", "priority", "category", "status"],
|
|
108
|
+
"optional_fields": ["workflow_id", "workflow_path", "trigger_id", "trigger_type", "trigger_event_id", "scheduled_for", "dedupe_key", "claim_id", "claimed_by", "claimed_at", "attempts", "next_attempt_at"],
|
|
109
|
+
"enums": { "status": ["pending", "in_progress", "done", "failed"] },
|
|
110
|
+
"spec_ref": "§5.4 task"
|
|
111
|
+
},
|
|
112
|
+
"assistant": {
|
|
113
|
+
"family": "actor",
|
|
114
|
+
"canonical_filename": "ASSISTANT.md",
|
|
115
|
+
"append_only": false,
|
|
116
|
+
"portability": "structural",
|
|
117
|
+
"required_fields": ["type", "name"],
|
|
118
|
+
"optional_fields": ["owns"],
|
|
119
|
+
"spec_ref": "§5.4 assistant"
|
|
120
|
+
},
|
|
121
|
+
"workflow": {
|
|
122
|
+
"family": "work",
|
|
123
|
+
"canonical_filename": "WORKFLOW.md",
|
|
124
|
+
"append_only": false,
|
|
125
|
+
"portability": "structural",
|
|
126
|
+
"required_fields": ["type", "name"],
|
|
127
|
+
"optional_fields": ["workflow_id", "slug", "description", "triggers", "isActive", "priority", "misfire_policy", "concurrency"],
|
|
128
|
+
"spec_ref": "§5.4 workflow"
|
|
129
|
+
},
|
|
130
|
+
"trigger": {
|
|
131
|
+
"family": "work",
|
|
132
|
+
"canonical_filename": null,
|
|
133
|
+
"append_only": false,
|
|
134
|
+
"portability": "structural",
|
|
135
|
+
"required_fields": ["type", "name", "source", "status"],
|
|
136
|
+
"optional_fields": ["slug", "description", "cron", "interval", "timezone", "target_workflow", "target_params", "concurrency", "misfire_policy", "event_subject", "event_match"],
|
|
137
|
+
"enums": {
|
|
138
|
+
"source": ["cron", "interval", "webhook", "event", "file_change", "condition", "manual"],
|
|
139
|
+
"status": ["active", "paused", "disabled"],
|
|
140
|
+
"concurrency": ["allow_parallel", "skip_if_running", "enqueue", "replace"],
|
|
141
|
+
"misfire_policy": ["skip", "run_once", "catch_up"]
|
|
142
|
+
},
|
|
143
|
+
"notes": "A standalone schedule or event-driven trigger that fires a task from a workflow template.",
|
|
144
|
+
"spec_ref": "§5.4 trigger"
|
|
145
|
+
},
|
|
146
|
+
"model": {
|
|
147
|
+
"family": "catalog",
|
|
148
|
+
"canonical_filename": "MODEL.md",
|
|
149
|
+
"append_only": false,
|
|
150
|
+
"portability": "structural",
|
|
151
|
+
"required_fields": ["type", "model_id", "provider"],
|
|
152
|
+
"spec_ref": "§5.4 model"
|
|
153
|
+
},
|
|
154
|
+
"thread": {
|
|
155
|
+
"family": "transcript",
|
|
156
|
+
"canonical_filename": "CONVERSATION.md",
|
|
157
|
+
"append_only": true,
|
|
158
|
+
"portability": "tenant_private",
|
|
159
|
+
"required_fields": ["type", "thread_id"],
|
|
160
|
+
"optional_fields": ["workspace_id", "user_id", "status", "turn_count", "created_at"],
|
|
161
|
+
"notes": "An append-only multi-turn chat transcript. Canonical form of conversation.",
|
|
162
|
+
"spec_ref": "§5.4 thread"
|
|
163
|
+
},
|
|
164
|
+
"conversation": {
|
|
165
|
+
"family": "transcript",
|
|
166
|
+
"canonical_filename": "CONVERSATION.md",
|
|
167
|
+
"append_only": true,
|
|
168
|
+
"portability": "tenant_private",
|
|
169
|
+
"required_fields": ["type", "thread_id"],
|
|
170
|
+
"spec_ref": "§5.4 conversation"
|
|
171
|
+
},
|
|
172
|
+
"run": {
|
|
173
|
+
"family": "transcript",
|
|
174
|
+
"canonical_filename": "RUN.md",
|
|
175
|
+
"append_only": true,
|
|
176
|
+
"portability": "tenant_private",
|
|
177
|
+
"required_fields": ["type", "run_id", "workflow_id"],
|
|
178
|
+
"optional_fields": ["task_id", "task_path", "workspace_id", "status", "step_count", "started_at", "ended_at", "claimed_by", "provenance"],
|
|
179
|
+
"enums": { "status": ["queued", "claimed", "running", "waiting_for_human", "succeeded", "failed", "canceled", "retrying", "dead_letter"] },
|
|
180
|
+
"spec_ref": "§5.4 run"
|
|
181
|
+
},
|
|
182
|
+
"conflict": {
|
|
183
|
+
"family": "meta",
|
|
184
|
+
"canonical_filename": null,
|
|
185
|
+
"append_only": false,
|
|
186
|
+
"portability": "tenant_private",
|
|
187
|
+
"required_fields": ["type", "conflict_id", "status", "new_slug", "existing_slug", "detected_at"],
|
|
188
|
+
"enums": { "status": ["pending", "resolved"] },
|
|
189
|
+
"spec_ref": "§5.4 conflict"
|
|
190
|
+
},
|
|
191
|
+
"page": {
|
|
192
|
+
"family": "capability",
|
|
193
|
+
"canonical_filename": null,
|
|
194
|
+
"append_only": false,
|
|
195
|
+
"portability": "structural",
|
|
196
|
+
"required_fields": ["type", "slug", "name", "sandbox_entry"],
|
|
197
|
+
"spec_ref": "§5.4 page"
|
|
198
|
+
},
|
|
199
|
+
"migration": {
|
|
200
|
+
"family": "meta",
|
|
201
|
+
"canonical_filename": null,
|
|
202
|
+
"append_only": false,
|
|
203
|
+
"portability": "structural",
|
|
204
|
+
"required_fields": ["type", "migration_id", "from_version", "to_version", "status", "description"],
|
|
205
|
+
"spec_ref": "§5.4 migration"
|
|
206
|
+
},
|
|
207
|
+
"release": {
|
|
208
|
+
"family": "meta",
|
|
209
|
+
"canonical_filename": null,
|
|
210
|
+
"append_only": false,
|
|
211
|
+
"portability": "structural",
|
|
212
|
+
"required_fields": ["type", "release_id", "version", "schema_version", "summary", "released_at"],
|
|
213
|
+
"spec_ref": "§5.4 release"
|
|
214
|
+
},
|
|
215
|
+
"primitive": {
|
|
216
|
+
"family": "meta",
|
|
217
|
+
"canonical_path": "primitives/<namespace>/<id>.md",
|
|
218
|
+
"append_only": false,
|
|
219
|
+
"portability": "structural",
|
|
220
|
+
"required_fields": ["type", "primitive_id", "namespace", "version", "name", "mutation", "portability", "scopes", "fields"],
|
|
221
|
+
"optional_fields": ["language", "aliases", "path_template", "capabilities", "events", "projections", "ui", "migrations", "requires"],
|
|
222
|
+
"immutable_fields": ["primitive_id", "namespace"],
|
|
223
|
+
"enums": {
|
|
224
|
+
"mutation": ["replace", "append"],
|
|
225
|
+
"portability": ["structural", "tenant_private", "resource_bound"],
|
|
226
|
+
"scopes": ["system", "account", "workspace", "user"]
|
|
227
|
+
},
|
|
228
|
+
"patterns": {
|
|
229
|
+
"primitive_id": "^[a-z][a-z0-9_-]{0,63}:[a-z][a-z0-9_-]{0,127}$",
|
|
230
|
+
"namespace": "^[a-z][a-z0-9_-]{0,63}$",
|
|
231
|
+
"language": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
|
|
232
|
+
},
|
|
233
|
+
"notes": "A governed, versioned definition for a repository, extension, workspace, or user primitive. Natural-language labels may use any language; stable field, enum, capability, and action identifiers are never translated.",
|
|
234
|
+
"spec_ref": "§5.4 primitive"
|
|
235
|
+
}
|
|
236
|
+
},
|
|
237
|
+
|
|
238
|
+
"contract_primitives": {
|
|
239
|
+
"operation": { "purpose": "Full atomic file write (create or full replace).", "spec_ref": "§6" },
|
|
240
|
+
"patch": { "purpose": "Partial merge into an existing file.", "spec_ref": "§6" },
|
|
241
|
+
"event": { "purpose": "Append-only immutable log entry.", "spec_ref": "§6, §8" },
|
|
242
|
+
"delete": { "purpose": "Tombstoning removal of a replace-type file; rejects append-type targets; emits a deletion event.", "spec_ref": "§6.2" },
|
|
243
|
+
"lease": { "purpose": "A file-level write lock.", "spec_ref": "§7" }
|
|
244
|
+
},
|
|
245
|
+
|
|
246
|
+
"universal_frontmatter": {
|
|
247
|
+
"required": ["type", "title", "description", "timestamp"],
|
|
248
|
+
"recommended_okf": ["resource", "tags", "aliases"],
|
|
249
|
+
"recommended_semantic": ["semantic_id", "resource", "tags", "aliases", "relations", "language"],
|
|
250
|
+
"spec_ref": "§4.2"
|
|
251
|
+
},
|
|
252
|
+
|
|
253
|
+
"portability": {
|
|
254
|
+
"description": "Every document primitive declares a portability class. The class governs whether a primitive may leave the workspace in a given export profile (§5.5). Contract primitives (operation/patch/event/lease) are protocol envelopes, not stored documents, and carry no portability. A file MAY override its type's default class with an `x_portability` frontmatter field; a host MUST honor the most restrictive of (type default, instance override).",
|
|
255
|
+
"classes": {
|
|
256
|
+
"structural": "The reusable business model — sellable and templatable. Carries no operator- or customer-specific data. Examples: workflow, assistant, page, skill, model, rule, memory, migration, release.",
|
|
257
|
+
"tenant_private": "The operator's private operational data — customers, transcripts, runtime work. NEVER leaves the workspace in a template or sale bundle; included only in an encrypted backup. Examples: conversation, run, task, conflict, and (via extension) profile / CRM contact / deal.",
|
|
258
|
+
"resource_bound": "Requires a real external resource bound at provision time (a domain, phone number, mailbox, API connection). NEVER ships the seller's resource value; ships only a requirement declaration the buyer satisfies. Defined by extension registries (e.g. festech domain / phone_number / integration_connection)."
|
|
259
|
+
},
|
|
260
|
+
"export_profiles": {
|
|
261
|
+
"backup": { "includes": ["structural", "tenant_private", "resource_bound"], "note": "Complete fidelity copy. tenant_private MUST be encrypted at rest." },
|
|
262
|
+
"template": { "includes": ["structural"], "resource_bound": "requirement_declaration_only", "excludes": ["tenant_private"] },
|
|
263
|
+
"sale": { "includes": ["structural"], "resource_bound": "requirement_declaration_only", "excludes": ["tenant_private"] }
|
|
264
|
+
},
|
|
265
|
+
"conformance": "A host MUST resolve every primitive's portability class from this registry (type default, overridable by `x_portability`). An exporter MUST drop every `tenant_private` primitive from a `template` or `sale` bundle, and MUST reduce every `resource_bound` primitive to a requirement declaration (stripping the seller's bound value) in those profiles. A host MUST reject a `template`/`sale` export that would emit a `tenant_private` primitive.",
|
|
266
|
+
"spec_ref": "§5.5"
|
|
267
|
+
},
|
|
268
|
+
|
|
269
|
+
"bundle": {
|
|
270
|
+
"description": "The `.ucw` bundle format (§16): a transportable package of a vault's files plus a manifest declaring what they are and what they need to run. Produced by an export under an export profile (§5.5), consumed by provision/import (§17).",
|
|
271
|
+
"container": "package.ucw.json",
|
|
272
|
+
"structure": ["manifest", "branding", "files"],
|
|
273
|
+
"file_sort": "files MUST be sorted by path (byte order) so equal vault state yields a byte-identical, content-hashable bundle.",
|
|
274
|
+
"manifest_required_fields": ["name", "description", "version", "exported_at", "ssss_core_version", "required_extensions", "export_profile", "primitive_inventory", "provisioning", "file_count", "provenance"],
|
|
275
|
+
"manifest_optional_fields": ["parameters", "source_workspace_id", "branding"],
|
|
276
|
+
"provenance_required_fields": ["content_hash", "exporter"],
|
|
277
|
+
"provenance_optional_fields": ["signature"],
|
|
278
|
+
"content_hash": "sha256 over the canonical (path-sorted) serialization of files; importer MUST recompute and reject on mismatch.",
|
|
279
|
+
"parameter_fields": {
|
|
280
|
+
"required": ["key", "label", "type", "scope", "source"],
|
|
281
|
+
"optional": ["required", "description", "defaultValue", "options", "dependsOn"],
|
|
282
|
+
"source_enum": ["user", "llm", "graph", "system"],
|
|
283
|
+
"note": "resource_bound requirements ship as parameters of source user/system."
|
|
284
|
+
},
|
|
285
|
+
"conformance": "A host MUST refuse a bundle whose `ssss_core_version` it does not support or that names a `required_extensions` entry it has not loaded. An exporter MUST NOT emit a file whose resolved portability class is excluded by `export_profile`. `primitive_inventory` MUST count every file by its registry `type`.",
|
|
286
|
+
"spec_ref": "§16"
|
|
287
|
+
},
|
|
288
|
+
|
|
289
|
+
"provisioning": {
|
|
290
|
+
"description": "The provisioning contract (§17): the deterministic, idempotent verbs that move a bundle between vaults — export, provision, import.",
|
|
291
|
+
"verbs": {
|
|
292
|
+
"export": "vault + profile → bundle. Pure: equal vault state and profile yield a byte-identical bundle.",
|
|
293
|
+
"provision": "bundle + parameters + target → ordered, replayable plan of Operation Contract envelopes plus resource bindings. Supports dry_run.",
|
|
294
|
+
"import": "plan + target → replay envelopes through the engine (§6.3); idempotent via each envelope's idempotency_key."
|
|
295
|
+
},
|
|
296
|
+
"step_required_fields": ["id", "label", "system", "mode", "required"],
|
|
297
|
+
"step_optional_fields": ["notes"],
|
|
298
|
+
"system_enum": ["workspace", "branding", "email", "phone", "domains", "accounts", "deployments", "marketplace", "tabs", "automation"],
|
|
299
|
+
"mode_enum": ["existing", "provision", "install", "generate", "configure"],
|
|
300
|
+
"edge_relations": ["uses_brand", "owns_domain", "routes_calls_to", "deploys_to", "has_surface", "contains_page", "installs_pack", "authenticates_account", "runs_workflow", "connects_to"],
|
|
301
|
+
"install_modes": ["optional", "recommended", "required"],
|
|
302
|
+
"id_remap": "Provision remaps slugs/workspace ids/links into the target; every internal link that resolved in the source MUST resolve post-import or the provision MUST fail.",
|
|
303
|
+
"upgrade": "Version steps run through a `migration` primitive plus structural-only `patch` envelopes; MUST NOT touch tenant_private data.",
|
|
304
|
+
"conformance": "import MUST be idempotent (re-run is a no-op via idempotency_key). A step's `mode` and `system` MUST be drawn from the enums above. Each `resource_bound` primitive (§5.5) declares its binding edge relation.",
|
|
305
|
+
"spec_ref": "§17"
|
|
306
|
+
},
|
|
307
|
+
|
|
308
|
+
"runtime": {
|
|
309
|
+
"description": "Workflow runtime contract (§11.8). A daemon, cron bridge, webhook worker, or agent host reads workflow triggers from the vault and derives Operation Contract envelopes. Scheduler queues, task dashboards, and cursor indexes are projections; the canonical schedule remains workflow frontmatter and the canonical history remains the event log.",
|
|
310
|
+
"trigger_types": ["manual", "cron", "interval", "event", "webhook", "file_change", "condition"],
|
|
311
|
+
"misfire_policies": ["skip", "run_once", "catch_up"],
|
|
312
|
+
"concurrency_policies": ["allow_parallel", "skip_if_running", "enqueue", "replace"],
|
|
313
|
+
"task_instantiation_fields": ["workflow_id", "workflow_path", "trigger_id", "trigger_type", "trigger_event_id", "scheduled_for", "dedupe_key"],
|
|
314
|
+
"run_statuses": ["queued", "claimed", "running", "waiting_for_human", "succeeded", "failed", "canceled", "retrying", "dead_letter"],
|
|
315
|
+
"idempotency_basis": "workspace_id + workflow_id + trigger_id + scheduled_for",
|
|
316
|
+
"spec_ref": "§11.8"
|
|
317
|
+
},
|
|
318
|
+
|
|
319
|
+
"semantic": {
|
|
320
|
+
"version": 1,
|
|
321
|
+
"identity_fields": ["semantic_id", "resource", "type", "path"],
|
|
322
|
+
"surface_fields": ["title", "description", "name", "slug", "aliases", "tags"],
|
|
323
|
+
"relation_fields": ["relations", "wiki_links", "markdown_links"],
|
|
324
|
+
"renderable_fields": ["title", "description", "body"],
|
|
325
|
+
"language_pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$",
|
|
326
|
+
"safe_default": "Semantic adapters exclude tenant_private and resource_bound documents unless an authorized context explicitly includes them. Runtime rendering never changes symbolic controls.",
|
|
327
|
+
"spec_ref": "§11.9"
|
|
328
|
+
},
|
|
329
|
+
|
|
330
|
+
"reserved_keys": ["type", "slug", "schema_version", "status", "feedback", "confidence", "semantic_id", "language", "relations"],
|
|
331
|
+
"host_field_prefix": "x_",
|
|
332
|
+
"spec_ref_reserved": "Appendix A"
|
|
333
|
+
}
|