@remnic/core 9.69.56 → 9.69.57

package/dist/peers/migrate-from-identity-anchor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Identity-anchor → peer-registry migration — issue #679 PR 5/5.
+ *
+ * Reads the legacy `identity/identity-anchor.md` file (written by
+ * `StorageManager.writeIdentityAnchor`) and the `IDENTITY.md`
+ * reflections file, then seeds the peer registry with a `self` peer
+ * whose `peers/self/identity.md` kernel captures the relevant
+ * source material.
+ *
+ * Design principles:
+ *
+ * 1. **Idempotent** — if `peers/self/identity.md` already exists this
+ *    function returns `{ skipped: true }` without overwriting it. The
+ *    second-run guarantee prevents accidental double-migration and
+ *    makes `remnic peer migrate` safe to run in CI / post-install hooks.
+ *
+ * 2. **Non-destructive** — the legacy files are never deleted. The
+ *    operator is responsible for archive / clean-up after verifying the
+ *    migration result. Legacy `engram.identity_anchor_*` MCP tools
+ *    continue to work against the on-disk anchor file.
+ *
+ * 3. **Dry-run** — when `options.dryRun` is `true` the function
+ *    computes the proposed `Peer` record and returns it alongside a
+ *    `{ dryRun: true }` marker, without writing anything to disk.
+ *
+ * 4. **Transparent** — the return value always includes the full
+ *    proposed `Peer` so callers can print what was (or would be) written.
+ *
+ * ## Source data
+ *
+ * The migrator reads two optional legacy sources:
+ *
+ * - `{memoryDir}/identity/identity-anchor.md` — structured sections
+ *   (`## Identity Traits`, `## Communication Preferences`, etc.) written
+ *   by `identityAnchorUpdate`. When present, the full content is
+ *   embedded in `peer.notes` under a clearly labelled subsection.
+ *
+ * - `{memoryDir}/IDENTITY.md` — free-form reflection entries appended
+ *   by the extraction engine. When present it is summarised as
+ *   a second subsection of `peer.notes`.
+ *
+ * If neither file exists the `self` peer is still created with sensible
+ * defaults so that the peer registry is bootstrapped for fresh installs.
+ *
+ * ## Path safety
+ *
+ * All file reads use `path.join` relative to the caller-supplied
+ * `memoryDir`. The migration never follows symlinks for the source files
+ * (uses `lstat` to detect + skip them). Writes go through the standard
+ * peer storage helpers which enforce path-traversal and symlink guards.
+ */
+import type { Peer } from "./types.js";
+/** Options for `migrateFromIdentityAnchor`. */
+export interface MigrateFromIdentityAnchorOptions {
+    /**
+     * Memory directory (same value as `config.memoryDir`). All source and
+     * destination paths are resolved relative to this root.
+     */
+    memoryDir: string;
+    /**
+     * When `true`, compute and return the proposed peer record without
+     * writing anything to disk. The `written` and `skipped` flags in the
+     * result will both be `false`; the `peer` field carries the proposed
+     * record.
+     */
+    dryRun?: boolean;
+    /**
+     * Optional override for the `self` peer's display name. Defaults to
+     * `"Self"`.
+     */
+    displayName?: string;
+    /**
+     * Optional ISO-8601 timestamp to use as `createdAt`. When omitted the
+     * current time is used.
+     */
+    createdAt?: string;
+}
+/** Result returned by `migrateFromIdentityAnchor`. */
+export interface MigrateFromIdentityAnchorResult {
+    /**
+     * The peer record that was (or would be) written for `peers/self/`.
+     * Always present regardless of `skipped` or `dryRun`.
+     */
+    peer: Peer;
+    /**
+     * `true` when the migration wrote `peers/self/identity.md` to disk.
+     * `false` when `dryRun` is set or the file already existed (`skipped`).
+     */
+    written: boolean;
+    /**
+     * `true` when an existing `peers/self/identity.md` was detected and
+     * the migration was a no-op. When `skipped` is `true`, `written` is
+     * always `false`.
+     */
+    skipped: boolean;
+    /**
+     * `true` when `options.dryRun` was set. No files were written; the
+     * `peer` field holds the proposed record.
+     */
+    dryRun: boolean;
+    /**
+     * The identity-anchor source file path that was read (if found).
+     * `null` when the file did not exist or was a symlink (skipped).
+     */
+    identityAnchorSource: string | null;
+    /**
+     * The `IDENTITY.md` source file path that was read (if found).
+     * `null` when the file did not exist or was a symlink (skipped).
+     */
+    identityMdSource: string | null;
+}
+/**
+ * Migrate legacy identity-anchor data into `peers/self/identity.md`.
+ *
+ * @see {@link MigrateFromIdentityAnchorOptions} for full option documentation.
+ * @see {@link MigrateFromIdentityAnchorResult} for return value semantics.
+ */
+export declare function migrateFromIdentityAnchor(options: MigrateFromIdentityAnchorOptions): Promise<MigrateFromIdentityAnchorResult>;
+//# sourceMappingURL=migrate-from-identity-anchor.d.ts.map

package/dist/peers/migrate-from-identity-anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-from-identity-anchor.d.ts","sourceRoot":"","sources":["../../src/peers/migrate-from-identity-anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAMvC,+CAA+C;AAC/C,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,IAAI,EAAE,IAAI,CAAC;IAEX;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAyGD;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,+BAA+B,CAAC,CA0E1C"}

package/dist/peers/profile-reasoner.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Peer profile reasoner — issue #679 PR 2/5.
+ *
+ * Pure async function that, for each peer:
+ *
+ *   1. Reads recent interaction-log entries via `readPeerInteractionLog`.
+ *   2. Calls an injected LLM client (same chat shape as
+ *      `FallbackLlmClient.chatCompletion`) to derive 0..N profile-field
+ *      proposals with provenance `{observedAt, signal, sourceSessionId,
+ *      note}`.
+ *   3. Merges the proposals into the peer's existing `PeerProfile`,
+ *      appending provenance entries (never replacing existing
+ *      provenance — the reasoner is additive by design so the operator
+ *      retains the full audit trail).
+ *   4. Writes via `writePeerProfile`.
+ *
+ * Gating is handled in two layers:
+ *
+ *   - The orchestrator wires the call behind the
+ *     `peerProfileReasonerEnabled` config flag (default `false` —
+ *     opt-in per Gotcha #30/#48). The reasoner ALSO short-circuits
+ *     when `options.enabled !== true`, so direct callers can't
+ *     accidentally bypass the flag.
+ *   - Per-peer, the `peerProfileReasonerMinInteractions` threshold
+ *     skips peers whose log has fewer entries since the last reasoner
+ *     run than required.
+ *
+ * The reasoner is intentionally storage-agnostic — it accepts an LLM
+ * client by interface (`PeerProfileReasonerLlm`) so tests can mock the
+ * call and the orchestrator can inject either the gateway client or
+ * a fast local model. No direct OpenAI imports here.
+ */
+import type { Peer, PeerInteractionLogEntry, PeerProfile } from "./types.js";
+/**
+ * Minimal chat-completion contract the reasoner depends on. Matches
+ * `FallbackLlmClient.chatCompletion` so the orchestrator can pass it
+ * through directly. Tests inject a mock that returns canned strings.
+ *
+ * Returning `null` means the LLM is unavailable / failed — the
+ * reasoner treats that as "no proposals for this peer" rather than an
+ * error so a flaky LLM never aborts the whole pass.
+ */
+export interface PeerProfileReasonerLlm {
+    chatCompletion(messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>, options?: {
+        temperature?: number;
+        maxTokens?: number;
+        timeoutMs?: number;
+    }): Promise<{
+        content: string;
+    } | null>;
+}
+/**
+ * One LLM-proposed profile-field update.
+ *
+ * `value` is the new markdown string to set under `field`. The
+ * provenance entry the LLM emits travels alongside it; the reasoner
+ * does NOT trust the LLM's `observedAt` — it always overwrites with
+ * the run's `now` timestamp so provenance can never claim future or
+ * past observation timestamps the operator didn't witness.
+ */
+export interface PeerProfileReasonerProposal {
+    /** Stable section key, e.g. "communication_style". */
+    readonly field: string;
+    /** Markdown value to set under that key. */
+    readonly value: string;
+    /**
+     * Short label for the signal that justified the inference,
+     * e.g. "explicit_preference", "tool_pattern", "topic_recurrence".
+     */
+    readonly signal: string;
+    /** Optional free-form note explaining the inference. */
+    readonly note?: string;
+    /**
+     * Originating session id, when the LLM can attribute the inference
+     * to a specific log line. Reasoner clamps this to a value that
+     * actually appeared in the log window so the LLM can't hallucinate.
+     */
+    readonly sourceSessionId?: string;
+}
+export interface PeerProfileReasonerOptions {
+    /** Memory directory containing the peers/ subtree. */
+    readonly memoryDir: string;
+    /**
+     * Master gate. When `false` (the default the orchestrator passes
+     * when the config flag is off), the reasoner is a no-op and
+     * returns an empty result. Direct callers must explicitly pass
+     * `true` so the gate can never be defaulted ON by accident
+     * (Gotcha #48 — least-privileged default).
+     */
+    readonly enabled: boolean;
+    /** Injected LLM client. Required when `enabled === true`. */
+    readonly llm?: PeerProfileReasonerLlm;
+    /** Model name to log for telemetry; not used to dispatch. */
+    readonly model?: string;
+    /**
+     * Minimum new interaction-log entries since last reasoner run
+     * before this peer is processed. Peers below the threshold are
+     * skipped with `reason: "below_min_interactions"`.
+     */
+    readonly minInteractions: number;
+    /**
+     * Hard cap on profile fields the reasoner will accept across all
+     * peers in a single run. Tracked in insertion order: once the cap
+     * is reached, subsequent proposals are dropped with
+     * `dropped_due_to_cap` in the per-peer result. Use to bound LLM
+     * cost and reviewer load per pass.
+     */
+    readonly maxFieldsPerRun: number;
+    /**
+     * Optional restriction to specific peer ids. When omitted, the
+     * reasoner enumerates the entire peer registry via `listPeers`.
+     */
+    readonly peerIds?: ReadonlyArray<string>;
+    /**
+     * Maximum number of recent log entries to feed the LLM per peer.
+     * Defaults to 50. Bounded so a runaway log can't blow the prompt.
+     */
+    readonly maxLogEntriesPerPeer?: number;
+    /**
+     * Reasoner run timestamp. Defaults to `new Date()` at call time.
+     * Tests inject a deterministic clock; the orchestrator passes
+     * `new Date()` so provenance entries reflect actual wall time.
+     */
+    readonly now?: Date;
+    /**
+     * Optional logger; defaults to a no-op so the reasoner stays
+     * silent in unit tests. The orchestrator wires its `log` here so
+     * runs surface in the gateway log under the
+     * `[peer-profile-reasoner]` prefix.
+     */
+    readonly log?: {
+        debug?: (msg: string) => void;
+        info?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+    /**
+     * Whether to append a `peer_profile_reasoner_run` entry to the
+     * peer's interaction log when the reasoner emits at least one
+     * field for that peer. Defaults to `true`. Disable in tests that
+     * want to assert the log was untouched.
+     */
+    readonly appendRunMarkerToLog?: boolean;
+    /**
+     * Optional abort signal. The reasoner checks between peers and
+     * returns the partial result if cancelled mid-run.
+     */
+    readonly signal?: AbortSignal;
+}
+export interface PeerProfileReasonerPeerResult {
+    readonly peerId: string;
+    readonly status: "processed" | "skipped_below_min_interactions" | "skipped_no_log" | "skipped_disabled" | "skipped_no_llm" | "skipped_llm_unavailable" | "skipped_invalid_proposal" | "skipped_cap_reached" | "skipped_aborted" | "error";
+    /** Number of fields actually applied to the peer's profile. */
+    readonly fieldsApplied: number;
+    /** Number of proposals dropped because the per-run cap was hit. */
+    readonly droppedDueToCap: number;
+    /** Set of field keys applied; useful for tests and telemetry. */
+    readonly fields: ReadonlyArray<string>;
+    /** Error message, when `status === "error"`. */
+    readonly error?: string;
+}
+export interface PeerProfileReasonerResult {
+    readonly peersConsidered: number;
+    readonly peersProcessed: number;
+    readonly fieldsApplied: number;
+    readonly perPeer: ReadonlyArray<PeerProfileReasonerPeerResult>;
+}
+/**
+ * Build the user-facing reasoner prompt. The system message carries
+ * the strict-JSON instruction; this function emits the user message
+ * with the peer context and the recent log slice.
+ *
+ * The prompt is intentionally schema-prescriptive — sibling modules
+ * (`semantic-consolidation.ts`, `extraction-judge.ts`) demonstrated
+ * that letting the LLM improvise field names produces unstable
+ * profiles across runs.
+ */
+export declare function buildPeerProfileReasonerPrompt(input: {
+    peer: Peer;
+    existingProfile: PeerProfile | null;
+    log: ReadonlyArray<PeerInteractionLogEntry>;
+    maxFields: number;
+}): string;
+/**
+ * Parse the LLM response. Tolerates a fenced code block wrapper.
+ * Returns an empty array on any malformed payload — the contract is
+ * that flaky LLM output silently produces zero proposals rather than
+ * surfacing an error to the caller.
+ *
+ * Exported so unit tests can verify parser behavior without spinning
+ * up the full reasoner.
+ */
+export declare function parsePeerProfileReasonerResponse(raw: string): PeerProfileReasonerProposal[];
+/**
+ * Run the reasoner across all (or the requested subset of) peers.
+ *
+ * Always returns a `PeerProfileReasonerResult` — never throws to the
+ * caller — so the orchestrator can wire it as a best-effort
+ * post-consolidation hook (Gotcha #13).
+ */
+export declare function runPeerProfileReasoner(options: PeerProfileReasonerOptions): Promise<PeerProfileReasonerResult>;
+//# sourceMappingURL=profile-reasoner.d.ts.map

package/dist/peers/profile-reasoner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-reasoner.d.ts","sourceRoot":"","sources":["../../src/peers/profile-reasoner.ts"],"names":[],"mappings":"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"}

package/dist/peers/storage.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Peer registry storage primitives — issue #679 PR 1/5.
+ *
+ * Pure file-I/O helpers for the per-peer kernel files:
+ *
+ *   peers/{peer-id}/identity.md       — slow, human-edited identity facts
+ *   peers/{peer-id}/profile.md        — evolving profile (reasoner-owned)
+ *   peers/{peer-id}/interactions.log.md — append-only signal log
+ *
+ * No reasoner logic, no recall integration, no migration of existing
+ * identity-anchor data — those land in PR 2/5 — 5/5.
+ *
+ * Path safety: `peerId` is validated against PEER_ID_PATTERN before any
+ * filesystem operation. Reading a non-existent peer returns null (does not
+ * throw). Reading malformed files throws — callers can catch and recover.
+ */
+import { type Peer, type PeerInteractionLogEntry, type PeerProfile } from "./types.js";
+/**
+ * Validate a peer id. Throws `Error` with a descriptive message on failure.
+ * Exported so callers can pre-check user input before constructing a Peer.
+ */
+export declare function assertValidPeerId(peerId: unknown): asserts peerId is string;
+/** Root directory holding the peer registry, relative to memoryDir. */
+export declare const PEERS_DIR_NAME = "peers";
+/**
+ * Read a peer's identity kernel.
+ *
+ * Returns `null` (does not throw) when the peer directory or identity
+ * file does not exist. Throws on filesystem errors other than ENOENT and
+ * on malformed files.
+ */
+export declare function readPeer(memoryDir: string, peerId: string): Promise<Peer | null>;
+/**
+ * Write (create or overwrite) a peer's identity kernel.
+ *
+ * Creates `peers/{id}/` if it does not exist. Does not touch the peer's
+ * profile or interaction log. Atomic-write semantics are deferred to
+ * later PRs — for the schema slice we simply write the file.
+ */
+export declare function writePeer(memoryDir: string, peer: Peer): Promise<void>;
+/**
+ * Create a peer identity only if it is absent, applying the same root,
+ * peer-directory, parent-inode, and O_NOFOLLOW guards as writePeer.
+ *
+ * Returns true when this call created the identity file and false when a
+ * regular identity file already existed. Symlinked roots, peer directories,
+ * identity paths, and non-regular identity paths are rejected.
+ */
+export declare function writePeerIfAbsent(memoryDir: string, peer: Peer): Promise<boolean>;
+/**
+ * Delete a peer's `identity.md` if present, applying the same symlink
+ * and path-escape protections as the read/write paths.
+ *
+ * Returns `true` if a regular file was unlinked, `false` if no
+ * `identity.md` existed at the time of the call. The peer directory
+ * itself is left in place so any companion files (`profile.md`,
+ * `interactions/`, etc.) are untouched. Idempotent: missing target
+ * returns `false` rather than throwing.
+ *
+ * Cursor M (PR #756 review): a manual `path.join` + raw `fs.unlink`
+ * bypasses `assertPeerDirNotEscaped`, the peers-root symlink check,
+ * and the parent-inode-stable / lstat guards used by every other
+ * peer I/O entrypoint. A symlinked `peers/<id>/` could redirect the
+ * unlink to an arbitrary `identity.md` outside `memoryDir`. This
+ * function consolidates the safe-delete contract so callers cannot
+ * skip the guards.
+ */
+export declare function deletePeer(memoryDir: string, peerId: string): Promise<boolean>;
+/**
+ * Destructively purge the entire peer directory for a given peerId —
+ * `identity.md`, `profile.md`, `interactions.log.md`, and any other
+ * files written by future extensions.
+ *
+ * This is the DESTRUCTIVE counterpart to `deletePeer` (which only
+ * removes `identity.md`). Callers must pass `confirm: "yes"` to prevent
+ * accidental data loss — the function throws `Error("forgetPeer requires
+ * confirm: 'yes'")` when the flag is absent or wrong.
+ *
+ * Idempotent: if the peer directory does not exist the function returns
+ * `{ purged: false }` rather than throwing. Safe to run twice.
+ *
+ * Security contract (mirrors `deletePeer`):
+ *   - `peerId` is validated against `PEER_ID_PATTERN`.
+ *   - The peers root is checked for symlink swap (assertPeersRootNotSymlink).
+ *   - `assertPeerDirNotEscaped` performs realpath containment: symlinked
+ *     peer directories are rejected and the resolved path is confirmed to
+ *     stay inside peersRoot (same guard used by every other I/O entry-point).
+ *   - A secondary `lstat` + `isSymbolicLink()` check is kept as defence-in-
+ *     depth before the `fs.rm` call itself.
+ *   - `fs.rm` with `{ recursive: true, force: true }` is used for the
+ *     actual removal so partially-populated directories are handled
+ *     atomically by the OS rather than file-by-file in userland.
+ *
+ * Returns:
+ *   `{ purged: true }`  — directory existed and was removed.
+ *   `{ purged: false }` — directory did not exist (no-op).
+ */
+export declare function forgetPeer(memoryDir: string, peerId: string, opts: {
+    confirm: string;
+}): Promise<{
+    purged: boolean;
+}>;
+/**
+ * Enumerate all peers under `memoryDir/peers/`.
+ *
+ * Returns an empty array if the peers root does not exist. Subdirectories
+ * whose name fails `PEER_ID_PATTERN` are skipped (defensive: the user
+ * may have hand-edited the directory). Directories that exist but lack
+ * `identity.md` are also skipped.
+ */
+export declare function listPeers(memoryDir: string): Promise<Peer[]>;
+/**
+ * Append one entry to a peer's interaction log.
+ *
+ * Creates `peers/{id}/` and `interactions.log.md` if needed. The file is
+ * append-only by contract — this helper never rewrites prior entries.
+ * Returns the absolute path of the log file (useful for tests).
+ */
+export declare function appendInteractionLog(memoryDir: string, peerId: string, entry: PeerInteractionLogEntry): Promise<string>;
+/**
+ * Read a peer's profile. Returns null if the profile file does not exist.
+ *
+ * The PR-1 surface only ships the structured read/write so the reasoner
+ * (PR 2/5) and recall integration (PR 3/5) have a stable target. We do
+ * not yet expose any field-update helpers.
+ */
+export declare function readPeerProfile(memoryDir: string, peerId: string): Promise<PeerProfile | null>;
+/**
+ * Write (create or overwrite) a peer's profile.
+ */
+export declare function writePeerProfile(memoryDir: string, profile: PeerProfile): Promise<void>;
+/**
+ * Read the raw interaction log for a peer.
+ *
+ * Returns the empty string if the log does not yet exist. Callers parse
+ * the log themselves — this PR does not ship structured log parsing.
+ * Exposed primarily so tests can verify monotonic append semantics.
+ */
+export declare function readInteractionLogRaw(memoryDir: string, peerId: string): Promise<string>;
+/**
+ * Read the structured interaction log for a peer.
+ *
+ * Returns an empty array when the log file does not exist. Each line
+ * is parsed via `parseLogLine`; malformed lines are silently skipped
+ * so the reasoner can still derive profile fields from a partially
+ * corrupt log rather than aborting the whole pass.
+ *
+ * `options.limit` (when > 0) restricts the result to the most recent
+ * N entries. `options.afterTimestamp` (ISO-8601) filters out entries
+ * with `timestamp <= afterTimestamp`, comparing parsed instants so
+ * legacy valid ISO-8601 forms like `Z` without milliseconds or
+ * offset timestamps keep working. Both filters are applied in order:
+ * timestamp first, then limit.
+ *
+ * Order: oldest → newest, matching the append-only on-disk order so
+ * downstream consumers can reason about temporal evolution without
+ * re-sorting.
+ */
+export declare function readPeerInteractionLog(memoryDir: string, peerId: string, options?: {
+    limit?: number;
+    afterTimestamp?: string;
+}): Promise<PeerInteractionLogEntry[]>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/peers/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/peers/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmIH,OAAO,EAGL,KAAK,IAAI,EACT,KAAK,uBAAuB,EAE5B,KAAK,WAAW,EAEjB,MAAM,YAAY,CAAC;AAapB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAuB3E;AA6BD,uEAAuE;AACvE,eAAO,MAAM,cAAc,UAAU,CAAC;AAmTtC;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CA6DtB;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAe5E;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoCpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACxB,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CA8C9B;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAsGlE;AA6DD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAyCjB;AA2JD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAc7B;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAsEf;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAYjB;AAyFD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAkCpC"}

package/dist/peers/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Peer registry types — issue #679 PR 1/5.
+ *
+ * Generalizes the singular identity-anchor model to a multi-peer registry.
+ * Every party Remnic interacts with — humans, agents, integrations, and
+ * "self" — is represented as a `Peer` with an evolving cognitive profile.
+ *
+ * This module defines pure types only. Storage primitives live in
+ * `./storage.ts`. Reasoner integration, recall injection, CLI/HTTP/MCP
+ * surfaces, and migration of existing identity-anchor data ship in later
+ * PRs (2/5 — 5/5).
+ */
+/**
+ * Kind of peer.
+ *
+ * - `self`     — the current Remnic operator (replaces singular identity-anchor).
+ * - `human`    — another human collaborator distinct from self.
+ * - `agent`    — another AI agent (Claude Code, Codex, Hermes, etc.).
+ * - `integration` — non-conversational integration (cron, webhook, importer).
+ */
+export type PeerKind = "self" | "human" | "agent" | "integration";
+/**
+ * Stable, slow-changing facts about a peer.
+ *
+ * `id` matches `^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$`, 1-64 chars,
+ * with no leading/trailing/consecutive dots or dashes. Stored on disk under
+ * `peers/{id}/identity.md` as YAML frontmatter + markdown body.
+ */
+export interface Peer {
+    /** Stable, opaque identifier. See PEER_ID_PATTERN. */
+    readonly id: string;
+    /** Kind of peer. Drives default profile schema and recall posture. */
+    readonly kind: PeerKind;
+    /** Human-readable display name. Distinct from `id`; mutable. */
+    readonly displayName: string;
+    /** ISO-8601 timestamp of first registration. */
+    readonly createdAt: string;
+    /** ISO-8601 timestamp of most recent update to identity. */
+    readonly updatedAt: string;
+    /** Optional free-form markdown body for the identity kernel. */
+    readonly notes?: string;
+}
+/**
+ * Evolving cognitive profile for a peer.
+ *
+ * Updated by the async profile reasoner (PR 2/5) from observable session
+ * signals. Every field carries provenance back to its originating session
+ * and signal. This PR only defines the shape — population is deferred.
+ */
+export interface PeerProfile {
+    /** Peer this profile belongs to. */
+    readonly peerId: string;
+    /** ISO-8601 timestamp of most recent profile mutation. */
+    readonly updatedAt: string;
+    /**
+     * Arbitrary key/value profile fields. Values are markdown strings.
+     * Keys are stable section identifiers (e.g. `communication_style`,
+     * `recurring_concerns`). The reasoner is responsible for choosing
+     * keys; this PR does not constrain them beyond requiring strings.
+     */
+    readonly fields: Record<string, string>;
+    /**
+     * Per-field provenance. Maps field key → list of provenance entries.
+     * A field may have multiple sources (the reasoner accumulates evidence
+     * across sessions before promoting a field).
+     */
+    readonly provenance: Record<string, ReadonlyArray<PeerProfileFieldProvenance>>;
+}
+/**
+ * Provenance for a single profile-field mutation.
+ *
+ * Reasoner output (PR 2/5) attaches one of these every time it touches a
+ * field, so the user can audit exactly why a profile claim exists.
+ */
+export interface PeerProfileFieldProvenance {
+    /** ISO-8601 timestamp the field was set/updated by this signal. */
+    readonly observedAt: string;
+    /** Originating session id (or other source identifier). */
+    readonly sourceSessionId?: string;
+    /** Short label for the signal type (e.g. "explicit_preference"). */
+    readonly signal: string;
+    /** Optional free-form note explaining the inference. */
+    readonly note?: string;
+}
+/**
+ * One row of the append-only interaction log for a peer.
+ *
+ * Stored on disk under `peers/{id}/interactions.log.md` as a sequence of
+ * markdown bullet entries with a leading ISO-8601 timestamp. Append-only
+ * by contract — the reasoner reads this log to derive profile updates.
+ */
+export interface PeerInteractionLogEntry {
+    /** ISO-8601 timestamp the interaction occurred. */
+    readonly timestamp: string;
+    /** Originating session id, if any. */
+    readonly sessionId?: string;
+    /** Short kind label (e.g. "message", "tool_call", "preference_set"). */
+    readonly kind: string;
+    /** Free-form markdown summary of the interaction. */
+    readonly summary: string;
+}
+/**
+ * Regex enforced on `Peer.id`. Exported so callers can mirror validation
+ * before constructing a `Peer`.
+ *
+ * Rules:
+ *   - 1-64 characters total
+ *   - First and last character must be `[A-Za-z0-9]`
+ *   - Interior may contain `.`, `_`, `-` in addition to alphanumerics
+ *   - No leading or trailing dot/dash/underscore
+ *   - No consecutive separators (`..`, `--`, `__`, `.-`, etc.)
+ *
+ * Cursor Medium: previously the regex allowed `a..b` even though the
+ * docs claimed otherwise — a separate JS-side check enforced the rule
+ * but the standalone PATTERN was wrong for any external consumer
+ * relying on it. Tighten the regex itself so PEER_ID_PATTERN is the
+ * single source of truth: an alphanumeric, optionally followed by
+ * groups of (one separator + one-or-more alphanumerics), with the
+ * final group ending on an alphanumeric. Negative lookahead-free so
+ * it works in any JS engine.
+ */
+export declare const PEER_ID_PATTERN: RegExp;
+/** Maximum length for `Peer.id`. */
+export declare const PEER_ID_MAX_LENGTH = 64;
+//# sourceMappingURL=types.d.ts.map

package/dist/peers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/peers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAAC,CAAC;CAChF;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,eAAO,MAAM,eAAe,QAAyC,CAAC;AAEtE,oCAAoC;AACpC,eAAO,MAAM,kBAAkB,KAAK,CAAC"}

package/dist/plugin-entry-resolver.d.ts

@@ -1,9 +1,8 @@
-interface PluginEntryResolverOptions {
+export interface PluginEntryResolverOptions {
     candidateIds: readonly string[];
     preferredId?: string;
     getEntries(raw: Record<string, unknown>): Record<string, unknown> | undefined;
     getSlotId?: (raw: Record<string, unknown>) => string | undefined;
 }
-declare function resolvePluginEntry(raw: unknown, options: PluginEntryResolverOptions): Record<string, unknown> | undefined;
-
-export { type PluginEntryResolverOptions, resolvePluginEntry };
+export declare function resolvePluginEntry(raw: unknown, options: PluginEntryResolverOptions): Record<string, unknown> | undefined;
+//# sourceMappingURL=plugin-entry-resolver.d.ts.map

package/dist/plugin-entry-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-entry-resolver.d.ts","sourceRoot":"","sources":["../src/plugin-entry-resolver.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC9E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CAClE;AAaD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA0BrC"}

package/dist/plugin-id.d.ts

@@ -5,14 +5,13 @@
  * and plugins.entries.<id>. The legacy shim package @joshuaswarren/openclaw-engram
  * intentionally uses a different id ("openclaw-engram") as a backwards-compat alias.
  */
-declare const PLUGIN_ID: "openclaw-remnic";
-declare const LEGACY_PLUGIN_ID: "openclaw-engram";
+export declare const PLUGIN_ID: "openclaw-remnic";
+export declare const LEGACY_PLUGIN_ID: "openclaw-engram";
 /**
  * Resolve the Remnic plugin entry from an OpenClaw-shaped config object.
  *
  * Kept as a compatibility subpath for consumers of @remnic/core/plugin-id while
  * the shared resolver lives in plugin-entry-resolver.ts.
  */
-declare function resolveRemnicPluginEntry(raw: unknown, preferredId?: string): Record<string, unknown> | undefined;
-
-export { LEGACY_PLUGIN_ID, PLUGIN_ID, resolveRemnicPluginEntry };
+export declare function resolveRemnicPluginEntry(raw: unknown, preferredId?: string): Record<string, unknown> | undefined;
+//# sourceMappingURL=plugin-id.d.ts.map