@alma-harness/core 0.1.0

package/dist/turn-store-uKJ4inz2.d.ts

@@ -0,0 +1,1054 @@
+/**
+ * Tenancy scope — the isolation boundary of the whole harness.
+ *
+ * `{org, uid}` derives from a server-verified token, never from a client
+ * payload, and is bound to tool registries by closure at construction time —
+ * the model never passes org/uid as parameters.
+ *
+ * @see docs/architecture.md §6.1, §6.8
+ */
+interface Scope {
+    /** Organization (tenant) id. */
+    readonly org: string;
+    /** User id within the organization. */
+    readonly uid: string;
+}
+/**
+ * Thrown by {@link scopePath} when a scope segment could be used for path
+ * traversal or key-delimiter injection.
+ */
+declare class InvalidScopeError extends Error {
+    constructor(segment: "org" | "uid", value: string);
+}
+/**
+ * The single place that builds `tenants/{org}/users/{uid}` — §6.8.
+ *
+ * A *concept*, not a literal storage path: the Firestore adapter renders it as
+ * a collection path, the Postgres adapter as row-level-security predicates
+ * (§6). Every store keys its data by this concept so scoped purge and export
+ * have one canonical addressing scheme.
+ */
+declare function scopePath(scope: Scope): string;
+
+/**
+ * Neutral message format — §6.1.
+ *
+ * The harness defines its own message vocabulary; provider adapters translate
+ * to/from each provider's wire format. Sessions persist ONLY this format — no
+ * opaque CLI transcripts, no derived project keys.
+ */
+type MediaKind = "image" | "audio" | "document";
+/**
+ * Reference to media held in product-owned storage — §6.1: media travels by
+ * reference and is never persisted inline.
+ *
+ * DECISION: the doc leaves the shape open; we use an opaque URI plus optional
+ * metadata. The product decides how the URI is dereferenced (GCS, S3, …); the
+ * harness never fetches it implicitly.
+ */
+interface MediaRef {
+    uri: string;
+    contentType?: string;
+    bytes?: number;
+    /**
+     * Display name the person saw — spec 040. Optional, and deliberately not
+     * derived from `uri`: a storage path is an id, and the two coincide only by
+     * accident.
+     *
+     * Added for a migration that measured both cases. One store being moved
+     * repeats the name inside the message text (168 of 168 messages with an
+     * attachment), so the field is redundant there; another carries it in 125 of
+     * 125 document messages and in the text in NONE, so it is the only copy.
+     * Reconstructing it by parsing prose is the failure mode this avoids.
+     */
+    filename?: string;
+}
+/** One content block of a message — §6.1. */
+type Block = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    callId: string;
+    output: unknown;
+    isError?: boolean;
+} | {
+    type: "media";
+    kind: MediaKind;
+    ref: MediaRef;
+};
+interface MsgMeta {
+    /** ISO 8601 timestamp. */
+    at: string;
+    /** Channel the message arrived on / was sent to (e.g. "whatsapp", "portal"). */
+    channel?: string;
+    /** Model that produced an assistant message (e.g. "anthropic/<model-id>"). */
+    model?: string;
+}
+/** A conversation message in the neutral format — §6.1. */
+interface Msg {
+    role: "user" | "assistant" | "tool";
+    blocks: Block[];
+    meta?: MsgMeta;
+}
+
+/**
+ * Model client contract — §6.2. One adapter per provider lives in
+ * `@alma-harness/providers`; each adapter swallows the provider differences
+ * (tool-call shapes, streaming, caching, structured output, token accounting)
+ * and has contract tests with recorded fixtures to catch API drift.
+ */
+/**
+ * The providers Alma knows by name — a CLOSED union, because the price table,
+ * the client map, and the routing trail all key on it. Anthropic and OpenAI
+ * from birth (§3 principle 4); `openrouter` is the gateway bridge (spec:
+ * openrouter-gateway) — a gateway does not answer "who processed this data?"
+ * by itself, so its adapter requires a declared upstream allowlist.
+ */
+type ProviderId = "anthropic" | "openai" | "openrouter";
+interface ModelRef {
+    provider: ProviderId;
+    /** Provider-native model id. */
+    id: string;
+}
+/**
+ * System prompt block carrying the stable/volatile boundary — §6.2, §6.9.
+ * Stable blocks (persona, guidance) form the cacheable prefix; volatile blocks
+ * (date/time, interlocutor identity, recall) come after it. One discipline
+ * optimizes caching on both providers.
+ */
+interface SystemBlock {
+    text: string;
+    volatility: "stable" | "volatile";
+}
+/**
+ * Wire spec of a tool as sent to the model — §6.4. Always DERIVED from the
+ * scoped registry, never a hand-maintained parallel list: the "tool exists on
+ * the server but is missing from the allowlist" bug class ceases to exist.
+ */
+interface ToolSpec {
+    name: string;
+    description: string;
+    /** JSON Schema derived from the registered validation schema. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Token accounting for one model call — §6.2, §6.5.
+ *
+ * DECISION (spec 005): `inputTokens` EXCLUDES cache reads — it counts
+ * uncached, full-price input tokens only. Adapters normalize their wire
+ * semantics to this (Anthropic already reports it this way; the OpenAI
+ * adapter subtracts `cached_tokens`), so the BudgetGuard prices every
+ * provider identically.
+ */
+interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens?: number;
+    cacheWriteInputTokens?: number;
+}
+/**
+ * DECISION: neutral stop vocabulary; adapters map provider-specific reasons
+ * (e.g. OpenAI `finish_reason`, Anthropic `stop_reason`) onto it.
+ * `refusal` (added by spec 002) is a provider-level safety decline — a harness
+ * serving people surfaces it as a first-class terminal state, never as a
+ * normal `end_turn`. `context_window_exceeded` (spec 002 review) means the
+ * conversation no longer fits the model's context window — distinct from
+ * `max_tokens` (output cap) so the long-context policy (§6.6) can react by
+ * pruning or summarizing.
+ */
+type StopReason = "end_turn" | "tool_use" | "max_tokens" | "refusal" | "context_window_exceeded";
+/**
+ * Neutral streaming event — §6.2 names the kinds ("text deltas, tool calls,
+ * usage"); DECISION: this union is the exact vocabulary both adapters must
+ * translate into. `tool_call` is emitted once per call with fully-parsed input.
+ */
+type ModelEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "usage";
+    usage: Usage;
+} | {
+    type: "stop";
+    reason: StopReason;
+};
+interface ModelRequest {
+    model: ModelRef;
+    /** With stable/volatile boundary markers — §6.9. */
+    system: SystemBlock[];
+    messages: Msg[];
+    /** Derived from the registry — never a parallel list (§6.4). */
+    tools: ToolSpec[];
+    maxTokens: number;
+}
+/**
+ * §6.2. `signal` (added by spec 005 review) lets the loop abort the in-flight
+ * provider call on cancellation or budget exhaustion — without it, tokens
+ * keep generating (and billing) after the harness has already terminated the
+ * turn, and a hung stream would keep the turn promise pending forever.
+ */
+interface ModelClient {
+    stream(req: ModelRequest, opts?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<ModelEvent>;
+}
+
+/**
+ * Budget — §6.5, spec: spend-store. Metering is mandatory; POLICY at the cap
+ * is product-owned. `perTurnUsd` is the one unconditional hard stop — at a
+ * sane level it trips only on malfunction (a tool loop), never on a
+ * legitimate conversation, and the session survives it. The persistent caps
+ * default to `warn` because this harness sits in front of people in fragile
+ * moments: a mid-conversation "budget exceeded" is a worse failure than the
+ * overspend. `BudgetGuard` enforcement is part of the privileged core — not a
+ * capability seam (§7.1); the `SpendStore` it accounts through is one.
+ */
+/** The two caps that need spend surviving the turn — spec: spend-store. */
+type PersistentCapName = "perSessionUsd" | "perTenantDayUsd";
+/** A persistent cap with its crossing policy. */
+interface PersistentCap {
+    usd: number;
+    /**
+     * DECISION (spec: spend-store): defaults to `"warn"` — the turn continues
+     * and the crossing lands on the cost trail and the `TurnResult`, exactly
+     * once per cap per turn. `"block"` (terminate `budget_exceeded`, refuse new
+     * turns at preflight) is the opt-in for machine-facing consumers — an eval
+     * sweep, a public agent's kill-switch — never the ambient default.
+     */
+    onExceeded?: "warn" | "block";
+}
+/** Dollar caps — §6.5, §8. All optional; an absent cap is uncapped. */
+interface BudgetCaps {
+    /**
+     * Hard cap for a single turn. DECISION: a triggered turn (routine run, §8)
+     * is one turn, so this is also the per-run cap — no separate field.
+     */
+    perTurnUsd?: number;
+    /** Bare number = `warn` (spec: spend-store). Keyed {org, uid, sessionId}. */
+    perSessionUsd?: number | PersistentCap;
+    /**
+     * Bare number = `warn`. Keyed {org, UTC day} — deliberately org-wide across
+     * uids: an org-level number is what an operator caps or watches (§6.5).
+     */
+    perTenantDayUsd?: number | PersistentCap;
+}
+/** Thrown by {@link BudgetGuard.charge} when a block-mode cap is crossed. */
+declare class BudgetExceededError extends Error {
+    readonly cap: keyof BudgetCaps;
+    readonly capUsd: number;
+    readonly spentUsd: number;
+    constructor(cap: keyof BudgetCaps, capUsd: number, spentUsd: number);
+}
+/**
+ * A {@link SpendStore} failure while a BLOCK-mode cap was configured — the
+ * fail-closed posture (spec: spend-store). Its own class because the loop must
+ * TERMINATE the turn on it wherever it surfaces: inside a delegate it would
+ * otherwise be swallowed into tool-result data like any handler error, and an
+ * opted-into stop would fail open exactly where the spend is.
+ */
+declare class SpendAccountingError extends Error {
+    constructor(operation: "add" | "peek", cause: unknown);
+}
+interface BudgetGuard {
+    /**
+     * Prices `usage` via the versioned price table, accumulates spend — in
+     * memory for the turn, through the {@link SpendStore} for the persistent
+     * caps — and throws {@link BudgetExceededError} when `perTurnUsd` or a
+     * block-mode cap is crossed. Async since spec: spend-store — a persistent
+     * counter cannot hide behind a sync signature. Warn-mode crossings are not
+     * returned here: they surface on the guard's own state (see
+     * `TurnBudgetGuard`), so the loop can stamp them on the settling
+     * `CostEvent` even when this call throws. Every turn's usage + cost also
+     * lands in the AuditLog cost trail — §6.8.
+     */
+    charge(usage: Usage & {
+        model: ModelRef;
+    }): Promise<void>;
+}
+/** Addresses both counters one charge touches — spec: spend-store. */
+interface SpendKey {
+    scope: Scope;
+    sessionId: string;
+    /** ISO 8601 — the store derives the UTC day bucket from it. */
+    at: string;
+}
+/** Post-operation counter totals. */
+interface SpendTotals {
+    /** Total for {org, uid, sessionId}. */
+    sessionUsd: number;
+    /** Total for {org, UTC day} — across ALL uids and sessions of the org. */
+    tenantDayUsd: number;
+}
+/**
+ * Persistent spend accounting — capability seam (§7.1), spec: spend-store.
+ * WHERE spend accumulates is swappable; THAT it is accounted — and that caps
+ * are enforced, in the privileged guard — is not (the `AuditLog` idiom).
+ *
+ * Counters are content-free aggregates and deliberately do NOT participate in
+ * scoped purge (§10): retained as a legitimate-interest financial record —
+ * purging them would turn an erasure right into a budget reset.
+ */
+interface SpendStore {
+    /**
+     * Atomically adds `usd` to BOTH counters and returns the post-add totals.
+     * Increment-and-return in one step is the load-bearing property: two
+     * concurrent turns must never both act on a stale total — read-modify-write
+     * is the store's job, not the guard's.
+     */
+    add(entry: SpendKey & {
+        usd: number;
+    }): Promise<SpendTotals>;
+    /** Current totals without charging — turn-start preflight, and the surface a product-side alerting watcher polls. */
+    peek(key: SpendKey): Promise<SpendTotals>;
+}
+/**
+ * One row of the per-provider/model price table — §6.5: versioned
+ * configuration data, not code.
+ */
+interface ModelPrice {
+    model: ModelRef;
+    inputUsdPerMTok: number;
+    outputUsdPerMTok: number;
+    cacheReadUsdPerMTok?: number;
+    cacheWriteUsdPerMTok?: number;
+}
+
+/**
+ * Routing policy — complexity × sensitivity — §6.3.
+ *
+ * The policy declares, per sensitivity class, which providers/models may touch
+ * the data and under what condition (e.g. `health` only on providers with an
+ * adequate data-processing agreement, or after pseudonymization).
+ *
+ * `ModelPolicy` enforcement is part of the privileged core — deliberately NOT
+ * a capability seam (§7.1).
+ */
+/** Task complexity tier — §6.3. */
+type Tier = "mechanical" | "standard" | "complex";
+/**
+ * Data sensitivity class — §6.3.
+ * `health` ⊃ special-category data under LGPD Art. 11 / GDPR Art. 9.
+ */
+type Sensitivity = "public" | "internal" | "personal" | "health";
+/** Ordered least → most sensitive — §6.3, spec 007. */
+declare const SENSITIVITY_LEVELS: readonly Sensitivity[];
+/**
+ * True when `a` is MORE sensitive than `b`. Spec 007: dispatch refuses a
+ * tool whose class exceeds the calling loop's declared sensitivity — a
+ * `health` tool in a `public` turn is a consumer bug surfaced loudly, never
+ * a silent data flow into a context routed for a lower class.
+ */
+declare function sensitivityExceeds(a: Sensitivity, b: Sensitivity): boolean;
+interface RoutingIntent {
+    tier: Tier;
+    sensitivity: Sensitivity;
+    /** Optional free-form task label, recorded in the routing trail. */
+    task?: string;
+}
+interface ModelChoice {
+    model: ModelRef;
+    /**
+     * DECISION: the "why" of §6.8's RoutingEvent is carried here so every
+     * resolution is auditable verbatim — a policy must explain itself.
+     */
+    rationale: string;
+}
+interface ModelPolicy {
+    /** Every resolution is recorded in the AuditLog routing trail — §6.3, §6.8. */
+    resolve(intent: RoutingIntent): ModelChoice;
+}
+
+/**
+ * Tenancy and audit — §6.8. Trails carry METADATA ONLY, never content — by
+ * construction, not by reviewer vigilance. Together with the logged-context
+ * invariant (§7.3) they answer "what exactly did the model see about this
+ * user?" as a query, not archaeology.
+ */
+/**
+ * Access trail entry: what/when/via which tool — §6.8. Correlation ids
+ * (spec 007) make "what happened in this turn?" a filter, not a join
+ * heuristic; they are optional because non-turn contexts (consolidation
+ * jobs) have no turnId.
+ */
+interface AccessEvent {
+    scope: Scope;
+    /** ISO 8601. */
+    at: string;
+    /** Tool that performed the access. */
+    tool: string;
+    /** DECISION: coarse verbs; finer detail goes in `resource`, never content. */
+    action: "read" | "write" | "delete" | "export";
+    /** Identifier of the touched resource (id/path) — never its content. */
+    resource?: string;
+    sessionId?: string;
+    turnId?: string;
+}
+/** Routing trail entry — §6.3, §6.8. */
+interface RoutingEvent {
+    scope: Scope;
+    at: string;
+    tier: Tier;
+    sensitivity: Sensitivity;
+    /** The chosen model. */
+    model: ModelRef;
+    /** Why — carried verbatim from `ModelChoice.rationale`. */
+    rationale: string;
+    sessionId?: string;
+    turnId?: string;
+}
+/**
+ * Recall trail entry — §7.3, spec 012.
+ *
+ * The logged-context invariant says a new MODEL-VISIBLE input requires a new
+ * logged event type, never a side channel. The recall block is exactly that:
+ * content the model sees which is not in the conversation.
+ *
+ * DECISION (spec 012): this records PROVENANCE, not the rendered text. A
+ * verbatim copy of recalled content would be a copy surface erasure cannot
+ * reach without rewriting history — the failure spec 011 closed, one layer up.
+ * "What did the model see about this user at turn 12" stays answerable as
+ * "these facts and these episodes", each resolvable to its CURRENT state,
+ * including erased. Replay of recall is therefore provenance-level, not
+ * byte-level: between perfect replay and erasure, erasure wins.
+ */
+interface RecallEvent {
+    scope: Scope;
+    at: string;
+    sessionId: string;
+    turnId: string;
+    /** Ids of the profile fact versions rendered into the block. */
+    factIds: readonly string[];
+    /** Ids of the episodes rendered into the block. */
+    episodeIds: readonly string[];
+    /** The single budget the whole block was assembled under (§6.7). */
+    budgetTokens: number;
+    /**
+     * Tokens the block the model actually SAW measured, by the core's own
+     * estimator — 0 when the block was dropped. (It formerly documented the
+     * assembler's self-reported number, which the core no longer trusts.)
+     */
+    estimatedTokens: number;
+    /** Measured size of a block that was dropped rather than shown. */
+    droppedTokens?: number;
+    /** True when the budget dropped content that would otherwise have shown. */
+    truncated: boolean;
+    /** Tiers whose read failed; their block is missing, the rest still rendered. */
+    degradedTiers?: readonly string[];
+}
+/**
+ * A field of the `ModelRequest` a `step:pre` interceptor may attempt — spec
+ * 029. Five, and the loop treats them in two classes: `system`, `messages` and
+ * `maxTokens` are the content and ceiling a hook may narrow; `model` and
+ * `tools` are privileged core and are repinned after the chain (§6.3, §6.4).
+ */
+type ContextField = "system" | "messages" | "maxTokens" | "model" | "tools";
+/**
+ * The SIZE of what a model call carried — spec 029. Metadata only: enough to
+ * answer "how much entered the model's view from outside the session log",
+ * never a copy of it.
+ */
+interface ContextShape {
+    systemBlocks: number;
+    systemChars: number;
+    messages: number;
+    /** Blocks across all messages — a fabricated block carrying no prose still moves this. */
+    messageBlocks: number;
+    /**
+     * Characters in TEXT blocks only. A size signal for injected prose, NOT a
+     * byte count of the request: serializing tool payloads to measure them would
+     * put the dispatch path's cost on every rewriting step, and `messageBlocks`
+     * already catches what carries no text.
+     */
+    messageChars: number;
+    maxTokens: number;
+}
+/**
+ * `step:pre` rewrote what the model was about to see — §7.3, spec 029.
+ *
+ * The logged-context invariant says a new MODEL-VISIBLE input requires a new
+ * logged event type, never a side channel. §7.2 deliberately lets an
+ * interceptor rewrite the request, so `system` and `messages` were exactly
+ * that: content in front of the model appearing in no session entry.
+ *
+ * DECISION (spec 029): this records SHAPES, not the rewritten text — the same
+ * trade {@link RecallEvent} made and for the same reason (a verbatim copy is a
+ * surface erasure cannot reach), plus the one that governs every trail here:
+ * they carry metadata only, by construction.
+ *
+ * DECISION (spec 029): emitted when the chain TOUCHED a field, not when the
+ * core honored it. A rewrite the core discards — a raised `maxTokens`, a
+ * swapped `model` — is named in {@link refused}. Recording only what survived
+ * would leave the pins silent, which is half of what the slice fixed.
+ *
+ * This narrows §7.3's `step:pre` hole; it does not close it. A rewrite is
+ * still not byte-level reconstructable. What it can no longer be is unrecorded.
+ */
+interface ContextEvent {
+    scope: Scope;
+    at: string;
+    sessionId: string;
+    turnId: string;
+    /** The turn step (1-based). A delegate's rewrite carries its PARENT's step. */
+    step: number;
+    /** True when the rewritten call was a delegate's, not the turn's own. */
+    delegate?: boolean;
+    /**
+     * Fields the chain touched — never empty, since the event exists because one
+     * was. Detected by REFERENCE (by value for `maxTokens`) against the pre-hook
+     * request, so a hook that rebuilds an identical array over-reports. That is
+     * the safe direction for a trail: a spurious entry is not a leak, a missing
+     * one is.
+     */
+    changed: readonly ContextField[];
+    /** Of those, the ones the core discarded or clamped rather than honored. */
+    refused?: readonly ContextField[];
+    /** What the model would have been sent. */
+    before: ContextShape;
+    /** What it WAS sent — post-clamp, post-pin. */
+    after: ContextShape;
+}
+/** Cost trail entry — §6.5, §6.8. */
+interface CostEvent {
+    scope: Scope;
+    at: string;
+    model: ModelRef;
+    usage: Usage;
+    costUsd: number;
+    sessionId?: string;
+    turnId?: string;
+    /**
+     * Warn-mode persistent caps THIS settle crossed — spec: spend-store. At
+     * most once per cap per turn; absent on every other event.
+     */
+    capsCrossed?: readonly PersistentCapName[];
+}
+/**
+ * §6.8. The SINK is a capability seam (§7.1) — where trails are written is
+ * swappable; THAT they are written is not (emission lives in the privileged
+ * core and cannot be bypassed by hooks or configuration).
+ *
+ * DECISION (spec 027, revised): every method may return a promise, and the
+ * harness AWAITS it. The previous rule — "synchronous fire-and-forget so
+ * auditing never blocks the critical path" — could not be enforced and was not
+ * true: `void` is exactly the return type TypeScript lets an `async` function
+ * satisfy, so a DB- or HTTP-backed sink (the shape §5 promises for Postgres)
+ * was always assignable, and its rejection escaped as an unhandled rejection —
+ * ending the process while the turn reported success.
+ *
+ * The latency the old rule protected is now the SINK's choice, where it
+ * belongs: buffer internally and return synchronously to stay off the critical
+ * path, or return a promise and be awaited. Either satisfies the type.
+ *
+ * A sink that FAILS terminates the turn, on every family. Where trails are
+ * written is swappable (§7.1); that they are written is not, and a trail that
+ * silently stopped being written is the failure the invariant exists to catch.
+ *
+ * One ergonomic consequence, worth knowing before it surprises you: a bare
+ * `void` return type accepts a function returning ANYTHING, and the union does
+ * not inherit that rule. `access: (e) => log.push(e)` no longer compiles —
+ * `void log.push(e)`, or a block body, does. The error is at the type level
+ * and immediate, which is the trade for a contract that no longer lies about
+ * what it accepts.
+ */
+interface AuditLog {
+    access(e: AccessEvent): void | Promise<void>;
+    routing(e: RoutingEvent): void | Promise<void>;
+    cost(e: CostEvent): void | Promise<void>;
+    /** §7.3 — what the model was shown from memory, by reference. */
+    recall(e: RecallEvent): void | Promise<void>;
+    /**
+     * §7.3, spec 029 — what a `step:pre` hook changed about the model request,
+     * by shape. Fires only when a hook actually touched one of the five fields,
+     * so an agent with no rewriting hooks never calls it. Required all the same:
+     * whether a trail is written is not a product choice.
+     */
+    context(e: ContextEvent): void | Promise<void>;
+}
+/**
+ * A trail sink failed — spec 027 review. TYPED, because "a failing audit sink
+ * terminates the turn" has to hold on every path, and the loop classifies
+ * errors by type: an untyped throw from a sink inside a delegate was caught by
+ * the tool-dispatch handler and became tool-result DATA, so the turn reported
+ * success with a trail silently unwritten. The same shape that made
+ * `SpendAccountingError` typed, for the same reason.
+ */
+declare class AuditSinkError extends Error {
+    readonly family: "access" | "routing" | "cost" | "recall" | "context";
+    readonly cause: unknown;
+    constructor(family: "access" | "routing" | "cost" | "recall" | "context", cause: unknown);
+}
+/** Consent state for one integration — §6.8, §10. */
+interface Consent {
+    granted: boolean;
+    /** ISO 8601 of the grant/revocation. */
+    at?: string;
+    /** Version of the consent text the user acted on. */
+    version?: string;
+}
+/**
+ * Per-integration consent gate — §6.8. Capability seam (§7.1).
+ * DECISION: `integration` is a product-defined slug (e.g. "calendar");
+ * absence of a record must resolve to `{ granted: false }`, never throw.
+ */
+interface ConsentStore {
+    get(scope: Scope, integration: string): Promise<Consent>;
+}
+
+/**
+ * Session persistence — §6.6. Design inherited from the two production stores:
+ * transactional seq, chunking, TTL on the root doc, owner stamping for scoped
+ * purge. Sessions persist ONLY the neutral message format (§6.1).
+ *
+ * The long-context policy belongs to the HARNESS, not the store — and it is
+ * entry-time tool-output discipline plus windowing/summary at cache-cold
+ * boundaries, NEVER mid-history pruning: a consuming product measured pruning
+ * at +27% total cost (+99% cache writes) — see §6.6 and spec:
+ * tool-output-discipline.
+ */
+interface LoadOpts {
+    /**
+     * DECISION: §6.6 leaves LoadOpts open; Phase 0 defines only recency
+     * windowing. `limit` returns the LAST `limit` messages, still in
+     * chronological order — recency is what context assembly wants. A
+     * non-positive limit yields an empty history.
+     */
+    limit?: number;
+}
+/** Capability seam — §7.1. Exercised by the shared contract suite (§6). */
+interface SessionStore {
+    /**
+     * Appends entries atomically and in order (transactional seq — §6.6):
+     * concurrent appends to one session must never interleave or lose entries.
+     *
+     * PRECONDITION: every string in `entries`, keys included, is well-formed
+     * UTF-16. `runTurn` repairs each message as it is recorded (spec:
+     * well-formed-text), but only BEST-EFFORT — its catch keeps the unrepaired
+     * message — and a product writing here directly gets no such pass at all.
+     * `toWellFormedDeep` from this package is the remedy.
+     *
+     * ENFORCED by every adapter this package ships, and identically: a violation
+     * throws {@link import("./text").MalformedTextError} naming the offending
+     * entry and path, before anything is written. Spec 040 closed this; until
+     * then they DIVERGED — the in-memory store kept a lone surrogate while
+     * Postgres refused the write — and both contracts said "do not rely on
+     * either behaviour", which is not a contract. Refusing rather than repairing
+     * is the deliberate half: a store that silently rewrites the bytes of a
+     * record kept for years is worse than one that declines.
+     *
+     * A PRODUCT's own `SessionStore` is not covered by that sentence and owns
+     * the check itself — `assertWellFormed` is exported for exactly this, and
+     * the quickstart's store calls it. This distinction is not pedantry: the
+     * first draft of this paragraph said "every adapter", which read as every
+     * implementation, and the example in this repo was at that moment still
+     * accepting what Postgres rejects (spec 040 review).
+     */
+    append(scope: Scope, sessionId: string, entries: Msg[]): Promise<void>;
+    /**
+     * Chronological history. DECISION: an unknown session resolves to `[]`
+     * rather than throwing — "no history yet" and "no such session" are the
+     * same thing to a turn that is about to create one.
+     */
+    load(scope: Scope, sessionId: string, opts?: LoadOpts): Promise<Msg[]>;
+    /**
+     * LGPD/GDPR erasure — §6.6, §10. With `sessionId`, erases that session;
+     * without it, purges EVERY session in the scope (owner-stamped purge).
+     */
+    erase(scope: Scope, sessionId?: string): Promise<void>;
+    /**
+     * Drops the session's `tool_call` and `tool_result` blocks, keeping
+     * everything the user saw — spec 039.
+     *
+     * The split it serves: for a product whose conversations are a professional
+     * record kept for years, the tool traffic is the arguments and results of
+     * what the agent DID — richer, more sensitive, and useful for weeks rather
+     * than years. What the trail keeps is the metadata (§6.8); what this removes
+     * is the payload.
+     *
+     * TWO CONSTRAINTS, both enforced here rather than documented and hoped for.
+     *
+     * `inactiveSince` is REQUIRED, and the store refuses when the session holds
+     * an entry newer than it — reporting `expired: false`, never throwing.
+     * Removing blocks from a session still in use is the mid-history pruning
+     * §6.6 forbids, and the cost is measured rather than feared: a consuming
+     * product ran that experiment and saw total cost +27% with cache writes
+     * +99%, because prompt caching is a prefix match and removing any byte
+     * mid-history rewrites everything after it. On a session nobody will resume
+     * the same removal is free, and that condition is the entire difference.
+     *
+     * ALL the tool blocks go, or none. Not "the ones older than X" — spec 026
+     * taught the loop to pair every `tool_call` with a `tool_result` on every
+     * exit path, and a provider answers 400 for a dangling `tool_use`, so a
+     * partial expiry would manufacture exactly that. All-or-nothing is paired by
+     * construction.
+     *
+     * A message left with no blocks is removed. `media` blocks survive: they are
+     * `MediaRef` pointers rather than content, they are user-facing, and the
+     * storage holding the bytes has its own lifecycle that is not Alma's.
+     *
+     * SCHEDULING IS THE PRODUCT'S. This is one session; enumerating which
+     * sessions are stale is a cross-scope question, and every contract here is
+     * scope-bound by design (§6.1).
+     */
+    expireToolTraffic(scope: Scope, sessionId: string, opts: {
+        inactiveSince: string;
+    }): Promise<ToolTrafficExpiry>;
+}
+/** What one {@link SessionStore.expireToolTraffic} pass did — spec 039. */
+interface ToolTrafficExpiry {
+    /** Blocks removed. */
+    blocks: number;
+    /** Messages left with nothing, and therefore removed entirely. */
+    messages: number;
+    /**
+     * False when the session was still active and nothing was touched.
+     *
+     * A refusal, not an error: a sweep over a thousand sessions where forty are
+     * still live is the normal case. A throw would make the caller write a
+     * try/catch per session and swallow it — and a swallowed refusal is how you
+     * stop noticing that nothing is being expired.
+     */
+    expired: boolean;
+}
+
+/**
+ * Lifecycle events — §7.2. A small, CLOSED set of typed hooks on the turn
+ * flow — enough for guards, telemetry, and extra policy without touching the
+ * loop. Deliberately not extensible: a new model-visible input requires a new
+ * logged event type (§7.3), never a side channel.
+ *
+ * Interceptors are capability-narrowing ONLY: a hook can veto, rewrite, or
+ * annotate, but it can never register tools outside the scoped registry,
+ * widen a scope, or bypass audit/budget. The loop enforces this by
+ * construction — hooks receive no registry or store handles.
+ *
+ * "By construction" became true of `step:pre` only in spec 029. Until then a
+ * hook could raise `maxTokens` — not audit or budget, but how far one step may
+ * spend before the cap gets its chance: a widening the sentence above already
+ * forbade and nothing enforced. See {@link StepDecision} for the backstop that
+ * now holds it.
+ */
+/** How the turn was initiated — §8, §9. */
+type TurnTrigger = "user" | "routine" | "system";
+/**
+ * §9 step 4 — every turn ends with exactly one of these.
+ *
+ * `busy` joined the original four in spec 030: a turn that waited out
+ * `leaseWaitMs` for a session another turn was holding. It is its own reason
+ * because this union is the vocabulary every product switches on — a lease
+ * timeout arriving as `"error"` with a magic message would be untypeable, and
+ * it is the one terminal state where retrying the SAME turn is the right move.
+ */
+type TerminalReason = "completed" | "budget_exceeded" | "cancelled" | "error" | "busy";
+interface TurnStartEvent {
+    scope: Scope;
+    sessionId: string;
+    turnId: string;
+    trigger: TurnTrigger;
+    /** ISO 8601. */
+    at: string;
+}
+interface TurnEndEvent {
+    scope: Scope;
+    sessionId: string;
+    turnId: string;
+    terminalReason: TerminalReason;
+    usage: Usage;
+    costUsd: number;
+    /**
+     * Model calls the TURN made — spec 032. The same index `TurnEvent.step`
+     * carries and `maxSteps` bounds; a delegate's own steps are not counted, or
+     * the number and its ceiling would measure different things.
+     */
+    steps: number;
+    /**
+     * Wall-clock of the turn's own work, milliseconds — spec 032. Excludes the
+     * session lease wait (spec 030): a caller holds both ends of its `runTurn`
+     * call and can already measure total time, so reporting the WORK is what
+     * gives it the split it cannot reconstruct.
+     */
+    durationMs: number;
+    at: string;
+}
+/** `step:pre` — what the model is about to see, before it is sent. */
+interface StepPreEvent {
+    scope: Scope;
+    sessionId: string;
+    turnId: string;
+    request: ModelRequest;
+}
+/**
+ * DECISION: outcome vocabulary for `step:pre` — rewrite happens by passing a
+ * modified event to `next()`; rejecting aborts the step with an auditable
+ * reason.
+ *
+ * The core applies a BACKSTOP after the chain returns, the way the registered
+ * ceiling still applies after every `tool:post` hook (see
+ * {@link ToolAnnotation}) — spec 029. `model` and `tools` are repinned,
+ * `maxTokens` is honored only when it NARROWS, and whichever of the five
+ * fields the chain touched is written to the `context` trail, honored or
+ * refused (§7.3).
+ *
+ * Rewrite by passing a modified event, never by mutating `event.request`: the
+ * request handed to the chain is FROZEN, so an in-place assignment throws. It
+ * used to succeed silently, bypassing both the backstop and the trail.
+ */
+type StepDecision = {
+    action: "proceed";
+    request: ModelRequest;
+} | {
+    action: "reject";
+    reason: string;
+};
+/** `tool:pre` — a tool call the model has requested, before dispatch. */
+interface ToolPreEvent {
+    scope: Scope;
+    sessionId: string;
+    turnId: string;
+    call: {
+        id: string;
+        name: string;
+        input: unknown;
+    };
+    spec: ToolSpec;
+}
+type ToolPreDecision = {
+    action: "proceed";
+    input: unknown;
+} | {
+    action: "veto";
+    reason: string;
+};
+/** `tool:post` — a tool result, before it is appended to the conversation. */
+interface ToolPostEvent {
+    scope: Scope;
+    sessionId: string;
+    turnId: string;
+    call: {
+        id: string;
+        name: string;
+        input: unknown;
+    };
+    result: {
+        output: unknown;
+        isError: boolean;
+    };
+}
+/**
+ * What a `tool:post` hook contributes to a tool result — §7.2, spec:
+ * tool-output-discipline. `advisory` appends context (the canonical
+ * loop-hygiene use); `output` REPLACES what the model will see — the entry
+ * point where a product swaps an oversized result for the relevant slice
+ * plus a pointer, BEFORE it enters the transcript (removal later costs more
+ * than it saves — §6.6). Hooks run in order, each seeing the output as left
+ * by the previous. §7.3 holds in both directions: the session persists
+ * exactly what the model saw, and the replaced original is retained nowhere.
+ * The registered ceiling still applies after every hook — the core backstop.
+ */
+interface ToolAnnotation {
+    advisory?: string;
+    /**
+     * Replaces the output the model will see — and the session will persist.
+     * A PRESENT key replaces even when its value is undefined (normalized to
+     * null), so a redaction hook can suppress a result outright.
+     */
+    output?: unknown;
+}
+/** Observe-mode hook — may be async; the loop awaits but never interprets it. */
+type Observer<E> = (event: E) => void | Promise<void>;
+/**
+ * Intercept-mode hook, middleware-style — §7.2: call `next()` to delegate
+ * down the chain (optionally with a rewritten event), or return without
+ * calling it to short-circuit.
+ */
+type Interceptor<E, R> = (event: E, next: (event: E) => Promise<R>) => Promise<R>;
+/** The closed hook set — §7.2. Keys are the event names, verbatim. */
+interface LifecycleHooks {
+    "turn:start"?: Observer<TurnStartEvent>;
+    "turn:end"?: Observer<TurnEndEvent>;
+    "step:pre"?: Interceptor<StepPreEvent, StepDecision>;
+    "tool:pre"?: Interceptor<ToolPreEvent, ToolPreDecision>;
+    "tool:post"?: (event: ToolPostEvent) => ToolAnnotation | undefined | Promise<ToolAnnotation | undefined>;
+}
+
+/**
+ * Turn coordination — spec 030. Two failures the loop could not see, closed by
+ * one seam.
+ *
+ * A webhook that redelivers because it never saw a 200 used to make the
+ * harness run the turn again: the message sent twice, the memory written
+ * twice, the spend charged twice. And two DIFFERENT messages arriving on one
+ * session concurrently both loaded the same history and both appended, so the
+ * second turn never saw the first.
+ *
+ * The first needs an idempotency record; the second needs serialization.
+ * They are one seam because the lease is what makes the claim simple: with the
+ * session serialized, a claim has exactly two outcomes — fresh, or a completed
+ * turn to replay — and an in-flight claim is only reachable after a crash,
+ * never through concurrency.
+ *
+ * The idiom is `AuditLog`'s and `SpendStore`'s: WHERE a turn's coordination
+ * record lives is swappable (§7.1); THAT a turn is claimed before it runs is
+ * not.
+ */
+/**
+ * Addresses one turn's idempotency record.
+ *
+ * DECISION (spec 030): keyed by the full scope AND the session, never by
+ * `idempotencyKey` alone. A key is unique only within the transport that
+ * issued it, and a global key space would let one tenant's retry collide with
+ * another's — the isolation boundary applies here like everywhere else (§6.1).
+ */
+interface TurnKey {
+    scope: Scope;
+    sessionId: string;
+    /** Caller-supplied delivery identity — typically the inbound message id. */
+    idempotencyKey: string;
+}
+interface LeaseOpts {
+    /**
+     * How long the lease is held before it expires on its own. Must exceed a
+     * realistic worst-case turn: a live turn whose lease expires gets it stolen
+     * and interleaves, which is the failure the lease exists to prevent. It is a
+     * ceiling on how long a CRASHED holder can block a session, so it cannot
+     * simply be enormous either.
+     */
+    ttlMs: number;
+    /** How long to wait for a busy session before giving up. */
+    waitMs: number;
+}
+/**
+ * Proof that this holder owns the session — spec 030.
+ *
+ * The token exists so {@link TurnStore.release} can refuse a STALE one. A
+ * holder whose lease already expired must never release the lease the next
+ * turn is now holding: that would serialize nothing while appearing to, which
+ * is worse than no lease at all.
+ */
+interface TurnLease {
+    readonly token: string;
+    /** ISO 8601. */
+    readonly expiresAt: string;
+}
+/**
+ * The replayable subset of a finished turn — spec 030.
+ *
+ * Deliberately NOT the loop's whole `TurnResult`. `capsCrossed`,
+ * `accountingError` and `budgetExceeded` describe the ORIGINAL run's
+ * infrastructure and enforcement state; re-reporting a cap crossing on every
+ * retry would double-count in exactly the product-side alerting spec 019
+ * built. What replays is what the turn produced, not how it went.
+ *
+ * It holds `reply` verbatim, which makes it a COPY SURFACE in the sense spec
+ * 010 defines — the price of replaying rather than refusing, paid explicitly.
+ * {@link TurnStore.erase} is how §10 reaches it.
+ */
+interface CompletedTurn {
+    reply: Msg;
+    terminalReason: TerminalReason;
+    stopReason: StopReason | null;
+    usage: Usage;
+    costUsd: number;
+    /**
+     * What the original turn cost in steps and milliseconds — spec 032, carried
+     * for the same reason `usage` and `costUsd` are. A replay reporting
+     * `durationMs: 0` would be the same lie as one reporting `costUsd: 0`.
+     */
+    steps: number;
+    durationMs: number;
+    /** The original turn's id — correlation across the trails it already wrote. */
+    turnId: string;
+    /**
+     * Present when `terminalReason` is `"error"` — spec 033. It replays where
+     * `capsCrossed`, `accountingError` and `budgetExceeded` deliberately do not,
+     * and the difference is what each describes: those three are the original
+     * run's INFRASTRUCTURE and enforcement state, where re-reporting on every
+     * retry would double-count in a product's alerting. This is the turn's
+     * OUTCOME. A replayed failure that says `"error"` with no reason is strictly
+     * less than the turn it replays, and no double-counting argument applies to a
+     * string.
+     */
+    error?: string;
+    /** ISO 8601 of the ORIGINAL turn. */
+    at: string;
+}
+/**
+ * `fresh` — nothing has run under this key; the turn proceeds.
+ * `replay` — a turn already finished under it; its result is returned as-is.
+ *
+ * A turn that ended `error` or `budget_exceeded` still COMPLETES its claim, so
+ * a retry replays that outcome. A failed turn is a result, not an invitation
+ * to run it again and charge again.
+ */
+type TurnClaim = {
+    status: "fresh";
+} | {
+    status: "replay";
+    completed: CompletedTurn;
+};
+/**
+ * Capability seam — §7.1, spec 030. Exercised by `describeTurnStoreContract`.
+ *
+ * Configured or not, with no half-protected mode: a product that wires this
+ * decided double-execution is unacceptable, so a store failure terminates the
+ * turn rather than degrading to "unprotected but running" — the fail-closed
+ * posture `SpendAccountingError` takes under a block cap.
+ */
+interface TurnStore {
+    /**
+     * Takes the session, waiting up to `opts.waitMs` for a busy one. Resolves
+     * `null` when the wait expires — the caller ends the turn `"busy"` rather
+     * than proceeding unserialized.
+     *
+     * Concurrent callers must see exactly ONE winner. That is the property the
+     * whole seam stands on, and it is the store's job: a lease handed to two
+     * holders serializes nothing.
+     */
+    acquire(scope: Scope, sessionId: string, opts: LeaseOpts): Promise<TurnLease | null>;
+    /**
+     * Releases the session. IDEMPOTENT, and a stale token is a no-op rather than
+     * another holder's release (see {@link TurnLease}).
+     */
+    release(scope: Scope, sessionId: string, lease: TurnLease): Promise<void>;
+    /** Records the attempt and reports whether this turn has already run. */
+    claim(key: TurnKey): Promise<TurnClaim>;
+    /** Stores the replayable record. Every later claim under this key replays it. */
+    complete(key: TurnKey, completed: CompletedTurn): Promise<void>;
+    /**
+     * Drops a claim so a genuine retry may run — the path a turn takes when it
+     * could not produce a result to store at all.
+     */
+    abandon(key: TurnKey): Promise<void>;
+    /**
+     * §10 erasure. With `sessionId`, clears that session's lease and records;
+     * without it, every session in the scope. Mirrors `SessionStore.erase`
+     * deliberately: a product erasing a session must erase its turn records in
+     * the same breath, or the reply survives the erasure that removed it from
+     * the transcript.
+     */
+    erase(scope: Scope, sessionId?: string): Promise<void>;
+}
+/**
+ * A `TurnStore` operation failed — spec 030. Its own class for the reason
+ * {@link import("./budget").SpendAccountingError} has one: the loop classifies
+ * errors by TYPE, and inside a delegate an untyped throw is caught by the
+ * tool-dispatch handler and becomes tool DATA, so a turn whose coordination
+ * broke would report success.
+ */
+declare class TurnStoreError extends Error {
+    readonly operation: "acquire" | "release" | "claim" | "complete" | "abandon";
+    readonly cause: unknown;
+    constructor(operation: "acquire" | "release" | "claim" | "complete" | "abandon", cause: unknown);
+}
+
+export { type ToolPostEvent as $, type AuditLog as A, type BudgetCaps as B, type CompletedTurn as C, type ProviderId as D, type RoutingEvent as E, type RoutingIntent as F, SENSITIVITY_LEVELS as G, type SessionStore as H, type Interceptor as I, SpendAccountingError as J, type SpendKey as K, type LeaseOpts as L, type ModelRef as M, type SpendStore as N, type Observer as O, type PersistentCap as P, type SpendTotals as Q, type RecallEvent as R, type Sensitivity as S, type Tier as T, type Usage as U, type StepDecision as V, type StepPreEvent as W, type StopReason as X, type SystemBlock as Y, type TerminalReason as Z, type ToolAnnotation as _, type Scope as a, type ToolPreDecision as a0, type ToolPreEvent as a1, type ToolSpec as a2, type ToolTrafficExpiry as a3, type TurnClaim as a4, type TurnEndEvent as a5, type TurnKey as a6, type TurnLease as a7, type TurnStartEvent as a8, type TurnStore as a9, TurnStoreError as aa, type TurnTrigger as ab, scopePath as ac, sensitivityExceeds as ad, type ModelPrice as b, type AccessEvent as c, AuditSinkError as d, type Block as e, BudgetExceededError as f, type BudgetGuard as g, type Consent as h, type ConsentStore as i, type ContextEvent as j, type ContextField as k, type ContextShape as l, type CostEvent as m, InvalidScopeError as n, type LifecycleHooks as o, type LoadOpts as p, type MediaKind as q, type MediaRef as r, type ModelChoice as s, type ModelClient as t, type ModelEvent as u, type ModelPolicy as v, type ModelRequest as w, type Msg as x, type MsgMeta as y, type PersistentCapName as z };