skillscript-runtime 0.15.2 → 0.15.3

package/docs/adopter-playbook.md

@@ -129,6 +129,14 @@ skillfile init --here
 
 This creates `~/.skillscript/` with `skills/`, `traces/`, an empty `connectors.json`, and a `config.toml` stub.
 
+**If you're writing a custom bootstrap (not just using the bundled CLI):** the package is ESM-only. `npm init -y` produces a CJS `package.json` by default, which will fail your first bootstrap run with top-level-await / ESM-import errors. Switch your adopter project to ESM before authoring bootstrap code:
+
+```bash
+npm pkg set type=module
+```
+
+(Phase 2 cold-adopter dogfood, 2026-06-01: first improvisation an adopter hit was this exact gap — surfaced after a `bootstrap.ts` failed at module load. One-sentence flag saves the trip.)
+
 ### 2. Decide on substrate wiring
 
 For each of the four substrates (data store, LLM, agent harness, MCP tools), decide Case 1 or Case 2. The onboarding scaffold (`examples/onboarding-scaffold/`) is Case 1 end-to-end against a file-backed data store + OpenAI + tmux.

package/examples/connectors/DataStoreTemplate/README.md

@@ -60,6 +60,10 @@ cp -r examples/connectors/DataStoreTemplate examples/connectors/MyDataStore
 
    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 `SqliteDataStore`.
 
+   ### Running conformance against a shared persistent substrate
+
+   Same discipline as the `SkillStoreTemplate` README's section of the same name: the suite's `build()` callback is invoked **per fixture**, and the first stateful test expects `query()` on an empty store to return `[]`. For shared persistent substrates (hosted vector DBs, multi-tenant Postgres, anything where state survives across `build()` calls), your `build()` must namespace each fixture into an isolatable + wipeable subspace (tag marker, per-test schema, per-test prefix) and clear before returning the instance. The conformance suite doesn't (and can't) know what isolation your substrate supports.
+
 ## Reference implementation
 
 When in doubt about semantics, read the bundled impl:

package/examples/connectors/SkillStoreTemplate/README.md

@@ -60,6 +60,20 @@ cp -r examples/connectors/SkillStoreTemplate examples/connectors/MyDatabaseSkill
 
    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.
 
+   ### Running conformance against a shared persistent substrate
+
+   The suite's `build()` callback is invoked **per fixture** — every test rebuilds. The first stateful assertion expects `query()` on an empty store to return `[]`. For bundled-default substrates that's trivial (fresh tmpdir + new instance), but for shared persistent substrates (AMP, Postgres, MongoDB, hosted memory APIs — anything where state survives across `build()` calls), a naive `build()` that returns a wrapper over the live store fails immediately because state from prior tests leaks in.
+
+   The fix: your `build()` callback should namespace each fixture into an **isolatable + wipeable subspace** and wipe before returning the instance. Common patterns:
+
+   - **Tag-marker isolation.** Each fixture gets a unique marker tag (`fixture-${randomUUID()}`); your impl filters every operation by that tag; teardown removes everything carrying the tag.
+   - **Per-test database/schema.** Open a fresh schema/database per fixture; drop on teardown.
+   - **Per-test prefix.** Prefix every key/name with a fixture-unique string; teardown deletes by prefix.
+
+   The shared-substrate handling is your impl's responsibility — the conformance suite doesn't (and can't) know what isolation your substrate supports. If your impl can't isolate, your conformance pass is unreliable.
+
+   Phase 2 cold-adopter dogfood (2026-06-01): adopter built `AmpSkillStore` against AMP's shared skills vault, used a marker-domain-tag namespace per fixture + wiped before/after. 20/20 conformance.
+
 ## Reference implementations
 
 When in doubt about semantics, read the bundled impls:

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

@@ -1,11 +1,12 @@
 # Skill: data-store-roundtrip
-# Status: Approved v1:83897803
+# Status: Approved v1:b6e1bfb1
 # 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.
+# Description: Round-trips the DataStore — writes a record tagged with a per-run marker, reads it back via full-text search against the same marker. The marker makes the read deterministic (count == 1) regardless of prior runs accumulated in the store. If this skill executes and emits "read back 1 items", 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
+    $set MARKER = "probe-${NOW}"
+    $ data_write content="${MARKER} adopter dogfood probe record" tags=["phase1","probe"] -> W
+    $ data_read mode="fts" query="${MARKER}" limit=5 -> R
     emit(text="wrote record '${W.id}'; read back ${R.items|length} items")
 
 default: run

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-06-01T16:00:30.193Z",
+  "compiled_at": "2026-06-01T18:34:24.038Z",
   "source_skill": {
     "name": "hello-world"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "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>",
@@ -48,6 +48,10 @@
       "types": "./dist/mcp-server.d.ts",
       "import": "./dist/mcp-server.js"
     },
+    "./dashboard": {
+      "types": "./dist/dashboard/server.d.ts",
+      "import": "./dist/dashboard/server.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"

package/scaffold/skills/data-store-roundtrip.skill.md

@@ -1,11 +1,12 @@
 # Skill: data-store-roundtrip
-# Status: Approved v1:83897803
+# Status: Approved v1:b6e1bfb1
 # 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.
+# Description: Round-trips the DataStore — writes a record tagged with a per-run marker, reads it back via full-text search against the same marker. The marker makes the read deterministic (count == 1) regardless of prior runs accumulated in the store. If this skill executes and emits "read back 1 items", 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
+    $set MARKER = "probe-${NOW}"
+    $ data_write content="${MARKER} adopter dogfood probe record" tags=["phase1","probe"] -> W
+    $ data_read mode="fts" query="${MARKER}" limit=5 -> R
     emit(text="wrote record '${W.id}'; read back ${R.items|length} items")
 
 default: run