@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/core/verbs/arc.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision } from "../decide.js";
+import type { ActorId, ArcData, ContractId } from "../facts/types.js";
+export type ArcInput = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    data: Readonly<Omit<ArcData, "seq">>;
+}>;
+export type ArcRefusal = Readonly<{
+    kind: "contract-missing" | "terminal";
+    contractId: ContractId;
+}>;
+export declare function decideArc({ input, attempt, observation }: DecideInput<ArcInput>): OfferDecision<ArcRefusal>;

package/build/src/core/verbs/arc.js

@@ -0,0 +1,25 @@
+import { activeContract } from "../facts/observation.js";
+export function decideArc({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = activeContract(observation, id);
+    if ("kind" in current)
+        return { kind: "refused", refusal: current };
+    const arc = {
+        v: 1,
+        kind: "arc",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: {
+            seq: (current.currentArc?.data.seq ?? 0) + 1,
+            title: input.data.title,
+            objective: input.data.objective,
+            brief: input.data.brief,
+        },
+    };
+    return {
+        kind: "offer",
+        offer: { facts: [{ contractId: id, expectedHead: current.head, entries: [arc] }] },
+    };
+}

package/build/src/core/verbs/attestation.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
+import type { ActorId, AttestationData, ContractId } from "../facts/types.js";
+export type AttestationInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    preparation?: Preparation<AttestationData, Failure>;
+}>;
+export type AttestationRefusal = Readonly<{
+    kind: "contract-missing" | "terminal";
+    contractId: ContractId;
+}>;
+export declare function decideAttestation<Failure>({ input, attempt, observation, }: DecideInput<AttestationInput<Failure>>): OfferDecision<AttestationRefusal | Failure>;

package/build/src/core/verbs/attestation.js

@@ -0,0 +1,21 @@
+import { activeContract } from "../facts/observation.js";
+export function decideAttestation({ input, attempt, observation, }) {
+    const state = activeContract(observation, input.contractId);
+    if ("kind" in state)
+        return { kind: "refused", refusal: state };
+    if (input.preparation === undefined) {
+        throw new Error("active contract requires an attestation preparation");
+    }
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const attestation = {
+        v: 1,
+        kind: "attestation",
+        contract: input.contractId,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: input.preparation.data,
+    };
+    return { kind: "offer", offer: { facts: [{ contractId: input.contractId, expectedHead: state.head, entries: [attestation] }] } };
+}

package/build/src/core/verbs/bind.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
+import type { ActorId, BindData, ContractId } from "../facts/types.js";
+export type BindInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    preparation: Preparation<BindData, Failure>;
+}>;
+export type BindRefusal = Readonly<{
+    kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
+    contractId: ContractId;
+}>;
+export declare function decideBind<Failure>({ input, attempt, observation }: DecideInput<BindInput<Failure>>): OfferDecision<BindRefusal | Failure>;

package/build/src/core/verbs/bind.js

@@ -0,0 +1,26 @@
+import { contractState, prerequisiteStatus } from "../facts/observation.js";
+export function decideBind({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = contractState(observation, id);
+    if (current !== null)
+        return { kind: "refused", refusal: { kind: "contract-exists", contractId: id } };
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const { data } = input.preparation;
+    if (data.terms.after.includes(id))
+        return { kind: "refused", refusal: { kind: "invalid-after", contractId: id } };
+    const prerequisites = prerequisiteStatus(data.terms.after, observation);
+    if (prerequisites === "unknown") {
+        return { kind: "refused", refusal: { kind: "unknown-prerequisite", contractId: id } };
+    }
+    const bind = {
+        v: 1,
+        kind: "bind",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data,
+    };
+    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: null, entries: [bind] }] } };
+}

package/build/src/core/verbs/deliver.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision, StampedPreparation } from "../decide.js";
+import type { ActorId, ContractId, DeliverData } from "../facts/types.js";
+export type DeliverInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    preparation: StampedPreparation<DeliverData, Failure>;
+}>;
+export type DeliverRefusal = Readonly<{
+    kind: "contract-missing" | "not-bound" | "terminal" | "document-moved";
+    contractId: ContractId;
+}>;
+export declare function decideDeliver<Failure>({ input, attempt, observation, }: DecideInput<DeliverInput<Failure>>): OfferDecision<DeliverRefusal | Failure>;

package/build/src/core/verbs/deliver.js

@@ -0,0 +1,42 @@
+import { activeContract, documentIsCurrent, prerequisiteStatus } from "../facts/observation.js";
+export function decideDeliver({ input, attempt, observation, }) {
+    const state = activeContract(observation, input.contractId);
+    if ("kind" in state)
+        return { kind: "refused", refusal: state };
+    const prerequisites = state.bound === null
+        ? prerequisiteStatus(state.terms.after, observation)
+        : "claimed";
+    if (prerequisites !== "claimed") {
+        return { kind: "refused", refusal: { kind: "not-bound", contractId: input.contractId } };
+    }
+    if (input.preparation.kind === "unavailable") {
+        throw new Error("existing contract requires a stamped delivery preparation");
+    }
+    if (!documentIsCurrent(state, input.preparation.document)) {
+        return { kind: "refused", refusal: { kind: "document-moved", contractId: input.contractId } };
+    }
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const entries = [];
+    if (state.bound === null)
+        entries.push({
+            v: 1,
+            kind: "bound",
+            contract: input.contractId,
+            entry: attempt.entryUlids[0],
+            at: input.at,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            data: {},
+        });
+    const deliver = {
+        v: 1,
+        kind: "deliver",
+        contract: input.contractId,
+        entry: attempt.entryUlids[state.bound === null ? 1 : 0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: input.preparation.data,
+    };
+    entries.push(deliver);
+    return { kind: "offer", offer: { facts: [{ contractId: input.contractId, expectedHead: state.head, entries }] } };
+}

package/build/src/core/verbs/placement.d.ts

@@ -0,0 +1,13 @@
+import type { ActorId, ContractId } from "../facts/types.js";
+import type { DecideInput, OfferDecision } from "../decide.js";
+type PlacementInput = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+}>;
+export type PlacementRefusal = Readonly<{
+    kind: "contract-missing" | "delivery-missing" | "terminal" | "gates-unsatisfied";
+    contractId: ContractId;
+}>;
+export declare function decidePlacement({ input, attempt, observation }: DecideInput<PlacementInput>): OfferDecision<PlacementRefusal>;
+export {};

package/build/src/core/verbs/placement.js

@@ -0,0 +1,37 @@
+import { gatesSatisfied } from "../facts/gate.js";
+import { activeContract } from "../facts/observation.js";
+export function decidePlacement({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = activeContract(observation, id);
+    if ("kind" in current)
+        return { kind: "refused", refusal: current };
+    const delivery = current.delivery;
+    if (!delivery) {
+        return { kind: "refused", refusal: { kind: "delivery-missing", contractId: id } };
+    }
+    if (!gatesSatisfied(current)) {
+        return { kind: "refused", refusal: { kind: "gates-unsatisfied", contractId: id } };
+    }
+    const claimed = {
+        v: 1,
+        kind: "claimed",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: { delivery: delivery.entry },
+    };
+    return {
+        kind: "offer",
+        offer: {
+            facts: [{ contractId: id, expectedHead: current.head, entries: [claimed] }],
+            ...(current.coordinates.target === undefined ? {} : {
+                target: {
+                    target: current.coordinates.target,
+                    expectedOid: delivery.data.integration.predecessor,
+                    newOid: delivery.data.integration.snapshot,
+                },
+            }),
+        },
+    };
+}

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

@@ -0,0 +1,33 @@
+import { type ContractId } from "../core/facts/types.js";
+import { type AkuId } from "../akuma/identity.js";
+import { type GitRepository } from "../git/repository.js";
+import { type GitReadObservation } from "../git/read-observation.js";
+export type Dispatch = Readonly<{
+    akuId: AkuId;
+    contractId: ContractId;
+    dispatchedAt: string;
+}>;
+export type DispatchFailure = Readonly<{
+    kind: "conflict";
+    current: Dispatch;
+}> | Readonly<{
+    kind: "contention";
+}> | Readonly<{
+    kind: "publication-failed";
+    diagnostic: string;
+}>;
+export type DispatchPublication = Readonly<{
+    kind: "dispatched";
+    dispatch: Dispatch;
+}> | Readonly<{
+    kind: "failed";
+    failure: DispatchFailure;
+}>;
+export declare function readDispatch(repository: GitRepository, value: AkuId): Dispatch | null;
+export declare function readDispatchesAt(observation: GitReadObservation): Promise<readonly Dispatch[]>;
+export declare function readDispatches(repository: GitRepository): Promise<readonly Dispatch[]>;
+export declare function publishDispatch(input: Readonly<{
+    repository: GitRepository;
+    akuId: AkuId;
+    contractId: ContractId;
+}>): DispatchPublication;

package/build/src/dispatch/index.js

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { contractId } from "../core/facts/types.js";
+import { parseAkuId } from "../akuma/identity.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";
+const DISPATCH_PREFIX = `${DISPATCH_ROOT}/`;
+const DISPATCH_SUFFIX = ".json";
+const MAX_ATTEMPTS = 3;
+function pathFor(akuId) {
+    return `${DISPATCH_PREFIX}${createHash("sha256").update(akuId).digest("hex")}${DISPATCH_SUFFIX}`;
+}
+function bytesFor(dispatch) {
+    return Buffer.from(`${JSON.stringify(dispatch)}\n`);
+}
+function corruption(message, cause) {
+    throw new AuthorityCorruptionError(message, cause === undefined ? {} : { cause });
+}
+function decode(path, bytes) {
+    let value;
+    try {
+        const text = Buffer.from(bytes).toString("utf8");
+        if (!text.endsWith("\n") || text.slice(0, -1).includes("\n")) {
+            corruption(`Dispatch is not one canonical JSON line: ${path}`);
+        }
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError)
+            throw error;
+        return corruption(`invalid Dispatch JSON: ${path}`, error);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        corruption(`Dispatch must be an object: ${path}`);
+    }
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length !== 3 || keys.some((key) => !["akuId", "contractId", "dispatchedAt"].includes(key))) {
+        corruption(`Dispatch has invalid fields: ${path}`);
+    }
+    if (typeof record.akuId !== "string" || typeof record.contractId !== "string"
+        || typeof record.dispatchedAt !== "string") {
+        corruption(`Dispatch has invalid values: ${path}`);
+    }
+    let akuId;
+    let owner;
+    try {
+        akuId = parseAkuId(record.akuId).id;
+        owner = contractId(record.contractId);
+    }
+    catch (error) {
+        return corruption(`Dispatch identity is invalid: ${path}`, error);
+    }
+    const timestamp = new Date(record.dispatchedAt);
+    if (!Number.isFinite(timestamp.getTime()) || timestamp.toISOString() !== record.dispatchedAt) {
+        corruption(`Dispatch timestamp is invalid: ${path}`);
+    }
+    const dispatch = { akuId, contractId: owner, dispatchedAt: record.dispatchedAt };
+    if (pathFor(akuId) !== path)
+        corruption(`Dispatch path does not match akuId: ${path}`);
+    if (!Buffer.from(bytesFor(dispatch)).equals(Buffer.from(bytes))) {
+        corruption(`Dispatch bytes are not canonical: ${path}`);
+    }
+    return dispatch;
+}
+function dispatchFromSnapshot(repository, snapshot, akuId) {
+    const path = pathFor(akuId);
+    const entry = snapshot.paths.get(path);
+    if (entry === undefined)
+        return null;
+    if (entry.type !== "blob")
+        corruption(`Dispatch path is not a blob: ${path}`);
+    return decode(path, readBlob(repository, entry.oid));
+}
+export function readDispatch(repository, value) {
+    const akuId = parseAkuId(value).id;
+    const path = pathFor(akuId);
+    return dispatchFromSnapshot(repository, readGitPaths(repository, [path]), akuId);
+}
+export async function readDispatchesAt(observation) {
+    const entries = [...observation.snapshot.paths]
+        .filter(([path, entry]) => path.startsWith(DISPATCH_PREFIX) && entry.type === "blob");
+    const blobs = await observation.readBlobs(entries.map(([, entry]) => entry.oid));
+    const dispatches = [];
+    const seen = new Set();
+    for (const [path, entry] of observation.snapshot.paths) {
+        if (path === DISPATCH_ROOT)
+            corruption(`Dispatch authority root is not a tree: ${path}`);
+        if (!path.startsWith(DISPATCH_PREFIX))
+            continue;
+        if (!path.endsWith(DISPATCH_SUFFIX))
+            corruption(`unexpected Dispatch authority path: ${path}`);
+        if (entry.type !== "blob")
+            corruption(`Dispatch path is not a blob: ${path}`);
+        const result = blobs.get(entry.oid);
+        if (result?.kind !== "present")
+            corruption(`missing Dispatch Git object: ${path}`);
+        const dispatch = decode(path, result.bytes);
+        if (seen.has(dispatch.akuId))
+            corruption(`duplicate Dispatch identity: ${dispatch.akuId}`);
+        seen.add(dispatch.akuId);
+        dispatches.push(dispatch);
+    }
+    return dispatches.sort((left, right) => Buffer.compare(Buffer.from(left.akuId), Buffer.from(right.akuId)));
+}
+export async function readDispatches(repository) {
+    return withGitDecodeChannel(repository, (channel) => withGitReadObservation(repository, channel, readDispatchesAt));
+}
+function observedPublication(repository, akuId, owner) {
+    const current = readDispatch(repository, akuId);
+    if (current === null)
+        return null;
+    return current.contractId === owner
+        ? { kind: "dispatched", dispatch: current }
+        : { kind: "failed", failure: { kind: "conflict", current } };
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function publishDispatch(input) {
+    const akuId = parseAkuId(input.akuId).id;
+    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 = readGitPaths(input.repository, [path]);
+        const current = 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: writeBlob(input.repository, GIT_FORMAT_BYTES) });
+        }
+        changes.set(path, { oid: writeBlob(input.repository, bytesFor(intended)) });
+        const tree = updateGitTree(input.repository, snapshot.tree, changes);
+        const commit = writeCommit({
+            repository: input.repository,
+            tree,
+            parent: snapshot.commit,
+            message: `dispatch ${akuId}`,
+            at: intended.dispatchedAt,
+        });
+        const publication = updateRefsAtomically(input.repository, [{
+                ref: GIT_REF,
+                newOid: commit,
+                expectedOid: snapshot.commit,
+            }]);
+        if (publication.kind === "published")
+            return { kind: "dispatched", dispatch: intended };
+        const observed = observedPublication(input.repository, akuId, owner);
+        if (observed !== null)
+            return observed;
+        if (publication.kind === "non-published") {
+            const fresh = 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" } };
+}

package/build/src/duration.d.ts

@@ -0,0 +1,10 @@
+export type DurationParseResult = Readonly<{
+    kind: "parsed";
+    milliseconds: number;
+}> | Readonly<{
+    kind: "invalid";
+}> | Readonly<{
+    kind: "overflow";
+}>;
+export declare function parseDuration(value: string): DurationParseResult;
+export declare function formatDuration(milliseconds: number): string;

package/build/src/duration.js

@@ -0,0 +1,22 @@
+const MULTIPLIERS = Object.freeze({
+    ms: 1n,
+    s: 1000n,
+    m: 60000n,
+    h: 3600000n,
+});
+export function parseDuration(value) {
+    const match = /^(0|[1-9][0-9]*)(ms|s|m|h)$/u.exec(value);
+    if (match === null)
+        return { kind: "invalid" };
+    const milliseconds = BigInt(match[1]) * MULTIPLIERS[match[2]];
+    if (milliseconds > BigInt(Number.MAX_SAFE_INTEGER))
+        return { kind: "overflow" };
+    return { kind: "parsed", milliseconds: Number(milliseconds) };
+}
+export function formatDuration(milliseconds) {
+    for (const [unit, multiplier] of [["h", 3_600_000], ["m", 60_000], ["s", 1_000]]) {
+        if (milliseconds >= multiplier && milliseconds % multiplier === 0)
+            return `${milliseconds / multiplier}${unit}`;
+    }
+    return `${milliseconds}ms`;
+}

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

@@ -0,0 +1,18 @@
+import type { Offer } from "../core/facts/offer.js";
+import type { GitAdmissionSnapshot } from "./observe.js";
+import { type GitRepository, type GitRefAssertion } from "./repository.js";
+import { type ContractHead } from "../core/facts/types.js";
+type Accepted = Readonly<{
+    kind: "accepted";
+    heads: Readonly<Record<string, ContractHead>>;
+}>;
+export type PublicationFailed = Readonly<{
+    kind: "publication-failed";
+    diagnostic: string;
+}>;
+type Unknown = Readonly<{
+    kind: "unknown";
+}>;
+export type Admission = Accepted | PublicationFailed | Unknown;
+export declare function admit(repository: GitRepository, offer: Offer, admission: GitAdmissionSnapshot, assertions?: readonly GitRefAssertion[]): Admission;
+export {};

package/build/src/git/admission.js

@@ -0,0 +1,126 @@
+import { decodeJournal, encodeEntry, } from "../core/facts/codec.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTreeFromFrozenDirectories, updateRefsAtomically, writeBlob, writeCommit, } from "./repository.js";
+import { contractJournalPath, contractJournalPaths, gitObjectIdForSnapshot, mintContractHead, mintSnapshotId, } from "./identity.js";
+import { validPath } from "./tree.js";
+const CONTRACT_JOURNAL_PATH = /^contracts\/(?:active|terminal)\/[0-9a-f]{2}\/[0-9a-f]{2}\/[0-9a-f]{60}\.jsonl$/u;
+function assertAppendStructure(appends) {
+    const seen = new Set();
+    for (const append of appends) {
+        if (!append || typeof append !== "object")
+            throw new Error("invalid contract append");
+        const id = append.contractId;
+        contractJournalPath(id);
+        if (seen.has(id))
+            throw new Error(`duplicate contract append: ${id}`);
+        seen.add(id);
+        if (!Array.isArray(append.entries) || append.entries.length === 0) {
+            throw new Error(`entries must be a nonempty array: ${id}`);
+        }
+    }
+    return appends;
+}
+function assertCompanionStructure(companions, appends) {
+    const reserved = new Set([GIT_FORMAT_PATH, ...appends.flatMap((append) => contractJournalPaths(append.contractId))]);
+    const seen = new Set();
+    for (const companion of companions) {
+        if (!companion || typeof companion !== "object")
+            throw new Error("invalid companion update");
+        validPath(companion.path);
+        if (!(companion.bytes instanceof Uint8Array))
+            throw new Error(`companion bytes must be Uint8Array: ${companion.path}`);
+        if (seen.has(companion.path))
+            throw new Error(`duplicate companion path: ${companion.path}`);
+        if (reserved.has(companion.path) || CONTRACT_JOURNAL_PATH.test(companion.path)) {
+            throw new Error(`companion path collides with admission-owned path: ${companion.path}`);
+        }
+        seen.add(companion.path);
+    }
+    return companions;
+}
+function readCanonicalJournal(admission, id) {
+    const snapshot = admission.snapshot;
+    const matches = contractJournalPaths(id).filter((path) => snapshot.paths.has(path));
+    if (matches.length > 1)
+        throw new Error(`duplicate contract journal identity: ${id}`);
+    const path = matches[0];
+    if (path === undefined)
+        return { bytes: Buffer.alloc(0), path: null };
+    const entry = snapshot.paths.get(path);
+    if (entry.type !== "blob")
+        throw new Error(`journal path is not a blob: ${path}`);
+    const journal = admission.frozenJournalBytes.get(entry.oid);
+    if (journal === undefined)
+        throw new Error(`missing frozen journal bytes: ${path}`);
+    return { bytes: journal, path };
+}
+function buildOffer(repository, admission, appends, companions) {
+    const snapshot = admission.snapshot;
+    const changes = new Map();
+    const heads = {};
+    if (snapshot.commit === null) {
+        changes.set(GIT_FORMAT_PATH, { oid: writeBlob(repository, GIT_FORMAT_BYTES), mode: "100644", type: "blob" });
+    }
+    for (const companion of companions) {
+        changes.set(companion.path, {
+            oid: writeBlob(repository, companion.bytes),
+            mode: "100644",
+            type: "blob",
+        });
+    }
+    for (const append of appends) {
+        const current = readCanonicalJournal(admission, append.contractId);
+        let journal = current.bytes;
+        for (const entry of append.entries)
+            journal = Buffer.concat([journal, Buffer.from(encodeEntry(entry))]);
+        const blob = writeBlob(repository, journal);
+        const entries = decodeJournal(journal.toString("utf8"));
+        const terminal = entries.some((entry) => entry.kind === "claimed" || entry.kind === "abandoned");
+        const destination = contractJournalPath(append.contractId, terminal ? "terminal" : "active");
+        if (current.path !== null && current.path !== destination)
+            changes.set(current.path, null);
+        changes.set(destination, { oid: blob, mode: "100644", type: "blob" });
+        heads[append.contractId] = mintContractHead(blob);
+    }
+    return { changes, heads };
+}
+function publishOffer(repository, admission, target, changes, assertions) {
+    const { snapshot } = admission;
+    const gitTree = updateGitTreeFromFrozenDirectories(repository, snapshot.tree, admission.treeDirectories, changes);
+    const gitCommit = mintSnapshotId(writeCommit({
+        repository,
+        tree: gitTree,
+        parent: snapshot.commit,
+    }));
+    return updateRefsAtomically(repository, [
+        { ref: GIT_REF, newOid: gitObjectIdForSnapshot(gitCommit), expectedOid: snapshot.commit },
+        ...(target === null
+            ? []
+            : [{
+                    ref: target.target,
+                    newOid: gitObjectIdForSnapshot(target.newOid),
+                    expectedOid: gitObjectIdForSnapshot(target.expectedOid),
+                }]),
+    ], assertions);
+}
+export function admit(repository, offer, admission, assertions = []) {
+    if (!Array.isArray(offer.facts) || offer.facts.length === 0) {
+        throw new Error("facts must be a nonempty array");
+    }
+    const appends = assertAppendStructure(offer.facts);
+    const companions = assertCompanionStructure(offer.companions ?? [], appends);
+    const target = offer.target ?? null;
+    const attempt = buildOffer(repository, admission, appends, companions);
+    const publication = publishOffer(repository, admission, target, attempt.changes, assertions);
+    if (publication.kind === "published") {
+        return {
+            kind: "accepted",
+            heads: attempt.heads,
+        };
+    }
+    if (publication.kind === "unknown")
+        return { kind: "unknown" };
+    return {
+        kind: "publication-failed",
+        diagnostic: publication.error instanceof Error ? publication.error.message : String(publication.error),
+    };
+}

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

@@ -0,0 +1,49 @@
+import { type Settings } from "../settings.js";
+export type HookCommand = Readonly<{
+    argv: readonly string[];
+    timeoutMs: number;
+}>;
+export type WorktreeHooks = Readonly<{
+    create: readonly HookCommand[];
+    destroy: readonly HookCommand[];
+}>;
+export type HookFailure = Readonly<{
+    kind: "exit";
+    code: number;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+}> | Readonly<{
+    kind: "timeout";
+}> | Readonly<{
+    kind: "spawn-error";
+    diagnostic: string;
+}> | Readonly<{
+    kind: "unknown-exit";
+}>;
+export type WorktreeHookLag = Readonly<{
+    kind: "worktree-hook-failed";
+    phase: HookPhase;
+    path: string;
+    command: number;
+    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";
+}> | Readonly<{
+    kind: "cancelled";
+}> | Readonly<{
+    kind: "failed";
+    command: number;
+    failure: HookFailure;
+}>;
+/** Execute an ordered command list without lifecycle state. Scratch owns this policy. */
+export declare function runHookCommands(worktree: string, commands: readonly HookCommand[], signal?: AbortSignal): Promise<HookCommandRun>;
+export declare function runCreateHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
+export declare function runDestroyHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
+export {};