@astrosheep/keiyaku 4.0.1 → 4.0.2

package/build/src/workspace-place.js

@@ -0,0 +1,386 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { replaceFileDurably } from "./coordination/durable-file.js";
+import { acquireSqliteTransactionLock } from "./coordination/sqlite-transaction-lock.js";
+import { AuthorityCorruptionError } from "./core/facts/errors.js";
+import { contractId } from "./core/facts/types.js";
+import { worktreePath } from "./git/workspace.js";
+export const CONTRACT_PLACES = Object.freeze([
+    "atlantis",
+    "hogwarts",
+    "narnia",
+    "neverland",
+    "mordor",
+    "shire",
+    "olympus",
+    "valhalla",
+    "asgard",
+    "hades",
+    "camelot",
+    "avalon",
+    "utopia",
+    "azkaban",
+    "konoha",
+    "namek",
+    "laputa",
+    "tatooine",
+    "stomach",
+    "eyeball",
+    "braincell",
+    "appendix",
+    "nostril",
+    "armpit",
+    "chineseroom",
+    "catbox",
+    "babel",
+    "teapot",
+    "blackhole",
+    "wormhole",
+    "devnull",
+    "localhost",
+    "recyclebin",
+    "bikeshed",
+    "serverroom",
+    "spawnpoint",
+    "bossroom",
+    "hiddenlevel",
+    "warpzone",
+    "styx",
+    "limbo",
+    "purgatory",
+    "penglai",
+    "longgong",
+    "nantianmen",
+    "guimenguan",
+    "naiheqiao",
+    "backrooms",
+    "bermuda",
+    "upsidedown",
+    "mindpalace",
+    "pandorabox",
+    "friendzone",
+    "comfortzone",
+    "echochamber",
+    "rabbithole",
+    "ivorytower",
+    "doghouse",
+    "panicroom",
+    "shoebox",
+    "snowglobe",
+    "dollhouse",
+    "donuthole",
+    "dumpster",
+    "blanketfort",
+    "kotatsu",
+    "fishbowl",
+    "pokeball",
+    "pineapple",
+    "titanic",
+    "disneyland",
+    "ikea",
+    "costco",
+    "warppipe",
+    "tetris",
+    "minecraft",
+    "ufo",
+    "catbus",
+    "timemachine",
+    "moonbox",
+    "huaguoshan",
+    "pansidong",
+    "bellybutton",
+    "sock",
+    "spam",
+    "downloads",
+    "toilet",
+    "blender",
+    "toaster",
+    "litterbox",
+    "kiddiepool",
+    "beanbag",
+    "vacuum",
+    "elevator",
+    "glovebox",
+    "attic",
+    "cloud",
+    "wall",
+    "can",
+    "cup",
+    "wc",
+    "bean",
+    "bus",
+    "helicopter",
+    "commandroom",
+    "box",
+    "jar",
+    "pot",
+    "wok",
+    "bowl",
+    "bucket",
+    "drawer",
+    "sofa",
+    "fridge",
+    "microwave",
+    "well",
+    "ditch",
+    "puddle",
+    "tent",
+    "cave",
+    "shed",
+    "garage",
+    "basement",
+    "balcony",
+    "corner",
+    "pigpen",
+    "henhouse",
+    "excavator",
+    "tank",
+    "submarine",
+    "treehouse",
+    "igloo",
+    "phonebooth",
+    "mailbox",
+    "doormat",
+    "bathtub",
+    "wardrobe",
+    "quicksand",
+    "tarpit",
+    "haystack",
+    "manhole",
+    "chimney",
+    "dryer",
+    "fittingroom",
+    "lazysusan",
+    "revolvingdoor",
+    "minibar",
+    "casino",
+    "karaoke",
+    "pinball",
+    "funhouse",
+    "burrito",
+    "dumpling",
+    "hotpot",
+    "bento",
+    "teabag",
+    "fortunecookie",
+    "airlock",
+    "escapepod",
+    "hammock",
+    "legroom",
+    "sidequest",
+    "lootbox",
+    "gutter",
+    "pawnshop",
+    "hermitcrab",
+    "couchgap",
+    "dumbwaiter",
+    "petridish",
+    "baggageclaim",
+    "morgue",
+    "ballpit",
+    "clawmachine",
+]);
+const PLACE_INDEX = new Map(CONTRACT_PLACES.map((base, index) => [base, index]));
+const PLACE_VERSION = 1;
+const GENERATION_SUFFIX = /^(?:[2-9]|[1-9][0-9]+)$/u;
+function placePaths(repository) {
+    return {
+        authority: join(repository.commonDirectory, "keiyaku", "places.json"),
+        lock: join(repository.commonDirectory, "keiyaku", "locks", "places.sqlite"),
+    };
+}
+export function placeRegisterPath(repository) {
+    return placePaths(repository).authority;
+}
+function indexedRegister(appointments) {
+    return {
+        appointments,
+        byPlace: new Map(appointments.map((appointment) => [appointment.place, appointment])),
+        byContract: new Map(appointments.map((appointment) => [appointment.contract, appointment])),
+    };
+}
+function parsedPlace(value) {
+    if (PLACE_INDEX.has(value))
+        return { base: value, generation: 1n };
+    for (let end = value.length - 1; end > 0; end -= 1) {
+        const base = value.slice(0, end);
+        const suffix = value.slice(end);
+        if (PLACE_INDEX.has(base) && GENERATION_SUFFIX.test(suffix)) {
+            return { base, generation: BigInt(suffix) };
+        }
+    }
+    return undefined;
+}
+function composePlace(base, generation) {
+    return (generation === 1n ? base : `${base}${generation.toString()}`);
+}
+export function place(value) {
+    if (parsedPlace(value) === undefined)
+        throw new TypeError(`Place is not canonical: ${value}`);
+    return value;
+}
+export function nextPlace(current) {
+    if (current === undefined)
+        return place(CONTRACT_PLACES[0]);
+    const parsed = parsedPlace(current);
+    if (parsed === undefined)
+        throw new TypeError(`Place is not canonical: ${current}`);
+    const index = PLACE_INDEX.get(parsed.base);
+    return index + 1 < CONTRACT_PLACES.length
+        ? composePlace(CONTRACT_PLACES[index + 1], parsed.generation)
+        : composePlace(CONTRACT_PLACES[0], parsed.generation + 1n);
+}
+export function firstFreePlace(register) {
+    for (let candidate = nextPlace();; candidate = nextPlace(candidate)) {
+        if (!register.byPlace.has(candidate))
+            return candidate;
+    }
+}
+export function canonicalPlaceRegister(register) {
+    const appointments = Object.fromEntries(register.appointments
+        .slice()
+        .sort((left, right) => Buffer.compare(Buffer.from(left.place), Buffer.from(right.place)))
+        .map((appointment) => [appointment.place, appointment.contract]));
+    return `${JSON.stringify({ version: PLACE_VERSION, appointments })}\n`;
+}
+function placeCorruption(path, message, cause) {
+    throw new AuthorityCorruptionError(`${message}: ${path}`, cause === undefined ? {} : { cause });
+}
+export function decodePlaceRegister(path, bytes) {
+    let value;
+    try {
+        if (!bytes.endsWith("\n") || bytes.slice(0, -1).includes("\n")) {
+            placeCorruption(path, "Place file is not one canonical JSON line");
+        }
+        value = JSON.parse(bytes);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError)
+            throw error;
+        return placeCorruption(path, "invalid Place JSON", error);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        placeCorruption(path, "Place file must be an object");
+    }
+    const record = value;
+    if (Object.keys(record).length !== 2 || !Object.hasOwn(record, "version") || !Object.hasOwn(record, "appointments")) {
+        placeCorruption(path, "Place file has invalid fields");
+    }
+    if (record.version !== PLACE_VERSION)
+        placeCorruption(path, `Place file version must be ${PLACE_VERSION}`);
+    if (typeof record.appointments !== "object" || record.appointments === null || Array.isArray(record.appointments)) {
+        placeCorruption(path, "Place appointments must be an object");
+    }
+    const appointments = [];
+    const contracts = new Set();
+    for (const [rawPlace, rawContract] of Object.entries(record.appointments)) {
+        if (typeof rawContract !== "string")
+            placeCorruption(path, "Place appointment must be a ContractId");
+        try {
+            const appointed = { place: place(rawPlace), contract: contractId(rawContract) };
+            if (contracts.has(appointed.contract))
+                placeCorruption(path, "Place file has duplicate Contract appointment");
+            contracts.add(appointed.contract);
+            appointments.push(appointed);
+        }
+        catch (error) {
+            return placeCorruption(path, "Place appointment is invalid", error);
+        }
+    }
+    appointments.sort((left, right) => Buffer.compare(Buffer.from(left.place), Buffer.from(right.place)));
+    const register = indexedRegister(appointments);
+    if (canonicalPlaceRegister(register) !== bytes)
+        placeCorruption(path, "Place bytes are not canonical");
+    return register;
+}
+export function emptyPlaceRegister() {
+    return indexedRegister([]);
+}
+export async function readPlaceRegister(repository) {
+    const path = placePaths(repository).authority;
+    try {
+        return decodePlaceRegister(path, await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return emptyPlaceRegister();
+        throw error;
+    }
+}
+export function appointmentFor(register, contract) {
+    return register.byContract.get(contract);
+}
+async function mutatePlaceRegister(repository, mutate) {
+    const location = placePaths(repository);
+    const held = await acquireSqliteTransactionLock({ path: location.lock, mode: "immediate" });
+    try {
+        const current = await readPlaceRegister(repository);
+        const next = mutate(current);
+        const bytes = canonicalPlaceRegister(next);
+        try {
+            if (await readFile(location.authority, "utf8") === bytes)
+                return next;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        await mkdir(dirname(location.authority), { recursive: true });
+        await replaceFileDurably(location.authority, bytes);
+        return next;
+    }
+    finally {
+        held.close();
+    }
+}
+function withAppointments(register, contracts) {
+    const additions = [];
+    const occupied = new Set(register.byPlace.keys());
+    const known = new Set(register.byContract.keys());
+    let cursor;
+    for (const contract of contracts) {
+        if (known.has(contract))
+            continue;
+        let candidate = cursor === undefined ? nextPlace() : nextPlace(cursor);
+        while (occupied.has(candidate))
+            candidate = nextPlace(candidate);
+        additions.push({ place: candidate, contract });
+        occupied.add(candidate);
+        known.add(contract);
+        cursor = candidate;
+    }
+    return additions.length === 0 ? register : indexedRegister([...register.appointments, ...additions]);
+}
+export async function appointManagedWorktrees(repository, contracts) {
+    return await mutatePlaceRegister(repository, (current) => withAppointments(current, contracts));
+}
+export async function appointManagedWorktree(repository, contract) {
+    const appointed = appointmentFor(await appointManagedWorktrees(repository, [contract]), contract);
+    if (appointed === undefined)
+        throw new Error(`Place appointment was not recorded: ${contract}`);
+    return appointed;
+}
+export async function releaseManagedWorktrees(repository, contracts) {
+    if (contracts.length === 0)
+        return;
+    const drop = new Set(contracts);
+    await mutatePlaceRegister(repository, (current) => {
+        const kept = current.appointments.filter((appointment) => !drop.has(appointment.contract));
+        return kept.length === current.appointments.length ? current : indexedRegister(kept);
+    });
+}
+export async function releaseManagedWorktree(repository, contract) {
+    await releaseManagedWorktrees(repository, [contract]);
+}
+export async function readManagedWorktreeAppointment(repository, contract, register) {
+    try {
+        const snapshot = register ?? await readPlaceRegister(repository);
+        const appointed = appointmentFor(snapshot, contract);
+        return appointed === undefined
+            ? { kind: "unappointed" }
+            : { kind: "appointed", place: appointed.place, path: worktreePath(repository, appointed.place) };
+    }
+    catch (error) {
+        return { kind: "failed", diagnostic: error instanceof Error ? error.message : String(error) };
+    }
+}

package/build/src/world.d.ts

@@ -2,12 +2,23 @@ declare const WORLD_BRAND: unique symbol;
 export type WorldRoot = string & {
     readonly [WORLD_BRAND]: true;
 };
+export type WorldResolutionInput = Readonly<{
+    cwd: string;
+    repositoryRoot?: string;
+}>;
+export type WorldResolution = Readonly<{
+    root: WorldRoot | null;
+    candidate: WorldRoot | null;
+    establish: () => Promise<WorldRoot>;
+}>;
 export declare class WorldError extends Error {
     readonly kind: "invalid-world" | "home-world" | "root-world";
     constructor(kind: "invalid-world" | "home-world" | "root-world", message: string);
 }
+type WorldInput = string | WorldResolutionInput;
 export declare const World: Readonly<{
-    locate(input: string): WorldRoot | null;
-    at(input: string): WorldRoot;
+    resolve(input: WorldInput): Promise<WorldResolution>;
+    locate(input: WorldInput): Promise<WorldRoot | null>;
+    at(input: string): Promise<WorldRoot>;
 }>;
 export {};

package/build/src/world.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { mkdir, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
 const WORLD_BRAND = Symbol("keiyaku.world");
@@ -10,28 +10,28 @@ export class WorldError extends Error {
         this.kind = kind;
     }
 }
-function homeRoot() {
+async function homeRoot() {
     try {
-        return realpathSync(resolve(homedir()));
+        return await realpath(resolve(homedir()));
     }
     catch {
         return resolve(homedir());
     }
 }
-function directory(input, label) {
+async function directory(input, label) {
     if (typeof input !== "string" || input.trim().length === 0) {
         throw new TypeError(`${label} must be a nonblank path`);
     }
     const path = resolve(input);
     let real;
     try {
-        real = realpathSync(path);
+        real = await realpath(path);
     }
     catch (error) {
         throw new WorldError("invalid-world", `world path is not an existing directory: ${path}`);
     }
     try {
-        if (!statSync(real).isDirectory())
+        if (!(await stat(real)).isDirectory())
             throw new Error("not a directory");
     }
     catch {
@@ -41,63 +41,96 @@ function directory(input, label) {
 }
 function brand(path) { return path; }
 function marker(root) { return join(root, ".keiyaku"); }
-function rejectReservedRoot(root) {
-    if (root === homeRoot()) {
+async function rejectReservedRoot(root) {
+    if (root === await homeRoot()) {
         throw new WorldError("home-world", "the user home directory cannot be a Keiyaku world");
     }
     if (root === parse(root).root) {
         throw new WorldError("root-world", "the filesystem root cannot be a Keiyaku world");
     }
 }
-function ensureMarker(root) {
+async function ensureMarker(root) {
     const path = marker(root);
-    if (existsSync(path)) {
-        try {
-            if (!statSync(path).isDirectory())
-                throw new Error("not a directory");
-        }
-        catch {
+    try {
+        if (!(await stat(path)).isDirectory())
+            throw new Error("not a directory");
+        return;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
             throw new WorldError("invalid-world", `world marker is not a directory: ${path}`);
         }
-        return;
     }
-    mkdirSync(path, { recursive: true });
-}
-function exact(input) {
-    const root = directory(input, "world");
-    rejectReservedRoot(root);
-    ensureMarker(root);
-    return brand(root);
+    await mkdir(path, { recursive: true });
 }
-function locateInput(input) {
-    return directory(input, "world location");
+async function inputValues(input, label) {
+    if (typeof input === "string")
+        return { cwd: await directory(input, label) };
+    if (input === null || typeof input !== "object")
+        throw new TypeError(`${label} must be a path or resolution input`);
+    const cwd = await directory(input.cwd, `${label} cwd`);
+    if (input.repositoryRoot === undefined)
+        return { cwd };
+    return { cwd, repositoryRoot: await directory(input.repositoryRoot, `${label} repository root`) };
 }
-export const World = Object.freeze({
-    locate(input) {
-        let candidate = locateInput(input);
-        const home = homeRoot();
-        for (;;) {
-            const filesystemRoot = parse(candidate).root;
-            if (candidate !== home && candidate !== filesystemRoot && existsSync(marker(candidate))) {
-                try {
-                    if (!statSync(marker(candidate)).isDirectory()) {
-                        throw new WorldError("invalid-world", `world marker is not a directory: ${marker(candidate)}`);
-                    }
-                }
-                catch (error) {
-                    if (error instanceof WorldError)
-                        throw error;
+async function locateMarker(input) {
+    let candidate = input;
+    const home = await homeRoot();
+    for (;;) {
+        const filesystemRoot = parse(candidate).root;
+        if (candidate !== home && candidate !== filesystemRoot) {
+            try {
+                if (!(await stat(marker(candidate))).isDirectory()) {
                     throw new WorldError("invalid-world", `world marker is not a directory: ${marker(candidate)}`);
                 }
                 return brand(candidate);
             }
-            const parent = dirname(candidate);
-            if (parent === candidate || candidate === filesystemRoot)
-                return null;
-            candidate = parent;
+            catch (error) {
+                if (error instanceof WorldError)
+                    throw error;
+                if (error.code !== "ENOENT") {
+                    throw new WorldError("invalid-world", `world marker is not a directory: ${marker(candidate)}`);
+                }
+            }
         }
-    },
-    at(input) {
-        return exact(input);
-    },
+        const parent = dirname(candidate);
+        if (parent === candidate || candidate === filesystemRoot)
+            return null;
+        candidate = parent;
+    }
+}
+async function exact(input) {
+    const root = await directory(input, "world");
+    await rejectReservedRoot(root);
+    await ensureMarker(root);
+    return brand(root);
+}
+async function resolved(input) {
+    const values = await inputValues(input, "world location");
+    const root = values.repositoryRoot === undefined ? await locateMarker(values.cwd) : brand(values.repositoryRoot);
+    const selected = root ?? brand(values.cwd);
+    let candidate = selected;
+    try {
+        await rejectReservedRoot(selected);
+    }
+    catch (error) {
+        if (root !== null || !(error instanceof WorldError))
+            throw error;
+        candidate = null;
+    }
+    return Object.freeze({
+        root,
+        candidate,
+        async establish() {
+            const established = candidate ?? brand(values.cwd);
+            await rejectReservedRoot(established);
+            await ensureMarker(established);
+            return established;
+        },
+    });
+}
+export const World = Object.freeze({
+    resolve(input) { return resolved(input); },
+    async locate(input) { return (await resolved(input)).root; },
+    at(input) { return exact(input); },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/keiyaku",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "files": [
     "build"
   ],
@@ -34,7 +34,7 @@
   "scripts": {
     "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('build', { recursive: true, force: true })\" && tsc -p tsconfig.json && node scripts/copy-integrations.js && node --input-type=module -e \"import { chmodSync } from 'node:fs'; chmodSync('build/src/cli/index.js', 0o755)\"",
     "review:model-impact": "node --import tsx scripts/model-change-impact.ts",
-    "test": "npm run test:architecture && npm run test:maintainability && npm run test:reachability && node --import tsx scripts/run-tests.mjs",
+    "test": "npm run build && npm run test:architecture && npm run test:maintainability && npm run test:reachability && node --import tsx scripts/run-tests.mjs",
     "test:architecture": "node --import tsx scripts/check-architecture.ts",
     "test:e2e": "npm run build && node --import tsx --test tests/packaged-cli.e2e.ts",
     "test:maintainability": "node scripts/check-maintainability.js",
@@ -51,6 +51,7 @@
     "typescript": "^5.9.0"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^1.3.0",
     "@anthropic-ai/claude-agent-sdk": "^0.3.226",
     "@earendil-works/pi-coding-agent": "0.80.10",
     "@opencode-ai/sdk": "1.18.3",

package/build/src/protocol/read/audit.d.ts

@@ -1,31 +0,0 @@
-import { type GitDecodeChannel } from "../../git/read-observation.js";
-import type { GitRepository } from "../../git/repository.js";
-import type { ContractId, ContractState, DeliverData, FactKind, Gate, JournalEntry, SnapshotId } from "../../core/facts/types.js";
-export type { FactKind } from "../../core/facts/types.js";
-export type TimelineEntry = Readonly<{
-    kind: FactKind;
-    at: string;
-    sincePrior: number | null;
-    attestation?: Readonly<{
-        gate: Gate;
-        verdict: "satisfied" | "unsatisfied";
-        summary?: string;
-    }>;
-}>;
-export type AuditReport = Readonly<{
-    reworks: number;
-    reviews: number;
-    timeline: readonly TimelineEntry[];
-    delivery?: DeliverData;
-    targetObservation?: Readonly<{
-        head: SnapshotId | null;
-        drift: boolean;
-    }>;
-}>;
-type AuditRead = Readonly<{
-    state: ContractState | null;
-    entries: readonly JournalEntry[];
-    report: AuditReport;
-}>;
-export declare function auditReport(entries: readonly JournalEntry[], reviewed: Gate, state?: ContractState, targetObservation?: AuditReport["targetObservation"]): AuditReport;
-export declare function readAuditAt(repository: GitRepository, channel: GitDecodeChannel, contract: ContractId, reviewed: Gate): Promise<AuditRead>;