@sema-agent/core/dist/core/shared-memory/contract.d.ts

Stateless, task-oriented AI agent core

/**
 * design/177 — the SharedMemoryStoreProvider conformance suite: the cross-repo acceptance contract a
 * third-party / deployment-authored provider runs against itself. Same shape as the memory-backend
 * suite it is modeled on — runner-agnostic (node:assert, zero vitest), a FRESH instance per case, and
 * an optional `runAssertion` wrapper so a vitest consumer can turn each case into an `it`.
 *
 * FIXTURES ARE HANDED IN, not written through the seam. Unlike the entry-transactional backend suite
 * (which can seed itself through its own patch face), this seam is read-only and has no public write
 * port at all, so `make` receives the intended contents and returns a provider that reads them back.
 *
 * NO CROSS-INSTANCE / CAS CASE — a DECLARED absence, not an omission: a compare-and-set case exists to
 * cover a write-race axis, and a face with no write channel has no such axis. There is consequently no
 * skip hook either: every case below is mandatory, so a passing run never means "most of it passed".
 *
 * WHAT IS ASSERTED. Only the PROVIDER's own obligations — faithfulness, absence-as-a-value, prefix
 * completeness, cancellation, isolation. Rendering, pagination, sanitizing and refusal wording are the
 * engine's job and are covered by the engine's own tests; asserting them here would make a third party
 * responsible for behavior it does not implement.
 */
import type { SharedMemorySnapshot, SharedMemoryStoreInfo, SharedMemoryStoreProvider } from "./types.js";
/** What an implementation must load into its own storage before returning a provider over it. */
export interface SharedMemoryFixture {
    state: SharedMemorySnapshot["state"];
    stores: Array<{
        info: SharedMemoryStoreInfo;
        documents: Array<{
            path: string;
            content: string;
            updatedAt?: string;
        }>;
    }>;
}
export interface SharedMemoryStoreContractHooks {
    make: (fixture: SharedMemoryFixture) => Promise<SharedMemoryStoreProvider> | SharedMemoryStoreProvider;
    /** Wrap each case (vitest `it`, sequential chaining, …). Default: run them sequentially. */
    runAssertion?: (name: string, fn: () => Promise<void>) => void | Promise<void>;
}
/** Run the full conformance suite. Throws (assert) on the first violated clause. */
export declare function sharedMemoryStoreContract(hooks: SharedMemoryStoreContractHooks): Promise<void>;