@intx/hub-sessions 0.1.2 → 0.3.0

package/dist/skill-kind.d.ts

@@ -0,0 +1,41 @@
+import { type AuthorizeFn, type KindHandler } from "./repo-store/index.js";
+export type SkillHubPrincipal = {
+    readonly kind: "hub";
+};
+export type SkillSidecarPrincipal = {
+    readonly kind: "sidecar";
+    readonly agentId: string;
+};
+export type SkillPrincipal = SkillHubPrincipal | SkillSidecarPrincipal;
+/**
+ * arktype schema for the SKILL.md frontmatter. Required fields are
+ * `name` and `description`; the Claude Code superset of optional fields
+ * (`when_to_use`, `allowed-tools`, `paths`, `model`, ...) is accepted
+ * via `onUndeclaredKey("ignore")` but not enforced.
+ *
+ * The forbidden-name narrow rejects `"anthropic"` and `"claude"`
+ * because those values are reserved by the upstream agentskills.io
+ * spec for vendor-owned skill packs.
+ */
+export declare const skillFrontmatterSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    name: string;
+    description: string;
+}, {}>;
+export type SkillFrontmatter = typeof skillFrontmatterSchema.infer;
+export type SkillIndexEntry = {
+    /** Equal to the containing directory name and to `frontmatter.name`. */
+    name: string;
+    description: string;
+    /** Full parsed frontmatter, including any accepted optional fields. */
+    frontmatter: Record<string, unknown>;
+    /** Path of the skill subdirectory relative to the asset mount, with trailing slash. */
+    workspaceSubpath: string;
+};
+/**
+ * Returns the parsed skill index for `(assetId, ref)`, or an empty
+ * array if no index has been populated yet. The index is refreshed by
+ * the kind handler's `onRefUpdated` hook after each successful write.
+ */
+export declare function getSkillIndex(assetId: string, ref: string): SkillIndexEntry[];
+export declare const skillKindHandler: KindHandler;
+export declare const skillAuthorize: AuthorizeFn;

package/dist/skill-kind.js

@@ -0,0 +1,292 @@
+import { type } from "arktype";
+import { getLogger } from "@intx/log";
+import { glob, repoActionToGrantVerb } from "@intx/hub-common";
+import { UserPrincipal, } from "./repo-store/index.js";
+const logger = getLogger(["hub-sessions", "skill-kind"]);
+/**
+ * arktype schema for the SKILL.md frontmatter. Required fields are
+ * `name` and `description`; the Claude Code superset of optional fields
+ * (`when_to_use`, `allowed-tools`, `paths`, `model`, ...) is accepted
+ * via `onUndeclaredKey("ignore")` but not enforced.
+ *
+ * The forbidden-name narrow rejects `"anthropic"` and `"claude"`
+ * because those values are reserved by the upstream agentskills.io
+ * spec for vendor-owned skill packs.
+ */
+export const skillFrontmatterSchema = type({
+    name: type(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+        .and("string<=64")
+        .narrow((n, ctx) => {
+        if (n === "anthropic" || n === "claude") {
+            return ctx.mustBe(`not the reserved name "anthropic" or "claude"`);
+        }
+        return true;
+    }),
+    description: type("1 <= string <= 1024").and(type(/^(?!.*<[^>]+>).*$/s)),
+}).onUndeclaredKey("ignore");
+function cacheKey(assetId, ref) {
+    return `${assetId}\u0000${ref}`;
+}
+const skillIndex = new Map();
+const pendingIndex = new Map();
+/**
+ * Returns the parsed skill index for `(assetId, ref)`, or an empty
+ * array if no index has been populated yet. The index is refreshed by
+ * the kind handler's `onRefUpdated` hook after each successful write.
+ */
+export function getSkillIndex(assetId, ref) {
+    return skillIndex.get(cacheKey(assetId, ref)) ?? [];
+}
+const FRONTMATTER_DELIMITER = "---";
+const YamlMapping = type("Record<string, unknown>");
+function parseSkillMd(body) {
+    const lines = body.split(/\r?\n/);
+    if (lines[0] !== FRONTMATTER_DELIMITER) {
+        throw new Error("SKILL.md is missing YAML frontmatter delimiter");
+    }
+    let endIdx = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i] === FRONTMATTER_DELIMITER) {
+            endIdx = i;
+            break;
+        }
+    }
+    if (endIdx === -1) {
+        throw new Error("SKILL.md frontmatter has no closing delimiter");
+    }
+    const yamlText = lines.slice(1, endIdx).join("\n");
+    const parsed = Bun.YAML.parse(yamlText);
+    const validated = YamlMapping(parsed);
+    if (validated instanceof type.errors) {
+        throw new Error(`SKILL.md frontmatter must be a YAML mapping: ${validated.summary}`);
+    }
+    return { frontmatter: validated };
+}
+async function parseSkillEntry(subdir, readBlob) {
+    const skillPath = `${subdir}/SKILL.md`;
+    let raw;
+    try {
+        raw = await readBlob(skillPath);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} is missing SKILL.md: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    const body = new TextDecoder().decode(raw);
+    let parsed;
+    try {
+        parsed = parseSkillMd(body);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} frontmatter parse failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    const result = skillFrontmatterSchema(parsed.frontmatter);
+    if (result instanceof type.errors) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} frontmatter is invalid: ${result.summary}`,
+        };
+    }
+    if (result.name !== subdir) {
+        return {
+            ok: false,
+            reason: `skill ${subdir} frontmatter.name ${JSON.stringify(result.name)} does not match directory name`,
+        };
+    }
+    return {
+        ok: true,
+        entry: {
+            name: result.name,
+            description: result.description,
+            frontmatter: parsed.frontmatter,
+            workspaceSubpath: `${subdir}/`,
+        },
+    };
+}
+async function buildSkillIndex(topLevelTreePaths, readBlob, listDir) {
+    const entries = [];
+    // Sort so the index ordering is deterministic across reads.
+    const candidates = [...topLevelTreePaths].sort();
+    for (const candidate of candidates) {
+        // Skill subdirectories are arbitrarily named (`<skill-name>/`), so
+        // there is no enumerable allowlist of names the way the workflow,
+        // package-registry, and agent-state handlers use. The structural
+        // distinction is tree-vs-blob: a top-level tree entry is a skill
+        // subdir, a top-level blob (e.g. `.gitignore` seeded by the
+        // genesis init) is not.
+        //
+        // Probe via `listDir`. The substrate's two implementations
+        // disagree on the not-a-tree signal — the receivePack closures
+        // throw, the writeTree closures return an empty array — so this
+        // probe accepts either signal as "not a directory" and skips the
+        // entry. Git does not store empty trees, so an empty `listDir`
+        // result is equivalent to "this name is not a directory in the
+        // prospective tree".
+        let children;
+        try {
+            children = await listDir(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (children.length === 0)
+            continue;
+        const outcome = await parseSkillEntry(candidate, readBlob);
+        if (!outcome.ok) {
+            return { ok: false, reason: outcome.reason };
+        }
+        entries.push(outcome.entry);
+    }
+    return { ok: true, entries };
+}
+export const skillKindHandler = {
+    kind: "skill",
+    directoryPrefix: "assets/skill",
+    async validatePush({ repoId, ref, topLevelTreePaths, readBlob, listDir, }) {
+        // Drop any staged entry from a previous attempt first. The
+        // substrate calls validatePush before advancing the ref, so a prior
+        // validation that was accepted but never followed by onRefUpdated
+        // (e.g. the commit step threw after validation succeeded) would
+        // otherwise leave a stale entry that a later rejected attempt
+        // would silently inherit.
+        const key = cacheKey(repoId.id, ref);
+        pendingIndex.delete(key);
+        const result = await buildSkillIndex(topLevelTreePaths, readBlob, listDir);
+        if (!result.ok) {
+            logger.debug `skill validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${result.reason}`;
+            return { ok: false, reason: result.reason };
+        }
+        // Stage the parsed index against (repoId.id, ref). The substrate
+        // calls onRefUpdated immediately after the ref is advanced and we
+        // promote the staged entry into the live cache there.
+        pendingIndex.set(key, result.entries);
+        return { ok: true };
+    },
+    onRefUpdated({ repoId, ref }) {
+        const key = cacheKey(repoId.id, ref);
+        const staged = pendingIndex.get(key);
+        if (staged === undefined) {
+            throw new Error(`skillKindHandler.onRefUpdated: no validated tree pending for ${repoId.id} @ ${ref}`);
+        }
+        pendingIndex.delete(key);
+        skillIndex.set(key, staged);
+    },
+};
+const SidecarPrincipal = type({
+    kind: "'sidecar'",
+    agentId: "string",
+});
+export const skillAuthorize = (principal, repoId, ref, action) => {
+    if (repoId.kind !== "skill") {
+        return {
+            allowed: false,
+            reason: `skill authorize received non-skill repo ${repoId.kind}/${repoId.id}`,
+        };
+    }
+    if (principal.kind === "hub") {
+        return { allowed: true };
+    }
+    if (principal.kind === "sidecar") {
+        const parsed = SidecarPrincipal(principal);
+        if (parsed instanceof type.errors) {
+            return {
+                allowed: false,
+                reason: `sidecar principal is malformed: ${parsed.summary}`,
+            };
+        }
+        switch (action) {
+            case "createPack":
+            case "resolveRef":
+                return { allowed: true };
+            case "init":
+            case "writeTree":
+            case "receivePack":
+                return {
+                    allowed: false,
+                    reason: `sidecars may only read skill assets, not ${action}`,
+                };
+            default: {
+                const _exhaustive = action;
+                return {
+                    allowed: false,
+                    reason: `unhandled action: ${String(_exhaustive)}`,
+                };
+            }
+        }
+    }
+    if (principal.kind === "user") {
+        // The route layer has already pre-resolved the grant verdict and
+        // attached it as `authz`. The substrate does NOT re-query the
+        // grant store here; it (a) checks the bearer-token's claims
+        // bound the requested (ref, action) and have not expired, and
+        // (b) sanity-checks that the pre-resolved verdict targets this
+        // exact resource and grant verb. Both gates must pass before the
+        // verdict's `effect` is honoured.
+        const parsed = UserPrincipal(principal);
+        if (parsed instanceof type.errors) {
+            return {
+                allowed: false,
+                reason: `user principal is malformed: ${parsed.summary}`,
+            };
+        }
+        if (!parsed.tokenClaims.actions.includes(action)) {
+            return {
+                allowed: false,
+                reason: `token does not grant action ${action}`,
+            };
+        }
+        // `ref === "*"` is the substrate's sentinel for a bulk read used
+        // by `listRefs`. The advertise-refs layer applies the per-ref
+        // refPattern filter on the listing it returns, so gating the bulk
+        // read on refPattern here would prevent any token with a
+        // narrow-pattern (e.g. `refs/heads/main`) from listing refs at
+        // all. Only the action and expiry are enforced for the bulk read;
+        // every other call site passes a concrete ref and is gated below.
+        if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
+            return {
+                allowed: false,
+                reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
+            };
+        }
+        if (Date.now() >= parsed.tokenClaims.expiresAt) {
+            return {
+                allowed: false,
+                reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
+            };
+        }
+        const expectedResource = `asset:${repoId.id}`;
+        if (parsed.authz.resource !== expectedResource) {
+            return {
+                allowed: false,
+                reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
+            };
+        }
+        const expectedGrantVerb = repoActionToGrantVerb(action);
+        if (parsed.authz.grantVerb !== expectedGrantVerb) {
+            return {
+                allowed: false,
+                reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
+            };
+        }
+        if (parsed.authz.effect === "allow") {
+            return { allowed: true };
+        }
+        return {
+            allowed: false,
+            reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
+        };
+    }
+    // Fail closed on any kind not handled above. The tenant-level
+    // `workflow` principal kind (`@intx/types` principalKinds) is a
+    // grant owner, not a skill bearer, and never carries a skill repo
+    // push here -- so it is intentionally left denied.
+    return {
+        allowed: false,
+        reason: `unknown principal kind: ${principal.kind}`,
+    };
+};

package/dist/substrate.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_CONSUMED_RETENTION_MS, dequeueToProcessing, enqueueInbox, markConsumed, parseEventSeq, readOwnedMessageIds, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, readProcessingEntry, replayProcessingToInbox, requireEventSeq, StaleInboxEnqueueError, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+export type { WorkflowRunSupervisorPrincipal, WorkflowRunWorkflowProcessPrincipal, DequeueToProcessingResult, EnqueueAlreadyPresentReason, EnqueueInboxArgs, EnqueueInboxOutcome, EnqueueInboxResult, MarkConsumedArgs, MarkConsumedResult, WorkflowRunLifecycle, ReplayProcessingToInboxOpts, ReplayProcessingToInboxResult, } from "./workflow-run-kind.js";
+export { encodeCombinedEventLog, splitCombinedEventLog, WORKFLOW_RUN_EVENTS_FILE, } from "./workflow-run-event-log.js";
+export { workflowDefinitionEnvelopeSchema } from "./workflow-kind.js";
+export { subscribeKind } from "./repo-store/subscribe-kind.js";
+export type { SubscribeKindEntry } from "./repo-store/subscribe-kind.js";
+export { createAgentRepoStore } from "./agent-repo.js";
+export type { CommittedReads, CommittedTreeEntry, Principal, RepoId, RepoStore, WriteResult, InitRepoOpts, NewlyTerminalRun, } from "./repo-store/types.js";

package/dist/substrate.js

@@ -0,0 +1,21 @@
+// The db-free substrate layer of this package.
+//
+// `@intx/hub-sessions` holds two layers: the git-backed repo-store substrate
+// (the `RepoStore`, the workflow-run claim-check and event-log primitives, the
+// kind-handler protocol) and the db-backed control-plane services (sessions,
+// credential push, the websocket layer). The substrate layer never imports
+// `@intx/db`; the services layer does. The package barrel (`index.ts`)
+// re-exports both, so importing any symbol through it pulls drizzle and the
+// rest of the hub data layer into module-evaluation.
+//
+// This entry exposes only the substrate layer, so any consumer that needs
+// repo/substrate access without the control-plane services -- for example a
+// process that reads and writes the agent-state and workflow-run repos but
+// runs nowhere near a database -- can import it without dragging `@intx/db`
+// into its boot graph. Every symbol re-exported here is defined in a db-free
+// module. The barrel still re-exports all of these for hub-side consumers.
+export { DEFAULT_CONSUMED_RETENTION_MS, dequeueToProcessing, enqueueInbox, markConsumed, parseEventSeq, readOwnedMessageIds, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, readProcessingEntry, replayProcessingToInbox, requireEventSeq, StaleInboxEnqueueError, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+export { encodeCombinedEventLog, splitCombinedEventLog, WORKFLOW_RUN_EVENTS_FILE, } from "./workflow-run-event-log.js";
+export { workflowDefinitionEnvelopeSchema } from "./workflow-kind.js";
+export { subscribeKind } from "./repo-store/subscribe-kind.js";
+export { createAgentRepoStore } from "./agent-repo.js";

package/dist/workflow-allocation-service.d.ts

@@ -0,0 +1,58 @@
+import { type DB, type SidecarAllocation } from "@intx/db";
+import { type CredentialCipher, type SidecarPlacementRequirement } from "@intx/types";
+import type { ToolPackagePin } from "@intx/types/tool-packages";
+import type { WorkflowDefinitionSource } from "@intx/types/workflow-sources";
+import type { DeployContent } from "./agent-repo.js";
+import { type SidecarPluginRegistry } from "./sidecar-allocation/index.js";
+import { type DeployWorkflowDefinitionResult, type PreparedWorkflowDeployer } from "./session-service.js";
+import type { SidecarAllocationRouter } from "./ws/sidecar-handler.js";
+export declare class ExclusiveWorkflowPlacementError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type PrepareExclusiveWorkflowDeploymentArgs = {
+    readonly tenantId: string;
+    readonly anchorRunId: string;
+    readonly deploymentDomain: string;
+    /** Where the definition's bytes come from at probe time. */
+    readonly source: WorkflowDefinitionSource;
+    /** The `interchange.workflow` entry-module path the sidecar evaluates. */
+    readonly entry: string;
+    /**
+     * A `name@range` spec for the definition package. REQUIRED for the `registry`
+     * and asset-`tarball` variants; omitted for the asset-`source` variant.
+     */
+    readonly pin?: string;
+    readonly definitionAssetId: string;
+    readonly placement: SidecarPlacementRequirement & {
+        readonly sharing: "exclusive";
+    };
+    readonly sessionId: string;
+    readonly sourceAuthorityPrincipalId: string;
+    readonly sourceOfferingIds: readonly string[];
+    readonly defaultSourceOfferingId: string;
+    readonly deployContent: DeployContent;
+    readonly toolPackagePins?: readonly ToolPackagePin[];
+};
+export type PreparedExclusiveWorkflowDeployment = {
+    readonly anchorRunId: string;
+    readonly deploymentAddress: string;
+    readonly allocationId: string;
+    readonly status: "pending";
+};
+export type WorkflowAllocationService = {
+    prepareExclusiveDeployment(args: PrepareExclusiveWorkflowDeploymentArgs): Promise<PreparedExclusiveWorkflowDeployment>;
+    deployReadyAllocation(allocation: SidecarAllocation): Promise<DeployWorkflowDefinitionResult | null>;
+};
+export type WorkflowAllocationServiceDeps = {
+    readonly db: DB["db"];
+    readonly plugins: SidecarPluginRegistry;
+    readonly preparedDeployer: PreparedWorkflowDeployer;
+    readonly credentialCipher?: CredentialCipher;
+    readonly allocationRouter: Pick<SidecarAllocationRouter, "isAllocatedWorkflowActive">;
+    readonly createAllocationId?: () => string;
+    readonly now?: () => Date;
+};
+/** Resolve the tenant-inherited sidecar placement into one launch decision. */
+export declare function resolveWorkflowSidecarPlacement(db: DB["db"], tenantId: string): Promise<SidecarPlacementRequirement | null>;
+export declare function createWorkflowAllocationService({ db, plugins, preparedDeployer, credentialCipher, allocationRouter, createAllocationId, now, }: WorkflowAllocationServiceDeps): WorkflowAllocationService;

package/dist/workflow-allocation-service.js

@@ -0,0 +1,239 @@
+import { createSidecarAllocationStore, createWorkflowRunLaunchSpecStore, getAncestorChain, resolveSourcesByOfferingIds, } from "@intx/db";
+import { grant, tenant as tenantTable, workflowRun } from "@intx/db/schema";
+import { eq, inArray } from "drizzle-orm";
+import { generateId } from "@intx/hub-common";
+import { hexEncode, TenantConfig, } from "@intx/types";
+import { deriveRunAddress, deriveRunAgentId } from "@intx/workflow-deploy";
+import { resolveEffectiveSidecarPlacement, } from "./sidecar-allocation/index.js";
+import { SessionLaunchError, } from "./session-service.js";
+export class ExclusiveWorkflowPlacementError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ExclusiveWorkflowPlacementError";
+        this.code = code;
+    }
+}
+function randomAllocationId() {
+    return `sal_${hexEncode(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+/** Resolve the tenant-inherited sidecar placement into one launch decision. */
+export async function resolveWorkflowSidecarPlacement(db, tenantId) {
+    const tenantIds = await getAncestorChain(db, tenantId);
+    const rows = await db.query.tenant.findMany({
+        where: inArray(tenantTable.id, tenantIds),
+        columns: { id: true, config: true },
+    });
+    const configsByTenantId = new Map(rows.map((row) => [
+        row.id,
+        row.config === null
+            ? TenantConfig.assert({})
+            : TenantConfig.assert(row.config),
+    ]));
+    const tenantConfigs = tenantIds.map((id) => {
+        const config = configsByTenantId.get(id);
+        if (config === undefined) {
+            throw new Error(`Tenant ${id} disappeared while resolving sidecar placement`);
+        }
+        return config;
+    });
+    return resolveEffectiveSidecarPlacement({ tenantConfigs });
+}
+export function createWorkflowAllocationService({ db, plugins, preparedDeployer, credentialCipher, allocationRouter, createAllocationId = randomAllocationId, now = () => new Date(), }) {
+    const allocationStore = createSidecarAllocationStore(db);
+    const launchSpecStore = createWorkflowRunLaunchSpecStore(db);
+    async function prepareExclusiveDeployment(args) {
+        // Fail closed before any probe: exclusive placement has no meaning without a
+        // provisioner to stand up its dedicated sidecar, and the shared-capacity
+        // probe below is wasted work if no provisioner exists. (In-tree this is
+        // always null -- exclusive is dormant -- so a live prepare never runs here.)
+        const provisioner = plugins.getDefaultProvisioner();
+        if (provisioner === null) {
+            throw new ExclusiveWorkflowPlacementError("exclusive_provisioner_unavailable", "No default sidecar provisioner is configured for exclusive workflows");
+        }
+        if (args.sourceOfferingIds.length === 0) {
+            throw new ExclusiveWorkflowPlacementError("invalid_source_offerings", "Exclusive workflow deployment requires at least one catalog offering");
+        }
+        if (!args.sourceOfferingIds.includes(args.defaultSourceOfferingId)) {
+            throw new ExclusiveWorkflowPlacementError("invalid_source_offerings", "The default source offering must be present in the source offering chain");
+        }
+        const sourceCheck = await resolveSourcesByOfferingIds(db, args.tenantId, args.sourceOfferingIds, credentialCipher);
+        if (!sourceCheck.ok) {
+            throw new ExclusiveWorkflowPlacementError("source_offering_unavailable", `Catalog offering ${sourceCheck.offeringId} cannot be used by the deployment authority`);
+        }
+        // Probe + gate + freeze the code-sourced definition ONCE, on shared
+        // capacity, at request time. The freeze is sidecar-agnostic (a wire hash
+        // over the inert projection plus the resolved closure), so the frozen bundle
+        // deploys later to the dedicated allocation with no re-probe. A non-approval
+        // surfaces as a `WorkflowDefinitionInvalidError` from the deployer, which the
+        // route maps to a 409.
+        const approved = await preparedDeployer.installAndApproveWorkflowSource({
+            source: args.source,
+            entry: args.entry,
+            ...(args.pin !== undefined ? { pin: args.pin } : {}),
+            definitionAssetId: args.definitionAssetId,
+        });
+        if (!approved.approval.ok) {
+            // `installAndApproveWorkflowSource` already fails closed on a non-approval;
+            // restate the narrowing so the frozen bundle below reads the ok arm.
+            throw new Error("prepareExclusiveDeployment: install did not yield an approved definition");
+        }
+        // Capture the narrowed values before the transaction: TS drops the
+        // `approval.ok` narrowing inside the async callback below.
+        const definitionId = approved.approval.definitionId;
+        const frozenApprovalBundle = {
+            source: args.source,
+            entry: args.entry,
+            projection: approved.projection,
+            closure: approved.closure,
+            approvedWireHash: approved.approval.approvedWireHash,
+            approvedGrants: [...approved.approval.approvedGrants],
+        };
+        const allocationId = createAllocationId();
+        const createdAt = now();
+        const deploymentAddress = deriveRunAddress({
+            runId: args.anchorRunId,
+            domain: args.deploymentDomain,
+        });
+        await db.transaction(async (tx) => {
+            // The freeze already ensured (create-if-absent) the definition row keyed by
+            // the approved wire hash and returned its id; anchor to THAT row rather
+            // than re-ensuring, so the anchor's definition is exactly the one approved.
+            await tx.insert(workflowRun).values({
+                id: args.anchorRunId,
+                tenantId: args.tenantId,
+                anchorRunId: args.anchorRunId,
+                definitionId,
+                address: deploymentAddress,
+                // Born "deployed": the anchor is live but pre-trigger. The first trigger
+                // flips it to "running" (see `anchorWithPrincipal`).
+                status: "deployed",
+                createdAt,
+            });
+            await tx.insert(grant).values({
+                id: generateId("grant"),
+                tenantId: args.tenantId,
+                principalId: args.sourceAuthorityPrincipalId,
+                resource: `workflow-run:${args.anchorRunId}`,
+                action: "read",
+                effect: "allow",
+                origin: "creator",
+                createdAt,
+                updatedAt: createdAt,
+            });
+            await launchSpecStore.create({
+                anchorRunId: args.anchorRunId,
+                sessionId: args.sessionId,
+                deploymentDomain: args.deploymentDomain,
+                sourceAuthorityPrincipalId: args.sourceAuthorityPrincipalId,
+                frozenApprovalBundle,
+                sourceOfferingIds: [...args.sourceOfferingIds],
+                defaultSourceOfferingId: args.defaultSourceOfferingId,
+                deployContent: args.deployContent,
+                ...(args.toolPackagePins !== undefined
+                    ? { toolPackagePins: [...args.toolPackagePins] }
+                    : {}),
+                createdAt,
+            }, tx);
+            await allocationStore.createPending({
+                id: allocationId,
+                anchorRunId: args.anchorRunId,
+                tenantId: args.tenantId,
+                provisionerId: provisioner.id,
+                provisionerApiVersion: provisioner.apiVersion,
+                provisionerBindingFingerprint: provisioner.bindingFingerprint,
+                placement: args.placement,
+                now: createdAt,
+            }, tx);
+        });
+        return {
+            anchorRunId: args.anchorRunId,
+            deploymentAddress,
+            allocationId,
+            status: "pending",
+        };
+    }
+    async function deployReadyAllocation(allocation) {
+        if (allocation.status !== "allocated" ||
+            allocation.ensureAcceptedGeneration !== allocation.generation) {
+            throw new Error(`Allocation ${allocation.id} generation ${String(allocation.generation)} is not accepted for deployment`);
+        }
+        const allocationTarget = {
+            allocationId: allocation.id,
+            generation: allocation.generation,
+        };
+        const anchor = await db.query.workflowRun.findFirst({
+            where: eq(workflowRun.id, allocation.anchorRunId),
+            columns: { publicKey: true, definitionId: true },
+        });
+        if (anchor === undefined) {
+            throw new Error(`Allocation ${allocation.id} has no workflow anchor run`);
+        }
+        if (await allocationRouter.isAllocatedWorkflowActive(allocationTarget)) {
+            if (anchor.publicKey !== null)
+                return null;
+            throw new SessionLaunchError("provision", new Error(`Allocation ${allocation.id} has an active workflow without a completed initialization key`), true);
+        }
+        if (anchor.definitionId === null) {
+            throw new Error(`Allocation ${allocation.id} anchor run has no frozen workflow definition`);
+        }
+        const spec = await launchSpecStore.get(allocation.anchorRunId);
+        if (spec === null) {
+            throw new Error(`Allocation ${allocation.id} has no workflow launch specification`);
+        }
+        // The frozen bundle deploys verbatim -- no re-probe. Rehydrate the approval
+        // hand-off from it: the approved grant set becomes a `Set`, and the frozen
+        // definition id is the anchor's own (set at prepare time from this freeze).
+        const bundle = spec.frozenApprovalBundle;
+        const approved = {
+            approval: {
+                ok: true,
+                definitionId: anchor.definitionId,
+                approvedWireHash: bundle.approvedWireHash,
+                approvedGrants: new Set(bundle.approvedGrants),
+                projection: bundle.projection,
+            },
+            projection: bundle.projection,
+            closure: bundle.closure,
+        };
+        // Re-resolve the inference chain from the catalog at launch time -- the
+        // launch spec stores offering ids, never resolved sources, so a rotated
+        // credential is picked up here and no secret was ever persisted.
+        const resolved = await resolveSourcesByOfferingIds(db, allocation.tenantId, spec.sourceOfferingIds, credentialCipher);
+        if (!resolved.ok) {
+            throw new Error(`Catalog offering ${resolved.offeringId} is unavailable while recovering allocation ${allocation.id}`);
+        }
+        const defaultSource = resolved.sources.find((source) => source.id === spec.defaultSourceOfferingId);
+        if (defaultSource === undefined) {
+            throw new Error(`Default offering ${spec.defaultSourceOfferingId} was not resolved for allocation ${allocation.id}`);
+        }
+        const deploymentAddress = deriveRunAddress({
+            runId: allocation.anchorRunId,
+            domain: spec.deploymentDomain,
+        });
+        const config = {
+            sessionId: spec.sessionId,
+            agentId: deriveRunAgentId({ runId: allocation.anchorRunId }),
+            tenantId: allocation.tenantId,
+            principalId: spec.sourceAuthorityPrincipalId,
+            agentAddress: deploymentAddress,
+            systemPrompt: "",
+            tools: [],
+            grants: [],
+            sources: resolved.sources,
+            defaultSource: defaultSource.id,
+        };
+        return preparedDeployer.deployPreparedCodeSourcedWorkflow({
+            tenantId: allocation.tenantId,
+            anchorRunId: allocation.anchorRunId,
+            deploymentDomain: spec.deploymentDomain,
+            agentAddress: deploymentAddress,
+            source: bundle.source,
+            approved,
+            config,
+            allocationTarget,
+            ...(credentialCipher !== undefined ? { credentialCipher } : {}),
+        });
+    }
+    return { prepareExclusiveDeployment, deployReadyAllocation };
+}