@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/library/fleet.js

@@ -0,0 +1,189 @@
+import { Akuma, } from "../akuma/index.js";
+import { readActionFeedbackStatus } from "../akuma/akuma.js";
+import { readDispatch } from "../dispatch/index.js";
+import { addressAkuma, addressAkumaSet } from "./address.js";
+import { requireInput } from "./input.js";
+import { scopeForRepo } from "./repo.js";
+function source(path, settings) {
+    return Akuma.of(path, settings);
+}
+function contractFor(repo, id) {
+    return repo === undefined ? undefined : readDispatch(scopeForRepo(repo), id)?.contractId;
+}
+function statusView(status, repo) {
+    const contractId = contractFor(repo, status.id);
+    return contractId === undefined ? { status } : { status, contractId };
+}
+function timeout(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new TypeError("timeoutMs must be a nonnegative finite number");
+    }
+    return value;
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+const PLURAL_DETAIL_LIMIT = 32;
+function pinned(entry) {
+    return entry.kind === "row"
+        && ((entry.row.kind === "tool" && entry.row.state === "running")
+            || (entry.row.kind === "tell" && entry.row.state === "pending"));
+}
+function budgetStatus(status, allowance) {
+    const entries = [];
+    const ordinary = status.timeline.entries.filter((entry) => entry.kind === "row" && !pinned(entry));
+    const kept = new Set(allowance === 0 ? [] : ordinary.slice(-allowance));
+    const used = kept.size;
+    let hidden = 0;
+    let single;
+    const flush = () => {
+        if (hidden === 1 && single !== undefined)
+            entries.push(single);
+        else if (hidden > 0)
+            entries.push({ kind: "gap", count: hidden });
+        hidden = 0;
+        single = undefined;
+    };
+    for (const entry of status.timeline.entries) {
+        if (pinned(entry)) {
+            flush();
+            entries.push(entry);
+            continue;
+        }
+        if (entry.kind === "row" && kept.has(entry)) {
+            flush();
+            entries.push(entry);
+            continue;
+        }
+        const count = entry.kind === "gap" ? entry.count : 1;
+        if (hidden === 0 && count === 1 && entry.kind === "row")
+            single = entry;
+        else
+            single = undefined;
+        hidden += count;
+    }
+    flush();
+    return { status: { ...status, timeline: { ...status.timeline, entries } }, used };
+}
+function budgetPlural(statuses) {
+    let remaining = PLURAL_DETAIL_LIMIT;
+    return statuses.map((status) => {
+        const budgeted = budgetStatus(status, remaining);
+        remaining -= budgeted.used;
+        return budgeted.status;
+    });
+}
+function directAddress(values) {
+    return {
+        path: values.path,
+        akuma: values.akuma,
+        ...(values.settings === undefined ? {} : { settings: values.settings }),
+        ...(values.repo === undefined ? {} : { repo: values.repo }),
+    };
+}
+function setAddress(values) {
+    return {
+        path: values.path,
+        akuma: values.akuma,
+        ...(values.settings === undefined ? {} : { settings: values.settings }),
+        ...(values.repo === undefined ? {} : { repo: values.repo }),
+    };
+}
+export function statusAkuma(input) {
+    const addressed = addressAkuma(input);
+    return statusView(source(addressed.path, addressed.settings).of({ id: addressed.id }).status(), input.repo);
+}
+export async function waitAkuma(input) {
+    const values = requireInput(input, "Keiyaku.wait input");
+    for (const key of Object.keys(values)) {
+        if (!["path", "akuma", "settings", "repo", "completion", "timeoutMs"].includes(key)) {
+            throw new TypeError(`Keiyaku.wait input has unknown field: ${key}`);
+        }
+    }
+    const addressed = await addressAkumaSet(setAddress(values));
+    const completion = values.completion;
+    if (addressed.ids.length > 1 && completion !== "any" && completion !== "all") {
+        throw new TypeError("completion must be any or all when waiting for multiple Akuma");
+    }
+    if (completion !== undefined && completion !== "any" && completion !== "all")
+        throw new TypeError("completion must be any or all");
+    const selected = completion ?? "all";
+    const timeoutMs = timeout(values.timeoutMs);
+    const handles = addressed.ids.map((id) => source(addressed.path, addressed.settings).of({ id }));
+    const deadline = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
+    for (;;) {
+        const statuses = handles.map((handle) => handle.status());
+        const settled = statuses.map((status) => status.life !== "running");
+        if ((selected === "any" ? settled.some(Boolean) : settled.every(Boolean))
+            || (deadline !== undefined && performance.now() >= deadline)) {
+            const observed = statuses.length > 1 ? budgetPlural(statuses) : statuses;
+            return { completion: selected, statuses: observed.map((status) => statusView(status, values.repo)) };
+        }
+        await delay(deadline === undefined ? 25 : Math.min(25, Math.max(0, deadline - performance.now())));
+    }
+}
+export async function killAkuma(input) {
+    const addressed = await addressAkumaSet(input);
+    const handles = addressed.ids.map((id) => source(addressed.path, addressed.settings).of({ id }));
+    const evidence = await Promise.all(handles.map(async (handle) => await handle.kill()));
+    return {
+        results: addressed.ids.map((id, index) => ({
+            id,
+            evidence: evidence[index],
+            observation: statusView(readActionFeedbackStatus(addressed.path, id), input.repo),
+        })),
+    };
+}
+export async function tellAkuma(input) {
+    const values = requireInput(input, "Keiyaku.tell input");
+    for (const key of Object.keys(values)) {
+        if (!["path", "akuma", "settings", "body", "repo"].includes(key))
+            throw new TypeError(`Keiyaku.tell input has unknown field: ${key}`);
+    }
+    if (typeof values.body !== "string")
+        throw new TypeError("body must be a string");
+    const addressed = addressAkuma(directAddress(values));
+    const handle = source(addressed.path, addressed.settings).of({ id: addressed.id });
+    const tell = await handle.tell(values.body);
+    return { akuma: addressed.id, tell, observation: statusView(readActionFeedbackStatus(addressed.path, addressed.id), values.repo) };
+}
+export async function interruptAkuma(input) {
+    const values = requireInput(input, "Keiyaku.interrupt input");
+    for (const key of Object.keys(values)) {
+        if (!["path", "akuma", "settings", "body", "repo"].includes(key))
+            throw new TypeError(`Keiyaku.interrupt input has unknown field: ${key}`);
+    }
+    if (typeof values.body !== "string")
+        throw new TypeError("body must be a string");
+    const addressed = addressAkuma(directAddress(values));
+    const receipt = await source(addressed.path, addressed.settings).of({ id: addressed.id }).interrupt(values.body);
+    return { id: addressed.id, receipt, observation: statusView(readActionFeedbackStatus(addressed.path, addressed.id), values.repo) };
+}
+export function historyAkuma(input) {
+    const values = requireInput(input, "Keiyaku.history input");
+    for (const key of Object.keys(values)) {
+        if (!["path", "akuma", "settings", "before", "since", "limit", "last", "repo"].includes(key)) {
+            throw new TypeError(`Keiyaku.history input has unknown field: ${key}`);
+        }
+    }
+    if (values.last !== undefined && typeof values.last !== "boolean")
+        throw new TypeError("last must be a boolean");
+    const addressed = addressAkuma(directAddress(values));
+    const handle = source(addressed.path, addressed.settings).of({ id: addressed.id });
+    if (values.last === true) {
+        const answer = handle.lastAnswer();
+        const contractId = contractFor(values.repo, addressed.id);
+        return answer.kind === "answer"
+            ? { kind: "last", id: addressed.id, answer: answer.answer, ...(contractId === undefined ? {} : { contractId }) }
+            : { kind: "no-answer", id: addressed.id, ...(contractId === undefined ? {} : { contractId }) };
+    }
+    const history = handle.history({
+        ...(values.before === undefined ? {} : { before: values.before }),
+        ...(values.since === undefined ? {} : { since: values.since }),
+        ...(values.limit === undefined ? {} : { limit: values.limit }),
+    });
+    const contractId = contractFor(values.repo, addressed.id);
+    return { kind: "history", id: addressed.id, history, ...(contractId === undefined ? {} : { contractId }) };
+}

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

@@ -0,0 +1,16 @@
+import type { DecodedContractDocument } from "../body/types.js";
+import { type ActorId, type ContractId, type ContractTerms, type Gate } from "../core/facts/types.js";
+import type { DocumentDerivation } from "../protocol/operations.js";
+export declare function actorOption(actor: unknown): Readonly<{
+    actor?: ActorId;
+}>;
+export declare function requireMarkdown(value: unknown, label?: string): string;
+export declare function requireInput(value: unknown, label: string): Record<string, unknown>;
+export declare function rejectUnknownFields(values: Record<string, unknown>, allowed: readonly string[], label: string): void;
+export declare function optionalNonblank(value: unknown, label: string): string | undefined;
+export declare function optionalBoolean(value: unknown, label: string): boolean | undefined;
+export declare function optionalSignal(value: unknown): AbortSignal | undefined;
+export declare function normalizedList<T>(values: unknown, label: string, brand: (value: string) => T): readonly T[];
+export declare function normalizedGates(values: unknown): readonly Gate[];
+export declare function contractTerms(document: DecodedContractDocument, gates: readonly Gate[], after: readonly ContractId[]): ContractTerms;
+export declare function documentDerivation(document: DecodedContractDocument, gates: readonly Gate[], contractId?: ContractId): DocumentDerivation;

package/build/src/library/input.js

@@ -0,0 +1,101 @@
+import { verificationDefinition } from "../body/decode.js";
+import { actorId, gate, gateWord, } from "../core/facts/types.js";
+import { prepareVerificationDeclaration } from "../verification/declaration.js";
+export function actorOption(actor) {
+    if (actor === undefined)
+        return {};
+    if (typeof actor !== "string" || actor.trim().length === 0) {
+        throw new TypeError("actor must be a nonblank string");
+    }
+    return { actor: actorId(actor) };
+}
+export function requireMarkdown(value, label = "markdown") {
+    if (typeof value !== "string")
+        throw new TypeError(`${label} must be a string`);
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function requireInput(value, label) {
+    if (!isRecord(value))
+        throw new TypeError(`${label} must be an object`);
+    return value;
+}
+export function rejectUnknownFields(values, allowed, label) {
+    for (const key of Object.keys(values))
+        if (!allowed.includes(key))
+            throw new TypeError(`${label} has unknown field: ${key}`);
+}
+export function optionalNonblank(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${label} must be a nonblank string`);
+    }
+    return value;
+}
+export function optionalBoolean(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new TypeError(`${label} must be a boolean`);
+    return value;
+}
+export function optionalSignal(value) {
+    if (value === undefined)
+        return undefined;
+    if (!(value instanceof AbortSignal))
+        throw new TypeError("signal must be an AbortSignal");
+    return value;
+}
+export function normalizedList(values, label, brand) {
+    if (values === undefined)
+        return [];
+    if (!Array.isArray(values))
+        throw new TypeError(`${label} must be an array`);
+    return values.map((value, index) => {
+        if (typeof value !== "string")
+            throw new TypeError(`${label}[${index}] must be a string`);
+        try {
+            return brand(value);
+        }
+        catch (error) {
+            throw new TypeError(error instanceof Error ? error.message : `${label}[${index}] is invalid`);
+        }
+    });
+}
+export function normalizedGates(values) {
+    if (values === undefined)
+        return [];
+    if (!Array.isArray(values))
+        throw new TypeError("gates must be an array");
+    const normalized = values.map((value, index) => {
+        if (!gateWord(value)) {
+            throw new TypeError(`gates[${index}] must match ^[a-z][a-z0-9-]{0,63}$`);
+        }
+        return gate(value);
+    });
+    if (new Set(normalized).size !== normalized.length)
+        throw new TypeError("gates must not contain duplicates");
+    return normalized;
+}
+export function contractTerms(document, gates, after) {
+    return {
+        document: document.document,
+        segments: document.segments,
+        gates,
+        after,
+    };
+}
+export function documentDerivation(document, gates, contractId) {
+    return {
+        document: document.document.key,
+        title: document.title,
+        verification: prepareVerificationDeclaration({
+            gates,
+            definition: verificationDefinition(document),
+            ...(contractId === undefined ? {} : { contractId }),
+        }),
+    };
+}

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

@@ -0,0 +1,42 @@
+import { KeiyakuHandle, bindKeiyaku, keiyakuOf, listKeiyaku, observeKeiyaku, type Keiyaku as KeiyakuType } from "./contract.js";
+import { callKeiyaku, forkKeiyaku } from "./akuma-creation.js";
+import { historyAkuma, interruptAkuma, killAkuma, statusAkuma, tellAkuma, waitAkuma } from "./fleet.js";
+import { listCatalog } from "./catalog.js";
+export { AuthorityCorruptionError } from "../core/facts/errors.js";
+export { Delivery, KeiyakuRefused, KeiyakuRetry, } from "./contract.js";
+export { NoGitWorldError, Repo } from "./repo.js";
+export { gatesFrom, requireBranchesToBeUpToDateFrom, SettingsError, } from "./configuration.js";
+export { worktreeHooksFrom } from "../git/hooks.js";
+export type { AbandonInput, ActorId, AmendInput, AmendResult, ArcInput, AttestationVerdict, AuditInput, AuditReport, BindInput, BindResult, ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractListInput, ContractObservation, ContractObservationInput, ContractPhase, ContractRow, DeliverInput, Fact, FactKind, KeiyakuOfInput, KeiyakuRefusal, KeiyakuRetryReason, Lag, MutationResult, PlacementStop, ReconcileReport, Review, ReviewInput, TimelineEntry, TaskId, TopologyEffect, VerificationStop, } from "./contract.js";
+export type { ContractId, ContractState, ChangeId, SnapshotId, } from "../core/facts/types.js";
+export type { Gate, GatesFromInput, HookCommand, RequireBranchesToBeUpToDateFromInput, WorktreeHooks, } from "./configuration.js";
+export type { RegionOverlap } from "./region.js";
+export type { ReconcileInput, RepoAtInput, RepoReconcileReport, } from "./repo.js";
+export type { SettlementAction, SettlementLag, SettlementReport, } from "../settlement/settle.js";
+export type { AliasStage, AkumaStatus, CallObservation, CallInput, CallResult, DispatchStage, ForkInput, ForkResult, IntegrationFailure, } from "./akuma-creation.js";
+export type { AliasBinding } from "../alias/index.js";
+export type { Dispatch, DispatchFailure } from "../dispatch/index.js";
+export type { AkumaAlias } from "../identity/selector.js";
+export type { AkumaGlob } from "../identity/selector.js";
+export type { AkuId } from "../akuma/identity.js";
+export type { Catalog, CatalogInput, CatalogQuery } from "./catalog.js";
+export type { AkumaAddressInput, AkumaSetAddressInput, DirectAkumaSelector, SetAkumaSelector, } from "./address.js";
+export type { AkumaHistoryInput, AkumaHistoryResult, AkumaInterruptInput, AkumaInterruptResult, AkumaKillResult, AkumaStatusView, AkumaTellInput, AkumaTellResult, AkumaWaitInput, AkumaWaitResult, } from "./fleet.js";
+export type Keiyaku = KeiyakuType;
+export declare const Keiyaku: Readonly<{
+    prototype: KeiyakuHandle;
+    [Symbol.hasInstance]: (value: unknown) => boolean;
+    bind: typeof bindKeiyaku;
+    call: typeof callKeiyaku;
+    fork: typeof forkKeiyaku;
+    history: typeof historyAkuma;
+    interrupt: typeof interruptAkuma;
+    kill: typeof killAkuma;
+    ls: typeof listCatalog;
+    list: typeof listKeiyaku;
+    observe: typeof observeKeiyaku;
+    of: typeof keiyakuOf;
+    status: typeof statusAkuma;
+    tell: typeof tellAkuma;
+    wait: typeof waitAkuma;
+}>;

package/build/src/library/keiyaku.js

@@ -0,0 +1,26 @@
+import { KeiyakuHandle, bindKeiyaku, keiyakuOf, listKeiyaku, observeKeiyaku, } from "./contract.js";
+import { callKeiyaku, forkKeiyaku } from "./akuma-creation.js";
+import { historyAkuma, interruptAkuma, killAkuma, statusAkuma, tellAkuma, waitAkuma, } from "./fleet.js";
+import { listCatalog } from "./catalog.js";
+export { AuthorityCorruptionError } from "../core/facts/errors.js";
+export { Delivery, KeiyakuRefused, KeiyakuRetry, } from "./contract.js";
+export { NoGitWorldError, Repo } from "./repo.js";
+export { gatesFrom, requireBranchesToBeUpToDateFrom, SettingsError, } from "./configuration.js";
+export { worktreeHooksFrom } from "../git/hooks.js";
+export const Keiyaku = Object.freeze({
+    prototype: KeiyakuHandle.prototype,
+    [Symbol.hasInstance]: (value) => value instanceof KeiyakuHandle,
+    bind: bindKeiyaku,
+    call: callKeiyaku,
+    fork: forkKeiyaku,
+    history: historyAkuma,
+    interrupt: interruptAkuma,
+    kill: killAkuma,
+    ls: listCatalog,
+    list: listKeiyaku,
+    observe: observeKeiyaku,
+    of: keiyakuOf,
+    status: statusAkuma,
+    tell: tellAkuma,
+    wait: waitAkuma,
+});

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

@@ -0,0 +1,38 @@
+import type { ContractHead, ContractId, JournalEntry } from "../core/facts/types.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import { type ReconcileReport, type RepositoryScope } from "../protocol/operations.js";
+import type { IntentOutcome } from "../protocol/operations.js";
+import { type SettlementReport } from "../settlement/settle.js";
+import type { TaskHolderAdmission } from "../settlement/holder.js";
+import type { WorktreeHooks } from "./configuration.js";
+import { type ContractFileEffect, type ContractFileLag } from "../contract-worktree.js";
+export type AcceptedIntent<Value> = Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: Value;
+    physical?: ReconcileReport;
+}>;
+export type MutationResult<Value> = Readonly<{
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: Value;
+    effects: readonly (ReconcileReport["effects"][number] | ContractFileEffect)[];
+    lags: readonly (ReconcileReport["lag"][number] | ContractFileLag)[];
+    settlement: SettlementReport;
+}>;
+type Completion<Value, PublicValue> = Readonly<{
+    scope: RepositoryScope;
+    channel: GitDecodeChannel;
+    contractId: ContractId;
+    accepted: AcceptedIntent<Value>;
+    value: (result: Value) => PublicValue;
+    hooks: WorktreeHooks;
+}>;
+export declare function completeMutation<Value, PublicValue>(input: Completion<Value, PublicValue>): Promise<MutationResult<PublicValue>>;
+export declare function completeHolderMutation<Value, PublicValue, Refusal>(input: Readonly<{
+    completion: Omit<Completion<Value, PublicValue>, "accepted">;
+    admission: TaskHolderAdmission<IntentOutcome<Value, Refusal>>;
+    requireAccepted: (result: IntentOutcome<Value, Refusal>) => AcceptedIntent<Value>;
+}>): Promise<MutationResult<PublicValue>>;
+export {};

package/build/src/library/mutation.js

@@ -0,0 +1,39 @@
+import { reconcileOperation } from "../protocol/operations.js";
+import { deferredTaskHolderSettlement, settle } from "../settlement/settle.js";
+import { projectContractWorktree } from "../contract-worktree.js";
+export async function completeMutation(input) {
+    const { scope, channel, contractId, accepted, value, hooks } = input;
+    const retained = await reconcileOperation({ scope, channel, contractId, hooks, retryHooks: false, retainTerminalWorktree: true });
+    const projection = projectContractWorktree(scope, retained.state);
+    const settlement = await settle({ repository: scope, channel, state: retained.state, effects: retained.report.effects });
+    const deferRemoval = retained.state !== null && retained.state.terminal !== null
+        && retained.state.coordinates.workspace === "worktree";
+    const cleanup = deferRemoval
+        ? await reconcileOperation({ scope, channel, contractId, hooks, retryHooks: false })
+        : null;
+    return {
+        facts: accepted.facts,
+        head: accepted.head,
+        value: value(accepted.value),
+        effects: [...(accepted.physical?.effects ?? []), ...retained.report.effects, ...projection.effects, ...(cleanup?.report.effects ?? [])],
+        lags: [...(accepted.physical?.lag ?? []), ...retained.report.lag, ...projection.lag, ...(cleanup?.report.lag ?? [])],
+        settlement,
+    };
+}
+export async function completeHolderMutation(input) {
+    const accepted = input.requireAccepted(input.admission.result);
+    if (input.admission.kind === "completed")
+        return completeMutation({ ...input.completion, accepted });
+    return {
+        facts: accepted.facts,
+        head: accepted.head,
+        value: input.completion.value(accepted.value),
+        effects: [...(accepted.physical?.effects ?? [])],
+        lags: [...(accepted.physical?.lag ?? [])],
+        settlement: deferredTaskHolderSettlement({
+            contractId: input.completion.contractId,
+            taskId: input.admission.taskId,
+            diagnostic: input.admission.diagnostic,
+        }),
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { ContractId } from "../core/facts/types.js";
+import type { IntentOutcome, IntentRefusal, IntentRetry } from "../protocol/operations.js";
+import type { AcceptedIntent } from "./mutation.js";
+export type ContractAppointmentRefusal = Readonly<{
+    kind: "here-worktree-appointed";
+    path: string;
+    contract?: ContractId;
+}>;
+export type KeiyakuRefusal = IntentRefusal | ContractAppointmentRefusal;
+export type KeiyakuRetryReason = IntentRetry;
+export declare class KeiyakuRefused extends Error {
+    readonly refusal: KeiyakuRefusal;
+    constructor(refusal: KeiyakuRefusal);
+    get code(): KeiyakuRefusal["kind"];
+}
+export declare class KeiyakuRetry extends Error {
+    readonly reason: KeiyakuRetryReason;
+    constructor(reason: KeiyakuRetryReason);
+    get code(): KeiyakuRetryReason["kind"];
+}
+export declare function requireAccepted<Value, Refusal extends KeiyakuRefusal>(result: IntentOutcome<Value, Refusal>): AcceptedIntent<Value>;

package/build/src/library/refusal.js

@@ -0,0 +1,29 @@
+export class KeiyakuRefused extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`Keiyaku refused: ${refusal.kind}`);
+        this.refusal = refusal;
+        this.name = "KeiyakuRefused";
+    }
+    get code() {
+        return this.refusal.kind;
+    }
+}
+export class KeiyakuRetry extends Error {
+    reason;
+    constructor(reason) {
+        super(reason.kind === "publication-failed" ? reason.diagnostic : `Keiyaku retry required: ${reason.kind}`);
+        this.reason = reason;
+        this.name = "KeiyakuRetry";
+    }
+    get code() {
+        return this.reason.kind;
+    }
+}
+export function requireAccepted(result) {
+    if (result.kind === "refused")
+        throw new KeiyakuRefused(result.refusal);
+    if (result.kind === "retry")
+        throw new KeiyakuRetry(result.reason);
+    return result;
+}

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

@@ -0,0 +1,18 @@
+import type { ContractId } from "../core/facts/types.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import { type RepositoryScope } from "../protocol/operations.js";
+export type RegionOverlap = Readonly<{
+    contract: ContractId;
+    patterns: readonly Readonly<{
+        mine: string;
+        theirs: string;
+    }>[];
+}>;
+export type RegionObservation = Readonly<{
+    overlaps: readonly RegionOverlap[];
+    overlapFailure?: never;
+} | {
+    overlapFailure: string;
+    overlaps?: never;
+}>;
+export declare function observeRegion(scope: RepositoryScope, channel: GitDecodeChannel, self: ContractId, mine: readonly string[]): Promise<RegionObservation>;

package/build/src/library/region.js

@@ -0,0 +1,30 @@
+import { decodeContractDocument } from "../body/decode.js";
+import { regionsOverlap } from "../body/region.js";
+import { documentsOperationAt } from "../protocol/operations.js";
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export async function observeRegion(scope, channel, self, mine) {
+    try {
+        const overlaps = [];
+        for (const peer of await documentsOperationAt(scope, channel)) {
+            if (peer.contract === self)
+                continue;
+            try {
+                const pairs = regionsOverlap(mine, decodeContractDocument(peer.documentBytes).region);
+                if (pairs.length > 0)
+                    overlaps.push({
+                        contract: peer.contract,
+                        patterns: pairs.map(([minePattern, theirsPattern]) => ({ mine: minePattern, theirs: theirsPattern })),
+                    });
+            }
+            catch (error) {
+                return { overlapFailure: `${peer.contract}: ${diagnostic(error)}` };
+            }
+        }
+        return { overlaps };
+    }
+    catch (error) {
+        return { overlapFailure: diagnostic(error) };
+    }
+}

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

@@ -0,0 +1,36 @@
+import { NoGitWorldError, type ReconcileReport as ProtocolReconcileReport, type RepositoryScope } from "../protocol/operations.js";
+import { type SettlementReport } from "../settlement/settle.js";
+import { type WorktreeHooks } from "./configuration.js";
+import type { ContractId } from "../core/facts/types.js";
+import { type ContractFileEffect, type ContractFileLag } from "../contract-worktree.js";
+export { NoGitWorldError };
+export type RepoAtInput = Readonly<{
+    path?: string;
+}>;
+export type ReconcileInput = Readonly<{
+    hooks?: WorktreeHooks;
+    retryHooks?: boolean;
+}>;
+export type RepoContractReconcileReport = Readonly<{
+    effects: readonly (ProtocolReconcileReport["effects"][number] | ContractFileEffect)[];
+    lag: readonly (ProtocolReconcileReport["lag"][number] | ContractFileLag)[];
+    settlement: SettlementReport;
+}>;
+export type RepoReconcileReport = Readonly<{
+    contracts: readonly Readonly<{
+        contractId: ContractId;
+        report: RepoContractReconcileReport;
+    }>[];
+}>;
+export declare function reconcileInput(input: ReconcileInput | undefined): Readonly<{
+    hooks: WorktreeHooks;
+    retryHooks: boolean;
+}>;
+export declare class Repo {
+    readonly root: string;
+    private constructor();
+    static at(input?: RepoAtInput): Repo;
+    currentBranch(): Promise<string | null>;
+    reconcile(input?: ReconcileInput): Promise<RepoReconcileReport>;
+}
+export declare function scopeForRepo(value: unknown): RepositoryScope;