@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/markdown/types.d.ts

@@ -0,0 +1,118 @@
+export type SourceSpan = Readonly<{
+    start: number;
+    end: number;
+}>;
+interface FrontmatterMap {
+    readonly [key: string]: FrontmatterValue;
+}
+export type FrontmatterValue = string | number | boolean | null | readonly FrontmatterValue[] | FrontmatterMap;
+export type FenceState = Readonly<{
+    delimiter: "`" | "~";
+    length: number;
+}>;
+type Spanned = Readonly<{
+    span: SourceSpan;
+}>;
+type HeaderToken = Spanned & Readonly<{
+    type: "header";
+    raw: string;
+    leadingSpaces: number;
+    level: number;
+    text: string;
+}>;
+type FenceToken = Spanned & Readonly<{
+    type: "fence";
+    raw: string;
+    leadingSpaces: number;
+    delimiter: "`" | "~";
+    length: number;
+    info: string;
+}>;
+export type ListMarkerToken = Spanned & Readonly<{
+    type: "list_marker";
+    raw: string;
+    leadingSpaces: number;
+    indent: number;
+    marker: string;
+    ordered: boolean;
+    body: string;
+    bodyStart: number;
+}>;
+type BlockquoteToken = Spanned & Readonly<{
+    type: "blockquote";
+    raw: string;
+    leadingSpaces: number;
+    marker: string;
+    body: string;
+}>;
+type TextToken = Spanned & Readonly<{
+    type: "text";
+    raw: string;
+    leadingSpaces: number;
+}>;
+type FrontmatterToken = Spanned & Readonly<{
+    type: "frontmatter";
+    raw: string;
+    entries: Readonly<Record<string, FrontmatterValue>>;
+}>;
+export type MarkdownToken = HeaderToken | FenceToken | ListMarkerToken | BlockquoteToken | TextToken | FrontmatterToken;
+export type FrontmatterNode = Spanned & Readonly<{
+    type: "frontmatter";
+    entries: Readonly<Record<string, FrontmatterValue>>;
+}>;
+export type DocumentNode = Spanned & Readonly<{
+    type: "document";
+    source: string;
+    bomLength: 0 | 1;
+    frontmatter?: FrontmatterNode;
+    children: readonly MarkdownBlockNode[];
+}>;
+export type SectionNode = Spanned & Readonly<{
+    type: "section";
+    level: 1 | 2;
+    title: string;
+    contentStart: number;
+    children: readonly MarkdownBlockNode[];
+}>;
+type ListNode = Spanned & Readonly<{
+    type: "list";
+    ordered: boolean;
+    indent: number;
+    items: readonly ListItemNode[];
+}>;
+export type ListItemNode = Spanned & Readonly<{
+    type: "list_item";
+    marker: string;
+    indent: number;
+    children: readonly MarkdownBlockNode[];
+}>;
+type CodeBlockNode = Spanned & Readonly<{
+    type: "code_block";
+    delimiter: "`" | "~";
+    fenceLength: number;
+    info: string;
+    closed: boolean;
+    lines: readonly string[];
+}>;
+type BlockquoteNode = Spanned & Readonly<{
+    type: "blockquote";
+    marker: string;
+    lines: readonly string[];
+    value: string;
+}>;
+export type TextNode = Spanned & Readonly<{
+    type: "text";
+    lines: readonly string[];
+    value: string;
+}>;
+export type HeadingNode = Spanned & Readonly<{
+    type: "heading";
+    level: number;
+    text: string;
+}>;
+export type MarkdownBlockNode = SectionNode | ListNode | CodeBlockNode | BlockquoteNode | TextNode | HeadingNode;
+export type MarkdownNode = DocumentNode | MarkdownBlockNode | ListItemNode;
+export declare class MarkdownParseError extends Error {
+    constructor(message: string);
+}
+export {};

package/build/src/markdown/types.js

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

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

@@ -0,0 +1,49 @@
+import { type PublicationFailed } from "../git/admission.js";
+import { type GitDecisionObservation } from "../git/observe.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import { type GitRefAssertion, type GitRepository } from "../git/repository.js";
+import type { AttemptContext } from "../core/decide.js";
+import type { Offer } from "../core/facts/offer.js";
+import { type ContractId, type ContractState, type EntryUlid, type JournalEntry } from "../core/facts/types.js";
+export declare function mintEntryUlids(count: number): readonly EntryUlid[];
+export declare function mintAttempts(input: Readonly<{
+    entryCount: number;
+}>): readonly AttemptContext[];
+export type UnknownAttemptClassification = Readonly<{
+    kind: "accepted";
+}> | Readonly<{
+    kind: "redecide";
+}> | Readonly<{
+    kind: "collision";
+    contractId: ContractId;
+    planned: JournalEntry;
+    observed: JournalEntry;
+    plannedBytes: string;
+    observedBytes: string;
+}>;
+export type AcceptedAdmission = Readonly<{
+    kind: "accepted";
+    facts: readonly JournalEntry[];
+    state: ContractState;
+    journal: readonly JournalEntry[];
+}>;
+export type AttemptTerminal = Readonly<{
+    kind: "collision";
+}> | PublicationFailed;
+export type DecidedOfferResult = AcceptedAdmission | AttemptTerminal | Readonly<{
+    kind: "redecide";
+}>;
+/** Admit one decided offer without making another legal decision. */
+export declare function admitDecidedOffer(input: Readonly<{
+    channel: GitDecodeChannel;
+    repository: GitRepository;
+    decisionObservation: GitDecisionObservation;
+    attempt: AttemptContext;
+    offer: Offer;
+    primaryContract: ContractId;
+    assertions?: readonly GitRefAssertion[];
+}>): Promise<DecidedOfferResult>;
+/** Classify an unknown atomic-publication outcome using only a captured Git observation. */
+export declare function classifyUnknownAttempt(observation: Readonly<{
+    contracts: GitDecisionObservation["journals"];
+}>, offer: Offer): UnknownAttemptClassification;

package/build/src/protocol/attempt.js

@@ -0,0 +1,150 @@
+import { randomBytes } from "node:crypto";
+import { encodeEntry } from "../core/facts/codec.js";
+import { admit } from "../git/admission.js";
+import { observeContractsForAdmissionAt } from "../git/observe.js";
+import { GIT_REF, readRef } from "../git/repository.js";
+import { foldJournal } from "../core/facts/fold.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { entryUlid, } from "../core/facts/types.js";
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const MAX_SEMANTIC_ATTEMPTS = 3;
+function nextEntryUlid() {
+    let value = "";
+    let time = BigInt(Date.now());
+    for (let index = 0; index < 10; index += 1) {
+        value = ALPHABET[Number(time & 31n)] + value;
+        time >>= 5n;
+    }
+    let random = BigInt(`0x${randomBytes(10).toString("hex")}`);
+    for (let index = 0; index < 16; index += 1) {
+        value += ALPHABET[Number(random & 31n)];
+        random >>= 5n;
+    }
+    return entryUlid(value);
+}
+export function mintEntryUlids(count) {
+    return Array.from({ length: count }, nextEntryUlid);
+}
+export function mintAttempts(input) {
+    return Array.from({ length: MAX_SEMANTIC_ATTEMPTS }, () => ({
+        entryUlids: mintEntryUlids(input.entryCount),
+    }));
+}
+function offerEntries(offer) {
+    return offer.facts.flatMap((append) => append.entries);
+}
+function primaryAppend(offer, primary) {
+    const append = offer.facts.find((candidate) => candidate.contractId === primary);
+    if (append === undefined)
+        throw new Error(`offer is missing its primary contract: ${primary}`);
+    return append;
+}
+function validateOffer(offer, attempt) {
+    const expectedEntries = new Set(attempt.entryUlids);
+    const actualEntries = new Set();
+    for (const append of offer.facts) {
+        for (const entry of append.entries) {
+            if (!expectedEntries.has(entry.entry) || actualEntries.has(entry.entry)) {
+                throw new Error("offer entries must use distinct ULIDs from the current attempt");
+            }
+            actualEntries.add(entry.entry);
+        }
+    }
+    if (actualEntries.size === 0)
+        throw new Error("offer requires at least one current-attempt ULID");
+}
+function snapshotFor(append, journals, head) {
+    const record = journals.get(append.contractId);
+    if (record === undefined)
+        throw new Error("accepted offer contract is missing from its observation");
+    return foldJournal(append.contractId, [...record.entries, ...append.entries], head);
+}
+function journalFor(append, journals) {
+    const record = journals.get(append.contractId);
+    if (record === undefined)
+        throw new Error("accepted offer contract is missing from its observation");
+    return [...record.entries, ...append.entries];
+}
+function recoveredAcceptance(observation, offer, primaryContract) {
+    const record = observation.contracts.get(primaryContract);
+    if (record?.state === null || record?.state === undefined) {
+        throw new Error(`recovered offer is missing its primary contract: ${primaryContract}`);
+    }
+    return {
+        kind: "accepted",
+        facts: offerEntries(offer),
+        state: record.state,
+        journal: record.entries,
+    };
+}
+function publicationPremiseMoved(repository, observation, offer, assertions) {
+    if (readRef(repository, GIT_REF) !== observation.admission.snapshot.commit)
+        return true;
+    for (const assertion of assertions)
+        if (readRef(repository, assertion.ref) !== assertion.oid)
+            return true;
+    return offer.target !== undefined
+        && readRef(repository, offer.target.target) !== offer.target.expectedOid;
+}
+/** Admit one decided offer without making another legal decision. */
+export async function admitDecidedOffer(input) {
+    const { channel, repository, decisionObservation, attempt, offer, primaryContract } = input;
+    const assertions = input.assertions ?? [];
+    validateOffer(offer, attempt);
+    const primary = primaryAppend(offer, primaryContract);
+    const admission = admit(repository, offer, decisionObservation.admission, assertions);
+    if (admission.kind === "accepted") {
+        return {
+            kind: "accepted",
+            facts: offerEntries(offer),
+            state: snapshotFor(primary, decisionObservation.journals, admission.heads[primary.contractId]),
+            journal: journalFor(primary, decisionObservation.journals),
+        };
+    }
+    if (admission.kind === "publication-failed") {
+        return publicationPremiseMoved(repository, decisionObservation, offer, assertions)
+            ? { kind: "redecide" }
+            : admission;
+    }
+    const recovered = await observeContractsForAdmissionAt(repository, channel, offer.facts.map((append) => append.contractId));
+    const classification = classifyUnknownAttempt({ contracts: recovered.journals }, offer);
+    if (classification.kind === "accepted")
+        return recoveredAcceptance({ contracts: recovered.journals }, offer, primaryContract);
+    return classification.kind === "collision" ? { kind: "collision" } : { kind: "redecide" };
+}
+/** Classify an unknown atomic-publication outcome using only a captured Git observation. */
+export function classifyUnknownAttempt(observation, offer) {
+    let exact = 0;
+    let missing = 0;
+    for (const append of offer.facts) {
+        const record = observation.contracts.get(append.contractId);
+        if (record === undefined)
+            throw new Error(`missing contract observation: ${append.contractId}`);
+        const entries = new Map(record.entries.map((entry) => [entry.entry, entry]));
+        for (const planned of append.entries) {
+            const plannedBytes = encodeEntry(planned);
+            const observed = entries.get(planned.entry);
+            if (observed === undefined) {
+                missing += 1;
+                continue;
+            }
+            const observedBytes = encodeEntry(observed);
+            if (plannedBytes !== observedBytes) {
+                return {
+                    kind: "collision",
+                    contractId: append.contractId,
+                    planned,
+                    observed,
+                    plannedBytes,
+                    observedBytes,
+                };
+            }
+            exact += 1;
+        }
+    }
+    if (missing === 0)
+        return { kind: "accepted" };
+    if (exact !== 0)
+        throw new AuthorityCorruptionError("partial unknown attempt match is corrupted authority");
+    return { kind: "redecide" };
+}

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

@@ -0,0 +1,32 @@
+import type { GitRepository } from "../git/repository.js";
+import type { GitDecodeChannel } from "../git/read-observation.js";
+import type { BindData, ActorId, ContractId } from "../core/facts/types.js";
+import { type BindRefusal } from "../core/verbs/bind.js";
+export type { BindRefusal } from "../core/verbs/bind.js";
+import type { VerificationDeclarationPreparation, VerificationDeclarationRefusal } from "../verification/declaration.js";
+import { type IntentOutcome } from "./outcome.js";
+import type { CompanionDecorator } from "./run.js";
+export type TargetInputRefusal = Readonly<{
+    kind: "invalid-target";
+}> | Readonly<{
+    kind: "target-missing";
+}> | Readonly<{
+    kind: "here-target-mismatch";
+    target: string;
+    branch: string | null;
+}>;
+type BindOperationInput = Readonly<{
+    scope: GitRepository;
+    channel: GitDecodeChannel;
+    title: string;
+    terms: BindData["terms"];
+    verification: VerificationDeclarationPreparation;
+    target?: string;
+    workspace: "worktree" | "here";
+    actor?: ActorId;
+    decorateOffer?: CompanionDecorator;
+    contractId?: ContractId;
+}>;
+export declare function bindOperation(input: BindOperationInput): Promise<IntentOutcome<Readonly<{
+    contractId: ContractId;
+}>, BindRefusal | TargetInputRefusal | VerificationDeclarationRefusal>>;

package/build/src/protocol/bind.js

@@ -0,0 +1,70 @@
+import { normalizeTargetBranch, observeBindCoordinates } from "../git/observe.js";
+import { gitObjectIdForSnapshot } from "../git/identity.js";
+import { contractIdFromSegment } from "../core/facts/types.js";
+import { decideBind } from "../core/verbs/bind.js";
+import { admitIntent } from "./intent.js";
+import { complete } from "./outcome.js";
+import { fitIdentityStem, normalizeIdentityStem } from "../identity/normalize.js";
+const COLLISION_ATTEMPTS = 3;
+function contractIdFor(title, suffix) {
+    const stem = fitIdentityStem({ stem: normalizeIdentityStem({ source: title }) || "contract", maxBytes: 48 });
+    return contractIdFromSegment(suffix === undefined ? stem : `${stem}-${suffix}`);
+}
+function bindPreparation(input, target, seed) {
+    if (input.verification.kind === "refused") {
+        return { kind: "prepared", input: { ...seed, preparation: input.verification } };
+    }
+    const observed = observeBindCoordinates(input.scope, target);
+    if (observed === null)
+        return { kind: "refused", refusal: { kind: "target-missing" } };
+    if (input.workspace === "here" && target !== undefined && observed.branch !== target) {
+        return { kind: "refused", refusal: { kind: "here-target-mismatch", target, branch: observed.branch } };
+    }
+    const oid = gitObjectIdForSnapshot(observed.start);
+    const assertions = [{ ref: target ?? "HEAD", oid }];
+    return {
+        kind: "prepared",
+        input: {
+            ...seed,
+            preparation: {
+                kind: "prepared",
+                data: {
+                    coordinates: {
+                        start: observed.start,
+                        ...(observed.target === undefined ? {} : { target: observed.target }),
+                        workspace: input.workspace,
+                    },
+                    terms: input.terms,
+                },
+            },
+        },
+        assertions,
+    };
+}
+export async function bindOperation(input) {
+    let target;
+    if (input.target !== undefined) {
+        const normalized = normalizeTargetBranch(input.scope, input.target);
+        if (normalized === null)
+            return { kind: "refused", refusal: { kind: "invalid-target" } };
+        target = normalized;
+    }
+    const at = new Date().toISOString();
+    const attempt = async (id) => complete(await admitIntent(input.channel, input.scope, {
+        contractId: id,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at,
+    }, decideBind, {
+        observedContracts: [id, ...input.terms.after],
+        prepareInput: (_observation, original) => bindPreparation(input, target, original),
+        ...(input.decorateOffer === undefined ? {} : { decorateOffer: input.decorateOffer }),
+    }), { contractId: id });
+    if (input.contractId !== undefined)
+        return attempt(input.contractId);
+    let result = await attempt(contractIdFor(input.title));
+    for (let collision = 0; collision < COLLISION_ATTEMPTS && result.kind === "refused" && result.refusal.kind === "contract-exists"; collision += 1) {
+        result = await attempt(contractIdFor(input.title, randomBytes(8).toString("hex")));
+    }
+    return result;
+}
+import { randomBytes } from "node:crypto";

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

@@ -0,0 +1,76 @@
+import type { GitDecisionObservation } from "../git/observe.js";
+import type { GitDecodeChannel, GitTreeSelection } from "../git/read-observation.js";
+import type { GitRepository } from "../git/repository.js";
+import type { GitRefAssertion } from "../git/repository.js";
+import { type WorktreeLeak } from "../git/scratch.js";
+import type { HookFailure } from "../git/hooks.js";
+import type { DecideInput, OfferDecision } from "../core/decide.js";
+import type { ActorId, ContractId, ContractState } from "../core/facts/types.js";
+import { type AttestationRefusal } from "../core/verbs/attestation.js";
+import { type VerificationDefinition } from "../verification/declaration.js";
+import { type CompanionDecorator, type ProtocolResult } from "./run.js";
+type IntentAdmissionOptions<Input, Refusal, Seed> = Readonly<{
+    observedContracts?: readonly ContractId[];
+    observe?: (repository: GitRepository, channel: GitDecodeChannel, contracts: readonly ContractId[]) => Promise<GitDecisionObservation>;
+    decorateOffer?: CompanionDecorator;
+    observationSelection?: GitTreeSelection;
+    prepareInput?: (observation: GitDecisionObservation, input: Seed) => Readonly<{
+        kind: "prepared";
+        input: Input;
+        assertions?: readonly GitRefAssertion[];
+    }> | Readonly<{
+        kind: "refused";
+        refusal: Refusal;
+    }> | Promise<Readonly<{
+        kind: "prepared";
+        input: Input;
+        assertions?: readonly GitRefAssertion[];
+    }> | Readonly<{
+        kind: "refused";
+        refusal: Refusal;
+    }>>;
+}>;
+/** Observe, decide, and atomically admit one intent with bounded Git retries. */
+export declare function admitIntent<Input extends Readonly<{
+    contractId: ContractId;
+}>, Refusal, Seed extends Readonly<{
+    contractId: ContractId;
+}> = Input>(channel: GitDecodeChannel, repository: GitRepository, input: Seed, decide: (input: DecideInput<Input>) => OfferDecision<Refusal>, options?: IntentAdmissionOptions<Input, Refusal, Seed>): Promise<ProtocolResult<Refusal>>;
+type VerifyDeliveryInput = Readonly<{
+    channel: GitDecodeChannel;
+    repository: GitRepository;
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    state: ContractState;
+    environment: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    verification?: VerificationDefinition;
+}>;
+export type VerificationRuntimeStop = Readonly<{
+    failure: "unknown-exit" | "cancelled";
+}> | Readonly<{
+    failure: "candidate-unavailable" | "spawn-error";
+    diagnostic: string;
+}> | Readonly<{
+    failure: "environment-failure";
+    diagnostic: string;
+}> | Readonly<{
+    failure: "environment-failure";
+    command: number;
+    detail: HookFailure;
+}>;
+export type VerificationCleanupFailure = Readonly<{
+    phase: "destroy";
+    command: number;
+    detail: HookFailure;
+}>;
+export type VerificationStep = ProtocolResult<AttestationRefusal> | VerificationRuntimeStop;
+export type VerificationResult = Readonly<{
+    step: VerificationStep;
+    cleanup?: VerificationCleanupFailure;
+    leak?: WorktreeLeak;
+}>;
+/** Run Verification for an observed delivery, then tender its fact. */
+export declare function verifyDelivery(input: VerifyDeliveryInput): Promise<VerificationResult | null>;
+export {};

package/build/src/protocol/intent.js

@@ -0,0 +1,90 @@
+import { materializeScratchCandidate } from "../git/scratch.js";
+import { projectSettings } from "../settings.js";
+import { dependencyKeySet } from "../core/subject.js";
+import { decideAttestation } from "../core/verbs/attestation.js";
+import { executeVerification } from "../verification/execution.js";
+import { VERIFIED } from "../verification/declaration.js";
+import { runProtocol } from "./run.js";
+import { mintAttempts } from "./attempt.js";
+/** Observe, decide, and atomically admit one intent with bounded Git retries. */
+export function admitIntent(channel, repository, input, decide, options = {}) {
+    const contracts = options.observedContracts ?? [input.contractId];
+    return runProtocol({
+        input,
+        channel,
+        repository,
+        contracts,
+        attempts: mintAttempts({ entryCount: 2 }),
+        decide,
+        ...(options.observe === undefined ? {} : { observe: options.observe }),
+        ...(options.decorateOffer === undefined ? {} : { decorateOffer: options.decorateOffer }),
+        ...(options.observationSelection === undefined ? {} : { observationSelection: options.observationSelection }),
+        ...(options.prepareInput === undefined ? {} : { prepareInput: options.prepareInput }),
+    });
+}
+function runtimeStop(outcome) {
+    return outcome.kind === "spawn-error"
+        ? { failure: outcome.kind, diagnostic: outcome.diagnostic }
+        : { failure: outcome.kind };
+}
+function verificationInput(outcome, input, subject) {
+    return {
+        contractId: input.contractId,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at: input.at,
+        preparation: {
+            kind: "prepared",
+            data: {
+                gate: VERIFIED,
+                subject,
+                verdict: outcome.verdict,
+                ...(outcome.summary === undefined ? {} : { summary: outcome.summary }),
+            },
+        },
+    };
+}
+/** Run Verification for an observed delivery, then tender its fact. */
+export async function verifyDelivery(input) {
+    const state = input.state;
+    if (state.delivery === null
+        || input.verification === undefined)
+        return null;
+    const subject = dependencyKeySet([
+        { kind: "snapshot", value: state.delivery.data.integration.snapshot },
+        { kind: "segment", value: input.verification.segment },
+    ]);
+    const execution = await executeVerification({
+        repository: input.repository,
+        candidate: state.delivery.data.integration.snapshot,
+        declarations: input.verification.declarations,
+        environment: input.environment,
+        materializeScratchCandidate,
+        projectSettings,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    let step;
+    if (execution.outcome.kind === "terminal") {
+        step = await admitIntent(input.channel, input.repository, verificationInput(execution.outcome, input, subject), decideAttestation);
+    }
+    else if (execution.outcome.kind === "candidate-unavailable") {
+        step = { failure: "candidate-unavailable", diagnostic: execution.outcome.diagnostic };
+    }
+    else if (execution.outcome.kind === "environment-failure") {
+        step = "diagnostic" in execution.outcome
+            ? { failure: "environment-failure", diagnostic: execution.outcome.diagnostic }
+            : { failure: "environment-failure", command: execution.outcome.command, detail: execution.outcome.detail };
+    }
+    else if (execution.outcome.kind === "unknown-exit"
+        || execution.outcome.kind === "cancelled"
+        || execution.outcome.kind === "spawn-error") {
+        step = runtimeStop(execution.outcome);
+    }
+    else {
+        throw new Error("Verification execution returned an invalid outcome");
+    }
+    return {
+        step,
+        ...(execution.cleanup === undefined ? {} : { cleanup: execution.cleanup }),
+        ...(execution.leak === undefined ? {} : { leak: execution.leak }),
+    };
+}