@astrosheep/square 0.3.85 → 0.3.87

package/dist/square-migration.js

@@ -1,9 +1,12 @@
+import { createHash } from 'node:crypto';
 import { openExistingSquareDatabase } from './artifact.js';
 import { inSqliteTransaction } from './sqlite-transaction.js';
-import { canonicalPath } from './canonical-path.js';
-import { isWakeRouteKind } from './model.js';
+import { canonicalPath, canonicalPathSync } from './canonical-path.js';
+import { formatActivityId, isWakeRouteKind, nameKey, sameBody, validateBody } from './model.js';
 import { parseActivityId } from './square-core.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';
+import { readLegacyHostData } from './square-migration-host-ledger.js';
+import { legacyRowFramingIssue, FORMAT4_ADDED_OBJECTS, FORMAT4_REPLACED_OBJECTS } from './square-legacy-framing.js';
+import { APPLICATION_ID, ACTIVITIES_TABLE_SQL, ACTIVITY_INDEXES_SQL, CURRENT_USER_VERSION, V2_USER_VERSION, V3_USER_VERSION, SCHEMA_SQL, createSqliteDriver, invalidArtifact, validateStoredActivity } from './square-sqlite.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -30,7 +33,7 @@ function validateRuntime(value) {
             && Object.entries(candidate).every(([id, observation]) => parseActivityId(id) !== undefined && isObject(observation) && hasExactKeys(observation, ['state', 'at']) && observation.state === 'seen' && isFiniteNumber(observation.at)))
         && validateRecord(value.leases, (candidate) => {
             try {
-                validateWatchLease(candidate);
+                validateLegacyLease(candidate);
                 return true;
             }
             catch {
@@ -126,37 +129,6 @@ function identity(database) {
 function standing(database) {
     return createSqliteDriver(database).roster().filter((participant) => participant.joined).length;
 }
-/** The snapshot row, decoded only by the legacy validator. */
-function decodeLegacySnapshot(database) {
-    const rows = database.prepare(`SELECT id, revision, state FROM ${V1_SNAPSHOT_TABLE}`).all();
-    if (rows.length !== 1 || rows[0].id !== 1 || !Number.isSafeInteger(rows[0].revision) || rows[0].revision < 0)
-        throw invalidArtifact('snapshot row is malformed.');
-    if (typeof rows[0].state !== 'string')
-        throw invalidArtifact('snapshot state is malformed.');
-    let parsed;
-    try {
-        parsed = JSON.parse(rows[0].state);
-    }
-    catch {
-        throw invalidArtifact('snapshot state is not valid JSON.');
-    }
-    return { revision: rows[0].revision, state: validateSquareState(parsed) };
-}
-function counts(state) {
-    let receipts = 0;
-    for (const observations of Object.values(state.runtime.observations))
-        receipts += Object.keys(observations).length;
-    return {
-        activities: state.acts.length,
-        receipts,
-        leases: Object.keys(state.runtime.leases).length,
-        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([
@@ -168,63 +140,393 @@ function rebuildV2Activities(database) {
         ...ACTIVITY_INDEXES_SQL.map((sql) => `${sql};`),
     ].join('\n'));
 }
+function normalizedSql(sql) {
+    return sql.trim().replace(/;$/, '').replace(/\s+/g, ' ').replace(/\s*([(),=])\s*/g, '$1');
+}
+function currentFormat4Schema() {
+    return SCHEMA_SQL.split(';').map((statement) => statement.trim()).filter(Boolean)
+        .filter((statement) => {
+        const match = /^(?:CREATE (?:UNIQUE )?TABLE|CREATE (?:UNIQUE )?INDEX)\s+([a-z_]+)/i.exec(statement);
+        return match === null || !FORMAT4_REPLACED_OBJECTS.has(match[1]);
+    }).map(normalizedSql).sort();
+}
+function validateFormat4Framing(database, location) {
+    const before = identity(database);
+    assertSource(before.applicationId === APPLICATION_ID, 'unrelated SQLite database.');
+    assertSource(before.userVersion === CURRENT_USER_VERSION, 'unsupported SQLite format version.');
+    const actual = database.prepare("SELECT sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' AND sql IS NOT NULL").all()
+        .map((row) => typeof row.sql === 'string' ? normalizedSql(row.sql) : '').sort();
+    const expected = currentFormat4Schema();
+    assertSource(actual.length === expected.length && actual.every((sql, index) => sql === expected[index]), 'unsupported row schema.');
+    const journalMode = database.prepare('PRAGMA journal_mode').get().journal_mode;
+    assertSource(journalMode === (location === ':memory:' ? 'memory' : 'delete'), 'unsupported journal mode.');
+    createSqliteDriver(database).header();
+}
+function assertSource(condition, detail = 'row is malformed.') {
+    if (!condition)
+        throw invalidArtifact(detail);
+}
+function parseJson(value, detail) {
+    assertSource(typeof value === 'string', detail);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw invalidArtifact(detail);
+    }
+}
+function decodeJsonString(value, nonempty = false) {
+    const parsed = parseJson(value, 'row contains invalid JSON.');
+    assertSource(typeof parsed === 'string' && (!nonempty || parsed.length > 0) && JSON.stringify(parsed) === value, 'string encoding is malformed.');
+    return parsed;
+}
+function sourceInteger(value, minimum = 0) {
+    assertSource(typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum);
+    return value;
+}
+function sourceFinite(value) {
+    assertSource(typeof value === 'number' && Number.isFinite(value));
+    return value;
+}
+function sourceStringArray(value) {
+    const parsed = parseJson(value, 'header contains invalid JSON.');
+    assertSource(Array.isArray(parsed) && parsed.every((item) => typeof item === 'string'));
+    assertSource(JSON.stringify(parsed) === value, 'header string encoding is malformed.');
+    return parsed;
+}
+function decodeLegacyRoute(row) {
+    assertSource(sourceInteger(row.position) >= 0);
+    const parsed = parseJson(row.payload_json, 'route payload is malformed.');
+    assertSource(isObject(parsed)
+        && hasExactKeys(parsed, ['location', 'participant', 'channel', 'address', 'extra'], ['epoch']), 'route payload is malformed.');
+    assertSource(typeof parsed.location === 'string' && typeof parsed.participant === 'string'
+        && typeof parsed.channel === 'string' && isObject(parsed.address)
+        && Object.values(parsed.address).every((value) => typeof value === 'string')
+        && isObject(parsed.extra), 'route payload is malformed.');
+    assertSource(isWakeRouteKind(row.kind), 'route kind is malformed.');
+    const participant = parsed.participant;
+    assertSource(row.participant_key_json === JSON.stringify(nameKey(participant)), 'route participant key is malformed.');
+    const sessionId = decodeJsonString(row.session_json);
+    sourceFinite(row.updated_at);
+    const body = { channel: parsed.channel, session: sessionId, ...(parsed.extra.agent === undefined ? {} : { agent: parsed.extra.agent }) };
+    validateBody(body);
+    const address = parsed.address;
+    if (row.kind === 'claude-native')
+        assertSource(address.sessionId === undefined || address.sessionId === sessionId, 'native route session conflicts with its body.');
+    return { location: parsed.location, participant, body,
+        wakeAddress: { kind: row.kind, address: { ...address, ...(row.kind === 'claude-native' ? { sessionId } : {}) } } };
+}
+function validateLegacyLease(value) {
+    assertSource(isObject(value) && hasExactKeys(value, ['leaseId', 'heartbeatAt', 'expiresAt'], ['filter']), 'legacy lease is malformed.');
+    assertSource(typeof value.leaseId === 'string' && value.leaseId.length > 0
+        && typeof value.heartbeatAt === 'number' && Number.isFinite(value.heartbeatAt)
+        && typeof value.expiresAt === 'number' && Number.isFinite(value.expiresAt)
+        && value.expiresAt >= value.heartbeatAt, 'legacy lease is malformed.');
+    if (!Object.hasOwn(value, 'filter'))
+        return;
+    const filter = value.filter;
+    assertSource(isObject(filter) && hasExactKeys(filter, [], ['participants', 'mention']), 'legacy lease filter is malformed.');
+    assertSource((!Object.hasOwn(filter, 'participants') || Array.isArray(filter.participants) && filter.participants.every((item) => typeof item === 'string'))
+        && (!Object.hasOwn(filter, 'mention') || typeof filter.mention === 'string'), 'legacy lease filter is malformed.');
+}
+function readLegacyRoutes(database) {
+    return database.prepare('SELECT position,participant_key_json,session_json,kind,updated_at,payload_json FROM routes ORDER BY position').all()
+        .map(decodeLegacyRoute);
+}
+function uniqueSeatAddress(routes) {
+    const addresses = new Map();
+    for (const route of routes) {
+        const entries = Object.entries(route.wakeAddress.address).sort(([left], [right]) => left.localeCompare(right));
+        addresses.set(JSON.stringify([route.wakeAddress.kind, entries]), route.wakeAddress);
+    }
+    return addresses.size === 1 ? [...addresses.values()][0] : undefined;
+}
+function establishingJoin(driver, participant) {
+    const join = driver.activityHeads({ actors: [participant.name], kinds: ['join'] }, { edge: 'newest', limit: 1 }).items[0];
+    assertSource(join?.kind === 'join' && join.index === participant.lastJoinIndex, `participant ${participant.name} has no verifiable establishing join.`);
+    return join.index;
+}
+function planSeats(location, roster, routes, owners, driver) {
+    const standing = roster.filter((participant) => participant.joined);
+    return standing.map((participant) => {
+        const joined = establishingJoin(driver, participant);
+        const candidates = routes.filter((route) => canonicalPathSync(route.location) === location && nameKey(route.participant) === nameKey(participant.name));
+        const owner = owners.find(row => nameKey(row.participant) === nameKey(participant.name));
+        assertSource(owner !== undefined, `standing participant ${participant.name} has no legacy owner.`);
+        const { body } = owner;
+        assertSource(candidates.length > 0 && candidates.every(route => sameBody(route.body, body)), `standing participant ${participant.name} has no unique legacy body agreeing with its owner.`);
+        const shared = [...owners, ...routes.filter(route => canonicalPathSync(route.location) === location)]
+            .some(row => nameKey(row.participant) !== nameKey(participant.name) && sameBody(row.body, body));
+        assertSource(!shared, `standing participant ${participant.name} shares a legacy body with another owner.`);
+        const address = uniqueSeatAddress(candidates);
+        return {
+            participant: participant.name,
+            body,
+            generation: formatActivityId(joined),
+            ...(address === undefined ? {} : { wakeAddress: address }),
+        };
+    });
+}
+function tableToken(database, table, order) {
+    const rows = database.prepare(`SELECT * FROM ${table} ORDER BY ${order}`).all();
+    return JSON.stringify(rows.map((row) => Object.entries(row).sort(([left], [right]) => left.localeCompare(right))));
+}
+function legacySourceToken(database) {
+    return JSON.stringify([
+        ['square_meta', tableToken(database, 'square_meta', 'id')],
+        ['activities', tableToken(database, 'activities', 'act_index')],
+        ['participants', tableToken(database, 'participants', 'name_key_json')],
+        ['attention', tableToken(database, 'attention', 'listener_key_json,target_key_json')],
+        ['landed_audience', tableToken(database, 'landed_audience', 'act_index,recipient_order')],
+        ['receipts', tableToken(database, 'receipts', 'owner_json,act_index')],
+        ['catch_leases', tableToken(database, 'catch_leases', 'owner_json')],
+        ['routes', tableToken(database, 'routes', 'position')],
+    ]);
+}
+function inspectLegacyRowArtifact(database, location, host) {
+    const metaRows = database.prepare('SELECT * FROM square_meta').all();
+    assertSource(metaRows.length === 1 && metaRows[0].id === 1, 'header row is malformed.');
+    const meta = metaRows[0];
+    sourceInteger(meta.revision);
+    const nextActIndex = sourceInteger(meta.next_act_index);
+    assertSource(meta.hard_cap === null || (typeof meta.hard_cap === 'number' && Number.isSafeInteger(meta.hard_cap) && meta.hard_cap > 0), 'header row is malformed.');
+    assertSource(meta.throttle_per_minute === null || (typeof meta.throttle_per_minute === 'number' && Number.isSafeInteger(meta.throttle_per_minute) && meta.throttle_per_minute > 0), 'header row is malformed.');
+    sourceStringArray(meta.preamble_json);
+    sourceStringArray(meta.warmup_json);
+    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()) {
+        const index = sourceInteger(row.act_index);
+        assertSource(index > previous && index < nextActIndex, 'activity index is malformed or unassigned.');
+        const activity = driver.activity(index);
+        assertSource(activity !== undefined);
+        validateStoredActivity(activity);
+        activityCount++;
+        previous = index;
+    }
+    assertSource(nextActIndex > previous, 'nextActIndex is behind the activity history.');
+    const roster = driver.roster();
+    const routes = readLegacyRoutes(database);
+    for (const row of database.prepare('SELECT owner_json,act_index,at FROM receipts').iterate()) {
+        decodeJsonString(row.owner_json, true);
+        assertSource(sourceInteger(row.act_index) < nextActIndex, 'receipt references an unassigned activity index.');
+        sourceFinite(row.at);
+    }
+    const leaseGenerations = [];
+    const leaseOwners = [];
+    for (const row of database.prepare('SELECT owner_json,lease_id_json,heartbeat_at,expires_at,filter_json FROM catch_leases').iterate()) {
+        const owner = decodeJsonString(row.owner_json, true);
+        leaseOwners.push(row.owner_json);
+        const leaseId = decodeJsonString(row.lease_id_json, true);
+        const lease = {
+            leaseId,
+            heartbeatAt: sourceFinite(row.heartbeat_at),
+            expiresAt: sourceFinite(row.expires_at),
+            ...(row.filter_json === null ? {} : { filter: parseJson(row.filter_json, 'lease filter is malformed.') }),
+        };
+        validateLegacyLease(lease);
+        const ownerParticipant = roster.find((participant) => participant.joined && participant.name === owner);
+        if (ownerParticipant?.lastJoinIndex !== undefined)
+            leaseGenerations.push({ ownerJson: row.owner_json, generation: formatActivityId(ownerParticipant.lastJoinIndex) });
+    }
+    const seats = planSeats(location, roster, routes, host.owners, driver);
+    const counts = {
+        activities: activityCount,
+        receipts: Number(database.prepare('SELECT COUNT(*) AS n FROM receipts').get().n),
+        leases: leaseOwners.length,
+        routes: routes.length,
+    };
+    const sourceToken = legacySourceToken(database);
+    return { standing: seats.length, seats, leaseGenerations, sourceToken, counts,
+        deliveries: planLegacyDeliveries(host.evidence, seats, driver) };
+}
+function legacyPayloadHash(payload) {
+    return createHash('sha256').update(payload).digest('hex');
+}
+function legacyDeliveryPayload(source, current) {
+    const native = source.nativeDelivery;
+    if (native === undefined)
+        return {};
+    assertSource(isObject(native) && typeof native.payload === 'string' && native.payload.length > 0, 'native delivery correlation is malformed.');
+    if (native.harness === 'claude') {
+        assertSource(typeof source.claimToken === 'string' && /^[a-zA-Z0-9-]+$/.test(source.claimToken)
+            && typeof native.endpoint === 'string' && native.endpoint.length > 0
+            && (native.messageId === undefined || typeof native.messageId === 'string' && native.messageId.length > 0), 'Claude native correlation is malformed.');
+        const address = current?.kind === 'claude-native' && current.address.endpoint === native.endpoint
+            ? current.address : { endpoint: native.endpoint, loaded: 'true' };
+        return { correlation: { harness: 'claude', token: source.claimToken,
+                ...(native.messageId === undefined ? {} : { messageId: native.messageId }), payloadHash: legacyPayloadHash(native.payload) },
+            route: { kind: 'claude-native', address: { ...address, sessionId: source.session } } };
+    }
+    assertSource(native.harness === 'opencode' && typeof native.inputId === 'string' && native.inputId.length > 0, 'OpenCode native correlation is malformed.');
+    return { correlation: { harness: 'opencode', token: native.inputId, payloadHash: legacyPayloadHash(native.payload) },
+        route: current?.kind === 'opencode-server' && current.address.sessionId === source.session
+            ? current : { kind: 'opencode-server', address: { sessionId: source.session } } };
+}
+function planLegacyDeliveries(records, seats, driver) {
+    const byGroup = new Map();
+    const tokens = new Set(), completedBodies = new Map();
+    for (const source of records) {
+        const participant = driver.participant(source.participant);
+        const native = source.kind === 'wake' && source.nativeDelivery !== undefined;
+        if (!participant?.joined && !native)
+            continue; // Noncritical completed diagnostics are not imported.
+        assertSource(participant?.joined || participant?.done, `native delivery evidence for ${source.participant} has no unique participant.`);
+        const joined = establishingJoin(driver, participant);
+        const generation = formatActivityId(joined);
+        const seat = seats.find(seat => nameKey(seat.participant) === nameKey(participant.name));
+        if (participant.joined)
+            assertSource(seat !== undefined && seat.body.session === source.session
+                && source.agent === seat.body.agent && (source.channel === undefined || source.channel === seat.body.channel), `delivery evidence for standing participant ${source.participant} has no unique owner.`);
+        if (native && seat !== undefined)
+            assertSource(source.nativeDelivery?.harness ===
+                (seat.body.channel === 'claude-code' ? 'claude' : seat.body.channel === 'opencode' ? 'opencode' : undefined), 'native delivery harness conflicts with its owner body.');
+        const index = parseActivityId(source.activity);
+        assertSource(index !== undefined && index > joined && driver.activity(index)?.kind === 'say'
+            && driver.directedAt(participant.name, index) !== undefined, `delivery evidence for ${source.participant} has no unique activity in its join generation.`);
+        const payload = legacyDeliveryPayload(source, seat?.wakeAddress);
+        if (participant.done) {
+            const done = driver.activityHeads({ actors: [participant.name], kinds: ['done'] }, { edge: 'newest', limit: 1 }).items[0];
+            assertSource(done !== undefined && index < done.index && source.session.length > 0, `native delivery evidence for ${source.participant} has no unique completed generation.`);
+            const harness = source.nativeDelivery.harness;
+            const body = { channel: harness === 'claude' ? 'claude-code' : 'opencode', session: source.session,
+                ...(source.agent === undefined ? {} : { agent: source.agent }) };
+            validateBody(body);
+            const coordinate = JSON.stringify([body.channel, body.session, body.agent]);
+            const previous = completedBodies.get(nameKey(participant.name));
+            assertSource(previous === undefined || previous === coordinate, 'completed native delivery owner mapping is ambiguous.');
+            completedBodies.set(nameKey(participant.name), coordinate);
+        }
+        assertSource(source.kind === 'wake' || source.kind === 'presentation', 'delivery evidence kind is unsupported.');
+        assertSource(['dispatching', 'accepted', 'failed', 'unknown', 'released', 'presented', 'clipped'].includes(source.outcome), 'delivery evidence outcome is unsupported.');
+        const at = sourceFinite(source.at);
+        const expiresAt = source.expiresAt === undefined ? undefined : sourceFinite(source.expiresAt);
+        const claimToken = source.claimToken;
+        assertSource(claimToken === undefined || typeof claimToken === 'string' && claimToken.length > 0, 'delivery claim token is malformed.');
+        if (claimToken !== undefined) {
+            assertSource(!tokens.has(claimToken), 'delivery claim token is ambiguous.');
+            tokens.add(claimToken);
+        }
+        const group = JSON.stringify([nameKey(participant.name), generation, index, source.kind]);
+        const row = {
+            participant: participant.name,
+            generation,
+            index,
+            kind: source.kind,
+            outcome: source.outcome,
+            at,
+            ...(expiresAt === undefined ? {} : { expiresAt }),
+            ...(claimToken === undefined ? {} : { claimToken }),
+            payload,
+            ...(source.attemptN === undefined ? {} : { attemptN: source.attemptN }),
+        };
+        const rows = byGroup.get(group) ?? [];
+        rows.push(row);
+        byGroup.set(group, rows);
+    }
+    const deliveries = [];
+    for (const rows of byGroup.values()) {
+        const attempts = rows.map(row => row.attemptN);
+        const explicit = attempts.filter((attempt) => attempt !== undefined);
+        assertSource(explicit.every((attempt) => Number.isSafeInteger(attempt) && attempt >= 0) && new Set(explicit).size === explicit.length, 'delivery attempt mapping is ambiguous.');
+        if (explicit.length !== rows.length)
+            assertSource(rows.length === 1 && explicit.length === 0, 'delivery attempt mapping is ambiguous.');
+        rows.forEach((row, index) => deliveries.push({ ...row, attemptN: explicit.length === 0 ? 0 : explicit[index] }));
+    }
+    return deliveries;
+}
+const V4_REBUILT_TABLES = ['square_meta', 'catch_leases'];
+function tableDefinition(name) {
+    const definition = SCHEMA_SQL.split(';').map((statement) => statement.trim()).find((statement) => statement.startsWith(`CREATE TABLE ${name} (`));
+    if (definition === undefined)
+        throw new Error(`Missing current table definition for ${name}.`);
+    return `${definition};`;
+}
+function currentAdditionStatements() {
+    return SCHEMA_SQL.split(';').map((statement) => statement.trim()).filter((statement) => {
+        const match = /^(?:CREATE (?:UNIQUE )?TABLE|CREATE (?:UNIQUE )?INDEX)\s+([a-z_]+)/i.exec(statement);
+        return match !== null && FORMAT4_ADDED_OBJECTS.has(match[1]);
+    }).map((statement) => `${statement};`);
+}
+function importOwnershipAndEvidence(database, plan) {
+    for (const generation of plan.leaseGenerations) {
+        database.prepare('UPDATE catch_leases SET generation_json=? WHERE owner_json=?').run(JSON.stringify(generation.generation), generation.ownerJson);
+    }
+    const insertSeat = database.prepare('INSERT INTO seats(participant_key_json,participant_json,channel_json,session_json,agent_json,generation_json,wake_address_json) VALUES(?,?,?,?,?,?,?)');
+    for (const seat of plan.seats) {
+        insertSeat.run(JSON.stringify(nameKey(seat.participant)), JSON.stringify(seat.participant), JSON.stringify(seat.body.channel), JSON.stringify(seat.body.session), seat.body.agent === undefined ? null : JSON.stringify(seat.body.agent), JSON.stringify(seat.generation), seat.wakeAddress === undefined ? null : JSON.stringify(seat.wakeAddress));
+    }
+    const insertDelivery = database.prepare('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(?,?,?,?,?,?,?,?,?,?,?)');
+    for (const evidence of plan.deliveries) {
+        insertDelivery.run(JSON.stringify(nameKey(evidence.participant)), JSON.stringify(evidence.participant), JSON.stringify(evidence.generation), evidence.index, evidence.kind, evidence.attemptN, evidence.outcome, evidence.at, evidence.expiresAt ?? null, evidence.claimToken === undefined ? null : JSON.stringify(evidence.claimToken), JSON.stringify(evidence.payload));
+    }
+}
+function upgradeRowArtifact(database, location, plan) {
+    database.exec('ALTER TABLE square_meta RENAME TO square_meta_v3;');
+    database.exec(tableDefinition('square_meta'));
+    database.exec('INSERT INTO square_meta(id,revision,delivery_revision,next_act_index,hard_cap,throttle_per_minute,preamble_json,warmup_json) SELECT id,revision,0,next_act_index,hard_cap,throttle_per_minute,preamble_json,warmup_json FROM square_meta_v3;');
+    database.exec('DROP TABLE square_meta_v3;');
+    database.exec('ALTER TABLE catch_leases RENAME TO catch_leases_v3;');
+    database.exec(tableDefinition('catch_leases'));
+    database.exec('INSERT INTO catch_leases(owner_json,generation_json,lease_id_json,heartbeat_at,expires_at,filter_json) SELECT owner_json, \'""\', lease_id_json,heartbeat_at,expires_at,filter_json FROM catch_leases_v3;');
+    database.exec('DROP TABLE catch_leases_v3;');
+    currentAdditionStatements().forEach((statement) => database.exec(statement));
+    importOwnershipAndEvidence(database, plan);
+    database.exec('DROP TABLE routes;');
+    database.exec(`PRAGMA user_version = ${CURRENT_USER_VERSION};`);
+    validateFormat4Framing(database, location);
+}
 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 === V2_USER_VERSION || before.userVersion === V3_USER_VERSION) {
+        const issue = legacyRowFramingIssue(database, APPLICATION_ID, before.userVersion, location, SCHEMA_SQL);
+        if (issue !== undefined)
+            throw invalidArtifact(issue);
+        return before.userVersion;
     }
     if (before.userVersion === CURRENT_USER_VERSION) {
-        validateSqliteHeader(database, location);
+        validateFormat4Framing(database, location);
         return undefined;
     }
     throw invalidArtifact('unsupported SQLite format version.');
 }
 /**
- * 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.
+ * Explicit conversion of the supported legacy formats. Row-backed versions 2 and 3 are
+ * preflighted read-only, then receive the format-4 ownership/evidence rows in one transaction.
+ * 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.
  */
-export async function migrateSquareFile(location, signal) {
+export async function migrateSquareFile(location, signal, env = process.env) {
     const squarePath = await canonicalPath(location);
     const database = openExistingSquareDatabase(squarePath);
     try {
-        let alreadyCurrent;
-        const preflight = await inSqliteTransaction(database, false, () => {
-            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;
+        const source = await inSqliteTransaction(database, false, () => validateMigrationSource(database, squarePath), value => value, signal);
+        if (source === undefined)
+            return { status: 'already-current', standing: standing(database) };
+        const host = await readLegacyHostData(squarePath, env, signal);
+        const plan = await inSqliteTransaction(database, false, () => {
+            assertSource(validateMigrationSource(database, squarePath) === source, 'source format changed during migration preflight.');
+            return inspectLegacyRowArtifact(database, squarePath, host);
+        }, value => value, signal);
         database.exec('PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL');
         const result = {};
         await inSqliteTransaction(database, true, () => {
-            const source = validateMigrationSource(database, squarePath);
-            result.source = source;
+            assertSource(validateMigrationSource(database, squarePath) === source, 'source format changed during migration preflight.');
+            // Resolve the same frozen host input again against the locked artifact before any DDL.
+            const lockedPlan = inspectLegacyRowArtifact(database, squarePath, host);
+            assertSource(lockedPlan.sourceToken === plan.sourceToken, 'source changed during migration preflight.');
+            result.plan = lockedPlan;
         }, () => {
-            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) {
+            if (source === 2)
                 rebuildV2Activities(database);
-                database.exec(`PRAGMA user_version = ${CURRENT_USER_VERSION}`);
-                result.outcome = { status: 'migrated', standing: standing(database), counts: rowCounts(database) };
-            }
+            const migratedPlan = result.plan;
+            upgradeRowArtifact(database, squarePath, migratedPlan);
+            result.outcome = { status: 'migrated', standing: migratedPlan.standing, counts: migratedPlan.counts };
         }, signal);
-        return result.outcome ?? { status: 'already-current', standing: standing(database) };
+        return result.outcome;
     }
     finally {
         database.close();

package/dist/square-sqlite.d.ts

@@ -1,6 +1,6 @@
 import { type DatabaseSync } from 'node:sqlite';
-import { SquareError, type ActivityObservation, type HardCap, type StoredAct, type WakeRoute, type WatchLease } from './model.js';
-import type { SquareHeader, SquareRead, RouteFact } from './ports.js';
+import { SquareError, type ActivityObservation, type HardCap, type StoredAct, type WatchLease } from './model.js';
+import type { SquareHeader, SquareRead, DeliveryClaimInput, DeliveryClaimResult, DeliveryCompletion, DeliveryPreparation } from './ports.js';
 import { type LandingWriter } from './square-domain.js';
 /** Explicit import/export DTOs, not a runtime transaction model. */
 export interface SquareRuntimeState {
@@ -14,13 +14,13 @@ export interface SquareState {
     preamble: string[];
     warmup: string[];
     acts: StoredAct[];
-    routes?: WakeRoute[];
     runtime: SquareRuntimeState;
 }
 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 V3_USER_VERSION = 3;
+export declare const CURRENT_USER_VERSION = 4;
 export declare const V1_SNAPSHOT_TABLE = "square_snapshot";
 export interface LegacyFraming {
     readonly applicationId: number;
@@ -37,21 +37,21 @@ export declare function validateLegacyFraming(database: DatabaseSync, applicatio
 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 validateRowFraming(db: DatabaseSync, version: 2 | 3 | 4, location?: string): void;
 export declare function validateSqliteHeader(db: DatabaseSync, location?: string): SquareHeader;
 export interface SqliteDriver extends SquareRead, LandingWriter {
     readonly changed: boolean;
+    readonly deliveryChanged: boolean;
+    claimDelivery(input: DeliveryClaimInput): DeliveryClaimResult;
+    prepareDelivery(input: DeliveryPreparation): boolean;
+    completeDelivery(input: DeliveryCompletion): boolean;
 }
 export declare function createSqliteDriver(db: DatabaseSync): SqliteDriver;
-export declare function legacyRouteFact(value: Record<string, unknown>): RouteFact;
 /** Explicit import only. Caller owns transaction, legacy validation and format publication. */
 export declare function initializeSqlite(db: DatabaseSync, state: SquareState, revision?: number): void;
-/** Exceptional export projection for fixtures, never a runtime fallback. */
 export declare function exportSqliteState(db: DatabaseSync): SquareState;
 /** Full read-only integrity inspection, including maintained-index replay comparison. */
 export declare function inspectSqlite(db: DatabaseSync): {