@astrosheep/pi-context 0.22.1 → 0.23.0

package/dist/test/integration.test.js

@@ -152,26 +152,19 @@ export function assertWithinBudget(result, message) {
     const bytes = text && text.type === "text" ? Buffer.byteLength(text.text, "utf8") : 0;
     assert.ok(bytes <= TOOL_OUTPUT_MAX_BYTES, `${message}: ${bytes} bytes over the ${TOOL_OUTPUT_MAX_BYTES}-byte budget`);
 }
-/**
- * Decode a raw read (notes_read / history_read): a one-line bracketed header, then
- * the payload verbatim (which may itself contain newlines), so split on the first newline only.
- */
+/** Decode either raw read without including its shared metadata block in the payload. */
 export function resultRead(result) {
     const text = result.content[0];
     assert.ok(text && text.type === "text", "read result carries text");
-    const newline = text.text.indexOf("\n");
-    assert.ok(newline !== -1, "raw read carries a header line and a payload");
-    const header = text.text.slice(0, newline);
-    const content = text.text.slice(newline + 1);
-    assert.match(header, /^\[/, "the header is bracketed");
-    assert.match(header, /\]$/, "the header closes its bracket");
-    const match = header.match(/ · chars (\d+)-(\d+) of (\d+) · (end|continue at offset_chars=(\d+))/);
-    assert.ok(match, `read header names the char range and resume cursor: ${header}`);
-    const offset_chars = Number(match[1]);
-    const end = Number(match[2]);
-    const total_chars = Number(match[3]);
-    const next_offset_chars = match[4] === "end" ? null : Number(match[5]);
-    assert.equal(Array.from(content).length, end - offset_chars, "the header range matches the delivered payload");
+    const block = /^(--- READ WINDOW ---\n(?:[a-z_]+: [^\n]*\n)+chars: \[(\d+),(\d+)\) of (\d+)\nnext_offset_chars: (null|\d+)\n)\n/.exec(text.text);
+    assert.ok(block, "raw read carries one READ WINDOW block followed by exactly one blank line");
+    const header = block[1];
+    const content = text.text.slice(block[0].length);
+    const offset_chars = Number(block[2]);
+    const end = Number(block[3]);
+    const total_chars = Number(block[4]);
+    const next_offset_chars = block[5] === "null" ? null : Number(block[5]);
+    assert.equal(Array.from(content).length, end - offset_chars, "READ WINDOW range matches the delivered payload");
     return { header, content, offset_chars, total_chars, next_offset_chars, details: (result.details ?? {}) };
 }
 /**
@@ -328,7 +321,7 @@ test("notes_list is most-recently-updated first across merged scopes", async ()
     assert.deepEqual((await files({})).map((file) => file.address), ["@personal/e.md", "a.md", "b.md", "@project/c.md"], "updated_at descending with address ascending as the tiebreak");
     // A same-path pair in two scopes keeps both rows; equal timestamps tie-break by scope name.
     put("personal", "a.md", base + 10);
-    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.scope), ["personal", "session"], "equal timestamps tie-break by full address");
+    assert.deepEqual((await files({})).filter((file) => file.address.endsWith("a.md")).map((file) => file.address), ["@personal/a.md", "a.md"], "equal timestamps tie-break by full address");
     assert.deepEqual((await files({ pattern: "*.md" })).map((file) => file.address), ["a.md", "b.md"], "a bare pattern narrows to the session home");
 });
 test("notes are real files that persist across sessions and round-trip Unicode", async () => {
@@ -345,7 +338,6 @@ test("notes are real files that persist across sessions and round-trip Unicode",
     const read = resultRead(rawRead);
     assert.equal(read.details.address, "@personal/checkpoint/进度.md");
     assert.equal(read.content, "Café", "a negative offset reads the body tail in one call");
-    assert.equal(read.details.scope, "personal");
     const searched = resultJson(await call(restoredCaptured, "notes_search", { query: "Café", scope: "personal" }, restoredCtx));
     assert.equal(searched.files[0]?.matches[0]?.line, 2);
     const listedFiles = resultJson(await call(restoredCaptured, "notes_list", { pattern: "checkpoint/**", scope: "personal" }, restoredCtx));
@@ -366,11 +358,11 @@ test("stale lifecycle: writes and metadata-only edits close and revive a note",
     // metadata-only: content unchanged, flag set, applied 0
     const markOnly = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: true }, ctx));
     assert.equal(markOnly.applied, 0);
-    assert.equal(markOnly.meta.stale, true);
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, true);
     assert.equal(resultRead(await call(captured, "notes_read", { path: "journal.md" }, ctx)).content.endsWith("log line"), true, "mark-only leaves content unchanged");
     // explicit revive
     const revived = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: false }, ctx));
-    assert.equal(revived.meta.stale, false, "stale:false revives");
+    assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, false, "stale:false revives");
     // write+stale closure then plain write revival
     await call(captured, "notes_write", { path: "journal.md", content: "final", stale: true }, ctx);
     assert.equal(listNotes(ctx, { scope: "session" })[0]?.meta.stale, true);
@@ -705,8 +697,8 @@ test("an over-budget note is delivered as a prefix and resumed by next_offset_ch
     assert.ok(first.content.length > 0, "the page is not empty");
     assert.equal(first.content.includes("…"), false, "the payload is a plain prefix with no marker");
     assert.ok(first.content.startsWith("---\n"), "the frontmatter is delivered first");
-    assert.equal(first.header, `[huge.md · chars 0-${first.next_offset_chars} of ${first.total_chars} · continue at offset_chars=${first.next_offset_chars} · session · created ${String(first.details.created_at)} · updated ${String(first.details.updated_at)}]`, "the raw header names the address, delivered range, resume cursor, scope and timestamps");
-    assert.deepEqual(Object.keys(first.details).sort(), ["address", "created_at", "limit_chars", "next_offset_chars", "offset_chars", "scope", "total_chars", "updated_at"], "notes_read details carries exactly the slim window metadata plus scope");
+    assert.equal(first.header, `--- READ WINDOW ---\naddress: huge.md\nchars: [0,${first.next_offset_chars}) of ${first.total_chars}\nnext_offset_chars: ${first.next_offset_chars}\n`, "the raw block names the address, half-open range, and resume cursor");
+    assert.deepEqual(Object.keys(first.details).sort(), ["address", "next_offset_chars", "offset_chars", "total_chars"], "notes_read details carries exactly the raw window address and cursor metadata");
     assert.equal("content" in first.details, false, "details never duplicates the payload");
     assert.equal(first.offset_chars, 0, "the default window starts at the resolved offset 0");
     // Following the cursor reconstructs frontmatter + body by plain concatenation.
@@ -753,11 +745,11 @@ test("an over-budget note search match is a named prefix with an honest line add
     assert.equal(oversized.matches.length, 1);
     const match = oversized.matches[0];
     assert.equal(match.truncated, true, "the oversized match line is flagged as truncated");
-    assert.equal(match.total_chars, Array.from(hugeLine).length, "total_chars names the full line length");
     assert.ok(hugeLine.startsWith(match.text), "the match text is a plain prefix of the line");
     assert.equal(match.text.includes("…"), false, "no marker is appended to the match text");
-    assert.equal(match.offset_chars, 500, "the match carries the body-absolute offset of the query");
     assert.equal(match.line, 1, "the informational line number survives");
+    const atMatch = resultRead(await call(captured, "notes_read", { path: "search.md", offset_chars: match.offset_chars }, ctx));
+    assert.ok(atMatch.content.startsWith("needle"), "the search offset starts a read at the matched substring");
     // The body is reconstructible by following notes_read's cursor from the start of the file.
     const parts = [];
     let offset = 0;
@@ -784,7 +776,9 @@ test("history_read delivers a prefix and next_offset_chars names the delivered c
     assert.equal(read.content.includes("…"), false, "no marker is appended to the payload");
     assert.ok(original.startsWith(read.content), "the delivered text is a prefix of the item");
     assert.equal(read.total_chars, original.length);
-    assert.deepEqual(Object.keys(read.details), ["window_id", "item_id", "offset_chars", "total_chars", "next_offset_chars", "limit_chars"], "history_read details carries exactly the slim window metadata");
+    assert.equal(read.header, `--- READ WINDOW ---\nwindow_id: ${historyFromSession(ctx)[0].windowId}\nitem_id: ${id}\nchars: [0,${read.next_offset_chars}) of ${read.total_chars}\nnext_offset_chars: ${read.next_offset_chars}\n`, "the paged history block names identities, half-open range, and resume cursor");
+    assert.deepEqual(Object.keys(read.details), ["window_id", "item_id", "offset_chars", "total_chars", "next_offset_chars"], "history_read details carries exactly the raw window identity and cursor metadata");
+    assert.equal("limit_chars" in read.details, false, "history_read details omits the request cap");
     assert.equal("content" in read.details, false, "details never duplicates the payload");
     assert.equal(read.next_offset_chars, read.offset_chars + Array.from(read.content).length, "the cursor is offset plus delivered code points");
     assert.ok(read.next_offset_chars !== null && read.next_offset_chars < read.total_chars, "the cursor points at the first undelivered character");
@@ -794,6 +788,7 @@ test("history_read delivers a prefix and next_offset_chars names the delivered c
     let next = offset;
     while (next !== null) {
         const page = resultRead(await call(captured, "history_read", { window_id: historyFromSession(ctx)[0].windowId, item_id: id, offset_chars: offset, limit_chars: 50000 }, ctx));
+        assert.equal(page.header, `--- READ WINDOW ---\nwindow_id: ${historyFromSession(ctx)[0].windowId}\nitem_id: ${id}\nchars: [${page.offset_chars},${page.offset_chars + Array.from(page.content).length}) of ${page.total_chars}\nnext_offset_chars: ${page.next_offset_chars}\n`, "every history page retains the exact shared READ WINDOW block");
         assert.equal(page.next_offset_chars, page.offset_chars + Array.from(page.content).length < page.total_chars ? page.offset_chars + Array.from(page.content).length : null, "the cursor is offset plus delivered, null only at item end");
         parts.push(page.content);
         next = page.next_offset_chars;
@@ -813,6 +808,7 @@ test("an empty body is a frontmatter-only file that terminates cleanly", async (
     assert.ok(empty.content.endsWith("---\n\n"), "an empty body leaves frontmatter and the blank separator only");
     assert.ok(empty.total_chars > 0, "the file is not zero-length once the harness frontmatter is written");
     assert.equal(empty.next_offset_chars, null, "a note that fits terminates instead of self-feeding");
+    assert.equal(empty.header, `--- READ WINDOW ---\naddress: empty.md\nchars: [0,${empty.total_chars}) of ${empty.total_chars}\nnext_offset_chars: null\n`, "an exhausted window writes literal null");
     // An offset beyond the file is an addressing error that names the real length,
     // not a silent empty page.
     const beyond = resultJson(await call(captured, "notes_read", { path: "empty.md", offset_chars: empty.total_chars + 9 }, ctx));
@@ -1727,13 +1723,16 @@ test("argument footguns die loudly and tool-run metadata surfaces (A1/A2/A3/B4/B
     const noteEnd = resultRead(await call(captured, "notes_read", { path: "a.md", offset_chars: noteTotal }, ctx));
     assert.equal(noteEnd.content, "", "notes: offset == total is the legal empty end-read");
     assert.equal(noteEnd.next_offset_chars, null, "notes: the end-read terminates");
+    assert.equal(noteEnd.header, `--- READ WINDOW ---\naddress: a.md\nchars: [${noteTotal},${noteTotal}) of ${noteTotal}\nnext_offset_chars: null\n`, "notes: empty end-read retains the exact READ WINDOW block");
+    const itemFull = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: target.item_id }, ctx));
+    assert.equal(itemFull.header, `--- READ WINDOW ---\nwindow_id: ${windowId}\nitem_id: ${target.item_id}\nchars: [0,11) of 11\nnext_offset_chars: null\n`, "history: a fitting read retains the exact shared READ WINDOW block");
     const itemPastEnd = resultJson(await call(captured, "history_read", { window_id: windowId, item_id: target.item_id, offset_chars: 12 }, ctx));
     assert.match(itemPastEnd.error ?? "", /past the end/, "history: past-end offset is a named error");
     assert.equal(itemPastEnd.total_chars, 11, "history: the error names the real length");
     assert.equal(itemPastEnd.item_id, target.item_id, "history: the error echoes the item_id");
     const itemEnd = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: target.item_id, offset_chars: 11 }, ctx));
     assert.equal(itemEnd.content, "", "history: offset == total is the legal empty end-read");
-    assert.equal(itemEnd.next_offset_chars, null, "history: the end-read terminates");
+    assert.equal(itemEnd.header, `--- READ WINDOW ---\nwindow_id: ${windowId}\nitem_id: ${target.item_id}\nchars: [11,11) of 11\nnext_offset_chars: null\n`, "history: empty end-read retains the exact READ WINDOW block");
     // A3: editing a missing note is the typed not-found arm; write still creates it.
     const editMissing = resultJson(await call(captured, "notes_edit", { path: "missing.md", stale: true }, ctx));
     assert.equal(editMissing.error, "note not found", "an edit of a missing note is named");

package/dist/test/notes.test.js

@@ -26,6 +26,20 @@ function setUpdatedAt(scope, path, ctx, timestamp) {
     const raw = readFileSync(file, "utf8");
     writeFileSync(file, raw.replace(/^updated_at: .*$/m, `updated_at: ${new Date(timestamp).toISOString()}`));
 }
+function assertNoPublicScope(value, label) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertNoPublicScope(item, label);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        assert.notEqual(key, "scope", `${label} does not expose scope`);
+        assert.notEqual(key, "resolved_scope", `${label} does not expose resolved_scope`);
+        assertNoPublicScope(child, label);
+    }
+}
 test("exactly the five notes tools are registered; the legacy five are gone", () => {
     const captured = makeExtension(manager());
     for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
@@ -34,6 +48,10 @@ test("exactly the five notes tools are registered; the legacy five are gone", ()
     for (const legacy of ["notes_write_file", "notes_append_to_file", "notes_read_file", "notes_search_contents", "notes_list_files"]) {
         assert.equal(captured.tools.get(legacy), undefined, `${legacy} is unregistered`);
     }
+    for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
+        const description = captured.tools.get(name)?.description ?? "";
+        assert.equal(/resolved_scope|\bscope\b/.test(description), false, `${name} describes home identity through address only`);
+    }
     assert.equal(captured.tools.get("notes_write")?.executionMode, "sequential");
     assert.equal(captured.tools.get("notes_edit")?.executionMode, "sequential");
     assert.equal(captured.tools.get("notes_read")?.executionMode, undefined);
@@ -45,8 +63,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     const ctx = context(session);
     const sessionId = session.getSessionId();
     const result = resultJson(await call(captured, "notes_write", { path: "a/b.md", content: "hello" }, ctx));
-    assert.equal(result.scope, "session");
-    assert.equal(result.size_bytes, 5);
+    assert.deepEqual(Object.keys(result).sort(), ["address", "written"]);
     const file = physicalPath("session", "a/b.md", ctx);
     assert.equal(file, join(root, "pi", "session", sessionId, "a", "b.md"));
     assert.ok(existsSync(file), "the note is a real file under the session scope dir");
@@ -60,7 +77,8 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     for (const key of ["created_at", "updated_at", "last_accessed"]) {
         assert.match(raw, new RegExp(`^${key}: \\d{4}-\\d{2}-\\d{2}T`, "m"), `frontmatter renders ${key} via localIso`);
     }
-    assert.equal(typeof result.meta.created_at, "string", "wire meta renders timestamps as ISO strings");
+    assert.equal(result.address, "a/b.md");
+    assert.equal(result.written, true);
     // A leading YAML block in user content is stripped from the body.
     await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: personal\nnonsense: true\n---\nreal body" }, ctx);
     const stripped = readFileSync(physicalPath("session", "stripped.md", ctx), "utf8");
@@ -83,7 +101,7 @@ test("overwrite preserves created_at and unknown keys, bumps updated_at, and cle
     assert.equal(after.includes("sleep_shift_key: keep-me"), true, "an unknown key survives a rewrite");
     assert.equal(after.includes("recurrence_count: 4"), true, "a known sleep-shift key survives a rewrite");
     assert.match(after, /\n---\n\nsecond$/, "the body is replaced");
-    assert.equal(rewrite.meta.origin, "self");
+    assert.deepEqual(Object.keys(rewrite).sort(), ["address", "written"]);
     const listed = listNotes(ctx, { scope: "session" })[0];
     assert.equal(listed.meta.created_at, created, "created_at is preserved across an overwrite");
     assert.ok(listed.meta.updated_at >= created, "updated_at is bumped");
@@ -111,7 +129,8 @@ test("edit is body-scoped with named failures and a replace_all escape hatch", a
     assert.equal(missing.edit_index, 0, "a zero-match anchor names the failing edit index");
     const all = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "beta", newText: "B" }], replace_all: true }, ctx));
     assert.equal(all.applied, 1);
-    assert.equal(all.resolved_scope, "session", "the success return names the layer the file was resolved from");
+    assert.equal(all.address, "edit.md");
+    assertNoPublicScope(all, "notes_edit");
     assert.equal(resultRead(await call(captured, "notes_read", { path: "edit.md" }, ctx)).content.endsWith("alpha\nB\nB\ngamma"), true, "replace_all replaces every occurrence");
     // An anchor that occurs only in frontmatter is not matched: edits are body-only.
     const frontmatterOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
@@ -149,11 +168,13 @@ test("metadata-only edit updates setters without touching the body", async () =>
     await call(captured, "notes_write", { path: "journal.md", content: "log line" }, ctx);
     const bare = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: true }, ctx));
     assert.equal(bare.applied, 0, "a metadata-only update applies no edits");
-    assert.equal(bare.resolved_scope, "session");
-    assert.equal(bare.meta.stale, true, "stale is set without a body edit");
+    assert.equal(bare.address, "journal.md");
+    assert.deepEqual(Object.keys(bare).sort(), ["address", "applied", "diff"]);
+    assert.equal(listNotes(ctx, { scope: "session" })[0].meta.stale, true, "stale is set without a body edit");
     assert.equal(resultRead(await call(captured, "notes_read", { path: "journal.md" }, ctx)).content.endsWith("log line"), true, "the body is untouched");
     const revived = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: false }, ctx));
-    assert.equal(revived.meta.stale, false, "a later metadata-only update revives the note");
+    assert.deepEqual(Object.keys(revived).sort(), ["address", "applied", "diff"]);
+    assert.equal(listNotes(ctx, { scope: "session" })[0].meta.stale, false, "a later metadata-only update revives the note");
 });
 test("notes_edit returns a pi-edit-style diff of what changed", async () => {
     freshRoot();
@@ -234,7 +255,39 @@ test.skip("scope resolution and movement are superseded by explicit address test
     assert.match(refusal.error, /already exists/);
     assert.equal(readFileSync(physicalPath("personal", "clash.md", ctx), "utf8"), beforePersonal, "the target survives a refused move");
 });
-test("list and search merge scopes and carry scope; the path jail rejects escapes", async () => {
+test("all notes tool results use address as the only home identity", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const notes = [
+        { address: "session.md", body: "session needle" },
+        { address: "@project/project.md", body: "project needle" },
+        { address: "@personal/personal.md", body: "personal needle" },
+    ];
+    for (const note of notes) {
+        const written = resultJson(await call(captured, "notes_write", { address: note.address, content: note.body }, ctx));
+        assert.equal(written.address, note.address, `notes_write returns ${note.address}`);
+        assertNoPublicScope(written, `notes_write ${note.address}`);
+        const edited = resultJson(await call(captured, "notes_edit", { address: note.address, edits: [{ oldText: "needle", newText: "match" }] }, ctx));
+        assert.equal(edited.address, note.address, `notes_edit returns ${note.address}`);
+        assertNoPublicScope(edited, `notes_edit ${note.address}`);
+        const rawRead = await call(captured, "notes_read", { address: note.address }, ctx);
+        const read = resultRead(rawRead);
+        assert.equal(read.details.address, note.address, `notes_read details returns ${note.address}`);
+        assert.equal(read.header.startsWith("--- READ WINDOW ---\naddress: "), true, `notes_read starts a READ WINDOW block for ${note.address}`);
+        assert.equal(read.header.includes("scope"), false, `notes_read header omits scope for ${note.address}`);
+        assert.equal(read.header.includes("resolved_scope"), false, `notes_read header omits resolved_scope for ${note.address}`);
+        assertNoPublicScope(read.details, `notes_read ${note.address}`);
+    }
+    const listed = resultJson(await call(captured, "notes_list", { pattern: "**" }, ctx));
+    assert.deepEqual(listed.files.map((file) => file.address).sort(), notes.map((note) => note.address).sort(), "notes_list returns each full address");
+    assertNoPublicScope(listed, "notes_list");
+    const searched = resultJson(await call(captured, "notes_search", { query: "match", pattern: "**" }, ctx));
+    assert.deepEqual(searched.files.map((file) => file.address), notes.map((note) => note.address).sort(), "notes_search returns each full address");
+    assertNoPublicScope(searched, "notes_search");
+});
+test("list and search merge scopes and carry addresses; the path jail rejects escapes", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
@@ -243,24 +296,24 @@ test("list and search merge scopes and carry scope; the path jail rejects escape
     await call(captured, "notes_write", { path: "two.md", content: "needle two", scope: "project" }, ctx);
     await call(captured, "notes_write", { path: "three.md", content: "needle three", scope: "personal" }, ctx);
     const listed = resultJson(await call(captured, "notes_list", {}, ctx));
-    assert.deepEqual([...listed.files].map((file) => file.scope).sort(), ["personal", "project", "session"], "every merged row carries its scope");
+    assert.deepEqual([...listed.files].map((file) => file.address).sort(), ["@personal/three.md", "@project/two.md", "one.md"], "every merged row carries its full address");
     for (const row of listed.files) {
-        assert.equal(typeof row.size_bytes, "number");
-        assert.equal(row.origin, "self");
-        assert.equal(row.status, "active");
+        assert.deepEqual(Object.keys(row).sort(), ["address", "stale", "updated_at"]);
         assert.equal(row.stale, false);
     }
     const scoped = resultJson(await call(captured, "notes_list", { scope: "personal" }, ctx));
-    assert.deepEqual(scoped.files.map((file) => file.path), ["three.md"], "a scope filter narrows the set");
+    assert.deepEqual(scoped.files.map((file) => file.address), ["@personal/three.md"], "an address-pattern filter narrows the set");
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     assert.equal(searched.files.length, 3, "literal search finds matches in every scope");
-    assert.deepEqual([...searched.files].map((file) => file.scope).sort(), ["personal", "project", "session"]);
+    assert.deepEqual([...searched.files].map((file) => file.address).sort(), ["@personal/three.md", "@project/two.md", "one.md"]);
+    for (const row of [...listed.files, ...searched.files])
+        assertNoPublicScope(row, "notes_list/search");
     assert.equal(searched.files.every((file) => file.matches_total === 1), true);
     const hit = searched.files[0].matches[0];
     assert.equal(hit.line, 1);
-    assert.equal(hit.offset_chars, 0);
+    assert.ok(hit.offset_chars > 0, "the offset includes serialized frontmatter");
     assert.equal(hit.truncated, false);
-    assert.equal(hit.total_chars, searched.files[0].path === "three.md" ? "needle three".length : hit.text.length, "total_chars names the real line length");
+    assert.deepEqual(Object.keys(hit).sort(), ["line", "offset_chars", "text", "truncated"]);
     const escaped = ["../evil", "/abs", "a\\b"];
     for (const tool of ["notes_write", "notes_edit", "notes_read"]) {
         for (const path of escaped) {
@@ -291,6 +344,38 @@ test("the boot index reads the physical store across scopes and excludes stale n
         assert.equal(PROTOCOL_BLOCK.includes(legacy), false, `the protocol block no longer names ${legacy}`);
     }
 });
+test("search offsets start reads at Unicode matches across homes without mutating search results", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const notes = [
+        { address: "session.md", scope: "session", body: "first line\n前置 🐉 needle-session\nend", needle: "needle-session" },
+        { address: "@project/crossing.md", scope: "project", body: "prefix\nneedle-project 😀", needle: "needle-project" },
+        { address: "@personal/legacy.md", scope: "personal", body: "legacy 😺 needle-personal", needle: "needle-personal" },
+    ];
+    for (const note of notes)
+        await call(captured, "notes_write", { address: note.address, content: note.body }, ctx);
+    const crossing = physicalPath("project", "crossing.md", ctx);
+    writeFileSync(crossing, readFileSync(crossing, "utf8").replace(/^access_count: 0$/m, "access_count: 9"));
+    const legacy = physicalPath("personal", "legacy.md", ctx);
+    writeFileSync(legacy, notes[2].body);
+    const before = new Map(notes.map((note) => [note.address, readFileSync(physicalPath(note.scope, note.address.replace(/^@(?:project|personal)\//, ""), ctx), "utf8")]));
+    const searched = resultJson(await call(captured, "notes_search", { query: notes.map((note) => note.needle), pattern: "**" }, ctx));
+    for (const note of notes) {
+        assert.equal(readFileSync(physicalPath(note.scope, note.address.replace(/^@(?:project|personal)\//, ""), ctx), "utf8"), before.get(note.address), `search leaves ${note.address} byte-identical`);
+        const file = searched.files.find((candidate) => candidate.address === note.address);
+        assert.ok(file, `search returns ${note.address}`);
+        assert.deepEqual(Object.keys(file).sort(), ["address", "matches", "matches_total", "stale", "updated_at"]);
+        const hit = file.matches[0];
+        assert.deepEqual(Object.keys(hit).sort(), ["line", "offset_chars", "text", "truncated"]);
+        const read = resultRead(await call(captured, "notes_read", { address: note.address, offset_chars: hit.offset_chars }, ctx));
+        assert.ok(read.content.startsWith(note.needle), `search offset starts notes_read at ${note.needle}`);
+        assert.deepEqual(Object.keys(read.details).sort(), ["address", "next_offset_chars", "offset_chars", "total_chars"]);
+    }
+    assert.match(readFileSync(crossing, "utf8"), /^access_count: 10$/m, "the predicted read crosses access_count from 9 to 10");
+    assert.match(resultRead(await call(captured, "notes_read", { address: "@personal/legacy.md" }, ctx)).content, /^---\n/, "a missing-frontmatter note is normalized only by read");
+});
 test("notes_read surfaces frontmatter and search reports body lines", async () => {
     freshRoot();
     const session = manager();
@@ -303,7 +388,7 @@ test("notes_read surfaces frontmatter and search reports body lines", async () =
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     const match = searched.files[0].matches[0];
     assert.equal(match.line, 2, "search reports the body line number");
-    assert.equal(match.offset_chars, Array.from("line one\n").length, "offset_chars addresses the query within the body");
+    assert.equal(match.offset_chars, read.content.indexOf("needle"), "offset_chars addresses the query in the serialized read stream");
 });
 test("mutations are atomic, leave no temp files, and a read bumps only the access keys", async () => {
     freshRoot();
@@ -443,11 +528,12 @@ test("full addresses drive outputs and patterns; on-disk scope is read then drop
     assert.deepEqual(resultJson(await call(captured, "notes_list", { pattern: "*.md" }, ctx)).files.map((file) => file.address), ["root.md"]);
     assert.deepEqual(resultJson(await call(captured, "notes_search", { query: "needle", pattern: "@project/**" }, ctx)).files.map((file) => file.address), ["@project/project.md"]);
     const read = resultRead(await call(captured, "notes_read", { address: "@personal/personal.md" }, ctx));
-    assert.match(read.header, /^\[@personal\/personal\.md /, "the raw read header echoes the full address");
+    assert.equal(read.header, "--- READ WINDOW ---\naddress: @personal/personal.md\nchars: [0," + read.total_chars + ") of " + read.total_chars + "\nnext_offset_chars: null\n", "the raw READ WINDOW block echoes the full address");
     const legacy = physicalPath("project", "legacy.md", ctx);
     writeFileSync(legacy, "---\nscope: personal\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00.000+00:00\nupdated_at: 2026-01-01T00:00:00.000+00:00\nlast_accessed: 2026-01-01T00:00:00.000+00:00\naccess_count: 0\n---\n\nlegacy");
     const legacyRead = resultRead(await call(captured, "notes_read", { address: "@project/legacy.md" }, ctx));
-    assert.equal(legacyRead.details.scope, "project", "scope is derived from the file location");
+    assert.equal(legacyRead.details.address, "@project/legacy.md", "the read keeps the requested address while deriving its home internally");
+    assertNoPublicScope(legacyRead.details, "legacy notes_read");
     await call(captured, "notes_edit", { address: "@project/legacy.md", stale: true }, ctx);
     assert.equal(/^scope:/m.test(readFileSync(legacy, "utf8")), false, "the next write removes legacy scope frontmatter");
 });

package/dist/test/pagination.property.test.js

@@ -292,21 +292,21 @@ function assertTruncatedIdentity(expectedPath, actual, label) {
     assert.ok(headChars.length + tailChars.length < expectedChars.length, `${label}: truncation actually removes characters`);
 }
 /**
- * Map a notes page entry's path back to the expected store path. A non-truncated path must
- * equal it; a flagged path must be a visible middle-truncation of a legacy path that the
- * write cap could never have produced. The expected path is returned either way so the
+ * Map a notes page entry's address back to the expected address. A non-truncated address must
+ * equal it; a flagged address must be a visible middle-truncation of a legacy address that the
+ * write cap could never have produced. The expected address is returned either way so the
  * pagination invariants compare like with like.
  */
 function notePathIdentity(expectedPaths, cursor, label, page, key) {
     return page[key].map((file, index) => {
         const expectedPath = expectedPaths[cursor + index];
         assert.ok(expectedPath !== undefined, `${label} cursor=${cursor}: page returned more entries than the store holds`);
-        if (file.path_truncated) {
-            assert.ok(Buffer.byteLength(expectedPath, "utf8") > MAX_NOTE_PATH_BYTES, `${label} cursor=${cursor}: only a legacy path beyond the write cap may be truncated, got ${file.path}`);
-            assertTruncatedIdentity(expectedPath, file.path, `${label} cursor=${cursor}`);
+        if (file.address_truncated) {
+            assert.ok(Buffer.byteLength(expectedPath, "utf8") > MAX_NOTE_PATH_BYTES, `${label} cursor=${cursor}: only a legacy address beyond the write cap may be truncated, got ${file.address}`);
+            assertTruncatedIdentity(expectedPath, file.address, `${label} cursor=${cursor}`);
         }
         else {
-            assert.equal(file.path, expectedPath, `${label} cursor=${cursor}: path is returned intact when its entry fits`);
+            assert.equal(file.address, expectedPath, `${label} cursor=${cursor}: address is returned intact when its entry fits`);
         }
         return expectedPath;
     });
@@ -398,10 +398,10 @@ test("notes_list enumerates every note file across seeded mixes", async () => {
         const captured = makeExtension(session);
         const ctx = context(session);
         await materializeNotes(plan, captured, ctx);
-        const all = new Map(listNotes(ctx, {}).map((row) => [row.path, row]));
+        const all = new Map(listNotes(ctx, {}).map((row) => [row.address, row]));
         for (const variant of plan.list) {
             const params = { pattern: variant.pattern, max_results: variant.maxResults };
-            const expected = expectedListRows(ctx, variant).map((row) => row.path);
+            const expected = expectedListRows(ctx, variant).map((row) => row.address);
             const label = `notes_list seed=${seed} ${variant.label} pattern=${JSON.stringify(variant.pattern)} max_results=${variant.maxResults}`;
             const pages = await walkPages({
                 captured, ctx, tool: "notes_list", params,
@@ -413,13 +413,12 @@ test("notes_list enumerates every note file across seeded mixes", async () => {
             let flat = 0;
             for (const page of pages) {
                 for (const file of page.files) {
-                    const storePath = expected[flat++];
-                    const row = all.get(storePath);
-                    assert.ok(row, `${label}: listed ${storePath} is not in the note store`);
-                    assert.equal(file.size_bytes, row.sizeBytes, `${label}: size_bytes for ${storePath}`);
-                    assert.equal(file.stale, row.meta.stale, `${label}: stale for ${storePath}`);
-                    assert.equal(Date.parse(file.created_at), row.meta.created_at, `${label}: created_at for ${storePath}`);
-                    assert.equal(Date.parse(file.updated_at), row.meta.updated_at, `${label}: updated_at for ${storePath}`);
+                    const address = expected[flat++];
+                    const row = all.get(address);
+                    assert.ok(row, `${label}: listed ${address} is not in the note store`);
+                    assert.deepEqual(Object.keys(file).sort(), file.address_truncated ? ["address", "address_truncated", "stale", "updated_at"] : ["address", "stale", "updated_at"]);
+                    assert.equal(file.stale, row.meta.stale, `${label}: stale for ${address}`);
+                    assert.equal(Date.parse(file.updated_at), row.meta.updated_at, `${label}: updated_at for ${address}`);
                 }
             }
         }
@@ -435,7 +434,9 @@ test("notes_search enumerates every matching file across seeded mixes", async ()
         const bodies = new Map(plan.writes.map((write) => [write.path, write.body]));
         for (const variant of plan.search) {
             const params = { query: variant.query, pattern: variant.pattern, max_files: variant.maxFiles, max_matches_per_file: variant.maxMatchesPerFile };
-            const expected = expectedSearchRows(ctx, variant).map((row) => row.path);
+            const expectedRows = expectedSearchRows(ctx, variant);
+            const expected = expectedRows.map((row) => row.address);
+            const expectedByAddress = new Map(expectedRows.map((row) => [row.address, row]));
             const label = `notes_search seed=${seed} ${variant.label} query=${JSON.stringify(variant.query)} pattern=${JSON.stringify(variant.pattern)} max_files=${variant.maxFiles} max_matches_per_file=${variant.maxMatchesPerFile}`;
             const pages = await walkPages({
                 captured, ctx, tool: "notes_search", params,
@@ -447,7 +448,8 @@ test("notes_search enumerates every matching file across seeded mixes", async ()
             let flat = 0;
             for (const page of pages) {
                 for (const file of page.files) {
-                    const storePath = expected[flat++];
+                    const address = expected[flat++];
+                    const storePath = address;
                     const body = bodies.get(storePath);
                     assert.ok(body !== undefined, `${label}: reported ${storePath} was never written`);
                     const lines = body.split("\n");
@@ -455,19 +457,12 @@ test("notes_search enumerates every matching file across seeded mixes", async ()
                     assert.ok(file.matches.length >= 1, `${label}: ${storePath} reports no matches but appears in the result`);
                     assert.ok(file.matches.length <= Math.min(matchingLines.length, variant.maxMatchesPerFile), `${label}: ${storePath} reports ${file.matches.length} matches beyond its cap`);
                     assert.deepEqual(file.matches.map((match) => match.line), matchingLines.slice(0, file.matches.length), `${label}: ${storePath} match lines are not the first matching lines`);
-                    const lineBase = [];
-                    let lineOffset = 0;
-                    for (const text of lines) {
-                        lineBase.push(lineOffset);
-                        lineOffset += Array.from(text).length + 1;
-                    }
-                    for (const match of file.matches) {
+                    const expectedMatches = expectedByAddress.get(address)?.matches;
+                    assert.ok(expectedMatches, `${label}: ${address} is absent from the store search`);
+                    for (const [index, match] of file.matches.entries()) {
                         const line = lines[match.line - 1];
                         assert.ok(line.includes(variant.query), `${label}: ${storePath}:${match.line} does not contain the query`);
-                        // The documented address: body-absolute code points up to the line, plus the query's
-                        // earliest occurrence inside it.
-                        const earliest = line.indexOf(variant.query);
-                        assert.equal(match.offset_chars, lineBase[match.line - 1] + Array.from(line.slice(0, earliest)).length, `${label}: ${storePath}:${match.line} offset_chars does not address the query`);
+                        assert.equal(match.offset_chars, expectedMatches[index]?.offsetChars, `${label}: ${storePath}:${match.line} offset_chars does not address the serialized read stream`);
                     }
                 }
             }