@astrosheep/square 0.3.87 → 0.3.89

package/dist/presentation-operations.js

@@ -2,71 +2,95 @@ import { randomUUID } from 'node:crypto';
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { isSquareError, sameBody } from './model.js';
 import { pendingHead, sameJoin } from './delivery.js';
+import { deliveryDeferralExpiry } from './delivery-deferral.js';
 import { asSeatRef } from './seats.js';
-function currentFor(input, captured, participant, index) {
-    return (facts) => {
-        const seat = facts.seat(captured.participant);
-        return seat !== undefined && sameBody(seat.body, captured.body) && seat.generation === captured.generation
-            && sameJoin(facts, participant) && input.current?.(facts) !== false
-            && pendingHead(facts, captured.participant, index) !== undefined;
-    };
-}
-/** Presentation is external; its claim and receipt/evidence commit are generation-fenced in the artifact. */
-export async function presentPending(input) {
+/** Prepare custody before any external effect. A batch prepares every included item first. */
+export async function preparePendingPresentation(input) {
     const index = typeof input.activity === 'number' ? input.activity : parseActivityId(input.activity);
     if (index === undefined)
-        return { presented: false };
+        return undefined;
     const initial = await input.artifact.read((facts) => {
         const participant = facts.participant(input.participant);
         const seat = facts.seat(input.participant);
         if (!participant?.joined || seat === undefined || input.generation !== undefined && input.generation !== seat.generation
             || input.seat !== undefined && (input.seat.generation !== seat.generation || !sameBody(input.seat.body, seat.body))
-            || input.current?.(facts) === false || !pendingHead(facts, participant.name, index))
+            || input.current?.(facts) === false || !pendingHead(facts, participant.name, index)
+            || deliveryDeferralExpiry(facts, seat, index, input.now ?? Date.now()) !== undefined)
             return undefined;
         const item = facts.activity(index);
         return item?.kind === 'say' ? { participant, seat, item } : undefined;
     }, input.signal).catch(() => undefined);
     if (initial?.value === undefined)
-        return { presented: false };
+        return undefined;
     const { participant, seat, item } = initial.value;
     const ref = asSeatRef(seat);
-    const current = currentFor(input, seat, participant, index);
+    const owns = (facts) => {
+        const current = facts.seat(seat.participant);
+        return current !== undefined && sameBody(current.body, seat.body) && current.generation === seat.generation
+            && sameJoin(facts, participant);
+    };
     const claimToken = randomUUID();
     const claimed = await input.artifact.claimDelivery({ seat: ref, activity: formatActivityId(index), kind: 'presentation',
         at: input.now ?? Date.now(), leaseMs: input.timeoutMs ?? 5000, claimToken }, input.signal).catch(() => ({ status: 'stale' }));
     if (claimed.status !== 'acquired')
+        return undefined;
+    let effectObserved = false, released = false;
+    return {
+        activity: item,
+        async eligible() {
+            return (await input.artifact.read(facts => owns(facts) && input.current?.(facts) !== false
+                && pendingHead(facts, participant.name, index) !== undefined
+                && deliveryDeferralExpiry(facts, seat, index, input.now ?? Date.now()) === undefined, input.signal).catch(() => undefined))?.value === true;
+        },
+        async release(outcome = 'released', message) {
+            if (effectObserved || released)
+                return;
+            released = true;
+            await input.artifact.settleAs({ kind: 'participant', seat: ref }, facts => facts.completeDelivery({
+                seat: ref, activity: formatActivityId(index), claimToken, outcome, at: Date.now(),
+                ...(message === undefined ? {} : { message }),
+            })).catch(() => false);
+        },
+        async recordPresented() {
+            // Success is an observed external fact, not another eligibility decision. Neither
+            // post-effect cancellation nor a new deferral can erase it and authorize replay.
+            effectObserved = true;
+            const outcome = input.markSeen === false ? 'clipped' : 'presented';
+            const { value: committed } = await input.artifact.settleAs({ kind: 'participant', seat: ref }, facts => {
+                if (!owns(facts))
+                    return false;
+                if (!facts.completeDelivery({ seat: ref, activity: formatActivityId(index), claimToken, outcome, at: input.now ?? Date.now() }))
+                    return false;
+                if (input.markSeen !== false)
+                    facts.markSeen(participant.name, [index], input.now ?? Date.now());
+                return true;
+            }).catch(error => {
+                if (isSquareError(error) && error.code === 'already_joined')
+                    return { value: false };
+                throw error;
+            });
+            return committed ? { presented: true, activity: item } : { presented: false };
+        },
+    };
+}
+/** Eligibility precedes the sink; only captured ownership fences its truthful completion. */
+export async function presentPending(input) {
+    const prepared = await preparePendingPresentation(input);
+    if (prepared === undefined)
         return { presented: false };
-    const release = async (outcome, message) => input.artifact.completeDelivery({
-        seat: ref, activity: formatActivityId(index), claimToken, outcome, at: Date.now(),
-        ...(message === undefined ? {} : { message }),
-    }, input.signal).catch(() => false);
-    const fresh = await input.artifact.read(current, input.signal).catch(() => undefined);
-    if (!fresh?.value) {
-        await release('released', 'The notification changed before presentation.');
-        return { presented: false };
-    }
     try {
-        await input.sink.present(item);
+        if (!await prepared.eligible() || input.signal?.aborted)
+            return { presented: false };
+        try {
+            await input.sink.present(prepared.activity);
+        }
+        catch (error) {
+            await prepared.release('failed', error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        return await prepared.recordPresented();
     }
-    catch (error) {
-        await release('failed', error instanceof Error ? error.message : String(error));
-        throw error;
+    finally {
+        await prepared.release();
     }
-    const outcome = input.markSeen === false ? 'clipped' : 'presented';
-    const { value: committed } = await input.artifact.transactAs({ kind: 'participant', seat: ref }, (facts) => {
-        if (!current(facts))
-            return false;
-        if (!facts.completeDelivery({ seat: ref, activity: formatActivityId(index), claimToken, outcome, at: input.now ?? Date.now() }))
-            return false;
-        if (input.markSeen === false)
-            return true;
-        return facts.markSeen(participant.name, [index], input.now ?? Date.now()) > 0;
-    }, input.signal).catch(error => {
-        if (isSquareError(error) && error.code === 'already_joined')
-            return { value: false };
-        throw error;
-    });
-    if (!committed)
-        return { presented: false };
-    return { presented: true, activity: item };
 }

package/dist/sqlite-square.js

@@ -1,4 +1,5 @@
 import { formatActivityId } from './square-core.js';
+import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
 import { squareLocation, localSquareLocation } from './square-location.js';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
@@ -55,10 +56,6 @@ function rejectUnsentActivity(operation) {
         throw error;
     }
 }
-/** A generic managed address must not displace the receiver's native registration on reconnect. */
-function canRefreshWakeAddress(current, proposed) {
-    return proposed.kind !== 'paseo' || current === undefined || current.kind === 'paseo';
-}
 /** One concrete local resource, including its entry-resolved dependencies and lifetime. */
 export class SqliteSquare {
     location;
@@ -382,6 +379,34 @@ export class SqliteSquare {
                     await releaseWatchLease(square.artifact, seat, leaseId).catch(() => undefined);
             }
         }
+        async deferDelivery(input, control) {
+            checkControl(control);
+            const match = validateMetadataMatch(input?.match), duration = validateDeferralDuration(input?.durationMs);
+            const square = this.owner, seat = requireSeat(this.seat, square.body, this.name);
+            return (await square.artifact.transactAs(participantAuthority(seat), facts => {
+                const now = square.clock(), expiresAt = now + duration, id = crypto.randomUUID();
+                const result = { id, expiresAt: new Date(expiresAt).toISOString() };
+                facts.putDeliveryDeferral(asSeatRef(seat), id, match, expiresAt, now);
+                return result;
+            }, control?.signal)).value;
+        }
+        async renewDeliveryDeferral(id, durationMs, control) {
+            checkControl(control);
+            validateDeferralId(id);
+            const duration = validateDeferralDuration(durationMs), square = this.owner;
+            const seat = requireSeat(this.seat, square.body, this.name);
+            return (await square.artifact.transactAs(participantAuthority(seat), facts => {
+                const now = square.clock(), expiresAt = now + duration;
+                const result = { id, expiresAt: new Date(expiresAt).toISOString() };
+                return facts.renewDeliveryDeferral(asSeatRef(seat), id, expiresAt, now) ? result : null;
+            }, control?.signal)).value;
+        }
+        async releaseDeliveryDeferral(id, control) {
+            checkControl(control);
+            validateDeferralId(id);
+            const square = this.owner, seat = requireSeat(this.seat, square.body, this.name);
+            return (await square.artifact.transactAs(participantAuthority(seat), facts => facts.releaseDeliveryDeferral(asSeatRef(seat), id, square.clock()), control?.signal)).value;
+        }
         history(query, control) { return this.owner.history(query, control); }
         async lifecycle(verb, body, options, control) {
             if (verb === 'done')
@@ -441,7 +466,7 @@ export class SqliteSquare {
                 else if (current?.joined) {
                     if (currentSeat === undefined || !sameBody(currentSeat.body, body))
                         throw new SquareError('already_joined', `${participantIdentity(participant)} is held by another body; take it over explicitly`);
-                    if (this.wakeAddress !== undefined && canRefreshWakeAddress(currentSeat.wakeAddress, this.wakeAddress))
+                    if (this.wakeAddress !== undefined)
                         facts.updateWakeAddress(asSeatRef(currentSeat), this.wakeAddress);
                     kind = 'reconnected';
                 }
@@ -482,7 +507,7 @@ export class SqliteSquare {
             if (decision.joinAct === undefined) {
                 if (decision.state === 'active' && (seat === undefined || !sameBody(seat.body, body)))
                     throw new SquareError('already_joined', `${participantIdentity(decision.joinedName)} is held by another body`);
-                if (decision.state === 'active' && this.wakeAddress !== undefined && canRefreshWakeAddress(seat.wakeAddress, this.wakeAddress))
+                if (decision.state === 'active' && this.wakeAddress !== undefined)
                     facts.updateWakeAddress(asSeatRef(seat), this.wakeAddress);
             }
             else {

package/dist/square-domain.d.ts

@@ -21,7 +21,7 @@ export interface LandingFacts {
 /** The single landing transition, shared by both adapters and explicit rebuild. */
 export declare function deriveLanding(activity: StoredAct, facts: LandingFacts): LandingEffect;
 export declare function landingFacts(read: SquareRead, activity: StoredAct): LandingFacts;
-export interface LandingWriter extends Pick<SquareWrite, 'markSeen' | 'putLease' | 'removeLease' | 'updateWakeAddress' | 'cancelThrough' | 'claimDelivery' | 'prepareDelivery' | 'completeDelivery' | 'observeNativeDelivery'> {
+export interface LandingWriter extends Pick<SquareWrite, 'markSeen' | 'putLease' | 'removeLease' | 'updateWakeAddress' | 'cancelThrough' | 'putDeliveryDeferral' | 'renewDeliveryDeferral' | 'releaseDeliveryDeferral' | 'claimDelivery' | 'prepareDelivery' | 'completeDelivery' | 'observeNativeDelivery'> {
     /** Artifact-private seat persistence used only by this gate's lifecycle transition. */
     storeSeat(seat: Seat): boolean;
     removeSeat(seat: import('./ports.js').SeatRef): boolean;

package/dist/square-domain.js

@@ -206,6 +206,18 @@ export function wrapSquareWrite(read, writes, authority) {
             assertParticipant(name, generation);
             return mutations.removeLease(name, leaseId, generation);
         },
+        putDeliveryDeferral(...args) {
+            assertSeat(args[0]);
+            return mutations.putDeliveryDeferral(...args);
+        },
+        renewDeliveryDeferral(...args) {
+            assertSeat(args[0]);
+            return mutations.renewDeliveryDeferral(...args);
+        },
+        releaseDeliveryDeferral(...args) {
+            assertSeat(args[0]);
+            return mutations.releaseDeliveryDeferral(...args);
+        },
         claimDelivery(input) {
             assertSeat(input.seat);
             return mutations.claimDelivery(input);

package/dist/square-facade.d.ts

@@ -1,4 +1,6 @@
 import type { SquareBackends } from './square-backend.js';
+import type { DeliveryDeferral, MetadataMatch } from './delivery-deferral.js';
+export type { DeliveryDeferral, MetadataMatch, MetadataScalar } from './delivery-deferral.js';
 import type { ActivityId, Perception, Reach } from './square-core.js';
 import type { Body, StoredAct, WakeAddress, ActivityMetadata } from './model.js';
 import type { WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
@@ -203,6 +205,12 @@ export interface Participant {
     resume(options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
     /** Leave without a message. Only an omitted or empty body is accepted. */
     done(body?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
+    deferDelivery(input: Readonly<{
+        match: MetadataMatch;
+        durationMs: number;
+    }>, control?: OperationControl): Promise<DeliveryDeferral>;
+    renewDeliveryDeferral(id: string, durationMs: number, control?: OperationControl): Promise<DeliveryDeferral | null>;
+    releaseDeliveryDeferral(id: string, control?: OperationControl): Promise<boolean>;
 }
 export type CatchTerminalStatus = 'already-active' | 'replaced' | 'capped' | 'quorum';
 export type CatchStopStatus = CatchTerminalStatus | 'empty-now' | 'stale';

package/dist/square-migration.d.ts

@@ -15,7 +15,8 @@ export interface MigrationOutcome {
 }
 /**
  * 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.
+ * preflighted read-only, then receive ownership/evidence and deferral storage in one
+ * format-5 transaction. Format 4 adds only the empty deferral table and its index.
  * 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

@@ -5,8 +5,8 @@ import { canonicalPath, canonicalPathSync } from './canonical-path.js';
 import { formatActivityId, isWakeRouteKind, nameKey, sameBody, validateBody } from './model.js';
 import { parseActivityId } from './square-core.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';
+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, SCHEMA_SQL, FORMAT4_SCHEMA_SQL, DELIVERY_DEFERRALS_SQL, validateRowFraming, inspectSqlite, createSqliteDriver, invalidArtifact, validateStoredActivity } from './square-sqlite.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -140,26 +140,8 @@ 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.');
+function validateCurrentFraming(database, location) {
+    validateRowFraming(database, CURRENT_USER_VERSION, location);
     createSqliteDriver(database).header();
 }
 function assertSource(condition, detail = 'row is malformed.') {
@@ -474,28 +456,35 @@ function upgradeRowArtifact(database, location, plan) {
     currentAdditionStatements().forEach((statement) => database.exec(statement));
     importOwnershipAndEvidence(database, plan);
     database.exec('DROP TABLE routes;');
+    database.exec(DELIVERY_DEFERRALS_SQL);
     database.exec(`PRAGMA user_version = ${CURRENT_USER_VERSION};`);
-    validateFormat4Framing(database, location);
+    validateCurrentFraming(database, location);
 }
 function validateMigrationSource(database, location) {
     const before = identity(database);
     if (before.applicationId !== APPLICATION_ID)
         throw invalidArtifact('unrelated SQLite database.');
     if (before.userVersion === V2_USER_VERSION || before.userVersion === V3_USER_VERSION) {
-        const issue = legacyRowFramingIssue(database, APPLICATION_ID, before.userVersion, location, SCHEMA_SQL);
+        const issue = legacyRowFramingIssue(database, APPLICATION_ID, before.userVersion, location, FORMAT4_SCHEMA_SQL);
         if (issue !== undefined)
             throw invalidArtifact(issue);
         return before.userVersion;
     }
+    if (before.userVersion === V4_USER_VERSION) {
+        validateRowFraming(database, V4_USER_VERSION, location);
+        inspectSqlite(database);
+        return V4_USER_VERSION;
+    }
     if (before.userVersion === CURRENT_USER_VERSION) {
-        validateFormat4Framing(database, location);
+        validateCurrentFraming(database, location);
         return undefined;
     }
     throw invalidArtifact('unsupported SQLite 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.
+ * preflighted read-only, then receive ownership/evidence and deferral storage in one
+ * format-5 transaction. Format 4 adds only the empty deferral table and its index.
  * 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.
  */
@@ -506,6 +495,16 @@ 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) {
+            return await inSqliteTransaction(database, true, () => {
+                assertSource(validateMigrationSource(database, squarePath) === source, 'source format changed during migration preflight.');
+            }, () => {
+                database.exec(DELIVERY_DEFERRALS_SQL);
+                database.exec(`PRAGMA user_version = ${CURRENT_USER_VERSION};`);
+                validateCurrentFraming(database, squarePath);
+                return { status: 'migrated', standing: standing(database) };
+            }, signal);
+        }
         const host = await readLegacyHostData(squarePath, env, signal);
         const plan = await inSqliteTransaction(database, false, () => {
             assertSource(validateMigrationSource(database, squarePath) === source, 'source format changed during migration preflight.');

package/dist/square-sqlite.d.ts

@@ -20,7 +20,8 @@ export declare function emptyRuntimeState(nextActIndex?: number): SquareRuntimeS
 export declare const APPLICATION_ID = 1397838405;
 export declare const V2_USER_VERSION = 2;
 export declare const V3_USER_VERSION = 3;
-export declare const CURRENT_USER_VERSION = 4;
+export declare const V4_USER_VERSION = 4;
+export declare const CURRENT_USER_VERSION = 5;
 export declare const V1_SNAPSHOT_TABLE = "square_snapshot";
 export interface LegacyFraming {
     readonly applicationId: number;
@@ -36,11 +37,13 @@ export interface LegacyFraming {
 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 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 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, location?: string): void;
+export declare function validateRowFraming(db: DatabaseSync, version: 2 | 3 | 4 | 5, 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,5 +1,6 @@
 import { DatabaseSync as MemoryDatabase } from 'node:sqlite';
-import { SquareError, nameKey, isWakeRouteKind, validateBody, validateActivityMetadata, activityMetadataHasContent } from './model.js';
+import { sameBody, SquareError, nameKey, isWakeRouteKind, validateBody, 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';
 export function emptyRuntimeState(nextActIndex = 0) {
@@ -9,7 +10,8 @@ export const APPLICATION_ID = 0x53515245;
 const V1_USER_VERSION = 1;
 export const V2_USER_VERSION = 2;
 export const V3_USER_VERSION = 3;
-export const CURRENT_USER_VERSION = 4;
+export const V4_USER_VERSION = 4;
+export const CURRENT_USER_VERSION = 5;
 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 = [
@@ -75,6 +77,16 @@ export const ACTIVITY_INDEXES_SQL = [
     "CREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say'",
     "CREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell'",
 ];
+export const DELIVERY_DEFERRALS_SQL = `CREATE TABLE delivery_deferrals (
+  participant_key_json TEXT COLLATE BINARY NOT NULL,
+  participant_json TEXT NOT NULL,
+  generation_json TEXT NOT NULL,
+  deferral_id_json TEXT NOT NULL,
+  match_json TEXT NOT NULL CHECK (json_valid(match_json)),
+  expires_at REAL NOT NULL,
+  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);`;
 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),
@@ -137,6 +149,8 @@ CREATE TABLE delivery_cancellations (
   PRIMARY KEY (participant_key_json,generation_json)
 ) WITHOUT ROWID;
 
+${DELIVERY_DEFERRALS_SQL}
+
 CREATE TABLE participants (
   name_key_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,
   name_json TEXT NOT NULL,
@@ -166,7 +180,9 @@ 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, '');
 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;
 const key = (name) => encode(nameKey(name));
 export function invalidArtifact(detail) {
@@ -412,6 +428,15 @@ function deliveryEvidence(row) {
         ...(nativeObservations === undefined ? {} : { nativeObservations }),
     });
 }
+function deliveryDeferral(row) {
+    const participant = decoded(row.participant_json, true);
+    requireFact(row.participant_key_json === key(participant));
+    const generation = activityId(decoded(row.generation_json, true));
+    const id = validateDeferralId(decoded(row.deferral_id_json, true));
+    const match = validateMetadataMatch(json(row.match_json));
+    requireFact(encode(match) === row.match_json, 'delivery deferral match encoding is malformed.');
+    return immutable({ participant, generation, id, match, expiresAt: finite(row.expires_at) });
+}
 function normalizedSql(sql) { return sql.trim().replace(/;$/, '').replace(/\s+/g, ' ').replace(/\s*([(),=])\s*/g, '$1'); }
 function validateOwnedSchema(db, expected, location) {
     const actual = db.prepare("SELECT sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' AND sql IS NOT NULL").all().map(r => normalizedSql(string(r.sql))).sort();
@@ -420,7 +445,7 @@ function validateOwnedSchema(db, expected, location) {
 }
 export function validateRowFraming(db, version, location = '') {
     if (version === V2_USER_VERSION || version === V3_USER_VERSION) {
-        const issue = legacyRowFramingIssue(db, APPLICATION_ID, version, location, SCHEMA_SQL);
+        const issue = legacyRowFramingIssue(db, APPLICATION_ID, version, location, FORMAT4_SCHEMA_SQL);
         if (issue !== undefined)
             throw invalidArtifact(issue);
         return;
@@ -428,7 +453,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, EXPECTED_SCHEMA_SQL, location);
+    validateOwnedSchema(db, version === V4_USER_VERSION ? FORMAT4_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();
@@ -437,7 +462,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) {
+    if (identity.user_version === V2_USER_VERSION || identity.user_version === V3_USER_VERSION || identity.user_version === V4_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' });
     }
@@ -669,6 +694,13 @@ export function createSqliteDriver(db) {
             return immutable({ ...(r.latest === null ? {} : { latestAt: finite(r.latest) }), ...(e.latest === null ? {} : { latestActorActivityIndex: integer(e.latest) }) });
         },
         receiptAssignments: () => immutable(all('SELECT owner_json,act_index FROM receipts ORDER BY owner_json,act_index').map(r => ({ owner: decoded(r.owner_json, true), index: integer(r.act_index) }))),
+        deliveryDeferrals(name, generation) {
+            const canonical = owner(name);
+            const current = read.seat(canonical);
+            if (current === undefined || current.generation !== generation)
+                return [];
+            return immutable(all('SELECT * FROM delivery_deferrals WHERE participant_key_json=? AND generation_json=? ORDER BY expires_at,deferral_id_json', [key(canonical), encode(generation)]).map(deliveryDeferral));
+        },
         lease(name) {
             const canonical = owner(name), current = read.seat(canonical);
             const r = current === undefined
@@ -690,6 +722,7 @@ export function createSqliteDriver(db) {
             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('DELETE FROM catch_leases WHERE owner_json=?', [encode(value.participant)]);
+            run('DELETE FROM delivery_deferrals WHERE participant_key_json=?', [key(value.participant)]);
             deliveryChanged = true;
             return true;
         },
@@ -713,6 +746,7 @@ export function createSqliteDriver(db) {
                 return false;
             run('UPDATE seats SET wake_address_json=NULL 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;
             deliveryChanged = true;
             return true;
@@ -791,6 +825,32 @@ export function createSqliteDriver(db) {
             changed = true;
             return true;
         },
+        putDeliveryDeferral(seatRef, id, match, expiresAt, now) {
+            finite(now);
+            finite(expiresAt);
+            const canonicalMatch = validateMetadataMatch(match);
+            run('DELETE FROM delivery_deferrals WHERE participant_key_json=? AND expires_at<=?', [key(seatRef.participant), now]);
+            run('INSERT INTO delivery_deferrals(participant_key_json,participant_json,generation_json,deferral_id_json,match_json,expires_at) VALUES(?,?,?,?,?,?)', [key(seatRef.participant), encode(seatRef.participant), encode(seatRef.generation), encode(id), encode(canonicalMatch), expiresAt]);
+            deliveryChanged = true;
+            return true;
+        },
+        renewDeliveryDeferral(seatRef, id, expiresAt, now) {
+            finite(now);
+            finite(expiresAt);
+            const pruned = run('DELETE FROM delivery_deferrals WHERE participant_key_json=? AND expires_at<=?', [key(seatRef.participant), now]);
+            const count = run('UPDATE delivery_deferrals SET expires_at=? WHERE participant_key_json=? AND generation_json=? AND deferral_id_json=? AND expires_at>?', [expiresAt, key(seatRef.participant), encode(seatRef.generation), encode(id), now]);
+            if (count || pruned)
+                deliveryChanged = true;
+            return count > 0;
+        },
+        releaseDeliveryDeferral(seatRef, id, now) {
+            finite(now);
+            const pruned = run('DELETE FROM delivery_deferrals WHERE participant_key_json=? AND expires_at<=?', [key(seatRef.participant), now]);
+            const count = run('DELETE FROM delivery_deferrals WHERE participant_key_json=? AND generation_json=? AND deferral_id_json=? AND expires_at>?', [key(seatRef.participant), encode(seatRef.generation), encode(id), now]);
+            if (count || pruned)
+                deliveryChanged = true;
+            return count > 0;
+        },
         removeLease(name, expected, generation) {
             const canonical = owner(name), row = one('SELECT generation_json FROM catch_leases WHERE owner_json=? AND lease_id_json=?', [encode(canonical), encode(expected)]);
             if (row === undefined || generation !== undefined && decoded(row.generation_json) !== generation)
@@ -810,8 +870,13 @@ export function createSqliteDriver(db) {
             string(input.claimToken, true);
             if (input.route !== undefined)
                 wakeAddress(input.route);
-            if (read.activity(index)?.kind !== 'say' || read.directedAt(input.seat.participant, index) === undefined)
+            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)
+                || 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)
+                return { status: 'deferred' };
             const cancelledThrough = read.cancelledThrough(input.seat.participant, input.seat.generation);
             if (cancelledThrough !== undefined && index <= cancelledThrough)
                 return { status: 'stale' };
@@ -962,6 +1027,14 @@ export function inspectSqlite(db) {
     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);
+    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) {
+        for (const row of db.prepare('SELECT * FROM delivery_deferrals').all())
+            deliveryDeferral(row);
+    }
     for (const p of d.roster()) {
         d.attention(p.name);
         d.incomingAttention(p.name);

package/dist/square-stdio.d.ts

@@ -2,7 +2,7 @@ import { type SquareErrorCode, type SquareErrorFacts } from './model.js';
 import type { SquareBackends, SquareBackend } from './square-backend.js';
 import type { ParsedSquareLocation } from './square-location.js';
 import type { OperationControl, OperationFailureDetail, SquareAtInput, SquareBuildInput } from './square-facade.js';
-export declare const STDIO_PROTOCOL_VERSION = 1;
+export declare const STDIO_PROTOCOL_VERSION = 2;
 export declare const STDIO_MAX_FRAME_BYTES: number;
 export declare const identityVariables: (import("./participant-identity.js").HarnessSessionVariable | "CLAUDE_CODE_CHILD_SESSION")[];
 export declare function wireIdentity(env: NodeJS.ProcessEnv): Record<string, string>;