@astrosheep/square 0.3.72 → 0.3.73

package/guides/host-ledger.md

@@ -1,11 +1,58 @@
-# Host Ledger Configuration
+# Host ledger
 
-Square uses one user-level host ledger for participant bindings, delivery evidence, and wake attempts.
+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.
 
-One wake attempt is one `evidence.ndjsonl` row: it carries the attention-wide exclusion for a recipient and activity, and the session-scoped history for that attempt. A row is `claimed` before any send and `dispatching` from the moment a send may happen; a stale `claimed` row is replaceable, while a stale `dispatching` row becomes `unknown` and forbids redispatch. Accepted and possibly-sent wake attempts stay readable at any age, and are eligible for explicit `gcEvidence` removal once their activity is no longer pending. Older Square versions kept a separate `wake-claims.ndjsonl`; that file is no longer read or written, and is left on disk untouched. Running old and new processes against the same ledger at once is unsupported: restart every host process together when upgrading.
+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.
 
-The default root is `~/.square/host-ledger`. Tests and isolated harnesses may set `SQUARE_HOST_LEDGER_ROOT`; when it is absent, `SQUARE_REGISTRY` provides the test root. An explicit `rootPath` passed to a ledger adapter takes precedence over both environment defaults.
+## Storage and delivery
 
-The old `SQUARE_HOST_LEDGER_USER` and `SQUARE_HOST_LEDGER_LOCAL` settings, project-local `.square/host-ledger` fallback, scope arguments, and reconcile-based copying are removed. Existing local ledger files and directories are left untouched but are no longer read. Bindings that existed only in an old local ledger require the participant to rejoin or restart its host session.
+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.
 
-The host ledger remains separate from the `.square` artifact: it owns host identity, ownership epochs, discovery, and delivery evidence. The artifact remains authoritative for square activity and participant lifecycle.
+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** Square host using that ledger, including interactive harnesses and background agents. Do not run old and new hosts 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-hosts 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 refuses an older or unsupported database with the migrate command and never upgrades silently.
+
+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

@@ -0,0 +1,39 @@
+# 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.72",
+  "version": "0.3.73",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.72",
+  "version": "0.3.73",
   "description": "Native Claude Code inbox delivery for Square participants",
   "types": "./types.d.ts",
   "author": {

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.72",
+  "version": "0.3.73",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/plugins/paseo/client/square-message.tsx

@@ -1,7 +1,7 @@
 import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
 import { copyText, Icon, useToast } from "@getpaseo/plugin/client/react-native";
 import { useMemo, useState } from "react";
-import { Platform, Pressable, Text, View } from "react-native";
+import { Platform, Pressable, ScrollView, Text, View } from "react-native";
 import { squareHeadline, type SquareMessageData } from "../shared/message";
 
 function withOpacity(color: string, opacity: number): string {
@@ -28,7 +28,7 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
     bodyPanel: {
       backgroundColor: theme.colors.surface1,
       borderRadius: 12,
-      marginTop: 7,
+      marginTop: 5,
       marginLeft: 17,
       overflow: "hidden" as const,
     },
@@ -37,20 +37,14 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
       fontSize: 12,
       lineHeight: 21,
       fontFamily: Platform.OS === "ios" ? "Menlo" : "monospace",
-      paddingHorizontal: layout.compact ? 12 : 14,
-      paddingTop: 12,
+      paddingHorizontal: layout.compact ? 10 : 12,
+      paddingTop: 8,
     },
-  }), [expanded, foreground, layout.compact, muted, theme.colors.accent, theme.colors.surface1]);
+  }), [foreground, layout.compact, muted, theme.colors.accent, theme.colors.surface1]);
 
   return (
     <View>
-      <Pressable
-        accessibilityRole="button"
-        accessibilityLabel={latest !== undefined ? squareHeadline(latest) : "Square context"}
-        aria-expanded={expanded}
-        onPress={() => setExpanded(value => !value)}
-        style={({ pressed }) => ({ opacity: pressed ? 0.6 : 1 })}
-      >
+      <View>
         <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 7, paddingVertical: 2 }}>
           <Text style={styles.marker}>■</Text>
           <Text numberOfLines={1} style={styles.headline}>
@@ -58,7 +52,16 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
           </Text>
           {items && items.length > 1 && <Text style={styles.meta}>· {items.length} landed</Text>}
           <View style={{ flex: 1 }} />
-          <View style={{ marginTop: 3 }}><Icon name={expanded ? "ChevronDown" : "ChevronRight"} size={14} color={muted} /></View>
+          {!expanded && <Pressable
+            accessibilityRole="button"
+            accessibilityLabel={`展开 ${latest !== undefined ? squareHeadline(latest) : "Square context"}`}
+            aria-expanded={false}
+            onPress={() => setExpanded(true)}
+            hitSlop={6}
+            style={({ pressed }) => ({ padding: 5, opacity: pressed ? 0.6 : 1 })}
+          >
+            <Icon name="ChevronDown" size={18} color={muted} />
+          </Pressable>}
         </View>
         {(latest?.actor !== undefined || preview) && <View style={{ marginLeft: 17, marginTop: 2 }}>
           <Text numberOfLines={1} style={styles.preview}>
@@ -67,17 +70,20 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
             {preview}
           </Text>
         </View>}
-      </Pressable>
+      </View>
       {expanded && <View style={styles.bodyPanel}>
-        <Text selectable style={styles.bodyText}>{text}</Text>
+        <ScrollView style={{ maxHeight: layout.compact ? 280 : 400 }} nestedScrollEnabled>
+          <Text selectable style={styles.bodyText}>{text}</Text>
+        </ScrollView>
         <View style={{
-          marginHorizontal: layout.compact ? 12 : 14,
-          marginTop: 12,
+          marginHorizontal: layout.compact ? 10 : 12,
+          marginTop: 5,
           borderTopWidth: 1,
           borderTopColor: withOpacity(theme.colors.border, 0.55),
-          paddingVertical: 7,
+          paddingVertical: 3,
           flexDirection: "row",
-          justifyContent: "flex-end",
+          alignItems: "center",
+          justifyContent: "space-between",
         }}>
           <Pressable
             accessibilityRole="button"
@@ -94,6 +100,16 @@ export function SquareMessage({ item, theme, layout }: PluginTimelineItemProps<S
             <Icon name="Copy" size={12} color={muted} />
             <Text style={{ color: muted, fontSize: 11 }}>Copy content</Text>
           </Pressable>
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel="收起 Square context"
+            aria-expanded={true}
+            onPress={() => setExpanded(false)}
+            hitSlop={6}
+            style={({ pressed }) => ({ paddingHorizontal: 5, paddingVertical: 1, opacity: pressed ? 0.6 : 1 })}
+          >
+            <Icon name="ChevronUp" size={18} color={muted} />
+          </Pressable>
         </View>
       </View>}
     </View>