@ixo/decision-oracle 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,337 @@
+/**
+ * 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 { and, eq, inArray } from "drizzle-orm";
+import { ClaimRecord, } from "../../contracts/api.js";
+import { apiCharges, apiClaims, apiEvents, claimIngests, claimReviews, decisions, matrixDeliveries, watchedCollections, } from "../../db/schema.js";
+import { reservationExpiry } from "../payments/extend.js";
+import { chargeTerms } from "../payments/terms.js";
+import { reviewTaskOf } from "../review/tasks.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 const FAILURE = {
+    bodyMismatch: "BODY_MISMATCH",
+    bodyErased: "BODY_ERASED",
+    contentMissing: "CONTENT_MISSING",
+    uploadUnsupported: "UPLOAD_UNSUPPORTED",
+    uploadMissing: "UPLOAD_MISSING",
+    attachmentInvalid: "ATTACHMENT_INVALID",
+    engineRejected: "Engine rejected the facts",
+    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 const ANSWER_BY_MARGIN_MS = 5 * 60_000;
+/**
+ * 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 const answerByOf = (charge) => new Date(reservationExpiry(charge).getTime() - ANSWER_BY_MARGIN_MS);
+/** One sentence per code — the only failure text a customer ever sees (see header). */
+export const CLAIM_ERROR_MESSAGES = {
+    invalid_facts: "The oracle could not produce facts for this claim that match the protocol's work order.",
+    engine_rejected: "The claim was refused: its facts were not accepted, or its content did not match.",
+    body_mismatch: "The stored claim body was erased or no longer matched its digest, so it was not evaluated.",
+    retries_exhausted: "The claim could not be evaluated before its retries ran out.",
+};
+export async function claimRecord(db, claimId, opts = {}) {
+    return (await claimRecordsFor(db, [claimId], opts))[0] ?? null;
+}
+/** D1 binds at most 100 parameters per STATEMENT, and two of these reads bind one more beside
+ *  the ids (`type = 'review_required'`, `kind = 'webhook'`) — so 99 ids a chunk. */
+const CHUNK = 99;
+const chunked = (ids) => {
+    const unique = [...new Set(ids)];
+    const chunks = [];
+    for (let i = 0; i < unique.length; i += CHUNK)
+        chunks.push(unique.slice(i, i + CHUNK));
+    return chunks;
+};
+/**
+ * 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 async function claimRecordsFor(db, claimIds, opts = {}) {
+    const read = await Promise.all(chunked(claimIds).map((chunk) => readRows(db, chunk)));
+    const byClaim = (rows) => new Map(rows.map((r) => [r.claimId, r]));
+    const claims = byClaim(read.flatMap((r) => r.claims));
+    const ingests = byClaim(read.flatMap((r) => r.ingests));
+    const decisionRows = byClaim(read.flatMap((r) => r.decisions));
+    const reviews = byClaim(read.flatMap((r) => r.reviews));
+    const charges = byClaim(read.flatMap((r) => r.charges));
+    // The LATEST `review_required` event per claim: its tasks are what the reviewer was asked
+    // (§10.1). Event ids are ULIDs, so the greatest is the newest.
+    const reviewEvents = new Map();
+    for (const e of read.flatMap((r) => r.reviewEvents)) {
+        const seen = reviewEvents.get(e.claimId);
+        if (!seen || e.eventId > seen.eventId)
+            reviewEvents.set(e.claimId, e);
+    }
+    const deliveries = Map.groupBy(read.flatMap((r) => r.deliveries), (d) => d.claimId);
+    // A chain claim's protocol is its collection's: one more read, for the page's collections only.
+    const chainCollections = [...ingests.values()]
+        .filter((i) => i.lane === "chain" && !claims.has(i.claimId))
+        .map((i) => i.collectionId);
+    const protocols = new Map((await Promise.all(chunked(chainCollections).map((chunk) => db.query.watchedCollections.findMany({
+        where: inArray(watchedCollections.collectionId, chunk),
+        columns: { collectionId: true, protocolDid: true },
+    }))))
+        .flat()
+        .map((w) => [w.collectionId, w.protocolDid]));
+    return claimIds.flatMap((id) => {
+        const head = headOf(claims.get(id), ingests.get(id), protocols, opts.sourceId ?? null);
+        if (!head)
+            return [];
+        return [
+            recordOf({
+                head,
+                ingest: ingests.get(id),
+                decision: decisionRows.get(id),
+                review: reviews.get(id),
+                charge: charges.get(id),
+                reviewEvent: reviewEvents.get(id),
+                deliveries: deliveries.get(id) ?? [],
+            }),
+        ];
+    });
+}
+/** One read per table for up to `CHUNK` ids. */
+function readRows(db, ids) {
+    return Promise.all([
+        db.query.apiClaims.findMany({
+            where: inArray(apiClaims.claimId, ids),
+            // The body is personal data and never part of the record (§6.3) — not even read.
+            columns: {
+                claimId: true,
+                sourceId: true,
+                protocolDid: true,
+                submitter: true,
+                submittedBy: true,
+                submittedVia: true,
+                submittedViaVerified: true,
+                contentDigest: true,
+                metadata: true,
+                receivedAt: true,
+            },
+        }),
+        db.query.claimIngests.findMany({ where: inArray(claimIngests.claimId, ids) }),
+        db.query.decisions.findMany({ where: inArray(decisions.claimId, ids) }),
+        db.query.claimReviews.findMany({
+            where: inArray(claimReviews.claimId, ids),
+            columns: { claimId: true, answeredAt: true, foldedAt: true, foldError: true },
+        }),
+        db.query.apiCharges.findMany({ where: inArray(apiCharges.claimId, ids) }),
+        db.query.apiEvents.findMany({
+            where: and(inArray(apiEvents.claimId, ids), eq(apiEvents.type, "review_required")),
+            columns: { claimId: true, eventId: true, data: true },
+        }),
+        db.query.matrixDeliveries.findMany({
+            where: and(inArray(matrixDeliveries.claimId, ids), eq(matrixDeliveries.kind, "webhook")),
+            columns: { claimId: true, dedupeKey: true, status: true, attempts: true },
+        }),
+    ]).then(([claims, ingests, decisions, reviews, charges, reviewEvents, deliveries]) => ({
+        claims,
+        ingests,
+        decisions,
+        reviews,
+        charges,
+        reviewEvents,
+        deliveries,
+    }));
+}
+/** 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 const submittedViaOfRow = (row) => row.submittedVia ? { name: row.submittedVia, verified: row.submittedViaVerified === true } : null;
+/**
+ * An API claim is its `api_claims` row; a chain claim its ledger row, with the watched collection's
+ * protocol (null only on a row registered before the column existed — nothing to show it under).
+ */
+function headOf(claim, ingest, protocols, sourceId) {
+    if (claim) {
+        return {
+            claimId: claim.claimId,
+            lane: "api",
+            sourceId: claim.sourceId,
+            collectionId: null,
+            protocolDid: claim.protocolDid,
+            submitter: claim.submitter ?? null,
+            submittedBy: claim.submittedBy ?? null,
+            submittedVia: submittedViaOfRow(claim),
+            contentDigest: claim.contentDigest ?? null,
+            metadata: claim.metadata ?? null,
+            createdAt: claim.receivedAt,
+        };
+    }
+    const protocolDid = ingest?.lane === "chain" ? protocols.get(ingest.collectionId) : null;
+    if (!ingest || !protocolDid)
+        return null;
+    return {
+        claimId: ingest.claimId,
+        lane: "chain",
+        sourceId,
+        collectionId: ingest.collectionId,
+        protocolDid,
+        submitter: null,
+        submittedBy: null,
+        submittedVia: null,
+        contentDigest: null,
+        metadata: null,
+        createdAt: ingest.createdAt,
+    };
+}
+/** The rows → the record: pure, so a single GET and a list page cannot build it two ways. */
+function recordOf({ head, ingest, decision, review, charge, reviewEvent, deliveries, }) {
+    // `skipped` is a chain-lane ledger state, and a missing row cannot outlive the accept batch that
+    // writes it beside `api_claims` — neither is a failure, so both read as not-yet-started `queued`.
+    const status = ingest && ingest.status !== "skipped" ? ingest.status : "queued";
+    const inReview = review !== undefined || decision?.status === "pending_review";
+    const decisionPending = decision?.decision?.pendingTasks ?? [];
+    const eventTasks = reviewEvent?.data?.pendingTasks;
+    const errorCode = status === "failed" ? claimErrorCode(ingest?.error ?? null, decision?.status ?? null) : null;
+    return ClaimRecord.parse({
+        claimId: head.claimId,
+        lane: head.lane,
+        sourceId: head.sourceId,
+        collectionId: head.collectionId,
+        protocolDid: head.protocolDid,
+        submitter: head.submitter,
+        submittedBy: head.submittedBy,
+        submittedVia: head.submittedVia,
+        contentDigest: head.contentDigest,
+        status,
+        decision: decision
+            ? {
+                status: decision.status,
+                verdict: decision.verdict,
+                rubricId: decision.rubricId,
+                factsDigest: decision.factsDigest,
+                resultDigest: decision.resultDigest,
+                decision: decision.decision,
+                explanation: decision.explanation,
+                receipt: decision.receiptCid && decision.receiptJws
+                    ? { cid: decision.receiptCid, jws: decision.receiptJws }
+                    : null,
+                // The API lane never signs; a chain claim shows where its `MsgEvaluateClaim` got to.
+                chainStatus: head.lane === "chain" ? decision.chainStatus : "skipped",
+                ...(decision.erroredFacts?.length ? { erroredFacts: decision.erroredFacts } : {}),
+            }
+            : null,
+        review: inReview
+            ? {
+                // The event's stored tasks, never a fresh manifest read: a later manifest change must not
+                // rewrite what the reviewer was asked. Without the event, the fallback deliver.ts
+                // `reviewTasks` uses (the engine's synthetic tasks stay approve/reject).
+                pendingTasks: Array.isArray(eventTasks)
+                    ? eventTasks
+                    : decisionPending.map((id) => reviewTaskOf(id, undefined)),
+                answeredAt: review?.answeredAt.toISOString() ?? null,
+                foldedAt: review?.foldedAt?.toISOString() ?? null,
+                foldError: review?.foldError ?? null,
+                // A paid claim's deadline while it awaits review (`answerByOf`). Null with no charge
+                // (`none`) and once the review is no longer pending.
+                answerBy: charge && decision?.status === "pending_review"
+                    ? answerByOf(charge).toISOString()
+                    : null,
+            }
+            : null,
+        payment: charge
+            ? {
+                ...chargeTerms(charge),
+                settlementId: charge.settlementId,
+                status: charge.status,
+                transaction: charge.txHash,
+                refundedAt: charge.refundedAt?.toISOString() ?? null,
+                refundId: charge.refundId,
+                refundedAmountCents: charge.refundedAmountCents,
+            }
+            : null,
+        webhook: webhookState(deliveries),
+        error: errorCode ? { code: errorCode, message: CLAIM_ERROR_MESSAGES[errorCode] } : null,
+        metadata: head.metadata,
+        createdAt: head.createdAt.toISOString(),
+        // When the verdict the record shows was reached: the fold's time once answers were folded (the
+        // row's `createdAt` is the PRE-review decision); the row's own time for a `decided`/`unusable`
+        // row; null while a human still owes answers, and for `invalid_facts` — the engine never decided.
+        decidedAt: review?.foldedAt
+            ? review.foldedAt.toISOString()
+            : decision?.status === "decided" || decision?.status === "unusable"
+                ? decision.createdAt.toISOString()
+                : null,
+    });
+}
+/**
+ * The claim's LATEST webhook event, aggregated over its targets (§4.5). The event id is the middle
+ * of the `wh:<eventId>:<target>` key, and event ids are ULIDs, so the greatest is the newest.
+ * Per row: `sent` ⇒ `delivered` (the wire says what the receiver got), `failed` / `dead` /
+ * `pending` as themselves, and `skipped` — never written on a webhook row — as not-yet-delivered
+ * `pending`. Then `dead` if any target is, `delivered` only when all are, `failed` (a retry is due)
+ * if any is, else `pending`.
+ */
+function webhookState(rows) {
+    if (rows.length === 0)
+        return null;
+    const eventOf = (key) => key.split(":")[1] ?? "";
+    const latest = rows.map((r) => eventOf(r.dedupeKey)).reduce((a, b) => (b > a ? b : a));
+    const event = rows.filter((r) => eventOf(r.dedupeKey) === latest);
+    const statuses = event.map((r) => r.status);
+    const status = statuses.includes("dead")
+        ? "dead"
+        : statuses.every((s) => s === "sent")
+            ? "delivered"
+            : statuses.includes("failed")
+                ? "failed"
+                : "pending";
+    return { status, attempts: event.reduce((n, r) => n + r.attempts, 0) };
+}
+/**
+ * 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 function decisionFailure(status) {
+    if (status === "invalid_facts")
+        return "invalid_facts";
+    if (status === "content_mismatch" || status === "payload_too_large")
+        return "engine_rejected";
+    return 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 function claimErrorCode(ingestError, decisionStatus) {
+    const failed = decisionFailure(decisionStatus);
+    if (failed)
+        return failed;
+    const is = (...prefixes) => prefixes.some((p) => ingestError?.startsWith(p));
+    if (is(FAILURE.bodyMismatch, FAILURE.bodyErased, FAILURE.contentMissing))
+        return "body_mismatch";
+    // A file the facts lane cannot read is facts it cannot produce, not a retry that ran out.
+    if (is(FAILURE.uploadUnsupported, FAILURE.uploadMissing, FAILURE.attachmentInvalid)) {
+        return "invalid_facts";
+    }
+    if (is(FAILURE.engineRejected, FAILURE.engineConflict, "VALIDATION"))
+        return "engine_rejected";
+    return "retries_exhausted";
+}
+//# sourceMappingURL=record.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../src/lib/api-lane/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAEL,WAAW,GAKZ,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAIL,UAAU,EACV,SAAS,EACT,SAAS,EAGT,YAAY,EACZ,YAAY,EAEZ,SAAS,EAET,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,YAAY,EAAE,eAAe;IAC7B,UAAU,EAAE,aAAa;IACzB,cAAc,EAAE,iBAAiB;IACjC,iBAAiB,EAAE,oBAAoB;IACvC,aAAa,EAAE,gBAAgB;IAC/B,iBAAiB,EAAE,oBAAoB;IACvC,cAAc,EAAE,2BAA2B;IAC3C,cAAc,EAAE,UAAU;CAClB,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAA8D,EAAQ,EAAE,CACjG,IAAI,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,GAAG,mBAAmB,CAAC,CAAC;AAEtE,uFAAuF;AACvF,MAAM,CAAC,MAAM,oBAAoB,GAAmC;IAClE,aAAa,EACX,yFAAyF;IAC3F,eAAe,EACb,mFAAmF;IACrF,aAAa,EACX,4FAA4F;IAC9F,iBAAiB,EAAE,8DAA8D;CAClF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAY,EACZ,OAAe,EACf,IAAI,GAA0B,EAAE;IAEhC,OAAO,CAAC,MAAM,eAAe,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AACjE,CAAC;AAED;oFACoF;AACpF,MAAM,KAAK,GAAG,EAAE,CAAC;AAEjB,MAAM,OAAO,GAAG,CAAC,GAAsB,EAAE,EAAE;IACzC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACvF,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,EAAY,EACZ,QAA2B,EAC3B,IAAI,GAA0B,EAAE;IAEhC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAEtF,MAAM,OAAO,GAAG,CAAuC,IAAS,EAAE,EAAE,CAClE,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAiB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACxD,0FAA0F;IAC1F,+DAA+D;IAC/D,MAAM,YAAY,GAAG,IAAI,GAAG,EAA8C,CAAC;IAC3E,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,OAAiB,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO;YAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,OAAiB,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAC5B,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,EACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAiB,CAC3B,CAAC;IACF,gGAAgG;IAChG,MAAM,gBAAgB,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;SAC3C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;SAC3D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,CACvB,CACE,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACtC,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,QAAQ,CAAC;QACnC,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,YAAY,EAAE,KAAK,CAAC;QACtD,OAAO,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;KACnD,CAAC,CACH,CACF,CACF;SACE,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAC/C,CAAC;IAEF,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC;QACvF,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC;QACrB,OAAO;YACL,QAAQ,CAAC;gBACP,IAAI;gBACJ,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvB,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvB,WAAW,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjC,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE;aACrC,CAAC;SACH,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gDAAgD;AAChD,SAAS,QAAQ,CAAC,EAAY,EAAE,GAAa;IAC3C,OAAO,OAAO,CAAC,GAAG,CAAC;QACjB,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC1B,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC;YACtC,iFAAiF;YACjF,OAAO,EAAE;gBACP,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,IAAI;gBACjB,SAAS,EAAE,IAAI;gBACf,WAAW,EAAE,IAAI;gBACjB,YAAY,EAAE,IAAI;gBAClB,oBAAoB,EAAE,IAAI;gBAC1B,aAAa,EAAE,IAAI;gBACnB,QAAQ,EAAE,IAAI;gBACd,UAAU,EAAE,IAAI;aACjB;SACF,CAAC;QACF,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;QAC7E,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;QACvE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC;YAC7B,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC;YACzC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE;SAC9E,CAAC;QACF,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;QACzE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC;YAC1B,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;YAClF,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;SACtD,CAAC;QACF,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,QAAQ,CAAC;YACjC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACxF,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC1E,CAAC;KACH,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;QACrF,MAAM;QACN,OAAO;QACP,SAAS;QACT,OAAO;QACP,OAAO;QACP,YAAY;QACZ,UAAU;KACX,CAAC,CAAC,CAAC;AACN,CAAC;AAED;yEACyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,GAA4D,EAC/B,EAAE,CAC/B,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,YAAY,EAAE,QAAQ,EAAE,GAAG,CAAC,oBAAoB,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAiBpG;;;GAGG;AACH,SAAS,MAAM,CACb,KAca,EACb,MAA+B,EAC/B,SAAqC,EACrC,QAAuB;IAEvB,IAAI,KAAK,EAAE,CAAC;QACV,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK;YACX,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;YAClC,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI;YACtC,YAAY,EAAE,iBAAiB,CAAC,KAAK,CAAC;YACtC,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;YAC1C,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;YAChC,SAAS,EAAE,KAAK,CAAC,UAAU;SAC5B,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzF,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,OAAO;QACb,QAAQ;QACR,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,WAAW;QACX,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,IAAI;QACjB,YAAY,EAAE,IAAI;QAClB,aAAa,EAAE,IAAI;QACnB,QAAQ,EAAE,IAAI;QACd,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC;AACJ,CAAC;AAaD,6FAA6F;AAC7F,SAAS,QAAQ,CAAC,EAChB,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,MAAM,EACN,MAAM,EACN,WAAW,EACX,UAAU,GACA;IACV,iGAAiG;IACjG,kGAAkG;IAClG,MAAM,MAAM,GAAgB,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAE7F,MAAM,QAAQ,GAAG,MAAM,KAAK,SAAS,IAAI,QAAQ,EAAE,MAAM,KAAK,gBAAgB,CAAC;IAC/E,MAAM,eAAe,GAAG,QAAQ,EAAE,QAAQ,EAAE,YAAY,IAAI,EAAE,CAAC;IAC/D,MAAM,UAAU,GAAG,WAAW,EAAE,IAAI,EAAE,YAAY,CAAC;IACnD,MAAM,SAAS,GACb,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,IAAI,IAAI,EAAE,QAAQ,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE/F,OAAO,WAAW,CAAC,KAAK,CAAC;QACvB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,MAAM;QACN,QAAQ,EAAE,QAAQ;YAChB,CAAC,CAAC;gBACE,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,OAAO,EAAE,QAAQ,CAAC,OAAyB;gBAC3C,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,YAAY,EAAE,QAAQ,CAAC,YAAY;gBACnC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,OAAO,EACL,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU;oBACxC,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE,QAAQ,CAAC,UAAU,EAAE;oBACxD,CAAC,CAAC,IAAI;gBACV,qFAAqF;gBACrF,WAAW,EAAE,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;gBACrE,GAAG,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClF;YACH,CAAC,CAAC,IAAI;QACR,MAAM,EAAE,QAAQ;YACd,CAAC,CAAC;gBACE,0FAA0F;gBAC1F,kFAAkF;gBAClF,yEAAyE;gBACzE,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;oBACrC,CAAC,CAAE,UAA2B;oBAC9B,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;gBAC5D,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,WAAW,EAAE,IAAI,IAAI;gBACpD,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,IAAI;gBACjD,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,IAAI;gBACpC,qFAAqF;gBACrF,qDAAqD;gBACrD,QAAQ,EACN,MAAM,IAAI,QAAQ,EAAE,MAAM,KAAK,gBAAgB;oBAC7C,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE;oBAClC,CAAC,CAAC,IAAI;aACX;YACH,CAAC,CAAC,IAAI;QACR,OAAO,EAAE,MAAM;YACb,CAAC,CAAC;gBACE,GAAG,WAAW,CAAC,MAAM,CAAC;gBACtB,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,WAAW,EAAE,MAAM,CAAC,MAAM;gBAC1B,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,IAAI;gBACpD,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;aAChD;YACH,CAAC,CAAC,IAAI;QACR,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC;QACjC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,oBAAoB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;QACvF,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE;QACvC,+FAA+F;QAC/F,+FAA+F;QAC/F,kGAAkG;QAClG,SAAS,EAAE,MAAM,EAAE,QAAQ;YACzB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE;YAC/B,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,IAAI,QAAQ,EAAE,MAAM,KAAK,UAAU;gBACjE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE;gBAClC,CAAC,CAAC,IAAI;KACX,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CACnB,IAAiE;IAEjE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,MAAM,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAmB,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;QACtD,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC;YACnC,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAC3B,CAAC,CAAC,QAAQ;gBACV,CAAC,CAAC,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAiC;IAC/D,IAAI,MAAM,KAAK,eAAe;QAAE,OAAO,eAAe,CAAC;IACvD,IAAI,MAAM,KAAK,kBAAkB,IAAI,MAAM,KAAK,mBAAmB;QAAE,OAAO,iBAAiB,CAAC;IAC9F,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,WAA0B,EAC1B,cAA6B;IAE7B,MAAM,MAAM,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;IAC/C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,EAAE,GAAG,CAAC,GAAG,QAAkB,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,IAAI,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,cAAc,CAAC;QAAE,OAAO,eAAe,CAAC;IACjG,0FAA0F;IAC1F,IAAI,EAAE,CAAC,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACpF,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,IAAI,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,YAAY,CAAC;QAAE,OAAO,iBAAiB,CAAC;IAC/F,OAAO,mBAAmB,CAAC;AAC7B,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * Erasure, and the operational housekeeping (Go Prod §6.1, §6.3, §7.3; owner, 2026-10-11). The
+ * oracle NEVER deletes an organisation's claim data on its own: a claim's answers (and the claim
+ * `content` that repeats them), its attachment descriptors, `submitter`, `metadata`, the webhook
+ * URL, its uploaded files and the webhook payloads that echo `metadata` stay until the organisation
+ * erases the claim (`DELETE /v1/api/claims/:claimId/body`, `eraseClaimBody` below). The row, the
+ * digests, the decision and its receipt survive an erase: they are not personal data, and
+ * `submitterDigest` keeps the frequency count honest after it.
+ *
+ * Answers also shadow into two places beside `api_claims`: the fact transcripts frozen on
+ * `decisions.facts` (an AI check's request, an external source's `send` payload) and the duplicate
+ * registry's `normalizedText` — both are stripped by the same erase; the fact VALUES stay (the act
+ * policy and the record read them, and they are codes and scores, not answers).
+ *
+ * The hourly housekeeping sweep (D12: "only housekeeping that is not the organisation's data")
+ * expires idempotency answers (24 h), OAuth approvals past their 15 minutes, auto-approvals past
+ * their end and their request locks, and deletes the upload objects an organisation's own action
+ * marked (an export bundle after its day, a deleted source's files). Timeline events, charges,
+ * audit, webhook deliveries and the email ledger are kept. Every pass is bounded — a few hundred
+ * rows a table — so a backlog drains over a few ticks and one tick stays inside D1's per-invocation
+ * budget.
+ */
+import type { Database } from "../../db/client.js";
+export declare const DAY_MS = 86400000;
+/** Rows deleted per table per sweep (uploads: also D1's bound-parameter cap on an `IN (…)`). */
+export declare const TRIM_BATCH = 100;
+/** The frozen facts minus every transcript — what an answer could have been copied into. */
+export declare function withoutTranscripts<T>(facts: T): T;
+/**
+ * Erase one claim's personal data, at the organisation's request; false when there was nothing
+ * left to erase (already erased, or no such claim). The R2 objects go first (idempotent), then
+ * every D1 write in ONE batch with the claim row LAST — so a failure anywhere leaves the claim
+ * un-erased and the caller's retry does it all again, never a half-erased claim. The claim's
+ * webhook rows lose payload and target, and queued ones die with their `attempts` bumped, so an
+ * attempt already in flight loses its lease and cannot revive them.
+ */
+export declare function eraseClaimBody(db: Database, uploads: R2Bucket | undefined, claimId: string): Promise<boolean>;
+/**
+ * One bounded pass of the housekeeping (the header's list); counts per kind, for the tick's log
+ * line. Nothing an organisation owns is deleted here unless the organisation itself marked it.
+ */
+export declare function sweepHousekeeping(db: Database, uploads: R2Bucket | undefined, now?: Date): Promise<Record<string, number>>;
+//# sourceMappingURL=retention.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../../src/lib/api-lane/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAiBhD,eAAO,MAAM,MAAM,WAAa,CAAC;AACjC,gGAAgG;AAChG,eAAO,MAAM,UAAU,MAAM,CAAC;AAI9B,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAYjD;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,QAAQ,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAuElB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,QAAQ,GAAG,SAAS,EAC7B,GAAG,OAAa,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwEjC"}

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

@@ -0,0 +1,176 @@
+/**
+ * Erasure, and the operational housekeeping (Go Prod §6.1, §6.3, §7.3; owner, 2026-10-11). The
+ * oracle NEVER deletes an organisation's claim data on its own: a claim's answers (and the claim
+ * `content` that repeats them), its attachment descriptors, `submitter`, `metadata`, the webhook
+ * URL, its uploaded files and the webhook payloads that echo `metadata` stay until the organisation
+ * erases the claim (`DELETE /v1/api/claims/:claimId/body`, `eraseClaimBody` below). The row, the
+ * digests, the decision and its receipt survive an erase: they are not personal data, and
+ * `submitterDigest` keeps the frequency count honest after it.
+ *
+ * Answers also shadow into two places beside `api_claims`: the fact transcripts frozen on
+ * `decisions.facts` (an AI check's request, an external source's `send` payload) and the duplicate
+ * registry's `normalizedText` — both are stripped by the same erase; the fact VALUES stay (the act
+ * policy and the record read them, and they are codes and scores, not answers).
+ *
+ * The hourly housekeeping sweep (D12: "only housekeeping that is not the organisation's data")
+ * expires idempotency answers (24 h), OAuth approvals past their 15 minutes, auto-approvals past
+ * their end and their request locks, and deletes the upload objects an organisation's own action
+ * marked (an export bundle after its day, a deleted source's files). Timeline events, charges,
+ * audit, webhook deliveries and the email ledger are kept. Every pass is bounded — a few hundred
+ * rows a table — so a backlog drains over a few ticks and one tick stays inside D1's per-invocation
+ * budget.
+ */
+import { and, eq, inArray, isNull, lte, sql } from "drizzle-orm";
+import { apiClaims, apiEvents, apiIdempotency, apiUploads, claimBodyDigests, decisions, matrixDeliveries, mcpApprovals, mcpStanding, mcpStandingSpends, reviewBillingDelegations, } from "../../db/schema.js";
+import { standingApprovalsAllowed } from "../oauth/standing.js";
+import { eventIdFor } from "./ids.js";
+export const DAY_MS = 86_400_000;
+/** Rows deleted per table per sweep (uploads: also D1's bound-parameter cap on an `IN (…)`). */
+export const TRIM_BATCH = 100;
+/** The frozen facts minus every transcript — what an answer could have been copied into. */
+export function withoutTranscripts(facts) {
+    const planes = facts;
+    const out = {};
+    for (const [plane, byName] of Object.entries(planes)) {
+        out[plane] = Object.fromEntries(Object.entries(byName ?? {}).map(([name, fact]) => {
+            const { transcript: _dropped, ...kept } = fact ?? {};
+            return [name, kept];
+        }));
+    }
+    return out;
+}
+/**
+ * Erase one claim's personal data, at the organisation's request; false when there was nothing
+ * left to erase (already erased, or no such claim). The R2 objects go first (idempotent), then
+ * every D1 write in ONE batch with the claim row LAST — so a failure anywhere leaves the claim
+ * un-erased and the caller's retry does it all again, never a half-erased claim. The claim's
+ * webhook rows lose payload and target, and queued ones die with their `attempts` bumped, so an
+ * attempt already in flight loses its lease and cannot revive them.
+ */
+export async function eraseClaimBody(db, uploads, claimId) {
+    const [claim, decision, files] = await Promise.all([
+        db.query.apiClaims.findFirst({
+            columns: { sourceId: true, bodyErasedAt: true },
+            where: eq(apiClaims.claimId, claimId),
+        }),
+        db.query.decisions.findFirst({
+            columns: { facts: true },
+            where: eq(decisions.claimId, claimId),
+        }),
+        db
+            .select({ uploadId: apiUploads.uploadId, r2Key: apiUploads.r2Key })
+            .from(apiUploads)
+            .where(eq(apiUploads.claimId, claimId)),
+    ]);
+    if (!claim || claim.bodyErasedAt)
+        return false;
+    // Without the bucket bound there are no objects to delete — the rows still go.
+    if (uploads && files.length > 0)
+        await uploads.delete(files.map((f) => f.r2Key));
+    const erasedAt = new Date();
+    const webhookRows = and(eq(matrixDeliveries.claimId, claimId), eq(matrixDeliveries.kind, "webhook"));
+    const [, , , , , , erased] = await db.batch([
+        db
+            .update(matrixDeliveries)
+            .set({
+            status: "dead",
+            nextAttemptAt: null,
+            lastError: "erased",
+            attempts: sql `${matrixDeliveries.attempts} + 1`,
+        })
+            .where(and(webhookRows, inArray(matrixDeliveries.status, ["pending", "failed"]))),
+        db.update(matrixDeliveries).set({ payload: null, targetUrl: null }).where(webhookRows),
+        db.delete(apiUploads).where(eq(apiUploads.claimId, claimId)),
+        db
+            .update(claimBodyDigests)
+            .set({ normalizedText: null })
+            .where(eq(claimBodyDigests.claimId, claimId)),
+        db
+            .update(decisions)
+            .set({ facts: decision?.facts ? withoutTranscripts(decision.facts) : null })
+            .where(eq(decisions.claimId, claimId)),
+        db
+            .insert(apiEvents)
+            .values({
+            eventId: await eventIdFor(`${claimId}:erased`, erasedAt),
+            sourceId: claim.sourceId,
+            claimId,
+            type: "erased",
+            data: { reason: "request" },
+            createdAt: erasedAt,
+        })
+            .onConflictDoNothing(),
+        db
+            .update(apiClaims)
+            .set({
+            body: null,
+            attachments: null,
+            submitter: null,
+            metadata: null,
+            webhookUrl: null,
+            // `contentDigest` stays, like `bodyDigest`: the receipt check outlives the answers.
+            content: null,
+            bodyErasedAt: erasedAt,
+        })
+            .where(and(eq(apiClaims.claimId, claimId), isNull(apiClaims.bodyErasedAt)))
+            .returning({ claimId: apiClaims.claimId }),
+    ]);
+    return erased.length > 0;
+}
+/**
+ * One bounded pass of the housekeeping (the header's list); counts per kind, for the tick's log
+ * line. Nothing an organisation owns is deleted here unless the organisation itself marked it.
+ */
+export async function sweepHousekeeping(db, uploads, now = new Date()) {
+    // Only objects an organisation's own action marked: an export bundle (its day is up) or a deleted
+    // source's files. A claim's uploads carry no `deleteAt` — they go with the claim's erase.
+    const marked = await db
+        .select({ uploadId: apiUploads.uploadId, r2Key: apiUploads.r2Key })
+        .from(apiUploads)
+        .where(lte(apiUploads.deleteAt, now))
+        .limit(TRIM_BATCH);
+    if (marked.length > 0) {
+        if (uploads)
+            await uploads.delete(marked.map((f) => f.r2Key));
+        await db.delete(apiUploads).where(inArray(apiUploads.uploadId, marked.map((f) => f.uploadId)));
+    }
+    // Each trim deletes at most TRIM_BATCH rows, oldest first, by rowid — and returns only a key.
+    const before = (ms) => new Date(now.getTime() - ms);
+    const rowids = (table, where) => sql `rowid in (select rowid from ${sql.identifier(table)} where ${where} limit ${TRIM_BATCH})`;
+    const idempotency = await db
+        .delete(apiIdempotency)
+        .where(rowids("api_idempotency", sql `${apiIdempotency.expiresAt} <= ${now.getTime()}`))
+        .returning({ k: apiIdempotency.idempotencyKey });
+    // OAuth approvals past their window (S7): a delegation never outlives its row's 15 minutes here.
+    const approvals = await db
+        .delete(mcpApprovals)
+        .where(rowids("mcp_approvals", sql `${mcpApprovals.expiresAt} <= ${now.getTime()}`))
+        .returning({ k: mcpApprovals.id });
+    // Auto-approve past its end (S7): it pays nothing more, so its delegation goes with the row. With
+    // `allowStandingApprovals` off (D8/F13) none pays at all, so EVERY stored one goes — the user's
+    // spending authority does not stay on an operator's server that never takes it.
+    const standing = await db
+        .delete(mcpStanding)
+        .where(rowids("mcp_standing", standingApprovalsAllowed() ? sql `${mcpStanding.until} <= ${now.getTime()}` : sql `1 = 1`))
+        .returning({ k: mcpStanding.grantId });
+    // Auto-approve request locks past the daily cap's window and a day of retries.
+    const spends = await db
+        .delete(mcpStandingSpends)
+        .where(rowids("mcp_standing_spends", sql `${mcpStandingSpends.createdAt} < ${before(2 * DAY_MS).getTime()}`))
+        .returning({ k: mcpStandingSpends.spendId });
+    // A review-billing delegation 30 days past its `exp` (payments/review-billing.ts): it pays nothing
+    // more, and its count has long been shown — the bearer credential goes with the row.
+    const reviewBilling = await db
+        .delete(reviewBillingDelegations)
+        .where(rowids("review_billing_delegations", sql `${reviewBillingDelegations.expiresAt} < ${before(30 * DAY_MS).getTime()}`))
+        .returning({ k: reviewBillingDelegations.sourceId });
+    return {
+        uploads: marked.length,
+        idempotency: idempotency.length,
+        approvals: approvals.length,
+        standing: standing.length,
+        spends: spends.length,
+        reviewBilling: reviewBilling.length,
+    };
+}
+//# sourceMappingURL=retention.js.map

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

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