@astrosheep/square 0.3.69 → 0.3.71

package/dist/square-facade.d.ts

@@ -1,5 +1,11 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
+import type { StoredAct } from './model.js';
 import type { HostLedgerPort, WakeTransportPort, DeliveryResult } from './ports.js';
+import type { DiagnoseResult } from './artifact.js';
+import type { MigrationOutcome } from './square-migration.js';
+export type { ActivityId, Perception, Reach } from './square-core.js';
+/** The existing indexed domain event, including read and historical actorless lifecycle records. */
+export type ArchiveRecord = Readonly<StoredAct>;
 export interface Activity {
     readonly id: ActivityId;
     readonly at: number;
@@ -24,12 +30,13 @@ export interface ExpressOptions {
 export interface ExpressResult {
     readonly activity: Activity;
     readonly delivery?: DeliveryResult;
-    /** The replied-to author was not standing when the reply landed, so no notification reached them. */
+    /** The replied-to author was not standing when the reply landed. */
     readonly replyAuthorNotHere?: string;
 }
-export interface ListenerChangeResult {
+export interface ListenerChangeData {
     readonly activity: Activity | null;
 }
+export type ListenerChangeResult = ListenerChangeData;
 export interface CatchOptions {
     readonly id?: ActivityId;
     readonly idle?: number;
@@ -43,13 +50,21 @@ export interface CatchResult {
     readonly idleExpired: boolean;
     readonly remaining: number;
 }
-export interface OperationProgress {
+export interface CatchWaitStart {
+    readonly idleMs: number;
+    readonly replacementRequested: boolean;
+    readonly replaced: boolean;
+}
+export type OperationProgress = {
     readonly kind: 'waiting';
     readonly reason: 'held' | 'throttled';
     readonly delayMs?: number;
     readonly holder?: string;
     readonly holdReason?: string;
-}
+} | ({
+    readonly kind: 'catch-started';
+    readonly participant: string;
+} & CatchWaitStart);
 export interface OperationControl {
     readonly signal?: AbortSignal;
     readonly onProgress?: (progress: OperationProgress) => void;
@@ -94,14 +109,10 @@ export interface OpenOptions {
 }
 export interface SquareAtInput extends SquareSource, OpenOptions {
 }
-export interface SquareBuildInput extends SquareSource {
+export interface SquareBuildInput extends SquareSource, OpenOptions {
     markdown: string;
     hardCap?: number | null;
     throttlePerMinute?: number;
-    clock?: () => number;
-    hostLedger?: HostLedgerPort;
-    wakeTransport?: WakeTransportPort;
-    env?: NodeJS.ProcessEnv;
 }
 /** Optional fence for owner-scoped lifecycle actions. */
 export interface OwnershipFenceOptions {
@@ -120,3 +131,343 @@ export interface Participant {
     /** Leave without a message. Only an omitted or empty body is accepted. */
     done(body?: string, control?: OperationControl): Promise<ExpressResult>;
 }
+export interface SquareApplicationContext extends Readonly<OpenOptions> {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly squarePath?: string;
+    readonly participant?: string;
+}
+export interface ApplicationOutcome<Data, Projection> {
+    readonly data: Data;
+    readonly projection: Projection;
+}
+export interface ApplicationFailureDetail {
+    readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
+    readonly subject?: 'caller' | 'filter' | 'recipient';
+    readonly participant?: string;
+    readonly expressEffect?: 'unsent' | 'landed' | 'unknown';
+    readonly landedId?: ActivityId;
+    readonly historyBounds?: {
+        readonly maxLimit: number;
+        readonly totalMatches: number;
+    };
+}
+export interface ApplicationError extends Error {
+    readonly operation?: ApplicationFailureDetail;
+}
+export interface SquareContextProjection {
+    readonly location: string;
+    readonly standingCount: number;
+    readonly held: boolean;
+    readonly now: number;
+    readonly participant?: string;
+    readonly automaticDeliveryAvailable: boolean;
+}
+export interface BuildApplicationInput {
+    readonly markdown: string;
+    readonly hardCap?: number | null;
+    readonly throttlePerMinute?: number;
+    readonly template?: string;
+    readonly force?: boolean;
+}
+export interface BuildApplicationData {
+    readonly location: string;
+    readonly hardCap: number | null;
+    readonly throttlePerMinute?: number;
+}
+export interface JoinApplicationOptions {
+    readonly takeover?: boolean;
+    readonly last?: number;
+}
+export interface JoinApplicationData {
+    readonly participant: string;
+    readonly activity: Activity | null;
+    readonly kind: 'joined' | 'reconnected' | 'taken-over';
+    /** Known joined-or-done participants, NOT the current standing count. */
+    readonly participantCount: number;
+}
+export interface ExpressApplicationOptions extends ExpressOptions {
+    readonly noWait?: boolean;
+    readonly requireExplicitReach?: boolean;
+}
+export interface ExpressApplicationData {
+    readonly activity: Activity;
+    readonly waited: boolean;
+    readonly replyAuthorNotHere?: string;
+}
+export interface CatchApplicationOptions extends CatchOptions {
+    readonly replace?: boolean;
+}
+export type CatchTerminalStatus = 'already-active' | 'replaced' | 'capped' | 'quorum';
+export type CatchStopStatus = CatchTerminalStatus | 'empty-now' | 'stale';
+export interface CatchApplicationData extends CatchResult {
+    readonly status?: CatchTerminalStatus;
+}
+export interface HistoryApplicationQuery extends HistoryQuery {
+    readonly since?: number;
+    readonly at?: readonly ActivityId[];
+    readonly contextBefore?: number;
+    readonly contextAfter?: number;
+}
+export interface HistoryApplicationData {
+    readonly activities: readonly Activity[];
+}
+export interface ListeningData {
+    readonly listening: readonly string[];
+}
+export interface LifecycleData {
+    readonly activity: Activity;
+}
+export type ParticipantPresence = 'never-joined' | 'active' | 'watching' | 'done';
+/** Canonical public participant fields; status excludes never-joined roster entries. */
+export interface ParticipantSummary {
+    readonly name: string;
+    readonly state: 'active' | 'done' | 'not joined';
+    readonly listening: readonly string[];
+    readonly activityCount: number;
+    readonly lastActiveAt?: number;
+    readonly presence: ParticipantPresence;
+    readonly unreadActivityCount: number;
+    readonly pendingMentionCount: number;
+}
+export interface StatusApplicationData {
+    readonly hardCap: number | null;
+    readonly activeCount: number;
+    readonly doneCount: number;
+    readonly participants: readonly ParticipantSummary[];
+    readonly now: number;
+    readonly throttlePerMinute?: number;
+    readonly hold: {
+        readonly by?: string;
+        readonly reason?: string;
+        readonly at?: number;
+    } | null;
+    readonly latestActivity?: Activity;
+}
+export interface ParticipantsApplicationData {
+    readonly participants: readonly ParticipantSummary[];
+}
+export type DiagnosisApplicationData = DiagnoseResult;
+export type MigrationApplicationData = MigrationOutcome;
+export interface DiscoveryApplicationOptions {
+    readonly depth?: number;
+    readonly limit?: number;
+    readonly after?: string;
+}
+export interface SquareListItem {
+    readonly path: string;
+    readonly lastActiveAt: number;
+    readonly context: readonly string[];
+    readonly participants: readonly string[];
+    readonly activities: number;
+}
+export interface DiscoveryApplicationData {
+    readonly items: readonly SquareListItem[];
+    readonly stopped: boolean;
+    /** All discovered squares before applying the cursor or page limit. */
+    readonly total: number;
+    readonly remaining: number;
+    readonly next?: string;
+}
+export interface DiscoveryProjection {
+    readonly cwd: string;
+    readonly now: number;
+    readonly depth: number;
+    readonly limit: number;
+}
+export interface InboxApplicationOptions {
+    readonly limit?: number;
+}
+export interface InboxMembershipSummary {
+    readonly name: string;
+    readonly squarePath: string;
+    readonly pending: number;
+}
+export interface InboxApplicationData {
+    readonly rows: readonly InboxMembershipSummary[];
+    readonly total: number;
+}
+export interface InboxProjection {
+    readonly sessionId: string;
+    readonly now: number;
+    readonly limit: number;
+}
+export interface RecoveryApplicationData {
+    readonly participant?: string;
+    readonly standingCount?: number;
+    readonly held?: boolean;
+    readonly holdReason?: string;
+    readonly ownActivityCount?: number;
+    readonly hardCap?: number | null;
+    readonly roster?: readonly string[];
+    readonly activitySummaries?: readonly UnreadActivitySummary[];
+}
+export type RecoveryProjection = RecoveryApplicationData & Partial<SquareContextProjection>;
+export type StreamStart = {
+    readonly kind: 'tail';
+    readonly last: number;
+} | {
+    readonly kind: 'after';
+    readonly after: number;
+};
+export interface StreamApplicationOptions {
+    readonly recipient?: string;
+    readonly start?: StreamStart;
+}
+export type StreamApplicationRecord = ArchiveRecord & {
+    readonly seq: number;
+    readonly square: string;
+    readonly route?: string;
+};
+export interface UnreadActivityPreview {
+    readonly number: number;
+    readonly act: Extract<ArchiveRecord, {
+        kind: 'say';
+    }>;
+    readonly perception: Perception;
+}
+export interface UnreadActivitySummary {
+    readonly name: string;
+    readonly count: number;
+    readonly latestActivityAgeMs: number;
+    readonly previews: readonly UnreadActivityPreview[];
+}
+/** Selected-row observations. participantCount in these existing concern DTOs is a standing count. */
+export interface RecoveryObservation {
+    readonly name: string;
+    readonly roster: readonly string[];
+    readonly activitySummaries: readonly UnreadActivitySummary[];
+    readonly participantCount: number;
+    readonly held: boolean;
+    readonly holdReason?: string;
+    readonly ownActivityCount: number;
+    readonly hardCap: number | null;
+}
+export interface EntryPresentation {
+    readonly joined: boolean;
+    readonly joinedBefore: boolean;
+    readonly scene: string;
+    readonly context: string;
+    readonly joinContext: string;
+    readonly recentActivities: readonly ArchiveRecord[];
+    readonly perceptions: Readonly<Record<number, Perception>>;
+    readonly sayNumbers: Readonly<Record<number, number>>;
+    readonly participantCount: number;
+    readonly held: boolean;
+}
+export interface HistoryContinuation {
+    readonly direction: 'before' | 'after';
+    readonly cursor: ActivityId;
+    readonly limit: number;
+}
+export interface ListPresentation {
+    readonly context: readonly string[];
+    readonly participants: readonly string[];
+    readonly activities: number;
+}
+export interface PresenceClassification {
+    /** Names in canonical data, watching first, then recent signs of life; no presentation clipping. */
+    readonly orderedHereNames: readonly string[];
+    readonly lingeringCount: number;
+    readonly classificationByName: Readonly<Record<string, 'here' | 'lingering' | 'done' | 'not-joined'>>;
+}
+export interface CatchPresence {
+    readonly participants: readonly ParticipantSummary[];
+    readonly now: number;
+}
+export interface StreamProjection {
+    readonly activities: readonly {
+        readonly activity: ArchiveRecord;
+        readonly route?: string;
+    }[];
+    readonly cursor: number;
+    readonly hasMore: boolean;
+}
+export interface EntryProjection extends SquareContextProjection, EntryPresentation {
+}
+export interface ExpressionObservation extends Pick<SquareContextProjection, 'standingCount' | 'held' | 'now'> {
+    readonly ownActivityCount: number;
+    readonly hardCap: number | null;
+}
+export interface ExpressProjection extends SquareContextProjection, ExpressionObservation {
+    readonly participant: string;
+    readonly pendingPublic: readonly ArchiveRecord[];
+    readonly sayNumbers: Readonly<Record<number, number>>;
+    readonly perceptions: Readonly<Record<number, Perception>>;
+    readonly reentry?: Activity;
+    readonly delivery?: DeliveryResult;
+}
+export interface CatchProjection extends SquareContextProjection, ExpressionObservation {
+    readonly participant: string;
+    readonly sayNumbers: Readonly<Record<number, number>>;
+    /** Optional nearby presence is not a commit-time selection fact. */
+    readonly presence?: CatchPresence;
+    readonly stop?: CatchStopStatus;
+    readonly waitStarted?: boolean;
+    readonly replaced?: boolean;
+    readonly enrichmentUnavailable?: true;
+}
+export interface HistoryProjection extends SquareContextProjection {
+    readonly activities: readonly ArchiveRecord[];
+    readonly sayNumbers: Readonly<Record<number, number>>;
+    readonly presenceAnchors: Readonly<Record<number, readonly string[]>>;
+    readonly totalMatches: number;
+    /** Ordinary terminal history visibility and stable continuation are owner policy. */
+    readonly visibleActivities: readonly ArchiveRecord[];
+    readonly continuation?: HistoryContinuation;
+}
+export interface ListenerProjection extends SquareContextProjection {
+    readonly participant: string;
+    readonly target: string;
+    readonly requestedTarget: string;
+}
+export interface EventPresentation {
+    readonly activity: ArchiveRecord;
+    readonly participantCount: number;
+    readonly held: boolean;
+}
+export interface LifecycleProjection extends SquareContextProjection, EventPresentation {
+    readonly delivery?: DeliveryResult;
+}
+export interface StatusProjection extends SquareContextProjection, PresenceClassification {
+    /** Full roster size, including never-joined names omitted from status data. */
+    readonly knownParticipantCount: number;
+    readonly latestActNumber?: number;
+    readonly latestPerception?: Perception;
+    readonly joins: readonly {
+        readonly activity: ArchiveRecord;
+        readonly rejoined: boolean;
+    }[];
+    readonly joinCount: number;
+    readonly attentionNames: readonly string[];
+    readonly viewer: string;
+}
+export interface ParticipantsProjection extends SquareContextProjection, PresenceClassification {
+}
+export interface SquareApplication {
+    now(): number;
+    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection>>;
+    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection>>;
+    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection>>;
+    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection>>;
+    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection>>;
+    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
+    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection>>;
+    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection>>;
+    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
+    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
+    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection>>;
+    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection>>;
+    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection>>;
+    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>>>;
+    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>>>;
+    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection>>;
+    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection>>;
+    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection>>;
+    stream(options: StreamApplicationOptions, control?: OperationControl): AsyncIterable<StreamApplicationRecord>;
+}
+export type JoinApplicationResult = JoinApplicationData;
+export type ExpressApplicationResult = ExpressApplicationData;
+export type ApplicationStatus = StatusApplicationData;
+export type ApplicationStatusProjection = StatusProjection;
+export type ApplicationParticipants = ParticipantsApplicationData;

package/dist/square-migration.d.ts

@@ -0,0 +1,24 @@
+import { type SquareState } from './square-sqlite.js';
+/** Validate persisted v1 JSON; row codecs share activity and lease acceptance. */
+export declare function validateSquareState(value: unknown): SquareState;
+export interface MigrationCounts {
+    readonly activities: number;
+    readonly receipts: number;
+    readonly leases: number;
+    readonly routes: number;
+}
+export interface MigrationOutcome {
+    readonly status: 'migrated' | 'already-format-2';
+    /** Participants standing after the conversion, for the CLI header. */
+    readonly standing: number;
+    readonly counts?: MigrationCounts;
+}
+/**
+ * Explicit in-place conversion of a normally persisted version 1 artifact.
+ *
+ * The legacy snapshot is read, validated and written here and nowhere else in
+ * production; the row schema, codec and landing transition come from the driver.
+ * One transaction: preflight framing, the same recheck under the lock, the
+ * preserved authority, the derived facts, the format flip and a single COMMIT.
+ */
+export declare function migrateSquareFile(location: string, signal?: AbortSignal): Promise<MigrationOutcome>;

package/dist/square-migration.js

@@ -0,0 +1,211 @@
+import { inSqliteTransaction, openExistingSquareDatabase } from './artifact.js';
+import { canonicalPath } from './canonical-path.js';
+import { isWakeRouteKind } from './model.js';
+import { parseActivityId } from './square-core.js';
+import { APPLICATION_ID, V1_SNAPSHOT_TABLE, createSqliteDriver, initializeSqlite, invalidArtifact, validateLegacyFraming, validateSqliteHeader, validateStoredActivity, validateWatchLease, } from './square-sqlite.js';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => allowed.has(key));
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function validateRecord(value, item) {
+    return isObject(value) && Object.entries(value).every(([key, candidate]) => key.length > 0 && item(candidate));
+}
+function validateRuntime(value) {
+    return isObject(value) && hasExactKeys(value, ['nextActIndex', 'observations', 'leases'])
+        && isNonNegativeInteger(value.nextActIndex)
+        && validateRecord(value.observations, (candidate) => isObject(candidate)
+            && 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);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+}
+function validateAssignedRuntimeReferences(runtime) {
+    for (const observations of Object.values(runtime.observations)) {
+        for (const id of Object.keys(observations)) {
+            const index = parseActivityId(id);
+            if (index === undefined)
+                return 'malformed';
+            if (index >= runtime.nextActIndex)
+                return 'future';
+        }
+    }
+    return 'ok';
+}
+function validateActs(value) {
+    if (!Array.isArray(value))
+        return false;
+    let previous = -1;
+    try {
+        for (const candidate of value) {
+            const act = validateStoredActivity(candidate);
+            if (act.index <= previous)
+                return false;
+            previous = act.index;
+        }
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function nonFiniteRoutePath(value, path) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? undefined : path;
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            const found = nonFiniteRoutePath(value[index], `${path}[${index}]`);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    if (isObject(value)) {
+        for (const [key, item] of Object.entries(value)) {
+            const found = nonFiniteRoutePath(item, `${path}.${key}`);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+/** Refuse exponent overflow with its legacy path before JSON could coerce it. */
+function assertFiniteRouteNumbers(routes) {
+    for (let index = 0; index < routes.length; index += 1) {
+        const found = nonFiniteRoutePath(routes[index], `routes[${index}]`);
+        if (found !== undefined)
+            throw invalidArtifact(`${found} is not a finite number.`);
+    }
+}
+/** Validate persisted v1 JSON; row codecs share activity and lease acceptance. */
+export function validateSquareState(value) {
+    if (isObject(value) && Array.isArray(value.routes))
+        assertFiniteRouteNumbers(value.routes);
+    if (!isObject(value) || !hasExactKeys(value, ['hardCap', 'preamble', 'warmup', 'acts', 'runtime'], ['throttlePerMinute', 'routes'])
+        || !(value.hardCap === null || (Number.isSafeInteger(value.hardCap) && value.hardCap > 0))
+        || (value.throttlePerMinute !== undefined && (!Number.isSafeInteger(value.throttlePerMinute) || value.throttlePerMinute <= 0))
+        || !isStringArray(value.preamble) || !isStringArray(value.warmup) || !validateActs(value.acts)
+        || (value.routes !== undefined && (!Array.isArray(value.routes) || !value.routes.every((route) => isObject(route) && isWakeRouteKind(route.kind)
+            && typeof route.location === 'string' && typeof route.participant === 'string' && typeof route.sessionId === 'string'
+            && typeof route.channel === 'string' && isObject(route.address) && Object.values(route.address).every((item) => typeof item === 'string')
+            && typeof route.updatedAt === 'number')))
+        || !validateRuntime(value.runtime))
+        throw invalidArtifact('snapshot schema is malformed.');
+    const historyBoundary = value.acts.at(-1)?.index ?? -1;
+    if (value.runtime.nextActIndex <= historyBoundary)
+        throw invalidArtifact('nextActIndex is behind the activity history.');
+    const references = validateAssignedRuntimeReferences(value.runtime);
+    if (references === 'malformed')
+        throw invalidArtifact('snapshot schema is malformed.');
+    if (references === 'future')
+        throw invalidArtifact('runtime references an unassigned activity index.');
+    return value;
+}
+function identity(database) {
+    const row = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
+    return { applicationId: row.application_id, userVersion: row.user_version };
+}
+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,
+    };
+}
+/**
+ * Explicit in-place conversion of a normally persisted version 1 artifact.
+ *
+ * The legacy snapshot is read, validated and written here and nowhere else in
+ * production; the row schema, codec and landing transition come from the driver.
+ * One transaction: preflight framing, the same recheck under the lock, the
+ * preserved authority, the derived facts, the format flip and a single COMMIT.
+ */
+export async function migrateSquareFile(location, signal) {
+    const squarePath = await canonicalPath(location);
+    const database = openExistingSquareDatabase(squarePath);
+    try {
+        // Owned framing, read-only, before any pragma or DDL touches the artifact.
+        // Every preflight statement reads one snapshot taken in the helper's
+        // retryable stage: a transient writer lock is waited out like any other
+        // acquisition, and a migrator that commits while we look cannot move the
+        // artifact between the identity read and the schema reads.
+        let alreadyConverted;
+        const preflight = await inSqliteTransaction(database, false, () => {
+            const before = identity(database);
+            if (before.applicationId === APPLICATION_ID && before.userVersion === 1) {
+                validateLegacyFraming(database, APPLICATION_ID, squarePath);
+                return;
+            }
+            // A row artifact means another migrator finished here; anything else is
+            // refused by the row header itself.
+            validateSqliteHeader(database, squarePath);
+            alreadyConverted = { status: 'already-format-2', standing: standing(database) };
+        }, () => alreadyConverted, signal);
+        if (preflight !== undefined)
+            return preflight;
+        database.exec('PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL');
+        const result = {};
+        await inSqliteTransaction(database, true, () => {
+            // Another migration may have finished between preflight and this lock.
+            const locked = identity(database);
+            if (locked.applicationId !== APPLICATION_ID || locked.userVersion !== 1) {
+                // A valid row artifact is done already; anything else is refused here.
+                validateSqliteHeader(database, squarePath);
+                return;
+            }
+            validateLegacyFraming(database, APPLICATION_ID, squarePath);
+            result.converted = true;
+        }, () => {
+            if (result.converted !== true)
+                return;
+            const legacy = decodeLegacySnapshot(database);
+            initializeSqlite(database, legacy.state, legacy.revision);
+            database.exec(`DROP TABLE ${V1_SNAPSHOT_TABLE}; PRAGMA user_version = 2`);
+            result.outcome = { status: 'migrated', standing: standing(database), counts: counts(legacy.state) };
+        }, signal);
+        return result.outcome ?? { status: 'already-format-2', standing: standing(database) };
+    }
+    finally {
+        database.close();
+    }
+}