opensquid 0.5.395

package/dist/functions/path_exists.js.map

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

package/dist/functions/rag.d.ts

@@ -0,0 +1,39 @@
+/**
+ * RAG primitives: `recall`, `embed`, `store_lesson`.
+ *
+ * Skills compose these into rule processes via YAML; the runtime
+ * dispatches each call through whichever backend the user configured
+ * (libsql-qwen3 default, libsql-lexical fallback, or an adapter — see
+ * src/rag/backend_factory.ts).
+ *
+ * Pluggability boundary: this file imports `RagBackend` ONLY from
+ * `../rag/types.js` — no `@libsql/client` types, no embedder-specific
+ * imports. A skill that calls `function: recall` doesn't know or care
+ * what backend serves the request. Audit rule: keep it that way.
+ *
+ * Primitive surfaces:
+ *
+ *   recall({ query, k? = 5 }) → ok(RecallHit[])
+ *     Fused semantic + lexical recall. Returns `[]` for empty DB or
+ *     queries that match nothing. Errors travel as `runtime` — recall
+ *     bugs (driver crash, schema mismatch) shouldn't silently mask
+ *     empty results.
+ *
+ *   embed({ text }) → ok(number[] | null)
+ *     `null` means the embedder is unavailable (Ollama down / model
+ *     missing). Treat that as a degraded-mode signal, not an error —
+ *     `store_lesson` continues to work, recall falls back to lexical.
+ *
+ *   store_lesson({ id, content, tags?, source?, author? }) → ok(undefined)
+ *     Stamps `createdAt` with `new Date().toISOString()` so YAML
+ *     authors don't have to compute it. `tags` defaults to `[]`,
+ *     `source` to `'unknown'`, `author` to `'agent'` — these match
+ *     the most common path (agent-captured candidates during a run).
+ *
+ * Imports from: zod, ../rag/types.js, ../runtime/result.js, ./registry.js.
+ * Imported by: src/functions/index.ts (registry wiring).
+ */
+import type { RagBackend } from '../rag/types.js';
+import type { FunctionRegistry } from './registry.js';
+export declare function registerRagFunctions(registry: FunctionRegistry, backend: RagBackend): void;
+//# sourceMappingURL=rag.d.ts.map

package/dist/functions/rag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag.d.ts","sourceRoot":"","sources":["../../src/functions/rag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAgCtD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CA2E1F"}

package/dist/functions/rag.js

@@ -0,0 +1,142 @@
+/**
+ * RAG primitives: `recall`, `embed`, `store_lesson`.
+ *
+ * Skills compose these into rule processes via YAML; the runtime
+ * dispatches each call through whichever backend the user configured
+ * (libsql-qwen3 default, libsql-lexical fallback, or an adapter — see
+ * src/rag/backend_factory.ts).
+ *
+ * Pluggability boundary: this file imports `RagBackend` ONLY from
+ * `../rag/types.js` — no `@libsql/client` types, no embedder-specific
+ * imports. A skill that calls `function: recall` doesn't know or care
+ * what backend serves the request. Audit rule: keep it that way.
+ *
+ * Primitive surfaces:
+ *
+ *   recall({ query, k? = 5 }) → ok(RecallHit[])
+ *     Fused semantic + lexical recall. Returns `[]` for empty DB or
+ *     queries that match nothing. Errors travel as `runtime` — recall
+ *     bugs (driver crash, schema mismatch) shouldn't silently mask
+ *     empty results.
+ *
+ *   embed({ text }) → ok(number[] | null)
+ *     `null` means the embedder is unavailable (Ollama down / model
+ *     missing). Treat that as a degraded-mode signal, not an error —
+ *     `store_lesson` continues to work, recall falls back to lexical.
+ *
+ *   store_lesson({ id, content, tags?, source?, author? }) → ok(undefined)
+ *     Stamps `createdAt` with `new Date().toISOString()` so YAML
+ *     authors don't have to compute it. `tags` defaults to `[]`,
+ *     `source` to `'unknown'`, `author` to `'agent'` — these match
+ *     the most common path (agent-captured candidates during a run).
+ *
+ * Imports from: zod, ../rag/types.js, ../runtime/result.js, ./registry.js.
+ * Imported by: src/functions/index.ts (registry wiring).
+ */
+import { z } from 'zod';
+import { resolveRecallScope } from '../rag/scope.js';
+import { err, ok } from '../runtime/result.js';
+// ---------------------------------------------------------------------------
+// Zod arg schemas.
+//
+// `query` / `text` get `min(1)` to block empty-string foot-guns (an empty
+// query against FTS5 is almost always a YAML wiring bug, not user intent).
+// `k` is bounded (1..100): the upper bound stops a pack from accidentally
+// asking for every row in the DB. `id` / `content` on store_lesson also
+// `min(1)` for the same reason.
+//
+// `author` is the canonical `'user' | 'agent'` enum from RagBackend's
+// `Lesson` type — keep them in sync.
+// ---------------------------------------------------------------------------
+const RecallArgs = z.object({
+    query: z.string().min(1),
+    k: z.number().int().positive().max(100).optional(),
+});
+const EmbedArgs = z.object({
+    text: z.string().min(1),
+});
+const StoreLessonArgs = z.object({
+    id: z.string().min(1),
+    content: z.string().min(1),
+    tags: z.array(z.string()).optional(),
+    source: z.string().min(1).optional(),
+    author: z.enum(['user', 'agent']).optional(),
+});
+export function registerRagFunctions(registry, backend) {
+    // DURABLE.2 — RAG primitives touch the libsql backend (and, for `embed`,
+    // possibly an Ollama subprocess). All three are durable: re-running on
+    // resume costs an extra round-trip per call; the checkpoint write is
+    // cheaper than rerunning the embedder or fts5 search. `recall` + `embed`
+    // are memoizable: same query/text → same hit list / vector (within a
+    // bounded TTL). `store_lesson` is a side-effecting write — never memoize a
+    // write, or two identical calls would silently no-op the second insert.
+    registry.register({
+        name: 'recall',
+        argSchema: RecallArgs,
+        durable: true,
+        memoizable: true,
+        costEstimateMs: 50,
+        execute: async ({ query, k }) => {
+            try {
+                const scope = await resolveRecallScope();
+                const hits = await backend.recall(query, k ?? 5, scope);
+                return ok(hits);
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `recall(${query}): ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+    registry.register({
+        name: 'embed',
+        argSchema: EmbedArgs,
+        durable: true,
+        memoizable: true,
+        costEstimateMs: 50,
+        execute: async ({ text }) => {
+            try {
+                const vec = await backend.embed(text);
+                return ok(vec);
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `embed: ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+    registry.register({
+        name: 'store_lesson',
+        argSchema: StoreLessonArgs,
+        durable: true,
+        memoizable: false,
+        costEstimateMs: 50,
+        execute: async ({ id, content, tags, source, author }) => {
+            try {
+                await backend.storeLesson({
+                    id,
+                    content,
+                    tags: tags ?? [],
+                    source: source ?? 'unknown',
+                    author: author ?? 'agent',
+                    createdAt: new Date().toISOString(),
+                });
+                return ok(undefined);
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `store_lesson(${id}): ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+}
+//# sourceMappingURL=rag.js.map

package/dist/functions/rag.js.map

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

package/dist/functions/recall_pre_inject.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `recall_pre_inject` primitive — pre-inject top-K memory hits into the
+ * current `UserPromptSubmit` context.
+ *
+ * Composes the same recall path as the `recall` MCP tool: pulls the user's
+ * prompt from the `prompt_submit` event, queries the configured RAG backend,
+ * filters by `min_score`, applies a whole-hit token-budget guard, and emits
+ * the formatted hit list as a `RuleResult.inject_context` payload.
+ *
+ * Cross-harness portability: this primitive is harness-AGNOSTIC. It only
+ * returns structured data (a `content: string`). The host-specific framing
+ * (Claude Code's `hookSpecificOutput.additionalContext` JSON envelope,
+ * Cursor's equivalent, Pack CLI's equivalent) lives in the per-host hook
+ * binary (currently `src/runtime/hooks/user-prompt-submit.ts`). Other hooks
+ * that emit this kind of result get a stderr warning at dispatch time
+ * (`dispatch.ts`) — only `UserPromptSubmit` actually writes it out.
+ *
+ * Special evaluator integration: returning the shape
+ * `{ kind: 'inject_context', content }` from this primitive makes the
+ * evaluator (`evaluator.ts`) treat it as a TERMINAL `RuleResult` — the same
+ * pattern the `verdict` primitive uses. No bindings, no fall-through. An
+ * empty / no-hit recall returns `null`, which the evaluator's `isEmpty`
+ * branch handles as no-verdict.
+ *
+ * Token-budget guard model (per task spec G.4):
+ *   - Crude estimate `Math.ceil(content.length / 4)` (4 chars/token); real
+ *     tokenizer is a deliberate follow-up. 4000 conservative for Claude.
+ *   - Score filter (cheaper signal) runs FIRST, then the token guard. This
+ *     keeps the loop bounded even if the backend returns many low-quality
+ *     hits — they're filtered before we start counting tokens.
+ *   - Whole-hit granularity only — never split a hit mid-string. If hit N+1
+ *     would push us past `max_tokens`, we keep N and stop.
+ *
+ * Imports from: zod, ../rag/types.js, ../runtime/result.js, ./registry.js.
+ * Imported by: src/runtime/bootstrap.ts (registry wiring).
+ */
+import type { RagBackend } from '../rag/types.js';
+import type { FunctionRegistry } from './registry.js';
+export declare function registerRecallPreInjectFunction(registry: FunctionRegistry, backend: RagBackend): void;
+//# sourceMappingURL=recall_pre_inject.d.ts.map

package/dist/functions/recall_pre_inject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall_pre_inject.d.ts","sourceRoot":"","sources":["../../src/functions/recall_pre_inject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,iBAAiB,CAAC;AAK7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAyFtD,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,UAAU,GAClB,IAAI,CA4DN"}

package/dist/functions/recall_pre_inject.js

@@ -0,0 +1,180 @@
+/**
+ * `recall_pre_inject` primitive — pre-inject top-K memory hits into the
+ * current `UserPromptSubmit` context.
+ *
+ * Composes the same recall path as the `recall` MCP tool: pulls the user's
+ * prompt from the `prompt_submit` event, queries the configured RAG backend,
+ * filters by `min_score`, applies a whole-hit token-budget guard, and emits
+ * the formatted hit list as a `RuleResult.inject_context` payload.
+ *
+ * Cross-harness portability: this primitive is harness-AGNOSTIC. It only
+ * returns structured data (a `content: string`). The host-specific framing
+ * (Claude Code's `hookSpecificOutput.additionalContext` JSON envelope,
+ * Cursor's equivalent, Pack CLI's equivalent) lives in the per-host hook
+ * binary (currently `src/runtime/hooks/user-prompt-submit.ts`). Other hooks
+ * that emit this kind of result get a stderr warning at dispatch time
+ * (`dispatch.ts`) — only `UserPromptSubmit` actually writes it out.
+ *
+ * Special evaluator integration: returning the shape
+ * `{ kind: 'inject_context', content }` from this primitive makes the
+ * evaluator (`evaluator.ts`) treat it as a TERMINAL `RuleResult` — the same
+ * pattern the `verdict` primitive uses. No bindings, no fall-through. An
+ * empty / no-hit recall returns `null`, which the evaluator's `isEmpty`
+ * branch handles as no-verdict.
+ *
+ * Token-budget guard model (per task spec G.4):
+ *   - Crude estimate `Math.ceil(content.length / 4)` (4 chars/token); real
+ *     tokenizer is a deliberate follow-up. 4000 conservative for Claude.
+ *   - Score filter (cheaper signal) runs FIRST, then the token guard. This
+ *     keeps the loop bounded even if the backend returns many low-quality
+ *     hits — they're filtered before we start counting tokens.
+ *   - Whole-hit granularity only — never split a hit mid-string. If hit N+1
+ *     would push us past `max_tokens`, we keep N and stop.
+ *
+ * Imports from: zod, ../rag/types.js, ../runtime/result.js, ./registry.js.
+ * Imported by: src/runtime/bootstrap.ts (registry wiring).
+ */
+import { z } from 'zod';
+import { NULL_SCOPE_NOTICE, resolveRecallScope } from '../rag/scope.js';
+import { applyHitBudget } from '../runtime/load_budget.js';
+import { err, ok } from '../runtime/result.js';
+import { readActiveTask } from '../runtime/session_state.js';
+// ---------------------------------------------------------------------------
+// Zod arg schema — defaults locked at Phase-2 (learn) per task spec G.4.
+// `.strict()` rejects unexpected YAML keys so typos surface as `arg_invalid`.
+// ---------------------------------------------------------------------------
+const RecallPreInjectArgs = z
+    .object({
+    k: z.number().int().min(1).max(20).default(5),
+    min_score: z.number().min(0).max(1).default(0.4),
+    max_tokens: z.number().int().min(100).max(20000).default(4000),
+    min_prompt_chars: z.number().int().min(0).max(10000).default(20),
+    query_field: z.enum(['prompt', 'user_prompt']).default('prompt'),
+})
+    .strict();
+/** Crude token estimate. ~4 chars/token is the documented approximation. */
+function estimateTokens(s) {
+    return Math.ceil(s.length / 4);
+}
+/**
+ * T-CTX-LOOP CTX.6 — score-filter + token-budget selection now delegates
+ * to the shared `applyHitBudget` primitive. The RecallHit's `tokenCost`
+ * computation (Math.ceil(content.length / 4)) is supplied at the call site
+ * so the primitive itself stays tokenizer-agnostic.
+ */
+function selectHitsForInjection(hits, minScore, maxTokens) {
+    const budgeted = hits.map((h) => ({
+        hit: h,
+        score: h.score,
+        tokenCost: estimateTokens(h.lesson.content),
+    }));
+    const result = applyHitBudget(budgeted, minScore, maxTokens);
+    return { kept: result.kept.map((b) => b.hit), truncated: result.truncated };
+}
+/**
+ * T-CTX-LOOP CTX.3 — compose the recall query with the active-task goal-token
+ * so retrieved hits are biased toward the CURRENT goal, not just the literal
+ * prompt vocabulary. When no active-task signal is present (interactive mode
+ * with no task seeded) the query falls through to the raw prompt — preserving
+ * the pre-CTX.3 behavior for non-automation use.
+ *
+ * Format: `task:<taskId> goal:<subject up to 80 chars> <prompt>`. The
+ * task-id surfaces the track identifier; the subject surfaces the
+ * human-readable goal vocabulary; both ride forward into the recall
+ * embedding so semantically-similar memories rank higher.
+ *
+ * Pack-hint extraction (the larger L14 spec form) is deferred to v2 —
+ * needs `packs` threaded through `EvalCtx` which is a wider change than
+ * CTX.3's scope. The active-task signal alone is the larger share of
+ * the goal-bias gain since it's already the workflow gate's source of
+ * truth.
+ */
+async function composeRecallQuery(prompt, sessionId) {
+    try {
+        const active = await readActiveTask(sessionId);
+        if (active === null)
+            return prompt;
+        const taskId = active.taskId ?? '';
+        const subject = (active.subject ?? '').slice(0, 80);
+        const goalToken = `task:${taskId} goal:${subject}`.trim();
+        return goalToken.length > 0 ? `${goalToken} ${prompt}` : prompt;
+    }
+    catch {
+        // Active-task read failure is non-fatal — fall back to the raw prompt
+        // so a corrupted state file can't break recall entirely.
+        return prompt;
+    }
+}
+/** Format the kept hits as a single string ready for context injection. */
+function formatHitsForInjection(hits, query, truncated) {
+    const headerQuery = query.length > 80 ? `${query.slice(0, 80)}…` : query;
+    const truncatedNote = truncated ? ' (truncated by token budget)' : '';
+    const header = `[opensquid recall — top ${String(hits.length)} memories for "${headerQuery}"${truncatedNote}]`;
+    const body = hits
+        .map((h, i) => `${String(i + 1)}. (score=${h.score.toFixed(3)}, source=${h.source})\n${h.lesson.content}`)
+        .join('\n\n');
+    return `${header}\n\n${body}\n\n[end opensquid recall]`;
+}
+export function registerRecallPreInjectFunction(registry, backend) {
+    registry.register({
+        name: 'recall_pre_inject',
+        argSchema: RecallPreInjectArgs,
+        // Backend recall is the same call as `recall`; same durability profile.
+        durable: true,
+        memoizable: true,
+        costEstimateMs: 50,
+        execute: async (args, ctx) => {
+            // Zod `.default()` is applied by the registry's `safeParse` before
+            // `execute` runs, but `FunctionDef<TArgs>` infers `TArgs` from the
+            // schema's INPUT type — where defaulted fields stay optional. The
+            // `??` fallbacks below mirror the schema defaults so TS narrows.
+            // Keeps the surface identical to the existing rag.ts pattern.
+            const k = args.k ?? 5;
+            const minScore = args.min_score ?? 0.4;
+            const maxTokens = args.max_tokens ?? 4000;
+            const minPromptChars = args.min_prompt_chars ?? 20;
+            // `query_field` reserved for future host adapters that surface the
+            // prompt under a different field name; the PromptSubmitEvent shape
+            // has only `prompt`, so 'user_prompt' is forward-compat scaffolding.
+            void args.query_field;
+            // Only meaningful on `prompt_submit` events. Other event kinds return
+            // null → evaluator treats as empty → no-verdict (no injection). This
+            // is the per-primitive guard; the dispatcher-level warning catches
+            // misconfiguration where a pack registers this on the wrong trigger.
+            if (ctx.event.kind !== 'prompt_submit')
+                return ok(null);
+            const rawPrompt = ctx.event.prompt;
+            // The min-prompt-chars gate runs against the RAW prompt — the
+            // goal-token doesn't artificially satisfy a short-prompt skip.
+            if (rawPrompt.length < minPromptChars)
+                return ok(null);
+            // T-CTX-LOOP CTX.3 — bias query toward the current goal when
+            // active-task is seeded. Falls back to raw prompt when no signal.
+            const query = await composeRecallQuery(rawPrompt, ctx.sessionId);
+            let hits;
+            const scope = await resolveRecallScope();
+            try {
+                hits = await backend.recall(query, k, scope);
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `recall_pre_inject(${query}): ${String(e)}`,
+                    cause: e,
+                });
+            }
+            // Fail-LOUD: a null namespace means project memory was withheld this turn — inject the notice so
+            // it is visible, never a silent forget. (Rare: the resolver falls back umbrella → project-uuid.)
+            const notice = scope.namespace === null ? `${NULL_SCOPE_NOTICE}\n\n` : '';
+            const { kept, truncated } = selectHitsForInjection(hits, minScore, maxTokens);
+            if (kept.length === 0) {
+                return notice === ''
+                    ? ok(null)
+                    : ok({ kind: 'inject_context', content: notice.trim() });
+            }
+            const content = notice + formatHitsForInjection(kept, query, truncated);
+            return ok({ kind: 'inject_context', content });
+        },
+    });
+}
+//# sourceMappingURL=recall_pre_inject.js.map

package/dist/functions/recall_pre_inject.js.map

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

package/dist/functions/registry.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Function-library registry: typed `FunctionDef` + name-keyed dispatcher.
+ *
+ * Architecture (per `project_opensquid_modular_function_skill_separation`):
+ * the runtime ships atomic primitives (regex, state I/O, LLM calls, verdicts);
+ * skills compose them into rule processes via YAML. The registry is the ONLY
+ * path from a skill step to a primitive — no global `import { add }`
+ * shortcuts. The evaluator (Task 1.3) drives every call through `call()`.
+ *
+ * Each `FunctionDef` carries its own Zod arg schema. The registry validates
+ * args before invoking `execute`, so primitives see only well-typed input
+ * and never have to re-check what the YAML claimed it was passing.
+ *
+ * Error model: throws are reserved for programmer errors at startup
+ * (duplicate registration). Runtime failures travel as `Result<T, FunctionError>`
+ * — see `src/runtime/result.ts`. Primitives MUST NOT throw inside `execute`;
+ * the evaluator catches stray throws and wraps them in `{ kind: 'runtime' }`,
+ * but that path is for bugs, not for normal failure modes.
+ *
+ * Imports from: zod, runtime/types.ts, runtime/result.ts.
+ * Imported by: runtime/ (evaluator), packs/ (when skills resolve `function:` refs).
+ */
+import type { z } from 'zod';
+import type { ModelsConfig } from '../packs/schemas/models.js';
+import { type Result } from '../runtime/result.js';
+import type { Event } from '../runtime/types.js';
+import type { Fsm } from '../runtime/fsm.js';
+export interface EvalCtx {
+    event: Event;
+    bindings: Map<string, unknown>;
+    sessionId: string;
+    packId: string;
+    /**
+     * PR-followup: pack-shipped `models.yaml` content (`Pack.models`), threaded
+     * through so `llm_classify` / `subagent_call` primitives can consult the
+     * pack's declared aliases without the global `loadModelsConfig()` call
+     * having to re-discover the active pack. `undefined` for packs that ship
+     * no `models.yaml` and for non-pack call sites (legacy daemon).
+     */
+    packModels?: ModelsConfig;
+    /**
+     * Slice A3b: the calling pack's declared lifecycle FSM (`Pack.fsm`), threaded
+     * like `packModels` so `read_fsm_state` / `advance_fsm` can read + advance the
+     * machine without re-loading the pack. `undefined` when the pack ships no
+     * `fsm.yaml` (those primitives then no-op).
+     */
+    packFsm?: Fsm;
+}
+export interface FunctionError {
+    kind: 'arg_invalid' | 'runtime' | 'timeout' | 'not_found';
+    message: string;
+    cause?: unknown;
+}
+export interface FunctionDef<TArgs = unknown, TResult = unknown> {
+    name: string;
+    argSchema: z.ZodSchema<TArgs>;
+    execute: (args: TArgs, ctx: EvalCtx) => Promise<Result<TResult, FunctionError>>;
+    /** Checkpoint after each call so crashes can resume mid-rule. */
+    durable?: boolean;
+    /** Cache identical `(fn, args)` outputs (DURABLE.3, wired separately). */
+    memoizable?: boolean;
+    /** Order-of-magnitude latency hint; informational only. */
+    costEstimateMs?: number;
+}
+/**
+ * Effective (post-default) durability metadata for a registered primitive.
+ * Returned by `FunctionRegistry.durability` so callers (evaluator, future
+ * memo cache, audit tooling) read a normalized record rather than poking at
+ * the raw `FunctionDef`.
+ */
+export interface PrimitiveDurability {
+    durable: boolean;
+    memoizable: boolean;
+    costEstimateMs: number | undefined;
+}
+export declare class FunctionRegistry {
+    private map;
+    register<TArgs, TResult>(def: FunctionDef<TArgs, TResult>): void;
+    get(name: string): FunctionDef<unknown, unknown> | undefined;
+    has(name: string): boolean;
+    list(): string[];
+    /**
+     * Normalized durability metadata for a registered primitive. Returns
+     * `undefined` if the name is not registered. Default-falses apply so
+     * downstream code never has to repeat the `?? false` plumbing.
+     */
+    durability(name: string): PrimitiveDurability | undefined;
+    call(name: string, rawArgs: unknown, ctx: EvalCtx): Promise<Result<unknown, FunctionError>>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/functions/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/functions/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,KAAK,MAAM,EAAO,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAW7C,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAYD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAoCD,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;IAChF,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,GAAG,CAAoD;IAE/D,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI;IAwBhE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS;IAI5D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,IAAI,IAAI,MAAM,EAAE;IAIhB;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAUnD,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;CAkB3C"}

package/dist/functions/registry.js

@@ -0,0 +1,90 @@
+/**
+ * Function-library registry: typed `FunctionDef` + name-keyed dispatcher.
+ *
+ * Architecture (per `project_opensquid_modular_function_skill_separation`):
+ * the runtime ships atomic primitives (regex, state I/O, LLM calls, verdicts);
+ * skills compose them into rule processes via YAML. The registry is the ONLY
+ * path from a skill step to a primitive — no global `import { add }`
+ * shortcuts. The evaluator (Task 1.3) drives every call through `call()`.
+ *
+ * Each `FunctionDef` carries its own Zod arg schema. The registry validates
+ * args before invoking `execute`, so primitives see only well-typed input
+ * and never have to re-check what the YAML claimed it was passing.
+ *
+ * Error model: throws are reserved for programmer errors at startup
+ * (duplicate registration). Runtime failures travel as `Result<T, FunctionError>`
+ * — see `src/runtime/result.ts`. Primitives MUST NOT throw inside `execute`;
+ * the evaluator catches stray throws and wraps them in `{ kind: 'runtime' }`,
+ * but that path is for bugs, not for normal failure modes.
+ *
+ * Imports from: zod, runtime/types.ts, runtime/result.ts.
+ * Imported by: runtime/ (evaluator), packs/ (when skills resolve `function:` refs).
+ */
+import { err } from '../runtime/result.js';
+export class FunctionRegistry {
+    map = new Map();
+    register(def) {
+        if (this.map.has(def.name)) {
+            throw new Error(`Function "${def.name}" already registered`);
+        }
+        // DURABLE.2 — warn loudly when a primitive omits the durability flag.
+        // Default is `false` (cheap fail-safe), but silent default-false on a
+        // primitive that SHOULD be durable would double-charge on every resume
+        // (e.g. an llm_classify variant whose author forgot the flag). The
+        // warning surfaces the omission at registration time so audit catches
+        // it before it ships. `memoizable` is bundled into the same warning —
+        // either both flags are explicit or neither is, by author convention.
+        if (def.durable === undefined) {
+            console.warn(`[opensquid:registry] Primitive "${def.name}" registered without an ` +
+                `explicit \`durable\` flag — defaulting to \`false\`. Declare ` +
+                `\`durable: true | false\` on the FunctionDef to silence this warning.`);
+        }
+        // type-erasure cast: TArgs/TResult are existentially quantified in the
+        // registry's Map. Each entry knows its own schema at the value level
+        // (via def.argSchema), so we don't need TS to track them per entry.
+        this.map.set(def.name, def);
+    }
+    get(name) {
+        return this.map.get(name);
+    }
+    has(name) {
+        return this.map.has(name);
+    }
+    list() {
+        return [...this.map.keys()].sort();
+    }
+    /**
+     * Normalized durability metadata for a registered primitive. Returns
+     * `undefined` if the name is not registered. Default-falses apply so
+     * downstream code never has to repeat the `?? false` plumbing.
+     */
+    durability(name) {
+        const def = this.map.get(name);
+        if (!def)
+            return undefined;
+        return {
+            durable: def.durable ?? false,
+            memoizable: def.memoizable ?? false,
+            costEstimateMs: def.costEstimateMs,
+        };
+    }
+    async call(name, rawArgs, ctx) {
+        const def = this.map.get(name);
+        if (!def) {
+            return err({
+                kind: 'not_found',
+                message: `No function "${name}"`,
+            });
+        }
+        const parsed = def.argSchema.safeParse(rawArgs);
+        if (!parsed.success) {
+            return err({
+                kind: 'arg_invalid',
+                message: `Invalid args for "${name}": ${parsed.error.message}`,
+                cause: parsed.error,
+            });
+        }
+        return def.execute(parsed.data, ctx);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/functions/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/functions/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAe,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAsHxD,MAAM,OAAO,gBAAgB;IACnB,GAAG,GAAG,IAAI,GAAG,EAAyC,CAAC;IAE/D,QAAQ,CAAiB,GAAgC;QACvD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,IAAI,sBAAsB,CAAC,CAAC;QAC/D,CAAC;QACD,sEAAsE;QACtE,sEAAsE;QACtE,uEAAuE;QACvE,mEAAmE;QACnE,sEAAsE;QACtE,sEAAsE;QACtE,sEAAsE;QACtE,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CACV,mCAAmC,GAAG,CAAC,IAAI,0BAA0B;gBACnE,+DAA+D;gBAC/D,uEAAuE,CAC1E,CAAC;QACJ,CAAC;QACD,uEAAuE;QACvE,qEAAqE;QACrE,oEAAoE;QACpE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAoC,CAAC,CAAC;IAC/D,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAY;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK;YAC7B,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,KAAK;YACnC,cAAc,EAAE,GAAG,CAAC,cAAc;SACnC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI,CACR,IAAY,EACZ,OAAgB,EAChB,GAAY;QAEZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,GAAG,CAAgB;gBACxB,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,gBAAgB,IAAI,GAAG;aACjC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,GAAG,CAAgB;gBACxB,IAAI,EAAE,aAAa;gBACnB,OAAO,EAAE,qBAAqB,IAAI,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE;gBAC9D,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;CACF"}