@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/api-lane/media-type.js

@@ -0,0 +1,73 @@
+/**
+ * A URL attachment's `mediaType`, when the caller left it out — an AI app over MCP, or a REST
+ * caller, sends a photo as `{ question, url }` and nothing else, and the evaluate step's
+ * octet-stream default then fails a rubric's `mediaTypeIn ["image/*"]` on a real JPEG.
+ *
+ * Detected ONCE, at accept, and stored on the claim's attachment: the evaluate step, its retries
+ * and the review fold all read the same frozen value (the FactSet must be deterministic — a HEAD at
+ * evaluate time could answer differently on a retry). The caller's own `mediaType` always wins.
+ * Order: the URL path's extension, else one guarded `HEAD`, else nothing (the octet-stream default
+ * stands). Detection never fails the submit: the price is already reserved when this runs.
+ */
+import { assertPublicHttpUrl, fetchGuarded } from "../http/client.js";
+/** Short on purpose: the types a claim form's file question plausibly accepts. */
+const BY_EXTENSION = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    webp: "image/webp",
+    gif: "image/gif",
+    heic: "image/heic",
+    heif: "image/heif",
+    avif: "image/avif",
+    pdf: "application/pdf",
+    mp4: "video/mp4",
+    mov: "video/quicktime",
+    webm: "video/webm",
+};
+/** A submit holds its connection: one slow host must not stall it. */
+const HEAD_TIMEOUT_MS = 3_000;
+/** A 100-claim batch names up to thousands of URLs; only extension misses HEAD, and this many at once. */
+const HEADS_AT_ONCE = 6;
+const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
+function mediaTypeFromExtension(url) {
+    const path = URL.parse(url)?.pathname ?? "";
+    const ext = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase();
+    return ext ? BY_EXTENSION[ext] : undefined;
+}
+/** One HEAD through the SSRF guard (every redirect hop re-checked). A 403/405 is left unknown —
+ *  no GET fallback: a body read to sniff a type is not worth a slower submit. */
+async function headMediaType(url) {
+    try {
+        assertPublicHttpUrl(url);
+        const res = await fetchGuarded(url, { method: "HEAD", timeoutMs: HEAD_TIMEOUT_MS });
+        await res.body?.cancel().catch(() => { });
+        if (!res.ok)
+            return undefined;
+        const type = res.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+        return type && MEDIA_TYPE.test(type) ? type : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Each claim's attachments with a detected `mediaType` filled in where the caller sent none. */
+export async function withMediaTypes(claims) {
+    const heads = new Map();
+    const pending = [
+        ...new Set(claims.flatMap((atts) => atts.flatMap((a) => "url" in a && !a.mediaType && !mediaTypeFromExtension(a.url) ? [a.url] : []))),
+    ];
+    const worker = async () => {
+        for (let url = pending.pop(); url !== undefined; url = pending.pop()) {
+            heads.set(url, await headMediaType(url));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(HEADS_AT_ONCE, pending.length) }, worker));
+    return claims.map((atts) => atts.map((a) => {
+        if (!("url" in a) || a.mediaType)
+            return a;
+        const mediaType = mediaTypeFromExtension(a.url) ?? heads.get(a.url);
+        return mediaType ? { ...a, mediaType } : a;
+    }));
+}
+//# sourceMappingURL=media-type.js.map

package/dist/lib/api-lane/media-type.js.map

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

package/dist/lib/api-lane/member-emails.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The three member emails of the invite flow (Go Prod §3.4 steps 2–3; copy in the member-emails
+ * spec §2–§4): the invitation to the address the owner typed, "accepted" to the inviter, "access
+ * granted" to the member — and the source contact's `balance.low` email (Go Prod §12.4), which
+ * rides the same claimed-row send.
+ *
+ * Addresses: the oracle emails ONLY addresses it was given — a member row's `email` (the one typed
+ * on the invite) or, for the source's owner without one, `api_sources.contactEmail`. It never
+ * learns an account's verified email, so an account is named by its `did:ixo`. No address ⇒ no
+ * email, one log line, never an error.
+ *
+ * Idempotent and fail-soft like reviewers.ts: each email is a `matrix_deliveries` row keyed by what
+ * it is about — `inv:<memberId>:<tokenHash16>` (a re-invite is a new token, so a new row),
+ * `acc:<memberId>`, `grant:<memberId>:<delegationCid>` — CLAIMED before the send (inserted
+ * `sending`, or a `failed` one taken over), so a racing or retried send path never sends twice and
+ * a `sent` row is never moved off it. A `failed` row is re-tried only when the same path runs again
+ * (nothing re-drives it); a crash mid-send leaves `sending` — at most once. No `EMAIL` binding,
+ * sender or `CONSOLE_URL` (every link) ⇒ skipped, no row. Nothing here throws: a route's answer
+ * never depends on an email.
+ */
+import type { Config } from "../../config.js";
+import type { Database } from "../../db/client.js";
+import { type ApiMember, type ApiSource } from "../../db/schema.js";
+import type { BlocksyncDeps } from "../ixo/blocksync/types.js";
+import type { Logger } from "../logger.js";
+import type { Metrics } from "../metrics.js";
+export interface MemberEmailDeps {
+    db: Database;
+    /** Blocksync, for a linked source's roots (its entity's controllers). */
+    chain: BlocksyncDeps;
+    config: Pick<Config, "CONSOLE_URL" | "EMAIL_FROM_ADDRESS" | "EMAIL_FROM_NAME" | "ORACLE_HOSTNAME">;
+    logger: Logger;
+    metrics: Metrics;
+    /** `env.EMAIL`; absent ⇒ no emails (one log line). */
+    email?: SendEmail;
+}
+/** What the claimed-row send needs: no chain read. */
+export type EmailLaneDeps = Omit<MemberEmailDeps, "chain">;
+/** §2, to the typed address. `token` is the fresh plaintext — it exists only in this request. */
+export declare function emailInvite(deps: MemberEmailDeps, source: ApiSource, member: ApiMember, token: string): Promise<void>;
+/**
+ * §3, to the inviter alone — while they can still manage members (a live grant covering
+ * `source/*`, a current controller always): a co-owner revoked, or a controller removed on chain,
+ * since they invited must not hear who joined. No recorded inviter, or one who no longer manages ⇒
+ * no email: the paying `ownerDid` is not the organisation (D10) and is never a fallback.
+ */
+export declare function emailInviteAccepted(deps: MemberEmailDeps, source: ApiSource, member: ApiMember): Promise<void>;
+/** §4, to the member, once per stored grant. `grantorDid` signed it. */
+export declare function emailAccessGranted(deps: MemberEmailDeps, source: ApiSource, member: ApiMember, grantorDid: string): Promise<void>;
+/**
+ * `balance.low` (Go Prod §12.4) to the source's `contactEmail`: the watch calls it on the crossing
+ * and on every later check while the balance stays under the floor. The UTC day in the key makes
+ * that one email a day — a `sent` row is never re-sent, a `failed` one is retried on the next check
+ * — and a balance that bobs around its floor still gets one. Never throws (`deliver`).
+ */
+export declare function emailBalanceLow(deps: EmailLaneDeps, source: Pick<ApiSource, "sourceId" | "name" | "contactEmail">, low: {
+    balanceCents: number;
+    floorCents: number;
+    at: Date;
+}): Promise<void>;
+/**
+ * A review-billing delegation running out (owner, 2026-10-14): the payer is emailed 30 and 7 days
+ * before its `exp`, once each — the key is the delegation's CID and the stage, so a new delegation
+ * starts its own pair and a 100-year one never gets one. To the payer's member address, else the
+ * source's contact. Never throws (`deliver`).
+ */
+export declare function emailReviewBillingExpiring(deps: EmailLaneDeps, source: Pick<ApiSource, "sourceId" | "name" | "contactEmail">, delegation: {
+    payerDid: string;
+    delegationCid: string;
+    expiresAt: Date;
+}, daysLeft: 30 | 7): Promise<void>;
+/**
+ * A review-billing delegation's cap almost used (owner, 2026-10-14): the payer is emailed when
+ * `spent` crosses 80% of `maxAmount`, and again at 95%, once each — keyed by the CID and the stage,
+ * so a new delegation (a raised cap) starts its own pair. Same address rule as the expiry
+ * reminder. Never throws (`deliver`); never carries the delegation.
+ */
+export declare function emailReviewBillingCapLow(deps: EmailLaneDeps, source: Pick<ApiSource, "sourceId" | "name" | "contactEmail">, delegation: {
+    payerDid: string;
+    delegationCid: string;
+    maxAmount: string;
+}, percent: 80 | 95, remainingUpay: bigint, priceUpay: bigint | null): Promise<void>;
+//# sourceMappingURL=member-emails.d.ts.map

package/dist/lib/api-lane/member-emails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-emails.d.ts","sourceRoot":"","sources":["../../../src/lib/api-lane/member-emails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAgC,MAAM,iBAAiB,CAAC;AAa/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,yEAAyE;IACzE,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,IAAI,CACV,MAAM,EACN,aAAa,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,iBAAiB,CAC7E,CAAC;IACF,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAUD,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAE3D,iGAAiG;AACjG,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wEAAwE;AACxE,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAcf;AAQD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,GAAG,cAAc,CAAC,EAC7D,GAAG,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAC1D,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,GAAG,cAAc,CAAC,EAC7D,UAAU,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,EACxE,QAAQ,EAAE,EAAE,GAAG,CAAC,GACf,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,GAAG,cAAc,CAAC,EAC7D,UAAU,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1E,OAAO,EAAE,EAAE,GAAG,EAAE,EAChB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/lib/api-lane/member-emails.js

@@ -0,0 +1,213 @@
+/**
+ * The three member emails of the invite flow (Go Prod §3.4 steps 2–3; copy in the member-emails
+ * spec §2–§4): the invitation to the address the owner typed, "accepted" to the inviter, "access
+ * granted" to the member — and the source contact's `balance.low` email (Go Prod §12.4), which
+ * rides the same claimed-row send.
+ *
+ * Addresses: the oracle emails ONLY addresses it was given — a member row's `email` (the one typed
+ * on the invite) or, for the source's owner without one, `api_sources.contactEmail`. It never
+ * learns an account's verified email, so an account is named by its `did:ixo`. No address ⇒ no
+ * email, one log line, never an error.
+ *
+ * Idempotent and fail-soft like reviewers.ts: each email is a `matrix_deliveries` row keyed by what
+ * it is about — `inv:<memberId>:<tokenHash16>` (a re-invite is a new token, so a new row),
+ * `acc:<memberId>`, `grant:<memberId>:<delegationCid>` — CLAIMED before the send (inserted
+ * `sending`, or a `failed` one taken over), so a racing or retried send path never sends twice and
+ * a `sent` row is never moved off it. A `failed` row is re-tried only when the same path runs again
+ * (nothing re-drives it); a crash mid-send leaves `sending` — at most once. No `EMAIL` binding,
+ * sender or `CONSOLE_URL` (every link) ⇒ skipped, no row. Nothing here throws: a route's answer
+ * never depends on an email.
+ */
+import { and, eq, ne, sql } from "drizzle-orm";
+import { covers } from "../../contracts/capabilities.js";
+import { apiMembers, matrixDeliveries } from "../../db/schema.js";
+import { getOracle } from "../../oracle.js";
+import { sendEmail } from "../email/send.js";
+import { oracleApiUrl, renderAccessGrantedEmail, renderBalanceLowEmail, renderInviteAcceptedEmail, renderInviteEmail, renderReviewBillingCapEmail, renderReviewBillingExpiringEmail, } from "../email/template.js";
+import { liveGrant } from "./members.js";
+/** §2, to the typed address. `token` is the fresh plaintext — it exists only in this request. */
+export async function emailInvite(deps, source, member, token) {
+    await deliver(deps, "member_invite", member, {
+        dedupeKey: `inv:${member.memberId}:${(member.inviteTokenHash ?? "").slice(0, 16)}`,
+        to: async () => member.email,
+        render: async (links) => renderInviteEmail({
+            ...base(links, source),
+            role: member.role,
+            inviter: await nameOf(deps.db, source, member.invitedBy ?? source.ownerDid),
+            inviteeEmail: member.email ?? "",
+            inviteToken: token,
+            expiresAt: member.inviteExpiresAt ?? new Date(),
+        }),
+    });
+}
+/**
+ * §3, to the inviter alone — while they can still manage members (a live grant covering
+ * `source/*`, a current controller always): a co-owner revoked, or a controller removed on chain,
+ * since they invited must not hear who joined. No recorded inviter, or one who no longer manages ⇒
+ * no email: the paying `ownerDid` is not the organisation (D10) and is never a fallback.
+ */
+export async function emailInviteAccepted(deps, source, member) {
+    const inviter = member.invitedBy;
+    await deliver(deps, "member_accepted", member, {
+        dedupeKey: `acc:${member.memberId}`,
+        to: async () => {
+            if (!inviter)
+                return null;
+            const grant = await liveGrant(deps, source.sourceId, inviter);
+            const manages = grant !== null && covers(grant.capabilities, "source/*");
+            return manages ? addressOf(deps.db, source, inviter) : null;
+        },
+        render: async (links) => renderInviteAcceptedEmail({
+            ...base(links, source),
+            role: member.role,
+            // No AuthHub name here: the address the invite went to is how the inviter knows them.
+            member: member.email ?? member.did ?? member.memberId,
+            accountDid: member.did ?? "",
+            invitedEmail: member.email ?? "",
+            memberId: member.memberId,
+        }),
+    });
+}
+/** §4, to the member, once per stored grant. `grantorDid` signed it. */
+export async function emailAccessGranted(deps, source, member, grantorDid) {
+    await deliver(deps, "member_granted", member, {
+        dedupeKey: `grant:${member.memberId}:${member.delegationCid}`,
+        to: async () => member.email,
+        render: async (links) => renderAccessGrantedEmail({
+            ...base(links, source),
+            role: member.role,
+            // No protocol catalogue with names yet (S8): the DIDs stand in, as in reviewers.ts.
+            protocols: member.nbProtocols ?? undefined,
+            owner: await nameOf(deps.db, source, grantorDid),
+            accessUntil: member.expiresAt ?? undefined,
+        }),
+    });
+}
+/**
+ * `balance.low` (Go Prod §12.4) to the source's `contactEmail`: the watch calls it on the crossing
+ * and on every later check while the balance stays under the floor. The UTC day in the key makes
+ * that one email a day — a `sent` row is never re-sent, a `failed` one is retried on the next check
+ * — and a balance that bobs around its floor still gets one. Never throws (`deliver`).
+ */
+export async function emailBalanceLow(deps, source, low) {
+    await deliver(deps, "notice_balance_low", source, {
+        dedupeKey: `notice_balance_low:${source.sourceId}:${low.at.toISOString().slice(0, 10)}`,
+        to: async () => source.contactEmail,
+        render: async (links) => renderBalanceLowEmail({
+            ...base(links, source),
+            balanceCents: low.balanceCents,
+            floorCents: low.floorCents,
+        }),
+    });
+}
+/**
+ * A review-billing delegation running out (owner, 2026-10-14): the payer is emailed 30 and 7 days
+ * before its `exp`, once each — the key is the delegation's CID and the stage, so a new delegation
+ * starts its own pair and a 100-year one never gets one. To the payer's member address, else the
+ * source's contact. Never throws (`deliver`).
+ */
+export async function emailReviewBillingExpiring(deps, source, delegation, daysLeft) {
+    await deliver(deps, "notice_review_billing_expiring", source, {
+        dedupeKey: `rb_expiring:${delegation.delegationCid}:${daysLeft}`,
+        to: () => payerAddress(deps.db, source, delegation.payerDid),
+        render: async (links) => renderReviewBillingExpiringEmail({
+            ...base(links, source),
+            expiresAt: delegation.expiresAt,
+            daysLeft,
+        }),
+    });
+}
+/**
+ * A review-billing delegation's cap almost used (owner, 2026-10-14): the payer is emailed when
+ * `spent` crosses 80% of `maxAmount`, and again at 95%, once each — keyed by the CID and the stage,
+ * so a new delegation (a raised cap) starts its own pair. Same address rule as the expiry
+ * reminder. Never throws (`deliver`); never carries the delegation.
+ */
+export async function emailReviewBillingCapLow(deps, source, delegation, percent, remainingUpay, priceUpay) {
+    await deliver(deps, "notice_review_billing_cap", source, {
+        dedupeKey: `rb_cap:${delegation.delegationCid}:${percent}`,
+        to: () => payerAddress(deps.db, source, delegation.payerDid),
+        render: async (links) => renderReviewBillingCapEmail({
+            ...base(links, source),
+            percent,
+            capUpay: delegation.maxAmount,
+            remainingUpay: remainingUpay.toString(),
+            reviewsLeft: priceUpay && priceUpay > 0n ? Number(remainingUpay / priceUpay) : null,
+        }),
+    });
+}
+/** A delegation's payer: their member address on the source, else the source's contact. */
+async function payerAddress(db, source, payerDid) {
+    const member = await db.query.apiMembers.findFirst({
+        columns: { email: true },
+        where: and(eq(apiMembers.sourceId, source.sourceId), eq(apiMembers.did, payerDid)),
+    });
+    return member?.email ?? source.contactEmail ?? null;
+}
+async function deliver(deps, kind, 
+/** A member row, or the source itself for a source-wide notice. */
+about, { dedupeKey, to: addressFor, render }) {
+    const { db, logger, config } = deps;
+    const ids = about.memberId ? { memberId: about.memberId } : { sourceId: about.sourceId };
+    try {
+        if (!deps.email || !config.EMAIL_FROM_ADDRESS || !config.CONSOLE_URL) {
+            logger.info(`email.${kind}.skipped`, {
+                ...ids,
+                reason: "EMAIL, EMAIL_FROM_ADDRESS or CONSOLE_URL not configured",
+            });
+            deps.metrics.count(`email.${kind}`, 1, { status: "skipped" });
+            return;
+        }
+        const to = await addressFor();
+        if (!to) {
+            logger.info(`email.${kind}.skipped`, { ...ids, reason: "no address" });
+            deps.metrics.count(`email.${kind}`, 1, { status: "skipped" });
+            return;
+        }
+        const mail = await render({ consoleUrl: config.CONSOLE_URL, oracleUrl: oracleApiUrl(config) });
+        // Claim the row, then send: a new row, or a `failed` one taken over — never a `sent` one.
+        const [claimed] = await db
+            .insert(matrixDeliveries)
+            .values({ dedupeKey, kind, sourceId: about.sourceId, status: "sending", attempts: 1 })
+            .onConflictDoUpdate({
+            target: matrixDeliveries.dedupeKey,
+            set: {
+                status: "sending",
+                attempts: sql `${matrixDeliveries.attempts} + 1`,
+                lastError: null,
+            },
+            setWhere: eq(matrixDeliveries.status, "failed"),
+        })
+            .returning({ dedupeKey: matrixDeliveries.dedupeKey });
+        if (!claimed)
+            return;
+        const outcome = await sendEmail(deps, { to, kind, ...mail });
+        await db
+            .update(matrixDeliveries)
+            .set({ status: outcome, lastError: outcome === "failed" ? "email send failed" : null })
+            .where(and(eq(matrixDeliveries.dedupeKey, dedupeKey), ne(matrixDeliveries.status, "sent")));
+    }
+    catch (err) {
+        logger.warn(`email.${kind}.failed`, { ...ids, detail: String(err) });
+    }
+}
+function base(links, source) {
+    return {
+        brand: getOracle().config.name,
+        ...links,
+        source: { id: source.sourceId, name: source.name },
+    };
+}
+/** A person's address on this source: their member row's email, else the owner's contact. */
+async function addressOf(db, source, did) {
+    const row = await db.query.apiMembers.findFirst({
+        columns: { email: true },
+        where: and(eq(apiMembers.sourceId, source.sourceId), eq(apiMembers.did, did)),
+    });
+    return row?.email ?? (did === source.ownerDid ? (source.contactEmail ?? null) : null);
+}
+/** How the copy names a person: their address when we hold one, else their DID. */
+async function nameOf(db, source, did) {
+    return (await addressOf(db, source, did)) ?? did;
+}
+//# sourceMappingURL=member-emails.js.map

package/dist/lib/api-lane/member-emails.js.map

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

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

@@ -0,0 +1,42 @@
+/**
+ * What a DID may do on a source RIGHT NOW (go-prod spec §3.4) — the one server-side reading of a
+ * member's grant, shared by every gate that keys on a stored member rather than a presented UCAN:
+ * the review answer (a reviewer key → its member), the payer binding (a payment delegation's root →
+ * its member), and the console's revocation check.
+ *
+ * The roots are identified by DID, never by a role label (`sourceRoots`: the current controllers of
+ * the source's organisation entity — D1, D10): a co-owner is a grant of `source/*` like any other
+ * and is revoked like any other. Everyone else needs an accepted
+ * member row with a stored grant, not revoked (stamped on the row, or listed for the source — the
+ * list is what makes a revoke effective at once), not expired. The row's copy of what the grant
+ * says was checked when the grant was stored, so no CAR is parsed here.
+ */
+import { type Capability } from "../../contracts/capabilities.js";
+import type { Database } from "../../db/client.js";
+import { type ApiMember } from "../../db/schema.js";
+import type { BlocksyncDeps } from "../ixo/blocksync/types.js";
+export interface LiveGrant {
+    capabilities: readonly Capability[];
+    /** `nb.protocols`: the protocols its `claims/*` are narrowed to; null = all. */
+    protocols: readonly string[] | null;
+}
+export declare function liveGrant(deps: {
+    db: Database;
+    chain: BlocksyncDeps;
+}, sourceId: string, did: string, now?: Date): Promise<LiveGrant | null>;
+/**
+ * `liveGrant` for every accepted member of a source at once — ONE query (members ⨝ the source's
+ * owner ⟕ the revocation list), for the crons that walk a whole source and must stay inside D1's
+ * per-invocation query budget. Same verdict per member as `liveGrant`, by the same `grantOf` —
+ * except that it reads no chain: a controller counts here only through a member grant of their own
+ * (the crons notify members, and Blocksync per source per tick is not worth it).
+ */
+export declare function liveMembers(db: Database, sourceId: string, now?: Date): Promise<{
+    member: ApiMember & {
+        did: string;
+    };
+    grant: LiveGrant;
+}[]>;
+/** Does the grant reach `protocolDid`? `nb.protocols` narrows only the `claims/*` capabilities. */
+export declare function reachesProtocol(grant: LiveGrant, protocolDid: string): boolean;
+//# sourceMappingURL=members.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../../../src/lib/api-lane/members.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,8BAA8B,CAAC;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,SAAS,EAA0C,MAAM,iBAAiB,CAAC;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG5D,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,gFAAgF;IAChF,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACrC;AAID,wBAAsB,SAAS,CAC7B,IAAI,EAAE;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,EAC5C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAuB3B;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,SAAS,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,EAAE,CAAC,CAwBtE;AASD,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAE9E"}

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

@@ -0,0 +1,75 @@
+/**
+ * What a DID may do on a source RIGHT NOW (go-prod spec §3.4) — the one server-side reading of a
+ * member's grant, shared by every gate that keys on a stored member rather than a presented UCAN:
+ * the review answer (a reviewer key → its member), the payer binding (a payment delegation's root →
+ * its member), and the console's revocation check.
+ *
+ * The roots are identified by DID, never by a role label (`sourceRoots`: the current controllers of
+ * the source's organisation entity — D1, D10): a co-owner is a grant of `source/*` like any other
+ * and is revoked like any other. Everyone else needs an accepted
+ * member row with a stored grant, not revoked (stamped on the row, or listed for the source — the
+ * list is what makes a revoke effective at once), not expired. The row's copy of what the grant
+ * says was checked when the grant was stored, so no CAR is parsed here.
+ */
+import { and, eq, isNotNull } from "drizzle-orm";
+import { ROLE_CAPABILITIES } from "../../contracts/capabilities.js";
+import { apiMembers, apiRevocations, apiSources } from "../../db/schema.js";
+import { sourceRoots } from "./company.js";
+const ROOT = { capabilities: ["source/*"], protocols: null };
+export async function liveGrant(deps, sourceId, did, now = new Date()) {
+    const { db } = deps;
+    const source = await db.query.apiSources.findFirst({
+        columns: { companyEntityDid: true },
+        where: eq(apiSources.sourceId, sourceId),
+    });
+    if (!source)
+        return null;
+    if ((await sourceRoots(deps.chain, source)).includes(did))
+        return ROOT;
+    const member = await db.query.apiMembers.findFirst({
+        where: and(eq(apiMembers.sourceId, sourceId), eq(apiMembers.did, did), isNotNull(apiMembers.acceptedAt)),
+    });
+    if (!member?.delegationCid || member.revokedAt)
+        return null;
+    if (member.expiresAt && member.expiresAt.getTime() <= now.getTime())
+        return null;
+    const revoked = await db.query.apiRevocations.findFirst({
+        columns: { cid: true },
+        where: and(eq(apiRevocations.sourceId, sourceId), eq(apiRevocations.cid, member.delegationCid)),
+    });
+    return grantOf(member, Boolean(revoked), now);
+}
+/**
+ * `liveGrant` for every accepted member of a source at once — ONE query (members ⨝ the source's
+ * owner ⟕ the revocation list), for the crons that walk a whole source and must stay inside D1's
+ * per-invocation query budget. Same verdict per member as `liveGrant`, by the same `grantOf` —
+ * except that it reads no chain: a controller counts here only through a member grant of their own
+ * (the crons notify members, and Blocksync per source per tick is not worth it).
+ */
+export async function liveMembers(db, sourceId, now = new Date()) {
+    const rows = await db
+        .select({ member: apiMembers, revoked: apiRevocations.cid })
+        .from(apiMembers)
+        .leftJoin(apiRevocations, and(eq(apiRevocations.sourceId, apiMembers.sourceId), eq(apiRevocations.cid, apiMembers.delegationCid)))
+        .where(and(eq(apiMembers.sourceId, sourceId), isNotNull(apiMembers.acceptedAt), isNotNull(apiMembers.did)));
+    const out = [];
+    for (const { member, revoked } of rows) {
+        const grant = member.did ? grantOf(member, revoked !== null, now) : null;
+        if (grant && member.did)
+            out.push({ member: { ...member, did: member.did }, grant });
+    }
+    return out;
+}
+/** The one reading of an accepted member row (its CID's revocation already looked up). */
+function grantOf(member, revoked, now) {
+    if (!member.delegationCid || member.revokedAt || revoked)
+        return null;
+    if (member.expiresAt && member.expiresAt.getTime() <= now.getTime())
+        return null;
+    return { capabilities: ROLE_CAPABILITIES[member.role], protocols: member.nbProtocols ?? null };
+}
+/** Does the grant reach `protocolDid`? `nb.protocols` narrows only the `claims/*` capabilities. */
+export function reachesProtocol(grant, protocolDid) {
+    return grant.protocols === null || grant.protocols.includes(protocolDid);
+}
+//# sourceMappingURL=members.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"members.js","sourceRoot":"","sources":["../../../src/lib/api-lane/members.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAmB,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,EAAkB,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEzF,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAQxC,MAAM,IAAI,GAAc,EAAE,YAAY,EAAE,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAExE,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAA4C,EAC5C,QAAgB,EAChB,GAAW,EACX,GAAG,GAAS,IAAI,IAAI,EAAE;IAEtB,MAAM,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC;IACpB,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;QACjD,OAAO,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE;QACnC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC;KACzC,CAAC,CAAC;IACH,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvE,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;QACjD,KAAK,EAAE,GAAG,CACR,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACjC,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EACvB,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,CACjC;KACF,CAAC,CAAC;IACH,IAAI,CAAC,MAAM,EAAE,aAAa,IAAI,MAAM,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5D,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,IAAI,CAAC;IACjF,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC;QACtD,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE;QACtB,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;KAChG,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,EAAY,EACZ,QAAgB,EAChB,GAAG,GAAS,IAAI,IAAI,EAAE;IAEtB,MAAM,IAAI,GAAG,MAAM,EAAE;SAClB,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,CAAC,GAAG,EAAE,CAAC;SAC3D,IAAI,CAAC,UAAU,CAAC;SAChB,QAAQ,CACP,cAAc,EACd,GAAG,CACD,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,EAChD,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,UAAU,CAAC,aAAa,CAAC,CACjD,CACF;SACA,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACjC,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,EAChC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,CAC1B,CACF,CAAC;IACJ,MAAM,GAAG,GAAgE,EAAE,CAAC;IAC5E,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACzE,IAAI,KAAK,IAAI,MAAM,CAAC,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,0FAA0F;AAC1F,SAAS,OAAO,CAAC,MAAiB,EAAE,OAAgB,EAAE,GAAS;IAC7D,IAAI,CAAC,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,SAAS,IAAI,OAAO;QAAE,OAAO,IAAI,CAAC;IACtE,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,IAAI,CAAC;IACjF,OAAO,EAAE,YAAY,EAAE,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;AACjG,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,eAAe,CAAC,KAAgB,EAAE,WAAmB;IACnE,OAAO,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC3E,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * 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 type { Database } from "../../db/client.js";
+import type { PullDeps } from "../ixo/index.js";
+import { type TimelineEvent } from "./timeline.js";
+export declare function notifyApiClaim(db: Database, deps: PullDeps, claimId: string): Promise<void>;
+/**
+ * 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 declare function announceExpiredReviews(db: Database, now?: Date): Promise<number>;
+/**
+ * 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 declare function announce(db: Database, events: TimelineEvent[]): Promise<string[]>;
+/**
+ * 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 declare function factCost(facts: {
+    ext: Record<string, unknown>;
+    ai: Record<string, unknown>;
+}): {
+    durationsMs: Record<string, number>;
+    costMicroUsd: number;
+} | Record<string, never>;
+//# sourceMappingURL=notify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../../src/lib/api-lane/notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAUhD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAKvC,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAc9D,wBAAsB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYjG;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,QAAQ,EACZ,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA2BvF;AAmHD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE;IAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7B,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAqBxF"}