@vibesdotdev/infra-deploy 1.0.0-rc.6 → 1.0.0-rc.8

package/dist/cli/shared/build-workspace-artifacts.js

@@ -1,6 +1,6 @@
 import { satisfies, validRange } from 'semver';
 import * as z from 'zod/v4';
-import { CapabilityError, settle } from '@vibesdotdev/kernel';
+import { CapabilityError, settle, settleNow } from '@vibesdotdev/kernel';
 import { JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
 import { planDag } from '@vibesdotdev/shared/schemas';
 import { resolveHash } from '@vibesdotdev/crypto';
@@ -274,7 +274,7 @@ async function readAppManifest(host, path) {
 }
 /** The errno facts a raw host absence carries. */
 const ErrnoCodeSchema = z.object({ code: z.string().optional() }).loose();
-function isMissingPathError(error) {
+export function isMissingPathError(error) {
     if (error instanceof CapabilityError && error.code === 'NOT_FOUND')
         return true;
     const facts = ErrnoCodeSchema.safeParse(error);
@@ -502,7 +502,7 @@ async function collectTsconfigInputs(host, packageRoot, artifactsDir, configPath
  * every `tsconfig*.json` (and their `extends`/`include` targets), tool config
  * files (`vite.config.*`, `svelte.config.*`, ...), `scripts/`, every file the
  * selected build script names, and every non-test, non-hidden file under
- * `src/`. Workspace dependencies are folded in by {@link effectiveSourceHash}.
+ * `src/`. Workspace dependencies enter through the stamp's traces ({@link currentTraces}).
  */
 async function packageBuildInputs(host, pkg) {
     const packageRoot = pkg.dir;
@@ -548,155 +548,108 @@ async function computePackageSourceHash(host, packageRoot) {
     }
     return hash.digestHex();
 }
-/** One memo for the build inputs and hashes read in a plan or independent postflight. */
-const effectiveHashMemos = new WeakMap();
-function dependencyHashMemo(ownHashes) {
-    let memo = effectiveHashMemos.get(ownHashes);
-    if (!memo) {
-        memo = { effective: new Map(), edges: new Map() };
-        effectiveHashMemos.set(ownHashes, memo);
-    }
-    return memo;
-}
-function buildDependencyNames(host, pkg, packages, memo) {
-    let pending = memo.edges.get(pkg.name);
+function buildDependencyNames(host, pkg, packages, context) {
+    let pending = context.edges.get(pkg.name);
     if (!pending) {
         pending = workspaceDependencyEdges(host, pkg, packages)
             .then(({ inputs }) => inputs.filter((name) => packages.has(name)));
-        memo.edges.set(pkg.name, pending);
+        context.edges.set(pkg.name, pending);
     }
     return pending;
 }
-/**
- * A package's own source hash folded with its workspace dependencies'
- * effective hashes, computed once per package in linear time.
- *
- * Packages that import each other (a tolerated mutual-import cycle) form a
- * strongly connected component; every member's hash covers the whole
- * component and everything it depends on, so the result does not depend on
- * which package the walk started from. A package outside any cycle hashes
- * exactly as it always has: its own hash, then `\0name\0effective` for each
- * declared dependency in order.
- */
-async function effectiveSourceHash(host, pkg, packages, ownHashes) {
-    const scope = dependencyHashMemo(ownHashes);
-    const memo = scope.effective;
-    const known = memo.get(pkg.name);
-    if (known !== undefined)
-        return known;
-    // Hash the planner's build inputs. Imported optional peers participate in
-    // freshness without becoming required members of the build closure.
-    const graph = new Map();
-    const pending = [pkg.name];
-    const queued = new Set(pending);
+function createTraceContext() {
+    return { ownHashes: new Map(), edges: new Map(), outputs: new Map(), verdicts: new Map() };
+}
+/** `name`'s artifacts directory was replaced: its output and every verdict that read it are stale. */
+function forgetArtifacts(context, name) {
+    context.outputs.delete(name);
+    context.verdicts.clear();
+}
+async function ownSourceHash(host, pkg, context) {
+    let own = context.ownHashes.get(pkg.name);
+    if (own === undefined) {
+        own = await computePackageSourceHash(host, pkg.dir);
+        context.ownHashes.set(pkg.name, own);
+    }
+    return own;
+}
+/** Every workspace package `pkg` reaches through build-input edges, itself excluded, sorted. */
+async function buildInputClosure(host, pkg, packages, context) {
+    if (!packages)
+        return [];
+    const reached = new Set();
+    const pending = [pkg];
     for (let cursor = 0; cursor < pending.length; cursor += 1) {
-        const name = pending[cursor];
-        if (memo.has(name))
-            continue;
-        const dependencies = await buildDependencyNames(host, packages.get(name), packages, scope);
-        graph.set(name, dependencies);
-        for (const dependency of dependencies) {
-            if (memo.has(dependency) || queued.has(dependency))
+        for (const name of await buildDependencyNames(host, pending[cursor], packages, context)) {
+            if (reached.has(name))
                 continue;
-            queued.add(dependency);
-            pending.push(dependency);
-        }
-    }
-    // Another concurrent writer may have completed this component during I/O.
-    const completed = memo.get(pkg.name);
-    if (completed !== undefined)
-        return completed;
-    const edges = (name) => graph.get(name) ?? [];
-    // Tarjan's SCC over the packages reachable from `pkg` that are not yet
-    // memoized; components come out dependencies-first.
-    const index = new Map();
-    const low = new Map();
-    const onStack = new Set();
-    const stack = [];
-    const components = [];
-    let counter = 0;
-    const connect = (name) => {
-        index.set(name, counter);
-        low.set(name, counter);
-        counter += 1;
-        stack.push(name);
-        onStack.add(name);
-        for (const dep of edges(name)) {
-            if (memo.has(dep))
+            reached.add(name);
+            pending.push(packages.get(name));
+        }
+    }
+    reached.delete(pkg.name);
+    return [...reached].sort();
+}
+/** The hash of every file under `artifactsDirectory` except the stamp and incremental build state. */
+async function computeOutputHash(host, artifactsDirectory) {
+    if (!(await host.files.exists(artifactsDirectory)))
+        return 'absent';
+    const files = [];
+    const visit = async (directory) => {
+        for (const entry of await host.files.list(directory)) {
+            const absolute = host.paths.join(directory, entry.name);
+            if (entry.kind === 'directory') {
+                await visit(absolute);
                 continue;
-            if (!index.has(dep)) {
-                connect(dep);
-                low.set(name, Math.min(low.get(name), low.get(dep)));
-            }
-            else if (onStack.has(dep)) {
-                low.set(name, Math.min(low.get(name), index.get(dep)));
             }
+            const path = toPosixPath(host, host.paths.relative(artifactsDirectory, absolute));
+            if (path === BUILD_STAMP_FILENAME || path.endsWith('.tsbuildinfo'))
+                continue;
+            files.push({ path, absolute });
         }
-        if (low.get(name) === index.get(name)) {
-            const component = [];
-            let member;
-            do {
-                member = stack.pop();
-                onStack.delete(member);
-                component.push(member);
-            } while (member !== name);
-            components.push(component);
-        }
-    };
-    connect(pkg.name);
-    const ownOf = async (name) => {
-        let own = ownHashes.get(name);
-        if (own === undefined) {
-            own = await computePackageSourceHash(host, packages.get(name).dir);
-            ownHashes.set(name, own);
-        }
-        return own;
     };
-    for (const component of components) {
-        const members = new Set(component);
-        const selfLoop = component.length === 1 && edges(component[0]).includes(component[0]);
-        if (component.length === 1 && !selfLoop) {
-            const name = component[0];
-            const hash = host.sha256().update(await ownOf(name));
-            for (const dep of edges(name))
-                hash.update(`\0${dep}\0${memo.get(dep)}`);
-            memo.set(name, hash.digestHex());
-            continue;
-        }
-        // One hash for the whole component: every member's own hash and every
-        // dependency the component reaches outside itself, in a fixed order.
-        const componentHash = host.sha256().update('scc');
-        for (const name of [...component].sort())
-            componentHash.update(`\0${name}\0${await ownOf(name)}`);
-        const external = new Set();
-        for (const name of component)
-            for (const dep of edges(name))
-                if (!members.has(dep))
-                    external.add(dep);
-        for (const dep of [...external].sort())
-            componentHash.update(`\0dep\0${dep}\0${memo.get(dep)}`);
-        const shared = componentHash.digestHex();
-        // Publish the whole component without yielding: concurrent walks must
-        // never observe only part of a cycle as memoized.
-        for (const name of component) {
-            memo.set(name, host.sha256().update(ownHashes.get(name)).update(`\0scc\0${shared}`).digestHex());
-        }
-    }
-    return memo.get(pkg.name);
-}
-/** What a stamp records about a package's workspace dependencies: name -> effective source hash. */
-const RecordedDependencyHashesSchema = z.record(z.string(), z.string());
-async function workspaceDependencyHashes(host, pkg, packages, ownHashes) {
-    const recorded = {};
+    await visit(artifactsDirectory);
+    if (files.length === 0)
+        return 'absent';
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const hash = host.sha256().update('outputs');
+    for (const file of files) {
+        const fileHash = host.sha256().update(await readBytes(host.files, file.absolute)).digestHex();
+        hash.update(`\0${file.path}\0${fileHash}`);
+    }
+    return hash.digestHex();
+}
+function outputHashOf(host, pkg, context) {
+    let pending = context.outputs.get(pkg.name);
+    if (!pending) {
+        pending = computeOutputHash(host, host.paths.join(pkg.dir, resolveArtifactsDir(pkg)));
+        context.outputs.set(pkg.name, pending);
+    }
+    return pending;
+}
+/**
+ * What a dependent's build consumed from `pkg`: the bytes it emitted, or for a
+ * package that builds nothing, its own sources.
+ */
+async function traceOf(host, pkg, context) {
+    return hasBuildArtifacts(pkg)
+        ? `output:${await outputHashOf(host, pkg, context)}`
+        : `source:${await ownSourceHash(host, pkg, context)}`;
+}
+/** The current trace of every package in `pkg`'s build-input closure. */
+async function currentTraces(host, pkg, packages, context) {
+    const traces = {};
     if (!packages)
-        return recorded;
-    for (const name of await buildDependencyNames(host, pkg, packages, dependencyHashMemo(ownHashes))) {
-        const dependency = packages.get(name);
-        if (!dependency)
-            continue;
-        recorded[name] = await effectiveSourceHash(host, dependency, packages, ownHashes);
+        return traces;
+    for (const name of await buildInputClosure(host, pkg, packages, context)) {
+        traces[name] = await traceOf(host, packages.get(name), context);
     }
-    return recorded;
+    return traces;
+}
+/** The first closure member whose recorded trace differs from `current`, if any. */
+function changedTrace(recorded, current) {
+    const names = new Set([...Object.keys(recorded), ...Object.keys(current)]);
+    return [...names].sort().find((name) => recorded[name] !== current[name]);
 }
 /** Every file the build emitted under the artifacts directory (the stamp itself excluded). */
 async function listEmittedFiles(host, artifactsDirectory) {
@@ -744,18 +697,22 @@ async function removeBuildStamp(host, pkg) {
     await removeIfPresent(host.files, host.paths.join(pkg.dir, resolveArtifactsDir(pkg), BUILD_STAMP_FILENAME));
 }
 /**
- * Records a successful build: the source content hash it was built from and the
- * exact files it emitted. Callers write it only after the build exited 0.
+ * Records a successful build: the source content hash it was built from, the
+ * traces of its build-input closure as they stand now, and the exact files it
+ * emitted. Callers write it only after the build exited 0 and, inside a
+ * cycle, only once the whole component settled.
  */
 export async function writeBuildOkStamp(packageDir, 
 /** The runtime whose logger reports a build input the hash could only read as bytes. */
-runtime, packages, dependencySourceHashes = new Map()) {
+runtime, packages, context = createTraceContext()) {
     const host = await resolveArtifactHost(runtime);
     const pkg = await readPackageManifest(host, packageDir);
     const artifactsDirectory = host.paths.join(pkg.dir, resolveArtifactsDir(pkg));
+    forgetArtifacts(context, pkg.name);
     const stamp = {
-        sourceHash: await computePackageSourceHash(host, pkg.dir),
-        dependencies: await workspaceDependencyHashes(host, pkg, packages, dependencySourceHashes),
+        sourceHash: await ownSourceHash(host, pkg, context),
+        traces: await currentTraces(host, pkg, packages, context),
+        outputHash: await outputHashOf(host, pkg, context),
         toolVersions: declaredToolVersions(pkg.packageJson),
         files: await listEmittedFiles(host, artifactsDirectory)
     };
@@ -769,7 +726,8 @@ runtime, packages, dependencySourceHashes = new Map()) {
 /** The admitted shape of a build stamp, parsed once at the boundary. */
 const BuildStampSchema = z.object({
     sourceHash: z.string(),
-    dependencies: z.record(z.string(), z.string()),
+    traces: z.record(z.string(), z.string()),
+    outputHash: z.string(),
     toolVersions: z.record(z.string(), z.string()),
     files: z.array(z.object({ path: z.string(), size: z.number() }).loose())
 }).loose();
@@ -777,11 +735,12 @@ function parseBuildStamp(text) {
     const parsed = BuildStampSchema.safeParse(JSON.parse(text));
     if (parsed.success) {
         // The schema admits extra keys from older and newer writers; the stamp
-        // is the four typed fields, constructed explicitly instead of cast.
-        const { sourceHash, dependencies, toolVersions, files } = parsed.data;
+        // is the five typed fields, constructed explicitly instead of cast.
+        const { sourceHash, traces, outputHash, toolVersions, files } = parsed.data;
         return {
             sourceHash,
-            dependencies,
+            traces,
+            outputHash,
             toolVersions,
             files: files.map((file) => ({ path: file.path, size: file.size }))
         };
@@ -793,13 +752,47 @@ function parseBuildStamp(text) {
 /**
  * The single freshness decision every caller shares: `assertDeployWorkspacePreflight`
  * uses it to refuse a deploy over stale inputs, and the build orchestration
- * below uses the same predicate to skip a closure member that never went
- * stale. Fresh means a build-success stamp exists, its source hash equals the
- * hash of the package's current build inputs, and every file it lists still
- * exists at the recorded size. There is no timestamp heuristic: a package with
- * no stamp (never built, failed build, interrupted build) is not fresh.
+ * below uses the same predicate to skip or restore a closure member. Fresh
+ * means the package's own build is valid ({@link checkOwnBuild}) and so is
+ * every package in its build-input closure: a trace only vouches for a
+ * dependency whose own build still matches its sources. There is no
+ * timestamp heuristic: a package with no stamp (never built, failed build,
+ * interrupted build) is not fresh.
  */
-async function checkWorkspacePackageFreshness(host, pkg, packages, ownHashes = new Map()) {
+async function checkWorkspacePackageFreshness(host, pkg, packages, context = createTraceContext()) {
+    const own = await checkOwnBuild(host, pkg, packages, context);
+    if (!own.fresh || !packages)
+        return own;
+    for (const name of await buildInputClosure(host, pkg, packages, context)) {
+        const dependency = packages.get(name);
+        if (!hasBuildArtifacts(dependency))
+            continue;
+        const verdict = await checkOwnBuild(host, dependency, packages, context);
+        if (!verdict.fresh) {
+            return {
+                ...own,
+                fresh: false,
+                reason: `workspace dependency ${name} changed since the last successful build (${verdict.reason})`
+            };
+        }
+    }
+    return own;
+}
+/**
+ * One package's own build, judged alone: a build-success stamp exists, its
+ * source hash equals the hash of the package's current build inputs, every
+ * closure trace it recorded equals that package's trace now, and the emitted
+ * files are still the recorded bytes.
+ */
+function checkOwnBuild(host, pkg, packages, context) {
+    let verdict = context.verdicts.get(pkg.name);
+    if (!verdict) {
+        verdict = judgeOwnBuild(host, pkg, packages, context);
+        context.verdicts.set(pkg.name, verdict);
+    }
+    return verdict;
+}
+async function judgeOwnBuild(host, pkg, packages, context) {
     const resolvedPackageRoot = await realpathChecked(host.files, pkg.dir);
     const artifactsDir = resolveArtifactsDir(pkg);
     const artifactsDirectory = host.paths.join(resolvedPackageRoot, artifactsDir);
@@ -825,16 +818,12 @@ async function checkWorkspacePackageFreshness(host, pkg, packages, ownHashes = n
         return result(`${artifactsDir}/${BUILD_STAMP_FILENAME} is not a valid build stamp`);
     if (stamp.files.length === 0)
         return result(`${artifactsDir}/${BUILD_STAMP_FILENAME} lists no emitted files`);
-    if (stamp.sourceHash !== (await computePackageSourceHash(host, resolvedPackageRoot))) {
+    if (stamp.sourceHash !== (await ownSourceHash(host, pkg, context))) {
         return result(`package sources changed since the last successful build`);
     }
-    const currentDependencies = await workspaceDependencyHashes(host, pkg, packages, ownHashes);
-    const dependencyNames = new Set([...Object.keys(stamp.dependencies), ...Object.keys(currentDependencies)]);
-    for (const name of [...dependencyNames].sort()) {
-        if (stamp.dependencies[name] !== currentDependencies[name]) {
-            return result(`workspace dependency ${name} changed since the last successful build`);
-        }
-    }
+    const changed = changedTrace(stamp.traces, await currentTraces(host, pkg, packages, context));
+    if (changed !== undefined)
+        return result(`workspace dependency ${changed} changed since the last successful build`);
     for (const file of stamp.files) {
         const path = host.paths.join(artifactsDirectory, file.path);
         if (!isPathWithin(host, artifactsDirectory, path)) {
@@ -854,6 +843,9 @@ async function checkWorkspacePackageFreshness(host, pkg, packages, ownHashes = n
             return result(`emitted file changed size (${file.size} -> ${size}): ${artifactsDir}/${file.path}`);
         }
     }
+    if (stamp.outputHash !== (await outputHashOf(host, pkg, context))) {
+        return result(`${artifactsDir} no longer holds the bytes its build emitted`);
+    }
     const buildInfoReason = await typeScriptBuildInfoRefusal(host, host.paths.join(artifactsDirectory, TYPESCRIPT_BUILD_INFO_FILENAME));
     if (buildInfoReason)
         return result(buildInfoReason);
@@ -888,7 +880,7 @@ async function typeScriptBuildInfoRefusal(host, tsBuildInfoPath) {
     }
     return undefined;
 }
-async function buildPackage(host, workspaceRoot, pkg, execution, packages, dependencySourceHashes, onLine) {
+async function buildPackage(host, workspaceRoot, pkg, execution, onLine) {
     const scriptName = resolveBuildScriptName(pkg);
     onLine?.('stdout', `[workspace-artifacts] building ${pkg.name}`);
     const diagnostics = createWorkspaceDiagnosticTail();
@@ -920,7 +912,6 @@ async function buildPackage(host, workspaceRoot, pkg, execution, packages, depen
         throw new Error(`Workspace artifact build failed for ${pkg.name} (exit=${result.code ?? 'unknown'})\n` +
             `Compiler diagnostics (redacted tail):\n${diagnostics.render()}`);
     }
-    await writeBuildOkStamp(pkg.dir, host.runtime, packages, dependencySourceHashes);
 }
 /** A failed build leaves neither its stamp nor its incremental state, so the next run rebuilds from scratch. */
 async function invalidateFailedBuild(host, pkg) {
@@ -933,11 +924,10 @@ async function invalidateFailedBuild(host, pkg) {
  * Independent branches of the dependency graph (declared or source-discovered
  * edges, the same edge set the planner used) run concurrently; a mutual-import
  * cycle — the class `orderCycleMembersByWorkspaceDependencies` already
- * resolves into one contiguous, order-sensitive run — still builds its
- * members serially, in the plan's existing order, so a tolerated cycle's
- * behaviour is unchanged. `run` decides per package whether to actually spawn
- * a build (it applies the freshness skip); this function only owns the safe
- * scheduling.
+ * resolves into one contiguous run — is handed to `run` whole, in the plan's
+ * existing order, once every component it depends on has settled. `run`
+ * decides which members actually spawn a build; this function only owns the
+ * safe scheduling.
  */
 async function runWorkspaceBuildPlan(host, plan, packages, concurrency, run) {
     if (plan.length === 0)
@@ -977,8 +967,7 @@ async function runWorkspaceBuildPlan(host, plan, packages, concurrency, run) {
         // combined rejection and completion always advances the scheduler.
         const runComponent = async (index) => {
             const outcome = await settle(async () => {
-                for (const pkg of components[index].members)
-                    await run(pkg);
+                await run(components[index].members);
             });
             if (!outcome.ok)
                 fail(outcome.cause);
@@ -1060,37 +1049,164 @@ function groupWorkspaceBuildPlanIntoComponents(plan, dependenciesOf) {
         dependsOn: dependsOnByComponent.get(component) ?? new Set()
     }));
 }
-/** Independent workspace package builds run this many at a time (see `runWorkspaceBuildPlan`). */
+/** Independent workspace package builds run this many at a time when the host reports no resources. */
 const DEFAULT_WORKSPACE_BUILD_CONCURRENCY = 4;
+/** One package build (tsc over the dependency graph's declarations) holds about this much memory. */
+const WORKSPACE_BUILD_MEMORY_BYTES = 4 * 1024 ** 3;
+/**
+ * Size the build to the host it runs on: half its cores, no more builds than its memory
+ * holds, never below the default.
+ */
+function workspaceBuildConcurrency(host) {
+    const resources = host.runtime.environment?.systemResources?.();
+    if (!resources)
+        return DEFAULT_WORKSPACE_BUILD_CONCURRENCY;
+    const byCpu = Math.floor(resources.cpuCount / 2);
+    const byMemory = Math.floor(resources.totalMemoryBytes / WORKSPACE_BUILD_MEMORY_BYTES);
+    return Math.max(DEFAULT_WORKSPACE_BUILD_CONCURRENCY, Math.min(byCpu, byMemory));
+}
 async function buildWorkspacePlanWithFreshnessSkip(host, workspaceRoot, plan, packages, execution, onLine, artifactStore) {
-    // Source hashes do not change while a plan builds (builds emit only into artifact directories).
-    const ownHashes = new Map();
+    const context = createTraceContext();
     const store = artifactStore ?? resolveWorkspaceArtifactStore(host.runtime, host.files, host.paths);
     const tools = await installedToolVersions(host, workspaceRoot);
-    await runWorkspaceBuildPlan(host, plan, packages, DEFAULT_WORKSPACE_BUILD_CONCURRENCY, async (pkg) => {
-        const freshness = await checkWorkspacePackageFreshness(host, pkg, packages, ownHashes);
-        // The graph decides what changed: a package whose effective hash (its inputs and every
-        // workspace dependency's) was built before is restored, and only then trusted by the
-        // same freshness predicate a local build passes.
-        const key = await artifactStoreKey(host, pkg, packages, ownHashes, tools);
-        const artifactsDirectory = host.paths.join(pkg.dir, resolveArtifactsDir(pkg));
-        if (freshness.fresh) {
-            onLine?.('stdout', `[workspace-artifacts] skip ${pkg.name}: ${freshness.artifactsDir} is already fresh`);
-            // A fresh local build is the build for this hash; another checkout restores it.
-            await store.save(pkg.name, key, artifactsDirectory);
-            return;
+    await runWorkspaceBuildPlan(host, plan, packages, workspaceBuildConcurrency(host), (members) => settleWorkspaceComponent(host, workspaceRoot, members, packages, execution, context, store, tools, onLine));
+}
+/**
+ * Settles one component (a lone package, or every member of an import cycle)
+ * once everything it depends on has settled.
+ *
+ * Each member reuses a build of its current sources (the one on disk, else a
+ * stored one) whose recorded traces agree with the settled packages below and
+ * with the builds already chosen for earlier members; a member with none
+ * builds. Builds read workspace dependencies from source, so a member built in
+ * this run is right whatever its siblings' artifacts hold; a reused member is
+ * right only if its traces still agree once the component's artifacts are in
+ * place, so any that disagree rebuild, until none do. Each pass turns at least
+ * one reuse into a build, so this ends. Stamps for the members built here are
+ * written last, recording the settled traces.
+ */
+async function settleWorkspaceComponent(host, workspaceRoot, members, packages, execution, context, store, tools, onLine) {
+    const memberNames = new Set(members.map((pkg) => pkg.name));
+    const ownKeys = new Map();
+    const options = new Map();
+    for (const pkg of members) {
+        const own = await ownSourceHash(host, pkg, context);
+        const ownKey = host.sha256().update(`workspace-artifacts\0v2\0${own}\0${tools}`).digestHex();
+        ownKeys.set(pkg.name, ownKey);
+        const current = await currentTraces(host, pkg, packages, context);
+        // Outside the component everything has settled, so a reusable build agrees with it exactly.
+        const agreesBelow = (stamp) => {
+            if (stamp.sourceHash !== own)
+                return false;
+            const names = new Set([...Object.keys(stamp.traces), ...Object.keys(current)]);
+            return [...names].every((name) => memberNames.has(name) || stamp.traces[name] === current[name]);
+        };
+        const reusable = [];
+        const onDisk = await readStampOnDisk(host, pkg);
+        if (onDisk && onDisk.outputHash === (await outputHashOf(host, pkg, context)) && agreesBelow(onDisk)) {
+            reusable.push({ stamp: onDisk });
+        }
+        for (const entry of await store.entries(pkg.name, ownKey, BUILD_STAMP_FILENAME)) {
+            const stamp = parseStoredStamp(entry.text);
+            if (stamp && agreesBelow(stamp))
+                reusable.push({ stamp, key: entry.key });
+        }
+        options.set(pkg.name, reusable);
+    }
+    // Inside the component, drop a build that traced a sibling output no reusable
+    // build of that sibling has. A sibling with none builds; its output is checked
+    // after it builds.
+    const satisfiable = (build) => Object.entries(build.stamp.traces).every(([name, trace]) => {
+        const sibling = memberNames.has(name) ? options.get(name) : [];
+        return sibling.length === 0 || sibling.some((other) => trace === `output:${other.stamp.outputHash}`);
+    });
+    for (let pruned = true; pruned;) {
+        pruned = false;
+        for (const pkg of members) {
+            const reusable = options.get(pkg.name);
+            const kept = reusable.filter(satisfiable);
+            if (kept.length === reusable.length)
+                continue;
+            options.set(pkg.name, kept);
+            pruned = true;
+        }
+    }
+    // Choose in plan order, each agreeing both ways with the builds chosen before it.
+    const chosen = new Map();
+    for (const pkg of members) {
+        const pick = options.get(pkg.name).find((build) => [...chosen].every(([name, other]) => (build.stamp.traces[name] === undefined || build.stamp.traces[name] === `output:${other.stamp.outputHash}`) &&
+            (other.stamp.traces[pkg.name] === undefined || other.stamp.traces[pkg.name] === `output:${build.stamp.outputHash}`)));
+        if (pick)
+            chosen.set(pkg.name, pick);
+    }
+    const built = new Set();
+    const build = async (pkg) => {
+        await buildPackage(host, workspaceRoot, pkg, execution, onLine);
+        forgetArtifacts(context, pkg.name);
+        built.add(pkg.name);
+    };
+    for (const pkg of members) {
+        const reuse = chosen.get(pkg.name);
+        if (!reuse)
+            continue;
+        if (reuse.key === undefined) {
+            onLine?.('stdout', `[workspace-artifacts] skip ${pkg.name}: ${resolveArtifactsDir(pkg)} is already fresh`);
+            continue;
         }
-        if (await store.restore(pkg.name, key, artifactsDirectory)) {
-            const restored = await checkWorkspacePackageFreshness(host, pkg, packages, ownHashes);
-            if (restored.fresh) {
-                onLine?.('stdout', `[workspace-artifacts] restore ${pkg.name}: built before at this source hash`);
-                return;
-            }
-            onLine?.('stdout', `[workspace-artifacts] rebuild ${pkg.name}: the stored build is not fresh (${restored.reason})`);
+        if (await store.restore(pkg.name, reuse.key, host.paths.join(pkg.dir, resolveArtifactsDir(pkg)))) {
+            forgetArtifacts(context, pkg.name);
+            onLine?.('stdout', `[workspace-artifacts] restore ${pkg.name}: built before from these sources and inputs`);
         }
-        await buildPackage(host, workspaceRoot, pkg, execution, packages, ownHashes, onLine);
-        await store.save(pkg.name, key, artifactsDirectory);
-    });
+        else {
+            chosen.delete(pkg.name);
+        }
+    }
+    for (const pkg of members)
+        if (!chosen.has(pkg.name))
+            await build(pkg);
+    for (;;) {
+        const disagreeing = [];
+        for (const pkg of members) {
+            if (built.has(pkg.name))
+                continue;
+            const verdict = await checkOwnBuild(host, pkg, packages, context);
+            if (verdict.fresh)
+                continue;
+            onLine?.('stdout', `[workspace-artifacts] rebuild ${pkg.name}: ${verdict.reason}`);
+            disagreeing.push(pkg);
+        }
+        if (disagreeing.length === 0)
+            break;
+        for (const pkg of disagreeing)
+            await build(pkg);
+    }
+    for (const pkg of members) {
+        const artifactsDirectory = host.paths.join(pkg.dir, resolveArtifactsDir(pkg));
+        const stamp = built.has(pkg.name)
+            ? await writeBuildOkStamp(pkg.dir, host.runtime, packages, context)
+            : chosen.get(pkg.name).stamp;
+        // A stored entry is the build for its key; a fresh build or a reused local one is stored for other checkouts.
+        if (!built.has(pkg.name) && chosen.get(pkg.name).key !== undefined)
+            continue;
+        await store.save(pkg.name, `${ownKeys.get(pkg.name)}/${tracesKey(host, stamp.traces)}`, artifactsDirectory);
+    }
+}
+function tracesKey(host, traces) {
+    const hash = host.sha256().update('traces');
+    for (const name of Object.keys(traces).sort())
+        hash.update(`\0${name}\0${traces[name]}`);
+    return hash.digestHex();
+}
+async function readStampOnDisk(host, pkg) {
+    const path = host.paths.join(pkg.dir, resolveArtifactsDir(pkg), BUILD_STAMP_FILENAME);
+    if (!(await host.files.exists(path)))
+        return undefined;
+    return parseStoredStamp(await readText(host.files, path));
+}
+/** A stamp read from disk or the store; one that does not parse is no candidate. */
+function parseStoredStamp(text) {
+    const parsed = settleNow(() => parseBuildStamp(text));
+    return parsed.ok ? parsed.value : undefined;
 }
 /**
  * The resolved versions of the toolchain a build runs (from the workspace install),
@@ -1104,11 +1220,6 @@ async function installedToolVersions(host, workspaceRoot) {
     }
     return JSON.stringify(versions);
 }
-/** A package build's store identity: its effective source hash and the installed toolchain. */
-async function artifactStoreKey(host, pkg, packages, ownHashes, tools) {
-    const effective = await effectiveSourceHash(host, pkg, packages, ownHashes);
-    return host.sha256().update(`workspace-artifacts\0v1\0${effective}\0${tools}`).digestHex();
-}
 async function discoverSvelteKitApps(host, workspaceRoot) {
     const appsRoot = host.paths.join(workspaceRoot, 'apps');
     if (!(await host.files.exists(appsRoot)))
@@ -1743,13 +1854,13 @@ export async function assertDeployWorkspacePreflight({ workspaceRoot, runtime, a
     if (artifactPolicy === 'planned-build') {
         return { warnings };
     }
-    const ownHashes = new Map();
+    const context = createTraceContext();
     for (const pkg of packageClosure.filter(hasBuildArtifacts)) {
         // Single source of truth: the same predicate that decides whether the
         // build orchestration below may skip this package's build (see
         // `checkWorkspacePackageFreshness`) decides whether this postflight
         // assertion accepts it as a valid deploy input.
-        const freshness = await checkWorkspacePackageFreshness(host, pkg, workspacePackages, ownHashes);
+        const freshness = await checkWorkspacePackageFreshness(host, pkg, workspacePackages, context);
         if (freshness.fresh)
             continue;
         if (freshness.artifactsMissing) {