skillscript-runtime 0.10.0 → 0.13.2

package/examples/connectors/MemoryStoreTemplate/README.md

@@ -0,0 +1,169 @@
+# MemoryStoreTemplate — fork-me skeleton
+
+A skeleton `MemoryStore` 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:
+- A vector database (Pinecone, Weaviate, Qdrant, Chroma)
+- A memory system (AMP, hosted memory API)
+- A different SQL flavor (Postgres + pgvector, MySQL)
+- An HTTP CRUD service
+- Anything else with query + write semantics
+
+## The three legs
+
+```
+MemoryStore (choose which connector)
+   ├── SqliteMemoryStore (bundled, SQLite + FTS5 — src/connectors/memory-store.ts)
+   ├── (no other bundled impl — vector DBs and remote services are adopter-side)
+   └── Your fork from this template
+```
+
+The runtime is substrate-agnostic. Memories don't know which backend they're stored against — the contract is the `MemoryStore` interface, and any class implementing it works.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/MemoryStoreTemplate examples/connectors/MyMemoryStore
+```
+
+1. **Rename the class.** Convention: `<Substrate>MemoryStore` (e.g., `PineconeMemoryStore`, `PostgresMemoryStore`, `AmpMemoryStore`).
+2. **Define your config interface.** Edit `MemoryStoreTemplateConfig` to declare what your substrate needs (connection URL, API key, vault name, index name, etc.).
+3. **Implement each method.** Three methods + `staticCapabilities()`. Each has a TODO comment in the skeleton explaining what to do.
+4. **Update `staticCapabilities()`** to declare what your impl actually supports. The runtime + lint consult these flags before exercising features.
+5. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyMemoryStore } from "./MyMemoryStore.js";
+
+   const registry = new Registry();
+   registry.registerMemoryStore("primary", new MyMemoryStore({
+     // your config
+   }));
+   ```
+
+6. **Validate via the conformance suite:**
+
+   ```typescript
+   import { describe, it } from "vitest";
+   import { MemoryStoreConformance } from "skillscript-runtime/testing";
+   import { MyMemoryStore } from "./MyMemoryStore.js";
+
+   describe("MyMemoryStore conformance", () => {
+     const tests = MemoryStoreConformance.buildTests({
+       build: () => new MyMemoryStore({ /* test config */ }),
+       ctor: MyMemoryStore,
+     });
+     for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
+   });
+   ```
+
+   The conformance suite verifies your impl honors the contract: method presence, return-type shape, capability flag self-consistency. Passes → runtime treats your impl interchangeably with `SqliteMemoryStore`.
+
+## Reference implementation
+
+When in doubt about semantics, read the bundled impl:
+
+- **`src/connectors/memory-store.ts`** — `SqliteMemoryStore`, SQLite + FTS5-backed. Schema lives in `bootstrap()` (memories table + FTS virtual table + AFTER INSERT/UPDATE/DELETE triggers). Single-process. Capability flags: `supports_writes: true`, `supports_tag_filter: true`, FTS only (semantic / rerank false).
+
+## Contract surface (3 methods)
+
+The MemoryStore contract is narrower than SkillStore. Three methods + `staticCapabilities()`:
+
+| Method | What it does | When called |
+|---|---|---|
+| `query(filters)` | Read memories by mode + filter; return `PortableMemory[]` | Every `$ memory mode=... query=...` op |
+| `write(entry)` | Persist a new memory; return `{id, created_at}` | Every `$ memory_write content=... -> R` op + `memory_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`, `PortableMemory` has a 4-tier field model:
+
+1. **Core fields** — `id`, `summary`, `detail`, `score` (always-meaningful)
+2. **Curated substrate subset** — top-level fields with portable concepts: `domain_tags`, `payload_type`, `knowledge_type`, `pinned`, `confidence`, `thread_status`, `recipients`, `expires_at`, `agent_id`, `vault`
+3. **Substrate-specific** — accessed via `metadata.X` (catch-all)
+4. **Ambient passthrough** — literal `$(MEMORY.field)` references for unknowns
+
+**Connector duplication discipline**: a curated-subset field must be at top-level only, never also in `metadata`. Silent divergence otherwise.
+
+## Query modes
+
+`QueryFilters.mode` is the dispatch axis:
+
+- **`"fts"`** — full-text search; substrate-defined (BM25, BM25F, etc.). `SqliteMemoryStore` supports this via FTS5.
+- **`"semantic"`** — embedding-based similarity. Vector-DB substrates support this; `SqliteMemoryStore` does not.
+- **`"rerank"`** — substrate-defined hybrid (e.g., FTS retrieve + embedding rerank). Optional.
+- **substrate-specific strings** — your fork can define its own modes; document them in `manifest().manifest.supported_modes`.
+
+Throw a clear error on unsupported modes (don't silently fall back; cold authors will be confused).
+
+## Filter fields
+
+`QueryFilters` extends a base shape with arbitrary additional filter keys. Common filters substrates honor:
+
+- **`domain_tags`** — string or array; substrate-specific match semantics (substring vs exact; AND vs OR)
+- **`payload_type`** — usually exact match
+- **`thread_status`** — usually exact match (set if your substrate has thread lifecycle)
+- **`pinned`** — boolean
+- **`agent_id`** — adopter-side scoping
+- **`recipients`** — array match (any-of)
+
+Honor what your substrate supports; ignore the rest. Document the supported set in `manifest().manifest.supported_filters`.
+
+## `write()` semantics
+
+The `MemoryWrite` shape:
+
+- **`content`** (required) — the memory 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
+- **`metadata`** (optional) — catch-all for substrate extensions (`vault`, `payload_type`, `confidence`, etc.)
+
+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.
+
+## Wiring against the dashboard / MCP
+
+Runtime hosts honor whichever MemoryStore impl your registry has. To make your fork visible through `skillfile dashboard`:
+
+- Write a custom bootstrap that constructs the runtime with your MemoryStore (see `src/bootstrap.ts` for the reference shape)
+- OR (planned future) declare in `~/.skillscript/connectors.json`:
+
+  ```json
+  {
+    "substrate": {
+      "memory_store": {
+        "type": "custom",
+        "module": "./my-memory-store.js",
+        "export": "MyMemoryStore",
+        "config": { "pineconeApiKey": "${PINECONE_KEY}" }
+      }
+    }
+  }
+  ```
+
+  Current limitation: sync `bootstrap()` can't dynamic-import, so the `custom` form surfaces an error today. Programmatic bootstrap is the path until async-bootstrap support lands.
+
+## MemoryStore vs SkillStore differences
+
+Both are substrate-agnostic, but they differ in shape:
+
+| Aspect | SkillStore | MemoryStore |
+|---|---|---|
+| Methods | 8 (load, query, metadata, versions, store, delete, update_status, manifest) | 3 (query, write, manifest) |
+| Versioning | First-class (`versions()`, `load(name, version)`) | Substrate-side (e.g., `supersededById` in AMP); not in contract |
+| Status lifecycle | Draft/Approved/Disabled with approval-token stamping | None |
+| Mutation gates | Approved transitions require approval token | None — writes are append-only |
+| Curated-subset fields | None | Many (`domain_tags`, `pinned`, `confidence`, `recipients`, etc.) |
+| Forking complexity | Higher (multi-method state machine) | Lower (three methods, simpler semantics) |
+
+The narrower contract is why MemoryStoreTemplate ships sooner + smaller than SkillStoreTemplate.
+
+## Further reading
+
+- **[`../../../docs/configuration.md`](../../../docs/configuration.md)** — substrate selection via `connectors.json`
+- **[`../../../docs/adopter-playbook.md`](../../../docs/adopter-playbook.md)** — programmatic-bootstrap patterns; two-instance posture
+- **`src/connectors/types.ts`** — authoritative `MemoryStore` interface, `PortableMemory`, `QueryFilters`, `MemoryWrite` types
+- **`src/testing/conformance.ts`** — the per-contract conformance test suites
+- **`src/connectors/memory-store.ts`** — `SqliteMemoryStore` reference impl + schema

package/examples/connectors/README.md

@@ -0,0 +1,47 @@
+# examples/connectors/
+
+Worked examples + fork-me templates for adopter-written connectors. The bundled defaults live in `src/connectors/`; this directory holds patterns for adopters writing their own.
+
+## Connector landscape
+
+| Contract | Bundled defaults | Worked example | Fork template |
+|---|---|---|---|
+| `SkillStore` | `FilesystemSkillStore`, `SqliteSkillStore` (in `src/connectors/`) | — | **[SkillStoreTemplate/](./SkillStoreTemplate/)** |
+| `MemoryStore` | `SqliteMemoryStore` (in `src/connectors/`) | — | **[MemoryStoreTemplate/](./MemoryStoreTemplate/)** |
+| `LocalModel` | `OllamaLocalModel` (in `src/connectors/`; opt-in via substrate config) | — | **[LocalModelTemplate/](./LocalModelTemplate/)** |
+| `McpConnector` | `RemoteMcpConnector`, `CallbackMcpConnector`, `LocalModelMcpConnector`, `MemoryStoreMcpConnector` (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.
+
+**Worked examples** are real implementations for substrates that aren't bundled — copy + customize for your specific deployment. HttpWebhookAgentConnector demonstrates the AgentConnector contract against a generic HTTP-webhook substrate.
+
+**Fork templates** are skeletons (every method throws TODO). Useful when you want the bare contract surface without any specific substrate assumptions. SkillStoreTemplate is the starting point for Postgres-, MongoDB-, AMP-, or vector-DB-backed SkillStore impls.
+
+## Forking workflow (any connector type)
+
+1. **Pick your starting point**:
+   - Fork from a worked example if it's close to your substrate (e.g., another HTTP service → fork HttpWebhookAgentConnector)
+   - Fork from a template if you're targeting a substrate type not yet demonstrated (e.g., Postgres SkillStore → fork SkillStoreTemplate)
+   - Fork from `src/connectors/` if you want the bundled default's behavior as a starting point (e.g., another SQL flavor → adapt sqlite-skill-store.ts)
+2. **Copy the directory** into your codebase
+3. **Implement against your substrate** (each method has a TODO comment)
+4. **Update `staticCapabilities()`** to declare what your impl actually supports
+5. **Register via `Registry.register*`** from your bootstrap
+6. **Validate via the conformance suite** (`<Contract>Conformance.buildTests()` from `skillscript-runtime/testing`)
+
+## Reference materials
+
+- **[`docs/configuration.md`](../../docs/configuration.md)** — substrate selection via `connectors.json`; programmatic-bootstrap vs declarative patterns
+- **[`docs/adopter-playbook.md`](../../docs/adopter-playbook.md)** — Case 1 vs Case 2 wiring decisions; two-instance posture; upstream-merge-friendly conventions
+- **[`docs/connector-contract-reference.md`](../../docs/connector-contract-reference.md)** — interface contracts for adopter agents writing connector impls
+- **`src/connectors/types.ts`** — authoritative contract interfaces (SkillStore, MemoryStore, LocalModel, McpConnector)
+- **`src/testing/conformance.ts`** — the per-contract conformance test suites
+
+## Naming convention
+
+Bundled defaults in `src/connectors/`: `<Substrate><Contract>` (e.g., `FilesystemSkillStore`, `SqliteSkillStore`, `OllamaLocalModel`).
+
+Worked examples + adopter forks in `examples/connectors/`: same `<Substrate><Contract>` pattern (e.g., `HttpWebhookAgentConnector`, your `PostgresSkillStore`).
+
+Templates: `<Contract>Template` (e.g., `SkillStoreTemplate`).

package/examples/connectors/SkillStoreTemplate/README.md

@@ -0,0 +1,143 @@
+# SkillStoreTemplate — fork-me skeleton
+
+A skeleton `SkillStore` 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 skills backed by:
+- A database the bundled impls don't cover (Postgres, MySQL, MongoDB, etc.)
+- A vector store (Pinecone, Weaviate, Qdrant)
+- A memory system (AMP, hosted memory API)
+- An HTTP CRUD service
+- Anything else with a query/write interface
+
+## The three legs
+
+```
+SkillStore (choose which connector)
+   ├── FilesystemSkillStore (bundled, FS-backed — src/connectors/skill-store.ts)
+   ├── SqliteSkillStore     (bundled, DB-backed   — src/connectors/sqlite-skill-store.ts)
+   └── Your fork from this template
+```
+
+The runtime is substrate-agnostic. Skills don't know which backend they're stored against — the contract is the `SkillStore` interface, and any class implementing it works.
+
+## Forking workflow
+
+```bash
+cp -r examples/connectors/SkillStoreTemplate examples/connectors/MyDatabaseSkillStore
+```
+
+1. **Rename the class.** Convention: `<Substrate>SkillStore` (e.g., `PostgresSkillStore`, `PineconeSkillStore`, `AmpSkillStore`).
+2. **Define your config interface.** Edit `SkillStoreTemplateConfig` to declare what your substrate needs (connection URL, API key, vault name, etc.).
+3. **Implement each method.** Eight methods + `staticCapabilities()`. Each has a TODO comment in the skeleton explaining what to do.
+4. **Update `staticCapabilities()`** to declare what your impl actually supports. The runtime + lint consult these flags before exercising features.
+5. **Wire from your adopter bootstrap:**
+
+   ```typescript
+   import { Registry } from "skillscript-runtime";
+   import { MyDatabaseSkillStore } from "./MyDatabaseSkillStore.js";
+
+   const registry = new Registry();
+   registry.registerSkillStore("primary", new MyDatabaseSkillStore({
+     // your config
+   }));
+   ```
+
+6. **Validate via the conformance suite:**
+
+   ```typescript
+   import { describe, it } from "vitest";
+   import { SkillStoreConformance } from "skillscript-runtime/testing";
+   import { MyDatabaseSkillStore } from "./MyDatabaseSkillStore.js";
+
+   describe("MyDatabaseSkillStore conformance", () => {
+     const tests = SkillStoreConformance.buildTests({
+       build: () => new MyDatabaseSkillStore({ /* test config */ }),
+       ctor: MyDatabaseSkillStore,
+     });
+     for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
+   });
+   ```
+
+   The conformance suite verifies your impl honors the contract: method presence, return-type shape, error-class throw conditions, capability flag self-consistency. If it passes, the runtime treats your impl interchangeably with the bundled defaults.
+
+## Reference implementations
+
+When in doubt about semantics, read the bundled impls:
+
+- **`src/connectors/skill-store.ts`** — `FilesystemSkillStore`, filesystem-backed. Skills as `.skill.md` files; version history in a sidecar `.versions.jsonl`. Simplest reference.
+- **`src/connectors/sqlite-skill-store.ts`** — `SqliteSkillStore`, SQLite-backed. Two-table schema, transactional status transitions, WAL, JSON-extract tag filter. Closest reference for any database-backed fork.
+
+Both implement the same `SkillStore` interface; the differences are in the substrate-specific code.
+
+## Approval token semantics
+
+The runtime ships an approval-token mechanism so headless MCP-only adopters get a runnable `Approved` state without a dashboard round-trip. When you `store()` or `update_status()` a body declaring `# Status: Approved`, the impl should stamp `# Status: Approved v1:<hex>` automatically.
+
+Helpers from `src/approval.ts`:
+
+```typescript
+import { extractStatusFromBody, stampApprovalToken } from "skillscript-runtime";
+
+// In store():
+const extracted = extractStatusFromBody(source);
+const body = extracted?.status === "Approved" ? stampApprovalToken(source) : source;
+
+// In update_status() — when transitioning TO Approved:
+const updated = status === "Approved"
+  ? stampApprovalToken(rewriteStatusHeader(source, "Approved"))
+  : rewriteStatusHeader(source, status);
+```
+
+Both bundled impls follow this pattern; your fork should too unless you're explicitly disabling approval tokens.
+
+## Error classes to throw
+
+From `src/errors.ts`:
+
+- **`SkillNotFoundError(name, implementationName)`** — `load()` / `metadata()` / `versions()` / `update_status()` / `delete()` on a missing skill
+- **`VersionNotFoundError(name, version, implementationName)`** — `load(name, version)` where `name` exists but `version` doesn't
+- **`StorageConflictError(name, reason, implementationName)`** — `store()` rejects (e.g., name violates substrate constraints)
+
+The `implementationName` is your class name — let cold authors trace errors back to the substrate.
+
+## Schema-level decisions
+
+Document your substrate's particulars in a README alongside your fork:
+
+- **Versioning shape** — full body bytes per version (rich audit), or just hash + status (lightweight)?
+- **Delete semantics** — hard-cascade (removes versions) or preserve (audit-grade retention)?
+- **Concurrency model** — single-writer, multi-reader (e.g., WAL), or fully concurrent?
+- **Tag filter** — indexed lookup, table scan, or unsupported?
+
+These trade-offs are substrate-side; the contract just specifies what each method does, not how.
+
+## Wiring against the CLI / dashboard
+
+Runtime hosts (MCP server + web dashboard) honor whichever SkillStore impl your registry has. To make your fork visible through `skillfile dashboard`:
+
+- Write a custom bootstrap that constructs the runtime with your SkillStore (see `src/bootstrap.ts` for the reference shape + `docs/adopter-playbook.md` for the pattern)
+- OR (planned future) declare in `~/.skillscript/connectors.json`:
+
+  ```json
+  {
+    "substrate": {
+      "skill_store": {
+        "type": "custom",
+        "module": "./my-database-skill-store.js",
+        "export": "MyDatabaseSkillStore",
+        "config": { "postgresUrl": "${POSTGRES_URL}" }
+      }
+    }
+  }
+  ```
+
+  Current limitation: sync `bootstrap()` can't dynamic-import, so the `custom` form surfaces an error today. Programmatic bootstrap is the path until async-bootstrap support lands.
+
+The bundled CLI authoring commands (`skillfile compile`, `skillfile lint`, `skillfile audit`, `skillfile list`) stay filesystem-pinned by design — they're the FS-authoring loop. Adopter-substrate skills are authored via the dashboard UI or the `skill_write` MCP tool.
+
+## Further reading
+
+- **[`docs/configuration.md`](../../../docs/configuration.md)** — substrate selection via `connectors.json`
+- **[`docs/sqlite-skill-store.md`](../../../docs/sqlite-skill-store.md)** — the bundled SqliteSkillStore's schema + semantics + forking checklist
+- **`src/connectors/types.ts`** — authoritative `SkillStore` interface spec (lines 192-208)
+- **`src/testing/conformance.ts`** — the conformance test suite

package/examples/connectors/SkillStoreTemplate/SkillStoreTemplate.ts

@@ -0,0 +1,199 @@
+/**
+ * SkillStoreTemplate — fork-me skeleton for writing your own SkillStore impl.
+ *
+ * This is NOT a runnable connector. Every method throws a "TODO" error. The
+ * purpose is to surface the SkillStore contract surface in a copy-and-customize
+ * shape so adopters writing Postgres-, MySQL-, MongoDB-, AMP-, or
+ * vector-DB-backed SkillStores have a starting skeleton.
+ *
+ * Forking workflow:
+ *   1. Copy this directory into your codebase (`cp -r examples/connectors/SkillStoreTemplate examples/connectors/MyDatabaseSkillStore`)
+ *   2. Rename the class — typically `<Substrate>SkillStore` (e.g., `PostgresSkillStore`)
+ *   3. Implement each method against your substrate's API
+ *   4. Update `staticCapabilities()` to declare what your impl actually supports
+ *   5. Register from your adopter bootstrap:
+ *        `registry.registerSkillStore("primary", new MyDatabaseSkillStore({ ... }))`
+ *   6. Validate via the conformance suite:
+ *        `SkillStoreConformance.buildTests({ build: () => new MyDatabaseSkillStore(...), ctor: MyDatabaseSkillStore })`
+ *
+ * See `src/connectors/sqlite-skill-store.ts` for a working reference
+ * implementation against SQLite + `node:sqlite`. See `src/connectors/skill-store.ts`
+ * for the bundled filesystem default. The full contract spec lives in
+ * `src/connectors/types.ts` (`SkillStore` interface, lines 192-208) and
+ * `docs/sqlite-skill-store.md` for schema + semantics depth.
+ *
+ * Runtime hosts (MCP server + web dashboard) honor whichever SkillStore impl
+ * 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.
+ */
+
+import type {
+  SkillStore,
+  SkillSource,
+  SkillMeta,
+  SkillStatus,
+  SkillFilter,
+  VersionInfo,
+  SkillStoreCapabilities,
+  ManifestInfo,
+} from "../../../src/connectors/types.js";
+
+/** Replace with your substrate's connection config (host, dbName, credentials, etc.). */
+export interface SkillStoreTemplateConfig {
+  // TODO — declare the fields your substrate needs to connect.
+  // Examples:
+  //   postgresUrl?: string;
+  //   pineconeApiKey?: string;
+  //   ampVault?: string;
+  exampleConfigField?: string;
+}
+
+export class SkillStoreTemplate implements SkillStore {
+  /**
+   * Declare what your impl supports. The runtime + lint consult these flags
+   * before exercising features. Set conservatively — overclaiming triggers
+   * cryptic downstream failures; underclaiming hides usable features.
+   */
+  static staticCapabilities(): SkillStoreCapabilities {
+    return {
+      connector_type: "skill_store",
+      implementation: "SkillStoreTemplate", // ← rename to your class name
+      contract_version: "1.0.0",
+      features: {
+        // TODO — set each flag based on what your substrate can actually do.
+        supports_writes: false,               // can you persist new skills?
+        supports_versioning: false,           // can you return historical bytes via load(name, version)?
+        supports_tag_filter: false,           // can query() filter by tag?
+        supports_audit_trail: false,          // does update_status populate previous_status?
+        supports_atomic_status_transitions: false, // can UPDATE + INSERT versions be transactional?
+      },
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  constructor(_config: SkillStoreTemplateConfig) {
+    // TODO — establish your substrate connection. For SQL: open the database
+    // + run schema migrations. For HTTP: store the base URL + auth headers.
+    // For AMP/Pinecone: cache the SDK client.
+    throw new Error("SkillStoreTemplate is a fork-me skeleton; replace with your impl.");
+  }
+
+  /**
+   * Capability snapshot for `runtime_capabilities` discovery. Return free-form
+   * substrate-specific metadata (kind, version, supported modes, etc.).
+   */
+  async manifest(): Promise<ManifestInfo<"skill_store">> {
+    // TODO — return a snapshot of your substrate's capabilities.
+    throw new Error("TODO: manifest() — return substrate-specific capability snapshot.");
+  }
+
+  /**
+   * Read the skill body bytes + metadata. If `version` is supplied, return
+   * historical bytes (or throw `VersionNotFoundError` if the version is
+   * unknown). If the skill doesn't exist at all, throw `SkillNotFoundError`.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async load(_name: string, _version?: string): Promise<SkillSource> {
+    // TODO — fetch the skill record from your substrate.
+    //   - Return SkillSource { name, version, content_hash, source, metadata }
+    //   - Throw SkillNotFoundError if name doesn't exist
+    //   - Throw VersionNotFoundError if version is supplied but unknown
+    throw new Error("TODO: load() — fetch skill source by name (+ optional version).");
+  }
+
+  /**
+   * List skill metadata. Apply the filter where your substrate supports it;
+   * fall back to client-side filtering for unsupported fields. Empty result
+   * is fine; never throw "not found" — return [].
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async query(_filter?: SkillFilter): Promise<SkillMeta[]> {
+    // TODO — query your substrate for skill metadata.
+    //   - Apply filter.status / filter.tag / filter.author / etc. as supported
+    //   - Honor filter.limit + filter.offset
+    //   - Never throw on no matches; return []
+    throw new Error("TODO: query() — return SkillMeta[] honoring the filter.");
+  }
+
+  /**
+   * Read skill metadata without the body bytes. Equivalent to `load()` but
+   * skips the `source` field — useful for listings + introspection where
+   * the body isn't needed.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async metadata(_name: string): Promise<SkillMeta> {
+    // TODO — return SkillMeta for `name`. Throw SkillNotFoundError if missing.
+    throw new Error("TODO: metadata() — return SkillMeta without body bytes.");
+  }
+
+  /**
+   * Return version history (chronological). Each entry has `version` +
+   * `content_hash` + `status` + `changed_at` + optional `previous_status`
+   * (audit trail). Throws `SkillNotFoundError` if the skill doesn't exist.
+   *
+   * If your substrate doesn't track versions, return a single-element array
+   * with the current state (and set `supports_versioning: false`).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async versions(_name: string): Promise<VersionInfo[]> {
+    // TODO — return version chain. SQL substrates: SELECT FROM skill_versions
+    // ORDER BY changed_at. MemoryStore-style: query memories with the right tag.
+    throw new Error("TODO: versions() — return VersionInfo[] chronologically.");
+  }
+
+  /**
+   * Persist a skill (create or update). Compute content_hash from the source;
+   * append a new version row; update the current-version pointer. Returns
+   * `VersionInfo` for the new version.
+   *
+   * For atomicity, wrap your substrate writes in a transaction (or equivalent)
+   * so the version row is never created without the current-version pointer
+   * updating, and vice versa.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async store(_name: string, _source: string, _metadata?: Partial<SkillMeta>): Promise<VersionInfo> {
+    // TODO — persist the skill source bytes + metadata.
+    //   - Compute content_hash (SHA-256 of source) + version (short hash)
+    //   - Auto-stamp approval token if body declares Approved (see
+    //     src/approval.ts → stampApprovalToken / extractStatusFromBody)
+    //   - Write to your substrate atomically
+    //   - Return VersionInfo
+    throw new Error("TODO: store() — persist skill source + metadata.");
+  }
+
+  /**
+   * Hard-delete the skill (substrate-only — referential integrity is the
+   * runtime's concern). Whether to cascade version history is your substrate
+   * choice; the bundled SqliteSkillStore cascades (rationale in
+   * `docs/sqlite-skill-store.md`).
+   *
+   * Throws `SkillNotFoundError` if `name` doesn't exist (so adopters get a
+   * clear error rather than a silent no-op).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async delete(_name: string): Promise<void> {
+    // TODO — remove the skill from your substrate. Decide cascade vs preserve
+    // history per your compliance needs. Throw SkillNotFoundError if missing.
+    throw new Error("TODO: delete() — remove skill (+ optionally history).");
+  }
+
+  /**
+   * Transition a skill's status (Draft / Approved / Disabled). Updates the
+   * current state + appends a `skill_versions` row with `previous_status`
+   * populated (audit trail). Wrap in a transaction for atomicity.
+   *
+   * Approved transitions should stamp the approval token (see
+   * `src/approval.ts`); transitions away from Approved should strip it.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async update_status(_name: string, _status: SkillStatus): Promise<VersionInfo> {
+    // TODO — atomically update status + append audit row.
+    //   - Load current status (for previous_status field)
+    //   - Apply stampApprovalToken if status=Approved
+    //   - Strip token if transitioning to Draft/Disabled
+    //   - UPDATE skills SET status, INSERT skill_versions (transaction)
+    //   - Return VersionInfo with previous_status populated
+    throw new Error("TODO: update_status() — atomic status transition + audit row.");
+  }
+}

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

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-05-28T19:20:14.463Z",
+  "compiled_at": "2026-05-29T18:50:40.018Z",
   "source_skill": {
     "name": "hello"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.10.0",
+  "version": "0.13.2",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",

package/scaffold/config.toml

@@ -16,18 +16,14 @@ plugins_dir = "~/.skillscript/plugins"
 # security-conscious deployments invert this to ["packages"] only.
 resolution_order = ["filesystem", "packages"]
 
-[local_model.default]
-# Bundled-default LocalModel: Ollama gemma2:9b at localhost.
-kind = "ollama"
-base_url = "http://localhost:11434"
-model_tag = "gemma2:9b"
-timeout_ms = 60000
-
-[local_model.qwen]
-kind = "ollama"
-base_url = "http://localhost:11434"
-model_tag = "qwen2.5:7b"
-timeout_ms = 60000
+# LocalModel wiring lives in `connectors.json` under `substrate.local_model`,
+# NOT here. v0.10+ moved substrate selection out of this file. Example:
+#   {
+#     "substrate": {
+#       "local_model": { "type": "ollama", "config": { "defaultModelTag": "gemma2:9b" } }
+#     }
+#   }
+# See docs/configuration.md.
 
 [runtime]
 # `@@` opt-in unsafe shell. Disabled by default. v1 spec gates this behind

package/scaffold/connectors.json

@@ -1,9 +1,9 @@
 {
   "_comment": "Per-host connector wiring. Copied to ~/.skillscript/connectors.json by `skillfile init`. The top-level `substrate` key selects singleton substrate connectors (SkillStore, MemoryStore, LocalModel). All other top-level keys define named MCP connector instances referenced via `$ name args` in skill source.",
 
-  "_comment_substrate": "v0.10 substrate selection — runtime hosts (MCP server + web dashboard) honor whatever you configure here. The bundled CLI authoring commands (`skillfile compile`, `skillfile lint`, `skillfile audit`, `skillfile list`) stay filesystem-pinned regardless — they're the FS-authoring loop. Three legs: bundled filesystem, bundled sqlite, adopter-custom (write your own SkillStore impl).",
+  "_comment_substrate": "Substrate selection — runtime hosts (MCP server + web dashboard) honor whatever you configure here. The bundled CLI authoring commands (`skillfile compile`, `skillfile lint`, `skillfile audit`, `skillfile list`) stay filesystem-pinned regardless — they're the FS-authoring loop. Three legs: bundled filesystem, bundled sqlite, adopter-custom (write your own SkillStore impl).",
 
-  "_comment_substrate_forms": "Each substrate slot accepts: (a) bare string for built-in types — \"filesystem\", \"sqlite\", \"ollama\"; (b) null to explicitly disable; (c) object form `{type, config}` to override defaults; (d) object form `{type:\"custom\", module, export, config}` for adopter-custom impls (requires programmatic bootstrap today — sync `bootstrap()` doesn't dynamic-import yet).",
+  "_comment_substrate_forms": "Each substrate slot accepts: (a) bare string for built-in types — \"filesystem\", \"sqlite\", \"ollama\"; (b) null to explicitly disable; (c) object form `{type, config}` to override defaults; (d) object form `{type:\"custom\", module, export, config}` for adopter-custom impls (requires programmatic bootstrap; sync `bootstrap()` doesn't dynamic-import).",
 
   "substrate": {
     "skill_store": "filesystem",
@@ -22,7 +22,7 @@
       "config": { "baseUrl": "http://gpu-host:11434", "defaultModelTag": "gemma2:9b" }
     },
 
-    "_example_custom": "Adopter-custom impl. Write `class FooSkillStore implements SkillStore { ... }` then reference it here. NOTE v0.10 — this form requires a programmatic bootstrap (sync `bootstrap()` can't dynamic-import). Wire via your own bootstrap script today; declarative custom config arrives in a follow-up.",
+    "_example_custom": "Adopter-custom impl. Write `class FooSkillStore implements SkillStore { ... }` then reference it here. NOTE — this form requires a programmatic bootstrap (sync `bootstrap()` can't dynamic-import). Wire via your own bootstrap script today; declarative custom config is a planned follow-up.",
     "_example_custom_object": {
       "type": "custom",
       "module": "./my-amp-skill-store.js",
@@ -31,7 +31,7 @@
     }
   },
 
-  "_comment_classes": "v0.4.0+ closed-set class registry. Available: `RemoteMcpConnector` (stdio-bridged remote MCP). Use `runtime_capabilities({include:['mcpConnectorClasses']})` to introspect the runtime's available class set. v0.7.2 added `LocalModelMcpConnector` + `MemoryStoreMcpConnector` bridges so `$ llm` / `$ memory` work canonically — these auto-wire when their substrates exist.",
+  "_comment_classes": "Closed-set class registry for MCP connectors. Available: `RemoteMcpConnector` (stdio-bridged remote MCP). Use `runtime_capabilities({include:['mcpConnectorClasses']})` to introspect the available class set. The `LocalModelMcpConnector` + `MemoryStoreMcpConnector` bridges (for `$ llm` / `$ memory` canonical dispatch) auto-wire when their substrates are configured above.",
 
   "_comment_security": "This file is secret-bearing when filled with real credentials. The repo's `.gitignore` excludes `connectors.json` (the live copy) but tracks `connectors.json.example`. Prefer `${VAR}` substitution over in-file literals for deployments.",