@sema-agent/core/dist/core/store-contracts/checkpoint-store-contract.d.ts

Stateless, task-oriented AI agent core

import { type Checkpoint, type CheckpointStore, type ResumeOutcome } from "../checkpoint-store.js";
import type { GateOutcome } from "../gate-outcome.js";
import { type CheckpointFields } from "../pause-registry.js";
import { type ContractAssertionRunner } from "./contract-harness.js";
/**
 * design/159 S1 — the cross-backend {@link CheckpointStore} contract, extracted VERBATIM from
 * `test/cross-backend-shared.ts` (design/87 §3 gap [cross-backend-enforce], the anti-drift guard
 * born in design/80 §6.3) into a vitest-free kit a third-party backend implementor can import and
 * run under any harness (or none — see {@link ContractAssertionRunner}).
 *
 * `make()` must return a FRESH, empty store each call. Core binds this to InMemory + File
 * (`test/cross-backend-inmem-file.test.ts`) and Pg via pg-mem (`test/pg-cross-backend.test.ts`);
 * a third-party durable backend passes its own factory.
 *
 * Version lockstep: see `contract-kit-version.ts` (`CONTRACT_KIT_ENGINE_VERSION`).
 */
/** Build a {@link Checkpoint} fixture. `createdAt` is FIXED (not wall-clock) so summary projections
 *  are deterministic and cross-backend byte-comparable; override via `over` for ordering tests. */
export declare function createCheckpointFixture(over?: Partial<CheckpointFields>): Checkpoint;
/** The canonical `policy_ask allow` outcome the contract resolves with. Declared as the NARROW
 *  `policy_ask` arm — not the whole union — so field access and spread call sites need no
 *  re-assertion (RB-396-d: the wide declaration forced an `as Extract<…>` + a same-value
 *  `boundCallId` overwrite at one site — verbatim 移植残渣, both gone with this declaration). */
export declare const ALLOW: Extract<ResumeOutcome, {
    gate: "policy_ask";
}>;
export declare const EXECUTED_ALLOW: GateOutcome;
export declare const EXECUTED_ALLOW_REORDERED: GateOutcome;
export declare const VETOED_BY_POLICY: GateOutcome;
/** The other decider: the record a `policy_ask` allow the deployment's own POLICY decided files
 *  (`policy_allowed`, `who.party: "policy"` with the seat that answered) — the decision's own record on the
 *  resolved winner, and the execution record once the call ran — and the decide that carries it. A backend keeps
 *  the record verbatim; nothing in it may be re-derived from the person's shape. */
export declare const POLICY_ALLOWED: GateOutcome;
export declare const POLICY_ALLOW: Extract<ResumeOutcome, {
    gate: "policy_ask";
}>;
/**
 * The full cross-backend contract for {@link CheckpointStore} — the SAME assertions for every
 * backend. Entries are a 1:1 port of the vitest originals (assertion semantics unchanged).
 */
export declare function checkpointStoreContract(make: () => CheckpointStore, runAssertion?: ContractAssertionRunner): Promise<void>;
/** Seed the canonical listByScope fixture into `store` and return the sorted summaries. Compare the
 *  result against {@link EXPECTED_LISTBYSCOPE_SUMMARIES} (deep equality) to prove the backend's
 *  summary projection matches the reference — the caller owns the comparison (harness-specific). */
export declare function checkpointListByScopeSummaries(store: CheckpointStore): Promise<import("../checkpoint-store.js").CheckpointSummary[]>;
/** The canonical expected summary projection (what `summarizeCheckpoint` must yield for the fixture above). */
export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
    token: string;
    sessionId: string;
    scope: string;
    gateKind: string;
    severity: number;
    deadline: number;
    createdAt: number;
    sourceTaskId: string;
    principal: string;
    toolCallId: string;
    toolName: string;
    toolInput: string;
    mandated: boolean;
    mandate: string;
    origin: string;
    spentMicroUsd?: undefined;
} | {
    token: string;
    sessionId: string;
    scope: string;
    gateKind: string;
    spentMicroUsd: number;
    createdAt: number;
    severity?: undefined;
    deadline?: undefined;
    sourceTaskId?: undefined;
    principal?: undefined;
    toolCallId?: undefined;
    toolName?: undefined;
    toolInput?: undefined;
    mandated?: undefined;
    mandate?: undefined;
    origin?: undefined;
})[];