@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/coordination/durable-file.js

@@ -0,0 +1,79 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, resolve } from "node:path";
+export function replaceFileDurably(path, bytes) {
+    const parent = dirname(path);
+    for (;;) {
+        const temporary = resolve(parent, `.tmp-${randomBytes(8).toString("hex")}`);
+        let descriptor;
+        try {
+            descriptor = openSync(temporary, "wx", 0o600);
+            writeFileSync(descriptor, bytes);
+            fsyncSync(descriptor);
+            closeSync(descriptor);
+            descriptor = undefined;
+            renameSync(temporary, path);
+            const directory = openSync(parent, "r");
+            try {
+                fsyncSync(directory);
+            }
+            finally {
+                closeSync(directory);
+            }
+            return;
+        }
+        catch (error) {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* renamed, absent, or best-effort cleanup */ }
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+}
+export function createFileDurablyExclusive(path, bytes, mode = 0o600) {
+    const parent = dirname(path);
+    mkdirSync(parent, { recursive: true });
+    let descriptor;
+    try {
+        descriptor = openSync(path, "wx", mode);
+        writeFileSync(descriptor, bytes);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        const directory = openSync(parent, "r");
+        try {
+            fsyncSync(directory);
+        }
+        finally {
+            closeSync(directory);
+        }
+        return true;
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        if (error.code === "EEXIST")
+            return false;
+        try {
+            unlinkSync(path);
+        }
+        catch { /* absent or best-effort cleanup */ }
+        throw error;
+    }
+}
+export function repairDerivedFile(path, bytes) {
+    const expected = Buffer.from(bytes);
+    mkdirSync(dirname(path), { recursive: true });
+    const stat = lstatSync(path, { throwIfNoEntry: false });
+    if (stat !== undefined && (!stat.isFile() || stat.isSymbolicLink())) {
+        throw new Error(`derived file is not a regular file: ${path}`);
+    }
+    if (stat !== undefined && readFileSync(path).equals(expected))
+        return "unchanged";
+    replaceFileDurably(path, expected);
+    return stat === undefined ? "created" : "updated";
+}

package/build/src/coordination/sqlite-transaction-lock.d.ts

@@ -0,0 +1,14 @@
+export type SqliteTransactionLockMode = "immediate" | "exclusive";
+export declare class SqliteTransactionLockError extends Error {
+    readonly reason: "timeout" | "invalid" | "open-failed" | "release-failed";
+    constructor(message: string, reason: "timeout" | "invalid" | "open-failed" | "release-failed", options?: ErrorOptions);
+}
+export type HeldSqliteTransactionLock = Readonly<{
+    close(): void;
+}>;
+export declare function acquireSqliteTransactionLock(input: {
+    path: string;
+    mode: SqliteTransactionLockMode;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<HeldSqliteTransactionLock>;

package/build/src/coordination/sqlite-transaction-lock.js

@@ -0,0 +1,119 @@
+import { randomInt } from "node:crypto";
+import { lstatSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const SQLITE_BUSY = 5;
+const INITIAL_RETRY_MS = 10;
+const MAX_RETRY_MS = 100;
+export class SqliteTransactionLockError extends Error {
+    reason;
+    constructor(message, reason, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "SqliteTransactionLockError";
+    }
+}
+function detail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isBusy(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const value = error;
+    const message = String(value.message ?? "").toLowerCase();
+    return value.errcode === SQLITE_BUSY || value.code === "ERR_SQLITE_BUSY"
+        || value.code === "ERR_SQLITE_LOCKED" || message.includes("database is locked")
+        || message.includes("database is busy");
+}
+function closeDatabase(database) {
+    let failure;
+    try {
+        database.exec("ROLLBACK");
+    }
+    catch (error) {
+        failure = error;
+    }
+    try {
+        database.close();
+    }
+    catch (error) {
+        failure ??= error;
+    }
+    return failure;
+}
+function openLock(path, mode) {
+    try {
+        const stat = lstatSync(path, { throwIfNoEntry: false });
+        if (stat && (!stat.isFile() || stat.isSymbolicLink())) {
+            throw new SqliteTransactionLockError(`SQLite lock is not a regular file: ${path}`, "invalid");
+        }
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    catch (error) {
+        if (error instanceof SqliteTransactionLockError)
+            throw error;
+        throw new SqliteTransactionLockError(`cannot prepare SQLite lock: ${detail(error)}`, "open-failed", { cause: error });
+    }
+    let database;
+    try {
+        database = new DatabaseSync(path);
+        database.exec("PRAGMA busy_timeout=0");
+        database.exec("PRAGMA journal_mode=DELETE");
+        database.exec("CREATE TABLE IF NOT EXISTS lock_anchor (singleton INTEGER PRIMARY KEY CHECK (singleton = 1))");
+        database.exec(`BEGIN ${mode.toUpperCase()}`);
+        database.prepare("SELECT singleton FROM lock_anchor LIMIT 1").get();
+    }
+    catch (error) {
+        if (database)
+            closeDatabase(database);
+        if (isBusy(error))
+            throw error;
+        throw new SqliteTransactionLockError(`cannot acquire SQLite lock: ${detail(error)}`, "open-failed", { cause: error });
+    }
+    let closed = false;
+    return { close() {
+            if (closed)
+                return;
+            closed = true;
+            const failure = closeDatabase(database);
+            if (failure !== undefined) {
+                throw new SqliteTransactionLockError(`cannot release SQLite lock: ${detail(failure)}`, "release-failed", { cause: failure });
+            }
+        } };
+}
+function wait(milliseconds, signal) {
+    return new Promise((resolve, reject) => {
+        const finish = () => { signal?.removeEventListener("abort", abort); resolve(); };
+        const timer = setTimeout(finish, milliseconds);
+        const abort = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); reject(signal?.reason); };
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+    });
+}
+export async function acquireSqliteTransactionLock(input) {
+    if (input.path.length === 0 || (input.timeoutMs !== undefined
+        && (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 0))) {
+        throw new SqliteTransactionLockError("SQLite lock path and timeout must be valid", "invalid");
+    }
+    const started = performance.now();
+    let cap = INITIAL_RETRY_MS;
+    for (;;) {
+        input.signal?.throwIfAborted();
+        try {
+            return openLock(input.path, input.mode);
+        }
+        catch (error) {
+            if (!isBusy(error))
+                throw error;
+            const elapsed = performance.now() - started;
+            if (input.timeoutMs !== undefined && elapsed >= input.timeoutMs) {
+                throw new SqliteTransactionLockError(`SQLite lock timed out after ${input.timeoutMs}ms: ${input.path}`, "timeout", { cause: error });
+            }
+            const delay = randomInt(Math.ceil(cap / 2), cap + 1);
+            const remaining = input.timeoutMs === undefined ? delay : Math.min(delay, input.timeoutMs - elapsed);
+            await wait(Math.max(0, remaining), input.signal);
+            cap = Math.min(MAX_RETRY_MS, cap * 2);
+        }
+    }
+}

package/build/src/core/decide.d.ts

@@ -0,0 +1,45 @@
+import type { Offer } from "./facts/offer.js";
+import type { ContractsObservation } from "./facts/observation.js";
+import type { DocumentKey, EntryUlid } from "./facts/types.js";
+export type AttemptContext = Readonly<{
+    entryUlids: readonly EntryUlid[];
+}>;
+export type DecideInput<Input> = Readonly<{
+    input: Input;
+    attempt: AttemptContext;
+    observation: ContractsObservation;
+}>;
+/** The protocol's mechanical or declaration result supplied to a legal decision. */
+export type Preparation<Data, Refusal> = Readonly<{
+    kind: "prepared";
+    data: Data;
+    refusal?: never;
+} | {
+    kind: "refused";
+    refusal: Refusal;
+    data?: never;
+}>;
+/** A document-derived preparation whose stamp is unavailable only with contract absence. */
+export type StampedPreparation<Data, Refusal> = Readonly<{
+    kind: "unavailable";
+    document?: never;
+    data?: never;
+    refusal?: never;
+} | {
+    kind: "prepared";
+    document: DocumentKey;
+    data: Data;
+    refusal?: never;
+} | {
+    kind: "refused";
+    document: DocumentKey;
+    refusal: Refusal;
+    data?: never;
+}>;
+export type OfferDecision<Refusal> = Readonly<{
+    kind: "offer";
+    offer: Offer;
+}> | Readonly<{
+    kind: "refused";
+    refusal: Refusal;
+}>;

package/build/src/core/facts/codec.d.ts

@@ -0,0 +1,3 @@
+import type { JournalEntry } from "./types.js";
+export declare function encodeEntry(entry: JournalEntry): string;
+export declare function decodeJournal(journal: string): JournalEntry[];

package/build/src/core/facts/codec.js

@@ -0,0 +1,277 @@
+import { parseDependencyKeySet } from "../subject.js";
+import { AuthorityCorruptionError } from "./errors.js";
+import { changeId, actorId, contractId, documentKey, documentSegmentKey, entryUlid, gate, snapshotId, } from "./types.js";
+const VERSION_BY_KIND = {
+    bind: 1,
+    amend: 1,
+    bound: 1,
+    deliver: 1,
+    attestation: 1,
+    claimed: 1,
+    arc: 1,
+    abandoned: 1,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fail(path, message) {
+    throw new AuthorityCorruptionError(`${path}: ${message}`);
+}
+function requireRecord(value, path) {
+    if (!isRecord(value))
+        fail(path, "expected an object");
+    return value;
+}
+function requireKeys(value, required, path, optional = []) {
+    const expected = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!expected.has(key))
+            fail(path, `unknown field '${key}'`);
+    }
+    for (const key of required) {
+        if (!(key in value))
+            fail(path, `missing field '${key}'`);
+    }
+}
+function stringValue(value, path, nonblank = true) {
+    if (typeof value !== "string" || (nonblank && value.trim().length === 0)) {
+        fail(path, nonblank ? "expected a nonblank string" : "expected a string");
+    }
+    return value;
+}
+function booleanValue(value, path) {
+    if (typeof value !== "boolean")
+        fail(path, "expected a boolean");
+    return value;
+}
+function brandedValue(value, path, brand) {
+    const text = stringValue(value, path);
+    try {
+        return brand(text);
+    }
+    catch (error) {
+        fail(path, error instanceof Error ? error.message : "invalid branded value");
+    }
+}
+function dependencyKeySetValue(value, path) {
+    if (typeof value !== "string")
+        fail(path, "expected a canonical dependency key set");
+    try {
+        return parseDependencyKeySet(value);
+    }
+    catch (error) {
+        fail(path, error instanceof Error ? error.message : "invalid dependency key set");
+    }
+}
+function documentValue(value, path) {
+    const object = requireRecord(value, path);
+    requireKeys(object, ["bytes", "key"], path);
+    return {
+        bytes: stringValue(object.bytes, `${path}.bytes`),
+        key: brandedValue(object.key, `${path}.key`, documentKey),
+    };
+}
+function arrayValue(value, path) {
+    if (!Array.isArray(value))
+        fail(path, "expected an array");
+    return value;
+}
+function brandedArray(value, path, brand) {
+    return arrayValue(value, path).map((item, index) => brandedValue(item, `${path}[${index}]`, brand));
+}
+function validateTimestamp(value, path) {
+    const text = stringValue(value, path);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(text)) {
+        fail(path, "expected a UTC RFC-3339 timestamp");
+    }
+    const milliseconds = Date.parse(text);
+    const canonical = Number.isFinite(milliseconds) ? new Date(milliseconds).toISOString() : "";
+    if (!Number.isFinite(milliseconds) || (text.includes(".") ? canonical !== text : canonical.replace(".000Z", "Z") !== text)) {
+        fail(path, "expected a real canonical UTC timestamp");
+    }
+    return text;
+}
+function validateCoordinates(value, path) {
+    const object = requireRecord(value, path);
+    requireKeys(object, ["start", "workspace"], path, ["target"]);
+    const workspace = stringValue(object.workspace, `${path}.workspace`);
+    if (workspace !== "worktree" && workspace !== "here")
+        fail(`${path}.workspace`, "unknown workspace");
+    return {
+        start: brandedValue(object.start, `${path}.start`, snapshotId),
+        workspace,
+        ...(object.target === undefined ? {} : { target: stringValue(object.target, `${path}.target`) }),
+    };
+}
+function termsValue(value, path) {
+    const object = requireRecord(value, path);
+    requireKeys(object, ["document", "segments", "gates", "after"], path);
+    return {
+        document: documentValue(object.document, `${path}.document`),
+        segments: brandedArray(object.segments, `${path}.segments`, documentSegmentKey),
+        gates: brandedArray(object.gates, `${path}.gates`, gate),
+        after: brandedArray(object.after, `${path}.after`, contractId),
+    };
+}
+function validateAttestation(value, path) {
+    const object = requireRecord(value, path);
+    requireKeys(object, ["gate", "subject", "verdict"], path, ["summary"]);
+    const declaredGate = brandedValue(object.gate, `${path}.gate`, gate);
+    const verdict = stringValue(object.verdict, `${path}.verdict`);
+    if (verdict !== "satisfied" && verdict !== "unsatisfied")
+        fail(`${path}.verdict`, "unknown attestation verdict");
+    return {
+        gate: declaredGate,
+        subject: dependencyKeySetValue(object.subject, `${path}.subject`),
+        verdict,
+        ...(object.summary === undefined ? {} : { summary: stringValue(object.summary, `${path}.summary`) }),
+    };
+}
+function validateArc(value, path) {
+    const object = requireRecord(value, path);
+    requireKeys(object, ["seq", "title", "objective", "brief"], path);
+    const seq = object.seq;
+    if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 1) {
+        fail(`${path}.seq`, "expected a positive safe integer");
+    }
+    return {
+        seq,
+        title: stringValue(object.title, `${path}.title`),
+        objective: stringValue(object.objective, `${path}.objective`),
+        brief: stringValue(object.brief, `${path}.brief`),
+    };
+}
+function validateData(kind, value) {
+    const path = `data.${kind}`;
+    switch (kind) {
+        case "bind": {
+            const object = requireRecord(value, path);
+            requireKeys(object, ["coordinates", "terms"], path);
+            return {
+                coordinates: validateCoordinates(object.coordinates, `${path}.coordinates`),
+                terms: termsValue(object.terms, `${path}.terms`),
+            };
+        }
+        case "amend":
+            return termsValue(value, path);
+        case "bound": {
+            const object = requireRecord(value, path);
+            requireKeys(object, [], path);
+            return {};
+        }
+        case "deliver": {
+            const object = requireRecord(value, path);
+            requireKeys(object, ["tenderSnapshot", "integration", "method", "policy"], path);
+            const integration = requireRecord(object.integration, `${path}.integration`);
+            requireKeys(integration, ["predecessor", "snapshot", "changeId"], `${path}.integration`);
+            const method = stringValue(object.method, `${path}.method`);
+            if (method !== "squash")
+                fail(`${path}.method`, "unknown merge method");
+            const policy = requireRecord(object.policy, `${path}.policy`);
+            requireKeys(policy, ["requireBranchesToBeUpToDate"], `${path}.policy`);
+            return {
+                tenderSnapshot: brandedValue(object.tenderSnapshot, `${path}.tenderSnapshot`, snapshotId),
+                integration: {
+                    predecessor: brandedValue(integration.predecessor, `${path}.integration.predecessor`, snapshotId),
+                    snapshot: brandedValue(integration.snapshot, `${path}.integration.snapshot`, snapshotId),
+                    changeId: brandedValue(integration.changeId, `${path}.integration.changeId`, changeId),
+                },
+                method,
+                policy: {
+                    requireBranchesToBeUpToDate: booleanValue(policy.requireBranchesToBeUpToDate, `${path}.policy.requireBranchesToBeUpToDate`),
+                },
+            };
+        }
+        case "attestation":
+            return validateAttestation(value, path);
+        case "claimed": {
+            const object = requireRecord(value, path);
+            requireKeys(object, ["delivery"], path);
+            return { delivery: brandedValue(object.delivery, `${path}.delivery`, entryUlid) };
+        }
+        case "arc":
+            return validateArc(value, path);
+        case "abandoned": {
+            const object = requireRecord(value, path);
+            requireKeys(object, [], path, ["note"]);
+            return {
+                ...(object.note === undefined ? {} : { note: stringValue(object.note, `${path}.note`) }),
+            };
+        }
+    }
+}
+function validateEntry(value) {
+    const object = requireRecord(value, "entry");
+    requireKeys(object, ["v", "kind", "contract", "entry", "at", "data"], "entry", ["actor"]);
+    const kind = object.kind;
+    if (typeof kind !== "string" || !Object.hasOwn(VERSION_BY_KIND, kind)) {
+        throw new AuthorityCorruptionError(`unknown journal entry kind: ${String(kind)}`);
+    }
+    const expectedVersion = VERSION_BY_KIND[kind];
+    if (object.v !== expectedVersion)
+        fail("entry.v", `expected version ${expectedVersion} for ${kind}`);
+    const entry = {
+        v: object.v,
+        kind,
+        contract: brandedValue(object.contract, "entry.contract", contractId),
+        entry: brandedValue(object.entry, "entry.entry", entryUlid),
+        at: validateTimestamp(object.at, "entry.at"),
+        ...(object.actor === undefined ? {} : { actor: brandedValue(object.actor, "entry.actor", actorId) }),
+        data: validateData(kind, object.data),
+    };
+    const after = entry.kind === "bind" ? entry.data.terms.after : entry.kind === "amend" ? entry.data.after : undefined;
+    if (after?.some((dependency) => dependency === entry.contract)) {
+        fail(`entry.data.${entry.kind}.after`, "after cannot reference its own contract");
+    }
+    return entry;
+}
+function canonicalValue(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new AuthorityCorruptionError("canonical JSON cannot encode a non-finite number");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalValue).join(",")}]`;
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort((left, right) => Buffer.from(left).compare(Buffer.from(right)));
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalValue(value[key])}`).join(",")}}`;
+    }
+    throw new AuthorityCorruptionError("canonical JSON accepts only JSON values");
+}
+function canonicalJson(value) {
+    return canonicalValue(value);
+}
+export function encodeEntry(entry) {
+    const validated = validateEntry(entry);
+    return `${canonicalJson(validated)}\n`;
+}
+function decodeEntry(line) {
+    if (line.includes("\r") || line.includes("\n\n"))
+        throw new AuthorityCorruptionError("journal entry must be one LF-delimited JSON value");
+    const body = line.endsWith("\n") ? line.slice(0, -1) : line;
+    if (body.length === 0)
+        throw new AuthorityCorruptionError("journal entry cannot be empty");
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch (error) {
+        throw new AuthorityCorruptionError("journal entry is not valid JSON", { cause: error });
+    }
+    const entry = validateEntry(value);
+    if (canonicalJson(entry) !== body)
+        throw new AuthorityCorruptionError("journal entry is not canonical");
+    return entry;
+}
+export function decodeJournal(journal) {
+    if (journal.length === 0)
+        return [];
+    if (journal.includes("\r") || !journal.endsWith("\n"))
+        throw new AuthorityCorruptionError("journal must use LF lines and end with LF");
+    return journal.slice(0, -1).split("\n").map((line) => decodeEntry(line));
+}

package/build/src/core/facts/eligibility.d.ts

@@ -0,0 +1,7 @@
+import { type ContractsObservation } from "./observation.js";
+import type { ContractId } from "./types.js";
+type EligibilityObservation = ContractsObservation;
+/** Decide whether resulting prerequisites reach the amended contract. */
+export declare function prerequisitesReach(contract: ContractId, prerequisites: readonly ContractId[], observation: EligibilityObservation): boolean;
+export declare function samePrerequisites(left: readonly ContractId[], right: readonly ContractId[]): boolean;
+export {};

package/build/src/core/facts/eligibility.js

@@ -0,0 +1,26 @@
+import { contractState } from "./observation.js";
+/** Decide whether resulting prerequisites reach the amended contract. */
+export function prerequisitesReach(contract, prerequisites, observation) {
+    const pending = [...prerequisites];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const dependency = pending.pop();
+        if (dependency === contract)
+            return true;
+        if (visited.has(dependency))
+            continue;
+        visited.add(dependency);
+        const state = contractState(observation, dependency);
+        if (state === null)
+            throw new Error(`absent contract in prerequisite closure: ${dependency}`);
+        pending.push(...state.terms.after);
+    }
+    return false;
+}
+export function samePrerequisites(left, right) {
+    if (left === right)
+        return true;
+    if (left.length !== right.length)
+        return false;
+    return left.every((id, index) => id === right[index]);
+}

package/build/src/core/facts/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class AuthorityCorruptionError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/build/src/core/facts/errors.js

@@ -0,0 +1,6 @@
+export class AuthorityCorruptionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "AuthorityCorruptionError";
+    }
+}

package/build/src/core/facts/fold.d.ts

@@ -0,0 +1,2 @@
+import type { ContractState, JournalEntry } from "./types.js";
+export declare function foldJournal(id: ContractState["id"], entries: readonly JournalEntry[], head?: ContractState["head"]): ContractState;