Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs(key-files): near-name and review-list entries under core services

garrytandb264f875114
diff --git a/docs/architecture/key-files/core-memory.md b/docs/architecture/key-files/core-memory.md
index 935b56a796..c4582623af 100644
--- a/docs/architecture/key-files/core-memory.md
+++ b/docs/architecture/key-files/core-memory.md
@@ -64,5 +64,3 @@ notice). User guide: [core memory](../../guides/core-memory.md).
`test/remember-batch-entity-7432.test.ts`,
`test/trust-cache-invalidation.test.ts` (core lane after trust transitions),
`test/e2e/core-memory-locks-postgres.test.ts`.
-- `src/core/entities/near-name.ts` — Flag-only near-name matcher for #2942 (never merges, never writes `entity_identities`; `entity-identity.ts` stays manual-only). `classifyNearName` returns `same` (normalized-equal after corporate suffixes, or a strong `name-variants.ts` shape), `typo` (Damerau distance 1 on 3–64 normalized characters) or `acronym` (one word equals a multi-word name's initials, at most one letter different). Candidates come from symmetric one-deletion keys plus initials keys, so recall is complete for those kinds; past `NEAR_NAME_MAX_KEYS_PER_SHARD` the index splits into shards by key hash (a pair shares a key, so it lands whole in one shard). `loadEntityNames` reads one source's fact-entity pages plus the source pack's linkable types, leaving out private pages for callers that exclude them. Pinned by `test/review-lists.test.ts`.
-- `src/core/review-lists.ts` — The two lists `extraction_pending` adds beside `pending`: `unattributed` (active facts with no entity, newest first, world-only for remote callers, each with a `remember` + `entity` + `replaces` relink action, never a forget) and opt-in `possible_duplicates` (entity pages created in the last `since_days` whose name is near another entity's name or alias; pairs in `aliases` or `distinct_from` are skipped). The duplicates cursor walks recent pages within a shard, then the next shard, and reports `complete` only after the last shard; index builds are serialized per process. Pinned by `test/review-lists.test.ts` and the Postgres parity file.
diff --git a/docs/architecture/key-files/core-services-1-continued.md b/docs/architecture/key-files/core-services-1-continued.md
index 455e4cc1d9..2a2ceef85c 100644
--- a/docs/architecture/key-files/core-services-1-continued.md
+++ b/docs/architecture/key-files/core-services-1-continued.md
@@ -14,3 +14,5 @@ The content-repair judgment tier under `src/core/content-repair/`, then the Retr
- `src/core/context/seat.ts` — seat identity for captured sessions (#4618), engine-free. `resolveSeat` returns the lowercased `GBRAIN_SEAT` label when it matches `SEAT_LABEL_RE` (`^[a-z0-9][a-z0-9._-]{0,63}$`), else `home-<8 hex>` over the realpath of the harness home (Claude Code: the directory holding `projects/` in the transcript path, then `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `~/.claude`; codex: `CODEX_HOME` or `~/.codex`; OpenClaw: the agent directory holding `sessions/`), so no raw path reaches frontmatter; `GBRAIN_SEAT=off` (the opt-out) resolves to null and nothing is recorded. `writeSeatSidecar` writes `<sessionId>.seat.json` (`{version: 1, seat, seat_source, hook_lane, harness, first_seen}`, 0600, tmp+rename) unless one exists, reporting `seat_conflict` when the existing seat differs; `readSeatSidecar` accepts only a valid v1 record. `SEAT_REASON_HINTS` holds the fixed heartbeat hints. The sidecar name and its GC live in `corpus-segments.ts` (`seatFileName`, `SEAT_SIDECAR_SUFFIX`).
- `src/core/context/ipc-path.ts` — engine-free local socket discovery and private Unix fallback when the complete role-specific address exceeds 103 UTF8 bytes. Hashes the physical parent plus basename under a fixed OS temporary root, verifies ownership/0700 directory/0600 client socket without following fallback symlinks, and retains a native binding claim through actual server close. Existing Unix socket accessibility is rechecked even when a runtime reports ENOENT; permission/resource probe failures never authorize stale takeover; on Windows a PGLite data-dir socket (`.gbrain-<kind>.sock`) over afunix's 107 UTF-8 bytes moves to `%USERPROFILE%\.gbrain\run\<kind>-<hash12(canonical data dir, case-folded)>.sock` (`windowsLocalIpcSocketPath`, the Postgres run-dir scheme; the secret stays in the data dir), and `localIpcPathTooLong` reports a resolved path still over the platform budget, which `ipc-path-too-long.ts` turns into the typed `ipc_path_too_long` serve log line and doctor `ipc_socket_path` warning (#6573; `test/ipc-path-windows-fallback-6573.test.ts` on every OS, the native bind and 20-cycle stability probe in `test/windows-ipc-long-path-6573.serial.test.ts` on windows-latest); Windows named pipes retain a native Global mutex through actual close; `windows-ipc.ts` normalizes namespace prefixes while native Windows Unicode casing defines the mutex identity. `test/local-ipc-path.test.ts` covers concurrent real processes, SIGKILL recovery, active-connection shutdown, aliases and unsafe paths. The published CLI smoke also uses a long Unicode datastore path.
+- `src/core/entities/near-name.ts` — Flag-only near-name matcher for #2942 (never merges, never writes `entity_identities`; `entity-identity.ts` stays manual-only). `classifyNearName` returns `same` (normalized-equal after corporate suffixes, or a strong `name-variants.ts` shape), `typo` (Damerau distance 1 on 3–64 normalized characters) or `acronym` (one word equals a multi-word name's initials, at most one letter different). Candidates come from symmetric one-deletion keys plus initials keys, so recall is complete for those kinds; past `NEAR_NAME_MAX_KEYS_PER_SHARD` the index splits into shards by key hash (a pair shares a key, so it lands whole in one shard). `loadEntityNames` reads one source's fact-entity pages plus the source pack's linkable types, leaving out private pages for callers that exclude them. Pinned by `test/review-lists.test.ts`.
+- `src/core/review-lists.ts` — The two lists `extraction_pending` adds beside `pending`: `unattributed` (active facts with no entity, newest first, world-only for remote callers, each with a `remember` + `entity` + `replaces` relink action, never a forget) and opt-in `possible_duplicates` (entity pages created in the last `since_days` whose name is near another entity's name or alias; pairs in `aliases` or `distinct_from` are skipped). The duplicates cursor walks recent pages within a shard, then the next shard, and reports `complete` only after the last shard; index builds are serialized per process. Pinned by `test/review-lists.test.ts` and the Postgres parity file.