@astrosheep/square 0.3.58 → 0.3.62

package/dist/mention-parse.js

@@ -0,0 +1,107 @@
+import { NAME_GRAPHEME_SOURCE, sameName } from './model.js';
+/**
+ * Roster-free scan for `@name` candidates in an activity body. Resolution against the
+ * standing roster happens at landing time in decideAct; this scanner only knows the
+ * name grammar and Markdown code spans.
+ *
+ * Guard rails:
+ * - Backtick code spans never yield candidates (also the escape hatch: `` `@name` `` stays literal).
+ * - A `@` glued to a handle-like prefix does not start a candidate, so emails
+ *   (`user@host`), URLs (`x.com/@user`), and `snake_@case` stay literal. Only ASCII
+ *   word characters, `_`, `-`, `/`, and `@` block a boundary: CJK adjacency like
+ *   `告诉@rei` stays mentionable because CJK text has no spaces to lean on.
+ * - The token must be a complete name (slash-separated segments allowed); resolution
+ *   never backs off to a shorter prefix, so `@rei2` does not mention `rei`.
+ */
+const MENTION_TOKEN = new RegExp(`@((?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*)`, 'vg');
+const BOUNDARY_BLOCKER = /[A-Za-z0-9_\-/@]/;
+/** Ranges [from, to) covered by Markdown code spans (backtick runs close at a run of equal length). */
+function codeSpanRanges(body) {
+    const ranges = [];
+    let index = 0;
+    while (index < body.length) {
+        if (body[index] !== '`') {
+            index += 1;
+            continue;
+        }
+        let runEnd = index;
+        while (runEnd < body.length && body[runEnd] === '`')
+            runEnd += 1;
+        const runLength = runEnd - index;
+        let scan = runEnd;
+        let closedEnd = -1;
+        while (scan < body.length) {
+            if (body[scan] !== '`') {
+                scan += 1;
+                continue;
+            }
+            let closeEnd = scan;
+            while (closeEnd < body.length && body[closeEnd] === '`')
+                closeEnd += 1;
+            if (closeEnd - scan === runLength) {
+                closedEnd = closeEnd;
+                break;
+            }
+            scan = closeEnd;
+        }
+        if (closedEnd === -1) {
+            // Unmatched backticks are literal text; scanning continues after the run.
+            index = runEnd;
+            continue;
+        }
+        ranges.push([index, closedEnd]);
+        index = closedEnd;
+    }
+    return ranges;
+}
+function codePointBefore(body, index) {
+    if (index <= 0)
+        return undefined;
+    const unit = body.charCodeAt(index - 1);
+    if (unit >= 0xdc00 && unit <= 0xdfff && index >= 2)
+        return String.fromCodePoint(body.codePointAt(index - 2));
+    return String.fromCodePoint(unit);
+}
+export function scanMentionCandidates(body) {
+    const spans = codeSpanRanges(body);
+    const found = [];
+    const seen = new Set();
+    for (const match of body.matchAll(MENTION_TOKEN)) {
+        const start = match.index;
+        if (spans.some(([from, to]) => start >= from && start < to))
+            continue;
+        const previous = codePointBefore(body, start);
+        if (previous !== undefined && BOUNDARY_BLOCKER.test(previous))
+            continue;
+        const token = match[1];
+        const key = token.toLocaleLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            found.push({ token, index: start });
+        }
+    }
+    return found;
+}
+/**
+ * Resolve the longest standing name starting at one candidate's position. A partial
+ * match is only accepted when the character right after it is not handle-continuation
+ * (ASCII word char, `_`, `-`, `/`): `@rei2` never degrades into mentioning `rei`, while
+ * CJK-fluent text like `告诉@rei这个` still mentions `rei`.
+ */
+const TRAILING_BLOCKER = /[A-Za-z0-9_\-/]/;
+export function resolveNameAt(body, candidate, names) {
+    const text = body.slice(candidate.index + 1, candidate.index + 1 + candidate.token.length);
+    let best;
+    for (const name of names) {
+        if (name.length > text.length)
+            continue;
+        if (!sameName(text.slice(0, name.length), name))
+            continue;
+        const after = text[name.length];
+        if (after !== undefined && TRAILING_BLOCKER.test(after))
+            continue;
+        if (best === undefined || name.length > best.length)
+            best = name;
+    }
+    return best;
+}

package/dist/model.d.ts

@@ -18,8 +18,11 @@ export interface ReceiverRoute extends WakeRoute {
 export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'held' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
 export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
 export interface SquareErrorFacts {
+    /** Express admission rejected before any activity was committed. */
+    activityUnsent?: true;
     pending?: number;
     holder?: string;
+    holdReason?: string;
     retryAfterMs?: number;
 }
 declare class SquareErrorBase<Code extends string> extends Error {
@@ -132,4 +135,6 @@ export declare function parseParticipantList(value: string): string[];
 export declare function nameKey(name: string): string;
 export declare function sameName(a: string, b: string): boolean;
 export declare function findParticipantName(participants: string[], name: string): string | undefined;
+/** One name grapheme: Unicode letters, digits, marks, hyphens, or underscores (no isolated variation selectors), or a complete RGI emoji. Shared by name validation and body @mention scanning. */
+export declare const NAME_GRAPHEME_SOURCE: string;
 export declare function validateName(name: string): void;

package/dist/model.js

@@ -39,8 +39,11 @@ export function sameName(a, b) {
 export function findParticipantName(participants, name) {
     return participants.find((participant) => sameName(participant, name));
 }
+/** One name grapheme: Unicode letters, digits, marks, hyphens, or underscores (no isolated variation selectors), or a complete RGI emoji. Shared by name validation and body @mention scanning. */
+export const NAME_GRAPHEME_SOURCE = String.raw `[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji}`;
+const NAME_PATTERN = new RegExp(`^(?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*$`, 'v');
 export function validateName(name) {
-    if (!name || !/^(?:[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji})+(?:\/(?:[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji})+)*$/v.test(name)) {
+    if (!name || !NAME_PATTERN.test(name)) {
         throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using Unicode letters, digits, marks, hyphens, underscores, or complete RGI emoji graphemes.');
     }
 }

package/dist/notifications.d.ts

@@ -12,6 +12,7 @@ export declare function hasDeliveredNotification(squarePath: string, name: strin
 export declare function hasAttentionNotification(squarePath: string, name: string, ref: number | ActivityId, env?: NodeJS.ProcessEnv): Promise<boolean>;
 export declare function waitForDeliveredNotification(squarePath: string, name: string, ref: number | ActivityId, opts?: {
     timeoutMs?: number;
+    signal?: AbortSignal;
 }): Promise<boolean>;
 interface ProcessNotificationOptions {
     adapters?: WakeAdapter[];

package/dist/notifications.js

@@ -1,12 +1,12 @@
-import { setTimeout as sleep } from 'node:timers/promises';
+import { hostLedgerRoot } from './host-ledger-root.js';
 import path from 'node:path';
 import fs from 'node:fs';
 import { planActNotifications, } from './delivery.js';
 import { SquareError } from './model.js';
-import { SLEEP_MS, matchesMentionTarget } from './runtime.js';
+import { matchesMentionTarget } from './runtime.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { displayAttentionPath } from './attention-presentation.js';
-import { openSquare } from './square-file-adapter.js';
+import { openSquare, observeSquareChanges } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { notificationDelivered, resolveParticipant } from './views.js';
 import { deliverPending, observeSquare, sweepPending, sweepPendingFromState } from './delivery-operations.js';
@@ -63,8 +63,8 @@ export async function hasAttentionNotification(squarePath, name, ref, env = proc
         const index = notificationIndex(ref);
         if (await notificationDelivered(square, recipient, index))
             return true;
-        const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-        const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
+        const root = hostLedgerRoot(env);
+        const hostLedger = createHostLedgerPort({ rootPath: root });
         return (await projectPresentationEvidence({ hostLedger, location: squarePath, participant: recipient, activity: formatActivityId(index), now: Date.now() })).some((row) => row.outcome === 'presented');
     }
     finally {
@@ -73,12 +73,20 @@ export async function hasAttentionNotification(squarePath, name, ref, env = proc
 }
 export async function waitForDeliveredNotification(squarePath, name, ref, opts = {}) {
     const deadline = Date.now() + (opts.timeoutMs ?? 30000);
-    while (Date.now() <= deadline) {
-        if (await hasDeliveredNotification(squarePath, name, ref))
-            return true;
-        await sleep(Math.min(SLEEP_MS, Math.max(1, deadline - Date.now())));
+    const observer = await observeSquareChanges(squarePath);
+    try {
+        while (Date.now() <= deadline) {
+            const baseline = await observer.read(opts.signal);
+            if (await hasDeliveredNotification(squarePath, name, ref))
+                return true;
+            if (!await observer.changed(baseline, Math.max(0, deadline - Date.now()), opts.signal))
+                return false;
+        }
+        return false;
+    }
+    finally {
+        observer.close();
     }
-    return false;
 }
 export async function defaultWakeAdapters() {
     const adapters = [];
@@ -188,10 +196,9 @@ export function createWakeTransport(adapters, hostLedger, clock) {
 export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
     const env = opts.env ?? process.env;
     const now = opts.now ?? Date.now;
-    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+    const ledgerRoot = hostLedgerRoot(env);
     const hostLedger = createHostLedgerPort({
-        userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot,
-        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot,
+        rootPath: ledgerRoot,
     });
     const square = await openSquare(squarePath, { clock: now, hostLedger, env });
     try {
@@ -213,11 +220,11 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
     const remainingMs = () => Math.max(0, deadline - Date.now());
     if (remainingMs() === 0 || signal?.aborted)
         return;
-    const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
+    const root = hostLedgerRoot(env);
+    const hostLedger = createHostLedgerPort({ rootPath: root });
     let indexed = [];
     try {
-        indexed = await hostLedger.listPresence({ scopes: ['user'], now: Date.now() });
+        indexed = await hostLedger.listPresence({ now: Date.now() });
     }
     catch { /* capability is best effort */ }
     const paths = new Set(indexed.map((binding) => binding.location));
@@ -237,7 +244,6 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
         try {
             const square = await openSquare(squarePath, { hostLedger, env, signal });
             try {
-                await hostLedger.reconcileBinding({ artifact: square.artifact, scopes: ['user'], now: Date.now() }).catch(() => undefined);
                 if (remainingMs() === 0 || signal?.aborted)
                     break;
                 const limit = Number.parseInt(env.SQUARE_NOTIFY_SWEEP_LIMIT ?? '8', 10);
@@ -262,7 +268,7 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
 }
 /** Select sweep candidates from one frozen snapshot and one delivery replay. */
 export async function pendingNotificationSweepFromState(squarePath, state, now, env, limit, deriveDelivery) {
-    const ledger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER, writableScope: 'user', readableScopes: ['user'] });
+    const ledger = createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
     return sweepPendingFromState({ state, hostLedger: ledger, location: squarePath, now, graceMs: wakeGraceMs(env), limit, deriveDelivery });
 }
 /** Select old pending attention at a bounded action boundary for an explicit executor. */
@@ -272,8 +278,7 @@ export async function sweepPendingNotifications(squarePath, opts = {}) {
         return [];
     const now = opts.now ?? Date.now();
     const limit = opts.limit ?? 8;
-    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot });
+    const hostLedger = createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
     const square = await openSquare(squarePath, { clock: () => now, hostLedger, env });
     let selected;
     try {

package/dist/participant-host.js

@@ -53,7 +53,7 @@ export async function ensureLocalPresence(context, participant, epoch) {
     const now = context.clock();
     // Semantic publish: an unexpired presence row already stands when it carries the same owner epoch.
     try {
-        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, scopes: ['local'], now });
+        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, now });
         if (existing.some((row) => row.channel === identity.channel
             && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
             && (ownerEpoch === undefined || row.epoch === ownerEpoch)))
@@ -68,7 +68,7 @@ export async function ensureLocalPresence(context, participant, epoch) {
         // Presence rows are host-ledger wall-time evidence; the square clock belongs to artifact activities.
         updatedAt: Date.now(),
         ...(ownerEpoch === undefined || ownerEpoch <= 0 ? {} : { epoch: ownerEpoch }),
-    }, 'local').catch((error) => ({
+    }).catch((error) => ({
         status: 'degraded',
         record: { location: context.location, participant, session: identity.session, channel: identity.channel },
         error,

package/dist/ports.d.ts

@@ -1,6 +1,6 @@
 import type { InboxNotification, SquareState, StoredAct, WakeRoute, WatchLease } from './model.js';
 import type { PlannedNotification } from './delivery.js';
-export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, HostLedgerScope, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, ReconcileBindingInput as HostLedgerReconcileBindingInput, ReconcileBindingResult, } from './host-ledger.js';
+export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, } from './host-ledger.js';
 import type { HostLedgerPort } from './host-ledger.js';
 /** Atomic artifact access. Never exposes framing, compression, locks, or storage schema. */
 export interface SquareArtifactPort {
@@ -12,7 +12,7 @@ export interface SquareArtifactPort {
         state?: SquareState;
         result: R;
     }, signal?: AbortSignal): Promise<R>;
-    changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
+    changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     close(): Promise<void>;
 }
 /** Capability-neutral wake transport. Unused by this Contract's activity operations. */
@@ -101,13 +101,6 @@ export interface ObserveSquareInput {
     readonly location?: string;
     readonly now?: number;
 }
-export interface ReconcileBindingInput {
-    readonly artifact: SquareArtifactPort;
-    readonly hostLedger: HostLedgerPort;
-    readonly location?: string;
-    readonly scopes?: readonly import('./host-ledger.js').HostLedgerScope[];
-    readonly now?: number;
-}
 export interface DeliveryResult {
     readonly attempted: number;
     readonly accepted: number;

package/dist/presentation.d.ts

@@ -6,6 +6,8 @@ export type WatchStatus = 'stale' | 'empty-now' | 'quorum' | 'capped';
 interface HeaderOptions {
     participantCount?: number;
     held?: boolean;
+    /** Refusal bodies go to stderr, which stays literal even when it is a TTY. */
+    plain?: boolean;
 }
 interface ParticipantOutputOptions {
     squarePath: string;
@@ -19,6 +21,7 @@ interface ActivityLimitOptions extends ParticipantOutputOptions {
     draftPath?: string;
 }
 interface ActivityBlockedOptions extends ParticipantOutputOptions {
+    retryCommand: string;
     forceCommand: string;
     activitySummaries: UnreadActivitySummary[];
     unreadRoomChanges: RoomChangeAct[];
@@ -27,10 +30,12 @@ interface ActivityBlockedOptions extends ParticipantOutputOptions {
 interface ExpressWaitingOptions {
     reason: 'throttled' | 'held';
     delayMs?: number;
+    holder?: string;
+    holdReason?: string;
 }
 interface ExpressNoWaitOptions extends ParticipantOutputOptions {
     reason: 'throttled' | 'held';
-    forceCommand: string;
+    retryCommand: string;
     delayMs?: number;
     holdReason?: string;
     draftPath?: string;
@@ -46,11 +51,18 @@ interface WatchStatusOptions extends ParticipantOutputOptions {
 }
 export declare function displayPath(squarePath: string, cwd?: string): string;
 export declare function withPathOutput(squarePath: string, body?: string, opts?: HeaderOptions): string;
+/** The same header/blank/body layout as withPathOutput, for refusal bodies written to stderr. */
+export declare function formatRefusal(squarePath: string, bodyLines: string[], opts?: {
+    participantCount?: number;
+    held?: boolean;
+}): string;
 export declare function quoteShell(value: string): string;
 export declare function commandPrefix(squarePath: string): string;
 export declare function participantCommandPrefix(squarePath: string, name: string): string;
 /** Blocked actions end with a full copy-pasteable recovery command. */
 export declare function joinRecoveryCommand(squarePath: string, name: string): string;
+/** Taking a name is an explicit recovery choice, never an automatic retry. */
+export declare function takeoverRecoveryLines(squarePath: string, name: string): string[];
 export declare function participantsRecoveryCommand(squarePath: string): string;
 export declare function renderPresenceLines(participants: ParticipantStatus[], now: number, limit?: number): string[];
 export declare function expressHintLine(ownActivityCount: number): string | undefined;
@@ -78,6 +90,12 @@ export declare function renderAmbientEvent(event: StoredAct, viewer: string, opt
 }): string;
 export declare function renderPendingFeed(history: StoredAct[], publicItems: PublicAct[], roomChanges: RoomChangeAct[], viewer: string | undefined, squareState: SquareState): string;
 export declare function renderActivityBlocked(opts: ActivityBlockedOptions): string;
+/** An indeterminate or already-committed send only points to inspection, never resend. */
+export declare function renderActivityUncertain(opts: ParticipantOutputOptions & {
+    draftPath: string;
+    landedId?: string;
+    detail?: string;
+}): string;
 export declare function renderExpressWaiting(opts: ExpressWaitingOptions): string;
 export declare function renderExpressNoWait(opts: ExpressNoWaitOptions): string;
 export declare function renderPublicTail(squareState: SquareState, events: StoredAct[], lastN: number | null | undefined, now?: number, viewer?: string): string;