@astrosheep/pi-context 0.25.2 → 0.26.1

package/dist/src/notes/store.js

@@ -1,55 +1,71 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { generateDiffString } from "@earendil-works/pi-coding-agent";
-import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "../protocol.js";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { earliestMatchOffsetChars } from "../text-match.js";
+import { assertAddress, assertGlobPattern, addressFor, globToRegExp } from "./address.js";
+import { snapshotNotesContext } from "./context.js";
+import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./constants.js";
 import { isOrigin, isScope, parseNote, serializeNote, stripLeadingFrontmatter } from "./frontmatter.js";
-import { addressFor, assertGlobPattern, assertVirtualPath, globToRegExp } from "./address.js";
-import { agentSlug, modelSlug, namespaceSlugs, physicalPath, scopeDir } from "./paths.js";
-import { earliestMatchOffsetChars } from "../tool-output.js";
-/** Typed store refusal. `line_numbers` and `edit_index` are the edit error's addressing fields. */
+import { namespaceSlugs, physicalPath, scopeDir, SLUG_PATTERN } from "./paths.js";
+/** Typed store refusal. Edit locations are exposed in camelCase. */
 export class NoteError extends Error {
     code;
-    line_numbers;
-    edit_index;
+    lineNumbers;
+    editIndex;
     constructor(code, message, extra = {}) {
         super(message);
         this.name = "NoteError";
         this.code = code;
-        this.line_numbers = extra.line_numbers;
-        this.edit_index = extra.edit_index;
+        this.lineNumbers = extra.lineNumbers;
+        this.editIndex = extra.editIndex;
     }
 }
 const SCOPE_ORDER = ["session", "project", "human", "agent", "model"];
-function assertScope(value) {
-    if (!isScope(value))
-        throw new NoteError("invalid_scope", `scope must be one of session, project, human, agent, model (got ${JSON.stringify(value)})`);
-    return value;
+/** Mutations and read-modify-write reads serialize by physical file across all store instances. */
+const pathQueues = new Map();
+function withPathQueue(path, operation) {
+    const key = resolve(path);
+    const previous = pathQueues.get(key) ?? Promise.resolve();
+    const result = previous.then(operation);
+    const tail = result.then(() => undefined, () => undefined);
+    pathQueues.set(key, tail);
+    void tail.then(() => {
+        if (pathQueues.get(key) === tail)
+            pathQueues.delete(key);
+    });
+    return result;
 }
-function assertOrigin(value) {
-    if (!isOrigin(value))
-        throw new NoteError("invalid_origin", `origin must be one of user, self, external (got ${JSON.stringify(value)})`);
-    return value;
+function errno(error) {
+    return typeof error === "object" && error !== null ? error.code : undefined;
+}
+async function readFileIfExists(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (errno(error) === "ENOENT")
+            return undefined;
+        throw error;
+    }
 }
 /** Recursively list `.md` files under `dir` as forward-slash virtual paths relative to `base`. */
-function walkMarkdown(dir, base = dir) {
+async function walkMarkdown(dir, base = dir) {
     let entries;
     try {
-        entries = readdirSync(dir, { withFileTypes: true });
+        entries = await readdir(dir, { withFileTypes: true });
     }
     catch (error) {
-        // A home that has never been created is normal. Every other directory
-        // failure must reach the boot snapshot boundary instead of masquerading as
-        // an empty home.
-        if (typeof error === "object" && error !== null && error.code === "ENOENT")
+        // A home that has never been created is normal. Other failures must reach the
+        // boot snapshot boundary instead of masquerading as an empty home.
+        if (errno(error) === "ENOENT")
             return [];
         throw error;
     }
     const paths = [];
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-        const child = `${dir}/${entry.name}`;
+        const child = join(dir, entry.name);
         if (entry.isDirectory())
-            paths.push(...walkMarkdown(child, base));
+            paths.push(...await walkMarkdown(child, base));
         else if (entry.isFile() && entry.name.endsWith(".md"))
             paths.push(child.slice(base.length + 1).split("\\").join("/"));
     }
@@ -59,49 +75,7 @@ function matcherFor(pattern) {
     const normalized = assertGlobPattern(pattern);
     return normalized === undefined ? undefined : globToRegExp(normalized);
 }
-/**
- * Every mutation lands through a tmp file renamed into place in the same directory, so a crash
- * never leaves a torn note. No cross-process locking: out of scope by decision.
- */
-function atomicWrite(path, content) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    try {
-        writeFileSync(tmp, content);
-        renameSync(tmp, path);
-    }
-    catch (error) {
-        rmSync(tmp, { force: true });
-        throw error;
-    }
-}
-/** Write-time vpath guard: the byte cap is a tool-boundary rule, never a jail rule. */
-function assertWritablePath(vpath) {
-    const bytes = Buffer.byteLength(vpath, "utf8");
-    if (bytes > MAX_NOTE_PATH_BYTES)
-        throw new NoteError("too_large", `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes (got ${bytes})`);
-}
-/** Serialized-size guard applied after the frontmatter is merged, before any bytes are written. */
-function assertSerializedSize(content) {
-    const bytes = Buffer.byteLength(content, "utf8");
-    if (bytes > MAX_NOTE_BYTES)
-        throw new NoteError("too_large", `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes (serialized ${bytes})`);
-}
-/** Frontmatter block only (the body separator stripped), for the metadata-only diff. */
-function frontmatterOf(meta) {
-    return serializeNote(meta, "").slice(0, -2);
-}
-/** Named agent/model homes are read-only to whoever is not running there. */
-function assertWritableHome(scope, who, ctx) {
-    if (who === undefined)
-        return;
-    const current = scope === "agent" ? agentSlug(ctx) : modelSlug(ctx);
-    if (who === current)
-        return;
-    const home = scope === "agent" ? `@agents/${who}/` : `@models/${who}/`;
-    throw new NoteError("invalid_scope", `${home} is not your home: writable homes are this session, @project/, @human/, @self/, and the current @model/ home`);
-}
-function homesForPattern(pattern) {
+async function homesForPattern(pattern, context) {
     if (!pattern || !pattern.startsWith("@"))
         return undefined;
     const head = /^@([^/]+)\//.exec(pattern)?.[1];
@@ -117,25 +91,51 @@ function homesForPattern(pattern) {
         const scope = head === "agents" ? "agent" : "model";
         const name = pattern.slice(head.length + 2).split("/")[0] ?? "";
         if (name.length > 0 && !/[*?]/.test(name))
-            return [{ scope, who: name }];
-        return namespaceSlugs(head).map((who) => ({ scope, who }));
+            return [{ scope, who: assertWho(name) }];
+        return (await namespaceSlugs(head, context.home)).map((who) => ({ scope, who }));
     }
     return [];
 }
 /** Relative pattern heads resolve to canonical names, so they match rendered addresses. */
-function normalizePattern(pattern, ctx) {
+function normalizePattern(pattern, context) {
     if (!pattern)
         return pattern;
     if (pattern.startsWith("@self/"))
-        return `@agents/${agentSlug(ctx)}/${pattern.slice("@self/".length)}`;
+        return `@agents/${context.agent}/${pattern.slice("@self/".length)}`;
     if (pattern.startsWith("@model/"))
-        return `@models/${modelSlug(ctx)}/${pattern.slice("@model/".length)}`;
+        return `@models/${context.model}/${pattern.slice("@model/".length)}`;
     return pattern;
 }
-function homesFor(ctx, opts) {
-    if (opts.scope !== undefined)
-        return [{ scope: opts.scope, who: opts.who }];
-    return homesForPattern(opts.pattern) ?? SCOPE_ORDER.map((scope) => ({ scope }));
+function assertScope(value) {
+    if (!isScope(value))
+        throw new NoteError("invalid_scope", `scope must be one of session, project, human, agent, model (got ${JSON.stringify(value)})`);
+    return value;
+}
+function assertOrigin(value) {
+    if (!isOrigin(value))
+        throw new NoteError("invalid_origin", `origin must be one of user, self, external (got ${JSON.stringify(value)})`);
+    return value;
+}
+function assertWho(value) {
+    if (typeof value !== "string" || !SLUG_PATTERN.test(value)) {
+        throw new NoteError("invalid_scope", "who must be a canonical lowercase slug");
+    }
+    return value;
+}
+async function homesFor(context, opts) {
+    if (opts.scope !== undefined) {
+        const scope = assertScope(opts.scope);
+        if (opts.who !== undefined) {
+            const who = assertWho(opts.who);
+            if (scope !== "agent" && scope !== "model")
+                throw new NoteError("invalid_scope", "who is only valid with agent or model scope");
+            return [{ scope, who }];
+        }
+        return [{ scope }];
+    }
+    if (opts.who !== undefined)
+        throw new NoteError("invalid_scope", "who requires agent or model scope");
+    return await homesForPattern(normalizePattern(opts.pattern, context), context) ?? SCOPE_ORDER.map((scope) => ({ scope }));
 }
 /** Line numbers (1-based) of every occurrence of `needle` in `body`. */
 function matchLineNumbers(body, needle) {
@@ -150,181 +150,221 @@ function matchLineNumbers(body, needle) {
     }
     return lines;
 }
-/** Create or overwrite a note; overwrite keeps created_at and every unknown key. */
-export function writeNote(ctx, vpath, body, opts) {
-    assertVirtualPath(vpath);
-    assertWritablePath(vpath);
-    const scope = assertScope(opts.scope);
-    assertWritableHome(scope, opts.who, ctx);
-    const origin = assertOrigin(opts.origin);
-    const path = physicalPath(scope, vpath, ctx, opts.who);
-    const now = Date.now();
-    const cleanBody = stripLeadingFrontmatter(body);
-    const existing = existsSync(path) ? parseNote(readFileSync(path, "utf8"), now).meta : undefined;
-    const meta = existing ?? {
-        scope,
-        origin,
-        status: "active",
-        stale: false,
-        created_at: now,
-        updated_at: now,
-        last_accessed: now,
-        access_count: 0,
-    };
-    meta.scope = scope;
-    meta.origin = origin;
-    meta.status = "active";
-    meta.stale = opts.stale ?? false;
-    meta.updated_at = now;
-    const serialized = serializeNote(meta, cleanBody);
-    assertSerializedSize(serialized);
-    atomicWrite(path, serialized);
-    return { meta };
-}
-/** Dream harness mutation: metadata changes still use the store's atomic writer. */
-export function updateNoteMeta(ctx, vpath, scope, mutate, who) {
-    assertVirtualPath(vpath);
-    const path = physicalPath(scope, vpath, ctx, who);
-    if (!existsSync(path))
-        throw new NoteError("not_found", `note not found: ${vpath}`);
-    const parsed = parseNote(readFileSync(path, "utf8"));
-    const meta = { ...parsed.meta, scope };
-    mutate(meta);
-    meta.updated_at = Date.now();
-    const serialized = serializeNote(meta, parsed.body);
-    assertSerializedSize(serialized);
-    atomicWrite(path, serialized);
-    return { meta, body: parsed.body };
-}
-/** Apply body-only edits against one explicit home; origin and stale are its metadata setters. */
-export function editNote(ctx, vpath, scope, edits, opts = {}, who) {
-    assertVirtualPath(vpath);
-    assertWritablePath(vpath);
-    assertWritableHome(scope, who, ctx);
-    const operations = edits ?? [];
-    if (operations.length === 0 && opts.origin === undefined && opts.stale === undefined) {
-        throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
+/** Every mutation uses a tmp file renamed into place in the same directory. */
+async function atomicWrite(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tmp, content);
+        await rename(tmp, path);
     }
-    const path = physicalPath(scope, vpath, ctx, who);
-    if (!existsSync(path))
-        throw new NoteError("not_found", "note not found");
-    const raw = readFileSync(path, "utf8");
-    const { meta, body } = parseNote(raw);
-    meta.scope = scope;
-    // Snapshot the pre-edit frontmatter so the diff can name exactly what the setters changed.
-    const beforeMeta = { ...meta };
-    // Every edit runs against this one snapshot; nothing is written until all of them succeed,
-    // so a failing edit leaves the file byte-identical (frontmatter included).
-    let next = body;
-    operations.forEach((edit, index) => {
-        const oldText = edit?.oldText;
-        const newText = edit?.newText;
-        if (typeof oldText !== "string" || oldText.length === 0)
-            throw new NoteError("no_match", `edit ${index}: oldText must be a non-empty string`, { edit_index: index });
-        if (typeof newText !== "string")
-            throw new NoteError("no_match", `edit ${index}: newText must be a string`, { edit_index: index });
-        const lines = matchLineNumbers(next, oldText);
-        if (lines.length === 0)
-            throw new NoteError("no_match", `edit ${index}: oldText does not occur in the note body`, { edit_index: index });
-        if (lines.length > 1 && !opts.replaceAll) {
-            throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { line_numbers: lines, edit_index: index });
-        }
-        // Single replacement is positional splicing, never String.replace: user text must be
-        // inserted byte-for-byte, without $-pattern substitution ($&, $`, $', $1, $$).
-        if (opts.replaceAll) {
-            next = next.split(oldText).join(newText);
-        }
-        else {
-            const matchIndex = next.indexOf(oldText);
-            next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+    catch (error) {
+        try {
+            await rm(tmp, { force: true });
         }
-    });
-    if (opts.origin !== undefined)
-        meta.origin = assertOrigin(opts.origin);
-    if (opts.stale !== undefined)
-        meta.stale = opts.stale;
-    meta.updated_at = Date.now();
-    const serialized = serializeNote(meta, next);
-    assertSerializedSize(serialized);
-    // pi-edit-style diff: body only for a content edit, frontmatter only for a metadata-only
-    // update, one combined file diff when both change.
-    const bodyChanged = body !== next;
-    const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
-    const diff = bodyChanged && metadataChanged
-        ? generateDiffString(raw, serialized).diff
-        : bodyChanged
-            ? generateDiffString(body, next).diff
-            : metadataChanged
-                ? generateDiffString(frontmatterOf(beforeMeta), frontmatterOf(meta)).diff
-                : "";
-    atomicWrite(path, serialized);
-    return { meta, applied: operations.length, resolved_scope: scope, diff };
+        catch { /* Preserve the original write/rename failure. */ }
+        throw error;
+    }
+}
+/** The byte cap is a write-time boundary rule, never a path-jail rule. */
+function assertWritablePath(vpath) {
+    const bytes = Buffer.byteLength(vpath, "utf8");
+    if (bytes > MAX_NOTE_PATH_BYTES)
+        throw new NoteError("too_large", `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes (got ${bytes})`);
+}
+function assertSerializedSize(content) {
+    const bytes = Buffer.byteLength(content, "utf8");
+    if (bytes > MAX_NOTE_BYTES)
+        throw new NoteError("too_large", `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes (serialized ${bytes})`);
 }
-/** Normalize a parsed note exactly as a read does, including its access metadata mutation. */
+/** Frontmatter block only (the body separator stripped), for metadata-only change inputs. */
+function frontmatterOf(meta) {
+    return serializeNote(meta, "").slice(0, -2);
+}
+/** Named agent/model homes are read-only to whoever is not running there. */
+function assertWritableHome(scope, who, context) {
+    if (who === undefined)
+        return;
+    const current = scope === "agent" ? context.agent : context.model;
+    if (who === current)
+        return;
+    const home = scope === "agent" ? `@agents/${who}/` : `@models/${who}/`;
+    throw new NoteError("invalid_scope", `${home} is not your home: writable homes are this session, @project/, @human/, @self/, and the current @model/ home`);
+}
+/** Normalize parsed metadata exactly as a read does, including its access mutation. */
 function accessedMeta(meta, scope, now) {
     const next = { ...meta, scope };
-    next.last_accessed = now;
-    next.access_count = (typeof next.access_count === "number" ? next.access_count : 0) + 1;
+    next.lastAccessed = now;
+    next.accessCount = (typeof next.accessCount === "number" ? next.accessCount : 0) + 1;
     return next;
 }
-/** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
-export function readNote(ctx, vpath, scope, who) {
-    assertVirtualPath(vpath);
-    const path = physicalPath(scope, vpath, ctx, who);
-    if (!existsSync(path))
-        return undefined;
-    const now = Date.now();
-    const parsed = parseNote(readFileSync(path, "utf8"), now);
-    const meta = accessedMeta(parsed.meta, scope, now);
-    const text = serializeNote(meta, parsed.body);
-    atomicWrite(path, text);
-    return { meta, body: parsed.body, text, resolvedScope: scope };
-}
-/** Merged rows across homes, most recently updated first (address breaks ties). */
-export function listNotes(ctx, opts = {}) {
-    const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
-    const rows = [];
-    for (const home of homesFor(ctx, opts)) {
-        const scope = home.scope;
-        const root = scopeDir(scope, ctx, home.who);
-        for (const path of walkMarkdown(root)) {
-            const address = addressFor(ctx, scope, path, home.who);
-            if (matcher && !matcher.test(address))
-                continue;
-            const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+/** Create a store over one validated, immutable snapshot of the supplied explicit identity. */
+export function createNotesStore(input) {
+    const context = snapshotNotesContext(input);
+    async function write(address, content, options = {}) {
+        const stableAddress = address;
+        const stableContent = content;
+        const stableOptions = { ...options };
+        const destination = assertAddress(stableAddress);
+        assertWritablePath(destination.path);
+        const scope = assertScope(destination.scope);
+        assertWritableHome(scope, destination.who, context);
+        const origin = assertOrigin(stableOptions.origin ?? "self");
+        const path = physicalPath(scope, destination.path, context, destination.who);
+        return withPathQueue(path, async () => {
+            const now = Date.now();
+            const cleanBody = stripLeadingFrontmatter(stableContent);
+            const existingRaw = await readFileIfExists(path);
+            const existing = existingRaw === undefined ? undefined : parseNote(existingRaw, now).meta;
+            const meta = existing ?? {
+                scope,
+                origin,
+                status: "active",
+                stale: false,
+                createdAt: now,
+                updatedAt: now,
+                lastAccessed: now,
+                accessCount: 0,
+                ...(scope === "session" ? { project: context.projectKey } : {}),
+            };
             meta.scope = scope;
-            rows.push({ address, scope, path, meta, body, sizeBytes: Buffer.byteLength(body, "utf8") });
-        }
+            meta.origin = origin;
+            meta.status = "active";
+            meta.stale = stableOptions.stale ?? false;
+            meta.updatedAt = now;
+            const serialized = serializeNote(meta, cleanBody);
+            assertSerializedSize(serialized);
+            await atomicWrite(path, serialized);
+            return { meta };
+        });
     }
-    rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.address.localeCompare(b.address));
-    return rows;
-}
-/** Case-sensitive literal substring search over note bodies, with a match address per line. */
-export function searchNotes(ctx, queries, opts = {}) {
-    const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
-    const rows = [];
-    for (const home of homesFor(ctx, opts)) {
-        const scope = home.scope;
-        const root = scopeDir(scope, ctx, home.who);
-        for (const path of walkMarkdown(root)) {
-            const address = addressFor(ctx, scope, path, home.who);
-            if (matcher && !matcher.test(address))
-                continue;
-            const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+    async function read(address) {
+        const stableAddress = address;
+        const destination = assertAddress(stableAddress);
+        const scope = assertScope(destination.scope);
+        const path = physicalPath(scope, destination.path, context, destination.who);
+        return withPathQueue(path, async () => {
+            const raw = await readFileIfExists(path);
+            if (raw === undefined)
+                return undefined;
+            const now = Date.now();
+            const parsed = parseNote(raw, now);
+            const meta = accessedMeta(parsed.meta, scope, now);
+            const text = serializeNote(meta, parsed.body);
+            await atomicWrite(path, text);
+            return { meta, body: parsed.body, text, resolvedScope: scope };
+        });
+    }
+    async function edit(address, edits, options = {}) {
+        const stableAddress = address;
+        const operations = edits === undefined ? [] : edits.map((operation) => ({ ...operation }));
+        const stableOptions = { ...options };
+        const destination = assertAddress(stableAddress);
+        assertWritablePath(destination.path);
+        const scope = assertScope(destination.scope);
+        assertWritableHome(scope, destination.who, context);
+        if (operations.length === 0 && stableOptions.origin === undefined && stableOptions.stale === undefined) {
+            throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
+        }
+        const path = physicalPath(scope, destination.path, context, destination.who);
+        return withPathQueue(path, async () => {
+            const raw = await readFileIfExists(path);
+            if (raw === undefined)
+                throw new NoteError("not_found", "note not found");
+            const { meta, body } = parseNote(raw);
             meta.scope = scope;
+            const beforeMeta = { ...meta };
+            let next = body;
+            operations.forEach((operation, index) => {
+                const oldText = operation?.oldText;
+                const newText = operation?.newText;
+                if (typeof oldText !== "string" || oldText.length === 0)
+                    throw new NoteError("no_match", `edit ${index}: oldText must be a non-empty string`, { editIndex: index });
+                if (typeof newText !== "string")
+                    throw new NoteError("no_match", `edit ${index}: newText must be a string`, { editIndex: index });
+                const lines = matchLineNumbers(next, oldText);
+                if (lines.length === 0)
+                    throw new NoteError("no_match", `edit ${index}: oldText does not occur in the note body`, { editIndex: index });
+                if (lines.length > 1 && !stableOptions.replaceAll) {
+                    throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { lineNumbers: lines, editIndex: index });
+                }
+                // Positional splicing preserves user replacement text byte-for-byte.
+                if (stableOptions.replaceAll)
+                    next = next.split(oldText).join(newText);
+                else {
+                    const matchIndex = next.indexOf(oldText);
+                    next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+                }
+            });
+            if (stableOptions.origin !== undefined)
+                meta.origin = assertOrigin(stableOptions.origin);
+            if (stableOptions.stale !== undefined)
+                meta.stale = stableOptions.stale;
+            meta.updatedAt = Date.now();
+            const serialized = serializeNote(meta, next);
+            assertSerializedSize(serialized);
+            const bodyChanged = body !== next;
+            const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+            let change;
+            if (bodyChanged && metadataChanged)
+                change = { kind: "file", before: raw, after: serialized };
+            else if (bodyChanged)
+                change = { kind: "body", before: body, after: next };
+            else if (metadataChanged)
+                change = { kind: "metadata", before: frontmatterOf(beforeMeta), after: frontmatterOf(meta) };
+            else
+                change = { kind: "none", before: "", after: "" };
+            await atomicWrite(path, serialized);
+            return { meta, applied: operations.length, resolvedScope: scope, change };
+        });
+    }
+    async function* scan(options) {
+        const matcher = matcherFor(normalizePattern(options.pattern, context));
+        const homes = await homesFor(context, options);
+        for (const home of homes) {
+            const scope = home.scope;
+            const root = scopeDir(scope, context, home.who);
+            for (const path of await walkMarkdown(root)) {
+                const address = addressFor(context, scope, path, home.who);
+                if (matcher && !matcher.test(address))
+                    continue;
+                const fullPath = join(root, path);
+                const raw = await withPathQueue(fullPath, () => readFile(fullPath, "utf8"));
+                const { meta, body } = parseNote(raw);
+                meta.scope = scope;
+                yield { address, scope, path, meta, body };
+            }
+        }
+    }
+    async function list(options = {}) {
+        const stableOptions = { ...options };
+        const rows = [];
+        for await (const row of scan(stableOptions)) {
+            rows.push({ ...row, sizeBytes: Buffer.byteLength(row.body, "utf8") });
+        }
+        rows.sort((a, b) => b.meta.updatedAt - a.meta.updatedAt || a.address.localeCompare(b.address));
+        return rows;
+    }
+    async function search(queries, options = {}) {
+        const stableQueries = [...queries];
+        const stableOptions = { ...options };
+        const rows = [];
+        for await (const note of scan(stableOptions)) {
+            const { address, path, scope, meta, body } = note;
             const serializedBodyOffset = Array.from(serializeNote(accessedMeta(meta, scope, Date.now()), "")).length;
             let baseChars = 0;
             const matches = [];
             for (const [index, line] of body.split("\n").entries()) {
-                if (queries.some((query) => line.includes(query))) {
-                    matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, queries) });
+                if (stableQueries.some((query) => line.includes(query))) {
+                    matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, stableQueries) });
                 }
                 baseChars += Array.from(line).length + 1;
             }
             if (matches.length > 0)
                 rows.push({ address, path, scope, meta, matches });
         }
+        rows.sort((a, b) => a.address.localeCompare(b.address));
+        return rows;
     }
-    rows.sort((a, b) => a.address.localeCompare(b.address));
-    return rows;
+    return { write, read, edit, list, search };
 }

package/dist/src/pi/notes/adapter.d.ts

@@ -0,0 +1,12 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { NotesContext } from "../../notes/context.js";
+/** Pi's default notes root; environment access stays on the host side of the library boundary. */
+export declare function notesRoot(): string;
+/** Translate the current Pi runtime into a fresh, explicit identity snapshot. */
+export declare function agentSlug(_ctx: ExtensionContext): string;
+/** Pi's active model identity is resolved live so a mid-session switch retargets @model. */
+export declare function modelSlug(ctx: ExtensionContext): string;
+/** Translate the current Pi runtime into one explicit notes identity snapshot. */
+export declare function notesContextFromPi(ctx: ExtensionContext, home?: string): NotesContext;
+/** One-time host activation migration from the legacy personal/ directory. */
+export declare function migrateLegacyHomes(home?: string): string | undefined;

package/dist/src/pi/notes/adapter.js

@@ -0,0 +1,39 @@
+import { existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { projectKey, slugify } from "../../notes/paths.js";
+/** Pi's default notes root; environment access stays on the host side of the library boundary. */
+export function notesRoot() {
+    const override = process.env.PI_NOTES_HOME;
+    return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+}
+/** Translate the current Pi runtime into a fresh, explicit identity snapshot. */
+export function agentSlug(_ctx) {
+    return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+/** Pi's active model identity is resolved live so a mid-session switch retargets @model. */
+export function modelSlug(ctx) {
+    const id = ctx.model?.id;
+    return id ? slugify(id.split("/").pop() ?? id) : "default";
+}
+/** Translate the current Pi runtime into one explicit notes identity snapshot. */
+export function notesContextFromPi(ctx, home = notesRoot()) {
+    return {
+        home,
+        sessionId: ctx.sessionManager.getSessionId(),
+        projectKey: projectKey(ctx.cwd),
+        agent: agentSlug(ctx),
+        model: modelSlug(ctx),
+    };
+}
+/** One-time host activation migration from the legacy personal/ directory. */
+export function migrateLegacyHomes(home = notesRoot()) {
+    const legacy = join(home, "personal");
+    const modern = join(home, "human");
+    if (!existsSync(legacy))
+        return undefined;
+    if (existsSync(modern))
+        return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
+    renameSync(legacy, modern);
+    return undefined;
+}