hammerkit 1.27.0-next.8 → 2.0.0-next.1

package/dist/dashboard/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#059669"/><path d="M9 8h4v6h6V8h4v16h-4v-6h-6v6H9z" fill="#fff"/></svg>

package/dist/dashboard/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <title>hammerkit</title>
+    <script type="module" crossorigin src="/assets/index-zPXa4klZ.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CjnKm5-3.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/docker/item-network.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeOrphanedNetworks = exports.removeItemNetworks = exports.getNetworkHostConfig = exports.removeItemNetwork = exports.prepareItemNetwork = exports.checkNetworkLimitSupport = exports.getProxyNetworkName = exports.getRunNetworkName = exports.getItemNetworkName = void 0;
+exports.removeOrphanedNetworks = exports.removeItemNetworks = exports.getNetworkHostConfig = exports.getPortBinding = exports.removeItemNetwork = exports.prepareItemNetwork = exports.checkNetworkLimitSupport = exports.getProxyNetworkName = exports.getRunNetworkName = exports.getItemNetworkName = void 0;
 const readline_1 = require("readline");
 const stream_1 = require("stream");
 const work_service_1 = require("../planner/work-service");
@@ -258,7 +258,7 @@ options) {
         await removeItemNetwork(docker, name);
         throw e;
     }
-    const publish = (options.publish ?? []).filter((port) => !!port.hostPort);
+    const publish = (options.publish ?? []).filter((port) => port.hostPort !== null);
     return {
         options: {
             mode: name,
@@ -272,8 +272,9 @@ options) {
                     await docker.getNetwork(getProxyNetworkName(name)).connect({ Container: container.id });
                 }
                 if (publish.length > 0) {
-                    await startPortRelay(docker, item, environment, name, container, publish, options);
+                    return await startPortRelay(docker, item, environment, name, container, publish, options);
                 }
+                return undefined;
             }
             catch (e) {
                 await removeItemNetwork(docker, name);
@@ -374,12 +375,13 @@ async function startPortRelay(docker, item, environment, networkName, service, p
         ExposedPorts: Object.fromEntries(ports.map((port) => [`${port.containerPort}/tcp`, {}])),
         HostConfig: {
             ...HELPER_HOST_CONFIG,
-            PortBindings: Object.fromEntries(ports.map((port) => [`${port.containerPort}/tcp`, [{ HostPort: `${port.hostPort}` }]])),
+            PortBindings: Object.fromEntries(ports.map((port) => [`${port.containerPort}/tcp`, [getPortBinding(port)]])),
         },
     });
     await docker.getNetwork(networkName).connect({ Container: container.id });
     await container.start();
-    item.status.write('debug', `ports ${ports.map((port) => port.hostPort).join(', ')} published by a relay`);
+    item.status.write('debug', `ports ${ports.map((port) => port.hostPort || 'any').join(', ')} published by a relay`);
+    return container;
 }
 // The network, its proxy network, its proxy and relay, and every endpoint on
 // them: what an earlier run left behind, or what the item used.
@@ -429,6 +431,12 @@ async function removeNetwork(docker, name) {
         }
     }
 }
+// A port of the host for a port of a container: a free one for 0, on one address of it
+// when the port names one.
+function getPortBinding(port) {
+    return { HostPort: port.hostPort ? `${port.hostPort}` : '', ...(port.hostIp ? { HostIp: port.hostIp } : {}) };
+}
+exports.getPortBinding = getPortBinding;
 function getNetworkHostConfig(network) {
     return {
         ...(network.mode ? { NetworkMode: network.mode } : {}),

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

@@ -10,11 +10,13 @@ const work_task_cache_description_1 = require("../optimizer/work-task-cache-desc
 // 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) {
+async function archiveTaskEntry(work, environment, 
+// the state the outputs are of, by default the one the task is at
+stateKey = work.state.current.stateKey) {
     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);
+    await work.runtime.archive(environment, cacheDir, stateKey ?? undefined);
     return cacheDir;
 }
 exports.archiveTaskEntry = archiveTaskEntry;

package/dist/executer/deadline.js

@@ -1,14 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withDeadline = void 0;
+exports.withDeadline = exports.getTaskTimeout = void 0;
 const abort_event_1 = require("../utils/abort-event");
+// How long a task may run: its own `timeout`, else the run's default (`--timeout`), and
+// never longer than the run's cap (`--max-timeout`), which also covers tasks with a
+// longer timeout of their own. A caller can shorten a task this way, never extend it.
+function getTaskTimeout(own, run) {
+    const timeout = own ?? run.timeout;
+    if (run.maxTimeout === null) {
+        return timeout;
+    }
+    return timeout === null ? run.maxTimeout : Math.min(timeout, run.maxTimeout);
+}
+exports.getTaskTimeout = getTaskTimeout;
+// the longest delay of setTimeout: Node fires a longer one after 1 ms
+const MAX_TIMER_MS = 2 ** 31 - 1;
 // An abort signal that follows `parent` and additionally fires after `timeout`
-// ms, so a task deadline reuses the runtimes' existing abort/cleanup path.
+// ms, so a task deadline reuses the runtimes' existing abort/cleanup path. A
+// timeout beyond what a timer can wait (about 24.8 days) sets no deadline.
 function withDeadline(parent, timeout) {
     const controller = new AbortController();
     let expired = false;
     const parentListener = (0, abort_event_1.listenOnAbort)(parent, () => controller.abort());
-    const timer = timeout === null
+    const timer = timeout === null || timeout > MAX_TIMER_MS
         ? null
         : setTimeout(() => {
             expired = true;

package/dist/executer/deferred-restore.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreDeferred = exports.clearDeferredRestore = exports.deferRestore = void 0;
+const abort_1 = require("./abort");
+// Keyed by the item's state, which every run replaces (resetWorkTree): a hit
+// deferred in one run of a Cli is never restored in a later one, over outputs
+// that run built.
+const deferred = new WeakMap();
+function deferRestore(item, run) {
+    deferred.set(item.state, { run, promise: null });
+}
+exports.deferRestore = deferRestore;
+// Every cache check starts from scratch: a key that changed since a hit was
+// deferred must not restore the old entry.
+function clearDeferredRestore(item) {
+    deferred.delete(item.state);
+}
+exports.clearDeferredRestore = clearDeferredRestore;
+// Restore every given item that was a hit without its outputs, in parallel,
+// each at most once however many items wait on it.
+async function restoreDeferred(work, items, abort) {
+    await Promise.all(items.map((item) => {
+        const entry = deferred.get(item.state);
+        if (!entry) {
+            return Promise.resolve();
+        }
+        if (!entry.promise) {
+            work.status.write('debug', `restore ${item.name} from cache, ${work.name} needs its outputs`);
+            entry.promise = entry.run();
+        }
+        return entry.promise;
+    }));
+    (0, abort_1.checkForAbort)(abort);
+}
+exports.restoreDeferred = restoreDeferred;
+//# sourceMappingURL=deferred-restore.js.map

package/dist/executer/docker-service.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dockerService = exports.buildServiceCreateOptions = void 0;
+exports.dockerService = exports.buildServiceCreateOptions = exports.readPublishedPorts = void 0;
 const work_service_1 = require("../planner/work-service");
 const run_labels_1 = require("../docker/run-labels");
 const service_hostname_1 = require("../planner/utils/service-hostname");
@@ -22,6 +22,28 @@ const work_healthcheck_1 = require("../planner/work-healthcheck");
 const docker_resources_1 = require("./docker-resources");
 const egress_proxy_1 = require("../network/egress-proxy");
 const HEALTHCHECK_INTERVAL_MS = 1000;
+// Where docker published the ports of a container (or of its relay), for those that asked
+// for a free one.
+async function readPublishedPorts(container, ports) {
+    const wanted = ports.filter((port) => port.hostPort === 0);
+    if (wanted.length === 0) {
+        return [];
+    }
+    const bound = (await container.inspect()).NetworkSettings.Ports ?? {};
+    return wanted.flatMap((port) => {
+        const binding = bound[`${port.containerPort}/tcp`]?.find((candidate) => candidate.HostPort);
+        return binding
+            ? [
+                {
+                    containerPort: port.containerPort,
+                    host: port.hostIp ?? (binding.HostIp && binding.HostIp !== '0.0.0.0' ? binding.HostIp : '127.0.0.1'),
+                    port: Number(binding.HostPort),
+                },
+            ]
+            : [];
+    });
+}
+exports.readPublishedPorts = readPublishedPorts;
 function buildServiceCreateOptions(item, options, network, secrets, resources = {}) {
     const envs = (0, replace_env_variables_1.getEnvironmentVariables)(item.data.envs);
     const command = (0, work_service_1.getServiceCommand)(item.data);
@@ -58,12 +80,9 @@ function buildServiceCreateOptions(item, options, network, secrets, resources =
             // collide with another run on the same host. A limited service's are
             // published by its relay.
             PortBindings: options.publishPorts && !network.relayPorts
-                ? item.data.ports
-                    .filter((p) => !!p.hostPort)
-                    .reduce((map, port) => {
-                    map[`${port.containerPort}/tcp`] = [{ HostPort: `${port.hostPort}` }];
-                    return map;
-                }, {})
+                ? Object.fromEntries(item.data.ports
+                    .filter((p) => p.hostPort !== null)
+                    .map((port) => [`${port.containerPort}/tcp`, [(0, item_network_1.getPortBinding)(port)]]))
                 : {},
             ...resources,
         },
@@ -90,16 +109,18 @@ async function dockerService(docker, item, options, environment) {
         const resources = await (0, docker_resources_1.resolveDockerResources)(docker, item.data.resources, item.status);
         await (0, execution_steps_1.refuseHostLinks)(item, environment);
         container = await docker.createContainer(buildServiceCreateOptions(item, options, network.options, secrets, resources));
-        await network.connect(container);
+        const relay = await network.connect(container);
         const stream = await container.attach({ stream: true, stdout: true, stderr: true });
         (0, stream_1.logStream)(item.status, stream);
         await container.start();
+        const published = options.publishPorts ? await readPublishedPorts(relay ?? container, item.data.ports) : [];
         if (!item.data.healthcheck || !options.waitForReady) {
             options.state.set({
                 type: 'running',
                 dns: { containerId: container.id },
                 stateKey: options.stateKey,
                 remote: null,
+                ...(published.length > 0 ? { published } : {}),
             });
         }
         else {
@@ -125,6 +146,7 @@ async function dockerService(docker, item, options, environment) {
                     dns: { containerId: container.id },
                     stateKey: options.stateKey,
                     remote: null,
+                    ...(published.length > 0 ? { published } : {}),
                 });
             }
         }

package/dist/executer/docker-task.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dockerTask = exports.buildCreateOptions = void 0;
+exports.dockerTask = exports.getCapabilityHostConfig = exports.buildCreateOptions = void 0;
 const run_labels_1 = require("../docker/run-labels");
 const execute_docker_1 = require("./execute-docker");
 const abort_1 = require("./abort");
@@ -47,10 +47,30 @@ function buildCreateOptions(item, stateKey, network, environment, secrets, resou
             ...(0, item_network_1.getNetworkHostConfig)(network),
             AutoRemove: true,
             ...resources,
+            ...getCapabilityHostConfig(item, environment),
         },
     };
 }
 exports.buildCreateOptions = buildCreateOptions;
+/**
+ * The capabilities a task adds (`capAdd`). On a server they are only granted in the
+ * sandboxed runtime of `backend.capabilities`, never by the kernel of the docker host.
+ */
+function getCapabilityHostConfig(item, environment) {
+    const capAdd = item.data.capAdd;
+    if (capAdd.length === 0) {
+        return {};
+    }
+    if (!environment.hosted) {
+        return { CapAdd: capAdd };
+    }
+    const runtime = environment.hosted.capabilityRuntime;
+    if (!runtime) {
+        throw new Error(`${item.name}: adds the capabilities ${capAdd.join(', ')}, which this server grants in no sandboxed runtime`);
+    }
+    return { CapAdd: capAdd, Runtime: runtime };
+}
+exports.getCapabilityHostConfig = getCapabilityHostConfig;
 async function dockerTask(docker, item, environment, options) {
     item.status.write('info', `execute ${item.name} in container`);
     let network = null;

package/dist/executer/execute-work-service.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeWorkService = exports.stopService = void 0;
 const work_item_1 = require("../planner/work-item");
 const await_completed_dependencies_1 = require("./await-completed-dependencies");
+const deferred_restore_1 = require("./deferred-restore");
 const abort_1 = require("./abort");
 const log_1 = require("../log");
 const watch_loop_1 = require("./watch-loop");
@@ -35,6 +36,7 @@ async function executeWorkService(work, environment, options) {
         });
         await (0, watch_loop_1.watchLoop)(work, environment, options, async (cacheState, abort, stop) => {
             await (0, await_completed_dependencies_1.awaitCompletedDependencies)(work, work.deps, abort);
+            await (0, deferred_restore_1.restoreDeferred)(work, (0, await_completed_dependencies_1.transitiveDeps)(work.deps), abort);
             work.state.set({
                 type: 'ready',
                 stateKey: cacheState.stateKey,

package/dist/executer/execute-work-task.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeWorkTask = void 0;
+const work_task_1 = require("../planner/work-task");
 const states_1 = require("./states");
 const abort_1 = require("./abort");
 const log_1 = require("../log");
@@ -10,9 +11,11 @@ const deadline_1 = require("./deadline");
 const explain_1 = require("../cache/explain");
 const archive_task_entry_1 = require("./archive-task-entry");
 const units_1 = require("../utils/units");
+const deferred_restore_1 = require("./deferred-restore");
 async function pushToBackend(work, environment, cacheState, options) {
     const { resolved, stateKey, provable } = cacheState;
-    if (resolved.method === 'none' || !provable) {
+    // an aggregate has nothing to store, see checkCacheState
+    if (resolved.method === 'none' || !provable || (0, work_task_1.isAggregateTask)(work.data)) {
         return;
     }
     if (options.cacheReadOnly) {
@@ -20,7 +23,7 @@ async function pushToBackend(work, environment, cacheState, options) {
         return;
     }
     try {
-        const cacheDir = await (0, archive_task_entry_1.archiveTaskEntry)(work, environment);
+        const cacheDir = await (0, archive_task_entry_1.archiveTaskEntry)(work, environment, stateKey);
         await resolved.backend.push(work.id(), stateKey, cacheDir, environment);
         work.status.write('info', `${work.name} pushed to cache "${resolved.name}" (${resolved.backend.type})`);
     }
@@ -29,7 +32,7 @@ async function pushToBackend(work, environment, cacheState, options) {
     }
 }
 // A task without cmds only groups its dependencies (`ci: { deps: [test, build] }`).
-// Having no src of its own it is never a cache hit, so its dependencies are
+// It is never a cache hit itself (see checkCacheState), so its dependencies are
 // always checked and their outputs restored. When every one of them was a hit,
 // nothing ran: report the group as cached too. Reporting only, the cache
 // decision is untouched.
@@ -87,6 +90,10 @@ dependents = null) {
                 }
             }
             await (0, await_completed_dependencies_1.awaitCompletedDependencies)(work, work.deps, abort);
+            // an aggregate runs nothing, so it needs no outputs on disk
+            if (!(0, work_task_1.isAggregateTask)(work.data)) {
+                await (0, deferred_restore_1.restoreDeferred)(work, (0, await_completed_dependencies_1.transitiveDeps)(work.deps), abort);
+            }
             await (0, await_completed_dependencies_1.awaitRunningNeeds)(work, work.needs.map((n) => n.service), abort);
             await options.processManager.task(work, async () => {
                 work.state.set({
@@ -94,7 +101,7 @@ dependents = null) {
                     stateKey: cacheState.stateKey,
                     started,
                 });
-                const timeout = work.data.timeout ?? options.timeout;
+                const timeout = (0, deadline_1.getTaskTimeout)(work.data.timeout, options);
                 const deadline = (0, deadline_1.withDeadline)(abort, timeout);
                 try {
                     await work.runtime.execute(environment, {

package/dist/executer/execution-steps.js

@@ -9,6 +9,7 @@ const work_task_1 = require("../planner/work-task");
 const work_service_1 = require("../planner/work-service");
 const get_container_binds_1 = require("./get-container-binds");
 const assert_item_paths_1 = require("../planner/utils/assert-item-paths");
+const log_1 = require("../log");
 // The files a server run works on: its checkout, or a sandbox. Somebody else wrote them.
 function hostedRoot(environment) {
     return environment.hosted ? environment.cwd : undefined;
@@ -66,10 +67,27 @@ async function prepareMounts(item, environment) {
             continue;
         }
         if ((0, path_1.extname)(mount.localPath)) {
-            await environment.file.writeFile(mount.localPath, '');
+            try {
+                await environment.file.writeFile(mount.localPath, '');
+            }
+            catch (e) {
+                // Docker would make a directory there
+                throw new Error(`mount ${mount.localPath} does not exist and can't be created (${(0, log_1.getErrorMessage)(e)})`);
+            }
         }
         else {
-            await environment.file.createDirectory(mount.localPath);
+            try {
+                await environment.file.createDirectory(mount.localPath);
+            }
+            catch (e) {
+                // on a server a root-owned directory in the run's files could break its cleanup
+                if (environment.hosted) {
+                    throw e;
+                }
+                // hammerkit may run in a container whose file system is not the one of the Docker
+                // host: Docker creates the missing directory of a bind on its own
+                item.status.write('warn', `can't create ${mount.localPath} (${(0, log_1.getErrorMessage)(e)}), Docker creates it on its host as root`);
+            }
         }
     }
     if ((0, work_task_1.isContainerWorkTask)(item.data)) {
@@ -89,8 +107,11 @@ exports.prepareMounts = prepareMounts;
 async function setUserPermissions(item, container, environment) {
     if (item.data.user) {
         // On a server only the volumes: a chown as the container's root on a path of the host
-        // would follow a link a task put there after the binds were checked
-        const binds = (0, get_container_binds_1.getContainerBinds)(item).filter((bind) => !environment.hosted || !(0, path_1.isAbsolute)(bind.localPath));
+        // would follow a link a task put there after the binds were checked. Never a mount: it
+        // is a path of the host the build file names, such as /var/run/docker.sock, whose owner
+        // is not hammerkit's to change
+        const mounted = new Set(item.data.mounts.map((mount) => mount.containerPath));
+        const binds = (0, get_container_binds_1.getContainerBinds)(item).filter((bind) => !mounted.has(bind.containerPath) && (!environment.hosted || !(0, path_1.isAbsolute)(bind.localPath)));
         if (!environment.hosted) {
             await (0, set_user_permission_1.setUserPermission)(item.data.cwd, item.status, environment, container, item.data.user);
         }

package/dist/executer/reset-work-tree.js

@@ -5,6 +5,10 @@ const state_1 = require("./state");
 function resetWorkTree(workTree, type) {
     return {
         tasks: Object.entries(workTree.tasks).reduce((tasks, [key, task]) => {
+            // down only stops services: a task it selects names the services it needs
+            if (type === 'down') {
+                return tasks;
+            }
             task.state = new state_1.State({
                 type: 'pending',
                 stateKey: null,

package/dist/executer/scheduler/enqueue-next.js

@@ -2,19 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkCacheState = exports.UNCACHED_STATE_KEY = void 0;
 const work_item_1 = require("../../planner/work-item");
+const work_task_1 = require("../../planner/work-task");
 const get_cache_directory_1 = require("../../optimizer/get-cache-directory");
 const cache_metadata_1 = require("../cache-metadata");
 const work_task_cache_description_1 = require("../../optimizer/work-task-cache-description");
 const log_1 = require("../../log");
 const state_key_1 = require("./state-key");
 const work_instance_id_1 = require("../../planner/work-instance-id");
+const deferred_restore_1 = require("../deferred-restore");
 // The key a task whose cache is off runs and records its outputs under. It is
 // no hash, so a later run with its cache on never takes those outputs as its own.
 exports.UNCACHED_STATE_KEY = 'uncached';
 async function checkCacheState(item, defaultCacheMethod, environment, 
 // watch mode compares keys to rerun on a change, so it needs one even when
 // the cache is off
+// restore: false only looks a backend hit up, its outputs are downloaded once
+// something that runs depends on them (`run --no-restore`, see deferred-restore)
 options = {}) {
+    (0, deferred_restore_1.clearDeferredRestore)(item);
     // A task whose cache is off is never looked up, so hashing its sources buys
     // nothing, and a `**` over a node_modules takes most of a minute (every run
     // with arguments). Its dependents still hash its sources for their own key.
@@ -35,18 +40,41 @@ options = {}) {
         item.status.write('debug', `${item.name} always runs, it or one of its dependencies has no src files`);
         return { cached: false, stateKey, resolved, provable };
     }
+    // An aggregate runs nothing, so running it costs nothing, and it is never a hit itself:
+    // asked for, it still has its dependencies checked and their outputs restored. Its key
+    // counts for what depends on it, and it is reported cached when they all were.
+    if ((0, work_item_1.isWorkTaskItem)(item) && (0, work_task_1.isAggregateTask)(item.data)) {
+        return { cached: false, stateKey, resolved, provable };
+    }
     if ((0, work_item_1.isWorkTaskItem)(item)) {
         const runtimeStateKey = await item.runtime.currentStateKey(environment);
         if (runtimeStateKey === stateKey) {
             return { cached: true, stateKey, resolved, provable };
         }
+        if (options.restore === false && options.watch) {
+            item.status.write('debug', `${item.name} restores cache hits, --no-restore has no effect in watch mode`);
+        }
+        if (options.restore === false && !options.watch) {
+            try {
+                if (await resolved.backend.has(item.id(), stateKey, environment)) {
+                    item.status.write('info', `${item.name} found in cache "${resolved.name}" (${resolved.backend.type}), not restored`);
+                    await touchEntry(item, resolved, stateKey, environment);
+                    (0, deferred_restore_1.deferRestore)(item, async () => {
+                        if (!(await restoreFromBackend(item, resolved, stateKey, currentStats, environment))) {
+                            throw new Error(`${item.name} is no longer in cache "${resolved.name}", its outputs can not be restored. ` +
+                                'Run again without --no-restore.');
+                        }
+                    });
+                    return { cached: true, stateKey, resolved, provable };
+                }
+            }
+            catch (e) {
+                item.status.write('warn', `${item.name} failed to look up cache "${resolved.name}": ${(0, log_1.getErrorMessage)(e)} — continuing with local execution`);
+            }
+            return { cached: false, stateKey, resolved, provable };
+        }
         try {
-            const cacheDir = (0, get_cache_directory_1.getCacheDirectory)((0, work_instance_id_1.getWorkInstanceId)(item));
-            const pulled = await resolved.backend.pull(item.id(), stateKey, cacheDir, environment);
-            if (pulled) {
-                item.status.write('info', `${item.name} pulled from cache "${resolved.name}" (${resolved.backend.type})`);
-                await item.runtime.restore(environment, cacheDir, stateKey);
-                await (0, cache_metadata_1.writeCacheMetadata)(environment, item, currentStats, (0, work_task_cache_description_1.getWorkTaskCacheDescription)(item));
+            if (await restoreFromBackend(item, resolved, stateKey, currentStats, environment)) {
                 return { cached: true, stateKey, resolved, provable };
             }
         }
@@ -57,4 +85,27 @@ options = {}) {
     return { cached: false, stateKey, resolved, provable };
 }
 exports.checkCacheState = checkCacheState;
+// Pull a task's entry and restore its outputs into the checkout. False when the
+// backend has no such entry.
+async function restoreFromBackend(item, resolved, stateKey, currentStats, environment) {
+    const cacheDir = (0, get_cache_directory_1.getCacheDirectory)((0, work_instance_id_1.getWorkInstanceId)(item));
+    const pulled = await resolved.backend.pull(item.id(), stateKey, cacheDir, environment);
+    if (!pulled) {
+        return false;
+    }
+    item.status.write('info', `${item.name} pulled from cache "${resolved.name}" (${resolved.backend.type})`);
+    await item.runtime.restore(environment, cacheDir, stateKey);
+    await (0, cache_metadata_1.writeCacheMetadata)(environment, item, currentStats, (0, work_task_cache_description_1.getWorkTaskCacheDescription)(item));
+    return true;
+}
+// A hit that is only looked up still counts as used, so retention keeps it.
+// Best effort: the hit stands whether or not the marker could be written.
+async function touchEntry(item, resolved, stateKey, environment) {
+    try {
+        await resolved.backend.touch?.(item.id(), stateKey, environment);
+    }
+    catch (e) {
+        item.status.write('debug', `${item.name} could not mark its cache entry as used: ${(0, log_1.getErrorMessage)(e)}`);
+    }
+}
 //# sourceMappingURL=enqueue-next.js.map

package/dist/executer/scheduler/state-key.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeStateKey = exports.combineStateKeys = exports.resolveEffective = void 0;
-const crypto_1 = require("crypto");
+exports.computeStateKey = exports.combineStateKeys = exports.isOwnProvable = exports.resolveEffective = void 0;
 const get_work_cache_stats_1 = require("../../optimizer/get-work-cache-stats");
+const work_task_1 = require("../../planner/work-task");
 // The state-key engine is shared by the scheduler's hit/miss decision
 // (`checkCacheState`) and the read-only cache-explain engine, so a prediction
 // can never diverge from the decision it predicts — there is one implementation.
@@ -21,9 +21,14 @@ exports.resolveEffective = resolveEffective;
 // whose `src` entries all match no file (a typo, a moved path). Services are not
 // affected.
 function isOwnProvable(item, unmatched) {
+    if ((0, work_task_1.isAggregateTask)(item.data)) {
+        // it runs nothing and reads nothing: what its dependencies prove is all there is
+        return true;
+    }
     // unmatched ⊆ declared, so this is also false when nothing is declared
     return unmatched.length < item.data.src.filter((src) => !src.inherited).length;
 }
+exports.isOwnProvable = isOwnProvable;
 // Fold a task's own state key together with the state keys of its dependencies.
 // A change anywhere in the dependency subtree must change the resulting key, so
 // that a downstream task is invalidated when an upstream source changes — even
@@ -34,9 +39,7 @@ function combineStateKeys(ownKey, depKeys) {
     }
     // Sort so the key is independent of dependency declaration order.
     const sorted = [...depKeys].sort();
-    return (0, crypto_1.createHash)('md5')
-        .update([ownKey, ...sorted].join(','))
-        .digest('hex');
+    return (0, get_work_cache_stats_1.stateKeyDigest)([ownKey, ...sorted].join(','));
 }
 exports.combineStateKeys = combineStateKeys;
 // `none` only disables the cache *check* for a task; its sources still influence
@@ -72,7 +75,41 @@ async function computeStateKey(item, defaultCacheMethod, environment, memo = new
         depKeys.push(effective.stateKey);
         provable = provable && effective.provable;
     }
+    // what a task that needs a service passed against: the sources of the service and of the
+    // tasks it depends on (its definition is in the task id, getWorkServiceCacheIdentity)
+    for (const need of item.needs) {
+        const effective = await resolveNeedStateKey(need.service, defaultCacheMethod, environment, memo);
+        depKeys.push(`${need.name}=${effective.stateKey}`);
+    }
     return { stateKey: combineStateKeys(ownKey, depKeys), stats, resolved, provable, unmatched };
 }
 exports.computeStateKey = computeStateKey;
+// A needed service's sources folded with the state keys of its dependencies and needs. It
+// does not make the task that needs it unprovable: a dependency without `src` (resetting the
+// service's data, say) is skipped with the service when the task is a cache hit.
+async function resolveNeedStateKey(service, defaultCacheMethod, environment, memo) {
+    const memoKey = `need\0${service.name}`;
+    const existing = memo.get(memoKey);
+    if (existing !== undefined) {
+        return existing;
+    }
+    // services that need each other in a loop fail to plan (checkForLoop): this only has to end
+    memo.set(memoKey, { stateKey: 'loop', provable: true });
+    const resolved = resolveEffective(service, defaultCacheMethod);
+    const { stats } = await (0, get_work_cache_stats_1.getWorkItemCacheStats)(service, environment);
+    const keys = [];
+    for (const dep of service.deps) {
+        keys.push((await resolveEffectiveStateKey(dep, defaultCacheMethod, environment, memo)).stateKey);
+    }
+    for (const need of service.needs) {
+        const effective = await resolveNeedStateKey(need.service, defaultCacheMethod, environment, memo);
+        keys.push(`${need.name}=${effective.stateKey}`);
+    }
+    const effective = {
+        stateKey: combineStateKeys((0, get_work_cache_stats_1.getStateKey)(stats, concreteMethod(resolved, defaultCacheMethod)), keys),
+        provable: true,
+    };
+    memo.set(memoKey, effective);
+    return effective;
+}
 //# sourceMappingURL=state-key.js.map

package/dist/executer/watch-loop.js

@@ -8,11 +8,14 @@ const state_resolver_1 = require("./state-resolver");
 const abort_1 = require("./abort");
 const enqueue_next_1 = require("./scheduler/enqueue-next");
 async function watchLoop(work, environment, options, factory) {
-    // continuous lives on container-services and on tasks (both task types); a
-    // kubernetes-service has no such field. Read it wherever it exists.
+    // a container service that watches its own files (`continuous`); a kubernetes-service and a
+    // task have no such field
     const continuous = 'continuous' in work.data ? work.data.continuous : false;
     const watchMode = options.watch && !options.daemon && !continuous;
-    const currentStats = await (0, enqueue_next_1.checkCacheState)(work, options.cacheDefault, environment, { watch: watchMode });
+    const currentStats = await (0, enqueue_next_1.checkCacheState)(work, options.cacheDefault, environment, {
+        watch: watchMode,
+        restore: options.restore,
+    });
     (0, abort_1.checkForAbort)(environment.abortCtrl.signal);
     const watchState = watchMode
         ? (0, watch_state_key_1.watchStateKey)(work, currentStats, environment, options)