@astrosheep/square 0.3.80 → 0.3.82

package/dist/square-facade.d.ts

@@ -7,7 +7,7 @@ export type ArchiveRecord = Readonly<StoredAct>;
 export interface Activity {
     readonly id: ActivityId;
     readonly at: number;
-    readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore';
+    readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore' | 'unlisten';
     readonly actor: string;
     readonly body?: string;
     readonly mentions: readonly string[];
@@ -40,6 +40,8 @@ export interface ExpressResult extends ActivityResult {
     readonly replyAuthorNotHere?: string;
     /** Body @name tokens with no standing match at landing; never stored on the activity. */
     readonly unmatchedMentions?: readonly string[];
+    /** Occasional participant-facing nudge; not part of the activity. */
+    readonly hint?: string;
     readonly observation?: ExpressObservation;
 }
 export interface ListenerChangeResult {
@@ -67,6 +69,8 @@ export interface CatchResult {
     readonly idleExpired: boolean;
     readonly remaining: number;
     readonly status?: CatchTerminalStatus;
+    /** Occasional participant-facing nudge; not part of any activity. */
+    readonly hint?: string;
     readonly observation?: CatchObservation;
 }
 export interface CatchWaitStart {
@@ -184,6 +188,7 @@ export interface Participant {
     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>;
+    unlisten(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>;

package/dist/square-migration.d.ts

@@ -8,17 +8,15 @@ export interface MigrationCounts {
     readonly routes: number;
 }
 export interface MigrationOutcome {
-    readonly status: 'migrated' | 'already-format-2';
+    readonly status: 'migrated' | 'already-current';
     /** Participants standing after the conversion, for the CLI header. */
     readonly standing: number;
     readonly counts?: MigrationCounts;
 }
 /**
- * Explicit in-place conversion of a normally persisted version 1 artifact.
- *
- * The legacy snapshot is read, validated and written here and nowhere else in
- * production; the row schema, codec and landing transition come from the driver.
- * One transaction: preflight framing, the same recheck under the lock, the
- * preserved authority, the derived facts, the format flip and a single COMMIT.
+ * Explicit in-place conversion of a version 1 snapshot or version 2 row
+ * artifact. Each source is validated before and under the write lock; v1 is
+ * imported through the normal current row initializer, while v2 rebuilds only
+ * activities and its indexes before publishing the new format version.
  */
 export declare function migrateSquareFile(location: string, signal?: AbortSignal): Promise<MigrationOutcome>;

package/dist/square-migration.js

@@ -3,7 +3,7 @@ import { inSqliteTransaction } from './sqlite-transaction.js';
 import { canonicalPath } from './canonical-path.js';
 import { isWakeRouteKind } from './model.js';
 import { parseActivityId } from './square-core.js';
-import { APPLICATION_ID, V1_SNAPSHOT_TABLE, createSqliteDriver, initializeSqlite, invalidArtifact, validateLegacyFraming, validateSqliteHeader, validateStoredActivity, validateWatchLease, } from './square-sqlite.js';
+import { APPLICATION_ID, ACTIVITIES_TABLE_SQL, ACTIVITY_INDEXES_SQL, CURRENT_USER_VERSION, V2_USER_VERSION, V1_SNAPSHOT_TABLE, createSqliteDriver, initializeSqlite, invalidArtifact, validateLegacyFraming, validateRowFraming, validateSqliteHeader, validateStoredActivity, validateWatchLease, } from './square-sqlite.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -57,7 +57,7 @@ function validateActs(value) {
     try {
         for (const candidate of value) {
             const act = validateStoredActivity(candidate);
-            if (act.index <= previous)
+            if (act.kind === 'unlisten' || act.index <= previous)
                 return false;
             previous = act.index;
         }
@@ -153,58 +153,78 @@ function counts(state) {
         routes: state.routes?.length ?? 0,
     };
 }
+function rowCounts(database) {
+    const count = (table) => Number(database.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
+    return { activities: count('activities'), receipts: count('receipts'), leases: count('catch_leases'), routes: count('routes') };
+}
+const ACTIVITY_INDEX_NAMES = ['activity_kind_index', 'activity_actor_index', 'activity_say_actor_index', 'activity_say_time', 'activity_bell_actor_time'];
+function rebuildV2Activities(database) {
+    database.exec([
+        ...ACTIVITY_INDEX_NAMES.map((name) => `DROP INDEX ${name};`),
+        'ALTER TABLE activities RENAME TO activities_v2;',
+        ACTIVITIES_TABLE_SQL,
+        'INSERT INTO activities(act_index,at,kind,actor_json,actor_key_json,reach,reply_index,payload_json) SELECT act_index,at,kind,actor_json,actor_key_json,reach,reply_index,payload_json FROM activities_v2 ORDER BY act_index;',
+        'DROP TABLE activities_v2;',
+        ...ACTIVITY_INDEXES_SQL.map((sql) => `${sql};`),
+    ].join('\n'));
+}
+function validateMigrationSource(database, location) {
+    const before = identity(database);
+    if (before.applicationId !== APPLICATION_ID)
+        throw invalidArtifact('unrelated SQLite database.');
+    if (before.userVersion === 1) {
+        validateLegacyFraming(database, APPLICATION_ID, location);
+        return 1;
+    }
+    if (before.userVersion === V2_USER_VERSION) {
+        validateRowFraming(database, V2_USER_VERSION, location);
+        createSqliteDriver(database).header();
+        return 2;
+    }
+    if (before.userVersion === CURRENT_USER_VERSION) {
+        validateSqliteHeader(database, location);
+        return undefined;
+    }
+    throw invalidArtifact('unsupported SQLite format version.');
+}
 /**
- * Explicit in-place conversion of a normally persisted version 1 artifact.
- *
- * The legacy snapshot is read, validated and written here and nowhere else in
- * production; the row schema, codec and landing transition come from the driver.
- * One transaction: preflight framing, the same recheck under the lock, the
- * preserved authority, the derived facts, the format flip and a single COMMIT.
+ * Explicit in-place conversion of a version 1 snapshot or version 2 row
+ * artifact. Each source is validated before and under the write lock; v1 is
+ * imported through the normal current row initializer, while v2 rebuilds only
+ * activities and its indexes before publishing the new format version.
  */
 export async function migrateSquareFile(location, signal) {
     const squarePath = await canonicalPath(location);
     const database = openExistingSquareDatabase(squarePath);
     try {
-        // Owned framing, read-only, before any pragma or DDL touches the artifact.
-        // Every preflight statement reads one snapshot taken in the helper's
-        // retryable stage: a transient writer lock is waited out like any other
-        // acquisition, and a migrator that commits while we look cannot move the
-        // artifact between the identity read and the schema reads.
-        let alreadyConverted;
+        let alreadyCurrent;
         const preflight = await inSqliteTransaction(database, false, () => {
-            const before = identity(database);
-            if (before.applicationId === APPLICATION_ID && before.userVersion === 1) {
-                validateLegacyFraming(database, APPLICATION_ID, squarePath);
-                return;
-            }
-            // A row artifact means another migrator finished here; anything else is
-            // refused by the row header itself.
-            validateSqliteHeader(database, squarePath);
-            alreadyConverted = { status: 'already-format-2', standing: standing(database) };
-        }, () => alreadyConverted, signal);
-        if (preflight !== undefined)
-            return preflight;
+            const source = validateMigrationSource(database, squarePath);
+            if (source === undefined)
+                alreadyCurrent = { status: 'already-current', standing: standing(database) };
+            return source;
+        }, (source) => source, signal);
+        if (preflight === undefined)
+            return alreadyCurrent;
         database.exec('PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL');
         const result = {};
         await inSqliteTransaction(database, true, () => {
-            // Another migration may have finished between preflight and this lock.
-            const locked = identity(database);
-            if (locked.applicationId !== APPLICATION_ID || locked.userVersion !== 1) {
-                // A valid row artifact is done already; anything else is refused here.
-                validateSqliteHeader(database, squarePath);
-                return;
-            }
-            validateLegacyFraming(database, APPLICATION_ID, squarePath);
-            result.converted = true;
+            const source = validateMigrationSource(database, squarePath);
+            result.source = source;
         }, () => {
-            if (result.converted !== true)
-                return;
-            const legacy = decodeLegacySnapshot(database);
-            initializeSqlite(database, legacy.state, legacy.revision);
-            database.exec(`DROP TABLE ${V1_SNAPSHOT_TABLE}; PRAGMA user_version = 2`);
-            result.outcome = { status: 'migrated', standing: standing(database), counts: counts(legacy.state) };
+            if (result.source === 1) {
+                const legacy = decodeLegacySnapshot(database);
+                initializeSqlite(database, legacy.state, legacy.revision);
+                database.exec(`DROP TABLE ${V1_SNAPSHOT_TABLE}; PRAGMA user_version = ${CURRENT_USER_VERSION}`);
+                result.outcome = { status: 'migrated', standing: standing(database), counts: counts(legacy.state) };
+            }
+            else if (result.source === 2) {
+                rebuildV2Activities(database);
+                database.exec(`PRAGMA user_version = ${CURRENT_USER_VERSION}`);
+                result.outcome = { status: 'migrated', standing: standing(database), counts: rowCounts(database) };
+            }
         }, signal);
-        return result.outcome ?? { status: 'already-format-2', standing: standing(database) };
+        return result.outcome ?? { status: 'already-current', standing: standing(database) };
     }
     finally {
         database.close();

package/dist/square-sqlite.d.ts

@@ -19,6 +19,8 @@ export interface SquareState {
 }
 export declare function emptyRuntimeState(nextActIndex?: number): SquareRuntimeState;
 export declare const APPLICATION_ID = 1397838405;
+export declare const V2_USER_VERSION = 2;
+export declare const CURRENT_USER_VERSION = 3;
 export declare const V1_SNAPSHOT_TABLE = "square_snapshot";
 export interface LegacyFraming {
     readonly applicationId: number;
@@ -32,11 +34,15 @@ export interface LegacyFraming {
  * 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);";
+export declare const ACTIVITIES_TABLE_SQL = "CREATE 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','unlisten')),\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);";
+export declare const ACTIVITY_INDEXES_SQL: readonly ["CREATE INDEX activity_kind_index ON activities(kind, act_index)", "CREATE INDEX activity_actor_index ON activities(actor_key_json, act_index)", "CREATE INDEX activity_say_actor_index ON activities(actor_key_json, act_index) WHERE kind='say'", "CREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say'", "CREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell'"];
+export declare const SCHEMA_SQL: string;
+export declare const SCHEMA_SQL_V2: string;
 export declare function invalidArtifact(detail: string): SquareError;
 export declare function validateStoredActivity(value: unknown): StoredAct;
 export declare function validateWatchLease(value: unknown): WatchLease;
 export declare function validateRoute(value: unknown): RouteFact;
+export declare function validateRowFraming(db: DatabaseSync, version: 2 | 3, location?: string): void;
 export declare function validateSqliteHeader(db: DatabaseSync, location?: string): SquareHeader;
 export interface SqliteDriver extends SquareRead, LandingWriter {
     readonly changed: boolean;

package/dist/square-sqlite.js

@@ -6,6 +6,8 @@ export function emptyRuntimeState(nextActIndex = 0) {
 }
 export const APPLICATION_ID = 0x53515245;
 const V1_USER_VERSION = 1;
+export const V2_USER_VERSION = 2;
+export const CURRENT_USER_VERSION = 3;
 export const V1_SNAPSHOT_TABLE = 'square_snapshot';
 const V1_SNAPSHOT_DDL = `CREATE TABLE ${V1_SNAPSHOT_TABLE} (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL CHECK(revision>=0), state TEXT NOT NULL)`;
 const V1_SNAPSHOT_COLUMNS = [
@@ -50,19 +52,12 @@ export function validateLegacyFraming(database, applicationId, location = '') {
 function normalizedLegacySql(sql) {
     return sql.trim().replace(/\s+/g, ' ').replace(/\s*(>=|[(),=])\s*/g, '$1');
 }
-export const SCHEMA_SQL = `CREATE TABLE square_meta (
-  id INTEGER PRIMARY KEY CHECK (id = 1),
-  revision INTEGER NOT NULL CHECK (revision BETWEEN 0 AND 9007199254740991),
-  next_act_index INTEGER NOT NULL CHECK (next_act_index BETWEEN 0 AND 9007199254740991),
-  hard_cap INTEGER CHECK (hard_cap BETWEEN 1 AND 9007199254740991),
-  throttle_per_minute INTEGER CHECK (throttle_per_minute BETWEEN 1 AND 9007199254740991),
-  preamble_json TEXT NOT NULL CHECK (json_valid(preamble_json)),
-  warmup_json TEXT NOT NULL CHECK (json_valid(warmup_json))
-);
-CREATE TABLE activities (
+const V2_ACTIVITY_KIND_CHECK = "kind IN ('join','done','say','hold','resume','read','listen','ignore')";
+const CURRENT_ACTIVITY_KIND_CHECK = "kind IN ('join','done','say','hold','resume','read','listen','ignore','unlisten')";
+export const ACTIVITIES_TABLE_SQL = `CREATE TABLE activities (
   act_index INTEGER PRIMARY KEY CHECK (act_index BETWEEN 0 AND 9007199254740991),
   at REAL NOT NULL,
-  kind TEXT NOT NULL CHECK (kind IN ('join','done','say','hold','resume','read','listen','ignore')),
+  kind TEXT NOT NULL CHECK (${CURRENT_ACTIVITY_KIND_CHECK}),
   actor_json TEXT COLLATE BINARY,
   actor_key_json TEXT COLLATE BINARY,
   reach TEXT CHECK (reach = 'bell'),
@@ -71,12 +66,25 @@ CREATE TABLE activities (
   CHECK ((actor_json IS NULL) = (actor_key_json IS NULL)),
   CHECK (kind IN ('hold','resume') OR actor_json IS NOT NULL),
   CHECK (kind = 'say' OR (reach IS NULL AND reply_index IS NULL))
+);`;
+export const ACTIVITY_INDEXES_SQL = [
+    'CREATE INDEX activity_kind_index ON activities(kind, act_index)',
+    'CREATE INDEX activity_actor_index ON activities(actor_key_json, act_index)',
+    "CREATE INDEX activity_say_actor_index ON activities(actor_key_json, act_index) WHERE kind='say'",
+    "CREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say'",
+    "CREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell'",
+];
+export const SCHEMA_SQL = `CREATE TABLE square_meta (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  revision INTEGER NOT NULL CHECK (revision BETWEEN 0 AND 9007199254740991),
+  next_act_index INTEGER NOT NULL CHECK (next_act_index BETWEEN 0 AND 9007199254740991),
+  hard_cap INTEGER CHECK (hard_cap BETWEEN 1 AND 9007199254740991),
+  throttle_per_minute INTEGER CHECK (throttle_per_minute BETWEEN 1 AND 9007199254740991),
+  preamble_json TEXT NOT NULL CHECK (json_valid(preamble_json)),
+  warmup_json TEXT NOT NULL CHECK (json_valid(warmup_json))
 );
-CREATE INDEX activity_kind_index ON activities(kind, act_index);
-CREATE INDEX activity_actor_index ON activities(actor_key_json, act_index);
-CREATE INDEX activity_say_actor_index ON activities(actor_key_json, act_index) WHERE kind='say';
-CREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say';
-CREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell';
+${ACTIVITIES_TABLE_SQL}
+${ACTIVITY_INDEXES_SQL.join(';\n')};
 
 CREATE TABLE receipts (
   owner_json TEXT COLLATE BINARY NOT NULL,
@@ -134,6 +142,8 @@ CREATE TABLE landed_audience (
 ) WITHOUT ROWID;
 CREATE INDEX audience_recipient ON landed_audience(recipient_key_json, act_index);`;
 const EXPECTED_SCHEMA_SQL = SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
+export const SCHEMA_SQL_V2 = SCHEMA_SQL.replace(CURRENT_ACTIVITY_KIND_CHECK, V2_ACTIVITY_KIND_CHECK);
+const EXPECTED_SCHEMA_SQL_V2 = SCHEMA_SQL_V2.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const encode = JSON.stringify;
 const key = (name) => encode(nameKey(name));
 export function invalidArtifact(detail) {
@@ -189,7 +199,7 @@ function immutable(value) {
     }
     return value;
 }
-const kinds = ['join', 'done', 'say', 'hold', 'resume', 'read', 'listen', 'ignore'];
+const kinds = ['join', 'done', 'say', 'hold', 'resume', 'read', 'listen', 'ignore', 'unlisten'];
 function head(row) {
     const index = integer(row.act_index), at = finite(row.at);
     requireFact(kinds.includes(string(row.kind)));
@@ -237,6 +247,7 @@ export function validateStoredActivity(value) {
             break;
         case 'listen':
         case 'ignore':
+        case 'unlisten':
             shape(a, [...common, 'target']);
             string(a.target, true);
             break;
@@ -247,7 +258,7 @@ export function validateStoredActivity(value) {
 function activity(row) {
     const h = head(row), payload = object(json(row.payload_json));
     // Payload cannot shadow indexed structural columns.
-    const allowed = h.kind === 'say' ? ['body', 'mentions'] : h.kind === 'done' || h.kind === 'hold' ? ['body'] : h.kind === 'read' ? ['through'] : h.kind === 'listen' || h.kind === 'ignore' ? ['target'] : [];
+    const allowed = h.kind === 'say' ? ['body', 'mentions'] : h.kind === 'done' || h.kind === 'hold' ? ['body'] : h.kind === 'read' ? ['through'] : h.kind === 'listen' || h.kind === 'ignore' || h.kind === 'unlisten' ? ['target'] : [];
     requireFact(Object.keys(payload).every(k => allowed.includes(k)));
     return immutable(validateStoredActivity({ ...h, ...payload }));
 }
@@ -315,6 +326,17 @@ function route(row) {
     }));
 }
 function normalizedSql(sql) { return sql.trim().replace(/;$/, '').replace(/\s+/g, ' ').replace(/\s*([(),=])\s*/g, '$1'); }
+function validateOwnedSchema(db, expected, location) {
+    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();
+    requireFact(actual.length === expected.length && actual.every((sql, i) => sql === expected[i]), 'unsupported row schema.');
+    requireFact(db.prepare('PRAGMA journal_mode').get().journal_mode === (location === ':memory:' ? 'memory' : 'delete'), 'unsupported journal mode.');
+}
+export function validateRowFraming(db, version, location = '') {
+    const identity = db.prepare('SELECT application_id,user_version FROM pragma_application_id,pragma_user_version').get();
+    requireFact(identity.application_id === APPLICATION_ID, 'unrelated SQLite database.');
+    requireFact(identity.user_version === version, 'unsupported SQLite format version.');
+    validateOwnedSchema(db, version === V2_USER_VERSION ? EXPECTED_SCHEMA_SQL_V2 : EXPECTED_SCHEMA_SQL, location);
+}
 export function validateSqliteHeader(db, location = '') {
     const identity = db.prepare('SELECT application_id,user_version FROM pragma_application_id,pragma_user_version').get();
     requireFact(identity.application_id === APPLICATION_ID, 'unrelated SQLite database.');
@@ -322,10 +344,12 @@ export function validateSqliteHeader(db, location = '') {
         validateLegacyFraming(db, APPLICATION_ID, location);
         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();
-    requireFact(actual.length === EXPECTED_SCHEMA_SQL.length && actual.every((sql, i) => sql === EXPECTED_SCHEMA_SQL[i]), 'unsupported row schema.');
-    requireFact(db.prepare('PRAGMA journal_mode').get().journal_mode === (location === ':memory:' ? 'memory' : 'delete'), 'unsupported journal mode.');
+    if (identity.user_version === V2_USER_VERSION) {
+        validateRowFraming(db, V2_USER_VERSION, location);
+        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 === CURRENT_USER_VERSION, 'unsupported SQLite format version.');
+    validateRowFraming(db, CURRENT_USER_VERSION, location);
     return createSqliteDriver(db).header();
 }
 function activitySelection(filter, alias = 'a') {
@@ -550,6 +574,12 @@ export function createSqliteDriver(db) {
             }
             if (effect.removeListeningOf !== undefined)
                 run("DELETE FROM attention WHERE listener_key_json=? AND kind='listen'", [key(effect.removeListeningOf)]);
+            if (effect.removeListening !== undefined) {
+                const target = effect.removeListening;
+                string(target.listener, true);
+                string(target.target, true);
+                run("DELETE FROM attention WHERE listener_key_json=? AND target_key_json=? AND kind='listen'", [key(target.listener), key(target.target)]);
+            }
             if (effect.replaceAttention) {
                 const t = effect.replaceAttention;
                 string(t.listener, true);

package/dist/square-tools.js

@@ -34,8 +34,9 @@ export const SQUARE_TOOLS = [
         limit: z.number().int().min(1).optional(), order: z.enum(['asc', 'desc']).optional(), before: activityId.optional(), after: activityId.optional(),
         grep: z.string().optional(), fixed: z.string().optional(), from: stringArray.optional(), mention: z.string().optional(),
     }, (square, args, control) => square.history(args, control)),
-    tool('listen', 'Listen for future bare activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).listen(target, {}, control)),
+    tool('listen', 'Listen for future activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).listen(target, {}, control)),
     tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).ignore(target, {}, control)),
+    tool('unlisten', 'Stop listening to a participant’s future activity; mentions and replies still reach you. An existing ignore is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).unlisten(target, {}, control)),
     tool('listening', 'List participants this participant is listening to.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).listening({}, control)),
     tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, async (square, { as, reason }, control) => (await square.participant(as)).hold(reason, {}, control)),
     tool('resume', 'Release the current hold.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).resume({}, control)),

package/dist/views.d.ts

@@ -6,7 +6,7 @@ import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, Operat
 export type { EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
-export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume", "listen", "ignore"];
+export declare const NON_READ: readonly ["join", "done", "say", "hold", "resume", "listen", "ignore", "unlisten"];
 /** The one StoredAct-to-public-Activity field mapping. Rejects read and actorless acts. */
 export declare function toPublicActivity(stored: StoredAct): Activity;
 export declare function parseRequiredActivityId(id: ActivityId): number;

package/dist/views.js

@@ -9,7 +9,7 @@ export const HISTORY_DEFAULT_LIMIT = 10;
 export const HISTORY_MAX_LIMIT = 100;
 const STATUS_HERE_WINDOW_MS = 30 * 60_000;
 const PRESENCE_WINDOW_MS = 8 * 60 * 60_000;
-export const NON_READ = ['join', 'done', 'say', 'hold', 'resume', 'listen', 'ignore'];
+export const NON_READ = ['join', 'done', 'say', 'hold', 'resume', 'listen', 'ignore', 'unlisten'];
 const ARCHIVE = new Set(['join', 'done', 'say', 'hold', 'resume']);
 /** The one StoredAct-to-public-Activity field mapping. Rejects read and actorless acts. */
 export function toPublicActivity(stored) {

package/guides/claude-native.md

@@ -50,9 +50,9 @@ protocol, resident service or ledger schema migration is introduced.
 
 ## Membership and lifecycle
 
-If `.square/PUBLIC.square` already exists, the mod joins the automatic participant.
-It never creates PUBLIC. Existing manual memberships also reconcile independently
-of PUBLIC. Main-conversation tool completion (including failed/aborted tools) and
+Participants join explicitly. The mod never discovers or joins a square from its
+filename; `PUBLIC.square` has no special behavior. Existing memberships reconcile
+on startup. Main-conversation tool completion (including failed/aborted tools) and
 conversation start reconcile late memberships: the receiver itself publishes
 routes; the CLI cannot infer mod capability from a socket or session environment.
 This reconciliation injects no activity and does not poll. Its recovery sweep

package/guides/migration.md

@@ -1,78 +1,75 @@
-# Migrating an existing square to row storage
+# Migrating an existing square
 
 Square stores authority in one versioned SQLite artifact. Version 1 kept the
-whole history as one JSON snapshot; version 2 keeps typed rows — activities,
-sparse receipts, catch leases, ordered routes and the small configuration
-facts — in one in-place database.
+whole history as one JSON snapshot. Version 2 introduced typed rows. Current
+format 3 adds the `unlisten` history event without changing the other tables.
 
-Existing artifacts are **not** converted automatically. A normal read of a
-version 1 artifact refuses with a descriptive offline-migration requirement.
-The CLI adds the concrete recovery command; native tools retain the description:
+Existing artifacts are **not** converted automatically. Ordinary reads and
+writes refuse versions 1 and 2 with an offline-migration requirement. The CLI
+adds the concrete recovery command; native tools retain the description:
 
 ```sh
 square --location /path/to/SQUARE.square migrate
 ```
 
-That is the only migration command. There is no `--check`, `--backup`,
-`--force`, bulk mode, sidecar, daemon or dual reader, and no operator
-configuration to set.
+This is the only artifact migration command. There is no `--check`, `--backup`,
+`--force`, bulk mode, sidecar, daemon or dual reader. The host ledger is a
+separate resource; unlisten does not change its format.
 
 ## What the command does
 
-It converts the artifact **in place**, in **one transaction**:
-
-1. Reads the owned legacy framing before touching anything (application id,
-   format version, `DELETE` journal mode, the exact snapshot schema) and
-   refuses anything that is not an owned version 1 square.
-2. Takes `BEGIN IMMEDIATE`, re-checks that framing under the lock, and decodes
-   and validates the complete snapshot inside the lock.
-3. Creates the row schema and writes the preserved authority: activity indices
-   and their gaps, optional-field presence, raw receipt and lease owner keys,
-   route order and duplicates, string content and finite fractional timestamps.
-4. Rebuilds the derived participant, hold, attention and landed-audience facts
-   through the same single landing transition the runtime uses.
-5. Drops the snapshot table, sets the format version, and commits once.
-
-The revision is preserved; migration never invents or advances it. Nothing is
-published piecemeal, and the file keeps its path, inode and registry identity.
-
-Two shapes are already fine and change nothing:
-
-- an artifact that is already version 2 (reported as already format 2);
-- an artifact converted by another process while this one waited for the lock.
+Both supported conversions happen **in place**, in **one transaction**:
+
+1. Read the owned framing before any persistent pragma or DDL: application id,
+   source format, `DELETE` journal mode, and exact known schema.
+2. Take `BEGIN IMMEDIATE` and re-check that framing under the lock.
+3. Convert the source using its explicit path:
+   - **Version 1:** decode and validate the complete snapshot, create current
+     rows, and preserve activity indices/gaps, optional fields, raw receipt and
+     lease owners, ordered routes, strings and finite fractional timestamps.
+     Rebuild derived participant, hold, attention and landed-audience facts
+     with the runtime's shared landing transition, then drop the snapshot.
+   - **Version 2:** rebuild only `activities` and its indexes to accept
+     `unlisten`, copying every existing activity row unchanged. All other
+     tables, including attention, landed audience, receipts, leases, routes
+     and configuration, remain untouched. No history is reinterpreted.
+4. Set format 3 and commit once.
+
+Revision and assigned activity indices are preserved. Migration adds no domain
+activity. Nothing is published piecemeal, and path, inode and registry identity
+remain unchanged. A format-3 artifact is reported as already current without
+writing, including when another migrator finished while this one waited.
 
 ## What it refuses
 
-Nothing is written when the input is not a normally persisted version 1 square:
-a missing file, an unrelated SQLite database, an unsupported format version, a
-different journal mode, an unknown snapshot schema, unreadable snapshot JSON, or
-a route carrying a non-finite number (an exponent-overflow value such as
-`1e999`, which the previous permissive check accepted and an ordinary JSON round
-trip cannot carry) are all refused before any write. The refusal names the
-offending route property.
-
-Journal mode is never rewritten to make a migration possible.
+Missing files, unrelated databases, unsupported versions, different journal
+modes, unknown schemas and malformed headers are refused without a write.
+Version-1 snapshot JSON and activity vocabulary must be valid for that source
+format. Non-finite numbers anywhere in a legacy route, including nested extra
+properties, are refused with the offending property named; they are not
+silently coerced to null. Journal mode is never rewritten to make conversion
+possible, and migration is not a corruption-repair command.
 
 ## Before you migrate
 
-- Stop attached runtimes, or upgrade them together with the migration. An
-  in-flight remote delivery is not revoked by migration, and a version 1 writer
-  either commits before the conversion or is refused afterwards — it can never
-  overwrite converted rows.
-- An offline backup is optional and, if you want one, ordinary: copy the file
-  while no writer is attached. The command does not manage backups.
+Stop every session and service using that artifact. Make an offline backup, or
+use SQLite's backup facilities rather than copying a live database. The command
+does not manage backups, stop processes, revoke in-flight remote deliveries,
+or update installed runtimes.
 
-## Crash safety
+Upgrade all attached runtimes before reopening the migrated artifact. Both
+version-1 and version-2 runtimes refuse format 3; do not mix old and new
+processes against the converted file. An older writer either commits before
+conversion or meets the new version gate afterwards.
 
-Before `COMMIT`, SQLite's own journal recovers the complete version 1 artifact;
-after it, the complete version 2 rows are there. A process killed mid-migration
-therefore leaves one or the other, never a partial artifact, and re-running the
-command finishes the job. A busy `COMMIT` retries the same transaction and never
-re-runs the conversion.
+## Crash safety and checking
 
-## Checking an artifact
+Before `COMMIT`, SQLite's journal recovers the complete source version; after
+it, complete format-3 rows are present. A failure or process death cannot leave
+a partial conversion. A busy `COMMIT` retries the same transaction, never the
+copy or domain callback.
 
-`square --location <path> doctor` is read-only. On a legacy artifact it
-recognizes version 1 and prints the migration command; it does not call the
-artifact damaged. On version 2 it validates the rows and recomputes the derived
-indices to compare them against the stored ones.
+`square --location <path> doctor` is read-only. On versions 1 and 2 it prints
+the migration requirement without calling the artifact damaged. On current
+format 3 it validates rows and recomputes derived indices for comparison.
+Run it after migration and before restarting upgraded clients.

package/guides/row-storage-design.md

@@ -1,6 +1,9 @@
 # Row-oriented artifact design
 
-**Status: design closed; row runtime candidate implemented and measured, awaiting independent review/acceptance.**
+**Historical accepted design for artifact format 2.** The current runtime uses format 3 for the
+`unlisten` event; see [Square API](square-api.md#artifact-format-and-explicit-migration) for current
+format/migration behavior. The schema and delivery-stage terms below record the original row-storage
+replacement, not a pending implementation or a second current-format definition.
 Source baseline: `99679eb` (0.3.70). This document specifies the design; [runtime delivery evidence](row-runtime-delivery-evidence.md) records implementation verification and actual capacity measurements. Explicit migration remains a separately accepted delivery.
 
 ## Decision in brief