@astrosheep/square 0.3.77 → 0.3.79

package/dist/square-facade.d.ts

@@ -1,10 +1,8 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
 import type { StoredAct } from './model.js';
 import type { HostLedgerPort, WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
-import type { DiagnoseResult } from './artifact.js';
-import type { MigrationOutcome } from './square-migration.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
-/** The existing indexed domain event, including read and historical actorless lifecycle records. */
+/** Indexed archive event, including read and historical actorless lifecycle records. */
 export type ArchiveRecord = Readonly<StoredAct>;
 export interface Activity {
     readonly id: ActivityId;
@@ -20,35 +18,57 @@ export interface Activity {
 export interface PerceivedActivity extends Activity {
     readonly perception: Perception;
 }
-export interface ExpressOptions {
+/** Request extra facts for rendering, without changing operation semantics. */
+export interface ObservationOptions {
+    readonly observe?: boolean;
+}
+export interface ExpressOptions extends ObservationOptions {
     readonly force?: boolean;
     readonly mentions?: readonly string[];
     readonly reach?: Reach;
     readonly reply?: ActivityId;
     readonly noMention?: boolean;
+    readonly noWait?: boolean;
+    readonly requireExplicitReach?: boolean;
 }
-export interface ExpressResult {
+export interface ActivityResult {
     readonly activity: Activity;
     readonly delivery?: DeliveryResult;
+}
+export interface ExpressResult extends ActivityResult {
+    readonly waited: boolean;
     /** The replied-to author was not standing when the reply landed. */
     readonly replyAuthorNotHere?: string;
+    /** Body @name tokens with no standing match at landing; never stored on the activity. */
+    readonly unmatchedMentions?: readonly string[];
+    readonly observation?: ExpressObservation;
 }
-export interface ListenerChangeData {
+export interface ListenerChangeResult {
     readonly activity: Activity | null;
+    readonly observation?: ListenerObservation;
 }
-export type ListenerChangeResult = ListenerChangeData;
-export interface CatchOptions {
+export interface ListeningResult {
+    readonly listening: readonly string[];
+    readonly observation?: SquareObservation;
+}
+export interface LifecycleResult extends ActivityResult {
+    readonly observation?: LifecycleObservation;
+}
+export interface CatchOptions extends ObservationOptions {
     readonly id?: ActivityId;
     readonly idle?: number;
     readonly from?: readonly string[];
     readonly mention?: boolean;
     readonly limit?: number;
+    readonly replace?: boolean;
 }
 export interface CatchResult {
     readonly activities: readonly PerceivedActivity[];
     readonly consumedThrough: ActivityId | null;
     readonly idleExpired: boolean;
     readonly remaining: number;
+    readonly status?: CatchTerminalStatus;
+    readonly observation?: CatchObservation;
 }
 export interface CatchWaitStart {
     readonly idleMs: number;
@@ -69,8 +89,23 @@ export interface OperationControl {
     readonly signal?: AbortSignal;
     readonly onProgress?: (progress: OperationProgress) => void;
 }
-export interface HistoryQuery {
-    readonly limit?: number;
+export interface OperationFailureDetail {
+    readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
+    readonly subject?: 'caller' | 'filter' | 'recipient';
+    readonly participant?: string;
+    readonly expressEffect?: 'unsent' | 'landed' | 'unknown';
+    readonly landedId?: ActivityId;
+    readonly historyBounds?: {
+        readonly maxLimit: number;
+        readonly totalMatches: number;
+    };
+}
+export interface OperationError extends Error {
+    readonly operation?: OperationFailureDetail;
+}
+export interface HistoryQuery extends ObservationOptions {
+    /** Ten by default; null explicitly reads the full archive. */
+    readonly limit?: number | null;
     readonly order?: 'asc' | 'desc';
     readonly before?: ActivityId;
     readonly after?: ActivityId;
@@ -78,6 +113,14 @@ export interface HistoryQuery {
     readonly fixed?: string;
     readonly from?: readonly string[];
     readonly mention?: string;
+    readonly since?: number;
+    readonly at?: readonly ActivityId[];
+    readonly contextBefore?: number;
+    readonly contextAfter?: number;
+}
+export interface HistoryResult {
+    readonly activities: readonly Activity[];
+    readonly observation?: HistoryObservation;
 }
 export interface ParticipantStatus {
     readonly name: string;
@@ -98,132 +141,61 @@ export interface SquareSnapshot {
     readonly participants: readonly ParticipantStatus[];
     delivered(name: string, id: ActivityId): boolean;
 }
-export type SquareSource = {
-    path: string;
-};
 export interface OpenOptions {
-    clock?: () => number;
-    hostLedger?: HostLedgerPort;
-    wakeTransport?: WakeTransportPort;
-    env?: NodeJS.ProcessEnv;
-}
-export interface SquareAtInput extends SquareSource, OpenOptions {
+    readonly clock?: () => number;
+    readonly hostLedger?: HostLedgerPort;
+    readonly wakeTransport?: WakeTransportPort;
+    readonly env?: NodeJS.ProcessEnv;
 }
-export interface SquareBuildInput extends SquareSource, OpenOptions {
-    markdown: string;
-    hardCap?: number | null;
-    throttlePerMinute?: number;
-}
-/** Optional fence for owner-scoped lifecycle actions. */
-export interface OwnershipFenceOptions {
-    readonly expectedEpoch?: number;
+export interface SquareLocation {
+    readonly path?: string;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
 }
-export interface Participant {
-    readonly name: string;
-    express(body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
-    listen(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
-    ignore(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
-    listening(control?: OperationControl): Promise<readonly string[]>;
-    catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
-    history(query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
-    hold(reason?: string, control?: OperationControl): Promise<ExpressResult>;
-    resume(control?: OperationControl): Promise<ExpressResult>;
-    /** Leave without a message. Only an omitted or empty body is accepted. */
-    done(body?: string, control?: OperationControl): Promise<ExpressResult>;
-}
-export interface SquareApplicationContext extends Readonly<OpenOptions> {
-    readonly cwd: string;
-    readonly env: NodeJS.ProcessEnv;
-    readonly squarePath?: string;
+export interface SquareAtInput extends SquareLocation, OpenOptions {
     readonly participant?: string;
-    /** Borrow the owner's connection for the configured square. The caller owns its lifetime;
-     *  without an owner, each operation opens and closes its own connection. */
+    /** A caller-owned connection; closing this Square never closes its owner. */
     readonly resources?: SquareResourceOwner;
 }
-/** Data-only callers do not request or pay for presentation work. */
-export interface ApplicationOutcome<Data, Projection, Presentation extends boolean = true> {
-    readonly data: Data;
-    readonly projection: Presentation extends true ? Projection : undefined;
-}
-export interface ApplicationFailureDetail {
-    readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
-    readonly subject?: 'caller' | 'filter' | 'recipient';
-    readonly participant?: string;
-    readonly expressEffect?: 'unsent' | 'landed' | 'unknown';
-    readonly landedId?: ActivityId;
-    readonly historyBounds?: {
-        readonly maxLimit: number;
-        readonly totalMatches: number;
-    };
-}
-export interface ApplicationError extends Error {
-    readonly operation?: ApplicationFailureDetail;
-}
-export interface SquareContextProjection {
-    readonly location: string;
-    readonly standingCount: number;
-    readonly held: boolean;
-    readonly now: number;
-    readonly participant?: string;
-    readonly automaticDeliveryAvailable: boolean;
-}
-export interface BuildApplicationInput {
+export interface SquareBuildInput extends SquareAtInput {
     readonly markdown: string;
     readonly hardCap?: number | null;
     readonly throttlePerMinute?: number;
     readonly template?: string;
     readonly force?: boolean;
 }
-export interface BuildApplicationData {
-    readonly location: string;
-    readonly hardCap: number | null;
-    readonly throttlePerMinute?: number;
-}
-export interface JoinApplicationOptions {
+export interface JoinOptions extends ObservationOptions {
     readonly takeover?: boolean;
     readonly last?: number;
 }
-export interface JoinApplicationData {
-    readonly participant: string;
+export interface JoinResult {
+    readonly participant: Participant;
     readonly activity: Activity | null;
     readonly kind: 'joined' | 'reconnected' | 'taken-over';
-    /** Known joined-or-done participants, NOT the current standing count. */
+    /** Known joined-or-done participants, not the current standing count. */
     readonly participantCount: number;
+    readonly observation?: JoinObservation;
 }
-export interface ExpressApplicationOptions extends ExpressOptions {
-    readonly noWait?: boolean;
-    readonly requireExplicitReach?: boolean;
-}
-export interface ExpressApplicationData {
-    readonly activity: Activity;
-    readonly waited: boolean;
-    readonly replyAuthorNotHere?: string;
+/** Optional fence for owner-scoped lifecycle actions. */
+export interface OwnershipFenceOptions {
+    readonly expectedEpoch?: number;
 }
-export interface CatchApplicationOptions extends CatchOptions {
-    readonly replace?: boolean;
+export interface Participant {
+    readonly name: string;
+    express(body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
+    listen(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
+    ignore(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
+    listening(options?: ObservationOptions, control?: OperationControl): Promise<ListeningResult>;
+    catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
+    hold(reason?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
+    resume(options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
+    /** Leave without a message. Only an omitted or empty body is accepted. */
+    done(body?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
 }
 export type CatchTerminalStatus = 'already-active' | 'replaced' | 'capped' | 'quorum';
 export type CatchStopStatus = CatchTerminalStatus | 'empty-now' | 'stale';
-export interface CatchApplicationData extends CatchResult {
-    readonly status?: CatchTerminalStatus;
-}
-export interface HistoryApplicationQuery extends HistoryQuery {
-    readonly since?: number;
-    readonly at?: readonly ActivityId[];
-    readonly contextBefore?: number;
-    readonly contextAfter?: number;
-}
-export interface HistoryApplicationData {
-    readonly activities: readonly Activity[];
-}
-export interface ListeningData {
-    readonly listening: readonly string[];
-}
-export interface LifecycleData {
-    readonly activity: Activity;
-}
 export type ParticipantPresence = 'never-joined' | 'active' | 'watching' | 'done';
-/** Canonical public participant fields; status excludes never-joined roster entries. */
 export interface ParticipantSummary {
     readonly name: string;
     readonly state: 'active' | 'done' | 'not joined';
@@ -234,7 +206,10 @@ export interface ParticipantSummary {
     readonly unreadActivityCount: number;
     readonly pendingMentionCount: number;
 }
-export interface StatusApplicationData {
+export interface StatusOptions extends ObservationOptions {
+    readonly viewer?: string;
+}
+export interface StatusResult {
     readonly hardCap: number | null;
     readonly activeCount: number;
     readonly doneCount: number;
@@ -247,13 +222,13 @@ export interface StatusApplicationData {
         readonly at?: number;
     } | null;
     readonly latestActivity?: Activity;
+    readonly observation?: StatusObservation;
 }
-export interface ParticipantsApplicationData {
+export interface ParticipantsResult {
     readonly participants: readonly ParticipantSummary[];
+    readonly observation?: ParticipantsObservation;
 }
-export type DiagnosisApplicationData = DiagnoseResult;
-export type MigrationApplicationData = MigrationOutcome;
-export interface DiscoveryApplicationOptions {
+export interface DiscoveryOptions {
     readonly depth?: number;
     readonly limit?: number;
     readonly after?: string;
@@ -265,21 +240,14 @@ export interface SquareListItem {
     readonly participants: readonly string[];
     readonly activities: number;
 }
-export interface DiscoveryApplicationData {
+export interface DiscoveryResult {
     readonly items: readonly SquareListItem[];
     readonly stopped: boolean;
-    /** All discovered squares before applying the cursor or page limit. */
     readonly total: number;
     readonly remaining: number;
     readonly next?: string;
 }
-export interface DiscoveryProjection {
-    readonly cwd: string;
-    readonly now: number;
-    readonly depth: number;
-    readonly limit: number;
-}
-export interface InboxApplicationOptions {
+export interface InboxOptions {
     readonly limit?: number;
 }
 export interface InboxMembershipSummary {
@@ -287,16 +255,11 @@ export interface InboxMembershipSummary {
     readonly squarePath: string;
     readonly pending: number;
 }
-export interface InboxApplicationData {
+export interface InboxResult {
     readonly rows: readonly InboxMembershipSummary[];
     readonly total: number;
 }
-export interface InboxProjection {
-    readonly sessionId: string;
-    readonly now: number;
-    readonly limit: number;
-}
-export interface RecoveryApplicationData {
+export interface RecoveryResult {
     readonly participant?: string;
     readonly standingCount?: number;
     readonly held?: boolean;
@@ -306,7 +269,6 @@ export interface RecoveryApplicationData {
     readonly roster?: readonly string[];
     readonly activitySummaries?: readonly UnreadActivitySummary[];
 }
-export type RecoveryProjection = RecoveryApplicationData & Partial<SquareContextProjection>;
 export type StreamStart = {
     readonly kind: 'tail';
     readonly last: number;
@@ -314,11 +276,11 @@ export type StreamStart = {
     readonly kind: 'after';
     readonly after: number;
 };
-export interface StreamApplicationOptions {
+export interface StreamOptions {
     readonly recipient?: string;
     readonly start?: StreamStart;
 }
-export type StreamApplicationRecord = ArchiveRecord & {
+export type StreamRecord = ArchiveRecord & {
     readonly seq: number;
     readonly square: string;
     readonly route?: string;
@@ -336,33 +298,13 @@ export interface UnreadActivitySummary {
     readonly latestActivityAgeMs: number;
     readonly previews: readonly UnreadActivityPreview[];
 }
-/** Selected-row observations. participantCount in these existing concern DTOs is a standing count. */
-export interface RecoveryObservation {
-    readonly name: string;
-    readonly roster: readonly string[];
-    readonly activitySummaries: readonly UnreadActivitySummary[];
-    readonly participantCount: number;
-    readonly held: boolean;
-    readonly holdReason?: string;
-    readonly ownActivityCount: number;
-    readonly hardCap: number | null;
-}
 export interface EntryPresentation {
-    readonly joined: boolean;
     readonly joinedBefore: boolean;
     readonly scene: string;
-    readonly context: string;
     readonly joinContext: string;
     readonly recentActivities: readonly ArchiveRecord[];
     readonly perceptions: Readonly<Record<number, Perception>>;
     readonly sayNumbers: Readonly<Record<number, number>>;
-    readonly participantCount: number;
-    readonly held: boolean;
-}
-export interface HistoryContinuation {
-    readonly direction: 'before' | 'after';
-    readonly cursor: ActivityId;
-    readonly limit: number;
 }
 export interface ListPresentation {
     readonly context: readonly string[];
@@ -370,7 +312,6 @@ export interface ListPresentation {
     readonly activities: number;
 }
 export interface PresenceClassification {
-    /** Names in canonical data, watching first, then recent signs of life; no presentation clipping. */
     readonly orderedHereNames: readonly string[];
     readonly lingeringCount: number;
     readonly classificationByName: Readonly<Record<string, 'here' | 'lingering' | 'done' | 'not-joined'>>;
@@ -387,54 +328,61 @@ export interface StreamProjection {
     readonly cursor: number;
     readonly hasMore: boolean;
 }
-export interface EntryProjection extends SquareContextProjection, EntryPresentation {
+export interface SquareObservation {
+    readonly location: string;
+    readonly standingCount: number;
+    readonly held: boolean;
+    readonly now: number;
+    readonly participant?: string;
+    readonly automaticDeliveryAvailable: boolean;
+}
+export interface JoinObservation extends SquareObservation {
+    readonly entry?: EntryPresentation;
+    /** The receipt succeeded, but optional recent-history/context enrichment was unavailable. */
+    readonly enrichmentUnavailable?: true;
 }
-export interface ExpressionObservation extends Pick<SquareContextProjection, 'standingCount' | 'held' | 'now'> {
+export interface ExpressionObservation extends Pick<SquareObservation, 'standingCount' | 'held' | 'now'> {
     readonly ownActivityCount: number;
     readonly hardCap: number | null;
 }
-export interface ExpressProjection extends SquareContextProjection, ExpressionObservation {
+export interface ExpressObservation extends SquareObservation, ExpressionObservation {
     readonly participant: string;
     readonly pendingPublic: readonly ArchiveRecord[];
     readonly sayNumbers: Readonly<Record<number, number>>;
     readonly perceptions: Readonly<Record<number, Perception>>;
     readonly reentry?: Activity;
-    readonly delivery?: DeliveryResult;
 }
-export interface CatchProjection extends SquareContextProjection, ExpressionObservation {
+export interface CatchObservation extends SquareObservation, ExpressionObservation {
     readonly participant: string;
     readonly sayNumbers: Readonly<Record<number, number>>;
-    /** Optional nearby presence is not a commit-time selection fact. */
     readonly presence?: CatchPresence;
     readonly stop?: CatchStopStatus;
     readonly waitStarted?: boolean;
     readonly replaced?: boolean;
     readonly enrichmentUnavailable?: true;
 }
-export interface HistoryProjection extends SquareContextProjection {
+export interface HistoryContinuation {
+    readonly direction: 'before' | 'after';
+    readonly cursor: ActivityId;
+    readonly limit: number;
+}
+export interface HistoryObservation extends SquareObservation {
     readonly activities: readonly ArchiveRecord[];
     readonly sayNumbers: Readonly<Record<number, number>>;
     readonly presenceAnchors: Readonly<Record<number, readonly string[]>>;
     readonly totalMatches: number;
-    /** Ordinary terminal history visibility and stable continuation are owner policy. */
     readonly visibleActivities: readonly ArchiveRecord[];
     readonly continuation?: HistoryContinuation;
 }
-export interface ListenerProjection extends SquareContextProjection {
+export interface ListenerObservation extends SquareObservation {
     readonly participant: string;
     readonly target: string;
     readonly requestedTarget: string;
 }
-export interface EventPresentation {
+export interface LifecycleObservation extends SquareObservation {
     readonly activity: ArchiveRecord;
-    readonly participantCount: number;
-    readonly held: boolean;
-}
-export interface LifecycleProjection extends SquareContextProjection, EventPresentation {
-    readonly delivery?: DeliveryResult;
 }
-export interface StatusProjection extends SquareContextProjection, PresenceClassification {
-    /** Full roster size, including never-joined names omitted from status data. */
+export interface StatusObservation extends SquareObservation, PresenceClassification {
     readonly knownParticipantCount: number;
     readonly latestActNumber?: number;
     readonly latestPerception?: Perception;
@@ -446,32 +394,5 @@ export interface StatusProjection extends SquareContextProjection, PresenceClass
     readonly attentionNames: readonly string[];
     readonly viewer: string;
 }
-export interface ParticipantsProjection extends SquareContextProjection, PresenceClassification {
-}
-export interface SquareApplication<Presentation extends boolean = true> {
-    now(): number;
-    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection, Presentation>>;
-    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection, Presentation>>;
-    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection, Presentation>>;
-    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection, Presentation>>;
-    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection, Presentation>>;
-    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
-    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
-    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection, Presentation>>;
-    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
-    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
-    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
-    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection, Presentation>>;
-    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, Presentation>>;
-    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>, Presentation>>;
-    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>, Presentation>>;
-    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection, Presentation>>;
-    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection, Presentation>>;
-    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection, Presentation>>;
-    stream(options: StreamApplicationOptions, control?: OperationControl): AsyncIterable<StreamApplicationRecord>;
-}
-export type JoinApplicationResult = JoinApplicationData;
-export type ExpressApplicationResult = ExpressApplicationData;
-export type ApplicationStatus = StatusApplicationData;
-export type ApplicationStatusProjection = StatusProjection;
-export type ApplicationParticipants = ParticipantsApplicationData;
+export interface ParticipantsObservation extends SquareObservation, PresenceClassification {
+}

package/dist/square-sqlite.d.ts

@@ -25,17 +25,11 @@ export interface LegacyFraming {
     readonly userVersion: number;
     readonly journalMode: string;
 }
-/**
- * The one recovery command for an owned legacy artifact, with a shell-quoted
- * path. Kept beside framing recognition so the refusal and migration
- * instruction cannot drift apart. This codec stays free of the renderer.
- */
-export declare function migrationRecoveryCommand(location: string): string;
 /**
  * Read-only legacy framing: application id, format version, journal mode and the
  * exact owned snapshot schema. It decodes no snapshot payload, writes no pragma
- * and runs no DDL, so ordinary open can establish ownership before offering
- * the migration command. Anything else is unrelated or unsupported, not repaired.
+ * and runs no DDL, so ordinary open can establish ownership before requiring
+ * migration. Anything else is unrelated or unsupported, not repaired.
  */
 export declare function validateLegacyFraming(database: DatabaseSync, applicationId: number, location?: string): LegacyFraming;
 export declare const SCHEMA_SQL = "CREATE TABLE square_meta (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  revision INTEGER NOT NULL CHECK (revision BETWEEN 0 AND 9007199254740991),\n  next_act_index INTEGER NOT NULL CHECK (next_act_index BETWEEN 0 AND 9007199254740991),\n  hard_cap INTEGER CHECK (hard_cap BETWEEN 1 AND 9007199254740991),\n  throttle_per_minute INTEGER CHECK (throttle_per_minute BETWEEN 1 AND 9007199254740991),\n  preamble_json TEXT NOT NULL CHECK (json_valid(preamble_json)),\n  warmup_json TEXT NOT NULL CHECK (json_valid(warmup_json))\n);\nCREATE TABLE activities (\n  act_index INTEGER PRIMARY KEY CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('join','done','say','hold','resume','read','listen','ignore')),\n  actor_json TEXT COLLATE BINARY,\n  actor_key_json TEXT COLLATE BINARY,\n  reach TEXT CHECK (reach = 'bell'),\n  reply_index INTEGER CHECK (reply_index >= 0 AND reply_index < act_index),\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n  CHECK ((actor_json IS NULL) = (actor_key_json IS NULL)),\n  CHECK (kind IN ('hold','resume') OR actor_json IS NOT NULL),\n  CHECK (kind = 'say' OR (reach IS NULL AND reply_index IS NULL))\n);\nCREATE INDEX activity_kind_index ON activities(kind, act_index);\nCREATE INDEX activity_actor_index ON activities(actor_key_json, act_index);\nCREATE INDEX activity_say_actor_index ON activities(actor_key_json, act_index) WHERE kind='say';\nCREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say';\nCREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell';\n\nCREATE TABLE receipts (\n  owner_json TEXT COLLATE BINARY NOT NULL,\n  act_index INTEGER NOT NULL CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  PRIMARY KEY (owner_json, act_index)\n) WITHOUT ROWID;\nCREATE INDEX receipt_owner_time ON receipts(owner_json, at);\nCREATE TABLE catch_leases (\n  owner_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,\n  lease_id_json TEXT NOT NULL,\n  heartbeat_at REAL NOT NULL,\n  expires_at REAL NOT NULL CHECK (expires_at >= heartbeat_at),\n  filter_json TEXT CHECK (filter_json IS NULL OR json_valid(filter_json))\n) WITHOUT ROWID;\n\nCREATE TABLE routes (\n  position INTEGER PRIMARY KEY CHECK (position >= 0),\n  participant_key_json TEXT COLLATE BINARY NOT NULL,\n  session_json TEXT COLLATE BINARY NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','claude-native','paseo')),\n  updated_at REAL NOT NULL,\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json))\n);\nCREATE INDEX route_participant ON routes(participant_key_json, position);\nCREATE INDEX route_session ON routes(session_json, position);\n\nCREATE TABLE participants (\n  name_key_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,\n  name_json TEXT NOT NULL,\n  first_index INTEGER NOT NULL UNIQUE,\n  joined INTEGER NOT NULL CHECK (joined IN (0,1)),\n  done INTEGER NOT NULL CHECK (done IN (0,1)),\n  say_count INTEGER NOT NULL CHECK (say_count >= 0),\n  last_active_at REAL,\n  last_join_index INTEGER,\n  CHECK (NOT (joined=1 AND done=1))\n) WITHOUT ROWID;\nCREATE TABLE attention (\n  listener_key_json TEXT COLLATE BINARY NOT NULL,\n  target_key_json TEXT COLLATE BINARY NOT NULL,\n  target_json TEXT NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('listen','ignore')),\n  since_index INTEGER NOT NULL,\n  PRIMARY KEY (listener_key_json, target_key_json)\n) WITHOUT ROWID;\nCREATE INDEX attention_target ON attention(target_key_json, kind, listener_key_json);\nCREATE TABLE landed_audience (\n  act_index INTEGER NOT NULL,\n  recipient_key_json TEXT COLLATE BINARY NOT NULL,\n  recipient_order INTEGER NOT NULL CHECK (recipient_order >= 0),\n  route TEXT NOT NULL CHECK (route IN ('mention','reply','attention','bell')),\n  PRIMARY KEY (act_index, recipient_key_json),\n  UNIQUE (act_index, recipient_order)\n) WITHOUT ROWID;\nCREATE INDEX audience_recipient ON landed_audience(recipient_key_json, act_index);";

package/dist/square-sqlite.js

@@ -13,19 +13,11 @@ const V1_SNAPSHOT_COLUMNS = [
     { cid: 1, name: 'revision', type: 'INTEGER', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
     { cid: 2, name: 'state', type: 'TEXT', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
 ];
-/**
- * The one recovery command for an owned legacy artifact, with a shell-quoted
- * path. Kept beside framing recognition so the refusal and migration
- * instruction cannot drift apart. This codec stays free of the renderer.
- */
-export function migrationRecoveryCommand(location) {
-    return `square --location '${location.replace(/'/g, `'\\''`)}' migrate`;
-}
 /**
  * Read-only legacy framing: application id, format version, journal mode and the
  * exact owned snapshot schema. It decodes no snapshot payload, writes no pragma
- * and runs no DDL, so ordinary open can establish ownership before offering
- * the migration command. Anything else is unrelated or unsupported, not repaired.
+ * and runs no DDL, so ordinary open can establish ownership before requiring
+ * migration. Anything else is unrelated or unsupported, not repaired.
  */
 export function validateLegacyFraming(database, applicationId, location = '') {
     const identity = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
@@ -328,7 +320,7 @@ export function validateSqliteHeader(db, location = '') {
     requireFact(identity.application_id === APPLICATION_ID, 'unrelated SQLite database.');
     if (identity.user_version === 1) {
         validateLegacyFraming(db, APPLICATION_ID, location);
-        throw new SquareError('invalid_args', `Square artifact needs migration.\n${migrationRecoveryCommand(location)}`, { reason: 'migration_required' });
+        throw new SquareError('invalid_args', `Square artifact at ${location} needs migration.\nStop sessions using it, back it up, then migrate and verify before restarting.`, { reason: 'migration_required' });
     }
     requireFact(identity.user_version === 2, 'unsupported SQLite format version.');
     const actual = db.prepare("SELECT sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' AND sql IS NOT NULL").all().map(r => normalizedSql(string(r.sql))).sort();

package/dist/square-tools.d.ts

@@ -1,12 +1,13 @@
 import { z } from 'zod/v4';
-import type { ApplicationOutcome, OperationControl, SquareApplication } from './square-facade.js';
+import type { Square } from './square-api.js';
+import type { OperationControl } from './square-facade.js';
 type JsonObject = Record<string, unknown>;
-type Outcome = Promise<ApplicationOutcome<object, unknown, false>>;
+type Outcome = Promise<object>;
 interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodObject<z.ZodRawShape>;
-    run(app: SquareApplication<false>, args: JsonObject, control: OperationControl): Outcome;
+    run(square: Square, args: JsonObject, control: OperationControl): Outcome;
 }
 export declare const SQUARE_TOOL_INSTRUCTIONS = "The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.";
 export declare const SQUARE_TOOLS: readonly ToolDefinition[];