@astrosheep/square 0.3.86 → 0.3.88

package/dist/wake-attempts.js

@@ -1,39 +0,0 @@
-import { hostLedgerRoot } from './host-ledger-root.js';
-import { nameKey } from './model.js';
-import { canonicalPath } from './canonical-path.js';
-import { formatActivityId } from './square-core.js';
-import { createHostLedgerPort } from './host-ledger-file-adapter.js';
-import { redactDiagnostic } from './diagnostic-redaction.js';
-import { decodeWakeEvidence } from './wake-evidence.js';
-export function redactWakeDiagnostic(value, env = process.env) {
-    return redactDiagnostic(value, env.PASEO_PASSWORD);
-}
-export async function readWakeReleaseDiagnostics(opts = {}) {
-    const now = opts.now ?? Date.now();
-    const env = opts.env ?? process.env;
-    const rows = await createHostLedgerPort({ rootPath: hostLedgerRoot(env) }).listEvidence({
-        kind: 'wake',
-        location: opts.location ?? opts.attention?.squarePath,
-        includeReleased: true,
-        now,
-    });
-    const expected = opts.attention === undefined ? undefined : JSON.stringify([await canonicalPath(opts.attention.squarePath), formatActivityId(opts.attention.actIndex), nameKey(opts.attention.recipient)]);
-    const releases = [];
-    for (const row of rows) {
-        const decoded = decodeWakeEvidence(row, now);
-        if (decoded?.kind !== 'release')
-            continue;
-        const release = decoded.value;
-        if (opts.sessionId !== undefined && release.session !== opts.sessionId)
-            continue;
-        const { attention } = release;
-        if (expected !== undefined && JSON.stringify([attention.squarePath, formatActivityId(attention.actIndex), nameKey(attention.recipient)]) !== expected)
-            continue;
-        releases.push({
-            ...release,
-            ...(release.message === undefined ? {} : { message: redactWakeDiagnostic(release.message, env) }),
-            ...(release.diagnostic === undefined ? {} : { diagnostic: redactWakeDiagnostic(release.diagnostic, env) }),
-        });
-    }
-    return releases.sort((left, right) => right.at - left.at);
-}

package/dist/wake-eligibility.d.ts

@@ -1,53 +0,0 @@
-import { type WakeRoute } from './model.js';
-import type { EvidenceRecord, PresenceRecord } from './host-ledger.js';
-import type { DirectedHead, HostLedgerPort, PresentationEvidenceProjection, RouteFact, WakeRequest } from './ports.js';
-import { type WakeAttempt } from './wake-evidence.js';
-export interface WakeSnapshot {
-    readonly routes: readonly RouteFact[];
-    readonly pending: readonly DirectedHead[];
-    readonly seen?: readonly {
-        readonly recipient: string;
-        readonly index: number;
-    }[];
-    /** Canonicalized by the caller; every identity in this snapshot is square-local. */
-    readonly location: string;
-    readonly owners: readonly PresenceRecord[];
-    readonly bindings?: readonly PresenceRecord[];
-    readonly wakeRecords: readonly EvidenceRecord[];
-    readonly presentations: readonly PresentationEvidenceProjection[];
-    readonly now: number;
-}
-export interface OwnedWakeRoute {
-    readonly route: WakeRoute;
-    readonly owner: PresenceRecord;
-}
-export interface WakeCurrentness {
-    readonly current: boolean;
-    readonly activityPending: boolean;
-    readonly sessionBound: boolean;
-    readonly routePublished: boolean;
-    readonly selectedOwner: boolean;
-    readonly cancelled: boolean;
-    readonly presented: boolean;
-}
-export interface WakeEvidence {
-    readonly delivered: boolean;
-    /** All selected, uncancelled routes have session-local presentation evidence. */
-    readonly presented: boolean;
-    readonly attempts: readonly WakeAttempt[];
-    readonly terminal?: WakeAttempt;
-    readonly attemptableRoutes: readonly WakeRoute[];
-}
-export interface WakeEligibility {
-    evidence(recipient: string, actIndex: number): WakeEvidence;
-    currentness(request: WakeRequest): WakeCurrentness;
-}
-/** One strict ownership join, latest selection, and request fence over primary evidence only. */
-export declare function projectWakeEligibility(input: WakeSnapshot): WakeEligibility;
-/** Host observation happens only after detached artifact facts have left their transaction. */
-export declare function projectWakeEvidence(input: Pick<WakeSnapshot, 'routes' | 'pending' | 'seen' | 'location' | 'now' | 'bindings'> & {
-    readonly hostLedger: HostLedgerPort;
-    readonly owners?: readonly PresenceRecord[];
-}): Promise<WakeEligibility>;
-export declare function sameBinding(captured: PresenceRecord, current: PresenceRecord): boolean;
-export declare function wakeIsEligible(evidence: WakeEvidence): boolean;

package/dist/wake-eligibility.js

@@ -1,123 +0,0 @@
-import { nameKey } from './model.js';
-import { formatActivityId, parseActivityId } from './square-core.js';
-import { presenceEpoch } from './registry.js';
-import { canonicalPath } from './canonical-path.js';
-import { decodeWakeEvidence } from './wake-evidence.js';
-function identity(...parts) { return JSON.stringify(parts); }
-/** One strict ownership join, latest selection, and request fence over primary evidence only. */
-export function projectWakeEligibility(input) {
-    const ownersBySession = new Map();
-    for (const owner of input.owners) {
-        if (owner.location !== input.location)
-            continue;
-        const key = identity(nameKey(owner.participant), owner.session);
-        const rows = ownersBySession.get(key) ?? [];
-        rows.push(owner);
-        ownersBySession.set(key, rows);
-    }
-    const ownerFor = (route) => route.location !== input.location ? undefined
-        : ownersBySession.get(identity(nameKey(route.participant), route.sessionId))?.find((row) => route.epoch === undefined || presenceEpoch(row) === route.epoch);
-    const ownedRoutes = [];
-    const latest = new Map();
-    for (const fact of input.routes) {
-        const participant = nameKey(fact.participant);
-        const owner = ownerFor(fact);
-        // Malformed legacy epoch cannot acquire an owner by coercion or enter a transport request.
-        if (owner === undefined || (fact.epoch !== undefined && typeof fact.epoch !== 'number'))
-            continue;
-        const { extra, epoch, ...route } = fact;
-        ownedRoutes.push({ route: { ...route, ...(epoch === undefined ? {} : { epoch }) }, owner });
-        latest.set(participant, Math.max(latest.get(participant) ?? Number.NEGATIVE_INFINITY, route.updatedAt));
-    }
-    const selectedByRecipient = new Map();
-    for (const owned of ownedRoutes) {
-        const key = nameKey(owned.route.participant);
-        if (owned.route.updatedAt !== latest.get(key))
-            continue;
-        const rows = selectedByRecipient.get(key) ?? [];
-        rows.push(owned);
-        selectedByRecipient.set(key, rows);
-    }
-    const pending = new Set(input.pending.map((head) => identity(nameKey(head.recipient), head.index)));
-    const seen = new Set(input.seen?.map((receipt) => identity(nameKey(receipt.recipient), receipt.index)));
-    const attemptsByAttention = new Map();
-    for (const record of input.wakeRecords) {
-        if (record.location !== input.location)
-            continue;
-        const decoded = decodeWakeEvidence(record, input.now);
-        if (decoded?.kind !== 'attempt')
-            continue;
-        const attempt = decoded.value;
-        const key = identity(nameKey(attempt.attention.recipient), attempt.attention.actIndex);
-        const rows = attemptsByAttention.get(key) ?? [];
-        rows.push(attempt);
-        attemptsByAttention.set(key, rows);
-    }
-    const presentedSessions = new Set();
-    for (const row of input.presentations) {
-        if (row.location !== input.location || (row.outcome !== 'presented' && row.outcome !== 'clipped'))
-            continue;
-        presentedSessions.add(identity(nameKey(row.participant), row.activity, row.sessionId));
-    }
-    const isPresented = (route, actIndex) => presentedSessions.has(identity(nameKey(route.participant), formatActivityId(actIndex), route.sessionId));
-    const isCancelled = (owner, actIndex) => actIndex <= (owner.cancelledThrough ?? -1);
-    const bindingCurrent = (owner) => input.bindings === undefined
-        || input.bindings.some((captured) => sameBinding(captured, owner));
-    return {
-        evidence(recipient, actIndex) {
-            const key = nameKey(recipient);
-            // Accepted/unknown exclusion belongs to attention, not to a surviving owner or route kind.
-            const attempts = attemptsByAttention.get(identity(key, actIndex)) ?? [];
-            const terminal = attempts.findLast((attempt) => attempt.outcome === 'accepted')
-                ?? attempts.findLast((attempt) => attempt.outcome === 'unknown');
-            const routes = (selectedByRecipient.get(key) ?? []).filter(({ owner }) => !isCancelled(owner, actIndex));
-            const presented = routes.length > 0 && routes.every(({ route }) => isPresented(route, actIndex));
-            return {
-                delivered: seen.has(identity(key, actIndex)), presented, attempts,
-                ...(terminal === undefined ? {} : { terminal }),
-                attemptableRoutes: terminal === undefined && pending.has(identity(key, actIndex))
-                    ? routes.filter(({ route, owner }) => bindingCurrent(owner) && !isPresented(route, actIndex)).map(({ route }) => route) : [],
-            };
-        },
-        currentness(request) {
-            const actIndex = parseActivityId(request.activity);
-            const route = request.route;
-            const sameRecipient = nameKey(request.participant) === nameKey(route.participant);
-            const sameLocation = request.location === input.location && route.location === input.location;
-            const activityPending = actIndex !== undefined && request.location === input.location
-                && pending.has(identity(nameKey(request.participant), actIndex));
-            const owner = sameLocation && sameRecipient ? ownerFor(route) : undefined;
-            const sessionBound = owner !== undefined && bindingCurrent(owner);
-            const matchesRequest = (published) => published.location === route.location
-                && nameKey(published.participant) === nameKey(route.participant) && published.sessionId === route.sessionId
-                && published.kind === route.kind && published.epoch === route.epoch && Object.keys(published.address).length === Object.keys(route.address).length && Object.keys(published.address).every((key) => published.address[key] === route.address[key]);
-            const routePublished = sameLocation && sameRecipient && input.routes.some(matchesRequest);
-            const selectedOwner = sameLocation && sameRecipient
-                && (selectedByRecipient.get(nameKey(route.participant)) ?? []).some(({ route: published }) => matchesRequest(published));
-            const cancelled = actIndex !== undefined && owner !== undefined && isCancelled(owner, actIndex);
-            const presented = actIndex !== undefined && sameLocation && sameRecipient && isPresented(route, actIndex);
-            // Dispatching evidence deliberately does not fence the request that owns the atomic claim.
-            return { current: activityPending && sessionBound && routePublished && selectedOwner && !cancelled && !presented,
-                activityPending, sessionBound, routePublished, selectedOwner, cancelled, presented };
-        },
-    };
-}
-/** Host observation happens only after detached artifact facts have left their transaction. */
-export async function projectWakeEvidence(input) {
-    const location = await canonicalPath(input.location);
-    const owners = input.owners ?? await input.hostLedger.listPresence({ location, now: input.now });
-    const records = await input.hostLedger.listEvidence({ location, now: input.now });
-    const presentations = records.filter((row) => row.kind === 'presentation').map((row) => ({
-        location: row.location, participant: row.participant, sessionId: row.session, activity: row.activity, outcome: row.outcome,
-        ...(row.at === undefined ? {} : { at: row.at }),
-    }));
-    return projectWakeEligibility({ ...input, location, owners, wakeRecords: records.filter((row) => row.kind === 'wake'), presentations });
-}
-export function sameBinding(captured, current) {
-    return captured.location === current.location && nameKey(captured.participant) === nameKey(current.participant)
-        && captured.session === current.session && captured.channel === current.channel && captured.epoch === current.epoch
-        && (captured.cancelledThrough ?? -1) === (current.cancelledThrough ?? -1);
-}
-export function wakeIsEligible(evidence) {
-    return !evidence.delivered && !evidence.presented && evidence.terminal === undefined && evidence.attemptableRoutes.length > 0;
-}

package/dist/wake-evidence.d.ts

@@ -1,33 +0,0 @@
-import type { EvidenceRecord, WakeAttention, NativeDeliveryObservation } from './host-ledger.js';
-import type { WakeRouteKind } from './model.js';
-export interface WakeAttempt {
-    readonly nativeObservations?: readonly NativeDeliveryObservation[];
-    readonly at: number;
-    readonly attention: WakeAttention;
-    readonly routeKind: WakeRouteKind;
-    readonly outcome: 'accepted' | 'unknown' | 'failed';
-    readonly signature?: string;
-    readonly attemptN: number;
-    readonly session?: string;
-    readonly message?: string;
-    readonly diagnostic?: unknown;
-}
-export interface WakeReleaseDiagnostic {
-    readonly at: number;
-    readonly attention: WakeAttention;
-    readonly routeKind?: WakeRouteKind;
-    readonly attemptN?: number;
-    readonly session?: string;
-    readonly signature?: string;
-    readonly message?: string;
-    readonly diagnostic?: unknown;
-}
-export type DecodedWakeEvidence = {
-    readonly kind: 'attempt';
-    readonly value: WakeAttempt;
-} | {
-    readonly kind: 'release';
-    readonly value: WakeReleaseDiagnostic;
-};
-/** Decode primary attempts and diagnostic-only releases without mixing their evidence. */
-export declare function decodeWakeEvidence(record: EvidenceRecord, now: number): DecodedWakeEvidence | undefined;

package/dist/wake-evidence.js

@@ -1,32 +0,0 @@
-import { parseActivityId } from './square-core.js';
-/** Decode primary attempts and diagnostic-only releases without mixing their evidence. */
-export function decodeWakeEvidence(record, now) {
-    if (record.kind !== 'wake')
-        return undefined;
-    const actIndex = parseActivityId(record.activity);
-    if (actIndex === undefined)
-        return undefined;
-    const value = {
-        at: record.at ?? now,
-        attention: { squarePath: record.location, recipient: record.participant, actIndex },
-        ...(record.session === undefined ? {} : { session: record.session }),
-        ...(record.signature === undefined ? {} : { signature: record.signature }),
-        ...(record.message === undefined ? {} : { message: record.message }),
-        ...(record.diagnostic === undefined ? {} : { diagnostic: record.diagnostic }),
-    };
-    if (record.outcome === 'released') {
-        if (record.at === undefined)
-            return undefined;
-        return { kind: 'release', value: {
-                ...value,
-                ...(record.routeKind === undefined ? {} : { routeKind: record.routeKind }),
-                ...(record.attemptN === undefined ? {} : { attemptN: record.attemptN }),
-            } };
-    }
-    if (record.outcome !== 'accepted' && record.outcome !== 'unknown' && record.outcome !== 'failed')
-        return undefined;
-    if (record.routeKind === undefined || typeof record.attemptN !== 'number')
-        return undefined;
-    return { kind: 'attempt', value: { ...value, routeKind: record.routeKind, attemptN: record.attemptN, outcome: record.outcome,
-            ...(record.nativeObservations === undefined ? {} : { nativeObservations: record.nativeObservations }) } };
-}

package/guides/host-ledger.md

@@ -1,58 +0,0 @@
-# Host ledger
-
-Square uses one user-level `host-ledger.sqlite` for participant bindings, delivery evidence, and wake attempts. It is separate from every `.square` artifact: the ledger owns host identity, ownership epochs, discovery and delivery evidence; the artifact owns square activity and participant lifecycle.
-
-The default root is `~/.square/host-ledger`. Tests and isolated harnesses may set `SQUARE_HOST_LEDGER_ROOT`; otherwise `SQUARE_REGISTRY` selects its containing directory. An explicit adapter `rootPath` takes precedence. These settings select a single root, not additional ledgers.
-
-## Storage and delivery
-
-SQLite uses DELETE journaling and FULL synchronous writes. Records retain original order and duplicates, with derived lookup indexes and separate presence/evidence revisions. Normal reads of an empty root create nothing. First mutation initializes storage only when neither legacy NDJSON file exists. Legacy-only storage refuses ordinary operation and requires explicit offline conversion; normal operation never dual-reads or automatically migrates.
-
-One wake attempt is one evidence record. Acquisition creates `dispatching` directly, before a send may happen. An interrupted dispatch becomes `unknown`, which forbids redispatch; current token-fenced recovery may still accept a late native admission. Accepted and possibly-sent wake records remain readable at any age. Prepared Claude correlations also bypass age visibility and housekeeping across every outcome, including failed and released, until explicitly retired. Ordinary records retain their existing seven-day visibility horizon, with expired ordinary rows reclaimed only during actual mutations. There is no automatic maintenance GC or activity-id-only sweep; durable delivery evidence is retired only by the explicit, artifact-proven `square ledger gc` below.
-
-## Verify and convert offline
-
-These commands need no participant or square location and use the resolved ledger root:
-
-```bash
-square ledger verify
-```
-
-Verification is read-only. It checks SQLite identity, version, schema, integrity, record codecs, derived indexes and revisions. With only legacy files, it scans both complete sources and reports accepted, ignored and rejected counts, readiness, and SHA-256 hashes of the original source bytes. Unsafe indexed records make readiness false without hiding the remaining counts or hashes; the CLI reports not ready and exits with status 2. With no files, it reports empty without creating a directory, database or lock. Output never includes record payloads, native credentials or endpoints.
-
-To upgrade an NDJSON ledger:
-
-1. Stop **every** agent session and MCP service using Square with this ledger, including interactive harnesses and background agents. Do not run old and new ones together.
-2. Keep a backup of the stopped legacy files.
-3. Run:
-
-   ```bash
-   square ledger verify
-   square ledger migrate
-   square ledger verify
-   ```
-
-4. Start all hosts with the updated Square version together, using the same root.
-
-Migration does not stop or restart hosts. Its locks fence compatible writers but do not prove hosts are stopped. It acquires the ownership claim fence, then `presence.ndjsonl.lock`, then `evidence.ndjsonl.lock`.
-
-An older SQLite ledger format is upgraded in place by the same `square ledger migrate` under the same stopped-sessions prerequisite and the same lock order. The upgrade preserves every record, duplicate, original order and both observer revisions. `square ledger verify` stays read-only: it reports a supported old format with the migrate command and never upgrades silently. An unsupported format version or an unrelated database is refused with a diagnosis path instead: migration is not a repair command, and a failed migration is never answered by rerunning it blindly.
-
-The importer preserves all ages, future records, duplicates, original order, native correlation and residual fields. It ignores malformed JSON, wrong versions and records without a numeric timestamp, as the old reader did, and reports those counts. Any valid version-1 record whose indexed fields are unsafe refuses the entire conversion rather than losing evidence. Refusal identifies only source kind, rejected count and first rejected line; no accepted subset is published. Legacy unknown wake sources are normalized once during import.
-
-A temporary SQLite database is built and verified under the same root, then published without overwriting an existing destination. Legacy sources remain byte-for-byte untouched. A valid existing SQLite ledger is an idempotent no-op; an older SQLite ledger format is upgraded in place under the fence; invalid or unsupported destinations are refused without repair. There is no force option. On a reported failure, keep hosts stopped, resolve the cause and rerun verification/conversion. An abrupt process termination can leave an unpublished `.host-ledger-migrate-*` directory; after confirming no converter is running, it can be removed without touching the sources or published database.
-
-Once SQLite exists, legacy files are not consulted. Keeping them does not provide a rollback path after new SQLite writes: reverting to them would lose ownership and possibly-sent evidence. For a live SQLite ledger, use SQLite backup facilities rather than copying only its main file.
-
-## Reclaim old evidence
-
-```bash
-square ledger gc --dry-run
-square ledger gc
-```
-
-`gc` considers wake and presentation evidence at least seven days old whose attention is permanently closed, proven per row against the square artifact named in the row: the activity historically reached that participant, and either catch recorded an exact receipt or the participant's later rejoin moved past it. Rows still `dispatching`, lifecycle rows, rows with unusable coordinates and rows whose artifact is missing, invalid or unreadable are retained. Eligibility is a proof, not a promise: `retired` counts rows actually removed, and a row whose record changed after the proof, or whose Claude correlation cannot be retired safely, is retained instead. `--dry-run` proves the same set and changes neither the ledger nor any artifact.
-
-Reclamation is counted in rows, not bytes. Deleted rows free storage for reuse but do not necessarily shrink the SQLite file immediately; `gc` never runs `VACUUM`. Retiring a prepared Claude correlation payload leaves only a permanent `(harness, session, token)` recognition record, without payload, endpoint, location, participant, epoch or timestamp. These records are absent from ordinary evidence and attempts and confer no admission, presentation or receipt authority. Any retired token vetoes the entire native frame, including a mixed live/retired frame. Total token count remains unbounded. There are no hooks, timers or install steps: maintenance runs only when asked.
-
-The obsolete `SQUARE_HOST_LEDGER_USER` and `SQUARE_HOST_LEDGER_LOCAL` settings, project-local fallback and scope-based copying are not used. Older local files and `wake-claims.ndjsonl` remain untouched and are not imported. Bindings that existed only in those abandoned stores require their host to rejoin; do not discard the supported ledger to reset bindings.

package/guides/indexed-host-ledger-performance.md

@@ -1,39 +0,0 @@
-# Indexed host-ledger measurement
-
-The indexed host ledger eliminates whole-file NDJSON reads. This run does not show a consistent reduction in the 300-process catch-phase latency: the smaller-history case was slightly slower and the larger-history case was faster. Artifact contention remains substantial.
-
-## Comparable workload
-
-Baseline: `895ff50` (NDJSON with origin-separated instrumentation). SQLite plus safe retirement candidate: `60ea8b0`. Both used the same benchmark script, 300 processes, session discovery, active bell, disabled filesystem hints, and histories of 1,800 and 18,000 unrelated activities.
-
-```sh
-node --import ./test/sandbox-env.js scripts/benchmark-idle-wait.mjs --workers 300 --mode session --active --no-hints
-```
-
-The catch phase times opening the square, recognizing the participant, a first catch, a second catch checking duplicate consumption, and closing the square. These numbers are **not single-catch latency**, nor ordinary single-user latency. Discovery is measured separately. These are one completed run per implementation and history size, not repeated-run confidence intervals.
-
-| Metric | NDJSON, 1,800 | SQLite, 1,800 | NDJSON, 18,000 | SQLite, 18,000 |
-| --- | ---: | ---: | ---: | ---: |
-| Catch-phase p50 (ms) | 6,134.67 | 6,159.17 | 6,775.98 | 5,532.52 |
-| Catch-phase p95 (ms) | 7,307.72 | 7,481.01 | 8,182.00 | 7,170.30 |
-| Catch-phase aggregate CPU (ms) | 24,171.34 | 24,045.67 | 27,538.51 | 23,574.19 |
-| Artifact busy observations | 46,710 | 52,686 | 56,401 | 46,069 |
-| Catch-phase artifact body rows | 300 | 300 | 300 | 300 |
-| Catch-phase artifact writes | 600 | 600 | 600 | 600 |
-| Discovery p95 (ms) | 1,931 | 1,927 | 1,881 | 1,915 |
-
-Every completed scenario discovered all 300 participants, consumed exactly one activity per participant, and consumed none again on the second catch.
-
-## Ledger work
-
-For either history size, the NDJSON catch phase performed 1,500 file reads totaling 95,520,000 bytes. The SQLite catch phase performed 1,500 data-read executions, returning 1,500 presence rows; all SQL result values together totaled 316,900 bytes (4,500 rows including header results). Host-ledger SQL busy observations were zero.
-
-These are different transport measurements: file bytes versus SQL values returned to JavaScript. They demonstrate that whole-ledger materialization is gone; they do **not** measure equivalent physical disk I/O or prove a proportional speedup. SQLite bypasses the JavaScript filesystem hooks, so zero NDJSON operations/bytes is structural, not a standalone performance result.
-
-The remaining catch-phase contention is attributed to the square artifact, separately from the host ledger. The result motivates investigating concurrent artifact transactions if reducing this latency is the next objective; it does not establish the benefit of any unimplemented change.
-
-## Evidence and limits
-
-Local raw reports: `/tmp/square-indexed-baseline-300.json` and `/tmp/square-indexed-final-300.json`. The completed SQLite run exited zero with empty stderr. An earlier invocation was terminated by the tool's 60-second execution limit before producing a report and was excluded; the completed run used the unchanged workload in a background process.
-
-This benchmark uses an isolated ledger. It does not migrate the live host ledger, exercise real native transports, or measure GC reclamation. GC correctness is covered by the separate retirement, closure-proof, schema-upgrade, and CLI tests. Retirement leaves reusable SQLite pages and indefinitely retained Claude recognition tokens; neither immediate file shrinkage nor bounded total token growth is promised.