skillscript-runtime 0.2.4

package/dist/testing/conformance.js

@@ -0,0 +1,365 @@
+// ContractConformance test suites. Verifies that any connector implementation
+// actually honors its contract. Framework-agnostic: each suite returns an
+// array of `ConformanceTest { name, run() }` objects that callers wire into
+// their test framework. Example in vitest:
+//
+//   import { describe, it } from "vitest";
+//   import { SkillStoreConformance } from "skillscript-runtime/testing";
+//
+//   describe("FilesystemSkillStore conformance", () => {
+//     const tests = SkillStoreConformance.buildTests({
+//       build: () => new FilesystemSkillStore(mkdtempSync(...)),
+//       ctor: FilesystemSkillStore,
+//     });
+//     for (const t of tests) it(`[${t.category}] ${t.name}`, t.run);
+//   });
+//
+// Test categories per the v1 spec:
+//   1. method-existence    — every declared method present + callable
+//   2. return-type         — methods return values matching the contract shape
+//   3. error-contract      — methods throw the documented error class on the
+//                            documented trigger condition
+//   4. static-capabilities — `staticCapabilities()` returns a well-formed
+//                            `StaticCapabilities` object
+//   5. feature-behavior    — for every feature flag the impl declares true,
+//                            the corresponding behavior actually works
+//
+// What conformance does NOT cover: performance (separate `benchmarks` suite),
+// cross-impl interop (v2 work).
+import { SkillNotFoundError, ConnectorError } from "../errors.js";
+export const SkillStoreConformance = {
+    buildTests(fixture) {
+        return [
+            ...staticCapabilitiesTests(fixture.ctor, "skill_store"),
+            methodExistence("SkillStore.load present", fixture, "load"),
+            methodExistence("SkillStore.query present", fixture, "query"),
+            methodExistence("SkillStore.metadata present", fixture, "metadata"),
+            methodExistence("SkillStore.versions present", fixture, "versions"),
+            methodExistence("SkillStore.store present", fixture, "store"),
+            methodExistence("SkillStore.delete present", fixture, "delete"),
+            methodExistence("SkillStore.update_status present", fixture, "update_status"),
+            methodExistence("SkillStore.manifest present", fixture, "manifest"),
+            {
+                category: "return-type",
+                name: "query returns empty array on empty store",
+                run: withInstance(fixture, async (store) => {
+                    const r = await store.query();
+                    assert(Array.isArray(r), `query must return an array (got ${typeof r})`);
+                    assert(r.length === 0, `empty store must return [], got ${r.length} entries`);
+                }),
+            },
+            {
+                category: "return-type",
+                name: "store returns VersionInfo with required fields",
+                run: withInstance(fixture, async (store) => {
+                    const info = await store.store("conformance-test", SAMPLE_SKILL);
+                    assert(typeof info.name === "string", "VersionInfo.name must be string");
+                    assert(typeof info.version === "string", "VersionInfo.version must be string");
+                    assert(/^[a-f0-9]+$/.test(info.content_hash), "VersionInfo.content_hash must be hex");
+                    assert(typeof info.changed_at === "number", "VersionInfo.changed_at must be number");
+                }),
+            },
+            {
+                category: "return-type",
+                name: "load returns SkillSource with non-empty content_hash and source",
+                run: withInstance(fixture, async (store) => {
+                    await store.store("conformance-test", SAMPLE_SKILL);
+                    const src = await store.load("conformance-test");
+                    assert(src.source === SAMPLE_SKILL, "load.source must round-trip the stored bytes");
+                    assert(src.content_hash.length > 0, "load.content_hash must be populated");
+                    assert(typeof src.metadata.status === "string", "load.metadata.status must be populated");
+                }),
+            },
+            {
+                category: "error-contract",
+                name: "load throws SkillNotFoundError on missing skill",
+                run: withInstance(fixture, async (store) => {
+                    await expectThrows(() => store.load("definitely-missing-skill-xyz"), (err) => err instanceof SkillNotFoundError, "expected SkillNotFoundError");
+                }),
+            },
+            {
+                category: "error-contract",
+                name: "delete throws SkillNotFoundError on missing skill",
+                run: withInstance(fixture, async (store) => {
+                    await expectThrows(() => store.delete("definitely-missing-skill-xyz"), (err) => err instanceof SkillNotFoundError, "expected SkillNotFoundError");
+                }),
+            },
+            {
+                category: "error-contract",
+                name: "errors carry connector_type='skill_store'",
+                run: withInstance(fixture, async (store) => {
+                    try {
+                        await store.load("missing");
+                        assertUnreachable("expected throw");
+                    }
+                    catch (err) {
+                        assert(err instanceof ConnectorError, "error must extend ConnectorError");
+                        assert(err.connector_type === "skill_store", "connector_type must be 'skill_store'");
+                    }
+                }),
+            },
+            {
+                category: "feature-behavior",
+                name: "update_status: previous_status populated when supports_audit_trail=true",
+                run: withInstance(fixture, async (store) => {
+                    const caps = fixture.ctor.staticCapabilities();
+                    if (caps.features["supports_audit_trail"] !== true)
+                        return; // skip; feature opt-out
+                    await store.store("conformance-test", SAMPLE_SKILL);
+                    const v = await store.update_status("conformance-test", "Approved");
+                    assert(v.previous_status !== undefined, "audit-trail impl must populate previous_status");
+                    assert(v.status === "Approved", "update_status must persist new status");
+                }),
+            },
+            {
+                category: "feature-behavior",
+                name: "filter narrows by status when supports_writes=true",
+                run: withInstance(fixture, async (store) => {
+                    const caps = fixture.ctor.staticCapabilities();
+                    if (caps.features["supports_writes"] !== true)
+                        return;
+                    await store.store("draft-a", SAMPLE_SKILL);
+                    await store.store("approved-b", SAMPLE_SKILL);
+                    await store.update_status("approved-b", "Approved");
+                    const approved = await store.query({ status: "Approved" });
+                    assert(approved.length === 1, `expected 1 approved skill, got ${approved.length}`);
+                    assert(approved[0].name === "approved-b", `expected 'approved-b', got '${approved[0].name}'`);
+                }),
+            },
+        ];
+    },
+};
+export const MemoryStoreConformance = {
+    buildTests(fixture) {
+        return [
+            ...staticCapabilitiesTests(fixture.ctor, "memory_store"),
+            methodExistence("MemoryStore.query present", fixture, "query"),
+            methodExistence("MemoryStore.manifest present", fixture, "manifest"),
+            {
+                category: "return-type",
+                name: "query returns array of PortableMemory shape",
+                run: withInstance(fixture, async (store) => {
+                    const r = await store.query({ query: "anything", limit: 10, mode: "fts" });
+                    assert(Array.isArray(r), `query must return an array (got ${typeof r})`);
+                    for (const m of r) {
+                        assert(typeof m.id === "string", "PortableMemory.id must be string");
+                        assert(typeof m.summary === "string", "PortableMemory.summary must be string");
+                    }
+                }),
+            },
+            {
+                category: "feature-behavior",
+                name: "supportedModes that declare true actually work",
+                run: withInstance(fixture, async (store) => {
+                    const caps = fixture.ctor.staticCapabilities();
+                    const modes = ["fts", "semantic", "rerank"];
+                    for (const mode of modes) {
+                        const flag = `supports_${mode === "fts" ? "fts" : mode}`;
+                        if (caps.features[flag] === true) {
+                            // Should not throw; empty result acceptable.
+                            const r = await store.query({ query: "test", limit: 1, mode });
+                            assert(Array.isArray(r), `mode='${mode}' must return an array`);
+                        }
+                    }
+                }),
+            },
+        ];
+    },
+};
+export const LocalModelConformance = {
+    buildTests(fixture) {
+        return [
+            ...staticCapabilitiesTests(fixture.ctor, "local_model"),
+            methodExistence("LocalModel.run present", fixture, "run"),
+            methodExistence("LocalModel.manifest present", fixture, "manifest"),
+            {
+                category: "return-type",
+                name: "manifest returns capabilities_version + manifest fields",
+                run: withInstance(fixture, async (model) => {
+                    const m = await model.manifest();
+                    assert(typeof m.capabilities_version === "string", "manifest.capabilities_version must be string");
+                    assert(typeof m.manifest === "object" && m.manifest !== null, "manifest.manifest must be object");
+                }),
+            },
+            {
+                category: "feature-behavior",
+                name: "run returns string on success when liveDispatch=true",
+                run: withInstance(fixture, async (model) => {
+                    if (fixture.liveDispatch !== true)
+                        return; // skip when not reachable
+                    const r = await model.run("hi", { maxTokens: 5 });
+                    assert(typeof r === "string", `run must return string (got ${typeof r})`);
+                }),
+            },
+        ];
+    },
+};
+export const McpConnectorConformance = {
+    buildTests(fixture) {
+        return [
+            ...staticCapabilitiesTests(fixture.ctor, "mcp_connector"),
+            methodExistence("McpConnector.call present", fixture, "call"),
+            methodExistence("McpConnector.manifest present", fixture, "manifest"),
+            {
+                category: "return-type",
+                name: "manifest returns capabilities_version + manifest fields",
+                run: withInstance(fixture, async (connector) => {
+                    const m = await connector.manifest();
+                    assert(typeof m.capabilities_version === "string", "manifest.capabilities_version must be string");
+                }),
+            },
+        ];
+    },
+};
+export const AgentConnectorConformance = {
+    buildTests(fixture) {
+        const tests = [
+            ...staticCapabilitiesTests(fixture.ctor, "agent_connector"),
+            methodExistence("AgentConnector.list_agents present", fixture, "list_agents"),
+            methodExistence("AgentConnector.deliver present", fixture, "deliver"),
+            methodExistence("AgentConnector.wake present", fixture, "wake"),
+            methodExistence("AgentConnector.manifest present", fixture, "manifest"),
+            {
+                category: "return-type",
+                name: "list_agents returns an array",
+                run: withInstance(fixture, async (connector) => {
+                    const r = await connector.list_agents();
+                    assert(Array.isArray(r), `list_agents must return an array (got ${typeof r})`);
+                }),
+            },
+            {
+                category: "return-type",
+                name: "manifest returns capabilities_version + manifest fields",
+                run: withInstance(fixture, async (connector) => {
+                    const m = await connector.manifest();
+                    assert(typeof m.capabilities_version === "string", "manifest.capabilities_version must be string");
+                }),
+            },
+        ];
+        const testAgentId = fixture.testAgentId;
+        if (testAgentId !== undefined) {
+            tests.push({
+                category: "feature-behavior",
+                name: "deliver(kind=augment) returns DeliveryReceipt with delivered_at",
+                run: withInstance(fixture, async (connector) => {
+                    const receipt = await connector.deliver(testAgentId, { kind: "augment", content: "conformance" });
+                    assert(typeof receipt.delivered_at === "number", "DeliveryReceipt.delivered_at must be number");
+                }),
+            });
+            tests.push({
+                category: "feature-behavior",
+                name: "deliver(kind=template) returns DeliveryReceipt with delivered_at",
+                run: withInstance(fixture, async (connector) => {
+                    const receipt = await connector.deliver(testAgentId, { kind: "template", prompt: "conformance" });
+                    assert(typeof receipt.delivered_at === "number", "DeliveryReceipt.delivered_at must be number");
+                }),
+            });
+            tests.push({
+                category: "feature-behavior",
+                name: "wake returns WakeReceipt with woken_at",
+                run: withInstance(fixture, async (connector) => {
+                    const receipt = await connector.wake(testAgentId);
+                    assert(typeof receipt.woken_at === "number", "WakeReceipt.woken_at must be number");
+                }),
+            });
+        }
+        return tests;
+    },
+};
+// ─── Shared assertion helpers ─────────────────────────────────────────────
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(`Conformance assertion failed: ${message}`);
+}
+function assertUnreachable(message) {
+    throw new Error(`Conformance assertion failed: ${message}`);
+}
+async function expectThrows(fn, predicate, message) {
+    try {
+        await fn();
+        throw new Error(`Conformance assertion failed: ${message}, but no error was thrown`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("Conformance assertion failed"))
+            throw err;
+        if (!predicate(err)) {
+            throw new Error(`Conformance assertion failed: ${message}, got ${err?.constructor?.name ?? typeof err}: ${err?.message ?? err}`);
+        }
+    }
+}
+function methodExistence(name, fixture, method) {
+    return {
+        category: "method-existence",
+        name,
+        run: withInstance(fixture, async (instance) => {
+            const obj = instance;
+            assert(typeof obj[method] === "function", `instance.${method} must be a function`);
+        }),
+    };
+}
+function staticCapabilitiesTests(ctor, expectedKind) {
+    return [
+        {
+            category: "static-capabilities",
+            name: `staticCapabilities() returns connector_type='${expectedKind}'`,
+            run: async () => {
+                const caps = ctor.staticCapabilities();
+                assert(caps.connector_type === expectedKind, `connector_type must be '${expectedKind}' (got '${caps.connector_type}')`);
+            },
+        },
+        {
+            category: "static-capabilities",
+            name: "staticCapabilities() returns non-empty implementation + contract_version",
+            run: async () => {
+                const caps = ctor.staticCapabilities();
+                assert(typeof caps.implementation === "string" && caps.implementation.length > 0, "implementation must be non-empty string");
+                assert(typeof caps.contract_version === "string" && /^\d+\.\d+\.\d+$/.test(caps.contract_version), "contract_version must be semver-ish");
+            },
+        },
+        {
+            category: "static-capabilities",
+            name: "staticCapabilities() features map is well-formed",
+            run: async () => {
+                const caps = ctor.staticCapabilities();
+                assert(typeof caps.features === "object" && caps.features !== null, "features must be object");
+                for (const [k, v] of Object.entries(caps.features)) {
+                    assert(typeof v === "boolean", `feature '${k}' must be boolean (got ${typeof v})`);
+                }
+            },
+        },
+        {
+            category: "static-capabilities",
+            name: "staticCapabilities() callable without instance construction",
+            run: async () => {
+                // The whole point of static-capabilities: the linter must be able to
+                // discover features without paying construction cost. This test
+                // asserts the method is on the class (constructor), not on the
+                // prototype/instance.
+                const caps = ctor.staticCapabilities();
+                assert(caps !== null, "static call returned null");
+            },
+        },
+    ];
+}
+function withInstance(fixture, body) {
+    return async () => {
+        const instance = fixture.build();
+        try {
+            await body(instance);
+        }
+        finally {
+            if (typeof fixture.teardown === "function")
+                await fixture.teardown(instance);
+        }
+    };
+}
+// Sample skill used by SkillStore conformance tests that need a payload.
+const SAMPLE_SKILL = `# Skill: conformance-test
+# Status: draft
+
+t:
+    ! hi
+
+default: t
+`;
+//# sourceMappingURL=conformance.js.map

package/dist/testing/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { SkillStoreConformance, MemoryStoreConformance, LocalModelConformance, McpConnectorConformance, AgentConnectorConformance, } from "./conformance.js";
+export type { ConformanceTest, ConformanceCategory, SkillStoreFixture, MemoryStoreFixture, LocalModelFixture, McpConnectorFixture, AgentConnectorFixture, } from "./conformance.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+// `skillscript-runtime/testing` entry point. ContractConformance suites for
+// the four connector contracts. Imported by impl authors writing conformance
+// tests against their substrate; not part of the runtime hot path.
+export { SkillStoreConformance, MemoryStoreConformance, LocalModelConformance, McpConnectorConformance, AgentConnectorConformance, } from "./conformance.js";
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAC7E,mEAAmE;AAEnE,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC"}

package/dist/trace.d.ts

@@ -0,0 +1,141 @@
+import type { ExecutionError } from "./runtime.js";
+/**
+ * Per-fire dispatch trace recording. Lets operators query "what did this
+ * skill do at 09:05?" + "which fires failed?" + replay traces against
+ * current connectors for "does this still work?" debugging.
+ *
+ * Three trace modes per-deployment + per-fire (per Open Q #6 disposition):
+ *   - off    — no per-fire record. Error-only trace records still written
+ *              (NFR-11 floor: failures always visible).
+ *   - on     — every op + every output recorded.
+ *   - sample — N% of fires recorded; sampling is deterministic via SHA-256
+ *              of (trigger_id + skill_name).
+ *
+ * Trace store contract: pluggable backend. v1 ships `FilesystemTraceStore`
+ * (file-backed default, zero external dependency). `MemoryStoreTraceStore`
+ * (substrate-backed via the configured MemoryStore connector) becomes
+ * possible when MemoryStore contract grows a write surface — currently
+ * read-only per §3.
+ */
+export type TraceMode = "off" | "on" | "sample";
+export interface TraceConfig {
+    mode: TraceMode;
+    /** Used when mode === "sample"; integer 0-100. Default 10. */
+    samplePct?: number;
+    /** Retention in ms before prune archives the record. Default 30d. */
+    retentionMs?: number;
+}
+/**
+ * Versioned trace record. Bumping `version` is a breaking change for
+ * trace store consumers; T6 ships at version 1.
+ */
+export interface TraceRecord {
+    version: 1;
+    trace_id: string;
+    skill_name: string;
+    skill_version: string;
+    trigger: {
+        source: string;
+        name: string;
+        fired_at_ms: number;
+    };
+    identity: {
+        agent_id?: string;
+    };
+    ops: TraceOpRecord[];
+    emissions: string[];
+    outputs: Record<string, unknown>;
+    errors: ExecutionError[];
+    fired_at_ms: number;
+    completed_at_ms: number;
+    duration_ms: number;
+}
+export interface TraceOpRecord {
+    op_kind: string;
+    target: string;
+    body: string;
+    started_at_ms: number;
+    duration_ms: number;
+    /** True when the op produced an error (captured in TraceRecord.errors). */
+    errored: boolean;
+    /**
+     * Connector instance this op dispatched through. Present for `$`/`~`/`>`
+     * ops; absent for `@`/`!`/`??`/`$set`/`foreach`/`if` (no connector
+     * involvement). Used by `healthMetrics()` for per-connector aggregation.
+     */
+    connector?: string;
+}
+export interface TraceQueryFilter {
+    skill_name?: string;
+    since_ms?: number;
+    until_ms?: number;
+    limit?: number;
+}
+export interface TraceStore {
+    write(record: TraceRecord): Promise<void>;
+    query(filter: TraceQueryFilter): Promise<TraceRecord[]>;
+    get(traceId: string): Promise<TraceRecord | null>;
+    /**
+     * Prune records older than now-retentionMs. Non-destructive by default:
+     * v1 hard-deletes (audit trail simplification); v1.x can add an archive
+     * path. Returns the count of records pruned.
+     */
+    prune(retentionMs: number): Promise<number>;
+}
+/**
+ * Writes JSON records under `<rootDir>/<skill_name>/<trace_id>.json`.
+ * Zero external dependency; suitable for the standalone runtime out of
+ * the box. Operators with a substrate wired can swap for a
+ * substrate-backed store via config.
+ */
+export declare class FilesystemTraceStore implements TraceStore {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    write(record: TraceRecord): Promise<void>;
+    query(filter: TraceQueryFilter): Promise<TraceRecord[]>;
+    get(traceId: string): Promise<TraceRecord | null>;
+    prune(retentionMs: number): Promise<number>;
+}
+/**
+ * Deterministic sample decision per Open Q #2: SHA-256 of `trigger_id +
+ * ":" + skill_name`, take the first byte mod 100, fire trace if under
+ * `pct`. Same inputs always produce the same sampling decision — useful
+ * for reproducible testing + dashboard drill-down.
+ */
+export declare function shouldSample(triggerId: string, skillName: string, pct: number): boolean;
+/**
+ * Accumulator used by the runtime during a single fire. Records per-op
+ * timing + body; finalize() builds the immutable TraceRecord.
+ */
+export declare class TraceBuilder {
+    private readonly skill_name;
+    private readonly skill_version;
+    private readonly trigger;
+    private readonly identity;
+    private readonly ops;
+    private readonly firedAtMs;
+    readonly trace_id: string;
+    constructor(skill_name: string, skill_version: string, trigger: {
+        source: string;
+        name: string;
+        fired_at_ms: number;
+    }, identity: {
+        agent_id?: string;
+    });
+    recordOp(record: TraceOpRecord): void;
+    finalize(emissions: string[], outputs: Record<string, unknown>, errors: ExecutionError[]): TraceRecord;
+}
+/**
+ * Decide whether a fire should be traced given config + trigger context.
+ * Used by the runtime / scheduler at fire start. `mode === "off"` always
+ * returns false (errors are still surfaced via `result.errors[]` — the
+ * NFR-11 floor); the trace store is bypassed entirely.
+ */
+export declare function shouldTraceFire(config: TraceConfig | undefined, triggerId: string, skillName: string): boolean;
+export declare const TRACE_DEFAULTS: {
+    readonly SAMPLE_PCT: 10;
+    readonly RETENTION_MS: number;
+};
+/** Convenience for tests: derive the on-disk path FilesystemTraceStore writes to. */
+export declare function _traceFilePathFor(rootDir: string, record: TraceRecord): string;
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"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"}