@astrosheep/square 0.3.93 → 0.3.95

package/dist/square-sqlite.js

@@ -1,8 +1,10 @@
 import { DatabaseSync as MemoryDatabase } from 'node:sqlite';
-import { sameBody, SquareError, nameKey, isWakeRouteKind, validateBody, validateActivityMetadata, activityMetadataHasContent } from './model.js';
+import { SquareError, nameKey, isWakeRouteKind, validateOwner, validateActivityMetadata, 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: {} };
 }
@@ -11,7 +13,10 @@ const V1_USER_VERSION = 1;
 export const V2_USER_VERSION = 2;
 export const V3_USER_VERSION = 3;
 export const V4_USER_VERSION = 4;
-export const CURRENT_USER_VERSION = 5;
+export const V5_USER_VERSION = 5;
+export const V6_USER_VERSION = 6;
+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 = [
@@ -56,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 = [
@@ -87,6 +90,7 @@ export const DELIVERY_DEFERRALS_SQL = `CREATE TABLE delivery_deferrals (
   PRIMARY KEY (participant_key_json,generation_json,deferral_id_json)
 ) WITHOUT ROWID;
 CREATE INDEX delivery_deferral_expiry ON delivery_deferrals(participant_key_json,generation_json,expires_at);`;
+const ATTACHMENT_COLUMN_SQL = "attachment TEXT NOT NULL DEFAULT 'attached' CHECK (attachment IN ('attached','detached'))";
 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),
@@ -119,13 +123,12 @@ CREATE TABLE catch_leases (
 CREATE TABLE seats (
   participant_key_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,
   participant_json TEXT NOT NULL,
-  channel_json TEXT NOT NULL,
-  session_json TEXT NOT NULL,
-  agent_json TEXT,
+  owner_json TEXT NOT NULL,
   generation_json TEXT NOT NULL,
-  wake_address_json TEXT CHECK (wake_address_json IS NULL OR json_valid(wake_address_json))
+  wake_address_json TEXT CHECK (wake_address_json IS NULL OR json_valid(wake_address_json)),
+  ${ATTACHMENT_COLUMN_SQL}
 ) WITHOUT ROWID;
-CREATE INDEX seat_body ON seats(channel_json, session_json, agent_json);
+CREATE INDEX seat_owner ON seats(owner_json);
 CREATE TABLE delivery_evidence (
   participant_key_json TEXT COLLATE BINARY NOT NULL,
   participant_json TEXT NOT NULL,
@@ -180,7 +183,13 @@ 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 FORMAT4_SCHEMA_SQL = SCHEMA_SQL.replace(DELIVERY_DEFERRALS_SQL, '');
+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();
 const FORMAT4_SCHEMA = FORMAT4_SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const encode = JSON.stringify;
@@ -238,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) {
@@ -256,13 +265,8 @@ 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']);
@@ -286,8 +290,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;
@@ -301,14 +304,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'] : 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 }));
 }
@@ -372,17 +375,19 @@ function wakeAddress(value) {
     stableJson(entries);
     return immutable({ kind: address.kind, address: entries });
 }
-function bodyFrom(row) {
-    const body = { channel: decoded(row.channel_json, true), session: decoded(row.session_json, true), ...(row.agent_json === null ? {} : { agent: decoded(row.agent_json, true) }) };
-    validateBody(body);
-    return immutable(body);
+function ownerFrom(row) {
+    const owner = decoded(row.owner_json, true);
+    validateOwner(owner);
+    return owner;
 }
 function seat(row) {
     const participant = decoded(row.participant_json, true);
     requireFact(row.participant_key_json === key(participant));
     const generation = activityId(decoded(row.generation_json, true));
     const parsedWake = row.wake_address_json === null ? undefined : wakeAddress(json(row.wake_address_json));
-    return immutable({ participant, body: bodyFrom(row), generation, ...(parsedWake === undefined ? {} : { wakeAddress: parsedWake }) });
+    requireFact(row.attachment === 'attached' || row.attachment === 'detached', 'seat attachment is malformed.');
+    requireFact(row.attachment !== 'detached' || parsedWake === undefined, 'a detached seat has a wake address.');
+    return immutable({ participant, owner: ownerFrom(row), generation, attachment: row.attachment, ...(parsedWake === undefined ? {} : { wakeAddress: parsedWake }) });
 }
 function nativeCorrelation(value) {
     const item = shape(value, ['harness'], ['token', 'messageId', 'payloadHash']);
@@ -395,8 +400,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));
@@ -453,7 +457,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 : 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();
@@ -462,7 +466,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) {
+    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' });
     }
@@ -486,8 +490,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')
@@ -532,7 +534,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)
         });
@@ -543,23 +545,22 @@ export function createSqliteDriver(db) {
     const latestSeats = `seats s JOIN participants p ON p.name_key_json=s.participant_key_json
         JOIN activities a ON a.act_index=p.last_join_index AND a.kind='join' AND a.actor_key_json=p.name_key_json
         AND s.generation_json='"act/'||a.act_index||'"'`;
-    function bodySeats(body, lifecycle) {
-        validateBody(body);
-        return immutable(all(`SELECT s.* FROM ${latestSeats} WHERE p.${lifecycle}=1 AND s.channel_json=? AND s.session_json=? AND s.agent_json IS ? ORDER BY s.participant_key_json`, [encode(body.channel), encode(body.session), body.agent === undefined ? null : encode(body.agent)]).map(seat));
+    function ownerSeats(owner) {
+        validateOwner(owner);
+        return immutable(all(`SELECT s.* FROM ${latestSeats} WHERE p.joined=1 AND s.owner_json=? ORDER BY s.participant_key_json`, [encode(owner)]).map(seat));
     }
     const read = {
         seat(name) {
             const r = one(`SELECT s.* FROM ${latestSeats} WHERE p.joined=1 AND s.participant_key_json=?`, [key(name)]);
             return r ? seat(r) : undefined;
         },
-        seatsForBody: body => bodySeats(body, 'joined'),
-        completedSeatsForBody: body => bodySeats(body, 'done'),
+        seatsForOwner: ownerSeats,
         deliveryEvidence(participant, generation, activityIndex) {
             const args = [key(participant), encode(generation)];
             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)]);
@@ -589,18 +590,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;
@@ -678,7 +667,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) }))
                 };
@@ -713,14 +702,14 @@ export function createSqliteDriver(db) {
     };
     const writes = {
         storeSeat(value) {
-            validateBody(value.body);
+            validateOwner(value.owner);
             activityId(value.generation);
             string(value.participant, true);
             const existing = read.seat(value.participant);
             if (existing !== undefined && stableJson(existing) === stableJson(value))
                 return false;
             const wake = value.wakeAddress === undefined ? null : encode(value.wakeAddress);
-            run('INSERT INTO seats(participant_key_json,participant_json,channel_json,session_json,agent_json,generation_json,wake_address_json) VALUES(?,?,?,?,?,?,?) ON CONFLICT(participant_key_json) DO UPDATE SET participant_json=excluded.participant_json,channel_json=excluded.channel_json,session_json=excluded.session_json,agent_json=excluded.agent_json,generation_json=excluded.generation_json,wake_address_json=excluded.wake_address_json', [key(value.participant), encode(value.participant), encode(value.body.channel), encode(value.body.session), value.body.agent === undefined ? null : encode(value.body.agent), encode(value.generation), wake]);
+            run('INSERT INTO seats(participant_key_json,participant_json,owner_json,generation_json,wake_address_json,attachment) VALUES(?,?,?,?,?,?) ON CONFLICT(participant_key_json) DO UPDATE SET participant_json=excluded.participant_json,owner_json=excluded.owner_json,generation_json=excluded.generation_json,wake_address_json=excluded.wake_address_json,attachment=excluded.attachment', [key(value.participant), encode(value.participant), encode(value.owner), encode(value.generation), wake, value.attachment]);
             run('DELETE FROM catch_leases WHERE owner_json=?', [encode(value.participant)]);
             run('DELETE FROM delivery_deferrals WHERE participant_key_json=?', [key(value.participant)]);
             deliveryChanged = true;
@@ -739,12 +728,28 @@ export function createSqliteDriver(db) {
                 deliveryChanged = true;
             return count > 0;
         },
+        reattachSeat(value, address) {
+            const current = read.seat(value.participant);
+            if (current?.attachment !== 'detached')
+                return false;
+            run("UPDATE seats SET attachment='attached',wake_address_json=? WHERE participant_key_json=? AND generation_json=?", [address === undefined ? null : encode(wakeAddress(address)), key(value.participant), encode(value.generation)]);
+            deliveryChanged = true;
+            return true;
+        },
+        detachSeat(value) {
+            const count = run("UPDATE seats SET attachment='detached',wake_address_json=NULL WHERE participant_key_json=? AND generation_json=? AND attachment='attached'", [key(value.participant), encode(value.generation)]);
+            if (!count)
+                return false;
+            run('DELETE FROM catch_leases WHERE owner_json=?', [encode(value.participant)]);
+            run('DELETE FROM delivery_deferrals WHERE participant_key_json=? AND generation_json=?', [key(value.participant), encode(value.generation)]);
+            deliveryChanged = true;
+            return true;
+        },
         removeSeat(value) {
-            // Done hides current authority; retain only its latest coordinate for exact-body resume.
             const row = one(`SELECT s.* FROM ${latestSeats} WHERE p.done=1 AND s.participant_key_json=?`, [key(value.participant)]);
-            if (row === undefined || decoded(row.generation_json) !== value.generation)
+            if (row === undefined || decoded(row.generation_json) !== value.generation || ownerFrom(row) !== value.owner)
                 return false;
-            run('UPDATE seats SET wake_address_json=NULL WHERE participant_key_json=?', [key(value.participant)]);
+            run('DELETE FROM seats WHERE participant_key_json=?', [key(value.participant)]);
             run('DELETE FROM catch_leases WHERE owner_json=?', [encode(value.participant)]);
             run('DELETE FROM delivery_deferrals WHERE participant_key_json=?', [key(value.participant)]);
             changed = true;
@@ -765,7 +770,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);
@@ -794,7 +802,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;
         },
@@ -802,11 +809,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;
@@ -861,6 +868,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');
@@ -872,7 +913,7 @@ export function createSqliteDriver(db) {
                 wakeAddress(input.route);
             const currentSeat = read.seat(input.seat.participant);
             const item = read.activity(index);
-            if (currentSeat === undefined || currentSeat.generation !== input.seat.generation || !sameBody(currentSeat.body, input.seat.body)
+            if (currentSeat === undefined || currentSeat.attachment !== 'attached' || currentSeat.generation !== input.seat.generation || currentSeat.owner !== input.seat.owner
                 || item?.kind !== 'say' || read.directedAt(input.seat.participant, index) === undefined)
                 return { status: 'stale' };
             if (matchingDeferrals(read.deliveryDeferrals(currentSeat.participant, currentSeat.generation), item.metadata, input.at).length > 0)
@@ -880,42 +921,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);
@@ -925,16 +948,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)]);
@@ -1023,15 +1039,18 @@ export function exportSqliteState(db) {
 }
 /** Full read-only integrity inspection, including maintained-index replay comparison. */
 export function inspectSqlite(db) {
+    return inspectRows(db, seat);
+}
+function inspectRows(db, inspectSeat) {
     const check = db.prepare('PRAGMA integrity_check').all();
     requireFact(check.length === 1 && check[0].integrity_check === 'ok', 'SQLite integrity check failed.');
     const state = exportSqliteState(db), d = createSqliteDriver(db);
     d.roster();
     for (const row of db.prepare('SELECT * FROM seats').all())
-        seat(row);
+        inspectSeat(row);
     for (const row of db.prepare('SELECT * FROM delivery_evidence').all())
         deliveryEvidence(row);
-    if (db.prepare('PRAGMA user_version').get().user_version === CURRENT_USER_VERSION) {
+    if (Number(db.prepare('PRAGMA user_version').get().user_version) >= V5_USER_VERSION) {
         for (const row of db.prepare('SELECT * FROM delivery_deferrals').all())
             deliveryDeferral(row);
     }
@@ -1045,6 +1064,12 @@ export function inspectSqlite(db) {
     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

@@ -1,20 +1,17 @@
 import { z } from 'zod/v4';
 import { type Square } from './square-api.js';
-import type { OperationControl } from './square-facade.js';
+import type { Owner, WakeAddress, OperationControl } from './square-facade.js';
+export interface ToolIdentity {
+    readonly owner?: Owner;
+    readonly wakeAddress?: WakeAddress;
+}
 type JsonObject = Record<string, unknown>;
-type Outcome = Promise<object>;
-type ToolRender = (result: JsonObject, args: JsonObject) => string | undefined;
 interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodObject<z.ZodRawShape>;
-    run(square: Square, args: JsonObject, control: ToolControl): Outcome;
-    /** Human text identical to what the CLI prints; transports show this to people. */
-    render: ToolRender;
-}
-/** A transport that shows people the square asks the same operation for its rendering facts. */
-export interface ToolControl extends OperationControl {
-    readonly observe?: boolean;
+    /** 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 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[];