@alisio/core 0.6.0 → 0.8.0

package/dist/proof/verify.js

@@ -0,0 +1,171 @@
+/**
+ * Running a verifier on demand (specs/011 3.1, 3.8). This is a USER-side entry point: no tool
+ * exposes it to the model, so the model can neither start a verification nor choose its verdict.
+ *
+ * - `file`, `data-check` and (opt-in) `coverage` run their canonical core tool call (`verifierCall`) as a real run
+ *   under the normal gate; the recorder captures the evidence from the raw result like it does
+ *   for a call the model made (D3, D6).
+ * - `plugin` runs the registered verifier. Its calls go through `callTool` (the same gate), the
+ *   result must carry referenceable evidence, and anything else degrades the criterion to
+ *   `manual_review` (an evidence of kind `manual`). A verifier that throws or hangs proves
+ *   nothing: the criterion stays as it was and the outcome says why.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { redactOutput } from "../eval/secrets.js";
+import { excerptOf } from "./recorder.js";
+import { treeFingerprint } from "./tree.js";
+import { verifierCall } from "./verifiers.js";
+const PLUGIN_TIMEOUT_MS = 60_000;
+const HEX_SHA256 = /^[0-9a-f]{64}$/i;
+const DETAIL_MAX = 200;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+function describeError(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return redactOutput(text).slice(0, DETAIL_MAX);
+}
+export async function verifyCriterion(deps, request) {
+    const { criterionId, sessionId } = request;
+    const statusOf = () => {
+        const ledger = deps.store.ledger(sessionId, (deps.now?.() ?? new Date()).toISOString());
+        const criterion = ledger.criteria.find((c) => c.criterionId === criterionId);
+        return { status: criterion?.status ?? "not_checked" };
+    };
+    const outcome = (reason, detail, evidenceId) => ({
+        criterionId,
+        ...statusOf(),
+        ...(evidenceId ? { evidenceId } : {}),
+        ...(reason ? { reason } : {}),
+        ...(detail ? { detail } : {}),
+    });
+    const record = deps.store.criterion(criterionId);
+    if (!record || record.sessionId !== sessionId)
+        return outcome("unknown_criterion");
+    if (record.notApplicableReason)
+        return outcome("not_applicable");
+    const verifier = record.verifier;
+    if (!verifier)
+        return outcome("no_verifier");
+    const signal = request.signal ?? new AbortController().signal;
+    if (verifier.kind === "coverage" && deps.coverage?.() !== true)
+        return outcome("coverage_disabled", "proof.coverage.enabled is false");
+    if (verifier.kind === "file" || verifier.kind === "data-check" || verifier.kind === "coverage") {
+        const call = verifierCall(verifier);
+        if (!call)
+            return outcome("unverifiable_spec");
+        let done;
+        try {
+            done = await deps.callTool(sessionId, call.name, call.input, signal);
+        }
+        catch (error) {
+            return outcome("verifier_failed", describeError(error));
+        }
+        const evidence = deps.store
+            .ledger(sessionId)
+            .evidence.find((e) => e.criterionId === criterionId && e.callId === done.callId);
+        return evidence ? outcome(undefined, undefined, evidence.evidenceId) : outcome("no_evidence");
+    }
+    if (verifier.kind === "plugin") {
+        const entry = deps.registry.get(verifier.verifierId);
+        if (!entry)
+            return outcome("verifier_unavailable");
+        const started = Date.now();
+        const timeout = AbortSignal.timeout(deps.timeoutMs ?? PLUGIN_TIMEOUT_MS);
+        const combined = AbortSignal.any([signal, timeout]);
+        const context = {
+            sessionId,
+            criterionId,
+            workspace: request.workspace,
+            signal: combined,
+            callTool: async (name, input) => {
+                const { callId, result } = await deps.callTool(sessionId, name, input, combined);
+                return { callId, result };
+            },
+        };
+        let result;
+        try {
+            result = await raceAbort(entry.verifier.run(verifier.input, context), combined);
+        }
+        catch (error) {
+            return outcome("verifier_failed", describeError(error));
+        }
+        const durationMs = Date.now() - started;
+        const checked = referenceable(result, deps.db, sessionId);
+        const filesTouched = deps.store.edits(sessionId).map((e) => e.path);
+        const base = {
+            criterionId,
+            durationMs,
+            treeFingerprint: treeFingerprint(request.workspace, filesTouched),
+            filesTouched,
+            capturedAt: (deps.now?.() ?? new Date()).toISOString(),
+        };
+        if (checked) {
+            const excerpt = typeof checked.excerpt === "string" ? excerptOf(checked.excerpt) : undefined;
+            const evidence = deps.store.appendEvidence({
+                ...base,
+                verifierKind: "plugin",
+                runId: checked.runId,
+                callId: checked.callId,
+                ok: checked.ok,
+                outputHash: checked.outputHash,
+                ...(excerpt ? { excerpt } : {}),
+            });
+            return outcome(undefined, undefined, evidence.evidenceId);
+        }
+        const why = `verifier ${verifier.verifierId} returned no traceable evidence`;
+        const evidence = deps.store.appendEvidence({
+            ...base,
+            verifierKind: "manual",
+            runId: `verify_${randomUUID()}`,
+            callId: `verify_${randomUUID()}`,
+            ok: false,
+            outputHash: sha256(why),
+            excerpt: why,
+        });
+        return outcome("no_referenceable_evidence", undefined, evidence.evidenceId);
+    }
+    return outcome("unsupported_verifier");
+}
+/** Rejects as soon as `signal` aborts, even when the verifier ignores it. */
+function raceAbort(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("aborted"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason ?? new Error("aborted"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        work.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+/**
+ * A plugin result is evidence only with a boolean verdict and a sha256 `outputHash`; a `callId`
+ * must name a call this session journaled (its run id is then the real one). Without a callId the
+ * host mints a verification id: the evidence is then the plugin's word plus the hash.
+ */
+function referenceable(result, db, sessionId) {
+    if (typeof result !== "object" || result === null)
+        return undefined;
+    const r = result;
+    if (typeof r.ok !== "boolean")
+        return undefined;
+    if (typeof r.outputHash !== "string" || !HEX_SHA256.test(r.outputHash))
+        return undefined;
+    const base = {
+        ok: r.ok,
+        outputHash: r.outputHash.toLowerCase(),
+        ...(typeof r.excerpt === "string" ? { excerpt: r.excerpt } : {}),
+    };
+    if (r.callId === undefined)
+        return { ...base, runId: `verify_${randomUUID()}`, callId: `verify_${randomUUID()}` };
+    if (typeof r.callId !== "string" || !r.callId)
+        return undefined;
+    const row = db
+        .prepare("SELECT run_id FROM tool_calls WHERE session=? AND call_id=?")
+        .get(sessionId, r.callId);
+    const runId = row ? String(row.run_id ?? "") : "";
+    return runId ? { ...base, callId: r.callId, runId } : undefined;
+}

package/dist/runtime/ids.d.ts

@@ -6,3 +6,24 @@
 export declare function ulid(now?: number): string;
 /** A prefixed id such as `art_01J…` or `exec_01J…`. */
 export declare const newId: (prefix: string, now?: number) => string;
+/**
+ * A replacement for the random identifiers the runtime generates (session ids, plan ids, forge
+ * execution ids, `ulid`-based ids). The reliability lab installs a seeded one while it records or
+ * replays a cassette so the requests a run sends do not depend on fresh randomness. Nothing
+ * installs one in normal use, and then every function here behaves exactly as before.
+ */
+export interface IdSource {
+    /** A UUID (the shape of `crypto.randomUUID()`). */
+    uuid(): string;
+    /** The 26-character body of a `ulid` (the argument is the caller's clock, which a source may ignore). */
+    ulid(now?: number): string;
+}
+/** Installs (or, with `undefined`, removes) the process-wide id source. */
+export declare function setIdSource(source?: IdSource): void;
+/** A random v4 UUID, or the next one of the installed id source. */
+export declare const newUuid: () => string;
+/**
+ * A deterministic source: the n-th UUID (and the n-th ULID) depends only on `seed`. UUIDs are
+ * v4-shaped; ULIDs carry a counter in their time part, so they stay sortable by creation order.
+ */
+export declare function seededIdSource(seed: string): IdSource;

package/dist/runtime/ids.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 /** Crockford base32 (no I, L, O, U), the ULID alphabet. */
 const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 /**
@@ -7,6 +7,8 @@ const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
  * millisecond sort arbitrarily, which is fine for row ids and folder names.
  */
 export function ulid(now = Date.now()) {
+    if (installed)
+        return installed.ulid(now);
     let time = "";
     let t = Math.max(0, Math.floor(now));
     for (let i = 0; i < 10; i++) {
@@ -30,3 +32,41 @@ export function ulid(now = Date.now()) {
 }
 /** A prefixed id such as `art_01J…` or `exec_01J…`. */
 export const newId = (prefix, now) => `${prefix}_${ulid(now)}`;
+let installed;
+/** Installs (or, with `undefined`, removes) the process-wide id source. */
+export function setIdSource(source) {
+    installed = source;
+}
+/** A random v4 UUID, or the next one of the installed id source. */
+export const newUuid = () => (installed ? installed.uuid() : randomUUID());
+/**
+ * A deterministic source: the n-th UUID (and the n-th ULID) depends only on `seed`. UUIDs are
+ * v4-shaped; ULIDs carry a counter in their time part, so they stay sortable by creation order.
+ */
+export function seededIdSource(seed) {
+    let uuids = 0;
+    let ulids = 0;
+    const digest = (kind, n) => createHash("sha256").update(`${seed}\0${kind}\0${n}`).digest();
+    return {
+        uuid() {
+            const bytes = digest("uuid", uuids++).subarray(0, 16);
+            bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+            bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+            const hex = bytes.toString("hex");
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+        },
+        ulid() {
+            let time = "";
+            let t = ulids;
+            for (let i = 0; i < 10; i++) {
+                time = (ALPHABET[t % 32] ?? "0") + time;
+                t = Math.floor(t / 32);
+            }
+            const bytes = digest("ulid", ulids++);
+            let random = "";
+            for (let i = 0; i < 16; i++)
+                random += ALPHABET[(bytes[i] ?? 0) & 31];
+            return time + random;
+        },
+    };
+}

package/dist/runtime/store.js

@@ -1,4 +1,5 @@
 import { textResult, } from "@alisio/sdk";
+import { newUuid } from "./ids.js";
 import { isProcessAlive } from "./process.js";
 import { openDatabase } from "./sqlite.js";
 const alive = isProcessAlive;
@@ -311,6 +312,66 @@ export class SQLiteStore {
                 this.db.exec("PRAGMA foreign_keys=ON");
             }
         }
+        if (!has(11))
+            this.db.transaction(() => {
+                // v11: the Proof ledger (specs/011). Criteria and evidence die with their session;
+                // evidence is append-only (the trigger rejects UPDATE). The status is never stored.
+                this.db.exec(`
+          CREATE TABLE IF NOT EXISTS proof_criteria(
+            criterion_id TEXT PRIMARY KEY,
+            session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+            goal_id TEXT,
+            text TEXT NOT NULL,
+            required INTEGER NOT NULL DEFAULT 0,
+            origin TEXT NOT NULL,
+            verifier_json TEXT,
+            scope_json TEXT,
+            na_reason TEXT,
+            created_at INTEGER NOT NULL);
+          CREATE INDEX IF NOT EXISTS proof_criteria_session ON proof_criteria(session_id, created_at);
+          CREATE TABLE IF NOT EXISTS proof_evidence(
+            evidence_id TEXT PRIMARY KEY,
+            criterion_id TEXT NOT NULL REFERENCES proof_criteria(criterion_id) ON DELETE CASCADE,
+            run_id TEXT NOT NULL,
+            call_id TEXT NOT NULL,
+            ok INTEGER NOT NULL,
+            verifier_kind TEXT NOT NULL,
+            fingerprint TEXT,
+            exit_code INTEGER,
+            duration_ms INTEGER NOT NULL,
+            output_hash TEXT NOT NULL,
+            excerpt TEXT,
+            tree_fingerprint TEXT NOT NULL,
+            files_json TEXT NOT NULL,
+            captured_at TEXT NOT NULL);
+          CREATE INDEX IF NOT EXISTS proof_evidence_criterion ON proof_evidence(criterion_id);
+          CREATE TRIGGER IF NOT EXISTS proof_evidence_append_only
+            BEFORE UPDATE ON proof_evidence
+            BEGIN SELECT RAISE(ABORT, 'proof_evidence is append-only'); END;
+          INSERT OR IGNORE INTO schema_migrations VALUES(11);`);
+            });
+        if (!has(12))
+            this.db.transaction(() => {
+                // v12: the newest successful write_file/edit_file per path for sessions with Proof
+                // criteria (specs/011 3.4, D5). One row per path keeps it bounded; it dies with the session.
+                this.db.exec(`
+          CREATE TABLE IF NOT EXISTS proof_edits(
+            session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+            path TEXT NOT NULL,
+            edited_at TEXT NOT NULL,
+            PRIMARY KEY(session_id, path));
+          INSERT OR IGNORE INTO schema_migrations VALUES(12);`);
+            });
+        if (!has(13))
+            this.db.transaction(() => {
+                // v13 (additive): the Proof snapshot a completed goal keeps (specs/011 3.6, O6): which
+                // required criteria were unmet and the user's override reason, as JSON. Old binaries
+                // ignore the column; goals without criteria keep it NULL.
+                const columns = new Set(this.db.prepare("PRAGMA table_info(session_goals)").all().map((c) => c.name));
+                if (!columns.has("proof_json"))
+                    this.db.exec("ALTER TABLE session_goals ADD COLUMN proof_json TEXT");
+                this.db.exec("INSERT OR IGNORE INTO schema_migrations VALUES(13);");
+            });
     }
     /**
      * The root of a session (itself for roots), following `parent_id`. Unknown ids are their own
@@ -327,7 +388,7 @@ export class SQLiteStore {
         return current;
     }
     create(workspace, provider, model) {
-        const id = crypto.randomUUID();
+        const id = newUuid();
         const now = Date.now();
         this.db
             .prepare("INSERT INTO sessions(id,workspace,provider,model,created_at,updated_at) VALUES(?,?,?,?,?,?)")
@@ -367,7 +428,7 @@ export class SQLiteStore {
             .map((r) => this.row(r));
     }
     createChild(record) {
-        const id = record.id ?? crypto.randomUUID();
+        const id = record.id ?? newUuid();
         const now = Date.now();
         this.db
             .prepare(`INSERT INTO sessions(id,workspace,provider,model,parent_id,depth,agent,status,title,usage,options,created_at,updated_at)

package/dist/tools/goal.d.ts

@@ -12,7 +12,11 @@ import type { ToolRegistry } from "../core/registry.ts";
 import type { GoalService } from "../goal/service.ts";
 export declare const GET_GOAL_TOOL = "get_goal";
 export declare const UPDATE_GOAL_TOOL = "update_goal";
-/** Parses the evidence list defensively (the schema is advisory for some providers). */
+/**
+ * Parses the evidence list defensively (the schema is advisory for some providers). An optional
+ * `evidenceId` is kept as declared here; the goal service later drops every id that does not
+ * resolve to captured evidence of the session (the declaration is then plain text).
+ */
 export declare function parseEvidence(raw: unknown): GoalEvidence[] | string;
 export declare function registerGoalTools(registry: ToolRegistry, deps: {
     goals: GoalService;

package/dist/tools/goal.js

@@ -35,7 +35,13 @@ function brief(goal) {
         max_minutes: Math.round(goal.maxWallMs / 60_000),
     };
 }
-/** Parses the evidence list defensively (the schema is advisory for some providers). */
+const MAX_EVIDENCE_ID = 100;
+const MAX_UNMET_LISTED = 20;
+/**
+ * Parses the evidence list defensively (the schema is advisory for some providers). An optional
+ * `evidenceId` is kept as declared here; the goal service later drops every id that does not
+ * resolve to captured evidence of the session (the declaration is then plain text).
+ */
 export function parseEvidence(raw) {
     if (!Array.isArray(raw) || !raw.length)
         return "evidence must list at least one item.";
@@ -48,7 +54,12 @@ export function parseEvidence(raw) {
         if (!detail)
             return "every evidence item needs a detail (a path, a test name, a log line).";
         const kind = KINDS.find((candidate) => candidate === item.kind) ?? "other";
-        items.push({ kind, detail: detail.slice(0, MAX_DETAIL) });
+        const evidenceId = typeof item?.evidenceId === "string" ? item.evidenceId.trim() : "";
+        items.push({
+            kind,
+            detail: detail.slice(0, MAX_DETAIL),
+            ...(evidenceId && evidenceId.length <= MAX_EVIDENCE_ID ? { evidenceId } : {}),
+        });
     }
     return items;
 }
@@ -85,7 +96,15 @@ export function registerGoalTools(registry, deps) {
                 type: "array",
                 minItems: 1,
                 maxItems: MAX_EVIDENCE,
-                items: objectSchema({ kind: { enum: [...KINDS] }, detail: { type: "string", maxLength: MAX_DETAIL } }, ["kind", "detail"]),
+                items: objectSchema({
+                    kind: { enum: [...KINDS] },
+                    detail: { type: "string", maxLength: MAX_DETAIL },
+                    evidenceId: {
+                        type: "string",
+                        maxLength: MAX_EVIDENCE_ID,
+                        description: "Optional: the id of captured Proof evidence this item refers to. Without a valid id the item is plain text and verifies nothing.",
+                    },
+                }, ["kind", "detail"]),
             },
         }, ["status", "summary", "evidence"]),
         async execute(input, context) {
@@ -101,7 +120,19 @@ export function registerGoalTools(registry, deps) {
                 return textResult(JSON.stringify({ ok: false, error: evidence }));
             const result = goals.report(sessionId, context.runId, { status, summary, evidence });
             if (!result.ok)
-                return textResult(JSON.stringify({ ok: false, error: result.message }));
+                return textResult(JSON.stringify({
+                    ok: false,
+                    error: result.message,
+                    ...(result.unmet
+                        ? {
+                            unmet: result.unmet.slice(0, MAX_UNMET_LISTED).map((u) => ({
+                                criterionId: u.criterionId,
+                                text: u.text,
+                                status: u.status,
+                            })),
+                        }
+                        : {}),
+                }));
             if (status === "complete")
                 return textResult(JSON.stringify({
                     ok: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.6.0",
+    "@alisio/sdk": "0.8.0",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",