@astrosheep/square 0.3.94 → 0.3.95

package/dist/square-facade.d.ts

@@ -5,12 +5,12 @@ import type { Owner, StoredAct, WakeAddress, ActivityMetadata, DirectedNotificat
 import type { WakeTransportPort, SquareResourceOwner } from './ports.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
 export type { Owner, WakeAddress, ActivityMetadata, JsonValue, DirectedNotificationRoute } from './model.js';
-/** Indexed archive event, including read and historical actorless lifecycle records. */
+/** Indexed archive event, including read bookkeeping. */
 export type ArchiveRecord = Readonly<StoredAct>;
 export interface Activity {
     readonly id: ActivityId;
     readonly at: number;
-    readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore' | 'unlisten';
+    readonly kind: 'join' | 'say' | 'done' | 'listen' | 'ignore' | 'unlisten';
     readonly actor: string;
     readonly body?: string;
     readonly metadata?: ActivityMetadata;
@@ -85,10 +85,8 @@ export interface CatchWaitStart {
 }
 export type OperationProgress = {
     readonly kind: 'waiting';
-    readonly reason: 'held' | 'throttled';
+    readonly reason: 'throttled';
     readonly delayMs?: number;
-    readonly holder?: string;
-    readonly holdReason?: string;
 } | ({
     readonly kind: 'catch-started';
     readonly participant: string;
@@ -135,10 +133,6 @@ export interface SquareSnapshot {
     readonly actCount: number;
     readonly hardCap: number | null;
     readonly throttlePerMinute?: number;
-    readonly held: {
-        readonly by: string;
-        readonly reason?: string;
-    } | null;
     readonly participants: readonly Pick<ParticipantSummary, 'name' | 'presence' | 'listening'>[];
     delivered(name: string, id: ActivityId): boolean;
 }
@@ -183,8 +177,6 @@ export interface Participant {
     unlisten(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     listening(options?: ObservationOptions, control?: OperationControl): Promise<ListeningResult>;
     catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
-    hold(reason?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
-    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<{
@@ -220,12 +212,6 @@ export interface StatusResult {
     readonly participants: readonly ParticipantSummary[];
     readonly now: number;
     readonly throttlePerMinute?: number;
-    /** Non-null whenever held; by is present with an actor and omitted only for historical actorless holds. */
-    readonly held: {
-        readonly by?: string;
-        readonly reason?: string;
-        readonly at?: number;
-    } | null;
     readonly latestActivity?: Activity;
     readonly observation?: StatusObservation;
 }
@@ -267,7 +253,6 @@ export interface InboxResult {
 export interface RecoveryResult {
     readonly participant?: string;
     readonly standingCount?: number;
-    readonly held?: boolean;
     readonly ownActivityCount?: number;
     readonly hardCap?: number | null;
     readonly activitySummaries?: readonly UnreadActivitySummary[];
@@ -310,7 +295,6 @@ export interface CatchPresence {
 export interface SquareObservation {
     readonly location: string;
     readonly standingCount: number;
-    readonly held: boolean;
     readonly now: number;
     readonly participant?: string;
 }
@@ -320,7 +304,7 @@ export interface JoinObservation extends SquareObservation {
     /** The receipt succeeded, but optional recent-history/context enrichment was unavailable. */
     readonly enrichmentUnavailable?: true;
 }
-export interface ExpressionObservation extends Pick<SquareObservation, 'standingCount' | 'held' | 'now'> {
+export interface ExpressionObservation extends Pick<SquareObservation, 'standingCount' | 'now'> {
     readonly ownActivityCount: number;
     readonly hardCap: number | null;
 }
@@ -361,7 +345,7 @@ export interface ListenerObservation extends SquareObservation {
     readonly participant: string;
     readonly target: string;
 }
-export interface StatusObservation extends Omit<SquareObservation, 'now' | 'held'>, PresenceClassification {
+export interface StatusObservation extends Omit<SquareObservation, 'now'>, PresenceClassification {
     readonly knownParticipantCount: number;
     readonly latestPerception?: Perception;
     readonly joins: readonly {

package/dist/square-legacy-framing.d.ts

@@ -1,6 +1,8 @@
 import type { DatabaseSync } from 'node:sqlite';
 export declare const FORMAT4_ADDED_OBJECTS: ReadonlySet<string>;
 export declare const FORMAT4_REPLACED_OBJECTS: ReadonlySet<string>;
+/** Historical activity framing only; no runtime activity decoder accepts these kinds. */
+export declare function legacyActivitySchema(currentSchemaSql: string): string;
 /**
  * Read-only recognition of the exact row framing accepted by explicit migration.
  * It inspects identity, owned schema and journal mode only; it never reads row

package/dist/square-legacy-framing.js

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

package/dist/square-migration.d.ts

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

package/dist/square-migration.js

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

package/dist/square-receive.d.ts

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

package/dist/square-receive.js

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

package/dist/square-sqlite.d.ts

@@ -23,7 +23,8 @@ export declare const V3_USER_VERSION = 3;
 export declare const V4_USER_VERSION = 4;
 export declare const V5_USER_VERSION = 5;
 export declare const V6_USER_VERSION = 6;
-export declare const CURRENT_USER_VERSION = 7;
+export declare const V7_USER_VERSION = 7;
+export declare const CURRENT_USER_VERSION = 8;
 export declare const V1_SNAPSHOT_TABLE = "square_snapshot";
 export interface LegacyFraming {
     readonly applicationId: number;
@@ -37,17 +38,18 @@ export interface LegacyFraming {
  * migration. Anything else is unrelated or unsupported, not repaired.
  */
 export declare function validateLegacyFraming(database: DatabaseSync, applicationId: number, location?: string): LegacyFraming;
-export declare const ACTIVITIES_TABLE_SQL = "CREATE TABLE activities (\n  act_index INTEGER PRIMARY KEY CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('join','done','say','hold','resume','read','listen','ignore','unlisten')),\n  actor_json TEXT COLLATE BINARY,\n  actor_key_json TEXT COLLATE BINARY,\n  reach TEXT CHECK (reach = 'bell'),\n  reply_index INTEGER CHECK (reply_index >= 0 AND reply_index < act_index),\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n  CHECK ((actor_json IS NULL) = (actor_key_json IS NULL)),\n  CHECK (kind IN ('hold','resume') OR actor_json IS NOT NULL),\n  CHECK (kind = 'say' OR (reach IS NULL AND reply_index IS NULL))\n);";
+export declare const ACTIVITIES_TABLE_SQL = "CREATE TABLE activities (\n  act_index INTEGER PRIMARY KEY CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('join','done','say','read','listen','ignore','unlisten')),\n  actor_json TEXT COLLATE BINARY NOT NULL,\n  actor_key_json TEXT COLLATE BINARY NOT NULL,\n  reach TEXT CHECK (reach = 'bell'),\n  reply_index INTEGER CHECK (reply_index >= 0 AND reply_index < act_index),\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n  CHECK (kind = 'say' OR (reach IS NULL AND reply_index IS NULL))\n);";
 export declare const ACTIVITY_INDEXES_SQL: readonly ["CREATE INDEX activity_kind_index ON activities(kind, act_index)", "CREATE INDEX activity_actor_index ON activities(actor_key_json, act_index)", "CREATE INDEX activity_say_actor_index ON activities(actor_key_json, act_index) WHERE kind='say'", "CREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say'", "CREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell'"];
 export declare const DELIVERY_DEFERRALS_SQL = "CREATE TABLE delivery_deferrals (\n  participant_key_json TEXT COLLATE BINARY NOT NULL,\n  participant_json TEXT NOT NULL,\n  generation_json TEXT NOT NULL,\n  deferral_id_json TEXT NOT NULL,\n  match_json TEXT NOT NULL CHECK (json_valid(match_json)),\n  expires_at REAL NOT NULL,\n  PRIMARY KEY (participant_key_json,generation_json,deferral_id_json)\n) WITHOUT ROWID;\nCREATE INDEX delivery_deferral_expiry ON delivery_deferrals(participant_key_json,generation_json,expires_at);";
 export declare const SCHEMA_SQL: string;
+export declare const FORMAT7_SCHEMA_SQL: string;
 export declare const FORMAT6_SCHEMA_SQL: string;
 export declare const FORMAT5_SCHEMA_SQL: string;
 export declare const FORMAT4_SCHEMA_SQL: string;
 export declare function invalidArtifact(detail: string): SquareError;
 export declare function validateStoredActivity(value: unknown): StoredAct;
 export declare function validateWatchLease(value: unknown): WatchLease;
-export declare function validateRowFraming(db: DatabaseSync, version: 2 | 3 | 4 | 5 | 6 | 7, location?: string): void;
+export declare function validateRowFraming(db: DatabaseSync, version: 2 | 3 | 4 | 5 | 6 | 7 | 8, location?: string): void;
 export declare function validateSqliteHeader(db: DatabaseSync, location?: string): SquareHeader;
 export interface SqliteDriver extends SquareRead, LandingWriter {
     readonly changed: boolean;