@astrosheep/keiyaku 2.9.13 → 4.0.0

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,36 @@
+import { type PublicationFailed } from "../git/admission.js";
+import { type GitDecisionObservation } from "../git/observe.js";
+import { 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 JournalEntry } from "../core/facts/types.js";
+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(repository: GitRepository, decisionObservation: GitDecisionObservation, attempt: AttemptContext, offer: Offer, primaryContract: ContractId): 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,119 @@
+import { encodeEntry } from "../core/facts/codec.js";
+import { admit } from "../git/admission.js";
+import { observeContracts } 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";
+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) {
+    if (readRef(repository, GIT_REF) !== observation.admission.snapshot.commit)
+        return true;
+    return offer.target !== undefined
+        && readRef(repository, offer.target.target) !== offer.target.expectedOid;
+}
+/** Admit one decided offer without making another legal decision. */
+export function admitDecidedOffer(repository, decisionObservation, attempt, offer, primaryContract) {
+    validateOffer(offer, attempt);
+    const primary = primaryAppend(offer, primaryContract);
+    const admission = admit(repository, offer, decisionObservation.admission);
+    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)
+            ? { kind: "redecide" }
+            : admission;
+    }
+    const recovered = observeContracts(repository, offer.facts.map((append) => append.contractId));
+    const classification = classifyUnknownAttempt(recovered, offer);
+    if (classification.kind === "accepted")
+        return recoveredAcceptance(recovered, 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,25 @@
+import type { GitRepository } from "../git/repository.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";
+}>;
+type BindOperationInput = Readonly<{
+    scope: GitRepository;
+    title: string;
+    terms: BindData["terms"];
+    verification: VerificationDeclarationPreparation;
+    target?: string;
+    workspace: "worktree" | "here";
+    actor?: ActorId;
+    decorateOffer?: CompanionDecorator;
+}>;
+export declare function bindOperation(input: BindOperationInput): IntentOutcome<Readonly<{
+    contractId: ContractId;
+}>, BindRefusal | TargetInputRefusal | VerificationDeclarationRefusal>;

package/build/src/protocol/bind.js

@@ -0,0 +1,62 @@
+import { randomBytes } from "node:crypto";
+import { normalizeTargetBranch, observeBindCoordinates } from "../git/observe.js";
+import { contractIdFromSegment } from "../core/facts/types.js";
+import { decideBind } from "../core/verbs/bind.js";
+import { fitIdentityStem, normalizeIdentityStem } from "../identity/normalize.js";
+import { admitIntent } from "./intent.js";
+import { complete } from "./outcome.js";
+const CONTRACT_ID_STEM_BYTES = 72;
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function mintCollisionSuffix() {
+    let random = BigInt(`0x${randomBytes(5).toString("hex")}`);
+    let suffix = "";
+    for (let index = 0; index < 8; index += 1) {
+        suffix = CROCKFORD_BASE32[Number(random & 31n)] + suffix;
+        random >>= 5n;
+    }
+    return suffix.toLowerCase();
+}
+function contractIdFromStem(stem, suffix) {
+    return contractIdFromSegment(fitIdentityStem({
+        stem,
+        maxBytes: CONTRACT_ID_STEM_BYTES,
+        ...(suffix === undefined ? {} : { suffix }),
+    }));
+}
+export 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 observed = observeBindCoordinates(input.scope, target);
+    if (observed === null)
+        return { kind: "refused", refusal: { kind: "target-missing" } };
+    const data = {
+        coordinates: {
+            start: observed.start,
+            ...(observed.target === undefined ? {} : { target: observed.target }),
+            workspace: input.workspace,
+        },
+        terms: input.terms,
+    };
+    const stem = normalizeIdentityStem({ source: input.title }) || "contract";
+    const at = new Date().toISOString();
+    const attempt = (id) => complete(admitIntent(input.scope, {
+        contractId: id,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        at,
+        preparation: input.verification.kind === "prepared"
+            ? { kind: "prepared", data }
+            : { kind: "refused", refusal: input.verification.refusal },
+    }, decideBind, {
+        observedContracts: [id, ...input.terms.after],
+        ...(input.decorateOffer === undefined ? {} : { decorateOffer: input.decorateOffer }),
+    }), { contractId: id });
+    const first = attempt(contractIdFromStem(stem));
+    return first.kind === "refused" && first.refusal.kind === "contract-exists"
+        ? attempt(contractIdFromStem(stem, mintCollisionSuffix()))
+        : first;
+}

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

@@ -0,0 +1,52 @@
+import { type GitDecisionObservation } from "../git/observe.js";
+import type { GitRepository } from "../git/repository.js";
+import type { WorktreeLeak } from "../git/verification.js";
+import type { AttemptContext, DecideInput, OfferDecision } from "../core/decide.js";
+import type { ActorId, ContractId, ContractState } from "../core/facts/types.js";
+import { type PlacementRefusal } from "../core/verbs/placement.js";
+import { type AttestationRefusal } from "../core/verbs/attestation.js";
+import { type ProduceVerificationInput, type VerificationOutcome } from "../verification/producer.js";
+import { type VerificationDefinition } from "../verification/declaration.js";
+import { type CompanionDecorator, type ProtocolResult } from "./run.js";
+export declare function mintAttempts(input: Readonly<{
+    entryCount: number;
+}>): readonly AttemptContext[];
+type IntentAdmissionOptions = Readonly<{
+    observedContracts?: readonly ContractId[];
+    observe?: (repository: GitRepository, contracts: readonly ContractId[]) => GitDecisionObservation;
+    decorateOffer?: CompanionDecorator;
+}>;
+/** Observe, decide, and atomically admit one intent with bounded Git retries. */
+export declare function admitIntent<Input extends Readonly<{
+    contractId: ContractId;
+}>, Refusal>(repository: GitRepository, input: Input, decide: (input: DecideInput<Input>) => OfferDecision<Refusal>, options?: IntentAdmissionOptions): ProtocolResult<Refusal>;
+/** Run the sole placement adjudicator; a gates-unsatisfied refusal is normal pending state. */
+export declare function admitPlacement(repository: GitRepository, input: Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+}>): ProtocolResult<PlacementRefusal>;
+type VerifyDeliveryInput = Readonly<{
+    repository: GitRepository;
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    state: ContractState;
+    environment: NodeJS.ProcessEnv;
+    produce: (input: ProduceVerificationInput) => Promise<VerificationOutcome>;
+    verification?: VerificationDefinition;
+}>;
+export type VerificationRuntimeStop = Readonly<{
+    failure: "timeout" | "unknown-exit";
+}> | Readonly<{
+    failure: "candidate-unavailable" | "spawn-error";
+    diagnostic: string;
+}>;
+export type VerificationStep = ProtocolResult<AttestationRefusal> | VerificationRuntimeStop;
+export type VerificationResult = Readonly<{
+    step: VerificationStep;
+    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,129 @@
+import { randomBytes } from "node:crypto";
+import { observeGitForAdmission } from "../git/observe.js";
+import { materializeVerificationCandidate } from "../git/verification.js";
+import { dependencyKeySet } from "../core/subject.js";
+import { entryUlid } from "../core/facts/types.js";
+import { decidePlacement } from "../core/verbs/placement.js";
+import { decideAttestation } from "../core/verbs/attestation.js";
+import { VERIFIED } from "../verification/declaration.js";
+import { runProtocol } from "./run.js";
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const VERIFICATION_TIMEOUT_MS = 5 * 60 * 1_000;
+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);
+}
+const MAX_SEMANTIC_ATTEMPTS = 3;
+export function mintAttempts(input) {
+    return Array.from({ length: MAX_SEMANTIC_ATTEMPTS }, () => ({
+        entryUlids: Array.from({ length: input.entryCount }, nextEntryUlid),
+    }));
+}
+/** Observe, decide, and atomically admit one intent with bounded Git retries. */
+export function admitIntent(repository, input, decide, options = {}) {
+    const contracts = options.observedContracts ?? [input.contractId];
+    return runProtocol({
+        input,
+        repository,
+        contracts,
+        attempts: mintAttempts({ entryCount: 2 }),
+        decide,
+        ...(options.observe === undefined ? {} : { observe: options.observe }),
+        ...(options.decorateOffer === undefined ? {} : { decorateOffer: options.decorateOffer }),
+    });
+}
+/** Run the sole placement adjudicator; a gates-unsatisfied refusal is normal pending state. */
+export function admitPlacement(repository, input) {
+    return runProtocol({
+        input,
+        repository,
+        contracts: [input.contractId],
+        attempts: mintAttempts({ entryCount: 2 }),
+        observe: observeGitForAdmission,
+        extendAttempt: (attempt, observedContractCount) => ({
+            ...attempt,
+            entryUlids: [
+                ...attempt.entryUlids,
+                ...Array.from({ length: Math.max(0, observedContractCount - attempt.entryUlids.length) }, nextEntryUlid),
+            ],
+        }),
+        decide: decidePlacement,
+    });
+}
+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.candidate },
+        { kind: "segment", value: input.verification.segment },
+    ]);
+    let prepared;
+    try {
+        prepared = materializeVerificationCandidate(input.repository, state.delivery.data.candidate);
+    }
+    catch (error) {
+        return {
+            step: {
+                failure: "candidate-unavailable",
+                diagnostic: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+    let step;
+    let leak = null;
+    try {
+        const outcome = await input.produce({
+            declarations: input.verification.declarations,
+            cwd: prepared.cwd,
+            timeoutMs: VERIFICATION_TIMEOUT_MS,
+            env: input.environment,
+        });
+        if (outcome.kind === "terminal") {
+            step = admitIntent(input.repository, verificationInput(outcome, input, subject), decideAttestation);
+        }
+        else {
+            step = runtimeStop(outcome);
+        }
+    }
+    finally {
+        leak = prepared.dispose();
+    }
+    return {
+        step,
+        ...(leak === null ? {} : { leak }),
+    };
+}