@qodeca/xezar 0.13.0 → 0.14.0

package/dist/mcp/operation-receipts.d.ts

@@ -0,0 +1,210 @@
+import { type OperationAnswer, type OperationResultRef, type ReconcileKind, type ReconcilePredicate } from '../contract/index.js';
+/** The append-only journal: one line per phase transition. The durable record (D-06 § 7.2). */
+export declare const RECEIPT_JOURNAL_FILE = "mcp-operations.ndjson";
+/** The compacted snapshot: a load-time shortcut, never the source of truth (D-06 § 7.2). */
+export declare const RECEIPT_SNAPSHOT_FILE = "mcp-operations.json";
+/**
+ * Receipt age floor: 12 resumes × 5 h + the 24 h missed-deadline tolerance = 84 h (D-06 § 8.2) —
+ * the longest span over which the engine itself may still resurrect a run one MCP mutation
+ * started. Derived from the live constants, so the derivation IS the decision.
+ */
+export declare const RECEIPT_MAX_AGE_MS: number;
+/** Receipt count floor per project: a measured 40.6 ms cold scan against a 300 ms budget (D-06 § 8.3). */
+export declare const RECEIPT_MAX_KEPT = 50000;
+/** Snapshot cadence: a 1 000-line journal scans in 0.7 ms, so compacting sooner does not pay (D-06 § 7.2). */
+export declare const RECEIPT_SNAPSHOT_EVERY_LINES = 1000;
+/**
+ * The UUIDv5 namespace MCP-created run ids are derived in (D-06 § 12.1). A constant, never
+ * regenerated: changing it would make every recorded prediction point at an id nobody creates.
+ */
+export declare const XEZAR_MCP_NAMESPACE = "a3c1e7d2-5b4f-4e8a-9c61-2f0d8b7e4a15";
+/** What an effect reports. A refusal the service makes after the intent is `rejected`. */
+export type EffectOutcome = {
+    outcome: 'ok';
+    resultRef: OperationResultRef;
+} | {
+    outcome: 'rejected' | 'not-applied';
+    errorCode: string;
+};
+/** A reconciler's verdict — the answer to "did this effect happen?", from a READ (D-06 § 9.3). */
+export type ReconcileVerdict = {
+    verdict: 'ok';
+    resultRef: OperationResultRef;
+} | {
+    verdict: 'not-applied';
+} | {
+    verdict: 'unverified';
+    reason: string;
+};
+/**
+ * Answers one question with an idempotent read, never a write — a reconciler that mutates to find
+ * out is the blind repeat this module exists to prevent (D-06 § 9.3 rule 2). `not-applied` needs a
+ * POSITIVE answer; silence, a timeout, a network error or a missing tool are `unverified` (rule 3).
+ */
+export type Reconciler = (predicate: ReconcilePredicate, context: {
+    action: string;
+    startedAt: string;
+}) => ReconcileVerdict | Promise<ReconcileVerdict>;
+export interface OperationRequest {
+    /** From the trusted connection binding — NEVER from a tool argument (D-06 § 5.2). */
+    projectId: string;
+    /** The client-generated operation id, as supplied. */
+    operationId: string;
+    /** The action id, e.g. `runs.create`. */
+    action: string;
+    /** The payload AFTER the action's zod schema parsed it — never raw params (D-06 § 5.4). */
+    payload: unknown;
+    /** Top-level keys the digest ignores. Ships empty; every addition needs a recorded reason. */
+    digestExclude?: readonly string[];
+    expectedVersion?: string;
+    ownerGeneration?: string;
+    /** The read that can later settle a dangling intent, fixed BEFORE the effect (D-06 § 9.3). */
+    reconcile: ReconcilePredicate;
+    /**
+     * D-06 § 7.3 step 2 — the version/permission check, run synchronously in the same critical
+     * section as the intent write. Return an error code to refuse; the refusal writes one `settled`
+     * `rejected` line and no intent, so a retry returns the same rejection.
+     */
+    precheck?: () => string | undefined;
+    /** D-06 § 7.3 step 4. Throwing is treated as "may have happened" and reconciled, never repeated. */
+    effect: () => EffectOutcome | Promise<EffectOutcome>;
+}
+export interface OperationReceiptStoreOptions {
+    /** Clock, for tests. */
+    now?: () => number;
+    /** One reconciler per predicate kind. A kind with no reconciler reads as `unverified`. */
+    reconcilers?: Partial<Record<ReconcileKind, Reconciler>>;
+    /**
+     * The structural floor (D-06 § 8.4): a receipt is never evicted while the resource its
+     * `resultRef` names still exists. Absent = no resource is known live.
+     */
+    isResultLive?: (ref: OperationResultRef) => boolean;
+    /** Bounds, for tests only — production uses the D-06 numbers above. */
+    maxAgeMs?: number;
+    maxKept?: number;
+    snapshotEveryLines?: number;
+}
+/** `<projectId>/<operationId>` (D-06 § 5.2). The id alphabet has no `/`, so the split is unambiguous. */
+export declare function operationKey(projectId: string, operationId: string): string;
+/** RFC 4122 § 4.3 name-based UUID, SHA-1 variant. */
+export declare function uuidV5(name: string, namespace: string): string;
+/**
+ * The run id an MCP `runs.create` must create, derived from the operation key before the effect
+ * (D-06 § 12.1). A retry predicts the same id; two operations cannot share one. Reconciliation is
+ * then a primary-key lookup and no new field is persisted on the run record.
+ */
+export declare function predictRunId(projectId: string, operationId: string): string;
+/**
+ * `sha256(canonical(payload))`, lowercase hex (D-06 § 5.4). The payload must already be the
+ * action's zod-parsed value. Canonical form: object keys sorted by UTF-16 code unit at every level,
+ * arrays in order, no whitespace, `undefined` object keys dropped, and every binary blob replaced
+ * by `{ bytes, sha256 }` so the digest covers the BYTES, never a path. Non-finite numbers and
+ * values JSON cannot carry are refused rather than silently coerced.
+ */
+export declare function payloadDigest(payload: unknown, digestExclude?: readonly string[]): string;
+/**
+ * `run-by-key` (D-06 § 9.3): the store write IS the effect, so a run under the predicted id means
+ * `ok` and its absence means `not-applied` — but only while the index can still answer. The run
+ * store evicts by COUNT, so a busy project may already have pruned the very run an old intent
+ * names; "not there" and "the store can no longer tell" must not share a branch.
+ *
+ * The index can answer only if the intent is no older than the oldest run each retention pool
+ * still holds (archived and live runs are pruned separately, so the newest of the two pool-oldest
+ * dates is the conservative bound). An empty index cannot answer at all — it may be a deleted or
+ * corrupt `runs.json` — so it is `unverified` too. Both errors fall on the safe side: a spurious
+ * "check this" is recoverable, a duplicated task is not.
+ */
+export declare function runByKeyReconciler(store: {
+    getRun(id: string): {
+        id: string;
+    } | undefined;
+    listRuns(): Array<{
+        createdAt: string;
+        archived?: boolean;
+    }>;
+}): Reconciler;
+/**
+ * The per-project receipt store. One instance per project data directory, owned by the process
+ * `ownProjectData` admits as that project's writer — which is why no cross-process lock is needed
+ * around the check-then-write (D-06 § 4.5).
+ */
+export declare class OperationReceiptStore {
+    readonly dataDir: string;
+    private readonly opts;
+    private readonly receipts;
+    /** Keys whose effect (or reconciliation) is running in THIS process right now. */
+    private readonly live;
+    private readonly warned;
+    private readonly journalPath;
+    private readonly snapshotPath;
+    private readonly now;
+    private readonly maxAgeMs;
+    private readonly maxKept;
+    private readonly snapshotEveryLines;
+    /** Lines appended (or scanned past the snapshot) since the last compaction. */
+    private linesSinceCompaction;
+    /** Journal lines that failed to parse. While > 0, a key miss reconciles before executing (§ 7.4). */
+    private quarantined;
+    private damageDetectedAt;
+    /** Whether the journal already exists with content; a fresh journal starts with a header line. */
+    private journalStarted;
+    /** The journal ends in a torn line: the next append must start on a fresh line, or the torn
+     *  fragment would swallow a good receipt into the quarantine with it. */
+    private needsNewline;
+    private constructor();
+    /**
+     * Open (or create on first write) the receipts for one project data directory. Never throws:
+     * absent files are an empty store, an unreadable snapshot is ignored, and unreadable journal
+     * lines are quarantined one by one — a torn final line costs exactly that one receipt (§ 7.4).
+     */
+    static open(dataDir: string, opts?: OperationReceiptStoreOptions): OperationReceiptStore;
+    /** Counts for diagnostics and tests. */
+    stats(): {
+        receipts: number;
+        quarantined: number;
+        live: number;
+    };
+    /**
+     * Run one mutation under its operation key, answering with exactly one § 6 result.
+     *
+     * Everything up to the intent append is synchronous, so two calls with one key cannot both pass
+     * the lookup: the second sees the first as live and answers `in-progress`.
+     */
+    execute(request: OperationRequest): Promise<OperationAnswer>;
+    /**
+     * Reconcile every dangling intent once, in the background (D-06 § 9.3 rule 1). Callers start it
+     * after project open and never await it: a `gh`-less or offline machine keeps working, and until
+     * a receipt's reconciliation finishes it truthfully reads `unverified`.
+     */
+    reconcilePending(): Promise<void>;
+    /** Clean shutdown: compact, so the next open reads a snapshot instead of the whole journal. */
+    close(): void;
+    private reconcileDangling;
+    private runReconciler;
+    private settledReceipt;
+    private settledAnswer;
+    private unverifiedAnswer;
+    /** Synchronous append — survives a process crash the instant it returns (D-06 § 3.3). Throws. */
+    private append;
+    /** Append where a failed write must not change the answer; the in-memory receipt still replays. */
+    private appendBestEffort;
+    private maybeCompact;
+    private load;
+    private noteDamage;
+    private readSnapshot;
+    /**
+     * Retention (D-06 § 8). A receipt is evicted only when it is BOTH older than the age floor AND
+     * outside the newest `maxKept` for its project. A dangling intent is never evicted — its
+     * `unverified` answer must not decay into "never happened" — and neither is a receipt whose
+     * result still exists (§ 8.4). Touches these files and nothing else (§ 12.2).
+     */
+    private evict;
+    /**
+     * Evict, then rewrite the journal from the folded set and write an offset-anchored snapshot
+     * (D-06 § 7.2, § 8.1). The quarantine count survives the rewrite as a damage marker until the
+     * age floor has passed since it was detected — a torn line's operation cannot be retried later
+     * than that — and then it is compacted out on its own, with no manual step.
+     */
+    private compact;
+    private warnOnce;
+}