SSSS — Structured Semantic Syntax System

A database-free, Markdown-first schema and mutation contract for AI-agent state. Turn an autonomous agent ecosystem into a single portable, tradeable bundle.

SSSS is a vendor-neutral standard and reference implementation for portable AI memory and state. It defines:

• Document primitives — typed Markdown files with YAML frontmatter (workflow, rule, page, assistant, …), validated against a registry, not hand-written code.
• The Operation Contract (§6) — four envelope types (operation / patch / event / delete) for mutating a vault, with idempotency replay and audit.
• The Workflow Runtime Contract (§11.8) — workflows own triggers; daemons, crons, and webhooks derive idempotent event/task/run envelopes from the vault.
• Multilingual semantic runtime (§11.9) — deterministic lexical evidence, injected multilingual embeddings, and runtime rendering with symbolic controls fixed.
• Portability classification (§5.5) — the keystone: every primitive is structural, tenant_private, or resource_bound, so a vault can be sold or shared without leaking private data.
• The .ucw bundle format (§16) and provisioning contract (§17) — package a vault, then export → provision → import it into a fresh environment, deterministically.

This package, @gregiteen/ssss-cli, is dependency-free: a host needs neither Zod nor a YAML library to be conformant. The reference engine is the validator.

Install

npm install -g @gregiteen/ssss-cli      # the `ssss` command
# or use it as a library:
npm install @gregiteen/ssss-cli

Requires Node 18+. No runtime dependencies.

Start a new project

ssss new my-app --install                # scaffold + install + run the conformance test

Scaffolds a starter vault/, a dependency-free conformance test, and instructions. See ssss help scaffold.

Quick start — the lifecycle

vault ──export──▶ .ucw bundle ──provision──▶ envelope plan ──import──▶ new vault
        (§16, pure)            (§17, params + links)        (§6, idempotent)

# 1. Package a vault as a sellable bundle (drops tenant-private data)
ssss export ./my-vault --profile sale --out bundle.ucw.json

# 2. Inspect / verify it
ssss inspect  bundle.ucw.json --files
ssss validate bundle.ucw.json

# 3. Stand up a fresh tenant from it
ssss import bundle.ucw.json --vault ./new-tenant \
  --param company_name="Acme Corp" --param domain=acme.com

# Re-running import commits nothing — it is idempotent.

0.9 application kernel

SSSS 0.9 provides a shared mutation kernel and host adapter contracts for any system using SSSS:

ssss primitive create --namespace acme --name "New Item" --language en
ssss registry compose --extension ./acme-extension.json
ssss adapter conformance
ssss migrate 0.8-to-0.9 ./vault

Library subpaths: @gregiteen/ssss-cli/kernel, /vfs, /identity, /leases, /events, /projections, /semantic, /ui.

Commands

| Command | Purpose | |---------|---------| | ssss new <dir> | Scaffold a new SSSS project (--install). | | ssss primitive <verb> | Create, validate, inspect, or migrate primitive definitions. | | ssss registry <verb> | Compose, lock, or verify an effective registry. | | ssss adapter conformance | Run machine-readable VFS/lease/idempotency contract suites. | | ssss migrate 0.8-to-0.9 | Dry-run migration diagnostics with backup manifest. | | ssss export <vault> | Package a vault into a .ucw bundle (§16). Pure & deterministic. | | ssss validate <bundle> | Check a bundle against the schema + portability rules. | | ssss inspect <bundle> | Human-readable summary (manifest, inventory, params, steps). | | ssss provision <bundle> | Plan an install: params + link integrity → envelopes (§17). | | ssss import <bundle> | Replay a bundle/plan into a vault via the engine (idempotent). | | ssss semantic <vault> | Build or query a deterministic, privacy-safe semantic index (§11.9). | | ssss autolink [dir] | Generate OKF wiki-links across a vault. | | ssss conformance | Run the canonical conformance suite (§12). | | ssss help [topic] | Local docs: runtime, portability, bundle, provisioning, leases, … |

Run ssss <command> --help for flags, or ssss help <topic> for concepts.

Portability — why a vault is safe to sell

| Class | Meaning | In a sale export? | |-------|---------|---------------------| | structural | The sellable business model (workflow, rule, page, …). | ✅ shipped | | resource_bound | Needs a real resource bound at provision (domain, phone_number). | ✅ shipped (as a parameter/step) | | tenant_private | The operator's private data (task, customer records). | ❌ dropped |

template and sale exports MUST drop every tenant_private file. The reference bundle proves it — see ssss help portability.

Conformance

A host MUST NOT claim SSSS conformance without passing the suite in conformance/:

ssss conformance            # structural + registry validation
ssss conformance --engine   # + replay all fixtures + round-trip the reference bundle
npm test                    # == ssss conformance --engine

Repository layout

docs/ssss-spec.md          The normative specification (v0.9).
docs/help/                 Topic docs surfaced by `ssss help`.
registry/core.json         15 document + 5 contract primitives; semantic, bundle & provisioning schemas.
registry/extensions/       Application extension registries.
src/engine.mjs             Operation Contract engine (§6).
src/runtime.mjs            Workflow trigger → event/task/run envelope planning (§11.8).
src/semantic.mjs           Multilingual semantic retrieval + runtime rendering (§11.9).
src/bundle.mjs             export / validate / provision / import (§16–§17).
src/registry.mjs           Registry-driven type + portability resolution.
src/frontmatter.mjs        Zero-dependency YAML frontmatter.
scripts/ssss.mjs           The `ssss` CLI dispatcher.
conformance/               Canonical fixtures + reference bundle.
skills/ssss/               Packaged SSSS system skill and dependency-free validator.

License

ISC © Greg Iteen. See LICENSE.