skillscript-runtime 0.14.0 → 0.15.0

package/examples/connectors/DataStoreTemplate/DataStoreTemplate.ts

@@ -88,6 +88,13 @@ export class DataStoreTemplate implements DataStore {
    *   { capabilities_version: "1", manifest: { kind: "sqlite-fts",
    *       supported_modes: ["fts"], score_range: "unbounded",
    *       supported_filters: ["domain_tags"], supports_write: true } }
+   *
+   * **v0.14.1 — `supported_filters` is load-bearing.** The DataStoreMcpConnector
+   * bridge enforces this declaration: filter keys passed to `$ data_read` that
+   * aren't in `supported_filters` throw `UnsupportedFilterError` at the bridge
+   * BEFORE your `query()` runs. Adopters can opt out per-call with
+   * `permissive_filters: true`. Declare every filter your `query()` actually
+   * honors here; omissions become silent "this filter is rejected".
    */
   async manifest(): Promise<ManifestInfo<"data_store">> {
     // TODO — return a snapshot of your substrate's capabilities.
@@ -103,11 +110,17 @@ export class DataStoreTemplate implements DataStore {
    *   - `query`: string (search terms; substrate-specific interpretation)
    *   - `limit`: number (max results)
    *   - `mode`: "fts" | "semantic" | "rerank" | substrate-specific string
-   *   - Plus arbitrary additional filter fields (`domain_tags`, `thread_status`,
-   *     `payload_type`, `pinned`, `agent_id`, etc.) — substrate honors what
-   *     it supports, ignores the rest. Per the curated-subset framing in
-   *     `types.ts`, these top-level fields are first-class for substrates
-   *     that have them.
+   *   - Plus filter fields you declared in `manifest().supported_filters`
+   *     (`domain_tags`, `thread_status`, `payload_type`, `pinned`, `agent_id`,
+   *     etc.). Per the curated-subset framing in `types.ts`, these top-level
+   *     fields are first-class for substrates that have them.
+   *
+   * **v0.14.1 — what reaches `query()`.** The DataStoreMcpConnector bridge
+   * pre-filters the keys against your `manifest().supported_filters`
+   * declaration; unsupported keys throw `UnsupportedFilterError` upstream and
+   * never reach this method. So when `query()` runs, every non-base key in
+   * `filters` is one your manifest declared. Don't defensively code for
+   * "filter the caller didn't declare" — that's the bridge's job.
    *
    * `PortableData` core fields:
    *   - Always: `id`, `summary`, `created_at`
@@ -130,11 +143,11 @@ export class DataStoreTemplate implements DataStore {
   }
 
   /**
-   * Persist a new memory entry. Return the substrate-assigned `id` +
+   * Persist a new data record. Return the substrate-assigned `id` +
    * `created_at` (unix seconds).
    *
    * `DataWrite` shape:
-   *   - `content`: string (required; the memory body)
+   *   - `content`: string (required; the record body)
    *   - `tags`: string[] (optional; routed to substrate's tag mechanism)
    *   - `recipients`: string[] (optional advisory — substrates with alerting
    *     machinery use this to route notifications, e.g., AMP's mailbox model)
@@ -144,12 +157,12 @@ export class DataStoreTemplate implements DataStore {
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   async write(_entry: DataWrite): Promise<DataWriteRecord> {
-    // TODO — persist the memory via your substrate.
+    // TODO — persist the record via your substrate.
     //   - Generate or accept an id (substrate-dependent)
     //   - Persist content + tags + metadata
     //   - Apply recipients hint if your substrate has alerting
     //   - Apply expires_at if your substrate has TTL
     //   - Return { id, created_at }
-    throw new Error("TODO: write() — persist memory; return { id, created_at }.");
+    throw new Error("TODO: write() — persist record; return { id, created_at }.");
   }
 }

package/examples/connectors/DataStoreTemplate/README.md

@@ -2,7 +2,7 @@
 
 A skeleton `DataStore` implementation for adopters writing their own. Not runnable; every method throws a `TODO` error. Copy this directory, rename, fill in the substrate-specific work.
 
-Use this when you want skillscript memories backed by:
+Use this when you want skillscript data persistence backed by:
 - A vector database (Pinecone, Weaviate, Qdrant, Chroma)
 - A data store backing (memory broker like AMP, hosted memory API, vector DB, etc.)
 - A different SQL flavor (Postgres + pgvector, MySQL)
@@ -18,7 +18,7 @@ DataStore (choose which connector)
    └── Your fork from this template
 ```
 
-The runtime is substrate-agnostic. Memories don't know which backend they're stored against — the contract is the `DataStore` interface, and any class implementing it works.
+The runtime is substrate-agnostic. Data records don't know which backend they're stored against — the contract is the `DataStore` interface, and any class implementing it works.
 
 ## Forking workflow
 
@@ -72,8 +72,8 @@ The DataStore contract is narrower than SkillStore. Three methods + `staticCapab
 
 | Method | What it does | When called |
 |---|---|---|
-| `query(filters)` | Read memories by mode + filter; return `PortableData[]` | Every `$ data_read mode=... query=...` op |
-| `write(entry)` | Persist a new memory; return `{id, created_at}` | Every `$ data_write content=... -> R` op + `data_write` skill notify routes |
+| `query(filters)` | Read records by mode + filter; return `PortableData[]` | Every `$ data_read mode=... query=...` op |
+| `write(entry)` | Persist a new record; return `{id, created_at}` | Every `$ data_write content=... -> R` op + `data_write` skill notify routes |
 | `manifest()` | Capability snapshot for `runtime_capabilities` discovery | At startup + on-demand from MCP clients |
 
 Per the curated-subset framing in `src/connectors/types.ts`, `PortableData` has a 4-tier field model:
@@ -113,7 +113,7 @@ Honor what your substrate supports; ignore the rest. Document the supported set
 
 The `DataWrite` shape:
 
-- **`content`** (required) — the memory body
+- **`content`** (required) — the record body
 - **`tags`** (optional) — routed to your substrate's tag mechanism
 - **`recipients`** (optional) — advisory hint; substrates with alerting (e.g., AMP's mailbox model) use it
 - **`expires_at`** (optional) — unix seconds; substrates with TTL honor it
@@ -121,7 +121,7 @@ The `DataWrite` shape:
 
 Return `{id, created_at}` — the substrate-assigned identifier + creation timestamp (unix seconds).
 
-If your substrate doesn't support writes (read-only memory like a search index over a static corpus), set `supports_writes: false` in `staticCapabilities()` and throw from `write()`. The runtime + lint will respect the flag.
+If your substrate doesn't support writes (read-only store like a search index over a static corpus), set `supports_writes: false` in `staticCapabilities()` and throw from `write()`. The runtime + lint will respect the flag.
 
 ## Wiring against the dashboard / MCP
 

package/examples/connectors/McpConnectorTemplate/McpConnectorTemplate.ts

@@ -18,6 +18,13 @@
  *   - `DataStoreMcpConnector` — bridges a registered DataStore as
  *     `$ data_read mode=...` MCP dispatch. Auto-wired when DataStore substrate
  *     is configured.
+ *   - `SkillStoreMcpConnector` (v0.15.0) — bridges a registered SkillStore as
+ *     `$ skill_write` / `$ skill_read` MCP dispatch. Makes the Lisp-shape
+ *     primitive (skills program skills) work from inside an executing skill.
+ *     Auto-wired against `substrate.skill_store`. In-skill writes are forced
+ *     to `# Status: Draft` at the bridge per the v0.15.0 trust boundary —
+ *     see `src/connectors/skill-store-mcp.ts` header for the threat-model
+ *     rationale.
  *
  * Fork from this template when none of those fit — e.g.:
  *   - Direct HTTP MCP (JSON-RPC over HTTP, no child process)

package/examples/connectors/McpConnectorTemplate/README.md

@@ -9,7 +9,8 @@ A skeleton `McpConnector` implementation for adopters writing their own. Not run
 | `RemoteMcpConnector` | Stdio bridging to remote MCP servers (`npx mcp-remote ...`). YouTrack, GitHub, Linear, most adopter MCP wiring goes through this. JSON-configurable via `connectors.json`. |
 | `CallbackMcpConnector` | Wraps a JS function. Test rigs + embedder-wired transports where the dispatch is local code. |
 | `LocalModelMcpConnector` | Bridges a registered `LocalModel` as `$ llm prompt=...`. Auto-wired when `substrate.local_model` is set. |
-| `DataStoreMcpConnector` | Bridges a registered `DataStore` as `$ data_read mode=...`. Auto-wired when `substrate.data_store` is set. |
+| `DataStoreMcpConnector` | Bridges a registered `DataStore` as `$ data_read mode=...` + `$ data_write content=...`. Auto-wired when `substrate.data_store` is set. |
+| `SkillStoreMcpConnector` (v0.15.0) | Bridges a registered `SkillStore` as in-skill `$ skill_write` + `$ skill_read` dispatch (Lisp-shape: skills program skills). Auto-wired against `substrate.skill_store`. In-skill writes are forced to `# Status: Draft` at the bridge per the v0.15.0 trust boundary. |
 
 **Fork this template only when none of those fit** — e.g.:
 
@@ -139,7 +140,7 @@ The declarative path is the canonical adopter pattern for stdio-bridged remote M
 | Cardinality | Many instances per deployment | One singleton per slot |
 | Substrate config | Per-instance via top-level keys | `substrate` section short/object/custom |
 | Class extensibility | `registerConnectorClass()` for adopter-custom classes | Programmatic bootstrap (or `substrate.skill_store: {type: "custom", ...}` once async-bootstrap lands) |
-| Auto-wired bridges | `llm` + `memory` + `data_write` (LocalModel + DataStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
+| Auto-wired bridges | `llm` + `data_read` + `data_write` + `skill_read` + `skill_write` (v0.15.0 — LocalModel + DataStore + SkillStore exposed via bridge connectors) | n/a (these ARE the substrates being bridged) |
 
 McpConnector is fundamentally the "dispatch to external tools" surface — narrowest contract, broadest range of impls.
 

package/examples/connectors/README.md

@@ -9,7 +9,7 @@ Worked examples + fork-me templates for adopter-written connectors. The bundled
 | `SkillStore` | `FilesystemSkillStore`, `SqliteSkillStore` (in `src/connectors/`) | — | **[SkillStoreTemplate/](./SkillStoreTemplate/)** |
 | `DataStore` | `SqliteDataStore` (in `src/connectors/`) | — | **[DataStoreTemplate/](./DataStoreTemplate/)** |
 | `LocalModel` | `OllamaLocalModel` (in `src/connectors/`; opt-in via substrate config) | — | **[LocalModelTemplate/](./LocalModelTemplate/)** |
-| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `DataStoreMcpConnector` (in `src/connectors/`) | — | **[McpConnectorTemplate/](./McpConnectorTemplate/)** |
+| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `DataStoreMcpConnector`, `SkillStoreMcpConnector` (in `src/connectors/`) | — | **[McpConnectorTemplate/](./McpConnectorTemplate/)** |
 | `AgentConnector` | `NoOpAgentConnector` (in `src/connectors/`) | **[HttpWebhookAgentConnector/](./HttpWebhookAgentConnector/)** | — |
 
 **Bundled defaults** are runnable out of the box — wired through `connectors.json` substrate config or programmatic bootstrap.

package/examples/connectors/SkillStoreTemplate/SkillStoreTemplate.ts

@@ -26,6 +26,32 @@
  * you register via the registry, so once your fork passes the conformance
  * suite the entire skillscript surface (skill_write / skill_list /
  * execute_skill / etc.) reads + writes against your substrate.
+ *
+ * **v0.15.0 — `SkillStoreMcpConnector` bridge auto-wires against your impl.**
+ * The runtime's `defaultRegistry` wraps your registered SkillStore in a
+ * `SkillStoreMcpConnector` instance and registers it under the connector
+ * names `skill_read` + `skill_write`, so `$ skill_read` / `$ skill_write` from
+ * inside an executing skill dispatches through your `load()` / `store()`
+ * methods. This is the Lisp-shape primitive — skills can program skills —
+ * and works against any `SkillStore` impl that passes the conformance suite.
+ *
+ * Your impl doesn't need to do anything special to participate. Two things
+ * worth knowing:
+ *   - **In-skill writes arrive Draft-stamped.** The bridge layer applies a
+ *     `# Status: Draft` override to the body before calling your `store()`.
+ *     This is the v0.15.0 trust boundary — autonomously-generated skill
+ *     bodies (e.g., `~ qwen prompt="generate a skill"` → `$ skill_write`)
+ *     shouldn't bypass human review by landing Approved + immediately
+ *     executable. See `src/connectors/skill-store-mcp.ts` header for the
+ *     threat-model rationale. Outside-MCP `skill_write` (cold-author agents
+ *     authoring directly via the wire surface) keeps the existing "body
+ *     declares status, you auto-stamp via store()" path — that's the path
+ *     your `store()` honor-the-body-Status logic addresses.
+ *   - **Substrate-level lint runs at `store()` entry.** If you mirror
+ *     `FilesystemSkillStore` / `SqliteSkillStore`, you'll run tier-1 lint
+ *     on the body before persisting + throw `LintFailureError` on rejection.
+ *     The bridge propagates that error through `$ skill_write` so authors
+ *     see lint-rejection-on-write, not silent persistence of malformed bodies.
  */
 
 import type {

package/examples/custom-bootstrap.example.ts

@@ -86,14 +86,32 @@ registry.registerSkillStore("primary", skillStore);
 // Wire your own LocalModel, DataStore, AgentConnector here. For typed-
 // contract impls, this is the "case 1" wiring — substrate-portable.
 //   registry.registerLocalModel("default", new MyHostedLlmAdapter(...));
-//   registry.registerDataStore("primary", new MyMemoryAdapter(...));
+//   registry.registerDataStore("primary", new MyDataStoreAdapter(...));
 //   registry.registerAgentConnector("primary", new MyAgentHarnessAdapter(...));
 
-// Then wire bridges if you want the canonical `$ llm` / `$ data_read` surfaces:
-//   import { LocalModelMcpConnector, DataStoreMcpConnector } from "skillscript-runtime";
+// Then wire bridges if you want the canonical in-skill `$ llm` /
+// `$ data_read` / `$ data_write` / `$ skill_read` / `$ skill_write`
+// surfaces. Each bridge handles its multi-verb tool surface via toolName
+// discrimination; register the same instance under each connector name so
+// bare-form name-match resolution picks the right route.
+//   import { LocalModelMcpConnector, DataStoreMcpConnector, SkillStoreMcpConnector } from "skillscript-runtime";
 //   registry.registerMcpConnector("llm", new LocalModelMcpConnector(registry.getLocalModel("default")));
 //   const ms = registry.listDataStores().find((e) => e.name === "primary");
-//   if (ms !== undefined) registry.registerMcpConnector("data_read", new DataStoreMcpConnector(ms.instance));
+//   if (ms !== undefined) {
+//     const dataBridge = new DataStoreMcpConnector(ms.instance);
+//     registry.registerMcpConnector("data_read", dataBridge);
+//     registry.registerMcpConnector("data_write", dataBridge);
+//   }
+//   // v0.15.0 — SkillStore-as-bridge. Makes `$ skill_write` / `$ skill_read`
+//   // dispatchable from inside an executing skill (Lisp-shape: skills program
+//   // skills). In-skill writes are Draft-forced at the bridge layer; outside-MCP
+//   // skill_write keeps the existing "body declares status" behavior.
+//   const ss = registry.listSkillStores().find((e) => e.name === "primary");
+//   if (ss !== undefined) {
+//     const skillBridge = new SkillStoreMcpConnector(ss.instance);
+//     registry.registerMcpConnector("skill_read", skillBridge);
+//     registry.registerMcpConnector("skill_write", skillBridge);
+//   }
 
 // Wire any connectors.json instances.
 for (const c of connectors) {

package/examples/onboarding-scaffold/README.md

@@ -1,4 +1,4 @@
-# Onboarding scaffold — file-backed memory + OpenAI + tmux-shell
+# Onboarding scaffold — file-backed data store + OpenAI + tmux-shell
 
 A complete adopter-deployment example demonstrating substrate-portable wiring for skillscript-runtime. **~200 LOC across three adapter files** plus bootstrap. Copy this directory and modify for your own deployment.
 
@@ -25,7 +25,7 @@ cd ~/my-skillscript-deployment
 # 3. Set up env
 export SKILLSCRIPT_HOME=$(pwd)
 export OPENAI_API_KEY=sk-...
-cp memory.example.json memory.json  # initial memory
+cp data.example.json data.json  # initial data store seed
 
 # 4. Init skillscript dir layout
 skillfile init --here
@@ -49,7 +49,7 @@ node --loader ts-node/esm bootstrap.ts
 | `tmux-shell-agent-connector.ts` | `AgentConnector` impl — tmux send-keys | ~75 |
 | `bootstrap.ts` | Wiring — Registry, bridges, scheduler, MCP server | ~75 |
 | `connectors.json` | Example adopter-MCP wiring (empty by default) | — |
-| `memory.example.json` | Seed memory file with three example records | — |
+| `data.example.json` | Seed data file with three example records | — |
 
 ## Two-instance posture
 
@@ -77,4 +77,3 @@ The skill bodies don't need to change. `$ llm prompt=...` keeps working; `$ data
 
 - **Adopter playbook** — `docs/adopter-playbook.md` walks through Case 1 vs Case 2 wiring patterns
 - **Custom bootstrap walkthrough** — `examples/custom-bootstrap.example.ts` shows registering custom McpConnector classes via `registerConnectorClass`
-- **v0.8.x roadmap** — `$ data_write` ships in v0.8.x bundled with the auth model. When that lands, extend `FileDataStore` with the corresponding `write()` method.

package/examples/onboarding-scaffold/bootstrap.ts

@@ -1,4 +1,4 @@
-// Onboarding scaffold: complete bootstrap wiring file-backed memory +
+// Onboarding scaffold: complete bootstrap wiring file-backed data store +
 // OpenAI LLM + tmux-shell AgentConnector. v0.7.3.
 //
 // Copy this file into your deployment and modify substrate choices to
@@ -20,12 +20,13 @@ import {
 import { Scheduler } from "skillscript-runtime/scheduler";
 import { FilesystemTraceStore } from "skillscript-runtime/trace";
 import { McpServer } from "skillscript-runtime/mcp-server";
-// Note: LocalModelMcpConnector + DataStoreMcpConnector are bridge classes
-// already exported from skillscript-runtime/connectors. They wrap any
-// typed-contract impl as an MCP-dispatchable connector.
+// Note: LocalModelMcpConnector + DataStoreMcpConnector + SkillStoreMcpConnector
+// are bridge classes already exported from skillscript-runtime/connectors.
+// They wrap any typed-contract impl as an MCP-dispatchable connector.
 import {
   LocalModelMcpConnector,
   DataStoreMcpConnector,
+  SkillStoreMcpConnector,
 } from "skillscript-runtime/connectors";
 
 import { FileDataStore } from "./file-data-store.js";
@@ -43,9 +44,9 @@ const registry = new Registry();
 const skillStore = new FilesystemSkillStore(config.skillsDir ?? `${HOME}/skills`);
 registry.registerSkillStore("primary", skillStore);
 
-// File-backed memory at $SKILLSCRIPT_HOME/memory.json
+// File-backed data store at $SKILLSCRIPT_HOME/data.json
 const dataStore = new FileDataStore({
-  filePath: config.dataDbPath ?? `${HOME}/memory.json`,
+  filePath: config.dataDbPath ?? `${HOME}/data.json`,
 });
 registry.registerDataStore("primary", dataStore);
 
@@ -63,10 +64,25 @@ const agentConnector = new TmuxShellAgentConnector({
 });
 registry.registerAgentConnector("primary", agentConnector);
 
-// Step 3: wire bridges so `$ llm` / `$ data_read` dispatch through the
-// adopter substrates above (case 1 typed-contract wiring — portable).
+// Step 3: wire bridges so canonical in-skill `$ llm` / `$ data_read` /
+// `$ data_write` / `$ skill_read` / `$ skill_write` dispatch through the
+// adopter substrates above (case 1 typed-contract wiring — portable). Each
+// bridge handles its multi-verb surface via toolName discrimination;
+// register the same instance under each connector name so bare-form
+// name-match resolution picks the right route.
 registry.registerMcpConnector("llm", new LocalModelMcpConnector(openai));
-registry.registerMcpConnector("data_read", new DataStoreMcpConnector(dataStore));
+const dataBridge = new DataStoreMcpConnector(dataStore);
+registry.registerMcpConnector("data_read", dataBridge);
+registry.registerMcpConnector("data_write", dataBridge);
+// v0.15.0 — SkillStore-as-bridge. Makes `$ skill_write` / `$ skill_read`
+// dispatchable from inside an executing skill (Lisp-shape: skills program
+// skills). In-skill writes are forced to `# Status: Draft` at the bridge
+// layer per the v0.15.0 trust boundary — see `src/connectors/skill-store-mcp.ts`
+// header for the threat-model rationale. Outside-MCP `skill_write` (via the
+// wire surface) keeps its existing "body declares status" behavior.
+const skillBridge = new SkillStoreMcpConnector(skillStore);
+registry.registerMcpConnector("skill_read", skillBridge);
+registry.registerMcpConnector("skill_write", skillBridge);
 
 // Step 4: wire connectors.json instances (adopter-defined MCP servers).
 for (const c of connectors) {

package/examples/onboarding-scaffold/connectors.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Onboarding scaffold connectors.json — wires example MCP servers an adopter might add alongside the bundled bridges. Most onboarding deployments don't need anything here; the file-backed memory + OpenAI LLM + tmux-shell wiring lives in bootstrap.ts. This file is the place for adopter-specific MCP servers (your in-house tools, a YouTrack instance, a custom agent API, etc.).",
+  "_comment": "Onboarding scaffold connectors.json — wires example MCP servers an adopter might add alongside the bundled bridges. Most onboarding deployments don't need anything here; the file-backed data store + OpenAI LLM + tmux-shell wiring lives in bootstrap.ts. This file is the place for adopter-specific MCP servers (your in-house tools, a YouTrack instance, a custom agent API, etc.).",
 
   "_example_remote_mcp": {
     "class": "RemoteMcpConnector",

package/examples/onboarding-scaffold/file-data-store.ts

@@ -22,11 +22,11 @@ import type {
 } from "skillscript-runtime/connectors";
 
 export interface FileDataStoreConfig {
-  /** Absolute path to the JSON file holding the memory array. */
+  /** Absolute path to the JSON file holding the data records. */
   filePath: string;
 }
 
-interface FileMemoryRecord extends PortableData {
+interface FileDataRecord extends PortableData {
   /** Optional substrate-specific fields go in `metadata`; everything top-level matches PortableData. */
 }
 
@@ -77,7 +77,7 @@ export class FileDataStore implements DataStore {
     const created_at = Math.floor(Date.now() / 1000);
     const firstLine = entry.content.split("\n")[0] ?? entry.content;
     const summary = firstLine.length > 200 ? firstLine.slice(0, 197) + "..." : firstLine;
-    const newRecord: FileMemoryRecord = {
+    const newRecord: FileDataRecord = {
       id,
       summary,
       detail: entry.content,
@@ -92,7 +92,7 @@ export class FileDataStore implements DataStore {
             },
           }
         : {}),
-    } as FileMemoryRecord;
+    } as FileDataRecord;
     records.push(newRecord);
     writeFileSync(this.config.filePath, JSON.stringify(records, null, 2), "utf8");
     return { id, created_at };
@@ -106,19 +106,30 @@ export class FileDataStore implements DataStore {
         file_path: this.config.filePath,
         record_count: this.loadFile().length,
         supports_write: true,
+        // v0.14.1 strict-filters: the bridge enforces every non-base filter
+        // key in `query()` calls against this declared set, throwing
+        // UnsupportedFilterError for unknowns. This reference impl's
+        // substring scorer doesn't actually filter on any field (it
+        // ignores everything beyond `query` + `limit`), so the honest
+        // declaration is `[]`. Adopters who extend `query()` to honor
+        // `domain_tags` / `payload_type` / etc. should add those names
+        // here so the bridge stops rejecting them. Callers that need
+        // to pass advisory filters this impl ignores can opt out per-
+        // call via `permissive_filters: true`.
+        supported_filters: [],
       },
     };
   }
 
-  private loadFile(): FileMemoryRecord[] {
+  private loadFile(): FileDataRecord[] {
     if (!existsSync(this.config.filePath)) return [];
     try {
       const raw = readFileSync(this.config.filePath, "utf8");
       const parsed: unknown = JSON.parse(raw);
       if (!Array.isArray(parsed)) {
-        throw new Error(`FileDataStore: '${this.config.filePath}' top-level must be an array of memory records.`);
+        throw new Error(`FileDataStore: '${this.config.filePath}' top-level must be an array of data records.`);
       }
-      return parsed as FileMemoryRecord[];
+      return parsed as FileDataRecord[];
     } catch (err) {
       throw new Error(`FileDataStore: failed to read '${this.config.filePath}': ${(err as Error).message}`);
     }

package/examples/programmatic-trace-demo.mjs

@@ -34,7 +34,7 @@ const SKILL_SRC = `# Skill: heartbeat
 # Triggers: cron: */1 * * * *
 
 emit:
-    ! heartbeat at $(EVENT.fired_at_unix)
+    emit(text="heartbeat at $(EVENT.fired_at_unix)")
 
 default: emit
 `;

package/examples/skillscripts/classify-support-ticket.skill.md

@@ -1,30 +1,31 @@
 # Skill: classify-support-ticket
-# Status: Approved v1:99819a42
+# Status: Approved v1:670a94cf
+# Autonomous: true
 # Description: Read an incoming support ticket and route it: severity-1 tickets get paged to ops-channel, billing tickets get tagged for finance review, everything else gets a draft reply queued for human review
 # Vars: TICKET_TEXT, TICKET_ID
 # Output: agent: ops-oncall
 
 classify:
-    $ llm prompt="Categorize this support ticket. Reply with EXACTLY one of: 'sev-1', 'billing', 'general'. No other text.\n\nTicket: ${TICKET_TEXT}" model=qwen maxTokens=10 -> CATEGORY
+    $ llm prompt="Categorize this support ticket. Reply with EXACTLY one of: 'sev-1', 'billing', 'general'. No other text.\n\nTicket: ${TICKET_TEXT}" maxTokens=10 -> CATEGORY
 
 severity_check:
     needs: classify
-    $ llm prompt="Does this support ticket describe a service outage, data loss, security incident, or other production-severity-1 issue? Reply ONLY 'yes' or 'no'.\n\nTicket: ${TICKET_TEXT}" model=qwen maxTokens=10 -> IS_SEV1
+    $ llm prompt="Does this support ticket describe a service outage, data loss, security incident, or other production-severity-1 issue? Reply ONLY 'yes' or 'no'.\n\nTicket: ${TICKET_TEXT}" maxTokens=10 -> IS_SEV1
 
 route:
     needs: severity_check
     if ${CATEGORY|trim} == "sev-1":
         emit(text="PAGE: sev-1 ticket ${TICKET_ID} - ${TICKET_TEXT}")
-        $ datastore.write summary="sev-1 ticket ${TICKET_ID}" detail="${TICKET_TEXT}" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","page"]
+        $ data_write content="sev-1 ticket ${TICKET_ID}: ${TICKET_TEXT}" tags=["support","sev-1","page"]
     elif ${IS_SEV1|trim} == "yes":
         emit(text="PAGE: classifier said ${CATEGORY|trim} but severity-check flagged this as sev-1: ${TICKET_ID}")
-        $ datastore.write summary="sev-1 escalation ${TICKET_ID}" detail="category=${CATEGORY|trim} but severity-check=yes" knowledge_type=hard_won vault=private domain_tags=["support","sev-1","disagreement"]
+        $ data_write content="sev-1 escalation ${TICKET_ID}: category=${CATEGORY|trim} but severity-check=yes" tags=["support","sev-1","disagreement"]
     elif ${CATEGORY|trim} == "billing":
         $set TAG_FOR = "finance"
         emit(text="Tagged for ${TAG_FOR} review: ${TICKET_ID}")
-        $ datastore.write summary="billing ticket ${TICKET_ID}" detail="${TICKET_TEXT}" knowledge_type=common vault=private domain_tags=["support","billing"]
+        $ data_write content="billing ticket ${TICKET_ID}: ${TICKET_TEXT}" tags=["support","billing"]
     else:
-        $ llm prompt="Draft a polite acknowledgment reply for this support ticket. Two short sentences. No greeting, no sign-off.\n\n${TICKET_TEXT}" model=qwen maxTokens=150 -> DRAFT
-        $ datastore.write summary="support draft ${TICKET_ID}" detail="${DRAFT|trim}" knowledge_type=common vault=private domain_tags=["support","draft"]
+        $ llm prompt="Draft a polite acknowledgment reply for this support ticket. Two short sentences. No greeting, no sign-off.\n\n${TICKET_TEXT}" maxTokens=150 -> DRAFT
+        $ data_write content="support draft ${TICKET_ID}: ${DRAFT|trim}" tags=["support","draft"]
 
 default: route

package/examples/skillscripts/cut-release-tag.skill.md

@@ -1,5 +1,5 @@
 # Skill: cut-release-tag
-# Status: Approved v1:eb29a798
+# Status: Approved v1:d3c2a91b
 # Description: Run when the user says "ship a release" or "cut a tag" on the current branch; collects commit-list since last tag, asks the user to confirm the version bump, applies the tag, and pushes it
 # Vars: BUMP_KIND=patch
 # Output: text
@@ -12,13 +12,13 @@ else:
 
 commits_since:
     needs: last_tag
-    shell(command="git log --oneline ${PREV_TAG}..HEAD") -> COMMITS
+    shell(command="git log --oneline \"${PREV_TAG}\"..HEAD") -> COMMITS
 else:
     $set COMMITS = "(unable to read commit log; proceeding without preview)"
 
 propose:
     needs: commits_since
-    $ llm prompt="Propose the next semver tag given prev tag '${PREV_TAG}', bump kind '${BUMP_KIND}', and commits below. Return ONLY the new tag string (e.g. v1.4.3). No commentary.\n\nCommits:\n${COMMITS}" model=qwen maxTokens=30 -> PROPOSED_TAG
+    $ llm prompt="Propose the next semver tag given prev tag '${PREV_TAG}', bump kind '${BUMP_KIND}', and commits below. Return ONLY the new tag string (e.g. v1.4.3). No commentary.\n\nCommits:\n${COMMITS}" maxTokens=30 -> PROPOSED_TAG
 
 confirm:
     needs: propose
@@ -30,11 +30,11 @@ confirm:
 
 apply:
     needs: confirm
-    shell(command="git tag ${PROPOSED_TAG|trim}") -> TAG_OUT
-    shell(command="git push origin ${PROPOSED_TAG|trim}") -> PUSH_OUT
+    shell(command="git tag \"${PROPOSED_TAG|trim}\"") -> TAG_OUT
+    shell(command="git push origin \"${PROPOSED_TAG|trim}\"") -> PUSH_OUT
     emit(text="Tagged and pushed ${PROPOSED_TAG|trim}")
 else:
     emit(text="Tag/push failed; rolling back local tag")
-    shell(command="git tag -d ${PROPOSED_TAG|trim}") -> ROLLBACK
+    shell(command="git tag -d \"${PROPOSED_TAG|trim}\"") -> ROLLBACK
 
 default: apply

package/examples/skillscripts/data-store-roundtrip.skill.md

@@ -0,0 +1,11 @@
+# Skill: data-store-roundtrip
+# Status: Approved v1:83897803
+# Autonomous: true
+# Description: Round-trips the DataStore — writes a record, reads it back via full-text search. If this skill executes and emits a successful round-trip, your DataStore substrate is wired correctly.
+
+run:
+    $ data_write content="adopter dogfood probe record" tags=["phase1","probe"] -> W
+    $ data_read mode="fts" query="adopter dogfood probe" limit=5 -> R
+    emit(text="wrote record '${W.id}'; read back ${R.items|length} items")
+
+default: run

package/examples/skillscripts/doc-qa-with-citations.skill.md

@@ -1,12 +1,12 @@
 # Skill: doc-qa-with-citations
-# Status: Approved v1:2187bf35
-# Description: When the user asks a question that requires retrieval over the doc set, answer with inline citations to memory IDs
+# Status: Approved v1:6e5dc167
+# Description: When the user asks a question that requires retrieval over the doc set, answer with inline citations to record IDs
 # Vars: QUESTION, K=6
 # Output: text
 
 answer:
     $ data_read mode=rerank query="${QUESTION}" limit=${K} -> HITS (fallback: [])
-    $ llm prompt="Answer the question using ONLY the supplied passages. Cite each claim inline as [id:<memory-id>]. Question: ${QUESTION}. Passages: ${HITS|json}" maxTokens=900 -> RESPONSE
+    $ llm prompt="Answer the question using ONLY the supplied passages. Cite each claim inline as [id:<record-id>]. Question: ${QUESTION}. Passages: ${HITS|json}" maxTokens=900 -> RESPONSE
     emit(text="${RESPONSE}")
 
 default: answer

package/examples/skillscripts/feedback-sentiment-scan.skill.md

@@ -1,12 +1,13 @@
 # Skill: feedback-sentiment-scan
-# Status: Approved v1:111610fc
+# Status: Approved v1:4484f7e0
+# Autonomous: true
 # Description: Each night, scan the previous 24h of customer feedback records, classify sentiment via local model, surface entries where sentiment is "frustrated" or "blocking" so the team sees them at start-of-day; skip entries already seen on prior nights
 # Triggers: cron: 0 3 * * *
 # Vars: SCAN_LIMIT=50
 # Output: agent: support-lead
 
 fetch_new:
-    $ data_read mode=fts query="customer feedback" limit=${SCAN_LIMIT} created_after=${EVENT.fired_at_unix} -> FEEDBACK
+    $ data_read mode=fts query="customer feedback" limit=${SCAN_LIMIT} -> FEEDBACK
 
 fetch_seen:
     $ data_read mode=fts query="sentiment-scan seen marker" limit=200 domain_tags=["sentiment-scan-seen"] -> SEEN_MARKERS
@@ -14,15 +15,15 @@ fetch_seen:
 classify_and_emit:
     needs: fetch_new, fetch_seen
     emit(text="Sentiment scan results for ${NOW}:")
-    foreach F in ${FEEDBACK}:
-        if ${F.id|trim} in ${SEEN_MARKERS}:
+    foreach F in ${FEEDBACK.items}:
+        if ${F.id|trim} in ${SEEN_MARKERS.items}:
             emit(text="- skipped (already classified): ${F.id|trim}")
-        elif ${F.id|trim} not in ${SEEN_MARKERS}:
-            $ llm prompt="Classify the sentiment of this customer feedback. Respond with ONE word: 'frustrated', 'blocking', 'satisfied', 'neutral'. No explanation.\n\nFeedback: ${F.summary}\nDetail: ${F.detail}" model=gemma2 maxTokens=10 -> VERDICT
+        elif ${F.id|trim} not in ${SEEN_MARKERS.items}:
+            $ llm prompt="Classify the sentiment of this customer feedback. Respond with ONE word: 'frustrated', 'blocking', 'satisfied', 'neutral'. No explanation.\n\nFeedback: ${F.summary}\nDetail: ${F.detail}" maxTokens=10 -> VERDICT
             if ${VERDICT|trim} == "frustrated":
                 emit(text="- FRUSTRATED [${F.id|trim}] ${F.summary}")
             elif ${VERDICT|trim} == "blocking":
                 emit(text="- BLOCKING [${F.id|trim}] ${F.summary}")
-            $ datastore.write summary="sentiment-scan seen ${F.id|trim}" detail="verdict=${VERDICT|trim} on ${EVENT.fired_at_unix}" knowledge_type=common vault=private domain_tags=["sentiment-scan-seen"] expires_at=${EVENT.fired_at_plus_7d_unix}
+            $ data_write content="sentiment-scan seen ${F.id|trim} verdict=${VERDICT|trim} on ${EVENT.fired_at_unix}" tags=["sentiment-scan-seen"] expires_at=${EVENT.fired_at_plus_7d_unix} -> ACK
 
 default: classify_and_emit

package/examples/skillscripts/hello-world.skill.md

@@ -0,0 +1,10 @@
+# Skill: hello-world
+# Status: Approved v1:5ce6d5bf
+# Description: The canonical first-run example. No substrate dependencies — pure emit. If this fails to execute, your install or runtime is broken; investigate before troubleshooting deeper layers. Demonstrates `# Vars:` declared inputs with `--input` override.
+# Vars: WHO=world
+
+greet:
+    emit(text="Hello, ${WHO}!")
+    emit(text="Your install is healthy. Try skill-store-roundtrip + data-store-roundtrip next to verify substrate wiring.")
+
+default: greet

package/examples/skillscripts/{hello.skill.provenance.json → hello-world.skill.provenance.json}

@@ -2,9 +2,9 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-05-30T14:28:14.260Z",
+  "compiled_at": "2026-06-01T14:54:14.858Z",
   "source_skill": {
-    "name": "hello"
+    "name": "hello-world"
   },
   "data_skills_inlined": []
 }

package/examples/skillscripts/morning-brief.skill.md

@@ -1,5 +1,5 @@
 # Skill: morning-brief
-# Status: Approved v1:037c18af
+# Status: Approved v1:091ae2ae
 # Description: Compose a daily morning brief from calendar, mailbox, and overnight data writes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc.
 # Vars: AGENT, BRIEF_HORIZON_HOURS=24
 # Triggers: cron: 0 7 * * *

package/examples/skillscripts/service-health-watch.skill.md

@@ -1,6 +1,7 @@
 # Skill: service-health-watch
-# Status: Approved v1:7c93b4b4
-# Description: Every 5 minutes check named service endpoints — if latency or status degrades, write a signal memory and alert
+# Status: Approved v1:628c8c69
+# Autonomous: true
+# Description: Every 5 minutes check named service endpoints — if latency or status degrades, write a signal record and alert
 # Vars: SERVICES=[auth-api, ledger-api, search-api], LATENCY_BUDGET_MS=400
 # Triggers: cron: */5 * * * *
 # Output: none
@@ -10,8 +11,8 @@ probe:
         shell(command="curl -s -o /dev/null -w \"%{http_code} %{time_total}\" https://status.internal/${SVC|url}") -> RAW
         $ llm prompt="From the line '${RAW|trim}' (http_code time_seconds), and budget ${LATENCY_BUDGET_MS} ms, answer ok or degraded only." -> STATUS
         if ${STATUS|trim} == "degraded":
-            $ datastore.write summary="service degradation: ${SVC}" detail="probe at ${NOW}: ${RAW|trim}" domain_tags=[ops, service-health, degraded:${SVC}] vault=private knowledge_type=common expires_at=${EVENT.fired_at_plus_1d_unix} -> ACK
-            emit(text="${SVC} degraded — wrote signal")
+            $ data_write content="service degradation: ${SVC} at ${NOW}: ${RAW|trim}" tags=["ops","service-health","degraded:${SVC}"] expires_at=${EVENT.fired_at_plus_1d_unix} -> ACK
+            emit(text="${SVC} degraded — wrote signal ${ACK.id}")
         else:
             emit(text="${SVC} ok")
 

package/examples/skillscripts/skill-store-roundtrip.skill.md

@@ -0,0 +1,11 @@
+# Skill: skill-store-roundtrip
+# Status: Approved v1:a3d46cf0
+# Autonomous: true
+# Description: Round-trips the SkillStore — writes a child skill, reads it back. Demonstrates the Lisp-shape primitive (skills can write skills). NOTE: under v0.15.0, in-skill `$ skill_write` lands the child as `# Status: Draft` regardless of what the body declares — to run the generated child, an authorized agent (human via dashboard, or MCP-direct) reviews + promotes via the outside-MCP `skill_status` tool. The Draft-default gate keeps autonomously-written skills out of the immediate execution loop.
+
+run:
+    $ skill_write name="hello-child" source="# Skill: hello-child\n# Status: Approved\nrun:\n    emit(text=\"hello from a programmatically-authored skill\")\ndefault: run\n" -> W
+    $ skill_read name="hello-child" -> R
+    emit(text="wrote skill '${W.name}' as Status: ${W.status}; read back ${R.source|length} bytes")
+
+default: run