@astrosheep/square 0.3.2

package/dist/delivery-health.js

@@ -0,0 +1,249 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadSquare, saveRuntimeSidecar } from './artifact.js';
+import { SquareError, sameName } from './model.js';
+import { planActNotifications } from './notifications.js';
+import { formatDuration } from './time.js';
+import { isCurrentlyJoined, isDeliveryDelivered, lastJoinAt, recordDeliveredDelivery, resolveRosterName, rosterNames, } from './runtime.js';
+const DEFAULT_STALE_MS = 60_000;
+/** Only acts inside this lookback can prove "hooks are dead right now". Older = historical debt. */
+const DEFAULT_LOOKBACK_MS = 60 * 60 * 1000;
+function parsePositiveIntegerEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new SquareError('invalid_args', `Invalid ${name}: expected a positive integer.`);
+    }
+    return value;
+}
+/** How long a mention/bell may remain undelivered before harness liveness is suspect. */
+export function deliveryStaleMs() {
+    return parsePositiveIntegerEnv('SQUARE_DELIVERY_STALE_MS', DEFAULT_STALE_MS);
+}
+/** How far back liveness scans look. Older unreceipted mentions are backlog, not hook-death. */
+export function deliveryLookbackMs() {
+    return parsePositiveIntegerEnv('SQUARE_DELIVERY_LOOKBACK_MS', DEFAULT_LOOKBACK_MS);
+}
+function baselinePath(env = process.env) {
+    return env.SQUARE_DELIVERY_BASELINE || path.join(os.homedir(), '.square', 'delivery-baseline.json');
+}
+function readBaselines(env = process.env) {
+    const file = baselinePath(env);
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+export function recordBacklogBaseline(squarePath, backlogCount, env = process.env, at = Date.now()) {
+    const file = baselinePath(env);
+    const data = readBaselines(env);
+    data[path.resolve(squarePath)] = { backlogCount, at };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temp, file);
+}
+export function previousBacklogCount(squarePath, env = process.env) {
+    return readBaselines(env)[path.resolve(squarePath)]?.backlogCount;
+}
+function isReceipted(_squarePath, doc, recipient, actIndex, _env) {
+    // This sidecar record is the only delivery authority. A machine-local
+    // presentation cache may suppress duplicate hook text, but never clears debt.
+    return isDeliveryDelivered(doc, recipient, actIndex);
+}
+function actedAfterMention(doc, recipient, mentionAt, mentionIndex) {
+    return doc.acts.some((act) => act.actor !== undefined &&
+        sameName(act.actor, recipient) &&
+        (act.at > mentionAt || act.index > mentionIndex));
+}
+function collectUnreceiptedMentions(squarePath, doc, now, opts = {}) {
+    const env = opts.env ?? process.env;
+    const pending = [];
+    for (const act of doc.acts) {
+        if (act.kind !== 'say')
+            continue;
+        const item = { act, index: act.index };
+        for (const planned of planActNotifications(doc, item)) {
+            if (planned.via !== 'mention' && planned.via !== 'bell')
+                continue;
+            const recipient = resolveRosterName(doc, planned.recipient) ?? planned.recipient;
+            if (opts.onlyJoined && !isCurrentlyJoined(doc.acts, recipient))
+                continue;
+            if (isReceipted(squarePath, doc, recipient, act.index, env))
+                continue;
+            pending.push({
+                squarePath,
+                recipient,
+                actIndex: act.index,
+                actor: act.actor,
+                at: act.at,
+                ageMs: now - act.at,
+                via: planned.via,
+                actedAfterWithoutDelivery: actedAfterMention(doc, recipient, act.at, act.index),
+            });
+        }
+    }
+    return pending;
+}
+/**
+ * Partition unreceipted mention/bell traffic.
+ * Liveness failure requires: past stale, inside lookback, currently joined, mention after last join.
+ */
+export function partitionPendingDeliveries(squarePath, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const staleMs = opts.staleMs ?? deliveryStaleMs();
+    const lookbackMs = Math.max(opts.lookbackMs ?? deliveryLookbackMs(), staleMs);
+    const doc = opts.doc ?? loadSquare(squarePath);
+    const recent = [];
+    const historical = [];
+    // Include not-joined for historical/reconcile; liveness only uses joined.
+    for (const item of collectUnreceiptedMentions(squarePath, doc, now, {
+        onlyJoined: false,
+        env: opts.env,
+    })) {
+        const joined = isCurrentlyJoined(doc.acts, item.recipient);
+        const joinAt = lastJoinAt(doc.acts, item.recipient);
+        const afterJoin = joinAt === undefined || item.at >= joinAt;
+        const inLookback = item.ageMs <= lookbackMs;
+        const pastStale = item.ageMs >= staleMs;
+        if (joined && pastStale && inLookback && afterJoin) {
+            recent.push(item);
+            continue;
+        }
+        // Still in grace window and would otherwise be live → ignore (not historical yet).
+        if (joined && !pastStale && inLookback && afterJoin)
+            continue;
+        historical.push(item);
+    }
+    return { recent, historical };
+}
+/** Recent stale only — the liveness signal. */
+export function findStalePendingMentions(squarePath, opts = {}) {
+    return partitionPendingDeliveries(squarePath, opts).recent;
+}
+function summarizeByRecipient(items) {
+    const byRecipient = new Map();
+    for (const item of items) {
+        const list = byRecipient.get(item.recipient) ?? [];
+        list.push(item);
+        byRecipient.set(item.recipient, list);
+    }
+    const lines = [];
+    for (const [recipient, group] of byRecipient) {
+        const oldest = group.reduce((a, b) => (a.at <= b.at ? a : b));
+        const ageSec = Math.max(1, Math.round(oldest.ageMs / 1000));
+        const adapter = group.some((item) => item.actedAfterWithoutDelivery);
+        lines.push(adapter
+            ? `  · @${recipient}: ${group.length} pending — acted after the mention, but delivery was not acknowledged (oldest act_${oldest.actIndex}, ~${ageSec}s)`
+            : `  · @${recipient}: ${group.length} pending (oldest act_${oldest.actIndex} from @${oldest.actor}, ~${ageSec}s)`);
+    }
+    return lines;
+}
+export function formatStaleDeliveryWarnings(recent, historical = [], opts = {}) {
+    const lines = [];
+    if (recent.length > 0) {
+        const adapterFaults = recent.filter((item) => item.actedAfterWithoutDelivery);
+        if (adapterFaults.length > 0) {
+            lines.push(`⚠ ${adapterFaults.length} recent mention(s): the recipient acted after the mention, but delivery was not acknowledged.`);
+            lines.push('  This points to an adapter failure, not participant behavior.');
+            lines.push('  » square harness doctor');
+        }
+        const other = recent.filter((item) => !item.actedAfterWithoutDelivery);
+        if (other.length > 0) {
+            lines.push(`⚠ ${other.length} recent mention or bell notification(s) were not acknowledged inside the delivery window.`);
+            lines.push('  The installed hook or extension may not be consuming notifications.');
+        }
+        lines.push(...summarizeByRecipient(recent));
+        if (adapterFaults.length === 0)
+            lines.push('  » square harness doctor');
+    }
+    if (historical.length > 0) {
+        lines.push(`○ ${historical.length} historical or pre-join mention(s) remain unacknowledged — backlog, not a current delivery failure.`);
+        const counts = new Map();
+        for (const item of historical) {
+            counts.set(item.recipient, (counts.get(item.recipient) ?? 0) + 1);
+        }
+        lines.push(`  · ${[...counts.entries()].map(([name, n]) => `@${name}:${n}`).join(', ')}`);
+        if (opts.previousBacklog !== undefined) {
+            const delta = historical.length - opts.previousBacklog;
+            if (delta > 0) {
+                lines.push(`  ⚠ backlog grew by ${delta} since last doctor (something aged out of lookback unnoticed).`);
+            }
+            else if (delta < 0) {
+                lines.push(`  · backlog shrank by ${-delta} since last doctor.`);
+            }
+            else {
+                lines.push('  · backlog unchanged since last doctor.');
+            }
+        }
+    }
+    else if (opts.previousBacklog !== undefined && opts.previousBacklog > 0) {
+        lines.push(`○ backlog cleared (was ${opts.previousBacklog}).`);
+    }
+    return lines;
+}
+export function doctorDeliveryHealth(squarePath, now = Date.now(), env = process.env) {
+    try {
+        const doc = loadSquare(squarePath);
+        const { recent, historical } = partitionPendingDeliveries(squarePath, { now, doc, env });
+        const previous = previousBacklogCount(squarePath, env);
+        const lines = [
+            `· stale after ${formatDuration(deliveryStaleMs())} · scan window ${formatDuration(deliveryLookbackMs())}`,
+            `· participants ${rosterNames(doc).join(', ') || '(none)'}`,
+        ];
+        if (recent.length === 0 && historical.length === 0) {
+            lines.push('✓ no stale undelivered mentions or bells');
+        }
+        else {
+            if (recent.length === 0) {
+                lines.push('✓ no current delivery failures inside the scan window');
+            }
+            lines.push(...formatStaleDeliveryWarnings(recent, historical, { previousBacklog: previous }).map((line) => line.startsWith('⚠ ') ? line.replace(/^⚠ /, '✕ ') : line));
+        }
+        recordBacklogBaseline(squarePath, historical.length, env, now);
+        return lines;
+    }
+    catch (error) {
+        return [`✕ delivery health unreadable: ${error instanceof Error ? error.message : String(error)}`];
+    }
+}
+/** Act-path only screams for recent liveness failures, not historical backlog. */
+export function hasStalePendingForAny(squarePath, now = Date.now()) {
+    return findStalePendingMentions(squarePath, { now }).length > 0;
+}
+export function notificationMessageId(squarePath, actIndex) {
+    return `square:${squarePath}#act_${actIndex}`;
+}
+/**
+ * Write delivered-class receipts with reason=reconciled for backlog items.
+ * Does not touch recent liveness failures.
+ */
+export function reconcileDeliveryBacklog(squarePath, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const doc = loadSquare(squarePath);
+    const { recent, historical } = partitionPendingDeliveries(squarePath, {
+        now,
+        doc,
+        lookbackMs: opts.lookbackMs,
+        staleMs: opts.staleMs,
+    });
+    const actor = opts.actor ?? 'doctor --fix reconcile-backlog';
+    let reconciled = 0;
+    for (const item of historical) {
+        if (recordDeliveredDelivery(doc, item.recipient, item.actIndex, { at: now, reason: 'reconciled', actor }))
+            reconciled += 1;
+    }
+    if (reconciled > 0)
+        saveRuntimeSidecar(squarePath, doc.runtime);
+    return { reconciled, skippedRecent: recent.length, items: historical };
+}

package/dist/delivery.js

@@ -0,0 +1,93 @@
+import { findParticipantName, sameName, } from './model.js';
+import { extractMentions, isDeliveryDelivered, lastJoinIndex, matchesMentionTarget, rosterNames } from './runtime.js';
+function uniqueKnownMentions(body, roster) {
+    const recipients = [];
+    for (const mention of extractMentions(body)) {
+        const known = findParticipantName(roster, mention);
+        if (known !== undefined && !recipients.some((recipient) => sameName(recipient, known))) {
+            recipients.push(known);
+        }
+    }
+    return recipients;
+}
+/**
+ * Derive delivery behavior once from the parsed Square document.
+ * All consumers share these targets instead of reinterpreting artifact text or cursor state.
+ */
+export function deriveDeliveryModel(doc) {
+    const roster = rosterNames(doc);
+    let pendingByRecipient;
+    function plan(item) {
+        if (item.act.kind !== 'say')
+            return [];
+        const sayItem = item;
+        const actor = sayItem.act.actor;
+        if (sayItem.act.reach === 'bell') {
+            return roster
+                .filter((recipient) => !sameName(recipient, actor))
+                .map((recipient) => ({ item: sayItem, recipient, via: 'bell' }));
+        }
+        if (sayItem.act.reach !== undefined) {
+            const recipient = findParticipantName(roster, sayItem.act.reach.beside);
+            return recipient === undefined || sameName(recipient, actor)
+                ? []
+                : [{ item: sayItem, recipient, via: 'mention' }];
+        }
+        const mentions = uniqueKnownMentions(sayItem.act.body, roster).filter((recipient) => !sameName(recipient, actor));
+        const recipients = mentions.length > 0
+            ? mentions
+            : roster.filter((recipient) => !sameName(recipient, actor));
+        const via = mentions.length > 0 ? 'mention' : 'broadcast';
+        return recipients.map((recipient) => ({ item: sayItem, recipient, via }));
+    }
+    function pendingFor(requestedRecipient) {
+        const recipient = findParticipantName(roster, requestedRecipient);
+        if (recipient === undefined)
+            return [];
+        if (pendingByRecipient === undefined) {
+            pendingByRecipient = new Map(roster.map((name) => [name, []]));
+            const joinedAfter = new Map(roster.map((name) => [name, lastJoinIndex(doc.acts, name)]));
+            for (const act of doc.acts) {
+                if (act.kind !== 'say')
+                    continue;
+                // Broadcasts can never be pending directed notifications. Skipping them here
+                // avoids allocating one planned notification per participant per activity.
+                if (act.reach === undefined && extractMentions(act.body).length === 0)
+                    continue;
+                for (const planned of plan({ act, index: act.index })) {
+                    if (planned.via === 'broadcast')
+                        continue;
+                    const joinedAt = joinedAfter.get(planned.recipient);
+                    if (joinedAt === undefined || act.index <= joinedAt)
+                        continue;
+                    if (isDeliveryDelivered(doc, planned.recipient, act.index))
+                        continue;
+                    pendingByRecipient.get(planned.recipient)?.push({ ...planned, via: planned.via });
+                }
+            }
+        }
+        return [...(pendingByRecipient.get(recipient) ?? [])];
+    }
+    return { plan, pendingFor };
+}
+export function planActNotifications(doc, item) {
+    return deriveDeliveryModel(doc).plan(item);
+}
+/** Canonical say-activity filter shared by catch selection and hook ownership. */
+export function matchesCatchFilter(activity, filter) {
+    if (activity.bell)
+        return true;
+    if (filter.participants !== undefined &&
+        !filter.participants.some((participant) => sameName(participant, activity.actor))) {
+        return false;
+    }
+    return filter.mention === undefined || matchesMentionTarget({ body: activity.body }, filter.mention);
+}
+/** True only when the live catch's own filters would deliver this notification. */
+export function leaseOwnsNotification(lease, notification) {
+    return matchesCatchFilter({
+        actor: notification.actor,
+        body: notification.body,
+        bell: notification.via === 'bell',
+    }, lease.filter ?? {});
+}

package/dist/doctor.js

@@ -0,0 +1,34 @@
+import { diagnoseSquare, } from './artifact.js';
+export function planRepair(text) {
+    const diagnosis = diagnoseSquare(text);
+    if (diagnosis.unfixable)
+        return { diagnosis };
+    const actions = [];
+    const acts = diagnosis.acts.map(({ act }, index) => ({ ...act, index }));
+    if (diagnosis.acts.some(({ act }, index) => act.index !== index)) {
+        actions.push({ message: 'renumbered act indexes to be contiguous' });
+    }
+    if (diagnosis.quarantined.length > 0) {
+        actions.push({ message: `quarantined ${diagnosis.quarantined.length} unparseable act block(s)` });
+    }
+    if (diagnosis.legacyParticipants.length > 0) {
+        actions.push({ message: 'dropped frontmatter participants; roster now derives from join/done acts' });
+    }
+    const nextActIndex = acts.length;
+    const doc = {
+        hardCap: diagnosis.hardCap,
+        throttlePerMinute: diagnosis.throttlePerMinute,
+        preamble: diagnosis.preamble,
+        warmup: diagnosis.warmup,
+        acts,
+        runtime: {
+            version: 2,
+            nextActIndex,
+            firstActIndex: acts.length > 0 ? (acts[0].index ?? 0) : 0,
+            cursors: {},
+            mentionReceipts: {},
+            leases: {},
+        },
+    };
+    return { diagnosis, repaired: { doc, actions, quarantinedBlocks: diagnosis.quarantined.map((q) => q.raw) } };
+}