@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/repository-ledger/traversal.js

@@ -0,0 +1,404 @@
+import { classifyRepositoryLedgerSubject, evidenceObjectId, parseRepositoryLedgerMessage, } from "./codec.js";
+import { transactionMembershipError } from "./transaction-membership.js";
+import { assertReadableCommitClosure, assertReadableCommit, deriveHostGitCoordinates, openRepositoryCommitReader, RepositoryObjectError, } from "./git-object-store.js";
+import { assertHonestClaimEvidence, assertHonestClaimEvidenceClosure, ClaimEvidenceMismatchError, ClaimEvidenceOperationalError, repositoryObjectDirectory } from "./claim-evidence.js";
+/** Ledger topology excludes lifecycle causality and evidence ancestry. */
+export function ledgerTopologyParents(node) {
+    if (node.type === "transaction" || node.type === "join")
+        return node.ledgerParents;
+    if (node.type === "disease" && (node.boundary === "transaction" || node.boundary === "join")) {
+        return node.ledgerParents;
+    }
+    return [];
+}
+function topologyFor(record, parents, objectId) {
+    if (record.kind === "join") {
+        if (parents.length !== 2 || parents[0] === parents[1])
+            throw new Error("structural join must have exactly two distinct ledger parents");
+        return { type: "join", objectId, join: record, ledgerParents: [parents[0], parents[1]], evidenceParent: null };
+    }
+    if (record.kind === "transaction") {
+        const predecessorCount = record.predecessor === "p1" ? 1 : 0;
+        if (parents.length <= predecessorCount)
+            throw new Error("transaction must link at least one introduced lifecycle entry");
+        const ledgerParents = parents.slice(0, predecessorCount);
+        const entryObjectIds = parents.slice(predecessorCount);
+        if (new Set(parents).size !== parents.length)
+            throw new Error("transaction parents must be distinct");
+        return {
+            type: "transaction",
+            objectId,
+            transaction: record,
+            ledgerParents,
+            entryObjectIds,
+            contract: "",
+            finalEntryObjectId: entryObjectIds.at(-1),
+            evidenceParent: null,
+        };
+    }
+    const evidence = evidenceObjectId(record);
+    if (evidence !== null) {
+        if (parents.length !== 2)
+            throw new Error(`${record.kind} requires lifecycle p1 and evidence p2`);
+        if (parents[1] !== evidence)
+            throw new Error(`${record.kind} evidence p2 does not match ${evidence}`);
+        return { type: "lifecycle", objectId, entry: record, ledgerParents: [parents[0]], evidenceParent: evidence };
+    }
+    if (parents.length > 1)
+        throw new Error(`${record.kind} may have at most one lifecycle parent and no evidence parent`);
+    if (parents.length === 0 && record.kind !== "bind")
+        throw new Error("the parentless lifecycle root must be bind");
+    return {
+        type: "lifecycle",
+        objectId,
+        entry: record,
+        ledgerParents: parents.length === 0 ? [] : [parents[0]],
+        evidenceParent: null,
+    };
+}
+function recoverDiseasedTopology(message, parents) {
+    const subject = message === undefined ? { type: "unknown" } : classifyRepositoryLedgerSubject(message);
+    if (subject.type === "join")
+        return { boundary: "join", ledgerParents: parents.slice(0, 2) };
+    if (subject.type === "transaction")
+        return { boundary: "transaction", ledgerParents: parents.slice(0, 1) };
+    if (subject.type === "lifecycle")
+        return { boundary: "lifecycle", contract: subject.contract, ledgerParents: parents.slice(0, 1) };
+    return { boundary: "unknown", ledgerParents: [] };
+}
+function decodeCommitMessage(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        throw new Error("commit message is not valid UTF-8", { cause: error });
+    }
+}
+function throwIfAborted(error) {
+    if (error instanceof Error && error.name === "AbortError")
+        throw error;
+}
+function readableLawfulTransactionContract(node, nodes) {
+    const entries = [];
+    for (const entryObjectId of node.entryObjectIds) {
+        const entryNode = nodes.get(entryObjectId);
+        if (entryNode?.type !== "lifecycle")
+            return undefined;
+        entries.push(entryNode.entry);
+    }
+    if (transactionMembershipError(node.transaction.verb, entries))
+        return undefined;
+    for (let index = 0; index < node.entryObjectIds.length; index += 1) {
+        const entryNode = nodes.get(node.entryObjectIds[index]);
+        const causalParent = entryNode.ledgerParents[0];
+        if (index === 0) {
+            if (entryNode.entry.kind === "bind" ? causalParent !== undefined : causalParent === undefined)
+                return undefined;
+        }
+        else if (causalParent !== node.entryObjectIds[index - 1]) {
+            return undefined;
+        }
+    }
+    return entries[0]?.contract;
+}
+function hasDisease(diseases, objectId, code) {
+    return diseases.some((disease) => disease.objectId === objectId && disease.code === code);
+}
+export function transactionEntryBoundaryError(node, nodes, wasAcceptedBefore) {
+    const entries = [];
+    for (const entryObjectId of node.entryObjectIds) {
+        if (wasAcceptedBefore(entryObjectId))
+            return "transaction links a lifecycle entry already reachable from its predecessor";
+        const entryNode = nodes.get(entryObjectId);
+        if (entryNode?.type !== "lifecycle")
+            return "transaction entry link is not a readable lifecycle node";
+        entries.push(entryNode.entry);
+    }
+    const membership = transactionMembershipError(node.transaction.verb, entries);
+    if (membership)
+        return membership;
+    for (let index = 0; index < node.entryObjectIds.length; index += 1) {
+        const entryNode = nodes.get(node.entryObjectIds[index]);
+        const causalParent = entryNode.ledgerParents[0];
+        if (index === 0) {
+            if (entryNode.entry.kind === "bind") {
+                if (causalParent !== undefined)
+                    return "bind transaction entry must be causally parentless";
+            }
+            else if (causalParent === undefined || !wasAcceptedBefore(causalParent)) {
+                return "first transaction entry must continue lifecycle causality reachable from the predecessor";
+            }
+        }
+        else if (causalParent !== node.entryObjectIds[index - 1]) {
+            return "transaction entries do not form one ordered lifecycle causal tail";
+        }
+    }
+    node.contract = entries[0].contract;
+    return null;
+}
+function transactionBoundaryError(node, nodes, acceptedEntryIntroductions) {
+    if (node.transaction.predecessor === "none") {
+        if (node.ledgerParents.length !== 0)
+            return "root transaction unexpectedly has a predecessor";
+        if (node.transaction.verb !== "bind")
+            return "the root transaction must be bind";
+    }
+    else if (node.ledgerParents.length !== 1) {
+        return "non-root transaction must have exactly one ledger predecessor";
+    }
+    const predecessor = node.ledgerParents[0];
+    if (predecessor !== undefined) {
+        const predecessorNode = nodes.get(predecessor);
+        if (!predecessorNode || predecessorNode.type === "lifecycle" || (predecessorNode.type === "disease" && predecessorNode.boundary === "lifecycle")) {
+            return "transaction predecessor is not a complete typed ledger node";
+        }
+    }
+    return transactionEntryBoundaryError(node, nodes, (entryObjectId) => {
+        const introduction = acceptedEntryIntroductions.get(entryObjectId);
+        return introduction !== undefined
+            && predecessor !== undefined
+            && isTypedLedgerAncestor({ nodes }, introduction, predecessor);
+    });
+}
+export async function traverseRepositoryLedger(cwd, head, signal, options = {}) {
+    const coordinates = await deriveHostGitCoordinates(cwd, signal);
+    let completeObservedClosure = true;
+    try {
+        await assertReadableCommitClosure(cwd, head, signal);
+    }
+    catch (error) {
+        if (error instanceof RepositoryObjectError && error.reason === "incomplete-commit-closure") {
+            completeObservedClosure = false;
+        }
+        else {
+            throw error;
+        }
+    }
+    const reader = openRepositoryCommitReader(cwd, coordinates, signal);
+    let objectDirectory;
+    const nodes = new Map();
+    const diseases = [];
+    const order = [];
+    const visiting = new Set();
+    const visited = new Set();
+    const acceptedEntryIntroductions = new Map();
+    const visit = async (objectId) => {
+        if (visited.has(objectId))
+            return;
+        if (visiting.has(objectId)) {
+            diseases.push({ objectId, code: "cycle", detail: "typed repository ancestry contains a cycle" });
+            return;
+        }
+        visiting.add(objectId);
+        let raw;
+        try {
+            raw = await reader.read(objectId);
+        }
+        catch (error) {
+            throwIfAborted(error);
+            diseases.push({ objectId, code: "unreadable-node", detail: error instanceof Error ? error.message : String(error) });
+            visiting.delete(objectId);
+            visited.add(objectId);
+            return;
+        }
+        let message;
+        let record;
+        try {
+            message = decodeCommitMessage(raw.messageBytes);
+            record = parseRepositoryLedgerMessage(message, coordinates.objectFormat);
+        }
+        catch (error) {
+            const diseased = recoverDiseasedTopology(message ?? raw.subjectHint, raw.parents);
+            diseases.push({ objectId, code: "invalid-codec", detail: error instanceof Error ? error.message : String(error), ...(diseased.contract ? { contract: diseased.contract } : {}) });
+            nodes.set(objectId, { type: "disease", objectId, ...diseased, evidenceParent: null });
+            for (const parent of diseased.ledgerParents)
+                await visit(parent);
+            order.push(objectId);
+            visiting.delete(objectId);
+            visited.add(objectId);
+            return;
+        }
+        if (raw.tree !== coordinates.emptyTree) {
+            const diseased = recoverDiseasedTopology(message, raw.parents);
+            diseases.push({ objectId, code: "wrong-tree", detail: `expected empty tree ${coordinates.emptyTree}, found ${raw.tree}`, ...(diseased.contract ? { contract: diseased.contract } : {}) });
+            nodes.set(objectId, { type: "disease", objectId, ...diseased, evidenceParent: null });
+            for (const parent of diseased.ledgerParents)
+                await visit(parent);
+            order.push(objectId);
+            visiting.delete(objectId);
+            visited.add(objectId);
+            return;
+        }
+        let node;
+        try {
+            node = topologyFor(record, raw.parents, objectId);
+        }
+        catch (error) {
+            const diseased = recoverDiseasedTopology(message, raw.parents);
+            diseases.push({ objectId, code: "invalid-parent-topology", detail: error instanceof Error ? error.message : String(error), ...(diseased.contract ? { contract: diseased.contract } : {}) });
+            nodes.set(objectId, { type: "disease", objectId, ...diseased, evidenceParent: null });
+            for (const parent of diseased.ledgerParents)
+                await visit(parent);
+            order.push(objectId);
+            visiting.delete(objectId);
+            visited.add(objectId);
+            return;
+        }
+        nodes.set(objectId, node);
+        const dependencies = node.type === "transaction"
+            ? [...node.ledgerParents, ...node.entryObjectIds]
+            : [...node.ledgerParents];
+        for (const parent of dependencies)
+            await visit(parent);
+        const unreadableLedgerParent = node.ledgerParents.find((parent) => hasDisease(diseases, parent, "unreadable-node") ||
+            (node.type === "transaction" && hasDisease(diseases, parent, "unreadable-ledger-closure")));
+        if ((node.type === "transaction" || node.type === "join") && unreadableLedgerParent !== undefined) {
+            const contract = node.type === "transaction"
+                ? readableLawfulTransactionContract(node, nodes)
+                : undefined;
+            const closureDisease = {
+                objectId,
+                code: "unreadable-ledger-closure",
+                detail: `ledger predecessor ${unreadableLedgerParent} is not completely readable`,
+                ...(contract === undefined ? {} : { contract }),
+            };
+            const predecessorDiseaseIndex = diseases.findIndex((disease) => disease.objectId === unreadableLedgerParent && disease.code === "unreadable-node");
+            if (predecessorDiseaseIndex < 0)
+                diseases.push(closureDisease);
+            else
+                diseases.splice(predecessorDiseaseIndex, 0, closureDisease);
+            nodes.set(objectId, {
+                type: "disease",
+                objectId,
+                boundary: node.type,
+                ...(contract === undefined ? {} : { contract }),
+                ledgerParents: [...node.ledgerParents],
+                evidenceParent: null,
+            });
+            order.push(objectId);
+            visiting.delete(objectId);
+            visited.add(objectId);
+            return;
+        }
+        if (node.type === "lifecycle" && node.evidenceParent !== null) {
+            try {
+                if (node.entry.kind === "claim") {
+                    if (options.historicalSemanticEvidence !== false) {
+                        objectDirectory ??= await repositoryObjectDirectory(cwd, signal);
+                        await assertHonestClaimEvidence(cwd, node.entry.data, { coordinates, reader, objectDirectory, signal });
+                    }
+                    else {
+                        await reader.read(node.evidenceParent);
+                    }
+                    if (!completeObservedClosure)
+                        await assertHonestClaimEvidenceClosure(cwd, node.evidenceParent);
+                }
+                else {
+                    await reader.read(node.evidenceParent);
+                    if (!completeObservedClosure)
+                        await assertReadableCommit(cwd, coordinates, node.evidenceParent);
+                }
+            }
+            catch (error) {
+                throwIfAborted(error);
+                if (node.entry.kind === "claim" && !(error instanceof ClaimEvidenceMismatchError)) {
+                    if (error instanceof ClaimEvidenceOperationalError)
+                        throw error;
+                    throw new ClaimEvidenceOperationalError("cannot read claim evidence for verification", { cause: error });
+                }
+                const code = node.entry.kind === "claim" ? "invalid-evidence" : "unreadable-evidence";
+                diseases.push({ objectId, code, detail: error instanceof Error ? error.message : String(error), contract: node.entry.contract });
+                nodes.set(objectId, { type: "disease", objectId, boundary: "lifecycle", contract: node.entry.contract, ledgerParents: [...node.ledgerParents], evidenceParent: null });
+            }
+        }
+        if (node.type === "transaction") {
+            const diseasedMembers = node.entryObjectIds
+                .map((entryObjectId) => nodes.get(entryObjectId))
+                .filter((entryNode) => entryNode?.type === "disease");
+            if (diseasedMembers.length > 0) {
+                const contracts = new Set(diseasedMembers.flatMap((member) => member.contract === undefined ? [] : [member.contract]));
+                const evidenceDiseaseOnly = node.entryObjectIds.every((entryObjectId) => diseases.some((disease) => disease.objectId === entryObjectId &&
+                    (disease.code === "invalid-evidence" || disease.code === "unreadable-evidence")));
+                if (!evidenceDiseaseOnly) {
+                    diseases.push({
+                        objectId,
+                        code: "invalid-transaction-boundary",
+                        detail: "transaction contains a diseased lifecycle member",
+                        ...(contracts.size === 1 ? { contract: [...contracts][0] } : {}),
+                    });
+                }
+                nodes.set(objectId, {
+                    type: "disease",
+                    objectId,
+                    boundary: "transaction",
+                    ...(contracts.size === 1 ? { contract: [...contracts][0] } : {}),
+                    ledgerParents: [...node.ledgerParents],
+                    evidenceParent: null,
+                });
+            }
+            else {
+                const detail = transactionBoundaryError(node, nodes, acceptedEntryIntroductions);
+                if (detail) {
+                    diseases.push({ objectId, code: "invalid-transaction-boundary", detail });
+                    nodes.set(objectId, { type: "disease", objectId, boundary: "transaction", ledgerParents: [...node.ledgerParents], evidenceParent: null });
+                }
+                else {
+                    for (const entryObjectId of node.entryObjectIds)
+                        acceptedEntryIntroductions.set(entryObjectId, node.objectId);
+                }
+            }
+        }
+        order.push(objectId);
+        visiting.delete(objectId);
+        visited.add(objectId);
+    };
+    try {
+        await visit(head);
+        const headNode = nodes.get(head);
+        if (headNode?.type === "lifecycle") {
+            diseases.push({ objectId: head, code: "invalid-transaction-boundary", detail: "repository ledger head is a lifecycle entry rather than a transaction or join" });
+            nodes.set(head, { type: "disease", objectId: head, boundary: "lifecycle", contract: headNode.entry.contract, ledgerParents: [...headNode.ledgerParents], evidenceParent: null });
+        }
+        return { head, coordinates, nodes, order, diseases };
+    }
+    finally {
+        await reader.close();
+    }
+}
+export function isTypedLedgerAncestor(ledger, ancestor, descendant) {
+    if (ancestor === descendant)
+        return true;
+    const pending = [descendant];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const objectId = pending.pop();
+        if (seen.has(objectId))
+            continue;
+        seen.add(objectId);
+        const node = ledger.nodes.get(objectId);
+        if (!node)
+            continue;
+        for (const parent of ledgerTopologyParents(node)) {
+            if (parent === ancestor)
+                return true;
+            pending.push(parent);
+        }
+    }
+    return false;
+}
+export function isLifecycleCausalAncestor(ledger, ancestor, descendant) {
+    if (ancestor === descendant)
+        return true;
+    let current = ledger.nodes.get(descendant);
+    const seen = new Set();
+    while (current?.type === "lifecycle" && current.ledgerParents.length === 1) {
+        const parent = current.ledgerParents[0];
+        if (parent === ancestor)
+            return true;
+        if (seen.has(parent))
+            return false;
+        seen.add(parent);
+        current = ledger.nodes.get(parent);
+    }
+    return false;
+}