@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/api-lane/notify.js

@@ -0,0 +1,240 @@
+/**
+ * The API lane's notify (Go Prod §7.1 `after.notify`, §5): what the claim's CURRENT state owes its
+ * timeline — `facts_produced` + `decided`, `review_required` (with the tasks as asked), `folded`,
+ * `unusable`, `failed` — and the `claim.*` webhook each is announced as (webhooks.ts). Read from the
+ * DB, never told by the caller, so the one function serves the
+ * ingest's notify step, the fold's, and the terminal catch; event ids are derived from what the
+ * event is about (ids.ts), so calling it again after a retry writes nothing new. A claim that
+ * waits for review also tells its reviewers (reviewers.ts: email + the source's Matrix room).
+ *
+ * And the one event no step owes: `review_expired` (`announceExpiredReviews`, the hourly pass) — a
+ * paid claim whose review closed unanswered at its `answerBy`.
+ */
+import { eq } from "drizzle-orm";
+import { apiClaims, claimIngests, claimReviews, decisions, matrixDeliveries, } from "../../db/schema.js";
+import { createEngineClient } from "../engine/client.js";
+import { isManifestUnusable } from "../engine/types.js";
+import { reviewTasks } from "../matrix/deliver.js";
+import { parseApiScopeId } from "./ids.js";
+import { claimErrorCode, claimRecord, decisionFailure } from "./record.js";
+import { expiredReviews, notifyReviewers } from "./reviewers.js";
+import { recordEvents } from "./timeline.js";
+import { deliverAll, enqueueWebhook } from "./webhooks.js";
+/** Timeline event type → the App. B webhook it is announced as (the same event id on both). */
+const CLAIM_WEBHOOKS = {
+    accepted: "claim.accepted",
+    decided: "claim.decided",
+    review_required: "claim.review_required",
+    folded: "claim.folded",
+    unusable: "claim.unusable",
+    failed: "claim.failed",
+    review_expired: "claim.review_expired",
+};
+export async function notifyApiClaim(db, deps, claimId) {
+    const events = await claimStateEvents(db, deps, claimId);
+    const keys = await announce(db, events);
+    const last = events.at(-1);
+    // The first attempt inline — the §1.4 "within 60 s" is the notify step, not the next cron tick.
+    // Each attempt is its own ledger write, so a retried step re-posts only what is still owed.
+    await deliverAll({ db, config: deps.config, logger: deps.logger, metrics: deps.metrics, cache: deps.cache }, keys);
+    // The people too, not only the system (§10.1): fail-soft, and idempotent per (claim, member).
+    if (last?.type === "review_required")
+        await notifyReviewers({ ...deps, db }, claimId);
+}
+/**
+ * A paid claim whose review passed its `answerBy` unanswered is closed unpaid: its record keeps the
+ * engine's `pending_review` (nothing was decided), so integrators are told instead — ONCE, a
+ * `review_expired` timeline row (`answerBy` only) announced as `claim.review_expired`. Stamped at
+ * the deadline, so a re-run lands on the same event; the `notice_review_expired:` marker, written
+ * last, is what keeps the pass off the claim. The webhook's first attempt is the minute tick's.
+ * The count announced.
+ */
+export async function announceExpiredReviews(db, now = new Date()) {
+    const claims = await expiredReviews(db, now);
+    for (const c of claims) {
+        const answerBy = c.answerBy;
+        await announce(db, [
+            {
+                key: `${c.claimId}:review_expired:`,
+                at: answerBy,
+                sourceId: c.sourceId,
+                claimId: c.claimId,
+                type: "review_expired",
+                data: { answerBy: answerBy.toISOString() },
+            },
+        ]);
+        await db
+            .insert(matrixDeliveries)
+            .values({
+            dedupeKey: `notice_review_expired:${c.claimId}`,
+            kind: "notice_review_expired",
+            claimId: c.claimId,
+            sourceId: c.sourceId,
+            status: "sent",
+            attempts: 1,
+        })
+            .onConflictDoNothing();
+    }
+    return claims.length;
+}
+/**
+ * Write the claim's timeline events and enqueue the `claim.*` webhook each one is announced as,
+ * with the §4.4 record as it stands now as `data`; the delivery keys. The webhook's event id IS the
+ * timeline row's, so `Oracle-Event-Id` is stable across every retry and replay.
+ */
+export async function announce(db, events) {
+    const ids = await recordEvents(db, events);
+    const keys = [];
+    for (const [i, e] of events.entries()) {
+        const type = CLAIM_WEBHOOKS[e.type];
+        if (!type || !e.claimId)
+            continue;
+        const [record, claim] = await Promise.all([
+            claimRecord(db, e.claimId),
+            db.query.apiClaims.findFirst({
+                columns: { webhookUrl: true },
+                where: eq(apiClaims.claimId, e.claimId),
+            }),
+        ]);
+        if (!record)
+            continue;
+        keys.push(...(await enqueueWebhook(db, {
+            eventId: ids[i],
+            type,
+            createdAt: e.at,
+            sourceId: e.sourceId,
+            claimId: e.claimId,
+            data: record,
+            claimWebhookUrl: claim?.webhookUrl ?? null,
+        })));
+    }
+    return keys;
+}
+async function claimStateEvents(db, deps, claimId) {
+    const [claim, ingest, decision, review] = await Promise.all([
+        db.query.apiClaims.findFirst({
+            columns: { sourceId: true, protocolDid: true, receivedAt: true, via: true },
+            where: eq(apiClaims.claimId, claimId),
+        }),
+        db.query.claimIngests.findFirst({ where: eq(claimIngests.claimId, claimId) }),
+        db.query.decisions.findFirst({ where: eq(decisions.claimId, claimId) }),
+        db.query.claimReviews.findFirst({ where: eq(claimReviews.claimId, claimId) }),
+    ]);
+    if (!claim || !ingest)
+        return [];
+    const event = (type, key, at, data) => ({
+        key: `${claimId}:${type}:${key}`,
+        at,
+        sourceId: claim.sourceId,
+        claimId,
+        type,
+        data,
+    });
+    // Paid for and running (§5): the first thing every state owes, stamped when it was received.
+    const accepted = event("accepted", "", claim.receivedAt, {
+        protocolDid: claim.protocolDid,
+        ...(claim.via ? { via: claim.via } : {}),
+    });
+    if (!decision) {
+        // The ledger's terminal failure with nothing recorded (the engine refused the facts, a body
+        // that no longer matches, the retry ladder ran out) — the code, never the stored message.
+        if (ingest.status !== "failed")
+            return [accepted];
+        const code = claimErrorCode(ingest.error, null);
+        return [accepted, event("failed", code, ingest.updatedAt, { code })];
+    }
+    const failed = decisionFailure(decision.status);
+    if (failed) {
+        return [accepted, event("failed", failed, decision.createdAt, { code: failed })];
+    }
+    const events = [accepted];
+    // Names only — the values are the answers' shadow and never leave the decision row. Stamped a
+    // millisecond before the decision it fed: ULID ids sort by time, and the timeline reads by id.
+    if (decision.facts) {
+        events.push(event("facts_produced", decision.factsDigest ?? "", new Date(decision.createdAt.getTime() - 1), {
+            ext: Object.keys(decision.facts.ext),
+            ai: Object.keys(decision.facts.ai),
+            ...factCost(decision.facts),
+        }));
+    }
+    const summary = {
+        status: decision.status,
+        verdict: decision.verdict,
+        resultDigest: decision.resultDigest,
+        receiptCid: decision.receiptCid,
+    };
+    const folded = review?.foldedAt ?? null;
+    if (decision.status === "pending_review") {
+        events.push(event("review_required", decision.resultDigest ?? "", decision.createdAt, {
+            ...summary,
+            pendingTasks: await pendingTasks(deps, decision),
+        }));
+    }
+    else if (decision.status === "unusable") {
+        events.push(event("unusable", decision.resultDigest ?? "", folded ?? decision.createdAt, {
+            ...summary,
+            issues: decision.decision?.reasons ?? decision.explanation,
+        }));
+    }
+    else if (folded) {
+        events.push(event("folded", decision.resultDigest ?? "", folded, summary));
+    }
+    else {
+        events.push(event("decided", decision.resultDigest ?? "", decision.createdAt, summary));
+    }
+    return events;
+}
+/**
+ * The engine's pending task ids × the manifest's prompts and answer shapes, stored on the event at
+ * decision time so a later manifest change never rewrites what the reviewer was asked (§10).
+ */
+async function pendingTasks(deps, decision) {
+    const ids = decision.decision?.pendingTasks ?? [];
+    const scope = parseApiScopeId(decision.collectionId);
+    if (ids.length === 0 || !scope)
+        return reviewTasks(ids, undefined);
+    const engine = createEngineClient({
+        config: deps.config,
+        logger: deps.logger,
+        trace: deps.trace,
+        cache: deps.cache,
+    });
+    // The notify step is fail-soft: an engine blip here must not cost the customer their
+    // `review_required` altogether, so the bare task ids stand in (the Matrix lane's fallback).
+    const manifest = await engine.getManifest(scope.protocolDid).catch((err) => {
+        deps.logger.warn("api.review-tasks-unread", { claimId: decision.claimId, detail: String(err) });
+        return null;
+    });
+    return reviewTasks(ids, !manifest || isManifestUnusable(manifest) ? undefined : manifest.review);
+}
+/**
+ * What producing the facts cost (§9: per claim on its timeline, summed per protocol to price it):
+ * each fact's wall time (`elapsedMs`, retries and backoff included), and the AI spend OpenRouter
+ * reported, as integer micro-USD (no floats in money). Read off the transcripts frozen on the
+ * decision — timings and usage, never a value. Nothing when no fact kept a transcript (an erased
+ * claim's are stripped), so a missing cost never reads as a real zero. The same-event judge's spend
+ * lives on the `unique` fact, which the decision row does not keep: not counted here.
+ */
+export function factCost(facts) {
+    const durationsMs = {};
+    let costUsd = 0;
+    let seen = false;
+    for (const [plane, byName] of [
+        ["ext", facts.ext],
+        ["ai", facts.ai],
+    ]) {
+        for (const [name, fact] of Object.entries(byName)) {
+            const transcript = fact?.transcript;
+            if (!transcript)
+                continue;
+            seen = true;
+            if (typeof transcript.elapsedMs === "number") {
+                durationsMs[`${plane}.${name}`] = transcript.elapsedMs;
+            }
+            if (typeof transcript.usage?.costUsd === "number")
+                costUsd += transcript.usage.costUsd;
+        }
+    }
+    return seen ? { durationsMs, costMicroUsd: Math.round(costUsd * 1_000_000) } : {};
+}
+//# sourceMappingURL=notify.js.map

package/dist/lib/api-lane/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../../src/lib/api-lane/notify.ts"],"names":[],"mappings":"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"}

package/dist/lib/api-lane/pause.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pausing an API source (Go Prod §5): new submits answer `503 SOURCE_PAUSED { reason }`, in-flight
+ * claims finish. The API lane's twin of `pauseCollection` (workflows/steps.ts): the latest reason is
+ * always recorded, but only a real active → paused transition is announced — on the source's
+ * timeline and as the `source.paused` webhook (sent by the retry tick) — so a retried step tells
+ * nobody twice.
+ */
+import { type SourcePausedReason } from "../../contracts/index.js";
+import type { Database } from "../../db/client.js";
+import type { Logger } from "../logger.js";
+import { type AlertDeps } from "../sentry.js";
+/**
+ * Pause the source; true iff this call changed it (paused it, or changed why). The announcement is
+ * keyed by the row's own `updatedAt`, not the clock, and made whenever the source IS paused — so a
+ * step that died between the UPDATE and the enqueue re-announces the same event on its retry
+ * instead of losing it, and a new reason is a new event.
+ */
+export declare function pauseSource(db: Database, deps: AlertDeps, sourceId: string, reason: SourcePausedReason, issues?: unknown, 
+/** False for a caller that pages once for many sources (`pauseForEngineCredits`). */
+alert?: boolean): Promise<boolean>;
+/**
+ * `pauseSource`'s announcement half, for a source some UPDATE already paused: the timeline event and
+ * the `source.paused` webhook whenever the source IS paused (keyed by its `updatedAt`), and — when
+ * `changed` — the log line and, unless `alert` is false, the page. Returns `changed` as applied.
+ * `pauseForEngineCredits` (workflows/steps.ts) calls it for the ids its one bulk UPDATE returned.
+ */
+export declare function announceSourcePaused(db: Database, deps: AlertDeps, sourceId: string, reason: SourcePausedReason, issues: unknown, changed: boolean, alert?: boolean): Promise<boolean>;
+/**
+ * The engine-credits resume for sources (§7.3 "resume"): the engine's `402` paused every active
+ * source; once its `/me` says `billingStatus: ok`, every source paused for THAT reason — never a
+ * rubric or an operator pause — comes back, and each announces `source.resumed` (keyed by the
+ * row's `updatedAt`, like the pause). The source ids resumed.
+ */
+export declare function resumeCreditPausedSources(db: Database, logger: Logger): Promise<string[]>;
+/**
+ * The operator's resume (`POST /v1/api/admin/sources/:id/resume`): lifts ANY pause, the ones only a
+ * person can lift included. True iff this call changed it; only that transition is announced — an
+ * active source has nothing to resume, and the route's `Idempotency-Key` covers a client's retry.
+ */
+export declare function resumeSource(db: Database, logger: Logger, sourceId: string): Promise<boolean>;
+//# sourceMappingURL=pause.d.ts.map

package/dist/lib/api-lane/pause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pause.d.ts","sourceRoot":"","sources":["../../../src/lib/api-lane/pause.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,WAAW,CAAC;AAIxD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,CAAC,EAAE,OAAO;AAChB,qFAAqF;AACrF,KAAK,UAAO,GACX,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,EAChB,KAAK,UAAO,GACX,OAAO,CAAC,OAAO,CAAC,CA0ClB;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa/F;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAkBlB"}

package/dist/lib/api-lane/pause.js

@@ -0,0 +1,155 @@
+/**
+ * Pausing an API source (Go Prod §5): new submits answer `503 SOURCE_PAUSED { reason }`, in-flight
+ * claims finish. The API lane's twin of `pauseCollection` (workflows/steps.ts): the latest reason is
+ * always recorded, but only a real active → paused transition is announced — on the source's
+ * timeline and as the `source.paused` webhook (sent by the retry tick) — so a retried step tells
+ * nobody twice.
+ */
+import { and, eq, ne, notInArray } from "drizzle-orm";
+import { SourceEventData } from "../../contracts/index.js";
+import { apiSources } from "../../db/schema.js";
+import { reportAlert } from "../sentry.js";
+import { recordEvents } from "./timeline.js";
+import { enqueueWebhook } from "./webhooks.js";
+/**
+ * Pause the source; true iff this call changed it (paused it, or changed why). The announcement is
+ * keyed by the row's own `updatedAt`, not the clock, and made whenever the source IS paused — so a
+ * step that died between the UPDATE and the enqueue re-announces the same event on its retry
+ * instead of losing it, and a new reason is a new event.
+ */
+export async function pauseSource(db, deps, sourceId, reason, issues, 
+/** False for a caller that pages once for many sources (`pauseForEngineCredits`). */
+alert = true) {
+    const where = eq(apiSources.sourceId, sourceId);
+    const [transition] = await db
+        .update(apiSources)
+        .set({ status: "paused", pausedReason: reason })
+        .where(and(where, eq(apiSources.status, "active")))
+        .returning({ sourceId: apiSources.sourceId });
+    // Already paused: record the latest reason — except that `engine-credits` never replaces a
+    // reason only a person can lift (a broken rubric, an operator's hand), or the credits cron's
+    // auto-resume would un-pause it.
+    const [changed] = transition
+        ? [transition]
+        : await db
+            .update(apiSources)
+            .set({ pausedReason: reason })
+            .where(and(where, eq(apiSources.status, "paused"), ne(apiSources.pausedReason, reason), reason === "engine-credits"
+            ? notInArray(apiSources.pausedReason, ["rubric-unusable", "operator"])
+            : undefined))
+            .returning({ sourceId: apiSources.sourceId });
+    return announceSourcePaused(db, deps, sourceId, reason, issues, !!changed, alert);
+}
+/**
+ * `pauseSource`'s announcement half, for a source some UPDATE already paused: the timeline event and
+ * the `source.paused` webhook whenever the source IS paused (keyed by its `updatedAt`), and — when
+ * `changed` — the log line and, unless `alert` is false, the page. Returns `changed` as applied.
+ * `pauseForEngineCredits` (workflows/steps.ts) calls it for the ids its one bulk UPDATE returned.
+ */
+export async function announceSourcePaused(db, deps, sourceId, reason, issues, changed, alert = true) {
+    const row = await db.query.apiSources.findFirst({ where: eq(apiSources.sourceId, sourceId) });
+    if (row?.status !== "paused" || !row.pausedReason)
+        return false;
+    const at = row.updatedAt;
+    const [eventId] = await recordEvents(db, [
+        {
+            key: `${sourceId}:paused:${row.pausedReason}:${at.getTime()}`,
+            at,
+            sourceId,
+            claimId: null,
+            type: "source.paused",
+            data: { reason: row.pausedReason, ...(issues === undefined ? {} : { issues }) },
+        },
+    ]);
+    // `source.paused` (App. B) — the engine's issues ride along only in the wire's shape.
+    const shaped = SourceEventData.shape.issues.safeParse(issues);
+    await enqueueWebhook(db, {
+        eventId: eventId,
+        type: "source.paused",
+        createdAt: at,
+        sourceId,
+        claimId: null,
+        data: {
+            sourceId,
+            status: "paused",
+            pausedReason: row.pausedReason,
+            ...(shaped.success && shaped.data ? { issues: shaped.data } : {}),
+        },
+    });
+    if (changed) {
+        deps.logger.error("api.source-paused", { sourceId, reason, issues: issues ?? null });
+        // A paused source answers every submit 503 — a customer is down until someone acts.
+        if (alert) {
+            await reportAlert(deps, `api.source-paused.${reason}`, { sourceId, reason }, `api.source-paused.${reason}:${sourceId}`);
+        }
+    }
+    return changed;
+}
+/**
+ * The engine-credits resume for sources (§7.3 "resume"): the engine's `402` paused every active
+ * source; once its `/me` says `billingStatus: ok`, every source paused for THAT reason — never a
+ * rubric or an operator pause — comes back, and each announces `source.resumed` (keyed by the
+ * row's `updatedAt`, like the pause). The source ids resumed.
+ */
+export async function resumeCreditPausedSources(db, logger) {
+    const rows = await db
+        .update(apiSources)
+        .set({ status: "active", pausedReason: null })
+        .where(and(eq(apiSources.status, "paused"), eq(apiSources.pausedReason, "engine-credits")))
+        .returning({ sourceId: apiSources.sourceId, updatedAt: apiSources.updatedAt });
+    for (const { sourceId, updatedAt } of rows) {
+        await announceResumed(db, sourceId, updatedAt, "engine-credits");
+    }
+    if (rows.length > 0) {
+        logger.info("api.sources-resumed", { sources: rows.map((r) => r.sourceId) });
+    }
+    return rows.map((r) => r.sourceId);
+}
+/**
+ * The operator's resume (`POST /v1/api/admin/sources/:id/resume`): lifts ANY pause, the ones only a
+ * person can lift included. True iff this call changed it; only that transition is announced — an
+ * active source has nothing to resume, and the route's `Idempotency-Key` covers a client's retry.
+ */
+export async function resumeSource(db, logger, sourceId) {
+    const where = eq(apiSources.sourceId, sourceId);
+    // Read first: RETURNING shows the row after the UPDATE, and the event says which pause lifted.
+    const prior = await db.query.apiSources.findFirst({
+        columns: { status: true, pausedReason: true },
+        where,
+    });
+    if (prior?.status !== "paused")
+        return false;
+    const [row] = await db
+        .update(apiSources)
+        .set({ status: "active", pausedReason: null })
+        .where(and(where, eq(apiSources.status, "paused")))
+        .returning({ updatedAt: apiSources.updatedAt });
+    if (!row)
+        return false;
+    const reason = prior.pausedReason ?? "operator";
+    await announceResumed(db, sourceId, row.updatedAt, reason);
+    logger.info("api.source-resumed", { sourceId, reason });
+    return true;
+}
+/** `source.resumed` on the timeline and as the webhook, keyed by the row's `updatedAt`. */
+async function announceResumed(db, sourceId, at, reason) {
+    const [eventId] = await recordEvents(db, [
+        {
+            key: `${sourceId}:resumed:${at.getTime()}`,
+            at,
+            sourceId,
+            claimId: null,
+            type: "source.resumed",
+            data: { reason },
+        },
+    ]);
+    await enqueueWebhook(db, {
+        eventId: eventId,
+        type: "source.resumed",
+        createdAt: at,
+        sourceId,
+        claimId: null,
+        data: { sourceId, status: "active", pausedReason: null },
+    });
+}
+//# sourceMappingURL=pause.js.map

package/dist/lib/api-lane/pause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pause.js","sourceRoot":"","sources":["../../../src/lib/api-lane/pause.ts"],"names":[],"mappings":"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"}

package/dist/lib/api-lane/record.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The §4.4 claim record (Go Prod §4.4, §5, §10) — built ONE way for everyone who shows a claim: the
+ * `GET /v1/api/claims/:claimId` route, the sync 200, every `claim.*` webhook's `data`, the operator
+ * view and a source's linked collections. A second builder would drift, and the record is a
+ * published wire shape, so it is parsed with the contract's `ClaimRecord` before it leaves: a
+ * mismatch is a loud bug here, never a malformed response.
+ *
+ * Both lanes (contracts v1.2): an API claim is headed by its `api_claims` row; a chain claim (no
+ * such row, `claim_ingests.lane = chain`) by its ledger row and its watched collection's protocol.
+ * Everything after the head — status, decision, review, webhook, error — is the same mapping.
+ *
+ * NEVER the answers (§6.3): `api_claims.body` is not even read, and `error.message` is fixed text
+ * per code — the stored `claim_ingests.error` can echo a handler's or the engine's text, which can
+ * quote answer values.
+ */
+import { type ClaimErrorCode, ClaimRecord } from "../../contracts/api.js";
+import type { Database } from "../../db/client.js";
+import { type ApiClaim } from "../../db/schema.js";
+/**
+ * The prefixes a deterministic failure's message starts with — written by the thrower (source.ts,
+ * the evaluate step), read back off `claim_ingests.error` by `claimErrorCode`. One list, so the two
+ * cannot drift.
+ */
+export declare const FAILURE: {
+    readonly bodyMismatch: "BODY_MISMATCH";
+    readonly bodyErased: "BODY_ERASED";
+    readonly contentMissing: "CONTENT_MISSING";
+    readonly uploadUnsupported: "UPLOAD_UNSUPPORTED";
+    readonly uploadMissing: "UPLOAD_MISSING";
+    readonly attachmentInvalid: "ATTACHMENT_INVALID";
+    readonly engineRejected: "Engine rejected the facts";
+    readonly engineConflict: "CONFLICT";
+};
+/**
+ * How long before the reservation runs out a paid review closes: after the answer, the fold and then
+ * the settle still have to reach the facilitator, and an unextended expiry is reckoned from our
+ * charge row's `createdAt`, written a moment AFTER the facilitator's verify started its clock.
+ */
+export declare const ANSWER_BY_MARGIN_MS: number;
+/**
+ * A paid claim's review deadline — THE value the record, the reviewer view, the emails and the
+ * `REVIEW_EXPIRED` refusal all use: the reservation's expiry as payments reckons it, less the margin.
+ */
+export declare const answerByOf: (charge: {
+    createdAt: Date;
+    reservationExpiresAt: Date | null;
+}) => Date;
+/** One sentence per code — the only failure text a customer ever sees (see header). */
+export declare const CLAIM_ERROR_MESSAGES: Record<ClaimErrorCode, string>;
+export declare function claimRecord(db: Database, claimId: string, opts?: {
+    sourceId?: string;
+}): Promise<ClaimRecord | null>;
+/**
+ * The same record for many claims — a list page — in ONE read per table per 100 ids, never seven
+ * per claim. In the input order; an id that is neither an API claim nor a chain claim of a watched
+ * collection with a known protocol is skipped. `sourceId` stamps the chain claims of a page read
+ * through a source's linked collection (an API claim always carries its own).
+ */
+export declare function claimRecordsFor(db: Database, claimIds: readonly string[], opts?: {
+    sourceId?: string;
+}): Promise<ClaimRecord[]>;
+/** The two `api_claims` columns → `ClaimRecord.submittedVia`: a name always came with its flag
+ *  (accept writes both), so the name alone says whether there is one. */
+export declare const submittedViaOfRow: (row: Pick<ApiClaim, "submittedVia" | "submittedViaVerified">) => ClaimRecord["submittedVia"];
+/**
+ * A `decisions` row that records why there is NO decision — the claim's failure, never a verdict:
+ * the facts lane's `invalid_facts`, or the engine refusing the content we sent (the oracle's side
+ * of the binding, so `engine_rejected`). Null for a row the engine decided.
+ */
+export declare function decisionFailure(status: string | null | undefined): ClaimErrorCode | null;
+/**
+ * A failed claim's §5 code, read off the ledger's stored error by its known prefixes only — the one
+ * place it is decided, shared with the `failed` timeline event (notify.ts).
+ */
+export declare function claimErrorCode(ingestError: string | null, decisionStatus: string | null): ClaimErrorCode;
+//# sourceMappingURL=record.d.ts.map

package/dist/lib/api-lane/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/lib/api-lane/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,WAAW,EAKZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAEL,KAAK,QAAQ,EAcd,MAAM,iBAAiB,CAAC;AAKzB;;;;GAIG;AACH,eAAO,MAAM,OAAO;aAClB,YAAY,EAAE,eAAe;aAC7B,UAAU,EAAE,aAAa;aACzB,cAAc,EAAE,iBAAiB;aACjC,iBAAiB,EAAE,oBAAoB;aACvC,aAAa,EAAE,gBAAgB;aAC/B,iBAAiB,EAAE,oBAAoB;aACvC,cAAc,EAAE,2BAA2B;aAC3C,cAAc,EAAE,UAAU;CAClB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAa,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,UAAU,WAAY;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,oBAAoB,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,KAAG,IACvB,CAAC;AAEtE,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAQ/D,CAAC;AAEF,wBAAsB,WAAW,CAC/B,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAE7B;AAaD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,WAAW,EAAE,CAAC,CAuDxB;AA+CD;yEACyE;AACzE,eAAO,MAAM,iBAAiB,QACvB,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,sBAAsB,CAAC,KAC3D,WAAW,CAAC,cAAc,CACsE,CAAC;AA4MpG;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAIxF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,cAAc,CAWhB"}