@intx/db 0.1.2 → 0.3.0

package/dist/parse-row.js

@@ -0,0 +1,232 @@
+import { type } from "arktype";
+import { Capability, CredentialBinding, GrantRequirement, grantEffects, grantOrigins, InvokerModelPreferences, ModelProviderPlugin, ModelRequirements, principalKinds, principalStatuses, signalKinds, TenantConfig, workflowDefinitionStatuses, workflowDefinitionVersionStatuses, } from "@intx/types";
+import { WireGrantRule } from "@intx/types/grant-wire";
+import { FrozenApprovalBundle, RepoAction } from "@intx/types/sidecar";
+import { ToolPackagePinArray } from "@intx/types/tool-packages";
+const JSONObject = type("Record<string, unknown>");
+const StringArray = type("string[]");
+const WireGrantRuleArray = WireGrantRule.array();
+const GrantEffectValidator = type.enumerated(...grantEffects);
+const GrantOriginValidator = type.enumerated(...grantOrigins);
+const approvalScopes = ["once", "always"];
+const ApprovalScopeValidator = type.enumerated(...approvalScopes);
+const approvalStatuses = [
+    "pending",
+    "approved",
+    "rejected",
+    "timeout",
+    "expired",
+];
+const ApprovalStatusValidator = type.enumerated(...approvalStatuses);
+const SignalKindValidator = type.enumerated(...signalKinds);
+const workflowRunStatuses = [
+    "deployed",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+];
+const WorkflowRunStatusValidator = type.enumerated(...workflowRunStatuses);
+const WorkflowRunDispatchStatusValidator = type.enumerated("pending", "acknowledged", "settled", "failed");
+const WorkflowRunDispatchKindValidator = type.enumerated("mail", "signal");
+const WorkflowDefinitionStatusValidator = type.enumerated(...workflowDefinitionStatuses);
+const WorkflowDefinitionVersionStatusValidator = type.enumerated(...workflowDefinitionVersionStatuses);
+const PrincipalKindValidator = type.enumerated(...principalKinds);
+const PrincipalStatusValidator = type.enumerated(...principalStatuses);
+const credentialTypes = [
+    "api_key",
+    "oauth_token",
+    "certificate",
+    "other",
+];
+const CredentialTypeValidator = type.enumerated(...credentialTypes);
+const credentialStatuses = ["active", "expired", "revoked", "error"];
+const CredentialStatusValidator = type.enumerated(...credentialStatuses);
+const walletBackendTypes = ["crypto", "fiat", "credits"];
+const WalletBackendTypeValidator = type.enumerated(...walletBackendTypes);
+const transactionDirections = ["inbound", "outbound"];
+const TransactionDirectionValidator = type.enumerated(...transactionDirections);
+const transactionStatuses = ["pending", "completed", "failed"];
+const TransactionStatusValidator = type.enumerated(...transactionStatuses);
+const gitTokenKinds = ["pat", "svc"];
+export const GitTokenKindValidator = type.enumerated(...gitTokenKinds);
+const turnPartTypes = [
+    "text",
+    "reasoning",
+    "tool",
+    "file",
+    "error",
+    "refusal",
+    "safety_rating",
+    "step-start",
+    "step-finish",
+    "snapshot",
+    "patch",
+];
+const TurnPartTypeValidator = type.enumerated(...turnPartTypes);
+export function parseWorkflowDefinitionRow(row) {
+    return {
+        ...row,
+        status: WorkflowDefinitionStatusValidator.assert(row.status),
+        grantRequirements: row.grantRequirements !== null
+            ? GrantRequirement.array().assert(row.grantRequirements)
+            : null,
+        modelRequirements: row.modelRequirements !== null
+            ? ModelRequirements.assert(row.modelRequirements)
+            : null,
+        // Nullable jsonb: `null` on a real drizzle row, `undefined` only on a
+        // partial row-shaped test stub that predates the column. Both mean "no
+        // bindings" -- treat them alike rather than asserting `undefined` as an
+        // array.
+        credentialBindings: row.credentialBindings === null || row.credentialBindings === undefined
+            ? null
+            : CredentialBinding.array().assert(row.credentialBindings),
+    };
+}
+export function parseWorkflowDefinitionVersionRow(row) {
+    return {
+        ...row,
+        status: WorkflowDefinitionVersionStatusValidator.assert(row.status),
+    };
+}
+export function parseGrantRow(row) {
+    return {
+        ...row,
+        effect: GrantEffectValidator.assert(row.effect),
+        origin: GrantOriginValidator.assert(row.origin),
+        conditions: row.conditions !== null ? JSONObject.assert(row.conditions) : null,
+    };
+}
+export function parseApprovalRow(row) {
+    return {
+        ...row,
+        scope: row.scope !== null ? ApprovalScopeValidator.assert(row.scope) : null,
+        status: ApprovalStatusValidator.assert(row.status),
+        toolDefinition: JSONObject.assert(row.toolDefinition),
+        toolArguments: JSONObject.assert(row.toolArguments),
+    };
+}
+export function parsePrincipalRow(row) {
+    return {
+        ...row,
+        kind: PrincipalKindValidator.assert(row.kind),
+        status: PrincipalStatusValidator.assert(row.status),
+    };
+}
+export function parseSignalCorrelationRow(row) {
+    return {
+        ...row,
+        kind: SignalKindValidator.assert(row.kind),
+    };
+}
+export function parseWorkflowRunRow(row) {
+    return {
+        ...row,
+        status: WorkflowRunStatusValidator.assert(row.status),
+        modelPreferences: row.modelPreferences !== null
+            ? InvokerModelPreferences.assert(row.modelPreferences)
+            : null,
+    };
+}
+export function parseWorkflowRunLaunchSpecRow(row) {
+    const sourceOfferingIds = StringArray.assert(row.sourceOfferingIds);
+    assertLaunchSpecSources(sourceOfferingIds, row.defaultSourceOfferingId);
+    return {
+        ...row,
+        frozenApprovalBundle: FrozenApprovalBundle.assert(row.frozenApprovalBundle),
+        sourceOfferingIds,
+        deployContent: JSONObject.assert(row.deployContent),
+        toolPackagePins: row.toolPackagePins !== null
+            ? ToolPackagePinArray.assert(row.toolPackagePins)
+            : null,
+    };
+}
+export function parseWorkflowRunDispatchRow(row) {
+    return {
+        ...row,
+        kind: WorkflowRunDispatchKindValidator.assert(row.kind),
+        status: WorkflowRunDispatchStatusValidator.assert(row.status),
+        stepGrants: WireGrantRuleArray.assert(row.stepGrants),
+    };
+}
+function assertLaunchSpecSources(sourceOfferingIds, defaultSourceOfferingId) {
+    if (sourceOfferingIds.length === 0) {
+        throw new Error("workflow launch spec requires at least one source offering");
+    }
+    if (new Set(sourceOfferingIds).size !== sourceOfferingIds.length) {
+        throw new Error("workflow launch spec source offering ids must be unique");
+    }
+    if (!sourceOfferingIds.includes(defaultSourceOfferingId)) {
+        throw new Error(`workflow launch spec default source ${defaultSourceOfferingId} is not in its source offering ids`);
+    }
+}
+export function parseOfferingRow(row) {
+    return {
+        ...row,
+        pricing: row.pricing !== null ? JSONObject.assert(row.pricing) : null,
+        schema: row.schema !== null ? JSONObject.assert(row.schema) : null,
+    };
+}
+export function parseCredentialRow(row) {
+    return {
+        ...row,
+        type: CredentialTypeValidator.assert(row.type),
+        status: CredentialStatusValidator.assert(row.status),
+        metadata: row.metadata !== null ? JSONObject.assert(row.metadata) : null,
+    };
+}
+export function parseProviderRow(row) {
+    return {
+        ...row,
+        metadata: row.metadata !== null ? JSONObject.assert(row.metadata) : null,
+    };
+}
+export function parseModelProviderRow(row) {
+    return {
+        ...row,
+        plugin: ModelProviderPlugin.assert(row.plugin),
+    };
+}
+export function parseModelOfferingRow(row) {
+    return {
+        ...row,
+        capabilities: Capability.array().assert(row.capabilities),
+        quirks: row.quirks !== null ? JSONObject.assert(row.quirks) : null,
+    };
+}
+export function parseTenantRow(row) {
+    return {
+        ...row,
+        config: row.config !== null ? TenantConfig.assert(row.config) : null,
+    };
+}
+export function parseWalletRow(row) {
+    return {
+        ...row,
+        backendType: WalletBackendTypeValidator.assert(row.backendType),
+        config: row.config !== null ? JSONObject.assert(row.config) : null,
+    };
+}
+export function parseTransactionRow(row) {
+    return {
+        ...row,
+        direction: TransactionDirectionValidator.assert(row.direction),
+        status: TransactionStatusValidator.assert(row.status),
+    };
+}
+export function parseOAuthClientRow(row) {
+    return {
+        ...row,
+        metadata: row.metadata !== null ? JSONObject.assert(row.metadata) : null,
+    };
+}
+export function parseGitTokenRow(row) {
+    return {
+        ...row,
+        kind: GitTokenKindValidator.assert(row.kind),
+        actions: RepoAction.array().assert(row.actions),
+    };
+}
+export function parseTurnPartType(partType) {
+    return TurnPartTypeValidator.assert(partType);
+}

package/dist/pg-error.d.ts

@@ -0,0 +1,3 @@
+export declare const PG_UNIQUE_VIOLATION = "23505";
+export declare const PG_FOREIGN_KEY_VIOLATION = "23503";
+export declare function pgErrorCode(err: unknown): string | undefined;

package/dist/pg-error.js

@@ -0,0 +1,19 @@
+import { hasCode } from "@intx/types";
+// Postgres SQLSTATE codes. https://www.postgresql.org/docs/current/errcodes-appendix.html
+export const PG_UNIQUE_VIOLATION = "23505";
+export const PG_FOREIGN_KEY_VIOLATION = "23503";
+// Extract a Postgres SQLSTATE from an error that a driver or ORM may have
+// wrapped. postgres-js sets the code on the error it throws; Drizzle
+// re-wraps that as the `cause` of a DrizzleQueryError, so the code can sit
+// one or more levels down the cause chain. Walk the chain (depth-bounded so
+// a self-referential cause cannot loop) and return the first code found.
+export function pgErrorCode(err) {
+    let cur = err;
+    for (let depth = 0; cur != null && depth < 8; depth++) {
+        if (hasCode(cur)) {
+            return cur.code;
+        }
+        cur = cur.cause;
+    }
+    return undefined;
+}

package/dist/pricing.d.ts

@@ -0,0 +1,15 @@
+import type { modelPricing } from "./schema/catalog.js";
+export type ModelPricingRow = typeof modelPricing.$inferSelect;
+/**
+ * Selects the active pricing row per currency from an offering's append-only
+ * price history. For each currency, the active row is the one with the
+ * greatest `effectiveFrom` that is at or before `asOf`; rows dated after
+ * `asOf` are not yet in effect. The `(offeringId, currency, effectiveFrom)`
+ * uniqueness on the table guarantees no ties, so the selection is
+ * unambiguous.
+ *
+ * Pure: `asOf` is a parameter, never read from the clock, so the same
+ * function serves discovery (asOf = now) and historical cost attribution
+ * (asOf = the call's billing timestamp).
+ */
+export declare function resolveActivePrice(rows: ModelPricingRow[], asOf: Date): ModelPricingRow[];

package/dist/pricing.js

@@ -0,0 +1,24 @@
+/**
+ * Selects the active pricing row per currency from an offering's append-only
+ * price history. For each currency, the active row is the one with the
+ * greatest `effectiveFrom` that is at or before `asOf`; rows dated after
+ * `asOf` are not yet in effect. The `(offeringId, currency, effectiveFrom)`
+ * uniqueness on the table guarantees no ties, so the selection is
+ * unambiguous.
+ *
+ * Pure: `asOf` is a parameter, never read from the clock, so the same
+ * function serves discovery (asOf = now) and historical cost attribution
+ * (asOf = the call's billing timestamp).
+ */
+export function resolveActivePrice(rows, asOf) {
+    const byCurrency = new Map();
+    for (const row of rows) {
+        if (row.effectiveFrom > asOf)
+            continue;
+        const current = byCurrency.get(row.currency);
+        if (current === undefined || row.effectiveFrom > current.effectiveFrom) {
+            byCurrency.set(row.currency, row);
+        }
+    }
+    return Array.from(byCurrency.values());
+}

package/dist/rekey-credential-secrets.d.ts

@@ -0,0 +1,13 @@
+import { type CredentialCipher } from "@intx/types";
+import type { DB } from "./client.js";
+export type RekeyReport = {
+    /** Credential `secret` columns newly encrypted. */
+    credentialSecrets: number;
+    /** Credential `refresh_secret` columns newly encrypted. */
+    credentialRefreshSecrets: number;
+    /** OAuth-client `client_secret` columns newly encrypted. */
+    oauthClientSecrets: number;
+    /** Columns already encrypted and left unchanged. */
+    alreadyEncrypted: number;
+};
+export declare function rekeyCredentialSecrets(db: DB["db"], cipher: CredentialCipher): Promise<RekeyReport>;

package/dist/rekey-credential-secrets.js

@@ -0,0 +1,61 @@
+// Re-key existing credential secrets: encrypt any secret still stored as
+// plaintext, in place, under the given cipher.
+//
+// Ordinarily every secret is encrypted at its write site, so on a database
+// created after encryption-at-rest landed there is nothing to do. This pass
+// exists for the transition: a database whose rows predate encryption still
+// holds plaintext, and the strict read path throws on a non-ciphertext value.
+// Running this once (against a stopped hub, so no write races an un-re-keyed
+// row) brings every row to the encrypted form.
+//
+// Idempotent: a value already a ciphertext is skipped, so the pass is safe to
+// re-run or resume after a partial failure.
+import { eq } from "drizzle-orm";
+import { credentialAad } from "@intx/types";
+import { isCiphertext } from "@intx/crypto";
+import { credential } from "./schema/credentials.js";
+import { oauthClient } from "./schema/oauth-clients.js";
+export async function rekeyCredentialSecrets(db, cipher) {
+    const report = {
+        credentialSecrets: 0,
+        credentialRefreshSecrets: 0,
+        oauthClientSecrets: 0,
+        alreadyEncrypted: 0,
+    };
+    for (const row of await db.select().from(credential)) {
+        const updates = {};
+        if (isCiphertext(row.secret)) {
+            report.alreadyEncrypted += 1;
+        }
+        else {
+            updates.secret = await cipher.encrypt(row.secret, credentialAad(row.id, "secret"));
+            report.credentialSecrets += 1;
+        }
+        if (row.refreshSecret !== null) {
+            if (isCiphertext(row.refreshSecret)) {
+                report.alreadyEncrypted += 1;
+            }
+            else {
+                updates.refreshSecret = await cipher.encrypt(row.refreshSecret, credentialAad(row.id, "refreshSecret"));
+                report.credentialRefreshSecrets += 1;
+            }
+        }
+        if (updates.secret !== undefined || updates.refreshSecret !== undefined) {
+            await db.update(credential).set(updates).where(eq(credential.id, row.id));
+        }
+    }
+    for (const row of await db.select().from(oauthClient)) {
+        if (isCiphertext(row.clientSecret)) {
+            report.alreadyEncrypted += 1;
+            continue;
+        }
+        await db
+            .update(oauthClient)
+            .set({
+            clientSecret: await cipher.encrypt(row.clientSecret, credentialAad(row.id, "clientSecret")),
+        })
+            .where(eq(oauthClient.id, row.id));
+        report.oauthClientSecrets += 1;
+    }
+    return report;
+}

package/dist/schema/approvals.d.ts

@@ -0,0 +1,245 @@
+export declare const approval: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "approval";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant_id";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        anchorRunId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "anchor_run_id";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        runId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "run_id";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        agentAddress: import("drizzle-orm/pg-core").PgColumn<{
+            name: "agent_address";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        correlationId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "correlation_id";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        toolDefinition: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tool_definition";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        toolArguments: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tool_arguments";
+            tableName: "approval";
+            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;
+        }, {}, {}>;
+        scope: import("drizzle-orm/pg-core").PgColumn<{
+            name: "scope";
+            tableName: "approval";
+            dataType: "string";
+            columnType: "PgText";
+            data: "always" | "once";
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["once", "always"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "approval";
+            dataType: "string";
+            columnType: "PgText";
+            data: "pending" | "approved" | "rejected" | "timeout" | "expired";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "approved", "rejected", "timeout", "expired"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timeoutAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timeout_at";
+            tableName: "approval";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        resolvedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "resolved_at";
+            tableName: "approval";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            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: "approval";
+            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;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "approval";
+            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/approvals.js

@@ -0,0 +1,52 @@
+import { index, jsonb, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { tenant } from "./tenants.js";
+import { workflowRun } from "./workflow-run.js";
+// Every approval originates from a workflow deployment, so the origin is
+// modeled as the deployment's anchor run -- the workflow_run whose id equals
+// the deployment id -- rather than a launched single agent. A workflow
+// deployment has no `agent_instance` or `agent` row, and the principal its run
+// executes under is a substrate principal, not a `principal`-table row -- so
+// none of those tables can hold a valid referent for an approval's origin.
+export const approval = pgTable("approval", {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id")
+        .notNull()
+        .references(() => tenant.id, { onDelete: "cascade" }),
+    anchorRunId: text("anchor_run_id")
+        .notNull()
+        .references(() => workflowRun.id, { onDelete: "cascade" }),
+    // References the run this approval belongs to, making "this approval is for
+    // a real run of this deployment" a database invariant. Cascades on the
+    // run's delete; the `anchor_run_id` FK above stays as the lock and cascade
+    // anchor the co-write orders against.
+    runId: text("run_id")
+        .notNull()
+        .references(() => workflowRun.id, { onDelete: "cascade" }),
+    agentAddress: text("agent_address").notNull(),
+    correlationId: text("correlation_id").notNull().unique(),
+    // Always populated: the ask rail is the sole co-writer and the register
+    // frame's required snapshot guarantees both fields at insert time.
+    toolDefinition: jsonb("tool_definition").notNull(),
+    toolArguments: jsonb("tool_arguments").notNull(),
+    scope: text("scope", { enum: ["once", "always"] }),
+    status: text("status", {
+        enum: ["pending", "approved", "rejected", "timeout", "expired"],
+    })
+        .notNull()
+        .default("pending"),
+    // Nullable so an approval that holds indefinitely can be recorded with no
+    // deadline. An agent-step suspend parks on its correlation's signal with no
+    // timeout (`parkOnSignal` is called without a `timeout`), so no `timeoutAt`
+    // reaches the sidecar frame that co-writes this row -- the deadline lives in
+    // the reactor's gate, which the hold-indefinitely suspend path never sets.
+    // A null `timeoutAt` is the hold-indefinitely case; a resolver that adds
+    // per-workflow expiry populates it when a deadline is configured. Parallels
+    // the tool-snapshot columns above, which are likewise deferred.
+    timeoutAt: timestamp("timeout_at"),
+    resolvedAt: timestamp("resolved_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (t) => [
+    index("approval_tenant_status_idx").on(t.tenantId, t.status, t.createdAt),
+    index("approval_anchor_run_idx").on(t.anchorRunId),
+]);