@astrosheep/square 0.3.85 → 0.3.87

package/dist/square-domain.js

@@ -1,4 +1,4 @@
-import { SquareError, sameName } from './model.js';
+import { SquareError, formatActivityId, parseActivityId, sameBody, sameName, validateBody, validateName } from './model.js';
 /** The single landing transition, shared by both adapters and explicit rebuild. */
 export function deriveLanding(activity, facts) {
     const audience = [];
@@ -64,18 +64,174 @@ export function landingFacts(read, activity) {
         replyAuthor: activity.kind === 'say' && activity.reply !== undefined ? read.activity(activity.reply)?.actor : undefined,
     };
 }
-/** Driver-owned methods validate rows/writes and track changes; the domain owns allocation. */
-export function wrapSquareWrite(read, writes) {
+function validateGeneration(value) {
+    if (typeof value !== 'string' || parseActivityId(value) === undefined)
+        throw new SquareError('invalid_args', 'Artifact authority requires a valid join generation.');
+}
+/** The artifact transaction supplies one captured authority; every mutation checks it here. */
+export function wrapSquareWrite(read, writes, authority) {
+    if (authority === undefined || typeof authority !== 'object' || authority === null)
+        throw new SquareError('invalid_args', 'Artifact writes require an explicit authority.');
     const { applyLanding, ...mutations } = writes;
-    return Object.assign({}, read, mutations, {
+    const expectedName = authority.kind === 'participant' ? authority.seat?.participant : authority.participant;
+    if (!['participant', 'join', 'takeover'].includes(authority.kind) || typeof expectedName !== 'string')
+        throw new SquareError('invalid_args', 'Artifact write authority is malformed.');
+    validateName(expectedName);
+    if (authority.kind === 'participant') {
+        validateBody(authority.seat.body);
+        validateGeneration(authority.seat.generation);
+    }
+    else {
+        validateBody(authority.body);
+        if (authority.kind === 'takeover')
+            validateGeneration(authority.expectedGeneration);
+    }
+    const assertSeat = (seat, expected = authority.kind === 'participant' ? authority.seat : undefined) => {
+        if (expected === undefined || !sameName(expected.participant, seat.participant)
+            || seat.generation !== expected.generation || !sameBody(seat.body, expected.body))
+            throw new SquareError('already_joined', 'This write needs the current participant seat.');
+        const current = read.seat(seat.participant);
+        if (current === undefined || !sameBody(current.body, expected.body) || current.generation !== expected.generation)
+            throw new SquareError('already_joined', 'This participant seat has been replaced.');
+    };
+    const assertParticipant = (name, generation) => {
+        if (authority.kind !== 'participant')
+            throw new SquareError('already_joined', 'This write needs the current participant seat.');
+        assertSeat({ ...authority.seat, participant: name, generation: generation === undefined ? authority.seat.generation : generation });
+    };
+    let reconnectSeat;
+    let takeoverPhase = authority.kind === 'takeover' ? 'ready' : undefined;
+    if (authority.kind === 'participant') {
+        assertSeat(authority.seat);
+    }
+    else if (authority.kind === 'join') {
+        const participant = read.participant(expectedName), seat = read.seat(expectedName);
+        if (participant?.joined) {
+            if (seat === undefined || !sameBody(seat.body, authority.body))
+                throw new SquareError('already_joined', `${expectedName} is held by another body; take it over explicitly`);
+            reconnectSeat = seat;
+        }
+    }
+    else {
+        const current = read.seat(expectedName);
+        if (current === undefined || current.generation !== authority.expectedGeneration)
+            throw new SquareError('already_joined', 'The participant seat changed before takeover.');
+    }
+    let lastActivity;
+    const facts = Object.assign({}, read, {
         land(activity) {
+            const actor = 'actor' in activity ? activity.actor : undefined;
+            if (actor === undefined)
+                throw new SquareError('invalid_args', 'Participant activities require a named actor.');
+            validateName(actor);
+            if (!sameName(actor, expectedName))
+                throw new SquareError('already_joined', 'Activity actor does not match the artifact authority.');
+            if (authority.kind === 'participant') {
+                assertSeat(authority.seat);
+                if (activity.kind === 'join')
+                    throw new SquareError('invalid_args', 'A participant seat can only be re-established by join.');
+            }
+            else if (authority.kind === 'join') {
+                if (activity.kind !== 'join')
+                    throw new SquareError('invalid_args', 'A new seat must be established by its join activity.');
+                if (read.participant(expectedName)?.joined)
+                    throw new SquareError('already_joined', `${expectedName} is already standing; join cannot replace an existing seat.`);
+            }
+            else if (takeoverPhase === 'ready') {
+                const current = read.seat(expectedName);
+                if (activity.kind !== 'done' || current === undefined || current.generation !== authority.expectedGeneration)
+                    throw new SquareError('already_joined', 'Takeover must first complete the captured participant.');
+            }
+            else if (authority.kind === 'takeover' && takeoverPhase === 'done') {
+                if (activity.kind !== 'join' || !read.participant(expectedName)?.done)
+                    throw new SquareError('already_joined', 'Takeover must join after its captured done activity.');
+            }
+            else {
+                throw new SquareError('invalid_args', 'Takeover permits only one done followed by one join.');
+            }
             const index = read.header().nextActIndex;
-            if (!Number.isSafeInteger(index) || index < 0 || index >= Number.MAX_SAFE_INTEGER) {
+            if (!Number.isSafeInteger(index) || index < 0 || index >= Number.MAX_SAFE_INTEGER)
                 throw new SquareError('invalid_args', 'Square activity index is exhausted.');
-            }
+            const captured = authority.kind === 'takeover' && activity.kind === 'done'
+                ? read.seat(expectedName) : undefined;
             const stored = { ...activity, index };
             applyLanding(deriveLanding(stored, landingFacts(read, stored)));
-            return read.activity(index);
+            if (stored.kind === 'join') {
+                if (authority.kind === 'participant')
+                    throw new SquareError('invalid_args', 'Participant authority cannot establish a seat.');
+                const seat = {
+                    participant: stored.actor,
+                    body: authority.body,
+                    generation: formatActivityId(stored.index),
+                    ...(authority.wakeAddress === undefined ? {} : { wakeAddress: authority.wakeAddress }),
+                };
+                mutations.storeSeat(seat);
+                const established = read.seat(seat.participant);
+                if (established === undefined || !sameBody(established.body, seat.body) || established.generation !== seat.generation)
+                    throw new SquareError('invalid_args', 'The join activity did not establish its artifact seat.');
+                if (authority.kind === 'takeover')
+                    takeoverPhase = 'joined';
+            }
+            else if (stored.kind === 'done' && authority.kind === 'participant') {
+                if (!mutations.removeSeat(authority.seat))
+                    throw new SquareError('already_joined', 'The participant seat changed while it was being completed.');
+            }
+            else if (stored.kind === 'done' && authority.kind === 'takeover') {
+                if (captured === undefined || !mutations.removeSeat({ participant: expectedName, body: captured.body, generation: captured.generation }))
+                    throw new SquareError('already_joined', 'The participant seat changed while takeover was completing it.');
+                takeoverPhase = 'done';
+            }
+            lastActivity = read.activity(index);
+            return lastActivity;
+        },
+        updateWakeAddress(seat, wakeAddress) {
+            assertSeat(seat, authority.kind === 'join' ? reconnectSeat : undefined);
+            return mutations.updateWakeAddress(seat, wakeAddress);
+        },
+        cancelThrough(seat, through) {
+            assertSeat(seat);
+            if (!Number.isSafeInteger(through) || through < 0 || through > read.header().lastActIndex || read.activity(through) === undefined)
+                throw new SquareError('invalid_args', 'Cancellation boundary must name an existing activity at or below the current head.');
+            return mutations.cancelThrough(seat, through);
+        },
+        markSeen(name, indexes, at) {
+            assertParticipant(name);
+            return mutations.markSeen(name, indexes, at);
+        },
+        putLease(name, lease, generation) {
+            assertParticipant(name, generation);
+            return mutations.putLease(name, lease, generation);
+        },
+        removeLease(name, leaseId, generation) {
+            assertParticipant(name, generation);
+            return mutations.removeLease(name, leaseId, generation);
+        },
+        claimDelivery(input) {
+            assertSeat(input.seat);
+            return mutations.claimDelivery(input);
+        },
+        prepareDelivery(input) {
+            assertSeat(input.seat);
+            return mutations.prepareDelivery(input);
+        },
+        completeDelivery(input) {
+            assertSeat(input.seat);
+            return mutations.completeDelivery(input);
+        },
+        observeNativeDelivery(input) {
+            assertSeat(input.seat);
+            return mutations.observeNativeDelivery(input);
         },
     });
+    return {
+        facts,
+        complete() {
+            if (authority.kind !== 'takeover')
+                return;
+            const seat = read.seat(expectedName);
+            if (takeoverPhase !== 'joined' || lastActivity?.kind !== 'join' || seat === undefined
+                || !sameBody(seat.body, authority.body) || seat.generation !== formatActivityId(lastActivity.index))
+                throw new SquareError('already_joined', 'Takeover did not complete its replacement join.');
+        },
+    };
 }

package/dist/square-facade.d.ts

@@ -1,7 +1,9 @@
+import type { SquareBackends } from './square-backend.js';
 import type { ActivityId, Perception, Reach } from './square-core.js';
-import type { StoredAct } from './model.js';
-import type { HostLedgerPort, WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
+import type { Body, StoredAct, WakeAddress, ActivityMetadata } from './model.js';
+import type { WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
+export type { Body, WakeAddress, ActivityMetadata, JsonValue } from './model.js';
 /** Indexed archive event, including read and historical actorless lifecycle records. */
 export type ArchiveRecord = Readonly<StoredAct>;
 export interface Activity {
@@ -10,6 +12,7 @@ export interface Activity {
     readonly kind: 'join' | 'say' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore' | 'unlisten';
     readonly actor: string;
     readonly body?: string;
+    readonly metadata?: ActivityMetadata;
     readonly mentions: readonly string[];
     readonly reach?: Reach;
     readonly target?: string;
@@ -23,6 +26,7 @@ export interface ObservationOptions {
     readonly observe?: boolean;
 }
 export interface ExpressOptions extends ObservationOptions {
+    readonly metadata?: ActivityMetadata;
     readonly force?: boolean;
     readonly mentions?: readonly string[];
     readonly reach?: Reach;
@@ -30,6 +34,9 @@ export interface ExpressOptions extends ObservationOptions {
     readonly noMention?: boolean;
     readonly noWait?: boolean;
 }
+export interface ExpressInput extends ExpressOptions {
+    readonly body?: string;
+}
 export interface ActivityResult {
     readonly activity: Activity;
     readonly delivery?: DeliveryResult;
@@ -146,9 +153,11 @@ export interface SquareSnapshot {
 }
 export interface OpenOptions {
     readonly clock?: () => number;
-    readonly hostLedger?: HostLedgerPort;
     readonly wakeTransport?: WakeTransportPort;
-    readonly env?: NodeJS.ProcessEnv;
+    /** Explicit execution coordinate resolved by an adapter. */
+    readonly body?: Body;
+    /** Optional wake address attached to this body. */
+    readonly wakeAddress?: WakeAddress;
 }
 export interface SquareLocation {
     readonly path?: string;
@@ -156,6 +165,7 @@ export interface SquareLocation {
     readonly env?: NodeJS.ProcessEnv;
 }
 export interface SquareAtInput extends SquareLocation, OpenOptions {
+    readonly backends?: SquareBackends;
     readonly participant?: string;
     /** A caller-owned connection; closing this Square never closes its owner. */
     readonly resources?: SquareResourceOwner;
@@ -179,13 +189,10 @@ export interface JoinResult {
     readonly participantCount: number;
     readonly observation?: JoinObservation;
 }
-/** Optional fence for owner-scoped lifecycle actions. */
-export interface OwnershipFenceOptions {
-    readonly expectedEpoch?: number;
-}
 export interface Participant {
     readonly name: string;
-    express(body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
+    express(body: string | undefined, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
+    express(input: ExpressInput, control?: OperationControl): Promise<ExpressResult>;
     listen(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     ignore(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     unlisten(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
@@ -354,7 +361,6 @@ export interface ExpressObservation extends SquareObservation, ExpressionObserva
     readonly pendingPublic: readonly ArchiveRecord[];
     readonly sayNumbers: Readonly<Record<number, number>>;
     readonly perceptions: Readonly<Record<number, Perception>>;
-    readonly reentry?: Activity;
 }
 export interface CatchObservation extends SquareObservation, ExpressionObservation {
     readonly participant: string;

package/dist/square-index.d.ts

@@ -0,0 +1,24 @@
+import { type VersionObserver } from './file-changes.js';
+import { type Body } from './model.js';
+/** A rebuildable discovery hint: the body that may have used an artifact and its path.
+ * It is deliberately not a participant, generation, ownership, suppression, or evidence row. */
+export interface SquareIndexEntry {
+    readonly location: string;
+    readonly body: Body;
+}
+export interface SquareIndexQuery {
+    readonly body?: Body;
+    readonly channel?: string;
+    readonly session?: string;
+    readonly agent?: string;
+}
+/** The index is the only host-side Square state. Its path is test/configuration plumbing, not authority. */
+export declare function squareIndexPath(env?: NodeJS.ProcessEnv): string;
+/** Read and verify the disposable index. Paths are canonicalized on access and duplicates collapse. */
+export declare function indexedSquareEntries(query?: SquareIndexQuery, env?: NodeJS.ProcessEnv): Promise<readonly SquareIndexEntry[]>;
+export declare function indexedSquarePaths(query?: SquareIndexQuery, env?: NodeJS.ProcessEnv): Promise<readonly string[]>;
+/** Best-effort discovery only: a busy index skips publication, never queues or delays artifact work. */
+export declare function rememberSquarePath(location: string, body: Body, index: string): Promise<boolean>;
+/** Index loss is tolerated by every caller; this observer is only a wake hint for rediscovery. */
+export declare function observeSquareIndex(env?: NodeJS.ProcessEnv): Promise<VersionObserver<string>>;
+export declare function bodyKey(body: Body): string;

package/dist/square-index.js

@@ -0,0 +1,131 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { withFileLock } from './file-lock.js';
+import { canonicalPath } from './canonical-path.js';
+import { observeFileMetadata } from './file-changes.js';
+import { sameBody, validateBody } from './model.js';
+/** The index is the only host-side Square state. Its path is test/configuration plumbing, not authority. */
+export function squareIndexPath(env = process.env) {
+    const configured = env.SQUARE_INDEX?.trim();
+    return path.resolve(configured ?? path.join(os.homedir(), '.square', 'index.ndjsonl'));
+}
+function lockPath(index) {
+    return `${index}.lock`;
+}
+function validEntry(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const row = value;
+    if (typeof row.location !== 'string' || !path.isAbsolute(row.location)
+        || row.body === null || typeof row.body !== 'object' || Array.isArray(row.body))
+        return undefined;
+    const raw = row.body;
+    const body = {
+        channel: raw.channel,
+        session: raw.session,
+        ...(raw.agent === undefined ? {} : { agent: raw.agent }),
+    };
+    try {
+        validateBody(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (Object.keys(raw).some((key) => !['channel', 'session', 'agent'].includes(key)))
+        return undefined;
+    return { location: row.location, body };
+}
+async function readEntries(index) {
+    let content;
+    try {
+        content = await fs.readFile(index, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const entries = [];
+    for (const line of content.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const entry = validEntry(JSON.parse(line));
+            if (entry !== undefined)
+                entries.push(entry);
+        }
+        catch {
+            // The index is disposable discovery input. A malformed line is ignored rather than
+            // becoming a second authority or preventing access to valid entries beside it.
+        }
+    }
+    return entries;
+}
+function matches(entry, query) {
+    if (query.body !== undefined && !sameBody(entry.body, query.body))
+        return false;
+    if (query.channel !== undefined && entry.body.channel !== query.channel)
+        return false;
+    if (query.session !== undefined && entry.body.session !== query.session)
+        return false;
+    if (query.agent !== undefined && entry.body.agent !== query.agent)
+        return false;
+    return true;
+}
+/** Read and verify the disposable index. Paths are canonicalized on access and duplicates collapse. */
+export async function indexedSquareEntries(query = {}, env = process.env) {
+    const entries = await readEntries(squareIndexPath(env));
+    const result = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!matches(entry, query))
+            continue;
+        let location;
+        try {
+            location = await canonicalPath(entry.location);
+        }
+        catch {
+            continue;
+        }
+        const key = JSON.stringify([location, entry.body.channel, entry.body.session, entry.body.agent ?? null]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push({ location, body: entry.body });
+    }
+    return result;
+}
+export async function indexedSquarePaths(query = {}, env = process.env) {
+    return [...new Set((await indexedSquareEntries(query, env)).map((entry) => entry.location))];
+}
+/** Best-effort discovery only: a busy index skips publication, never queues or delays artifact work. */
+export async function rememberSquarePath(location, body, index) {
+    validateBody(body);
+    const canonical = await canonicalPath(location);
+    await fs.mkdir(path.dirname(index), { recursive: true });
+    return await withFileLock(lockPath(index), { retryMs: 10, skipIfBusy: true }, async () => {
+        const entries = await readEntries(index);
+        if (entries.some((entry) => entry.location === canonical && sameBody(entry.body, body)))
+            return false;
+        const next = [...entries, { location: canonical, body }];
+        const temporary = `${index}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await fs.writeFile(temporary, next.map((entry) => JSON.stringify(entry)).join('\n') + '\n', { flag: 'wx', mode: 0o600 });
+            await fs.rename(temporary, index);
+        }
+        finally {
+            await fs.rm(temporary, { force: true });
+        }
+        return true;
+    }) ?? false;
+}
+/** Index loss is tolerated by every caller; this observer is only a wake hint for rediscovery. */
+export function observeSquareIndex(env = process.env) {
+    return observeFileMetadata(squareIndexPath(env));
+}
+export function bodyKey(body) {
+    validateBody(body);
+    return JSON.stringify([body.channel, body.session, body.agent ?? null]);
+}

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

@@ -0,0 +1,9 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare const FORMAT4_ADDED_OBJECTS: ReadonlySet<string>;
+export declare const FORMAT4_REPLACED_OBJECTS: ReadonlySet<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
+ * contents (including legacy routes), changes pragmas, or performs DDL.
+ */
+export declare function legacyRowFramingIssue(database: DatabaseSync, applicationId: number, version: 2 | 3, location: string, currentSchemaSql: string): string | undefined;

package/dist/square-legacy-framing.js

@@ -0,0 +1,56 @@
+export const FORMAT4_ADDED_OBJECTS = new Set([
+    'seats', 'seat_body', 'delivery_evidence', 'delivery_claim_token', 'delivery_activity', 'delivery_cancellations',
+]);
+export const FORMAT4_REPLACED_OBJECTS = new Set(['routes', 'route_participant', 'route_session']);
+const LEGACY_ROUTES_SQL = `CREATE TABLE routes (
+  position INTEGER PRIMARY KEY CHECK (position >= 0),
+  participant_key_json TEXT COLLATE BINARY NOT NULL,
+  session_json TEXT COLLATE BINARY NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','claude-native','paseo')),
+  updated_at REAL NOT NULL,
+  payload_json TEXT NOT NULL CHECK (json_valid(payload_json))
+);
+CREATE INDEX route_participant ON routes(participant_key_json, position);
+CREATE INDEX route_session ON routes(session_json, position);`;
+function normalizedSql(sql) {
+    return sql.trim().replace(/;$/, '').replace(/\s+/g, ' ').replace(/\s*([(),=])\s*/g, '$1');
+}
+function legacyRowSchema(currentSchemaSql, version) {
+    const statements = currentSchemaSql.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_ADDED_OBJECTS.has(match[1]) && !FORMAT4_REPLACED_OBJECTS.has(match[1]);
+    });
+    const legacyStatements = statements.join(';\n')
+        .replace('  delivery_revision INTEGER NOT NULL CHECK (delivery_revision BETWEEN 0 AND 9007199254740991),\n', '')
+        .replace('  generation_json TEXT NOT NULL DEFAULT \'""\',\n', '');
+    const allStatements = [...legacyStatements.split(';').map((statement) => statement.trim()).filter(Boolean),
+        ...LEGACY_ROUTES_SQL.split(';').map((statement) => statement.trim()).filter(Boolean)];
+    let schema = allStatements.join(';\n');
+    if (version === 2) {
+        schema = schema.replace("kind IN ('join','done','say','hold','resume','read','listen','ignore','unlisten')", "kind IN ('join','done','say','hold','resume','read','listen','ignore')");
+    }
+    return schema.split(';').map((statement) => normalizedSql(statement)).filter(Boolean).sort();
+}
+/**
+ * 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
+ * contents (including legacy routes), changes pragmas, or performs DDL.
+ */
+export function legacyRowFramingIssue(database, applicationId, version, location, currentSchemaSql) {
+    const identity = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
+    if (identity.application_id !== applicationId)
+        return 'unrelated SQLite database.';
+    if (identity.user_version !== version)
+        return '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 = legacyRowSchema(currentSchemaSql, version);
+    if (actual.length !== expected.length || actual.some((sql, index) => sql !== expected[index]))
+        return 'unsupported row schema.';
+    const journalMode = database.prepare('PRAGMA journal_mode').get().journal_mode;
+    if (journalMode !== (location === ':memory:' ? 'memory' : 'delete'))
+        return 'unsupported journal mode.';
+    return undefined;
+}

package/dist/square-location.d.ts

@@ -0,0 +1,15 @@
+import type { SquareAtInput, SquareLocation } from './square-facade.js';
+import type { SquareBackends } from './square-backend.js';
+export type ParsedSquareLocation = {
+    readonly kind: 'local';
+    readonly path: string;
+} | {
+    readonly kind: 'stdio';
+    readonly backend: string;
+    readonly key: string;
+    readonly uri: string;
+};
+export declare function parseSquareLocation(value: string): ParsedSquareLocation;
+export declare function squareLocation(input: SquareLocation): string;
+export declare function localSquareLocation(input: SquareLocation): string;
+export declare function backendConfiguration(input: SquareAtInput): Promise<SquareBackends>;

package/dist/square-location.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import os from 'node:os';
+import { readFile } from 'node:fs/promises';
+import { SquareError } from './model.js';
+export function parseSquareLocation(value) {
+    if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value))
+        return { kind: 'local', path: value };
+    // Parse the raw components, before URL dot-segment normalization or host lowercasing.
+    const match = /^stdio:\/\/([A-Za-z0-9_-]+)\/([^/?#]+)$/.exec(value);
+    if (!match)
+        throw new SquareError('invalid_args', 'Expected a local path or stdio://<configured-name>/<encoded-square-key>; no credentials, port, query or fragment');
+    let key;
+    try {
+        key = decodeURIComponent(match[2]);
+    }
+    catch {
+        throw new SquareError('invalid_args', 'Invalid percent encoding in stdio square key');
+    }
+    if (!key || key === '.' || key === '..' || /[/\\\x00-\x1f\x7f]/.test(key))
+        throw new SquareError('invalid_args', 'A stdio square key must be one nonempty name, not a path');
+    return { kind: 'stdio', backend: match[1], key, uri: `stdio://${match[1]}/${encodeURIComponent(key)}` };
+}
+export function squareLocation(input) {
+    const selected = input.path ?? (input.env ?? process.env).SQUARE_LOCATION;
+    if (selected === undefined || selected.trim() === '')
+        throw new SquareError('invalid_args', 'Square needs a location');
+    const location = parseSquareLocation(selected);
+    return location.kind === 'local' ? path.resolve(input.cwd ?? process.cwd(), location.path) : location.uri;
+}
+export function localSquareLocation(input) {
+    const location = squareLocation(input);
+    if (parseSquareLocation(location).kind !== 'local')
+        throw new SquareError('invalid_args', 'This file operation requires a local square artifact; backend URIs are not supported');
+    return location;
+}
+function validateBackends(value) {
+    const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+    const invalid = () => new SquareError('invalid_args', 'Invalid backend configuration: expected {backends:{name:{command,args?,cwd?,env?}}}');
+    if (!object(value))
+        throw invalid();
+    for (const [name, entry] of Object.entries(value)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(name) || !object(entry) || typeof entry.command !== 'string' || !entry.command.trim()
+            || Object.keys(entry).some(key => !['command', 'args', 'cwd', 'env'].includes(key))
+            || (entry.args !== undefined && (!Array.isArray(entry.args) || entry.args.some(arg => typeof arg !== 'string')))
+            || (entry.cwd !== undefined && typeof entry.cwd !== 'string')
+            || (entry.env !== undefined && (!object(entry.env) || Object.values(entry.env).some(v => typeof v !== 'string'))))
+            throw invalid();
+    }
+    return value;
+}
+export async function backendConfiguration(input) {
+    if (input.backends !== undefined)
+        return validateBackends(input.backends);
+    const env = input.env ?? process.env;
+    const configured = env.SQUARE_BACKENDS_CONFIG;
+    const file = configured === undefined ? path.join(env.HOME ?? os.homedir(), '.config/square/backends.json')
+        : path.resolve(input.cwd ?? process.cwd(), configured);
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (configured === undefined && error.code === 'ENOENT')
+            return {};
+        throw new SquareError('invalid_args', 'Cannot read backend configuration; check SQUARE_BACKENDS_CONFIG');
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object' || Object.keys(parsed).some(key => key !== 'backends') || parsed.backends === undefined)
+            throw new Error();
+        return validateBackends(parsed.backends);
+    }
+    catch {
+        throw new SquareError('invalid_args', 'Invalid backend configuration; expected {backends:{name:{command,args?,cwd?,env?}}}');
+    }
+}

package/dist/square-migration-host-ledger.d.ts

@@ -0,0 +1,26 @@
+import { type Body } from './model.js';
+/** Offline conversion input only; never a runtime ownership or evidence reader. */
+export interface LegacyOwner {
+    readonly participant: string;
+    readonly body: Body;
+}
+export interface LegacyHostData {
+    readonly owners: readonly LegacyOwner[];
+    readonly evidence: readonly LegacyDeliveryEvidence[];
+}
+export interface LegacyDeliveryEvidence {
+    readonly v: 1;
+    readonly location: string;
+    readonly participant: string;
+    readonly session: string;
+    readonly activity: string;
+    readonly kind: 'wake' | 'presentation' | 'lifecycle';
+    readonly outcome: string;
+    readonly at?: number;
+    readonly expiresAt?: number;
+    readonly attemptN?: number;
+    readonly claimToken?: string;
+    readonly [key: string]: unknown;
+}
+/** One frozen snapshot, latest owners only; no age, expiry, or ownership history inference. */
+export declare function readLegacyHostData(location: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<LegacyHostData>;