@astrosheep/square 0.4.0 → 0.4.1

package/dist/inbox.js

@@ -1,382 +1,35 @@
-import { createArtifactPort, observeSquareDeliveryRevision, observeSquareRevision } from './artifact.js';
-import { indexedSquareEntries, observeSquareIndex } from './square-index.js';
+import path from 'node:path';
+import { createArtifactPort } from './artifact.js';
+import { discoverSquares, MAX_LIST_LIMIT } from './list.js';
 import { canonicalPath } from './canonical-path.js';
-import { formatMessageId } from './message.js';
-import { freshWatchLease, WATCH_STALE_MS } from './runtime.js';
-import { nativePendingHead, pendingHeads } from './delivery.js';
-import { deliveryDeferralExpiry } from './delivery-deferral.js';
-import { projectMessageNotification, renderSquareReminder } from './attention-presentation.js';
-export function pendingKey(membership, messageIndex) {
-    return membership.location + '\0' + membership.seat.participant.toLocaleLowerCase() + '\0' + messageIndex;
-}
-function eligibleNotifications(facts, membership, now = Date.now()) {
-    const seat = facts.seat(membership.seat.participant);
-    if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== membership.seat.generation
-        || seat.owner !== membership.seat.owner)
-        return { notifications: [] };
-    const cancelledThrough = facts.channel.cancelledThrough(seat.participant, seat.generation);
-    let expiry = Infinity;
-    const notifications = membership.notifications.filter(notification => {
-        if (cancelledThrough !== undefined && notification.messageIndex <= cancelledThrough
-            || facts.deliveryEvidence(seat.participant, seat.generation, formatMessageId(notification.messageIndex))
-                .some(row => row.outcome !== 'failed' && row.outcome !== 'released'))
-            return false;
-        const deferredUntil = deliveryDeferralExpiry(facts.channel, seat, notification.messageIndex, now);
-        if (deferredUntil === undefined)
-            return true;
-        expiry = Math.min(expiry, deferredUntil);
-        return false;
-    });
-    return { notifications, ...(expiry === Infinity ? {} : { deliveryDeferralExpiry: expiry }) };
-}
-/** Revalidate a supplied batch immediately before the boundary's independent claim/send checks. */
-export async function projectBoundaryEligibility(inbox) {
-    const grouped = new Map();
-    for (const membership of inbox.filter(candidate => candidate.notifications.length > 0)) {
-        const entries = grouped.get(membership.location) ?? [];
-        entries.push(membership);
-        grouped.set(membership.location, entries);
-    }
-    const pending = [];
-    for (const [location, memberships] of grouped) {
-        const artifact = createArtifactPort(location);
-        try {
-            const { value } = await artifact.read(facts => memberships.flatMap(membership => {
-                const eligibility = eligibleNotifications(facts, membership);
-                return eligibility.notifications.length === 0 ? [] : [{ ...membership, ...eligibility }];
-            }));
-            pending.push(...value);
-        }
-        catch {
-            // An unreadable or stale candidate cannot authorize boundary presentation.
-        }
-        finally {
-            await artifact.close();
-        }
-    }
-    return pending;
-}
-/** HOME is a candidate path index; current seats and delivery evidence live in the artifact. */
-export async function projectSessionCandidates(input) {
-    const location = input.location === undefined ? undefined : await canonicalPath(input.location);
-    const entries = await indexedSquareEntries({ owner: input.owner }, input.env ?? process.env);
-    const candidates = new Map();
-    for (const entry of entries) {
-        if (location !== undefined && location !== entry.location)
-            continue;
-        const key = JSON.stringify([entry.location, entry.owner]);
-        candidates.set(key, { location: entry.location, owner: entry.owner });
-    }
-    return [...candidates.values()];
-}
-function groupCandidates(candidates) {
-    const grouped = new Map();
-    for (const { location, owner } of candidates) {
-        const owners = grouped.get(location) ?? [];
-        owners.push(owner);
-        grouped.set(location, owners);
-    }
-    return grouped;
-}
-function locatedSeats(facts, location, seats) {
-    return seats.flatMap(seat => {
-        const participant = facts.participant(seat.participant);
-        const index = participant?.lastJoinIndex;
-        const joined = index === undefined ? undefined : facts.activity(index);
-        return joined?.kind === 'join' ? [{ location, seat, joinedAt: joined.at }] : [{ location, seat, joinedAt: 0 }];
-    });
-}
-/** Lifecycle reads resolve seats and join times, never pending activity bodies. */
-export async function projectSessionSeats(input, signal) {
-    const seats = [];
-    for (const [location, owners] of groupCandidates(await projectSessionCandidates(input))) {
-        signal?.throwIfAborted();
-        const artifact = createArtifactPort(location, undefined, signal);
-        try {
-            seats.push(...(await artifact.read(facts => locatedSeats(facts, location, owners.flatMap(owner => facts.seatsForOwner(owner))), signal)).value);
-        }
-        catch (error) {
-            if (signal?.aborted)
-                throw signal.reason ?? error;
-        }
-        finally {
-            await artifact.close();
-        }
-    }
-    return seats;
-}
-/** Public count boundary: one coherent read per artifact, without pending body hydration. */
+/** Filesystem-scoped membership counts. This is a World read, not a delivery scan. */
 export async function sessionInboxCounts(input, signal) {
+    const root = path.resolve(input.cwd ?? process.cwd());
     const rows = [];
-    for (const [location, owners] of groupCandidates(await projectSessionCandidates(input))) {
+    let after;
+    do {
         signal?.throwIfAborted();
-        const artifact = createArtifactPort(location, undefined, signal);
-        try {
-            rows.push(...(await artifact.read(facts => locatedSeats(facts, location, owners.flatMap(owner => facts.seatsForOwner(owner).filter(seat => seat.attachment === 'attached'))).map(({ seat }) => ({
-                name: seat.participant, squarePath: location, pending: facts.directedCount(seat.participant, { unseenOnly: true, currentGeneration: true }),
-            })), signal)).value);
-        }
-        catch (error) {
-            if (signal?.aborted)
-                throw signal.reason ?? error;
-        }
-        finally {
-            await artifact.close();
-        }
-    }
-    return rows;
-}
-/** One authoritative read per canonical artifact, even when discovery names several bodies. */
-async function projectPending(candidates, cache, signal) {
-    const pending = [];
-    for (const [location, owners] of groupCandidates(candidates)) {
-        signal?.throwIfAborted();
-        const artifact = createArtifactPort(location, undefined, signal);
-        try {
-            const { value: current } = await artifact.read(facts => {
-                const seats = owners.flatMap(owner => facts.seatsForOwner(owner).filter(seat => seat.attachment === 'attached'));
-                const coordinate = JSON.stringify([owners, seats.map(seat => [seat.participant, seat.owner, seat.generation])]);
-                const header = facts.header();
-                let cached = cache?.get(location);
-                if (cached?.coordinate !== coordinate || cached.version !== header.revision) {
-                    cached = { coordinate, version: header.revision, value: locatedSeats(facts, location, seats).map(membership => {
-                            const heads = pendingHeads(facts, membership.seat.participant, Date.now(), false);
-                            const messages = new Map(facts.channel.messages(heads.map(head => head.index)).map(item => [item.index, item]));
-                            return { ...membership, notifications: heads.flatMap(head => {
-                                    const item = messages.get(head.index);
-                                    if (item === undefined)
-                                        return [];
-                                    return [{ messageIndex: item.index, ...(head.activityIndex === undefined ? {} : { actIndex: head.activityIndex }),
-                                            actor: item.from, at: item.at, body: item.body, ...(item.preview === undefined ? {} : { preview: item.preview }), ...(head.route === undefined ? {} : { route: head.route }) }];
-                                }) };
-                        }) };
-                }
-                // Cache conversation content, never leases or delivery eligibility: evidence can change
-                // without a conversation revision and must not force body hydration or self-wake retries.
-                return { cached, pending: cached.value.map(membership => {
-                        const catchLease = freshWatchLease(facts, membership.seat.participant);
-                        // Cached conversation content, but claim coverage and deferrals are re-read on every projection.
-                        const observed = { ...membership, notifications: membership.notifications.filter(note => !facts.channel.suppressed(membership.seat.participant, membership.seat.generation, note.messageIndex, Date.now())) };
-                        return { ...observed, ...eligibleNotifications(facts, observed),
-                            ...(catchLease === undefined ? {} : { catchLease }) };
-                    }) };
-            }, signal);
-            cache?.set(location, current.cached);
-            pending.push(...current.pending);
-        }
-        catch (error) {
-            cache?.delete(location);
-            if (signal?.aborted)
-                throw signal.reason ?? error;
-            // Unreadable candidates remain watch targets, but never authorize cached content.
-        }
-        finally {
-            await artifact.close();
-        }
-    }
-    return pending;
-}
-/** One current eligibility + source projection read; senders use text, ACK coverage uses clipped. */
-export function nativePendingSource(facts, input) {
-    const head = nativePendingHead(facts, input);
-    if (head === undefined)
-        return undefined;
-    const item = facts.channel.message(input.index);
-    if (item === undefined)
-        return undefined;
-    const projected = projectMessageNotification({ squarePath: input.location, recipient: input.participant,
-        actor: item.from, body: item.body, ...(item.preview === undefined ? {} : { preview: item.preview }),
-        ...(head.activityIndex === undefined || head.route === undefined ? {} : { agora: { actIndex: head.activityIndex, route: head.route } }) });
-    return { text: projected.text, clipped: projected.clipped };
-}
-/** The sender-facing fixed reminder over the shared source projection. */
-export function nativePendingPreview(facts, input) {
-    const source = nativePendingSource(facts, input);
-    return source === undefined ? undefined : { payload: renderSquareReminder([source.text]), clipped: source.clipped };
-}
-export async function sessionInbox(owner, env = process.env, signal) {
-    return projectPending(await projectSessionCandidates({ owner, env }), undefined, signal);
-}
-async function capture(observer, kind, signal) {
-    const generation = observer.generation;
-    try {
-        const value = await observer.read(signal);
-        return { kind, value, wait: (timeout, abort) => observer.changed(value, timeout, abort) };
-    }
-    catch (error) {
-        if (signal.aborted)
-            throw signal.reason ?? error;
-        // Failed revision reads are not changes; only a successful retry wakes projection.
-        return { kind, wait: async (timeout, abort) => {
-                const deadline = Date.now() + Math.max(0, timeout);
-                let since = generation;
-                while (await observer.hinted(since, Math.max(0, deadline - Date.now()), abort)) {
-                    since = observer.generation;
-                    try {
-                        await observer.read(abort);
-                        return true;
-                    }
-                    catch (error) {
-                        if (abort.aborted)
-                            throw abort.reason ?? error;
-                    }
-                }
-                return false;
-            } };
-    }
-}
-/** Session-scoped projection over process-shared storage change detectors. */
-export async function observeSessionPending(owner, suppliedEnv = process.env) {
-    const env = { ...suppliedEnv };
-    const query = { owner, env };
-    const index = await observeSquareIndex(env);
-    const artifacts = new Map();
-    const cache = new Map();
-    const lifetime = new AbortController();
-    async function currentInbox(candidates, signal) {
-        const inbox = await projectPending(candidates, cache, signal);
-        const now = Date.now();
-        return inbox.map((membership) => {
-            const { catchLease, ...rest } = membership;
-            return catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
-                ? membership : rest;
-        });
-    }
-    function eligibleInbox(inbox, excludeKeys) {
-        const eligible = inbox.filter(membership => membership.notifications.length > 0);
-        return excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
-            const notifications = membership.notifications.filter((notification) => !excludeKeys.has(pendingKey(membership, notification.messageIndex)));
-            return notifications.length === 0 ? [] : [{ ...membership, notifications }];
-        });
-    }
-    return {
-        async read(options = {}) {
-            const signal = AbortSignal.any([lifetime.signal, ...(options.signal === undefined ? [] : [options.signal])]);
-            signal.throwIfAborted();
-            const inbox = await currentInbox(await projectSessionCandidates(query), signal);
-            const pending = eligibleInbox(inbox, options.excludeKeys);
-            signal.throwIfAborted();
-            return pending;
-        },
-        async wait(timeoutMs, options = {}) {
-            const deadline = Date.now() + Math.max(0, timeoutMs);
-            const expired = new AbortController();
-            const timer = Number.isFinite(timeoutMs) && timeoutMs > 0
-                ? setTimeout(() => expired.abort(), Math.min(timeoutMs, 2_147_483_647)) : undefined;
-            const signal = AbortSignal.any([lifetime.signal, expired.signal, ...(options.signal === undefined ? [] : [options.signal])]);
-            let canReturn = !options.skipImmediate;
-            let previousEligible;
-            let armed = false;
-            let candidates = [];
-            let candidatePresence;
-            let discoveredCandidates = false;
+        const page = await discoverSquares(root, { limit: MAX_LIST_LIMIT, ...(after === undefined ? {} : { after }) }, { signal });
+        for (const item of page.items) {
+            signal?.throwIfAborted();
+            const location = await canonicalPath(path.resolve(root, item.path));
+            const artifact = createArtifactPort(location, undefined, signal);
             try {
-                while (!signal.aborted) {
-                    // Subscribe to the candidate index before discovering artifacts; a concurrent join can
-                    // publish its path without touching the artifact revision.
-                    const sources = [await capture(index, 'index', signal)];
-                    const presence = sources[0];
-                    const currentPresence = presence.value;
-                    if (!discoveredCandidates || currentPresence !== undefined && !Object.is(currentPresence, candidatePresence)) {
-                        candidates = await projectSessionCandidates(query);
-                        candidatePresence = currentPresence;
-                        discoveredCandidates = true;
-                    }
-                    const paths = new Set(candidates.map((candidate) => candidate.location));
-                    for (const [file, entry] of artifacts) {
-                        if (!paths.has(file)) {
-                            entry.observer.close();
-                            entry.delivery.close();
-                            artifacts.delete(file);
-                            cache.delete(file);
-                        }
-                    }
-                    for (const file of paths) {
-                        if (artifacts.has(file))
-                            continue;
-                        const observer = await observeSquareRevision(file);
-                        const delivery = await observeSquareDeliveryRevision(file);
-                        if (signal.aborted) {
-                            observer.close();
-                            delivery.close();
-                            return [];
-                        }
-                        artifacts.set(file, { observer, delivery });
-                    }
-                    // Capture both revision baselines before selecting seats and pending facts. A takeover
-                    // during an empty selection must remain visible to the already armed observers.
-                    for (const entry of artifacts.values()) {
-                        sources.push(await capture(entry.observer, 'artifact', signal));
-                        sources.push(await capture(entry.delivery, 'delivery', signal));
-                    }
-                    const inbox = await currentInbox(candidates, signal);
-                    const pending = eligibleInbox(inbox, options.excludeKeys);
-                    const eligibleKeys = JSON.stringify(pending.flatMap((membership) => membership.notifications.map((note) => pendingKey(membership, note.messageIndex))).sort());
-                    if (previousEligible !== undefined && previousEligible !== eligibleKeys)
-                        canReturn = true;
-                    previousEligible = eligibleKeys;
-                    if (signal.aborted)
-                        return [];
-                    if (canReturn && pending.length > 0)
-                        return pending;
-                    const remaining = deadline - Date.now();
-                    if (remaining <= 0)
-                        return [];
-                    // Eligibility may change at lease expiry without any storage write.
-                    const leaseExpiry = Math.min(Infinity, ...inbox.flatMap((membership) => membership.catchLease === undefined ? [] : [Math.min(membership.catchLease.expiresAt, membership.catchLease.heartbeatAt + WATCH_STALE_MS + 1)]));
-                    const nextExpiry = Math.min(leaseExpiry, ...inbox.map(membership => membership.deliveryDeferralExpiry ?? Infinity));
-                    const duration = Math.min(remaining, Math.max(1, nextExpiry - Date.now()));
-                    const cancelled = new AbortController();
-                    const waitSignal = AbortSignal.any([signal, cancelled.signal]);
-                    const waits = sources.map(async (source) => {
-                        try {
-                            return await source.wait(duration, waitSignal) ? source.kind : 'deadline';
-                        }
-                        catch (error) {
-                            if (waitSignal.aborted)
-                                throw error;
-                            return source.kind;
-                        }
-                    });
-                    if (!armed) {
-                        armed = true;
-                        options.onChangeArmed?.(true);
-                    }
-                    try {
-                        const change = await Promise.race(waits);
-                        if (change !== 'delivery')
-                            canReturn = true;
-                    }
-                    finally {
-                        cancelled.abort();
-                        await Promise.allSettled(waits);
-                    }
-                }
-                return [];
+                rows.push(...(await artifact.read(facts => facts.seatsForOwner(input.owner)
+                    .filter(seat => facts.participant(seat.participant)?.joined)
+                    .map(seat => ({ name: seat.participant, squarePath: location,
+                    pending: facts.directedCount(seat.participant, { unseenOnly: true, currentGeneration: true }) })), signal)).value);
             }
             catch (error) {
-                if (signal.aborted)
-                    return [];
-                throw error;
+                if (signal?.aborted)
+                    throw signal.reason ?? error;
+                // Discovery candidates may disappear or become unreadable before this read.
             }
             finally {
-                if (timer !== undefined)
-                    clearTimeout(timer);
-                if (!armed)
-                    options.onChangeArmed?.(false);
+                await artifact.close();
             }
-        },
-        close() {
-            if (lifetime.signal.aborted)
-                return;
-            lifetime.abort();
-            index.close();
-            for (const entry of artifacts.values()) {
-                entry.observer.close();
-                entry.delivery.close();
-            }
-            artifacts.clear();
-            cache.clear();
-        },
-    };
+        }
+        after = page.next;
+    } while (after !== undefined);
+    return rows;
 }

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
-export { selectOwnSeat, requireOwner, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
-export type { WakeTransportPort, WakeRequest, WakeOutcome } from './ports.js';
-export type { WakeTransports } from './notifications.js';
+export { selectOwnSeat, requireOwner, requireJoinName, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
+export { postAndDispatch, dispatchEligibleCards } from './notifications.js';
+export { DeliveryLedger, deliveryLedgerLocation } from './delivery-ledger.js';
+export type * from './delivery-ledger.js';
+export { isCardPresentation } from './card-presentation.js';
+export type { CardPresentation } from './card-presentation.js';
 export type * from './square-facade.js';

package/dist/index.js

@@ -1,3 +1,6 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
-export { selectOwnSeat, requireOwner, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
+export { selectOwnSeat, requireOwner, requireJoinName, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
+export { postAndDispatch, dispatchEligibleCards } from './notifications.js';
+export { DeliveryLedger, deliveryLedgerLocation } from './delivery-ledger.js';
+export { isCardPresentation } from './card-presentation.js';

package/dist/mcp.js

@@ -51,7 +51,7 @@ export function createSquareMcpServer(options) {
                         ? wakeAddress : undefined;
                     return {
                         identity: { owner, wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
-                                ? codexWakeAddress(threadId, env) : callWake },
+                                ? { ...codexWakeAddress(threadId, env), kind: 'codex-queue' } : callWake },
                         open: (location, control) => Square.at({
                             ...resourceOptions, env, cwd: claude?.cwd ?? resourceOptions.cwd,
                             path: location ?? options.path,

package/dist/model.d.ts

@@ -1,9 +1,8 @@
 import type { Act, ActivityId } from './square-core.js';
-import type { EndpointGeneration } from './message.js';
 import type { Owner } from './neutral.js';
-import type { MessageMetadata as ActivityMetadata, WakeAddress } from './channel-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 './channel-values.js';
-export type { WakeRouteKind, JsonValue, MessageMetadata as ActivityMetadata, WakeAddress, WakeRoute } from './channel-values.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';
@@ -11,7 +10,7 @@ export type { Act, ActivityId, Audience, Reach } from './square-core.js';
 export interface Seat {
     readonly participant: string;
     readonly owner: Owner;
-    readonly generation: EndpointGeneration;
+    readonly generation: string;
     readonly attachment: 'attached' | 'detached';
     readonly wakeAddress?: WakeAddress;
 }
@@ -30,26 +29,12 @@ export interface BuildOptions {
 export type ActDraft = Act & {
     at: number;
 };
-/** Persisted say: identity and social facts only. Its content lives in the linked Channel message. */
-export type SayRelation = Omit<Extract<Act, {
-    kind: 'say';
-}>, 'body' | 'metadata'> & {
+/** A landed activity owns its content and social facts. */
+export type StoredAct = Act & {
     index: number;
     at: number;
-    messageIndex: number;
-};
-/** A landed upper activity. A say is a relation; it carries no content of its own. */
-export type StoredAct = Extract<Act, {
-    kind: 'join' | 'done' | 'read' | 'listen' | 'ignore' | 'unlisten';
-}> & {
-    index: number;
-    at: number;
-} | SayRelation;
-/** Explicit upper projection: a stored say resolved against its authoritative message. */
-export type HydratedAct = Exclude<StoredAct, SayRelation> | SayRelation & {
-    body?: string;
-    metadata?: ActivityMetadata;
 };
+export type HydratedAct = StoredAct;
 export type ObservationState = 'seen';
 export interface ActivityObservation {
     state: ObservationState;
@@ -66,31 +51,6 @@ export interface WatchLease {
     filter?: WatchLeaseFilter;
 }
 export type DirectedNotificationRoute = import('./attention.js').AudienceRoute;
-export interface InboxNotification {
-    /** Lower message coordinate. */
-    messageIndex: number;
-    /** Upper Agora activity sharing this message, when one exists. */
-    actIndex?: number;
-    actor: string;
-    at: number;
-    route?: DirectedNotificationRoute;
-    body: string;
-    readonly preview?: string;
-    readonly description?: string;
-    readonly coverage?: 'full' | 'clipped';
-}
-/** The one stored-content-to-notification field mapping used by inbox and native previews. */
-export declare function notificationFacts(item: HydratedAct, route: DirectedNotificationRoute): InboxNotification;
-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;

package/dist/model.js

@@ -1,12 +1,6 @@
 // Shared model and constants for Square.
-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 './channel-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 { SquareErrorBase, SquareError, InternalSquareError, isSquareError, validateOwner, nameKey } from './neutral.js';
-/** The one stored-content-to-notification field mapping used by inbox and native previews. */
-export function notificationFacts(item, route) {
-    if (item.kind !== 'say' || item.messageIndex === undefined)
-        throw new Error(`Activity ${item.index} is not conversation content.`);
-    return { messageIndex: item.messageIndex, actIndex: item.index, actor: item.actor, at: item.at, route, body: item.body ?? '(structured activity)' };
-}
 export function formatHardCap(hardCap) {
     return hardCap === null ? '-1' : String(hardCap);
 }

package/dist/notifications.d.ts

@@ -1,20 +1,24 @@
-import { type WakeTransports } from './wake-transports.js';
-export { createDefaultWakeTransport, createWakeTransport, type WakeTransports } from './wake-transports.js';
-export declare const PRIVILEGED_HOOK_BUDGET_MS = 3000;
-export declare function wakeGraceMs(env?: NodeJS.ProcessEnv): number;
-interface ProcessNotificationOptions {
-    transports?: WakeTransports;
-    env?: NodeJS.ProcessEnv;
-    now?: () => number;
-}
-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[]>;
+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>;