@oxygen-agent/cli 1.1003.12 → 1.1010.1

package/node_modules/@oxygen/shared/dist/llm-durable-capture.d.ts

@@ -0,0 +1,24 @@
+import type { LlmTraceBody, LlmTracingClient } from "./langfuse.js";
+export type LlmCaptureTimestampLookup = {
+    type: "root";
+    id: string;
+} | {
+    type: "event";
+    key: string;
+} | {
+    type: "approval";
+    id: string;
+    phase: "requested" | "decided";
+};
+/**
+ * Langfuse v3 deduplication includes the start date. Stable ids alone do not
+ * prevent cross-day duplicates. This per-trace adapter obtains the original
+ * ledger clock without blocking runtime methods or borrowing their transaction.
+ * The underlying transport still owns identity, payloads, isolation and flush.
+ */
+export declare function withDurableLlmCapture(input: {
+    client: LlmTracingClient;
+    enabled: boolean;
+    root: LlmTraceBody;
+    readTimestamp?: ((lookup: LlmCaptureTimestampLookup) => Promise<Date | null>) | undefined;
+}): LlmTracingClient;

package/node_modules/@oxygen/shared/dist/llm-durable-capture.js

@@ -0,0 +1,89 @@
+import { log } from "./log.js";
+/**
+ * Langfuse v3 deduplication includes the start date. Stable ids alone do not
+ * prevent cross-day duplicates. This per-trace adapter obtains the original
+ * ledger clock without blocking runtime methods or borrowing their transaction.
+ * The underlying transport still owns identity, payloads, isolation and flush.
+ */
+export function withDurableLlmCapture(input) {
+    if (!input.enabled)
+        return input.client;
+    const pending = new Set();
+    const warned = new Set();
+    const missing = (stage) => {
+        if (warned.has(stage))
+            return;
+        warned.add(stage);
+        log("warn", "llm_tracing.missing_capture", { provider: "langfuse", stage, error_code: "langfuse_immutable_timestamp_unavailable" });
+    };
+    const valid = (value) => value instanceof Date && Number.isFinite(value.getTime());
+    const read = (lookup) => new Promise((resolve) => {
+        // Bounds injected readers too. A DB reader must independently bound its
+        // statement and release its own scope when a late acquisition completes.
+        const timer = setTimeout(() => resolve(null), 750);
+        timer.unref?.();
+        void Promise.resolve().then(() => input.readTimestamp?.(lookup) ?? null).then((date) => resolve(valid(date) ? date : null), () => resolve(null)).finally(() => clearTimeout(timer));
+    });
+    const seed = (startTime) => {
+        if (!valid(startTime)) {
+            missing("root_timestamp");
+            return null;
+        }
+        try {
+            input.client.trace({ ...input.root, startTime, endTime: startTime });
+        }
+        catch {
+            missing("root_emission");
+            return null;
+        }
+        return startTime;
+    };
+    // Seed synchronously when the caller already has the run/turn row. A web
+    // approval-only tracer can instead look up its root before queued children.
+    const knownRoot = valid(input.root.startTime) ? seed(input.root.startTime) : undefined;
+    const rootReady = knownRoot !== undefined ? Promise.resolve(knownRoot)
+        : read({ type: "root", id: input.root.id }).then(seed);
+    const enqueue = (action) => {
+        const task = rootReady.then(async (start) => { if (start)
+            await action(start); }).catch(() => missing("capture"));
+        pending.add(task);
+        void task.finally(() => pending.delete(task));
+    };
+    const eventLookup = (body) => {
+        const key = body.metadata?.oxygen_durable_event_key;
+        if (typeof key === "string" && key) {
+            // Auto-approval requests have a persisted approval card before an event
+            // append. The card clock is canonical for both approval capture paths.
+            const approvalKey = /^approval_(requested|decided):(.+)$/.exec(key);
+            if (approvalKey)
+                return { type: "approval", phase: approvalKey[1], id: approvalKey[2] };
+            return { type: "event", key };
+        }
+        const approval = /^apr:(requested|decided):(.+)$/.exec(body.id);
+        return approval ? { type: "approval", phase: approval[1], id: approval[2] } : null;
+    };
+    return {
+        trace: (body) => enqueue((startTime) => input.client.trace({ ...body, startTime })),
+        generation: (body) => enqueue(() => input.client.generation(body)),
+        embedding: (body) => enqueue(() => input.client.embedding(body)),
+        span: (body) => enqueue(() => input.client.span(body)),
+        event: (body) => {
+            const lookup = eventLookup(body);
+            enqueue(async () => {
+                if (!lookup) {
+                    input.client.event(body);
+                    return;
+                }
+                const startTime = valid(body.startTime) ? body.startTime : await read(lookup);
+                if (!startTime) {
+                    missing("event_timestamp");
+                    return;
+                }
+                input.client.event({ ...body, startTime });
+            });
+        },
+        score: (body) => input.client.score(body),
+        flush: async () => { await rootReady; await Promise.allSettled([...pending]); await input.client.flush(); },
+        shutdown: async () => { await rootReady; await Promise.allSettled([...pending]); await input.client.shutdown(); },
+    };
+}

package/node_modules/@oxygen/shared/dist/llm-prompts.d.ts

@@ -0,0 +1,75 @@
+export type LlmPromptRef = {
+    /** Langfuse prompt name, e.g. `copilot.system` or `table_column`. */
+    name: string;
+    /** First 12 hex chars of sha256(template); changes whenever the template does. */
+    hash: string;
+    /** True only for code-owned templates published by the prompt sync. */
+    registered: boolean;
+};
+export type LlmPromptDefinition = LlmPromptRef & {
+    registered: true;
+    template: string;
+};
+/** Deterministic content hash; object key order never changes it. */
+export declare function llmPromptHash(template: unknown): string;
+/** The Langfuse label that identifies one exact template version. */
+export declare function llmPromptLabel(hash: string): string;
+/**
+ * Declare a code-owned prompt template. Call once at module scope with the
+ * template the call site renders from. Placeholders stay literal (`{{name}}`)
+ * so the hash moves only when the instructions do, not per request.
+ */
+export declare function defineLlmPrompt(name: string, template: string): LlmPromptDefinition;
+/** Names declared twice with different templates (a catalog defect). */
+export declare function conflictingLlmPromptNames(): string[];
+/** The Langfuse-safe name shape code prompts must use. */
+export declare function isValidLlmPromptName(name: string): boolean;
+/**
+ * An AI column's prompt as the text Langfuse stores: the instruction template
+ * (placeholders unresolved) plus its output schema, so a schema change is a new
+ * prompt version too. Customer columns and code-owned helpers share it.
+ */
+export declare function aiColumnPromptTemplate(definition: {
+    prompt?: unknown;
+    outputSchema?: unknown;
+}): string;
+/** Declare a code-owned AI helper prompt (knowledge synthesis, drafts, ...). */
+export declare function defineAiColumnPrompt(name: string, definition: {
+    prompt: string;
+    outputSchema?: Record<string, unknown> | null;
+}): LlmPromptDefinition;
+/**
+ * Resolve a lazy prompt getter on a product path. Prompt identity is telemetry:
+ * a template renderer that throws must degrade to an unlinked trace, never
+ * fail the model call it describes.
+ */
+export declare function safeLlmPrompt<T extends LlmPromptRef>(getter: () => T | null): T | null;
+/** Reference a customer-authored or per-request template: metadata only. */
+export declare function llmPromptRef(name: string, template: unknown): LlmPromptRef;
+/**
+ * The registered code prompt whose template is exactly this text, if any: lets
+ * a tracer that only sees the rendered system message recognise a static
+ * template (compaction, sub-agent instructions) without importing its owner.
+ */
+export declare function findLlmPromptByTemplate(template: string): LlmPromptDefinition | undefined;
+/**
+ * The declared code prompt behind a reference, only when its template still
+ * hashes to that reference: lets the tracing client publish the exact text a
+ * generation was rendered from, and never a same-named neighbour.
+ */
+export declare function registeredLlmPrompt(ref: LlmPromptRef): LlmPromptDefinition | undefined;
+/** Every code prompt declared by the modules imported so far, sorted by name. */
+export declare function listLlmPrompts(): LlmPromptDefinition[];
+/**
+ * The prompt a Copilot/Agent model call ran on, from the exact messages sent.
+ * A main-loop call (`kind` "turn") uses the surface's versioned system
+ * template; compaction and sub-agent calls match a registered static template
+ * by the content of one of their system messages; anything else is traced by
+ * content hash only.
+ */
+export declare function llmPromptForModelCall(input: {
+    surface: "copilot" | "agent";
+    kind: string;
+    messages: unknown;
+    turnPrompt?: LlmPromptRef | null;
+}): LlmPromptRef | null;

package/node_modules/@oxygen/shared/dist/llm-prompts.js

@@ -0,0 +1,161 @@
+// Prompt identity for LLM tracing (ADR 0014). Prompts stay in code or in the
+// tenant database; nothing here is fetched at runtime to BUILD a prompt, so a
+// Langfuse outage can never leave a model call without its instructions.
+//
+// Every traced model call carries a prompt reference: a stable name plus a
+// content hash of the template it was rendered from. Code-owned templates are
+// declared once with `defineLlmPrompt` and are REGISTERED — the deploy-time sync
+// (`scripts/ops/langfuse-prompts-sync.mjs`) publishes each one to Langfuse
+// Prompt Management under the label `oxygen-<hash>`, which lets the tracing
+// client link generations to the native prompt version. Customer-authored
+// templates (table AI columns, Agent instructions, message templates) get an
+// unregistered reference: name + hash as metadata only, never published.
+import { createHash } from "node:crypto";
+const NAME_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/;
+const registry = new Map();
+const conflicts = new Set();
+function canonical(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${typeof entry === "string" ? JSON.stringify(entry) : canonical(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+/** Deterministic content hash; object key order never changes it. */
+export function llmPromptHash(template) {
+    return createHash("sha256").update(canonical(template), "utf8").digest("hex").slice(0, 12);
+}
+/** The Langfuse label that identifies one exact template version. */
+export function llmPromptLabel(hash) {
+    return `oxygen-${hash}`;
+}
+/**
+ * Declare a code-owned prompt template. Call once at module scope with the
+ * template the call site renders from. Placeholders stay literal (`{{name}}`)
+ * so the hash moves only when the instructions do, not per request.
+ */
+export function defineLlmPrompt(name, template) {
+    // Never throws: this runs at module scope in production code. The catalog
+    // test (llm-prompt-catalog.test.ts) enforces valid, unique, non-empty names.
+    const definition = { name, hash: llmPromptHash(template), registered: true, template };
+    const existing = registry.get(name);
+    if (existing && existing.hash !== definition.hash)
+        conflicts.add(name);
+    registry.set(name, definition);
+    return definition;
+}
+/** Names declared twice with different templates (a catalog defect). */
+export function conflictingLlmPromptNames() {
+    return [...conflicts].sort();
+}
+/** The Langfuse-safe name shape code prompts must use. */
+export function isValidLlmPromptName(name) {
+    return NAME_PATTERN.test(name);
+}
+/**
+ * An AI column's prompt as the text Langfuse stores: the instruction template
+ * (placeholders unresolved) plus its output schema, so a schema change is a new
+ * prompt version too. Customer columns and code-owned helpers share it.
+ */
+export function aiColumnPromptTemplate(definition) {
+    const prompt = typeof definition.prompt === "string" ? definition.prompt : JSON.stringify(definition.prompt ?? null);
+    return definition.outputSchema == null
+        ? prompt
+        : `${prompt}\n\nOUTPUT SCHEMA\n${JSON.stringify(definition.outputSchema, null, 2)}`;
+}
+/** Declare a code-owned AI helper prompt (knowledge synthesis, drafts, ...). */
+export function defineAiColumnPrompt(name, definition) {
+    return defineLlmPrompt(name, aiColumnPromptTemplate(definition));
+}
+/**
+ * Resolve a lazy prompt getter on a product path. Prompt identity is telemetry:
+ * a template renderer that throws must degrade to an unlinked trace, never
+ * fail the model call it describes.
+ */
+export function safeLlmPrompt(getter) {
+    try {
+        return getter();
+    }
+    catch {
+        return null;
+    }
+}
+/** Reference a customer-authored or per-request template: metadata only. */
+export function llmPromptRef(name, template) {
+    return { name, hash: llmPromptHash(template), registered: false };
+}
+/**
+ * The registered code prompt whose template is exactly this text, if any: lets
+ * a tracer that only sees the rendered system message recognise a static
+ * template (compaction, sub-agent instructions) without importing its owner.
+ */
+export function findLlmPromptByTemplate(template) {
+    const hash = llmPromptHash(template);
+    for (const definition of registry.values())
+        if (definition.hash === hash)
+            return definition;
+    return undefined;
+}
+/**
+ * The declared code prompt behind a reference, only when its template still
+ * hashes to that reference: lets the tracing client publish the exact text a
+ * generation was rendered from, and never a same-named neighbour.
+ */
+export function registeredLlmPrompt(ref) {
+    if (!ref.registered)
+        return undefined;
+    const definition = registry.get(ref.name);
+    return definition?.hash === ref.hash ? definition : undefined;
+}
+/** Every code prompt declared by the modules imported so far, sorted by name. */
+export function listLlmPrompts() {
+    return [...registry.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+function systemTexts(messages) {
+    if (!Array.isArray(messages))
+        return [];
+    const texts = [];
+    for (const message of messages) {
+        if (!message || typeof message !== "object" || message.role !== "system")
+            continue;
+        const content = message.content;
+        if (typeof content === "string")
+            texts.push(content);
+        else if (Array.isArray(content)) {
+            const text = content
+                .map((part) => (part && typeof part === "object" && typeof part.text === "string" ? part.text : ""))
+                .join("");
+            if (text)
+                texts.push(text);
+        }
+    }
+    return texts;
+}
+/**
+ * The prompt a Copilot/Agent model call ran on, from the exact messages sent.
+ * A main-loop call (`kind` "turn") uses the surface's versioned system
+ * template; compaction and sub-agent calls match a registered static template
+ * by the content of one of their system messages; anything else is traced by
+ * content hash only.
+ */
+export function llmPromptForModelCall(input) {
+    if (input.kind === "turn" && input.turnPrompt)
+        return input.turnPrompt;
+    const texts = systemTexts(input.messages);
+    if (texts.length === 0)
+        return input.turnPrompt ?? null;
+    if (input.kind !== "turn") {
+        for (const text of texts) {
+            const registered = findLlmPromptByTemplate(text);
+            if (registered)
+                return registered;
+        }
+    }
+    return llmPromptRef(`${input.surface}.${input.kind === "turn" ? "system" : input.kind}`, texts.join("\n\n"));
+}

package/node_modules/@oxygen/shared/dist/mailbox-egress-ownership.d.ts

@@ -0,0 +1,90 @@
+export declare const MAILBOX_EGRESS_MODE_ENV = "OXYGEN_MAILBOX_EGRESS_MODE";
+export type MailboxEgressMode = "direct" | "proxy";
+/** `proxy` only when explicitly selected; anything else keeps today's transport. */
+export declare function readMailboxEgressMode(env?: NodeJS.ProcessEnv): MailboxEgressMode;
+export type DedicatedEgressInventoryRow = {
+    id: string;
+    organizationId: string | null;
+    status: string;
+    createdAt: Date | null;
+    vendorVerifiedAt: Date | null;
+    metadata: Record<string, unknown> | null;
+};
+export type DedicatedEgressReadinessInput = {
+    createdAt: Date | null;
+    environment: "dev" | "prod";
+    metadata: Record<string, unknown> | null;
+    vendorVerifiedAt: Date | null;
+};
+export type DedicatedEgressOwnershipSnapshot = {
+    activeOrganizationIds: ReadonlySet<string>;
+    /** Every recent retirement marker is re-evaluated on every read. */
+    retiredMetadataByOrganization: ReadonlyMap<string, readonly Record<string, unknown>[]>;
+    /** Present only when exactly one active, entitled row exists for the organization. */
+    readinessInputByOrganization: ReadonlyMap<string, DedicatedEgressReadinessInput>;
+};
+export type DedicatedEgressClassification = DedicatedEgressOwnershipSnapshot & {
+    /** Two active apps could race the same org through different IPs. */
+    conflicts: {
+        organizationId: string;
+        activeIds: string[];
+    }[];
+    /** Active inventory whose add-on entitlement is not live. */
+    entitlementMissing: {
+        organizationId: string;
+        activeId: string;
+    }[];
+};
+export type DedicatedEgressOwnership = {
+    /** Active or still-cooling dedicated inventory: never the shared IP. */
+    ownedOrganizationIds: ReadonlySet<string>;
+    /** Exact active and ready Fly app for each org; org identity alone is insufficient. */
+    readyAppNameByOrganization: ReadonlyMap<string, string>;
+};
+/**
+ * Classify `status in (active, retired)` dedicated Fly rows for one environment
+ * plus the orgs holding a live `dedicated_egress_ip` add-on. Entitlement is
+ * conservative ownership evidence: a paying org whose inventory row is missing
+ * still stays off the shared IP while its dedicated transport also blocks.
+ */
+export declare function classifyDedicatedEgressInventory(input: {
+    rows: readonly DedicatedEgressInventoryRow[];
+    entitledOrganizationIds: ReadonlySet<string>;
+    environment: "dev" | "prod";
+    now: number;
+}): DedicatedEgressClassification;
+/**
+ * Ownership at `now`. Re-evaluated on every read of a cached snapshot, because
+ * caching a readiness boolean would extend a liveness grant past its expiry.
+ */
+export declare function evaluateDedicatedEgressOwnership(snapshot: DedicatedEgressOwnershipSnapshot, now: number): DedicatedEgressOwnership;
+export type MailboxEgressRoute = 
+/** Leave from this process's own address (direct mode only). */
+{
+    kind: "direct";
+}
+/** Tunnel through the proxy Machine of this Fly app, which owns the IP. */
+ | {
+    kind: "proxy";
+    appName: string;
+    tier: "shared" | "dedicated";
+}
+/** No transport may carry this org right now. Fail closed: never fall back. */
+ | {
+    kind: "blocked";
+    reason: "dedicated_egress_not_ready" | "ownership_unreadable";
+};
+export declare const MAILBOX_EGRESS_SHARED_APP_ENV = "OXYGEN_MAILBOX_EGRESS_SHARED_APP";
+/**
+ * The Fly app whose static egress IP carries every non-dedicated org. Dev sets
+ * OXYGEN_MAILBOX_EGRESS_SHARED_APP=oxygen-table-worker-prod and tunnels through
+ * the production shared proxy (founder decision 2026-09-25: Fly holds only
+ * production proxies). Web and worker read the same value, so they agree.
+ */
+export declare function sharedMailboxEgressAppName(environment: "dev" | "prod", env?: NodeJS.ProcessEnv): string;
+/**
+ * The proxy-mode route for one org. A dedicated org uses its own app once ready
+ * and is blocked until then: routing it through the shared IP, even briefly,
+ * would show its mailboxes a second, shared source address.
+ */
+export declare function mailboxEgressRouteFor(organizationId: string, ownership: DedicatedEgressOwnership | null, environment: "dev" | "prod"): MailboxEgressRoute;

package/node_modules/@oxygen/shared/dist/mailbox-egress-ownership.js

@@ -0,0 +1,130 @@
+/**
+ * Which static egress IP may carry an organization's mailbox traffic, as pure
+ * functions over control-plane rows. The worker (every org, cached) and the web
+ * app (one org, per request) must reach the same answer from the same rows, so
+ * the classification lives here rather than in either process.
+ *
+ * Two transports read it. In `direct` mode the process's own IP carries shared
+ * orgs and a dedicated org's own Fly drain carries it. In `proxy` mode every
+ * process tunnels through the one Fly proxy Machine that owns the right IP:
+ * `oxygen-table-worker-<env>` for shared orgs, the org's own dedicated app
+ * otherwise (ADR 0029 amendment 2026-09-25).
+ */
+import { dedicatedEgressRetirementStillCooling, evaluateFlyDedicatedEgressTransportReadiness, } from "./egress-transport-readiness.js";
+export const MAILBOX_EGRESS_MODE_ENV = "OXYGEN_MAILBOX_EGRESS_MODE";
+/** `proxy` only when explicitly selected; anything else keeps today's transport. */
+export function readMailboxEgressMode(env = process.env) {
+    return env[MAILBOX_EGRESS_MODE_ENV]?.trim().toLowerCase() === "proxy" ? "proxy" : "direct";
+}
+/**
+ * Classify `status in (active, retired)` dedicated Fly rows for one environment
+ * plus the orgs holding a live `dedicated_egress_ip` add-on. Entitlement is
+ * conservative ownership evidence: a paying org whose inventory row is missing
+ * still stays off the shared IP while its dedicated transport also blocks.
+ */
+export function classifyDedicatedEgressInventory(input) {
+    const rowsByOrganization = new Map();
+    for (const row of input.rows) {
+        if (!row.organizationId)
+            continue;
+        const current = rowsByOrganization.get(row.organizationId) ?? [];
+        current.push(row);
+        rowsByOrganization.set(row.organizationId, current);
+    }
+    const activeOrganizationIds = new Set(input.entitledOrganizationIds);
+    const retiredMetadataByOrganization = new Map();
+    const readinessInputByOrganization = new Map();
+    const conflicts = [];
+    const entitlementMissing = [];
+    for (const [organizationId, organizationRows] of rowsByOrganization) {
+        const activeRows = organizationRows.filter((row) => row.status === "active");
+        const coolingRetiredRows = organizationRows.filter((row) => row.status === "retired" && dedicatedEgressRetirementStillCooling(row.metadata, input.now));
+        // Shared must keep excluding the org, but no dedicated transport may carry it
+        // while two active apps could race its jobs through different source IPs. A
+        // just-retired row also keeps shared away for one handoff window.
+        if (activeRows.length > 0)
+            activeOrganizationIds.add(organizationId);
+        if (coolingRetiredRows.length > 0) {
+            // Preserve every marker: picking one unordered row could choose an older
+            // retirement and hand the org back while a newer app's cache is alive.
+            retiredMetadataByOrganization.set(organizationId, coolingRetiredRows.map((row) => row.metadata ?? {}));
+        }
+        if (activeRows.length !== 1) {
+            if (activeRows.length > 1) {
+                conflicts.push({ organizationId, activeIds: activeRows.map((row) => row.id) });
+            }
+            continue;
+        }
+        const row = activeRows[0];
+        if (!input.entitledOrganizationIds.has(organizationId)) {
+            entitlementMissing.push({ organizationId, activeId: row.id });
+            continue;
+        }
+        readinessInputByOrganization.set(organizationId, {
+            createdAt: row.createdAt,
+            environment: input.environment,
+            metadata: row.metadata,
+            vendorVerifiedAt: row.vendorVerifiedAt,
+        });
+    }
+    return {
+        activeOrganizationIds,
+        retiredMetadataByOrganization,
+        readinessInputByOrganization,
+        conflicts,
+        entitlementMissing,
+    };
+}
+/**
+ * Ownership at `now`. Re-evaluated on every read of a cached snapshot, because
+ * caching a readiness boolean would extend a liveness grant past its expiry.
+ */
+export function evaluateDedicatedEgressOwnership(snapshot, now) {
+    const ownedOrganizationIds = new Set(snapshot.activeOrganizationIds);
+    for (const [organizationId, metadataRows] of snapshot.retiredMetadataByOrganization) {
+        if (metadataRows.some((metadata) => dedicatedEgressRetirementStillCooling(metadata, now))) {
+            ownedOrganizationIds.add(organizationId);
+        }
+    }
+    const readyAppNameByOrganization = new Map();
+    for (const [organizationId, readinessInput] of snapshot.readinessInputByOrganization) {
+        const readiness = evaluateFlyDedicatedEgressTransportReadiness(readinessInput, now);
+        if (readiness.ready)
+            readyAppNameByOrganization.set(organizationId, readiness.appName);
+    }
+    return { ownedOrganizationIds, readyAppNameByOrganization };
+}
+export const MAILBOX_EGRESS_SHARED_APP_ENV = "OXYGEN_MAILBOX_EGRESS_SHARED_APP";
+const FLY_APP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{1,62}$/;
+/**
+ * The Fly app whose static egress IP carries every non-dedicated org. Dev sets
+ * OXYGEN_MAILBOX_EGRESS_SHARED_APP=oxygen-table-worker-prod and tunnels through
+ * the production shared proxy (founder decision 2026-09-25: Fly holds only
+ * production proxies). Web and worker read the same value, so they agree.
+ */
+export function sharedMailboxEgressAppName(environment, env = process.env) {
+    const override = env[MAILBOX_EGRESS_SHARED_APP_ENV]?.trim();
+    if (override) {
+        if (!FLY_APP_NAME_PATTERN.test(override)) {
+            throw new Error(`${MAILBOX_EGRESS_SHARED_APP_ENV} is not a Fly app name`);
+        }
+        return override;
+    }
+    return `oxygen-table-worker-${environment}`;
+}
+/**
+ * The proxy-mode route for one org. A dedicated org uses its own app once ready
+ * and is blocked until then: routing it through the shared IP, even briefly,
+ * would show its mailboxes a second, shared source address.
+ */
+export function mailboxEgressRouteFor(organizationId, ownership, environment) {
+    if (!ownership)
+        return { kind: "blocked", reason: "ownership_unreadable" };
+    const dedicatedApp = ownership.readyAppNameByOrganization.get(organizationId);
+    if (dedicatedApp)
+        return { kind: "proxy", appName: dedicatedApp, tier: "dedicated" };
+    if (ownership.ownedOrganizationIds.has(organizationId)) {
+        return { kind: "blocked", reason: "dedicated_egress_not_ready" };
+    }
+    return { kind: "proxy", appName: sharedMailboxEgressAppName(environment), tier: "shared" };
+}

package/node_modules/@oxygen/shared/dist/operational-telemetry.d.ts

@@ -0,0 +1,24 @@
+type AttributeContainer = {
+    attributes?: Record<string, unknown>;
+    name?: string;
+};
+/** Sink-local copy; the managed logger retains its original record. */
+export declare function operationalLogSnapshot(record: Record<string, unknown>): Record<string, unknown>;
+/** Export a sanitized copy; never mutate the span another destination reads. */
+export declare function operationalSpanSnapshot<T extends {
+    name: string;
+    attributes: Record<string, unknown>;
+    status: {
+        code: number;
+        message?: string;
+    };
+    events: ReadonlyArray<{
+        name: string;
+        attributes?: Record<string, unknown>;
+    }>;
+    links?: ReadonlyArray<AttributeContainer>;
+    resource?: AttributeContainer;
+    instrumentationScope?: AttributeContainer;
+    spanContext(): unknown;
+}>(span: T): T;
+export {};

package/node_modules/@oxygen/shared/dist/operational-telemetry.js

@@ -0,0 +1,73 @@
+import { normalizeTelemetryAttributes, redactSecretsInString } from "./redaction.js";
+// Namespaced semantic-convention fields evade the generic exact-key log policy.
+// Numeric usage remains operational data, subject to the shared secret policy.
+const PAYLOAD_KEY = /(?:^|[._-])(?:prompts?|completions?|inputs?|outputs?|payloads?|rows?|messages?|content|body|customer_data)(?:$|[._-])|^(?:request|response)$/i;
+const EXCEPTION_CONTENT = /^exception\.(?:message|stacktrace)$/i;
+const QUERY_CONTENT = /^(?:db\.(?:statement|query\.text)(?:[._].*)?|(?:http|url)\.(?:query|query_string|request\.query)|process\.command(?:_args|_line)?)$/i;
+// Addresses keep their domain (the operational signal) and drop the person.
+const EMAIL_ADDRESS = /[A-Za-z0-9._%+-]+@((?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,})/g;
+function maskEmails(value) {
+    return value.replace(EMAIL_ADDRESS, "***@$1");
+}
+function operationalText(value) {
+    return maskEmails(redactSecretsInString(value).replace(/(?:https?:\/\/|\/)[^\s"'<>]+/gi, stripOperationalUrl));
+}
+function operationalValue(value, key, depth = 0) {
+    if (PAYLOAD_KEY.test(key) && typeof value !== "number" && typeof value !== "boolean")
+        return "[omitted]";
+    if (typeof value === "string")
+        return /(?:^|[._-])(?:url|path|target|href)(?:$|[._-])/i.test(key)
+            ? maskEmails(stripOperationalUrl(redactSecretsInString(value))) : operationalText(value);
+    if (!value || typeof value !== "object")
+        return value;
+    if (depth >= 5)
+        return "[truncated]";
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.slice(0, 20).map((entry) => operationalValue(entry, key, depth + 1));
+    return Object.fromEntries(Object.entries(value).slice(0, 40)
+        .filter(([child]) => !EXCEPTION_CONTENT.test(child) && !QUERY_CONTENT.test(child))
+        .map(([child, entry]) => [child, operationalValue(entry, child, depth + 1)]));
+}
+function operationalAttributes(attributes) {
+    return normalizeTelemetryAttributes(Object.fromEntries(Object.entries(attributes ?? {}).slice(0, 40)
+        .filter(([key]) => !EXCEPTION_CONTENT.test(key) && !QUERY_CONTENT.test(key))
+        .map(([key, value]) => [key, operationalValue(value, key)])));
+}
+/** Sink-local copy; the managed logger retains its original record. */
+export function operationalLogSnapshot(record) {
+    return operationalAttributes(record);
+}
+function containerSnapshot(container) {
+    return { ...container, attributes: operationalAttributes(container.attributes) };
+}
+/** Export a sanitized copy; never mutate the span another destination reads. */
+export function operationalSpanSnapshot(span) {
+    const attributes = operationalAttributes(span.attributes);
+    // Exception messages/stacks can contain arbitrary customer payloads. Error
+    // classification lives on the span's structured attributes and correlated log.
+    return {
+        ...span,
+        spanContext: () => span.spanContext(),
+        name: operationalText(span.name),
+        attributes,
+        status: { code: span.status.code },
+        events: span.events.map((event) => ({
+            ...containerSnapshot(event),
+            name: operationalText(event.name),
+        })),
+        ...(span.links ? { links: span.links.map(containerSnapshot) } : {}),
+        ...(span.resource ? { resource: containerSnapshot(span.resource) } : {}),
+        ...(span.instrumentationScope ? { instrumentationScope: containerSnapshot(span.instrumentationScope) } : {}),
+    };
+}
+function stripOperationalUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return value.split(/[?#]/, 1)[0] ?? "";
+    }
+}