@astrosheep/square 0.3.105 → 0.4.0

package/dist/paseo-delivery.js

@@ -1,4 +1,3 @@
-import { wakePreview } from './delivery.js';
 import { DeliveryError } from './packages/agent-delivery/src/index.js';
 import { resolvePaseoDaemon } from './packages/agent-delivery/src/paseo-native.js';
 import { discoverPaseoAgents, waitForPaseoWakeBoundary } from './paseo-state.js';
@@ -44,8 +43,7 @@ export class PaseoWakeTransport {
                 diagnostic: diagnostic('selection', address, 'invalid_address'),
             };
         }
-        const payload = request.artifact === undefined ? undefined
-            : (await request.artifact.read((facts) => wakePreview(facts, request))).value;
+        const payload = request.presentation?.payload;
         if (payload === undefined)
             return { outcome: 'not-capable', diagnostic: 'No pending Square activity to preview.' };
         let remaining = remainingMs();
@@ -94,7 +92,7 @@ export class PaseoWakeTransport {
                 prompt: payload,
                 location: request.location,
                 participant: request.participant,
-                activity: request.activity,
+                message: request.message,
                 ...(request.attemptN === undefined ? {} : { attemptN: request.attemptN }),
             }, { timeoutMs: remaining });
             return { outcome: 'accepted' };

package/dist/paseo-timeline.js

@@ -40,6 +40,7 @@ export async function waitForPaseoToolBoundary(agentId, opts = {}) {
     let client;
     try {
         client = await openPaseoClient(target, daemonCredential({ endpointPassword: target.password }), 3_000);
+        await client.connect();
         return await waitSnapshots(agentId, async (id) => {
             const payload = await client.fetchAgentTimeline(id, {
                 direction: 'tail',

package/dist/plugins/opencode/delivery.js

@@ -1,10 +1,11 @@
 import { createHash } from 'node:crypto';
-import { createArtifactPort } from '../../artifact.js';
+import { squareWakeProjection } from '../../wake-preview.js';
+import { channelArtifact, createArtifactPort } from '../../artifact.js';
 import { deliverPending } from '../../delivery-operations.js';
-import { nativePendingPreview, observeSessionPending, projectSessionSeats } from '../../inbox.js';
-import { automaticWakeEligible, presentationBlocksWake } from '../../delivery.js';
+import { nativePendingSource, observeSessionPending, projectSessionSeats } from '../../inbox.js';
+import { automaticWakeEligible, nativePendingHead, presentationBlocksWake } from '../../delivery.js';
 import { harnessOwner, decodeHarnessOwner } from '../../owner.js';
-import { formatActivityId, parseActivityId } from '../../square-core.js';
+import { formatMessageId, parseMessageId } from '../../message.js';
 import { indexedSquareEntries } from '../../square-index.js';
 import { asSeatRef } from '../../seats.js';
 import { restoreSessionSeats } from '../../session-lifecycle.js';
@@ -13,18 +14,6 @@ import { createNativeInputId, sendNativeText } from '../../packages/agent-delive
 const routeKind = 'opencode-server';
 const ownerFor = (sessionId) => harnessOwner({ channel: 'opencode', session: sessionId });
 const payloadHash = (payload) => createHash('sha256').update(payload).digest('hex');
-function preview(facts, location, captured, index) {
-    const seat = facts.seat(captured.participant);
-    if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== captured.generation || seat.owner !== captured.owner)
-        return undefined;
-    const wake = seat.wakeAddress;
-    if (wake?.kind !== routeKind)
-        return undefined;
-    return nativePendingPreview(facts, {
-        location, routeKind, generation: seat.generation, participant: seat.participant,
-        actIndex: index, address: wake.address, now: Date.now(),
-    });
-}
 export async function indexedOpenCodeSessions(env) {
     return [...new Set((await indexedSquareEntries({}, env)).flatMap((entry) => {
             const coordinate = decodeHarnessOwner(entry.owner);
@@ -42,9 +31,8 @@ function createOpenCodeWakeTransport(target, lifetime) {
         probe: async (route) => !lifetime.aborted && route.kind === routeKind
             && route.address.sessionId === target.sessionId,
         async attempt(request, timeoutMs, beforeSend) {
-            const index = parseActivityId(request.activity);
-            const artifact = request.artifact;
-            if (artifact === undefined || request.claimToken === undefined || index === undefined
+            const presentation = request.presentation;
+            if (request.claimToken === undefined || parseMessageId(request.message) === undefined || presentation === undefined
                 || request.route.kind !== routeKind || request.route.address.sessionId !== target.sessionId) {
                 return { outcome: 'not-capable', diagnostic: 'OpenCode attention has no matching artifact claim or session.' };
             }
@@ -52,19 +40,14 @@ function createOpenCodeWakeTransport(target, lifetime) {
             const started = Date.now();
             if (signal.aborted || !await beforeSend())
                 return { outcome: 'not-capable', diagnostic: 'OpenCode attention changed before send.' };
-            const { value: prepared } = await artifact.read((facts) => preview(facts, request.location, request.seat, index), signal);
-            if (prepared === undefined)
-                return { outcome: 'not-capable', diagnostic: 'OpenCode attention is no longer current.' };
             const inputId = createNativeInputId();
-            const correlation = { harness: 'opencode', token: inputId, payloadHash: payloadHash(prepared.payload) };
-            if (!await artifact.prepareDelivery({ seat: request.seat, claimToken: request.claimToken, correlation }, signal))
+            const correlation = { harness: 'opencode', token: inputId, payloadHash: payloadHash(presentation.payload) };
+            if (!await request.channel.prepare({ correlation,
+                coverage: presentation.coverage, ...(presentation.description === undefined ? {} : { description: presentation.description }) }, signal))
                 return { outcome: 'not-capable', diagnostic: 'OpenCode delivery claim is no longer current.' };
-            const fresh = await artifact.read((facts) => preview(facts, request.location, request.seat, index), signal);
-            if (fresh.value === undefined || payloadHash(fresh.value.payload) !== correlation.payloadHash)
-                return { outcome: 'not-capable', diagnostic: 'OpenCode attention changed before native send.' };
             if (signal.aborted || !await beforeSend())
                 return { outcome: 'not-capable', diagnostic: 'OpenCode attention was consumed before send.' };
-            const result = await sendNativeText(target, prepared.payload, {
+            const result = await sendNativeText(target, presentation.payload, {
                 inputId, delivery: 'steer', timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)), signal,
             });
             if (result.state === 'accepted')
@@ -99,28 +82,30 @@ export async function observeOpenCodeContext(sessionId, messages, env, signal) {
                 return facts.deliveryEvidence(seat.participant, seat.generation).flatMap((evidence) => {
                     const token = evidence.correlation?.harness === 'opencode' ? evidence.correlation.token : undefined;
                     const hash = token === undefined ? undefined : observed.get(token);
-                    const index = parseActivityId(evidence.activity);
+                    const index = parseMessageId(evidence.message), now = Date.now();
                     if (token === undefined || hash === undefined || evidence.claimToken === undefined || index === undefined
-                        || !['dispatching', 'unknown', 'accepted'].includes(evidence.outcome)
-                        || evidence.correlation?.payloadHash !== hash)
+                        || evidence.route === undefined || !['dispatching', 'unknown', 'accepted'].includes(evidence.outcome)
+                        || evidence.correlation?.payloadHash !== hash
+                        || evidence.route.kind !== routeKind
+                        || presentationBlocksWake(facts.deliveryEvidence(seat.participant, seat.generation, evidence.message), now))
                         return [];
-                    const prepared = preview(facts, location, seat, index);
-                    if (prepared === undefined || payloadHash(prepared.payload) !== hash
-                        || presentationBlocksWake(facts.deliveryEvidence(seat.participant, seat.generation, evidence.activity), Date.now()))
+                    const source = nativePendingSource(facts, { location, participant: seat.participant, generation: seat.generation,
+                        owner: seat.owner, index, route: evidence.route, now });
+                    if (source === undefined)
                         return [];
-                    return [{ evidence, index, hash, clipped: prepared.clipped }];
+                    return [{ evidence, index, hash, clipped: evidence.coverage === 'clipped' }];
                 });
             }, signal);
             for (const { evidence, index, hash, clipped } of matches) {
                 if (signal.aborted || evidence.claimToken === undefined)
                     return;
                 await presentPending({ artifact, location, participant: seat.participant,
-                    activity: formatActivityId(index), seat: asSeatRef(seat), observationOf: evidence.claimToken, sink: { present() { } }, markSeen: !clipped, signal,
+                    message: formatMessageId(index), seat: asSeatRef(seat), observationOf: evidence.claimToken, sink: { present() { } }, markSeen: !clipped, signal,
                     current: (facts) => {
-                        const current = facts.seat(seat.participant);
-                        const prepared = current === undefined || !sameSeat(current, seat) ? undefined : preview(facts, location, seat, index);
                         const correlation = facts.deliveryByToken(evidence.claimToken);
-                        return prepared !== undefined && payloadHash(prepared.payload) === hash
+                        return nativePendingHead(facts, { location, participant: seat.participant, generation: seat.generation,
+                            owner: seat.owner, index, route: evidence.route, now: Date.now() }) !== undefined
+                            && ['dispatching', 'unknown', 'accepted'].includes(correlation?.outcome ?? '')
                             && correlation?.correlation?.harness === 'opencode'
                             && correlation.correlation.token !== undefined
                             && correlation.correlation.payloadHash === hash;
@@ -157,12 +142,12 @@ export async function receiveOpenCodePending(target, env, signal) {
                     const { value: notifications } = await artifact.read((facts) => {
                         if (!sameSeat(facts.seat(seat.participant), seat))
                             return [];
-                        return membership.notifications.filter((note) => automaticWakeEligible(facts.deliveryEvidence(seat.participant, seat.generation, formatActivityId(note.actIndex)), Date.now()));
+                        return membership.notifications.filter((note) => automaticWakeEligible(facts.deliveryEvidence(seat.participant, seat.generation, formatMessageId(note.messageIndex)), Date.now()));
                     }, signal);
                     for (const note of notifications) {
                         if (signal.aborted)
                             return;
-                        await deliverPending({ artifact, transport, location, activity: formatActivityId(note.actIndex), now: Date.now() });
+                        await deliverPending({ artifact: channelArtifact(artifact), preparePresentation: squareWakeProjection(artifact), transport, location, message: formatMessageId(note.messageIndex), now: Date.now() });
                     }
                 }
                 catch (error) {
@@ -213,7 +198,7 @@ export async function cancelOpenCodeDeliveries(sessionId, env, signal) {
             continue;
         const artifact = createArtifactPort(location, undefined, signal);
         try {
-            const { value: through } = await artifact.read((facts) => facts.header().lastActIndex, signal);
+            const { value: through } = await artifact.read((facts) => facts.channel.header().lastMessageIndex, signal);
             if (through >= 0)
                 await artifact.cancelDeliveries(asSeatRef(seat), through, signal);
         }

package/dist/ports.d.ts

@@ -1,7 +1,10 @@
-import type { Act, ActivityId, Owner, HardCap, Seat, StoredAct, WakeAddress, WakeRoute, WatchLease } from './model.js';
-import type { AttemptOutcome } from './delivery-attempts.js';
-import type { MetadataMatch, DeliveryDeferralFact } from './delivery-deferral.js';
+import type { ActDraft, HydratedAct, SayRelation, Owner, HardCap, Seat, StoredAct, WakeAddress, WatchLease } from './model.js';
 import type { ActivitySearch } from './square-facade.js';
+import type { IndexPage, FactPage } from './neutral.js';
+export type { WakeTransportPort, WakePresentation, WakeProjectionContext, WakeProjection, WakeRequest, WakeOutcome } from './channel-transport.js';
+export type { IndexPage, FactPage } from './neutral.js';
+import type { ChannelRead, ChannelWrite, ChannelWriteAuthority, ChannelDeliveryEvidence, ChannelDeliveryClaimInput, ChannelDeliveryClaimResult, ChannelDeliveryPreparation, ChannelDeliveryCompletion, MessageId, EndpointGeneration } from './channel-ports.js';
+export type { ChannelArtifact, ChannelRead, ChannelWrite, ChannelWriteAuthority, ChannelHeader, MessageFact, MessageAddressFact, MessageHead, MessageFilter, MessageDraft, EndpointFact, EndpointRef, ReceiveClaimFact, ChannelDeliveryEvidence, ChannelDeliveryClaimInput, ChannelDeliveryClaimResult, ChannelDeliveryPreparation, ChannelDeliveryCompletion } from './channel-ports.js';
 export type ActivityIndex = number;
 export interface SquareHeader {
     readonly revision: number;
@@ -40,6 +43,7 @@ export interface ActivityHead {
     readonly actor: string;
     readonly reach?: 'bell';
     readonly reply?: ActivityIndex;
+    readonly messageIndex?: number;
 }
 export interface ActivityFilter {
     readonly afterIndex?: number;
@@ -51,19 +55,13 @@ export interface ActivityFilter {
     readonly actorMatch?: 'identity' | 'exact';
     readonly afterAt?: number;
     /** Shared query predicates, applied before paging or counting. */
-    readonly metadataMatch?: MetadataMatch;
+    readonly metadataMatch?: import('./delivery-deferral.js').MetadataMatch;
     readonly search?: ActivitySearch;
 }
-export interface IndexPage {
-    readonly edge: 'oldest' | 'newest';
-    readonly limit: number;
-}
-export interface FactPage<T> {
-    readonly items: readonly T[];
-    readonly hasMore: boolean;
-}
+/** Upper attention filter over its own landed reasons and lower message addresses. */
 export interface DirectedFilter extends Omit<ActivityFilter, 'actors' | 'actorMatch'> {
     readonly unseenOnly?: true;
+    readonly currentGeneration?: true;
     readonly senders?: readonly string[];
     readonly attentionOnly?: true;
 }
@@ -72,21 +70,21 @@ export interface DirectedHead {
     readonly at: number;
     readonly actor: string;
     readonly recipient: string;
-    readonly route: import('./attention.js').AudienceRoute;
+    readonly route: import('./model.js').DirectedNotificationRoute;
+    readonly messageIndex: number;
+    readonly generation?: EndpointGeneration;
+}
+export interface LandedRecipient {
+    readonly recipient: string;
+    readonly route: import('./model.js').DirectedNotificationRoute;
+    readonly generation?: EndpointGeneration;
 }
-export type LandedRecipient = import('./attention.js').AudienceRecipient;
 export interface ReceiptFacts {
     readonly latestAt?: number;
     readonly latestActorActivityIndex?: number;
 }
 export type SeatRef = Pick<Seat, 'participant' | 'owner' | 'generation'>;
-export type ArtifactWriteAuthority = {
-    readonly kind: 'send';
-    readonly actor: string;
-} | {
-    readonly kind: 'participant';
-    readonly seat: SeatRef;
-} | {
+export type ArtifactWriteAuthority = ChannelWriteAuthority | {
     readonly kind: 'host-cleanup';
     readonly seat: SeatRef;
 } | {
@@ -98,79 +96,24 @@ export type ArtifactWriteAuthority = {
     readonly kind: 'takeover';
     readonly participant: string;
     readonly owner: Owner;
-    readonly expectedGeneration: ActivityId;
+    readonly expectedGeneration: EndpointGeneration;
     readonly wakeAddress?: WakeAddress;
 };
-export interface DeliveryEvidence {
-    readonly participant: string;
-    readonly generation: ActivityId;
-    readonly activity: ActivityId;
-    readonly kind: 'wake' | 'presentation';
-    readonly outcome: AttemptOutcome;
-    readonly attemptN: number;
-    readonly at: number;
-    readonly expiresAt?: number;
-    readonly claimToken?: string;
-    readonly route?: WakeAddress;
-    readonly signature?: string;
-    readonly message?: string;
-    readonly diagnostic?: import('./model.js').JsonValue;
-    readonly correlation?: {
-        readonly harness: 'claude' | 'opencode' | 'pi';
-        readonly token?: string;
-        readonly messageId?: string;
-        readonly payloadHash?: string;
-    };
-    readonly nativeObservations?: readonly {
-        readonly eventId: string;
-        readonly messageId: string;
-        readonly state: 'held' | 'released' | 'dropped';
-        readonly reason?: string;
-        readonly observedAt: number;
-    }[];
-}
-export interface DeliveryClaimInput {
-    readonly seat: SeatRef;
-    readonly activity: ActivityId;
-    readonly kind: 'wake' | 'presentation';
-    /** Observe an existing wake's exact token; never authorizes another content injection. */
-    readonly observationOf?: string;
-    readonly route?: WakeAddress;
-    readonly at: number;
-    readonly leaseMs: number;
-    readonly claimToken: string;
-}
-export type DeliveryClaimResult = {
-    readonly status: 'acquired';
-    readonly claimToken: string;
-    readonly attemptN: number;
-} | {
-    readonly status: 'busy' | 'terminal' | 'stale' | 'deferred';
-    readonly evidence?: DeliveryEvidence;
-};
-export interface DeliveryPreparation {
-    readonly seat: SeatRef;
-    readonly claimToken: string;
-    readonly correlation: NonNullable<DeliveryEvidence['correlation']>;
-}
-export interface DeliveryCompletion {
-    readonly seat: SeatRef;
-    readonly activity: ActivityId;
-    readonly claimToken: string;
-    readonly outcome: Exclude<DeliveryEvidence['outcome'], 'dispatching'>;
-    readonly at: number;
-    readonly signature?: string;
-    readonly message?: string;
-    readonly diagnostic?: import('./model.js').JsonValue;
-    readonly correlation?: DeliveryEvidence['correlation'];
-}
+export type DeliveryEvidence = ChannelDeliveryEvidence;
+export type DeliveryClaimInput = ChannelDeliveryClaimInput;
+export type DeliveryClaimResult = ChannelDeliveryClaimResult;
+export type DeliveryPreparation = ChannelDeliveryPreparation;
+export type DeliveryCompletion = ChannelDeliveryCompletion;
+export type { MessageId, EndpointGeneration };
 /** Domain facts exist only during a synchronous artifact callback. Values are detached. */
 export interface SquareRead {
+    /** Lower Channel facts. Upper layers may use them; Channel never sees this composite. */
+    readonly channel: ChannelRead;
     seat(requestedName: string): Seat | undefined;
     seatsForOwner(owner: Owner): readonly Seat[];
-    deliveryEvidence(participant: string, generation: ActivityId, activity?: ActivityId): readonly DeliveryEvidence[];
+    deliveryEvidence(participant: string, generation: EndpointGeneration, message?: MessageId): readonly DeliveryEvidence[];
     deliveryByToken(claimToken: string): DeliveryEvidence | undefined;
-    cancelledThrough(participant: string, generation: ActivityId): number | undefined;
+    cancelledThrough(participant: string, generation: EndpointGeneration): number | undefined;
     header(): SquareHeader;
     participant(requestedName: string): ParticipantFact | undefined;
     participantCounts(): ParticipantCounts;
@@ -178,8 +121,10 @@ export interface SquareRead {
     attention(listener: string): readonly AttentionFact[];
     incomingAttention(sender: string): readonly AttentionFact[];
     activity(index: ActivityIndex): StoredAct | undefined;
+    activityByMessage(messageIndex: number): SayRelation | undefined;
     activityHeads(filter: ActivityFilter, page: IndexPage): FactPage<ActivityHead>;
-    activities(indexes: readonly ActivityIndex[]): readonly StoredAct[];
+    /** The explicit content projection: each say resolved against its Channel message in one read. */
+    activities(indexes: readonly ActivityIndex[]): readonly HydratedAct[];
     activityCount(filter: ActivityFilter): number;
     contextIndexes(centers: readonly ActivityIndex[], before: number, after: number): readonly ActivityIndex[];
     sayOrdinals(indexes: readonly ActivityIndex[]): Readonly<Record<number, number>>;
@@ -188,46 +133,24 @@ export interface SquareRead {
     directed(recipient: string, filter: DirectedFilter, page: IndexPage): FactPage<DirectedHead>;
     directedAt(recipient: string, index: ActivityIndex): DirectedHead | undefined;
     directedCount(recipient: string, filter: DirectedFilter): number;
-    pendingAudience(afterExclusive: number, throughInclusive: number, activityLimit: number): {
-        readonly groups: readonly {
-            readonly index: ActivityIndex;
-            readonly at: number;
-            readonly actor: string;
-            readonly recipients: readonly LandedRecipient[];
-        }[];
-        readonly hasMore: boolean;
-    };
     receipt(requestedName: string, index: ActivityIndex): {
         readonly at: number;
     } | undefined;
     receiptFacts(requestedName: string, afterIndex: number): ReceiptFacts;
     lease(requestedName: string): WatchLease | undefined;
-    deliveryDeferrals(participant: string, generation: ActivityId): readonly DeliveryDeferralFact[];
+    deliveryDeferrals(participant: string, generation: EndpointGeneration): readonly import('./delivery-deferral.js').DeliveryDeferralFact[];
 }
 export interface SquareWrite extends SquareRead {
-    land(activity: Act & {
-        readonly at: number;
-    }): StoredAct;
+    readonly channel: ChannelWrite;
+    land(draft: ActDraft): StoredAct;
     updateWakeAddress(seat: SeatRef, wakeAddress?: WakeAddress): boolean;
     /** Join authority only; preserves membership and its establishing generation. */
     reattachSeat(seat: SeatRef, wakeAddress?: WakeAddress): boolean;
     /** Host-cleanup authority only; stale/already-detached coordinates are a no-op. */
     detachSeat(seat: SeatRef): boolean;
-    cancelThrough(seat: SeatRef, through: ActivityIndex): boolean;
-    claimDelivery(input: DeliveryClaimInput): DeliveryClaimResult;
-    prepareDelivery(input: DeliveryPreparation): boolean;
-    completeDelivery(input: DeliveryCompletion): boolean;
-    observeNativeDelivery(input: {
-        readonly seat: SeatRef;
-        readonly claimToken: string;
-        readonly observation: NonNullable<DeliveryEvidence['nativeObservations']>[number];
-    }): boolean;
-    markSeen(requestedName: string, indexes: readonly ActivityIndex[], at: number): number;
-    putLease(requestedName: string, lease: WatchLease, generation?: ActivityId): boolean;
-    removeLease(requestedName: string, expectedLeaseId: string, generation?: ActivityId): boolean;
-    putDeliveryDeferral(seat: SeatRef, id: string, match: MetadataMatch, expiresAt: number, now: number): boolean;
-    renewDeliveryDeferral(seat: SeatRef, id: string, expiresAt: number, now: number): boolean;
-    releaseDeliveryDeferral(seat: SeatRef, id: string, now: number): boolean;
+    /** Upper catch claim: the lease plus the message coverage it currently owns. */
+    putLease(requestedName: string, lease: WatchLease, generation?: EndpointGeneration, suppressed?: readonly number[]): boolean;
+    removeLease(requestedName: string, expectedLeaseId: string, generation?: EndpointGeneration): boolean;
 }
 export interface SquareReadResult<R> {
     readonly value: R;
@@ -249,8 +172,8 @@ export interface SquareArtifactPort {
     claimDelivery(input: DeliveryClaimInput, signal?: AbortSignal): Promise<DeliveryClaimResult>;
     prepareDelivery(input: DeliveryPreparation, signal?: AbortSignal): Promise<boolean>;
     completeDelivery(input: DeliveryCompletion, signal?: AbortSignal): Promise<boolean>;
-    /** Persist suppression through a fixed index, or atomically capture the current artifact head. */
-    cancelDeliveries(seat: SeatRef, through?: ActivityIndex, signal?: AbortSignal): Promise<boolean>;
+    /** Persist suppression through a fixed message, or atomically capture the current artifact head. */
+    cancelDeliveries(seat: SeatRef, through?: number, signal?: AbortSignal): Promise<boolean>;
     changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     close(): Promise<void>;
 }
@@ -264,71 +187,25 @@ export interface SquareResourceOwner {
     artifact(location: string): SquareArtifactPort;
     close(): Promise<void>;
 }
-/** Sole wake executor protocol; implementations own only transport readiness and sending. */
-export interface WakeTransportPort {
-    /** Capability check that performs no external wake and writes no evidence. */
-    probe?(route: WakeRoute): Promise<boolean | {
-        readonly outcome: 'not-capable';
-        readonly diagnostic?: string;
-    }>;
-    attempt(request: WakeRequest, timeoutMs: number, beforeSend: () => Promise<boolean>): Promise<WakeOutcome>;
-}
-export interface WakeRequest {
-    readonly location: string;
-    readonly participant: string;
-    readonly activity: string;
-    readonly actor: string;
-    readonly seat: SeatRef;
-    readonly claimToken?: string;
-    readonly attemptN?: number;
-    readonly route: WakeRoute;
-    /** Artifact context for native adapters that must persist correlation before I/O. */
-    readonly artifact?: SquareArtifactPort;
-}
 /** Executor-neutral presentation capability; intentionally separate from wake transport. */
 export interface PresentationSinkPort {
-    present(activity: StoredAct): void | Promise<void>;
-}
-export type WakeOutcome = {
-    readonly outcome: 'accepted';
-    readonly signature?: string;
-} | {
-    readonly outcome: 'failed';
-    readonly message?: string;
-    readonly signature?: string;
-    readonly diagnostic?: unknown;
-} | {
-    readonly outcome: 'not-capable';
-    readonly diagnostic?: string;
-} | {
-    readonly outcome: 'unknown';
-    readonly signature?: string;
-    readonly message?: string;
-    readonly diagnostic?: unknown;
-};
-export interface DeliverPendingInput {
-    readonly artifact: SquareArtifactPort;
-    readonly transport: WakeTransportPort;
-    readonly location: string;
-    readonly timeoutMs?: number;
-    readonly now?: number;
-    readonly activity?: string | number;
+    present(message: MessageFact): void | Promise<void>;
 }
 export interface PresentationResult {
     readonly presented: boolean;
-    readonly activity?: StoredAct;
+    readonly message?: MessageFact;
 }
 export interface PresentPendingInput {
     readonly artifact: SquareArtifactPort;
     readonly location: string;
     readonly participant: string;
-    readonly activity: string | number;
+    readonly message: string | number;
     readonly sink: PresentationSinkPort;
     /** Existing wake observed by a native receiver; the sink must not inject content. */
     readonly observationOf?: string;
     /** Captured artifact seat; used to fence both presentation and consumption. */
     readonly seat?: SeatRef;
-    readonly generation?: ActivityId;
+    readonly generation?: EndpointGeneration;
     readonly now?: number;
     readonly timeoutMs?: number;
     /** Pre-effect work control only; successful sink evidence settles independently, with a bounded lifetime. */
@@ -338,3 +215,4 @@ export interface PresentPendingInput {
     /** Receiver-specific pre-effect eligibility, never a veto of an already successful sink. */
     readonly current?: (facts: SquareRead) => boolean;
 }
+import type { MessageFact } from './channel-ports.js';

package/dist/presentation-operations.d.ts

@@ -1,18 +1,5 @@
 import type { PresentationResult, PresentPendingInput } from './ports.js';
 /** Prepare custody before any external effect. A batch prepares every included item first. */
-export declare function preparePendingPresentation(input: Omit<PresentPendingInput, 'sink'>): Promise<import("./delivery-effects.js").PreparedPresentation<{
-    kind: "say";
-    actor: import("./square-core.js").Participant;
-    at?: number;
-    body?: string;
-    metadata?: import("./model.js").ActivityMetadata;
-    delivery?: import("./model.js").ActivityDelivery;
-    mentions?: readonly import("./square-core.js").Participant[];
-    reach?: import("./square-core.js").Reach;
-    reply?: number;
-} & {
-    index: number;
-    at: number;
-}> | undefined>;
+export declare function preparePendingPresentation(input: Omit<PresentPendingInput, 'sink'>): Promise<import("./delivery-effects.js").PreparedPresentation<import("./channel-ports.js").MessageFact> | undefined>;
 /** A sink error cannot prove that content was never injected. */
 export declare function presentPending(input: PresentPendingInput): Promise<PresentationResult>;

package/dist/presentation-operations.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { formatActivityId, parseActivityId } from './square-core.js';
+import { formatMessageId, parseMessageId } from './message.js';
 import { isSquareError } from './model.js';
 import { pendingHead, sameJoin } from './delivery.js';
 import { deliveryDeferralExpiry } from './delivery-deferral.js';
@@ -7,19 +7,19 @@ import { asSeatRef } from './seats.js';
 import { preparePresentation, presentPrepared } from './delivery-effects.js';
 /** Prepare custody before any external effect. A batch prepares every included item first. */
 export async function preparePendingPresentation(input) {
-    const index = typeof input.activity === 'number' ? input.activity : parseActivityId(input.activity);
+    const named = input.message;
+    const index = typeof named === 'number' ? named : parseMessageId(named);
     if (index === undefined)
         return undefined;
     const initial = await input.artifact.read((facts) => {
-        const participant = facts.participant(input.participant);
-        const seat = facts.seat(input.participant);
-        if (!participant?.joined || seat === undefined || seat.attachment !== 'attached' || input.generation !== undefined && input.generation !== seat.generation
+        const seat = facts.channel.endpoint(input.participant);
+        if (seat === undefined || seat.attachment !== 'attached' || input.generation !== undefined && input.generation !== seat.generation
             || input.seat !== undefined && (input.seat.generation !== seat.generation || input.seat.owner !== seat.owner)
-            || input.current?.(facts) === false || !pendingHead(facts, participant.name, index)
-            || deliveryDeferralExpiry(facts, seat, index, input.now ?? Date.now()) !== undefined)
+            || input.current?.(facts) === false || !pendingHead(facts, input.participant, index)
+            || deliveryDeferralExpiry(facts.channel, seat, index, input.now ?? Date.now()) !== undefined)
             return undefined;
-        const item = facts.activity(index);
-        return item?.kind === 'say' ? { participant, seat, item } : undefined;
+        const item = facts.channel.message(index);
+        return item === undefined ? undefined : { participant: { name: input.participant, generation: seat.generation }, seat, item };
     }, input.signal).catch(() => undefined);
     if (initial?.value === undefined)
         return undefined;
@@ -35,14 +35,14 @@ export async function preparePendingPresentation(input) {
         payload: item, coverage: input.markSeen === false ? 'clipped' : 'full',
         port: {
             async claim(signal) {
-                const claimed = await input.artifact.claimDelivery({ seat: ref, activity: formatActivityId(index), kind: 'presentation',
+                const claimed = await input.artifact.claimDelivery({ seat: ref, message: formatMessageId(index), kind: 'presentation',
                     observationOf: input.observationOf, at: input.now ?? Date.now(), leaseMs: input.timeoutMs ?? 5000, claimToken }, signal).catch(() => ({ status: 'stale' }));
                 return claimed.status === 'acquired' ? { token: claimToken, ordinal: claimed.attemptN } : undefined;
             },
             async current(signal) {
                 return (await input.artifact.read(facts => owns(facts) && input.current?.(facts) !== false
                     && pendingHead(facts, participant.name, index) !== undefined
-                    && deliveryDeferralExpiry(facts, seat, index, input.now ?? Date.now()) === undefined, signal ?? input.signal)).value;
+                    && deliveryDeferralExpiry(facts.channel, seat, index, input.now ?? Date.now()) === undefined, signal ?? input.signal)).value;
             },
             async settle(claim, completion) {
                 const success = completion.outcome === 'presented' || completion.outcome === 'clipped';
@@ -50,13 +50,13 @@ export async function preparePendingPresentation(input) {
                     // Captured ownership fences truth; post-effect policy/cancellation cannot veto it.
                     if (!owns(facts))
                         return false;
-                    if (!facts.completeDelivery({ seat: ref, activity: formatActivityId(index), claimToken: claim.token,
+                    if (!facts.channel.completeDelivery({ seat: ref, message: formatMessageId(index), claimToken: claim.token,
                         outcome: completion.outcome, at: success ? input.now ?? Date.now() : Date.now(),
-                        ...(completion.reason === 'threw' ? { message: completion.error instanceof Error ? completion.error.message : String(completion.error) } : {}),
+                        ...(completion.reason === 'threw' ? { messageText: completion.error instanceof Error ? completion.error.message : String(completion.error) } : {}),
                     }))
                         return false;
                     if (completion.outcome === 'presented')
-                        facts.markSeen(participant.name, [index], input.now ?? Date.now());
+                        facts.channel.markSeen(participant.name, [index], input.now ?? Date.now());
                     return true;
                 }).catch(error => {
                     if (!success || isSquareError(error) && error.code === 'already_joined')
@@ -73,7 +73,7 @@ export async function presentPending(input) {
     const prepared = await preparePendingPresentation(input);
     if (prepared === undefined)
         return { presented: false };
-    const report = await presentPrepared(prepared, activity => input.sink.present(activity), {
+    const report = await presentPrepared(prepared, message => input.sink.present(message), {
         signal: input.signal,
     });
     if (report.observation.kind === 'threw')
@@ -82,5 +82,5 @@ export async function presentPending(input) {
     if (result.persistence.status === 'error')
         throw result.persistence.error;
     return report.observation.kind === 'returned' && result.persistence.status === 'recorded'
-        ? { presented: true, activity: prepared.payload } : { presented: false };
+        ? { presented: true, message: prepared.payload } : { presented: false };
 }

package/dist/presentation.d.ts

@@ -1,4 +1,4 @@
-import { type StoredAct, type RoomChangeAct } from './model.js';
+import { type HydratedAct, type RoomChangeAct } from './model.js';
 export { participantIdentity } from './participant-identity.js';
 import { type Perception } from './square-core.js';
 import type { Activity, UnreadActivitySummary, ParticipantSummary } from './square-facade.js';
@@ -72,19 +72,19 @@ interface RenderedEvent {
     /** The rendered body was cut short by `preview`. */
     bodyClipped: boolean;
 }
-export declare function renderEventCli(event: StoredAct | Activity, opts?: {
+export declare function renderEventCli(event: HydratedAct | Activity, opts?: {
     now?: number;
     preview?: number;
     mention?: string;
 }): string;
-export declare function renderAmbientEventFacts(event: StoredAct | Activity, viewer: string, opts?: {
+export declare function renderAmbientEventFacts(event: HydratedAct | Activity, viewer: string, opts?: {
     now?: number;
     preview?: number;
     presencePreview?: number;
     mention?: string;
     perception?: Perception;
 }): RenderedEvent;
-export declare function renderAmbientEvent(event: StoredAct | Activity, viewer: string, opts?: {
+export declare function renderAmbientEvent(event: HydratedAct | Activity, viewer: string, opts?: {
     now?: number;
     preview?: number;
     presencePreview?: number;
@@ -101,7 +101,7 @@ export declare function renderActivityUncertain(opts: ParticipantOutputOptions &
 export declare function renderExpressWaiting(opts: ExpressWaitingOptions): string;
 export declare function renderExpressNoWait(opts: ExpressNoWaitOptions): string;
 export declare function renderPresenceAnchor(names: readonly string[]): string;
-export declare function renderGrepActivitiesView(visible: readonly StoredAct[], totalMatches: number, noTruncate: boolean | undefined, squarePath: string, pattern: string, fixed?: boolean, perception?: (act: StoredAct) => Perception): string;
+export declare function renderGrepActivitiesView(visible: readonly HydratedAct[], totalMatches: number, noTruncate: boolean | undefined, squarePath: string, pattern: string, fixed?: boolean, perception?: (act: HydratedAct) => Perception): string;
 export declare function renderActivityLimit(opts: ActivityLimitOptions): string;
 export declare function renderWatchAlreadyActive(opts: ParticipantOutputOptions): string;
 export declare function renderWatchForceTakeover(_opts: ParticipantOutputOptions): string;