@astrosheep/square 0.3.105 → 0.4.0

package/dist/boundary-presentation.js

@@ -4,9 +4,8 @@ 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 };
+import { sessionInbox, projectBoundaryEligibility, pendingKey } from './inbox.js';
+import { projectChannelNotification, projectNotification, renderSquareReminder } from './attention-presentation.js';
 const CONTEXT_MAX = 1200;
 export function renderPendingAtBoundary(inbox) {
     return renderBoundary(inbox).context;
@@ -15,26 +14,23 @@ function renderBoundary(inbox) {
     const queued = inbox.flatMap((membership) => membership.notifications.map((notification) => ({ membership, notification })));
     const blocks = [];
     const agoraBlocks = [];
-    const deliveries = [];
-    let remainingAgora = queued.filter(({ notification }) => notification.delivery?.mode !== 'direct').length;
+    let remainingAgora = queued.filter(({ notification }) => notification.route !== undefined).length;
     const entries = [];
     let omitted = 0;
     const omission = (count) => `${count} more ${count === 1 ? 'activity' : 'activities'} not shown.`;
     for (const entry of queued) {
         const { membership, notification } = entry;
         // The omission line represents the rest of this batch too, but never consumes its bodies.
-        const coverage = { membership, actIndex: notification.actIndex, markSeen: false };
+        const coverage = { membership, messageIndex: notification.messageIndex, markSeen: false };
         entries.push(coverage);
-        const block = renderAttentionPreview({
-            squarePath: membership.location,
-            actIndex: notification.actIndex,
-            recipient: membership.seat.participant,
-            actor: notification.actor,
-            route: notification.route,
-            body: notification.body,
-            delivery: notification.delivery,
-        });
-        if (notification.delivery?.mode !== 'direct') {
+        const projected = notification.route === undefined
+            ? projectChannelNotification({ squarePath: membership.location, recipient: membership.seat.participant,
+                actor: notification.actor, body: notification.body, ...(notification.preview === undefined ? {} : { preview: notification.preview }) })
+            : projectNotification({ squarePath: membership.location, actIndex: notification.actIndex ?? notification.messageIndex,
+                recipient: membership.seat.participant, actor: notification.actor, route: notification.route,
+                body: notification.body, ...(notification.preview === undefined ? {} : { preview: notification.preview }) });
+        const block = projected.text;
+        if ('agora' in projected && projected.agora) {
             remainingAgora -= 1;
             const omittedAfter = omitted + remainingAgora;
             const prospective = renderSquareReminder([...agoraBlocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
@@ -45,11 +41,10 @@ function renderBoundary(inbox) {
             agoraBlocks.push(block);
         }
         blocks.push(block);
-        deliveries.push(notification.delivery);
-        coverage.markSeen = !attentionBodyIsClipped(notification.body, notification.delivery);
+        coverage.markSeen = !projected.clipped;
     }
     return {
-        context: renderSquareReminder([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])], deliveries),
+        context: renderSquareReminder([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])]),
         entries,
     };
 }
@@ -74,9 +69,9 @@ async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sess
                     artifacts.set(location, artifact);
                 }
                 const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
-                    activity: entry.actIndex, seat, markSeen: entry.markSeen, signal });
+                    message: entry.messageIndex, seat, markSeen: entry.markSeen, signal });
                 if (claim !== undefined)
-                    claims.push({ key: pendingKey(entry.membership, entry.actIndex), claim });
+                    claims.push({ key: pendingKey(entry.membership, entry.messageIndex), claim });
             }
         }
         catch (error) {
@@ -87,7 +82,7 @@ async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sess
         const report = await presentPreparedBatch(claims.map(({ claim }) => claim), eligibleClaims => {
             const eligible = new Set(claims.filter(({ claim }) => eligibleClaims.includes(claim)).map(({ key }) => key));
             const delivered = pending.map(membership => ({ ...membership,
-                notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.actIndex))),
+                notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.messageIndex))),
             })).filter(membership => membership.notifications.length > 0);
             return { payload: { context: renderBoundary(delivered).context, delivered }, included: eligibleClaims };
         }, payload => present(payload.context, payload.delivered), { signal });

package/dist/catch-decisions.d.ts

@@ -1,4 +1,4 @@
-import { type StoredAct } from './model.js';
+import { type HydratedAct } from './model.js';
 import type { ActivityIndex, DirectedFilter, SquareRead, SquareWrite } from './ports.js';
 import type { CatchOptions, CatchReason, PerceivedActivity } from './square-facade.js';
 export interface CatchSelection {
@@ -14,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, remaining?: number): CatchSelection;
+export declare function observeCatchSelection(facts: SquareRead, participant: string, activities: readonly HydratedAct[], 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

@@ -33,7 +33,7 @@ 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 filter = { unseenOnly: true, ...(senders === undefined ? {} : { senders }), ...(options.mention === true ? { attentionOnly: true } : {}) };
+    const filter = { kinds: ['say'], unseenOnly: true, ...(senders === undefined ? {} : { senders }), ...(options.mention === true ? { attentionOnly: true } : {}) };
     return { participant, filter, selection: { kind: 'page', query: filter, limit } };
 }
 /** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
@@ -44,7 +44,7 @@ export function selectCatchPage(facts, requestedName, options) {
 /** Selection, receipts and resulting cursor belong to one artifact write transaction. */
 export function decideCatch(facts, requestedName, options, at) {
     let viewer;
-    let filter = { unseenOnly: true };
+    let filter = { kinds: ['say'], unseenOnly: true };
     let selection;
     if (options.id !== undefined) {
         viewer = resolveKnownName(facts, requestedName);
@@ -64,9 +64,19 @@ export function decideCatch(facts, requestedName, options, at) {
     }
     let consumed;
     try {
+        // Receipts are recorded by message coordinate; the batch hydration above already resolved each selected say.
+        let selected = new Map();
         consumed = consumeReceived({
             ...squareReceiveRead(facts),
-            insertReceipt: (ref, time) => facts.markSeen(ref.recipient, [ref.item], time) > 0,
+            load(keys) { selected = facts.activities(keys).reduce((map, item) => map.set(item.index, item), new Map()); return selected; },
+            addressed(recipient, index) {
+                const head = facts.directed(recipient, { indexes: [index], kinds: ['say'] }, { edge: 'oldest', limit: 1 }).items[0];
+                return head === undefined ? undefined : { key: head.index, via: head.route };
+            },
+            insertReceipt: (ref, time) => {
+                const item = selected.get(ref.item);
+                return item?.kind === 'say' && facts.channel.markSeen(ref.recipient, [item.messageIndex], time) > 0;
+            },
         }, viewer, selection, at);
     }
     catch (error) {
@@ -85,7 +95,7 @@ export function decideCatch(facts, requestedName, options, 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 });
+    const caught = facts.directedCount(viewer, { kinds: ['say'] }) - facts.directedCount(viewer, { kinds: ['say'], 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 - consumed.newlyConsumed, caught) : undefined;
     return hint === undefined ? observed : { ...observed, hint };

package/dist/catch-selection.d.ts

@@ -4,3 +4,11 @@ export declare function matchesCatchSelection(actor: string, audience: Audience,
     readonly participants?: readonly string[];
     readonly mention?: string;
 }, replyAuthor?: string): boolean;
+/** One directed arrival and the upper reason it reached its recipient. */
+export interface RoutedNotification {
+    readonly actor: string;
+    readonly route: import('./model.js').DirectedNotificationRoute;
+    readonly recipient: string;
+}
+/** A live catch owns every matching notification, independent of its page size. */
+export declare function leaseOwnsNotification(lease: import('./model.js').WatchLease, notification: RoutedNotification): boolean;

package/dist/catch-selection.js

@@ -12,3 +12,8 @@ export function matchesCatchSelection(actor, audience, filter, replyAuthor) {
     return audienceIncludes(audience, filter.mention)
         || (replyAuthor !== undefined && sameName(replyAuthor, filter.mention));
 }
+/** A live catch owns every matching notification, independent of its page size. */
+export function leaseOwnsNotification(lease, notification) {
+    return matchesCatchSelection(notification.actor, notification.route === 'bell' ? { kind: 'bell' }
+        : { kind: 'mentions', names: notification.route === 'mention' ? [notification.recipient] : [] }, lease.filter ?? {}, notification.route === 'reply' ? notification.recipient : undefined);
+}

package/dist/channel-artifact.d.ts

@@ -0,0 +1,10 @@
+import { type StoreTransaction } from './artifact-store.js';
+import type { ChannelArtifact, ChannelRead, ChannelWrite } from './channel-ports.js';
+import type { WakeTransportPort, WakeProjection } from './channel-transport.js';
+export declare function channelReads(channel: ChannelRead, guard: StoreTransaction['guard']): ChannelRead;
+export declare function channelWrites(channel: ChannelWrite, guard: StoreTransaction['guard']): ChannelWrite;
+/** Native Channel factories use only lower SQL and the shared physical-store lifetime. */
+export declare function openChannelArtifact(location: string, signal?: AbortSignal): ChannelArtifact;
+export declare function createMemoryChannelArtifact(description?: string): ChannelArtifact;
+export declare function createChannelArtifactFile(location: string, description: string, force: boolean, signal?: AbortSignal): Promise<void>;
+export declare function channelCourier(artifact: ChannelArtifact, transport: WakeTransportPort, location: string, clock: () => number, preparePresentation?: WakeProjection): (message?: number) => Promise<void>;

package/dist/channel-artifact.js

@@ -0,0 +1,55 @@
+import { createArtifactStore, createStoreFile, replaceStoreFile } from './artifact-store.js';
+import { channelStoreFormat, initializeStandaloneChannel } from './channel-sqlite-schema.js';
+import { createChannelSqlite } from './sqlite-channel.js';
+import { wrapChannelWrite } from './channel-domain.js';
+import { deliverPending } from './delivery-operations.js';
+import { InternalSquareError } from './neutral.js';
+const readMethods = [
+    'header', 'message', 'messages', 'messageHeads', 'messageCount', 'addresses', 'receipt', 'receiptFacts',
+    'directed', 'directedCount', 'endpoint', 'endpointsForOwner', 'endpoints', 'deliveryEvidence', 'deliveryByToken',
+    'cancelledThrough', 'deliveryDeferrals', 'receiveClaims', 'claimLease', 'suppressed',
+];
+export function channelReads(channel, guard) {
+    return Object.fromEntries(readMethods.map(name => [name, guard(channel[name])]));
+}
+export function channelWrites(channel, guard) {
+    return Object.fromEntries(Object.entries(channel).filter(([, value]) => typeof value === 'function')
+        .map(([name, value]) => [name, guard(value)]));
+}
+function channelPort(location, initialize, signal) {
+    const store = createArtifactStore(location, channelStoreFormat, initialize, signal);
+    const port = {
+        read: (select, signal) => store.run(false, ({ db, guard }) => select(channelReads(createChannelSqlite(db), guard)), signal),
+        transactAs: (authority, change, signal) => store.run(true, ({ db, guard, track }) => {
+            const channel = createChannelSqlite(db);
+            track(channel);
+            return change(wrapChannelWrite(channelReads(channel, guard), channelWrites(channel, guard), authority));
+        }, signal),
+        async claimDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.claimDelivery(input), signal)).value; },
+        async prepareDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.prepareDelivery(input), signal)).value; },
+        async completeDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.completeDelivery(input), signal)).value; },
+        async cancelDeliveries(seat, through, signal) {
+            return (await port.transactAs({ kind: 'participant', seat }, facts => {
+                const boundary = through ?? facts.header().lastMessageIndex;
+                return boundary < 0 ? false : facts.cancelThrough(seat, boundary);
+            }, signal)).value;
+        },
+        changed: store.changed, close: store.close,
+    };
+    return port;
+}
+/** Native Channel factories use only lower SQL and the shared physical-store lifetime. */
+export function openChannelArtifact(location, signal) { return channelPort(location, undefined, signal); }
+export function createMemoryChannelArtifact(description = '# Channel\n') {
+    return channelPort(':memory:', db => initializeStandaloneChannel(db, 0, description));
+}
+export async function createChannelArtifactFile(location, description, force, signal) {
+    if (force)
+        await replaceStoreFile(location, channelStoreFormat, (db, revision) => initializeStandaloneChannel(db, revision, description), signal);
+    else if (!await createStoreFile(location, channelStoreFormat, db => initializeStandaloneChannel(db, 0, description), signal))
+        throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${location}\nPass -f to overwrite.`);
+}
+export function channelCourier(artifact, transport, location, clock, preparePresentation) {
+    return (message) => deliverPending({ artifact, transport, location, now: clock(),
+        ...(preparePresentation === undefined ? {} : { preparePresentation }), ...(message === undefined ? {} : { message }) });
+}

package/dist/channel-delivery.d.ts

@@ -0,0 +1,11 @@
+import type { ChannelRead, ChannelDeliveryEvidence as DeliveryEvidence, MessageHead } from './channel-ports.js';
+/** Presentation custody blocks a wake, independently of native wake acceptance. */
+export declare function presentationBlocksWake(evidence: readonly DeliveryEvidence[], now: number): boolean;
+/** Preselection only: an expired wake dispatch is uncertain, never safe automatic replay. */
+export declare function automaticWakeEligible(evidence: readonly DeliveryEvidence[], now: number): boolean;
+/** One lower pending message: attached, unconsumed and not suppressed by a live claim. */
+export declare function pendingHeadAt(facts: ChannelRead, name: string, index: number, now?: number): MessageHead | undefined;
+/** Lower pending selection for one recipient, oldest first. */
+export declare function pendingMessageHeads(facts: ChannelRead, name: string, now?: number, suppress?: boolean): MessageHead[];
+/** Lower recipients of one message that still owe a wake; other endpoints are untouched. */
+export declare function pendingAddresses(facts: ChannelRead, index: number, now?: number): readonly MessageHead[];

package/dist/channel-delivery.js

@@ -0,0 +1,51 @@
+import { automaticDispatchEligible, presentationBlocksDispatch } from './delivery-attempts.js';
+function custody(evidence) {
+    return evidence.map(row => ({ purpose: row.kind === 'wake' ? 'dispatch' : 'presentation', outcome: row.outcome, expiresAt: row.expiresAt }));
+}
+/** Presentation custody blocks a wake, independently of native wake acceptance. */
+export function presentationBlocksWake(evidence, now) {
+    return presentationBlocksDispatch(custody(evidence), now);
+}
+/** Preselection only: an expired wake dispatch is uncertain, never safe automatic replay. */
+export function automaticWakeEligible(evidence, now) {
+    return automaticDispatchEligible(custody(evidence), now);
+}
+/** One lower pending message: attached, unconsumed and not suppressed by a live claim. */
+export function pendingHeadAt(facts, name, index, now = Date.now()) {
+    const endpoint = facts.endpoint(name);
+    if (endpoint === undefined || endpoint.attachment !== 'attached' || facts.receipt(endpoint.participant, index))
+        return undefined;
+    if (facts.suppressed(endpoint.participant, endpoint.generation, index, now))
+        return undefined;
+    return facts.directed(endpoint.participant, { afterIndex: index - 1, throughIndex: index, currentGeneration: true }, { edge: 'oldest', limit: 1 }).items[0];
+}
+/** Lower pending selection for one recipient, oldest first. */
+export function pendingMessageHeads(facts, name, now = Date.now(), suppress = true) {
+    const endpoint = facts.endpoint(name);
+    if (endpoint === undefined || endpoint.attachment !== 'attached')
+        return [];
+    const heads = [];
+    let afterIndex = -1;
+    for (;;) {
+        const page = facts.directed(endpoint.participant, { afterIndex, unseenOnly: true, currentGeneration: true }, { edge: 'oldest', limit: 100 });
+        for (const head of page.items)
+            if (!suppress || !facts.suppressed(endpoint.participant, endpoint.generation, head.index, now))
+                heads.push(head);
+        if (!page.hasMore)
+            break;
+        afterIndex = page.items.at(-1).index;
+    }
+    return heads;
+}
+/** Lower recipients of one message that still owe a wake; other endpoints are untouched. */
+export function pendingAddresses(facts, index, now = Date.now()) {
+    return facts.addresses(index).flatMap(({ recipient, generation }) => {
+        const current = facts.endpoint(recipient);
+        if (current === undefined || current.attachment !== 'attached')
+            return [];
+        if (generation !== undefined && current.generation !== generation)
+            return [];
+        const head = pendingHeadAt(facts, recipient, index, now);
+        return head === undefined ? [] : [head];
+    });
+}

package/dist/channel-domain.d.ts

@@ -0,0 +1,3 @@
+import type { ChannelRead, ChannelWrite, ChannelWriteAuthority } from './channel-ports.js';
+/** Endpoint custody and operation authority without participant membership or social events. */
+export declare function wrapChannelWrite(read: ChannelRead, write: ChannelWrite, authority: ChannelWriteAuthority): ChannelWrite;

package/dist/channel-domain.js

@@ -0,0 +1,83 @@
+import { SquareError, validateOwner } from './neutral.js';
+import { sameName, validateName } from './channel-values.js';
+import { validateEndpointGeneration } from './message.js';
+/** Endpoint custody and operation authority without participant membership or social events. */
+export function wrapChannelWrite(read, write, authority) {
+    if (!authority || !['send', 'endpoint', 'endpoint-cleanup', 'participant'].includes(authority.kind))
+        throw new SquareError('invalid_args', 'Channel writes require an explicit authority.');
+    const name = authority.kind === 'send' ? authority.actor : authority.kind === 'endpoint' ? authority.participant : authority.seat.participant;
+    validateName(name);
+    if (authority.kind !== 'send')
+        validateOwner(authority.kind === 'endpoint' ? authority.owner : authority.seat.owner);
+    const fail = () => { throw new SquareError('already_joined', 'This operation needs its captured Channel endpoint.'); };
+    const captured = authority.kind === 'participant' || authority.kind === 'endpoint-cleanup' ? authority.seat : undefined;
+    if (captured)
+        validateEndpointGeneration(captured.generation);
+    function current(ref, allowDetached = false) {
+        const actual = read.endpoint(ref.participant);
+        if (!actual || !sameName(ref.participant, name) || actual.owner !== ref.owner || actual.generation !== ref.generation
+            || !allowDetached && actual.attachment !== 'attached')
+            fail();
+    }
+    function own(ref, allowDetached = false) {
+        if (authority.kind === 'endpoint') {
+            if (!sameName(ref.participant, name) || ref.owner !== authority.owner)
+                fail();
+        }
+        else if (!captured || !sameName(ref.participant, captured.participant) || ref.owner !== captured.owner || ref.generation !== captured.generation)
+            fail();
+        current(ref, allowDetached);
+    }
+    if (authority.kind === 'participant')
+        current(authority.seat);
+    const forbidden = () => { throw new SquareError('invalid_args', 'This Channel authority does not permit that mutation.'); };
+    const facts = Object.assign({}, read, Object.fromEntries(Object.keys(write)
+        .filter(key => !(key in read)).map(key => [key, forbidden])));
+    if (authority.kind === 'send' || authority.kind === 'participant') {
+        facts.publishMessage = draft => {
+            if (!sameName(draft.from, name))
+                fail();
+            if (captured)
+                current(captured);
+            return write.publishMessage(draft);
+        };
+    }
+    if (authority.kind === 'endpoint') {
+        facts.storeEndpoint = endpoint => {
+            if (!sameName(endpoint.participant, name) || endpoint.owner !== authority.owner)
+                fail();
+            return write.storeEndpoint(endpoint);
+        };
+        facts.reattachEndpoint = (ref, address) => { own(ref, true); return write.reattachEndpoint(ref, address); };
+    }
+    if (authority.kind === 'endpoint' || authority.kind === 'participant')
+        facts.updateWakeAddress = (ref, address) => { own(ref); return write.updateWakeAddress(ref, address); };
+    if (authority.kind === 'endpoint-cleanup') {
+        // Cleanup races are harmless; storage compares the captured owner and generation.
+        const cleanup = (ref) => {
+            if (!captured || !sameName(ref.participant, captured.participant) || ref.owner !== captured.owner || ref.generation !== captured.generation)
+                fail();
+        };
+        facts.detachEndpoint = ref => { cleanup(ref); return write.detachEndpoint(ref); };
+        facts.removeEndpoint = ref => { cleanup(ref); return write.removeEndpoint(ref); };
+    }
+    if (authority.kind === 'participant') {
+        facts.markSeen = (recipient, indexes, at) => { own({ ...authority.seat, participant: recipient }); return write.markSeen(recipient, indexes, at); };
+        facts.cancelThrough = (ref, through) => {
+            own(ref);
+            if (!Number.isSafeInteger(through) || through < 0 || through >= read.header().nextMessageIndex)
+                throw new SquareError('invalid_args', 'Cancellation boundary must be an assigned message index below the allocator.');
+            return write.cancelThrough(ref, through);
+        };
+        facts.claimDelivery = input => { own(input.seat); return write.claimDelivery(input); };
+        facts.prepareDelivery = input => { own(input.seat); return write.prepareDelivery(input); };
+        facts.completeDelivery = input => { own(input.seat); return write.completeDelivery(input); };
+        facts.observeNativeDelivery = input => { own(input.seat); return write.observeNativeDelivery(input); };
+        facts.putDeliveryDeferral = (ref, ...args) => { own(ref); return write.putDeliveryDeferral(ref, ...args); };
+        facts.renewDeliveryDeferral = (ref, ...args) => { own(ref); return write.renewDeliveryDeferral(ref, ...args); };
+        facts.releaseDeliveryDeferral = (ref, ...args) => { own(ref); return write.releaseDeliveryDeferral(ref, ...args); };
+        facts.putReceiveClaim = claim => { own({ ...authority.seat, participant: claim.owner, generation: claim.generation }); return write.putReceiveClaim(claim); };
+        facts.removeReceiveClaim = (owner, namespace, id) => { own({ ...authority.seat, participant: owner }); return write.removeReceiveClaim(owner, namespace, id); };
+    }
+    return facts;
+}

package/dist/channel-facade.d.ts

@@ -0,0 +1,76 @@
+import type { MessageMetadata } from './channel-values.js';
+import type { MetadataMatch } from './channel-metadata.js';
+import type { MessageId } from './message.js';
+export type ChannelTruncate = number | false;
+export interface ChannelSendInput {
+    readonly from: string;
+    readonly to: string | readonly string[];
+    readonly body: string;
+    readonly truncate?: ChannelTruncate;
+    readonly metadata?: MessageMetadata;
+}
+export interface ChannelSendResult {
+    readonly id: MessageId;
+    readonly at: number;
+    readonly from: string;
+    readonly to: readonly string[];
+    readonly body: string;
+    readonly metadata?: MessageMetadata;
+}
+export interface ChannelEndpointSummary {
+    readonly name: string;
+    readonly generation: string;
+    readonly attachment: 'attached' | 'detached';
+    readonly deliveryAvailable: boolean;
+    readonly unreadCount: number;
+    readonly lastActiveAt?: number;
+}
+export interface ChannelMessage {
+    readonly id: MessageId;
+    readonly at: number;
+    readonly from: string;
+    readonly to: readonly string[];
+    readonly body: string;
+    readonly metadata?: MessageMetadata;
+}
+export interface ChannelPendingResult {
+    readonly messages: readonly ChannelMessage[];
+    readonly remaining: number;
+}
+export interface MessageCursor {
+    readonly id: MessageId;
+    readonly direction: 'before' | 'after';
+}
+export interface MessageSearch {
+    readonly text: string;
+    readonly mode: 'literal' | 'regex';
+}
+export interface MessageQuery {
+    readonly at?: readonly MessageId[];
+    readonly from?: readonly string[];
+    readonly match?: MetadataMatch;
+    readonly search?: MessageSearch;
+    readonly cursor?: MessageCursor;
+}
+export interface ChannelHistoryQuery extends MessageQuery {
+    readonly limit?: number | null;
+    readonly order?: 'asc' | 'desc';
+}
+export interface ChannelPendingOptions extends MessageQuery {
+    readonly limit?: number;
+}
+export interface ChannelHistoryResult {
+    readonly messages: readonly ChannelMessage[];
+}
+export interface ChannelReceiveResult extends ChannelPendingResult {
+    readonly consumed: number;
+    readonly remaining: number;
+}
+export interface AckResult {
+    readonly consumed: number;
+}
+export interface ChannelEndpointHold {
+    readonly name: string;
+    readonly generation: string;
+    readonly attachment: 'attached' | 'detached';
+}

package/dist/channel-facade.js

@@ -0,0 +1 @@
+export {};

package/dist/channel-internal.d.ts

@@ -0,0 +1,126 @@
+import { type MetadataMatch } from './delivery-deferral.js';
+import { type Owner } from './neutral.js';
+import { type WakeAddress } from './channel-values.js';
+import { type HarnessSessionChannel } from './participant-identity.js';
+import type { ChannelWriteAuthority, ChannelArtifact, EndpointFact, EndpointRef } from './channel-ports.js';
+import type { WakeTransportPort } from './channel-transport.js';
+import { validateEndpointGeneration, type MessageId } from './message.js';
+import type { AckResult, ChannelEndpointSummary, ChannelReceiveResult, ChannelPendingResult, ChannelHistoryResult, ChannelSendInput, ChannelSendResult, ChannelHistoryQuery, ChannelPendingOptions, ChannelEndpointHold } from './channel-facade.js';
+import type { DeliveryDeferral } from './delivery-deferral.js';
+import type { OperationControl, OperationFailureDetail } from './neutral.js';
+export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
+export type { MessageMetadata } from './channel-values.js';
+export type { MessageSearch, ChannelTruncate, ChannelPendingOptions, MessageCursor, MessageQuery, ChannelPendingResult, ChannelHistoryResult, ChannelHistoryQuery, AckResult, ChannelEndpointSummary, ChannelMessage, ChannelReceiveResult } from './channel-facade.js';
+export type { MessageId } from './message.js';
+export type { ChannelArtifact } from './channel-ports.js';
+export type { ChannelSendInput, ChannelSendResult, DeliveryDeferral, MetadataMatch, OperationControl, Owner, WakeAddress, WakeTransportPort, HarnessSessionChannel };
+export interface ResolvedHarnessSession {
+    readonly channel: HarnessSessionChannel;
+    readonly sessionId: string;
+    readonly agentId?: string;
+    readonly owner: Owner;
+    readonly wakeAddress?: WakeAddress;
+}
+export declare function resolveHarnessSession(env?: NodeJS.ProcessEnv): ResolvedHarnessSession | undefined;
+export interface ChannelOpenInput {
+    readonly path: string;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly clock?: () => number;
+    /** Transport for post-commit custody; `false` disables delivery for this handle. */
+    readonly wakeTransport?: WakeTransportPort | false;
+}
+export interface ChannelCreateInput extends ChannelOpenInput {
+    readonly force?: boolean;
+    readonly description?: string;
+}
+/** Every dependency one Channel needs; the artifact is already opened and narrowed. */
+export interface ChannelPortInit {
+    readonly location: string;
+    readonly artifact: ChannelArtifact;
+    readonly clock: () => number;
+    readonly deliverEffect?: (message?: number) => Promise<void>;
+    readonly indexPath?: string;
+    readonly closesArtifact?: boolean;
+}
+type EndpointOptions = {
+    readonly owner: Owner;
+    readonly wakeAddress?: WakeAddress;
+};
+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;
+/** Foundational point-to-point endpoint and messaging resource over one artifact port. */
+export declare class Channel {
+    readonly location: string;
+    readonly artifact: ChannelArtifact;
+    readonly clock: () => number;
+    private readonly deliverEffect?;
+    private readonly indexPath?;
+    private readonly closesArtifact;
+    private constructor();
+    /** Internal composition point for upper resources; no wrapping square is involved. */
+    static fromPort(init: ChannelPortInit): Channel;
+    static open(input: ChannelOpenInput, control?: OperationControl): Promise<Channel>;
+    static create(input: ChannelCreateInput, control?: OperationControl): Promise<Channel>;
+    static inMemory(input?: Omit<ChannelCreateInput, 'path' | 'force'>): Channel;
+    remember(owner: Owner): Promise<void>;
+    /** Establish a new opaque endpoint generation, or take over the existing one explicitly. */
+    attach(name: string, options: EndpointOptions & {
+        readonly takeover?: boolean;
+    }, control?: OperationControl): Promise<ChannelEndpoint>;
+    /** Restore an exact standing endpoint without changing its generation. */
+    reattach(name: string, { owner, wakeAddress }: Pick<EndpointOptions, 'owner' | 'wakeAddress'>, control?: OperationControl): Promise<ChannelEndpoint | null>;
+    private reattachEndpoint;
+    /** Select one attached endpoint held by an exact owner. */
+    endpoint(name: string, { owner }: {
+        readonly owner: Owner;
+    }): Promise<ChannelEndpoint>;
+    endpointsOf(owner: Owner): Promise<readonly ChannelEndpointHold[]>;
+    listEndpoints(control?: OperationControl): Promise<readonly ChannelEndpointSummary[]>;
+    detach(name: string, identity: {
+        readonly owner: Owner;
+        readonly generation: string;
+    }): Promise<true | null>;
+    cancelDeliveries(name: string, identity: {
+        readonly owner: Owner;
+        readonly generation: string;
+    }, control?: OperationControl): Promise<boolean>;
+    remove(name: string, identity: {
+        readonly owner: Owner;
+        readonly generation: string;
+    }): Promise<boolean>;
+    private held;
+    /** Commit one message, then run the shared custody runner outside the transaction. */
+    send(input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
+    sendAs(authority: ChannelWriteAuthority, input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
+    /** Shared post-commit custody runner. */
+    deliver(message?: number): Promise<void>;
+    history(query?: ChannelHistoryQuery, control?: OperationControl): Promise<ChannelHistoryResult>;
+    close(): Promise<void>;
+}
+/** Captures one recipient endpoint through the channel's own storage, never a wrapped square. */
+export declare class ChannelEndpoint {
+    private readonly channel;
+    private readonly endpointFact;
+    constructor(channel: Channel, endpointFact: EndpointFact);
+    get name(): string;
+    get generation(): string;
+    get ref(): EndpointRef;
+    private get storage();
+    private get participant();
+    pending(options?: ChannelPendingOptions, control?: OperationControl): Promise<ChannelPendingResult>;
+    ack(ids: readonly MessageId[], control?: OperationControl): Promise<AckResult>;
+    /** Select and consume matching unconsumed messages in one transaction. */
+    receive(options?: ChannelPendingOptions, control?: OperationControl): Promise<ChannelReceiveResult>;
+    deferDelivery(input: Readonly<{
+        match: MetadataMatch;
+        durationMs: number;
+    }>, control?: OperationControl): Promise<DeliveryDeferral>;
+    renewDeliveryDeferral(id: string, durationMs: number, control?: OperationControl): Promise<DeliveryDeferral | null>;
+    releaseDeliveryDeferral(id: string, control?: OperationControl): Promise<boolean>;
+    send(input: Omit<ChannelSendInput, 'from'>, control?: OperationControl): Promise<ChannelSendResult>;
+    /** Standalone Channel retirement; it ends no Agora membership. */
+    leave(control?: OperationControl): Promise<void>;
+}
+export { validateEndpointGeneration };