@astrosheep/square 0.3.94 → 0.3.96

package/dist/square-legacy-framing.js

@@ -15,6 +15,14 @@ CREATE INDEX route_session ON routes(session_json, position);`;
 function normalizedSql(sql) {
     return sql.trim().replace(/;$/, '').replace(/\s+/g, ' ').replace(/\s*([(),=])\s*/g, '$1');
 }
+/** Historical activity framing only; no runtime activity decoder accepts these kinds. */
+export function legacyActivitySchema(currentSchemaSql) {
+    return currentSchemaSql
+        .replace("kind IN ('join','done','say','read','listen','ignore','unlisten')", "kind IN ('join','done','say','hold','resume','read','listen','ignore','unlisten')")
+        .replace('  actor_json TEXT COLLATE BINARY NOT NULL,', '  actor_json TEXT COLLATE BINARY,')
+        .replace('  actor_key_json TEXT COLLATE BINARY NOT NULL,', '  actor_key_json TEXT COLLATE BINARY,')
+        .replace("  CHECK (kind = 'say' OR (reach IS NULL AND reply_index IS NULL))", "  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))");
+}
 function legacyRowSchema(currentSchemaSql, version) {
     const statements = currentSchemaSql.split(';').map((statement) => statement.trim()).filter(Boolean)
         .filter((statement) => {

package/dist/square-migration.d.ts

@@ -20,8 +20,10 @@ export interface MigrationOutcome {
 /**
  * Explicit conversion of the supported legacy formats. Row-backed versions 2 and 3 are
  * preflighted read-only, then receive ownership/evidence and deferral storage in one
- * format-7 transaction. Formats 4/5 gain attachment; format 4 also gains empty deferrals.
+ * format-8 transaction. Formats 4/5 gain attachment; format 4 also gains empty deferrals.
  * All legacy seats are encoded as opaque owners, preserving format-6 attachment.
+ * Every source drops obsolete activities and their identity references, clears dangling
+ * replies and rebuilds derived indices; surviving ids and allocation watermarks remain stable.
  * Legacy delivery evidence is copied from HostLedger only when its owner/session mapping is
  * unique; no source record is retired. Version 1 is not a supported source for this format transition.
  */

package/dist/square-migration.js

@@ -1,3 +1,4 @@
+import { DatabaseSync } from 'node:sqlite';
 import { createHash } from 'node:crypto';
 import { openExistingSquareDatabase } from './artifact.js';
 import { inSqliteTransaction } from './sqlite-transaction.js';
@@ -7,7 +8,7 @@ import { formatActivityId, isWakeRouteKind, nameKey } from './model.js';
 import { parseActivityId } from './square-core.js';
 import { readLegacyHostData } from './square-migration-host-ledger.js';
 import { legacyRowFramingIssue, FORMAT4_ADDED_OBJECTS } from './square-legacy-framing.js';
-import { APPLICATION_ID, ACTIVITIES_TABLE_SQL, ACTIVITY_INDEXES_SQL, CURRENT_USER_VERSION, V2_USER_VERSION, V3_USER_VERSION, V4_USER_VERSION, V5_USER_VERSION, V6_USER_VERSION, SCHEMA_SQL, FORMAT4_SCHEMA_SQL, DELIVERY_DEFERRALS_SQL, validateRowFraming, inspectSqlite, createSqliteDriver, invalidArtifact, validateStoredActivity } from './square-sqlite.js';
+import { APPLICATION_ID, ACTIVITIES_TABLE_SQL, ACTIVITY_INDEXES_SQL, CURRENT_USER_VERSION, V2_USER_VERSION, V3_USER_VERSION, V4_USER_VERSION, V5_USER_VERSION, V6_USER_VERSION, V7_USER_VERSION, SCHEMA_SQL, FORMAT4_SCHEMA_SQL, DELIVERY_DEFERRALS_SQL, validateRowFraming, inspectSqlite, createSqliteDriver, invalidArtifact, validateStoredActivity, exportSqliteState, initializeSqlite } from './square-sqlite.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -134,15 +135,44 @@ function standing(database) {
     return createSqliteDriver(database).roster().filter((participant) => participant.joined).length;
 }
 const ACTIVITY_INDEX_NAMES = ['activity_kind_index', 'activity_actor_index', 'activity_say_actor_index', 'activity_say_time', 'activity_bell_actor_time'];
-function rebuildV2Activities(database) {
+function migrateActivities(database) {
+    // Only activity identity references are deleted. Range watermarks (read.through and
+    // delivery cancellation boundaries) remain meaningful even when their endpoint is gone.
+    for (const table of ['landed_audience', 'receipts', 'delivery_evidence']) {
+        database.exec(`DELETE FROM ${table} WHERE act_index IN (SELECT act_index FROM activities WHERE kind IN ('hold','resume'));`);
+    }
     database.exec([
+        "UPDATE activities SET reply_index=NULL WHERE reply_index IN (SELECT act_index FROM activities WHERE kind IN ('hold','resume'));",
         ...ACTIVITY_INDEX_NAMES.map((name) => `DROP INDEX ${name};`),
-        'ALTER TABLE activities RENAME TO activities_v2;',
+        'ALTER TABLE activities RENAME TO activities_legacy;',
         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;',
+        "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_legacy WHERE kind NOT IN ('hold','resume') ORDER BY act_index;",
+        'DROP TABLE activities_legacy;',
         ...ACTIVITY_INDEXES_SQL.map((sql) => `${sql};`),
     ].join('\n'));
+    // Actor-bearing deleted activities and cleared replies can change maintained indices.
+    // Replay surviving facts only, without lowering the authoritative next allocator.
+    const names = database.prepare('SELECT name_key_json,name_json FROM participants').all();
+    const rebuilt = new DatabaseSync(':memory:');
+    try {
+        initializeSqlite(rebuilt, exportSqliteState(database));
+        // Canonical spelling is an established identity fact, not the spelling of
+        // whichever actor activity happens to survive this migration first.
+        const retainName = rebuilt.prepare('UPDATE participants SET name_json=? WHERE name_key_json=?');
+        for (const row of names)
+            retainName.run(row.name_json, row.name_key_json);
+        for (const table of ['participants', 'attention', 'landed_audience']) {
+            database.exec(`DELETE FROM ${table};`);
+            for (const row of rebuilt.prepare(`SELECT * FROM ${table}`).all()) {
+                const columns = Object.keys(row);
+                database.prepare(`INSERT INTO ${table}(${columns.join(',')}) VALUES(${columns.map(() => '?').join(',')})`)
+                    .run(...Object.values(row));
+            }
+        }
+    }
+    finally {
+        rebuilt.close();
+    }
 }
 function validateCurrentFraming(database, location) {
     validateRowFraming(database, CURRENT_USER_VERSION, location);
@@ -282,7 +312,7 @@ function inspectLegacyRowArtifact(database, location, host) {
     const driver = createSqliteDriver(database);
     let activityCount = 0;
     let previous = -1;
-    for (const row of database.prepare('SELECT act_index FROM activities ORDER BY act_index').iterate()) {
+    for (const row of database.prepare("SELECT act_index FROM activities WHERE kind NOT IN ('hold','resume') ORDER BY act_index").iterate()) {
         const index = sourceInteger(row.act_index);
         assertSource(index > previous && index < nextActIndex, 'activity index is malformed or unassigned.');
         const activity = driver.activity(index);
@@ -389,7 +419,7 @@ function planLegacyDeliveries(records, seats, driver) {
             continue;
         const joined = establishingJoin(driver, participant);
         const generation = formatActivityId(joined);
-        if (index <= joined || driver.activity(index)?.kind !== 'say' || driver.directedAt(participant.name, index) === undefined)
+        if (index <= joined || driver.activityHeads({ indexes: [index], kinds: ['say'] }, { edge: 'oldest', limit: 1 }).items.length === 0 || driver.directedAt(participant.name, index) === undefined)
             continue;
         if (participant.done) {
             const done = driver.activityHeads({ actors: [participant.name], kinds: ['done'] }, { edge: 'newest', limit: 1 }).items[0];
@@ -488,6 +518,7 @@ function upgradeRowArtifact(database, location, plan) {
     importOwnershipAndEvidence(database, plan);
     database.exec('DROP TABLE routes;');
     database.exec(DELIVERY_DEFERRALS_SQL);
+    migrateActivities(database);
     database.exec(`PRAGMA user_version = ${CURRENT_USER_VERSION};`);
     validateCurrentFraming(database, location);
 }
@@ -501,7 +532,7 @@ function validateMigrationSource(database, location) {
             throw invalidArtifact(issue);
         return before.userVersion;
     }
-    if (before.userVersion === V4_USER_VERSION || before.userVersion === V5_USER_VERSION || before.userVersion === V6_USER_VERSION) {
+    if (before.userVersion === V4_USER_VERSION || before.userVersion === V5_USER_VERSION || before.userVersion === V6_USER_VERSION || before.userVersion === V7_USER_VERSION) {
         validateRowFraming(database, before.userVersion, location);
         return before.userVersion;
     }
@@ -514,8 +545,10 @@ function validateMigrationSource(database, location) {
 /**
  * Explicit conversion of the supported legacy formats. Row-backed versions 2 and 3 are
  * preflighted read-only, then receive ownership/evidence and deferral storage in one
- * format-7 transaction. Formats 4/5 gain attachment; format 4 also gains empty deferrals.
+ * format-8 transaction. Formats 4/5 gain attachment; format 4 also gains empty deferrals.
  * All legacy seats are encoded as opaque owners, preserving format-6 attachment.
+ * Every source drops obsolete activities and their identity references, clears dangling
+ * replies and rebuilds derived indices; surviving ids and allocation watermarks remain stable.
  * Legacy delivery evidence is copied from HostLedger only when its owner/session mapping is
  * unique; no source record is retired. Version 1 is not a supported source for this format transition.
  */
@@ -526,13 +559,15 @@ export async function migrateSquareFile(location, signal, env = process.env) {
         const source = await inSqliteTransaction(database, false, () => validateMigrationSource(database, squarePath), value => value, signal);
         if (source === undefined)
             return { status: 'already-current', standing: standing(database) };
-        if (source === V4_USER_VERSION || source === V5_USER_VERSION || source === V6_USER_VERSION) {
+        if (source === V4_USER_VERSION || source === V5_USER_VERSION || source === V6_USER_VERSION || source === V7_USER_VERSION) {
             return await inSqliteTransaction(database, true, () => {
                 assertSource(validateMigrationSource(database, squarePath) === source, 'source format changed during migration preflight.');
             }, () => {
                 if (source === V4_USER_VERSION)
                     database.exec(DELIVERY_DEFERRALS_SQL);
-                migrateSeatOwnership(database, source);
+                if (source !== V7_USER_VERSION)
+                    migrateSeatOwnership(database, source);
+                migrateActivities(database);
                 database.exec(`PRAGMA user_version = ${CURRENT_USER_VERSION};`);
                 validateCurrentFraming(database, squarePath);
                 return { status: 'migrated', standing: standing(database) };
@@ -552,8 +587,6 @@ export async function migrateSquareFile(location, signal, env = process.env) {
             assertSource(lockedPlan.sourceToken === plan.sourceToken, 'source changed during migration preflight.');
             result.plan = lockedPlan;
         }, () => {
-            if (source === 2)
-                rebuildV2Activities(database);
             const migratedPlan = result.plan;
             upgradeRowArtifact(database, squarePath, migratedPlan);
             result.outcome = { status: 'migrated', standing: migratedPlan.standing, counts: migratedPlan.counts };

package/dist/square-receive.d.ts

@@ -0,0 +1,6 @@
+import type { AudienceRoute } from './attention.js';
+import type { StoredAct } from './model.js';
+import type { DirectedFilter, SquareRead } from './ports.js';
+import type { ReceiveRead } from './receive.js';
+/** Transaction-local projections only; the artifact still owns indexed selection and bodies. */
+export declare function squareReceiveRead(facts: SquareRead): ReceiveRead<number, StoredAct, AudienceRoute, DirectedFilter>;

package/dist/square-receive.js

@@ -0,0 +1,18 @@
+/** Transaction-local projections only; the artifact still owns indexed selection and bodies. */
+export function squareReceiveRead(facts) {
+    const filter = (query, unconsumed) => {
+        const { unseenOnly: _, ...rest } = query;
+        return unconsumed ? { ...rest, unseenOnly: true } : rest;
+    };
+    return {
+        heads: (recipient, query, options) => facts.directed(recipient, filter(query, options.unconsumed), { edge: 'oldest', limit: options.limit })
+            .items.map(item => ({ key: item.index, via: item.route })),
+        addressed(recipient, index) {
+            const head = facts.directedAt(recipient, index);
+            return head === undefined ? undefined : { key: head.index, via: head.route };
+        },
+        load: keys => new Map(facts.activities(keys).map(item => [item.index, item])),
+        count: (recipient, query, unconsumed) => facts.directedCount(recipient, filter(query, unconsumed)),
+        receipt: ref => facts.receipt(ref.recipient, ref.item),
+    };
+}

package/dist/square-sqlite.d.ts

@@ -23,7 +23,8 @@ export declare const V3_USER_VERSION = 3;
 export declare const V4_USER_VERSION = 4;
 export declare const V5_USER_VERSION = 5;
 export declare const V6_USER_VERSION = 6;
-export declare const CURRENT_USER_VERSION = 7;
+export declare const V7_USER_VERSION = 7;
+export declare const CURRENT_USER_VERSION = 8;
 export declare const V1_SNAPSHOT_TABLE = "square_snapshot";
 export interface LegacyFraming {
     readonly applicationId: number;
@@ -37,17 +38,18 @@ 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 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 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','read','listen','ignore','unlisten')),\n  actor_json TEXT COLLATE BINARY NOT NULL,\n  actor_key_json TEXT COLLATE BINARY NOT NULL,\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 (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 DELIVERY_DEFERRALS_SQL = "CREATE TABLE delivery_deferrals (\n  participant_key_json TEXT COLLATE BINARY NOT NULL,\n  participant_json TEXT NOT NULL,\n  generation_json TEXT NOT NULL,\n  deferral_id_json TEXT NOT NULL,\n  match_json TEXT NOT NULL CHECK (json_valid(match_json)),\n  expires_at REAL NOT NULL,\n  PRIMARY KEY (participant_key_json,generation_json,deferral_id_json)\n) WITHOUT ROWID;\nCREATE INDEX delivery_deferral_expiry ON delivery_deferrals(participant_key_json,generation_json,expires_at);";
 export declare const SCHEMA_SQL: string;
+export declare const FORMAT7_SCHEMA_SQL: string;
 export declare const FORMAT6_SCHEMA_SQL: string;
 export declare const FORMAT5_SCHEMA_SQL: string;
 export declare const FORMAT4_SCHEMA_SQL: 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 validateRowFraming(db: DatabaseSync, version: 2 | 3 | 4 | 5 | 6 | 7, location?: string): void;
+export declare function validateRowFraming(db: DatabaseSync, version: 2 | 3 | 4 | 5 | 6 | 7 | 8, 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

@@ -1,8 +1,10 @@
 import { DatabaseSync as MemoryDatabase } from 'node:sqlite';
-import { SquareError, nameKey, isWakeRouteKind, validateOwner, validateActivityMetadata, activityMetadataHasContent } from './model.js';
+import { SquareError, nameKey, isWakeRouteKind, validateOwner, validateActivityMetadata, validateActivityDelivery, activityMetadataHasContent } from './model.js';
 import { validateMetadataMatch, matchingDeferrals, validateDeferralId } from './delivery-deferral.js';
 import { deriveLanding, landingFacts } from './square-domain.js';
-import { legacyRowFramingIssue } from './square-legacy-framing.js';
+import { claimAttempt, prepareAttempt, settleAttempt } from './delivery-attempts.js';
+import { legacyRowFramingIssue, legacyActivitySchema } from './square-legacy-framing.js';
+import { receive, recordConsumed } from './receive.js';
 export function emptyRuntimeState(nextActIndex = 0) {
     return { nextActIndex, observations: {}, leases: {} };
 }
@@ -13,7 +15,8 @@ export const V3_USER_VERSION = 3;
 export const V4_USER_VERSION = 4;
 export const V5_USER_VERSION = 5;
 export const V6_USER_VERSION = 6;
-export const CURRENT_USER_VERSION = 7;
+export const V7_USER_VERSION = 7;
+export const CURRENT_USER_VERSION = 8;
 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 = [
@@ -58,18 +61,16 @@ export function validateLegacyFraming(database, applicationId, location = '') {
 function normalizedLegacySql(sql) {
     return sql.trim().replace(/\s+/g, ' ').replace(/\s*(>=|[(),=])\s*/g, '$1');
 }
-const CURRENT_ACTIVITY_KIND_CHECK = "kind IN ('join','done','say','hold','resume','read','listen','ignore','unlisten')";
+const CURRENT_ACTIVITY_KIND_CHECK = "kind IN ('join','done','say','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 (${CURRENT_ACTIVITY_KIND_CHECK}),
-  actor_json TEXT COLLATE BINARY,
-  actor_key_json TEXT COLLATE BINARY,
+  actor_json TEXT COLLATE BINARY NOT NULL,
+  actor_key_json TEXT COLLATE BINARY NOT NULL,
   reach TEXT CHECK (reach = 'bell'),
   reply_index INTEGER CHECK (reply_index >= 0 AND reply_index < act_index),
   payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),
-  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 = [
@@ -182,9 +183,11 @@ CREATE TABLE landed_audience (
   UNIQUE (act_index, recipient_order)
 ) WITHOUT ROWID;
 CREATE INDEX audience_recipient ON landed_audience(recipient_key_json, act_index);`;
-export const FORMAT6_SCHEMA_SQL = SCHEMA_SQL.replace(`  owner_json TEXT NOT NULL,\n  generation_json TEXT NOT NULL,`, `  channel_json TEXT NOT NULL,\n  session_json TEXT NOT NULL,\n  agent_json TEXT,\n  generation_json TEXT NOT NULL,`).replace('CREATE INDEX seat_owner ON seats(owner_json);', 'CREATE INDEX seat_body ON seats(channel_json, session_json, agent_json);');
+export const FORMAT7_SCHEMA_SQL = legacyActivitySchema(SCHEMA_SQL);
+export const FORMAT6_SCHEMA_SQL = FORMAT7_SCHEMA_SQL.replace(`  owner_json TEXT NOT NULL,\n  generation_json TEXT NOT NULL,`, `  channel_json TEXT NOT NULL,\n  session_json TEXT NOT NULL,\n  agent_json TEXT,\n  generation_json TEXT NOT NULL,`).replace('CREATE INDEX seat_owner ON seats(owner_json);', 'CREATE INDEX seat_body ON seats(channel_json, session_json, agent_json);');
 export const FORMAT5_SCHEMA_SQL = FORMAT6_SCHEMA_SQL.replace(`,\n  ${ATTACHMENT_COLUMN_SQL}`, '');
 export const FORMAT4_SCHEMA_SQL = FORMAT5_SCHEMA_SQL.replace(DELIVERY_DEFERRALS_SQL, '');
+const FORMAT7_SCHEMA = FORMAT7_SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const FORMAT6_SCHEMA = FORMAT6_SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const FORMAT5_SCHEMA = FORMAT5_SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const EXPECTED_SCHEMA_SQL = SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
@@ -244,17 +247,17 @@ function immutable(value) {
     }
     return value;
 }
-const kinds = ['join', 'done', 'say', 'hold', 'resume', 'read', 'listen', 'ignore', 'unlisten'];
+const kinds = ['join', 'done', 'say', 'read', 'listen', 'ignore', 'unlisten'];
 function head(row) {
     const index = integer(row.act_index), at = finite(row.at);
     requireFact(kinds.includes(string(row.kind)));
-    const actor = row.actor_json === null ? undefined : decoded(row.actor_json, true);
-    requireFact(actor === undefined ? row.actor_key_json === null && ['hold', 'resume'].includes(row.kind) : row.actor_key_json === key(actor));
+    const actor = decoded(row.actor_json, true);
+    requireFact(row.actor_key_json === key(actor));
     requireFact(row.reach === null || row.kind === 'say' && row.reach === 'bell');
     if (row.reply_index !== null)
         requireFact(row.kind === 'say' && integer(row.reply_index) < index);
     return immutable({
-        index, at, kind: row.kind, ...(actor === undefined ? {} : { actor }), ...(row.reach === null ? {} : { reach: 'bell' }), ...(row.reply_index === null ? {} : { reply: row.reply_index })
+        index, at, kind: row.kind, actor, ...(row.reach === null ? {} : { reach: 'bell' }), ...(row.reply_index === null ? {} : { reply: row.reply_index })
     });
 }
 export function validateStoredActivity(value) {
@@ -262,16 +265,20 @@ export function validateStoredActivity(value) {
     integer(a.index);
     finite(a.at);
     requireFact(kinds.includes(string(a.kind)));
-    const common = ['kind', 'at', 'index'];
-    if (a.kind !== 'hold' && a.kind !== 'resume') {
-        common.push('actor');
-        string(a.actor, true);
-    }
-    else if (Object.hasOwn(a, 'actor'))
-        string(a.actor, true);
+    const common = ['kind', 'at', 'index', 'actor'];
+    string(a.actor, true);
     switch (a.kind) {
         case 'say':
-            shape(a, [...common], ['body', 'mentions', 'reach', 'reply', 'metadata']);
+            shape(a, [...common], ['body', 'mentions', 'reach', 'reply', 'metadata', 'delivery']);
+            if (Object.hasOwn(a, 'delivery')) {
+                requireFact(a.delivery !== undefined, 'say delivery is malformed.');
+                try {
+                    validateActivityDelivery(a.delivery);
+                }
+                catch {
+                    throw invalidArtifact('say delivery is malformed.');
+                }
+            }
             if (Object.hasOwn(a, 'body'))
                 string(a.body);
             if (Object.hasOwn(a, 'metadata')) {
@@ -292,8 +299,7 @@ export function validateStoredActivity(value) {
                 requireFact(integer(a.reply) < a.index);
             break;
         case 'done':
-        case 'hold':
-            shape(a, common, ['body', ...(a.kind === 'hold' ? ['actor'] : [])]);
+            shape(a, common, ['body']);
             if (Object.hasOwn(a, 'body'))
                 string(a.body);
             break;
@@ -307,14 +313,14 @@ export function validateStoredActivity(value) {
             shape(a, [...common, 'target']);
             string(a.target, true);
             break;
-        default: shape(a, common, a.kind === 'resume' ? ['actor'] : []);
+        default: shape(a, common);
     }
     return 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', 'metadata'] : h.kind === 'done' || h.kind === 'hold' ? ['body'] : h.kind === 'read' ? ['through'] : h.kind === 'listen' || h.kind === 'ignore' || h.kind === 'unlisten' ? ['target'] : [];
+    const allowed = h.kind === 'say' ? ['body', 'mentions', 'metadata', 'delivery'] : h.kind === 'done' ? ['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 }));
 }
@@ -403,8 +409,7 @@ function nativeCorrelation(value) {
         ...(item.messageId === undefined ? {} : { messageId: item.messageId }),
         ...(item.payloadHash === undefined ? {} : { payloadHash: item.payloadHash }) });
 }
-function deliveryEvidence(row) {
-    const payload = object(json(row.payload_json));
+function deliveryEvidence(row, payload = object(json(row.payload_json))) {
     const participant = decoded(row.participant_json, true);
     requireFact(row.participant_key_json === key(participant));
     const generation = activityId(decoded(row.generation_json, true));
@@ -461,7 +466,7 @@ 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 === V4_USER_VERSION ? FORMAT4_SCHEMA : version === V5_USER_VERSION ? FORMAT5_SCHEMA : version === V6_USER_VERSION ? FORMAT6_SCHEMA : EXPECTED_SCHEMA_SQL, location);
+    validateOwnedSchema(db, version === V4_USER_VERSION ? FORMAT4_SCHEMA : version === V5_USER_VERSION ? FORMAT5_SCHEMA : version === V6_USER_VERSION ? FORMAT6_SCHEMA : version === V7_USER_VERSION ? FORMAT7_SCHEMA : 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();
@@ -470,7 +475,7 @@ 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' });
     }
-    if (identity.user_version === V2_USER_VERSION || identity.user_version === V3_USER_VERSION || identity.user_version === V4_USER_VERSION || identity.user_version === V5_USER_VERSION || identity.user_version === V6_USER_VERSION) {
+    if (identity.user_version === V2_USER_VERSION || identity.user_version === V3_USER_VERSION || identity.user_version === V4_USER_VERSION || identity.user_version === V5_USER_VERSION || identity.user_version === V6_USER_VERSION || identity.user_version === V7_USER_VERSION) {
         validateRowFraming(db, identity.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' });
     }
@@ -494,8 +499,6 @@ function activitySelection(filter, alias = 'a') {
         add(`${alias}.act_index <= ?`, integer(filter.throughIndex, -1));
     if (filter.afterAt !== undefined)
         add(`${alias}.at > ?`, finite(filter.afterAt));
-    if (filter.actorRequired)
-        terms.push(`${alias}.actor_json IS NOT NULL`);
     for (const [column, values] of [['act_index', filter.indexes], ['kind', filter.kinds], [filter.actorMatch === 'exact' ? 'actor_json' : 'actor_key_json', filter.actors?.map(name => filter.actorMatch === 'exact' ? encode(name) : key(name))]]) {
         if (values !== undefined) {
             if (column === 'act_index')
@@ -540,7 +543,7 @@ export function createSqliteDriver(db) {
     }
     function directedHead(row, recipient) {
         const h = head(row);
-        requireFact(h.kind === 'say' && h.actor !== undefined);
+        requireFact(h.kind === 'say');
         return immutable({
             index: h.index, at: h.at, actor: h.actor, recipient, route: routeKind(row.route)
         });
@@ -566,7 +569,7 @@ export function createSqliteDriver(db) {
             const filter = activityIndex === undefined ? '' : ' AND act_index=?';
             if (activityIndex !== undefined)
                 args.push(integer(Number(activityIndex.slice(4))));
-            return immutable(all(`SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=?${filter} ORDER BY act_index,kind,attempt_n`, args).map(deliveryEvidence));
+            return immutable(all(`SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=?${filter} ORDER BY act_index,kind,attempt_n`, args).map(row => deliveryEvidence(row)));
         },
         deliveryByToken(claimToken) {
             const row = one('SELECT * FROM delivery_evidence WHERE claim_token_json=?', [encode(claimToken)]);
@@ -596,18 +599,6 @@ export function createSqliteDriver(db) {
         roster: () => immutable(all('SELECT * FROM participants ORDER BY first_index').map(participant)),
         attention: name => immutable(attentionRows('t.listener_key_json=?', [key(name)])),
         incomingAttention: name => immutable(attentionRows('t.target_key_json=?', [key(name)])),
-        hold() {
-            const r = one("SELECT * FROM activities WHERE kind IN ('hold','resume') ORDER BY act_index DESC LIMIT 1");
-            if (!r)
-                return immutable({ active: false });
-            const a = activity(r);
-            if (a.kind === 'resume')
-                return immutable({ active: false });
-            requireFact(a.kind === 'hold');
-            return immutable({
-                active: true, at: a.at, ...(a.body === undefined ? {} : { reason: a.body }), ...(a.actor === undefined ? {} : { actor: a.actor })
-            });
-        },
         activity(index) {
             const r = one('SELECT * FROM activities WHERE act_index=?', [integer(index)]);
             return r ? activity(r) : undefined;
@@ -685,7 +676,7 @@ export function createSqliteDriver(db) {
             const groups = indices.map(r => {
                 const rows = all(`SELECT a.act_index,a.at,a.kind,a.actor_json,a.actor_key_json,a.reach,a.reply_index,p.name_json,d.route FROM ${pendingFrom} WHERE ${pendingWhere} AND d.act_index=? ORDER BY d.recipient_order`, [integer(r.act_index)]);
                 const h = head(rows[0]);
-                requireFact(h.kind === 'say' && h.actor !== undefined);
+                requireFact(h.kind === 'say');
                 return {
                     index: h.index, at: h.at, actor: h.actor, recipients: rows.map(v => ({ recipient: decoded(v.name_json, true), route: routeKind(v.route) }))
                 };
@@ -788,7 +779,10 @@ export function createSqliteDriver(db) {
             const a = validateStoredActivity(effect.activity);
             requireFact(a.index >= read.header().nextActIndex && a.index < Number.MAX_SAFE_INTEGER, 'activity index cannot advance.');
             const { index, at, kind, actor, reach, reply, ...payload } = a;
-            run('INSERT INTO activities(act_index,at,kind,actor_json,actor_key_json,reach,reply_index,payload_json) VALUES(?,?,?,?,?,?,?,?)', [index, at, kind, actor === undefined ? null : encode(actor), actor === undefined ? null : key(actor), reach ?? null, reply ?? null, encode(payload)]);
+            receive({
+                insertItem: () => { run('INSERT INTO activities(act_index,at,kind,actor_json,actor_key_json,reach,reply_index,payload_json) VALUES(?,?,?,?,?,?,?,?)', [index, at, kind, encode(actor), key(actor), reach ?? null, reply ?? null, encode(payload)]); },
+                insertAddress: (item, address, order) => { run('INSERT INTO landed_audience(act_index,recipient_key_json,recipient_order,route) VALUES(?,?,?,?)', [item, key(address.recipient), order, address.via]); },
+            }, { item: { key: index, data: a }, audience: effect.audience.map(r => ({ recipient: r.recipient, via: r.route })) });
             if (effect.participant) {
                 const p = effect.participant;
                 string(p.name, true);
@@ -817,7 +811,6 @@ export function createSqliteDriver(db) {
                 requireFact(t.kind === 'listen' || t.kind === 'ignore');
                 run('INSERT INTO attention(listener_key_json,target_key_json,target_json,kind,since_index) VALUES(?,?,?,?,?) ON CONFLICT(listener_key_json,target_key_json) DO UPDATE SET target_json=excluded.target_json,kind=excluded.kind,since_index=excluded.since_index', [key(t.listener), key(t.target), encode(t.target), t.kind, t.sinceIndex]);
             }
-            effect.audience.forEach((r, order) => run('INSERT INTO landed_audience(act_index,recipient_key_json,recipient_order,route) VALUES(?,?,?,?)', [index, key(r.recipient), order, r.route]));
             run('UPDATE square_meta SET next_act_index=? WHERE id=1', [index + 1]);
             changed = true;
         },
@@ -825,11 +818,11 @@ export function createSqliteDriver(db) {
             finite(at);
             const next = read.header().nextActIndex;
             indexes.forEach(index => requireFact(integer(index) < next, 'receipt references an unassigned activity index.'));
-            let count = 0;
-            const encoded = encode(owner(name));
-            string(owner(name), true);
-            for (const index of indexes)
-                count += run('INSERT OR IGNORE INTO receipts(owner_json,act_index,at) VALUES(?,?,?)', [encoded, index, at]);
+            const canonical = owner(name);
+            string(canonical, true);
+            const count = recordConsumed({
+                insertReceipt: (ref, time) => run('INSERT OR IGNORE INTO receipts(owner_json,act_index,at) VALUES(?,?,?)', [encode(ref.recipient), ref.item, time]) > 0,
+            }, indexes.map(item => ({ recipient: canonical, item })), at);
             if (count)
                 changed = true;
             return count;
@@ -884,6 +877,40 @@ export function createSqliteDriver(db) {
             return count > 0;
         },
     };
+    function attempt(row) {
+        const data = object(json(row.payload_json)), evidence = deliveryEvidence(row, data);
+        return { purpose: evidence.kind === 'wake' ? 'dispatch' : 'presentation', token: evidence.claimToken ?? '',
+            ordinal: evidence.attemptN, outcome: evidence.outcome, at: evidence.at, expiresAt: evidence.expiresAt, data };
+    }
+    function attemptRows(seat, index, kind, known) {
+        const scope = [key(seat.participant), encode(seat.generation), index, kind];
+        let sources = [];
+        return {
+            list() {
+                sources = all('SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=? AND act_index=? AND kind=? ORDER BY attempt_n DESC', scope);
+                return sources.map(attempt);
+            },
+            evidence(value) {
+                const source = sources.find(row => row.attempt_n === value.ordinal);
+                return deliveryEvidence({ ...source, outcome: value.outcome, at: value.at, expires_at: value.expiresAt ?? null }, value.data);
+            },
+            byToken(token) {
+                if (known?.token === token)
+                    return known;
+                const row = one('SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=? AND act_index=? AND kind=? AND claim_token_json=?', [...scope, encode(token)]);
+                return row === undefined ? undefined : attempt(row);
+            },
+            insert(value) {
+                run('INSERT INTO delivery_evidence(participant_key_json,participant_json,generation_json,act_index,kind,attempt_n,outcome,at,expires_at,claim_token_json,payload_json) VALUES(?,?,?,?,?,?,?,?,?,?,?)', [scope[0], encode(seat.participant), scope[1], index, kind, value.ordinal, value.outcome, value.at, value.expiresAt ?? null, encode(value.token), encode(value.data)]);
+                deliveryChanged = true;
+            },
+            replace(value) {
+                const count = run('UPDATE delivery_evidence SET outcome=?,at=?,expires_at=?,payload_json=? WHERE participant_key_json=? AND generation_json=? AND act_index=? AND kind=? AND attempt_n=? AND claim_token_json IS ?', [value.outcome, value.at, value.expiresAt ?? null, encode(value.data), ...scope, value.ordinal, value.token === '' ? null : encode(value.token)]);
+                if (count)
+                    deliveryChanged = true;
+            },
+        };
+    }
     const delivery = {
         claimDelivery(input) {
             requireFact(input.kind === 'wake' || input.kind === 'presentation');
@@ -903,42 +930,24 @@ export function createSqliteDriver(db) {
             const cancelledThrough = read.cancelledThrough(input.seat.participant, input.seat.generation);
             if (cancelledThrough !== undefined && index <= cancelledThrough)
                 return { status: 'stale' };
-            const rows = all('SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=? AND act_index=? AND kind=? ORDER BY attempt_n DESC', [key(input.seat.participant), encode(input.seat.generation), index, input.kind]);
-            const decoded = rows.map(deliveryEvidence);
-            const terminal = decoded.find((row) => input.kind === 'wake'
-                ? row.outcome === 'accepted' || row.outcome === 'unknown'
-                : row.outcome === 'presented' || row.outcome === 'unknown');
-            if (terminal !== undefined)
-                return { status: 'terminal', evidence: terminal };
-            const dispatching = decoded.find((row) => row.outcome === 'dispatching');
-            if (dispatching !== undefined && (dispatching.expiresAt === undefined || dispatching.expiresAt > input.at))
-                return { status: 'busy', evidence: dispatching };
-            if (dispatching !== undefined) {
-                const updated = { ...dispatching, outcome: 'unknown', at: input.at, expiresAt: undefined, diagnostic: 'interrupted dispatch' };
-                const source = rows.find((row) => row.attempt_n === dispatching.attemptN);
-                run('UPDATE delivery_evidence SET outcome=?,at=?,expires_at=NULL,payload_json=? WHERE participant_key_json=? AND generation_json=? AND act_index=? AND kind=? AND attempt_n=?', ['unknown', input.at, encode({ ...object(json(source.payload_json)), diagnostic: 'interrupted dispatch' }), key(input.seat.participant), encode(input.seat.generation), index, input.kind, dispatching.attemptN]);
-                deliveryChanged = true;
-                return { status: 'terminal', evidence: updated };
-            }
-            const attemptN = (decoded[0]?.attemptN ?? -1) + 1;
-            const payload = input.route === undefined ? {} : { route: input.route };
-            const expiry = finite(input.at + leaseMs);
-            run('INSERT INTO delivery_evidence(participant_key_json,participant_json,generation_json,act_index,kind,attempt_n,outcome,at,expires_at,claim_token_json,payload_json) VALUES(?,?,?,?,?,?,?,?,?,?,?)', [key(input.seat.participant), encode(input.seat.participant), encode(input.seat.generation), index, input.kind, attemptN, 'dispatching', input.at, expiry, encode(input.claimToken), encode(payload)]);
-            deliveryChanged = true;
-            return { status: 'acquired', claimToken: input.claimToken, attemptN };
+            const rows = attemptRows(input.seat, index, input.kind);
+            const result = claimAttempt({ ...rows, replace(value) {
+                    rows.replace({ ...value, data: { ...value.data, diagnostic: 'interrupted dispatch' } });
+                } }, { purpose: input.kind === 'wake' ? 'dispatch' : 'presentation', token: input.claimToken,
+                at: input.at, leaseMs, data: input.route === undefined ? {} : { route: input.route } });
+            if (result.status === 'acquired')
+                return { status: 'acquired', claimToken: result.token, attemptN: result.ordinal };
+            const evidence = result.interrupted ? { ...result.evidence, data: { ...result.evidence.data, diagnostic: 'interrupted dispatch' } } : result.evidence;
+            return { status: result.status, evidence: rows.evidence(evidence) };
         },
         prepareDelivery(input) {
             const row = one('SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=? AND claim_token_json=?', [key(input.seat.participant), encode(input.seat.generation), encode(input.claimToken)]);
             if (row === undefined || row.outcome !== 'dispatching')
                 return false;
-            const correlation = nativeCorrelation(input.correlation);
-            const payload = object(json(row.payload_json));
+            const previous = attempt(row), correlation = nativeCorrelation(input.correlation), payload = previous.data;
             if (stableJson(payload.correlation ?? null) === stableJson(correlation))
                 return true;
-            const count = run('UPDATE delivery_evidence SET payload_json=? WHERE participant_key_json=? AND generation_json=? AND claim_token_json=?', [encode({ ...payload, correlation }), key(input.seat.participant), encode(input.seat.generation), encode(input.claimToken)]);
-            if (count)
-                deliveryChanged = true;
-            return count > 0;
+            return prepareAttempt(attemptRows(input.seat, integer(row.act_index), row.kind, previous), { token: input.claimToken, data: { ...payload, correlation } });
         },
         completeDelivery(input) {
             const index = activityIndex(input.activity);
@@ -948,16 +957,9 @@ export function createSqliteDriver(db) {
             const row = one('SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=? AND act_index=? AND claim_token_json=?', [key(input.seat.participant), encode(input.seat.generation), index, encode(input.claimToken)]);
             if (row === undefined)
                 return false;
-            if (row.outcome === 'accepted' && input.outcome === 'accepted')
-                return true;
-            if (row.outcome !== 'dispatching' && !(row.outcome === 'unknown' && input.outcome === 'accepted'))
-                return false;
-            const previous = object(json(row.payload_json));
-            const payload = { ...previous, ...(input.signature === undefined ? {} : { signature: input.signature }), ...(input.message === undefined ? {} : { message: input.message }), ...(input.diagnostic === undefined ? {} : { diagnostic: input.diagnostic }), ...(input.correlation === undefined ? {} : { correlation: input.correlation }) };
-            const count = run('UPDATE delivery_evidence SET outcome=?,at=?,expires_at=NULL,payload_json=? WHERE participant_key_json=? AND generation_json=? AND act_index=? AND claim_token_json=?', [input.outcome, input.at, encode(payload), key(input.seat.participant), encode(input.seat.generation), index, encode(input.claimToken)]);
-            if (count)
-                deliveryChanged = true;
-            return count > 0;
+            const previous = attempt(row);
+            const payload = { ...previous.data, ...(input.signature === undefined ? {} : { signature: input.signature }), ...(input.message === undefined ? {} : { message: input.message }), ...(input.diagnostic === undefined ? {} : { diagnostic: input.diagnostic }), ...(input.correlation === undefined ? {} : { correlation: input.correlation }) };
+            return settleAttempt(attemptRows(input.seat, index, row.kind, previous), { token: input.claimToken, outcome: input.outcome, at: input.at, data: payload });
         },
         observeNativeDelivery(input) {
             const row = one('SELECT * FROM delivery_evidence WHERE participant_key_json=? AND generation_json=? AND claim_token_json=?', [key(input.seat.participant), encode(input.seat.generation), encode(input.claimToken)]);
@@ -1071,6 +1073,12 @@ function inspectRows(db, inspectSeat) {
     const rebuilt = new MemoryDatabase(':memory:');
     try {
         initializeSqlite(rebuilt, state, d.header().revision);
+        // A migration may remove the activity that established canonical casing.
+        // Retained participant spelling stays authoritative while replay checks
+        // every derived lifecycle/count fact against surviving activities.
+        const retainName = rebuilt.prepare('UPDATE participants SET name_json=? WHERE name_key_json=?');
+        for (const p of d.roster())
+            retainName.run(encode(p.name), key(p.name));
         for (const table of ['participants', 'attention', 'landed_audience']) {
             const original = db.prepare(`SELECT * FROM ${table} ORDER BY 1,2`).all();
             const expected = rebuilt.prepare(`SELECT * FROM ${table} ORDER BY 1,2`).all();

package/dist/square-tools.d.ts

@@ -13,6 +13,7 @@ interface ToolDefinition {
     /** Human text identical to what the CLI prints; domain receipts stay inside the adapter. */
     run(square: Square, args: JsonObject, control: OperationControl, identity: ToolIdentity): Promise<string>;
 }
+export declare function squareToolsEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare const SQUARE_TOOL_INSTRUCTIONS = "Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.";
 export declare const SQUARE_TOOLS: readonly ToolDefinition[];
 export declare function squareToolFailure(error: unknown, signal?: AbortSignal): JsonObject;