@intx/hub-sessions 0.1.2 → 0.3.0

package/dist/workflow-run-reader.d.ts

@@ -0,0 +1,47 @@
+import type { RepoId } from "./repo-store/types.js";
+import type { RepoStore } from "./repo-store/types.js";
+/**
+ * A workflow-run event as committed under
+ * `runs/<runId>/events/<seq>.json`. The discriminator field is `type`;
+ * the per-type body is opaque to the reader and surfaced verbatim as
+ * `body` so consumers narrow on the discriminator they care about.
+ */
+export type WorkflowRunEvent = {
+    seq: number;
+    type: string;
+    body: Record<string, unknown>;
+};
+/**
+ * Reader for a workflow-run repo's committed event log. Projects the
+ * `runs/<runId>/events/<seq>.json` substrate the workflow-process child
+ * writes (validated at push time by the workflow-run kind handler) into
+ * seq-ordered in-memory events, mirroring the read-model approach the
+ * per-session timeline reconstruction uses against an agent-state repo.
+ *
+ * The reader is read-only: it composes `RepoStore.getRepoDir` (a pure
+ * path computation) with direct `isomorphic-git` tree/blob reads. It
+ * never writes, so it carries no authorize gate of its own; callers
+ * gate access at their own boundary (the REST routes use a
+ * `workflow-run:<runId>` grant check).
+ */
+export interface WorkflowRunReader {
+    /**
+     * Enumerate the run ids present under `runs/` on `ref`. Returns an
+     * empty array when the repo has not been initialised yet (no on-disk
+     * repoDir, no ref, or no `runs/` tree). A corrupt repo, a
+     * present-but-malformed tree, or any other unexpected isomorphic-git
+     * error propagates so the caller sees the failure rather than
+     * treating it as "no runs yet".
+     */
+    listRunIds(repoId: RepoId, ref: string): Promise<string[]>;
+    /**
+     * Read every event under `runs/<runId>/events/` on `ref` and return
+     * them in ascending `seq` order. Returns an empty array when the run
+     * has not yet committed any events or the repo/ref has not been
+     * created. A blob that parses but is missing a string `type`
+     * discriminator is a substrate-invariant violation and throws rather
+     * than being silently dropped.
+     */
+    readRunEvents(repoId: RepoId, ref: string, runId: string): Promise<WorkflowRunEvent[]>;
+}
+export declare function createWorkflowRunReader(repoStore: RepoStore): WorkflowRunReader;

package/dist/workflow-run-reader.js

@@ -0,0 +1,153 @@
+import fs from "node:fs";
+import git from "isomorphic-git";
+import { requireEventSeq, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+import { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, } from "./workflow-run-event-log.js";
+export function createWorkflowRunReader(repoStore) {
+    function repoDirOrNull(repoId) {
+        try {
+            return repoStore.getRepoDir(repoId);
+        }
+        catch {
+            // getRepoDir throws only when the repoId fails the kind handler's
+            // slug validation; an uninitialised-but-valid repo returns a path
+            // that does not yet exist on disk. A validation failure here means
+            // the caller handed an id the substrate would never have written,
+            // which is indistinguishable from "no such run repo" at this read
+            // boundary.
+            return null;
+        }
+    }
+    async function resolveRefOrNull(dir, ref) {
+        try {
+            return await git.resolveRef({ fs, dir, ref });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError ||
+                (cause instanceof Error && /ENOENT|not found/i.test(cause.message))) {
+                return null;
+            }
+            throw cause;
+        }
+    }
+    async function listRunIds(repoId, ref) {
+        const dir = repoDirOrNull(repoId);
+        if (dir === null)
+            return [];
+        const oid = await resolveRefOrNull(dir, ref);
+        if (oid === null)
+            return [];
+        let tree;
+        try {
+            tree = await git.readTree({
+                fs,
+                dir,
+                oid,
+                filepath: WORKFLOW_RUN_RUNS_PREFIX,
+            });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError)
+                return [];
+            throw cause;
+        }
+        return tree.tree
+            .filter((entry) => entry.type === "tree")
+            .map((entry) => entry.path);
+    }
+    async function readRunEvents(repoId, ref, runId) {
+        const dir = repoDirOrNull(repoId);
+        if (dir === null)
+            return [];
+        const oid = await resolveRefOrNull(dir, ref);
+        if (oid === null)
+            return [];
+        const runDir = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}`;
+        let runTree;
+        try {
+            runTree = await git.readTree({ fs, dir, oid, filepath: runDir });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError)
+                return [];
+            throw cause;
+        }
+        // A terminated run is sealed into a single combined `events.jsonl`;
+        // an in-flight run keeps per-event `events/<seq>.json` files. The two
+        // forms are mutually exclusive in a run directory; a run carrying both
+        // is a botched seal, and silently preferring one would mask it, so
+        // surface it instead.
+        const combined = runTree.tree.find((e) => e.type === "blob" && e.path === WORKFLOW_RUN_EVENTS_FILE);
+        const perEventDir = runTree.tree.find((e) => e.type === "tree" && e.path === WORKFLOW_RUN_EVENTS_DIR);
+        if (combined !== undefined && perEventDir !== undefined) {
+            throw new Error(`workflow-run reader: run ${runId} carries both a combined ${WORKFLOW_RUN_EVENTS_FILE} and a per-event ${WORKFLOW_RUN_EVENTS_DIR}/ directory`);
+        }
+        if (combined !== undefined) {
+            const blob = await git.readBlob({ fs, dir, oid: combined.oid });
+            const source = `${runDir}/${WORKFLOW_RUN_EVENTS_FILE}`;
+            const events = [];
+            for (const line of splitCombinedEventLog(new TextDecoder().decode(blob.blob))) {
+                events.push(parseRunEventLine(line, source));
+            }
+            events.sort((a, b) => a.seq - b.seq);
+            return events;
+        }
+        const eventsDir = `${runDir}/${WORKFLOW_RUN_EVENTS_DIR}`;
+        let tree;
+        try {
+            tree = await git.readTree({ fs, dir, oid, filepath: eventsDir });
+        }
+        catch (cause) {
+            if (cause instanceof git.Errors.NotFoundError)
+                return [];
+            throw cause;
+        }
+        const events = [];
+        for (const entry of tree.tree) {
+            if (entry.type !== "blob")
+                continue;
+            const path = `${eventsDir}/${entry.path}`;
+            const seq = requireEventSeq(entry.path, path);
+            const blob = await git.readBlob({ fs, dir, oid: entry.oid });
+            const parsed = parseEventObject(new TextDecoder().decode(blob.blob), path);
+            const type = parsed["type"];
+            if (typeof type !== "string") {
+                throw new Error(`workflow-run reader: event at ${path} is missing a string \`type\` field`);
+            }
+            // The per-event form carries the seq in the filename; when the body
+            // also carries one, the two must agree (the combined form reads the
+            // seq from the body, so a disagreement would make the forms diverge).
+            const bodySeq = parsed["seq"];
+            if (typeof bodySeq === "number" && bodySeq !== seq) {
+                throw new Error(`workflow-run reader: event at ${path} body seq ${String(bodySeq)} does not match filename seq ${String(seq)}`);
+            }
+            events.push({ seq, type, body: parsed });
+        }
+        events.sort((a, b) => a.seq - b.seq);
+        return events;
+    }
+    // Parse one combined-log line (the verbatim text of a former
+    // `events/<seq>.json` blob): the seq is read from the body, since the
+    // combined form drops the per-event filename that carried it.
+    function parseRunEventLine(line, source) {
+        const parsed = parseEventObject(line, source);
+        const seq = parsed["seq"];
+        const type = parsed["type"];
+        if (typeof seq !== "number") {
+            throw new Error(`workflow-run reader: event in ${source} is missing a numeric \`seq\` field`);
+        }
+        if (typeof type !== "string") {
+            throw new Error(`workflow-run reader: event in ${source} is missing a string \`type\` field`);
+        }
+        return { seq, type, body: parsed };
+    }
+    function parseEventObject(text, source) {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new Error(`workflow-run reader: event at ${source} is not a JSON object`);
+        }
+        return { ...parsed };
+    }
+    return { listRunIds, readRunEvents };
+}

package/dist/workflow-run-restore.d.ts

@@ -0,0 +1,15 @@
+import type { AgentRepoStore } from "./agent-repo.js";
+import type { AllocatedSidecarTarget, SidecarAllocationRouter } from "./ws/sidecar-handler.js";
+export declare const WORKFLOW_RUN_RESTORE_REFS: readonly ["refs/heads/main", "refs/heads/events"];
+/**
+ * Replay every authoritative workflow-run ref the runtime understands onto an
+ * exact replacement allocation. Refs are sent sequentially and the function
+ * resolves only after the worker acknowledges each one, making it a barrier
+ * the deploy path can place before supervisor spawn.
+ */
+export declare function restoreWorkflowRunToAllocation(args: {
+    agentRepoStore: AgentRepoStore;
+    allocationRouter: Pick<SidecarAllocationRouter, "sendWorkflowRunPackToAllocation">;
+    allocationTarget: AllocatedSidecarTarget;
+    agentAddress: string;
+}): Promise<void>;

package/dist/workflow-run-restore.js

@@ -0,0 +1,26 @@
+import { deriveWorkflowRunRepoId } from "@intx/workflow-deploy";
+export const WORKFLOW_RUN_RESTORE_REFS = [
+    "refs/heads/main",
+    "refs/heads/events",
+];
+/**
+ * Replay every authoritative workflow-run ref the runtime understands onto an
+ * exact replacement allocation. Refs are sent sequentially and the function
+ * resolves only after the worker acknowledges each one, making it a barrier
+ * the deploy path can place before supervisor spawn.
+ */
+export async function restoreWorkflowRunToAllocation(args) {
+    const { agentRepoStore, allocationRouter, allocationTarget, agentAddress } = args;
+    const principal = { kind: "hub" };
+    const repoId = {
+        kind: "workflow-run",
+        id: deriveWorkflowRunRepoId(agentAddress),
+    };
+    for (const ref of WORKFLOW_RUN_RESTORE_REFS) {
+        const tip = await agentRepoStore.repoStore.resolveRef(principal, repoId, ref);
+        if (tip === null)
+            continue;
+        const pack = await agentRepoStore.repoStore.createPack(principal, repoId, ref);
+        await allocationRouter.sendWorkflowRunPackToAllocation(allocationTarget, agentAddress, pack.pack, pack.ref, pack.commitSha);
+    }
+}

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

@@ -0,0 +1,35 @@
+import { type PackumentFetcher, type RegistryConfig } from "@intx/tool-packaging";
+import type { ToolPackageManifest } from "@intx/types/tool-packages";
+import type { WorkflowDefinitionAssetSource } from "@intx/types/workflow-sources";
+import type { CommittedTreeEntry } from "./repo-store/types.js";
+/** Git-tree reads pinned to the source's commit. */
+export interface SourceTreeReads {
+    readBlob(path: string): Promise<Uint8Array>;
+    listDir(path: string): Promise<CommittedTreeEntry[]>;
+    treeOid(path: string): Promise<string | null>;
+}
+export interface ResolveSourceWorkflowClosureArgs {
+    /** A source whose `package.format` is `"source"`. */
+    readonly source: WorkflowDefinitionAssetSource;
+    readonly reads: SourceTreeReads;
+    /**
+     * The registry name external deps are stamped with in the frozen closure.
+     * The sidecar resolves each entry's `source.registry` against its own
+     * registry map at materialization, so this MUST be a name that map is keyed
+     * by (the sidecar's npm registry, e.g. `"npmjs"`); an unknown name fails the
+     * materialization loud. The caller owns the sidecar's registry configuration,
+     * so it supplies the name here rather than the walk inventing one.
+     */
+    readonly registryName: string;
+    /** URL and credentials for the npm registry external deps resolve against. */
+    readonly registryConfig: RegistryConfig;
+    /** Test seam for external packument fetches. */
+    readonly fetchPackument?: PackumentFetcher;
+}
+/**
+ * Resolve a source-format workflow definition's dependency closure to a frozen
+ * `ToolPackageManifest`: a `format:"source"` entry for the workflow package and
+ * each workspace-local dependency (identity = git tree oid), plus tarball
+ * entries for the external npm closure.
+ */
+export declare function resolveSourceWorkflowClosure(args: ResolveSourceWorkflowClosureArgs): Promise<ToolPackageManifest>;

package/dist/workflow-source-closure.js

@@ -0,0 +1,342 @@
+// Hub-side dependency-closure resolution for a SOURCE-format workflow
+// definition -- a codebase living as a subtree of a hub git asset at a
+// pinned commit.
+//
+// Unlike the registry and tarball arms (which resolve against npm packuments
+// with SRI integrity), a source package has no packument: its content
+// identity is the git tree oid of its subtree, and its dependency closure is
+// a DISJOINT UNION of two origins built by construction --
+//   - workspace-local members (other subtrees in the SAME asset) become
+//     `format:"source"` entries and are walked recursively, and
+//   - external npm dependencies are resolved through the pristine registry
+//     walker (which keeps its SRI invariant intact) into tarball entries.
+// A member name never appears in the external set, so the two origins cannot
+// collide on a workspace member; the one residual collision (an external
+// transitive dep whose `name@version` equals a member's) is detected and
+// fails loud rather than silently picking an origin.
+import { HttpRegistrySource, createClosureResolver, } from "@intx/tool-packaging";
+/**
+ * Resolve a source-format workflow definition's dependency closure to a frozen
+ * `ToolPackageManifest`: a `format:"source"` entry for the workflow package and
+ * each workspace-local dependency (identity = git tree oid), plus tarball
+ * entries for the external npm closure.
+ */
+export async function resolveSourceWorkflowClosure(args) {
+    const { source, reads, registryName, registryConfig, fetchPackument } = args;
+    if (source.package.format !== "source") {
+        throw new Error("resolveSourceWorkflowClosure: source.package.format must be 'source'");
+    }
+    const { commitSha, packageName } = source.package;
+    const assetId = source.assetId;
+    const { members, rootName, catalog } = await enumerateMembers(reads);
+    const selected = selectMember(members, packageName);
+    // BFS over the reachable workspace members. A dependency classifies by NAME,
+    // never by parsing its range: a name that is a member recurses (a
+    // workspace-local edge); the workspace root's own name is an invalid target
+    // (the root is not a member) and fails loud regardless of how the range is
+    // spelled; anything else is external and resolves through the registry walker.
+    //
+    // External deps collect by name, and a second member contributing the same
+    // name at a DIFFERENT resolved range fails loud rather than silently
+    // collapsing to one pin -- the walker resolves a single range per name, so a
+    // silent overwrite would drop a real constraint. This is a DELIBERATE v1
+    // limitation: two members with drifting-but-compatible ranges (e.g. `^1.0.0`
+    // and `^1.2.0`) that npm/bun would reconcile to one version are rejected here,
+    // not intersected. Aligning the ranges across members, or declaring the dep
+    // once in the root `catalog`, resolves it. (Semver intersection across
+    // members is tracked separately as INTR-460.)
+    const sourceEntries = [];
+    const externalPins = new Map();
+    const seen = new Set();
+    const queue = [selected.name];
+    while (queue.length > 0) {
+        const memberName = queue.shift();
+        if (memberName === undefined || seen.has(memberName))
+            continue;
+        seen.add(memberName);
+        const member = members.get(memberName);
+        if (member === undefined) {
+            throw new Error(`resolveSourceWorkflowClosure: internal -- member ${JSON.stringify(memberName)} was queued but not enumerated`);
+        }
+        const treeOid = await reads.treeOid(member.packageDir);
+        if (treeOid === null) {
+            throw new Error(`resolveSourceWorkflowClosure: subtree ${JSON.stringify(member.packageDir)} not found at commit ${commitSha}`);
+        }
+        sourceEntries.push({
+            name: member.name,
+            version: member.version,
+            source: {
+                kind: "asset",
+                assetId,
+                package: {
+                    format: "source",
+                    commitSha,
+                    packageDir: member.packageDir,
+                    treeOid,
+                },
+            },
+        });
+        for (const [depName, depSpec] of Object.entries(member.dependencies)) {
+            if (members.has(depName)) {
+                queue.push(depName);
+                continue;
+            }
+            if (rootName !== undefined && depName === rootName) {
+                throw new Error(`resolveSourceWorkflowClosure: member ${JSON.stringify(member.name)} depends on the workspace root ${JSON.stringify(rootName)}, which is not a workspace member`);
+            }
+            const resolvedSpec = resolveExternalSpec(depName, depSpec, catalog);
+            const existing = externalPins.get(depName);
+            if (existing !== undefined && existing !== resolvedSpec) {
+                throw new Error(`resolveSourceWorkflowClosure: workspace members pin external ${JSON.stringify(depName)} at conflicting ranges ${JSON.stringify(existing)} and ${JSON.stringify(resolvedSpec)}; the closure resolves a single range per name`);
+            }
+            externalPins.set(depName, resolvedSpec);
+        }
+    }
+    const externalEntries = externalPins.size > 0
+        ? await resolveExternalClosure(externalPins, registryName, registryConfig, fetchPackument)
+        : [];
+    return {
+        schemaVersion: "1",
+        topLevel: [{ name: selected.name, version: selected.version }],
+        entries: mergeDisjoint(sourceEntries, externalEntries),
+    };
+}
+/**
+ * Read the workspace members from the asset's tree. A repo with no
+ * `workspaces` field is a single package rooted at the tree (the root IS the
+ * one member). A `workspaces` monorepo enumerates its members from the globs;
+ * the root is the workspace root, NOT a member -- its `name`/`catalog` inform
+ * dependency classification but it contributes no closure entry.
+ */
+async function enumerateMembers(reads) {
+    const root = await readPackageJSON(reads, ".");
+    if (root.workspaces === undefined) {
+        // A pnpm monorepo declares its members in `pnpm-workspace.yaml`, not the
+        // package.json `workspaces` field, so a pnpm root reaches here looking like
+        // a single package. Detect that layout and fail loud rather than silently
+        // misread the private root as the workflow. Full pnpm support is tracked in
+        // INTR-461.
+        if (await rootHasPnpmWorkspaceFile(reads)) {
+            throw new Error(`resolveSourceWorkflowClosure: the asset root declares a pnpm-workspace.yaml; the pnpm workspace layout is not supported -- declare members via a package.json "workspaces" array`);
+        }
+        // Single-package: the root is the workflow package itself, so it must
+        // declare a name and version.
+        const member = requireMember(root, ".");
+        return {
+            members: new Map([[member.name, member]]),
+            rootName: root.name,
+            catalog: root.catalog,
+        };
+    }
+    const members = new Map();
+    for (const glob of root.workspaces) {
+        for (const packageDir of await expandWorkspaceGlob(reads, glob)) {
+            // A `<dir>/*` glob matches every subdirectory, but not all are packages
+            // (docs, fixtures, ...). Skip a directory with no package.json rather than
+            // fail the whole resolution, matching how bun/yarn/pnpm treat a
+            // non-package directory that a workspace glob happens to match. A
+            // directory that HAS a package.json must still parse and declare a name
+            // and version, so a malformed member fails loud.
+            if (!(await dirHasPackageJSON(reads, packageDir)))
+                continue;
+            const parsed = await readPackageJSON(reads, packageDir);
+            const member = requireMember(parsed, packageDir);
+            if (members.has(member.name)) {
+                throw new Error(`resolveSourceWorkflowClosure: workspace member ${JSON.stringify(member.name)} is declared by more than one package directory`);
+            }
+            members.set(member.name, member);
+        }
+    }
+    if (members.size === 0) {
+        throw new Error(`resolveSourceWorkflowClosure: workspaces ${JSON.stringify(root.workspaces)} matched no member packages`);
+    }
+    return { members, rootName: root.name, catalog: root.catalog };
+}
+/**
+ * Turn a parsed package.json at `packageDir` into a workspace member, failing
+ * loud if it does not declare both a string `name` and `version` (the closure
+ * entry it produces is keyed on `name@version`).
+ */
+function requireMember(parsed, packageDir) {
+    if (parsed.name === undefined || parsed.version === undefined) {
+        const blobPath = packageDir === "." ? "package.json" : `${packageDir}/package.json`;
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} must declare string "name" and "version"`);
+    }
+    return {
+        name: parsed.name,
+        version: parsed.version,
+        packageDir,
+        dependencies: parsed.dependencies,
+    };
+}
+/**
+ * Expand one `workspaces` glob to the member directories it names. Supports
+ * `<base>/*` (each subtree directly under `<base>`) and an exact path (no glob
+ * character). Any richer shape (`**`, a mid-segment `*`, braces, negation)
+ * fails loud rather than risk mis-enumerating the workspace.
+ */
+async function expandWorkspaceGlob(reads, glob) {
+    const trimmed = glob.replace(/\/+$/, "");
+    if (!/[*{}!]/.test(trimmed)) {
+        return [trimmed];
+    }
+    const suffix = "/*";
+    const base = trimmed.slice(0, -suffix.length);
+    if (trimmed.endsWith(suffix) && !/[*{}!]/.test(base)) {
+        const children = await reads.listDir(base === "" ? "." : base);
+        return children
+            .filter((child) => child.type === "tree")
+            .map((child) => (base === "" ? child.name : `${base}/${child.name}`));
+    }
+    throw new Error(`resolveSourceWorkflowClosure: unsupported workspaces glob ${JSON.stringify(glob)}; only "<dir>/*" and exact paths are supported`);
+}
+/** Whether `dir` holds a `package.json` blob (i.e. is a package directory). */
+async function dirHasPackageJSON(reads, dir) {
+    const entries = await reads.listDir(dir);
+    return entries.some((entry) => entry.name === "package.json" && entry.type === "blob");
+}
+/** Whether the tree root holds a `pnpm-workspace.yaml` blob (the pnpm layout). */
+async function rootHasPnpmWorkspaceFile(reads) {
+    const entries = await reads.listDir(".");
+    return entries.some((entry) => entry.name === "pnpm-workspace.yaml" && entry.type === "blob");
+}
+function selectMember(members, packageName) {
+    if (packageName !== undefined) {
+        const member = members.get(packageName);
+        if (member === undefined) {
+            throw new Error(`resolveSourceWorkflowClosure: workflow member ${JSON.stringify(packageName)} is not a workspace member`);
+        }
+        return member;
+    }
+    if (members.size !== 1) {
+        throw new Error("resolveSourceWorkflowClosure: a monorepo source requires a packageName selector");
+    }
+    const [only] = members.values();
+    if (only === undefined) {
+        throw new Error("resolveSourceWorkflowClosure: internal -- no members");
+    }
+    return only;
+}
+async function readPackageJSON(reads, packageDir) {
+    const blobPath = packageDir === "." ? "package.json" : `${packageDir}/package.json`;
+    let bytes;
+    try {
+        bytes = await reads.readBlob(blobPath);
+    }
+    catch (err) {
+        throw new Error(`resolveSourceWorkflowClosure: could not read ${blobPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (err) {
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!isRecord(raw)) {
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} is not an object`);
+    }
+    // `name`/`version` are optional here: a private workspace root routinely
+    // omits them. A member that omits either fails loud where it is turned into a
+    // WorkspaceMember (`requireMember`), not here.
+    const nameRaw = raw["name"];
+    const versionRaw = raw["version"];
+    const name = typeof nameRaw === "string" ? nameRaw : undefined;
+    const version = typeof versionRaw === "string" ? versionRaw : undefined;
+    const depsRaw = raw["dependencies"];
+    const dependencies = {};
+    if (isRecord(depsRaw)) {
+        for (const [k, v] of Object.entries(depsRaw)) {
+            if (typeof v === "string")
+                dependencies[k] = v;
+        }
+    }
+    const workspacesRaw = raw["workspaces"];
+    let workspaces;
+    if (workspacesRaw === undefined) {
+        workspaces = undefined;
+    }
+    else if (Array.isArray(workspacesRaw) &&
+        workspacesRaw.every((w) => typeof w === "string")) {
+        workspaces = workspacesRaw;
+    }
+    else {
+        throw new Error(`resolveSourceWorkflowClosure: ${blobPath} "workspaces" must be an array of glob strings; the object form ({ packages, catalog, catalogs }) is not supported`);
+    }
+    const catalogRaw = raw["catalog"];
+    let catalog;
+    if (isRecord(catalogRaw)) {
+        catalog = {};
+        for (const [k, v] of Object.entries(catalogRaw)) {
+            if (typeof v === "string")
+                catalog[k] = v;
+        }
+    }
+    return { name, version, dependencies, workspaces, catalog };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Translate an EXTERNAL dependency specifier (one whose name is not a workspace
+ * member) to a concrete npm range the registry walker can pick against:
+ *   - `workspace:` protocol -- the name is not a member, so this is an invalid
+ *     workspace reference; fail loud.
+ *   - bare `catalog:` -- expand against the root `catalog` object; fail loud if
+ *     the catalog declares no entry for this name.
+ *   - named `catalog:<name>` -- not supported; fail loud.
+ *   - plain range -- pass through.
+ */
+function resolveExternalSpec(depName, spec, catalog) {
+    if (spec.startsWith("workspace:")) {
+        throw new Error(`resolveSourceWorkflowClosure: ${depName} uses ${JSON.stringify(spec)} but is not a workspace member`);
+    }
+    if (spec === "catalog:") {
+        const range = catalog?.[depName];
+        if (range === undefined) {
+            throw new Error(`resolveSourceWorkflowClosure: ${depName} uses the default catalog but the workspace root declares no "catalog" entry for it`);
+        }
+        return range;
+    }
+    if (spec.startsWith("catalog:")) {
+        throw new Error(`resolveSourceWorkflowClosure: ${depName} uses named catalog ${JSON.stringify(spec)}, which is not supported`);
+    }
+    return spec;
+}
+async function resolveExternalClosure(pins, registryName, registryConfig, fetchPackument) {
+    const registrySource = new HttpRegistrySource({
+        name: registryName,
+        config: registryConfig,
+        ...(fetchPackument !== undefined ? { fetchPackument } : {}),
+    });
+    const resolver = createClosureResolver({
+        registries: new Map([[registryName, registrySource]]),
+        defaultRegistry: registryName,
+    });
+    const rootPins = [...pins].map(([name, version]) => ({
+        name,
+        version,
+    }));
+    const manifest = await resolver.resolveClosure(rootPins);
+    return [...manifest.entries];
+}
+/**
+ * Union the source and external entries, deduped on `name@version`. A key that
+ * appears in BOTH origins is an unrepresentable collision (the manifest keys on
+ * `name@version` with neither treeOid nor SRI participating), so fail loud
+ * rather than silently picking one origin.
+ */
+function mergeDisjoint(sourceEntries, externalEntries) {
+    const byKey = new Map();
+    for (const entry of sourceEntries) {
+        byKey.set(`${entry.name}@${entry.version}`, entry);
+    }
+    for (const entry of externalEntries) {
+        const key = `${entry.name}@${entry.version}`;
+        if (byKey.has(key)) {
+            throw new Error(`resolveSourceWorkflowClosure: ${key} resolved from both a workspace member and an external registry; the closure cannot represent both origins`);
+        }
+        byKey.set(key, entry);
+    }
+    return [...byKey.values()];
+}

package/dist/ws/index.d.ts

@@ -0,0 +1,3 @@
+export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SidecarConnection, type SidecarAuthIdentity, type SidecarAuthenticator, type AllocatedSidecarTarget, type SidecarAllocationRouter, type SendPackOptions, type WsHandle, } from "./sidecar-handler.js";
+export { createSidecarCredentialResolver, createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, } from "./sidecar-token-authenticator.js";
+export { createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedRow, type SidecarMailPersistedPayload, type MailTriggeredRunGrantsResult, type WorkflowRunPackSource, } from "./sidecar-events.js";

package/dist/ws/index.js

@@ -0,0 +1,3 @@
+export { createSidecarRouter, } from "./sidecar-handler.js";
+export { createSidecarCredentialResolver, createSidecarTokenAuthenticator, } from "./sidecar-token-authenticator.js";
+export { createSidecarEmitter, } from "./sidecar-events.js";