@astrosheep/square 0.3.84 → 0.3.86

package/dist/square-api.js

@@ -1,474 +1,27 @@
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { setTimeout as sleep } from 'node:timers/promises';
-import { SquareError, isSquareError, nameKey, validateName } from './model.js';
-import { resolveKnownName, validateDoneBody } from './decisions.js';
-import { HELD_WAIT_BUDGET_MS, WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
-import { catchLimit, observeCatchSelection } from './catch-decisions.js';
-import { directedSuffix } from './activity-feed.js';
-import { expressHint } from './hints.js';
-import { assertLiveOwner } from './participant-host.js';
-import { buildMemorySquare, openSquare, closeOpenSquare } from './open-square.js';
-import { catchUp, done, endOwnedSession, express, hold, ignore, implicitJoin, join, takeover, listen, listening, unlisten, resume, retireEndedSessionRoutes } from './square-actions.js';
-import { recoveryObservation, currentParticipant, entryPresentation, resolveParticipant, snapshot, queryStatus, queryParticipants, catchPresence, toPublicActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
-import { hasAutomaticDeliveryIdentity, hostLedgerForEnv, localParticipantName, localSessionIdentities, presenceEpoch, readParticipantOwner } from './registry.js';
-import { projectSessionBindings } from './square-projections.js';
-import { sessionIdsFromEnvironment } from './participant-identity.js';
-import { createDefaultWakeTransport } from './notifications.js';
-import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
-import { createSquare, diagnoseSquareFile } from './artifact.js';
-import { migrateSquareFile } from './square-migration.js';
-import { discoverSquares } from './list.js';
-import { streamSquare } from './stream.js';
-export { createSquareResourceOwner } from './open-square.js';
-export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
-export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
-export { HELD_WAIT_BUDGET_MS } from './runtime.js';
-export { HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
-export { DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './list.js';
-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');
-    return path.resolve(input.cwd ?? process.cwd(), selected);
-}
-function checkControl(control) {
-    if (control?.signal?.aborted)
-        throw control.signal.reason ?? new Error('Square operation was cancelled');
-}
-export function squareClock(env, clock) {
-    if (clock !== undefined)
-        return clock;
-    if (env.SQUARE_NOW_MS === undefined)
-        return Date.now;
-    return () => {
-        const value = Number.parseInt(env.SQUARE_NOW_MS, 10);
-        if (!Number.isFinite(value))
-            throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
-        return value;
-    };
-}
-function failure(error, detail) {
-    const normalized = error instanceof Error ? error : new Error(String(error), { cause: error });
-    Object.assign(normalized, { operation: detail });
-    return normalized;
-}
-function defaultTransport(square) {
-    let transport;
-    return () => transport ??= square.wakeTransport !== undefined ? Promise.resolve(square.wakeTransport)
-        : square.location === 'memory' || square.hostLedger === undefined ? Promise.resolve(undefined)
-            : createDefaultWakeTransport(square.hostLedger, square.clock, square.env).catch(() => undefined);
-}
-function observedContext(square, standingCount, held, participant, now = square.clock()) {
-    return { location: square.location, standingCount, held, now,
-        ...(participant === undefined ? {} : { participant }), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(square.env) };
-}
-async function contextObservation(square, participant, control) {
-    const observation = (await square.artifact.read((facts) => ({ standingCount: inSquareCount(facts), held: facts.hold().active }), control?.signal)).value;
-    return observedContext(square, observation.standingCount, observation.held, participant);
-}
-async function prepareExpression(square, requested, control) {
-    try {
-        checkControl(control);
-        const result = await join(square, requested, control, { requireKnown: true });
-        return { participant: result.name, activity: result.activity };
-    }
-    catch (error) {
-        throw failure(error, { operation: 'express', subject: 'caller', participant: requested, expressEffect: 'unsent' });
-    }
-}
-/** One retry/commit owner for every participant, regardless of transport. */
-async function landExpression(square, name, body, options, transport, control) {
-    let effect = 'unsent';
-    let waited = false, heldWaitedMs = 0;
-    try {
-        const wakeTransport = await transport();
-        while (true) {
-            checkControl(control);
-            try {
-                effect = 'unknown';
-                return { ...await express({ ...square, wakeTransport }, name, body, options, control), waited };
-            }
-            catch (error) {
-                if (isSquareError(error) && error.facts?.activityUnsent === true)
-                    effect = 'unsent';
-                if (!isSquareError(error) || options.noWait || (error.code !== 'held' && error.code !== 'throttled'))
-                    throw error;
-                if (error.code === 'held' && heldWaitedMs >= HELD_WAIT_BUDGET_MS)
-                    throw error;
-                waited = true;
-                control?.onProgress?.({ kind: 'waiting', reason: error.code,
-                    ...(error.code === 'throttled' ? { delayMs: error.facts?.retryAfterMs ?? 1 } : {}),
-                    ...(error.facts?.holder === undefined ? {} : { holder: error.facts.holder }),
-                    ...(error.facts?.holdReason === undefined ? {} : { holdReason: error.facts.holdReason }),
-                });
-                if (error.code === 'throttled')
-                    await sleep(error.facts?.retryAfterMs ?? 1, undefined, { signal: control?.signal });
-                else {
-                    const started = Date.now();
-                    const observation = await square.artifact.read((facts) => facts.hold().active, control?.signal);
-                    if (observation.value)
-                        await square.artifact.changed(observation.version, Math.max(1, HELD_WAIT_BUDGET_MS - heldWaitedMs), control?.signal);
-                    heldWaitedMs += Date.now() - started;
-                }
-            }
-        }
-    }
-    catch (error) {
-        const recipient = isSquareError(error) && ['not_standing', 'bell_mention_conflict'].includes(error.facts?.reason ?? '');
-        throw failure(error, { operation: 'express', participant: name, subject: recipient ? 'recipient' : 'caller', expressEffect: effect });
-    }
-}
-/** Leases, quiet waiting and receipt selection share one lifecycle. */
-async function catchOwned(square, requested, options = {}, control) {
-    let name = requested, subject = 'caller';
-    let leaseId;
-    let waitStarted = false, replaced = false;
-    let selection = options;
-    const idle = options.idle ?? 0;
-    async function complete(caught, stop) {
-        const selected = caught ?? (await square.artifact.read((facts) => observeCatchSelection(facts, name, [], {
-            unseenOnly: true, senders: selection.from, ...(selection.mention === true ? { attentionOnly: true } : {}),
-        }, square.clock()))).value;
-        const terminal = stop === 'empty-now' || stop === undefined ? selected.terminalStatus ?? stop : stop;
-        if (leaseId !== undefined) {
-            await releaseWatchLease(square, name, leaseId).catch(() => undefined);
-            leaseId = undefined;
-        }
-        return { selection: selected, stop: terminal, waitStarted, replaced };
-    }
-    const empty = (stop) => complete(undefined, stop);
-    try {
-        checkControl(control);
-        if (!Number.isFinite(idle) || idle < 0)
-            throw new SquareError('invalid_args', 'Catch idle duration must be a non-negative number');
-        if (options.id !== undefined && ['idle', 'from', 'mention', 'limit', 'replace'].some((key) => Object.hasOwn(options, key)))
-            throw new SquareError('invalid_args', 'Catch id cannot be combined with idle, from, mention, limit or replace');
-        if (Object.hasOwn(options, 'replace') && idle === 0)
-            throw new SquareError('invalid_args', 'Catch replacement requires a positive idle duration');
-        catchLimit(options.limit);
-        const from = (await square.artifact.read((facts) => {
-            name = resolveKnownName(facts, requested);
-            subject = 'filter';
-            return options.from?.map((target) => resolveKnownName(facts, target));
-        }, control?.signal)).value;
-        selection = { ...options, ...(from === undefined ? {} : { from }) };
-        subject = 'caller';
-        if (idle === 0) {
-            const data = await catchUp(square, name, selection, control);
-            return await complete(data, data.activities.length === 0 ? 'empty-now' : undefined);
-        }
-        if (!await assertLiveOwner(square, name))
-            throw new SquareError('already_joined', `${name} already stands here — another session holds the name`);
-        const watch = {
-            ...(from === undefined ? {} : { participants: [...from] }), ...(options.mention ? { mention: name } : {}),
-            ...(options.replace === undefined ? {} : { replace: options.replace }),
-        };
-        const start = await acquireWatchLease(square, name, crypto.randomUUID(), watch, control?.signal);
-        if (start.type === 'active')
-            return await empty('already-active');
-        leaseId = start.leaseId;
-        waitStarted = true;
-        replaced = start.replaced;
-        control?.onProgress?.({ kind: 'catch-started', participant: name, idleMs: idle, replacementRequested: options.replace ?? false, replaced });
-        let quietSince = square.clock(), wasHeld = false, nextHeartbeat = start.heartbeatAt + WATCH_HEARTBEAT_MS;
-        while (true) {
-            checkControl(control);
-            // Capture before evaluation so a commit during selection cannot be missed.
-            const baseline = await square.artifact.revision(control?.signal);
-            const pulse = await pulseWatchLease(square, name, leaseId, watch, square.clock() >= nextHeartbeat, control?.signal);
-            if (pulse.type === 'replaced')
-                return await empty('replaced');
-            if (pulse.type === 'terminal')
-                return await empty(pulse.status);
-            if (pulse.heartbeatAt !== undefined)
-                nextHeartbeat = pulse.heartbeatAt + WATCH_HEARTBEAT_MS;
-            if (pulse.type === 'sleep') {
-                const caught = await catchUp(square, name, selection, control, leaseId);
-                if (caught === null)
-                    return await empty('replaced');
-                if (caught.activities.length > 0)
-                    return await complete(caught);
-            }
-            if (pulse.type === 'held' || wasHeld)
-                quietSince = square.clock();
-            wasHeld = pulse.type === 'held';
-            if (!wasHeld && square.clock() - quietSince >= idle) {
-                const owns = await ownsWatchLease(square, name, leaseId, control?.signal);
-                return await empty(owns ? 'stale' : 'replaced');
-            }
-            const deadline = Math.min(nextHeartbeat, wasHeld ? Infinity : quietSince + idle);
-            await square.artifact.changed(baseline, Math.max(0, deadline - square.clock()), control?.signal);
-        }
-    }
-    catch (error) {
-        throw failure(error, { operation: 'catch', subject, participant: name });
-    }
-    finally {
-        // An aborted request still releases its own lease, never its replacement's.
-        if (leaseId !== undefined)
-            await releaseWatchLease(square, name, leaseId).catch(() => undefined);
-    }
-}
-class ParticipantHandle {
-    name;
-    owner;
-    square;
-    transport;
-    constructor(name, owner, square, transport) {
-        this.name = name;
-        this.owner = owner;
-        this.square = square;
-        this.transport = transport;
-    }
-    async express(body, options = {}, control) {
-        const entry = await prepareExpression(this.square, this.name, control);
-        const name = entry.participant;
-        let result;
-        try {
-            const feed = !options.observe ? undefined : (await this.square.artifact.read((facts) => {
-                const pendingPublic = directedSuffix(facts, name);
-                return { pendingPublic, sayNumbers: facts.sayOrdinals(pendingPublic.map((item) => item.index)),
-                    perceptions: Object.fromEntries(pendingPublic.map((item) => [item.index, 'full'])) };
-            }, control?.signal)).value;
-            result = await landExpression(this.square, name, body, options, this.transport, control);
-            const { observation: committed, ...data } = result;
-            const hint = expressHint(committed.ownActivityCount);
-            return { ...data, ...(hint === undefined ? {} : { hint }), ...(feed === undefined ? {} : { observation: {
-                        ...observedContext(this.square, committed.standingCount, committed.held, name, committed.now), ...committed, ...feed, participant: name,
-                        ...(entry.activity === null ? {} : { reentry: entry.activity }),
-                    } }) };
-        }
-        catch (error) {
-            if (result === undefined && error?.operation?.operation === 'express')
-                throw error;
-            throw failure(error, { operation: 'express', participant: name, subject: 'caller', expressEffect: result === undefined ? 'unsent' : 'landed',
-                ...(result === undefined ? {} : { landedId: result.activity.id }) });
-        }
-    }
-    async listener(verb, target, options, control) {
-        const name = (await resolveParticipant(this.square, this.name, control)).name;
-        const { observation: committed, ...result } = await (verb === 'listen' ? listen : verb === 'ignore' ? ignore : unlisten)(this.square, name, target, control);
-        return { ...result, ...(!options.observe ? {} : { observation: {
-                    ...observedContext(this.square, committed.standingCount, committed.held, name, committed.now),
-                    participant: name, requestedTarget: target, target: result.activity?.target ?? target,
-                } }) };
-    }
-    listen(target, options = {}, control) { return this.listener('listen', target, options, control); }
-    ignore(target, options = {}, control) { return this.listener('ignore', target, options, control); }
-    unlisten(target, options = {}, control) { return this.listener('unlisten', target, options, control); }
-    async listening(options = {}, control) {
-        const name = (await resolveParticipant(this.square, this.name, control)).name;
-        return { listening: await listening(this.square, name, control),
-            ...(!options.observe ? {} : { observation: await contextObservation(this.square, name, control) }) };
-    }
-    async catch(options = {}, control) {
-        const result = await catchOwned(this.square, this.name, options, control), view = result.selection, stop = result.stop;
-        const presence = !options.observe ? undefined : await catchPresence(this.square, control).catch(() => undefined);
-        const status = stop === 'already-active' || stop === 'replaced' || stop === 'capped' || stop === 'quorum' ? stop : undefined;
-        return { activities: view.activities.map((activity) => ({ ...toPublicActivity(activity), perception: 'full' })),
-            consumedThrough: view.consumedThrough, remaining: view.remaining, idleExpired: stop === 'stale',
-            ...(status === undefined ? {} : { status }), ...(view.hint === undefined ? {} : { hint: view.hint }), ...(!options.observe ? {} : { observation: {
-                    ...observedContext(this.square, view.standingCount, view.held, view.participant, view.now), participant: view.participant,
-                    sayNumbers: view.sayNumbers, ownActivityCount: view.ownActivityCount, hardCap: view.hardCap, stop,
-                    ...(presence === undefined ? { enrichmentUnavailable: true } : { presence }), waitStarted: result.waitStarted, replaced: result.replaced,
-                } }) };
-    }
-    history(query, control) { return this.owner.history(query, control); }
-    async lifecycle(verb, body, options, control) {
-        if (verb === 'done')
-            validateDoneBody(body);
-        const identity = localSessionIdentities(this.square.env ?? {})[0];
-        const owner = verb !== 'done' || identity === undefined || this.square.hostLedger === undefined ? undefined
-            : await readParticipantOwner(this.square.location, this.name, this.square.hostLedger);
-        const fenced = identity !== undefined && owner?.session === identity.sessionId && presenceEpoch(owner) > 0;
-        const name = fenced ? this.name : (await join(this.square, this.name, control)).name;
-        const result = verb === 'done' ? await done(this.square, name, body ?? '', fenced ? { expectedEpoch: presenceEpoch(owner) } : {}, control)
-            : verb === 'hold' ? await hold(this.square, name, body, control) : await resume(this.square, name, control);
-        const { observation: committed, ...receipt } = result;
-        return { ...receipt, ...(!options.observe ? {} : { observation: {
-                    ...observedContext(this.square, committed.standingCount, committed.held, name, committed.now), ...committed,
-                } }) };
-    }
-    hold(reason, options = {}, control) { return this.lifecycle('hold', reason, options, control); }
-    resume(options = {}, control) { return this.lifecycle('resume', undefined, options, control); }
-    done(body, options = {}, control) { return this.lifecycle('done', body, options, control); }
-}
-/** One concrete square resource. Request handles may borrow a server-owned connection. */
-export class Square {
-    location;
-    square;
-    defaultParticipant;
-    transport;
-    constructor(location, square, defaultParticipant) {
-        this.location = location;
-        this.square = square;
-        this.defaultParticipant = defaultParticipant;
-        this.transport = defaultTransport(square);
-    }
-    static async at(input, control) {
-        const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env });
-        return new Square(location, await openSquare(location, { ...input, env, clock: squareClock(env, input.clock), artifact: input.resources?.artifact(location) }, control), input.participant);
-    }
-    static async build(input, control) {
-        checkControl(control);
-        const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env });
-        await createSquare(location, { hardCap: input.hardCap, throttlePerMinute: input.throttlePerMinute,
-            template: input.template, force: input.force ?? false }, input.markdown, control?.signal);
-        // A completed build survives cancellation arriving after its commit.
-        return Square.at({ ...input, path: location, env });
-    }
-    static inMemory(input) {
-        const env = { ...(input.env ?? process.env) };
-        return new Square('memory', buildMemorySquare({ ...input, env, clock: squareClock(env, input.clock) }), input.participant);
-    }
-    handle(name) { return new ParticipantHandle(name, this, this.square, this.transport); }
-    async participant(requested) {
-        const selected = requested ?? this.defaultParticipant ?? this.square.env?.SQUARE_PARTICIPANT_NAME;
-        if (requested !== undefined || this.defaultParticipant !== undefined || selected?.trim()) {
-            validateName(selected);
-            return this.handle(selected);
-        }
-        const discovered = this.square.hostLedger === undefined ? undefined : await localParticipantName(this.location, this.square.hostLedger, this.square.env);
-        if (discovered !== undefined)
-            return this.handle(discovered);
-        throw new SquareError('invalid_args', 'Square needs one unambiguous participant name');
-    }
-    async join(requested, options = {}, control) {
-        let name = requested;
-        try {
-            checkControl(control);
-            name = (await this.participant(requested)).name;
-            const last = options.last ?? HISTORY_DEFAULT_LIMIT;
-            if (!Number.isSafeInteger(last) || last < 1 || last > HISTORY_MAX_LIMIT)
-                throw new SquareError('invalid_args', 'Join history limit must be between 1 and 100');
-            let committed;
-            let result;
-            if (options.takeover && await currentParticipant(this.square, name, control) !== undefined) {
-                const taken = await takeover(this.square, name, control);
-                result = { participant: taken.name, activity: taken.activities.at(-1) ?? null, kind: 'taken-over', participantCount: taken.participantCount };
-                committed = taken.observation;
-            }
-            else {
-                const joined = await join(this.square, name, control);
-                result = { participant: joined.name, activity: joined.activity, kind: joined.reconnected ? 'reconnected' : 'joined', participantCount: joined.participantCount };
-                committed = joined.observation;
-            }
-            const entry = !options.observe ? undefined : await entryPresentation(this.square, result.participant, last, control).catch(() => undefined);
-            return { ...result, participant: this.handle(result.participant), ...(!options.observe ? {} : {
-                    observation: {
-                        ...observedContext(this.square, committed.standingCount, committed.held, result.participant, committed.now),
-                        ...(entry === undefined ? { enrichmentUnavailable: true } : { entry }),
-                    },
-                }) };
-        }
-        catch (error) {
-            throw failure(error, { operation: 'join', subject: 'caller', participant: name });
-        }
-    }
-    doneOwnedSession(name, body, expectedEpoch, control) { return done(this.square, name, body, { expectedEpoch }, control); }
-    async implicitJoin(name, control) {
-        const result = await implicitJoin(this.square, name, control);
-        return { state: result.state, ...(result.state === 'done' ? {} : { participant: this.handle(result.name) }) };
-    }
-    snapshot(control) { return snapshot(this.square, control); }
-    async history(query = {}, control) {
-        if (query.limit !== undefined && query.limit !== null && (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > HISTORY_MAX_LIMIT))
-            throw new SquareError('invalid_args', `History limit must be a positive integer no greater than ${HISTORY_MAX_LIMIT}`);
-        if (query.grep !== undefined && query.fixed !== undefined)
-            throw new SquareError('invalid_args', 'History cannot combine regular-expression and literal search');
-        if (query.grep === '' || query.fixed === '')
-            throw new SquareError('invalid_args', 'History search requires non-empty text');
-        if (query.since !== undefined && !Number.isFinite(query.since))
-            throw new SquareError('invalid_args', 'History timestamp must be finite');
-        for (const count of [query.contextBefore, query.contextAfter])
-            if (count !== undefined && (!Number.isSafeInteger(count) || count < 0))
-                throw new SquareError('invalid_args', 'History context must be a non-negative safe integer');
-        const limit = query.limit === undefined ? (query.at?.length ? null : HISTORY_DEFAULT_LIMIT) : query.limit;
-        const contextual = !!query.at?.length || query.contextBefore !== undefined || query.contextAfter !== undefined;
-        const kinds = contextual || query.since !== undefined ? undefined : NON_READ;
-        return (await this.square.artifact.read((facts) => {
-            const selected = selectHistory(facts, query, limit, kinds, query.observe === true);
-            if (contextual && limit === null && selected.totalMatches > HISTORY_MAX_LIMIT)
-                throw failure(new SquareError('invalid_args', `History context exceeds ${HISTORY_MAX_LIMIT} activities`), { operation: 'history', historyBounds: { maxLimit: HISTORY_MAX_LIMIT, totalMatches: selected.totalMatches } });
-            const activities = publicActivities(selected.activities);
-            if (!query.observe)
-                return { activities };
-            const indexes = selected.activities.map((activity) => activity.index), presenceAnchors = {};
-            for (const participant of facts.roster()) {
-                const anchor = presenceAnchor(facts, participant.name);
-                if (indexes.includes(anchor))
-                    (presenceAnchors[anchor] ??= []).push(participant.name);
-            }
-            return { activities, observation: { ...observedContext(this.square, inSquareCount(facts), facts.hold().active), ...selected,
-                    sayNumbers: facts.sayOrdinals(indexes), presenceAnchors } };
-        }, control?.signal)).value;
-    }
-    async status(options = {}, control) {
-        const viewer = !options.observe ? '' : options.viewer ?? (await this.participant().catch(() => undefined))?.name ?? '';
-        return (await this.square.artifact.read((facts) => queryStatus(facts, {
-            location: this.location, now: this.square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(this.square.env),
-        }, viewer, options.observe === true), control?.signal)).value;
-    }
-    async participants(options = {}, control) {
-        return (await this.square.artifact.read((facts) => queryParticipants(facts, {
-            location: this.location, now: this.square.clock(), automaticDeliveryAvailable: hasAutomaticDeliveryIdentity(this.square.env),
-        }, options.observe === true), control?.signal)).value;
-    }
-    async recovery(requested, control) {
-        const name = (await this.participant(requested).catch(() => undefined))?.name;
-        const facts = name === undefined ? undefined : await recoveryObservation(this.square, name, control).catch(() => undefined);
-        return facts ?? await contextObservation(this.square, name, control);
-    }
-    stream(options, control) { return streamSquare(this.location, options, control, this.square); }
-    async recognize(env) {
-        if (this.square.hostLedger === undefined)
-            return null;
-        const candidates = (await Promise.all(sessionIdsFromEnvironment(env).map((sessionId) => projectSessionBindings({ hostLedger: this.square.hostLedger, location: this.location, sessionId })))).flat();
-        if (candidates.length !== 1)
-            return null;
-        const name = await currentParticipant(this.square, candidates[0].participant);
-        return name === undefined ? null : this.handle(name);
-    }
-    close() { return closeOpenSquare(this.square); }
-    endOwnedSession(name, sessionId, expectedEpoch) { return endOwnedSession(this.square, name, sessionId, expectedEpoch); }
-    retireEndedSessionRoutes(sessionId) { return retireEndedSessionRoutes(this.square, sessionId); }
-}
-export function diagnoseSquare(input, control) { checkControl(control); return diagnoseSquareFile(squareLocation(input)); }
-export function migrateSquare(input, control) { checkControl(control); return migrateSquareFile(squareLocation(input), control?.signal); }
-export function discover(input, options = {}, control) {
-    const env = { ...(input.env ?? process.env) };
-    return discoverSquares(input.cwd ?? process.cwd(), options, control, { ...input, env, clock: squareClock(env, input.clock) });
-}
-export async function inbox(input, sessionId, options = {}, control) {
-    checkControl(control);
-    const env = { ...(input.env ?? process.env) }, hostLedger = input.hostLedger ?? hostLedgerForEnv(env), limit = options.limit ?? 20;
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
-        throw new SquareError('invalid_args', 'Inbox limit must be between 1 and 100');
-    const rows = [];
-    for (const binding of await projectSessionBindings({ hostLedger, sessionId })) {
-        checkControl(control);
-        let square;
-        try {
-            square = await openSquare(binding.location, { ...input, env, hostLedger, clock: squareClock(env, input.clock) }, control);
-            const row = (await square.artifact.read((facts) => {
-                const participant = facts.participant(binding.participant);
-                return !participant?.joined ? undefined : { name: participant.name, squarePath: binding.location,
-                    pending: facts.directedCount(participant.name, { unseenOnly: true }) };
-            }, control?.signal)).value;
-            if (row !== undefined)
-                rows.push(row);
-        }
-        catch (error) {
-            if (control?.signal?.aborted)
-                throw error;
-        }
-        finally {
-            if (square !== undefined)
-                await closeOpenSquare(square);
-        }
-    }
-    const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
-    rows.sort((a, b) => compare(a.squarePath, b.squarePath) || compare(nameKey(a.name), nameKey(b.name)) || compare(a.name, b.name));
-    return { rows: rows.slice(0, limit), total: rows.length };
-}
+import { SqliteSquare } from './sqlite-square.js';
+import { squareLocation, backendConfiguration, parseSquareLocation } from './square-location.js';
+import { openStdioSquare } from './square-stdio.js';
+export { squareLocation } from './square-location.js';
+export { squareClock, createSquareResourceOwner, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT, HELD_WAIT_BUDGET_MS, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, diagnoseSquare, migrateSquare, discover, inbox } from './sqlite-square.js';
+export const Square = {
+    async at(input, control) {
+        const captured = { ...input, cwd: input.cwd ?? process.cwd(), env: { ...(input.env ?? process.env) } };
+        const location = squareLocation(captured);
+        const selected = parseSquareLocation(location);
+        const backends = await backendConfiguration(captured);
+        return selected.kind === 'local' ? SqliteSquare.at({ ...captured, path: location }, control)
+            : openStdioSquare(location, selected, captured, backends, undefined, control);
+    },
+    async build(input, control) {
+        const captured = { ...input, cwd: input.cwd ?? process.cwd(), env: { ...(input.env ?? process.env) } };
+        const location = squareLocation(captured);
+        const selected = parseSquareLocation(location);
+        const backends = await backendConfiguration(captured);
+        return selected.kind === 'local' ? SqliteSquare.build({ ...captured, path: location }, control)
+            : openStdioSquare(location, selected, captured, backends, {
+                markdown: input.markdown, hardCap: input.hardCap, throttlePerMinute: input.throttlePerMinute,
+                template: input.template, force: input.force,
+            }, control);
+    },
+    inMemory(input) { return SqliteSquare.inMemory(input); },
+};

package/dist/square-backend.d.ts

@@ -0,0 +1,13 @@
+import type { SqliteSquare } from './sqlite-square.js';
+/** Structural resource contract extracted from the existing implementation.
+ * Backends implement the actual resource, not a second operation/policy dispatcher.
+ * Host-internal methods may explicitly refuse where their capabilities do not exist. */
+export interface SquareBackend extends Pick<SqliteSquare, keyof SqliteSquare> {
+}
+export interface StdioBackendConfiguration {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}
+export type SquareBackends = Readonly<Record<string, StdioBackendConfiguration>>;

package/dist/square-backend.js

@@ -0,0 +1 @@
+export {};

package/dist/square-facade.d.ts

@@ -1,3 +1,4 @@
+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';
@@ -156,6 +157,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;

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?}}}');
+    }
+}