@astrosheep/square 0.3.94 → 0.3.95

package/dist/artifact.js

@@ -117,7 +117,7 @@ function synchronous(value) {
     }
 }
 const readMethods = [
-    'header', 'participant', 'roster', 'attention', 'incomingAttention', 'hold',
+    'header', 'participant', 'roster', 'attention', 'incomingAttention',
     'activity', 'activityHeads', 'activities', 'activityCount', 'contextIndexes', 'sayOrdinals', 'recentSayTimes',
     'audience', 'directed', 'directedAt', 'directedCount', 'pendingAudience',
     'receipt', 'receiptFacts', 'receiptAssignments', 'lease', 'participantCounts', 'seat', 'seatsForOwner',

package/dist/attention.d.ts

@@ -0,0 +1,19 @@
+export type AudienceRoute = 'mention' | 'reply' | 'attention' | 'bell';
+export interface AudienceRecipient {
+    readonly recipient: string;
+    readonly route: AudienceRoute;
+}
+export interface AudienceInput {
+    readonly actor: string;
+    readonly recipients: readonly string[];
+    readonly mentions?: readonly string[];
+    readonly replyAuthor?: string;
+    readonly reach?: 'bell';
+    readonly incoming?: readonly {
+        readonly listener: string;
+        readonly kind: 'listen' | 'ignore';
+    }[];
+    readonly sameIdentity?: (a: string, b: string) => boolean;
+}
+/** Resolve attention against the caller's eligible recipient snapshot. */
+export declare function resolveAudience(input: AudienceInput): readonly AudienceRecipient[];

package/dist/attention.js

@@ -0,0 +1,30 @@
+/** Resolve attention against the caller's eligible recipient snapshot. */
+export function resolveAudience(input) {
+    const same = input.sameIdentity ?? ((a, b) => a === b);
+    const incoming = input.incoming ?? [];
+    const audience = [];
+    const add = (requested, route) => {
+        const recipient = input.recipients.find((item) => same(item, requested));
+        if (recipient === undefined || same(recipient, input.actor)
+            || audience.some((item) => same(item.recipient, recipient)))
+            return;
+        if (input.reach !== 'bell' && incoming.some((item) => item.kind === 'ignore' && same(item.listener, recipient)))
+            return;
+        audience.push({ recipient, route });
+    };
+    if (input.reach === 'bell') {
+        for (const recipient of input.recipients)
+            add(recipient, 'bell');
+    }
+    else {
+        for (const mention of input.mentions ?? [])
+            add(mention, 'mention');
+        if (input.replyAuthor !== undefined)
+            add(input.replyAuthor, 'reply');
+        for (const recipient of input.recipients) {
+            if (incoming.some((item) => item.kind === 'listen' && same(item.listener, recipient)))
+                add(recipient, 'attention');
+        }
+    }
+    return audience;
+}

package/dist/boundary-presentation.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { withFileLock } from './file-lock.js';
 import { createArtifactPort } from './artifact.js';
 import { preparePendingPresentation } from './presentation-operations.js';
+import { presentPreparedBatch } from './delivery-effects.js';
 import { sessionInbox, projectBoundaryEligibility, pendingAtBoundary, pendingKey } from './inbox.js';
 import { attentionBodyIsClipped, renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
 export { pendingAtBoundary };
@@ -56,53 +57,45 @@ async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sess
     const artifacts = new Map();
     const claims = [];
     try {
-        // Claim the entire candidate batch before its one external effect. No later item needs
-        // a new claim (and new eligibility decision) after its bytes have already been rendered.
-        for (const entry of renderBoundary(pending).complete) {
-            const { location, seat } = entry.membership;
-            let artifact = artifacts.get(location);
-            if (artifact === undefined) {
-                // This boundary owns the connection until all effect evidence/cleanup has settled.
-                // Request cancellation travels with pre-effect operations, not that lifetime.
-                artifact = createArtifactPort(location);
-                artifacts.set(location, artifact);
-            }
-            for (const index of entry.actIndexes) {
-                const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
-                    activity: index, seat, markSeen: entry.markSeen, signal });
-                if (claim !== undefined)
-                    claims.push({ key: pendingKey(entry.membership, index), claim });
-            }
-        }
-        const eligible = new Set();
-        for (const { key, claim } of claims)
-            if (await claim.eligible())
-                eligible.add(key);
-        const fresh = renderBoundary(pending.map(membership => ({ ...membership,
-            notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.actIndex))),
-        })));
-        const included = new Set(fresh.complete.flatMap(entry => entry.actIndexes.map(index => pendingKey(entry.membership, index))));
-        if (included.size === 0 || signal?.aborted)
-            return undefined;
-        const rendered = claims.filter(({ key }) => included.has(key));
-        let result;
         try {
-            result = await present(fresh.context);
+            // Enumeration owns discovery/connections only; returned handles belong to the common runner.
+            for (const entry of renderBoundary(pending).complete) {
+                const { location, seat } = entry.membership;
+                let artifact = artifacts.get(location);
+                if (artifact === undefined) {
+                    // Keep connections alive through all signal-independent settlement/cleanup.
+                    artifact = createArtifactPort(location);
+                    artifacts.set(location, artifact);
+                }
+                for (const index of entry.actIndexes) {
+                    const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
+                        activity: index, seat, markSeen: entry.markSeen, signal });
+                    if (claim !== undefined)
+                        claims.push({ key: pendingKey(entry.membership, index), claim });
+                }
+            }
         }
         catch (error) {
-            await Promise.all(rendered.map(({ claim }) => claim.release('failed', error instanceof Error ? error.message : String(error))));
+            // Transfer has not happened: enumeration must abandon any custody already acquired.
+            await Promise.all(claims.map(({ claim }) => claim.release()));
             throw error;
         }
-        // These are successful sink effects, not fresh delivery attempts. Settle the entire
-        // rendered set before closing any connection, even if one member's settlement fails.
-        const settlements = await Promise.allSettled(rendered.map(({ claim }) => claim.recordPresented()));
-        for (const settlement of settlements)
-            if (settlement.status === 'rejected')
-                throw settlement.reason;
-        return result;
+        const report = await presentPreparedBatch(claims.map(({ claim }) => claim), eligibleClaims => {
+            const eligible = new Set(claims.filter(({ claim }) => eligibleClaims.includes(claim)).map(({ key }) => key));
+            const fresh = renderBoundary(pending.map(membership => ({ ...membership,
+                notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.actIndex))),
+            })));
+            const included = new Set(fresh.complete.flatMap(entry => entry.actIndexes.map(index => pendingKey(entry.membership, index))));
+            return { payload: fresh.context, included: claims.filter(({ key }) => included.has(key)).map(({ claim }) => claim) };
+        }, present, { signal, classifyError: () => 'failed' });
+        if (report.observation.kind === 'threw')
+            throw report.observation.error;
+        for (const { result } of report.settlements)
+            if (result.persistence.status === 'error')
+                throw result.persistence.error;
+        return report.observation.kind === 'returned' ? report.observation.value : undefined;
     }
     finally {
-        await Promise.all(claims.map(({ claim }) => claim.release()));
         await Promise.all([...artifacts.values()].map(artifact => artifact.close()));
     }
 }

package/dist/catch-decisions.d.ts

@@ -6,7 +6,6 @@ export interface CatchSelection {
     readonly activities: readonly PerceivedActivity[];
     readonly remaining: number;
     readonly standingCount: number;
-    readonly held: boolean;
     readonly deliveryAvailable: boolean;
     readonly now: number;
     readonly ownActivityCount: number;
@@ -15,7 +14,7 @@ export interface CatchSelection {
     readonly hint?: string;
 }
 /** Capture a selected page (or an empty completion) without opening another resource. */
-export declare function observeCatchSelection(facts: SquareRead, participant: string, activities: readonly StoredAct[], filter: DirectedFilter, at: number): CatchSelection;
+export declare function observeCatchSelection(facts: SquareRead, participant: string, activities: readonly StoredAct[], filter: DirectedFilter, at: number, remaining?: number): CatchSelection;
 export declare const CATCH_DEFAULT_LIMIT = 10;
 export declare const CATCH_MAX_LIMIT = 100;
 export declare function catchLimit(value: number | undefined): number;

package/dist/catch-decisions.js

@@ -4,15 +4,17 @@ import { SquareError } from './model.js';
 import { resolveKnownName } from './decisions.js';
 import { toPerceivedActivity } from './views.js';
 import { catchHint } from './hints.js';
+import { consumeReceived, ReceiveError, selectReceivedHeads } from './receive.js';
+import { squareReceiveRead } from './square-receive.js';
 /** Capture a selected page (or an empty completion) without opening another resource. */
-export function observeCatchSelection(facts, participant, activities, filter, at) {
+export function observeCatchSelection(facts, participant, activities, filter, at, remaining) {
     if (typeof at !== 'number' || !Number.isFinite(at))
         throw new SquareError('invalid_args', 'Catch time must be a finite number.');
     const counts = facts.participantCounts(), header = facts.header(), current = facts.participant(participant);
     return {
         participant, activities: activities.map(activity => toPerceivedActivity(facts, activity, participant)),
-        remaining: facts.directedCount(participant, filter),
-        standingCount: counts.joined, held: facts.hold().active, now: at,
+        remaining: remaining ?? facts.directedCount(participant, filter),
+        standingCount: counts.joined, now: at,
         deliveryAvailable: facts.seat(participant)?.wakeAddress !== undefined,
         ownActivityCount: current.sayCount, hardCap: header.hardCap,
         terminalStatus: terminalStatusFor(current, header.hardCap, counts),
@@ -27,19 +29,23 @@ export function catchLimit(value) {
     }
     return limit;
 }
-/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
-export function selectCatchPage(facts, requestedName, options) {
+function catchPageSelection(facts, requestedName, options) {
     const participant = resolveKnownName(facts, requestedName);
     const limit = catchLimit(options.limit);
-    const senders = options.from?.map((name) => resolveKnownName(facts, name));
+    const senders = options.from?.map(name => resolveKnownName(facts, name));
     const filter = { unseenOnly: true, ...(senders === undefined ? {} : { senders }), ...(options.mention === true ? { attentionOnly: true } : {}) };
-    return { participant, indexes: facts.directed(participant, filter, { edge: 'oldest', limit }).items.map((item) => item.index), filter };
+    return { participant, filter, selection: { kind: 'page', query: filter, limit } };
+}
+/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
+export function selectCatchPage(facts, requestedName, options) {
+    const { participant, filter, selection } = catchPageSelection(facts, requestedName, options);
+    return { participant, indexes: selectReceivedHeads(squareReceiveRead(facts), participant, selection).map(item => item.key), filter };
 }
 /** Selection, receipts and resulting cursor belong to one artifact write transaction. */
 export function decideCatch(facts, requestedName, options, at) {
     let viewer;
-    let delivered;
     let filter = { unseenOnly: true };
+    let selection;
     if (options.id !== undefined) {
         viewer = resolveKnownName(facts, requestedName);
         catchLimit(options.limit);
@@ -48,25 +54,39 @@ export function decideCatch(facts, requestedName, options, at) {
         const index = parseActivityId(options.id);
         if (index === undefined)
             throw new SquareError('invalid_args', 'Invalid catch id: expected an activity id like act/12.');
-        const activity = facts.activity(index);
-        if (activity === undefined || activity.kind !== 'say' || facts.directedAt(viewer, index) === undefined) {
-            throw new SquareError('invalid_args', `✕ ${formatActivityId(index)} isn't addressed to you`, {
-                reason: 'not_addressed', activityId: formatActivityId(index), activityExists: activity !== undefined,
-            });
-        }
-        delivered = [activity];
+        selection = { kind: 'exact', key: index, remainingQuery: filter };
     }
     else {
-        const page = selectCatchPage(facts, requestedName, options);
+        const page = catchPageSelection(facts, requestedName, options);
         viewer = page.participant;
         filter = page.filter;
-        delivered = facts.activities(page.indexes);
+        selection = page.selection;
+    }
+    let consumed;
+    try {
+        consumed = consumeReceived({
+            ...squareReceiveRead(facts),
+            insertReceipt: (ref, time) => facts.markSeen(ref.recipient, [ref.item], time) > 0,
+        }, viewer, selection, at);
+    }
+    catch (error) {
+        if ((error instanceof TypeError || error instanceof RangeError) && (typeof at !== 'number' || !Number.isFinite(at))) {
+            throw new SquareError('invalid_args', 'Invalid square artifact: row is malformed.');
+        }
+        if (!(error instanceof ReceiveError))
+            throw error;
+        if (error.code === 'missing_item')
+            throw new SquareError('invalid_args', 'Invalid square artifact: addressed activity is missing.');
+        const index = error.key;
+        throw new SquareError('invalid_args', `✕ ${formatActivityId(index)} isn't addressed to you`, {
+            reason: 'not_addressed', activityId: formatActivityId(index), activityExists: facts.activity(index) !== undefined,
+        });
     }
-    const marked = facts.markSeen(viewer, delivered.map((item) => item.index), at);
-    const selection = observeCatchSelection(facts, viewer, delivered, filter, at);
+    const delivered = consumed.items.map(item => item.data);
+    const observed = observeCatchSelection(facts, viewer, delivered, filter, at, consumed.remaining);
     // Receipts are the durable catch count: everything directed here minus what is still unseen.
     const caught = facts.directedCount(viewer, {}) - facts.directedCount(viewer, { unseenOnly: true });
     // An exact id catch is a targeted fetch and stays repeatable, so it carries no nudge.
-    const hint = options.id === undefined ? catchHint(caught - marked, caught) : undefined;
-    return hint === undefined ? selection : { ...selection, hint };
+    const hint = options.id === undefined ? catchHint(caught - consumed.newlyConsumed, caught) : undefined;
+    return hint === undefined ? observed : { ...observed, hint };
 }

package/dist/cli/context.js

@@ -99,8 +99,6 @@ const LOCATION_REQUIRED_COMMANDS = new Set([
     'unlisten',
     'listening',
     'done',
-    'hold',
-    'resume',
     'history',
     'status',
     'participants',

package/dist/cli/express-presentation.js

@@ -88,7 +88,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
         const selected = square === undefined ? undefined : await selectOwnSeat(square, owner, name).catch(() => undefined);
         const fresh = await square?.recovery(selected?.name ?? name).catch(() => undefined);
         name = fresh?.participant ?? name;
-        const output = { squarePath, name, owner: opts.recoveryOwner, draftPath, participantCount: fresh?.standingCount, held: fresh?.held };
+        const output = { squarePath, name, owner: opts.recoveryOwner, draftPath, participantCount: fresh?.standingCount };
         const confirmedUnsent = landedId === undefined && detail?.landedId === undefined
             && detail?.expressEffect !== 'landed' && detail?.expressEffect !== 'unknown'
             && (!attempted || detail?.expressEffect === 'unsent' || (isSquareError(error) && error.facts?.activityUnsent === true));
@@ -116,9 +116,9 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
                 exitCode(1);
                 return;
             }
-            if (error.code === 'held' || error.code === 'throttled') {
+            if (error.code === 'throttled') {
                 process.stdout.write(renderExpressNoWait({ ...output, reason: error.code, retryCommand: retryInput,
-                    delayMs: error.facts?.retryAfterMs ?? 1, holder: error.facts?.holder, holdReason: error.facts?.holdReason,
+                    delayMs: error.facts?.retryAfterMs ?? 1,
                 }));
                 exitCode(1);
                 return;

package/dist/cli/json.js

@@ -1,6 +1,6 @@
 export const JSON_COMMANDS = new Set([
     'join', 'express', 'catch', 'history', 'listen', 'ignore', 'unlisten', 'listening',
-    'hold', 'resume', 'done', 'status', 'participants', 'inbox',
+    'done', 'status', 'participants', 'inbox',
 ]);
 /** Serialize the SDK receipt, not its optional presentation or live participant handle. */
 export function jsonResult(result) {

package/dist/cli/program.js

@@ -17,7 +17,7 @@ async function handleSquareError(error, context) {
         process.stderr.write(`${lines.join('\n')}\n`);
     else
         process.stderr.write(formatRefusal(squarePath, lines, {
-            participantCount: recovery?.standingCount, held: recovery?.held,
+            participantCount: recovery?.standingCount,
         }));
     process.exit(error.code === 'not_found' ? 1 : 2);
 }

package/dist/cli/registry.js

@@ -1,4 +1,4 @@
-import { buildCommand, doneCommand, expressCommand, holdCommand, ignoreCommand, joinCommand, listenCommand, listeningCommand, resumeCommand, unlistenCommand } from './square-commands.js';
+import { buildCommand, doneCommand, expressCommand, ignoreCommand, joinCommand, listenCommand, listeningCommand, unlistenCommand } from './square-commands.js';
 import { doctorCommand, migrateCommand } from './maintenance-commands.js';
 import { harnessCommand, installCommand, uninstallCommand } from './harness-command.js';
 import { helpCommand, versionCommand } from './meta-commands.js';
@@ -21,8 +21,6 @@ export const commandRegistry = [
     { names: ['unlisten'], spec: unlistenCommand },
     { names: ['listening'], spec: listeningCommand },
     { names: ['done'], spec: doneCommand },
-    { names: ['hold'], spec: holdCommand },
-    { names: ['resume'], spec: resumeCommand },
     { names: ['install'], spec: installCommand },
     { names: ['uninstall'], spec: uninstallCommand },
     { names: ['harness'], spec: harnessCommand },

package/dist/cli/square-commands.d.ts

@@ -35,6 +35,4 @@ export declare const ignoreCommand: CommandSpec<ListenerIntent, string>;
 export declare const unlistenCommand: CommandSpec<ListenerIntent, string>;
 export declare const listeningCommand: CommandSpec<ListenerIntent, string>;
 export declare const doneCommand: CommandSpec<BodyIntent, string>;
-export declare const holdCommand: CommandSpec<BodyIntent, string>;
-export declare const resumeCommand: CommandSpec<BodyIntent, string>;
 export {};

package/dist/cli/square-commands.js

@@ -54,7 +54,7 @@ export const buildCommand = {
         const cap = data.hardCap === null ? 'unlimited' : formatHardCap(data.hardCap);
         const throttle = data.throttlePerMinute === undefined ? [] : [`  · throttle ${data.throttlePerMinute}/min`];
         return withPathOutput(square.location, ['· the square stands ready', `  · cap ${cap}`, ...throttle].join('\n'), {
-            participantCount: 0, held: false,
+            participantCount: 0,
         });
     },
     present: (result) => process.stdout.write(result),
@@ -182,29 +182,23 @@ export const listeningCommand = {
     },
     present: (result) => process.stdout.write(result),
 };
-function lifecycleCommand(verb) {
-    return {
-        parse(argv, context) {
-            const args = argv.filter((arg) => arg !== '--json');
-            if (args.length > (verb === 'resume' ? 0 : 1))
-                usage(context.command);
-            return { body: args[0] };
-        },
-        async execute(intent, context) {
-            const body = verb === 'hold' ? (await resolveBody(intent.body ?? '')).replace(/\r\n/g, '\n').trim()
-                : verb === 'done' && (intent.body === '-' || ((intent.body === undefined || intent.body === '') && !process.stdin.isTTY))
-                    ? await readStdin() : intent.body;
-            const squarePath = requireSquarePath(context);
-            const result = await withSquare(context, async (square) => {
-                const participant = await selectOwnSeat(square, commandIdentity(context.env, context.owner).owner, context.name);
-                const options = context.json ? {} : { observe: true };
-                return verb === 'resume' ? participant.resume(options) : participant[verb](body, options);
-            });
-            return context.json ? jsonResult(result) : renderLifecycleResult(squarePath, verb, result);
-        },
-        present: (result) => process.stdout.write(result),
-    };
-}
-export const doneCommand = lifecycleCommand('done');
-export const holdCommand = lifecycleCommand('hold');
-export const resumeCommand = lifecycleCommand('resume');
+export const doneCommand = {
+    parse(argv, context) {
+        const args = argv.filter((arg) => arg !== '--json');
+        if (args.length > 1)
+            usage(context.command);
+        return { body: args[0] };
+    },
+    async execute(intent, context) {
+        const body = intent.body === '-' || ((intent.body === undefined || intent.body === '') && !process.stdin.isTTY)
+            ? await readStdin() : intent.body;
+        const squarePath = requireSquarePath(context);
+        const result = await withSquare(context, async (square) => {
+            const participant = await selectOwnSeat(square, commandIdentity(context.env, context.owner).owner, context.name);
+            const options = context.json ? {} : { observe: true };
+            return participant.done(body, options);
+        });
+        return context.json ? jsonResult(result) : renderLifecycleResult(squarePath, result);
+    },
+    present: (result) => process.stdout.write(result),
+};

package/dist/decisions.d.ts

@@ -26,9 +26,6 @@ export type ActDecision = ({
 } | {
     type: 'throttled';
     delayMs: number;
-} | {
-    type: 'held';
-    reason: string | undefined;
 } | {
     type: 'bell_quota';
     nextAt: number;
@@ -52,8 +49,6 @@ export declare function coreListen(facts: SquareRead, actor: string, target: str
 export declare function coreIgnore(facts: SquareRead, actor: string, target: string, now: number): TimedAct<"listen" | "ignore" | "unlisten"> | undefined;
 export declare function coreUnlisten(facts: SquareRead, actor: string, target: string, now: number): TimedAct<"listen" | "ignore" | "unlisten"> | undefined;
 export declare function coreListening(facts: SquareRead, actor: string): readonly string[];
-export declare function coreHold(facts: SquareRead, actor: string, body: string, now: number): TimedAct<'hold'>;
-export declare function coreResume(facts: SquareRead, actor: string, now: number): TimedAct<'resume'>;
 export declare function compareParticipantActivity(a: Pick<ParticipantSummary, 'name' | 'lastActiveAt'>, b: Pick<ParticipantSummary, 'name' | 'lastActiveAt'>): number;
 export declare function coreParticipants(facts: SquareRead, now: number): ParticipantSummary[];
 export {};

package/dist/decisions.js

@@ -130,9 +130,6 @@ export function decideAct(facts, input) {
         throw activityRefusal('already_done', `${name} is already done`);
     if (!current.joined)
         throw activityRefusal('not_joined', `${name} has not joined this square`);
-    const hold = facts.hold();
-    if (hold.active)
-        return { type: 'held', reason: hold.reason };
     if (header.hardCap !== null && current.sayCount >= header.hardCap)
         return { type: 'capped', count: current.sayCount, hardCap: header.hardCap };
     if (reach === 'bell') {
@@ -185,16 +182,6 @@ export function coreListening(facts, actor) {
     const current = resolveStanding(facts, actor);
     return facts.attention(current.name).filter((item) => item.kind === 'listen').map((item) => item.target);
 }
-export function coreHold(facts, actor, body, now) {
-    const current = resolveStanding(facts, actor);
-    requireStanding(current);
-    return { kind: 'hold', actor: current.name, at: now, body: body.replace(/\r\n/g, '\n').trim() };
-}
-export function coreResume(facts, actor, now) {
-    const current = resolveStanding(facts, actor);
-    requireStanding(current);
-    return { kind: 'resume', actor: current.name, at: now };
-}
 export function compareParticipantActivity(a, b) {
     return (b.lastActiveAt ?? -Infinity) - (a.lastActiveAt ?? -Infinity) || a.name.localeCompare(b.name);
 }

package/dist/delivery-attempts.d.ts

@@ -0,0 +1,52 @@
+export type DeliveryPurpose = 'dispatch' | 'presentation';
+export type AttemptOutcome = 'dispatching' | 'accepted' | 'failed' | 'unknown' | 'released' | 'presented' | 'clipped';
+export interface Attempt<D> {
+    readonly purpose: DeliveryPurpose;
+    readonly token: string;
+    readonly ordinal: number;
+    readonly outcome: AttemptOutcome;
+    readonly at: number;
+    readonly expiresAt?: number;
+    readonly data: D;
+}
+/** One item/recipient/authority/purpose series, bound inside the caller's transaction.
+ * The caller owns token uniqueness, isolation and rollback; replacements retain coordinates.
+ */
+export interface AttemptRows<D> {
+    list(): readonly Attempt<D>[];
+    byToken(token: string): Attempt<D> | undefined;
+    insert(attempt: Attempt<D>): void;
+    replace(attempt: Attempt<D>): void;
+}
+export type AttemptClaim<D> = {
+    readonly status: 'acquired';
+    readonly token: string;
+    readonly ordinal: number;
+} | {
+    readonly status: 'busy' | 'terminal';
+    readonly evidence: Attempt<D>;
+    readonly interrupted?: true;
+};
+export declare function claimAttempt<D>(rows: AttemptRows<D>, input: {
+    purpose: DeliveryPurpose;
+    token: string;
+    at: number;
+    leaseMs: number;
+    data: D;
+}): AttemptClaim<D>;
+export declare function prepareAttempt<D>(rows: AttemptRows<D>, input: {
+    token: string;
+    data: D;
+}): boolean;
+export declare function settleAttempt<D>(rows: AttemptRows<D>, input: {
+    token: string;
+    outcome: Exclude<AttemptOutcome, 'dispatching'>;
+    at: number;
+    data: D;
+}): boolean;
+type Custody = Pick<Attempt<unknown>, 'purpose' | 'outcome' | 'expiresAt'>;
+/** Presentation custody suppresses dispatch independently of dispatch acceptance. */
+export declare function presentationBlocksDispatch(attempts: readonly Custody[], now: number): boolean;
+/** An expired dispatch is uncertain, not permission for automatic replay. */
+export declare function automaticDispatchEligible(attempts: readonly Custody[], now: number): boolean;
+export {};

package/dist/delivery-attempts.js

@@ -0,0 +1,73 @@
+function finite(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new RangeError('time must be finite');
+}
+function token(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new TypeError('token must be nonempty');
+}
+export function claimAttempt(rows, input) {
+    if (input.purpose !== 'dispatch' && input.purpose !== 'presentation')
+        throw new TypeError('unsupported purpose');
+    token(input.token);
+    finite(input.at);
+    if (!Number.isSafeInteger(input.leaseMs) || input.leaseMs <= 0)
+        throw new RangeError('leaseMs must be a positive safe integer');
+    const expiresAt = input.at + input.leaseMs;
+    finite(expiresAt);
+    const attempts = rows.list();
+    const terminal = attempts.find(row => row.outcome === 'unknown'
+        || row.outcome === (input.purpose === 'dispatch' ? 'accepted' : 'presented'));
+    if (terminal !== undefined)
+        return { status: 'terminal', evidence: terminal };
+    const dispatching = attempts.find(row => row.outcome === 'dispatching');
+    if (dispatching !== undefined) {
+        if (dispatching.expiresAt === undefined || dispatching.expiresAt > input.at)
+            return { status: 'busy', evidence: dispatching };
+        const { expiresAt: _expiry, ...previous } = dispatching;
+        const evidence = { ...previous, outcome: 'unknown', at: input.at };
+        rows.replace(evidence);
+        return { status: 'terminal', evidence, interrupted: true };
+    }
+    const ordinal = (attempts[0]?.ordinal ?? -1) + 1;
+    if (!Number.isSafeInteger(ordinal) || ordinal < 0)
+        throw new RangeError('attempt ordinal exhausted');
+    rows.insert({ purpose: input.purpose, token: input.token, ordinal, outcome: 'dispatching', at: input.at, expiresAt, data: input.data });
+    return { status: 'acquired', token: input.token, ordinal };
+}
+export function prepareAttempt(rows, input) {
+    token(input.token);
+    const previous = rows.byToken(input.token);
+    if (previous?.outcome !== 'dispatching')
+        return false;
+    rows.replace({ ...previous, data: input.data });
+    return true;
+}
+export function settleAttempt(rows, input) {
+    token(input.token);
+    finite(input.at);
+    if (!['accepted', 'failed', 'unknown', 'released', 'presented', 'clipped'].includes(input.outcome))
+        throw new TypeError('unsupported completion');
+    const previous = rows.byToken(input.token);
+    if (previous === undefined)
+        return false;
+    if (previous.outcome === 'accepted' && input.outcome === 'accepted')
+        return true;
+    if (previous.outcome !== 'dispatching' && !(previous.outcome === 'unknown' && input.outcome === 'accepted'))
+        return false;
+    const { expiresAt: _expiry, ...retained } = previous;
+    rows.replace({ ...retained, outcome: input.outcome, at: input.at, data: input.data });
+    return true;
+}
+/** Presentation custody suppresses dispatch independently of dispatch acceptance. */
+export function presentationBlocksDispatch(attempts, now) {
+    finite(now);
+    return attempts.some(row => row.purpose === 'presentation'
+        && (row.outcome === 'presented' || row.outcome === 'clipped' || row.outcome === 'unknown'
+            || row.outcome === 'dispatching' && (row.expiresAt === undefined || row.expiresAt > now)));
+}
+/** An expired dispatch is uncertain, not permission for automatic replay. */
+export function automaticDispatchEligible(attempts, now) {
+    return !presentationBlocksDispatch(attempts, now) && !attempts.some(row => row.purpose === 'dispatch'
+        && (row.outcome === 'accepted' || row.outcome === 'unknown' || row.outcome === 'dispatching'));
+}