@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/workflow-allocation-service.js

@@ -0,0 +1,554 @@
+import { type } from "arktype";
+import { sha256 } from "@intx/crypto";
+import { createSidecarAllocationStore, createWorkflowProbeStore, createWorkflowRunLaunchSpecStore, resolveTenantSidecarCapabilityPolicies, resolveSourcesByOfferingIds, } from "@intx/db";
+import { grant, workflowRun } from "@intx/db/schema";
+import { eq } from "drizzle-orm";
+import { generateId } from "@intx/hub-common";
+import { hexEncode, SidecarCapabilityRule, } from "@intx/types";
+import { approvalItemsFromSet, approvalSetFromItems, buildInertProjectionStepSources, deriveRunAddress, deriveRunAgentId, } from "@intx/workflow-deploy";
+import { DestroySidecarResult, EnsureSidecarResult, } from "./sidecar-allocation/index.js";
+import { SessionLaunchError, } from "./session-service.js";
+import { buildReferencedWorkflowSourcePins } from "./workflow-source-pins.js";
+import { DEFAULT_SIDECAR_OPERATION_TIMEOUT_MS, runSidecarOperation, } from "./sidecar-allocation/operation.js";
+export class WorkflowProvisioningError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorkflowProvisioningError";
+        this.code = code;
+    }
+}
+function randomAllocationId() {
+    return `sal_${hexEncode(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+function randomSidecarId() {
+    return `sc_${hexEncode(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+function randomToken() {
+    return `intx_sc_${hexEncode(crypto.getRandomValues(new Uint8Array(32)))}`;
+}
+function selectProvisioner(selection) {
+    if (selection.ok)
+        return selection.provisioner;
+    throw new WorkflowProvisioningError("provisioner_no_match", formatProvisionerMismatches(selection.mismatches));
+}
+function parseEnsureResult(value) {
+    const result = EnsureSidecarResult(value);
+    if (result instanceof type.errors) {
+        throw new Error(`Sidecar provisioner returned an invalid ensure result: ${result.summary}`);
+    }
+    return result;
+}
+function parseDestroyResult(value) {
+    const result = DestroySidecarResult(value);
+    if (result instanceof type.errors) {
+        throw new Error(`Sidecar provisioner returned an invalid destroy result: ${result.summary}`);
+    }
+    return result;
+}
+function createProvisionedHarnessConfig(args) {
+    const deploymentAddress = deriveRunAddress({
+        runId: args.anchorRunId,
+        domain: args.deploymentDomain,
+    });
+    return {
+        sessionId: args.sessionId,
+        agentId: deriveRunAgentId({ runId: args.anchorRunId }),
+        tenantId: args.tenantId,
+        principalId: args.sourceAuthorityPrincipalId,
+        agentAddress: deploymentAddress,
+        systemPrompt: "",
+        tools: [],
+        grants: [],
+        sources: args.sources,
+        defaultSource: args.defaultSource,
+    };
+}
+export function createWorkflowAllocationService({ db, deploymentPlugins, probePlugins, preparedDeployer, credentialCipher, probeCapabilityRules = [], allocationRouter, hubWebSocketUrl, createAllocationId = randomAllocationId, createSidecarId = randomSidecarId, createToken = randomToken, connectTimeoutMs = 120_000, operationTimeoutMs = DEFAULT_SIDECAR_OPERATION_TIMEOUT_MS, now = () => new Date(), }) {
+    const allocationStore = createSidecarAllocationStore(db);
+    const probeStore = createWorkflowProbeStore(db);
+    const launchSpecStore = createWorkflowRunLaunchSpecStore(db);
+    const validatedProbeCapabilityRules = SidecarCapabilityRule.array()(probeCapabilityRules);
+    if (validatedProbeCapabilityRules instanceof type.errors) {
+        throw new Error(`Invalid workflow probe capability rules: ${validatedProbeCapabilityRules.summary}`);
+    }
+    const configuredProbeCapabilityRules = validatedProbeCapabilityRules.map((rule) => ({ ...rule }));
+    if (connectTimeoutMs <= 0) {
+        throw new Error("connectTimeoutMs must be positive");
+    }
+    if (!Number.isSafeInteger(operationTimeoutMs) || operationTimeoutMs <= 0) {
+        throw new Error("operationTimeoutMs must be a positive integer");
+    }
+    function matchingProvisioner(probe) {
+        const provisioner = probePlugins.getProvisioner(probe.provisionerId);
+        return provisioner !== null &&
+            provisioner.apiVersion === probe.provisionerApiVersion &&
+            provisioner.bindingFingerprint === probe.provisionerBindingFingerprint
+            ? provisioner
+            : null;
+    }
+    async function beginProbeRelease(probe, failure) {
+        if (probe.status === "releasing")
+            return probe;
+        return probeStore.transition(probe.id, ["pending", "provisioning", "probing"], "releasing", {
+            ...(failure !== undefined
+                ? {
+                    failureCode: failure.code,
+                    failureMessage: failure.message,
+                }
+                : {}),
+            now: now(),
+        });
+    }
+    const probeCleanupTasks = new Map();
+    function finishProbeRelease(probe, finalStatus) {
+        const existing = probeCleanupTasks.get(probe.id);
+        if (existing !== undefined)
+            return existing;
+        const task = cleanUpProbe(probe, finalStatus);
+        probeCleanupTasks.set(probe.id, task);
+        const settled = () => {
+            if (probeCleanupTasks.get(probe.id) === task)
+                probeCleanupTasks.delete(probe.id);
+        };
+        void task.then(settled, settled);
+        return task;
+    }
+    async function cleanUpProbe(probe, finalStatus) {
+        const releasing = await probeStore.get(probe.id);
+        if (releasing?.status === "succeeded" || releasing?.status === "failed")
+            return;
+        if (releasing?.status !== "releasing") {
+            throw new Error(`Workflow probe ${probe.id} is not releasing`);
+        }
+        const sidecarId = releasing.sidecarId;
+        if (sidecarId !== null) {
+            const provisioner = matchingProvisioner(releasing);
+            if (provisioner === null) {
+                throw new Error(`Cannot clean up workflow probe ${releasing.id}: provisioner binding ${releasing.provisionerId} is unavailable`);
+            }
+            const destroyed = parseDestroyResult(await runSidecarOperation("Probe destroy", operationTimeoutMs, (signal) => provisioner.destroy({
+                signal,
+                allocationId: releasing.id,
+                generation: releasing.generation,
+                sidecarId,
+                ...(releasing.externalRef !== null
+                    ? { externalRef: releasing.externalRef }
+                    : {}),
+            })));
+            if (destroyed.kind === "rejected") {
+                throw new Error(`Provisioner ${provisioner.id} rejected probe cleanup: ${destroyed.message}`);
+            }
+            allocationRouter.disconnectAllocation({
+                allocationId: releasing.id,
+                generation: releasing.generation,
+            });
+        }
+        const completed = await probeStore.transition(releasing.id, ["releasing"], finalStatus, { now: now() });
+        if (completed === null) {
+            throw new Error(`Workflow probe ${releasing.id} changed before cleanup completed`);
+        }
+        allocationRouter.retireAllocation({
+            allocationId: releasing.id,
+            generation: releasing.generation,
+        });
+    }
+    async function releaseProbe(probe, finalStatus, failure) {
+        const releasing = await beginProbeRelease(probe, failure);
+        if (releasing === null)
+            return;
+        await finishProbeRelease(releasing, finalStatus);
+    }
+    async function createDeployment(args) {
+        const { request, approved, provisioner, probe, adoptProbe } = args;
+        const probeSidecarId = probe.sidecarId;
+        if (adoptProbe && probeSidecarId === null) {
+            throw new Error(`Workflow probe ${probe.id} has no sidecar to adopt`);
+        }
+        const allocationId = adoptProbe ? probe.id : createAllocationId();
+        const createdAt = now();
+        const deploymentAddress = deriveRunAddress({
+            runId: request.anchorRunId,
+            domain: request.deploymentDomain,
+        });
+        const frozenApprovalBundle = {
+            source: request.source,
+            entry: request.entry,
+            projection: approved.projection,
+            closure: approved.closure,
+            approvedWireHash: approved.approval.approvedWireHash,
+            approvedGrants: [
+                ...approvalItemsFromSet(approved.approval.approvedSurface),
+            ],
+        };
+        await db.transaction(async (tx) => {
+            await tx.insert(workflowRun).values({
+                id: request.anchorRunId,
+                tenantId: request.tenantId,
+                anchorRunId: request.anchorRunId,
+                definitionId: approved.approval.definitionId,
+                address: deploymentAddress,
+                status: "deployed",
+                createdAt,
+            });
+            await tx.insert(grant).values({
+                id: generateId("grant"),
+                tenantId: request.tenantId,
+                principalId: request.sourceAuthorityPrincipalId,
+                resource: `workflow-run:${request.anchorRunId}`,
+                action: "read",
+                effect: "allow",
+                origin: "creator",
+                createdAt,
+                updatedAt: createdAt,
+            });
+            await launchSpecStore.create({
+                anchorRunId: request.anchorRunId,
+                sessionId: request.sessionId,
+                deploymentDomain: request.deploymentDomain,
+                sourceAuthorityPrincipalId: request.sourceAuthorityPrincipalId,
+                frozenApprovalBundle,
+                sourceOfferingIds: [...request.sourceOfferingIds],
+                defaultSourceOfferingId: request.defaultSourceOfferingId,
+                deployContent: request.deployContent,
+                ...(request.toolPackagePins !== undefined
+                    ? { toolPackagePins: [...request.toolPackagePins] }
+                    : {}),
+                createdAt,
+            }, tx);
+            if (adoptProbe) {
+                if (probeSidecarId === null) {
+                    throw new Error(`Workflow probe ${probe.id} lost its sidecar`);
+                }
+                await allocationStore.createAdopted({
+                    id: allocationId,
+                    anchorRunId: request.anchorRunId,
+                    tenantId: request.tenantId,
+                    provisionerId: provisioner.id,
+                    provisionerApiVersion: provisioner.apiVersion,
+                    provisionerBindingFingerprint: provisioner.bindingFingerprint,
+                    sidecarId: probeSidecarId,
+                    generation: probe.generation,
+                    ...(probe.externalRef !== null
+                        ? { externalRef: probe.externalRef }
+                        : {}),
+                    connectDeadline: new Date(createdAt.getTime() + connectTimeoutMs),
+                    now: createdAt,
+                }, tx);
+                const completed = await probeStore.transition(probe.id, ["probing"], "succeeded", { now: createdAt, tx });
+                if (completed === null) {
+                    throw new Error(`Workflow probe ${probe.id} changed before adoption`);
+                }
+            }
+            else {
+                await allocationStore.createPending({
+                    id: allocationId,
+                    anchorRunId: request.anchorRunId,
+                    tenantId: request.tenantId,
+                    provisionerId: provisioner.id,
+                    provisionerApiVersion: provisioner.apiVersion,
+                    provisionerBindingFingerprint: provisioner.bindingFingerprint,
+                    now: createdAt,
+                }, tx);
+            }
+        });
+        if (adoptProbe) {
+            allocationRouter.disconnectAllocation({
+                allocationId: probe.id,
+                generation: probe.generation,
+            });
+        }
+        return {
+            anchorRunId: request.anchorRunId,
+            deploymentAddress,
+            allocationId,
+            status: "pending",
+        };
+    }
+    async function prepareProvisionedDeployment(args) {
+        if (args.sourceOfferingIds.length === 0) {
+            throw new WorkflowProvisioningError("invalid_source_offerings", "Provisioned workflow deployment requires at least one catalog offering");
+        }
+        if (!args.sourceOfferingIds.includes(args.defaultSourceOfferingId)) {
+            throw new WorkflowProvisioningError("invalid_source_offerings", "The default source offering must be present in the source offering chain");
+        }
+        const [sourceCheck, tenantPolicies] = await Promise.all([
+            resolveSourcesByOfferingIds(db, args.tenantId, args.sourceOfferingIds, credentialCipher),
+            resolveTenantSidecarCapabilityPolicies(db, args.tenantId),
+        ]);
+        if (!sourceCheck.ok) {
+            throw new WorkflowProvisioningError("source_offering_unavailable", `Catalog offering ${sourceCheck.offeringId} cannot be used by the deployment authority`);
+        }
+        const defaultSource = sourceCheck.sources.find((source) => source.id === args.defaultSourceOfferingId);
+        if (defaultSource === undefined) {
+            throw new WorkflowProvisioningError("invalid_source_offerings", `Default offering ${args.defaultSourceOfferingId} was not resolved for deployment ${args.anchorRunId}`);
+        }
+        const probeProvisioner = selectProvisioner(await probePlugins.selectProvisioner({
+            tenantPolicies,
+            probeRules: configuredProbeCapabilityRules,
+            workflowRules: [],
+        }));
+        const probeId = createAllocationId();
+        let probe = await probeStore.create({
+            id: probeId,
+            tenantId: args.tenantId,
+            definitionAssetId: args.definitionAssetId,
+            source: args.source,
+            entry: args.entry,
+            ...(args.pin !== undefined ? { pin: args.pin } : {}),
+            provisionerId: probeProvisioner.id,
+            provisionerApiVersion: probeProvisioner.apiVersion,
+            provisionerBindingFingerprint: probeProvisioner.bindingFingerprint,
+            now: now(),
+        });
+        try {
+            const token = createToken();
+            const sidecarId = createSidecarId();
+            const bound = await probeStore.bindSidecar({
+                probeId,
+                sidecarId,
+                tokenHashSha256: await sha256(token),
+                now: now(),
+            });
+            if (bound === null) {
+                throw new Error(`Workflow probe ${probeId} changed before provisioning`);
+            }
+            probe = bound;
+            const allocationTarget = {
+                allocationId: probe.id,
+                generation: probe.generation,
+            };
+            allocationRouter.fenceAllocation(probe.id, probe.generation);
+            const ensured = parseEnsureResult(await runSidecarOperation("Probe ensure", operationTimeoutMs, (signal) => probeProvisioner.ensure({
+                signal,
+                allocationId: probe.id,
+                generation: probe.generation,
+                tenantId: probe.tenantId,
+                // The provisioner contract treats this as an opaque owner id. A
+                // probe has no workflow run, so its own id is the honest owner.
+                anchorRunId: probe.id,
+                sidecarId,
+                token,
+                hubWebSocketUrl,
+            })));
+            if (ensured.kind === "rejected") {
+                throw new WorkflowProvisioningError(ensured.code, ensured.message);
+            }
+            const probing = await probeStore.markProbing({
+                probeId,
+                ...(ensured.externalRef !== undefined
+                    ? { externalRef: ensured.externalRef }
+                    : {}),
+                now: now(),
+            });
+            if (probing === null) {
+                throw new Error(`Workflow probe ${probeId} changed after provisioning`);
+            }
+            probe = probing;
+            await allocationRouter.waitForAllocatedSidecar(allocationTarget, connectTimeoutMs);
+            let resultRecorded = false;
+            const approved = await preparedDeployer.installAndApproveWorkflowSource({
+                source: args.source,
+                entry: args.entry,
+                ...(args.pin !== undefined ? { pin: args.pin } : {}),
+                definitionAssetId: args.definitionAssetId,
+                allocationTarget,
+                onProbeResult: async (result) => {
+                    if ((await probeStore.recordResult(probeId, result, now())) === null) {
+                        throw new Error(`Workflow probe ${probeId} changed before result persistence`);
+                    }
+                    resultRecorded = true;
+                },
+            });
+            if (!resultRecorded) {
+                throw new Error(`Workflow probe ${probeId} completed without persisting its result`);
+            }
+            if (!approved.approval.ok) {
+                throw new Error("prepareProvisionedDeployment: install did not yield an approved definition");
+            }
+            const narrowed = {
+                ...approved,
+                approval: approved.approval,
+            };
+            const config = createProvisionedHarnessConfig({
+                tenantId: args.tenantId,
+                anchorRunId: args.anchorRunId,
+                deploymentDomain: args.deploymentDomain,
+                sessionId: args.sessionId,
+                sourceAuthorityPrincipalId: args.sourceAuthorityPrincipalId,
+                sources: sourceCheck.sources,
+                defaultSource: defaultSource.id,
+            });
+            buildInertProjectionStepSources({
+                projection: approved.projection,
+                config,
+                operatorApprovals: approved.approval.approvedSurface,
+            });
+            await buildReferencedWorkflowSourcePins({
+                projection: approved.projection,
+                config,
+                operatorApprovals: approved.approval.approvedSurface,
+            });
+            const deploymentProvisioner = selectProvisioner(await deploymentPlugins.selectProvisioner({
+                tenantPolicies,
+                workflowRules: approved.projection.sidecarPlacement?.capabilities ?? [],
+            }));
+            const adoptProbe = deploymentProvisioner.id === probeProvisioner.id &&
+                deploymentProvisioner.apiVersion === probeProvisioner.apiVersion &&
+                deploymentProvisioner.bindingFingerprint ===
+                    probeProvisioner.bindingFingerprint;
+            if (!adoptProbe) {
+                await releaseProbe(probe, "succeeded");
+            }
+            return await createDeployment({
+                request: args,
+                approved: narrowed,
+                provisioner: deploymentProvisioner,
+                probe,
+                adoptProbe,
+            });
+        }
+        catch (error) {
+            try {
+                await releaseProbe(probe, "failed", {
+                    code: "probe_failed",
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            catch {
+                // Preserve the primary probe/provisioning error. The durable
+                // `releasing` row remains discoverable for periodic cleanup.
+            }
+            throw error;
+        }
+    }
+    async function deployReadyAllocation(allocation, reconciliation) {
+        reconciliation.signal.throwIfAborted();
+        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 persisted flat item list is partitioned back into
+        // the gate's `ApprovalSet`, 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,
+                approvedSurface: approvalSetFromItems(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 config = createProvisionedHarnessConfig({
+            tenantId: allocation.tenantId,
+            anchorRunId: allocation.anchorRunId,
+            deploymentDomain: spec.deploymentDomain,
+            sessionId: spec.sessionId,
+            sourceAuthorityPrincipalId: spec.sourceAuthorityPrincipalId,
+            sources: resolved.sources,
+            defaultSource: defaultSource.id,
+        });
+        reconciliation.signal.throwIfAborted();
+        return preparedDeployer.deployPreparedCodeSourcedWorkflow({
+            reconciliation,
+            tenantId: allocation.tenantId,
+            anchorRunId: allocation.anchorRunId,
+            deploymentDomain: spec.deploymentDomain,
+            agentAddress: config.agentAddress,
+            source: bundle.source,
+            approved,
+            config,
+            allocationTarget,
+            credentialCipher,
+        });
+    }
+    function cleanupFinalStatus(probe) {
+        return probe.failureCode === null ? "succeeded" : "failed";
+    }
+    async function reconcileReleasingProbes() {
+        const failures = [];
+        for (const probe of await probeStore.listReleasing()) {
+            try {
+                await releaseProbe(probe, cleanupFinalStatus(probe));
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, "Failed to clean up releasing workflow probes");
+        }
+    }
+    async function initialize() {
+        const failures = [];
+        for (const probe of await probeStore.listActive()) {
+            try {
+                await beginProbeRelease(probe, probe.status === "releasing"
+                    ? undefined
+                    : {
+                        code: "probe_interrupted",
+                        message: "Hub restarted before the workflow probe completed",
+                    });
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, "Failed to mark interrupted workflow probes for cleanup");
+        }
+    }
+    return {
+        initialize,
+        reconcileReleasingProbes,
+        prepareProvisionedDeployment,
+        deployReadyAllocation,
+    };
+}
+function formatProvisionerMismatches(mismatches) {
+    const details = Object.entries(mismatches)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .flatMap(([provisionerId, failures]) => failures.map(({ capability, expected, actual }) => `${provisionerId}: ${capability} must be ${expected}, was ${actual}`));
+    return details.length === 0
+        ? "No sidecar provisioners are registered"
+        : `No sidecar provisioner satisfies the deployment (${details.join("; ")})`;
+}

package/dist/workflow-closure-resolution.d.ts

@@ -0,0 +1,106 @@
+import { type PackumentFetcher, type RegistryConfig } from "@intx/tool-packaging";
+import type { WorkflowSourceAssetMount } from "@intx/types/sidecar";
+import type { ToolPackageManifest } from "@intx/types/tool-packages";
+import type { WorkflowDefinitionAssetSource, WorkflowDefinitionRegistrySource } from "@intx/types/workflow-sources";
+import { type SourceTreeReads } from "./workflow-source-closure.js";
+/**
+ * Resolve a workflow definition's dependency closure against the npm registry
+ * the source names.
+ */
+export type ResolveWorkflowClosureRegistryArgs = {
+    readonly source: WorkflowDefinitionRegistrySource;
+    /** A `name@range` spec for the workflow definition package. */
+    readonly pin: string;
+    /** URL and credentials for the registry named by `source.registry`. */
+    readonly registryConfig: RegistryConfig;
+    /**
+     * Test seam for packument fetches. Omitted in production, where the
+     * default `npm-registry-fetch` wrapper reaches the configured URL.
+     */
+    readonly fetchPackument?: PackumentFetcher;
+};
+/**
+ * Resolve a workflow definition's dependency closure against a single hub
+ * `package-registry` asset.
+ *
+ * The resolver is single-source by design: the asset is the sole and default
+ * registry, so a self-contained definition (its `@intx/*` imports bundled at
+ * author time) resolves to one `kind:"asset"` entry. A specifier the asset does
+ * not publish fails loud from `AssetRegistrySource` -- there is no silent
+ * fallback to npm. A definition that genuinely needs external npm dependencies
+ * would resolve through the mixed `AssetRegistrySource` + `HttpRegistrySource`
+ * map `session-service` already builds for tool packages; that path is not
+ * threaded here.
+ */
+export type ResolveWorkflowClosureAssetTarballArgs = {
+    /** An asset source whose `package.format` is `"tarball"`. */
+    readonly source: WorkflowDefinitionAssetSource;
+    /** A `name@range` spec for the workflow definition package. */
+    readonly pin: string;
+    /** Reads a blob at `path` from the asset the definition is sourced from. */
+    readonly readBlob: (path: string) => Promise<Uint8Array>;
+    /** Lists the blob names directly under `dir` in that asset. */
+    readonly listBlobs: (dir: string) => Promise<string[]>;
+};
+/**
+ * Resolve a source-format workflow definition's dependency closure from the
+ * asset's git tree at the pinned commit. The workspace-local members become
+ * `format:"source"` entries and the external npm deps resolve through the
+ * npm registry the caller supplies; there is no `name@range` pin (the member
+ * is selected from `source.package.packageName`).
+ */
+export type ResolveWorkflowClosureAssetSourceArgs = {
+    /** An asset source whose `package.format` is `"source"`. */
+    readonly source: WorkflowDefinitionAssetSource;
+    /** Git-tree reads pinned to `source.package.commitSha`. */
+    readonly reads: SourceTreeReads;
+    /**
+     * The registry name external deps are stamped with in the frozen closure.
+     * Must be a name the sidecar's registry map is keyed by (its npm registry),
+     * since the sidecar resolves each external entry's `source.registry` against
+     * that map at materialization.
+     */
+    readonly registryName: string;
+    /** URL and credentials for the npm registry external deps resolve against. */
+    readonly registryConfig: RegistryConfig;
+    /**
+     * Test seam for packument fetches. Omitted in production, where the
+     * default `npm-registry-fetch` wrapper reaches the configured URL.
+     */
+    readonly fetchPackument?: PackumentFetcher;
+};
+export type ResolveWorkflowClosureArgs = ResolveWorkflowClosureRegistryArgs | ResolveWorkflowClosureAssetTarballArgs | ResolveWorkflowClosureAssetSourceArgs;
+/**
+ * Resolve a workflow definition's dependency closure to concrete versions
+ * and integrity SRIs, reusing the tool-packaging closure resolver.
+ *
+ * @returns the frozen closure: a `ToolPackageManifest` whose `topLevel`
+ *   pins the definition package and whose `entries` carry the concrete
+ *   version and integrity SRI of every transitive dependency.
+ */
+export declare function resolveWorkflowClosure(args: ResolveWorkflowClosureArgs): Promise<ToolPackageManifest>;
+/**
+ * The workspace-relative mount path a workflow definition's source asset is
+ * delivered under, keyed by asset id. Both the probe (inline delivery) and the
+ * deploy (streamed fan-out) build their `assetId -> mountPath` maps through
+ * this one helper, so the same asset lands at the same path on both paths.
+ */
+export declare function workflowSourceAssetMountPath(assetId: string): string;
+/**
+ * Resolves an asset (by id) to the git pack a source-ref frame delivers for it.
+ * The caller binds the ref: an asset source binds the asset's default ref, so
+ * the install/deploy glue stays ref-agnostic.
+ */
+export type ResolveAssetAttachmentFn = (assetId: string) => Promise<{
+    pack: Uint8Array;
+    ref: string;
+    commitSha: string;
+}>;
+/**
+ * Build the inline asset mounts a source-ref frame delivers for an asset-sourced
+ * closure: one per distinct asset the closure's `kind:"asset"` entries name (so
+ * a multi-asset closure delivers every backing asset, not just the source), each
+ * carrying the git pack the caller resolves for that asset. `mountPath` is
+ * derived through the shared helper so probe and deploy agree on it.
+ */
+export declare function buildSourceAssetMounts(closure: ToolPackageManifest, resolveAttachment: ResolveAssetAttachmentFn): Promise<WorkflowSourceAssetMount[]>;