@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/repository-ledger/read-model.js

@@ -0,0 +1,469 @@
+import { openTaskAdmissionEvidenceReader, readTaskAdmissionEvidenceAtCommit, } from "../task/settlement-git.js";
+import { repositoryDeliveryRef, } from "./codec.js";
+import { observeRepositoryLedgerHead, readAcceptedRepositoryFold } from "./accepted-fold-read.js";
+import { advanceRepositoryCurrentState, discardRepositoryCurrentState, publishRepositoryCurrentState, readPinnedCurrentContract, readPinnedRepositoryLifecycle, readRepositoryCurrentStateNodeIds, readRepositoryCurrentStatePin } from "./current-state-store.js";
+import { IncrementalLedgerValidationError, readIncrementalRepositorySegment } from "./incremental-read.js";
+import { RepositoryObjectError } from "./git-object-store.js";
+/** Public lifecycle state derived only from the accepted repository-ledger fold. */
+export function currentLifecycleState(model) {
+    switch (model.phase) {
+        case "active":
+            return model.history.every(({ entry }) => entry.kind === "bind" || entry.kind === "bootstrap")
+                ? { state: "bound" }
+                : { state: "active" };
+        case "sealed":
+            return { state: "active" };
+        case "awaiting-verdict":
+        case "approved":
+            return { state: "petitioned" };
+        case "claimed":
+            return { state: "claimed" };
+        case "forfeited":
+            return { state: "forfeited" };
+    }
+}
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}
+function acceptedHistory(state, nodes) {
+    return state.entryObjectIds.map((objectId) => {
+        const node = nodes.get(objectId);
+        if (node?.type !== "lifecycle") {
+            throw new Error(`accepted lifecycle entry ${objectId} is absent from typed traversal`);
+        }
+        return { objectId, entry: structuredClone(node.entry) };
+    });
+}
+function findLastRow(history, kind) {
+    for (let index = history.length - 1; index >= 0; index -= 1) {
+        const row = history[index];
+        if (row.entry.kind === kind) {
+            return row;
+        }
+    }
+    return undefined;
+}
+function unavailableHistoryFact(reason) {
+    return { retention: "unavailable", reason };
+}
+/**
+ * Projects only accepted lifecycle rows into the retained consequences history
+ * may expose. Review responses are not lifecycle records, so they remain
+ * explicitly unavailable here rather than being reconstructed from artifacts.
+ */
+export function unavailableContractHistoryConsequences(reason) {
+    const unavailable = unavailableHistoryFact(reason);
+    return deepFreeze({
+        retention: "unavailable",
+        reason,
+        review: unavailable,
+        petition: unavailable,
+        verdict: unavailable,
+        claim: unavailable,
+        landedCommit: unavailable,
+    });
+}
+export function historyConsequencesForContract(outcome) {
+    if (outcome.status === "absent")
+        return unavailableContractHistoryConsequences("contract-absent");
+    if (outcome.status === "diseased")
+        return unavailableContractHistoryConsequences("lifecycle-diseased");
+    if (outcome.status === "isolated")
+        return unavailableContractHistoryConsequences("lifecycle-isolated");
+    if (outcome.status === "indeterminate")
+        return unavailableContractHistoryConsequences("lifecycle-indeterminate");
+    return historyConsequencesForAcceptedHistory(outcome.model.history);
+}
+function historyConsequencesForAcceptedHistory(history) {
+    const petition = findLastRow(history, "petition");
+    const verdict = findLastRow(history, "verdict");
+    const claim = findLastRow(history, "claim");
+    const missing = unavailableHistoryFact("not-recorded");
+    const review = unavailableHistoryFact("not-retained-in-lifecycle");
+    const retainedClaim = claim
+        ? {
+            retention: "retained",
+            objectId: claim.objectId,
+            target: claim.entry.data.target,
+            base: claim.entry.data.base,
+            targetHead: claim.entry.data.targetHead,
+            deliveryHead: claim.entry.data.deliveryHead,
+            mergeCommit: claim.entry.data.mergeCommit,
+        }
+        : missing;
+    return deepFreeze({
+        retention: "retained",
+        review,
+        petition: petition
+            ? {
+                retention: "retained",
+                objectId: petition.objectId,
+                intent: petition.entry.data.intent,
+                target: petition.entry.data.target,
+                targetHead: petition.entry.data.intent === "claim" ? petition.entry.data.targetHead : null,
+                seat: petition.entry.data.seat,
+            }
+            : missing,
+        verdict: verdict
+            ? {
+                retention: "retained",
+                objectId: verdict.objectId,
+                result: verdict.entry.data.result,
+                summary: verdict.entry.data.summary,
+            }
+            : missing,
+        claim: retainedClaim,
+        landedCommit: claim
+            ? { retention: "retained", commit: claim.entry.data.mergeCommit }
+            : missing,
+    });
+}
+function currentIntent(state, history) {
+    const explicit = findLastRow(history, "arc");
+    if (explicit) {
+        return {
+            arc: explicit.entry.data.arc,
+            openedBy: explicit.objectId,
+            title: explicit.entry.data.title,
+            objective: explicit.entry.data.objective,
+            brief: explicit.entry.data.brief,
+        };
+    }
+    return {
+        arc: 0,
+        openedBy: state.entryObjectIds[0],
+        title: state.bind.data.title,
+        objective: state.bind.data.objective,
+        brief: null,
+    };
+}
+function petitionState(state, history) {
+    // Terminal rows retain petition/verdict history, but no longer represent a live petition.
+    if (state.terminalObjectId !== null)
+        return { state: "none" };
+    if (!state.petition)
+        return { state: "none" };
+    const petition = findLastRow(history, "petition");
+    if (!petition)
+        throw new Error(`folded petition for ${state.contract} is absent from accepted history`);
+    const data = state.petition.data;
+    const common = {
+        objectId: petition.objectId,
+        intent: data.intent,
+        seat: data.seat,
+        target: data.target,
+        targetHead: data.intent === "claim" ? data.targetHead : null,
+    };
+    if (state.phase !== "approved" || !state.verdict)
+        return { state: "awaiting-verdict", ...common };
+    const verdict = state.verdict ? findLastRow(history, "verdict") : undefined;
+    if (!verdict) {
+        throw new Error(`folded verdict for ${state.contract} is absent from accepted history`);
+    }
+    return {
+        state: "approved",
+        ...common,
+        verdictObjectId: verdict.objectId,
+        summary: state.verdict.data.summary,
+    };
+}
+function bootstrapReplay(state) {
+    const plan = state.bind.data.workspace === "worktree" ? state.bind.data.bootstrap : undefined;
+    if (!plan)
+        return { state: "not-planned" };
+    const immutablePlan = { command: [...plan.command], timeoutMs: plan.timeoutMs };
+    if (!state.bootstrap)
+        return { state: "pending", plan: immutablePlan };
+    const observed = {
+        plan: immutablePlan,
+        objectId: state.bootstrap.objectId,
+        result: structuredClone(state.bootstrap.result),
+    };
+    if (!state.bootstrap.failed)
+        return { state: "succeeded", ...observed };
+    if (state.bootstrapFailure === "awaiting-forfeit") {
+        return { state: "failed-awaiting-forfeit", ...observed };
+    }
+    if (state.bootstrapFailure === "interrupted") {
+        return { state: "failed-interrupted", ...observed };
+    }
+    if (state.terminal?.kind === "forfeit" &&
+        state.terminal.data.reason === "bind-failed" &&
+        state.terminalObjectId !== null) {
+        return { state: "failed-reconciled", ...observed, forfeitObjectId: state.terminalObjectId };
+    }
+    throw new Error(`failed bootstrap for ${state.contract} has no folded replay disposition`);
+}
+function lifecycleModel(observedLedgerHead, state, nodes, taskAdmissionEvidence) {
+    const history = acceptedHistory(state, nodes);
+    const verdict = findLastRow(history, "verdict");
+    const released = state.terminalObjectId !== null;
+    const taskReleased = state.terminal?.kind === "forfeit";
+    const selectedTasks = [...(state.bind.data.taskIds ?? [])];
+    return deepFreeze({
+        observedLedgerHead,
+        contract: state.contract,
+        phase: state.phase,
+        intent: currentIntent(state, history),
+        receiptSegments: structuredClone(state.segments),
+        seal: structuredClone(state.segments.at(-1)?.seal ?? null),
+        bootstrapReplay: bootstrapReplay(state),
+        petition: petitionState(state, history),
+        verdict: verdict
+            ? { objectId: verdict.objectId, result: verdict.entry.data.result, summary: verdict.entry.data.summary }
+            : null,
+        pins: {
+            base: state.base,
+            delivery: state.deliveryHead,
+            target: { ref: state.target, approvedHead: state.approvedTargetSnapshot?.targetHead ?? null },
+        },
+        effectiveScope: [...state.effectiveScope],
+        causal: {
+            after: [...(state.bind.data.after ?? [])],
+            needs: structuredClone(taskAdmissionEvidence),
+        },
+        resources: {
+            deliveryRef: repositoryDeliveryRef(state.contract),
+            worktree: state.bind.data.workspace === "worktree"
+                ? { place: state.bind.data.place, state: released ? "released" : "held" }
+                : null,
+            tasks: selectedTasks.map((taskId) => ({ taskId, state: taskReleased ? "released" : "held" })),
+        },
+        history,
+    });
+}
+async function materializeIncrementalContract(cwd, observedLedgerHead, state, history) {
+    const nodes = new Map();
+    for (const row of history) {
+        nodes.set(row.objectId, {
+            type: "lifecycle",
+            objectId: row.objectId,
+            entry: structuredClone(row.entry),
+            ledgerParents: [],
+            evidenceParent: null,
+        });
+    }
+    let evidence = null;
+    const selectedTaskIds = state.bind.data.taskIds ?? [];
+    if (selectedTaskIds.length > 0) {
+        evidence = await readTaskAdmissionEvidenceAtCommit({
+            cwd,
+            bindObjectId: state.entryObjectIds[0],
+            base: state.bind.data.base,
+            contract: state.contract,
+            selectedTaskIds,
+        });
+        if (evidence.bindObjectId !== state.entryObjectIds[0]
+            || evidence.base !== state.bind.data.base
+            || evidence.selected.length !== selectedTaskIds.length
+            || evidence.selected.some((candidate, index) => candidate.taskId !== selectedTaskIds[index]))
+            throw new Error("task admission evidence does not match incremental bind state");
+    }
+    return lifecycleModel(observedLedgerHead, state, nodes, evidence);
+}
+async function recoverRepositoryLifecycle(cwd, options = {}) {
+    const accepted = await readAcceptedRepositoryFold(cwd, { observeHead: options.observeHead, signal: options.signal });
+    if (accepted.observedLedgerHead === null) {
+        options.captureFold?.({ contracts: new Map(), isolatedContracts: new Set(), diseases: [] });
+        return deepFreeze({
+            observedLedgerHead: null,
+            objectFormat: null,
+            emptyTree: null,
+            contracts: [],
+            isolatedContracts: [],
+            diagnostics: [],
+            topology: { head: null, nodes: [] },
+        });
+    }
+    const { observedLedgerHead, traversed, folded } = accepted;
+    options.captureFold?.(folded);
+    const diagnostics = [...folded.diseases];
+    const isolatedContracts = new Set(folded.isolatedContracts);
+    const contracts = [];
+    const states = [...folded.contracts.values()].sort((left, right) => left.contract.localeCompare(right.contract));
+    const taskReader = options.readTaskAdmissionEvidence === undefined
+        && states.some((state) => (state.bind.data.taskIds?.length ?? 0) > 0)
+        ? openTaskAdmissionEvidenceReader(cwd)
+        : null;
+    const readTaskEvidence = options.readTaskAdmissionEvidence
+        ?? taskReader?.read
+        ?? readTaskAdmissionEvidenceAtCommit;
+    try {
+        for (const state of states) {
+            const selectedTaskIds = state.bind.data.taskIds ?? [];
+            let taskAdmissionEvidence = null;
+            if (selectedTaskIds.length > 0) {
+                try {
+                    taskAdmissionEvidence = await readTaskEvidence({
+                        cwd,
+                        bindObjectId: state.entryObjectIds[0],
+                        base: state.bind.data.base,
+                        contract: state.contract,
+                        selectedTaskIds,
+                    });
+                    const evidenceIds = taskAdmissionEvidence.selected.map((candidate) => candidate.taskId);
+                    if (taskAdmissionEvidence.bindObjectId !== state.entryObjectIds[0] ||
+                        taskAdmissionEvidence.base !== state.bind.data.base ||
+                        evidenceIds.length !== selectedTaskIds.length ||
+                        evidenceIds.some((taskId, index) => taskId !== selectedTaskIds[index])) {
+                        throw new Error("task admission evidence does not match bind identity, base, and selected task order");
+                    }
+                }
+                catch (error) {
+                    isolatedContracts.add(state.contract);
+                    diagnostics.push({
+                        objectId: state.entryObjectIds[0],
+                        code: "task-admission-evidence",
+                        contract: state.contract,
+                        detail: error instanceof Error ? error.message : String(error),
+                    });
+                    continue;
+                }
+            }
+            contracts.push(lifecycleModel(observedLedgerHead, state, traversed.nodes, taskAdmissionEvidence));
+        }
+    }
+    finally {
+        await taskReader?.close();
+    }
+    const topologyNodes = [...traversed.nodes.values()].map((node) => {
+        if (node.type === "transaction") {
+            return {
+                objectId: node.objectId,
+                type: node.type,
+                ledgerParents: [...node.ledgerParents],
+                verb: node.transaction.verb,
+                contract: node.contract,
+                entryObjectIds: [...node.entryObjectIds],
+                finalEntryObjectId: node.finalEntryObjectId,
+            };
+        }
+        return { objectId: node.objectId, type: node.type, ledgerParents: [...node.ledgerParents] };
+    });
+    return deepFreeze({
+        observedLedgerHead,
+        objectFormat: traversed.coordinates.objectFormat,
+        emptyTree: traversed.coordinates.emptyTree,
+        contracts,
+        isolatedContracts: [...isolatedContracts].sort(),
+        diagnostics: structuredClone(diagnostics),
+        topology: {
+            head: observedLedgerHead,
+            nodes: topologyNodes,
+        },
+    });
+}
+export async function readRepositoryLifecycle(cwd, options = {}) {
+    const observe = options.observeHead ?? observeRepositoryLedgerHead;
+    const observedHead = await observe(cwd);
+    const injected = options.observeHead !== undefined || options.readTaskAdmissionEvidence !== undefined;
+    if (!injected) {
+        const pinned = await readPinnedRepositoryLifecycle(cwd, observedHead, options.signal, { includeTopology: options.includeTopology });
+        if (pinned)
+            return deepFreeze(pinned);
+        const priorHead = await readRepositoryCurrentStatePin(cwd, options.signal);
+        if (priorHead && observedHead && priorHead !== observedHead) {
+            try {
+                const acceptedObjectIds = await readRepositoryCurrentStateNodeIds(cwd, priorHead, options.signal);
+                const segment = await readIncrementalRepositorySegment(cwd, priorHead, observedHead, options.signal, acceptedObjectIds ?? undefined);
+                if (segment && await advanceRepositoryCurrentState(cwd, priorHead, observedHead, segment, {
+                    signal: options.signal,
+                    confirmHead: () => observeRepositoryLedgerHead(cwd),
+                    materialize: (state, history) => materializeIncrementalContract(cwd, observedHead, state, history),
+                })) {
+                    const advanced = await readPinnedRepositoryLifecycle(cwd, observedHead, options.signal, { includeTopology: options.includeTopology });
+                    if (advanced)
+                        return deepFreeze(advanced);
+                }
+                const concurrentlyAdvanced = await readPinnedRepositoryLifecycle(cwd, observedHead, options.signal, { includeTopology: options.includeTopology });
+                if (concurrentlyAdvanced)
+                    return deepFreeze(concurrentlyAdvanced);
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === "AbortError")
+                    throw error;
+                const untrustedDelta = error instanceof IncrementalLedgerValidationError
+                    || (error instanceof RepositoryObjectError && error.reason !== "git-failure");
+                if (!untrustedDelta)
+                    throw error;
+                await discardRepositoryCurrentState(cwd, options.signal);
+            }
+        }
+    }
+    let recoveredFold;
+    const recovered = await recoverRepositoryLifecycle(cwd, {
+        ...options,
+        observeHead: async () => observedHead,
+        captureFold: (fold) => { recoveredFold = fold; },
+    });
+    if (!injected) {
+        const published = await publishRepositoryCurrentState(cwd, recovered, {
+            signal: options.signal,
+            confirmHead: () => observeRepositoryLedgerHead(cwd),
+            fold: recoveredFold,
+        });
+        if (!published)
+            return readRepositoryLifecycle(cwd, options);
+    }
+    return recovered;
+}
+/** Current repository summaries for status-like consumers; retained lifecycle history is not materialized. */
+export async function readRepositoryLifecycleSummaries(cwd, options = {}) {
+    const observedHead = await observeRepositoryLedgerHead(cwd);
+    const pinned = await readPinnedRepositoryLifecycle(cwd, observedHead, options.signal, {
+        includeTopology: false,
+        summaryOnly: true,
+    });
+    if (pinned)
+        return deepFreeze(pinned);
+    await readRepositoryLifecycle(cwd, { signal: options.signal });
+    const rebuilt = await readPinnedRepositoryLifecycle(cwd, observedHead, options.signal, {
+        includeTopology: false,
+        summaryOnly: true,
+    });
+    if (!rebuilt)
+        return readRepositoryLifecycleSummaries(cwd, options);
+    return deepFreeze(rebuilt);
+}
+export async function readCurrentContractLifecycle(cwd, contract, options = {}) {
+    const observe = options.observeHead ?? observeRepositoryLedgerHead;
+    const observedHead = await observe(cwd);
+    const injected = options.observeHead !== undefined || options.readTaskAdmissionEvidence !== undefined;
+    if (!injected) {
+        const pinned = await readPinnedCurrentContract(cwd, observedHead, contract, options.signal);
+        if (pinned)
+            return deepFreeze(pinned);
+    }
+    const repository = await readRepositoryLifecycle(cwd, {
+        ...options,
+        includeTopology: false,
+        observeHead: injected ? async () => observedHead : undefined,
+    });
+    if (!injected) {
+        const targeted = await readPinnedCurrentContract(cwd, repository.observedLedgerHead, contract, options.signal);
+        if (targeted)
+            return deepFreeze(targeted);
+    }
+    return lookupCurrentContract(repository, contract);
+}
+export function lookupCurrentContract(read, contract) {
+    const diagnostics = read.diagnostics.filter((disease) => disease.contract === contract);
+    if (read.isolatedContracts.includes(contract)) {
+        return deepFreeze({ status: "isolated", contract, diagnostics: [...diagnostics] });
+    }
+    const model = read.contracts.find((candidate) => candidate.contract === contract);
+    if (!model) {
+        const unattributed = read.diagnostics.filter((disease) => disease.contract === undefined);
+        return unattributed.length > 0
+            ? deepFreeze({ status: "indeterminate", contract, diagnostics: [...unattributed] })
+            : deepFreeze({ status: "absent", contract, diagnostics: [] });
+    }
+    if (diagnostics.length > 0)
+        return deepFreeze({ status: "diseased", model, diagnostics: [...diagnostics] });
+    return deepFreeze({ status: "healthy", model, diagnostics: [] });
+}

package/build/core/repository-ledger/transaction-membership.js

@@ -0,0 +1,78 @@
+function invalid(verb, entries) {
+    const kinds = entries.map((entry) => entry.kind).join(",");
+    return { status: "invalid", detail: `${verb} transaction has unlawful entry grammar ${kinds || "empty"}` };
+}
+function validateContractContinuity(verb, entries) {
+    const contract = entries.at(-1)?.contract;
+    if (contract !== undefined && entries.some((entry) => entry.contract !== contract)) {
+        return { status: "invalid", detail: `${verb} transaction crosses contract identities` };
+    }
+    return null;
+}
+function isSealFor(entry, verb) {
+    return entry?.kind === "seal" && entry.data.sealedBy === verb;
+}
+/** Parse the one current, closed, verb-bound transaction membership grammar. */
+export function validateTransactionMembership(verb, entries) {
+    const continuity = validateContractContinuity(verb, entries);
+    if (continuity)
+        return continuity;
+    const [first, second, third] = entries;
+    if (verb === "bind" && entries.length === 1 && first?.kind === "bind")
+        return { status: "valid", membership: { verb, entries: [first] } };
+    if (verb === "bootstrap" && entries.length === 1 && first?.kind === "bootstrap")
+        return { status: "valid", membership: { verb, entries: [first] } };
+    if (verb === "amend" && entries.length === 1 && first?.kind === "amend")
+        return { status: "valid", membership: { verb, entries: [first] } };
+    if (verb === "seal" && entries.length === 1 && first?.kind === "seal")
+        return { status: "valid", membership: { verb, entries: [first] } };
+    if (verb === "verdict" && entries.length === 1 && first?.kind === "verdict")
+        return { status: "valid", membership: { verb, entries: [first] } };
+    if (verb === "claim" && entries.length === 1 && first?.kind === "claim")
+        return { status: "valid", membership: { verb, entries: [first] } };
+    if (verb === "forfeit" && entries.length === 1 && first?.kind === "forfeit")
+        return { status: "valid", membership: { verb, entries: [first] } };
+    if (verb === "arc") {
+        if (entries.length === 1 && first?.kind === "arc")
+            return { status: "valid", membership: { verb, entries: [first] } };
+        if (entries.length === 2 && isSealFor(first, "arc") && second?.kind === "arc") {
+            return { status: "valid", membership: { verb, entries: [first, second] } };
+        }
+        if (entries.length === 2 && first?.kind === "amend" && second?.kind === "arc") {
+            return { status: "valid", membership: { verb, entries: [first, second] } };
+        }
+        if (entries.length === 3 && first?.kind === "amend" && isSealFor(second, "arc") && third?.kind === "arc") {
+            return { status: "valid", membership: { verb, entries: [first, second, third] } };
+        }
+    }
+    if (verb === "petition") {
+        if (entries.length === 1 && first?.kind === "petition")
+            return { status: "valid", membership: { verb, entries: [first] } };
+        if (entries.length === 2 && isSealFor(first, "petition") && second?.kind === "petition") {
+            return { status: "valid", membership: { verb, entries: [first, second] } };
+        }
+        if (entries.length === 2 && first?.kind === "amend" && second?.kind === "petition") {
+            return { status: "valid", membership: { verb, entries: [first, second] } };
+        }
+        if (entries.length === 3 && first?.kind === "amend" && isSealFor(second, "petition") && third?.kind === "petition") {
+            return { status: "valid", membership: { verb, entries: [first, second, third] } };
+        }
+    }
+    if (verb === "renew") {
+        if (entries.length === 1 && first?.kind === "amend")
+            return { status: "valid", membership: { verb, entries: [first] } };
+        if (entries.length === 1 && first?.kind === "renew")
+            return { status: "valid", membership: { verb, entries: [first] } };
+        if (entries.length === 2 && isSealFor(first, "renew") && second?.kind === "renew") {
+            return { status: "valid", membership: { verb, entries: [first, second] } };
+        }
+        if (entries.length === 3 && first?.kind === "amend" && isSealFor(second, "renew") && third?.kind === "renew") {
+            return { status: "valid", membership: { verb, entries: [first, second, third] } };
+        }
+    }
+    return invalid(verb, entries);
+}
+export function transactionMembershipError(verb, entries) {
+    const validation = validateTransactionMembership(verb, entries);
+    return validation.status === "valid" ? null : validation.detail;
+}