@astrosheep/keiyaku 4.0.0 → 4.0.2

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

@@ -0,0 +1,89 @@
+import { gitObjectId, gitObjectIdForSnapshot, mintSnapshotId } from "./identity.js";
+import { runGit } from "./repository.js";
+import { captureWorkspaceTree } from "./workspace.js";
+export function terminalSealSnapshots(state) {
+    return [...new Set([
+            state.coordinates.start,
+            ...(state.delivery === null ? [] : [
+                state.delivery.data.tenderSnapshot,
+                state.delivery.data.integration.snapshot,
+            ]),
+        ])];
+}
+function commitMetadata(snapshot, result) {
+    if (result === undefined || result.kind === "missing") {
+        throw new Error(`terminal seal commit is missing: ${snapshot}`);
+    }
+    if (result.type !== "commit")
+        throw new Error(`terminal seal snapshot is not a commit: ${snapshot}`);
+    const headerEnd = result.bytes.indexOf("\n\n");
+    if (headerEnd < 0)
+        throw new Error(`terminal seal commit has no headers: ${snapshot}`);
+    const headers = result.bytes.subarray(0, headerEnd).toString("ascii").split("\n");
+    const treeHeader = headers[0];
+    if (treeHeader === undefined || !treeHeader.startsWith("tree ")) {
+        throw new Error(`terminal seal commit has no root tree: ${snapshot}`);
+    }
+    return {
+        tree: gitObjectId(treeHeader.slice("tree ".length), "terminal seal tree"),
+        parents: headers
+            .filter((header) => header.startsWith("parent "))
+            .map((header) => mintSnapshotId(header.slice("parent ".length))),
+    };
+}
+export function terminalSealExpectations(state, objects) {
+    const snapshots = terminalSealSnapshots(state);
+    const metadata = new Map(snapshots.map((snapshot) => [
+        snapshot,
+        commitMetadata(snapshot, objects.get(gitObjectIdForSnapshot(snapshot))),
+    ]));
+    const treeBySnapshot = new Map([...metadata].map(([snapshot, commit]) => [snapshot, commit.tree]));
+    if (state.delivery === null) {
+        return { heads: [state.coordinates.start], trees: [...treeBySnapshot.values()], treeBySnapshot };
+    }
+    const tender = state.delivery.data.tenderSnapshot;
+    const tenderMetadata = metadata.get(tender);
+    if (tenderMetadata === undefined)
+        throw new Error(`terminal seal metadata was not resolved: ${tender}`);
+    const [tenderParent] = tenderMetadata.parents;
+    return {
+        heads: [...new Set([
+                state.coordinates.start,
+                ...(tenderParent === undefined ? [] : [tenderParent]),
+                tender,
+                state.delivery.data.integration.snapshot,
+            ])],
+        trees: [...treeBySnapshot.values()],
+        treeBySnapshot,
+    };
+}
+async function changedPaths(repository, left, right) {
+    const fields = (await runGit(repository, ["diff", "--name-only", "-z", left, right])).toString("utf8").split("\0");
+    if (fields.at(-1) !== "")
+        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);
+    const headIsSealed = expected.heads.includes(workspace.head);
+    if (workspace.changes.submodules.length > 0) {
+        return {
+            kind: "unsealed-bytes",
+            path,
+            paths: workspace.changes.submodules,
+            ...(headIsSealed ? {} : { head: workspace.head }),
+        };
+    }
+    if (headIsSealed && expected.trees.includes(workspace.tree))
+        return null;
+    const alternatives = [];
+    for (const tree of expected.trees)
+        alternatives.push(await changedPaths(repository, tree, workspace.tree));
+    alternatives.sort((left, right) => left.length - right.length || left.join("\0").localeCompare(right.join("\0")));
+    return {
+        kind: "unsealed-bytes",
+        path,
+        paths: alternatives[0] ?? [],
+        ...(headIsSealed ? {} : { head: workspace.head }),
+    };
+}

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

@@ -7,7 +7,7 @@ export type TreeChange = Readonly<{
     oid: string;
     mode?: string;
     type?: string;
-}>;
+}> | null;
 type MutableTreeNode = Readonly<{
     files: Map<string, TreeChange>;
     directories: Map<string, MutableTreeNode>;
@@ -25,7 +25,7 @@ export declare function treeUpdate(changes: ReadonlyMap<string, TreeChange>): Tr
 export declare function parseTreeObject(bytes: Buffer, oidBytes: number): Map<string, TreeEntry>;
 export declare function prepareTreeUpdate(input: Readonly<{
     update: TreeUpdate;
-    bases: ReadonlyMap<string, Map<string, TreeEntry>>;
+    bases: ReadonlyMap<string, ReadonlyMap<string, TreeEntry>>;
     oidBytes: number;
 }>): Readonly<{
     root: string;

package/build/src/git/tree.js

@@ -86,6 +86,10 @@ function record(name, change) {
 function prepareNode(node, path, bases, oidBytes, prepared) {
     const entries = new Map(bases.get(path) ?? []);
     for (const [name, change] of node.files) {
+        if (change === null) {
+            entries.delete(name);
+            continue;
+        }
         entries.set(name, {
             oid: change.oid,
             mode: change.mode ?? "100644",

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

@@ -0,0 +1,53 @@
+import type { SnapshotId } from "../core/facts/types.js";
+import { type GitObjectId } from "./identity.js";
+import { type GitRepository } from "./repository.js";
+export type WorkspaceChanges = Readonly<{
+    staged: readonly string[];
+    unstaged: readonly string[];
+    untracked: readonly string[];
+    submodules: readonly string[];
+}>;
+export type WorkspaceTree = Readonly<{
+    tree: GitObjectId;
+    head: SnapshotId;
+    dirty: boolean;
+    changes: WorkspaceChanges;
+}>;
+export declare function worktreePath(repository: GitRepository, place: string): string;
+export declare function withPrivateGitIndex<Value>(action: (environment: Readonly<{
+    GIT_INDEX_FILE: string;
+}>) => Value | PromiseLike<Value>): Promise<Value>;
+export type WorkspaceChangeCounts = Readonly<{
+    staged: number;
+    unstaged: number;
+    untracked: number;
+    submodules: number;
+}>;
+export type ContractWorkspaceLocation = Readonly<{
+    kind: "worktree";
+    path: string;
+}> | Readonly<{
+    kind: "here";
+}>;
+export type ContractWorkspaceObservation = Readonly<{
+    kind: "clean" | "dirty";
+    location: ContractWorkspaceLocation;
+    counts: WorkspaceChangeCounts;
+}> | Readonly<{
+    kind: "unavailable";
+    location: ContractWorkspaceLocation;
+}> | Readonly<{
+    kind: "unappointed";
+}>;
+export type ContractTargetLag = Readonly<{
+    kind: "counted";
+    behind: number;
+}> | Readonly<{
+    kind: "unknown";
+}> | Readonly<{
+    kind: "none";
+}>;
+export declare function observeWorkspace(repository: GitRepository, location: ContractWorkspaceLocation, workspace: string): Promise<ContractWorkspaceObservation>;
+export declare function observeTargetLag(repository: GitRepository, workspace: string, head: SnapshotId | null | undefined): Promise<ContractTargetLag>;
+/** Capture tracked and untracked workspace bytes without changing its real index. */
+export declare function captureWorkspaceTree(repository: GitRepository, workspace: string): Promise<WorkspaceTree>;

package/build/src/git/workspace.js

@@ -0,0 +1,139 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { gitObjectId, mintSnapshotId } from "./identity.js";
+import { runGit, runGitWithEnvironment } from "./repository.js";
+const WORKTREE_DIRECTORY = ["keiyaku", "wt"];
+export function worktreePath(repository, place) {
+    return resolve(repository.commonDirectory, ...WORKTREE_DIRECTORY, place);
+}
+export async function withPrivateGitIndex(action) {
+    const directory = await mkdtemp(join(tmpdir(), "keiyaku-v4-index-"));
+    try {
+        return await action({ GIT_INDEX_FILE: join(directory, "index") });
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+function fields(record, count) {
+    const result = [];
+    let start = 0;
+    while (result.length < count - 1) {
+        const separator = record.indexOf(" ", start);
+        if (separator < 0)
+            throw new Error(`malformed workspace status record: ${record}`);
+        result.push(record.slice(start, separator));
+        start = separator + 1;
+    }
+    result.push(record.slice(start));
+    return result;
+}
+async function workspaceChanges(repository, workspace) {
+    const records = (await runGit(repository, [
+        "-C", workspace,
+        "status", "--porcelain=v2", "-z", "--untracked-files=all", "--ignore-submodules=none",
+    ])).toString("utf8").split("\0");
+    const staged = new Set();
+    const unstaged = new Set();
+    const untracked = new Set();
+    const submodules = new Set();
+    for (let index = 0; index < records.length - 1; index += 1) {
+        const record = records[index];
+        const kind = record[0];
+        if (kind === "?") {
+            untracked.add(fields(record, 2)[1]);
+            continue;
+        }
+        if (kind === "1" || kind === "2" || kind === "u") {
+            const parts = fields(record, kind === "1" ? 9 : kind === "2" ? 10 : 11);
+            const xy = parts[1];
+            const sub = parts[2];
+            const path = parts.at(-1);
+            if (xy[0] !== ".")
+                staged.add(path);
+            if (xy[1] !== ".")
+                unstaged.add(path);
+            if (sub.startsWith("S") && (sub[2] !== "." || sub[3] !== "."))
+                submodules.add(path);
+            if (kind === "2") {
+                const origin = records[index + 1];
+                if (origin === undefined)
+                    throw new Error("renamed workspace status record is missing its origin path");
+                if (xy[0] !== ".")
+                    staged.add(origin);
+                if (xy[1] !== ".")
+                    unstaged.add(origin);
+                index += 1;
+            }
+            continue;
+        }
+        throw new Error(`unknown workspace status record: ${record}`);
+    }
+    return {
+        staged: [...staged].sort(),
+        unstaged: [...unstaged].sort(),
+        untracked: [...untracked].sort(),
+        submodules: [...submodules].sort(),
+    };
+}
+function countsOf(changes) {
+    return {
+        staged: changes.staged.length,
+        unstaged: changes.unstaged.length,
+        untracked: changes.untracked.length,
+        submodules: changes.submodules.length,
+    };
+}
+export async function observeWorkspace(repository, location, workspace) {
+    try {
+        const counts = countsOf(await workspaceChanges(repository, workspace));
+        const dirty = counts.staged > 0 || counts.unstaged > 0 || counts.untracked > 0 || counts.submodules > 0;
+        return { kind: dirty ? "dirty" : "clean", location, counts };
+    }
+    catch {
+        return { kind: "unavailable", location };
+    }
+}
+export async function observeTargetLag(repository, workspace, head) {
+    if (head === undefined)
+        return { kind: "none" };
+    if (head === null)
+        return { kind: "unknown" };
+    try {
+        const text = (await runGit(repository, ["-C", workspace, "rev-list", "--count", `HEAD..${head}`]))
+            .toString("utf8")
+            .trim();
+        if (!/^[0-9]+$/u.test(text))
+            return { kind: "unknown" };
+        return { kind: "counted", behind: Number(text) };
+    }
+    catch {
+        return { kind: "unknown" };
+    }
+}
+/** 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"]))
+        .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");
+    }
+    const head = mintSnapshotId(identities[0]);
+    const tree = gitObjectId(identities[1], "workspace tree");
+    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 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,
+            dirty,
+            changes,
+        };
+    });
+}

package/build/src/identity/selector.d.ts

@@ -1,6 +1,12 @@
 declare const AKUMA_ALIAS: unique symbol;
+declare const AKUMA_GLOB: unique symbol;
 export type AkumaAlias = string & {
     readonly [AKUMA_ALIAS]: true;
 };
+export type AkumaGlob = string & {
+    readonly [AKUMA_GLOB]: true;
+};
 export declare function parseAkumaAlias(value: string): AkumaAlias;
+export declare function parseAkumaGlob(value: string): AkumaGlob;
+export declare function matchesAkumaGlob(glob: AkumaGlob, value: string): boolean;
 export {};

package/build/src/identity/selector.js

@@ -1,7 +1,26 @@
 const AKUMA_ALIAS_PATTERN = /^@[a-z][a-z0-9-]{0,63}$/u;
+const AKUMA_GLOB_SUFFIX = /^[0-9a-f*]+$/u;
 export function parseAkumaAlias(value) {
     if (!AKUMA_ALIAS_PATTERN.test(value)) {
         throw new TypeError("Akuma alias must match ^@[a-z][a-z0-9-]{0,63}$");
     }
     return value;
 }
+export function parseAkumaGlob(value) {
+    const segments = value.split("/");
+    const archetype = segments[1] ?? "";
+    const archetypeProbe = archetype.replaceAll("*", "x");
+    if (segments.length !== 3 || segments[0] !== "aku" || !value.includes("*")
+        || archetype.length === 0 || normalizeIdentityStem({ source: archetypeProbe }) !== archetypeProbe
+        || !AKUMA_GLOB_SUFFIX.test(segments[2] ?? "")) {
+        throw new TypeError("Akuma glob must be aku/<akuma-pattern>/<hex-pattern> and contain *");
+    }
+    return value;
+}
+export function matchesAkumaGlob(glob, value) {
+    const pattern = parseAkumaGlob(glob)
+        .replaceAll(/[.+?^${}()|[\]\\]/gu, "\\$&")
+        .replaceAll("*", "[^/]*");
+    return new RegExp(`^${pattern}$`, "u").test(value);
+}
+import { normalizeIdentityStem } from "./normalize.js";

package/build/src/index.d.ts

@@ -1,4 +1,6 @@
-export { AuthorityCorruptionError, Delivery, gatesFrom, Keiyaku, KeiyakuRefused, KeiyakuRetry, NoGitWorldError, Repo, SettingsError, worktreeHooksFrom } from "./library/keiyaku.js";
+export { AuthorityCorruptionError, AkumaWorldScopeError, Delivery, gatesFrom, Keiyaku, KeiyakuRefused, KeiyakuRetry, NoGitWorldError, Repo, requireBranchesToBeUpToDateFrom, SettingsError, worktreeHooksFrom } from "./library/keiyaku.js";
 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, AkumaAlias, AkumaStatus, AliasBinding, AliasStage, AmendResult, AmendInput, ArcInput, AuditReport, BindInput, BindResult, CallInput, CallObservation, CallResult, ChangeId, ContractId, ContractState, ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractListInput, ContractObservation, ContractObservationInput, ContractPhase, ContractRow, DeliverInput, Fact, FactKind, Dispatch, DispatchFailure, DispatchStage, Gate, GatesFromInput, HookCommand, KeiyakuOfInput, KeiyakuRefusal, KeiyakuRetryReason, ForkInput, ForkResult, IntegrationFailure, Lag, MutationResult, PlacementStop, RegionOverlap, ReconcileInput, RepoReconcileReport, Review, ReconcileReport, ReviewInput, RepoAtInput, AuditInput, SnapshotId, SettlementAction, SettlementLag, SettlementReport, TaskId, TimelineEntry, TopologyEffect, VerificationStop, WorktreeHooks, WorktreeHooksFromInput, } from "./library/keiyaku.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";

package/build/src/index.js

@@ -1,2 +1,3 @@
-export { AuthorityCorruptionError, Delivery, gatesFrom, Keiyaku, KeiyakuRefused, KeiyakuRetry, NoGitWorldError, Repo, SettingsError, worktreeHooksFrom } from "./library/keiyaku.js";
+export { AuthorityCorruptionError, AkumaWorldScopeError, Delivery, gatesFrom, Keiyaku, KeiyakuRefused, KeiyakuRetry, NoGitWorldError, Repo, requireBranchesToBeUpToDateFrom, SettingsError, worktreeHooksFrom } from "./library/keiyaku.js";
 export { settings } from "./settings.js";
+export { World, WorldError } from "./world.js";

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

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

package/build/src/kanshi/index.js

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

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

@@ -1,5 +1,9 @@
-import type { KanshiReport } from "./report.js";
+import { Repo } from "../library/repo.js";
+import type { KanshiReport, KanshiRegionSelection } from "./report.js";
+import type { WorldRoot } from "../world.js";
 export type KanshiInput = Readonly<{
-    path?: string;
+    world: WorldRoot | null;
+    repo?: Repo;
+    region?: KanshiRegionSelection;
 }>;
-export declare function kanshi(input?: KanshiInput): Promise<KanshiReport>;
+export declare function kanshi(input: KanshiInput): Promise<KanshiReport>;