hammerkit 1.6.0-alpha.3 → 1.7.0

package/dist/cache/explain.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainWorkTree = exports.explainTask = exports.describeCause = void 0;
+const state_key_1 = require("../executer/scheduler/state-key");
+const work_task_cache_description_1 = require("../optimizer/work-task-cache-description");
+const get_cache_directory_1 = require("../optimizer/get-cache-directory");
+const last_resolved_1 = require("./last-resolved");
+const work_instance_id_1 = require("../planner/work-instance-id");
+function describeCause(cause) {
+    switch (cause.kind) {
+        case 'no-src':
+            return 'no src declared (uncacheable)';
+        case 'no-src-files':
+            return 'src matches no files (uncacheable)';
+        case 'dependency-uncacheable':
+            return `dependency always runs: ${cause.identifier}`;
+        case 'caching-disabled':
+            return 'caching disabled';
+        case 'never-cached':
+            return 'never cached';
+        case 'cache-format-changed':
+            return 'cache format changed';
+        case 'source-changed':
+            return `source changed: ${cause.identifier}`;
+        case 'source-added':
+            return `source added: ${cause.identifier}`;
+        case 'source-removed':
+            return `source removed: ${cause.identifier}`;
+        case 'env-changed':
+            return `environment variable changed: ${cause.identifier}`;
+        case 'command-changed':
+            return 'command changed';
+        case 'image-changed':
+            return 'image changed';
+        case 'dependency-changed':
+            return `dependency changed: ${cause.identifier}`;
+    }
+}
+exports.describeCause = describeCause;
+async function safeCurrentStateKey(item, environment) {
+    // currentStateKey is read-only (a file read for local, a container *list* for
+    // docker/k8s — never a start). If the runtime is unreachable (offline, no
+    // daemon) explain must still answer, so failures degrade to "no runtime state".
+    try {
+        return await item.runtime.currentStateKey(environment);
+    }
+    catch {
+        return null;
+    }
+}
+async function safeHas(item, stateKey, environment) {
+    try {
+        return await item.data.caching.backend.has(item.id(), stateKey, environment);
+    }
+    catch {
+        return false;
+    }
+}
+function diffDescription(current, previous, causes) {
+    if (JSON.stringify(current.cmds) !== JSON.stringify(previous.cmds)) {
+        causes.push({ kind: 'command-changed' });
+    }
+    if (current.image !== previous.image) {
+        causes.push({ kind: 'image-changed' });
+    }
+    // shell / mounts / cwd / generates all alter how the task runs; the closed
+    // cause vocabulary folds them into "command changed".
+    if (current.shell !== previous.shell ||
+        JSON.stringify(current.mounts) !== JSON.stringify(previous.mounts) ||
+        current.cwd !== previous.cwd ||
+        JSON.stringify(current.generates) !== JSON.stringify(previous.generates)) {
+        if (!causes.some((c) => c.kind === 'command-changed')) {
+            causes.push({ kind: 'command-changed' });
+        }
+    }
+    const currentEnvs = current.envs ?? {};
+    const previousEnvs = previous.envs ?? {};
+    const envKeys = Array.from(new Set([...Object.keys(currentEnvs), ...Object.keys(previousEnvs)])).sort();
+    for (const key of envKeys) {
+        if (currentEnvs[key] !== previousEnvs[key]) {
+            causes.push({ kind: 'env-changed', identifier: key });
+        }
+    }
+}
+function diffStats(current, previous, method, causes) {
+    const currentFiles = current.files ?? {};
+    const previousFiles = previous.files ?? {};
+    const paths = Array.from(new Set([...Object.keys(currentFiles), ...Object.keys(previousFiles)])).sort();
+    for (const path of paths) {
+        const now = currentFiles[path];
+        const before = previousFiles[path];
+        if (now && !before) {
+            causes.push({ kind: 'source-added', identifier: path });
+        }
+        else if (!now && before) {
+            causes.push({ kind: 'source-removed', identifier: path });
+        }
+        else if (now && before) {
+            const changed = method === 'modify-date' ? now.lastModified !== before.lastModified : now.checksum !== before.checksum;
+            if (changed) {
+                causes.push({ kind: 'source-changed', identifier: path });
+            }
+        }
+    }
+}
+function isAlwaysRun(explanation) {
+    return (explanation.status === 'uncacheable' &&
+        explanation.causes.some((c) => c.kind === 'no-src' || c.kind === 'no-src-files' || c.kind === 'dependency-uncacheable'));
+}
+// Explain a single task, recursively explaining its dependencies so a downstream
+// task whose own inputs are unchanged is attributed to the upstream dependency
+// that actually changed. Memoized by task id; `visiting` guards against a cyclic
+// graph (already rejected by the planner, but explain runs before scheduling).
+async function explainTask(item, defaultCacheMethod, environment, memo = new Map(), visiting = new Set()) {
+    const existing = memo.get(item.id());
+    if (existing) {
+        return existing;
+    }
+    if (visiting.has(item.id())) {
+        // Cycle: report neutrally rather than recursing forever.
+        return { taskId: item.id(), taskName: item.name, status: 'miss', causes: [{ kind: 'never-cached' }] };
+    }
+    visiting.add(item.id());
+    const { stateKey, stats, resolved, provable, unmatched } = await (0, state_key_1.computeStateKey)(item, defaultCacheMethod, environment);
+    // Mirrors the scheduler: a task that cannot be proven up to date always runs
+    // (see computeStateKey), whatever a cache holds for it.
+    if (!provable) {
+        const causes = [];
+        const declared = item.data.src.filter((src) => !src.inherited);
+        if (declared.length === 0) {
+            causes.push({ kind: 'no-src' });
+        }
+        else if (unmatched.length === declared.length) {
+            causes.push({ kind: 'no-src-files' });
+        }
+        for (const dep of item.deps) {
+            const depExplanation = await explainTask(dep, defaultCacheMethod, environment, memo, visiting);
+            if (isAlwaysRun(depExplanation)) {
+                causes.push({ kind: 'dependency-uncacheable', identifier: dep.name });
+            }
+        }
+        const explanation = { taskId: item.id(), taskName: item.name, status: 'uncacheable', causes };
+        memo.set(item.id(), explanation);
+        visiting.delete(item.id());
+        return explanation;
+    }
+    if (resolved.method === 'none') {
+        const explanation = {
+            taskId: item.id(),
+            taskName: item.name,
+            status: 'uncacheable',
+            causes: [{ kind: 'caching-disabled' }],
+        };
+        memo.set(item.id(), explanation);
+        visiting.delete(item.id());
+        return explanation;
+    }
+    const runtimeStateKey = await safeCurrentStateKey(item, environment);
+    const hasEntry = await safeHas(item, stateKey, environment);
+    const predictedHit = runtimeStateKey === stateKey || hasEntry;
+    if (predictedHit) {
+        const explanation = { taskId: item.id(), taskName: item.name, status: 'hit', causes: [] };
+        memo.set(item.id(), explanation);
+        visiting.delete(item.id());
+        return explanation;
+    }
+    const causes = [];
+    const record = await (0, last_resolved_1.readLastResolvedRecord)(environment, item);
+    if (record === null) {
+        const legacyDesc = await environment.file.exists((0, get_cache_directory_1.getCacheDescriptionFile)((0, work_instance_id_1.getWorkInstanceId)(item)));
+        if (runtimeStateKey === null && !hasEntry && !legacyDesc) {
+            causes.push({ kind: 'never-cached' });
+        }
+        else {
+            // Prior evidence of a run, but no diffable breakdown (pre-feature entry).
+            causes.push({ kind: 'cache-format-changed' });
+        }
+    }
+    else {
+        // records store env values as digests, so compare in the stored form
+        diffDescription((0, work_task_cache_description_1.storedCacheDescription)((0, work_task_cache_description_1.getWorkTaskCacheDescription)(item)), record.description, causes);
+        diffStats(stats, record.stats, resolved.method, causes);
+    }
+    for (const dep of item.deps) {
+        const depExplanation = await explainTask(dep, defaultCacheMethod, environment, memo, visiting);
+        if (depExplanation.status !== 'hit') {
+            causes.push({ kind: 'dependency-changed', identifier: dep.name });
+        }
+    }
+    if (causes.length === 0) {
+        // A miss we could not attribute (e.g. the artifact was pruned/evicted though
+        // metadata records a prior run) — treat as no usable cache entry.
+        causes.push({ kind: 'never-cached' });
+    }
+    const explanation = { taskId: item.id(), taskName: item.name, status: 'miss', causes };
+    memo.set(item.id(), explanation);
+    visiting.delete(item.id());
+    return explanation;
+}
+exports.explainTask = explainTask;
+// Explain every task in scope (the work tree already includes dependencies),
+// deterministically ordered by name. Read-only: executes no command, starts no
+// container/service, performs no cache push/pull (only metadata `has` lookups).
+async function explainWorkTree(workTree, defaultCacheMethod, environment) {
+    const memo = new Map();
+    const tasks = Object.values(workTree.tasks).sort((a, b) => a.name.localeCompare(b.name));
+    const results = [];
+    for (const task of tasks) {
+        results.push(await explainTask(task, defaultCacheMethod, environment, memo));
+    }
+    return results;
+}
+exports.explainWorkTree = explainWorkTree;
+//# sourceMappingURL=explain.js.map

package/dist/cache/last-resolved.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readLastResolvedRecord = exports.writeLastResolvedRecord = exports.getLastResolvedFile = void 0;
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const work_task_cache_description_1 = require("../optimizer/work-task-cache-description");
+// Stored in the project's `.hammerkit` dir (local-first, alongside the local
+// runtime state file) keyed by task name. The name is sanitized for the
+// filesystem and suffixed with a hash of the full name to avoid collisions
+// between names that sanitize to the same string (e.g. referenced `lib:build`).
+function getLastResolvedFile(task) {
+    const sanitized = task.name.replace(/[^a-z0-9-_]+/gi, '_').slice(0, 80);
+    const suffix = (0, crypto_1.createHash)('sha1').update(task.name).digest('hex').slice(0, 8);
+    return (0, path_1.join)(task.data.cwd, '.hammerkit', 'last-resolved', `${sanitized}-${suffix}.json`);
+}
+exports.getLastResolvedFile = getLastResolvedFile;
+async function writeLastResolvedRecord(environment, task, record) {
+    const file = getLastResolvedFile(task);
+    await environment.file.createDirectory((0, path_1.join)(task.data.cwd, '.hammerkit', 'last-resolved'));
+    const payload = {
+        taskId: task.id(),
+        taskName: task.name,
+        description: (0, work_task_cache_description_1.storedCacheDescription)(record.description),
+        stats: record.stats,
+    };
+    await environment.file.writeFile(file, JSON.stringify(payload));
+}
+exports.writeLastResolvedRecord = writeLastResolvedRecord;
+async function readLastResolvedRecord(environment, task) {
+    const file = getLastResolvedFile(task);
+    if (!(await environment.file.exists(file))) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(await environment.file.read(file));
+        // A record written by an older hammerkit (or otherwise truncated) lacks the
+        // component breakdown explain needs — signal that rather than crashing.
+        if (!parsed || typeof parsed !== 'object' || !parsed.description || !parsed.stats) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+exports.readLastResolvedRecord = readLastResolvedRecord;
+//# sourceMappingURL=last-resolved.js.map

package/dist/cache/read-only.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCacheReadOnly = exports.CACHE_READ_ONLY_ENV = void 0;
+exports.CACHE_READ_ONLY_ENV = 'HAMMERKIT_CACHE_READ_ONLY';
+// Read-only is on when the flag is passed or the env var is set to a truthy
+// value, so a sandbox image can enforce it once for every invocation.
+function isCacheReadOnly(flag, processEnvs) {
+    if (flag) {
+        return true;
+    }
+    const value = (processEnvs[exports.CACHE_READ_ONLY_ENV] ?? '').trim().toLowerCase();
+    return value !== '' && value !== '0' && value !== 'false' && value !== 'no';
+}
+exports.isCacheReadOnly = isCacheReadOnly;
+//# sourceMappingURL=read-only.js.map

package/dist/cache/retention.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planRetention = void 0;
+function recency(entry) {
+    return entry.lastAccessedAt ?? entry.createdAt;
+}
+// most recent first; entries without a timestamp count as the oldest
+function byRecencyDesc(a, b) {
+    return (recency(b) ?? -Infinity) - (recency(a) ?? -Infinity);
+}
+const entries = (count) => `${count} ${count === 1 ? 'entry' : 'entries'}`;
+// Decide which cache entries a retention policy evicts. Pure: listing and
+// removing is the caller's job. Applied in order keepPerTask → maxAge →
+// maxSize, each on what the previous step kept. Evicting never causes a false
+// hit, only a rebuild.
+function planRetention(all, policy, now) {
+    const evict = [];
+    const unavailable = [];
+    let keep = [...all];
+    if (policy.keepPerTask !== undefined) {
+        const byTask = new Map();
+        for (const entry of keep) {
+            byTask.set(entry.taskId, [...(byTask.get(entry.taskId) ?? []), entry]);
+        }
+        keep = [];
+        for (const versions of byTask.values()) {
+            versions.sort(byRecencyDesc);
+            keep.push(...versions.slice(0, policy.keepPerTask));
+            evict.push(...versions.slice(policy.keepPerTask));
+        }
+    }
+    if (policy.maxAge !== undefined) {
+        const maxAge = policy.maxAge;
+        const undated = keep.filter((entry) => recency(entry) === null);
+        if (undated.length > 0) {
+            unavailable.push(`max-age: ${entries(undated.length)} ${undated.length === 1 ? 'has' : 'have'} no timestamp and ${undated.length === 1 ? 'was' : 'were'} kept`);
+        }
+        evict.push(...keep.filter((entry) => recency(entry) !== null && now - recency(entry) > maxAge));
+        keep = keep.filter((entry) => !evict.includes(entry));
+    }
+    if (policy.maxSize !== undefined) {
+        const unsized = keep.filter((entry) => entry.size === null);
+        if (unsized.length > 0) {
+            unavailable.push(`max-size: the backend cannot report the size of ${entries(unsized.length)}`);
+        }
+        else {
+            let total = keep.reduce((sum, entry) => sum + entry.size, 0);
+            for (const entry of [...keep].sort(byRecencyDesc).reverse()) {
+                if (total <= policy.maxSize) {
+                    break;
+                }
+                evict.push(entry);
+                total -= entry.size;
+            }
+            keep = keep.filter((entry) => !evict.includes(entry));
+        }
+    }
+    return { keep, evict, unavailable };
+}
+exports.planRetention = planRetention;
+//# sourceMappingURL=retention.js.map

package/dist/cli.js

@@ -14,6 +14,11 @@ const get_scheduler_execute_result_1 = require("./executer/get-scheduler-execute
 const reset_work_tree_1 = require("./executer/reset-work-tree");
 const execute_work_tree_1 = require("./executer/execute-work-tree");
 const package_1 = require("./docker/package");
+const explain_1 = require("./cache/explain");
+const work_graph_serializer_1 = require("./planner/work-graph-serializer");
+const dry_run_1 = require("./executer/dry-run");
+const cache_sync_1 = require("./cache/cache-sync");
+const cache_inventory_1 = require("./cache/cache-inventory");
 const isCliTask = (val) => val.type === 'task';
 exports.isCliTask = isCliTask;
 const isCliService = (val) => val.type === 'service';
@@ -48,6 +53,10 @@ class Cli {
                         workers: options?.workers ?? 0,
                         processManager,
                         type,
+                        explain: options?.explain ?? false,
+                        cacheReadOnly: options?.cacheReadOnly ?? false,
+                        timeout: options?.timeout ?? null,
+                        skipDeps: options?.skipDeps ?? true,
                     });
                 }
                 const result = (0, get_scheduler_execute_result_1.getSchedulerExecuteResult)(workTree);
@@ -104,6 +113,40 @@ class Cli {
     validate() {
         return (0, validate_1.validate)(this.workTree, this.environment);
     }
+    // Read-only cache prediction for every task in scope: executes no command,
+    // starts no container/service, performs no cache push/pull.
+    async explain(options) {
+        return (0, explain_1.explainWorkTree)(this.workTree, options?.cacheDefault ?? 'checksum', this.environment);
+    }
+    // Serialize the in-scope work graph for rendering (mermaid/dot). Pure read of
+    // the planner's graph — nothing executes.
+    graph(format) {
+        return (0, work_graph_serializer_1.serializeWorkGraph)(this.workTree, format);
+    }
+    // Ordered execution plan with predicted cache decisions, reusing the explain
+    // engine — executes nothing, starts nothing, performs no cache push/pull.
+    async dryRun(options) {
+        return (0, dry_run_1.planDryRun)(this.workTree, options?.cacheDefault ?? 'checksum', this.environment);
+    }
+    // Move cache entries between the tasks' own caches and a named remote without
+    // executing anything (`cache pull` / `cache push`).
+    async syncCache(options) {
+        return (0, cache_sync_1.syncCache)(this.workTree, options, this.environment);
+    }
+    // Entries of a named cache (default: the local `default` cache).
+    async listCache(cacheName) {
+        return (0, cache_inventory_1.listCache)(this.workTree, cacheName, this.environment);
+    }
+    retentionPolicy(cacheName, overrides) {
+        return (0, cache_inventory_1.retentionPolicyOf)(this.workTree, cacheName, overrides);
+    }
+    async pruneCache(cacheName, policy, dryRun = false) {
+        return (0, cache_inventory_1.pruneCache)(this.workTree, cacheName, policy, { dryRun }, this.environment);
+    }
+    // Apply declared retention to the local caches this build file uses.
+    async autoPrune() {
+        return (0, cache_inventory_1.autoPrune)(this.workTree, this.environment);
+    }
     task(name) {
         const task = this.workTree.tasks[name];
         if (!task) {

package/dist/docker/using-container.js

@@ -4,6 +4,7 @@ exports.usingContainer = void 0;
 const remove_container_1 = require("./remove-container");
 const log_1 = require("../log");
 const execute_docker_1 = require("../executer/execute-docker");
+const work_instance_id_1 = require("../planner/work-instance-id");
 async function usingContainer(docker, item, createOptions, stateKey, callback) {
     let container = null;
     let succeeded = false;
@@ -22,7 +23,10 @@ async function usingContainer(docker, item, createOptions, stateKey, callback) {
                 if (container) {
                     await container.pause();
                 }
-                const containers = await docker.listContainers({ all: true, filters: { label: [`hammerkit-id=${item.id()}`] } });
+                const containers = await docker.listContainers({
+                    all: true,
+                    filters: { label: [`hammerkit-id=${(0, work_instance_id_1.getWorkInstanceId)(item)}`] },
+                });
                 for (const container of containers) {
                     item.status.write('debug', `found container ${container.Id}`);
                     if (container.Labels['hammerkit-state'] != stateKey) {

package/dist/executer/archive-task-entry.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.archiveTaskEntry = void 0;
+const get_cache_directory_1 = require("../optimizer/get-cache-directory");
+const work_instance_id_1 = require("../planner/work-instance-id");
+const get_work_cache_stats_1 = require("../optimizer/get-work-cache-stats");
+const cache_metadata_1 = require("./cache-metadata");
+const work_task_cache_description_1 = require("../optimizer/work-task-cache-description");
+// Package a task's current outputs as a cache entry (metadata + output
+// archives) in its staging directory, and return that directory for a backend
+// to push from. Used after a task ran, and by `cache push` for a task whose
+// outputs are up to date in this checkout but were never stored in a backend.
+async function archiveTaskEntry(work, environment) {
+    const cacheDir = (0, get_cache_directory_1.getCacheDirectory)((0, work_instance_id_1.getWorkInstanceId)(work));
+    const { stats } = await (0, get_work_cache_stats_1.getWorkItemCacheStats)(work, environment);
+    await (0, cache_metadata_1.writeCacheMetadata)(environment, work, stats, (0, work_task_cache_description_1.getWorkTaskCacheDescription)(work));
+    await work.runtime.archive(environment, cacheDir);
+    return cacheDir;
+}
+exports.archiveTaskEntry = archiveTaskEntry;
+//# sourceMappingURL=archive-task-entry.js.map

package/dist/executer/await-completed-dependencies.js

@@ -1,19 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.awaitRunningNeeds = exports.awaitRunningNeed = exports.awaitCompleted = exports.awaitCompletedDependencies = exports.awaitNoRequirements = exports.awaitRequirement = void 0;
+exports.awaitRunningNeeds = exports.awaitRunningNeed = exports.awaitCompleted = exports.awaitCompletedDependencies = exports.awaitNoRequirements = exports.awaitDependentNeed = exports.awaitRequirement = void 0;
 const work_item_1 = require("../planner/work-item");
 const state_resolver_1 = require("./state-resolver");
-async function awaitRequirement(svc, abort) {
-    await Promise.race(svc.requiredBy.map((required) => {
-        if ((0, work_item_1.isWorkTaskItem)(required)) {
-            return (0, state_resolver_1.awaitState)('await-requirement', required.state, (state) => state.type === 'ready', abort);
-        }
-        else {
-            return (0, state_resolver_1.awaitState)('await-requirement', required.state, (state) => state.type === 'ready', abort);
-        }
-    }));
+// Resolve true once any requirer is `ready` (about to run). With
+// `untilAllDone`, resolve false instead when every requirer has finished
+// without needing the service — e.g. all of them were cache hits — so the
+// service is never started.
+async function awaitRequirement(svc, abort, options = { untilAllDone: false }) {
+    const ready = Promise.race(svc.requiredBy.map((required) => (0, state_resolver_1.awaitState)('await-requirement', required.state, (state) => state.type === 'ready', abort))).then(() => true);
+    if (!options.untilAllDone) {
+        return ready;
+    }
+    const allDone = awaitNoRequirements(svc, abort).then(() => false);
+    return Promise.race([ready, allDone]);
 }
 exports.awaitRequirement = awaitRequirement;
+// Resolve true once any dependent is `ready` — it missed the cache and is about
+// to run, so it needs this task's outputs — and false once every dependent
+// finished without needing it (all cache hits, or skipped themselves).
+async function awaitDependentNeed(dependents, abort) {
+    const ready = Promise.race(dependents.map((dependent) => (0, state_resolver_1.awaitState)('await-dependent', dependent.state, (s) => s.type === 'ready', abort))).then(() => true);
+    const allDone = Promise.all(dependents.map((dependent) => (0, state_resolver_1.awaitState)('await-dependent-done', dependent.state, (s) => s.type === 'completed' || s.type === 'error' || s.type === 'crash' || s.type === 'canceled', abort))).then(() => false);
+    return Promise.race([ready, allDone]);
+}
+exports.awaitDependentNeed = awaitDependentNeed;
 async function awaitNoRequirements(svc, abort) {
     await Promise.all(svc.requiredBy.map((required) => {
         if ((0, work_item_1.isWorkTaskItem)(required)) {
@@ -36,8 +47,15 @@ function awaitCompleted(work, dep, abort) {
     return (0, state_resolver_1.isState)('await-completed-' + work.name, dep.state, isCompleted, abort);
 }
 exports.awaitCompleted = awaitCompleted;
-function awaitRunningNeed(work, dep, abort) {
-    return (0, state_resolver_1.isState)('await-running-need-' + work.name, dep.state, isRunning, abort);
+// Wait for a needed service to run. A service that reaches a terminal state
+// first (it failed to start or exited) can never become ready, so the waiting
+// item fails instead of waiting forever.
+async function awaitRunningNeed(work, dep, abort) {
+    const state = await (0, state_resolver_1.isState)('await-running-need-' + work.name, dep.state, isRunningOrDone, abort);
+    if (state.type !== 'running') {
+        throw new Error(`needed service ${dep.name} ${state.type === 'end' ? 'stopped' : 'failed'} before it was ready`);
+    }
+    return state;
 }
 exports.awaitRunningNeed = awaitRunningNeed;
 async function awaitRunningNeeds(work, needs, abort) {
@@ -50,7 +68,7 @@ exports.awaitRunningNeeds = awaitRunningNeeds;
 function isCompleted(val) {
     return val.type === 'completed';
 }
-function isRunning(val) {
-    return val.type === 'running';
+function isRunningOrDone(val) {
+    return val.type === 'running' || val.type === 'end' || val.type === 'error' || val.type === 'canceled';
 }
 //# sourceMappingURL=await-completed-dependencies.js.map

package/dist/executer/cache-metadata.js

@@ -2,10 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeCacheMetadata = void 0;
 const get_cache_directory_1 = require("../optimizer/get-cache-directory");
-async function writeCacheMetadata(environment, taskId, stats, description) {
+const work_task_cache_description_1 = require("../optimizer/work-task-cache-description");
+const last_resolved_1 = require("../cache/last-resolved");
+const work_instance_id_1 = require("../planner/work-instance-id");
+async function writeCacheMetadata(environment, task, stats, description) {
+    const taskId = (0, work_instance_id_1.getWorkInstanceId)(task);
     await environment.file.createDirectory((0, get_cache_directory_1.getCacheDirectory)(taskId));
     await environment.file.writeFile((0, get_cache_directory_1.getCacheStatsFile)(taskId), JSON.stringify(stats));
-    await environment.file.writeFile((0, get_cache_directory_1.getCacheDescriptionFile)(taskId), JSON.stringify(description));
+    await environment.file.writeFile((0, get_cache_directory_1.getCacheDescriptionFile)(taskId), JSON.stringify((0, work_task_cache_description_1.storedCacheDescription)(description)));
+    // Additive per-task-name record for `explain` — never affects the hit/miss
+    // decision, written wherever the id-keyed metadata is.
+    await (0, last_resolved_1.writeLastResolvedRecord)(environment, task, { description, stats });
 }
 exports.writeCacheMetadata = writeCacheMetadata;
 //# sourceMappingURL=cache-metadata.js.map

package/dist/executer/docker-service.js

@@ -12,6 +12,7 @@ const execution_steps_1 = require("./execution-steps");
 const docker_task_1 = require("./docker-task");
 const replace_env_variables_1 = require("../environment/replace-env-variables");
 const get_service_containers_1 = require("./get-service-containers");
+const work_instance_id_1 = require("../planner/work-instance-id");
 async function dockerService(docker, item, options, environment) {
     let container = null;
     try {
@@ -30,7 +31,7 @@ async function dockerService(docker, item, options, environment) {
             Env: Object.keys(envs).map((k) => `${k}=${envs[k]}`),
             Labels: {
                 app: 'hammerkit',
-                'hammerkit-id': item.id(),
+                'hammerkit-id': (0, work_instance_id_1.getWorkInstanceId)(item),
                 'hammerkit-pid': process.pid.toString(),
                 'hammerkit-type': 'service',
                 'hammerkit-state': options.stateKey,

package/dist/executer/docker-task.js

@@ -12,6 +12,7 @@ const tar_1 = require("tar");
 const replace_env_variables_1 = require("../environment/replace-env-variables");
 const get_container_binds_1 = require("./get-container-binds");
 const get_service_containers_1 = require("./get-service-containers");
+const work_instance_id_1 = require("../planner/work-instance-id");
 function getNeedsNetwork(serviceContainers, needs) {
     const links = [];
     const hosts = [];
@@ -44,7 +45,7 @@ function buildCreateOptions(item, stateKey, serviceContainers, environment) {
         WorkingDir: (0, execute_docker_1.convertToPosixPath)(item.data.cwd),
         Labels: {
             app: 'hammerkit',
-            'hammerkit-id': item.id(),
+            'hammerkit-id': (0, work_instance_id_1.getWorkInstanceId)(item),
             'hammerkit-pid': process.pid.toString(),
             'hammerkit-type': 'task',
             'hammerkit-state': stateKey,

package/dist/executer/dry-run.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printDryRun = exports.planDryRun = void 0;
+const colors_1 = __importDefault(require("colors"));
+const validate_1 = require("../planner/validate");
+const explain_1 = require("../cache/explain");
+const log_1 = require("../log");
+// Deterministic topological order (dependencies before dependents). Visited-set
+// guards against runaway recursion; a real cycle is reported separately.
+function topoOrder(workTree) {
+    const visited = new Set();
+    const order = [];
+    const visit = (task) => {
+        if (visited.has(task.id())) {
+            return;
+        }
+        visited.add(task.id());
+        for (const dep of [...task.deps].sort((a, b) => a.name.localeCompare(b.name))) {
+            visit(dep);
+        }
+        order.push(task);
+    };
+    for (const task of Object.values(workTree.tasks).sort((a, b) => a.name.localeCompare(b.name))) {
+        visit(task);
+    }
+    return order;
+}
+// Compute the ordered execution plan with a predicted cache decision per task,
+// reusing the cache-explain engine — no command runs, no container/service
+// starts, no cache push/pull occurs.
+async function planDryRun(workTree, defaultCacheMethod, environment) {
+    for (const task of Object.values(workTree.tasks)) {
+        const path = (0, validate_1.hasDependencyCycle)(task, []);
+        if (path && path.length > 0) {
+            return { entries: [], cycle: path.map((n) => n.name) };
+        }
+    }
+    const explanations = await (0, explain_1.explainWorkTree)(workTree, defaultCacheMethod, environment);
+    const byName = new Map(explanations.map((e) => [e.taskName, e]));
+    const entries = [];
+    for (const task of topoOrder(workTree)) {
+        const explanation = byName.get(task.name);
+        entries.push({
+            taskId: task.id(),
+            taskName: task.name,
+            status: explanation?.status ?? 'miss',
+            causes: explanation?.causes ?? [],
+        });
+    }
+    return { entries, cycle: null };
+}
+exports.planDryRun = planDryRun;
+function printDryRun(environment, plan) {
+    (0, log_1.printTitle)(environment, 'Dry run (no commands executed)');
+    if (plan.entries.length === 0) {
+        environment.stdout.write('  no tasks in scope\n');
+        return;
+    }
+    plan.entries.forEach((entry, index) => {
+        const label = entry.status === 'hit'
+            ? colors_1.default.green('cache hit')
+            : entry.status === 'uncacheable'
+                ? colors_1.default.grey('uncacheable')
+                : colors_1.default.yellow('cache miss');
+        const causes = entry.causes.length > 0 ? colors_1.default.grey(` (${entry.causes.map(explain_1.describeCause).join(', ')})`) : '';
+        environment.stdout.write(`  ${index + 1}. ${entry.taskName}: ${label}${causes}\n`);
+    });
+}
+exports.printDryRun = printDryRun;
+//# sourceMappingURL=dry-run.js.map