@dsh-enhanced/assistant-work-items 0.0.0-stage → 0.1.67

package/lib/store.d.ts

@@ -0,0 +1,791 @@
+import { type WorkItemContinuationInput, type WorkItemContinuationRecord } from './continuation-record.js';
+import { type WorkItemDiagnosisPlan } from './diagnosis-contract.js';
+import type { WorkItemClaimRecord, WorkItemClaimState, WorkItemDeliveryState, WorkItemDispatchRecord, WorkItemEventRecord, WorkItemFollowRecord, WorkItemFollowUpOwnResult, WorkItemFollowUpRecord, WorkItemPolicyNotice, WorkItemAcceptanceBinding, WorkItemAcceptanceVerdict, WorkItemAcceptanceBlockReason, WorkItemAcceptanceGateExpectation, WorkItemLateAcceptanceBinding, WorkItemOutcomeEvidence, WorkItemOutcomeEvidenceReason, WorkItemOutcomeEvidenceState, WorkItemOutcomeRecord, WorkItemOutcomeView, WorkItemRecord, WorkItemReportRecord, WorkItemReportStatus, WorkItemResumeContext, WorkItemState, WorkItemThreadClosure } from './types.ts';
+import type { WorkItemIntakeCandidate, WorkItemIntakeRecord, WorkItemIntakeResult } from './intake.ts';
+import type { WorkItemIntakeEvaluationRecord } from './intake-evaluation.ts';
+import type { WorkItemIntakeAdmissionRecord } from './intake-admission.ts';
+/** Waiting reasons that mean an admission mandate failed revalidation. */
+declare const AUTHORITY_REVOKED = "authority-revoked";
+declare const AUTHORITY_UNAVAILABLE = "authority-unavailable";
+/** One validated follow, already resolved to its registered source at admission. */
+/** Append-only event kinds for WP21 notices and follow-up ownership (no schema change). */
+export declare const POLICY_NOTICE_EVENT = "policy-change-noticed";
+export declare const FOLLOW_UP_OWNED_EVENT = "follow-up-owned";
+export declare const FOLLOW_UP_PROCESSED_EVENT = "follow-up-processed";
+export declare const FOLLOW_UP_RELEASED_EVENT = "follow-up-released";
+/** WP21 slice 4: the independent verifier's verdict, read back once per bound item. */
+export declare const ACCEPTANCE_VERIFIED_EVENT = "acceptance-verified";
+/** WP21 slice 6: a worker run's contract bound after wake; the latest row is current. */
+export declare const ACCEPTANCE_BOUND_EVENT = "acceptance-bound";
+/** Message of the fail-closed storage error for a malformed latest `acceptance-bound` row. */
+export declare const MALFORMED_ACCEPTANCE_BINDING = "recorded acceptance binding is malformed";
+/** One dispatched, unbound item whose current worker run may be late-bound. */
+export interface WorkItemLateAcceptanceCandidate {
+    readonly item: WorkItemRecord;
+    readonly automationId: string;
+    readonly occurrenceId: string;
+    /** Earliest time this generation's run can have started: max(item createdAt, dispatch occurredAt). */
+    readonly notBefore: number;
+}
+/** Position of one released follow-up in release order. */
+export interface WorkItemFollowUpCursor {
+    readonly recordedAt: number;
+    readonly itemId: string;
+    readonly sequence: number;
+}
+export interface WorkItemFollowInput {
+    readonly kind: string;
+    readonly ref: string;
+    /** Registered source key; equals `kind` and is persisted for audit. */
+    readonly source: string;
+    /** Registration generation at admission; a newer one cannot close this row. */
+    readonly sourceGeneration: string;
+}
+/**
+ * Deterministic external event identity for one dispatch generation.
+ *
+ * Generation 0 is the admission identity and equals the item id, so existing
+ * rows keep their exact `(event_id, occurred_at)` pair. Later generations append
+ * a suffix, because the automation intake dedupes occurrences by
+ * `(automationId, eventId, occurredAt)` and would replay a completed occurrence
+ * instead of starting a new run.
+ */
+export declare function dispatchEventId(itemId: string, generation: number): string;
+/** Create a mode-0700 directory and prove it is not a link or group-writable. */
+export declare function preparePrivateDirectory(path: string): void;
+/** Create the SQLite file with mode 0600 before SQLite opens it. */
+export declare function prepareDatabaseFile(path: string): void;
+export interface ClaimResult {
+    readonly item: WorkItemRecord;
+    readonly claim: WorkItemClaimRecord;
+    readonly replayed: boolean;
+}
+export interface ReportResult {
+    readonly item: WorkItemRecord;
+    readonly report: WorkItemReportRecord;
+    readonly replayed: boolean;
+}
+export interface ReclaimResult {
+    readonly requeued: readonly string[];
+    readonly blocked: readonly string[];
+}
+/** Which signal drove a withdrawal; recorded on every retired item's event. */
+export interface WithdrawAttribution {
+    readonly sourceId: string;
+    readonly externalId: string;
+    readonly observedAt: number;
+}
+/** Result of retiring every open item of one canonical dedup key. */
+export interface WithdrawDedupResult {
+    readonly outcome: 'withdrawn' | 'settled' | 'absent';
+    /** Items actually retired (`withdrawn`), the newest item (`settled`), or none. */
+    readonly items: readonly WorkItemRecord[];
+}
+export interface WorkItemStoreStats {
+    readonly schemaVersion: number;
+    readonly items: number;
+    readonly openItems: number;
+    readonly reports: number;
+    readonly dispatches: number;
+    readonly outcomes: number;
+    readonly pendingOutcomes: number;
+    readonly unverifiedOutcomes: number;
+    /** Latest settled revisions still waiting for one trusted Evaluation append. */
+    readonly evaluationPending: number;
+    readonly evaluationExported: number;
+    readonly evaluationSkipped: number;
+    /** Persisted followed-thread rows (open and closed). */
+    readonly follows: number;
+    /** Open items admitted before the revalidation basis existed (schema < v7). */
+    readonly authorityLegacy: number;
+    /** Open items parked because their admission mandate failed revalidation. */
+    readonly authorityParked: number;
+}
+/**
+ * Durable execution facts one work item can contribute to an Evaluation claim.
+ *
+ * Only counts the ledger already records are exposed. No provider token/cost
+ * usage is read here: this ledger owns no run-usage contract, while the
+ * automation side records those figures for the same run scope, so copying them
+ * would double-count cost. Zero counts are omitted so a quiet item stays compact.
+ */
+export interface WorkItemExecutionMetrics {
+    readonly latencyMs: number;
+    readonly retries?: number;
+    readonly claims?: number;
+    readonly reports?: number;
+    readonly waitingReports?: number;
+    readonly unknownDispatches?: number;
+    readonly claimExpiries?: number;
+}
+/**
+ * Single-writer SQLite ledger.
+ *
+ * Every mutation runs inside `BEGIN IMMEDIATE`; the database file is created
+ * 0600 next to a 0700 directory, WAL keeps readers unblocked, and schema
+ * upgrades are bounded to the single-writer upgrade boundary at open time.
+ */
+export declare class WorkItemStore {
+    #private;
+    constructor(path: string, options?: {
+        now?: () => number;
+        settleWindowMs?: number;
+    });
+    /** Keep report/plan sources writer-fenced through a synchronous Host commit.
+     * Delivery and Evaluation own their outer locks; this method never acquires
+     * either peer or starts any execution. */
+    withFeedbackSourceFence<T>(work: () => T): T;
+    close(): void;
+    get closed(): boolean;
+    stats(): WorkItemStoreStats;
+    /**
+     * Record one classified intake candidate exactly once.
+     *
+     * A replay of the same `(source, sourceEventId)` returns the original row
+     * unchanged, with no second write. A new event whose content digest matches
+     * an earlier `stored` row of the same source and at least the same strength
+     * is recorded as `duplicate`; a stronger repeat (for example the same text
+     * re-posted with a mention) is never suppressed by a weaker original.
+     * This method writes only the intake table; it admits and dispatches nothing.
+     */
+    recordIntake(candidate: WorkItemIntakeCandidate): WorkItemIntakeResult;
+    getIntake(source: string, sourceEventId: string): WorkItemIntakeRecord | undefined;
+    /**
+     * Append one evaluation result exactly once per `(row, rule, Policy version)`.
+     * The intake row must be a `stored` `inferred` row whose content digest is the
+     * evaluated source digest. A replay returns the original row unchanged.
+     */
+    recordIntakeEvaluation(record: Omit<WorkItemIntakeEvaluationRecord, 'recordedAt'>): {
+        readonly record: WorkItemIntakeEvaluationRecord;
+        readonly replayed: boolean;
+    };
+    getIntakeEvaluation(source: string, sourceEventId: string, ruleId: string, policyVersion: string): WorkItemIntakeEvaluationRecord | undefined;
+    /** Every persisted evaluation of one intake row, oldest first; read-only. */
+    listIntakeEvaluations(source: string, sourceEventId: string): readonly WorkItemIntakeEvaluationRecord[];
+    /** Status counts over the evaluation table; read-only. */
+    countIntakeEvaluations(): Readonly<Record<WorkItemIntakeEvaluationRecord['status'], number>>;
+    /**
+     * Append one admission outcome exactly once per evaluation row. The
+     * evaluation must exist and would accept. A replay returns the first row
+     * unchanged, so a later outcome never rewrites an earlier one.
+     */
+    recordIntakeAdmission(record: Omit<WorkItemIntakeAdmissionRecord, 'recordedAt'>): WorkItemIntakeAdmissionRecord;
+    getIntakeAdmission(source: string, sourceEventId: string, ruleId: string, policyVersion: string): WorkItemIntakeAdmissionRecord | undefined;
+    /** Every admission outcome of one intake row, oldest first; read-only. */
+    listIntakeAdmissions(source: string, sourceEventId: string): readonly WorkItemIntakeAdmissionRecord[];
+    /** Oldest accepting evaluations without an admission row, at most `limit`; read-only. */
+    pendingIntakeAdmissions(limit: number): readonly WorkItemIntakeEvaluationRecord[];
+    /**
+     * The intake decision that admitted one item, if any: its first
+     * `admitted` (or crash-recovered `replayed`) admission row joined with the
+     * evaluation it acted on.
+     * Read-only. Served by the partial `item_id` index (schema 13).
+     */
+    intakeProvenance(itemId: string): Readonly<{
+        admission: WorkItemIntakeAdmissionRecord;
+        evaluation: WorkItemIntakeEvaluationRecord;
+    }> | undefined;
+    /** Items admitted from intake at or after `since`; the hourly intake budget. */
+    countIntakeAdmitted(since: number): number;
+    /** Outcome counts over the admission table; read-only. */
+    countIntakeAdmissions(): Readonly<Record<WorkItemIntakeAdmissionRecord['outcome'], number>>;
+    /** Decision counts over the intake table; read-only. */
+    countIntake(): Readonly<Record<WorkItemIntakeRecord['decision'], number>>;
+    /** SQL owner filtering precedes keyset pagination; no recovery or writes. */
+    listOwnerItems(owner: Readonly<{
+        principalId: string;
+        principalRecordId: string;
+        principalVersion: number;
+        workspace: string;
+        preset: string;
+        ownerRouteId: string;
+        workerAutomationId: string;
+        continuationAutomationId?: string;
+        generation: number;
+        bindingVersion: number;
+    }>, after: Readonly<{
+        createdAt: number;
+        id: string;
+    }> | undefined, limit: number, itemId?: string): readonly WorkItemRecord[];
+    /** Exact UTF-8 body bytes after the caller has selected an owner-filtered item. */
+    ownerRecallText(itemId: string, revision?: number): string;
+    findItemById(itemId: string): WorkItemRecord | undefined;
+    findItemByDedup(dedupKey: string, dedupBucket: number): WorkItemRecord | undefined;
+    /**
+     * Latest item admitted for one canonical dedup key, across all windows.
+     *
+     * The dedup window forgets history when a bucket rolls over; this lookup is
+     * what lets a correction or withdrawal of an already-settled signal stay
+     * settled instead of reviving a completed item.
+     */
+    findLatestItemByDedupKey(dedupKey: string): WorkItemRecord | undefined;
+    /**
+     * The item whose frozen mandate already binds `contractId`, if any. One
+     * acceptance contract settles exactly one item. A full scan over the stored
+     * basis JSON (no index, no schema change); unreadable bases never match.
+     */
+    findItemByAcceptanceContract(contractId: string): WorkItemRecord | undefined;
+    /**
+     * WP21 slice 6 candidates: items whose worker dispatch is `dispatched` to
+     * `workerAutomationId` under their current occurrence, whose mandate binds
+     * no contract, that have no verdict yet and no `acceptance-bound` row for
+     * that occurrence. Never-run, withdrawn, failed and dropped items are out.
+     * (created_at, id) order strictly after `after`; bounded scan, no schema change.
+     */
+    listLateAcceptanceCandidates(workerAutomationId: string, after: Readonly<{
+        createdAt: number;
+        id: string;
+    }> | null, limit: number): readonly WorkItemLateAcceptanceCandidate[];
+    /** The current (latest) late acceptance binding of one item, if any; malformed rows fail closed. */
+    lateAcceptanceBinding(itemId: string): WorkItemLateAcceptanceBinding | undefined;
+    /**
+     * Append one late acceptance binding for the item's current occurrence.
+     * Refused for a mandate-bound or already-verified item, for a stale
+     * occurrence, and for a contract another item already binds. The same
+     * occurrence and contract again is idempotent; a later occurrence's row
+     * supersedes earlier ones. State, lease and mandate are untouched.
+     */
+    recordLateAcceptanceBinding(input: Readonly<{
+        itemId: string;
+        occurrenceId: string;
+        binding: WorkItemAcceptanceBinding;
+    }>): Readonly<{
+        binding: WorkItemLateAcceptanceBinding;
+        created: boolean;
+    }>;
+    /**
+     * Executed (`ready`, attempt ≥ 1) items whose frozen mandate binds an
+     * acceptance contract, or whose latest late binding is for the item's
+     * current occurrence, and that have no recorded verdict yet, in
+     * (created_at, id) order strictly after `after`. A bounded full scan over
+     * the stored basis JSON, like `findItemByAcceptanceContract` (no schema change).
+     */
+    listUnsettledAcceptanceItems(after: Readonly<{
+        createdAt: number;
+        id: string;
+    }> | null, limit: number): readonly WorkItemRecord[];
+    /**
+     * WP21 slice 8 (`acceptance.holdReport`): executed items whose latest report
+     * is a terminal `ready` self-report that has not been handed to Delivery and
+     * that is either still waiting for the verifier (`ready`) or was moved to
+     * `blocked` by the verdict gate (`acceptance-*`). One row per item, oldest
+     * report first. `after` is the `(recordedAt, itemId)` keyset position of the
+     * previous page, so a full page advances the caller's in-memory round-robin
+     * position instead of rescanning rows that are still waiting. Read-only and
+     * bounded; no schema change.
+     */
+    listHeldAcceptanceReports(limit: number, after?: Readonly<{
+        recordedAt: number;
+        itemId: string;
+    }>): readonly Readonly<{
+        item: WorkItemRecord;
+        report: WorkItemReportRecord;
+    }>[];
+    /** Read one durable key/value row from the schema-meta table. */
+    meta(key: string): string | null;
+    /** Persist one durable key/value row; no schema change is required for it. */
+    setMeta(key: string, value: string): void;
+    /** Full SQLite bytes; TEXT projection is insufficient for authority-bearing JSON. */
+    readCanonicalMeta(key: string): unknown;
+    /** Only the exact first admitted event may confer a diagnostic plan. Never scan later events for one. */
+    readDiagnosisPlan(itemId: string): Readonly<WorkItemDiagnosisPlan> | undefined;
+    diagnosisInterventionPending(itemId: string): boolean;
+    diagnosisInterventionItems(limit?: number): readonly WorkItemRecord[];
+    diagnosisExplicitlyDisposed(itemId: string): boolean;
+    clearDiagnosisIntervention(itemId: string): void;
+    /** Locate a real report, then prove its released/completed claim using complete NUL-delimited bytes. */
+    diagnosisReportOccurrence(itemId: string, revision: number): Readonly<{
+        itemId: string;
+        revision: number;
+        status: string;
+        occurrenceId: string;
+    }>;
+    /** Row order is database-owned; wall-clock jumps cannot choose a different last report. */
+    latestWorkerDiagnosisReport(workerId?: string): Readonly<{
+        itemId: string;
+        revision: number;
+        status: string;
+        occurrenceId: string;
+    }> | undefined;
+    /** Drop one durable key/value row when its cursor no longer applies. */
+    deleteMeta(key: string): void;
+    /** Count latest outcome revisions in one evidence state. */
+    countLatestOutcomes(evidenceState: WorkItemOutcomeEvidenceState): number;
+    findItemByOccurrence(occurrenceId: string): WorkItemRecord | undefined;
+    listItems(options?: {
+        states?: readonly WorkItemState[];
+        includeObserved?: boolean;
+        limit?: number;
+    }): readonly WorkItemRecord[];
+    lastAdmitAt(kind?: string): number | null;
+    /** Latest successful dispatch timestamp, for bounded health reporting. */
+    lastDispatchedAt(): number | null;
+    countItemsSince(createdAt: number): number;
+    countOpenItems(): number;
+    /** Open items admitted before schema v7, i.e. with no persisted mandate. */
+    countAuthorityLegacy(): number;
+    /** Open items parked because their admission mandate failed revalidation. */
+    countAuthorityParked(): number;
+    /** Follows of one item, in admission order (their stable position). */
+    follows(itemId: string): readonly WorkItemFollowRecord[];
+    countOpenFollows(itemId: string): number;
+    /** Global follow counts for health reporting (open rows of live items only). */
+    countFollows(): {
+        open: number;
+        closed: number;
+    };
+    /**
+     * Identity of every open follow on a live item, for health projections.
+     *
+     * A follow row outlives the item it parked when that item is withdrawn or
+     * otherwise settled by another path (no resolver ever observed those threads).
+     * Reporting those rows as gaps would make health permanently degraded over
+     * dead items, so only follows of still-open items count.
+     */
+    openFollowIdentities(): readonly {
+        readonly source: string;
+        readonly sourceGeneration: string;
+    }[];
+    /** Open follows across live items, oldest first, bounded for diagnostics. */
+    listOpenFollows(limit: number): readonly WorkItemFollowRecord[];
+    /**
+     * Close one open follow exactly once.
+     *
+     * The CAS on `state = 'open'` is what makes duplicate and out-of-order
+     * closures harmless: a second observation of the same closure changes no row
+     * and reports `undefined`, so no settlement signal can be produced twice.
+     */
+    closeFollow(itemId: string, position: number, closure: WorkItemThreadClosure, now?: number): WorkItemFollowRecord | undefined;
+    /**
+     * Waiting items that owe a thread-closure settlement.
+     *
+     * `waiting` with a terminal `last_report_status` is produced only by the
+     * deferred report branch, so this is exactly the deferred set. Selecting on
+     * the report status rather than on open follow rows keeps the sweep
+     * crash-safe: a crash after closing the last follow but before appending the
+     * outcome still finds the item on the next pass. A live lease is excluded
+     * (additionally to the state check) so a re-claimed item is never settled
+     * underneath its new worker.
+     */
+    itemsAwaitingThreadClosure(limit: number): readonly WorkItemRecord[];
+    /**
+     * Settle one deferred item because every followed thread is closed.
+     *
+     * This appends at most one outcome revision, and a second call is a no-op.
+     * The transition reuses the recorded terminal report status, so the item
+     * still ends in the state the worker reported; the closure itself is never
+     * treated as evidence of objective achievement.
+     */
+    settleThreadClosure(itemId: string): WorkItemOutcomeRecord | undefined;
+    /**
+     * Ambiguous sends that still describe an actionable gap.
+     *
+     * A failed row is dead weight once its item is terminal or observed (for
+     * example a withdrawal after an ambiguous send): no retry is owed and the
+     * owner already settled the item, so counting it would report a permanent
+     * false gap. The gate mirrors `wakePending()`'s eligibility check.
+     */
+    countDispatchUnknown(): number;
+    /**
+     * Park one item whose admission mandate failed revalidation.
+     *
+     * Parking is never terminal: the item stays `waiting` with a typed reason, its
+     * pending dispatch row is left intact, and it becomes claimable/wakeable again
+     * as soon as the identical mandate allows. Repeating the same park only
+     * refreshes the audit timestamp, so a sweep that observes the same denial on
+     * every tick does not flood the event log.
+     */
+    parkAuthority(itemId: string, reason: typeof AUTHORITY_REVOKED | typeof AUTHORITY_UNAVAILABLE, detail: Readonly<Record<string, unknown>>, now: number): WorkItemRecord;
+    /**
+     * Record a successful revalidation of one item's mandate.
+     *
+     * Only a wait this gate itself created is lifted; a slice-9
+     * `following-thread` wait is a different concern and stays untouched.
+     */
+    restoreAuthority(itemId: string, now: number): WorkItemRecord;
+    /** Latest authority denial for bounded health reporting. */
+    lastAuthorityDenial(): {
+        readonly at: number;
+        readonly reason: string;
+    } | null;
+    getContinuation(itemId: string): Readonly<WorkItemContinuationRecord> | undefined;
+    findContinuationBySourceKey(key: string): Readonly<WorkItemContinuationRecord> | undefined;
+    /** Most recently admitted dispatched child, by immutable dispatch rowid; no wall-clock ordering. */
+    latestContinuationDispatch(automationId: string): Readonly<{
+        item: WorkItemRecord;
+        dispatch: WorkItemDispatchRecord;
+        continuation: WorkItemContinuationRecord;
+    }> | undefined;
+    continuationDispatchUncertain(automationId: string): boolean;
+    listPendingContinuations(automationId: string, limit?: number, after?: Readonly<{
+        createdAt: number;
+        id: string;
+    }>): readonly Readonly<{
+        item: WorkItemRecord;
+        dispatch: WorkItemDispatchRecord;
+        continuation: WorkItemContinuationRecord;
+    }>[];
+    continuationParentBrief(itemId: string): string;
+    continuationParentReports(itemId: string, afterRevision?: number, limit?: number): readonly WorkItemReportRecord[];
+    continuationParentOutcomes(itemId: string, afterRevision?: number, limit?: number): readonly WorkItemOutcomeRecord[];
+    /**
+     * Insert one admitted item, its lifecycle event and its single dispatch row
+     * in one transaction. A crash between these writes is impossible.
+     */
+    admitItem(record: WorkItemRecord, event: {
+        kind: string;
+        actor: string;
+        detail?: unknown;
+    }, dispatch: WorkItemDispatchRecord, follows?: readonly WorkItemFollowInput[], diagnosisPlan?: WorkItemDiagnosisPlan, continuation?: WorkItemContinuationInput): WorkItemRecord;
+    /**
+     * Retire every open item a canonical signal produced, because it was withdrawn.
+     *
+     * This is the only lifecycle transition driven by the read side of autonomy
+     * rather than by a worker report. It is deliberately narrow: the items stop
+     * being open, their active claim (if any) is released so the current run
+     * cannot keep reporting, and a still-pending wake-up is failed rather than
+     * re-armed. A wake-up already handed to the automation is left alone —
+     * delivery to a running occurrence cannot be recalled from here.
+     *
+     * Withdrawal targets the whole dedup key, not the newest row, because the
+     * dedup window is a freshness bound: once it rolls, a still-open item can be
+     * re-admitted under the same key with a different bucket. Retiring only the
+     * newest row would leave the older one winnable by `wakePending()` on the next
+     * host start, i.e. cancelled work could still be woken. All rows of the key
+     * therefore settle together in one transaction.
+     *
+     * Idempotent: an already-terminal key is returned unchanged (`settled`) with
+     * no new event, so a repeated withdrawn revision never rewrites history.
+     */
+    withdrawByDedupKey(dedupKey: string, attribution?: WithdrawAttribution): WithdrawDedupResult;
+    latestOutcome(itemId: string): WorkItemOutcomeRecord | undefined;
+    /** Every outcome revision for one item, oldest first. */
+    outcomes(itemId: string): readonly WorkItemOutcomeRecord[];
+    /**
+     * Latest outcome plus the report delivery state it depends on.
+     *
+     * `reportRevision` is the terminal report that caused a report-derived
+     * transition; observation and expiry revisions keep pointing at it, while
+     * withdrawal and retry exhaustion never had a report.
+     */
+    outcomeView(itemId: string): WorkItemOutcomeView | undefined;
+    /** Latest outcomes, newest first, optionally filtered by evidence state. */
+    listOutcomes(options?: {
+        limit?: number;
+        evidenceState?: WorkItemOutcomeEvidenceState;
+    }): readonly WorkItemOutcomeView[];
+    /**
+     * Latest outcome revisions still waiting for evidence, soonest deadline first.
+     *
+     * Only the newest revision per item is considered: an older revision that was
+     * superseded still says `pending` in the immutable row, but it is history, not
+     * an open window.
+     */
+    pendingOutcomes(limit: number): readonly WorkItemOutcomeRecord[];
+    /**
+     * Append the settling revision for one pending outcome.
+     *
+     * Compare-and-swap on the revision number: a concurrent pass that already
+     * settled the item fails here instead of overwriting its history.
+     *
+     * This intentionally appends no `work_item_event`: the outcome ledger is its
+     * own append-only audit trail, and duplicating every revision into the event
+     * log would mix worker lifecycle with independently sourced evidence.
+     */
+    settleOutcome(input: {
+        itemId: string;
+        revision: number;
+        evidence: WorkItemOutcomeEvidence | null;
+        reason: WorkItemOutcomeEvidenceReason | null;
+        degraded: boolean;
+        expired: boolean;
+    }): WorkItemOutcomeRecord;
+    /**
+     * Latest outcome revisions that still owe exactly one trusted Evaluation
+     * append.
+     *
+     * Only the newest revision per item is exportable, and only once it carries a
+     * settled evidence state: an unresolved `pending` window is still changing, so
+     * exporting it early would publish a claim that later revisions contradict.
+     */
+    outcomesAwaitingEvaluation(limit: number, attemptBound?: number): readonly WorkItemOutcomeRecord[];
+    /** Count settled revisions that used up their bounded export attempts. */
+    countExhaustedEvaluations(attemptBound: number): number;
+    /** Count latest export-eligible revisions per Evaluation export state. */
+    countEvaluations(): {
+        pending: number;
+        exported: number;
+        skipped: number;
+    };
+    /**
+     * Bounded, read-only execution facts for one item at a settlement instant.
+     *
+     * Every counter is a COUNT over durable rows this ledger already keeps for
+     * the item; nothing is re-derived from live process state. `settledAt` bounds
+     * each read because rows recorded after the settled revision belong to a
+     * later observation and must not inflate an earlier claim. An absent item row
+     * returns `undefined` so the caller can keep the live-record fallback.
+     *
+     * Claims are counted from `claimed` ledger events rather than claim rows:
+     * each committed claim appends exactly one such event in the same transaction
+     * as the claim row and the `item.attempt` increment (the replay branch appends
+     * neither, retry-exhausted appends `blocked` only, and nothing deletes either
+     * record), while `work_item_claim` has no `item_id` index. `work_item_event`
+     * is `WITHOUT ROWID` keyed by `(item_id, sequence)`, so its count is an
+     * indexed prefix search instead of a scan of every claim ever recorded.
+     */
+    workItemExecutionMetrics(itemId: string, settledAt: number): WorkItemExecutionMetrics | undefined;
+    /**
+     * Bounded, read-only resume brief for one item at a claim instant.
+     *
+     * Everything is derived from the item's own append-only ledger rows, so a
+     * fresh occurrence can continue without replaying a prior model's memory.
+     * Absent items return `undefined` (mirroring `workItemExecutionMetrics`) so
+     * the caller never invents an empty context for a row that vanished.
+     *
+     * The event read is a bounded newest-first scan of one item's primary-key
+     * prefix; it reconstructs prior attempts from the `claimed` event that
+     * records `{runId, attempt}` and the recovery/report events that end one.
+     * Malformed or absent detail JSON is skipped, never thrown. Reports are read
+     * newest-first through the same primary-key prefix and capped at five, with
+     * each summary cut to a safe UTF-8 byte boundary.
+     */
+    workItemResumeContext(itemId: string, now?: number): WorkItemResumeContext | undefined;
+    /** Mark one settled revision exported; CAS on `pending` so a replay is refused. */
+    markOutcomeExported(itemId: string, revision: number, digest: string, recordedAt: number): WorkItemOutcomeRecord;
+    /** Mark one settled revision skipped; CAS on `pending`. */
+    markOutcomeSkipped(itemId: string, revision: number, recordedAt: number): WorkItemOutcomeRecord;
+    /** Count one failed export attempt, saturated at the caller's bound. */
+    recordOutcomeEvaluationAttempt(itemId: string, revision: number, maxAttempts: number): WorkItemOutcomeRecord;
+    appendEvent(itemId: string, kind: string, actor: string, detail?: unknown): void;
+    events(itemId: string): readonly WorkItemEventRecord[];
+    /**
+     * Record Policy-change notices for live items in one transaction, at most
+     * once per (item, policyVersion). A notice is an append-only event: it
+     * changes no state, lease or dispatch, so a Policy change never cancels
+     * work. All or nothing: a failure writes none of the batch, and a retry with
+     * the same version re-derives it. Each entry yields the written notice, or
+     * `undefined` when the item already had one for this version or is no
+     * longer live work.
+     */
+    recordPolicyNotices(policyVersion: string, entries: ReadonlyArray<Readonly<{
+        itemId: string;
+        notice: Omit<WorkItemPolicyNotice, 'itemId' | 'recordedAt' | 'policyVersion'>;
+    }>>): ReadonlyArray<WorkItemPolicyNotice | undefined>;
+    /**
+     * Live (open, non-observed) items in admission order after `after`, for a
+     * bounded notice pass; also how many live items lie beyond the page.
+     */
+    listLiveItemsPage(options: {
+        after?: Readonly<{
+            createdAt: number;
+            id: string;
+        }>;
+        limit: number;
+    }): Readonly<{
+        items: readonly WorkItemRecord[];
+        remaining: number;
+    }>;
+    /**
+     * The independent verifier's verdict recorded for one item, if any.
+     *
+     * Append-only event, at most one per item: a receipt is final for its
+     * contract, so the first validated read-back is the item's verdict.
+     */
+    acceptanceVerdict(itemId: string): WorkItemAcceptanceVerdict | undefined;
+    /**
+     * Record the verifier's verdict for one item, at most once. The same
+     * receipt again is idempotent; a different receipt for an item that already
+     * has a verdict is an identity mismatch and writes nothing. The item's state,
+     * lease and outcome revisions are untouched.
+     */
+    recordAcceptanceVerdict(verdict: Omit<WorkItemAcceptanceVerdict, 'recordedAt'>, gate?: WorkItemAcceptanceGateExpectation): Readonly<{
+        verdict: WorkItemAcceptanceVerdict;
+        created: boolean;
+        blockedReason?: WorkItemAcceptanceBlockReason;
+    }>;
+    /**
+     * WP21 slice 7 (`acceptance.verdictGate`): an independent verifier said the
+     * executed item's objective was not achieved, could not tell, or needs
+     * attention. Move it from `ready` to the existing `blocked` state with an
+     * `acceptance-*` reason and one `blocked` event. Compare-and-swap on the
+     * expected state, attempt and occurrence: an item that moved on (re-armed,
+     * withdrawn, already blocked) is left untouched and nothing is written. The
+     * outcome ledger is not rewritten; the self-reported `ready` revision stays
+     * history.
+     */
+    blockForAcceptance(itemId: string, expect: WorkItemAcceptanceGateExpectation, reason: WorkItemAcceptanceBlockReason, detail: Readonly<{
+        contractId: string;
+        receiptDigest?: string;
+        verifierReason?: string | null;
+    }>): boolean;
+    /** Every Policy-change notice recorded for one item, oldest first. */
+    policyNotices(itemId: string): readonly WorkItemPolicyNotice[];
+    /**
+     * Hand one human follow-up on the item's work thread to that item.
+     *
+     * The message id is owned by at most one item for its whole life; the same
+     * (item, message, digest) is idempotent, anything else under the same id is
+     * an identity mismatch. An item that already ended takes nothing: the
+     * message stays with judgment and no row is written.
+     */
+    ownFollowUp(input: {
+        itemId: string;
+        bindingId: string;
+        messageId: string;
+        sourceDigest: string;
+    }): WorkItemFollowUpOwnResult;
+    /**
+     * Mark one owned follow-up processed by its live item. Idempotent; once the
+     * item ended an unprocessed follow-up belongs to judgment and cannot be
+     * claimed as processed any more, whether or not the release sweep ran.
+     */
+    markFollowUpProcessed(itemId: string, messageId: string, options?: {
+        readonly allowEnded?: boolean;
+    }): WorkItemFollowUpRecord;
+    /** Follow-ups owned by one item, in the order they were handed over. */
+    followUps(itemId: string): readonly WorkItemFollowUpRecord[];
+    /**
+     * Materialize the release of every unprocessed follow-up whose item ended.
+     *
+     * Derived from durable state only (terminal item, owned, neither processed
+     * nor released), so it is restart-safe and covers every terminal path
+     * without hooking each one; a second sweep releases nothing new.
+     */
+    releaseEndedFollowUps(limit?: number): readonly WorkItemFollowUpRecord[];
+    /**
+     * Released follow-ups in release order, for judgment to (re)read after a
+     * restart. `after` is the cursor of the last record already seen.
+     */
+    listReleasedFollowUps(options?: {
+        limit?: number;
+        after?: WorkItemFollowUpCursor;
+    }): Readonly<{
+        items: readonly WorkItemFollowUpRecord[];
+        next: WorkItemFollowUpCursor | null;
+    }>;
+    getDispatch(itemId: string): WorkItemDispatchRecord | undefined;
+    /** Final synchronous wake fence. This method calls no peer or user callback;
+     * full SQLite text equality also closes Node 24's hidden-NUL projection gap. */
+    isWakeSnapshotCurrent(item: WorkItemRecord, dispatch: WorkItemDispatchRecord): boolean;
+    /**
+     * Pending dispatches whose due time has arrived.
+     *
+     * `occurred_at` doubles as the due time: admission sets it to the admit
+     * instant, a lease reclaim re-arms it at the reclaim instant, and a `waiting`
+     * report re-arms it at `now + limits.waitingResumeMs`. Filtering here keeps
+     * recovery lazy and prevents an early wake of a deliberately delayed resume.
+     */
+    listOpenDispatches(limit: number): readonly WorkItemDispatchRecord[];
+    /** At most ten due waiting resumes, with durable keyset round-robin fairness. */
+    listDueWaitingResumes(limit?: number): readonly WorkItemDispatchRecord[];
+    /** Advance even past denied/expired-owner rows so later items are not starved. */
+    advanceWaitingResumeCursor(dispatch: WorkItemDispatchRecord): void;
+    /**
+     * Failed dispatches whose wake outcome is unknown and that still own one
+     * bounded retry inside the same generation.
+     */
+    listRetryableUnknownDispatches(limit: number): readonly WorkItemDispatchRecord[];
+    markDispatchDispatched(itemId: string, occurrenceId: string): void;
+    markDispatchFailed(itemId: string, reason: string): void;
+    /**
+     * Record an ambiguous wake failure: the peer may or may not have committed
+     * the occurrence, so the row is failed with `unknown_after_send` and the
+     * generation's retry budget is spent once.
+     *
+     * The identity is preserved, so a retry resolves the same occurrence instead
+     * of minting a second run.
+     */
+    markDispatchUnknown(itemId: string): WorkItemDispatchRecord;
+    /**
+     * Re-arm one failed-with-unknown row inside the *same* generation.
+     *
+     * The persisted event id and occurred-at are reused verbatim, so the retry is
+     * idempotent against the automation intake: if the first attempt did commit,
+     * the retry resolves that occurrence; if it did not, the retry creates it.
+     */
+    retryUnknownDispatch(itemId: string): WorkItemDispatchRecord;
+    /**
+     * Re-arm a fresh wake after a claim-time revalidation denial.
+     *
+     * At claim time the occurrence already exists, so parking alone would leave
+     * the item without any future wake. A new generation is minted because the
+     * denied run never claimed the item; once the mandate allows again, the
+     * ordinary wake path hands the same item to a fresh occurrence.
+     */
+    rearmAuthority(itemId: string): void;
+    /**
+     * Reclaim every claim whose lease elapsed. Lazy by design: no timer owns
+     * recovery, so a host that was down simply reclaims on the next touch.
+     *
+     * The expired claim is retired explicitly, the item returns to `queued` and
+     * its dispatch row is re-armed so the normal wake path can hand the item to a
+     * fresh occurrence. A re-queued item that nobody wakes would otherwise stay
+     * queued forever, counted against `maxOpenItems`.
+     */
+    reclaimExpired(): ReclaimResult;
+    /** Latest claim for one run; a re-claim after expiry appends a newer row. */
+    findClaimByRun(runId: string): WorkItemClaimRecord | undefined;
+    activeClaim(itemId: string): WorkItemClaimRecord | undefined;
+    /**
+     * Compare-and-swap claim.
+     *
+     * A repeated claim from the same run replays the existing claim only while
+     * that claim is still active, so a tool retry after transport loss is safe.
+     * Once the lease elapsed the claim is retired and the same run obtains a new
+     * claim row (and a new attempt), instead of replaying a dead lease forever.
+     * A competing run loses with `claim-conflict`.
+     */
+    claim(input: {
+        itemId: string;
+        runId: string;
+        occurrenceId: string;
+        leaseMs: number;
+        reclaimExpired?: boolean;
+    }): ClaimResult;
+    reportCount(itemId: string): number;
+    lastReport(itemId: string): WorkItemReportRecord | undefined;
+    reports(itemId: string): readonly WorkItemReportRecord[];
+    /**
+     * Compare the existing scoped key and normalized persisted payload in SQLite.
+     * Node 24.7.0 TEXT projections truncate at NUL; bound SQL comparisons retain
+     * every byte. The existing key format alone also has delimiter collisions.
+     */
+    reportReplayState(input: Pick<WorkItemReportRecord, 'itemId' | 'idempotencyKey' | 'status' | 'summary' | 'truncated' | 'artifactPaths'>): 'absent' | 'match' | 'conflict';
+    /** Exact report and adjacent references, using the existing item/revision key. */
+    reportByRevision(itemId: string, revision: number): Readonly<{
+        report: WorkItemReportRecord;
+        previousRevision: number | null;
+        nextRevision: number | null;
+    }> | undefined;
+    /** Feedback evidence keeps immutable report TEXT bytes intact on Node 24.
+     * This reads exactly the requested revision and performs no state changes. */
+    feedbackReportByRevision(itemId: string, revision: number): WorkItemReportRecord | undefined;
+    /**
+     * Append one report revision under the active claim, then apply the state
+     * transition for that status.
+     *
+     * The caller's idempotency key is scoped to the claim row, so identical text
+     * reported by different claims (or different items) is not mistaken for a
+     * replay, while a retried call on the same claim returns the stored revision.
+     */
+    report(input: {
+        itemId: string;
+        runId: string;
+        status: WorkItemReportStatus;
+        summary: string;
+        truncated: boolean;
+        artifactPaths: readonly string[];
+        idempotencyKey: string;
+        maxReports: number;
+        leaseMs: number;
+        waitingResumeMs: number;
+    }): ReportResult;
+    setReportDelivery(itemId: string, revision: number, state: WorkItemDeliveryState, deliveryId: string | null): void;
+    /** Terminal item states map to terminal claim states. */
+    static claimStateFor(report: WorkItemReportStatus): WorkItemClaimState;
+    /** Open states are exposed for admission accounting and tests. */
+    static openStates(): readonly WorkItemState[];
+}
+export {};
+//# sourceMappingURL=store.d.ts.map