skillscript-runtime 0.13.8 → 0.14.1

package/docs/language-reference.md

@@ -4,9 +4,6 @@ Canonical language reference for skillscript. Audience: skill authors (human + a
 
 Implementation state is cross-referenced to commit hashes; pending items mark v2/v3 work.
 
-Companion docs under the Skillscript project anchor:
-- `skillscript-prd` — product positioning, value prop, roadmap
-- `skillscript-erd` — engineering requirements, system architecture, runtime mechanics
 
 ## Not yet implemented, but planned
 
@@ -103,7 +100,7 @@ Skillscript is a constrained domain-specific language for authoring agent workfl
 Every skill follows the same shape:
 
 1. **Trigger** — what fires the skill: cron, command, session-start, agent-event, file-watch, webhook, etc.
-2. **Process** — pull data (MCP / memory / file), classify or compose via sub-LLM + iteration, build the deliverable.
+2. **Process** — pull data (MCP / data store / file), classify or compose via sub-LLM + iteration, build the deliverable.
 3. **Deliver** — emit the result via one or more delivery channels (see below).
 
 Skillscript's job is to express this pipeline declaratively. When there is an agent above the skill, the agent's job is to act on the delivered artifact. When there isn't (autonomous fires), the delivery channel IS the outcome.
@@ -128,9 +125,9 @@ A skill delivers its work via one or more of three channels. Delivery channel is
 |---|---|---|
 | **Augmenting (context to agent)** | `emit(text="...")` + `# Output: agent: <name>` | Skill output is augment-kind payload for the receiving agent's next turn; joined emit stream becomes the delivered context. Pattern: agent-augmenting skills (briefing skills, session-start prepared context). |
 | **Template (playbook to agent)** | `emit(text="...")` + `# Output: template: <name>` | Skill output is a template-kind payload (recipe/playbook) the receiving agent executes. Pattern: instructional skills, reusable recipes. |
-| **Memory handoff** | `$ memory_write content="..." recipients=[<agent>] -> R` | Skill writes a memory the target agent picks up via mailbox at next session. Pattern: async carrier skills, autonomous fires that hand off to a future session. |
+| **Data handoff** | `$ data_write content="..." recipients=[<agent>] -> R` | Skill writes data the target agent picks up via mailbox at next session. Pattern: async carrier skills, autonomous fires that hand off to a future session. |
 
-A single skill can use any combination. An autonomous cron-fired sweep might write a memory to one agent AND emit augment-kind context to another. The combinations are unconstrained — the per-op gating model governs which mutating ops are authorized, not which channels a skill uses.
+A single skill can use any combination. An autonomous cron-fired sweep might write data to one agent AND emit augment-kind context to another. The combinations are unconstrained — the per-op gating model governs which mutating ops are authorized, not which channels a skill uses.
 
 ## Three op classes
 
@@ -148,19 +145,19 @@ Full op catalog and per-op semantics in Ops Reference.
 
 ## Substrate portability
 
-The language doesn't privilege any backend. `$ llm`, `$ memory`, `$ ticketing_search` are not language built-ins — they're connector names resolved at runtime through the registered MCP connector instances. The same skill source runs against any conforming substrate.
+The language doesn't privilege any backend. `$ llm`, `$ data_read`, `$ ticketing_search` are not language built-ins — they're connector names resolved at runtime through the registered MCP connector instances. The same skill source runs against any conforming substrate.
 
 The runtime ships bundled bridges for two common patterns:
 
 - `$ llm` routes through whichever LocalModel is wired (via `substrate.local_model` in `connectors.json`)
-- `$ memory` / `$ memory_write` route through whichever MemoryStore is wired (via `substrate.memory_store`)
+- `$ data_read` / `$ data_write` route through whichever DataStore is wired (via `substrate.data_store`)
 
 Adopters wire OpenAI instead of Ollama, Pinecone instead of SQLite, etc. Configuration lives outside the skill body; the language remains agnostic.
 
 | Connector slot | Adopter A wires | Adopter B wires |
 |---|---|---|
 | `llm` | LocalModel: Ollama (default) | LocalModel: OpenAI |
-| `memory` / `memory_write` | MemoryStore: SqliteMemoryStore (default) | MemoryStore: Pinecone |
+| `data_read` / `data_write` | DataStore: SqliteDataStore (default) | DataStore: Pinecone |
 | `ticketing_search` | YouTrack MCP | Jira MCP |
 
 Substrate config syntax + the three-form configuration shape lives in the adopter playbook, not in this reference. Skill authors don't typically need to touch it — they author against the canonical `$ tool` surfaces and adopters wire whatever's underneath.
@@ -201,7 +198,7 @@ The joined `emit()` stream becomes the augment-kind payload delivered to the on-
 2. **Targets** — named blocks of typed ops, optionally with `needs:` dependencies
 3. **`default:`** — names the goal target the runtime walks toward
 
-Other delivery channels for the same shape: swap `# Output: agent: oncall` + the `emit()` calls for `$ memory_write content="..." recipients=["oncall"] approved="cron-fired" -> R` (one summary memory handoff per fire) or `file_write(path="/var/log/showstoppers-${EVENT.fired_at_unix}.md", content="...", approved="cron-fired")` (one file deliverable per fire).
+Other delivery channels for the same shape: swap `# Output: agent: oncall` + the `emit()` calls for `$ data_write content="..." recipients=["oncall"] approved="cron-fired" -> R` (one summary data handoff per fire) or `file_write(path="/var/log/showstoppers-${EVENT.fired_at_unix}.md", content="...", approved="cron-fired")` (one file deliverable per fire).
 
 ## Lexical conventions
 
@@ -476,14 +473,14 @@ Both forms are first-class. Neither is canonical; choose by what makes the call
 ```
 $ ticketing_search query="project:INFRA" -> R
 $ llm prompt="${INPUT}" -> V
-$ memory mode=fts query="..." limit=5 -> M
+$ data_read mode=fts query="..." limit=5 -> M
 ```
 
 **Dotted-prefix dispatch** is the explicit-routing escape hatch — useful when multiple connectors expose tools with overlapping names, or when an adopter wants the connector identity visible at the call site for audit clarity:
 
 ```
 $ ticketing.search query="project:INFRA" -> R
-$ memory.query_memories query="..." -> M
+$ data_read.query query="..." -> M
 ```
 
 Parser rule: the text before the dot is the connector name (must match an entry in `connectors.json`); the rest is the tool + args.
@@ -493,13 +490,13 @@ Parser rule: the text before the dot is the connector name (must match an entry
 ```
 $ ticketing_search query="project:INFRA state:Open" limit=20 -> ISSUES
 $ llm prompt="Classify: ${INPUT}" -> VERDICT
-$ memory mode=fts query="${TOPIC}" limit=5 -> RESULTS
-$ memory_write content="${SUMMARY}" recipients=["oncall"] approved="morning roundup, 2026-05-25" -> ACK
+$ data_read mode=fts query="${TOPIC}" limit=5 -> RESULTS
+$ data_write content="${SUMMARY}" recipients=["oncall"] approved="morning roundup, 2026-05-25" -> ACK
 ```
 
 Tool args are unconstrained `key=value` pairs — the connector forwards them to the underlying MCP tool. If a dispatched call returns `isError: true`, the executor throws via `makeOpError`, which routes through `else:` / `# OnError:` machinery. The inner tool's error text is preserved in `result.errors[]`.
 
-**Substrate-neutrality.** Connector names like `$ llm`, `$ memory`, `$ ticketing_search` are NOT reserved or built-in — they're whatever the adopter declares in `connectors.json` (substrate config). Bridges for `$ llm` and `$ memory` / `$ memory_write` auto-wire only when the adopter's substrate config sets `substrate.local_model` / `substrate.memory_store` respectively. See the adopter playbook for the full substrate config reference.
+**Substrate-neutrality.** Connector names like `$ llm`, `$ data_read`, `$ ticketing_search` are NOT reserved or built-in — they're whatever the adopter declares in `connectors.json` (substrate config). Bridges for `$ llm` and `$ data_read` / `$ data_write` auto-wire only when the adopter's substrate config sets `substrate.local_model` / `substrate.data_store` respectively. See the adopter playbook for the full substrate config reference.
 
 **Unknown connector** → tier-1 `unknown-connector` lint with the list of wired connector names.
 
@@ -513,7 +510,7 @@ Mutation ops require an authorization signal. The signal is per-op, not a mode b
 
 **Mutation-classified ops:**
 - `file_write(...)` (runtime-intrinsic)
-- `$ memory_write ...` and any MCP connector entry declared `"mutating": true` in `connectors.json`
+- `$ data_write ...` and any MCP connector entry declared `"mutating": true` in `connectors.json`
 - `shell(command=..., unsafe=true)` (always mutation-classified)
 - `shell(command=...)` with destructive verb (rm, mv, dd, mkfs, etc. — heuristic list)
 - `$ <tool>` matching the mutating-verb regex
@@ -537,7 +534,7 @@ Mutation ops require an authorization signal. The signal is per-op, not a mode b
 
 deliver:
     file_write(path="/tmp/sweep.md", content="${REPORT}")        # no approved= needed
-    $ memory_write content="${REPORT}" recipients=["oncall"]     # no approved= needed
+    $ data_write content="${REPORT}" recipients=["oncall"]       # no approved= needed
 ```
 
 ```
@@ -577,35 +574,15 @@ flush:
 | Runtime-intrinsic | `file_write` | `file_write(path="...", content="...", [approved="..."])` | none |
 | External MCP | `$ <connector>` | `$ <name>[.<tool>] kwarg=value, ... [-> R]` | optional |
 
----
-
-## Legacy syntax (deprecated, grace period)
-
-These symbol-forms shipped in earlier versions and still compile during the grace period with tier-2 `deprecated-symbol-op` warnings. New skills should use the canonical forms.
-
-| Deprecated | Canonical replacement |
-|---|---|
-| `~ prompt="..."` | `$ llm prompt="..."` |
-| `> mode=... query=...` | `$ memory mode=... query=...` |
-| `@ <command>` | `shell(command="...")` |
-| `@ unsafe <command>` | `shell(command="...", unsafe=true)` |
-| `! <text>` | `emit(text="<text>")` |
-| `?? "<prompt>" -> R` | `ask(prompt="<prompt>") -> R` |
-| `& <data-skill-name>` | `inline(skill="<data-skill-name>")` |
-| `$(VAR)` (legacy substitution) | `${VAR}` |
-| `(approved: "reason")` trailer | `approved="reason"` kwarg |
-
-The symbol-per-op design was deprecated when verb-word ops in function-call shape proved more author-friendly (training-corpus alignment + human-reviewability). Removal lands in a future version; until then, the canonical surface is the recommended form.
-
 ## Variable resolution — ${VAR} canonical, substitution + ambient refs + # Requires: cascade
 
-Skillscript supports four tiers of variables, each with distinct resolution timing and scope. Substitution uses **`${VAR}` as the canonical form**. The legacy `$(VAR)` form (parentheses) continues to compile during the grace period; see Ops Reference legacy syntax section for the deprecation map.
+Skillscript supports four tiers of variables, each with distinct resolution timing and scope. Substitution uses **`${VAR}` as the canonical form**.
 
 ## Substitution syntax — `${VAR}` canonical
 
 ```
 emit(text="Hello, ${USER.login}!")
-$ memory mode=fts query="${TOPIC}" limit=5 -> R
+$ data_read mode=fts query="${TOPIC}" limit=5 -> R
 $set REPORT = "Triage for ${PROJECT} (${ISSUES|length} open):\n"
 ```
 
@@ -638,7 +615,7 @@ For cron and session triggers, the scheduler injects time-offset ambient fields
 
 These let skill bodies compute `expires_at` and similar bounded-lifetime values without arithmetic in op kwargs. For ISO-formatted rendering of any epoch value, see the `|isodate` filter.
 
-Additional ambient refs may be injected based on connector configuration (e.g., a vault-backed memory connector may expose `${VAULT_ROOT}`). Connectors section documents which ambient refs each connector contributes.
+Additional ambient refs may be injected based on connector configuration. Connector documentation specifies which ambient refs each connector contributes.
 
 ## Tier 2: Input
 
@@ -662,18 +639,16 @@ Bracketed list literals supported (`# Vars: TAGS=[a, b, c]`).
 
 ## Tier 4: Local
 
-Bound to a previous target's output mid-execution. Two forms:
+Bound to a previous target's output mid-execution. Three forms:
 - `${target.output}` — the bound output of a target
 - `${VAR}` — an explicit `-> VAR` binding from any op
-- `${target.output.field}` or `${MEMORY.field}` — dotted field access into structured output
+- `${VAR.field}` / `${VAR.nested.field}` — dotted field access into structured output
 
-**Field access resolution tiers** for `${MEMORY.field}`:
-1. Core `PortableMemory` fields (id, summary, detail, score)
-2. Curated substrate subset (thread_status, pinned, confidence, domain_tags, payload_type, knowledge_type, recipients, expires_at, created_at, agent_id, vault)
-3. `metadata.X` for everything else
-4. Ambient passthrough as literal `${MEMORY.field}` if unresolved
+The exact field set available on a bound variable depends on what the wired connector returns. Field access resolves against the returned object's structure. If a field doesn't resolve, the substitution errors unless `|fallback:"default"` is supplied (see Pipe filters for full `|fallback:` semantics):
 
-**Missing-field opt-out:** `${MEMORY.field|fallback:"-"}` coalesces to the literal when the field doesn't resolve. See Pipe filters for the full `|fallback:` semantics.
+```
+emit(text="Assignee: ${ISSUE.customFields.Assignee|fallback:\"unassigned\"}")
+```
 
 ## Resolution order
 
@@ -751,7 +726,7 @@ Strings that hold JSON arrays get the same tolerance as `in`/`not in` RHS: if th
 Pairs naturally with the numeric comparison operators (see Conditionals section):
 
 ```
-$ memory mode=fts query="urgent" -> ITEMS
+$ data_read mode=fts query="urgent" -> ITEMS
 if ${ITEMS|length} > 5:
     emit(text="Mailbox is getting crowded")
 ```
@@ -901,7 +876,7 @@ The ref-vs-ref form is the canonical change-detection pattern. Both sides resolv
 if ${M.id|trim} in ${SEEN}:
     emit(text="already processed")
 elif ${M.id} not in ${SEEN}:
-    $ memory_write content="..." approved="dedup" -> R
+    $ data_write content="..." approved="dedup" -> R
 ```
 
 Both sides are explicit refs. RHS must resolve to an array at runtime; clean error otherwise. LHS-undefined evaluates to `false` for both polarities. Optional filter on LHS.
@@ -909,9 +884,9 @@ Both sides are explicit refs. RHS must resolve to an array at runtime; clean err
 **JSON-string tolerance on RHS**: if the RHS resolves to a *string* that successfully JSON-parses to an array, the parsed array is used. This accommodates the canonical pattern where the array comes from a `$ llm` call that prompted for JSON output:
 
 ```
-$ llm prompt="List the URGENT memory IDs as a JSON array of strings. Items: ${M|json}" -> SEEN
+$ llm prompt="List the URGENT item IDs as a JSON array of strings. Items: ${M|json}" -> SEEN
 
-foreach M in ${MEMORIES}:
+foreach M in ${ITEMS}:
     if ${M.id} in ${SEEN}:
         emit(text="flagged urgent")
 ```
@@ -932,7 +907,7 @@ elif ${COUNT} <= 0:
 Filters and dotted-field access work on either side, same as equality. The `|length` filter (see Pipe filters section) is the canonical companion — `${LIST|length} > 5` is the natural "more than five items" pattern:
 
 ```
-$ memory mode=fts query="urgent" -> ITEMS
+$ data_read mode=fts query="urgent" -> ITEMS
 if ${ITEMS|length} > 5:
     emit(text="Mailbox is getting crowded")
 ```
@@ -972,7 +947,7 @@ classify:
 
 ```
 mailbox_check:
-    $ memory mode=fts query="addressed:perry" limit=10 -> MAILBOX
+    $ data_read mode=fts query="addressed:perry" limit=10 -> MAILBOX
     if not ${MAILBOX}:
         emit(text="empty mailbox today")
     elif ${MAILBOX|length} > 5:
@@ -1019,12 +994,12 @@ Both can coexist in the same target.
 foreach M in ${RESULTS}:
     emit(text="Processing ${M.id} — ${M.summary}")
     if ${M.id|trim} not in ${SEEN}:
-        $ memory_write content="${M.summary}" approved="dedup" -> ACK
+        $ data_write content="${M.summary}" approved="dedup" -> ACK
 ```
 
 ### Iterator vars
 
-`${M}` and `${M.field}` pass through ambient at compile; runtime substitutes per iteration. Dotted field access against `PortableMemory` shape applies (core fields → curated subset → metadata). Indexed access (`${LIST.0}`, `${LIST.0.id}`) also works on bound results.
+`${M}` and `${M.field}` pass through ambient at compile; runtime substitutes per iteration. Dotted field access resolves against whatever structure the connector returned per item — the exact field set depends on the connector. Indexed access (`${LIST.0}`, `${LIST.0.id}`) also works on bound results.
 
 ### Loop-local scope (and the accumulator exception)
 
@@ -1369,7 +1344,7 @@ Runs if any op in the target's primary body errors. Local to the failing target.
 
 ```
 fetch:
-    $ memory mode=fts query=${TOPIC} limit=5 -> RESULT
+    $ data_read mode=fts query=${TOPIC} limit=5 -> RESULT
 else:
     emit(text="retrieval failed, falling back to empty result")
     $set RESULT = ""
@@ -1412,7 +1387,7 @@ Inline fallback declared on the op line. Used when the call fails or returns emp
 
 ```
 weather:
-    $ memory mode=fts query="weather ${LOCATION}" limit=1 -> CURRENT (fallback: "weather unavailable")
+    $ data_read mode=fts query="weather ${LOCATION}" limit=1 -> CURRENT (fallback: "weather unavailable")
     $ llm prompt="Summarize: ${CURRENT}" -> SUMMARY (fallback: "summary unavailable")
     $ slack.post channel=${CHANNEL} text=${SUMMARY} (fallback: "post failed silently") -> ACK
 ```
@@ -1422,7 +1397,7 @@ Same pattern as the `# Requires:` cascade's `(fallback: ...)` syntax — consist
 **Fallback value parsing.** Permissive: bare identifiers, quoted strings, and bracketed array literals all accepted. Matches the `# Requires:` cascade convention.
 
 ```
-$ memory mode=fts query="..." -> RESULTS (fallback: [])              # array literal
+$ data_read mode=fts query="..." -> RESULTS (fallback: [])           # array literal
 $ llm prompt="..." -> VERDICT (fallback: unknown)                    # bare identifier
 $ slack.post text="..." -> ACK (fallback: "post failed")             # quoted string
 ```
@@ -1728,7 +1703,7 @@ Normal `prompt` / `prose` compilation ignores the `# Tests:` section entirely
 
 ### Runtime assertion sandboxing
 
-`# Tests:` cases that exercise runtime behavior (memory writes, shell ops, LocalModel calls) need a sandbox so they don't pollute production data. Two approaches:
+`# Tests:` cases that exercise runtime behavior (data writes, shell ops, LocalModel calls) need a sandbox so they don't pollute production data. Two approaches:
 - Scratch DB / scratch connector overrides for tests
 - Skip-and-warn for non-deterministic ops, only assert deterministic compile-time properties
 
@@ -1832,7 +1807,7 @@ $set NAME = value scope=session
 
 Backed by a configured data-records connector (the same surface `# Requires:` reads from) with conventionally-namespaced keys (e.g., `state:skill-local:<skill-name>:<key>`).
 
-**Rationale:** Most interesting skills need memory across firings — change-detection, windowing, dedup-against-recent. Without lifecycle, every skill rebuilds state tracking via raw memory-write / memory-query calls.
+**Rationale:** Most interesting skills need persistent state across firings — change-detection, windowing, dedup-against-recent. Without lifecycle, every skill rebuilds state tracking via raw `$ data_write` / `$ data_read` calls.
 
 ## Cross-skill pub-sub
 
@@ -1905,7 +1880,7 @@ ${SELF.confidence-trend}
 Skill declares its required surfaces:
 
 ```
-# Requires-Capabilities: sensors=[mic, camera], tools=[memorystore.write, slack.post]
+# Requires-Capabilities: sensors=[mic, camera], tools=[datastore.write, slack.post]
 # Requires-Privacy: private-channel-only
 ```
 
@@ -1968,5 +1943,5 @@ Hung dispatches hang the skill without explicit timeout configuration. Lean: ski
 
 ---
 
-*Rendered from `skillscript/skillscript-language-reference` — 2026-05-29 10:20 EDT*  
+*Rendered from `skillscript/skillscript-language-reference` — 2026-05-30 09:52 EDT*  
 *Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*

package/docs/sqlite-skill-store.md

@@ -42,7 +42,7 @@ const store = registry.getSkillStore("primary");
 await store.store("morning-status", `# Skill: morning-status
 # Status: Approved
 t:
-    ! report status
+    emit(text="report status")
 default: t
 `);
 ```
@@ -159,7 +159,7 @@ registerApprovalFn("v2", (body) => hmacSha256(SECRET, body));
 When forking into your codebase:
 
 1. Rename the class (e.g., `PostgresSkillStore`, `AmpSkillStore`)
-2. Replace the SQL with your substrate's API (HTTP, MemoryStore, vector DB, etc.)
+2. Replace the SQL with your substrate's API (HTTP, DataStore, vector DB, etc.)
 3. Update `staticCapabilities()` to match what your substrate actually supports — drop `supports_versioning` if you can't track history, drop `supports_tag_filter` if querying tags isn't tractable
 4. Update `manifest()` to describe your substrate (`kind: "amp"` or whatever)
 5. Tests: copy `tests/SqliteSkillStore.test.ts` as a starting point + run the conformance suite (`SkillStoreConformance.buildTests()` from `skillscript-runtime/testing`)

package/examples/README.md

@@ -9,9 +9,9 @@ For full language semantics, see [`../docs/language-reference.md`](../docs/langu
 | [`hello.skill.md`](./skillscripts/hello.skill.md) | Three-command first run; `! emit`; default target; `# Vars:` declared inputs |
 | [`morning-brief.skill.md`](./skillscripts/morning-brief.skill.md) | Multi-target with `needs:`; cron-fired with `EVENT.fired_at_*`; `# OnError:` fallback; dual `# Output:` (slack + prompt-context); `# Requires:` user-var cascade with fallback; LocalModel + retrieval composition |
 | [`doc-qa-with-citations.skill.md`](./skillscripts/doc-qa-with-citations.skill.md) | Single-target retrieval; `(fallback: [])` op-level fallback; LLM-with-citation pattern; pipe filter `\|json` for prompt embedding |
-| [`classify-support-ticket.skill.md`](./skillscripts/classify-support-ticket.skill.md) | `if`/`elif`/`else` multi-branch routing; classifier-cascade pattern; MemoryStore `$` writes with structured `domain_tags`; `$set` literal binding |
+| [`classify-support-ticket.skill.md`](./skillscripts/classify-support-ticket.skill.md) | `if`/`elif`/`else` multi-branch routing; classifier-cascade pattern; DataStore `$` writes with structured `domain_tags`; `$set` literal binding |
 | [`cut-release-tag.skill.md`](./skillscripts/cut-release-tag.skill.md) | `??` interactive ask-for-input; `else:` short-circuit on multiple targets; `@` shell ops with per-op error fallback; rollback-on-failure flow |
-| [`service-health-watch.skill.md`](./skillscripts/service-health-watch.skill.md) | `foreach` iteration; cron-fired with `expires_at=$(EVENT.fired_at_plus_1d_unix)` TTL math; classifier-gated MemoryStore writes; pipe filter `\|url` for path-safe interpolation |
+| [`service-health-watch.skill.md`](./skillscripts/service-health-watch.skill.md) | `foreach` iteration; cron-fired with `expires_at=$(EVENT.fired_at_plus_1d_unix)` TTL math; classifier-gated DataStore writes; pipe filter `\|url` for path-safe interpolation |
 | [`feedback-sentiment-scan.skill.md`](./skillscripts/feedback-sentiment-scan.skill.md) | `in` / `not in` set-membership ops; dedupe-via-seen-markers idiom; nested `if`/`elif` classification cascade; TTL on bookkeeping writes |
 
 ## Connector requirements
@@ -19,9 +19,9 @@ For full language semantics, see [`../docs/language-reference.md`](../docs/langu
 Most examples assume the bundled-default connectors:
 
 - `hello.skill.md` — zero deps (runs cold)
-- `doc-qa-with-citations.skill.md` — Ollama (LocalModel) + MemoryStore for the retrieval cache
-- `morning-brief.skill.md`, `feedback-sentiment-scan.skill.md` — Ollama + MemoryStore + a calendar MCP connector (the `$ calendar.list_events` op)
-- `classify-support-ticket.skill.md` — Ollama + MemoryStore
+- `doc-qa-with-citations.skill.md` — Ollama (LocalModel) + DataStore for the retrieval cache
+- `morning-brief.skill.md`, `feedback-sentiment-scan.skill.md` — Ollama + DataStore + a calendar MCP connector (the `$ calendar.list_events` op)
+- `classify-support-ticket.skill.md` — Ollama + DataStore
 - `cut-release-tag.skill.md` — git CLI on `PATH`; expects to run inside a git repo
 - `service-health-watch.skill.md` — `curl` on `PATH`; network egress to `status.internal/*`
 

package/examples/connectors/{MemoryStoreTemplate/MemoryStoreTemplate.ts → DataStoreTemplate/DataStoreTemplate.ts}

@@ -1,44 +1,44 @@
 /**
- * MemoryStoreTemplate — fork-me skeleton for writing your own MemoryStore impl.
+ * DataStoreTemplate — fork-me skeleton for writing your own DataStore impl.
  *
  * This is NOT a runnable connector. Every method throws a "TODO" error. The
- * purpose is to surface the MemoryStore contract surface in a copy-and-customize
+ * purpose is to surface the DataStore contract surface in a copy-and-customize
  * shape so adopters writing AMP-, Pinecone-, Weaviate-, Qdrant-, or
- * Postgres-backed MemoryStores have a starting skeleton.
+ * Postgres-backed DataStores have a starting skeleton.
  *
  * Forking workflow:
- *   1. Copy this directory into your codebase (`cp -r examples/connectors/MemoryStoreTemplate examples/connectors/MyMemoryStore`)
- *   2. Rename the class — typically `<Substrate>MemoryStore` (e.g., `PineconeMemoryStore`, `AmpMemoryStore`)
+ *   1. Copy this directory into your codebase (`cp -r examples/connectors/DataStoreTemplate examples/connectors/MyDataStore`)
+ *   2. Rename the class — typically `<Substrate>DataStore` (e.g., `PineconeDataStore`, `AmpDataStore`)
  *   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.registerMemoryStore("primary", new MyMemoryStore({ ... }))`
+ *        `registry.registerDataStore("primary", new MyDataStore({ ... }))`
  *   6. Validate via the conformance suite:
- *        `MemoryStoreConformance.buildTests({ build: () => new MyMemoryStore(...), ctor: MyMemoryStore })`
+ *        `DataStoreConformance.buildTests({ build: () => new MyDataStore(...), ctor: MyDataStore })`
  *
- * See `src/connectors/memory-store.ts` for the working reference implementation
- * (`SqliteMemoryStore` — SQLite + FTS5 backing). The full contract spec lives in
- * `src/connectors/types.ts` (`MemoryStore` interface + `PortableMemory` +
- * `QueryFilters` + `MemoryWrite` types).
+ * See `src/connectors/data-store.ts` for the working reference implementation
+ * (`SqliteDataStore` — SQLite + FTS5 backing). The full contract spec lives in
+ * `src/connectors/types.ts` (`DataStore` interface + `PortableData` +
+ * `QueryFilters` + `DataWrite` types).
  *
- * Runtime hosts (MCP server + web dashboard) honor whichever MemoryStore impl
+ * Runtime hosts (MCP server + web dashboard) honor whichever DataStore impl
  * you register via the registry, so once your fork passes the conformance
- * suite the entire `$ memory` / `$ memory_write` dispatch path reads + writes
+ * suite the entire `$ data_read` / `$ data_write` dispatch path reads + writes
  * against your substrate.
  */
 
 import type {
-  MemoryStore,
+  DataStore,
   QueryFilters,
-  PortableMemory,
-  MemoryWrite,
-  MemoryWriteRecord,
-  MemoryStoreCapabilities,
+  PortableData,
+  DataWrite,
+  DataWriteRecord,
+  DataStoreCapabilities,
   ManifestInfo,
 } from "skillscript-runtime/connectors";
 
 /** Replace with your substrate's connection config (host, dbName, API key, etc.). */
-export interface MemoryStoreTemplateConfig {
+export interface DataStoreTemplateConfig {
   // TODO — declare the fields your substrate needs to connect.
   // Examples:
   //   pineconeApiKey?: string;
@@ -48,16 +48,16 @@ export interface MemoryStoreTemplateConfig {
   exampleConfigField?: string;
 }
 
-export class MemoryStoreTemplate implements MemoryStore {
+export class DataStoreTemplate implements DataStore {
   /**
    * 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(): MemoryStoreCapabilities {
+  static staticCapabilities(): DataStoreCapabilities {
     return {
-      connector_type: "memory_store",
-      implementation: "MemoryStoreTemplate", // ← rename to your class name
+      connector_type: "data_store",
+      implementation: "DataStoreTemplate", // ← rename to your class name
       contract_version: "1.0.0",
       features: {
         // TODO — set each flag based on what your substrate can actually do.
@@ -73,29 +73,36 @@ export class MemoryStoreTemplate implements MemoryStore {
   }
 
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  constructor(_config: MemoryStoreTemplateConfig) {
+  constructor(_config: DataStoreTemplateConfig) {
     // TODO — establish your substrate connection. For SQL: open the database
     // + run schema migrations. For vector DB: cache the SDK client + index
     // name. For HTTP: store the base URL + auth headers.
-    throw new Error("MemoryStoreTemplate is a fork-me skeleton; replace with your impl.");
+    throw new Error("DataStoreTemplate 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, score range, etc.).
    *
-   * The bundled `SqliteMemoryStore.manifest()` returns:
+   * The bundled `SqliteDataStore.manifest()` returns:
    *   { 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<"memory_store">> {
+  async manifest(): Promise<ManifestInfo<"data_store">> {
     // TODO — return a snapshot of your substrate's capabilities.
     throw new Error("TODO: manifest() — return substrate-specific capability snapshot.");
   }
 
   /**
-   * Query memories by mode + filter. Return `PortableMemory[]` ordered by
+   * Query memories by mode + filter. Return `PortableData[]` ordered by
    * relevance (most relevant first). Empty result is fine; never throw "not
    * found" — return [].
    *
@@ -103,13 +110,19 @@ export class MemoryStoreTemplate implements MemoryStore {
    *   - `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.
    *
-   * `PortableMemory` core fields:
+   * `PortableData` core fields:
    *   - Always: `id`, `summary`, `created_at`
    *   - Often: `detail`, `score`, `domain_tags`, `payload_type`
    *   - Per-substrate (curated): `pinned`, `confidence`, `thread_status`,
@@ -117,24 +130,24 @@ export class MemoryStoreTemplate implements MemoryStore {
    *   - Catch-all: `metadata` object for substrate-specific extensions
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async query(_filters: QueryFilters): Promise<PortableMemory[]> {
+  async query(_filters: QueryFilters): Promise<PortableData[]> {
     // TODO — translate `filters` to your substrate's query API.
     //   - Reject unsupported `mode` values with a clear error (don't silently
     //     fall back; cold authors will be confused)
     //   - Apply curated-subset filters (domain_tags, payload_type, etc.) where
     //     the substrate supports them
-    //   - Map your substrate's result rows into `PortableMemory` shape
+    //   - Map your substrate's result rows into `PortableData` shape
     //   - Order by relevance (most relevant first)
     //   - Honor `limit`
-    throw new Error("TODO: query() — return PortableMemory[] ordered by relevance.");
+    throw new Error("TODO: query() — return PortableData[] ordered by relevance.");
   }
 
   /**
-   * Persist a new memory entry. Return the substrate-assigned `id` +
+   * Persist a new data record. Return the substrate-assigned `id` +
    * `created_at` (unix seconds).
    *
-   * `MemoryWrite` shape:
-   *   - `content`: string (required; the memory body)
+   * `DataWrite` shape:
+   *   - `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)
@@ -143,13 +156,13 @@ export class MemoryStoreTemplate implements MemoryStore {
    *     extensions like `vault`, `payload_type`, `confidence`)
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async write(_entry: MemoryWrite): Promise<MemoryWriteRecord> {
-    // TODO — persist the memory via your substrate.
+  async write(_entry: DataWrite): Promise<DataWriteRecord> {
+    // 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 }.");
   }
 }