@astrosheep/square 0.3.70 → 0.3.72

package/dist/packages/agent-delivery/src/opencode.d.ts

@@ -1,14 +1,5 @@
-import { type Endpoint } from '@opencode/client/service';
-import type { OpenCodeDeliveryResult, OpenCodeTarget, OpenCodeSendTextOptions } from './types.js';
-export interface OpenCodeConnectExistingOptions {
-    readonly harness: 'opencode';
-    readonly sessionId: string;
-    readonly endpoint?: Endpoint;
-    readonly registrationFile?: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
+import type { OpenCodeConnectOptions, OpenCodeDeliveryResult, OpenCodeTarget, OpenCodeSendTextOptions } from './types.js';
 /** Resolve an existing service and persisted session. Never starts or stops a service. */
-export declare function connectExisting(options: OpenCodeConnectExistingOptions): Promise<OpenCodeTarget>;
+export declare function connectExisting(options: OpenCodeConnectOptions): Promise<OpenCodeTarget>;
 /** Submit once through the shared native sender; HTTP metadata alone refines rejection. */
 export declare function sendText(target: OpenCodeTarget, text: string, options?: OpenCodeSendTextOptions): Promise<OpenCodeDeliveryResult>;

package/dist/packages/agent-delivery/src/paseo.d.ts

@@ -1,17 +1,6 @@
-import type { PaseoDeliveryResult, PaseoSendTextOptions, PaseoTarget } from './types.js';
-export interface PaseoConnectExistingOptions {
-    readonly harness: 'paseo';
-    readonly agentId: string;
-    readonly endpoint?: string;
-    readonly password?: string;
-    readonly authHeader?: string;
-    readonly localCredential?: string;
-    readonly paseoHome?: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
+import type { PaseoConnectOptions, PaseoDeliveryResult, PaseoSendTextOptions, PaseoTarget } from './types.js';
 /** Connect to an existing daemon and address one existing agent. Never starts or stops anything. */
-export declare function connectPaseo(options: PaseoConnectExistingOptions): Promise<PaseoTarget>;
+export declare function connectPaseo(options: PaseoConnectOptions): Promise<PaseoTarget>;
 /**
  * Every call owns its daemon connection: one for connect to prove the endpoint
  * and credential, and one per send, closed again as soon as the daemon answers.

package/dist/packages/agent-delivery/src/pi-client.d.ts

@@ -1,10 +1,3 @@
-import type { PiDeliveryResult, PiSendTextOptions, PiTarget } from './types.js';
-export interface PiConnectExistingOptions {
-    readonly harness: 'pi';
-    readonly sessionId: string;
-    readonly endpoint: string;
-    readonly timeoutMs?: number;
-    readonly signal?: AbortSignal;
-}
-export declare function connectPi(options: PiConnectExistingOptions): Promise<PiTarget>;
+import type { PiConnectOptions, PiDeliveryResult, PiSendTextOptions, PiTarget } from './types.js';
+export declare function connectPi(options: PiConnectOptions): Promise<PiTarget>;
 export declare function sendPiText(target: PiTarget, text: string, options?: PiSendTextOptions): Promise<PiDeliveryResult>;

package/dist/packages/agent-delivery/src/types.d.ts

@@ -46,6 +46,48 @@ export interface PaseoSendTextOptions {
     readonly signal?: AbortSignal;
 }
 export type SendTextOptions = OpenCodeSendTextOptions | ClaudeSendTextOptions | PiSendTextOptions | PaseoSendTextOptions;
+export interface OpenCodeConnectOptions {
+    readonly harness: 'opencode';
+    readonly sessionId: string;
+    readonly endpoint?: {
+        readonly url: string;
+        readonly auth?: {
+            readonly type: 'basic';
+            readonly username: string;
+            readonly password: string;
+        };
+    };
+    readonly registrationFile?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ClaudeConnectOptions {
+    readonly harness: 'claude';
+    readonly sessionId: string;
+    readonly endpoint: string;
+    readonly token?: string;
+    readonly claudeHome?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface PiConnectOptions {
+    readonly harness: 'pi';
+    readonly sessionId: string;
+    readonly endpoint: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface PaseoConnectOptions {
+    readonly harness: 'paseo';
+    readonly agentId: string;
+    readonly endpoint?: string;
+    readonly password?: string;
+    readonly authHeader?: string;
+    readonly localCredential?: string;
+    readonly paseoHome?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
 interface OpenCodeAttempt {
     readonly harness: 'opencode';
     readonly sessionId: string;

package/dist/participant-host.d.ts

@@ -12,8 +12,11 @@ export declare function processIdentity(env: NodeJS.ProcessEnv): {
     channel: PresenceChannel;
 };
 export declare function identityRouteDraft(context: HostContext, participant: string): Promise<Omit<WakeRoute, 'updatedAt'> | undefined>;
-export declare function publishIdentityRoute(context: HostContext, participant: string, epoch?: number): Promise<void>;
+/** One postcommit host observation; presence and route publication fail independently. */
+export declare function publishCommittedIdentity(context: HostContext, participant: string, epoch?: number): Promise<void>;
 export declare function retireIdentityRoute(context: HostContext, participant: string, expectedEpoch?: number): Promise<void>;
 export declare function assertLiveOwner(context: HostContext, participant: string, expectedEpoch?: number): Promise<boolean>;
-/** Presence is best effort and runs only after the artifact mutation commits. */
-export declare function ensureLocalPresence(context: HostContext, participant: string, epoch?: number): Promise<void>;
+/** Best-effort postcommit presence; a returned epoch also witnesses a readable host observation. */
+export declare function ensureLocalPresence(context: HostContext, participant: string, epoch?: number): Promise<{
+    readonly epoch?: number;
+} | undefined>;

package/dist/participant-host.js

@@ -1,5 +1,6 @@
-import { presenceEpoch, readParticipantOwner, sessionOwnsParticipant } from './registry.js';
+import { currentOwner, presenceEpoch, sessionOwnsParticipant } from './registry.js';
 import { firstHarnessSession } from './participant-identity.js';
+import { canonicalPath } from './canonical-path.js';
 import { defaultWakeRouteCapabilities, publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, ROUTE_FRESH_MS } from './routes.js';
 export function processIdentity(env) {
     const found = firstHarnessSession(env);
@@ -13,19 +14,17 @@ export async function identityRouteDraft(context, participant) {
     const capabilities = context.hostLedger === undefined ? { canUse: () => false } : await defaultWakeRouteCapabilities(context.hostLedger);
     return resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
 }
-async function currentOwnerEpoch(context, participant) {
-    const hostLedger = context.hostLedger;
-    if (hostLedger === undefined || context.location === undefined || context.location === 'memory')
-        return undefined;
-    const owner = await readParticipantOwner(context.location, participant, hostLedger);
-    return owner === undefined ? undefined : presenceEpoch(owner);
-}
-export async function publishIdentityRoute(context, participant, epoch) {
-    const route = await identityRouteDraft(context, participant);
-    if (route === undefined)
+/** One postcommit host observation; presence and route publication fail independently. */
+export async function publishCommittedIdentity(context, participant, epoch) {
+    const observed = await ensureLocalPresence(context, participant, epoch).catch(() => undefined);
+    if (observed === undefined)
         return;
-    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
-    await publishWakeRoute(context.artifact, { ...route, ...(ownerEpoch === undefined ? {} : { epoch: ownerEpoch }) }, { at: context.clock(), requireCurrentSession: true }).catch(() => undefined);
+    try {
+        const route = await identityRouteDraft(context, participant);
+        if (route !== undefined)
+            await publishWakeRoute(context.artifact, { ...route, ...observed }, { at: context.clock(), requireCurrentSession: true });
+    }
+    catch { /* Optional route enrichment cannot undo the committed activity. */ }
 }
 export async function retireIdentityRoute(context, participant, expectedEpoch) {
     if (context.location === undefined || context.location === 'memory')
@@ -43,35 +42,42 @@ export async function assertLiveOwner(context, participant, expectedEpoch) {
         return true;
     return sessionOwnsParticipant(context.location, participant, identity.session, hostLedger, expectedEpoch);
 }
-/** Presence is best effort and runs only after the artifact mutation commits. */
+/** Best-effort postcommit presence; a returned epoch also witnesses a readable host observation. */
 export async function ensureLocalPresence(context, participant, epoch) {
     if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
         return;
     const identity = processIdentity(context.env ?? process.env);
-    const ownerEpoch = epoch ?? await currentOwnerEpoch(context, participant);
-    const now = context.clock();
-    // Semantic publish: an unexpired presence row already stands when it carries the same owner epoch.
+    const now = Date.now();
+    let existing;
     try {
-        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, now });
-        if (existing.some((row) => row.channel === identity.channel
-            && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
-            && (ownerEpoch === undefined || presenceEpoch(row) === ownerEpoch)))
-            return;
+        existing = await context.hostLedger.listPresence({ location: await canonicalPath(context.location), participant, now });
+    }
+    catch (error) {
+        process.stderr.write(`! host presence degraded: ${error instanceof Error ? error.message : String(error)}\n`);
+        return;
+    }
+    const owner = currentOwner(existing);
+    const ownerEpoch = epoch ?? (owner === undefined ? undefined : presenceEpoch(owner));
+    const observed = ownerEpoch === undefined ? {} : { epoch: ownerEpoch };
+    // A fresh exact local binding at the observed (or explicit claim) generation already stands.
+    if (existing.some((row) => row.session === identity.session && row.channel === identity.channel
+        && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
+        && (ownerEpoch === undefined || presenceEpoch(row) === ownerEpoch)))
+        return observed;
+    try {
+        const result = await context.hostLedger.ensurePresence({
+            location: context.location,
+            participant,
+            session: identity.session,
+            channel: identity.channel,
+            updatedAt: Date.now(),
+            ...(ownerEpoch === undefined || ownerEpoch <= 0 ? {} : { epoch: ownerEpoch }),
+        });
+        if (result.status === 'degraded')
+            throw result.error;
+    }
+    catch (error) {
+        process.stderr.write(`! host presence degraded: ${error instanceof Error ? error.message : String(error)}\n`);
     }
-    catch { /* fall through to the best-effort ensure below */ }
-    const result = await context.hostLedger.ensurePresence({
-        location: context.location,
-        participant,
-        session: identity.session,
-        channel: identity.channel,
-        // Presence rows are host-ledger wall-time evidence; the square clock belongs to artifact activities.
-        updatedAt: Date.now(),
-        ...(ownerEpoch === undefined || ownerEpoch <= 0 ? {} : { epoch: ownerEpoch }),
-    }).catch((error) => ({
-        status: 'degraded',
-        record: { location: context.location, participant, session: identity.session, channel: identity.channel },
-        error,
-    }));
-    if (result.status === 'degraded')
-        process.stderr.write(`! host presence degraded: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`);
+    return observed;
 }

package/dist/perception-projection.d.ts

@@ -1,15 +1,6 @@
-import { type LandedAudienceReplay, type Perception } from './square-core.js';
-import { type SquareState, type StoredAct } from './model.js';
-/**
- * The small, state-only perception surface shared by catch and delivery.
- * Notification planning deliberately remains outside this projection.
- */
-export interface PerceptionProjection {
-    directedTo(activity: StoredAct, name: string): boolean;
-    perceive(activity: StoredAct, name: string): Perception;
-    cursorFor(name: string): number;
-    isSeen(name: string, index: number): boolean;
-    readonly replayedActivityCount: number;
-}
-/** Build perception over one audience replay of a SquareState snapshot. */
-export declare function derivePerceptionProjection(state: SquareState, landed?: LandedAudienceReplay): PerceptionProjection;
+import type { Perception } from './square-core.js';
+import { type StoredAct } from './model.js';
+import type { SquareRead } from './ports.js';
+export declare function directedTo(facts: SquareRead, activity: StoredAct, name: string): boolean;
+/** Audience is settled at landing, never reconstructed from a partial history. */
+export declare function perceiveActivity(facts: SquareRead, activity: StoredAct, name: string): Perception;

package/dist/perception-projection.js

@@ -1,28 +1,8 @@
-import { formatActivityId, replayLandedAudiences } from './square-core.js';
 import { sameName } from './model.js';
-import { readCursor } from './runtime.js';
-/** Build perception over one audience replay of a SquareState snapshot. */
-export function derivePerceptionProjection(state, landed = replayLandedAudiences(state.acts)) {
-    function canonicalName(name) {
-        return landed.resolveParticipant(name) ?? name;
-    }
-    function directedTo(activity, name) {
-        return activity.kind === 'say' && landed.includes(activity, name);
-    }
-    function perceive(activity, name) {
-        if (activity.kind !== 'say' || sameName(activity.actor, name))
-            return 'full';
-        return directedTo(activity, name) ? 'full' : 'presence';
-    }
-    function isSeen(name, index) {
-        const recipient = canonicalName(name);
-        return state.runtime.observations?.[recipient]?.[formatActivityId(index)]?.state === 'seen';
-    }
-    return {
-        directedTo,
-        perceive,
-        cursorFor: (name) => readCursor(state, name, landed),
-        isSeen,
-        replayedActivityCount: landed.replayedActivityCount,
-    };
+export function directedTo(facts, activity, name) {
+    return activity.kind === 'say' && facts.directedAt(name, activity.index) !== undefined;
+}
+/** Audience is settled at landing, never reconstructed from a partial history. */
+export function perceiveActivity(facts, activity, name) {
+    return activity.kind !== 'say' || sameName(activity.actor, name) || directedTo(facts, activity, name) ? 'full' : 'presence';
 }

package/dist/plugins/opencode/delivery.js

@@ -1,9 +1,9 @@
 import { nameKey } from '../../model.js';
-import { observeSessionPending, sessionInbox } from '../../inbox.js';
+import { nativePendingPreview, observeSessionPending, sessionInbox } from '../../inbox.js';
 import { hostLedgerForEnv } from '../../registry.js';
-import { openSquare } from '../../square-file-adapter.js';
+import { openSquare } from '../../open-square.js';
 import { closeOpenSquare } from '../../open-square.js';
-import { nativePendingPreview, presentationSuppressesWake, projectPresentationEvidence } from '../../square-projections.js';
+import { presentationSuppressesWake, projectPresentationEvidence } from '../../square-projections.js';
 import { presentPending } from '../../presentation-operations.js';
 import { deliverPending } from '../../delivery-operations.js';
 import { createWakeTransport } from '../../notifications.js';
@@ -13,8 +13,8 @@ import { createNativeInputId, sendNativeText } from '../../packages/agent-delive
 const routeKind = 'opencode-server';
 const key = (location, participant, index) => `${location}\0${nameKey(participant)}\0${index}`;
 /** The one native pending preview: the audience/catch/epoch fence before send and inside presentation. */
-function preview(state, owner, index) {
-    return nativePendingPreview(state, { location: owner.location, routeKind, sessionId: owner.session, participant: owner.participant, actIndex: index, epoch: owner.epoch, address: { sessionId: owner.session }, cancelledThrough: owner.cancelledThrough, now: Date.now() });
+function preview(facts, owner, index) {
+    return nativePendingPreview(facts, { location: owner.location, routeKind, sessionId: owner.session, participant: owner.participant, actIndex: index, epoch: owner.epoch, address: { sessionId: owner.session }, cancelledThrough: owner.cancelledThrough, now: Date.now() });
 }
 function createOpenCodeWakeTransport(target, env, lifetime) {
     const ledger = hostLedgerForEnv(env);
@@ -36,14 +36,14 @@ function createOpenCodeWakeTransport(target, env, lifetime) {
                     return undefined;
                 const square = await openSquare(owner.location, { hostLedger: ledger, env, signal });
                 try {
-                    const prepared = preview((await square.artifact.read(signal)).state, owner, index);
+                    const { value: prepared } = await square.artifact.read((facts) => preview(facts, owner, index), signal);
                     if (!prepared)
                         return undefined;
                     const row = { location: owner.location, participant: owner.participant, session: target.sessionId,
                         activity: request.activity, kind: 'wake', outcome: 'dispatching', routeKind, attemptN: request.attemptN, claimToken: request.claimToken,
                         nativeDelivery: { harness: 'opencode', epoch: owner.epoch ?? 0, inputId: createNativeInputId(), payload: prepared.payload } };
                     if (!await ledger.prepareNativeWake(row) || !await (beforeSend?.() ?? Promise.resolve(true)) || signal.aborted
-                        || preview((await square.artifact.read(signal)).state, owner, index)?.payload !== prepared.payload)
+                        || (await square.artifact.read((facts) => preview(facts, owner, index)?.payload, signal)).value !== prepared.payload)
                         return undefined;
                     return { sending: sendNativeText(target, prepared.payload, { inputId: row.nativeDelivery.inputId, delivery: 'steer',
                             timeoutMs: Math.max(1, deadline - Date.now()), signal }) };
@@ -82,7 +82,7 @@ export async function observeOpenCodeContext(sessionId, messages, env, signal) {
                 continue;
             const square = await openSquare(row.location, { hostLedger: ledger, env, signal });
             try {
-                const prepared = preview((await square.artifact.read(signal)).state, owner, index);
+                const { value: prepared } = await square.artifact.read((facts) => preview(facts, owner, index), signal);
                 if (!prepared || prepared.payload !== row.nativeDelivery.payload)
                     continue;
                 const prior = await projectPresentationEvidence({ hostLedger: ledger, location: row.location, participant: row.participant, sessionId, activity: row.activity });
@@ -90,7 +90,7 @@ export async function observeOpenCodeContext(sessionId, messages, env, signal) {
                     continue;
                 await presentPending({ artifact: square.artifact, hostLedger: ledger, location: row.location, participant: row.participant, session: sessionId,
                     activity: row.activity, sink: { present() { } }, markSeen: !prepared.clipped, signal,
-                    current: (state) => !signal.aborted && preview(state, owner, index)?.payload === row.nativeDelivery.payload });
+                    current: (facts) => !signal.aborted && preview(facts, owner, index)?.payload === row.nativeDelivery.payload });
             }
             finally {
                 await closeOpenSquare(square);

package/dist/plugins/opencode/index.js

@@ -1,9 +1,9 @@
 import { automaticSessionStart, operationEnv } from '../../automatic-session.js';
 import { hostLedgerForEnv } from '../../registry.js';
 import { canonicalPath } from '../../canonical-path.js';
-import { openSquare } from '../../square-file-adapter.js';
+import { openSquare } from '../../open-square.js';
 import { closeOpenSquare } from '../../open-square.js';
-import { Square } from '../../square-wiring.js';
+import { Square } from '../../square-application.js';
 import { connectNative } from '../../packages/agent-delivery/src/opencode-native.js';
 import { observeOpenCodeContext, publishOpenCodeRoutes, receiveOpenCodePending } from './delivery.js';
 /** Actual OpenCode 2.0.20 server plugin. Harness identity belongs to ctx, never process.env. */
@@ -81,7 +81,7 @@ export default {
                 for (const owner of (await ledger.listPresence({ session: sessionId })).filter((binding) => binding.channel === 'opencode')) {
                     const square = await openSquare(owner.location, { hostLedger: ledger, env, signal: lifetime.signal });
                     try {
-                        await ledger.suppressPresence(owner, (await square.artifact.read(lifetime.signal)).state.runtime.nextActIndex - 1);
+                        await ledger.suppressPresence(owner, (await square.artifact.read((facts) => facts.header().nextActIndex - 1, lifetime.signal)).value);
                     }
                     finally {
                         await closeOpenSquare(square);

package/dist/ports.d.ts

@@ -1,16 +1,161 @@
-import type { InboxNotification, SquareState, StoredAct, WakeRoute, WatchLease } from './model.js';
+import type { Act, HardCap, InboxNotification, StoredAct, WakeRoute, WakeRouteKind, WatchLease } from './model.js';
 export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, } from './host-ledger.js';
 import type { HostLedgerPort } from './host-ledger.js';
-/** Atomic artifact access. Never exposes framing, compression, locks, or storage schema. */
+export type ActivityIndex = number;
+export interface SquareHeader {
+    readonly revision: number;
+    readonly nextActIndex: number;
+    readonly lastActIndex: number;
+    readonly hardCap: HardCap;
+    readonly throttlePerMinute?: number;
+    readonly preamble: readonly string[];
+    readonly warmup: readonly string[];
+}
+export interface ParticipantFact {
+    readonly name: string;
+    readonly firstIndex: number;
+    readonly joined: boolean;
+    readonly done: boolean;
+    readonly sayCount: number;
+    readonly lastActiveAt?: number;
+    readonly lastJoinIndex?: number;
+}
+export interface AttentionFact {
+    readonly listener: string;
+    readonly target: string;
+    readonly kind: 'listen' | 'ignore';
+    readonly sinceIndex: number;
+}
+export interface ActivityHead {
+    readonly index: ActivityIndex;
+    readonly at: number;
+    readonly kind: StoredAct['kind'];
+    readonly actor?: string;
+    readonly reach?: 'bell';
+    readonly reply?: ActivityIndex;
+}
+export interface ActivityFilter {
+    readonly afterIndex?: number;
+    readonly beforeIndex?: number;
+    readonly throughIndex?: number;
+    readonly indexes?: readonly ActivityIndex[];
+    readonly kinds?: readonly StoredAct['kind'][];
+    readonly actors?: readonly string[];
+    readonly actorMatch?: 'identity' | 'exact';
+    readonly actorRequired?: true;
+    readonly afterAt?: number;
+}
+export interface IndexPage {
+    readonly edge: 'oldest' | 'newest';
+    readonly limit: number;
+}
+export interface FactPage<T> {
+    readonly items: readonly T[];
+    readonly hasMore: boolean;
+}
+export interface DirectedFilter {
+    readonly afterIndex?: number;
+    readonly beforeIndex?: number;
+    readonly throughIndex?: number;
+    readonly unseenOnly?: true;
+    readonly senders?: readonly string[];
+    readonly attentionOnly?: true;
+}
+export interface DirectedHead {
+    readonly index: ActivityIndex;
+    readonly at: number;
+    readonly actor: string;
+    readonly recipient: string;
+    readonly route: 'mention' | 'reply' | 'attention' | 'bell';
+}
+export interface LandedRecipient {
+    readonly recipient: string;
+    readonly route: DirectedHead['route'];
+}
+export interface ReceiptFacts {
+    readonly latestAt?: number;
+    readonly latestActorActivityIndex?: number;
+}
+export interface ReceiptAssignment {
+    readonly owner: string;
+    readonly index: ActivityIndex;
+}
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export interface RouteFact {
+    readonly location: string;
+    readonly participant: string;
+    readonly sessionId: string;
+    readonly channel: string;
+    readonly kind: WakeRouteKind;
+    readonly address: Readonly<Record<string, string>>;
+    readonly updatedAt: number;
+    readonly epoch?: JsonValue;
+    readonly extra: Readonly<Record<string, JsonValue>>;
+}
+/** Domain facts exist only during a synchronous artifact callback. Values are detached. */
+export interface SquareRead {
+    header(): SquareHeader;
+    participant(requestedName: string): ParticipantFact | undefined;
+    roster(): readonly ParticipantFact[];
+    attention(listener: string): readonly AttentionFact[];
+    incomingAttention(sender: string): readonly AttentionFact[];
+    hold(): {
+        readonly active: boolean;
+        readonly at?: number;
+        readonly reason?: string;
+        readonly actor?: string;
+    };
+    activity(index: ActivityIndex): StoredAct | undefined;
+    activityHeads(filter: ActivityFilter, page: IndexPage): FactPage<ActivityHead>;
+    activities(indexes: readonly ActivityIndex[]): readonly StoredAct[];
+    activityCount(filter: ActivityFilter): number;
+    contextIndexes(centers: readonly ActivityIndex[], before: number, after: number): readonly ActivityIndex[];
+    sayOrdinals(indexes: readonly ActivityIndex[]): Readonly<Record<number, number>>;
+    recentSayTimes(afterExclusive: number, takeLatest: number, actor?: string, bellOnly?: true): readonly number[];
+    audience(index: ActivityIndex): readonly LandedRecipient[];
+    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;
+    receiptAssignments(): readonly ReceiptAssignment[];
+    lease(requestedName: string): WatchLease | undefined;
+    routes(): readonly RouteFact[];
+}
+export interface SquareWrite extends SquareRead {
+    land(activity: Act & {
+        readonly at: number;
+    }): StoredAct;
+    markSeen(requestedName: string, indexes: readonly ActivityIndex[], at: number): number;
+    putLease(requestedName: string, lease: WatchLease): boolean;
+    removeLease(requestedName: string, expectedLeaseId: string): boolean;
+    replaceRoutes(routes: readonly RouteFact[]): boolean;
+}
+export interface SquareReadResult<R> {
+    readonly value: R;
+    readonly version: number;
+}
+export interface SquareCommitResult<R> extends SquareReadResult<R> {
+    readonly changed: boolean;
+}
+/** Atomic artifact access; no framing, SQL or lazy transaction capability escapes. */
 export interface SquareArtifactPort {
-    read(signal?: AbortSignal): Promise<{
-        state: SquareState;
-        version: number;
-    }>;
-    transact<R>(fn: (state: SquareState, version: number) => {
-        state?: SquareState;
-        result: R;
-    }, signal?: AbortSignal): Promise<R>;
+    read<R>(select: (facts: SquareRead) => R, signal?: AbortSignal): Promise<SquareReadResult<R>>;
+    transact<R>(change: (facts: SquareWrite) => R, signal?: AbortSignal): Promise<SquareCommitResult<R>>;
+    revision(signal?: AbortSignal): Promise<number>;
     changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     close(): Promise<void>;
 }
@@ -121,5 +266,5 @@ export interface PresentPendingInput {
     /** Boundary previews that were clipped remain pending for a later full presentation. */
     readonly markSeen?: boolean;
     /** Receiver-specific fences checked inside the artifact observation transaction. */
-    readonly current?: (state: SquareState) => boolean;
+    readonly current?: (facts: SquareRead) => boolean;
 }

package/dist/presentation-operations.d.ts

@@ -1,3 +1,3 @@
 import type { PresentationResult, PresentPendingInput } from './ports.js';
-/** Present one pending activity; artifact seen remains the authoritative receipt. */
+/** Presentation evidence is not a receipt; only the fenced receipt transaction marks seen. */
 export declare function presentPending(input: PresentPendingInput): Promise<PresentationResult>;