@astrosheep/keiyaku 2.9.13 → 4.0.0

package/build/src/core/facts/types.d.ts

@@ -0,0 +1,130 @@
+declare const contractIdBrand: unique symbol;
+declare const entryUlidBrand: unique symbol;
+declare const contractHeadBrand: unique symbol;
+declare const snapshotIdBrand: unique symbol;
+declare const changeIdBrand: unique symbol;
+declare const documentKeyBrand: unique symbol;
+declare const documentSegmentKeyBrand: unique symbol;
+declare const gateBrand: unique symbol;
+declare const dependencyKeySetBrand: unique symbol;
+declare const actorIdBrand: unique symbol;
+export type ContractId = string & {
+    readonly [contractIdBrand]: "ContractId";
+};
+export type EntryUlid = string & {
+    readonly [entryUlidBrand]: "EntryUlid";
+};
+export type ContractHead = string & {
+    readonly [contractHeadBrand]: "ContractHead";
+};
+export type SnapshotId = string & {
+    readonly [snapshotIdBrand]: "SnapshotId";
+};
+export type ChangeId = string & {
+    readonly [changeIdBrand]: "ChangeId";
+};
+export type DocumentKey = string & {
+    readonly [documentKeyBrand]: "DocumentKey";
+};
+export type DocumentSegmentKey = string & {
+    readonly [documentSegmentKeyBrand]: "DocumentSegmentKey";
+};
+export type Gate = string & {
+    readonly [gateBrand]: "Gate";
+};
+export type DependencyKeySet = string & {
+    readonly [dependencyKeySetBrand]: "DependencyKeySet";
+};
+export type ActorId = string & {
+    readonly [actorIdBrand]: "ActorId";
+};
+export declare function contractId(value: string): ContractId;
+export declare function contractIdFromSegment(segment: string): ContractId;
+export declare function contractSegment(value: ContractId): string;
+export declare function entryUlid(value: string): EntryUlid;
+export declare function contractHead(value: string): ContractHead;
+/** Validate an opaque persisted snapshot value; only Git may mint one. */
+export declare function snapshotId(value: string): SnapshotId;
+/** Validate an opaque persisted change value; only Git may mint one. */
+export declare function changeId(value: string): ChangeId;
+/** Validate optional opaque testimony without imposing a registry. */
+export declare function actorId(value: string): ActorId;
+export declare function documentKey(value: string): DocumentKey;
+export declare function documentSegmentKey(value: string): DocumentSegmentKey;
+export declare function gateWord(value: unknown): value is string;
+export declare function gate(value: string): Gate;
+export type ContractCoordinates = Readonly<{
+    start: SnapshotId;
+    target?: string;
+    workspace: "worktree" | "here";
+}>;
+export type ContractTerms = Readonly<{
+    document: Readonly<{
+        bytes: string;
+        key: DocumentKey;
+    }>;
+    segments: readonly DocumentSegmentKey[];
+    gates: readonly Gate[];
+    after: readonly ContractId[];
+}>;
+export type BindData = Readonly<{
+    coordinates: ContractCoordinates;
+    terms: ContractTerms;
+}>;
+export type AmendData = ContractTerms;
+export type BoundData = Readonly<Record<string, never>>;
+export type DeliverData = Readonly<{
+    expectedPredecessor: SnapshotId;
+    candidate: SnapshotId;
+    deliveryPatchId: ChangeId;
+}>;
+export type AttestationData = Readonly<{
+    gate: Gate;
+    subject: DependencyKeySet;
+    verdict: "satisfied" | "unsatisfied";
+    summary?: string;
+}>;
+export type ClaimedData = Readonly<{
+    delivery: EntryUlid;
+}>;
+export type ArcData = Readonly<{
+    seq: number;
+    title: string;
+    objective: string;
+    brief: string;
+}>;
+export type AbandonedData = Readonly<{
+    note?: string;
+}>;
+type JournalEnvelope<Kind extends string, Data> = Readonly<{
+    v: 1;
+    kind: Kind;
+    contract: ContractId;
+    entry: EntryUlid;
+    at: string;
+    actor?: ActorId;
+    data: Data;
+}>;
+export type BindEntry = JournalEnvelope<"bind", BindData>;
+type AmendEntry = JournalEnvelope<"amend", AmendData>;
+type BoundEntry = JournalEnvelope<"bound", BoundData>;
+type DeliverEntry = JournalEnvelope<"deliver", DeliverData>;
+export type AttestationEntry = JournalEnvelope<"attestation", AttestationData>;
+type ClaimedEntry = JournalEnvelope<"claimed", ClaimedData>;
+export type ArcEntry = JournalEnvelope<"arc", ArcData>;
+type AbandonedEntry = JournalEnvelope<"abandoned", AbandonedData>;
+export type JournalEntry = BindEntry | AmendEntry | BoundEntry | DeliverEntry | AttestationEntry | ClaimedEntry | ArcEntry | AbandonedEntry;
+export type FactKind = JournalEntry["kind"];
+type ContractTerminal = ClaimedEntry | AbandonedEntry;
+export type ContractState = Readonly<{
+    id: ContractId;
+    head: ContractHead | null;
+    coordinates: ContractCoordinates;
+    terms: ContractTerms;
+    bound: BoundEntry | null;
+    delivery: DeliverEntry | null;
+    attestations: readonly AttestationEntry[];
+    currentArc?: ArcEntry;
+    terminal: ContractTerminal | null;
+}>;
+export {};

package/build/src/core/facts/types.js

@@ -0,0 +1,66 @@
+import { identityCoordinate, identitySegments } from "../../identity/coordinates.js";
+const ULID = /^[0-9ABCDEFGHJKMNPQRSTVWXYZ]{26}$/;
+function requireText(value, label) {
+    if (value.length === 0 || /\s/.test(value))
+        throw new Error(`${label} must be nonempty and contain no whitespace`);
+    return value;
+}
+function requireOpaqueId(value, label) {
+    if (value.trim().length === 0)
+        throw new Error(`${label} must be nonblank`);
+    return value;
+}
+export function contractId(value) {
+    requireText(value, "contract ID");
+    let segments;
+    try {
+        segments = identitySegments({ family: "kei", value });
+    }
+    catch {
+        throw new Error("contract ID must be kei/<contract-segment>");
+    }
+    if (segments.length !== 1)
+        throw new Error("contract ID must be kei/<contract-segment>");
+    return value;
+}
+export function contractIdFromSegment(segment) {
+    return contractId(identityCoordinate({ family: "kei", segments: [segment] }));
+}
+export function contractSegment(value) {
+    return identitySegments({ family: "kei", value: contractId(value) })[0];
+}
+export function entryUlid(value) {
+    if (!ULID.test(value))
+        throw new Error("entry ULID must be a canonical 26-character uppercase ULID");
+    return value;
+}
+export function contractHead(value) {
+    return requireOpaqueId(value, "contract head");
+}
+/** Validate an opaque persisted snapshot value; only Git may mint one. */
+export function snapshotId(value) {
+    return requireOpaqueId(value, "snapshot ID");
+}
+/** Validate an opaque persisted change value; only Git may mint one. */
+export function changeId(value) {
+    return requireOpaqueId(value, "change ID");
+}
+/** Validate optional opaque testimony without imposing a registry. */
+export function actorId(value) {
+    return requireOpaqueId(value, "actor");
+}
+export function documentKey(value) {
+    return requireOpaqueId(value, "document key");
+}
+export function documentSegmentKey(value) {
+    return requireOpaqueId(value, "document segment key");
+}
+export function gateWord(value) {
+    return typeof value === "string" && /^[a-z][a-z0-9-]{0,63}$/u.test(value);
+}
+export function gate(value) {
+    if (!gateWord(value)) {
+        throw new Error("gate must match ^[a-z][a-z0-9-]{0,63}$");
+    }
+    return value;
+}

package/build/src/core/subject.d.ts

@@ -0,0 +1,21 @@
+import { type ChangeId, type ContractState, type DependencyKeySet, type DocumentKey, type DocumentSegmentKey, type SnapshotId } from "./facts/types.js";
+type DependencyKey = Readonly<{
+    readonly kind: "document";
+    readonly value: DocumentKey;
+} | {
+    readonly kind: "segment";
+    readonly value: DocumentSegmentKey;
+} | {
+    readonly kind: "snapshot";
+    readonly value: SnapshotId;
+} | {
+    readonly kind: "change";
+    readonly value: ChangeId;
+}>;
+/** Mint the opaque persisted representation of an ordered producer-selected key set. */
+export declare function dependencyKeySet(keys: readonly DependencyKey[]): DependencyKeySet;
+/** Parse and canonicalize the opaque dependency-key-set fact value. */
+export declare function parseDependencyKeySet(value: string): DependencyKeySet;
+/** Build one memoized currentness test for a folded contract snapshot. */
+export declare function currentSubjectPredicate(state: ContractState): (subject: DependencyKeySet) => boolean;
+export {};

package/build/src/core/subject.js

@@ -0,0 +1,89 @@
+import { changeId, documentKey, documentSegmentKey, snapshotId, } from "./facts/types.js";
+import { AuthorityCorruptionError } from "./facts/errors.js";
+function keyTuple(key) {
+    return [key.kind, key.value];
+}
+function encodeKey(key) {
+    return JSON.stringify(keyTuple(key));
+}
+function parseKey(value, index) {
+    if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== "string" || typeof value[1] !== "string") {
+        throw new AuthorityCorruptionError(`dependency key [${index}] must be a [kind, value] pair`);
+    }
+    try {
+        switch (value[0]) {
+            case "document": return { kind: "document", value: documentKey(value[1]) };
+            case "segment": return { kind: "segment", value: documentSegmentKey(value[1]) };
+            case "snapshot": return { kind: "snapshot", value: snapshotId(value[1]) };
+            case "change": return { kind: "change", value: changeId(value[1]) };
+            default: throw new AuthorityCorruptionError(`unknown dependency key kind '${value[0]}'`);
+        }
+    }
+    catch (error) {
+        throw error instanceof AuthorityCorruptionError
+            ? error
+            : new AuthorityCorruptionError(error instanceof Error ? error.message : `invalid dependency key [${index}]`);
+    }
+}
+function canonicalEncodedKeys(keys) {
+    const encoded = keys.map(encodeKey).sort();
+    for (let index = 1; index < encoded.length; index += 1) {
+        if (encoded[index] === encoded[index - 1])
+            throw new AuthorityCorruptionError("dependency key set cannot contain duplicates");
+    }
+    return encoded;
+}
+function canonicalKeys(keys) {
+    return `[${canonicalEncodedKeys(keys).join(",")}]`;
+}
+/** Mint the opaque persisted representation of an ordered producer-selected key set. */
+export function dependencyKeySet(keys) {
+    return canonicalKeys(keys);
+}
+function decodeDependencyKeySet(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new AuthorityCorruptionError("dependency key set must be nonblank");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        throw new AuthorityCorruptionError("dependency key set must be canonical JSON", { cause: error });
+    }
+    if (!Array.isArray(parsed))
+        throw new AuthorityCorruptionError("dependency key set must be an array");
+    const keys = parsed.map(parseKey);
+    const encodedKeys = canonicalEncodedKeys(keys);
+    const canonical = `[${encodedKeys.join(",")}]`;
+    if (canonical !== value)
+        throw new AuthorityCorruptionError("dependency key set must be canonical JSON");
+    return { canonical: canonical, encodedKeys };
+}
+/** Parse and canonicalize the opaque dependency-key-set fact value. */
+export function parseDependencyKeySet(value) {
+    return decodeDependencyKeySet(value).canonical;
+}
+function currentKeys(state) {
+    return new Set([
+        encodeKey({ kind: "document", value: state.terms.document.key }),
+        ...state.terms.segments.map((value) => encodeKey({ kind: "segment", value })),
+        ...(state.delivery === null ? [] : [
+            encodeKey({ kind: "snapshot", value: state.delivery.data.candidate }),
+            encodeKey({ kind: "change", value: state.delivery.data.deliveryPatchId }),
+        ]),
+    ]);
+}
+/** Build one memoized currentness test for a folded contract snapshot. */
+export function currentSubjectPredicate(state) {
+    const available = currentKeys(state);
+    const current = new Map();
+    return (subject) => {
+        const known = current.get(subject);
+        if (known !== undefined)
+            return known;
+        const value = decodeDependencyKeySet(subject).encodedKeys.every((key) => available.has(key));
+        current.set(subject, value);
+        return value;
+    };
+}

package/build/src/core/verbs/abandon.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision } from "../decide.js";
+import type { ActorId, ContractId } from "../facts/types.js";
+export type AbandonInput = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    note?: string;
+}>;
+export type AbandonRefusal = Readonly<{
+    kind: "contract-missing" | "terminal";
+    contractId: ContractId;
+}>;
+export declare function decideAbandon({ input, attempt, observation }: DecideInput<AbandonInput>): OfferDecision<AbandonRefusal>;

package/build/src/core/verbs/abandon.js

@@ -0,0 +1,17 @@
+import { activeContract } from "../facts/observation.js";
+export function decideAbandon({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = activeContract(observation, id);
+    if ("kind" in current)
+        return { kind: "refused", refusal: current };
+    const abandoned = {
+        v: 1,
+        kind: "abandoned",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: input.note === undefined ? {} : { note: input.note },
+    };
+    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: current.head, entries: [abandoned] }] } };
+}

package/build/src/core/verbs/amend.d.ts

@@ -0,0 +1,14 @@
+import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
+import type { ActorId, AmendData, ContractId, ContractTerms } from "../facts/types.js";
+export type AmendInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    source?: ContractTerms;
+    preparation?: Preparation<AmendData, Failure>;
+}>;
+export type AmendRefusal = Readonly<{
+    kind: "contract-missing" | "terminal" | "terms-moved" | "prerequisites-already-consumed" | "unknown-prerequisite" | "cyclic-prerequisite";
+    contractId: ContractId;
+}>;
+export declare function decideAmend<Failure>({ input, attempt, observation }: DecideInput<AmendInput<Failure>>): OfferDecision<AmendRefusal | Failure>;

package/build/src/core/verbs/amend.js

@@ -0,0 +1,56 @@
+import { prerequisiteStatus, prerequisitesReach, samePrerequisites } from "../facts/eligibility.js";
+import { activeContract } from "../facts/observation.js";
+export function decideAmend({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = activeContract(observation, id);
+    if ("kind" in current)
+        return { kind: "refused", refusal: current };
+    if (input.preparation === undefined || input.source === undefined) {
+        throw new Error("existing contract requires an amend preparation and source terms");
+    }
+    const source = input.source;
+    const termsCurrent = source.document.key === current.terms.document.key
+        && source.segments.length === current.terms.segments.length
+        && source.segments.every((value, index) => value === current.terms.segments[index])
+        && source.gates.length === current.terms.gates.length
+        && source.gates.every((value, index) => value === current.terms.gates[index])
+        && samePrerequisites(source.after, current.terms.after);
+    if (!termsCurrent) {
+        return { kind: "refused", refusal: { kind: "terms-moved", contractId: id } };
+    }
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const { data } = input.preparation;
+    if (current.bound !== null && !samePrerequisites(current.terms.after, data.after)) {
+        return { kind: "refused", refusal: { kind: "prerequisites-already-consumed", contractId: id } };
+    }
+    const prerequisites = prerequisiteStatus(data.after, observation);
+    if (prerequisites === "unknown") {
+        return { kind: "refused", refusal: { kind: "unknown-prerequisite", contractId: id } };
+    }
+    if (prerequisitesReach(id, data.after, observation)) {
+        return { kind: "refused", refusal: { kind: "cyclic-prerequisite", contractId: id } };
+    }
+    const entry = {
+        v: 1,
+        kind: "amend",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data,
+    };
+    const entries = [entry];
+    if (current.bound === null && prerequisites === "claimed") {
+        entries.push({
+            v: 1,
+            kind: "bound",
+            contract: id,
+            entry: attempt.entryUlids[1],
+            at: input.at,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            data: {},
+        });
+    }
+    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: current.head, entries }] } };
+}

package/build/src/core/verbs/arc.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision } from "../decide.js";
+import type { ActorId, ArcData, ContractId } from "../facts/types.js";
+export type ArcInput = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    data: Readonly<Omit<ArcData, "seq">>;
+}>;
+export type ArcRefusal = Readonly<{
+    kind: "contract-missing" | "terminal";
+    contractId: ContractId;
+}>;
+export declare function decideArc({ input, attempt, observation }: DecideInput<ArcInput>): OfferDecision<ArcRefusal>;

package/build/src/core/verbs/arc.js

@@ -0,0 +1,25 @@
+import { activeContract } from "../facts/observation.js";
+export function decideArc({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = activeContract(observation, id);
+    if ("kind" in current)
+        return { kind: "refused", refusal: current };
+    const arc = {
+        v: 1,
+        kind: "arc",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: {
+            seq: (current.currentArc?.data.seq ?? 0) + 1,
+            title: input.data.title,
+            objective: input.data.objective,
+            brief: input.data.brief,
+        },
+    };
+    return {
+        kind: "offer",
+        offer: { facts: [{ contractId: id, expectedHead: current.head, entries: [arc] }] },
+    };
+}

package/build/src/core/verbs/attestation.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
+import type { ActorId, AttestationData, ContractId } from "../facts/types.js";
+export type AttestationInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    preparation?: Preparation<AttestationData, Failure>;
+}>;
+export type AttestationRefusal = Readonly<{
+    kind: "contract-missing" | "terminal";
+    contractId: ContractId;
+}>;
+export declare function decideAttestation<Failure>({ input, attempt, observation, }: DecideInput<AttestationInput<Failure>>): OfferDecision<AttestationRefusal | Failure>;

package/build/src/core/verbs/attestation.js

@@ -0,0 +1,21 @@
+import { activeContract } from "../facts/observation.js";
+export function decideAttestation({ input, attempt, observation, }) {
+    const state = activeContract(observation, input.contractId);
+    if ("kind" in state)
+        return { kind: "refused", refusal: state };
+    if (input.preparation === undefined) {
+        throw new Error("active contract requires an attestation preparation");
+    }
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const attestation = {
+        v: 1,
+        kind: "attestation",
+        contract: input.contractId,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: input.preparation.data,
+    };
+    return { kind: "offer", offer: { facts: [{ contractId: input.contractId, expectedHead: state.head, entries: [attestation] }] } };
+}

package/build/src/core/verbs/bind.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision, Preparation } from "../decide.js";
+import type { ActorId, BindData, ContractId } from "../facts/types.js";
+export type BindInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    preparation: Preparation<BindData, Failure>;
+}>;
+export type BindRefusal = Readonly<{
+    kind: "contract-exists" | "invalid-after" | "unknown-prerequisite";
+    contractId: ContractId;
+}>;
+export declare function decideBind<Failure>({ input, attempt, observation }: DecideInput<BindInput<Failure>>): OfferDecision<BindRefusal | Failure>;

package/build/src/core/verbs/bind.js

@@ -0,0 +1,40 @@
+import { prerequisiteStatus } from "../facts/eligibility.js";
+import { contractState } from "../facts/observation.js";
+export function decideBind({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = contractState(observation, id);
+    if (current !== null)
+        return { kind: "refused", refusal: { kind: "contract-exists", contractId: id } };
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const { data } = input.preparation;
+    if (data.terms.after.includes(id))
+        return { kind: "refused", refusal: { kind: "invalid-after", contractId: id } };
+    const prerequisites = prerequisiteStatus(data.terms.after, observation);
+    if (prerequisites === "unknown") {
+        return { kind: "refused", refusal: { kind: "unknown-prerequisite", contractId: id } };
+    }
+    const bind = {
+        v: 1,
+        kind: "bind",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data,
+    };
+    const entries = [bind];
+    if (prerequisites === "claimed") {
+        const bound = {
+            v: 1,
+            kind: "bound",
+            contract: id,
+            entry: attempt.entryUlids[1],
+            at: input.at,
+            ...(input.actor === undefined ? {} : { actor: input.actor }),
+            data: {},
+        };
+        entries.push(bound);
+    }
+    return { kind: "offer", offer: { facts: [{ contractId: id, expectedHead: null, entries }] } };
+}

package/build/src/core/verbs/deliver.d.ts

@@ -0,0 +1,13 @@
+import type { DecideInput, OfferDecision, StampedPreparation } from "../decide.js";
+import type { ActorId, ContractId, DeliverData } from "../facts/types.js";
+export type DeliverInput<Failure = never> = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+    preparation: StampedPreparation<DeliverData, Failure>;
+}>;
+export type DeliverRefusal = Readonly<{
+    kind: "contract-missing" | "not-bound" | "terminal" | "document-moved";
+    contractId: ContractId;
+}>;
+export declare function decideDeliver<Failure>({ input, attempt, observation, }: DecideInput<DeliverInput<Failure>>): OfferDecision<DeliverRefusal | Failure>;

package/build/src/core/verbs/deliver.js

@@ -0,0 +1,26 @@
+import { activeContract, documentIsCurrent } from "../facts/observation.js";
+export function decideDeliver({ input, attempt, observation, }) {
+    const state = activeContract(observation, input.contractId);
+    if ("kind" in state)
+        return { kind: "refused", refusal: state };
+    if (state.bound === null)
+        return { kind: "refused", refusal: { kind: "not-bound", contractId: input.contractId } };
+    if (input.preparation.kind === "unavailable") {
+        throw new Error("existing contract requires a stamped delivery preparation");
+    }
+    if (!documentIsCurrent(state, input.preparation.document)) {
+        return { kind: "refused", refusal: { kind: "document-moved", contractId: input.contractId } };
+    }
+    if (input.preparation.kind === "refused")
+        return { kind: "refused", refusal: input.preparation.refusal };
+    const deliver = {
+        v: 1,
+        kind: "deliver",
+        contract: input.contractId,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: input.preparation.data,
+    };
+    return { kind: "offer", offer: { facts: [{ contractId: input.contractId, expectedHead: state.head, entries: [deliver] }] } };
+}

package/build/src/core/verbs/placement.d.ts

@@ -0,0 +1,13 @@
+import type { ActorId, ContractId } from "../facts/types.js";
+import type { DecideInput, OfferDecision } from "../decide.js";
+type PlacementInput = Readonly<{
+    contractId: ContractId;
+    actor?: ActorId;
+    at: string;
+}>;
+export type PlacementRefusal = Readonly<{
+    kind: "contract-missing" | "delivery-missing" | "terminal" | "gates-unsatisfied";
+    contractId: ContractId;
+}>;
+export declare function decidePlacement({ input, attempt, observation }: DecideInput<PlacementInput>): OfferDecision<PlacementRefusal>;
+export {};

package/build/src/core/verbs/placement.js

@@ -0,0 +1,42 @@
+import { gatesSatisfied } from "../facts/gate.js";
+import { placeEligibleBounds } from "../facts/eligibility.js";
+import { activeContract } from "../facts/observation.js";
+export function decidePlacement({ input, attempt, observation }) {
+    const id = input.contractId;
+    const current = activeContract(observation, id);
+    if ("kind" in current)
+        return { kind: "refused", refusal: current };
+    const delivery = current.delivery;
+    if (!delivery) {
+        return { kind: "refused", refusal: { kind: "delivery-missing", contractId: id } };
+    }
+    if (!gatesSatisfied(current)) {
+        return { kind: "refused", refusal: { kind: "gates-unsatisfied", contractId: id } };
+    }
+    const claimed = {
+        v: 1,
+        kind: "claimed",
+        contract: id,
+        entry: attempt.entryUlids[0],
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+        data: { delivery: delivery.entry },
+    };
+    const offer = {
+        kind: "offer",
+        offer: {
+            facts: [{ contractId: id, expectedHead: current.head, entries: [claimed] }],
+            ...(current.coordinates.target === undefined ? {} : {
+                target: {
+                    target: current.coordinates.target,
+                    expectedOid: delivery.data.expectedPredecessor,
+                    newOid: delivery.data.candidate,
+                },
+            }),
+        },
+    };
+    return {
+        ...offer,
+        offer: placeEligibleBounds(offer.offer, observation, attempt),
+    };
+}