@astrosheep/square 0.3.106 → 0.4.1

package/dist/model.d.ts

@@ -1,33 +1,16 @@
 import type { Act, ActivityId } from './square-core.js';
-export { formatActivityId, parseActivityId } from './square-core.js';
+import type { Owner } from './neutral.js';
+import type { WakeAddress } from './square-values.js';
+export { WAKE_ROUTE_KINDS, MESSAGE_METADATA_MAX_BYTES as ACTIVITY_METADATA_MAX_BYTES, MESSAGE_METADATA_MAX_DEPTH as ACTIVITY_METADATA_MAX_DEPTH, validateMessageMetadata as validateActivityMetadata, messageMetadataHasContent as activityMetadataHasContent, isWakeRouteKind, sameName, NAME_GRAPHEME_SOURCE, validateName } from './square-values.js';
+export type { WakeRouteKind, JsonValue, MessageMetadata as ActivityMetadata, WakeAddress, WakeRoute } from './square-values.js';
+export { SquareErrorBase, SquareError, InternalSquareError, isSquareError, validateOwner, nameKey } from './neutral.js';
+export type { Owner, SquareErrorCode, InternalSquareErrorCode, SquareErrorFacts } from './neutral.js';
 export type { Act, ActivityId, Audience, Reach } from './square-core.js';
-export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo", "http"];
-export type WakeRouteKind = typeof WAKE_ROUTE_KINDS[number];
-export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
-    readonly [key: string]: JsonValue;
-};
-export type ActivityMetadata = Readonly<Record<string, JsonValue>>;
-export interface ActivityDelivery {
-    readonly mode: 'direct';
-    readonly preview?: string;
-}
-export declare function validateActivityDelivery(value: unknown): ActivityDelivery | undefined;
-export declare const ACTIVITY_METADATA_MAX_BYTES: number;
-export declare const ACTIVITY_METADATA_MAX_DEPTH = 256;
-/** Validate the bounded, lossless JSON object carried by a say. */
-export declare function validateActivityMetadata(value: unknown): ActivityMetadata | undefined;
-export declare function activityMetadataHasContent(metadata: ActivityMetadata | undefined): boolean;
-/** Opaque custody identity. Harness coordinates are adapter-owned. */
-export type Owner = string;
-export interface WakeAddress {
-    readonly kind: WakeRouteKind;
-    readonly address: Readonly<Record<string, string>>;
-}
 /** Artifact-owned custody binding. Generation is the join activity that established it. */
 export interface Seat {
     readonly participant: string;
     readonly owner: Owner;
-    readonly generation: ActivityId;
+    readonly generation: string;
     readonly attachment: 'attached' | 'detached';
     readonly wakeAddress?: WakeAddress;
 }
@@ -35,48 +18,6 @@ export interface SeatWatchLease {
     readonly generation: ActivityId;
     readonly lease: WatchLease;
 }
-export declare function validateOwner(owner: Owner): Owner;
-export declare function isWakeRouteKind(value: unknown): value is WakeRouteKind;
-export interface WakeRoute {
-    /** Ownership generation, when the receiver publishes a fenced route. */
-    epoch?: number;
-    location: string;
-    participant: string;
-    kind: WakeRouteKind;
-    address: Record<string, string>;
-    updatedAt: number;
-}
-export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
-export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
-export interface SquareErrorFacts {
-    /** Copyable recovery for a missing, detached or foreign seat. */
-    join?: string;
-    /** Express admission rejected before any activity was committed. */
-    activityUnsent?: true;
-    /** Refusal reason, including absent participants, conflicting reach, and inaccessible activities. */
-    reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'invalid_reply' | 'invalid_done_body' | 'needs_seat';
-    /** The activity id a `catch --id` refusal named. */
-    activityId?: string;
-    /** The host ledger requiring offline migration, rather than the selected artifact. */
-    ledgerRoot?: string;
-    /** Requested recipient spellings, without parsing presentation copy. */
-    targets?: readonly string[];
-    /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */
-    activityExists?: boolean;
-    pending?: number;
-    retryAfterMs?: number;
-}
-declare class SquareErrorBase<Code extends string> extends Error {
-    code: Code;
-    facts?: SquareErrorFacts | undefined;
-    operation?: import('./square-facade.js').OperationFailureDetail;
-    constructor(code: Code, message: string, facts?: SquareErrorFacts | undefined);
-}
-export declare class SquareError extends SquareErrorBase<SquareErrorCode> {
-}
-export declare class InternalSquareError extends SquareErrorBase<InternalSquareErrorCode> {
-}
-export declare function isSquareError(error: unknown): error is SquareError | InternalSquareError;
 export type HardCap = number | null;
 export interface BuildOptions {
     force: boolean;
@@ -84,10 +25,16 @@ export interface BuildOptions {
     template?: string;
     throttlePerMinute?: number;
 }
+/** An upper publication draft: content and social facts before any index exists. */
+export type ActDraft = Act & {
+    at: number;
+};
+/** A landed activity owns its content and social facts. */
 export type StoredAct = Act & {
     index: number;
     at: number;
 };
+export type HydratedAct = StoredAct;
 export type ObservationState = 'seen';
 export interface ActivityObservation {
     state: ObservationState;
@@ -104,39 +51,16 @@ export interface WatchLease {
     filter?: WatchLeaseFilter;
 }
 export type DirectedNotificationRoute = import('./attention.js').AudienceRoute;
-export interface InboxNotification {
-    actIndex: number;
-    actor: string;
-    at: number;
-    route: DirectedNotificationRoute;
-    body: string;
-    readonly delivery?: ActivityDelivery;
-}
-export interface LocatedSeat {
-    readonly location: string;
-    readonly seat: Seat;
-    readonly joinedAt: number;
-}
-export interface PendingMembership extends LocatedSeat {
-    readonly notifications: InboxNotification[];
-    readonly catchLease?: WatchLease;
-    readonly deliveryDeferralExpiry?: number;
-}
 export interface WatchOptions {
     participants?: string[];
     mention?: string;
     replace?: boolean;
 }
-export type PublicAct = Extract<StoredAct, {
+export type PublicAct = Extract<HydratedAct, {
     kind: 'say' | 'done';
 }>;
-export type RoomChangeAct = Extract<StoredAct, {
+export type RoomChangeAct = Extract<HydratedAct, {
     kind: 'join' | 'done' | 'listen' | 'ignore' | 'unlisten';
 }>;
 export declare function formatHardCap(hardCap: HardCap): string;
 export declare function parseParticipantList(value: string): string[];
-export declare function nameKey(name: string): string;
-export declare function sameName(a: string, b: string): boolean;
-/** One name grapheme: Unicode letters, digits, marks, hyphens, or underscores (no isolated variation selectors), or a complete RGI emoji. Shared by name validation and body @mention scanning. */
-export declare const NAME_GRAPHEME_SOURCE: string;
-export declare function validateName(name: string): void;

package/dist/model.js

@@ -1,127 +1,6 @@
 // Shared model and constants for Square.
-export { formatActivityId, parseActivityId } from './square-core.js';
-export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo', 'http'];
-export function validateActivityDelivery(value) {
-    if (value === undefined)
-        return undefined;
-    if (value !== null && typeof value === 'object'
-        && [Object.prototype, null].includes(Object.getPrototypeOf(value))
-        && Object.getOwnPropertySymbols(value).length === 0) {
-        const keys = Object.getOwnPropertyNames(value);
-        const mode = Object.getOwnPropertyDescriptor(value, 'mode');
-        const preview = Object.getOwnPropertyDescriptor(value, 'preview');
-        if (mode?.enumerable && 'value' in mode && mode.value === 'direct') {
-            if (keys.length === 1)
-                return { mode: 'direct' };
-            if (keys.length === 2 && preview?.enumerable && 'value' in preview
-                && typeof preview.value === 'string' && preview.value.trim() !== '')
-                return { mode: 'direct', preview: preview.value };
-        }
-    }
-    throw new SquareError('invalid_args', "Activity delivery must be { mode: 'direct', preview?: string }.");
-}
-export const ACTIVITY_METADATA_MAX_BYTES = 16 * 1024;
-export const ACTIVITY_METADATA_MAX_DEPTH = 256;
-/** Validate the bounded, lossless JSON object carried by a say. */
-export function validateActivityMetadata(value) {
-    if (value === undefined)
-        return undefined;
-    if (value === null || typeof value !== 'object' || Array.isArray(value))
-        throw new SquareError('invalid_args', 'Activity metadata must be a non-null JSON object.');
-    const visiting = new Set();
-    const stack = [{ value, depth: 0 }];
-    while (stack.length > 0) {
-        const frame = stack.pop();
-        if (frame.exit !== undefined) {
-            visiting.delete(frame.exit);
-            continue;
-        }
-        const item = frame.value;
-        if (item === null || typeof item === 'boolean' || typeof item === 'string')
-            continue;
-        if (typeof item === 'number') {
-            if (!Number.isFinite(item))
-                throw new SquareError('invalid_args', 'Activity metadata must contain only finite JSON values.');
-            continue;
-        }
-        if (typeof item !== 'object')
-            throw new SquareError('invalid_args', 'Activity metadata must contain only JSON values.');
-        if (frame.depth > ACTIVITY_METADATA_MAX_DEPTH)
-            throw new SquareError('invalid_args', `Activity metadata nesting cannot exceed ${ACTIVITY_METADATA_MAX_DEPTH} levels.`);
-        if (visiting.has(item))
-            throw new SquareError('invalid_args', 'Activity metadata cannot contain a cycle.');
-        visiting.add(item);
-        stack.push({ value: item, depth: frame.depth, exit: item });
-        if (Array.isArray(item)) {
-            if (Object.getOwnPropertySymbols(item).length > 0 || Object.keys(item).length !== item.length)
-                throw new SquareError('invalid_args', 'Activity metadata arrays must be dense JSON arrays.');
-            const names = Object.getOwnPropertyNames(item);
-            if (names.some(name => name !== 'length' && (!/^(0|[1-9]\d*)$/.test(name) || Number(name) >= item.length)))
-                throw new SquareError('invalid_args', 'Activity metadata arrays must contain only indexed values.');
-            for (const key of Object.keys(item).reverse()) {
-                const descriptor = Object.getOwnPropertyDescriptor(item, key);
-                if (descriptor === undefined || !('value' in descriptor))
-                    throw new SquareError('invalid_args', 'Activity metadata cannot contain accessors.');
-                stack.push({ value: descriptor.value, depth: frame.depth + 1 });
-            }
-            continue;
-        }
-        const prototype = Object.getPrototypeOf(item);
-        if (prototype !== Object.prototype && prototype !== null)
-            throw new SquareError('invalid_args', 'Activity metadata must contain only plain JSON objects.');
-        if (Object.getOwnPropertySymbols(item).length > 0)
-            throw new SquareError('invalid_args', 'Activity metadata cannot contain symbol keys.');
-        const names = Object.getOwnPropertyNames(item);
-        if (names.some(name => !Object.prototype.propertyIsEnumerable.call(item, name)))
-            throw new SquareError('invalid_args', 'Activity metadata cannot contain non-enumerable properties.');
-        for (const name of names.reverse()) {
-            const descriptor = Object.getOwnPropertyDescriptor(item, name);
-            if (!('value' in descriptor))
-                throw new SquareError('invalid_args', 'Activity metadata cannot contain accessors.');
-            stack.push({ value: descriptor.value, depth: frame.depth + 1 });
-        }
-    }
-    let serialized;
-    try {
-        serialized = JSON.stringify(value);
-    }
-    catch {
-        throw new SquareError('invalid_args', 'Activity metadata must contain only lossless JSON values.');
-    }
-    if (serialized === undefined || Buffer.byteLength(serialized, 'utf8') > ACTIVITY_METADATA_MAX_BYTES)
-        throw new SquareError('invalid_args', `Activity metadata cannot exceed ${ACTIVITY_METADATA_MAX_BYTES} UTF-8 bytes.`);
-    return value;
-}
-export function activityMetadataHasContent(metadata) {
-    return metadata !== undefined && Object.keys(metadata).length > 0;
-}
-export function validateOwner(owner) {
-    if (typeof owner !== 'string' || !owner || Buffer.byteLength(owner, 'utf8') > 512 || /[\u0000-\u001f\u007f-\u009f]/u.test(owner)) {
-        throw new SquareError('invalid_args', 'A participant write requires a non-empty owner without control characters (at most 512 UTF-8 bytes).');
-    }
-    return owner;
-}
-export function isWakeRouteKind(value) {
-    return typeof value === 'string' && WAKE_ROUTE_KINDS.includes(value);
-}
-class SquareErrorBase extends Error {
-    code;
-    facts;
-    operation;
-    constructor(code, message, facts) {
-        super(message);
-        this.code = code;
-        this.facts = facts;
-        this.name = 'SquareError';
-    }
-}
-export class SquareError extends SquareErrorBase {
-}
-export class InternalSquareError extends SquareErrorBase {
-}
-export function isSquareError(error) {
-    return error instanceof SquareError || error instanceof InternalSquareError;
-}
+export { WAKE_ROUTE_KINDS, MESSAGE_METADATA_MAX_BYTES as ACTIVITY_METADATA_MAX_BYTES, MESSAGE_METADATA_MAX_DEPTH as ACTIVITY_METADATA_MAX_DEPTH, validateMessageMetadata as validateActivityMetadata, messageMetadataHasContent as activityMetadataHasContent, isWakeRouteKind, sameName, NAME_GRAPHEME_SOURCE, validateName } from './square-values.js';
+export { SquareErrorBase, SquareError, InternalSquareError, isSquareError, validateOwner, nameKey } from './neutral.js';
 export function formatHardCap(hardCap) {
     return hardCap === null ? '-1' : String(hardCap);
 }
@@ -131,20 +10,3 @@ export function parseParticipantList(value) {
         .map((name) => name.trim())
         .filter(Boolean);
 }
-export function nameKey(name) {
-    return name.toLocaleLowerCase();
-}
-export function sameName(a, b) {
-    return nameKey(a) === nameKey(b);
-}
-const TEXT_NAME_GRAPHEME_SOURCE = String.raw `[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]`;
-/** One name grapheme: Unicode letters, digits, marks, hyphens, or underscores (no isolated variation selectors), or a complete RGI emoji. Shared by name validation and body @mention scanning. */
-export const NAME_GRAPHEME_SOURCE = String.raw `${TEXT_NAME_GRAPHEME_SOURCE}|\p{RGI_Emoji}`;
-// Ordinary Unicode names need not trigger the full RGI emoji matcher’s cold compilation.
-const TEXT_NAME_PATTERN = new RegExp(`^(?:${TEXT_NAME_GRAPHEME_SOURCE})+(?:/(?:${TEXT_NAME_GRAPHEME_SOURCE})+)*$`, 'v');
-const NAME_PATTERN = new RegExp(`^(?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*$`, 'v');
-export function validateName(name) {
-    if (!name || (!TEXT_NAME_PATTERN.test(name) && !NAME_PATTERN.test(name))) {
-        throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using Unicode letters, digits, marks, hyphens, underscores, or complete RGI emoji graphemes.');
-    }
-}

package/dist/neutral.d.ts

@@ -0,0 +1,72 @@
+/** Shared identity, error and paging types used below both Channel and Agora. */
+export type Owner = string;
+export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
+export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
+export interface SquareErrorFacts {
+    /** Copyable recovery for a missing, detached or foreign seat. */
+    join?: string;
+    /** Express admission rejected before any activity was committed. */
+    activityUnsent?: true;
+    /** Refusal reason, including absent participants, conflicting reach, and inaccessible activities. */
+    reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'invalid_reply' | 'invalid_done_body' | 'needs_seat';
+    /** The activity id a `catch --id` refusal named. */
+    activityId?: string;
+    /** Requested recipient spellings, without parsing presentation copy. */
+    targets?: readonly string[];
+    /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */
+    activityExists?: boolean;
+    pending?: number;
+    retryAfterMs?: number;
+}
+export interface CatchWaitStart {
+    readonly idleMs: number;
+    readonly replacementRequested: boolean;
+    readonly replaced: boolean;
+}
+export type OperationProgress = {
+    readonly kind: 'waiting';
+    readonly reason: 'throttled';
+    readonly delayMs?: number;
+} | ({
+    readonly kind: 'catch-started';
+    readonly participant: string;
+} & CatchWaitStart);
+export interface OperationControl {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: OperationProgress) => void;
+}
+export interface OperationFailureDetail {
+    readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
+    readonly subject?: 'caller' | 'filter' | 'recipient';
+    readonly participant?: string;
+    readonly expressEffect?: 'unsent' | 'landed' | 'unknown';
+    readonly landedId?: string;
+    readonly historyBounds?: {
+        readonly maxLimit: number;
+        readonly totalMatches: number;
+    };
+}
+export interface OperationError extends Error {
+    readonly operation?: OperationFailureDetail;
+}
+export declare class SquareErrorBase<Code extends string> extends Error {
+    code: Code;
+    facts?: SquareErrorFacts | undefined;
+    operation?: OperationFailureDetail;
+    constructor(code: Code, message: string, facts?: SquareErrorFacts | undefined);
+}
+export declare class SquareError extends SquareErrorBase<SquareErrorCode> {
+}
+export declare class InternalSquareError extends SquareErrorBase<InternalSquareErrorCode> {
+}
+export declare function isSquareError(error: unknown): error is SquareError | InternalSquareError;
+export declare function validateOwner(owner: Owner): Owner;
+export declare function nameKey(name: string): string;
+export interface IndexPage {
+    readonly edge: 'oldest' | 'newest';
+    readonly limit: number;
+}
+export interface FactPage<T> {
+    readonly items: readonly T[];
+    readonly hasMore: boolean;
+}

package/dist/neutral.js

@@ -0,0 +1,27 @@
+export class SquareErrorBase extends Error {
+    code;
+    facts;
+    operation;
+    constructor(code, message, facts) {
+        super(message);
+        this.code = code;
+        this.facts = facts;
+        this.name = 'SquareError';
+    }
+}
+export class SquareError extends SquareErrorBase {
+}
+export class InternalSquareError extends SquareErrorBase {
+}
+export function isSquareError(error) {
+    return error instanceof SquareError || error instanceof InternalSquareError;
+}
+export function validateOwner(owner) {
+    if (typeof owner !== 'string' || !owner || Buffer.byteLength(owner, 'utf8') > 512 || /[\u0000-\u001f\u007f-\u009f]/u.test(owner)) {
+        throw new SquareError('invalid_args', 'A participant write requires a non-empty owner without control characters (at most 512 UTF-8 bytes).');
+    }
+    return owner;
+}
+export function nameKey(name) {
+    return name.toLocaleLowerCase();
+}

package/dist/notifications.d.ts

@@ -1,26 +1,24 @@
-import { type WakeRouteKind } from './model.js';
-import type { WakeTransportPort } from './ports.js';
-export declare const PRIVILEGED_HOOK_BUDGET_MS = 3000;
-export declare function wakeGraceMs(env?: NodeJS.ProcessEnv): number;
-export type WakeTransports = Readonly<Partial<Record<WakeRouteKind, WakeTransportPort>>>;
-interface ProcessNotificationOptions {
-    transports?: WakeTransports;
-    env?: NodeJS.ProcessEnv;
-    now?: () => number;
-}
-/** Concrete transports use wall time; semantic state time belongs to Square operations. */
-export declare function createDefaultWakeTransport(env?: NodeJS.ProcessEnv, suppliedTransports?: WakeTransports): Promise<WakeTransportPort>;
-/** Route selection only: all implementations receive the same request and final gate. */
-export declare function createWakeTransport(transports: WakeTransports): WakeTransportPort;
-export declare function processActNotificationsOnce(squarePath: string, actIndex: number, opts?: ProcessNotificationOptions): Promise<void>;
-/** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares within one boundary budget. */
-export declare function sweepPrivilegedPending(cwd: string, env?: NodeJS.ProcessEnv, suppliedTransports?: WakeTransports, deadline?: number, signal?: AbortSignal): Promise<void>;
-export interface SweepPendingNotificationsOptions {
-    env?: NodeJS.ProcessEnv;
-    now?: number;
-    limit?: number;
-    dispatchCandidate?: (actIndex: number) => void | Promise<void>;
-}
-/** Select old pending attention at a bounded action boundary for an explicit executor. */
-export declare function sweepPendingNotifications(squarePath: string, opts?: SweepPendingNotificationsOptions): Promise<number[]>;
-export {};
+import type { DeliveryLedger, DeliveryTransport, HandoffResult, PostResult } from './delivery-ledger.js';
+import type { Owner } from './owner.js';
+export { createDefaultDeliveryTransports } from './wake-transports.js';
+/** Best-effort dispatch for currently eligible cards, including cards restored by release. */
+export declare function dispatchEligibleCards(ledger: DeliveryLedger, owner: Owner, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+    readonly track?: (result: HandoffResult) => void;
+    readonly transports?: readonly DeliveryTransport[];
+}): Promise<void>;
+/** Post, then best-effort dispatch without consulting producer storage. */
+export declare function postAndDispatch(ledger: DeliveryLedger, input: {
+    readonly owner: Owner;
+    readonly key: string;
+    readonly text: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}, options?: {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+    readonly track?: (result: HandoffResult) => void;
+    readonly transports?: readonly DeliveryTransport[];
+}): Promise<PostResult>;
+/** Best-effort dispatch after a card has been posted; never inspect producer storage. */
+export declare function dispatchPostedCard(ledger: DeliveryLedger, owner: Owner, key: string, track: (result: HandoffResult) => void, env?: NodeJS.ProcessEnv, signal?: AbortSignal, suppliedTransports?: readonly DeliveryTransport[]): Promise<void>;

package/dist/notifications.js

@@ -1,152 +1,48 @@
-import path from 'node:path';
-import { canonicalPath } from './canonical-path.js';
-import fs from 'node:fs';
-import { indexedSquareEntries } from './square-index.js';
-import { InternalSquareError, SquareError } from './model.js';
-import { createArtifactPort } from './artifact.js';
-import { deliverPending, sweepPending } from './delivery-operations.js';
-export const PRIVILEGED_HOOK_BUDGET_MS = 3000;
-export function wakeGraceMs(env = process.env) {
-    const value = Number.parseInt(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? '5000', 10);
-    if (!Number.isFinite(value) || value <= 0) {
-        throw new SquareError('invalid_args', 'Invalid SQUARE_NOTIFY_DELIVERY_WAIT_MS: expected a positive integer.');
-    }
-    return value;
-}
-/** Concrete transports use wall time; semantic state time belongs to Square operations. */
-export async function createDefaultWakeTransport(env = process.env, suppliedTransports) {
-    if (suppliedTransports !== undefined)
-        return createWakeTransport(suppliedTransports);
-    const transports = {};
-    try {
-        const { CodexQueueTransport } = await import('./codex-queue.js');
-        transports['codex-queue'] = new CodexQueueTransport({ env });
-    }
-    catch { /* core-only builds may omit Codex */ }
-    if (env.SQUARE_DISABLE_PASEO_WAKE !== '1') {
-        try {
-            const { PaseoWakeTransport } = await import('./paseo-delivery.js');
-            transports.paseo = new PaseoWakeTransport();
-        }
-        catch { /* Paseo is optional */ }
-    }
-    const { createClaudeWakeTransport } = await import('./claude-delivery.js');
-    transports['claude-native'] = createClaudeWakeTransport(env);
-    const { HttpWakeTransport } = await import('./http-delivery.js');
-    transports.http = new HttpWakeTransport({ env });
-    return createWakeTransport(transports);
-}
-/** Route selection only: all implementations receive the same request and final gate. */
-export function createWakeTransport(transports) {
-    const missing = (kind) => ({ outcome: 'not-capable', diagnostic: `no transport for ${kind}` });
-    return {
-        async probe(route) {
-            const transport = transports[route.kind];
-            if (transport === undefined)
-                return missing(route.kind);
-            try {
-                return await transport.probe?.(route) ?? true;
-            }
-            catch (error) {
-                return { outcome: 'not-capable', diagnostic: error instanceof Error ? error.message : String(error) };
-            }
-        },
-        attempt: (request, timeoutMs, beforeSend) => transports[request.route.kind]?.attempt(request, timeoutMs, beforeSend)
-            ?? Promise.resolve(missing(request.route.kind)),
-    };
+import { createDefaultDeliveryTransports } from './wake-transports.js';
+export { createDefaultDeliveryTransports } from './wake-transports.js';
+/** Best-effort dispatch for currently eligible cards, including cards restored by release. */
+export async function dispatchEligibleCards(ledger, owner, options = {}) {
+    const session = await ledger.session(owner);
+    if (!session || session.state !== 'attached' || options.signal?.aborted)
+        return;
+    const pending = await ledger.pending(owner, { generation: session.generation });
+    for (const card of pending)
+        await dispatchPostedCard(ledger, owner, card.key, options.track ?? (() => undefined), options.env, options.signal, options.transports);
 }
-export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
-    const env = opts.env ?? process.env;
-    const now = opts.now ?? Date.now;
-    squarePath = await canonicalPath(squarePath);
-    const artifact = createArtifactPort(squarePath);
-    try {
-        await artifact.read(facts => facts.header());
-        const transport = await createDefaultWakeTransport(env, opts.transports);
+/** Post, then best-effort dispatch without consulting producer storage. */
+export async function postAndDispatch(ledger, input, options = {}) {
+    const result = await ledger.post(input);
+    if (result.status === 'posted' || result.status === 'duplicate') {
         try {
-            await deliverPending({ artifact, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: now() });
+            await dispatchEligibleCards(ledger, input.owner, options);
         }
-        catch { /* Delivery failure does not undo the activity. */ }
-    }
-    catch (error) {
-        if (error instanceof InternalSquareError && error.code === 'not_found')
-            throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
-        throw error;
-    }
-    finally {
-        await artifact.close();
+        catch { /* Posting is already committed. */ }
     }
+    return result;
 }
-/** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares within one boundary budget. */
-export async function sweepPrivilegedPending(cwd, env = process.env, suppliedTransports, deadline = Date.now() + PRIVILEGED_HOOK_BUDGET_MS, signal) {
-    const remainingMs = () => Math.max(0, deadline - Date.now());
-    if (remainingMs() === 0 || signal?.aborted)
+/** Best-effort dispatch after a card has been posted; never inspect producer storage. */
+export async function dispatchPostedCard(ledger, owner, key, track, env = process.env, signal, suppliedTransports) {
+    if (signal?.aborted)
         return;
-    const indexed = await indexedSquareEntries({}, env).catch(() => []);
-    const paths = new Set(indexed.map((binding) => binding.location));
-    try {
-        for (const entry of await fs.promises.readdir(path.join(cwd, '.square'))) {
-            if (entry.endsWith('.square'))
-                paths.add(path.join(cwd, '.square', entry));
-        }
-    }
-    catch { /* no local square directory */ }
-    if (remainingMs() === 0 || signal?.aborted)
+    const session = await ledger.session(owner);
+    if (!session || session.state !== 'attached')
         return;
-    const transport = await createDefaultWakeTransport(env, suppliedTransports);
-    for (const candidate of paths) {
-        if (remainingMs() === 0 || signal?.aborted)
-            break;
-        try {
-            const squarePath = await canonicalPath(candidate);
-            const artifact = createArtifactPort(squarePath, undefined, signal);
-            try {
-                await artifact.read(facts => facts.header(), signal);
-                if (remainingMs() === 0 || signal?.aborted)
-                    break;
-                const limit = Number.parseInt(env.SQUARE_NOTIFY_SWEEP_LIMIT ?? '8', 10);
-                const graceMs = 0;
-                const selected = await sweepPending({ artifact, location: squarePath, now: Date.now(), graceMs, limit: Number.isFinite(limit) && limit > 0 ? limit : 8 }).catch(() => []);
-                for (const actIndex of selected) {
-                    const remaining = remainingMs();
-                    if (remaining === 0 || signal?.aborted)
-                        break;
-                    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
-                    const timeoutMs = Math.max(1, Math.min(Number.isFinite(configured) && configured > 0 ? configured : 5000, remaining));
-                    await deliverPending({ artifact, transport, location: squarePath, activity: actIndex, timeoutMs, now: Date.now() }).catch(() => undefined);
-                }
-            }
-            finally {
-                await artifact.close();
-            }
-        }
-        catch { /* stale index entries are ignored by the hook */ }
-    }
-}
-/** Select old pending attention at a bounded action boundary for an explicit executor. */
-export async function sweepPendingNotifications(squarePath, opts = {}) {
-    const env = opts.env ?? process.env;
-    if (env.SQUARE_DISABLE_PASEO_WAKE === '1')
-        return [];
-    const now = opts.now ?? Date.now();
-    const limit = opts.limit ?? 8;
-    const artifact = createArtifactPort(squarePath);
-    let selected;
-    try {
-        await artifact.read(facts => facts.header());
-        selected = await sweepPending({ artifact, location: squarePath, now, graceMs: wakeGraceMs(env), limit });
-    }
-    catch (error) {
-        if (error instanceof InternalSquareError && error.code === 'not_found')
-            throw new SquareError('unavailable', `Square is unavailable at ${squarePath}`);
-        throw error;
-    }
-    finally {
-        await artifact.close();
-    }
-    if (opts.dispatchCandidate !== undefined) {
-        for (const actIndex of selected)
-            await opts.dispatchCandidate(actIndex);
+    const transports = suppliedTransports ?? await createDefaultDeliveryTransports(env);
+    const configured = Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000);
+    const timeoutMs = Number.isSafeInteger(configured) && configured > 0 ? configured : 5000;
+    for (const route of session.routes) {
+        // Codex custody belongs to its native receiver, including for callers that
+        // supply transports explicitly to the public producer API.
+        if (route.kind === 'codex-queue')
+            continue;
+        if (signal?.aborted)
+            return;
+        const transport = transports.find(candidate => candidate.kind === route.kind);
+        if (!transport)
+            continue;
+        const result = await ledger.dispatchHandoff(owner, key, transport, { generation: session.generation, timeoutMs, signal });
+        track(result);
+        if (result.outcome === 'accepted' || result.outcome === 'presented' || result.outcome === 'unknown')
+            return;
     }
-    return selected;
 }

package/dist/operation-control.d.ts

@@ -0,0 +1,4 @@
+import type { OperationControl, OperationFailureDetail } from './neutral.js';
+export declare function checkControl(control?: OperationControl): void;
+export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
+export declare function failure(error: unknown, detail: OperationFailureDetail): Error;