@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/matrix/client.js

@@ -0,0 +1,104 @@
+/**
+ * The Matrix wire — the ONLY module in this package that talks to a homeserver.
+ *
+ * No SDK, no crypto, no `/sync`: the oracle creates a room it owns, invites the collection owner,
+ * and posts structured UNENCRYPTED events (v1's D2 ruling carries over — a Worker can't do E2EE,
+ * so content stays ids/prompts only, never claim answers). That is the whole surface, so this is a
+ * ~100-line `fetch` wrapper over `fetchClient`'s timeout/traceparent policy plus a bearer token.
+ *
+ * Two things it owns that nothing above it should re-derive:
+ *  - the Matrix error taxonomy → `AppError`, with the `errcode` preserved in `details` so a caller
+ *    can branch on `M_ROOM_IN_USE` (create-or-reuse) or `M_FORBIDDEN` (already in the room);
+ *  - `retry_after_ms` on `429 M_LIMIT_EXCEEDED`. `fetchClient` retries 429 blindly on a guessed
+ *    backoff, so this client keeps `attempts: 1` and does the one informed retry itself.
+ *
+ * `authorization` is a full account credential. It is built here, never logged, and never placed
+ * in an error — every thrown AppError carries method + path + status + errcode only.
+ */
+import { AppError } from "../errors.js";
+import { fetchClient } from "../http/client.js";
+import { normalizeMatrixHomeServerUrl } from "../ixo/claim-bot.js";
+const RATE_LIMIT_CAP_MS = 10_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The Matrix `errcode` behind an AppError this client threw, or `null`. */
+export function matrixErrcode(err) {
+    if (!(err instanceof AppError))
+        return null;
+    const details = err.details;
+    return details?.errcode ?? null;
+}
+/** The homeserver's human-readable `error` text — the only way to spot "already in the room". */
+export function matrixErrorText(err) {
+    if (!(err instanceof AppError))
+        return "";
+    const details = err.details;
+    return details?.error ?? "";
+}
+function mapError(deps, req, status, body) {
+    // Redacted by construction: the token never enters a message, a detail, or a log field.
+    const where = `${req.method} ${req.path}`;
+    const details = { errcode: body.errcode ?? null, error: body.error ?? "", status };
+    const message = `Matrix ${where} failed (${status} ${body.errcode ?? "unknown"})`;
+    if (status === 401) {
+        // The lane goes dark until an operator rotates the secret — loud, and only here.
+        deps.logger.error("matrix.token-invalid", { path: req.path, soft_logout: !!body.soft_logout });
+        return new AppError(message, { code: "INTERNAL", expose: false, details });
+    }
+    if (status === 403)
+        return new AppError(message, { code: "FORBIDDEN", details });
+    if (status === 404)
+        return new AppError(message, { code: "NOT_FOUND", details });
+    if (status === 429)
+        return new AppError(message, { code: "RATE_LIMITED", details });
+    // 400 covers both `M_ROOM_IN_USE` (a routine create-or-reuse signal the caller catches) and our
+    // own bad payloads — CONFLICT/INTERNAL respectively; neither is ever retried by this client.
+    if (status === 400) {
+        return body.errcode === "M_ROOM_IN_USE"
+            ? new AppError(message, { code: "CONFLICT", details })
+            : new AppError(message, { code: "INTERNAL", expose: false, details });
+    }
+    return new AppError(message, { code: "UNAVAILABLE", expose: false, details });
+}
+/**
+ * One Client-Server API call. Throws `AppError` for every non-2xx; the caller decides what a given
+ * `errcode` means for its lane.
+ */
+export async function matrixRequest(deps, req) {
+    const token = deps.config.ORACLE_MATRIX_ACCESS_TOKEN;
+    if (!token)
+        throw AppError.internal("ORACLE_MATRIX_ACCESS_TOKEN is not configured");
+    const base = normalizeMatrixHomeServerUrl(deps.config.MATRIX_HOMESERVER_URL);
+    if (!base)
+        throw AppError.internal("MATRIX_HOMESERVER_URL is not configured");
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        let res;
+        try {
+            res = await fetchClient(`${base}${req.path}`, {
+                method: req.method,
+                trace: deps.trace,
+                // attempts:1 — the 429 retry below is informed by `retry_after_ms`, and a non-idempotent
+                // PUT/POST must not be re-sent on a guess.
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${token}`,
+                },
+                body: req.body === undefined ? undefined : JSON.stringify(req.body),
+            });
+        }
+        catch (err) {
+            // Timeout / network. `err` is a fetch error — it carries no headers, so nothing to redact.
+            throw AppError.unavailable(`Matrix ${req.method} ${req.path} unreachable`, err);
+        }
+        if (res.ok)
+            return (await res.json().catch(() => ({})));
+        const body = ((await res.json().catch(() => ({}))) ?? {});
+        if (res.status === 429 && attempt === 1) {
+            await sleep(Math.min(body.retry_after_ms ?? 1_000, RATE_LIMIT_CAP_MS));
+            continue;
+        }
+        throw mapError(deps, req, res.status, body);
+    }
+    // Unreachable: the loop either returns or throws.
+    throw AppError.unavailable(`Matrix ${req.method} ${req.path} exhausted its rate-limit retry`);
+}
+//# sourceMappingURL=client.js.map

package/dist/lib/matrix/client.js.map

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

package/dist/lib/matrix/deliver.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The Matrix side-effect lane — sends the in-chat review card when a decision needs a human, and
+ * edits it to "completed" when the fold lands. There is ONE room kind (the collection's review
+ * room: the owner and the reviewers the company granted — `syncCollectionReviewers`; no
+ * channel/assignee routing, no dispute rooms), so the room identity lives here beside the delivery
+ * instead of in its own file.
+ *
+ * Same three properties, for the same reasons as every other side-effect lane in this kit:
+ *  - **Idempotent.** Every function is `check marker → do → record marker`, over two overlapping
+ *    layers: the `matrix_deliveries.dedupeKey` row (durable) and a deterministic Matrix `txnId`
+ *    (Synapse-side, bounded window). Re-entering a lane after a workflow-step retry costs zero HTTP.
+ *  - **Fail-soft.** Matrix must never block or fail a claim's ingest or fold. Nothing here throws
+ *    for a Matrix-side failure: the outcome is recorded on the delivery row and returned.
+ *    `ORACLE_MATRIX_ACCESS_TOKEN` unset ⇒ every lane logs one line and returns `skipped` — what
+ *    local dev and every test run look like.
+ *  - **Self-contained.** Every function reads everything it needs from the DB, so a workflow step
+ *    passes only the claimId — exactly like `deliverChainEvaluation` (lib/ixo/chain-write.ts).
+ *
+ * The review room is keyed on the STABLE pair `(collectionId, ownerDid)` — never one room per
+ * claim, and never `rubricId` (a re-anchored rubric would otherwise mint a new room every time).
+ *
+ * `sendWithRejoin` ports v1's E3 recovery (eval-engine deliver.ts:496-521) uniformly to both
+ * `sendEvent` call sites: a `M_FORBIDDEN` posting into a room this oracle CREATED means membership
+ * itself broke after the fact (an operator removed the bot, a homeserver hiccup), never "we were
+ * never let in" — one `joinRoom`, one re-send; still failing records `oracle_not_in_room`, never
+ * the invite lane's `user_not_on_homeserver` label.
+ */
+import type { Database } from "../../db/client.js";
+import type { EngineClient } from "../engine/client.js";
+import { type Manifest } from "../engine/types.js";
+import { type Metrics } from "../metrics.js";
+import { type CreateRoomPayload } from "./api.js";
+import { type MatrixClientDeps } from "./client.js";
+import { type ReviewRequestContent } from "./events.js";
+export interface MatrixLedgerDeps extends MatrixClientDeps {
+    metrics: Metrics;
+    runDb: <T>(fn: (db: Database) => Promise<T>) => Promise<T>;
+}
+export interface MatrixDeps extends MatrixLedgerDeps {
+    cache: KVNamespace;
+    /**
+     * `env.EMAIL` (Cloudflare Email Service) — the review-request email twin's
+     * binding. Absent ⇒ that lane no-ops (lib/email/send.ts); `deliverReviewFold` never reads it.
+     */
+    email?: SendEmail;
+}
+export type MatrixOutcome = "sent" | "skipped" | "failed";
+export type MatrixIdentity = {
+    status: "ok";
+    userId: string;
+}
+/** No token — the whole lane is a documented no-op. */
+ | {
+    status: "unconfigured";
+}
+/** The token is not this oracle's own Matrix account. */
+ | {
+    status: "mismatch";
+    userId: string;
+    expected: string;
+} | {
+    status: "unreachable";
+    detail: string;
+};
+/**
+ * `whoami()` must answer `ORACLE_MATRIX_USER_ID` — nothing else proves the configured token
+ * belongs to OUR oracle, and the wrong token would post review cards (and own rooms) as somebody
+ * else's account. Cost: one `whoami` per hour, not per delivery, cached both in-isolate and in
+ * `CACHE_KV` (keyed on a token-hash prefix, so the token itself never enters a KV key and a
+ * rotated secret re-checks immediately). Only DETERMINISTIC answers are cached.
+ */
+export declare function matrixIdentity(deps: MatrixDeps): Promise<MatrixIdentity>;
+/**
+ * The gate every fail-soft lane opens with. `false` ⇒ the token belongs to another account:
+ * deliver nothing, log loudly, leave the caller alone. Every other state returns `true` — the
+ * lane's own `skipped`/`failed` recording takes it from there, because Matrix trouble must never
+ * become the caller's problem.
+ */
+export declare function matrixLaneReady(deps: MatrixDeps): Promise<boolean>;
+export declare function aliasLocalpart(prefix: string, key: string): Promise<string>;
+/** Synapse dedups repeated PUTs on `(access_token, txnId)` — a cheap first line, not the guarantee. */
+export declare function transactionId(dedupeKey: string): Promise<string>;
+/**
+ * After `sendWithRejoin` has ALREADY tried one join-and-retry, a remaining `M_FORBIDDEN` means the
+ * oracle itself is locked out of a room it owns — a distinct failure from `failureReason`'s
+ * `user_not_on_homeserver` (which is about the OWNER we invited, not us), so callers logging a
+ * send failure use this instead.
+ */
+export declare function sendFailureReason(err: unknown): string;
+/**
+ * E3 (v1 deliver.ts:496-521) — we are not in the room (removed after creation, or a homeserver
+ * hiccup on the very first send). One join, one re-send; a second failure of any kind propagates
+ * to the caller's own failure recording untouched.
+ */
+export declare function sendWithRejoin(deps: MatrixLedgerDeps, roomId: string, eventType: string, txnId: string, content: unknown): Promise<{
+    event_id: string;
+}>;
+/** Invites are best-effort: the room stands, and the next lane run retries. */
+export declare function inviteBestEffort(deps: MatrixLedgerDeps, roomId: string, userId: string, reason?: string): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+/**
+ * The create-or-reuse path every engine-owned room shares (this kit has exactly one kind):
+ *
+ *   sent marker ⇒ return roomId (durable reuse, zero HTTP)
+ *   else createRoom(alias, …) → 200 ⇒ record sent
+ *                             → M_ROOM_IN_USE ⇒ resolve the alias to the same room
+ *                             → anything else ⇒ record failed, return null (fail-soft)
+ */
+export declare function createOrReuseRoom(deps: MatrixLedgerDeps, input: {
+    dedupeKey: string;
+    alias: string;
+    collectionId: string;
+    payload: CreateRoomPayload;
+    /**
+     * Re-invited on the REUSE path only — the first create's invite may have failed. Absent for a
+     * room whose members are invited by their own ledger rows (the API lane's, api-lane/reviewers.ts).
+     */
+    invitee?: string;
+}): Promise<string | null>;
+/**
+ * The oracle-owned review room for a collection: created LAZILY at the first claim that needs
+ * review, reused for every later one. Keyed `(collectionId, ownerDid)` — never per claim, never
+ * per rubric (a re-anchored rubric must not orphan and re-mint the room).
+ */
+export declare function ensureReviewRoom(deps: MatrixDeps, collectionId: string, ownerDid: string): Promise<string | null>;
+/**
+ * The review room follows the collection's reviewer grants: every grant that stands now
+ * (`liveReviewerGrants` — unrevoked, in its window, its root still a controller of the entity) is
+ * invited, and whoever was invited and no longer stands is kicked — never the owner, whose seat is
+ * the room's own (`ensureReviewRoom`). One `crvi:<collectionId>:<mxid>` row per person — keyed by
+ * the MXID (`mxidFromDid`, the portal's own derivation), so a reviewer granted again after a revoke
+ * finds their row, never a second invite plus a kick from the old one; a row sent into another
+ * room (a re-register under a new owner made this one) is not an invite here. Who may ANSWER is
+ * the gate's (lib/review/reviewer-grant.ts), re-checked at every answer and fold; the room only
+ * tells. Best-effort: a failed invite is a row the next pass retries, and nothing here ever throws
+ * — Blocksync down skips the whole sync, so nobody is kicked on a blip.
+ */
+export declare function syncCollectionReviewers(deps: MatrixLedgerDeps, collection: {
+    collectionId: string;
+    ownerDid: string;
+}, roomId: string, now?: Date): Promise<void>;
+/**
+ * The collection's review room as it stands — the CURRENT owner's (`review_room:<id>:<ownerDid>`)
+ * — synced to its grants now (a revoke kicks at once), or nothing when no room was ever made.
+ */
+export declare function syncCollectionReviewRoom(deps: MatrixDeps, collectionId: string): Promise<void>;
+/**
+ * The hourly pass over the chain review rooms: kick whoever's grant expired since, or whose root
+ * is no longer a controller of the entity (a revoke kicked already), and retry a failed invite. `REVIEW_ROOMS_PER_PASS` a pass, least recently synced first
+ * — the room marker's `updatedAt` is the rotation's cursor, touched after each sync (as the API
+ * lane's `syncReviewRooms`).
+ */
+export declare function syncChainReviewRooms(deps: MatrixDeps, now?: Date): Promise<void>;
+/**
+ * `decision.pendingTasks` ⨯ the manifest's `review.taskDetails` — id/prompt/answer, nothing else.
+ * Falls back to the bare id as its own prompt (and a boolean answer) when the engine has not sent
+ * `taskDetails` yet, or a given pending task has no entry in it (engine T9 is additive) — except
+ * the engine's synthetic `unique:<ruleId>` / `checks:held`, which are always approve/reject
+ * (lib/review/tasks.ts).
+ */
+export declare function reviewTasks(pendingTaskIds: string[], review: Manifest["review"]): ReviewRequestContent["tasks"];
+/**
+ * The `notify-review` workflow step's whole body. Self-contained: it reads everything from the
+ * DB, so the workflow passes only the claimId.
+ *
+ * A clean no-op (one log line) when: `ORACLE_MATRIX_ACCESS_TOKEN` is unset; no decision is
+ * recorded for the claim; the decision is not `pending_review`; it has no pending tasks; the
+ * collection is not watched or has no protocol; the engine's rubric manifest is unusable; or a
+ * `sent` marker already exists.
+ *
+ * The `review_request` (Matrix) and `notice_review_email` markers are independent (header), which
+ * matters most on the ONE path where they can end up out of step: Matrix sends fine, the email
+ * throws in the SAME invocation (an `allSettled` rejection below) — and the workflow step that
+ * calls this memoizes its return forever once `review_request` is `sent`, so nothing would ever
+ * call this function's full body again. The `existing?.status === "sent"` branch below is that
+ * function's ONLY remaining production entry point for such a claim, so it doubles as the email's
+ * retry point: absent-or-failed AND a contact email on file → attempt just the email (no Matrix
+ * re-send, no room work) before reporting the now-familiar `skipped`.
+ */
+export declare function deliverReviewRequest(deps: MatrixDeps, engine: Pick<EngineClient, "getManifest">, claimId: string): Promise<MatrixOutcome>;
+/**
+ * The `notify-folded` workflow step's whole body — an `m.replace` edit of the SAME event the
+ * review-request sent, flipping `status` to `completed` and stamping `verdict`/`foldedAt`.
+ * Self-contained like `deliverReviewRequest`: reads the folded decision, the answered review's
+ * task ids (`Object.keys(claimReviews.answers)` IS the pre-fold `pendingTasks` set — the route
+ * validates it covers exactly that set, so it survives the fold untouched) and the delivered
+ * request's room/event id off `matrix_deliveries`.
+ *
+ * A clean no-op when: the token is unset; no decision or no completed fold is recorded; no
+ * `review_request` was ever sent for this claim (nothing to edit); the collection/manifest can't
+ * be resolved; or a `review_fold` marker already exists.
+ */
+export declare function deliverReviewFold(deps: MatrixDeps, engine: Pick<EngineClient, "getManifest">, claimId: string): Promise<MatrixOutcome>;
+/**
+ * A collection notice as a plain `m.room.message` in the collection's review room — the PRIMARY
+ * channel; email is the twin, `workflows/steps.ts`). The room is the
+ * SAME `ensureReviewRoom` the review card uses, so an owner has one room per collection, not one
+ * per lane. `body`/`formattedBody` are the two renders of the ONE `Notice` (lib/email/template.ts
+ * `chatBody`/`noticeHtml`).
+ *
+ * Records NOTHING on `matrix_deliveries`: the caller owns the told-once marker (`notice_paused` /
+ * `notice_resumed`, the alternating pair in steps.ts) and writes this outcome onto it beside the
+ * email's. Never throws — token unset is one `skipped` line, everything else `failed` with the
+ * reason, exactly like the review lanes.
+ */
+export declare function sendCollectionNoticeMessage(deps: MatrixDeps, input: {
+    kind: "notice_paused" | "notice_resumed";
+    collectionId: string;
+    ownerDid: string;
+    dedupeKey: string;
+    body: string;
+    formattedBody: string;
+}): Promise<{
+    status: "sent";
+    roomId: string;
+    eventId: string;
+} | {
+    status: "skipped" | "failed";
+    roomId: string | null;
+    reason: string;
+}>;
+//# sourceMappingURL=deliver.d.ts.map

package/dist/lib/matrix/deliver.d.ts.map

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