@astrosheep/keiyaku 2.8.0 → 2.8.2

package/build/core/addressing.js

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import { FlowError } from "../flow-error.js";
 import { listContractIds, readLedger } from "./ledger.js";
+import { isResponseArtifactId } from "./response-artifact-id.js";
 import { stableRepoRoot } from "./worktree-path.js";
 import { deriveContractState, isTerminalState, } from "./status.js";
 function normalizeAddressQuery(raw) {
@@ -66,10 +67,39 @@ export function buildResolutionAttempt(input) {
         workdir: path.resolve(input.workdir),
         expected: "commission",
         ...(input.spelling ? { spelling: input.spelling } : {}),
+        ...(input.actual !== undefined ? { actual: input.actual } : {}),
         candidates: [...(input.candidates ?? [])],
         inference: [...(input.inference ?? [])],
     };
 }
+export function buildObjectResolutionAttempt(input) {
+    return {
+        repo: input.repo,
+        workdir: path.resolve(input.workdir),
+        expected: input.expected,
+        supplied: input.supplied,
+        ...(input.actual !== undefined ? { actual: input.actual } : {}),
+        ...(input.scope ? { scope: input.scope } : {}),
+        candidates: [...(input.candidates ?? [])],
+        inference: [...(input.inference ?? [])],
+    };
+}
+export function buildArtifactResolutionAttempt(input) {
+    return {
+        ...buildObjectResolutionAttempt({
+            ...input,
+            expected: "artifact",
+        }),
+        expected: "artifact",
+    };
+}
+function commissionSelectorAsTyped(query, source) {
+    if (source === "at-address")
+        return `@${query}`;
+    if (source === "explicit-flag")
+        return `--contract ${query}`;
+    return query;
+}
 export class AddressResolutionError extends FlowError {
     attempt;
     constructor(code, message, attempt, options) {
@@ -162,63 +192,77 @@ export async function resolveUncommissionedRepositoryAddress(input) {
 export async function resolveContractAddress(cwd, raw, source = raw?.startsWith("@") ? "at-address" : "explicit-flag") {
     const workdir = path.resolve(cwd);
     const repo = await resolvedRepository(cwd);
-    const candidates = await commissionAddressCandidates(repo.stableRoot);
-    if (raw === undefined) {
-        const operable = candidates.filter((candidate) => candidate.active);
+    if (raw !== undefined) {
+        const query = normalizeAddressQuery(raw);
+        const spelling = { asTyped: commissionSelectorAsTyped(query, source), source };
+        // Lexical artifact fence: no ledger enumeration for rsp_<ULID>.
+        if (isResponseArtifactId(query)) {
+            throw new AddressResolutionError("EMPTY_PARAM", `artifact ${query} is a response artifact; expected a commission address`, {
+                repo,
+                workdir,
+                expected: "commission",
+                spelling,
+                candidates: [],
+                inference: [],
+                actual: "artifact",
+            });
+        }
+        const candidates = await commissionAddressCandidates(repo.stableRoot);
+        const matches = matchCommissionAddress(query, candidates);
         const attempt = {
             repo,
             workdir,
             expected: "commission",
-            candidates: attemptCandidates(operable),
-            inference: ["consulted active commission ledgers"],
+            spelling,
+            candidates: matches.map((candidate) => ({
+                commissionId: candidate.contractId,
+                matchedBy: candidate.spelling,
+                place: candidate.bind.data.place ?? null,
+                name: candidate.bind.data.name,
+                objective: candidate.bind.data.objective,
+                lifecycle: candidate.lifecycle,
+                target: { branch: candidate.bind.data.target },
+            })),
+            inference: [],
         };
-        if (operable.length === 1) {
-            const candidate = operable[0];
+        if (matches.length === 1) {
             return buildResolvedAddress({
                 repo,
                 workdir,
-                candidate,
-                matchedBy: "id",
-                asTyped: `@${candidate.contractId}`,
-                source: "sole-active",
-                inference: attempt.inference,
+                candidate: matches[0],
+                matchedBy: matches[0].spelling,
+                asTyped: attempt.spelling.asTyped,
+                source,
+                inference: [],
             });
         }
-        throw new AddressResolutionError(operable.length === 0 ? "EMPTY_PARAM" : "CONTRACT_AMBIGUOUS", operable.length === 0
-            ? "no active commission found; pass @place, @slug, full @commission-id, or --contract <addr>"
-            : "multiple active commissions found; pass @place, @slug, full @commission-id, or --contract <addr>", attempt);
+        if (matches.length === 0) {
+            throw new AddressResolutionError("EMPTY_PARAM", `unknown contract address @${query}`, attempt);
+        }
+        throw new AddressResolutionError("CONTRACT_AMBIGUOUS", `contract address @${query} is ambiguous: ${attempt.candidates.map((candidate) => formatAmbiguousCandidate(query, candidate)).join("; ")}; use a full @commission-id`, attempt);
     }
-    const query = normalizeAddressQuery(raw);
-    const matches = matchCommissionAddress(query, candidates);
+    const candidates = await commissionAddressCandidates(repo.stableRoot);
+    const operable = candidates.filter((candidate) => candidate.active);
     const attempt = {
         repo,
         workdir,
         expected: "commission",
-        spelling: { asTyped: source === "at-address" ? `@${query}` : query, source },
-        candidates: matches.map((candidate) => ({
-            commissionId: candidate.contractId,
-            matchedBy: candidate.spelling,
-            place: candidate.bind.data.place ?? null,
-            name: candidate.bind.data.name,
-            objective: candidate.bind.data.objective,
-            lifecycle: candidate.lifecycle,
-            target: { branch: candidate.bind.data.target },
-        })),
-        inference: [],
+        candidates: attemptCandidates(operable),
+        inference: ["consulted active commission ledgers"],
     };
-    if (matches.length === 1) {
+    if (operable.length === 1) {
+        const candidate = operable[0];
         return buildResolvedAddress({
             repo,
             workdir,
-            candidate: matches[0],
-            matchedBy: matches[0].spelling,
-            asTyped: attempt.spelling.asTyped,
-            source,
-            inference: [],
+            candidate,
+            matchedBy: "id",
+            asTyped: `@${candidate.contractId}`,
+            source: "sole-active",
+            inference: attempt.inference,
         });
     }
-    if (matches.length === 0) {
-        throw new AddressResolutionError("EMPTY_PARAM", `unknown contract address @${query}`, attempt);
-    }
-    throw new AddressResolutionError("CONTRACT_AMBIGUOUS", `contract address @${query} is ambiguous: ${attempt.candidates.map((candidate) => formatAmbiguousCandidate(query, candidate)).join("; ")}; use a full @commission-id`, attempt);
+    throw new AddressResolutionError(operable.length === 0 ? "EMPTY_PARAM" : "CONTRACT_AMBIGUOUS", operable.length === 0
+        ? "no active commission found; pass @place, @slug, full @commission-id, or --contract <addr>"
+        : "multiple active commissions found; pass @place, @slug, full @commission-id, or --contract <addr>", attempt);
 }

package/build/core/call.js

@@ -11,6 +11,8 @@ import { buildCallTermsV2 } from "../agents/call-terms_v2.js";
 import { applySnapshotEffort, resolveAkumaLaunchSnapshot, } from "../agents/launch-snapshot_v2.js";
 import { restoreOutcome } from "../agents/harness/index.js";
 import { mintProjection, mintRepositoryProjection } from "./projection-mint.js";
+import { assertProjectionAlias, moveProjectionAlias } from "./projection-alias.js";
+import { projectionDir } from "./projection-core.js";
 import { waitForProjection } from "./projection-wait.js";
 import { requireResumableArtifact } from "./transcripts.js";
 import { appendDebugBlock } from "../telemetry/debug-log.js";
@@ -125,7 +127,7 @@ async function readCallKeiyakuContext(executionCwd, input) {
         if (input.bare && input.contractId) {
             const asTyped = input.contractAddressSource === "at-address"
                 ? `@${input.contractId}`
-                : input.contractId;
+                : `--contract ${input.contractId}`;
             throw new AddressResolutionError("EMPTY_PARAM", `commission address ${asTyped} cannot be combined with --bare`, buildResolutionAttempt({
                 repo: { kind: "user" },
                 workdir: executionCwd,
@@ -138,7 +140,7 @@ async function readCallKeiyakuContext(executionCwd, input) {
         if (input.contractId) {
             const asTyped = input.contractAddressSource === "at-address"
                 ? `@${input.contractId}`
-                : input.contractId;
+                : `--contract ${input.contractId}`;
             throw new AddressResolutionError("EMPTY_PARAM", `${asTyped} is a commission address, but ${ledgerCandidate} has no repository ledger; contract addressing requires a ledger`, buildResolutionAttempt({
                 repo: { kind: "user" },
                 workdir: executionCwd,
@@ -190,7 +192,7 @@ async function readCallKeiyakuContext(executionCwd, input) {
         });
         const asTyped = input.contractAddressSource === "at-address"
             ? `@${input.contractId}`
-            : input.contractId;
+            : `--contract ${input.contractId}`;
         throw new AddressResolutionError("EMPTY_PARAM", `commission address ${asTyped} cannot be combined with --bare`, buildResolutionAttempt({
             repo: repositoryAddress.repo,
             workdir: repositoryAddress.workdir,
@@ -240,6 +242,7 @@ async function readCallKeiyakuContext(executionCwd, input) {
         catch (error) {
             if (error instanceof AddressResolutionError
                 && error.code === "EMPTY_PARAM"
+                && error.attempt.expected === "commission"
                 && error.attempt.candidates.length === 0) {
                 return {
                     activeKeiyaku: false,
@@ -414,7 +417,7 @@ async function buildCallConfig(agentName, prompt, cwd, options) {
         idleTimeoutMs: options.idleTimeoutMs,
     });
     // Mint projection directory for supervisor pump.
-    const slug = launchSnapshot.akuma.name.replace(/[^a-zA-Z0-9_-]/g, "-").toLowerCase();
+    const slug = launchSnapshot.akuma.name;
     const publishProjection = async () => {
         const mintInput = {
             cwd: options.projectionCwd ?? cwd,
@@ -462,7 +465,29 @@ async function buildCallConfig(agentName, prompt, cwd, options) {
         finally {
             store.close();
         }
-        return { id: minted.id, dir: minted.dir, executionId };
+        const previousAliasTarget = options.alias === undefined
+            ? undefined
+            : moveProjectionAlias(options.projectionCwd ?? cwd, assertProjectionAlias(options.alias), minted.id);
+        const previousAliasTargetStillRunning = previousAliasTarget === undefined
+            ? undefined
+            : (() => {
+                try {
+                    const phase = observeProjectionLife(projectionDir(options.projectionCwd ?? cwd, previousAliasTarget), { nowMs: Date.now(), startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS }).phase;
+                    return phase === "minting" || phase === "active" || phase === "quiescent"
+                        ? previousAliasTarget
+                        : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+        return {
+            id: minted.id,
+            dir: minted.dir,
+            executionId,
+            ...(options.alias ? { alias: options.alias } : {}),
+            ...(previousAliasTargetStillRunning ? { previousAliasTarget: previousAliasTargetStillRunning } : {}),
+        };
     };
     // Every public launch has one durable projection object. Repository-free
     // authority changes the storage owner, not whether the object exists; mint
@@ -565,6 +590,7 @@ export async function runCall(input) {
             binding: keiyakuContext.address.binding,
             title,
             context: input.context,
+            ...(input.mode === "call" && input.alias !== undefined ? { alias: assertProjectionAlias(input.alias) } : {}),
         };
         if ((input.mode ?? "call") === "call") {
             const launched = await launchSubagentGeneration(launchSnapshot.akuma.name, prompt, executionCwd, executionOptions);
@@ -574,6 +600,8 @@ export async function runCall(input) {
                     nowMs: Date.now(),
                     startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS,
                 }).phase,
+                ...(launched.projection.alias ? { alias: launched.projection.alias } : {}),
+                ...(launched.projection.previousAliasTarget ? { previousAliasTarget: launched.projection.previousAliasTarget } : {}),
             };
             input.onLaunch?.({ address: keiyakuContext.address, projection: adoptedProjection });
             if (input.detach) {

package/build/core/projection/mint.js

@@ -20,11 +20,21 @@ function assertMintSlug(slug) {
     if (!normalized) {
         throw new ProjectionStateError("projection slug cannot be empty");
     }
-    if (normalized.includes("/") || normalized.includes("\0")) {
+    if (!/^[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*$/.test(normalized)) {
         throw new ProjectionStateError(`invalid projection slug: ${slug}`);
     }
     return normalized;
 }
+function removeEmptyAkumaRoot(dir) {
+    try {
+        fs.rmdirSync(dir);
+    }
+    catch (error) {
+        if (isErrnoException(error) && ["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code ?? ""))
+            return;
+        throw error;
+    }
+}
 /**
  * Validate mint inputs that can fail, then reserve one private staging directory.
  * Dot-prefixed staging is never a published projection address.
@@ -43,14 +53,19 @@ function reserveProjectionDirectory(input) {
     }
     const root = projectionRoot(input.cwd);
     fs.mkdirSync(root, { recursive: true });
+    const akumaRoot = path.join(root, slug);
+    const createdAkumaRoot = !fs.existsSync(akumaRoot);
+    fs.mkdirSync(akumaRoot, { recursive: true });
     for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
         const hex = (input.randomHex?.(attempt) ?? randomHex8()).toLowerCase();
         if (!/^[0-9a-f]{8}$/.test(hex)) {
+            if (createdAkumaRoot)
+                removeEmptyAkumaRoot(akumaRoot);
             throw new ProjectionStateError(`projection id random segment must be 8 hex chars, got ${hex}`);
         }
-        const id = `${slug}-${hex}`;
+        const id = `${slug}/${hex}`;
         const dir = projectionDir(input.cwd, id);
-        const stagingDir = path.join(root, `.mint-${id}`);
+        const stagingDir = path.join(akumaRoot, `.mint-${hex}`);
         if (fs.existsSync(dir))
             continue;
         try {
@@ -60,6 +75,8 @@ function reserveProjectionDirectory(input) {
             if (isErrnoException(error) && error.code === "EEXIST") {
                 continue;
             }
+            if (createdAkumaRoot)
+                removeEmptyAkumaRoot(akumaRoot);
             throw error;
         }
         if (fs.existsSync(dir)) {
@@ -68,6 +85,8 @@ function reserveProjectionDirectory(input) {
         }
         return { id, dir, stagingDir };
     }
+    if (createdAkumaRoot)
+        removeEmptyAkumaRoot(akumaRoot);
     throw new ProjectionMintCollisionError(`exhausted ${maxAttempts} projection id attempts under ${PROJECTION_ROOT_SEGMENTS.join("/")} (PROJECTION_MINT_COLLISION)`);
 }
 /** Build the identity fields shared by both authority variants. */
@@ -107,6 +126,7 @@ function publishReservedProjection(pact, reserved) {
         if (!published) {
             // Failure removes only this mint's staging.
             fs.rmSync(reserved.stagingDir, { recursive: true, force: true });
+            removeEmptyAkumaRoot(path.dirname(reserved.stagingDir));
         }
     }
 }

package/build/core/projection-alias.js

@@ -0,0 +1,123 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isErrnoException } from "../errno.js";
+import { ProjectionStateError, randomHex8 } from "./atomic-publish.js";
+import { projectionCoordinateRoot } from "./projection-coordinate.js";
+import { isProjectionId } from "./projection-core.js";
+export const PROJECTION_ALIAS_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const MAX_ALIAS_REF_BYTES = 1024;
+export function isProjectionAlias(value) {
+    return PROJECTION_ALIAS_PATTERN.test(value);
+}
+export function assertProjectionAlias(value) {
+    if (!isProjectionAlias(value)) {
+        throw new ProjectionStateError("projection alias must match ^[a-z0-9][a-z0-9-]{0,63}$");
+    }
+    return value;
+}
+export function projectionAliasRoot(cwd) {
+    return path.join(projectionCoordinateRoot(cwd), ".keiyaku", "projection-alias");
+}
+export function projectionAliasPath(cwd, alias) {
+    assertProjectionAlias(alias);
+    return path.join(projectionAliasRoot(cwd), alias);
+}
+function invalidAliasRef(filePath) {
+    return new ProjectionStateError(`invalid projection alias ref: ${filePath}`);
+}
+function readBoundedRegularAliasRef(filePath) {
+    let before;
+    try {
+        before = fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (!before.isFile() || before.size > MAX_ALIAS_REF_BYTES)
+        throw invalidAliasRef(filePath);
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ELOOP")
+            throw invalidAliasRef(filePath);
+        throw error;
+    }
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile() || opened.size > MAX_ALIAS_REF_BYTES)
+            throw invalidAliasRef(filePath);
+        const bytes = Buffer.alloc(opened.size);
+        const count = fs.readSync(fd, bytes, 0, bytes.length, 0);
+        if (count !== bytes.length)
+            throw invalidAliasRef(filePath);
+        return bytes.toString("utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Undefined means no ref; malformed refs fail closed with their exact sidecar path. */
+export function readProjectionAlias(cwd, alias) {
+    const filePath = projectionAliasPath(cwd, alias);
+    const content = readBoundedRegularAliasRef(filePath);
+    if (content === undefined)
+        return undefined;
+    if (!content.endsWith("\n") || content.indexOf("\n") !== content.length - 1)
+        throw invalidAliasRef(filePath);
+    const id = content.slice(0, -1);
+    if (!isProjectionId(id))
+        throw invalidAliasRef(filePath);
+    return id;
+}
+/** Atomically replace one alias ref. Aliases intentionally have no multi-ref transaction. */
+export function moveProjectionAlias(cwd, alias, id) {
+    assertProjectionAlias(alias);
+    if (!isProjectionId(id))
+        throw new ProjectionStateError(`invalid projection id: ${id}`);
+    const previous = readProjectionAlias(cwd, alias);
+    const root = projectionAliasRoot(cwd);
+    fs.mkdirSync(root, { recursive: true });
+    const target = projectionAliasPath(cwd, alias);
+    let temp;
+    try {
+        for (let attempt = 0; attempt < 16; attempt += 1) {
+            const candidate = path.join(root, `.tmp.${randomHex8()}`);
+            try {
+                const fd = fs.openSync(candidate, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+                temp = candidate;
+                try {
+                    fs.writeFileSync(fd, `${id}\n`, "utf8");
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                break;
+            }
+            catch (error) {
+                if (isErrnoException(error) && error.code === "EEXIST")
+                    continue;
+                throw error;
+            }
+        }
+        if (!temp)
+            throw new ProjectionStateError(`failed to create projection alias temp: ${target}`);
+        fs.renameSync(temp, target);
+        const directoryFd = fs.openSync(root, fs.constants.O_RDONLY);
+        try {
+            fs.fsyncSync(directoryFd);
+        }
+        finally {
+            fs.closeSync(directoryFd);
+        }
+    }
+    finally {
+        if (temp)
+            fs.rmSync(temp, { force: true });
+    }
+    return previous;
+}

package/build/core/projection-coordinate.js

@@ -2,13 +2,13 @@ import { spawnSync } from "node:child_process";
 import * as path from "node:path";
 import { ProjectionStateError } from "./atomic-publish.js";
 /**
- * Select the filesystem authority for repository projection state.
+ * Resolve projection storage root and authority from one Git probe.
  *
  * A non-bare repository uses the parent of its absolute common Git directory,
  * so every linked worktree shares one coordinate. Repo-free callers retain the
  * existing cwd-local authority until its replacement is legislated.
  */
-export function projectionCoordinateRoot(cwd) {
+export function resolveProjectionCoordinate(cwd) {
     const result = spawnSync("git", ["rev-parse", "--is-bare-repository", "--path-format=absolute", "--git-common-dir"], {
         cwd,
         encoding: "utf8",
@@ -24,12 +24,28 @@ export function projectionCoordinateRoot(cwd) {
     }
     if (result.status !== 0) {
         const detail = result.stderr.trim();
-        if (detail.includes("not a git repository"))
-            return cwd;
+        if (detail.includes("not a git repository")) {
+            return { physicalRoot: cwd, authority: { kind: "user" } };
+        }
         throw new ProjectionStateError(`cannot resolve projection repository coordinate${detail ? `: ${detail}` : ` (git exited ${String(result.status)})`}`);
     }
     const [bare, commonDir] = result.stdout.trim().split(/\r?\n/);
-    if (bare !== "false" || !commonDir || !path.isAbsolute(commonDir))
-        return cwd;
-    return path.dirname(commonDir);
+    if (bare !== "false" || !commonDir || !path.isAbsolute(commonDir)) {
+        return { physicalRoot: cwd, authority: { kind: "user" } };
+    }
+    const physicalRoot = path.dirname(commonDir);
+    return {
+        physicalRoot,
+        authority: { kind: "repository", stableRoot: physicalRoot },
+    };
+}
+/**
+ * Select the filesystem authority for repository projection state.
+ *
+ * A non-bare repository uses the parent of its absolute common Git directory,
+ * so every linked worktree shares one coordinate. Repo-free callers retain the
+ * existing cwd-local authority until its replacement is legislated.
+ */
+export function projectionCoordinateRoot(cwd) {
+    return resolveProjectionCoordinate(cwd).physicalRoot;
 }

package/build/core/projection-core.js

@@ -3,16 +3,22 @@ import * as path from "node:path";
 import { isErrnoException } from "../errno.js";
 import { projectionCoordinateRoot } from "./projection-coordinate.js";
 import { ProjectionStateError, } from "./atomic-publish.js";
-import { readProjectionIdentity } from "./projection-identity.js";
 export { atomicPublishFile, ProjectionStateError, randomHex8 } from "./atomic-publish.js";
 export { claimAllInbox, claimFencedTells, claimTellToInflight, demoteSubmittedTellsForReplay, isTellCausallyConsumed, listTellIds, markTellConsumed, markTellSubmitted, readTellOriginal, readTellSubmitted, snapshotPendingTells, writeInboxTell, } from "./projection-tells.js";
 /** Relative segments for `.keiyaku/projection`. */
 export const PROJECTION_ROOT_SEGMENTS = [".keiyaku", "projection"];
+export const PROJECTION_ID_PATTERN = /^[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*\/[0-9a-f]{8}$/;
+export function isProjectionId(value) {
+    return PROJECTION_ID_PATTERN.test(value);
+}
 export function projectionRoot(cwd) {
     return path.join(projectionCoordinateRoot(cwd), ...PROJECTION_ROOT_SEGMENTS);
 }
 export function projectionDir(cwd, id) {
-    return path.join(projectionRoot(cwd), id);
+    if (!isProjectionId(id))
+        throw new ProjectionStateError(`invalid projection id: ${id}`);
+    const [akuma, hex] = id.split("/");
+    return path.join(projectionRoot(cwd), akuma, hex);
 }
 export function encodeProjectionJson(value) {
     return `${JSON.stringify(value)}\n`;
@@ -32,51 +38,6 @@ export function isPublishedProjection(dir) {
         return false;
     }
 }
-/** readdir-based address resolution. Atomic mint rename makes every visible non-dot directory published. */
-export function resolveProjectionPrefix(cwd, prefix, commissionId) {
-    const needle = prefix.trim();
-    if (!needle) {
-        return { status: "none" };
-    }
-    const root = projectionRoot(cwd);
-    let entries;
-    try {
-        entries = fs.readdirSync(root);
-    }
-    catch (error) {
-        if (isErrnoException(error) && error.code === "ENOENT") {
-            return { status: "none" };
-        }
-        throw error;
-    }
-    const publishedIds = entries
-        .filter((id) => {
-        if (id.startsWith("."))
-            return false;
-        const directory = path.join(root, id);
-        return isPublishedProjection(directory);
-    })
-        .sort();
-    const addressed = publishedIds.filter((id) => {
-        if (id === needle || id.startsWith(needle))
-            return true;
-        const suffix = /-([0-9a-f]{8})$/.exec(id)?.[1];
-        return suffix === needle;
-    });
-    const candidates = commissionId === undefined
-        ? addressed
-        : addressed.filter((id) => {
-            const identity = readProjectionIdentity(path.join(root, id));
-            return identity.binding.kind === "commission" && identity.binding.commissionId === commissionId;
-        });
-    if (candidates.length === 1) {
-        return { status: "resolved", id: candidates[0] };
-    }
-    if (candidates.length === 0) {
-        return { status: "none" };
-    }
-    return { status: "ambiguous", candidates };
-}
 const PROJECTION_EXECUTION_ID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
 function assertProjectionExecutionId(executionId) {
     if (!PROJECTION_EXECUTION_ID_PATTERN.test(executionId)) {

package/build/core/projection-kill.js

@@ -0,0 +1,26 @@
+import { openProjectionGenerationStore } from "./projection-generation-store.js";
+export function killProjectionGeneration(projectionDirectory, nowMs = Date.now()) {
+    const store = openProjectionGenerationStore(projectionDirectory);
+    try {
+        const current = store.readCurrentGeneration();
+        if (!current)
+            return { status: "already-resting" };
+        if (current.verdict) {
+            return { status: "already-resting", executionId: current.launch.executionId };
+        }
+        const transition = store.verdictIfOpen({
+            executionId: current.launch.executionId,
+            verdict: "completed",
+            facts: {
+                operatorAction: "kill",
+                killedAt: new Date(nowMs).toISOString(),
+            },
+        });
+        return transition.status === "committed"
+            ? { status: "killed", executionId: current.launch.executionId }
+            : { status: "already-resting", executionId: current.launch.executionId };
+    }
+    finally {
+        store.close();
+    }
+}