@astrosheep/keiyaku 2.9.12 → 4.0.0

package/build/src/protocol/operations.d.ts

@@ -0,0 +1,140 @@
+import { type DeliveryPreparationRefusal, type ReviewPreparationRefusal } from "../git/delivery.js";
+import { type ReconcileResult } from "../git/reconcile.js";
+import type { WorktreeHooks } from "../git/hooks.js";
+import { NoGitWorldError, type GitRepository } from "../git/repository.js";
+import type { WorktreeLeak } from "../git/verification.js";
+import type { ActorId, AmendData, ArcData, AttestationData, ChangeId, ContractId, ContractState, ContractTerms, DocumentKey, SnapshotId } from "../core/facts/types.js";
+import { type AbandonRefusal } from "../core/verbs/abandon.js";
+import { type AmendRefusal } from "../core/verbs/amend.js";
+import { type ArcRefusal } from "../core/verbs/arc.js";
+import { type DeliverRefusal } from "../core/verbs/deliver.js";
+import type { PlacementRefusal } from "../core/verbs/placement.js";
+import { type AttestationRefusal } from "../core/verbs/attestation.js";
+import type { VerificationDeclarationPreparation, VerificationDeclarationRefusal } from "../verification/declaration.js";
+import { type VerificationRuntimeStop } from "./intent.js";
+import { type AuditReport as AuditReadReport } from "./read/audit.js";
+import { type ContractDocumentProjection } from "./read/documents.js";
+import { type ContractBoard, type ContractDisposition, type ContractGateCurrent, type ContractGateReport, type ContractObservation, type ContractPhase, type ContractRow } from "./read/status.js";
+export { bindOperation } from "./bind.js";
+import type { BindRefusal, TargetInputRefusal } from "./bind.js";
+import { type IntentOutcome as ProtocolIntentOutcome } from "./outcome.js";
+import type { ProtocolTerminal } from "./run.js";
+import type { CompanionDecorator } from "./run.js";
+export type { FactKind, TimelineEntry } from "./read/audit.js";
+export type { ContractDocumentProjection } from "./read/documents.js";
+type ReviewRefusal = AttestationRefusal | ReviewPreparationRefusal;
+export type IntentRefusal = AbandonRefusal | AmendRefusal | ArcRefusal | BindRefusal | DeliverRefusal | DeliveryPreparationRefusal | PlacementRefusal | ReviewRefusal | TargetInputRefusal | VerificationDeclarationRefusal;
+export type { TargetInputRefusal } from "./bind.js";
+export type IntentRetry = ProtocolTerminal;
+export type IntentOutcome<Value, Refusal = IntentRefusal> = ProtocolIntentOutcome<Value, Refusal>;
+type OperationInput = Readonly<{
+    scope: RepositoryScope;
+    contractId: ContractId;
+    actor?: ActorId;
+}>;
+export type AuditReport = AuditReadReport & Readonly<{
+    attempt?: VerificationStop;
+    leak?: WorktreeLeak;
+}>;
+export type DocumentDerivation = Readonly<{
+    document: DocumentKey;
+    title: string;
+    verification: VerificationDeclarationPreparation;
+}>;
+export type StepStop<R> = Readonly<{
+    refusal: R;
+    retry?: never;
+} | {
+    retry: IntentRetry;
+    refusal?: never;
+}>;
+export type VerificationStop = StepStop<AttestationRefusal> | VerificationRuntimeStop;
+export type PlacementStop = StepStop<PlacementRefusal>;
+type ScopeOperationInput = Readonly<{
+    coordinate: string;
+}>;
+export type RepositoryScope = GitRepository;
+export { NoGitWorldError };
+export declare function scopeOperation(input: ScopeOperationInput): RepositoryScope;
+export declare function currentBranchOperation(input: Readonly<{
+    scope: RepositoryScope;
+}>): string | null;
+export declare function contractsOperation(input: Readonly<{
+    scope: RepositoryScope;
+}>): ContractBoard;
+export declare function contractObservationOperation(input: OperationInput): ContractObservation;
+export type { ContractBoard, ContractDisposition, ContractGateCurrent, ContractGateReport, ContractObservation, ContractPhase, ContractRow };
+export declare function documentsOperation(input: Readonly<{
+    scope: RepositoryScope;
+}>): readonly ContractDocumentProjection[];
+export declare function stateOperation(input: OperationInput): ContractState;
+export declare function readStateOperation(input: OperationInput): ContractState | null;
+type DeliveryIdentity = Readonly<{
+    snapshotId: SnapshotId;
+    changeId: ChangeId;
+    expectedPredecessor: SnapshotId;
+}>;
+export declare function deliveryOperation(input: OperationInput): DeliveryIdentity | null;
+type DeliveryDiffOperationInput = Readonly<{
+    scope: RepositoryScope;
+    expectedPredecessor: SnapshotId;
+    snapshotId: SnapshotId;
+}>;
+export declare function deliveryDiffOperation(input: DeliveryDiffOperationInput): Promise<string | null>;
+type AmendOperationInput = OperationInput & Readonly<{
+    amendment?: Readonly<{
+        source: ContractTerms;
+        terms: AmendData;
+        verification: VerificationDeclarationPreparation;
+    }>;
+}>;
+export declare function amendOperation(input: AmendOperationInput): IntentOutcome<void, AmendRefusal | VerificationDeclarationRefusal>;
+export type DeliverValue = DeliveryIdentity & Readonly<{
+    verification?: VerificationStop;
+    placement?: PlacementStop;
+    leak?: WorktreeLeak;
+}>;
+type DeliverOperationInput = OperationInput & Readonly<{
+    derivation?: DocumentDerivation;
+    message?: string;
+}>;
+export declare function deliverOperation(input: DeliverOperationInput): Promise<IntentOutcome<DeliverValue>>;
+export declare function abandonOperation(input: OperationInput & Readonly<{
+    note?: string;
+    decorateOffer?: CompanionDecorator;
+}>): IntentOutcome<void, AbandonRefusal>;
+export declare function arcOperation(input: OperationInput & Readonly<{
+    chapter: Omit<ArcData, "seq">;
+}>): IntentOutcome<void, ArcRefusal>;
+type ReviewOperationInput = OperationInput & Readonly<{
+    verdict: AttestationData["verdict"];
+    summary?: string;
+}>;
+export type ReviewValue = Readonly<{
+    placement?: PlacementStop;
+}>;
+export declare function reviewOperation(input: ReviewOperationInput): IntentOutcome<ReviewValue, ReviewRefusal>;
+export declare function auditOperation(input: OperationInput & Readonly<{
+    derivation?: DocumentDerivation;
+}>): Promise<IntentOutcome<AuditReport>>;
+export type ReconcileReport = ReconcileResult;
+export type ReconcileObservation = Readonly<{
+    state: ContractState | null;
+    report: ReconcileReport;
+}>;
+type ReconcileOptions = Readonly<{
+    hooks: WorktreeHooks;
+    retryHooks: boolean;
+}>;
+export declare function reconcileOperation(input: OperationInput & ReconcileOptions): Promise<ReconcileObservation>;
+type RepoReconcileItem = Readonly<{
+    contractId: ContractId;
+    state: ContractState | null;
+    report: ReconcileReport;
+}>;
+export type RepoReconcileReport = Readonly<{
+    contracts: readonly RepoReconcileItem[];
+}>;
+export declare function reconcileAllOperation(input: Readonly<{
+    scope: RepositoryScope;
+}> & ReconcileOptions): Promise<RepoReconcileReport>;

package/build/src/protocol/operations.js

@@ -0,0 +1,373 @@
+import { prepareDelivery, prepareReview, } from "../git/delivery.js";
+import { currentBranch, extendContractsForAdmission, observeGit, observeContract, observeContractsForAdmission, } from "../git/observe.js";
+import { reconcile, reconcileBatch, reconcileObservationFailure } from "../git/reconcile.js";
+import { NoGitWorldError, repositoryAt } from "../git/repository.js";
+import { readDeliveryDiff } from "../git/verification.js";
+import { dependencyKeySet } from "../core/subject.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { contractState, documentIsCurrent } from "../core/facts/observation.js";
+import { gate } from "../core/facts/types.js";
+import { decideAbandon } from "../core/verbs/abandon.js";
+import { decideAmend } from "../core/verbs/amend.js";
+import { decideArc } from "../core/verbs/arc.js";
+import { decideDeliver } from "../core/verbs/deliver.js";
+import { decideAttestation } from "../core/verbs/attestation.js";
+import { produceVerification } from "../verification/producer.js";
+import { admitIntent, admitPlacement, mintAttempts, verifyDelivery } from "./intent.js";
+import { auditReport, readAudit } from "./read/audit.js";
+import { readDocuments } from "./read/documents.js";
+import { readContractBoard, readContractObservation, } from "./read/status.js";
+import { admitDecidedOffer } from "./attempt.js";
+export { bindOperation } from "./bind.js";
+import { accepted, admitted, complete } from "./outcome.js";
+const REVIEWED = gate("reviewed");
+function timestamp() { return new Date().toISOString(); }
+function mergeAdmissions(current, next) {
+    return { ...next, facts: [...current.facts, ...next.facts] };
+}
+function stepStop(result) {
+    if (result.kind === "accepted")
+        return undefined;
+    return result.kind === "refused" ? { refusal: result.refusal } : { retry: result };
+}
+export { NoGitWorldError };
+export function scopeOperation(input) { return repositoryAt(input.coordinate); }
+export function currentBranchOperation(input) {
+    return currentBranch(input.scope);
+}
+export function contractsOperation(input) { return readContractBoard(input.scope); }
+export function contractObservationOperation(input) {
+    return readContractObservation(input.scope, input.contractId);
+}
+export function documentsOperation(input) { return readDocuments(input.scope); }
+export function stateOperation(input) {
+    const state = observeContract(input.scope, input.contractId).state;
+    if (state === null)
+        throw new Error(`contract does not exist: ${input.contractId}`);
+    return state;
+}
+export function readStateOperation(input) { return observeContract(input.scope, input.contractId).state; }
+export function deliveryOperation(input) {
+    const state = observeContract(input.scope, input.contractId).state;
+    if (state === null || state.delivery === null)
+        return null;
+    return {
+        snapshotId: state.delivery.data.candidate,
+        changeId: state.delivery.data.deliveryPatchId,
+        expectedPredecessor: state.delivery.data.expectedPredecessor,
+    };
+}
+function observePrerequisiteClosure(repository, contracts) {
+    let observation = observeContractsForAdmission(repository, contracts);
+    let frontier = contracts.slice(1);
+    while (frontier.length > 0) {
+        const next = new Set();
+        for (const id of frontier) {
+            const state = contractState(observation.decision, id);
+            if (state === null)
+                continue;
+            for (const dependency of state.terms.after) {
+                if (!observation.decision.has(dependency))
+                    next.add(dependency);
+            }
+        }
+        frontier = [...next];
+        observation = extendContractsForAdmission(repository, observation, frontier);
+    }
+    return observation;
+}
+export async function deliveryDiffOperation(input) { return readDeliveryDiff(input.scope, input.expectedPredecessor, input.snapshotId); }
+export function amendOperation(input) {
+    const amendment = input.amendment;
+    const preparation = amendment === undefined
+        ? undefined
+        : amendment.verification.kind === "prepared"
+            ? { kind: "prepared", data: amendment.terms }
+            : { kind: "refused", refusal: amendment.verification.refusal };
+    const decisionInput = {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        ...(amendment === undefined ? {} : { source: amendment.source }),
+        ...(preparation === undefined ? {} : { preparation }),
+    };
+    return complete(admitIntent(input.scope, decisionInput, decideAmend, {
+        observedContracts: [input.contractId, ...(amendment?.terms.after ?? [])],
+        observe: observePrerequisiteClosure,
+    }), undefined);
+}
+function deliverAttempt(input, attempt) {
+    const decisionObservation = observeContractsForAdmission(input.scope, [input.contractId]);
+    const state = contractState(decisionObservation.decision, input.contractId);
+    let preparation;
+    if (state === null || input.derivation === undefined) {
+        preparation = { kind: "unavailable" };
+    }
+    else if (input.derivation.verification.kind === "refused") {
+        preparation = {
+            kind: "refused",
+            document: input.derivation.document,
+            refusal: input.derivation.verification.refusal,
+        };
+    }
+    else {
+        const prepared = prepareDelivery(input.scope, {
+            contractId: state.id,
+            coordinates: state.coordinates,
+        }, {
+            title: input.derivation.title,
+            ...(input.message === undefined ? {} : { message: input.message }),
+        });
+        preparation = prepared.kind === "refused"
+            ? { kind: "refused", document: input.derivation.document, refusal: prepared.refusal }
+            : { kind: "prepared", document: input.derivation.document, data: prepared.data };
+    }
+    const decisionInput = {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        preparation,
+    };
+    const decision = decideDeliver({ input: decisionInput, attempt, observation: decisionObservation.decision });
+    if (decision.kind === "refused")
+        return { kind: "refused", refusal: decision.refusal };
+    if (preparation.kind !== "prepared") {
+        throw new Error("offered delivery is missing its mechanical preparation");
+    }
+    const admitted = admitDecidedOffer(input.scope, decisionObservation, attempt, decision.offer, input.contractId);
+    if (admitted.kind === "accepted") {
+        return { ...admitted, value: {
+                snapshotId: preparation.data.candidate,
+                changeId: preparation.data.deliveryPatchId,
+                expectedPredecessor: preparation.data.expectedPredecessor,
+            } };
+    }
+    return admitted;
+}
+async function completeDelivery(input, first) {
+    if (input.derivation === undefined) {
+        throw new Error("accepted delivery is missing its document derivation");
+    }
+    const derivation = input.derivation;
+    if (derivation.verification.kind !== "prepared") {
+        throw new Error("accepted delivery is missing its Verification preparation");
+    }
+    let admission = first;
+    let verificationValue;
+    let leak;
+    const verification = await verifyDelivery({
+        repository: input.scope,
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        state: first.state,
+        environment: process.env,
+        produce: produceVerification,
+        ...(derivation.verification.data === null
+            ? {}
+            : { verification: derivation.verification.data }),
+    });
+    if (verification !== null) {
+        leak = verification.leak;
+        if ("failure" in verification.step)
+            verificationValue = verification.step;
+        else {
+            verificationValue = stepStop(verification.step);
+            if (verification.step.kind === "accepted")
+                admission = mergeAdmissions(admission, verification.step);
+        }
+    }
+    const placement = admitPlacement(input.scope, {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+    });
+    const placementValue = stepStop(placement);
+    if (placement.kind === "accepted")
+        admission = mergeAdmissions(admission, placement);
+    return admitted(admission, {
+        ...first.value,
+        ...(verificationValue === undefined ? {} : { verification: verificationValue }),
+        ...(placementValue === undefined ? {} : { placement: placementValue }),
+        ...(leak === undefined ? {} : { leak }),
+    });
+}
+export async function deliverOperation(input) {
+    const attempts = mintAttempts({ entryCount: 2 });
+    let first = null;
+    for (let index = 0; index < attempts.length; index += 1) {
+        const result = deliverAttempt(input, attempts[index]);
+        if (result.kind === "accepted") {
+            first = result;
+            break;
+        }
+        if (result.kind === "refused")
+            return result;
+        if (result.kind === "publication-failed")
+            return { kind: "retry", reason: result };
+        if (result.kind === "collision" && index + 1 === attempts.length)
+            return { kind: "retry", reason: result };
+        if (result.kind === "redecide")
+            continue;
+    }
+    if (first === null)
+        return { kind: "retry", reason: { kind: "exhausted" } };
+    return completeDelivery(input, first);
+}
+export function abandonOperation(input) {
+    return complete(admitIntent(input.scope, {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        ...(input.note === undefined ? {} : { note: input.note }),
+    }, decideAbandon, input.decorateOffer === undefined ? {} : { decorateOffer: input.decorateOffer }), undefined);
+}
+export function arcOperation(input) {
+    return complete(admitIntent(input.scope, {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        data: input.chapter,
+    }, decideArc), undefined);
+}
+function reviewAttempt(input, attempt) {
+    const decisionObservation = observeContractsForAdmission(input.scope, [input.contractId]);
+    const state = contractState(decisionObservation.decision, input.contractId);
+    let preparation;
+    if (state !== null) {
+        const prepared = prepareReview(input.scope, { contractId: state.id, coordinates: state.coordinates });
+        preparation = prepared.kind === "refused"
+            ? { kind: "refused", refusal: prepared.refusal }
+            : {
+                kind: "prepared",
+                data: {
+                    gate: REVIEWED,
+                    subject: dependencyKeySet([
+                        { kind: "document", value: state.terms.document.key },
+                        { kind: "change", value: prepared.data },
+                    ]),
+                    verdict: input.verdict,
+                    ...(input.summary === undefined ? {} : { summary: input.summary }),
+                },
+            };
+    }
+    const decisionInput = {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        ...(preparation === undefined ? {} : { preparation }),
+    };
+    const decision = decideAttestation({ input: decisionInput, attempt, observation: decisionObservation.decision });
+    if (decision.kind === "refused")
+        return { kind: "refused", refusal: decision.refusal };
+    const admitted = admitDecidedOffer(input.scope, decisionObservation, attempt, decision.offer, input.contractId);
+    if (admitted.kind === "accepted")
+        return { ...admitted, value: undefined };
+    return admitted;
+}
+export function reviewOperation(input) {
+    const git = input.scope;
+    const attempts = mintAttempts({ entryCount: 2 });
+    let review = null;
+    for (let index = 0; index < attempts.length; index += 1) {
+        const result = reviewAttempt(input, attempts[index]);
+        if (result.kind === "accepted" || result.kind === "refused") {
+            review = result;
+            break;
+        }
+        if (result.kind === "publication-failed")
+            return { kind: "retry", reason: result };
+        if (result.kind === "collision" && index + 1 === attempts.length)
+            return { kind: "retry", reason: result };
+    }
+    if (review === null)
+        return { kind: "retry", reason: { kind: "exhausted" } };
+    if (review.kind !== "accepted")
+        return review;
+    if (input.verdict !== "satisfied")
+        return admitted(review, {});
+    const placement = admitPlacement(git, {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+    });
+    const placementStop = stepStop(placement);
+    const admission = placement.kind === "accepted" ? mergeAdmissions(review, placement) : review;
+    return admitted(admission, placementStop === undefined ? {} : { placement: placementStop });
+}
+export async function auditOperation(input) {
+    const git = input.scope;
+    const initial = readAudit(git, input.contractId, REVIEWED);
+    if (initial.state === null)
+        return { kind: "refused", refusal: { kind: "contract-missing", contractId: input.contractId } };
+    const derivation = input.derivation;
+    if (derivation === undefined) {
+        return { kind: "refused", refusal: { kind: "document-moved", contractId: input.contractId } };
+    }
+    if (!documentIsCurrent(initial.state, derivation.document)) {
+        return { kind: "refused", refusal: { kind: "document-moved", contractId: input.contractId } };
+    }
+    if (derivation.verification.kind === "refused") {
+        return { kind: "refused", refusal: derivation.verification.refusal };
+    }
+    if (initial.state.delivery === null || derivation.verification.data === null) {
+        return accepted(initial.state, [], initial.report);
+    }
+    const verification = await verifyDelivery({
+        repository: git,
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: timestamp(),
+        state: initial.state,
+        environment: process.env,
+        produce: produceVerification,
+        verification: derivation.verification.data,
+    });
+    if (verification === null) {
+        throw new Error("audit verification preparation unexpectedly produced no attempt");
+    }
+    const attempt = "failure" in verification.step
+        ? verification.step
+        : verification.step.kind === "accepted"
+            ? undefined
+            : verification.step.kind === "refused"
+                ? { refusal: verification.step.refusal }
+                : { retry: verification.step };
+    const report = !("failure" in verification.step) && verification.step.kind === "accepted"
+        ? auditReport(verification.step.journal, REVIEWED)
+        : initial.report;
+    const value = {
+        ...report,
+        ...(attempt === undefined ? {} : { attempt }),
+        ...(verification.leak === undefined ? {} : { leak: verification.leak }),
+    };
+    return !("failure" in verification.step) && verification.step.kind === "accepted"
+        ? admitted(verification.step, value)
+        : accepted(initial.state, [], value);
+}
+export async function reconcileOperation(input) {
+    try {
+        const observation = await reconcile({
+            repository: input.scope,
+            contractId: input.contractId,
+            hooks: input.hooks,
+            retryHooks: input.retryHooks,
+        });
+        return { state: observation.state, report: observation.result };
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+            throw error;
+        return { state: null, report: reconcileObservationFailure(error) };
+    }
+}
+export async function reconcileAllOperation(input) {
+    const git = input.scope;
+    const observation = observeGit(git);
+    const contracts = (await reconcileBatch(git, observation.contracts.keys(), input.hooks, input.retryHooks)).map((item) => ({
+        contractId: item.contract,
+        state: item.state,
+        report: item.result,
+    }));
+    return { contracts };
+}

package/build/src/protocol/outcome.d.ts

@@ -0,0 +1,18 @@
+import type { ContractHead, ContractState, JournalEntry } from "../core/facts/types.js";
+import type { AcceptedAdmission } from "./attempt.js";
+import type { ProtocolResult, ProtocolTerminal } from "./run.js";
+export type IntentOutcome<Value, Refusal = never> = Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    head: ContractHead;
+    value: Value;
+}> | Readonly<{
+    kind: "refused";
+    refusal: Refusal;
+}> | Readonly<{
+    kind: "retry";
+    reason: ProtocolTerminal;
+}>;
+export declare function accepted<Value, Refusal = never>(state: ContractState, facts: readonly JournalEntry[], value: Value): IntentOutcome<Value, Refusal>;
+export declare function admitted<Value, Refusal = never>(admission: AcceptedAdmission, value: Value): IntentOutcome<Value, Refusal>;
+export declare function complete<Value, Refusal>(result: ProtocolResult<Refusal>, value: Value): IntentOutcome<Value, Refusal>;

package/build/src/protocol/outcome.js

@@ -0,0 +1,15 @@
+export function accepted(state, facts, value) {
+    if (state.head === null)
+        throw new Error("accepted contract is missing its journal head");
+    return { kind: "accepted", facts, head: state.head, value };
+}
+export function admitted(admission, value) {
+    return accepted(admission.state, admission.facts, value);
+}
+export function complete(result, value) {
+    if (result.kind === "refused")
+        return { kind: "refused", refusal: result.refusal };
+    if (result.kind !== "accepted")
+        return { kind: "retry", reason: result };
+    return admitted(result, value);
+}

package/build/src/protocol/read/audit.d.ts

@@ -0,0 +1,25 @@
+import type { GitRepository } from "../../git/repository.js";
+import type { ContractId, ContractState, FactKind, Gate, JournalEntry } from "../../core/facts/types.js";
+export type { FactKind } from "../../core/facts/types.js";
+export type TimelineEntry = Readonly<{
+    kind: FactKind;
+    at: string;
+    sincePrior: number | null;
+    attestation?: Readonly<{
+        gate: Gate;
+        verdict: "satisfied" | "unsatisfied";
+        summary?: string;
+    }>;
+}>;
+export type AuditReport = Readonly<{
+    reworks: number;
+    reviews: number;
+    timeline: readonly TimelineEntry[];
+}>;
+type AuditRead = Readonly<{
+    state: ContractState | null;
+    entries: readonly JournalEntry[];
+    report: AuditReport;
+}>;
+export declare function auditReport(entries: readonly JournalEntry[], reviewed: Gate): AuditReport;
+export declare function readAudit(repository: GitRepository, contract: ContractId, reviewed: Gate): AuditRead;

package/build/src/protocol/read/audit.js

@@ -0,0 +1,39 @@
+import { observeContract } from "../../git/observe.js";
+function elapsedSince(prior, current) {
+    if (prior === undefined)
+        return null;
+    const priorMs = Date.parse(prior);
+    const currentMs = Date.parse(current);
+    return currentMs - priorMs;
+}
+export function auditReport(entries, reviewed) {
+    let reworks = 0;
+    let reviews = 0;
+    const timeline = entries.map((entry, index) => {
+        if (entry.kind === "deliver")
+            reworks += 1;
+        if (entry.kind === "attestation" && entry.data.gate === reviewed)
+            reviews += 1;
+        return {
+            kind: entry.kind,
+            at: entry.at,
+            sincePrior: elapsedSince(entries[index - 1]?.at, entry.at),
+            ...(entry.kind === "attestation" ? {
+                attestation: {
+                    gate: entry.data.gate,
+                    verdict: entry.data.verdict,
+                    ...(entry.data.summary === undefined ? {} : { summary: entry.data.summary }),
+                },
+            } : {}),
+        };
+    });
+    return { reworks, reviews, timeline };
+}
+export function readAudit(repository, contract, reviewed) {
+    const observation = observeContract(repository, contract);
+    return {
+        state: observation.state,
+        entries: observation.entries,
+        report: auditReport(observation.entries, reviewed),
+    };
+}

package/build/src/protocol/read/documents.d.ts

@@ -0,0 +1,8 @@
+import type { GitRepository } from "../../git/repository.js";
+import type { ContractId } from "../../core/facts/types.js";
+export type ContractDocumentProjection = Readonly<{
+    contract: ContractId;
+    documentBytes: string;
+}>;
+/** Read every live contract document from one immutable Git snapshot. */
+export declare function readDocuments(repository: GitRepository): readonly ContractDocumentProjection[];

package/build/src/protocol/read/documents.js

@@ -0,0 +1,16 @@
+import { observeGit } from "../../git/observe.js";
+/** Read every live contract document from one immutable Git snapshot. */
+export function readDocuments(repository) {
+    const observed = observeGit(repository);
+    const documents = [];
+    for (const [contract, observation] of observed.contracts) {
+        const state = observation.state;
+        if (state === null || state.terminal !== null)
+            continue;
+        documents.push({
+            contract,
+            documentBytes: state.terms.document.bytes,
+        });
+    }
+    return documents;
+}

package/build/src/protocol/read/status.d.ts

@@ -0,0 +1,38 @@
+import type { GitRepository } from "../../git/repository.js";
+import { type GateCurrent } from "../../core/facts/gate.js";
+import type { ContractId, SnapshotId } from "../../core/facts/types.js";
+export type ContractPhase = "waiting" | "bound" | "pending-delivery" | "claimed" | "abandoned";
+export type ContractDisposition = "active" | "terminal";
+export type ContractGateCurrent = GateCurrent;
+export type ContractGateReport = Readonly<{
+    gate: string;
+    current: ContractGateCurrent;
+}>;
+export type ContractRow = Readonly<{
+    id: ContractId;
+    phase: ContractPhase;
+    disposition: ContractDisposition;
+    workspace: "worktree" | "here";
+    worktreePath: string | null;
+    target: string | null;
+    candidate: SnapshotId | null;
+    gates: Readonly<{
+        reports: readonly ContractGateReport[];
+        satisfied: boolean;
+    }>;
+}>;
+export type ContractBoard = Readonly<{
+    root: string;
+    rows: readonly ContractRow[];
+}>;
+export type ContractObservation = Readonly<{
+    kind: "missing";
+    id: ContractId;
+}> | Readonly<{
+    kind: "present";
+    row: ContractRow;
+}>;
+/** Build the Contract board from one immutable git observation. */
+export declare function readContractBoard(repository: GitRepository): ContractBoard;
+/** Observe one Contract without enumerating the Contract world. */
+export declare function readContractObservation(repository: GitRepository, id: ContractId): ContractObservation;