@sema-agent/core 7.52.0 → 7.54.0

package/dist/core/store-contracts/session-store-contract.d.ts

@@ -0,0 +1,49 @@
+import { type SessionStore } from "../session.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+import { type SessionStoreIncarnationContractHooks } from "./session-store-incarnation-contract.js";
+/**
+ * The cross-backend contract for {@link SessionStore} as the interface states it TODAY — what a store must
+ * do so that the engine, a deployment's authorizer and a shell read the same answers off it whether the
+ * store is the bundled `TtlSessionStore` (over an in-memory or file repo) or a backend that implements the
+ * interface directly (a SQL store). vitest-free (see `contract-harness.ts`); every case builds a FRESH store
+ * through `make()` and disposes it.
+ *
+ * Each case pins one sentence of the interface (`core/session.ts`) or of the session-tree storage it hands
+ * out (`SessionStorage`, whose path / leaf / write-CAS rules every store's sessions carry). Optional faces
+ * are judged only when present; a group whose face is absent passes WITHOUT asserting and says so through
+ * `onOptionalMember` — a case name cannot carry "absent" (the default runner drops names, and a green
+ * absent run is byte-identical to a green verified one), so a consumer that relies on a face asserts the
+ * report, never the green.
+ *
+ * What the kit cannot see from outside, it does not claim: idle eviction and `pin` (the interface has no
+ * clock seam), what `release` does to an ordinary session's live set (`size` is best-effort and a durable
+ * `list` may still show the history), a durable backend's crash recovery, and a delete that fails half-way.
+ * One stated obligation is not a case yet because the bundled store does not keep it: an ownership row
+ * outliving its session across a restart (`TtlSessionStore` holds owners in process memory).
+ *
+ * Semantics since @sema-agent/core 7.55.0.
+ */
+export interface SessionStoreContractHooks {
+    /** The same hook as the incarnation kit's ({@link SessionStoreIncarnationContractHooks.deleteSession}): one
+     *  function serves both kits. */
+    deleteSession: SessionStoreIncarnationContractHooks["deleteSession"];
+    /** A SECOND, independent store instance over the same rows as `store` — what a restarted process
+     *  constructs. After calling it the kit no longer uses `store`, so a backend that holds an exclusive lock
+     *  may release `store`'s first (the kit still disposes `store` at the end of the case: that dispose must
+     *  then be harmless). The kit disposes the returned instance. */
+    reopen: (store: SessionStore) => SessionStore | Promise<SessionStore>;
+    /** A second LIVE instance over the same rows, used CONCURRENTLY with `store` — what another replica
+     *  constructs. Absent ⇒ the replica case is reported absent (a backend that is single-process by
+     *  contract has no replica). The kit disposes it. */
+    replica?: (store: SessionStore) => SessionStore;
+    runAssertion?: ContractAssertionRunner;
+    /** Optional faces (plus the replica hook, and `requireExisting` — absent = the store rejects the option, its other
+     *  legal mode) a run verified or found absent; reported per judging case, after its assertions held. */
+    onOptionalMember?: (report: {
+        member: "requireExisting" | "forget" | "fork" | "list" | "noteTaskRun" | "listPlaced" | "placements" | "ownership" | "incarnationOf" | "replica";
+        status: "verified" | "absent";
+    }) => void;
+}
+/** A hooks record the kit cannot run with is refused SYNCHRONOUSLY, before any case is registered, so a
+ *  `void sessionStoreContract(…)` registration fails at collection instead of as an unhandled rejection. */
+export declare function sessionStoreContract(make: () => SessionStore, hooks: SessionStoreContractHooks): Promise<void>;