@tangleai/agents 0.21.1 → 0.24.1

package/src/index.d.ts

@@ -1,11 +1,12 @@
-export type ProgramRunResult = import("./program-result.js").ProgramRunResult;
-export type ProgramAnswer = import("./program-result.js").ProgramAnswer;
-export type ProgramStepReport = import("./program-result.js").ProgramStepReport;
-export type ProgramDiagnostic = import("./program-result.js").ProgramDiagnostic;
-export { createProgramSession, questionFingerprint, DEFAULT_REUSE_THRESHOLD } from "./program-session.js";
-export { createToolbox, registerModelContext } from "./toolbox.js";
-export { createAgent, transcriptText } from "./agent.js";
-export { compileProgram, programGate, createProgramRunner, createProgramAuthor, ProgramError, PROGRAM_EXAMPLE, readProgramAnswer } from "./program.js";
-export { createLongHorizonAgent, createBudgetAccount, createTrajectory, resolveDepth, childScope, MAX_DEPTH, DEFAULT_DEPTH } from "./recursive.js";
-export { createRefiner, describeTrajectory } from "./refine.js";
-export { PROGRAM_SCHEMA, programSchema, PROGRAM_OPS, MAX_STEPS, MAX_PROGRAM_CHARS, NAME_PATTERN } from "./schemas/program.js";
+/** agents: public AI mechanisms over injected Jaren foundations. */
+export { createProgramSession, questionFingerprint, DEFAULT_REUSE_THRESHOLD } from './program-session.ts';
+export { createToolbox, registerModelContext } from './toolbox.ts';
+export { createAgent, transcriptText } from './agent.ts';
+export { compileProgram, programGate, createProgramRunner, createProgramAuthor, ProgramError, PROGRAM_EXAMPLE, readProgramAnswer } from './program.ts';
+export { createLongHorizonAgent, createBudgetAccount, createTrajectory, resolveDepth, childScope, MAX_DEPTH, DEFAULT_DEPTH } from './recursive.ts';
+export { createRefiner, describeTrajectory } from './refine.ts';
+export { PROGRAM_SCHEMA, programSchema, PROGRAM_OPS, MAX_STEPS, MAX_PROGRAM_CHARS, NAME_PATTERN } from './schemas/program.ts';
+export type ProgramRunResult = import('./program-result.ts').ProgramRunResult;
+export type ProgramAnswer = import('./program-result.ts').ProgramAnswer;
+export type ProgramStepReport = import('./program-result.ts').ProgramStepReport;
+export type ProgramDiagnostic = import('./program-result.ts').ProgramDiagnostic;

package/src/index.js

@@ -1,13 +1,8 @@
-//@ts-check
 /** agents: public AI mechanisms over injected Jaren foundations. */
-export { createProgramSession, questionFingerprint, DEFAULT_REUSE_THRESHOLD } from './program-session.js';
-export { createToolbox, registerModelContext } from './toolbox.js';
-export { createAgent, transcriptText } from './agent.js';
-export { compileProgram, programGate, createProgramRunner, createProgramAuthor, ProgramError, PROGRAM_EXAMPLE, readProgramAnswer } from './program.js';
-export { createLongHorizonAgent, createBudgetAccount, createTrajectory, resolveDepth, childScope, MAX_DEPTH, DEFAULT_DEPTH } from './recursive.js';
-export { createRefiner, describeTrajectory } from './refine.js';
-export { PROGRAM_SCHEMA, programSchema, PROGRAM_OPS, MAX_STEPS, MAX_PROGRAM_CHARS, NAME_PATTERN } from './schemas/program.js';
-/** @typedef {import('./program-result.js').ProgramRunResult} ProgramRunResult */
-/** @typedef {import('./program-result.js').ProgramAnswer} ProgramAnswer */
-/** @typedef {import('./program-result.js').ProgramStepReport} ProgramStepReport */
-/** @typedef {import('./program-result.js').ProgramDiagnostic} ProgramDiagnostic */
+export { createProgramSession, questionFingerprint, DEFAULT_REUSE_THRESHOLD } from "./program-session.js";
+export { createToolbox, registerModelContext } from "./toolbox.js";
+export { createAgent, transcriptText } from "./agent.js";
+export { compileProgram, programGate, createProgramRunner, createProgramAuthor, ProgramError, PROGRAM_EXAMPLE, readProgramAnswer } from "./program.js";
+export { createLongHorizonAgent, createBudgetAccount, createTrajectory, resolveDepth, childScope, MAX_DEPTH, DEFAULT_DEPTH } from "./recursive.js";
+export { createRefiner, describeTrajectory } from "./refine.js";
+export { PROGRAM_SCHEMA, programSchema, PROGRAM_OPS, MAX_STEPS, MAX_PROGRAM_CHARS, NAME_PATTERN } from "./schemas/program.js";

package/src/program-result.d.ts

@@ -1,32 +1,10 @@
 /** Public program results and bounded access to their stored answers. */
-/** @typedef {{ slot: string, size: number, text: string, truncated: boolean }} ProgramAnswer */
-/** @typedef {{ code: string, docPath: string, message: string }} ProgramDiagnostic */
-/** @typedef {(
- * { op: 'chunk', as: string, count: number, family: string } |
- * { op: 'grep', as: string, total: number, slots: number, size: number } |
- * { op: 'select', as: string, size: number, count?: number } |
- * { op: 'stat' | 'peek', as: string, size: number } |
- * { op: 'map', as: string, subcalls: number, failed: number, concurrency: number,
- *   skipped?: number, note?: string, stopped?: string } |
- * { op: 'reduce', as: string, over: number, size: number }
- * )} ProgramStepReport */
-/** @typedef {{ ran: number, steps: ProgramStepReport[], subcalls: number,
- * failed: number, concurrency: number, ms: number }} ProgramRunMetrics */
-/** @typedef {ProgramRunMetrics & (
- * { ok: true, answer: ProgramAnswer, error?: never, errors?: never, stopped?: never } |
- * { ok: false, answer: null, error: string, errors?: ProgramDiagnostic[], stopped?: string }
- * )} ProgramRunResult */
 /**
  * Read a complete answer through the owning environment's scoped ledger.
  * Check metadata before loading content, then check its actual length as well.
  * A missing, resized or oversized slot is a refusal, never a parsed preview.
- * @param {{ ledger: { getSlot: (name: string) => Promise<{ size: number } | null>,
- *   readSlot: (name: string) => Promise<unknown> } }} environment
- * @param {ProgramAnswer} answer
- * @param {{ maxChars: number }} options
- * @returns {Promise<{ ok: true, answer: ProgramAnswer } | { ok: false, error: string }>}
  */
-export function readProgramAnswer(environment: {
+export declare function readProgramAnswer(environment: {
     ledger: {
         getSlot: (name: string) => Promise<{
             size: number;
@@ -54,27 +32,27 @@ export type ProgramDiagnostic = {
     message: string;
 };
 export type ProgramStepReport = ({
-    op: "chunk";
+    op: 'chunk';
     as: string;
     count: number;
     family: string;
 } | {
-    op: "grep";
+    op: 'grep';
     as: string;
     total: number;
     slots: number;
     size: number;
 } | {
-    op: "select";
+    op: 'select';
     as: string;
     size: number;
     count?: number;
 } | {
-    op: "stat" | "peek";
+    op: 'stat' | 'peek';
     as: string;
     size: number;
 } | {
-    op: "map";
+    op: 'map';
     as: string;
     subcalls: number;
     failed: number;
@@ -83,7 +61,7 @@ export type ProgramStepReport = ({
     note?: string;
     stopped?: string;
 } | {
-    op: "reduce";
+    op: 'reduce';
     as: string;
     over: number;
     size: number;

package/src/program-result.js

@@ -1,48 +1,24 @@
-//@ts-check
 /** Public program results and bounded access to their stored answers. */
-
-/** @typedef {{ slot: string, size: number, text: string, truncated: boolean }} ProgramAnswer */
-/** @typedef {{ code: string, docPath: string, message: string }} ProgramDiagnostic */
-/** @typedef {(
- * { op: 'chunk', as: string, count: number, family: string } |
- * { op: 'grep', as: string, total: number, slots: number, size: number } |
- * { op: 'select', as: string, size: number, count?: number } |
- * { op: 'stat' | 'peek', as: string, size: number } |
- * { op: 'map', as: string, subcalls: number, failed: number, concurrency: number,
- *   skipped?: number, note?: string, stopped?: string } |
- * { op: 'reduce', as: string, over: number, size: number }
- * )} ProgramStepReport */
-/** @typedef {{ ran: number, steps: ProgramStepReport[], subcalls: number,
- * failed: number, concurrency: number, ms: number }} ProgramRunMetrics */
-/** @typedef {ProgramRunMetrics & (
- * { ok: true, answer: ProgramAnswer, error?: never, errors?: never, stopped?: never } |
- * { ok: false, answer: null, error: string, errors?: ProgramDiagnostic[], stopped?: string }
- * )} ProgramRunResult */
-
 /**
  * Read a complete answer through the owning environment's scoped ledger.
  * Check metadata before loading content, then check its actual length as well.
  * A missing, resized or oversized slot is a refusal, never a parsed preview.
- * @param {{ ledger: { getSlot: (name: string) => Promise<{ size: number } | null>,
- *   readSlot: (name: string) => Promise<unknown> } }} environment
- * @param {ProgramAnswer} answer
- * @param {{ maxChars: number }} options
- * @returns {Promise<{ ok: true, answer: ProgramAnswer } | { ok: false, error: string }>}
  */
 export async function readProgramAnswer(environment, answer, options) {
-  const maxChars = options.maxChars;
-  if (!Number.isSafeInteger(maxChars) || maxChars < 1)
-    throw new RangeError('maxChars must be a positive safe integer');
-  if (!answer || typeof answer.slot !== 'string' || !Number.isSafeInteger(answer.size) || answer.size < 0)
-    return { ok: false, error: 'the program answer has invalid slot metadata' };
-  if (answer.size > maxChars)
-    return { ok: false, error: `the program answer exceeds the ${maxChars} character limit` };
-  const slot = await environment.ledger.getSlot(answer.slot);
-  if (slot === null) return { ok: false, error: `no answer slot '${answer.slot}'` };
-  if (slot.size !== answer.size)
-    return { ok: false, error: `answer slot '${answer.slot}' changed size since the program ran` };
-  const raw = await environment.ledger.readSlot(answer.slot);
-  if (typeof raw !== 'string' || raw.length !== answer.size || raw.length > maxChars)
-    return { ok: false, error: `answer slot '${answer.slot}' no longer matches its bounded size` };
-  return { ok: true, answer: { slot: answer.slot, size: raw.length, text: raw, truncated: false } };
+    const maxChars = options.maxChars;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 1)
+        throw new RangeError('maxChars must be a positive safe integer');
+    if (!answer || typeof answer.slot !== 'string' || !Number.isSafeInteger(answer.size) || answer.size < 0)
+        return { ok: false, error: 'the program answer has invalid slot metadata' };
+    if (answer.size > maxChars)
+        return { ok: false, error: `the program answer exceeds the ${maxChars} character limit` };
+    const slot = await environment.ledger.getSlot(answer.slot);
+    if (slot === null)
+        return { ok: false, error: `no answer slot '${answer.slot}'` };
+    if (slot.size !== answer.size)
+        return { ok: false, error: `answer slot '${answer.slot}' changed size since the program ran` };
+    const raw = await environment.ledger.readSlot(answer.slot);
+    if (typeof raw !== 'string' || raw.length !== answer.size || raw.length > maxChars)
+        return { ok: false, error: `answer slot '${answer.slot}' no longer matches its bounded size` };
+    return { ok: true, answer: { slot: answer.slot, size: raw.length, text: raw, truncated: false } };
 }

package/src/program-session.d.ts

@@ -1,18 +1,14 @@
+/** The fixture frontier requires an outcome checker; hosts must remeasure other embedders. */
+export declare const DEFAULT_REUSE_THRESHOLD = 0.9;
 /** Hash the exact question; case and whitespace may be meaningful inside record keys.
- * @param {string} question */
-export function questionFingerprint(question: string): Promise<string>;
+ * @param question */
+export declare function questionFingerprint(question: string): Promise<string>;
 /** Compose author and runner with one fresh fallback and append-only failure evidence.
  * `check` is required when reuse is enabled, including the first successful stored run.
  * `accept` proves suitability before a paraphrase executes; an identical fingerprint
  * under the same host environment identity needs no separate suitability hook.
- * @param {{ environment: any, client?: any, compileQuery?: any, createStructuredOutput?: any,
- *   querySchema?: any, maxRepairs?: number, system?: string, recursive?: boolean,
- *   analyzeQuery?: any, annotateTypes?: any, selectModel?: any, limits?: any, onRoute?: any,
- *   depth?: number, account?: any, maxSubcalls?: number, maxConcurrentSubcalls?: number,
- *   reuse?: { environmentId: string, schemaVersion: string, threshold?: number,
- *   tools?: string[], embedder?: any, check: (context: any) => any,
- *   accept?: (context: any) => any }, author?: any, runner?: any }} options */
-export function createProgramSession(options: {
+ * @param options */
+export declare function createProgramSession(options: {
     environment: any;
     client?: any;
     compileQuery?: any;
@@ -42,7 +38,5 @@ export function createProgramSession(options: {
     author?: any;
     runner?: any;
 }): {
-    run(question: any, hooks?: {}): Promise<any>;
+    run(question: any, hooks?: Record<string, any>): Promise<any>;
 };
-/** The fixture frontier requires an outcome checker; hosts must remeasure other embedders. */
-export const DEFAULT_REUSE_THRESHOLD: 0.9;

package/src/program-session.js

@@ -1,121 +1,143 @@
-//@ts-check
 /** Verified, opt-in reuse. Retrieval proposes; the host and current compiler decide. */
-import { createProgramAuthor, createProgramRunner, programGate } from './program.js';
+import { createProgramAuthor, createProgramRunner, programGate } from "./program.js";
 import { checkOutcome } from '@jarenjs/core/check';
-
 /** The fixture frontier requires an outcome checker; hosts must remeasure other embedders. */
 export const DEFAULT_REUSE_THRESHOLD = 0.9;
-
 /** Hash the exact question; case and whitespace may be meaningful inside record keys.
- * @param {string} question */
+ * @param question */
 export async function questionFingerprint(question) {
-  const bytes = new TextEncoder().encode(question);
-  const hash = await globalThis.crypto.subtle.digest('SHA-256', bytes);
-  return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    const bytes = new TextEncoder().encode(question);
+    const hash = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, '0')).join('');
 }
-
 /** Compose author and runner with one fresh fallback and append-only failure evidence.
  * `check` is required when reuse is enabled, including the first successful stored run.
  * `accept` proves suitability before a paraphrase executes; an identical fingerprint
  * under the same host environment identity needs no separate suitability hook.
- * @param {{ environment: any, client?: any, compileQuery?: any, createStructuredOutput?: any,
- *   querySchema?: any, maxRepairs?: number, system?: string, recursive?: boolean,
- *   analyzeQuery?: any, annotateTypes?: any, selectModel?: any, limits?: any, onRoute?: any,
- *   depth?: number, account?: any, maxSubcalls?: number, maxConcurrentSubcalls?: number,
- *   reuse?: { environmentId: string, schemaVersion: string, threshold?: number,
- *   tools?: string[], embedder?: any, check: (context: any) => any,
- *   accept?: (context: any) => any }, author?: any, runner?: any }} options */
+ * @param options */
 export function createProgramSession(options) {
-  const author = options.author ?? createProgramAuthor(options);
-  const runner = options.runner ?? createProgramRunner(options);
-  const policy = options.reuse;
-  if (policy !== undefined && (typeof policy.check !== 'function'
-    || !policy.environmentId || !policy.schemaVersion))
-    throw new TypeError('program reuse needs environmentId, schemaVersion and an outcome check');
-  const threshold = policy?.threshold ?? DEFAULT_REUSE_THRESHOLD;
-  if (!Number.isFinite(threshold) || threshold < -1 || threshold > 1)
-    throw new TypeError('reuse threshold must be finite and between -1 and 1');
-  const ledger = options.environment.ledger;
-
-  return {
-    async run(question, hooks = {}) {
-      const events = [];
-      const fingerprint = policy ? await questionFingerprint(question) : null;
-      const tools = [...(policy?.tools ?? [])].sort();
-      let candidate = null;
-      let attempts = 0;
-      const failed = async (skill, reason) => {
-        events.push({ kind: 'rejected', skill: skill.id, reason });
-        const evidence = await ledger.addMemory({ text: `Program reuse failed: ${reason}`,
-          evidence: `skill:${skill.id}; question:${fingerprint}`, tags: ['program-reuse-failure'] });
-        if (evidence.error) events.push({ kind: 'storage-error', operation: 'failure-evidence' });
-      };
-      if (policy && !hooks.signal?.aborted) {
-        const recalled = await ledger.recallSkills({ near: question, limit: 5, minScore: threshold });
-        events.push({ kind: 'retrieval', error: recalled.error ?? null });
-        for (const [index, skill] of (recalled.skills ?? []).entries()) {
-          const stored = skill.program;
-          if (!stored) continue;
-          const reason = stored.version !== 1 || stored.schemaVersion !== policy.schemaVersion ? 'schema-drift'
-            : stored.environmentId !== policy.environmentId ? 'environment-drift'
-              : JSON.stringify([...skill.tools].sort()) !== JSON.stringify(tools) ? 'tool-drift'
-                : stored.checked !== true ? 'missing-success' : null;
-          if (reason) { await failed(skill, reason); continue; }
-          // A returned metadata record is mutable in some storage adapters. Validate
-          // and compile it again rather than trusting a past compiler or cached closure.
-          const names = (await ledger.listSlots()).map((slot) => slot.name);
-          const gate = programGate({ compileQuery: options.compileQuery, known: names,
-            recursive: options.recursive, analyzeQuery: options.analyzeQuery, annotateTypes: options.annotateTypes })(stored.document);
-          if (gate !== true) { await failed(skill, 'compile-gate'); continue; }
-          let suitable = stored.fingerprint === fingerprint;
-          if (!suitable && policy.accept) {
-            try { suitable = await policy.accept({ question, skill, score: recalled.scores[index] }) === true; }
-            catch { suitable = false; }
-          }
-          if (!suitable) { await failed(skill, 'unsuitable'); continue; }
-          candidate = skill;
-          break;
-        }
-      }
-      if (candidate) {
-        const result = await runner.run(candidate.program.document, hooks);
-        let accepted = false;
-        if (result.ok) {
-          try { accepted = checkOutcome(await policy.check({ question, result, reused: true })).valid; }
-          catch { /* A checker exception is a failed reuse, never implicit success. */ }
-        }
-        if (accepted) {
-          events.push({ kind: 'reused', skill: candidate.id });
-          return { ...result, program: candidate.program.document, reuse: { reused: true, authorCalls: 0, fallback: false, events } };
-        }
-        await failed(candidate, result.ok ? 'wrong-outcome' : 'execution-failed');
-      }
-      if (hooks.signal?.aborted) return { ok: false, stopped: 'aborted', reuse: { reused: false, authorCalls: 0, events } };
-      const authored = await author.author(question, hooks);
-      attempts += authored.attempts ?? 1;
-      const reuse = { reused: false, authorCalls: attempts, fallback: candidate !== null || events.some((event) => event.kind === 'rejected'), events };
-      if (authored.value === undefined) return { ok: false, errors: authored.errors, reuse };
-      const result = await runner.run(authored.value, hooks);
-      if (!policy || !result.ok) return { ...result, program: authored.value, reuse };
-      let checked = false;
-      try { checked = checkOutcome(await policy.check({ question, result, reused: false })).valid; }
-      catch { /* A failed fresh check ends this request; fallback never loops. */ }
-      if (!checked) return { ...result, ok: false, error: 'fresh program failed outcome check', reuse };
-      let pair = {};
-      if (policy.embedder) {
-        try {
-          const [vector] = await policy.embedder.embed([question], { signal: hooks.signal });
-          pair = { embedding: Array.from(vector), embeddedBy: { model: policy.embedder.model, dims: policy.embedder.dims } };
-        }
-        catch { events.push({ kind: 'embedding-failed' }); }
-      }
-      const saved = await ledger.addSkill({ name: 'Verified program', when: question,
-        instructions: 'Run the verified program after checking its requirements.', tools, ...pair,
-        program: { version: 1, question, fingerprint, environmentId: policy.environmentId,
-          schemaVersion: policy.schemaVersion, document: authored.value,
-          evidence: `outcome-check:${fingerprint}`, checked: true } });
-      events.push(saved.error ? { kind: 'storage-error', operation: 'successful-program' } : { kind: 'stored', skill: saved.id });
-      return { ...result, program: authored.value, reuse };
-    },
-  };
+    const author = options.author ?? createProgramAuthor({ ...options, client: options.client, createStructuredOutput: options.createStructuredOutput });
+    const runner = options.runner ?? createProgramRunner(options);
+    const policy = options.reuse;
+    if (policy !== undefined && (typeof policy.check !== 'function'
+        || !policy.environmentId || !policy.schemaVersion))
+        throw new TypeError('program reuse needs environmentId, schemaVersion and an outcome check');
+    const threshold = policy?.threshold ?? DEFAULT_REUSE_THRESHOLD;
+    if (!Number.isFinite(threshold) || threshold < -1 || threshold > 1)
+        throw new TypeError('reuse threshold must be finite and between -1 and 1');
+    const ledger = options.environment.ledger;
+    return {
+        async run(question, hooks = {}) {
+            const events = [];
+            const fingerprint = policy ? await questionFingerprint(question) : null;
+            const tools = [...(policy?.tools ?? [])].sort();
+            let candidate = null;
+            let attempts = 0;
+            const failed = async (skill, reason) => {
+                events.push({ kind: 'rejected', skill: skill.id, reason });
+                const evidence = await ledger.addMemory({
+                    text: `Program reuse failed: ${reason}`,
+                    evidence: `skill:${skill.id}; question:${fingerprint}`, tags: ['program-reuse-failure']
+                });
+                if (evidence.error)
+                    events.push({ kind: 'storage-error', operation: 'failure-evidence' });
+            };
+            if (policy && !hooks.signal?.aborted) {
+                const recalled = await ledger.recallSkills({ near: question, limit: 5, minScore: threshold });
+                events.push({ kind: 'retrieval', error: recalled.error ?? null });
+                for (const [index, skill] of (recalled.skills ?? []).entries()) {
+                    const stored = skill.program;
+                    if (!stored)
+                        continue;
+                    const reason = stored.version !== 1 || stored.schemaVersion !== policy.schemaVersion ? 'schema-drift'
+                        : stored.environmentId !== policy.environmentId ? 'environment-drift'
+                            : JSON.stringify([...skill.tools].sort()) !== JSON.stringify(tools) ? 'tool-drift'
+                                : stored.checked !== true ? 'missing-success' : null;
+                    if (reason) {
+                        await failed(skill, reason);
+                        continue;
+                    }
+                    // A returned metadata record is mutable in some storage adapters. Validate
+                    // and compile it again rather than trusting a past compiler or cached closure.
+                    const names = (await ledger.listSlots()).map((slot) => slot.name);
+                    const gate = programGate({
+                        compileQuery: options.compileQuery, known: names,
+                        recursive: options.recursive, analyzeQuery: options.analyzeQuery, annotateTypes: options.annotateTypes
+                    })(stored.document);
+                    if (gate !== true) {
+                        await failed(skill, 'compile-gate');
+                        continue;
+                    }
+                    let suitable = stored.fingerprint === fingerprint;
+                    if (!suitable && policy.accept) {
+                        try {
+                            suitable = await policy.accept({ question, skill, score: recalled.scores[index] }) === true;
+                        }
+                        catch {
+                            suitable = false;
+                        }
+                    }
+                    if (!suitable) {
+                        await failed(skill, 'unsuitable');
+                        continue;
+                    }
+                    candidate = skill;
+                    break;
+                }
+            }
+            if (candidate) {
+                const result = await runner.run(candidate.program.document, hooks);
+                let accepted = false;
+                if (result.ok) {
+                    try {
+                        accepted = checkOutcome(await policy.check({ question, result, reused: true })).valid;
+                    }
+                    catch { /* A checker exception is a failed reuse, never implicit success. */ }
+                }
+                if (accepted) {
+                    events.push({ kind: 'reused', skill: candidate.id });
+                    return { ...result, program: candidate.program.document, reuse: { reused: true, authorCalls: 0, fallback: false, events } };
+                }
+                await failed(candidate, result.ok ? 'wrong-outcome' : 'execution-failed');
+            }
+            if (hooks.signal?.aborted)
+                return { ok: false, stopped: 'aborted', reuse: { reused: false, authorCalls: 0, events } };
+            const authored = await author.author(question, hooks);
+            attempts += authored.attempts ?? 1;
+            const reuse = { reused: false, authorCalls: attempts, fallback: candidate !== null || events.some((event) => event.kind === 'rejected'), events };
+            if (authored.value === undefined)
+                return { ok: false, errors: authored.errors, reuse };
+            const result = await runner.run(authored.value, hooks);
+            if (!policy || !result.ok)
+                return { ...result, program: authored.value, reuse };
+            let checked = false;
+            try {
+                checked = checkOutcome(await policy.check({ question, result, reused: false })).valid;
+            }
+            catch { /* A failed fresh check ends this request; fallback never loops. */ }
+            if (!checked)
+                return { ...result, ok: false, error: 'fresh program failed outcome check', reuse };
+            let pair = {};
+            if (policy.embedder) {
+                try {
+                    const [vector] = await policy.embedder.embed([question], { signal: hooks.signal });
+                    pair = { embedding: Array.from(vector), embeddedBy: { model: policy.embedder.model, dims: policy.embedder.dims } };
+                }
+                catch {
+                    events.push({ kind: 'embedding-failed' });
+                }
+            }
+            const saved = await ledger.addSkill({
+                name: 'Verified program', when: question,
+                instructions: 'Run the verified program after checking its requirements.', tools, ...pair,
+                program: {
+                    version: 1, question, fingerprint, environmentId: policy.environmentId,
+                    schemaVersion: policy.schemaVersion, document: authored.value,
+                    evidence: `outcome-check:${fingerprint}`, checked: true
+                }
+            });
+            events.push(saved.error ? { kind: 'storage-error', operation: 'successful-program' } : { kind: 'stored', skill: saved.id });
+            return { ...result, program: authored.value, reuse };
+        },
+    };
 }

package/src/program-shape.d.ts

@@ -1,21 +1,21 @@
+/** Recursive answers carry the same envelope as map elements. Query engines stay injected. */
+export declare const RECURSIVE_ITEM_SCHEMA: {
+    type: string;
+    properties: {
+        slot: {
+            type: string;
+        };
+        value: {};
+    };
+    required: string[];
+};
 /** Query singleton normalization: empty sequence, one item, or several items.
- * @param {any} value */
-export function recursiveItems(value: any): any[];
+ * @param value */
+export declare function recursiveItems(value: any): any[] | null;
 /** Conservatively prove a declared item/sequence schema. Unknown schema keywords
  * never manufacture required properties. Runtime validation enforces the full declaration.
- * @param {any} schema @param {boolean} [item] @returns {boolean} */
-export function recursiveSchema(schema: any, item?: boolean): boolean;
+ * @param schema @param [item] @returns */
+export declare function recursiveSchema(schema: any, item?: boolean): boolean;
 /** Three-valued structural proof over the existing annotated query AST.
- * @param {any} node @param {boolean} [item] @returns {'compatible'|'incompatible'|'unknown'} */
-export function recursiveShape(node: any, item?: boolean): "compatible" | "incompatible" | "unknown";
-export namespace RECURSIVE_ITEM_SCHEMA {
-    let type: string;
-    namespace properties {
-        namespace slot {
-            let type_1: string;
-            export { type_1 as type };
-        }
-        let value: {};
-    }
-    let required: string[];
-}
+ * @param node @param [item] @returns */
+export declare function recursiveShape(node: any, item?: boolean): 'compatible' | 'incompatible' | 'unknown';