@astrosheep/keiyaku 2.9.13 → 4.0.0

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

@@ -0,0 +1,258 @@
+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 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, ["expectedPredecessor", "candidate", "deliveryPatchId"], path);
+            return {
+                expectedPredecessor: brandedValue(object.expectedPredecessor, `${path}.expectedPredecessor`, snapshotId),
+                candidate: brandedValue(object.candidate, `${path}.candidate`, snapshotId),
+                deliveryPatchId: brandedValue(object.deliveryPatchId, `${path}.deliveryPatchId`, changeId),
+            };
+        }
+        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,16 @@
+import type { Offer } from "./offer.js";
+import { type ContractsObservation } from "./observation.js";
+import type { ContractId, EntryUlid } from "./types.js";
+type EligibilityObservation = ContractsObservation;
+type EligibilityAttempt = Readonly<{
+    entryUlids: readonly EntryUlid[];
+}>;
+type PrerequisiteStatus = "unknown" | "pending" | "claimed";
+/** Resolve prerequisite existence and eligibility from one decision snapshot. */
+export declare function prerequisiteStatus(prerequisites: readonly ContractId[], observation: EligibilityObservation, offeredClaims?: ReadonlySet<ContractId>): PrerequisiteStatus;
+/** 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;
+/** Append bounds made eligible by a claimed offer from its full snapshot. */
+export declare function placeEligibleBounds(offer: Offer, observation: EligibilityObservation, attempt: EligibilityAttempt): Offer;
+export {};

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

@@ -0,0 +1,75 @@
+import { contractState } from "./observation.js";
+/** Resolve prerequisite existence and eligibility from one decision snapshot. */
+export function prerequisiteStatus(prerequisites, observation, offeredClaims) {
+    let pending = false;
+    for (const dependency of prerequisites) {
+        const state = contractState(observation, dependency);
+        if (state === null)
+            return "unknown";
+        if (state.terminal?.kind !== "claimed" && offeredClaims?.has(dependency) !== true)
+            pending = true;
+    }
+    return pending ? "pending" : "claimed";
+}
+/** 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]);
+}
+/** Append bounds made eligible by a claimed offer from its full snapshot. */
+export function placeEligibleBounds(offer, observation, attempt) {
+    const claimedEntry = offer.facts[0]?.entries[0];
+    if (offer.facts.length !== 1 || offer.facts[0]?.entries.length !== 1 || claimedEntry?.kind !== "claimed") {
+        throw new Error("eligible-bound placement requires exactly one claimed fact");
+    }
+    const claimed = new Set([claimedEntry.contract]);
+    const used = new Set([claimedEntry.entry]);
+    const available = attempt.entryUlids.filter((entry) => !used.has(entry));
+    let availableIndex = 0;
+    const additions = [];
+    for (const id of observation.keys()) {
+        const state = contractState(observation, id);
+        if (!state || state.bound || state.terminal)
+            continue;
+        if (prerequisiteStatus(state.terms.after, observation, claimed) !== "claimed")
+            continue;
+        const entry = available[availableIndex];
+        if (entry === undefined)
+            throw new Error("placement attempt lacks an entry ULID for an eligible contract");
+        availableIndex += 1;
+        additions.push({
+            contractId: id,
+            expectedHead: state.head,
+            entries: [{
+                    v: 1,
+                    kind: "bound",
+                    contract: id,
+                    entry,
+                    at: claimedEntry.at,
+                    ...(claimedEntry.actor === undefined ? {} : { actor: claimedEntry.actor }),
+                    data: {},
+                }],
+        });
+    }
+    return additions.length === 0 ? offer : { ...offer, facts: [...additions, ...offer.facts] };
+}

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;

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

@@ -0,0 +1,97 @@
+import { samePrerequisites } from "./eligibility.js";
+import { gatesSatisfied } from "./gate.js";
+import { AuthorityCorruptionError } from "./errors.js";
+function foldError(message) {
+    throw new AuthorityCorruptionError(`invalid journal fold: ${message}`);
+}
+function cloneTerms(terms) {
+    return {
+        document: { ...terms.document },
+        segments: [...terms.segments],
+        gates: [...terms.gates],
+        after: [...terms.after],
+    };
+}
+function cloneCoordinates(coordinates) {
+    return { ...coordinates };
+}
+function stateFromBind(id, head, bind, attestations) {
+    if (bind.contract !== id)
+        foldError(`entry belongs to ${bind.contract}, not ${id}`);
+    return {
+        id,
+        head,
+        coordinates: cloneCoordinates(bind.data.coordinates),
+        terms: cloneTerms(bind.data.terms),
+        bound: null,
+        delivery: null,
+        attestations,
+        terminal: null,
+    };
+}
+function requireActive(state, entry) {
+    if (state.terminal !== null)
+        foldError(`terminal contract cannot accept ${entry.kind}`);
+}
+function foldArc(state, entry) {
+    const expectedSequence = (state.currentArc?.data.seq ?? 0) + 1;
+    if (entry.data.seq !== expectedSequence) {
+        foldError(`arc sequence must be ${expectedSequence}`);
+    }
+    return { ...state, currentArc: entry };
+}
+function foldEntry(state, entry, attestations) {
+    if (entry.contract !== state.id)
+        foldError(`entry belongs to ${entry.contract}, not ${state.id}`);
+    requireActive(state, entry);
+    switch (entry.kind) {
+        case "bind":
+            foldError("bind may appear only once");
+        case "amend": {
+            if (state.bound !== null && !samePrerequisites(state.terms.after, entry.data.after)) {
+                foldError("cannot change after once prerequisites are consumed");
+            }
+            return { ...state, terms: cloneTerms(entry.data) };
+        }
+        case "bound":
+            if (state.bound !== null)
+                foldError("bound may appear only once");
+            return { ...state, bound: entry };
+        case "deliver":
+            if (state.bound === null)
+                foldError("deliver requires bound");
+            return { ...state, delivery: entry };
+        case "attestation":
+            attestations.push(entry);
+            return { ...state, attestations };
+        case "claimed":
+            if (state.delivery === null)
+                foldError("claimed requires a deliver");
+            if (entry.data.delivery !== state.delivery.entry)
+                foldError("claimed must name the current deliver");
+            if (!gatesSatisfied(state))
+                foldError("claimed gates are not satisfied");
+            return { ...state, terminal: entry };
+        case "arc":
+            return foldArc(state, entry);
+        case "abandoned":
+            return { ...state, terminal: entry };
+    }
+}
+export function foldJournal(id, entries, head = null) {
+    const first = entries[0];
+    if (first === undefined || first.kind !== "bind")
+        foldError("journal must begin with bind");
+    const seen = new Set();
+    const attestations = [];
+    seen.add(first.entry);
+    let state = stateFromBind(id, head, first, attestations);
+    for (let index = 1; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (seen.has(entry.entry))
+            foldError(`duplicate entry ${entry.entry}`);
+        seen.add(entry.entry);
+        state = foldEntry(state, entry, attestations);
+    }
+    return state;
+}

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

@@ -0,0 +1,24 @@
+import type { AttestationEntry, ContractState, Gate } from "./types.js";
+export type GateCurrent = Readonly<{
+    kind: "attested";
+    verdict: "satisfied" | "unsatisfied";
+    summary?: string;
+}> | Readonly<{
+    kind: "stale";
+    priorVerdict: "satisfied" | "unsatisfied";
+}> | Readonly<{
+    kind: "missing";
+}>;
+export type GateReport = Readonly<{
+    gate: Gate;
+    current: GateCurrent;
+}>;
+export type GateReports = Readonly<{
+    reports: readonly GateReport[];
+    satisfied: boolean;
+}>;
+/** Resolve the latest testimony for each requested gate and current subject. */
+export declare function latestCurrentAttestations(state: ContractState, requested: ReadonlySet<Gate>): ReadonlyMap<Gate, AttestationEntry>;
+export declare function gatesSatisfied(state: ContractState): boolean;
+/** Project every declared gate without allowing consumers to reimplement currency. */
+export declare function gateReports(state: ContractState): GateReports;

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

@@ -0,0 +1,52 @@
+import { currentSubjectPredicate } from "../subject.js";
+/** Resolve the latest testimony for each requested gate and current subject. */
+export function latestCurrentAttestations(state, requested) {
+    const attestations = new Map();
+    const subjectIsCurrent = currentSubjectPredicate(state);
+    for (let index = state.attestations.length - 1; index >= 0; index -= 1) {
+        const attestation = state.attestations[index];
+        const { gate, subject } = attestation.data;
+        if (!requested.has(gate) || attestations.has(gate) || !subjectIsCurrent(subject))
+            continue;
+        attestations.set(gate, attestation);
+        if (attestations.size === requested.size)
+            break;
+    }
+    return attestations;
+}
+export function gatesSatisfied(state) {
+    return gateReports(state).satisfied;
+}
+/** Project every declared gate without allowing consumers to reimplement currency. */
+export function gateReports(state) {
+    const declared = state.terms.gates;
+    const requested = new Set(declared);
+    const current = latestCurrentAttestations(state, requested);
+    const prior = new Map();
+    for (let index = state.attestations.length - 1; index >= 0; index -= 1) {
+        const entry = state.attestations[index];
+        if (!prior.has(entry.data.gate) && requested.has(entry.data.gate))
+            prior.set(entry.data.gate, entry);
+    }
+    const reports = declared.map((gate) => {
+        const attestation = current.get(gate);
+        if (attestation !== undefined) {
+            return {
+                gate,
+                current: {
+                    kind: "attested",
+                    verdict: attestation.data.verdict,
+                    ...(attestation.data.summary === undefined ? {} : { summary: attestation.data.summary }),
+                },
+            };
+        }
+        const previous = prior.get(gate);
+        return previous === undefined
+            ? { gate, current: { kind: "missing" } }
+            : { gate, current: { kind: "stale", priorVerdict: previous.data.verdict } };
+    });
+    return {
+        reports,
+        satisfied: reports.every((report) => report.current.kind === "attested" && report.current.verdict === "satisfied"),
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { ContractId, ContractState, DocumentKey } from "./types.js";
+/** The complete state projection consumed by one pure pact decision. */
+export type ContractsObservation = ReadonlyMap<ContractId, ContractState | null>;
+/** Read one requested identity; a missing key violates the observation contract. */
+export declare function contractState(observation: ContractsObservation, contract: ContractId): ContractState | null;
+export type ActiveContractRefusal = Readonly<{
+    kind: "contract-missing" | "terminal";
+    contractId: ContractId;
+}>;
+/** The single lifecycle guard shared by every operation on an existing contract. */
+export declare function activeContract(observation: ContractsObservation, contract: ContractId): ContractState | ActiveContractRefusal;
+export declare function documentIsCurrent(state: ContractState, document: DocumentKey): boolean;

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

@@ -0,0 +1,23 @@
+/** Read one requested identity; a missing key violates the observation contract. */
+export function contractState(observation, contract) {
+    const state = observation.get(contract);
+    if (state === undefined) {
+        throw new Error(`missing contract decision observation: ${contract}`);
+    }
+    if (state !== null && state.id !== contract) {
+        throw new Error(`contract state identity disagrees with decision map: ${contract}`);
+    }
+    return state;
+}
+/** The single lifecycle guard shared by every operation on an existing contract. */
+export function activeContract(observation, contract) {
+    const state = contractState(observation, contract);
+    if (state === null)
+        return { kind: "contract-missing", contractId: contract };
+    if (state.terminal)
+        return { kind: "terminal", contractId: contract };
+    return state;
+}
+export function documentIsCurrent(state, document) {
+    return state.terms.document.key === document;
+}

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

@@ -0,0 +1,21 @@
+import type { ContractHead, ContractId, JournalEntry, SnapshotId } from "./types.js";
+export type ContractJournalAppend = Readonly<{
+    readonly contractId: ContractId;
+    readonly expectedHead: ContractHead | null;
+    readonly entries: readonly JournalEntry[];
+}>;
+/** A target operation is optional because claim can be journal-only. */
+export type RefOperation = Readonly<{
+    readonly target: string;
+    readonly newOid: SnapshotId;
+    readonly expectedOid: SnapshotId;
+}>;
+export type TreeUpdate = Readonly<{
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}>;
+export type Offer = Readonly<{
+    readonly facts: readonly ContractJournalAppend[];
+    readonly target?: RefOperation;
+    readonly companions?: readonly TreeUpdate[];
+}>;