@intx/db 0.2.2 → 0.4.0

package/dist/schema/workflow-run-launch-spec.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Immutable inputs required to recreate an exclusively placed workflow on a
+ * replacement sidecar. Secrets are deliberately excluded: source offering
+ * ids are resolved against the current catalog and principal authority when a
+ * generation is launched.
+ */
+export declare const workflowRunLaunchSpec: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "workflow_run_launch_spec";
+    schema: undefined;
+    columns: {
+        anchorRunId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "anchor_run_id";
+            tableName: "workflow_run_launch_spec";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        schemaVersion: import("drizzle-orm/pg-core").PgColumn<{
+            name: "schema_version";
+            tableName: "workflow_run_launch_spec";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sessionId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "session_id";
+            tableName: "workflow_run_launch_spec";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deploymentDomain: import("drizzle-orm/pg-core").PgColumn<{
+            name: "deployment_domain";
+            tableName: "workflow_run_launch_spec";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sourceAuthorityPrincipalId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source_authority_principal_id";
+            tableName: "workflow_run_launch_spec";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        frozenApprovalBundle: import("drizzle-orm/pg-core").PgColumn<{
+            name: "frozen_approval_bundle";
+            tableName: "workflow_run_launch_spec";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sourceOfferingIds: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source_offering_ids";
+            tableName: "workflow_run_launch_spec";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        defaultSourceOfferingId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "default_source_offering_id";
+            tableName: "workflow_run_launch_spec";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deployContent: import("drizzle-orm/pg-core").PgColumn<{
+            name: "deploy_content";
+            tableName: "workflow_run_launch_spec";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        toolPackagePins: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tool_package_pins";
+            tableName: "workflow_run_launch_spec";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "workflow_run_launch_spec";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

package/dist/schema/workflow-run-launch-spec.js

@@ -0,0 +1,26 @@
+import { integer, jsonb, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { principal } from "./principals.js";
+import { workflowRun } from "./workflow-run.js";
+/**
+ * Immutable inputs required to recreate an exclusively placed workflow on a
+ * replacement sidecar. Secrets are deliberately excluded: source offering
+ * ids are resolved against the current catalog and principal authority when a
+ * generation is launched.
+ */
+export const workflowRunLaunchSpec = pgTable("workflow_run_launch_spec", {
+    anchorRunId: text("anchor_run_id")
+        .primaryKey()
+        .references(() => workflowRun.id, { onDelete: "cascade" }),
+    schemaVersion: integer("schema_version").notNull().default(1),
+    sessionId: text("session_id").notNull(),
+    deploymentDomain: text("deployment_domain").notNull(),
+    sourceAuthorityPrincipalId: text("source_authority_principal_id")
+        .notNull()
+        .references(() => principal.id, { onDelete: "restrict" }),
+    frozenApprovalBundle: jsonb("frozen_approval_bundle").notNull(),
+    sourceOfferingIds: jsonb("source_offering_ids").notNull(),
+    defaultSourceOfferingId: text("default_source_offering_id").notNull(),
+    deployContent: jsonb("deploy_content").notNull(),
+    toolPackagePins: jsonb("tool_package_pins"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+});

package/dist/schema/{instances.d.ts → workflow-run.d.ts}

@@ -1,10 +1,18 @@
-export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithColumns<{
-    name: "agent_instance";
+export type WorkflowRunCredentialRefs = {
+    credentialIds: string[];
+    bindings: {
+        handle: string;
+        credentialId: string;
+        consumer: string;
+    }[];
+};
+export declare const workflowRun: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "workflow_run";
     schema: undefined;
     columns: {
         id: import("drizzle-orm/pg-core").PgColumn<{
             name: "id";
-            tableName: "agent_instance";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
@@ -19,9 +27,9 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        agentId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "agent_id";
-            tableName: "agent_instance";
+        definitionId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "definition_id";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
@@ -36,14 +44,14 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        tenantId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "tenant_id";
-            tableName: "agent_instance";
+        anchorRunId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "anchor_run_id";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
             driverParam: string;
-            notNull: true;
+            notNull: false;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -53,9 +61,9 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        principalId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "principal_id";
-            tableName: "agent_instance";
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant_id";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
@@ -70,14 +78,14 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        address: import("drizzle-orm/pg-core").PgColumn<{
-            name: "address";
-            tableName: "agent_instance";
+        principalId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "principal_id";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
             driverParam: string;
-            notNull: true;
+            notNull: false;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -87,26 +95,26 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        versionId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "version_id";
-            tableName: "agent_instance";
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
-            data: string;
+            data: "deployed" | "failed" | "running" | "completed" | "cancelled";
             driverParam: string;
-            notNull: false;
-            hasDefault: false;
+            notNull: true;
+            hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
+            enumValues: ["deployed", "running", "completed", "failed", "cancelled"];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        sessionId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "session_id";
-            tableName: "agent_instance";
+        address: import("drizzle-orm/pg-core").PgColumn<{
+            name: "address";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
@@ -121,26 +129,9 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        status: import("drizzle-orm/pg-core").PgColumn<{
-            name: "status";
-            tableName: "agent_instance";
-            dataType: "string";
-            columnType: "PgText";
-            data: "deployed" | "stopped" | "error" | "running" | "updating";
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["deployed", "running", "updating", "error", "stopped"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-        sidecarId: import("drizzle-orm/pg-core").PgColumn<{
-            name: "sidecar_id";
-            tableName: "agent_instance";
+        publicKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "public_key";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
@@ -155,9 +146,9 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        publicKey: import("drizzle-orm/pg-core").PgColumn<{
-            name: "public_key";
-            tableName: "agent_instance";
+        sidecarId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "sidecar_id";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
@@ -174,7 +165,7 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
         }, {}, {}>;
         kernelId: import("drizzle-orm/pg-core").PgColumn<{
             name: "kernel_id";
-            tableName: "agent_instance";
+            tableName: "workflow_run";
             dataType: "string";
             columnType: "PgText";
             data: string;
@@ -191,7 +182,7 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
         }, {}, {}>;
         modelPreferences: import("drizzle-orm/pg-core").PgColumn<{
             name: "model_preferences";
-            tableName: "agent_instance";
+            tableName: "workflow_run";
             dataType: "json";
             columnType: "PgJsonb";
             data: unknown;
@@ -206,15 +197,15 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        createdAt: import("drizzle-orm/pg-core").PgColumn<{
-            name: "created_at";
-            tableName: "agent_instance";
-            dataType: "date";
-            columnType: "PgTimestamp";
-            data: Date;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
+        credentialRefs: import("drizzle-orm/pg-core").PgColumn<{
+            name: "credential_refs";
+            tableName: "workflow_run";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: WorkflowRunCredentialRefs;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
@@ -222,10 +213,12 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
             baseColumn: never;
             identity: undefined;
             generated: undefined;
-        }, {}, {}>;
-        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
-            name: "updated_at";
-            tableName: "agent_instance";
+        }, {}, {
+            $type: WorkflowRunCredentialRefs;
+        }>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "workflow_run";
             dataType: "date";
             columnType: "PgTimestamp";
             data: Date;
@@ -242,7 +235,7 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
         }, {}, {}>;
         endedAt: import("drizzle-orm/pg-core").PgColumn<{
             name: "ended_at";
-            tableName: "agent_instance";
+            tableName: "workflow_run";
             dataType: "date";
             columnType: "PgTimestamp";
             data: Date;
@@ -260,3 +253,5 @@ export declare const agentInstance: import("drizzle-orm/pg-core").PgTableWithCol
     };
     dialect: "pg";
 }>;
+export declare const liveWorkflowRunStatuses: readonly ["deployed", "running"];
+export declare function isLiveWorkflowRunStatus(status: string): boolean;

package/dist/schema/workflow-run.js

@@ -0,0 +1,110 @@
+import { sql } from "drizzle-orm";
+import { index, jsonb, pgTable, text, timestamp, uniqueIndex, } from "drizzle-orm/pg-core";
+import { principal } from "./principals.js";
+import { sidecar } from "./sidecar.js";
+import { tenant } from "./tenants.js";
+import { workflowDefinition } from "./workflow-definitions.js";
+// workflow_run is the per-run authorization subject: one row per run of a
+// workflow deployment. It gives "this approval belongs to a real run of this
+// deployment" a database referent, so approvals and signal correlations anchor
+// to a run row rather than a bare run id string.
+//
+// The id is opaque and heterogeneous: a deployment's addressable top-level
+// run uses its stable mail address, while internal body-child runs use freshly
+// minted synthetic ids. Both are run identifiers, so no format is enforced on
+// the column.
+export const workflowRun = pgTable("workflow_run", {
+    id: text("id").primaryKey(),
+    // The definition a run belongs to, carried by every run: a folded
+    // agent-origin run sets it at launch, and a deployment's anchor run and its
+    // child runs carry the deployment's definition. It is the run's anchor to a
+    // first-class definition. `cascade` matches `anchorRunId`'s onDelete, so
+    // deleting the definition removes its runs.
+    definitionId: text("definition_id")
+        .notNull()
+        .references(() => workflowDefinition.id, { onDelete: "cascade" }),
+    // Nullable as of the fold: a folded agent-origin run carries a
+    // `definitionId` and no deployment, while a deployment's anchor run sets
+    // this to its own id and a child run sets it to its anchor's id. It
+    // references the anchor `workflow_run` -- the run whose id equals the
+    // deployment id -- so an anchor row is self-referential. The only runtime
+    // read of the column (`resolveWorkflowPrincipalNames`) degrades gracefully
+    // when it is null.
+    anchorRunId: text("anchor_run_id").references(() => workflowRun.id, { onDelete: "cascade" }),
+    tenantId: text("tenant_id")
+        .notNull()
+        .references(() => tenant.id, { onDelete: "cascade" }),
+    // Nullable by design: an internal, workflow-spawned run has no principal of
+    // its own -- it inherits the deployment's grants at read time -- so null is
+    // the honest signal for "this run has no own principal." `onDelete: "set
+    // null"` is deliberate (unlike agent_instance's principal, which uses the
+    // implicit default): deleting a run's principal nulls the column rather than
+    // wedging the run row.
+    principalId: text("principal_id").references(() => principal.id, {
+        onDelete: "set null",
+    }),
+    // A deployment's anchor run is born "deployed": the deploy->first-trigger
+    // window is live but not yet running. The first trigger reconciles the
+    // anchor and flips this column "deployed" -> "running" (see
+    // `anchorWithPrincipal`). A child run has no such window -- it exists only
+    // once execution spawns it -- so it is born "running". A run settles into a
+    // terminal status when its terminal event lands on the workflow-run ref:
+    // the hub's pack-receive path flips this column under a live-status guard so
+    // a redelivered terminal event does not re-terminate the run.
+    status: text("status", {
+        enum: ["deployed", "running", "completed", "failed", "cancelled"],
+    })
+        .notNull()
+        .default("running"),
+    // Runtime bindings a folded run carries, mirroring `agent_instance`: a
+    // folded run IS the launched instance, so it owns its routing endpoint.
+    // `address` is that endpoint -- nullable because an address-less child run
+    // routes via its deployment (a deployment's anchor run instead carries a
+    // workflow-derived address), but unique among the runs that set it (the
+    // partial unique index below). The folded launch writes `address` and
+    // `modelPreferences`; `publicKey` is persisted when the sidecar acks the
+    // deploy; no code populates `sidecarId`/`kernelId`.
+    address: text("address"),
+    publicKey: text("public_key"),
+    sidecarId: text("sidecar_id").references(() => sidecar.id, {
+        onDelete: "set null",
+    }),
+    kernelId: text("kernel_id"),
+    modelPreferences: jsonb("model_preferences"),
+    // The non-secret shape of the credential delivery this deployment resolved
+    // at deploy: the credentialIds it references and the tool binding
+    // descriptors. Set on a deployment anchor run; null for runs that carry no
+    // credential delivery. Secrets are NEVER stored here -- only ids and
+    // descriptors -- so the reconnect resync can re-resolve each id's CURRENT
+    // material from the credential table (dropping a revoked or deleted id,
+    // picking up a rotated secret) and reconcile the reconnecting child.
+    credentialRefs: jsonb("credential_refs").$type(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    // Nullable: a run has no end time until it reaches a terminal state.
+    endedAt: timestamp("ended_at"),
+}, (t) => [
+    // Supports lookups of a definition's runs, the read path folded runs use
+    // once `definitionId` is the anchor.
+    index("workflow_run_definition_idx").on(t.definitionId),
+    // A folded run owns a unique routing address, exactly like the agent
+    // instance it stands in for; a run that anchors on a deployment instead
+    // leaves `address` null and is not indexed. Partial so the many null-address
+    // rows never collide and are kept out of the index.
+    uniqueIndex("workflow_run_address_idx")
+        .on(t.address)
+        .where(sql `${t.address} is not null`),
+]);
+// The statuses a run holds while live -- not yet settled into a terminal state.
+// A deployment anchor is born "deployed" and flips to "running" on its first
+// trigger; a child run is born "running". Every status gate that must treat a
+// live run as live tests membership here, so "which statuses count as live" has
+// a single definition rather than a `status !== "running"` scattered across the
+// workflow-run domain. The `satisfies` bound makes a drift from the column enum
+// a compile error.
+export const liveWorkflowRunStatuses = [
+    "deployed",
+    "running",
+];
+export function isLiveWorkflowRunStatus(status) {
+    return liveWorkflowRunStatuses.some((live) => live === status);
+}

package/dist/sender-key-resolver.d.ts

@@ -0,0 +1,91 @@
+import type { DBExecutor } from "./client.js";
+import type { PrincipalKeyStore } from "./principal-key-store.js";
+/**
+ * The durable public key that authenticates a signed mail sender, resolved from
+ * the hub's own storage. `source` records which store the key came from -- a
+ * run sender's key is the sidecar-minted key recorded on the deployment anchor,
+ * a user sender's key is the hub-custodied principal key -- so a consumer can
+ * bucket a resolution without re-parsing the address.
+ */
+export type SenderKeyResolution = {
+    source: "run";
+    publicKey: string;
+} | {
+    source: "user";
+    publicKey: string;
+};
+/**
+ * Resolve the durable public key a signed mail sender must verify against,
+ * unioning the two existing durable-key sources: a run address
+ * (`run_<id>@<domain>`) resolves to the run's `workflow_run.public_key`; any
+ * other address (`<refId>@<domain>`) is treated as a user sender and resolves
+ * to that principal's hub-custodied key.
+ *
+ * Read-only. Returns `null` when the sender has no durable key to resolve -- a
+ * malformed address, an unknown run, a run whose deploy has not been acked yet,
+ * or an address that matches no user principal. A `null` is a legitimate
+ * "unresolvable sender" answer the caller acts on; it is NOT an error.
+ *
+ * Addresses are matched case-insensitively. Inbound `From` addresses are
+ * lowercased when parsed (see `@intx/mime` `extractAddrSpec`), so the address is
+ * normalized here and stored values are compared under `lower(...)`. Tenant
+ * domains are `lower(domain)`-unique (`tenant_domain_lower_idx`), so a
+ * normalized domain matches at most one tenant. A user `refId` is a
+ * case-sensitively-unique betterAuth id that can carry uppercase; lowercasing it
+ * to reconcile with the parser is lossy, so the resolver prefers the exact
+ * (already-lowercase) row and falls back to a case-insensitive match to find a
+ * mixed-case-stored refId. When two principals in one tenant hold case-variant
+ * refIds the case-insensitive match is not unique and no exact row disambiguates
+ * it: the resolver throws rather than silently return one, which would attribute
+ * the sender to the wrong principal.
+ */
+export declare function resolveSenderKey(db: DBExecutor, principalKeyStore: PrincipalKeyStore, address: string): Promise<SenderKeyResolution | null>;
+/**
+ * Resolve the hex-encoded public key to stamp on an outbound mail frame, as a
+ * BEST-EFFORT value that never blocks delivery. Returns the key, or `null` when
+ * the sender has no resolvable key -- OR when resolution FAILS.
+ *
+ * {@link resolveSenderKey} throws on a genuine fault (an ambiguous user address,
+ * or a principal with no active key -- an INTR-164 invariant break). Those
+ * throws must fail loud for {@link auditSenderKeys}, but they must not break
+ * the send path: the frame key is nullable, so a recipient with no co-delivered
+ * key resolves the sender as `unknown`, which its admission policy rejects by
+ * default (a workflow may relax `unknown` to admit).
+ * Coupling delivery to key resolution would let a data-integrity fault strand a
+ * run or drop mail. So a throw here degrades to `null` and is logged at ERROR
+ * with its cause -- a degraded fault, kept distinct from the ordinary
+ * unresolvable-sender `null`, which stays silent.
+ *
+ * The principal key store is real in production (INTR-164 mints every principal
+ * a key), so the throw path is a defensive safety net, not the common case: the
+ * normal outcome is a resolved, populated key.
+ */
+export declare function resolveFrameSenderKey(db: DBExecutor, principalKeyStore: PrincipalKeyStore, address: string): Promise<string | null>;
+/**
+ * The outcome of sweeping every sender that could sign a piece of mail: how many
+ * of each kind were checked, and any whose address did not resolve to a durable
+ * key. An empty `unresolved` is the "no unresolvable signed senders" state a
+ * durable-signature verifier depends on.
+ */
+export type SenderKeyAuditReport = {
+    runsChecked: number;
+    usersChecked: number;
+    unresolved: {
+        address: string;
+        kind: "run" | "user";
+    }[];
+};
+/**
+ * Sweep every mail sender that could sign and confirm each resolves to a durable
+ * public key via {@link resolveSenderKey}. Read-only.
+ *
+ * The senders that can sign are every workflow run that holds a signing key or
+ * is live ("running") and carries a sending address, plus every active user
+ * principal. A never-signed run -- deployed-but-not-yet-acked, or failed or
+ * cancelled before ack (address set, key null) -- is excluded. Any checked
+ * sender that does not resolve is collected in `unresolved`. A keyless user
+ * principal is an INTR-164 invariant break, so `resolveSenderKey` throws and the
+ * sweep fails loudly rather than folding it into `unresolved` -- it is a
+ * different, more serious fault than an unresolvable address.
+ */
+export declare function auditSenderKeys(db: DBExecutor, principalKeyStore: PrincipalKeyStore): Promise<SenderKeyAuditReport>;