@intx/db 0.1.2 → 0.3.0

package/dist/credential-resolution.js

@@ -0,0 +1,255 @@
+import { eq, and, isNull } from "drizzle-orm";
+import { toolConsumer } from "@intx/authz";
+import { credentialAad } from "@intx/types";
+import { credential } from "./schema/credentials.js";
+import { oauthClient } from "./schema/oauth-clients.js";
+import { provider } from "./schema/providers.js";
+import { getAncestorChain } from "./tenant-hierarchy.js";
+/**
+ * Thrown by `resolveCredentialRequirement` when more than one credential
+ * matches a requirement and no name disambiguates them. A distinct type so
+ * callers can catch *this* condition (a launch-blocking configuration error)
+ * without also swallowing the DB reads the resolver performs first -- an
+ * infrastructure failure must surface, not be mislabeled as ambiguity.
+ */
+export class AmbiguousCredentialError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AmbiguousCredentialError";
+    }
+}
+/**
+ * Resolve a credential USABLE by the launching tenant purely through ownership:
+ * it exists, is reachable in the tenant's ancestor chain, and is tenant-owned
+ * (`principalId IS NULL`). Returns the row -- the proof of authority -- or null.
+ *
+ * This is the one "usable by ownership" resolver: a tenant may use what it (or
+ * an ancestor) owns, and descendants inherit; a principal-owned credential is
+ * never usable this way, its delegation flowing from its owner instead. It
+ * wraps `resolveCredentialById` (the ancestor-chain check) with the tenant-owned
+ * gate, so callers do not re-implement the predicate. `buildSource` expands it
+ * inline only to distinguish an unresolved reference from a principal-owned one.
+ */
+export async function resolveTenantOwnedCredentialById(db, tenantId, credentialId) {
+    const row = await resolveCredentialById(db, tenantId, credentialId);
+    return row !== null && row.principalId === null ? row : null;
+}
+/**
+ * Resolves a provider by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveProviderByName(db, tenantId, name) {
+    const chain = await getAncestorChain(db, tenantId);
+    for (const tid of chain) {
+        const row = await db.query.provider.findFirst({
+            where: and(eq(provider.tenantId, tid), eq(provider.name, name)),
+        });
+        if (row)
+            return row;
+    }
+    return null;
+}
+/**
+ * Resolves an OAuth client for a provider, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveOAuthClient(db, tenantId, providerId) {
+    const chain = await getAncestorChain(db, tenantId);
+    for (const tid of chain) {
+        const row = await db.query.oauthClient.findFirst({
+            where: and(eq(oauthClient.tenantId, tid), eq(oauthClient.providerId, providerId)),
+        });
+        if (row)
+            return row;
+    }
+    return null;
+}
+/**
+ * Resolves a credential by name, walking up the tenant hierarchy.
+ * Returns the first match (child shadows parent).
+ */
+export async function resolveCredentialByName(db, tenantId, name) {
+    const chain = await getAncestorChain(db, tenantId);
+    for (const tid of chain) {
+        const row = await db.query.credential.findFirst({
+            where: and(eq(credential.tenantId, tid), eq(credential.name, name)),
+        });
+        if (row)
+            return row;
+    }
+    return null;
+}
+/**
+ * Resolves a credential by ID, validating that it belongs to the
+ * given tenant or one of its ancestors.
+ */
+export async function resolveCredentialById(db, tenantId, credentialId) {
+    const row = await db.query.credential.findFirst({
+        where: eq(credential.id, credentialId),
+    });
+    if (!row)
+        return null;
+    const chain = await getAncestorChain(db, tenantId);
+    if (!chain.includes(row.tenantId))
+        return null;
+    return row;
+}
+/**
+ * Resolves a credential matching an agent definition requirement.
+ * Used at agent launch time by the control plane to satisfy a definition's
+ * tool and integration credentials (inference sources resolve through the
+ * catalog, not this path).
+ */
+export async function resolveCredentialRequirement(db, tenantId, requirement, creatorPrincipalId, invokerPrincipalId) {
+    const resolvedProvider = await resolveProviderByName(db, tenantId, requirement.providerName);
+    if (!resolvedProvider)
+        return null;
+    const chain = await getAncestorChain(db, tenantId);
+    const principalFilter = requirement.source === "tenant"
+        ? null
+        : requirement.source === "creator"
+            ? creatorPrincipalId
+            : invokerPrincipalId;
+    for (const tid of chain) {
+        const conditions = [
+            eq(credential.tenantId, tid),
+            eq(credential.providerId, resolvedProvider.id),
+            eq(credential.status, "active"),
+        ];
+        if (principalFilter === null) {
+            conditions.push(isNull(credential.principalId));
+        }
+        else if (principalFilter) {
+            conditions.push(eq(credential.principalId, principalFilter));
+        }
+        if (requirement.name) {
+            conditions.push(eq(credential.name, requirement.name));
+        }
+        const rows = await db.query.credential.findMany({
+            where: and(...conditions),
+        });
+        const matching = rows.filter((row) => {
+            if (!requirement.scopes || requirement.scopes.length === 0)
+                return true;
+            const rowScopes = row.scopes ?? [];
+            return requirement.scopes.every((s) => rowScopes.includes(s));
+        });
+        const [sole] = matching;
+        // Return the resolved provider alongside the credential. The provider was
+        // already fetched above to constrain the credential query, so surfacing it
+        // spares the caller a second lookup for the provider facts (plugin, base
+        // URL) a resolved credential is always paired with.
+        if (matching.length === 1 && sole) {
+            return { credential: sole, provider: resolvedProvider };
+        }
+        if (matching.length > 1) {
+            throw new AmbiguousCredentialError(`Ambiguous credential match: ${matching.length} credentials match ` +
+                `provider=${requirement.providerName} source=${requirement.source} ` +
+                `in tenant ${tid}. Specify a name to disambiguate.`);
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a definition's credential bindings into the material + per-handle
+ * descriptors delivered to its tools. Each credential's secret is decrypted
+ * once, keyed by credentialId (a credential backing several handles is
+ * decrypted once).
+ *
+ * This path delivers credential material only; it does not mint, stamp, or
+ * carry any grant. Credential-use authorization is enforced by a separate grant
+ * layer.
+ *
+ * The workflow-deploy path (`deployCodeSourcedWorkflow`) is the only caller
+ * today, using `delivery`. Returning a discriminated result rather than an HTTP
+ * response keeps it safe to call off the request path: a configuration failure
+ * is `ok: false`, and a transient DB read fault THROWS so the caller surfaces it
+ * rather than silently dropping a still-valid credential.
+ */
+export async function buildCredentialDelivery(args) {
+    const materials = new Map();
+    const descriptors = [];
+    for (const binding of args.bindings) {
+        const context = {
+            provider: binding.provider,
+            package: binding.package,
+            handle: binding.handle,
+        };
+        let resolved;
+        try {
+            resolved = await resolveCredentialRequirement(args.db, args.tenantId, {
+                providerName: binding.provider,
+                source: binding.locator,
+                ...(binding.name !== undefined ? { name: binding.name } : {}),
+            }, args.creatorPrincipalId, args.invokerPrincipalId);
+        }
+        catch (e) {
+            // AmbiguousCredentialError is a launch-blocking config failure; any other
+            // throw is a DB read fault the resolver performs first -- surface it, do
+            // not mislabel it as revocation.
+            if (!(e instanceof AmbiguousCredentialError))
+                throw e;
+            return {
+                ok: false,
+                reason: {
+                    code: "ambiguous",
+                    binding: context,
+                    message: `Ambiguous credential for the binding on provider ${binding.provider} (package ${binding.package}, handle ${binding.handle}): ${e.message}`,
+                },
+            };
+        }
+        if (resolved === null) {
+            return {
+                ok: false,
+                reason: {
+                    code: "unresolved",
+                    binding: context,
+                    message: `No credential resolves the binding for provider ${binding.provider} (package ${binding.package}, handle ${binding.handle})`,
+                },
+            };
+        }
+        // The credential is delivered as an origin-pinned http handle, so its
+        // provider must declare an API origin. A provider without one (OAuth-login
+        // only) cannot back a tool credential; fail closed rather than deliver an
+        // un-pinnable secret.
+        const providerOrigin = resolved.provider.apiBaseUrl;
+        if (providerOrigin === null || providerOrigin === "") {
+            return {
+                ok: false,
+                reason: {
+                    code: "no_origin",
+                    binding: context,
+                    message: `Provider ${binding.provider} has no API base URL; cannot deliver an origin-pinned credential (package ${binding.package}, handle ${binding.handle})`,
+                },
+            };
+        }
+        const credentialId = resolved.credential.id;
+        // A binding resolves only a tenant-owned credential (the `tenant` locator
+        // filters `principalId IS NULL` in resolveCredentialRequirement), so its use
+        // is authorized by ownership -- already proven by this walk-up resolution,
+        // not re-checked here. This path delivers credential material only; it does
+        // not mint or carry any grant. Credential-use authorization is enforced by a
+        // separate grant layer.
+        descriptors.push({
+            handle: binding.handle,
+            credentialId,
+            consumer: toolConsumer(binding.package),
+        });
+        if (!materials.has(credentialId)) {
+            // Decrypt at the single point of use. A decrypt failure propagates and
+            // fails the caller closed; there is no placeholder secret.
+            materials.set(credentialId, {
+                credentialId,
+                providerKey: resolved.provider.plugin,
+                origin: providerOrigin,
+                secret: await args.credentialCipher.decrypt(resolved.credential.secret, credentialAad(credentialId, "secret")),
+            });
+        }
+    }
+    return {
+        ok: true,
+        delivery: descriptors.length > 0
+            ? { bindings: descriptors, materials: [...materials.values()] }
+            : undefined,
+    };
+}

package/dist/grant-store.d.ts

@@ -0,0 +1,3 @@
+import type { GrantStore } from "@intx/types/authz";
+import type { DB } from "./client.js";
+export declare function createGrantStore(db: DB["db"]): GrantStore;

package/dist/grant-store.js

@@ -0,0 +1,59 @@
+import { eq, and, or, isNull, gt, inArray } from "drizzle-orm";
+import { grant } from "./schema/grants.js";
+import { principalRole } from "./schema/roles.js";
+import { parseGrantRow } from "./parse-row.js";
+import { getAncestorChain } from "./tenant-hierarchy.js";
+function toGrantRule(row) {
+    const parsed = parseGrantRow(row);
+    return {
+        id: parsed.id,
+        resource: parsed.resource,
+        action: parsed.action,
+        effect: parsed.effect,
+        origin: parsed.origin,
+        conditions: parsed.conditions,
+        expiresAt: parsed.expiresAt,
+        roleId: parsed.roleId,
+        principalId: parsed.principalId,
+    };
+}
+/**
+ * Collects a principal's live (non-expired) grants — the ones the principal
+ * owns directly plus the ones granted to any role it holds — restricted to
+ * the tenants matched by `tenantScope`. The scope is the sole knob that
+ * decides single-tenant versus chain-aware collection.
+ */
+async function collectGrantsScoped(db, principalId, tenantScope) {
+    const roleAssignments = await db.query.principalRole.findMany({
+        where: eq(principalRole.principalId, principalId),
+    });
+    const roleIds = roleAssignments.map((a) => a.roleId);
+    const now = new Date();
+    const ownership = [eq(grant.principalId, principalId)];
+    if (roleIds.length > 0) {
+        ownership.push(inArray(grant.roleId, roleIds));
+    }
+    const rows = await db.query.grant.findMany({
+        where: and(tenantScope, or(...ownership), or(isNull(grant.expiresAt), gt(grant.expiresAt, now))),
+    });
+    return rows.map(toGrantRule);
+}
+export function createGrantStore(db) {
+    return {
+        async collectGrants(principalId, tenantId) {
+            return collectGrantsScoped(db, principalId, eq(grant.tenantId, tenantId));
+        },
+        // Union the principal's grants across the tenant ancestor chain — the
+        // acting tenant plus every ancestor up to the root. Mirrors the
+        // ancestor-chain resolution credential lookup already performs, so a
+        // `credential:{id}` / `use` grant stamped with an ancestor tenant (as the
+        // mint path and 0037 backfill do) still authorizes use of a credential
+        // inherited down the chain. Kept distinct from the single-tenant
+        // `collectGrants` so only the source-resolution credential-use check
+        // widens to the chain; the general RBAC path stays single-tenant.
+        async collectGrantsInChain(principalId, tenantId) {
+            const chain = await getAncestorChain(db, tenantId);
+            return collectGrantsScoped(db, principalId, inArray(grant.tenantId, chain));
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { createDB, type DB, type DBExecutor } from "./client.js";
+export { pgErrorCode, PG_UNIQUE_VIOLATION, PG_FOREIGN_KEY_VIOLATION, } from "./pg-error.js";
+export type { DBConfig } from "./config.js";
+export { runMigrations, dropSchema } from "./migrate.js";
+export { rekeyCredentialSecrets, type RekeyReport, } from "./rekey-credential-secrets.js";
+export { createGrantStore } from "./grant-store.js";
+export { createApprovalStore, type ApprovalStore, type ResolveApprovalArgs, } from "./approval-store.js";
+export { createSignalCorrelationStore, type SignalCorrelationStore, } from "./signal-correlation-store.js";
+export { createWorkflowRunStore, type WorkflowRunStore, } from "./workflow-run-store.js";
+export { createWorkflowRunLaunchSpecStore, type WorkflowRunLaunchSpecStore, } from "./workflow-run-launch-spec-store.js";
+export { createWorkflowRunDispatchStore, WorkflowRunDispatchPayloadConflictError, type AcknowledgeWorkflowRunDispatchArgs, type ClaimWorkflowRunDispatchArgs, type EnqueueWorkflowRunDispatchArgs, type EnqueueWorkflowRunDispatchResult, type EnqueueWorkflowSignalDispatchArgs, type RetryWorkflowRunDispatchArgs, type WorkflowRunDispatchStore, } from "./workflow-run-dispatch-store.js";
+export { createSidecarAllocationStore, type BeginSidecarReleaseArgs, type BeginSidecarReplacementArgs, type BindInitialSidecarArgs, type BindReplacementSidecarArgs, type ClaimSidecarAllocationArgs, type CreatePendingSidecarAllocationArgs, type FailSidecarAllocationArgs, type MarkSidecarAllocatedArgs, type MarkSidecarConnectionLostArgs, type MarkSidecarConnectionReadyArgs, type MarkSidecarReleasedArgs, type ParkSidecarReconciliationPolicy, type ScheduleSidecarAllocationRetryArgs, type SidecarAllocation, type SidecarAllocationStore, } from "./sidecar-allocation-store.js";
+export { createWorkflowDefinitionStore, loadFrozenGrantSnapshot, resolveDefinitionIdForAsset, type WorkflowDefinitionRollbackResult, type WorkflowDefinitionSelector, } from "./workflow-definition-store.js";
+export { getAncestorChain, getDescendantTenants } from "./tenant-hierarchy.js";
+export { resolveActivePrice, type ModelPricingRow } from "./pricing.js";
+export { resolveProviderByName, resolveOAuthClient, resolveCredentialByName, resolveCredentialById, resolveCredentialRequirement, resolveTenantOwnedCredentialById, AmbiguousCredentialError, buildCredentialDelivery, } from "./credential-resolution.js";
+export type { BuildCredentialDeliveryResult, CredentialDeliveryFailure, } from "./credential-resolution.js";
+export { resolveAssetByName, resolveAssetById, listAssetsForTenant, type AssetRow, type AssetWithOrigin, } from "./asset-resolution.js";
+export { listVisibleModels, listVisibleProviders, listVisibleOfferings, type ModelRow, type ModelProviderRow, type ModelOfferingRow, type Origin, type VisibleModel, type VisibleProvider, type ResolvedOffering, } from "./catalog-resolution.js";
+export { resolveModelSources, resolveInferencePreferences, resolveInstanceModelSources, resolveSourcesByOfferingIds, type CatalogSourceResolution, type OfferingSourceResolution, type SourceSkip, } from "./model-source-resolution.js";
+export { parseGrantRow, parseApprovalRow, parsePrincipalRow, parseSignalCorrelationRow, parseWorkflowRunRow, parseWorkflowRunDispatchRow, parseWorkflowRunLaunchSpecRow, parseWorkflowDefinitionRow, parseWorkflowDefinitionVersionRow, parseOfferingRow, parseModelOfferingRow, parseCredentialRow, parseProviderRow, parseTenantRow, parseWalletRow, parseTransactionRow, parseOAuthClientRow, parseGitTokenRow, parseTurnPartType, } from "./parse-row.js";
+export * as schema from "./schema/index.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+export { createDB } from "./client.js";
+export { pgErrorCode, PG_UNIQUE_VIOLATION, PG_FOREIGN_KEY_VIOLATION, } from "./pg-error.js";
+export { runMigrations, dropSchema } from "./migrate.js";
+export { rekeyCredentialSecrets, } from "./rekey-credential-secrets.js";
+export { createGrantStore } from "./grant-store.js";
+export { createApprovalStore, } from "./approval-store.js";
+export { createSignalCorrelationStore, } from "./signal-correlation-store.js";
+export { createWorkflowRunStore, } from "./workflow-run-store.js";
+export { createWorkflowRunLaunchSpecStore, } from "./workflow-run-launch-spec-store.js";
+export { createWorkflowRunDispatchStore, WorkflowRunDispatchPayloadConflictError, } from "./workflow-run-dispatch-store.js";
+export { createSidecarAllocationStore, } from "./sidecar-allocation-store.js";
+export { createWorkflowDefinitionStore, loadFrozenGrantSnapshot, resolveDefinitionIdForAsset, } from "./workflow-definition-store.js";
+export { getAncestorChain, getDescendantTenants } from "./tenant-hierarchy.js";
+export { resolveActivePrice } from "./pricing.js";
+export { resolveProviderByName, resolveOAuthClient, resolveCredentialByName, resolveCredentialById, resolveCredentialRequirement, resolveTenantOwnedCredentialById, AmbiguousCredentialError, buildCredentialDelivery, } from "./credential-resolution.js";
+export { resolveAssetByName, resolveAssetById, listAssetsForTenant, } from "./asset-resolution.js";
+export { listVisibleModels, listVisibleProviders, listVisibleOfferings, } from "./catalog-resolution.js";
+export { resolveModelSources, resolveInferencePreferences, resolveInstanceModelSources, resolveSourcesByOfferingIds, } from "./model-source-resolution.js";
+export { parseGrantRow, parseApprovalRow, parsePrincipalRow, parseSignalCorrelationRow, parseWorkflowRunRow, parseWorkflowRunDispatchRow, parseWorkflowRunLaunchSpecRow, parseWorkflowDefinitionRow, parseWorkflowDefinitionVersionRow, parseOfferingRow, parseModelOfferingRow, parseCredentialRow, parseProviderRow, parseTenantRow, parseWalletRow, parseTransactionRow, parseOAuthClientRow, parseGitTokenRow, parseTurnPartType, } from "./parse-row.js";
+export * as schema from "./schema/index.js";

package/dist/migrate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Rewrite drizzle-generated schema-qualified references like
+ * `REFERENCES "public"."<table>"` so they point at the target
+ * schema. The pattern matches `"public".` only when followed by
+ * another quoted identifier, leaving bare `"public"` inside string
+ * literals alone.
+ */
+export declare function rewriteSchemaQualifiedReferences(sql: string, schemaIdent: string): string;
+/**
+ * Apply the drizzle-generated migration SQL into the given postgres
+ * schema. The schema is created if absent; nothing else is dropped.
+ *
+ * The migration source files reference the destination schema
+ * literally (e.g. `"public"."user"` in FK constraints). To make the
+ * same source apply cleanly into an arbitrary schema, we substitute
+ * the literal token `"public"` with the quoted target schema before
+ * executing each file. This is a textual substitution rather than a
+ * postgres-side `search_path` trick because the FK references are
+ * fully qualified; `search_path` would not redirect them.
+ *
+ * The substitution is bounded: the migration source is
+ * machine-generated and never contains the string `"public"` other
+ * than in schema-qualified identifiers, so there is no ambiguity to
+ * worry about. The substitution is a no-op when the target schema is
+ * literally `public`, which is the common case.
+ */
+export declare function runMigrations(configRaw: unknown, options: {
+    schema: string;
+}): Promise<void>;
+/**
+ * Drop the given schema along with everything in it. Used by the
+ * integration-test harness to tear down per-test schemas.
+ */
+export declare function dropSchema(configRaw: unknown, options: {
+    schema: string;
+}): Promise<void>;

package/dist/migrate.js

@@ -0,0 +1,135 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { type } from "arktype";
+import postgres from "postgres";
+import { DBConfig } from "./config.js";
+// Resolution of the migrations directory: the package layout pins
+// the drizzle-generated SQL at `<pkgRoot>/migrations`. This file
+// lives at `<pkgRoot>/src/migrate.ts`, so the directory is one level
+// up from `__dirname`. Resolving via `import.meta` keeps the runtime
+// honest about where it is reading SQL from instead of relying on a
+// cwd-relative path that breaks under callers that change `cwd`.
+const MIGRATIONS_DIR = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "migrations");
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/**
+ * Rewrite drizzle-generated schema-qualified references like
+ * `REFERENCES "public"."<table>"` so they point at the target
+ * schema. The pattern matches `"public".` only when followed by
+ * another quoted identifier, leaving bare `"public"` inside string
+ * literals alone.
+ */
+export function rewriteSchemaQualifiedReferences(sql, schemaIdent) {
+    return sql.replace(/"public"\.(?=")/g, `${schemaIdent}.`);
+}
+/**
+ * Construct the single-connection postgres client used by the
+ * migration and teardown entry points. Both paths share the same SSL
+ * passthrough and suppress NOTICE-level diagnostics (cascade reports,
+ * "schema already exists") that postgres.js logs by default but are
+ * informational only in this harness context. The optional `searchPath`
+ * pins `search_path` on connection-open so unqualified `CREATE TABLE`
+ * statements land in the caller's schema.
+ */
+function createMigrationClient(config, searchPath) {
+    return postgres({
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password,
+        database: config.database,
+        max: 1,
+        onnotice: () => undefined,
+        ...(config.ssl !== undefined && { ssl: config.ssl }),
+        ...(searchPath !== undefined && {
+            connection: { search_path: searchPath },
+        }),
+    });
+}
+/**
+ * Apply the drizzle-generated migration SQL into the given postgres
+ * schema. The schema is created if absent; nothing else is dropped.
+ *
+ * The migration source files reference the destination schema
+ * literally (e.g. `"public"."user"` in FK constraints). To make the
+ * same source apply cleanly into an arbitrary schema, we substitute
+ * the literal token `"public"` with the quoted target schema before
+ * executing each file. This is a textual substitution rather than a
+ * postgres-side `search_path` trick because the FK references are
+ * fully qualified; `search_path` would not redirect them.
+ *
+ * The substitution is bounded: the migration source is
+ * machine-generated and never contains the string `"public"` other
+ * than in schema-qualified identifiers, so there is no ambiguity to
+ * worry about. The substitution is a no-op when the target schema is
+ * literally `public`, which is the common case.
+ */
+export async function runMigrations(configRaw, options) {
+    const config = DBConfig(configRaw);
+    if (config instanceof type.errors) {
+        throw new Error(`Invalid database config: ${config.summary}`);
+    }
+    const { schema } = options;
+    if (schema.length === 0) {
+        throw new Error("runMigrations: schema name must not be empty");
+    }
+    const schemaIdent = quoteIdentifier(schema);
+    // Pin search_path on the migration connection so unqualified
+    // `CREATE TABLE "name"` statements land in the target schema.
+    // The FK references in the source SQL are already schema-qualified
+    // (`"public"."user"`); we rewrite those to the target schema
+    // below. Together these two mechanisms route every object the
+    // migration touches into the caller's schema.
+    const sql = createMigrationClient(config, schemaIdent);
+    try {
+        // The CREATE SCHEMA must run on a connection that does not
+        // require the schema to already exist for search_path to be
+        // applied. postgres.js sets the GUC after connection-open, so
+        // CREATE SCHEMA IF NOT EXISTS here is the first statement and
+        // creates the schema before search_path matters.
+        await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS ${schemaIdent}`);
+        const files = (await readdir(MIGRATIONS_DIR))
+            .filter((f) => f.endsWith(".sql"))
+            .sort();
+        if (files.length === 0) {
+            throw new Error(`runMigrations: no .sql files found in ${MIGRATIONS_DIR}`);
+        }
+        for (const file of files) {
+            const raw = await readFile(path.join(MIGRATIONS_DIR, file), "utf-8");
+            const rendered = rewriteSchemaQualifiedReferences(raw, schemaIdent);
+            // drizzle emits multi-statement files separated by its own
+            // statement-breakpoint marker. Split on it and execute each
+            // statement individually so a syntax error in one statement
+            // surfaces with the right context.
+            const statements = rendered
+                .split("--> statement-breakpoint")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            for (const stmt of statements) {
+                await sql.unsafe(stmt);
+            }
+        }
+    }
+    finally {
+        await sql.end();
+    }
+}
+/**
+ * Drop the given schema along with everything in it. Used by the
+ * integration-test harness to tear down per-test schemas.
+ */
+export async function dropSchema(configRaw, options) {
+    const config = DBConfig(configRaw);
+    if (config instanceof type.errors) {
+        throw new Error(`Invalid database config: ${config.summary}`);
+    }
+    const sql = createMigrationClient(config);
+    try {
+        const schemaIdent = quoteIdentifier(options.schema);
+        await sql.unsafe(`DROP SCHEMA IF EXISTS ${schemaIdent} CASCADE`);
+    }
+    finally {
+        await sql.end();
+    }
+}

package/dist/model-source-resolution.d.ts

@@ -0,0 +1,115 @@
+import { type CredentialCipher, type ModelRequirement, type ProviderPreference } from "@intx/types";
+import type { InferenceSource } from "@intx/types/runtime";
+import type { DB } from "./client.js";
+/**
+ * Why a single offering could not be turned into a launchable source.
+ * `wallet_backed` providers are storable in the catalog but not launchable
+ * in this credential-backed-only release.
+ */
+export type SourceSkip = {
+    reason: "wallet_backed";
+    provider: string;
+} | {
+    reason: "credential_unresolved";
+    provider: string;
+} | {
+    reason: "credential_unauthorized";
+    provider: string;
+} | {
+    reason: "provider_misconfigured";
+    provider: string;
+};
+/**
+ * Outcome of resolving an agent's model requirements to an ordered set of
+ * inference sources. The order is the routing order: the head is the
+ * default, the tail is the failover chain.
+ *
+ * `model_unavailable.skips` enumerates the offerings that were eligible for
+ * the model but could not produce a launchable source (wallet-backed, or an
+ * unresolvable credential). It is empty when no offering was eligible at all
+ * — the model is absent from the tenant catalog, or the capability and
+ * preference filters excluded every offering — a case the launch path can
+ * distinguish from a populated `skips` when explaining the failure.
+ */
+export type CatalogSourceResolution = {
+    ok: true;
+    sources: InferenceSource[];
+} | {
+    ok: false;
+    reason: "no_requirements";
+} | {
+    ok: false;
+    reason: "model_unavailable";
+    model: string;
+    skips: SourceSkip[];
+};
+export type OfferingSourceResolution = {
+    ok: true;
+    sources: InferenceSource[];
+} | {
+    ok: false;
+    reason: "offering_unavailable";
+    offeringId: string;
+    skip?: SourceSkip;
+};
+/**
+ * Rebuild an exact, ordered source chain from durable catalog offering ids.
+ * This is the recovery counterpart to launch-time source selection: it keeps
+ * secrets out of persisted launch specs and rechecks tenant visibility and
+ * credential ownership on every launch.
+ */
+export declare function resolveSourcesByOfferingIds(db: DB["db"], tenantId: string, offeringIds: readonly string[], credentialCipher?: CredentialCipher): Promise<OfferingSourceResolution>;
+/**
+ * Resolves an agent's model requirements against the tenant catalog into an
+ * ordered `InferenceSource[]` for the harness.
+ *
+ * For each requirement, the tenant-visible offerings for the named model are
+ * filtered by the required capabilities, ordered by catalog priority, then
+ * reordered by the creator preference and finally the invoker preference
+ * (invoker preferences key on the canonical model name). Each surviving
+ * offering is resolved to a credential-backed source; offerings that cannot
+ * produce one are skipped. A required model that yields no source makes the
+ * agent unlaunchable.
+ *
+ * A credential-backed source is emitted only when the launching tenant owns
+ * the referenced credential within its hierarchy (ownership is the authority);
+ * otherwise the offering is skipped (`credential_unauthorized`) and its secret
+ * is withheld.
+ */
+export declare function resolveModelSources(db: DB["db"], tenantId: string, requirements: ModelRequirement[], opts?: {
+    invokerPreferences?: Record<string, ProviderPreference>;
+    credentialCipher?: CredentialCipher;
+}): Promise<CatalogSourceResolution>;
+/**
+ * Resolve an agent's model requirements to the credential-free
+ * `{ provider, model }` inference preferences a folded workflow definition
+ * carries on its step agent. Reuses `resolveModelSources` -- the same catalog
+ * + creator-grant resolution the instance launch path runs -- and projects its
+ * ordered sources to their `{ provider (plugin), model }` identity, dropping
+ * the credentials: a definition's inference preference is hash-only, and the
+ * credential-bearing sources are supplied per deploy on the workflow path.
+ *
+ * A requirement set that resolves to no source is a hard failure. A folded
+ * agent whose model is unresolvable is undeployable, so this raises rather
+ * than synthesizing an empty preference list that would silently strip the
+ * agent's inference. It also raises when the resolved sources are not
+ * injective on `(provider, model)` -- the projection would otherwise freeze
+ * an ambiguous preference list whose lost `offering.id` distinctions cannot be
+ * recovered after the agent's columns are dropped.
+ */
+export declare function resolveInferencePreferences(db: DB["db"], tenantId: string, requirements: ModelRequirement[]): Promise<{
+    provider: string;
+    model: string;
+}[]>;
+/**
+ * Resolves the ordered sources for a running instance from persisted state:
+ * the definition's model requirements and the invoker's launch-time
+ * preferences stored on the instance row. The credential-rotation and
+ * catalog-edit source push resolves through this, so a running instance's
+ * source list is a pure function of persisted state — re-resolution
+ * reproduces the launch ordering, including the invoker's reorder/restrict.
+ */
+export declare function resolveInstanceModelSources(db: DB["db"], tenantId: string, instance: {
+    definitionId: string;
+    modelPreferences: unknown;
+}, credentialCipher?: CredentialCipher): Promise<CatalogSourceResolution>;