@astrosheep/keiyaku 4.0.2 → 4.0.4

package/build/src/dispatch/index.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
+import { join } from "node:path";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
 import { parseAkuId } from "../akuma/identity.js";
+import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, readBlob, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.js";
 import { withGitDecodeChannel, withGitReadObservation } from "../git/read-observation.js";
 const DISPATCH_ROOT = "dispatch";
@@ -123,46 +125,55 @@ export async function publishDispatch(input) {
     const owner = contractId(input.contractId);
     const intended = { akuId, contractId: owner, dispatchedAt: new Date().toISOString() };
     const path = pathFor(akuId);
-    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
-        const snapshot = await readGitPaths(input.repository, [path]);
-        const current = await dispatchFromSnapshot(input.repository, snapshot, akuId);
-        if (current !== null) {
-            return current.contractId === owner
-                ? { kind: "dispatched", dispatch: current }
-                : { kind: "failed", failure: { kind: "conflict", current } };
-        }
-        const changes = new Map();
-        if (snapshot.commit === null) {
-            changes.set(GIT_FORMAT_PATH, { oid: await writeBlob(input.repository, GIT_FORMAT_BYTES) });
-        }
-        changes.set(path, { oid: await writeBlob(input.repository, bytesFor(intended)) });
-        const tree = await updateGitTree(input.repository, snapshot.tree, changes);
-        const commit = await writeCommit({
-            repository: input.repository,
-            tree,
-            parent: snapshot.commit,
-            message: `dispatch ${akuId}`,
-            at: intended.dispatchedAt,
-        });
-        const publication = await updateRefsAtomically(input.repository, [{
-                ref: GIT_REF,
-                newOid: commit,
-                expectedOid: snapshot.commit,
-            }]);
-        if (publication.kind === "published")
-            return { kind: "dispatched", dispatch: intended };
-        const observed = await observedPublication(input.repository, akuId, owner);
-        if (observed !== null)
-            return observed;
-        if (publication.kind === "non-published") {
-            const fresh = await readGitPaths(input.repository, [path]);
-            if (fresh.commit === snapshot.commit) {
-                return {
-                    kind: "failed",
-                    failure: { kind: "publication-failed", diagnostic: diagnostic(publication.error) },
-                };
+    const held = await acquireSqliteTransactionLock({
+        path: join(input.repository.commonDirectory, "keiyaku", "locks", "dispatch.sqlite"),
+        mode: "immediate",
+    });
+    try {
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+            const snapshot = await readGitPaths(input.repository, [path]);
+            const current = await dispatchFromSnapshot(input.repository, snapshot, akuId);
+            if (current !== null) {
+                return current.contractId === owner
+                    ? { kind: "dispatched", dispatch: current }
+                    : { kind: "failed", failure: { kind: "conflict", current } };
+            }
+            const changes = new Map();
+            if (snapshot.commit === null) {
+                changes.set(GIT_FORMAT_PATH, { oid: await writeBlob(input.repository, GIT_FORMAT_BYTES) });
+            }
+            changes.set(path, { oid: await writeBlob(input.repository, bytesFor(intended)) });
+            const tree = await updateGitTree(input.repository, snapshot.tree, changes);
+            const commit = await writeCommit({
+                repository: input.repository,
+                tree,
+                parent: snapshot.commit,
+                message: `dispatch ${akuId}`,
+                at: intended.dispatchedAt,
+            });
+            const publication = await updateRefsAtomically(input.repository, [{
+                    ref: GIT_REF,
+                    newOid: commit,
+                    expectedOid: snapshot.commit,
+                }]);
+            if (publication.kind === "published")
+                return { kind: "dispatched", dispatch: intended };
+            const observed = await observedPublication(input.repository, akuId, owner);
+            if (observed !== null)
+                return observed;
+            if (publication.kind === "non-published") {
+                const fresh = await readGitPaths(input.repository, [path]);
+                if (fresh.commit === snapshot.commit) {
+                    return {
+                        kind: "failed",
+                        failure: { kind: "publication-failed", diagnostic: diagnostic(publication.error) },
+                    };
+                }
             }
         }
+        return { kind: "failed", failure: { kind: "contention" } };
+    }
+    finally {
+        held.close();
     }
-    return { kind: "failed", failure: { kind: "contention" } };
 }

package/build/src/git/hooks.d.ts

@@ -1,4 +1,3 @@
-import { type Settings } from "../settings.js";
 export type HookCommand = Readonly<{
     argv: readonly string[];
     timeoutMs: number;
@@ -29,9 +28,6 @@ export type WorktreeHookLag = Readonly<{
     failure: HookFailure;
 }>;
 type HookPhase = "create" | "destroy";
-export declare function worktreeHooksFrom(input: Readonly<{
-    settings: Settings;
-}>): WorktreeHooks;
 export declare function hookMarkerPath(administrationDirectory: string): string;
 export type HookCommandRun = Readonly<{
     kind: "ok";

package/build/src/git/hooks.js

@@ -4,46 +4,10 @@ import { fileURLToPath } from "node:url";
 import { replaceFileDurably } from "../coordination/durable-file.js";
 import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { runProcess, runProcessToExit } from "../runtime/proc/run.js";
-import { SettingsError } from "../settings.js";
 const MARKER_VERSION = 1;
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-export function worktreeHooksFrom(input) {
-    if (!object(input))
-        throw new TypeError("worktreeHooksFrom input must be an object");
-    const view = input.settings.namespace("worktree");
-    if (view.kind === "failed") {
-        throw new SettingsError(view.failures.map((failure) => `${failure.scope}: ${failure.diagnostic}`).join("; "));
-    }
-    for (const entry of view.entries) {
-        if (entry.name !== "create" && entry.name !== "destroy")
-            throw new SettingsError(`worktree has unknown entry: ${entry.name}`);
-    }
-    const commands = (phase) => {
-        const selected = view.entries.find((entry) => entry.name === phase);
-        if (selected === undefined)
-            return Object.freeze([]);
-        if (!Array.isArray(selected.value))
-            throw new SettingsError(`worktree.${phase} must be an array`);
-        return Object.freeze(selected.value.map((item, index) => {
-            if (!object(item))
-                throw new SettingsError(`worktree.${phase}[${index}] must be an object`);
-            const coordinate = `worktree.${phase}[${index}]`;
-            exactKeys(item, ["argv", "timeoutMs"], coordinate);
-            if (!Array.isArray(item.argv) || item.argv.length === 0 || !item.argv.every((value) => typeof value === "string")) {
-                throw new SettingsError(`${coordinate}.argv must be a nonempty string array`);
-            }
-            if (item.argv[0].trim().length === 0)
-                throw new SettingsError(`${coordinate}.argv[0] must be nonblank`);
-            if (!Number.isSafeInteger(item.timeoutMs) || item.timeoutMs < 1 || item.timeoutMs > 2_147_483_647) {
-                throw new SettingsError(`${coordinate}.timeoutMs must be an integer from 1 through 2147483647`);
-            }
-            return Object.freeze({ argv: Object.freeze([...item.argv]), timeoutMs: item.timeoutMs });
-        }));
-    };
-    return Object.freeze({ create: commands("create"), destroy: commands("destroy") });
-}
 function exactKeys(value, keys, coordinate) {
     const actual = Object.keys(value).sort();
     const expected = [...keys].sort();

package/build/src/git/integration.d.ts

@@ -2,7 +2,7 @@ import type { Preparation } from "../core/decide.js";
 import type { ChangeId, ContractCoordinates, ContractId, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import { type GitRepository } from "./repository.js";
-import type { TenderCapture } from "./tender.js";
+import type { DeliveryCommitMetadata, TenderCapture } from "./tender.js";
 declare const REQUIRED_GIT: "2.38";
 export type IntegrationPreparationRefusal = Readonly<{
     kind: "integration-failed";
@@ -26,11 +26,7 @@ export type IntegrationPlan = Readonly<{
 /** Mint the one worktree-content identity shared by review and delivery. */
 export declare function worktreeChangeId(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture): Promise<ChangeId>;
 /** Materialize the exact integration tree against its observed predecessor. */
-export declare function materializeIntegrationSnapshot(repository: GitRepository, tree: GitObjectId, parent: SnapshotId, input: Readonly<{
-    contractId: ContractId;
-    title: string;
-    message?: string;
-}>): Promise<SnapshotId>;
+export declare function materializeIntegrationSnapshot(repository: GitRepository, tree: GitObjectId, parent: SnapshotId, metadata: DeliveryCommitMetadata): Promise<SnapshotId>;
 export declare function planIntegration(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture, requireBranchesToBeUpToDate: boolean): Promise<Preparation<IntegrationPlan, Readonly<{
     kind: "target-missing";
     contractId: ContractId;

package/build/src/git/integration.js

@@ -44,14 +44,14 @@ export async function worktreeChangeId(repository, input, tender) {
     return mintChangeId(id === "" ? "0000000000000000000000000000000000000000" : id);
 }
 /** Materialize the exact integration tree against its observed predecessor. */
-export async function materializeIntegrationSnapshot(repository, tree, parent, input) {
-    const commit = (await runGitWithEnvironment(repository, ["commit-tree", tree, "-p", gitObjectIdForSnapshot(parent)], `${input.message ?? `${input.contractId}: ${input.title}`}\n\nKeiyaku-Contract: ${input.contractId}\n`, {
-        GIT_AUTHOR_NAME: "Keiyaku",
-        GIT_AUTHOR_EMAIL: "keiyaku@localhost",
-        GIT_COMMITTER_NAME: "Keiyaku",
-        GIT_COMMITTER_EMAIL: "keiyaku@localhost",
-        GIT_AUTHOR_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
-        GIT_COMMITTER_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
+export async function materializeIntegrationSnapshot(repository, tree, parent, metadata) {
+    const commit = (await runGitWithEnvironment(repository, ["commit-tree", tree, "-p", gitObjectIdForSnapshot(parent)], metadata.message, {
+        GIT_AUTHOR_NAME: metadata.identity.name,
+        GIT_AUTHOR_EMAIL: metadata.identity.email,
+        GIT_COMMITTER_NAME: metadata.identity.name,
+        GIT_COMMITTER_EMAIL: metadata.identity.email,
+        GIT_AUTHOR_DATE: metadata.at,
+        GIT_COMMITTER_DATE: metadata.at,
     })).toString("utf8").trim();
     return mintSnapshotId(commit);
 }

package/build/src/git/read-observation.js

@@ -39,6 +39,7 @@ function batchObjectReader(repository) {
     const child = spawn("git", ["cat-file", "--batch"], {
         cwd: repository.effectiveCwd,
         stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
     });
     const cursor = streamCursor(child.stdout);
     const cache = new Map();

package/build/src/git/reconcile.d.ts

@@ -1,5 +1,5 @@
 import { type GitOid, type GitRepository } from "./repository.js";
-import type { ContractId, ContractState } from "../core/facts/types.js";
+import type { ContractId, ContractState, SnapshotId } from "../core/facts/types.js";
 import type { GitDecodeChannel } from "./read-observation.js";
 import { type TargetCheckoutEffect, type TargetCheckoutLag } from "./target-placement.js";
 import { type WorktreeHookLag, type WorktreeHooks } from "./hooks.js";
@@ -8,6 +8,11 @@ export type Effect = Readonly<{
     kind: "worktree";
     path: string;
     action: "created" | "removed" | "unchanged";
+}> | Readonly<{
+    kind: "recovery-snapshot";
+    action: "created";
+    snapshot: SnapshotId;
+    retention: "ephemeral";
 }> | TargetCheckoutEffect | Readonly<{
     kind: "ref";
     name: string;

package/build/src/git/reconcile.js

@@ -2,14 +2,14 @@ import { access, mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
-import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, GitPlumbingError, isKeiyakuOwnedRef, readRef, registeredWorktreePaths, runGit, worktreeGitDirectory, } from "./repository.js";
+import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, GitPlumbingError, isKeiyakuOwnedRef, readRef, registeredWorktreePaths, runGit, writeCommit, worktreeGitDirectory, } from "./repository.js";
 import { contractLocator, contractPhysicalName, gitObjectIdForSnapshot, mintSnapshotId, } from "./identity.js";
 import { observeContractAt } from "./observe.js";
 import { acquireTargetPlacementFence, recoverTargetPlacement, } from "./target-placement.js";
 import { runCreateHooks, runDestroyHooks, } from "./hooks.js";
 import { worktreePath } from "./workspace.js";
 import { collectableScratchWorktrees } from "./scratch.js";
-import { terminalSealExpectations as decodeTerminalSealExpectations, terminalSealSnapshots, unsealedBytes, } from "./terminal-seal.js";
+import { terminalSealExpectations as decodeTerminalSealExpectations, terminalSealSnapshots, observeTerminalWorkspace, } from "./terminal-seal.js";
 const pathExists = (path) => access(path).then(() => true, () => false);
 function deliveryRefFor(contract) {
     return `${DELIVERY_REF_NAMESPACE}/${contractPhysicalName(contract)}`;
@@ -230,17 +230,62 @@ async function terminalSealExpectations(channel, state) {
     const objects = await channel.readObjects(snapshots.map(gitObjectIdForSnapshot));
     return decodeTerminalSealExpectations(state, objects);
 }
-async function removeSealedTerminalWorktree({ repository, topology, path, expected, hooks, retryHooks, acc }) {
+async function removeSealedTerminalWorktree({ repository, topology, path, state, expected, hooks, retryHooks, acc }) {
     if (topology.paths.has(path) && await pathExists(path)) {
-        const beforeHooks = await unsealedBytes(repository, path, expected);
-        if (beforeHooks !== null)
-            return retainTerminalWorktree(path, beforeHooks, acc);
+        const terminal = state.terminal;
+        if (terminal === null)
+            throw new Error(`terminal worktree cleanup received active Contract ${state.id}`);
+        const canRecover = terminal.kind === "abandoned";
+        let recovery = null;
+        const recordRecovery = async (workspace) => {
+            const snapshot = mintSnapshotId(await writeCommit({
+                repository,
+                tree: workspace.tree,
+                parent: gitObjectIdForSnapshot(recovery?.snapshot ?? workspace.head),
+                message: `${state.id}: ephemeral abandoned-workspace recovery\n\nKeiyaku-Contract: ${state.id}`,
+                actor: "Keiyaku Recovery",
+                at: terminal.at,
+            }));
+            const effect = {
+                kind: "recovery-snapshot",
+                action: "created",
+                snapshot,
+                retention: "ephemeral",
+            };
+            const existing = acc.effects.findIndex((item) => item.kind === "recovery-snapshot");
+            if (existing < 0)
+                acc.effects.push(effect);
+            else
+                acc.effects[existing] = effect;
+            return { snapshot, workspace };
+        };
+        const before = await observeTerminalWorkspace(repository, path, expected);
+        const beforeWorkspace = before.workspace;
+        const beforeHooks = before.unsealed;
+        if (beforeHooks !== null) {
+            if (!canRecover || beforeWorkspace.submodules.length > 0) {
+                return retainTerminalWorktree(path, beforeHooks, acc);
+            }
+            recovery = await recordRecovery(beforeWorkspace);
+        }
         const hookLag = await runDestroyHooks(path, await worktreeGitDirectory(repository, path), hooks, retryHooks);
         if (hookLag !== null)
             return retainTerminalWorktree(path, hookLag, acc);
-        const afterHooks = await unsealedBytes(repository, path, expected);
-        if (afterHooks !== null)
-            return retainTerminalWorktree(path, afterHooks, acc);
+        const after = await observeTerminalWorkspace(repository, path, expected);
+        const afterWorkspace = after.workspace;
+        const afterHooks = after.unsealed;
+        if (afterHooks !== null) {
+            if (!canRecover || afterWorkspace.submodules.length > 0) {
+                return retainTerminalWorktree(path, afterHooks, acc);
+            }
+        }
+        if (canRecover
+            && (recovery === null
+                || recovery.workspace.head !== afterWorkspace.head
+                || recovery.workspace.tree !== afterWorkspace.tree)
+            && (recovery !== null || beforeWorkspace.head !== afterWorkspace.head || beforeWorkspace.tree !== afterWorkspace.tree)) {
+            recovery = await recordRecovery(afterWorkspace);
+        }
     }
     const removal = await removeWorktree(repository, topology, path, true);
     if (removal.retained)
@@ -300,6 +345,7 @@ async function reconcileTerminalManagedWorktree({ repository, channel, hooks, re
         repository: primary,
         topology,
         path,
+        state,
         expected,
         hooks,
         retryHooks,

package/build/src/git/tender.d.ts

@@ -1,5 +1,5 @@
 import type { Preparation } from "../core/decide.js";
-import type { ContractCoordinates, ContractId, SnapshotId } from "../core/facts/types.js";
+import type { ActorId, ContractCoordinates, ContractId, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import { type GitRepository } from "./repository.js";
 import { captureWorkspaceTree } from "./workspace.js";
@@ -34,6 +34,7 @@ export type DirtyWorkspaceRefusal = Readonly<{
 export type TenderCapture = Readonly<{
     tree: GitObjectId;
     head: SnapshotId;
+    at: string;
     dirty: boolean;
     changes: Awaited<ReturnType<typeof captureWorkspaceTree>>["changes"];
 }>;
@@ -41,9 +42,23 @@ export type TenderCapture = Readonly<{
 export declare function captureTender(repository: GitRepository, input: TenderCaptureCoordinates): Promise<Preparation<TenderCapture, TenderCaptureRefusal>>;
 export declare function dirtyTenderRefusal(repository: GitRepository, contractId: ContractId, tender: TenderCapture): Promise<DirtyWorkspaceRefusal>;
 export declare function dirtyTenderDelta(repository: GitRepository, tender: TenderCapture): Promise<WorkspaceDirtyDelta | undefined>;
-/** Materialize the tender tree when it contains admitted dirty workspace bytes. */
-export declare function materializeTenderSnapshot(repository: GitRepository, tender: TenderCapture, input: Readonly<{
+type GitCommitIdentity = Readonly<{
+    name: string;
+    email: string;
+}>;
+export type DeliveryCommitMetadata = Readonly<{
+    message: string;
+    at: string;
+    identity: GitCommitIdentity;
+}>;
+export declare function prepareDeliveryCommitMetadata(repository: GitRepository, input: Readonly<{
     contractId: ContractId;
     title: string;
+    document: string;
+    at: string;
+    actor?: ActorId;
     message?: string;
-}>): Promise<SnapshotId>;
+}>): Promise<DeliveryCommitMetadata>;
+/** Materialize the tender tree when it contains admitted dirty workspace bytes. */
+export declare function materializeTenderSnapshot(repository: GitRepository, tender: TenderCapture, commit: DeliveryCommitMetadata): Promise<SnapshotId>;
+export {};

package/build/src/git/tender.js

@@ -1,6 +1,6 @@
 import { access } from "node:fs/promises";
 import { gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
-import { decodeGitNumstat, registeredWorktreePaths, runGit, runGitWithEnvironment } from "./repository.js";
+import { decodeGitNumstat, GitPlumbingError, registeredWorktreePaths, runGit, runGitWithEnvironment, } from "./repository.js";
 import { captureWorkspaceTree, worktreePath } from "./workspace.js";
 async function workspaceExists(repository, workspace, path) {
     const exists = await access(path).then(() => true, () => false);
@@ -43,21 +43,52 @@ export async function dirtyTenderDelta(repository, tender) {
     const { staged, unstaged, untracked } = tender.changes;
     return { staged, unstaged, untracked, shortStat: await dirtyShortStat(repository, tender) };
 }
-function commitMessage(contractId, title, message) {
-    const subject = message ?? `${contractId}: ${title}`;
-    return `${subject}\n\nKeiyaku-Contract: ${contractId}\n`;
+async function effectiveConfig(repository, key) {
+    try {
+        const value = (await runGit(repository, ["config", "--get", key])).toString("utf8").trim();
+        return value.length === 0 ? undefined : value;
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError && error.status === 1)
+            return undefined;
+        throw error;
+    }
+}
+function contractBody(bytes) {
+    return `${bytes.replace(/(?:\r\n|\r|\n)+$/u, "")}\n`;
+}
+export async function prepareDeliveryCommitMetadata(repository, input) {
+    let identity;
+    if (input.actor !== undefined) {
+        identity = { name: input.actor, email: "keiyaku@localhost" };
+    }
+    else {
+        const [name, email] = await Promise.all([
+            effectiveConfig(repository, "user.name"),
+            effectiveConfig(repository, "user.email"),
+        ]);
+        identity = name !== undefined && email !== undefined
+            ? { name, email }
+            : { name: "Keiyaku", email: "keiyaku@localhost" };
+    }
+    const subject = input.message ?? `${input.contractId}: ${input.title}`;
+    return {
+        message: `${subject}\n\n${contractBody(input.document)}\nKeiyaku-Contract: ${input.contractId}\n`,
+        at: input.at,
+        identity,
+    };
 }
 /** Materialize the tender tree when it contains admitted dirty workspace bytes. */
-export async function materializeTenderSnapshot(repository, tender, input) {
+export async function materializeTenderSnapshot(repository, tender, commit) {
     if (!tender.dirty)
         return tender.head;
-    const commit = (await runGitWithEnvironment(repository, ["commit-tree", tender.tree, "-p", gitObjectIdForSnapshot(tender.head)], commitMessage(input.contractId, input.title, input.message), {
-        GIT_AUTHOR_NAME: "Keiyaku",
-        GIT_AUTHOR_EMAIL: "keiyaku@localhost",
-        GIT_COMMITTER_NAME: "Keiyaku",
-        GIT_COMMITTER_EMAIL: "keiyaku@localhost",
-        GIT_AUTHOR_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
-        GIT_COMMITTER_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
+    const oid = (await runGitWithEnvironment(repository, ["commit-tree", tender.tree, "-p", gitObjectIdForSnapshot(tender.head)], commit.message, {
+        GIT_AUTHOR_NAME: commit.identity.name,
+        GIT_AUTHOR_EMAIL: commit.identity.email,
+        GIT_COMMITTER_NAME: commit.identity.name,
+        GIT_COMMITTER_EMAIL: commit.identity.email,
+        GIT_AUTHOR_DATE: commit.at,
+        GIT_COMMITTER_DATE: commit.at,
     })).toString("utf8").trim();
-    return mintSnapshotId(commit);
+    return mintSnapshotId(oid);
 }

package/build/src/git/terminal-seal.d.ts

@@ -1,6 +1,7 @@
 import type { ContractState, SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import { type GitOid, type GitRepository } from "./repository.js";
+import { captureWorkspaceTree } from "./workspace.js";
 export type UnsealedBytes = Readonly<{
     kind: "unsealed-bytes";
     path: string;
@@ -19,6 +20,19 @@ export type TerminalSealObject = Readonly<{
 }> | Readonly<{
     kind: "missing";
 }>;
+type WorkspaceTree = Awaited<ReturnType<typeof captureWorkspaceTree>>;
+export type TerminalWorkspace = Readonly<{
+    tree: GitObjectId;
+    head: SnapshotId;
+    submodules: readonly string[];
+}>;
+export type TerminalWorkspaceObservation = Readonly<{
+    workspace: TerminalWorkspace;
+    unsealed: UnsealedBytes | null;
+}>;
 export declare function terminalSealSnapshots(state: ContractState): readonly SnapshotId[];
 export declare function terminalSealExpectations(state: ContractState, objects: ReadonlyMap<GitOid, TerminalSealObject>): TerminalSealExpectations;
+export declare function unsealedWorkspaceBytes(repository: GitRepository, path: string, expected: TerminalSealExpectations, workspace: WorkspaceTree): Promise<UnsealedBytes | null>;
 export declare function unsealedBytes(repository: GitRepository, path: string, expected: TerminalSealExpectations): Promise<UnsealedBytes | null>;
+export declare function observeTerminalWorkspace(repository: GitRepository, path: string, expected: TerminalSealExpectations): Promise<TerminalWorkspaceObservation>;
+export {};

package/build/src/git/terminal-seal.js

@@ -63,8 +63,7 @@ async function changedPaths(repository, left, right) {
         throw new Error("Git tree diff paths are not NUL terminated");
     return fields.slice(0, -1).sort();
 }
-export async function unsealedBytes(repository, path, expected) {
-    const workspace = await captureWorkspaceTree(repository, path);
+export async function unsealedWorkspaceBytes(repository, path, expected, workspace) {
     const headIsSealed = expected.heads.includes(workspace.head);
     if (workspace.changes.submodules.length > 0) {
         return {
@@ -87,3 +86,17 @@ export async function unsealedBytes(repository, path, expected) {
         ...(headIsSealed ? {} : { head: workspace.head }),
     };
 }
+export async function unsealedBytes(repository, path, expected) {
+    return (await observeTerminalWorkspace(repository, path, expected)).unsealed;
+}
+export async function observeTerminalWorkspace(repository, path, expected) {
+    const captured = await captureWorkspaceTree(repository, path);
+    return {
+        workspace: {
+            tree: captured.tree,
+            head: captured.head,
+            submodules: captured.changes.submodules,
+        },
+        unsealed: await unsealedWorkspaceBytes(repository, path, expected, captured),
+    };
+}

package/build/src/git/workspace.d.ts

@@ -10,6 +10,7 @@ export type WorkspaceChanges = Readonly<{
 export type WorkspaceTree = Readonly<{
     tree: GitObjectId;
     head: SnapshotId;
+    at: string;
     dirty: boolean;
     changes: WorkspaceChanges;
 }>;

package/build/src/git/workspace.js

@@ -114,24 +114,32 @@ export async function observeTargetLag(repository, workspace, head) {
 }
 /** Capture tracked and untracked workspace bytes without changing its real index. */
 export async function captureWorkspaceTree(repository, workspace) {
-    const identities = (await runGit(repository, ["-C", workspace, "show", "-s", "--format=%H%n%T", "HEAD"]))
+    const identities = (await runGit(repository, ["-C", workspace, "show", "-s", "--format=%H%n%T%n%cI", "HEAD"]))
         .toString("utf8")
         .split("\n");
-    if (identities.length !== 3 || identities[0] === undefined || identities[1] === undefined || identities[2] !== "") {
-        throw new Error("workspace HEAD/tree resolution did not return exactly two object IDs");
+    if (identities.length !== 4
+        || identities[0] === undefined
+        || identities[1] === undefined
+        || identities[2] === undefined
+        || identities[3] !== "") {
+        throw new Error("workspace HEAD/tree/time resolution returned an unexpected shape");
     }
     const head = mintSnapshotId(identities[0]);
     const tree = gitObjectId(identities[1], "workspace tree");
+    const at = identities[2];
+    if (Number.isNaN(Date.parse(at)))
+        throw new Error("workspace HEAD has an invalid committer timestamp");
     const changes = await workspaceChanges(repository, workspace);
     const dirty = changes.staged.length > 0 || changes.unstaged.length > 0 || changes.untracked.length > 0;
     if (!dirty)
-        return { tree, head, dirty, changes };
+        return { tree, head, at, dirty, changes };
     return await withPrivateGitIndex(async (environment) => {
         await runGitWithEnvironment(repository, ["-C", workspace, "read-tree", "HEAD"], undefined, environment);
         await runGitWithEnvironment(repository, ["-C", workspace, "add", "--all"], undefined, environment);
         return {
             tree: gitObjectId((await runGitWithEnvironment(repository, ["-C", workspace, "write-tree"], undefined, environment)).toString("utf8").trim(), "workspace tree"),
             head,
+            at,
             dirty,
             changes,
         };

package/build/src/index.d.ts

@@ -3,4 +3,4 @@ export { settings } from "./settings.js";
 export { World, WorldError } from "./world.js";
 export type { WorldResolution, WorldResolutionInput, WorldRoot } from "./world.js";
 export type { Settings, SettingsEntry, SettingsInput, SettingsNamespaceFailure, SettingsNamespaceView, SettingsScope, SettingsScopeState, } from "./settings.js";
-export type { AttestationVerdict, AbandonInput, ActorId, AkuId, AkumaAddressInput, AkumaAlias, AkumaGlob, AkumaHistoryInput, AkumaHistoryResult, AkumaInterruptInput, AkumaInterruptResult, AkumaKillResult, AkumaSetAddressInput, AkumaStatus, AkumaStatusView, AkumaTellInput, AkumaTellResult, AkumaWaitInput, AkumaWaitResult, AkumaWorldScopeRefusal, AliasBinding, AliasStage, AmendResult, AmendInput, ArcInput, AuditReport, DeliveryPreparationRefusal, BindInput, BindResult, CallInput, CallObservation, CallResult, Catalog, CatalogInput, CatalogQuery, ChangeId, ContractId, ContractState, ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractListInput, ContractObservation, ContractObservationInput, ContractPhase, ContractRow, DeliverInput, Fact, FactKind, Dispatch, DispatchFailure, DispatchStage, DirectAkumaSelector, Gate, GatesFromInput, HookCommand, RequireBranchesToBeUpToDateFromInput, KeiyakuOfInput, KeiyakuRefusal, KeiyakuRetryReason, ForkInput, ForkResult, IntegrationFailure, Lag, MutationResult, PlacementStop, RegionOverlap, ReconcileInput, RepoReconcileReport, Review, ReconcileReport, ReviewInput, RepoAtInput, AuditInput, SnapshotId, SettlementAction, SettlementLag, SettlementReport, SetAkumaSelector, TaskId, TopologyEffect, VerificationReuse, VerificationStop, WorktreeHooks, } from "./library/keiyaku.js";
+export type { AttestationVerdict, AbandonInput, ActorId, AkuId, AllowedAction, AllowedActions, AkumaAddressInput, AkumaAlias, AkumaGlob, AkumaHistoryInput, AkumaHistoryResult, AkumaInterruptInput, AkumaInterruptResult, AkumaKillResult, AkumaObservation, AkumaSetAddressInput, AkumaStatus, AkumaTellInput, CreatedTaskObservation, AkumaTellResult, AkumaWaitInput, AkumaWaitResult, AkumaWorldScopeRefusal, AliasBinding, AliasStage, AmendResult, AmendInput, ArcInput, AuditReport, DeliveryPreparationRefusal, BindInput, BindResult, CallInput, CallObservation, CallResult, Catalog, CatalogInput, CatalogQuery, ChangeId, ContractId, ContractState, ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractHistory, ContractHistoryEvent, ContractListInput, ContractObservation, ContractObservationInput, ContractPhase, ContractRow, DeliverInput, Fact, FactKind, Dispatch, DispatchFailure, DispatchStage, DirectAkumaSelector, Gate, GatesFromInput, HookCommand, RequireBranchesToBeUpToDateFromInput, KeiyakuOfInput, KeiyakuRefusal, KeiyakuRetryReason, ForkInput, ForkResult, IntegrationFailure, Lag, MutationResult, PlacementStop, RegionOverlap, ReconcileInput, RepoReconcileReport, Review, ReconcileReport, ReviewInput, RepoAtInput, AuditInput, SnapshotId, SettlementAction, SettlementLag, SettlementReport, SetAkumaSelector, TaskId, TopologyEffect, VerificationReuse, VerificationStop, WorktreeHooks, } from "./library/keiyaku.js";

package/build/src/kanshi/index.d.ts

@@ -1,4 +1,4 @@
-export { kanshi } from "./read.js";
+export { kanshi, observeKanshi } from "./read.js";
 export { selectKanshi, selectRegion } from "./select.js";
 export type { KanshiInput } from "./read.js";
 export type { AkumaKanshiRow, AkumaKanshiWorld, ContractEndpointObservation, ContractHolderObservation, ContractKanshiBoard, ContractKanshiRow, KanshiReport, Section, TaskKanshiRow, TaskKanshiWorld, KanshiRegionSelection, RegionDeclaration, RegionIntersection, RegionPathMatch, RegionRead, } from "./report.js";

package/build/src/kanshi/index.js

@@ -1,2 +1,2 @@
-export { kanshi } from "./read.js";
+export { kanshi, observeKanshi } from "./read.js";
 export { selectKanshi, selectRegion } from "./select.js";

package/build/src/kanshi/read.d.ts

@@ -1,9 +1,17 @@
 import { Repo } from "../library/repo.js";
-import type { KanshiReport, KanshiRegionSelection } from "./report.js";
+import type { ContractBoard } from "../library/contract.js";
+import { type AliasBinding } from "../alias/index.js";
+import type { KanshiReport, Section, KanshiRegionSelection } from "./report.js";
 import type { WorldRoot } from "../world.js";
 export type KanshiInput = Readonly<{
     world: WorldRoot | null;
     repo?: Repo;
     region?: KanshiRegionSelection;
+    contract?: ContractBoard["rows"][number]["id"];
 }>;
+export type KanshiObservation = Readonly<{
+    report: KanshiReport;
+    aliases: Section<readonly AliasBinding[]>;
+}>;
+export declare function observeKanshi(input: KanshiInput): Promise<KanshiObservation>;
 export declare function kanshi(input: KanshiInput): Promise<KanshiReport>;