@astrosheep/keiyaku 2.9.13 → 4.0.0

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

@@ -0,0 +1,31 @@
+import { type ContractId } from "../core/facts/types.js";
+import { type AkuId } from "../akuma/identity.js";
+import { type GitRepository } from "../git/repository.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 readDispatches(repository: GitRepository): readonly Dispatch[];
+export declare function publishDispatch(input: Readonly<{
+    repository: GitRepository;
+    akuId: AkuId;
+    contractId: ContractId;
+}>): DispatchPublication;

package/build/src/dispatch/index.js

@@ -0,0 +1,159 @@
+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, readGit, readGitPaths, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.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 function readDispatches(repository) {
+    const snapshot = readGit(repository);
+    const dispatches = [];
+    const seen = new Set();
+    for (const [path, entry] of 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 dispatch = decode(path, readBlob(repository, entry.oid));
+        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)));
+}
+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/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 } 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): Admission;
+export {};

package/build/src/git/admission.js

@@ -0,0 +1,116 @@
+import { encodeEntry, } from "../core/facts/codec.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "./repository.js";
+import { contractJournalPath, gitObjectIdForSnapshot, mintContractHead, mintSnapshotId, } from "./identity.js";
+import { validPath } from "./tree.js";
+const CONTRACT_JOURNAL_PATH = /^contracts\/[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.map((append) => contractJournalPath(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 path = contractJournalPath(id);
+    const entry = snapshot.paths.get(path);
+    if (entry === undefined)
+        return Buffer.alloc(0);
+    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 journal;
+}
+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) {
+        let journal = readCanonicalJournal(admission, append.contractId);
+        for (const entry of append.entries)
+            journal = Buffer.concat([journal, Buffer.from(encodeEntry(entry))]);
+        const blob = writeBlob(repository, journal);
+        changes.set(contractJournalPath(append.contractId), { oid: blob, mode: "100644", type: "blob" });
+        heads[append.contractId] = mintContractHead(blob);
+    }
+    return { changes, heads };
+}
+function publishOffer(repository, snapshot, target, changes) {
+    const gitTree = updateGitTree(repository, snapshot.tree, 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),
+                }]),
+    ]);
+}
+export function admit(repository, offer, admission) {
+    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.snapshot, target, attempt.changes);
+    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/delivery.d.ts

@@ -0,0 +1,20 @@
+import type { Preparation } from "../core/decide.js";
+import type { ChangeId, ContractCoordinates, ContractId, DeliverData } from "../core/facts/types.js";
+import { type GitRepository } from "./repository.js";
+export type DeliveryPreparationRefusal = Readonly<{
+    kind: "target-missing" | "candidate-not-based-on-target" | "worktree-missing";
+    contractId: ContractId;
+}>;
+export type ReviewPreparationRefusal = Readonly<{
+    kind: "worktree-missing";
+    contractId: ContractId;
+}>;
+export type DeliveryPreparationCoordinates = Readonly<{
+    contractId: ContractId;
+    coordinates: ContractCoordinates;
+}>;
+export declare function prepareReview(repository: GitRepository, input: DeliveryPreparationCoordinates): Preparation<ChangeId, ReviewPreparationRefusal>;
+export declare function prepareDelivery(repository: GitRepository, stage: DeliveryPreparationCoordinates, input: Readonly<{
+    title: string;
+    message?: string;
+}>): Preparation<DeliverData, DeliveryPreparationRefusal>;

package/build/src/git/delivery.js

@@ -0,0 +1,109 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mintChangeId, mintSnapshotId, gitObjectIdForSnapshot, gitObjectId } from "./identity.js";
+import { readRef, registeredWorktreePaths, runGit, runGitWithEnvironment } from "./repository.js";
+import { deliveryWorktreePath } from "./reconcile.js";
+function workspaceExists(repository, workspace, path) {
+    return workspace === "here"
+        || (existsSync(path) && registeredWorktreePaths(repository).includes(path));
+}
+function withPrivateGitIndex(action) {
+    const directory = mkdtempSync(join(tmpdir(), "keiyaku-v4-index-"));
+    const index = join(directory, "index");
+    try {
+        return action({ GIT_INDEX_FILE: index });
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+}
+function workspaceFor(repository, id, workspace) {
+    return workspace === "worktree" ? deliveryWorktreePath(repository, id) : repository.effectiveCwd;
+}
+function stablePatchId(repository, predecessor, tree) {
+    const diff = runGit(repository, ["diff", "--binary", gitObjectIdForSnapshot(predecessor), tree]);
+    const output = runGit(repository, ["patch-id", "--stable"], diff).toString("utf8").trim();
+    const separator = output.indexOf(" ");
+    const identity = output.length === 0
+        ? runGit(repository, ["hash-object", "-t", "blob", "--stdin"], diff).toString("utf8").trim()
+        : separator < 0 ? output : output.slice(0, separator);
+    return mintChangeId(identity);
+}
+function workspaceTree(repository, workspace) {
+    const identities = runGit(repository, ["-C", workspace, "rev-parse", "HEAD", "HEAD^{tree}"])
+        .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 status = runGit(repository, ["-C", workspace, "status", "--porcelain=v1", "--untracked-files=all"]).toString("utf8");
+    const dirty = status.length > 0;
+    if (!dirty)
+        return { tree, head, dirty };
+    return withPrivateGitIndex((environment) => {
+        runGitWithEnvironment(repository, ["-C", workspace, "read-tree", "HEAD"], undefined, environment);
+        runGitWithEnvironment(repository, ["-C", workspace, "add", "--all"], undefined, environment);
+        const tree = gitObjectId(runGitWithEnvironment(repository, ["-C", workspace, "write-tree"], undefined, environment).toString("utf8").trim(), "workspace tree");
+        return { tree, head, dirty };
+    });
+}
+function materializeCandidate(input) {
+    const subject = input.message ?? `${input.contractId}: ${input.title}`;
+    const message = `${subject}\n\nKeiyaku-Contract: ${input.contractId}\n`;
+    const commit = runGitWithEnvironment(input.repository, ["-C", input.workspace, "commit-tree", input.tree, "-p", gitObjectIdForSnapshot(input.head)], message, {
+        GIT_AUTHOR_NAME: "Keiyaku",
+        GIT_AUTHOR_EMAIL: "keiyaku@localhost",
+        GIT_COMMITTER_NAME: "Keiyaku",
+        GIT_COMMITTER_EMAIL: "keiyaku@localhost",
+        GIT_AUTHOR_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
+        GIT_COMMITTER_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
+    }).toString("utf8").trim();
+    return mintSnapshotId(commit);
+}
+export function prepareReview(repository, input) {
+    const workspace = workspaceFor(repository, input.contractId, input.coordinates.workspace);
+    if (!workspaceExists(repository, input.coordinates.workspace, workspace)) {
+        return { kind: "refused", refusal: { kind: "worktree-missing", contractId: input.contractId } };
+    }
+    const tree = workspaceTree(repository, workspace);
+    return { kind: "prepared", data: stablePatchId(repository, input.coordinates.start, tree.tree) };
+}
+export function prepareDelivery(repository, stage, input) {
+    const id = stage.contractId;
+    const coordinates = stage.coordinates;
+    const observedTarget = coordinates.target === undefined ? null : readRef(repository, coordinates.target);
+    if (coordinates.target !== undefined && observedTarget === null) {
+        return { kind: "refused", refusal: { kind: "target-missing", contractId: id } };
+    }
+    const predecessor = observedTarget === null ? coordinates.start : mintSnapshotId(observedTarget);
+    const workspace = workspaceFor(repository, id, coordinates.workspace);
+    if (!workspaceExists(repository, coordinates.workspace, workspace)) {
+        return { kind: "refused", refusal: { kind: "worktree-missing", contractId: id } };
+    }
+    const content = workspaceTree(repository, workspace);
+    const candidate = content.dirty
+        ? materializeCandidate({ repository, contractId: id, workspace, ...input, tree: content.tree, head: content.head })
+        : content.head;
+    if (coordinates.target !== undefined) {
+        try {
+            runGit(repository, ["merge-base", "--is-ancestor", gitObjectIdForSnapshot(predecessor), gitObjectIdForSnapshot(candidate)]);
+        }
+        catch (error) {
+            const status = error.status;
+            if (status === 1)
+                return { kind: "refused", refusal: { kind: "candidate-not-based-on-target", contractId: id } };
+            throw error;
+        }
+    }
+    return {
+        kind: "prepared",
+        data: {
+            expectedPredecessor: predecessor,
+            candidate,
+            deliveryPatchId: stablePatchId(repository, predecessor, content.tree),
+        },
+    };
+}

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

@@ -0,0 +1,34 @@
+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 hookMarkerPath(administrationDirectory: string): string;
+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 {};