@astrosheep/square 0.4.0 → 0.4.1

package/dist/cmd/notify-once.js

@@ -1,29 +0,0 @@
-#!/usr/bin/env node
-import { resolve } from 'node:path';
-import { setTimeout as sleep } from 'node:timers/promises';
-import { processActNotificationsOnce, wakeGraceMs } from '../notifications.js';
-function args(argv) {
-    let squarePath;
-    let actIndex;
-    for (let index = 0; index < argv.length; index += 1) {
-        if (argv[index] === '--location' && argv[index + 1] !== undefined)
-            squarePath = resolve(argv[++index]);
-        else if (argv[index] === '--act-index' && /^\d+$/.test(argv[index + 1] ?? ''))
-            actIndex = Number(argv[++index]);
-        else
-            throw new Error(`Unknown notify-once argument: ${argv[index]}`);
-    }
-    if (squarePath === undefined || actIndex === undefined)
-        throw new Error('notify-once requires --location and --act-index.');
-    return { squarePath, actIndex };
-}
-async function main() {
-    if (process.env.SQUARE_DISABLE_PASEO_WAKE === '1')
-        return;
-    const { squarePath, actIndex } = args(process.argv.slice(2));
-    await sleep(wakeGraceMs());
-    await processActNotificationsOnce(squarePath, actIndex);
-}
-main().catch(() => {
-    process.exitCode = 0;
-});

package/dist/delivery-attempts.d.ts

@@ -1,52 +0,0 @@
-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

@@ -1,73 +0,0 @@
-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'));
-}
-/** 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'));
-}

package/dist/delivery-effects.d.ts

@@ -1,139 +0,0 @@
-export interface EffectClaim {
-    readonly token: string;
-    readonly ordinal: number;
-}
-/** Bound to one captured item/recipient/authority/purpose, not an encoded series key. */
-export interface EffectPort<C> {
-    /** The caller's existing atomic claim operation. Undefined means no custody acquired. */
-    claim(signal?: AbortSignal): Promise<EffectClaim | undefined>;
-    /** Pre-effect policy only. Rejection means unverifiable/not current. */
-    current(signal?: AbortSignal): Promise<boolean>;
-    /**
-     * No request signal: persistence has its own bounded lifetime. For presentation,
-     * `presented` MUST complete the attempt and record ALL captured full-consumption
-     * receipts in ONE atomic transaction (rollback both on error). `clipped`, `failed`,
-     * `unknown` and `released` complete the attempt without full-consumption receipts.
-     * No post-effect currentness/deferral/cancellation veto; captured authority still fences.
-     */
-    settle(claim: EffectClaim, completion: C): Promise<boolean>;
-}
-export type Persistence = {
-    readonly status: 'recorded';
-} | {
-    readonly status: 'not-recorded';
-} | {
-    readonly status: 'error';
-    readonly error: unknown;
-};
-export interface Settlement<C> {
-    readonly completion: C;
-    readonly persistence: Persistence;
-}
-export interface DispatchOutcome {
-    readonly outcome: 'accepted' | 'failed' | 'unknown' | 'not-capable';
-    readonly data?: unknown;
-}
-export type DispatchCompletion = {
-    readonly outcome: 'accepted' | 'failed' | 'unknown';
-    readonly reason: 'returned';
-    readonly data?: unknown;
-} | {
-    readonly outcome: 'unknown';
-    readonly reason: 'threw';
-    readonly error: unknown;
-} | {
-    readonly outcome: 'unknown';
-    readonly reason: 'timeout';
-} | {
-    readonly outcome: 'released';
-    readonly reason: 'not-current';
-    readonly phase: 'initial' | 'final';
-} | {
-    readonly outcome: 'released';
-    readonly reason: 'not-capable';
-    readonly data?: unknown;
-} | {
-    readonly outcome: 'released';
-    readonly reason: 'cancelled';
-};
-export interface DispatchContext {
-    readonly claim: EffectClaim;
-    readonly timeoutMs: number;
-    readonly deadline: number;
-    readonly signal?: AbortSignal;
-    /** Policy only. Sender MUST recheck deadline/cancellation after this await before I/O. */
-    beforeSend(): Promise<boolean>;
-}
-export interface DispatchReport {
-    readonly observation: {
-        readonly kind: 'not-invoked';
-    } | {
-        readonly kind: 'returned';
-        readonly result: DispatchOutcome;
-    } | {
-        readonly kind: 'threw';
-        readonly error: unknown;
-    } | {
-        readonly kind: 'timeout';
-    };
-    readonly settlement?: Settlement<DispatchCompletion>;
-}
-/** Timer bounds the external attempt only, not claim/currentness/persistence. No automatic retry. */
-export declare function dispatchEffect(port: EffectPort<DispatchCompletion>, send: (context: DispatchContext) => Promise<DispatchOutcome>, options: {
-    readonly timeoutMs: number;
-    readonly signal?: AbortSignal;
-}): Promise<DispatchReport>;
-export type PresentationCompletion = {
-    readonly outcome: 'presented' | 'clipped';
-    readonly reason: 'returned';
-} | {
-    readonly outcome: 'failed' | 'unknown';
-    readonly reason: 'threw';
-    readonly error: unknown;
-} | {
-    readonly outcome: 'released';
-    readonly reason: 'not-current' | 'cancelled' | 'unused';
-};
-export interface PresentationWork<P> {
-    readonly payload: P;
-    readonly coverage: 'full' | 'clipped';
-    readonly port: EffectPort<PresentationCompletion>;
-}
-declare const preparedBrand: unique symbol;
-export interface PreparedPresentation<P> {
-    readonly [preparedBrand]: true;
-    readonly payload: P;
-    eligible(signal?: AbortSignal): Promise<boolean>;
-    release(): Promise<Settlement<PresentationCompletion>>;
-}
-export interface PresentationControl {
-    readonly signal?: AbortSignal;
-    /** Default unknown; throwing or invalid classifiers also stay unknown. */
-    readonly classifyError?: (error: unknown) => 'failed' | 'unknown';
-}
-export interface PresentationReport<P, R> {
-    readonly observation: {
-        readonly kind: 'not-invoked';
-    } | {
-        readonly kind: 'returned';
-        readonly value: R;
-    } | {
-        readonly kind: 'threw';
-        readonly error: unknown;
-        readonly outcome: 'failed' | 'unknown';
-    };
-    readonly settlements: readonly {
-        readonly prepared: PreparedPresentation<P>;
-        readonly result: Settlement<PresentationCompletion>;
-    }[];
-}
-export declare function preparePresentation<P>(work: PresentationWork<P>, control?: {
-    readonly signal?: AbortSignal;
-}): Promise<PreparedPresentation<P> | undefined>;
-export declare function presentPrepared<P, R>(prepared: PreparedPresentation<P>, sink: (payload: P) => R | Promise<R>, control?: PresentationControl): Promise<PresentationReport<P, R>>;
-/** Takes all local custody synchronously, then owns eligibility/effect/settlement/cleanup. */
-export declare function presentPreparedBatch<P, B, R>(prepared: readonly PreparedPresentation<P>[], render: (eligible: readonly PreparedPresentation<P>[]) => {
-    readonly payload: B;
-    readonly included: readonly PreparedPresentation<P>[];
-}, sink: (payload: B) => R | Promise<R>, control?: PresentationControl): Promise<PresentationReport<P, R>>;
-export {};

package/dist/delivery-effects.js

@@ -1,163 +0,0 @@
-async function settle(port, claim, completion) {
-    try {
-        return { completion, persistence: { status: await port.settle(claim, completion) ? 'recorded' : 'not-recorded' } };
-    }
-    catch (error) {
-        return { completion, persistence: { status: 'error', error } };
-    }
-}
-async function current(port, signal) {
-    try {
-        return await port.current(signal);
-    }
-    catch {
-        return false;
-    }
-}
-/** Timer bounds the external attempt only, not claim/currentness/persistence. No automatic retry. */
-export async function dispatchEffect(port, send, options) {
-    const notInvoked = { kind: 'not-invoked' };
-    if (options.signal?.aborted)
-        return { observation: notInvoked };
-    const claim = await port.claim(options.signal);
-    if (claim === undefined)
-        return { observation: notInvoked };
-    if (!await current(port, options.signal))
-        return { observation: notInvoked,
-            settlement: await settle(port, claim, { outcome: 'released', reason: 'not-current', phase: 'initial' }) };
-    if (options.signal?.aborted)
-        return { observation: notInvoked,
-            settlement: await settle(port, claim, { outcome: 'released', reason: 'cancelled' }) };
-    let denied = false;
-    let timer;
-    const deadline = Date.now() + options.timeoutMs;
-    const timeout = new Promise(resolve => {
-        timer = setTimeout(() => resolve({ kind: 'timeout' }), options.timeoutMs);
-    });
-    let observation;
-    let completion;
-    try {
-        observation = await Promise.race([timeout, (async () => {
-                try {
-                    return { kind: 'returned', result: await send({ claim, deadline, ...options,
-                            beforeSend: async () => {
-                                const allowed = await current(port, options.signal);
-                                if (!allowed)
-                                    denied = true;
-                                return allowed;
-                            },
-                        }) };
-                }
-                catch (error) {
-                    return { kind: 'threw', error };
-                }
-            })()]);
-        // Freeze before persistence. Late policy results/sender completions cannot rewrite it.
-        completion = observation.kind === 'timeout' ? { outcome: 'unknown', reason: 'timeout' }
-            : denied ? { outcome: 'released', reason: 'not-current', phase: 'final' }
-                : observation.kind === 'threw' ? { outcome: 'unknown', reason: 'threw', error: observation.error }
-                    : observation.result.outcome === 'not-capable'
-                        ? { outcome: 'released', reason: 'not-capable', data: observation.result.data }
-                        : { outcome: observation.result.outcome, reason: 'returned', data: observation.result.data };
-    }
-    finally {
-        if (timer !== undefined)
-            clearTimeout(timer);
-    }
-    return { observation, settlement: await settle(port, claim, completion) };
-}
-const preparedBrand = Symbol('prepared presentation');
-const custody = new WeakMap();
-export async function preparePresentation(work, control) {
-    if (control?.signal?.aborted)
-        return undefined;
-    const claim = await work.port.claim(control?.signal);
-    if (claim === undefined)
-        return undefined;
-    let resolve;
-    let decided = false;
-    const state = {
-        owned: false, coverage: work.coverage,
-        eligible: signal => signal?.aborted ? Promise.resolve(false) : current(work.port, signal),
-        done: new Promise(res => { resolve = res; }),
-        finish(completion) {
-            if (decided)
-                return;
-            decided = true;
-            // Defer callbacks: every included handle is marked before any settlement starts.
-            void Promise.resolve().then(() => settle(work.port, claim, completion)).then(resolve);
-        },
-    };
-    const prepared = Object.freeze({
-        [preparedBrand]: true,
-        payload: work.payload,
-        eligible: (signal) => state.owned ? Promise.resolve(false) : state.eligible(signal),
-        release() {
-            if (!state.owned) {
-                state.owned = true;
-                state.finish({ outcome: 'released', reason: 'unused' });
-            }
-            return state.done;
-        },
-    });
-    custody.set(prepared, state);
-    return prepared;
-}
-export function presentPrepared(prepared, sink, control) {
-    return presentPreparedBatch([prepared], eligible => ({ payload: prepared.payload, included: eligible }), sink, control);
-}
-/** Takes all local custody synchronously, then owns eligibility/effect/settlement/cleanup. */
-export async function presentPreparedBatch(prepared, render, sink, control = {}) {
-    const handles = [...prepared];
-    const states = handles.map(handle => custody.get(handle));
-    if (new Set(handles).size !== handles.length || states.some(state => state === undefined || state.owned)) {
-        await Promise.all([...new Set(handles)].filter(handle => custody.has(handle) && !custody.get(handle).owned).map(handle => handle.release()));
-        throw new TypeError('Presentation requires unique, unused prepared custody.');
-    }
-    const owned = states;
-    for (const state of owned)
-        state.owned = true;
-    let observation = { kind: 'not-invoked' };
-    try {
-        const eligible = [];
-        for (const [index, state] of owned.entries()) {
-            if (await state.eligible(control.signal))
-                eligible.push(handles[index]);
-            else
-                state.finish({ outcome: 'released', reason: control.signal?.aborted ? 'cancelled' : 'not-current' });
-        }
-        const rendered = render(Object.freeze(eligible));
-        const included = [...rendered.included];
-        if (new Set(included).size !== included.length || included.some(handle => !eligible.includes(handle)))
-            throw new TypeError('Included presentations must be a unique subset of eligible custody.');
-        if (included.length > 0 && !control.signal?.aborted) {
-            let completion;
-            try {
-                const value = await sink(rendered.payload);
-                observation = { kind: 'returned', value };
-                completion = { outcome: 'presented', reason: 'returned' };
-            }
-            catch (error) {
-                let outcome = 'unknown';
-                try {
-                    if (control.classifyError?.(error) === 'failed')
-                        outcome = 'failed';
-                }
-                catch { /* conservative */ }
-                observation = { kind: 'threw', error, outcome };
-                completion = { outcome, reason: 'threw', error };
-            }
-            for (const handle of included) {
-                const state = custody.get(handle);
-                state.finish(completion.outcome === 'presented'
-                    ? { outcome: state.coverage === 'full' ? 'presented' : 'clipped', reason: 'returned' } : completion);
-            }
-        }
-    }
-    finally {
-        for (const state of owned)
-            state.finish({ outcome: 'released', reason: control.signal?.aborted ? 'cancelled' : 'unused' });
-        await Promise.all(owned.map(state => state.done));
-    }
-    return { observation, settlements: await Promise.all(handles.map(async (handle, index) => ({ prepared: handle, result: await owned[index].done }))) };
-}

package/dist/delivery-health.d.ts

@@ -1,51 +0,0 @@
-import { type DirectedNotificationRoute } from './delivery.js';
-import type { DeliveryEvidence } from './ports.js';
-export interface WakeAttempt {
-    readonly nativeObservations?: readonly NonNullable<DeliveryEvidence['nativeObservations']>[number][];
-    readonly at: number;
-    readonly attention: {
-        readonly squarePath: string;
-        readonly recipient: string;
-        readonly messageIndex: number;
-    };
-    readonly routeKind: import('./model.js').WakeRouteKind;
-    readonly outcome: 'accepted' | 'unknown' | 'failed';
-    readonly signature?: string;
-    readonly attemptN: number;
-    readonly message?: string;
-    readonly diagnostic?: unknown;
-}
-export interface WakeReleaseDiagnostic {
-    readonly at: number;
-    readonly attention: {
-        readonly squarePath: string;
-        readonly recipient: string;
-        readonly messageIndex: number;
-    };
-    readonly routeKind?: import('./model.js').WakeRouteKind;
-    readonly attemptN?: number;
-    readonly session?: string;
-    readonly signature?: string;
-    readonly message?: string;
-    readonly diagnostic?: unknown;
-}
-export type DeliveryHealthKind = 'awaiting' | 'wake-accepted' | 'wake-unknown' | 'presented-not-delivered' | 'unreachable';
-export interface DeliveryHealthItem {
-    squarePath: string;
-    recipient: string;
-    messageIndex: number;
-    actor: string;
-    at: number;
-    ageMs: number;
-    route?: DirectedNotificationRoute;
-    kind: DeliveryHealthKind;
-    attempt?: WakeAttempt;
-}
-/** Classify current pending attention from the artifact's seats and delivery evidence. */
-export declare function classifyDeliveryHealth(squarePath: string, opts: {
-    graceMs: number;
-    now?: number;
-    env?: NodeJS.ProcessEnv;
-}): Promise<DeliveryHealthItem[]>;
-export declare function renderDeliveryHealth(items: readonly DeliveryHealthItem[], releases?: readonly WakeReleaseDiagnostic[], now?: number, nativeAttempts?: readonly WakeAttempt[]): string[];
-export declare function doctorDeliveryHealth(squarePath: string, graceMs: number, now?: number, env?: NodeJS.ProcessEnv): Promise<string[]>;