@astrosheep/keiyaku 4.0.1 → 4.0.2

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

@@ -1,4 +1,4 @@
-import type { ContractId, SnapshotId } from "../core/facts/types.js";
+import type { SnapshotId } from "../core/facts/types.js";
 import { type GitObjectId } from "./identity.js";
 import { type GitRepository } from "./repository.js";
 export type WorkspaceChanges = Readonly<{
@@ -13,9 +13,41 @@ export type WorkspaceTree = Readonly<{
     dirty: boolean;
     changes: WorkspaceChanges;
 }>;
-export declare function deliveryWorktreePath(repository: GitRepository, contract: ContractId): string;
+export declare function worktreePath(repository: GitRepository, place: string): string;
 export declare function withPrivateGitIndex<Value>(action: (environment: Readonly<{
     GIT_INDEX_FILE: string;
-}>) => Value): Value;
+}>) => 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): WorkspaceTree;
+export declare function captureWorkspaceTree(repository: GitRepository, workspace: string): Promise<WorkspaceTree>;

package/build/src/git/workspace.js

@@ -1,19 +1,19 @@
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { contractPhysicalName, gitObjectId, mintSnapshotId } from "./identity.js";
+import { gitObjectId, mintSnapshotId } from "./identity.js";
 import { runGit, runGitWithEnvironment } from "./repository.js";
 const WORKTREE_DIRECTORY = ["keiyaku", "wt"];
-export function deliveryWorktreePath(repository, contract) {
-    return resolve(repository.commonDirectory, ...WORKTREE_DIRECTORY, contractPhysicalName(contract));
+export function worktreePath(repository, place) {
+    return resolve(repository.commonDirectory, ...WORKTREE_DIRECTORY, place);
 }
-export function withPrivateGitIndex(action) {
-    const directory = mkdtempSync(join(tmpdir(), "keiyaku-v4-index-"));
+export async function withPrivateGitIndex(action) {
+    const directory = await mkdtemp(join(tmpdir(), "keiyaku-v4-index-"));
     try {
-        return action({ GIT_INDEX_FILE: join(directory, "index") });
+        return await action({ GIT_INDEX_FILE: join(directory, "index") });
     }
     finally {
-        rmSync(directory, { recursive: true, force: true });
+        await rm(directory, { recursive: true, force: true });
     }
 }
 function fields(record, count) {
@@ -29,11 +29,11 @@ function fields(record, count) {
     result.push(record.slice(start));
     return result;
 }
-function workspaceChanges(repository, workspace) {
-    const records = runGit(repository, [
+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");
+    ])).toString("utf8").split("\0");
     const staged = new Set();
     const unstaged = new Set();
     const untracked = new Set();
@@ -77,9 +77,44 @@ function workspaceChanges(repository, workspace) {
         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 function captureWorkspaceTree(repository, workspace) {
-    const identities = runGit(repository, ["-C", workspace, "show", "-s", "--format=%H%n%T", "HEAD"])
+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] !== "") {
@@ -87,15 +122,15 @@ export function captureWorkspaceTree(repository, workspace) {
     }
     const head = mintSnapshotId(identities[0]);
     const tree = gitObjectId(identities[1], "workspace tree");
-    const changes = workspaceChanges(repository, workspace);
+    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 withPrivateGitIndex((environment) => {
-        runGitWithEnvironment(repository, ["-C", workspace, "read-tree", "HEAD"], undefined, environment);
-        runGitWithEnvironment(repository, ["-C", workspace, "add", "--all"], undefined, environment);
+    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(runGitWithEnvironment(repository, ["-C", workspace, "write-tree"], undefined, environment).toString("utf8").trim(), "workspace tree"),
+            tree: gitObjectId((await runGitWithEnvironment(repository, ["-C", workspace, "write-tree"], undefined, environment)).toString("utf8").trim(), "workspace tree"),
             head,
             dirty,
             changes,

package/build/src/identity/selector.js

@@ -13,7 +13,7 @@ export function parseAkumaGlob(value) {
     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/<archetype-pattern>/<hex-pattern> and contain *");
+        throw new TypeError("Akuma glob must be aku/<akuma-pattern>/<hex-pattern> and contain *");
     }
     return value;
 }

package/build/src/index.d.ts

@@ -1,6 +1,6 @@
-export { AuthorityCorruptionError, Delivery, gatesFrom, Keiyaku, KeiyakuRefused, KeiyakuRetry, NoGitWorldError, Repo, requireBranchesToBeUpToDateFrom, 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 { WorldRoot } 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, AliasBinding, AliasStage, AmendResult, AmendInput, ArcInput, AuditReport, 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, TimelineEntry, TopologyEffect, VerificationStop, WorktreeHooks, } 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,3 +1,3 @@
-export { AuthorityCorruptionError, Delivery, gatesFrom, Keiyaku, KeiyakuRefused, KeiyakuRetry, NoGitWorldError, Repo, requireBranchesToBeUpToDateFrom, 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, ContractHolderObservation, ContractKanshiBoard, ContractKanshiRow, 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,8 +1,9 @@
 import { Repo } from "../library/repo.js";
-import type { KanshiReport } from "./report.js";
+import type { KanshiReport, KanshiRegionSelection } from "./report.js";
 import type { WorldRoot } from "../world.js";
 export type KanshiInput = Readonly<{
     world: WorldRoot | null;
     repo?: Repo;
+    region?: KanshiRegionSelection;
 }>;
 export declare function kanshi(input: KanshiInput): Promise<KanshiReport>;

package/build/src/kanshi/read.js

@@ -7,6 +7,10 @@ import { readDispatchesAt } from "../dispatch/index.js";
 import { readTaskHolderProjectionAt } from "../settlement/holder.js";
 import { readContractBoard } from "../protocol/read/status.js";
 import { withGitDecodeChannel, withGitReadObservation } from "../git/read-observation.js";
+import { readDocuments } from "../protocol/read/documents.js";
+import { readRegionDeclarations, validateRegionPath } from "../library/region.js";
+import { contractId } from "../core/facts/types.js";
+import { selectRegion } from "./select.js";
 function diagnostic(error) {
     let source;
     if (error instanceof Error)
@@ -24,18 +28,81 @@ function diagnostic(error) {
     const line = source.replaceAll(/\s+/gu, " ").trim();
     return line.length <= 240 ? line : `${line.slice(0, 239)}…`;
 }
+function record(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError(`kanshi ${label} must be an object`);
+    return value;
+}
+function exactKeys(value, allowed, label) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new TypeError(`kanshi ${label} has unknown field: ${key}`);
+}
+function regionSelection(value) {
+    const selection = record(value, "region selection");
+    if (typeof selection.kind !== "string")
+        throw new TypeError("kanshi region selection kind must be a string");
+    if (selection.kind === "declarations") {
+        exactKeys(selection, ["kind"], "region selection");
+        return { kind: "declarations" };
+    }
+    if (selection.kind === "contract") {
+        exactKeys(selection, ["kind", "contract"], "region selection");
+        if (typeof selection.contract !== "string")
+            throw new TypeError("kanshi region contract must be a ContractId");
+        try {
+            return { kind: "contract", contract: contractId(selection.contract) };
+        }
+        catch {
+            throw new TypeError("kanshi region contract must be a canonical ContractId");
+        }
+    }
+    if (selection.kind === "overlap") {
+        exactKeys(selection, ["kind", "contract"], "region selection");
+        if (selection.contract === undefined)
+            return { kind: "overlap" };
+        if (typeof selection.contract !== "string")
+            throw new TypeError("kanshi region contract must be a ContractId");
+        try {
+            return { kind: "overlap", contract: contractId(selection.contract) };
+        }
+        catch {
+            throw new TypeError("kanshi region contract must be a canonical ContractId");
+        }
+    }
+    if (selection.kind === "path") {
+        exactKeys(selection, ["kind", "path"], "region selection");
+        try {
+            validateRegionPath(selection.path);
+        }
+        catch (error) {
+            throw new TypeError(error instanceof Error ? error.message : String(error));
+        }
+        return { kind: "path", path: selection.path };
+    }
+    throw new TypeError(`kanshi region selection kind is invalid: ${selection.kind}`);
+}
 function coordinate(input) {
     if (typeof input !== "object" || input === null || Array.isArray(input))
         throw new TypeError("kanshi input must be an object");
     for (const key of Object.keys(input))
-        if (key !== "world" && key !== "repo")
+        if (key !== "world" && key !== "repo" && key !== "region")
             throw new TypeError(`kanshi input has unknown field: ${key}`);
     if (input.world !== null && (typeof input.world !== "string" || input.world.trim().length === 0)) {
         throw new TypeError("kanshi world must be a WorldRoot or null");
     }
     if (input.repo !== undefined && !(input.repo instanceof Repo))
         throw new TypeError("kanshi repo must be a Repo");
-    return input;
+    return input.region === undefined ? input : { ...input, region: regionSelection(input.region) };
+}
+async function readRegion(observation, selection) {
+    try {
+        const declarations = [...readRegionDeclarations(await readDocuments(observation))].sort((left, right) => left.contract.localeCompare(right.contract));
+        return { kind: "present", value: selectRegion({ declarations, selection }) };
+    }
+    catch (error) {
+        return { kind: "failed", failure: { message: diagnostic(error) } };
+    }
 }
 async function readBranch(repo) {
     if (repo === undefined)
@@ -63,6 +130,27 @@ async function readHolders(observation) {
         return { kind: "failed", failure: { message: diagnostic(error) } };
     }
 }
+function attachFleet(contracts, akuma) {
+    if (contracts.kind !== "present")
+        return contracts;
+    const attachments = new Map();
+    if (akuma.kind === "present") {
+        for (const row of akuma.value.rows) {
+            if (row.contract === undefined)
+                continue;
+            const current = attachments.get(row.contract.id) ?? [];
+            current.push({ id: row.id, aliases: row.aliases });
+            attachments.set(row.contract.id, current);
+        }
+    }
+    return {
+        kind: "present",
+        value: {
+            ...contracts.value,
+            rows: contracts.value.rows.map((row) => ({ ...row, fleet: attachments.get(row.id) ?? [] })),
+        },
+    };
+}
 function decorateContracts(contracts, holders) {
     if (contracts.kind !== "present")
         return contracts;
@@ -72,11 +160,15 @@ function decorateContracts(contracts, holders) {
             ...contracts.value,
             rows: contracts.value.rows.map((row) => {
                 if (holders.kind === "failed")
-                    return { ...row, holder: { kind: "unavailable" } };
+                    return { ...row, holder: { kind: "unavailable" }, fleet: [] };
                 const holder = holders.kind === "present" ? holders.value.get(row.id) : undefined;
-                return holder?.disposition === "held"
-                    ? { ...row, holder: { kind: "held", taskId: holder.taskId } }
-                    : { ...row, holder: { kind: "none" } };
+                return {
+                    ...row,
+                    fleet: [],
+                    holder: holder?.disposition === "held"
+                        ? { kind: "held", taskId: holder.taskId }
+                        : { kind: "none" },
+                };
             }),
         },
     };
@@ -100,23 +192,23 @@ function joinTasks(rows, holders, observeContract) {
         return { ...row, contract: { id: contractId, observed: observeContract(contractId) } };
     });
 }
-function readTasks(path, holders, observeContract) {
+async function readTasks(path, holders, observeContract) {
     if (holders.kind === "failed")
         return { kind: "failed", failure: holders.failure };
     try {
         return {
             kind: "present",
-            value: { root: path, rows: joinTasks(observeTaskStatusRows(path), holders, observeContract) },
+            value: { root: path, rows: joinTasks(await observeTaskStatusRows(path), holders, observeContract) },
         };
     }
     catch (error) {
         return { kind: "failed", failure: { message: diagnostic(error) } };
     }
 }
-function joinAkuma(path, observeContract, dispatches) {
+async function joinAkuma(path, observeContract, dispatches) {
     try {
-        const source = Akuma.of(path).list();
-        const aliases = readAliases(path);
+        const source = await Akuma.of(path).list();
+        const aliases = await readAliases(path);
         const aliasById = new Map();
         for (const binding of aliases)
             aliasById.set(binding.akuId, [...(aliasById.get(binding.akuId) ?? []), binding]);
@@ -161,37 +253,35 @@ export async function kanshi(input) {
         const contracts = { kind: "absent" };
         const holders = { kind: "absent" };
         const observeContract = contractEndpointObserver(contracts);
-        return {
-            root: world,
-            observedAt,
-            branch,
-            contracts,
-            tasks: world === null ? { kind: "absent" } : readTasks(world, holders, observeContract),
-            akuma: world === null ? { kind: "absent" } : joinAkuma(world, observeContract, []),
-        };
+        const tasks = world === null ? { kind: "absent" } : await readTasks(world, holders, observeContract);
+        const akuma = world === null ? { kind: "absent" } : await joinAkuma(world, observeContract, []);
+        return { root: world, observedAt, branch, contracts, tasks, akuma, ...(input.region === undefined ? {} : { region: { kind: "absent" } }) };
     }
     try {
         const repository = scopeForRepo(repo);
         return await withGitDecodeChannel(repository, (channel) => withGitReadObservation(repository, channel, async (observation) => {
-            const [contractSection, holders, dispatches] = await Promise.all([
+            const [contractSection, holders, dispatches, region] = await Promise.all([
                 readContracts(observation),
                 readHolders(observation),
                 readDispatches(observation),
+                input.region === undefined ? Promise.resolve(undefined) : readRegion(observation, input.region),
             ]);
             const contracts = decorateContracts(contractSection, holders);
             const observeContract = contractEndpointObserver(contracts);
-            const tasks = world === null ? { kind: "absent" } : readTasks(world, holders, observeContract);
+            const tasks = world === null ? { kind: "absent" } : await readTasks(world, holders, observeContract);
+            const akuma = world === null
+                ? { kind: "absent" }
+                : dispatches.kind === "failed"
+                    ? dispatches
+                    : await joinAkuma(world, observeContract, dispatches.value);
             return {
                 root: world,
                 observedAt,
                 branch,
-                contracts,
+                contracts: attachFleet(contracts, akuma),
                 tasks,
-                akuma: world === null
-                    ? { kind: "absent" }
-                    : dispatches.kind === "failed"
-                        ? dispatches
-                        : joinAkuma(world, observeContract, dispatches.value),
+                akuma,
+                ...(region === undefined ? {} : { region }),
             };
         }));
     }
@@ -204,6 +294,7 @@ export async function kanshi(input) {
             contracts: failure,
             tasks: world === null ? { kind: "absent" } : failure,
             akuma: world === null ? { kind: "absent" } : failure,
+            ...(input.region === undefined ? {} : { region: failure }),
         };
     }
 }

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

@@ -3,6 +3,7 @@ import type { TaskId, TaskRef, TaskRow } from "../task/index.js";
 import type { AkumaList, AkumaListRow, UnbornAkumaListRow } from "../akuma/index.js";
 import type { AkumaAlias } from "../identity/selector.js";
 import type { WorldRoot } from "../world.js";
+import type { ContractId } from "../library/contract.js";
 export type Section<Value> = Readonly<{
     kind: "present";
     value: Value;
@@ -23,8 +24,13 @@ export type ContractHolderObservation = Readonly<{
 }> | Readonly<{
     kind: "unavailable";
 }>;
+export type ContractFleetAttachment = Readonly<{
+    id: string;
+    aliases: readonly AkumaAlias[];
+}>;
 export type ContractKanshiRow = ContractBoard["rows"][number] & Readonly<{
     holder: ContractHolderObservation;
+    fleet: readonly ContractFleetAttachment[];
 }>;
 export type ContractKanshiBoard = Omit<ContractBoard, "rows"> & Readonly<{
     rows: readonly ContractKanshiRow[];
@@ -50,6 +56,49 @@ export type AkumaKanshiRow = (AkumaListRow | UnbornAkumaListRow) & Readonly<{
 export type AkumaKanshiWorld = Omit<AkumaList, "rows"> & Readonly<{
     rows: readonly AkumaKanshiRow[];
 }>;
+export type KanshiRegionSelection = Readonly<{
+    kind: "declarations";
+}> | Readonly<{
+    kind: "contract";
+    contract: ContractId;
+}> | Readonly<{
+    kind: "overlap";
+    contract?: ContractId;
+}> | Readonly<{
+    kind: "path";
+    path: string;
+}>;
+export type RegionDeclaration = Readonly<{
+    contract: ContractId;
+    patterns: readonly string[];
+}>;
+export type RegionIntersection = Readonly<{
+    left: ContractId;
+    right: ContractId;
+    patterns: readonly Readonly<{
+        left: string;
+        right: string;
+    }>[];
+}>;
+export type RegionPathMatch = Readonly<{
+    contract: ContractId;
+    pattern: string;
+}>;
+export type RegionRead = Readonly<{
+    kind: "declarations";
+    declarations: readonly RegionDeclaration[];
+}> | Readonly<{
+    kind: "contract";
+    declaration: RegionDeclaration;
+}> | Readonly<{
+    kind: "overlap";
+    subject?: ContractId;
+    intersections: readonly RegionIntersection[];
+}> | Readonly<{
+    kind: "path";
+    path: string;
+    matches: readonly RegionPathMatch[];
+}>;
 export type KanshiReport = Readonly<{
     root: WorldRoot | null;
     observedAt: string;
@@ -57,4 +106,5 @@ export type KanshiReport = Readonly<{
     contracts: Section<ContractKanshiBoard>;
     tasks: Section<TaskKanshiWorld>;
     akuma: Section<AkumaKanshiWorld>;
+    region?: Section<RegionRead>;
 }>;

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

@@ -1,4 +1,5 @@
 import type { KanshiReport } from "./report.js";
+import type { KanshiRegionSelection, RegionDeclaration, RegionRead } from "./report.js";
 export type KanshiSelection = Readonly<{
     contract: string;
 }>;
@@ -6,3 +7,7 @@ export declare function selectKanshi(input: Readonly<{
     report: KanshiReport;
     contract: string;
 }>): KanshiReport;
+export declare function selectRegion(input: Readonly<{
+    declarations: readonly RegionDeclaration[];
+    selection: KanshiRegionSelection;
+}>): RegionRead;

package/build/src/kanshi/select.js

@@ -1,3 +1,4 @@
+import { regionIntersections, regionPathMatches } from "../library/region.js";
 export function selectKanshi(input) {
     const { report, contract } = input;
     return {
@@ -19,3 +20,34 @@ export function selectKanshi(input) {
             : report.akuma,
     };
 }
+export function selectRegion(input) {
+    const { declarations, selection } = input;
+    if (selection.kind === "declarations")
+        return { kind: "declarations", declarations };
+    if (selection.kind === "contract") {
+        const declaration = declarations.find((value) => value.contract === selection.contract);
+        if (declaration === undefined)
+            throw new Error(`active contract not found: ${selection.contract}`);
+        return { kind: "contract", declaration };
+    }
+    if (selection.kind === "path") {
+        const matches = declarations.flatMap((declaration) => regionPathMatches(declaration.patterns, selection.path).map((pattern) => ({ contract: declaration.contract, pattern })));
+        return { kind: "path", path: selection.path, matches };
+    }
+    const intersections = [];
+    for (let leftIndex = 0; leftIndex < declarations.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < declarations.length; rightIndex += 1) {
+            const left = declarations[leftIndex];
+            const right = declarations[rightIndex];
+            if (selection.contract !== undefined && left.contract !== selection.contract && right.contract !== selection.contract)
+                continue;
+            const patterns = regionIntersections(left.patterns, right.patterns);
+            if (patterns.length > 0)
+                intersections.push({ left: left.contract, right: right.contract, patterns });
+        }
+    }
+    if (selection.contract !== undefined && !declarations.some((value) => value.contract === selection.contract)) {
+        throw new Error(`active contract not found: ${selection.contract}`);
+    }
+    return { kind: "overlap", ...(selection.contract === undefined ? {} : { subject: selection.contract }), intersections };
+}

package/build/src/library/address.d.ts

@@ -17,6 +17,15 @@ export type AkumaSetAddressInput = Readonly<{
     settings?: Settings;
     repo?: Repo;
 }>;
+export type AkumaWorldScopeRefusal = Readonly<{
+    kind: "akuma-not-in-world";
+    ids: readonly AkuId[];
+    world: WorldRoot;
+}>;
+export declare class AkumaWorldScopeError extends TypeError {
+    readonly refusal: AkumaWorldScopeRefusal;
+    constructor(refusal: AkumaWorldScopeRefusal);
+}
 export type NamedAddressContract = Readonly<{
     id: string;
     disposition: "active" | "terminal";
@@ -35,12 +44,12 @@ export type NamedAddressInput = Readonly<{
     selector: string;
     contracts: readonly NamedAddressContract[];
 }>;
-export declare function resolveNamedAddress(input: NamedAddressInput): NamedAddress;
-export declare function addressAkuma(input: AkumaAddressInput): Readonly<{
+export declare function resolveNamedAddress(input: NamedAddressInput): Promise<NamedAddress>;
+export declare function addressAkuma(input: AkumaAddressInput): Promise<Readonly<{
     path: WorldRoot;
     id: AkuId;
     settings?: Settings;
-}>;
+}>>;
 export declare function addressAkumaSet(input: AkumaSetAddressInput): Promise<Readonly<{
     path: WorldRoot;
     ids: readonly AkuId[];