humanish 0.20.4 → 0.21.0

package/dist/comms-email-catch.d.ts

@@ -0,0 +1,53 @@
+import { type ServerResponse } from "node:http";
+import type { CommsChannel } from "./comms-types.js";
+/** One send, normalized across providers. `body` is html-preferred, else text. */
+export interface NormalizedSend {
+    from: string;
+    to: string[];
+    subject?: string;
+    body: string;
+}
+/**
+ * A provider wire-shape adapter. Vendor-neutral seam: the server owns the HTTP + routing + bus
+ * delivery; a profile only knows how ONE provider (or a custom app) shapes its send request.
+ */
+export interface EmailSendProfile {
+    /** Descriptive name (e.g. "generic", "sendgrid"). Not a dependency — just a label. */
+    name: string;
+    /** Request paths (method POST) this profile accepts a send on. */
+    sendPaths: string[];
+    /** Parse a POST body (already JSON-parsed) into zero+ normalized sends (a batch yields many). */
+    parse(path: string, body: unknown): NormalizedSend[];
+    /** Optional provider-faithful success response. Default: 200 `{ id }` (single) / `{ data:[{id}] }`. */
+    respond?: (res: ServerResponse, ids: string[], batch: boolean) => void;
+}
+export interface EmailCatchServer {
+    /** Point the app's email-API base URL here (loopback only). */
+    readonly url: string;
+    readonly port: number;
+    /** Every normalized send accepted this run (runtime-only; for inspection/tests). */
+    readonly received: NormalizedSend[];
+    close(): Promise<void>;
+}
+export interface EmailCatchOptions {
+    /** Bind host. Default 127.0.0.1 (loopback ONLY). */
+    host?: string;
+    /** Port. Default 0 (ephemeral). */
+    port?: number;
+    /** Wire-shape profiles, tried in order by path. Default [genericEmailProfile, sendgridEmailProfile]. */
+    profiles?: EmailSendProfile[];
+    /** Deterministic id for responses (tests). Default a zero-padded counter. */
+    idFor?: (n: number) => string;
+}
+/** The flat-JSON shape: `{ from, to, subject, html, text }`. Matches Resend (POST /emails) AND a
+ *  custom app that sends the common shape AND Postmark's TitleCase keys (From/To/HtmlBody/…). */
+export declare const genericEmailProfile: EmailSendProfile;
+/** SendGrid's nested shape: `from.email`, `personalizations[].to[].email`, `content[].value`. Proves
+ *  the seam handles a structurally different vendor, not just a field-name rename. */
+export declare const sendgridEmailProfile: EmailSendProfile;
+export declare const DEFAULT_EMAIL_PROFILES: EmailSendProfile[];
+/**
+ * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as its email-API base URL. `close()` in a finally (mirror by-id teardown).
+ */
+export declare function startEmailCatchServer(channel: CommsChannel, options?: EmailCatchOptions): Promise<EmailCatchServer>;

package/dist/comms-email-catch.js

@@ -0,0 +1,209 @@
+// A VENDOR-NEUTRAL loopback catch server for email-send APIs (#297). An app hardwired to a hosted
+// email provider is redirected into the faux bus with ONE env var and no code change: point the app's
+// API base URL at this server. The catch does not depend on, or name itself after, any one vendor —
+// it normalizes each provider's distinct wire shape (Resend's flat body, SendGrid's nested
+// personalizations, Postmark's TitleCase, a custom app's own JSON) to one shape via pluggable
+// PROFILES, and routes the result into a CommsChannel. Resend-compatible and SendGrid-compatible out
+// of the box; extend with a custom profile for anything else. (There is no standardized email-send
+// request shape across vendors, so normalization is by design, not a shortcut.)
+//
+// 127.0.0.1 only; request bodies are never logged; request size is capped.
+import { createServer } from "node:http";
+// ---------------------------------------------------------------- shared parse helpers
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+function optStr(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** "Name <email@host>" → "email@host"; a bare address passes through. */
+function bareEmail(value) {
+    const angle = value.match(/<([^>]+)>/);
+    return (angle ? angle[1] ?? value : value).trim();
+}
+/** A recipient field → address strings: an array, a single, or a comma-separated string (Postmark). */
+function toAddresses(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => bareEmail(String(entry)));
+    if (typeof value === "string")
+        return value.split(",").map((part) => bareEmail(part)).filter((part) => part.length > 0);
+    return [];
+}
+// ---------------------------------------------------------------- built-in profiles
+/** The flat-JSON shape: `{ from, to, subject, html, text }`. Matches Resend (POST /emails) AND a
+ *  custom app that sends the common shape AND Postmark's TitleCase keys (From/To/HtmlBody/…). */
+export const genericEmailProfile = {
+    name: "generic",
+    sendPaths: ["/emails", "/emails/batch", "/email", "/email/batch", "/send"],
+    parse(_path, body) {
+        const items = Array.isArray(body) ? body : [body];
+        const out = [];
+        for (const item of items) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const rec = item;
+            const from = str(rec.from ?? rec.From);
+            const to = toAddresses(rec.to ?? rec.To);
+            const subject = optStr(rec.subject ?? rec.Subject);
+            const bodyValue = str(rec.html ?? rec.HtmlBody ?? rec.text ?? rec.TextBody);
+            if (to.length === 0 && from === "" && bodyValue === "")
+                continue;
+            out.push({ from, to, ...(subject === undefined ? {} : { subject }), body: bodyValue });
+        }
+        return out;
+    }
+};
+/** SendGrid's nested shape: `from.email`, `personalizations[].to[].email`, `content[].value`. Proves
+ *  the seam handles a structurally different vendor, not just a field-name rename. */
+export const sendgridEmailProfile = {
+    name: "sendgrid",
+    sendPaths: ["/v3/mail/send"],
+    parse(_path, body) {
+        if (typeof body !== "object" || body === null)
+            return [];
+        const rec = body;
+        const fromObj = rec.from;
+        const from = typeof fromObj === "object" && fromObj !== null ? str(fromObj.email) : str(fromObj);
+        const subject = optStr(rec.subject);
+        const content = Array.isArray(rec.content) ? rec.content : [];
+        const isPart = (part) => typeof part === "object" && part !== null;
+        const chosen = content.find((part) => isPart(part) && part.type === "text/html") ??
+            content.find((part) => isPart(part) && part.type === "text/plain");
+        const bodyValue = isPart(chosen) ? str(chosen.value) : "";
+        const personalizations = Array.isArray(rec.personalizations) ? rec.personalizations : [];
+        const to = [];
+        for (const personalization of personalizations) {
+            if (!isPart(personalization))
+                continue;
+            const recipients = Array.isArray(personalization.to) ? personalization.to : [];
+            for (const recipient of recipients) {
+                if (!isPart(recipient))
+                    continue;
+                const email = str(recipient.email);
+                if (email.length > 0)
+                    to.push(email);
+            }
+        }
+        if (to.length === 0)
+            return [];
+        return [{ from, to, ...(subject === undefined ? {} : { subject }), body: bodyValue }];
+    },
+    respond(res, ids, _batch) {
+        // SendGrid answers 202 with the id in a header and an empty body.
+        res.statusCode = 202;
+        if (ids[0] !== undefined)
+            res.setHeader("x-message-id", ids[0]);
+        res.end();
+    }
+};
+export const DEFAULT_EMAIL_PROFILES = [genericEmailProfile, sendgridEmailProfile];
+// ---------------------------------------------------------------- server
+class BodyTooLargeError extends Error {
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                // Reject WITHOUT destroying the socket here: the handler responds 413 cleanly first (a
+                // write-after-destroy would otherwise reset the connection), then tears the request down.
+                reject(new BodyTooLargeError("request body too large"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/**
+ * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as its email-API base URL. `close()` in a finally (mirror by-id teardown).
+ */
+export async function startEmailCatchServer(channel, options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const profiles = options.profiles ?? DEFAULT_EMAIL_PROFILES;
+    const received = [];
+    let idCounter = 0;
+    const idFor = options.idFor ?? ((n) => `humanish-catch-${n.toString().padStart(6, "0")}`);
+    const respondJson = (res, status, value) => {
+        res.statusCode = status;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify(value));
+    };
+    const handle = async (req, res) => {
+        const path = (req.url ?? "/").split("?")[0] ?? "/";
+        if (req.method === "GET" && (path === "/" || path === "/health")) {
+            respondJson(res, 200, { ok: true, service: "humanish-email-catch", channel: channel.channel, profiles: profiles.map((p) => p.name) });
+            return;
+        }
+        const profile = req.method === "POST" ? profiles.find((candidate) => candidate.sendPaths.includes(path)) : undefined;
+        if (profile === undefined) {
+            respondJson(res, 404, { error: "not found" });
+            return;
+        }
+        let raw;
+        try {
+            raw = await readBody(req, MAX_BODY_BYTES);
+        }
+        catch (error) {
+            if (!res.headersSent)
+                respondJson(res, error instanceof BodyTooLargeError ? 413 : 400, { error: "request body could not be read" });
+            req.destroy();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.length > 0 ? raw : "{}");
+        }
+        catch {
+            respondJson(res, 422, { error: "invalid JSON body" });
+            return;
+        }
+        const sends = profile.parse(path, parsed);
+        if (sends.length === 0) {
+            // A well-formed request that names no deliverable recipient (empty body, or a shape the profile
+            // could not resolve to a send) — return a bad-request rather than a fabricated success id.
+            respondJson(res, 422, { error: "no deliverable message in request" });
+            return;
+        }
+        const ids = [];
+        for (const send of sends) {
+            received.push(send);
+            const inbound = {
+                from: send.from,
+                to: send.to,
+                ...(send.subject === undefined ? {} : { subject: send.subject }),
+                body: send.body
+            };
+            await channel.deliverRaw(inbound);
+            idCounter += 1;
+            ids.push(idFor(idCounter));
+        }
+        const batch = Array.isArray(parsed) || path.endsWith("/batch");
+        if (profile.respond)
+            profile.respond(res, ids, batch);
+        else if (batch)
+            respondJson(res, 200, { data: ids.map((id) => ({ id })) });
+        else
+            respondJson(res, 200, { id: ids[0] ?? idFor(idCounter) });
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch(() => {
+            if (!res.headersSent)
+                respondJson(res, 500, { error: "catch server error" });
+        });
+    });
+    await new Promise((resolve) => server.listen(options.port ?? 0, host, () => resolve()));
+    const port = server.address().port;
+    return {
+        url: `http://${host}:${port}`,
+        port,
+        received,
+        close: () => new Promise((resolve) => server.close(() => resolve()))
+    };
+}
+//# sourceMappingURL=comms-email-catch.js.map

package/dist/comms-email-catch.js.map

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

package/dist/comms-faux-inbox.d.ts

@@ -0,0 +1,37 @@
+import type { CommsAddress, CommsChannel, CommsChannelKind, CommsMessage, InboundRaw, OutboundMessage } from "./comms-types.js";
+/** Extract actionable http(s) links from a message body (href="…" and bare URLs), de-duped, in order.
+ *  The verification magic-link the persona would tap. Pure; body is runtime-only. */
+export declare function extractLinks(body: string): string[];
+/** Extract OTP-shaped tokens from a message body. Labeled codes ("your code is 481920",
+ *  "verification code 8A3F2K") are high-precision and preferred; if none are labeled, fall back to an
+ *  isolated 4–8 digit run (a bare OTP). Pure; tokens are runtime-only literal-scrub targets. */
+export declare function extractOtpCodes(body: string): string[];
+export interface FauxInboxOptions {
+    /** "email" (default) or "sms" — the address shape + surface differ; machinery is identical. */
+    channel?: CommsChannelKind;
+    /** Email domain for minted addresses. Default example.test (an RFC 6761 reserved, unroutable test
+     *  domain — public-safe; override to a branded reserved domain once it's added to the email allowlist). */
+    domain?: string;
+    /** Injected clock (ms) for deterministic tests. Default Date.now. */
+    now?: () => number;
+}
+/** The in-process faux adapter. Implements the same CommsChannel port a real provider adapter would. */
+export declare class FauxInbox implements CommsChannel {
+    readonly channel: CommsChannelKind;
+    readonly kind: "faux";
+    private readonly domain;
+    private readonly clock;
+    private readonly byActor;
+    private readonly byValue;
+    private readonly queues;
+    private counter;
+    constructor(options?: FauxInboxOptions);
+    provision(actorId: string): Promise<CommsAddress>;
+    private route;
+    send(message: OutboundMessage): Promise<CommsMessage>;
+    deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;
+    poll(address: CommsAddress, since?: number): Promise<CommsMessage[]>;
+    teardown(): Promise<void>;
+    /** Inspection helper (tests / a surface): every inbox currently provisioned. */
+    addresses(): CommsAddress[];
+}

package/dist/comms-faux-inbox.js

@@ -0,0 +1,157 @@
+// The FAUX in-process email/SMS bus (#297 Stage 2). Deterministic, $0, offline, public-safe: a
+// message an app-under-test "sends" (via an ingress like the vendor-neutral email catch) is routed to the
+// addressed actor inbox and read back through the same CommsChannel port a real provider adapter
+// would implement. Nothing leaves the process. See comms-types.ts for the port + public-safety notes.
+import { digestText } from "./redaction.js";
+/** Extract actionable http(s) links from a message body (href="…" and bare URLs), de-duped, in order.
+ *  The verification magic-link the persona would tap. Pure; body is runtime-only. */
+export function extractLinks(body) {
+    if (typeof body !== "string" || body.length === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    const push = (raw) => {
+        const url = raw.trim().replace(/[).,;'"]+$/, "");
+        if (/^https?:\/\//i.test(url) && !seen.has(url)) {
+            seen.add(url);
+            out.push(url);
+        }
+    };
+    let m;
+    const href = /href\s*=\s*["']([^"']+)["']/gi;
+    while ((m = href.exec(body)) !== null)
+        push(m[1] ?? "");
+    const bare = /https?:\/\/[^\s"'<>)\]]+/gi;
+    while ((m = bare.exec(body)) !== null)
+        push(m[0]);
+    return out.slice(0, 50);
+}
+function stripTags(html) {
+    return html
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Extract OTP-shaped tokens from a message body. Labeled codes ("your code is 481920",
+ *  "verification code 8A3F2K") are high-precision and preferred; if none are labeled, fall back to an
+ *  isolated 4–8 digit run (a bare OTP). Pure; tokens are runtime-only literal-scrub targets. */
+export function extractOtpCodes(body) {
+    if (typeof body !== "string" || body.length === 0)
+        return [];
+    const text = stripTags(body);
+    const labeled = [];
+    const seen = new Set();
+    const push = (list, code) => {
+        const c = code.toUpperCase();
+        if (c && !seen.has(c)) {
+            seen.add(c);
+            list.push(c);
+        }
+    };
+    // The alphanumeric alternative requires at least one DIGIT (lookahead) so a labeled prose word like
+    // "your code is INVALID" isn't captured as a code; pure-digit codes (4–8) match directly.
+    const labeledRe = /(?:one[-\s]?time\s+(?:pass)?code|verification\s+code|security\s+code|access\s+code|login\s+code|confirmation\s+code|passcode|\bOTP\b|\bPIN\b|\bcode\b)\D{0,15}\b([0-9]{4,8}|(?=[A-Za-z0-9]*[0-9])[A-Z0-9]{6,8})\b/gi;
+    let m;
+    while ((m = labeledRe.exec(text)) !== null)
+        push(labeled, m[1] ?? "");
+    if (labeled.length > 0)
+        return labeled.slice(0, 10);
+    // Fallback: an isolated 4–8 digit run (a bare, unlabeled OTP), not embedded in a longer token.
+    const bare = [];
+    const bareRe = /(?<![0-9A-Za-z])([0-9]{4,8})(?![0-9A-Za-z])/g;
+    while ((m = bareRe.exec(text)) !== null)
+        push(bare, m[1] ?? "");
+    return bare.slice(0, 10);
+}
+function sanitizeLocalPart(actorId) {
+    return actorId.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "actor";
+}
+function smsAddressFor(actorId) {
+    const digits = digestText(actorId, 16).replace(/[a-f]/g, (c) => String(c.charCodeAt(0) % 10)).slice(0, 7);
+    return `+1555${digits}`;
+}
+/** The in-process faux adapter. Implements the same CommsChannel port a real provider adapter would. */
+export class FauxInbox {
+    channel;
+    kind = "faux";
+    domain;
+    clock;
+    byActor = new Map();
+    byValue = new Map();
+    queues = new Map();
+    counter = 0;
+    constructor(options = {}) {
+        this.channel = options.channel ?? "email";
+        this.domain = options.domain ?? "example.test";
+        this.clock = options.now ?? (() => Date.now());
+    }
+    async provision(actorId) {
+        const existing = this.byActor.get(actorId);
+        if (existing)
+            return existing;
+        const value = this.channel === "sms" ? smsAddressFor(actorId) : `${sanitizeLocalPart(actorId)}@${this.domain}`;
+        // Address collision guard: two distinct actor ids can sanitize to the same local part. Reuse the
+        // existing inbox rather than resetting its queue (which would drop already-delivered mail). Both
+        // actors then share it — a faux-world edge; declare distinct addresses to avoid it.
+        const prior = this.byValue.get(value.toLowerCase());
+        if (prior) {
+            this.byActor.set(actorId, prior);
+            return prior;
+        }
+        const address = { channel: this.channel, actorId, value, digest: digestText(value, 16) };
+        this.byActor.set(actorId, address);
+        this.byValue.set(value.toLowerCase(), address);
+        this.queues.set(value.toLowerCase(), []);
+        return address;
+    }
+    route(from, to, subject, body) {
+        const at = this.clock();
+        const message = {
+            id: `comms-${(this.counter += 1).toString().padStart(4, "0")}`,
+            channel: this.channel,
+            from,
+            to,
+            ...(subject === undefined ? {} : { subject }),
+            body,
+            links: extractLinks(body),
+            codes: extractOtpCodes(body),
+            sentAt: at,
+            deliveredAt: at
+        };
+        for (const addr of to) {
+            const queue = this.queues.get(addr.value.toLowerCase());
+            if (queue)
+                queue.push(message);
+        }
+        return message;
+    }
+    async send(message) {
+        return this.route(message.from.value, message.to, message.subject, message.body);
+    }
+    async deliverRaw(inbound) {
+        const to = (inbound.to ?? [])
+            .map((raw) => this.byValue.get(String(raw).trim().toLowerCase()))
+            .filter((address) => address !== undefined);
+        if (to.length === 0)
+            return []; // no provisioned inbox matched → nothing to deliver to
+        return [this.route(inbound.from, to, inbound.subject, inbound.body)];
+    }
+    async poll(address, since = 0) {
+        const queue = this.queues.get(address.value.toLowerCase()) ?? [];
+        return queue.filter((message) => message.deliveredAt > since);
+    }
+    async teardown() {
+        this.byActor.clear();
+        this.byValue.clear();
+        this.queues.clear();
+        this.counter = 0;
+    }
+    /** Inspection helper (tests / a surface): every inbox currently provisioned. */
+    addresses() {
+        return [...this.byActor.values()];
+    }
+}
+//# sourceMappingURL=comms-faux-inbox.js.map

package/dist/comms-faux-inbox.js.map

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

package/dist/comms-types.d.ts

@@ -0,0 +1,63 @@
+export type CommsChannelKind = "email" | "sms";
+/** One actor's inbox identity. `value` is runtime-only; `digest` is the only form meant to persist. */
+export interface CommsAddress {
+    channel: CommsChannelKind;
+    /** Which lane owns this inbox. */
+    actorId: string;
+    /** Runtime-only raw address, e.g. patient-07@example.test | +15550137. */
+    value: string;
+    /** sha256-short(value) — the only form persisted (redaction.digestText). */
+    digest: string;
+}
+/** A message that arrived to (or was sent from) an inbox. Body/links/codes are runtime-only. */
+export interface CommsMessage {
+    id: string;
+    channel: CommsChannelKind;
+    /** Raw sender — an app-under-test address, or another actor's address. Runtime-only. */
+    from: string;
+    /** Resolved recipient inboxes this message was delivered to. */
+    to: CommsAddress[];
+    subject?: string;
+    /** Runtime-only for real; local-only for faux (never a share path without redaction — #108). */
+    body: string;
+    /** Actionable links extracted from the body (magic-link / invite / reset). Runtime-only. */
+    links: string[];
+    /** OTP-shaped tokens extracted from the body. Runtime-only; literal-scrub targets. */
+    codes: string[];
+    sentAt: number;
+    deliveredAt: number;
+}
+/** An actor sending OUT (a reply/compose); recipients are known CommsAddresses. */
+export interface OutboundMessage {
+    from: CommsAddress;
+    to: CommsAddress[];
+    subject?: string;
+    body: string;
+}
+/** A raw inbound from an INGRESS (the vendor-neutral email catch, an SMTP sink, …): recipients are
+ *  raw address strings the bus resolves against its provisioned inboxes. */
+export interface InboundRaw {
+    from: string;
+    to: string[];
+    subject?: string;
+    body: string;
+}
+/**
+ * The port. Faux (in-process) + real-email + real-sms adapters implement it identically. Async so a
+ * real (network) adapter fits without changing callers; the faux adapter just resolves immediately.
+ */
+export interface CommsChannel {
+    readonly channel: CommsChannelKind;
+    readonly kind: "faux" | "real";
+    /** Mint/allocate an inbox for an actor (address auto-generated). Idempotent per actor. */
+    provision(actorId: string): Promise<CommsAddress>;
+    /** Route a composed message from one actor to addressed inboxes. Returns the delivered record. */
+    send(message: OutboundMessage): Promise<CommsMessage>;
+    /** Route a raw ingress delivery (app-under-test → recipient strings). Returns the messages that
+     *  matched a provisioned inbox (unmatched recipients are dropped — no inbox to deliver to). */
+    deliverRaw(inbound: InboundRaw): Promise<CommsMessage[]>;
+    /** New messages delivered to `address` since `since` (exclusive), oldest-first. Drives the surface. */
+    poll(address: CommsAddress, since?: number): Promise<CommsMessage[]>;
+    /** Release inboxes BY id (mirror the by-id sandbox teardown rail). */
+    teardown(): Promise<void>;
+}

package/dist/comms-types.js

@@ -0,0 +1,10 @@
+// The addressed message bus (#297) — the seam that makes "off-app" comms (email/SMS the persona
+// actually lives in) a first-class, persona-driven testable surface. A single port, addressed by
+// actor; faux (in-process) and real (provider-backed) adapters implement it identically, so the
+// persona surface + evidence writer consume it without knowing which is behind it.
+//
+// PUBLIC-SAFETY: raw address values, message bodies, links, and codes are RUNTIME-ONLY. Only the
+// address DIGEST (sha256-short, via redaction.digestText) is ever meant to reach a persisted bundle;
+// a verification link / OTP has "no secret shape" (like the lobby code) → literal-scrub + digest.
+export {};
+//# sourceMappingURL=comms-types.js.map

package/dist/comms-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-types.js","sourceRoot":"","sources":["../src/comms-types.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,iGAAiG;AACjG,gGAAgG;AAChG,mFAAmF;AACnF,EAAE;AACF,iGAAiG;AACjG,qGAAqG;AACrG,kGAAkG"}

package/dist/concurrent-shared-world-lab.js

@@ -39,7 +39,7 @@ import { adapterScoreFailureMessage, applyBrowserAdapterHooks } from "./adapter-
 import { actorRegistry, isCuaActorDescriptor } from "./actor-registry.js";
 import { toErrorMessage } from "./command-failure.js";
 import { mapWithConcurrency } from "./concurrency.js";
-import { commandDigestOf, composeLaneInstructions, defaultPackLocalTree, provisionCloneSubject, provisionLocalTreeSubject, resolveLaneDevice, resolveSubjectState, runCuaLane } from "./cua-actor-lab.js";
+import { commandDigestOf, composeLaneInstructions, defaultPackLocalTree, provisionCloneSubject, provisionLocalTreeSubject, declaredScreenForRender, resolveLaneDevice, resolveSubjectState, runCuaLane } from "./cua-actor-lab.js";
 import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 import { concurrentSharedWorldValidationReason, externalPublicSharedWorldValidationReason } from "./lab-config.js";
 import { buildObserverData } from "./observer-data.js";
@@ -1379,8 +1379,15 @@ export function buildConcurrentSharedWorldBundle(args) {
                 ? "Actor desktop is running; the attached Observer hydrates the runtime stream URL without persisting it."
                 : "Contract actor only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.");
         const traceScreenshotMode = session?.trace.redaction.screenshots;
+        // Include `declared` on the no-outcome fallback too (dry-run, skipped lane): otherwise an
+        // ABSENT declared means either "the preset rendered faithfully" or "there was no live
+        // outcome", and a dry-run bundle keeps the self-confirming shape this field exists to kill.
+        const fallbackDeclared = declaredScreenForRender(spec.devicePreset, spec.deviceName, spec.resolution);
         const desktopGeometry = outcome?.desktopGeometry ?? {
-            screen: { requested: { width: spec.resolution[0], height: spec.resolution[1] } }
+            screen: {
+                requested: { width: spec.resolution[0], height: spec.resolution[1] },
+                ...(fallbackDeclared ? { declared: fallbackDeclared } : {})
+            }
         };
         const screenshotMode = traceScreenshotMode === "raw" || traceScreenshotMode === "blurred"
             ? traceScreenshotMode