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

Stateless, task-oriented AI agent core

/**
 * The CROSS-STORE read-back rule (`@contract store.read_back_shape_judged`, quoted for integrators in
 * `docs/INTEGRATION-CORE.md` §5.0) and the acceptance suite that pins it. Kit form as the sibling kits
 * (see `permission-rule-write-contract.ts`): no test framework, no skip hook.
 */
import { type ContractAssertionRunner } from "./contract-harness.js";
/**
 * @contract store.read_back_shape_judged — every read a store answers, a single get and an enumeration
 * alike, judges the SHAPE of what it read before answering: a body that is not the shape this store
 * writes is CORRUPT, and a corrupt body is answered in the store's own corrupt vocabulary — a loud
 * refusal, or an absence that carries a disclosure naming the loss — never as an empty set, an empty
 * object or a default value, because an answer a caller cannot tell apart from "there is nothing here"
 * turns a recoverable incident into a silent one. Which read-back failures a store TOLERATES (an
 * enumeration that skips one unreadable row and serves the rest, a torn trailing write read as absent)
 * is a per-store fact registered beside that store's own contract, never assumed from another store's.
 * On the JSONL file format the unterminated last segment is judged by the same parse as every other line
 * (`readJsonlRecords`): one that parses to an object is a whole record that lost only its newline (served,
 * and its line ended at the next open or append), one that does not parse is a crash's partial write (absent,
 * cut back to the last newline), so a newline is the boundary's spelling and never the condition of a record
 * existing.
 */
export declare const CORRUPT_BODY_FORMS: readonly ["not-an-object", "missing-required", "wrong-type", "torn-json"];
/** One way a persisted body can fail to be the shape its store writes. */
export type CorruptBodyForm = (typeof CORRUPT_BODY_FORMS)[number];
export interface ReadBackShapeSubject {
    /** Declared ONCE per subject, and only by a backend that keeps no bytes a foreign writer could damage
     *  (a process-local map holding objects it minted itself). Never per attempt: a planter that cannot
     *  find bytes it knows exist must FAIL rather than exempt its backend. */
    readonly unplantable?: string;
    /** Plant ONE corrupt body of `form`, with `sentinel` inside the planted bytes wherever the form allows
     *  (that is how clause 3 detects a body handed straight back). No declining return: a backend with no
     *  bodies declares that at the subject, and a planter that cannot find bytes it knows exist THROWS. */
    plant: (form: CorruptBodyForm, sentinel: string) => Promise<void>;
    /** Perform the read under test. THROWING IS AN ANSWER — the loud refusal — and is not a suite failure. */
    read: () => Promise<unknown>;
    /** Write ONE well-formed row — clause 1's subject. */
    seed: () => Promise<void>;
    close?: () => void;
}
export interface StoreReadBackShapeHooks {
    /** The face under test, named as a reader would name it (`"FileCheckpointStore.get"`). Failure text only. */
    face: string;
    /** Open a FRESH, EMPTY store and return its subject. Called once per observation; teardown is `close`. */
    open: () => Promise<ReadBackShapeSubject>;
    runAssertion?: ContractAssertionRunner;
}
/**
 * Run the read-back shape suite over ONE read face. Throws (assert) on the first violated clause.
 *
 * Clauses: (1) a seeded row and an empty store both ANSWER, answer differently, and the empty answer is
 * REPRODUCIBLE — a face that throws at everything, answers everything alike, or carries incidental data
 * (a read id, a timestamp) proves nothing by differing under corruption;
 * (2) each of the four {@link CORRUPT_BODY_FORMS}, planted, is answered differently from an empty store;
 * (3) and the answer never contains the planted bytes.
 *
 * CEILING: clause 2 proves the corrupt case is DISTINGUISHABLE, not that the distinguishing answer is
 * right — a face answering one invalid row where a good read answers rows passes. Whether the store then
 * named the loss correctly is judged by its own section in §5.0, by a person; the four forms are a
 * fixture set, not the space of corrupt bodies.
 */
export declare function storeReadBackShapeContract(hooks: StoreReadBackShapeHooks): Promise<void>;