@sema-agent/core/dist/core/store-contracts/read-back-shape-contract.js

Stateless, task-oriented AI agent core

import assert from "node:assert";
import { thrownText } from "../thrown-value.js";
import { beginContract } from "./contract-harness.js";
export const CORRUPT_BODY_FORMS = Object.freeze(["not-an-object", "missing-required", "wrong-type", "torn-json"]);
async function observe(subject) {
    try {
        const value = await subject.read();
        return { threw: false, body: safeStringify(value) };
    }
    catch (err) {
        return { threw: true, message: thrownText(err) };
    }
}
function safeStringify(value) {
    const seen = new WeakSet();
    try {
        return (JSON.stringify(value, (_k, v) => {
            if (typeof v === "object" && v !== null) {
                if (seen.has(v))
                    return "[circular]";
                seen.add(v);
            }
            return v;
        }) ?? String(value));
    }
    catch {
        return String(value);
    }
}
function render(o) {
    return o.threw ? `threw(${o.message})` : `answered ${o.body}`;
}
async function withSubject(hooks, fn) {
    const subject = await hooks.open();
    try {
        return await fn(subject);
    }
    finally {
        subject.close?.();
    }
}
export async function storeReadBackShapeContract(hooks) {
    const { run, settle } = beginContract(hooks.runAssertion);
    const where = hooks.face;
    run(`${where}: the read face tells a present row from an absent one (positive control)`, async () => {
        const empty = await withSubject(hooks, observe);
        const seeded = await withSubject(hooks, async (s) => {
            await s.seed();
            return observe(s);
        });
        assert.equal(empty.threw, false, `${where}: reading an EMPTY store must answer, not throw (${render(empty)}) — absence is not damage`);
        assert.equal(seeded.threw, false, `${where}: reading a well-formed row must answer, not throw (${render(seeded)})`);
        const again = await withSubject(hooks, observe);
        assert.deepEqual(again, empty, `${where}: two reads of two EMPTY stores answered differently (${render(empty)} then ${render(again)}) — this suite's oracle is "the corrupt answer differs from the empty one", which is free for a face carrying incidental data; project it away in the binding`);
        assert.notDeepEqual(seeded, empty, `${where}: a seeded store and an empty one answered identically (${render(empty)}) — this face reports nothing a corrupt body could differ from, so every clause below would pass without meaning anything`);
    });
    for (const form of CORRUPT_BODY_FORMS) {
        run(`${where}: a ${form} body is not read as an absent row`, async () => {
            const sentinel = `sema-corrupt-sentinel-${form}`;
            const empty = await withSubject(hooks, observe);
            const corrupt = await withSubject(hooks, async (s) => {
                if (s.unplantable !== undefined) {
                    assert.ok(s.unplantable.length > 0, `${where}: a subject declaring no plantable body must say WHY`);
                    return undefined;
                }
                await s.plant(form, sentinel);
                return observe(s);
            });
            if (corrupt === undefined)
                return;
            assert.notDeepEqual(corrupt, empty, `${where}: a ${form} body was answered exactly as an absent row is (${render(empty)}) — a corrupt body must reach the caller as a refusal or as an absence that names the loss, never as the store's empty answer`);
            if (!corrupt.threw) {
                assert.ok(!corrupt.body.includes(sentinel), `${where}: a ${form} body was handed back through the read face (the planted marker is in the answer) — the read judged nothing`);
            }
        });
    }
    await settle();
}