@looprun-ai/core 0.2.1 → 0.4.0

package/dist/testing/proof.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The declarative PROOF format + the framework-free runners for the @looprun-ai/core testing kit.
+ *
+ * A {@link GuardProof} states, for ONE guard kind, the L1 (deterministic check in isolation) and optional
+ * L3 (full loop) obligations across positive/negative/neutral cases. This file holds only the pieces that
+ * need NO framework backend: the proof TYPES, the collective non-interference whitelist, the L1 runner,
+ * and the spec builders (isolated / collective) over the fixture surface. The full-loop runners
+ * (runProofLoop / expectedSignal / pickRecord / assertSignal) live in the backend package, since they
+ * drive a real conversation.
+ */
+import { AgentSpecBase } from '../spec.js';
+import type { AgentSpecConfig, Hook, ToolTarget } from '../spec.js';
+import type { Guard, GuardCtx } from '../rules.js';
+import type { FixturePreset } from './fixture-world.js';
+export type ProofPolarity = 'positive' | 'negative' | 'neutral';
+export type ProofExpect = 'veto' | 'redrive' | 'refusal' | 'pass';
+export type PartialGuardCtx = Partial<GuardCtx>;
+/** One conversation turn's input (structural — the backend's TurnInput shape). */
+type ProofTurn = {
+    userText: string;
+    attachments?: string[];
+};
+/** One scripted LLM response (structural — the fake model's ScriptStep shape). */
+type ScriptStep = Array<{
+    tool: string;
+    args: Record<string, unknown>;
+} | {
+    text: string;
+}>;
+export interface ProofLoopCase {
+    preset: FixturePreset;
+    turns: ProofTurn[];
+    script: ScriptStep[];
+    expect: ProofExpect;
+    tool?: string;
+    /** Which turnRecord to assert on (default: the last). */
+    turn?: number;
+    /** Guard kinds that LEGITIMATELY co-fire on this scenario in the COLLECTIVE run (two guards genuinely
+     *  binding the same violation — e.g. a destructive claim that is also a pending, un-relayed
+     *  confirmation). Added to that case's non-interference whitelist; keep it minimal and justified. */
+    alsoFires?: string[];
+}
+export interface ProofCase {
+    name: string;
+    polarity: ProofPolarity;
+    ctx?: PartialGuardCtx;
+    l1: 'fires' | 'silent';
+    l3?: ProofLoopCase;
+}
+export interface GuardProof {
+    /** MUST equal the guards.ts kind (the ratchet key). */
+    guard: string;
+    /** Instantiate the guard. Always required in practice (the runners throw without it); `auto` only
+     *  controls whether buildIsolatedSpec/buildCollectiveSpec ADD it (an auto-installed kind is already on
+     *  the spec via AgentSpecBase). */
+    make?: () => Guard;
+    hook: Hook;
+    target: ToolTarget;
+    /** Rely on AgentSpecBase auto-install (minimal/base layer) instead of addGuard. */
+    auto?: 'minimal' | 'base';
+    /** Spec config to merge (e.g. destructiveTools / confirmMechanism / lexicon for auto kinds). */
+    specTweaks?: Partial<AgentSpecConfig>;
+    /** 'skip' excludes this guard from the collective super-agent. Reserved for content-contract reply
+     *  guards (replyMustMention, replySingleQuestion, replyConfirmsLabels, replyMaxOccurrences): an author
+     *  binds those to ONE agent's specific reply contract — installing them agent-wide over arbitrary
+     *  scenarios would fire on every unrelated reply by construction, which is a category error, not an
+     *  interference finding. They are still fully proven isolated (L1 + L3). */
+    collective?: 'include' | 'skip';
+    cases: ProofCase[];
+}
+/** The collective non-interference whitelist — the kinds AgentSpecBase auto-installs. */
+export declare const AUTO_LAYER_KINDS: readonly ["noDuplicateCall", "degenerationGuard", "emptyReply", "noFalseFailureClaim", "confirmFirst", "destructiveThrottle"];
+/** Fill a GuardCtx from a partial: empty args, a fresh FixtureWorld('seeded-media') unless a world is
+ *  given, empty observed, turnIndex 0. */
+export declare function craftCtx(partial?: PartialGuardCtx): GuardCtx;
+/** Instantiate a proof's guard, or throw when `make` is absent (the runners require it). */
+export declare function requireMake(proof: GuardProof): () => Guard;
+/** L1 — run the guard's deterministic check in isolation against a crafted ctx. */
+export declare function runL1(proof: GuardProof, c: ProofCase): Promise<{
+    fired: boolean;
+    reason: string | null;
+}>;
+/** Build a spec that isolates ONE proof's guard over the fixture surface. */
+export declare function buildIsolatedSpec(proof: GuardProof): AgentSpecBase;
+/** Build ONE spec with EVERY non-auto proof guard installed — the collective non-interference harness.
+ *  Auto kinds ride AgentSpecBase (destructiveTools + confirmMechanism + lexicon below). Duplicate kinds
+ *  at different targets are fine; ids are made unique by suffixing `#2`, `#3`, … */
+export declare function buildCollectiveSpec(proofs: GuardProof[]): AgentSpecBase;
+export {};
+//# sourceMappingURL=proof.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../../src/testing/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAClE,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhD,kFAAkF;AAClF,KAAK,SAAS,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAC9D,kFAAkF;AAClF,KAAK,UAAU,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE5F,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;yGAEqG;IACrG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,EAAE,EAAE,OAAO,GAAG,QAAQ,CAAC;IACvB,EAAE,CAAC,EAAE,aAAa,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd;;uCAEmC;IACnC,IAAI,CAAC,EAAE,MAAM,KAAK,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,mFAAmF;IACnF,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B,gGAAgG;IAChG,UAAU,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACtC;;;;gFAI4E;IAC5E,UAAU,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAChC,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,yFAAyF;AACzF,eAAO,MAAM,gBAAgB,+HAOnB,CAAC;AAEX;0CAC0C;AAC1C,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAQhE;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,KAAK,CAG1D;AAED,mFAAmF;AACnF,wBAAsB,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAI/G;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAclE;AAED;;oFAEoF;AACpF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,aAAa,CA2BvE"}

package/dist/testing/proof.js

@@ -0,0 +1,93 @@
+/**
+ * The declarative PROOF format + the framework-free runners for the @looprun-ai/core testing kit.
+ *
+ * A {@link GuardProof} states, for ONE guard kind, the L1 (deterministic check in isolation) and optional
+ * L3 (full loop) obligations across positive/negative/neutral cases. This file holds only the pieces that
+ * need NO framework backend: the proof TYPES, the collective non-interference whitelist, the L1 runner,
+ * and the spec builders (isolated / collective) over the fixture surface. The full-loop runners
+ * (runProofLoop / expectedSignal / pickRecord / assertSignal) live in the backend package, since they
+ * drive a real conversation.
+ */
+import { AgentSpecBase } from '../spec.js';
+import { FixtureWorld, FIXTURE_TOOL_NAMES, FIXTURE_THEME, FIXTURE_LEXICON } from './fixture-world.js';
+/** The collective non-interference whitelist — the kinds AgentSpecBase auto-installs. */
+export const AUTO_LAYER_KINDS = [
+    'noDuplicateCall',
+    'degenerationGuard',
+    'emptyReply',
+    'noFalseFailureClaim',
+    'confirmFirst',
+    'destructiveThrottle',
+];
+/** Fill a GuardCtx from a partial: empty args, a fresh FixtureWorld('seeded-media') unless a world is
+ *  given, empty observed, turnIndex 0. */
+export function craftCtx(partial = {}) {
+    return {
+        args: {},
+        world: new FixtureWorld('seeded-media'),
+        observed: [],
+        turnIndex: 0,
+        ...partial,
+    };
+}
+/** Instantiate a proof's guard, or throw when `make` is absent (the runners require it). */
+export function requireMake(proof) {
+    if (!proof.make)
+        throw new Error(`GuardProof "${proof.guard}": make() is required to instantiate the guard.`);
+    return proof.make;
+}
+/** L1 — run the guard's deterministic check in isolation against a crafted ctx. */
+export async function runL1(proof, c) {
+    const guard = requireMake(proof)();
+    const reason = await guard.check(craftCtx(c.ctx));
+    return { fired: reason != null, reason: reason ?? null };
+}
+/** Build a spec that isolates ONE proof's guard over the fixture surface. */
+export function buildIsolatedSpec(proof) {
+    const cfg = {
+        id: `proof-${proof.guard}`,
+        mode: 'PROOF',
+        persona: 'You are the proof agent.',
+        tools: [...FIXTURE_TOOL_NAMES],
+        theme: FIXTURE_THEME,
+        ...(proof.specTweaks ?? {}),
+    };
+    const spec = new AgentSpecBase(cfg);
+    if (!proof.auto) {
+        spec.addGuard(proof.hook, proof.target, requireMake(proof)(), { id: `agent:${proof.guard}` });
+    }
+    return spec;
+}
+/** Build ONE spec with EVERY non-auto proof guard installed — the collective non-interference harness.
+ *  Auto kinds ride AgentSpecBase (destructiveTools + confirmMechanism + lexicon below). Duplicate kinds
+ *  at different targets are fine; ids are made unique by suffixing `#2`, `#3`, … */
+export function buildCollectiveSpec(proofs) {
+    const spec = new AgentSpecBase({
+        id: 'proof-collective',
+        mode: 'PROOF',
+        persona: 'You are the proof agent.',
+        tools: [...FIXTURE_TOOL_NAMES],
+        theme: FIXTURE_THEME,
+        destructiveTools: ['deleteItem', 'purgeAll'],
+        confirmMechanism: { purgeAll: 'prior-ask' },
+        lexicon: {
+            falseFailureClaimRe: FIXTURE_LEXICON.falseFailureClaimRe,
+            confirmAskRe: FIXTURE_LEXICON.confirmAskRe,
+        },
+    });
+    const used = new Set();
+    for (const proof of proofs) {
+        if (proof.auto || proof.collective === 'skip')
+            continue;
+        let id = `agent:${proof.guard}`;
+        let n = 1;
+        while (used.has(id)) {
+            n += 1;
+            id = `agent:${proof.guard}#${n}`;
+        }
+        used.add(id);
+        spec.addGuard(proof.hook, proof.target, requireMake(proof)(), { id });
+    }
+    return spec;
+}
+//# sourceMappingURL=proof.js.map

package/dist/testing/proof.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looprun-ai/core",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "looprun core: the AgentSpec governance layer for LLM agents — typed deterministic guards (prose+check pairing), the byte-stable scoped trunk renderer, and the backend-agnostic governed-turn machine. Framework-free: zero runtime dependencies; backends (@looprun-ai/mastra, …) supply the loop.",
   "keywords": [
@@ -28,6 +28,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -44,6 +48,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:proofs": "vitest run test/proofs --passWithNoTests"
   }
 }