@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/skill-kind.js

@@ -281,6 +281,10 @@ export const skillAuthorize = (principal, repoId, ref, action) => {
             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

@@ -1,8 +1,8 @@
-export { DEFAULT_CONSUMED_RETENTION_MS, dequeueToProcessing, enqueueInbox, markConsumed, readOwnedMessageIds, readProcessingEntry, replayProcessingToInbox, WORKFLOW_RUN_AGENT_STATE_PREFIX, } from "./workflow-run-kind.js";
-export type { WorkflowRunSupervisorPrincipal, WorkflowRunWorkflowProcessPrincipal, DequeueToProcessingResult, EnqueueInboxArgs, EnqueueInboxResult, MarkConsumedArgs, MarkConsumedResult, ReplayProcessingToInboxOpts, ReplayProcessingToInboxResult, } from "./workflow-run-kind.js";
+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 { Principal, RepoId, RepoStore, WriteResult, InitRepoOpts, NewlyTerminalRun, } from "./repo-store/types.js";
+export type { CommittedReads, CommittedTreeEntry, Principal, RepoId, RepoStore, WriteResult, InitRepoOpts, NewlyTerminalRun, } from "./repo-store/types.js";

package/dist/substrate.js

@@ -14,7 +14,7 @@
 // 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, readOwnedMessageIds, readProcessingEntry, replayProcessingToInbox, WORKFLOW_RUN_AGENT_STATE_PREFIX, } from "./workflow-run-kind.js";
+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";

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 };
+}

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[]>;

package/dist/workflow-closure-resolution.js

@@ -0,0 +1,123 @@
+// Hub-side dependency-closure resolution for a code-sourced workflow
+// definition.
+//
+// Given a `WorkflowDefinitionSource` and a pin, walk the full dependency
+// closure to concrete versions plus integrity SRIs, reusing the tool-packaging
+// closure resolver. This is the "what exactly would we install" step: packument
+// and package.json metadata reads only, no code execution. The returned
+// `ToolPackageManifest` is the frozen closure the deploy path later ships by
+// source-ref.
+//
+// There are three arms, one per `(source.kind, package.format)`:
+//   - `registry` names an npm registry; its URL and credentials are supplied by
+//     the caller as a `RegistryConfig`, since the caller owns the registry
+//     configuration.
+//   - `asset` + `tarball` names a hub asset that publishes the definition
+//     package as a tarball; the caller supplies bound `readBlob`/`listBlobs`
+//     closures over that asset (the same shape `session-service` mints for
+//     `AssetRegistrySource`).
+//   - `asset` + `source` names a hub asset whose definition package lives as a
+//     git subtree at a pinned commit; the caller supplies a `SourceTreeReads`
+//     pinned to that commit plus a `RegistryConfig` for the external npm deps.
+//     This arm delegates to `resolveSourceWorkflowClosure`, which reads the
+//     tree directly and needs no `name@range` pin (it selects the member from
+//     the source's `packageName`).
+// Every arm takes pre-bound read capabilities, keeping this module free of any
+// asset-service or repo-store dependency.
+import { base64Encode } from "@intx/types";
+import { AssetRegistrySource, HttpRegistrySource, createClosureResolver, parsePin, } from "@intx/tool-packaging";
+import { resolveSourceWorkflowClosure, } from "./workflow-source-closure.js";
+// Both asset arms carry an identical `source` field type, so narrow on the
+// source's own `package.format` discriminant rather than adding a redundant
+// discriminant to the args.
+function isAssetSourceArgs(args) {
+    return (args.source.kind === "asset" && args.source.package.format === "source");
+}
+function isAssetTarballArgs(args) {
+    return (args.source.kind === "asset" && args.source.package.format === "tarball");
+}
+/**
+ * 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 async function resolveWorkflowClosure(args) {
+    if (isAssetSourceArgs(args)) {
+        return resolveSourceWorkflowClosure({
+            source: args.source,
+            reads: args.reads,
+            registryName: args.registryName,
+            registryConfig: args.registryConfig,
+            ...(args.fetchPackument !== undefined
+                ? { fetchPackument: args.fetchPackument }
+                : {}),
+        });
+    }
+    if (isAssetTarballArgs(args)) {
+        // The assetId is the source name so every walker resolution error is
+        // traceable to the exact asset; it is the sole and default source.
+        const name = args.source.assetId;
+        const assetSource = new AssetRegistrySource({
+            name,
+            assetId: args.source.assetId,
+            readBlob: args.readBlob,
+            listBlobs: args.listBlobs,
+        });
+        const resolver = createClosureResolver({
+            registries: new Map([[name, assetSource]]),
+            defaultRegistry: name,
+        });
+        return resolver.resolveClosure([parsePin(args.pin)]);
+    }
+    const registrySource = new HttpRegistrySource({
+        name: args.source.registry,
+        config: args.registryConfig,
+        ...(args.fetchPackument !== undefined
+            ? { fetchPackument: args.fetchPackument }
+            : {}),
+    });
+    const resolver = createClosureResolver({
+        registries: new Map([[registrySource.name, registrySource]]),
+        defaultRegistry: registrySource.name,
+    });
+    return resolver.resolveClosure([parsePin(args.pin)]);
+}
+/**
+ * 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 function workflowSourceAssetMountPath(assetId) {
+    return `source-assets/${assetId}/`;
+}
+/**
+ * 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 async function buildSourceAssetMounts(closure, resolveAttachment) {
+    const assetIds = new Set();
+    for (const entry of closure.entries) {
+        if (entry.source.kind === "asset") {
+            assetIds.add(entry.source.assetId);
+        }
+    }
+    const mounts = [];
+    for (const assetId of assetIds) {
+        const attachment = await resolveAttachment(assetId);
+        mounts.push({
+            assetId,
+            mountPath: workflowSourceAssetMountPath(assetId),
+            pack: base64Encode(attachment.pack),
+            ref: attachment.ref,
+            commitSha: attachment.commitSha,
+        });
+    }
+    return mounts;
+}

package/dist/workflow-definition-ensure.d.ts

@@ -0,0 +1,24 @@
+import { type DBExecutor, type WorkflowDefinitionSelector } from "@intx/db";
+/**
+ * The first-class `workflow_definition` a selector names, created if absent. A
+ * native workflow carries its body in the asset it points at, so this only
+ * projects a definition row -- plus its version "1" -- over that asset, keyed
+ * by the selector's wire hash, so a run can anchor on a first-class definition.
+ * A single asset backs many definitions distinguished by their wire hash, so
+ * distinct hashes over one asset yield distinct definitions.
+ * `currentVersion`/`status` are left to the table defaults; the definition
+ * carries no `modelRequirements` manifest, so it deploys as a workflow rather
+ * than launching as an instance.
+ *
+ * Idempotent and concurrency-safe: the definition insert conflicts on the
+ * unique `(assetId, wireHash)` and the version on `(definitionId, version)`, so
+ * two concurrent deploys of the same selector still yield exactly one
+ * definition and one version. The returned id is read back after the conflict
+ * -- the winner's id, not a locally-minted one -- so a losing insert anchors
+ * its version on the real row. `created` distinguishes a fresh projection from
+ * a pre-existing one for callers that report fold counts.
+ */
+export declare function ensureWorkflowDefinitionForAsset(db: DBExecutor, selector: WorkflowDefinitionSelector): Promise<{
+    definitionId: string;
+    created: boolean;
+}>;

package/dist/workflow-definition-ensure.js

@@ -0,0 +1,75 @@
+import { eq } from "drizzle-orm";
+import { resolveDefinitionIdForAsset, } from "@intx/db";
+import { asset, workflowDefinition, workflowDefinitionVersion, } from "@intx/db/schema";
+import { generateId } from "@intx/hub-common";
+/**
+ * The first-class `workflow_definition` a selector names, created if absent. A
+ * native workflow carries its body in the asset it points at, so this only
+ * projects a definition row -- plus its version "1" -- over that asset, keyed
+ * by the selector's wire hash, so a run can anchor on a first-class definition.
+ * A single asset backs many definitions distinguished by their wire hash, so
+ * distinct hashes over one asset yield distinct definitions.
+ * `currentVersion`/`status` are left to the table defaults; the definition
+ * carries no `modelRequirements` manifest, so it deploys as a workflow rather
+ * than launching as an instance.
+ *
+ * Idempotent and concurrency-safe: the definition insert conflicts on the
+ * unique `(assetId, wireHash)` and the version on `(definitionId, version)`, so
+ * two concurrent deploys of the same selector still yield exactly one
+ * definition and one version. The returned id is read back after the conflict
+ * -- the winner's id, not a locally-minted one -- so a losing insert anchors
+ * its version on the real row. `created` distinguishes a fresh projection from
+ * a pre-existing one for callers that report fold counts.
+ */
+export async function ensureWorkflowDefinitionForAsset(db, selector) {
+    const { assetId, wireHash } = selector;
+    const assetRow = await db
+        .select({
+        tenantId: asset.tenantId,
+        creatorPrincipalId: asset.creatorPrincipalId,
+        name: asset.name,
+        displayName: asset.displayName,
+    })
+        .from(asset)
+        .where(eq(asset.id, assetId))
+        .limit(1)
+        .then((rows) => rows[0]);
+    if (assetRow === undefined) {
+        throw new Error(`ensureWorkflowDefinitionForAsset: no asset found for id "${assetId}"`);
+    }
+    const inserted = await db
+        .insert(workflowDefinition)
+        .values({
+        id: generateId("workflowDefinition"),
+        tenantId: assetRow.tenantId,
+        creatorPrincipalId: assetRow.creatorPrincipalId,
+        assetId,
+        wireHash,
+        name: assetRow.name,
+        description: assetRow.displayName,
+    })
+        .onConflictDoNothing({
+        target: [workflowDefinition.assetId, workflowDefinition.wireHash],
+    })
+        .returning({ id: workflowDefinition.id });
+    const created = inserted.length > 0;
+    const insertedId = inserted[0]?.id;
+    const definitionId = insertedId ?? (await resolveDefinitionIdForAsset(db, selector));
+    if (definitionId === null || definitionId === undefined) {
+        throw new Error(`ensureWorkflowDefinitionForAsset: definition for asset "${assetId}" (wire hash "${wireHash}") missing after insert`);
+    }
+    await db
+        .insert(workflowDefinitionVersion)
+        .values({
+        id: generateId("workflowDefinitionVersion"),
+        definitionId,
+        version: "1",
+    })
+        .onConflictDoNothing({
+        target: [
+            workflowDefinitionVersion.definitionId,
+            workflowDefinitionVersion.version,
+        ],
+    });
+    return { definitionId, created };
+}