narraeon 0.3.1 → 0.5.0

package/dist/node/runtime/play/PlayDocumentTools.js

@@ -1,5 +1,7 @@
-import { createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
+import { renderDocumentWritePosition } from "../prompt/WorldMaintenanceReport.js";
+import { createHash } from "node:crypto";
 import { stringify } from "yaml";
+import { renderPlayerViewBindings } from "../world/PlayerViewBindings.js";
 import { PromptCompilationError, } from "../prompt/FileNativePromptCompiler.js";
 import {} from "../world/WorldDocumentStore.js";
 import { acceptWorldStateRevision, beginWorldStateRevision, fileNativeStateChanges, worldDocumentRevisionFailureMessage, } from "../world/WorldStateRevision.js";
@@ -18,20 +20,54 @@ class PlayDocumentToolFailure extends Error {
  */
 export class FileNativePlayDocuments {
     #candidate;
+    #committedSnapshot;
     #reads;
+    #declaredDirectories = [];
+    #maintenanceWarning;
+    get maintenanceWarning() {
+        return this.#maintenanceWarning;
+    }
+    bindMaintenanceUnavailable(reason, locale) {
+        this.#maintenance = {};
+        this.#maintenanceLocale = locale;
+        this.#maintenanceWarning = reason;
+    }
+    #maintenanceLocale = "en";
+    #maintenance = {};
+    bindMaintenance(facts, locale = "en") {
+        this.#maintenanceWarning = undefined;
+        this.#maintenance = structuredClone(facts);
+        this.#maintenanceLocale = locale;
+    }
     constructor(files) {
         this.#candidate = openPlayCandidate({ ...files });
+        this.#committedSnapshot = this.#candidate.snapshot;
         this.#reads = {
             snapshotId: this.#candidate.snapshot.id,
             documents: new Map(),
-            pendingReads: new Map(),
         };
     }
     get snapshot() {
         return this.#candidate.snapshot;
     }
-    bindBootstrap(bootstrap) {
-        this.#reads = bootstrapAuthorizations(bootstrap, this.#candidate.snapshot);
+    get committedSnapshot() {
+        return this.#committedSnapshot;
+    }
+    bindBootstrap(bootstrap, previousAuthorization) {
+        const injected = bootstrapAuthorizations(bootstrap, this.#candidate.snapshot);
+        this.#reads = injected;
+        // Refreshing a prefix retains the native conversation. Its exact reads
+        // remain valid only on the identical state tree, including our own writes.
+        if (previousAuthorization?.stateFingerprint ===
+            fingerprintStateFiles(this.#candidate.files)) {
+            this.restoreAuthorizationCheckpoint(previousAuthorization);
+            for (const [ref, locators] of injected.documents) {
+                for (const locator of locators ?? [null])
+                    authorizeRead(this.#reads, this.#candidate.snapshot.id, ref, locator);
+            }
+        }
+        // Creation capabilities come from this prefix, not past directory slots.
+        this.#declaredDirectories = declaredStateDirectories(bootstrap);
     }
     authorizationCheckpoint() {
         return {
@@ -75,62 +111,33 @@ export class FileNativePlayDocuments {
         this.#reads = {
             snapshotId: this.#candidate.snapshot.id,
             documents,
-            // Provider cursors are deliberately snapshot-local. A partial read has
-            // granted no write authority yet, so it restarts after cold recovery.
-            pendingReads: new Map(),
         };
     }
-    contextToolBudgetRequest(call, history) {
-        const preview = previewContextToolResult(this.#candidate.snapshot, history, call);
-        if (preview === null)
-            return null;
-        const retryParameter = call.name === "context_read" ? "max_bytes" : "limit";
-        return {
-            requestedResultBytes: Buffer.byteLength(preview.markdown, "utf8"),
-            previewMarkdown: preview.markdown,
-            retryParameter,
-            retryMinimum: call.name === "context_read" ? 4 : 1,
-            retryMaximum: contextToolRetryMaximum(call),
-            restartWithoutCursor: record(call.arguments) && typeof call.arguments.cursor === "string",
-        };
-    }
-    contextToolRetryPreview(call, history, retryValue) {
-        const argumentsWithoutCursor = record(call.arguments)
-            ? Object.fromEntries(Object.entries(call.arguments).filter(([key]) => key !== "cursor"))
-            : {};
-        const retryCall = {
-            ...structuredClone(call),
-            id: `${call.id}-budget-retry`,
-            arguments: {
-                ...argumentsWithoutCursor,
-                [call.name === "context_read" ? "maxBytes" : "limit"]: retryValue,
-            },
-        };
-        const preview = previewContextToolResult(this.#candidate.snapshot, history, retryCall);
-        if (preview === null)
-            throw new TypeError("context tool retry preview requires a read tool");
-        return { call: retryCall, markdown: preview.markdown };
-    }
     execute(call, history) {
         if (call.name === "context_search")
             return executeContextSearch(this.#candidate.snapshot, history, call.arguments);
         if (call.name === "state_list")
-            return executeStateList(this.#candidate.snapshot, history, call.arguments);
+            return executeStateList(this.#candidate.snapshot, history, call.arguments, this.#declaredDirectories);
         if (call.name === "history_list")
             return executeHistoryList(this.#candidate.snapshot, history, call.arguments);
         // Frozen contexts created before runtime-tools-v5 retain this exact name
         // and argument shape. New contexts never advertise it.
         if (call.name === "context_list")
-            return executeContextList(this.#candidate.snapshot, history, call.arguments);
+            return executeContextList(this.#candidate.snapshot, history, call.arguments, this.#declaredDirectories);
         if (call.name === "context_read") {
             const result = executeContextRead(this.#candidate.snapshot, history, call.arguments);
             authorizeToolRead(this.#reads, this.#candidate.snapshot, result);
+            const ref = result.readAuthorization?.shortRef;
+            if (ref !== undefined && result.markdown !== undefined)
+                result.markdown += `\n\n${this.#maintenanceWarning === undefined ? renderDocumentWritePosition(ref, this.#maintenance[ref], this.#maintenanceLocale) : `${this.#maintenanceLocale === "zh-CN" ? "最近写入位置暂时不可用" : "Last committed write unavailable"}: ${this.#maintenanceWarning}`}`;
             return result;
         }
         if (call.name === "world_patch")
             return applyPlayCandidatePatch(this.#candidate, this.#reads, call.arguments);
         if (call.name === "world_create")
-            return applyPlayCandidateCreate(this.#candidate, this.#reads, call.arguments);
+            return applyPlayCandidateCreate(this.#candidate, this.#reads, call.arguments, this.#declaredDirectories);
+        if (call.name === "world_retire")
+            return applyPlayCandidateRetirement(this.#candidate, this.#reads, call.arguments);
         return toolFailure(`The current document context does not accept ${call.name}`);
     }
     stateChanges() {
@@ -142,15 +149,14 @@ export class FileNativePlayDocuments {
      * this new committed baseline instead of replaying the old diff.
      */
     acceptCommittedState() {
+        this.#committedSnapshot = this.#candidate.snapshot;
         this.#candidate.changes.clear();
-        this.#candidate.suppliedBytes = 0;
     }
 }
 function bootstrapAuthorizations(bootstrap, snapshot) {
     const result = {
         snapshotId: snapshot.id,
         documents: new Map(),
-        pendingReads: new Map(),
     };
     for (const { status, complete, readAuthorization } of bootstrap.coverage) {
         if (status !== "resolved" || !complete || readAuthorization === undefined)
@@ -159,7 +165,6 @@ function bootstrapAuthorizations(bootstrap, snapshot) {
             const resolved = snapshot.query({
                 kind: "read_document",
                 document: { shortRef: readAuthorization.shortRef },
-                maxBytes: 4,
             });
             if (resolved.kind === "read_document" && resolved.ok)
                 authorizeRead(result, snapshot.id, resolved.document.shortRef, null);
@@ -176,6 +181,16 @@ function bootstrapAuthorizations(bootstrap, snapshot) {
     }
     return result;
 }
+function declaredStateDirectories(bootstrap) {
+    // Catalog coverage is the durable compiler projection shared by current
+    // state_list contexts and legacy context_list contexts.
+    return [
+        ...new Set(bootstrap.coverage
+            .filter(({ slot }) => slot === "catalog")
+            .map(({ source }) => source)
+            .filter(validStateDirectory)),
+    ].sort((left, right) => left.localeCompare(right));
+}
 function authorizeRead(authorizations, snapshotId, ref, locator) {
     if (authorizations.snapshotId !== snapshotId)
         return;
@@ -192,31 +207,7 @@ function authorizeToolRead(authorizations, snapshot, result) {
     if (authorization?.snapshotId !== snapshot.id ||
         authorizations.snapshotId !== snapshot.id)
         return;
-    const { page } = authorization;
-    let progress = authorizations.pendingReads.get(authorization.readKey);
-    if (page.start === 0) {
-        progress = {
-            shortRef: authorization.shortRef,
-            locator: authorization.locator,
-            nextOffset: page.end,
-            totalBytes: page.total,
-        };
-        authorizations.pendingReads.set(authorization.readKey, progress);
-    }
-    else {
-        if (progress === undefined)
-            return;
-        if (progress.shortRef !== authorization.shortRef ||
-            !sameLocator(progress.locator, authorization.locator) ||
-            progress.nextOffset !== page.start ||
-            progress.totalBytes !== page.total)
-            return;
-        progress.nextOffset = page.end;
-    }
-    if (progress.nextOffset !== progress.totalBytes)
-        return;
-    authorizeRead(authorizations, snapshot.id, progress.shortRef, progress.locator);
-    authorizations.pendingReads.delete(authorization.readKey);
+    authorizeRead(authorizations, snapshot.id, authorization.shortRef, authorization.locator);
 }
 function sameLocator(left, right) {
     if (left === null || right === null)
@@ -231,16 +222,12 @@ function parseYamlHandleSegment(segment) {
     return /^(?:0|[1-9][0-9]*)$/u.test(segment) ? Number(segment) : segment;
 }
 function openPlayCandidate(files) {
-    return {
-        ...beginWorldStateRevision(files),
-        suppliedBytes: 0,
-    };
+    return beginWorldStateRevision(files);
 }
 function documentDescriptorByRef(snapshot, ref) {
     const result = snapshot.query({
         kind: "read_document",
         document: { shortRef: ref },
-        maxBytes: 4,
     });
     return result.kind === "read_document" && result.ok ? result.document : null;
 }
@@ -255,17 +242,11 @@ function applyPlayCandidatePatch(candidate, reads, args) {
     const target = documentDescriptorByRef(candidate.snapshot, ref);
     if (target === null)
         return toolFailure(`Target @${ref} does not exist.`);
-    const retainedAuthorization = reads.documents.get(ref);
+    const retainedAuthorization = authorizationsAfterEdits(reads.documents.get(ref), args.edits);
     if (reads.snapshotId !== candidate.snapshot.id ||
-        retainedAuthorization === undefined ||
-        !editsAreAuthorized(retainedAuthorization, args.edits))
+        retainedAuthorization === undefined)
         return toolFailure(`Read @${ref} exactly, or receive the complete document in bootstrap, before writing it.`);
     try {
-        const suppliedBytes = Buffer.byteLength(JSON.stringify(args.edits), "utf8");
-        if (suppliedBytes > 64 * 1024)
-            throw new PlayDocumentToolFailure("A single patch body exceeds 64 KiB");
-        if (candidate.suppliedBytes + suppliedBytes > 256 * 1024)
-            throw new PlayDocumentToolFailure("New body content for this model operation exceeds 256 KiB in total");
         assertToolReferenceHandles(args.edits);
         const revised = candidate.snapshot.revise({
             commands: [
@@ -282,13 +263,19 @@ function applyPlayCandidatePatch(candidate, reads, args) {
         const receipt = formatToolRevisionReceipt(target.shortRef, revised.changes);
         const previousSnapshot = candidate.snapshot;
         acceptWorldStateRevision(candidate, revised);
-        candidate.suppliedBytes += suppliedBytes;
         carryWriteAuthorizations(previousSnapshot, candidate, reads, revised.changes);
         if (retainedAuthorization === null)
             authorizeRead(reads, candidate.snapshot.id, ref, null);
         else
-            for (const locator of retainedAuthorization)
-                authorizeRead(reads, candidate.snapshot.id, ref, locator);
+            for (const locator of retainedAuthorization) {
+                const selected = candidate.snapshot.query({
+                    kind: "select_node",
+                    document: { shortRef: ref },
+                    locator,
+                });
+                if (selected.kind === "select_node" && selected.ok)
+                    authorizeRead(reads, candidate.snapshot.id, ref, selected.node.locator);
+            }
         return {
             ok: true,
             markdown: receipt,
@@ -301,26 +288,53 @@ function applyPlayCandidatePatch(candidate, reads, args) {
         throw error;
     }
 }
-function editsAreAuthorized(authorization, edits) {
-    if (authorization === null)
-        return true;
-    if (authorization === undefined)
-        return false;
-    return edits.every((edit) => {
+function authorizationsAfterEdits(authorization, edits) {
+    if (authorization === null || authorization === undefined)
+        return authorization;
+    for (const edit of edits) {
         if (!record(edit) || edit.op === "set_metadata" || !record(edit.locator))
-            return false;
+            return undefined;
         const requested = Array.isArray(edit.locator.yaml)
             ? { codec: "yaml", path: edit.locator.yaml }
             : Array.isArray(edit.locator.markdown)
                 ? { codec: "markdown", path: edit.locator.markdown }
                 : null;
-        return (requested !== null &&
-            authorization.some((allowed) => {
+        if (requested === null ||
+            !authorization.some((allowed) => {
                 const path = "yaml" in allowed ? allowed.yaml : allowed.markdown;
                 return (requested.codec in allowed &&
                     path.every((segment, index) => requested.path[index] === segment));
-            }));
-    });
+            }))
+            return undefined;
+        // A removed/replaced subtree or shifted array address is no longer proof
+        // about its old descendants. Check each edit before moving to the next so
+        // a batch cannot use a deleted array item to overwrite its unread successor.
+        authorization = authorization.filter((allowed) => {
+            if (!(requested.codec in allowed))
+                return true;
+            const path = "yaml" in allowed ? allowed.yaml : allowed.markdown;
+            const withinEdit = requested.path.every((segment, index) => path[index] === segment);
+            if (withinEdit &&
+                ["remove", "remove_section", "rename_section"].includes(String(edit.op)))
+                return false;
+            if (withinEdit &&
+                path.length > requested.path.length &&
+                ["replace", "replace_section"].includes(String(edit.op)))
+                return false;
+            if (edit.op === "remove" && requested.codec === "yaml") {
+                const index = requested.path.length - 1;
+                const removed = requested.path[index];
+                const current = path[index];
+                if (typeof removed === "number" &&
+                    typeof current === "number" &&
+                    current >= removed &&
+                    requested.path.slice(0, -1).every((segment, i) => path[i] === segment))
+                    return false;
+            }
+            return true;
+        });
+    }
+    return authorization;
 }
 function formatToolRevisionReceipt(shortRef, changes) {
     if (changes.length > 1)
@@ -329,6 +343,43 @@ function formatToolRevisionReceipt(shortRef, changes) {
         ? `@${shortRef} pending write`
         : `@${shortRef} unchanged`;
 }
+function applyPlayCandidateRetirement(candidate, reads, args) {
+    if (!record(args) ||
+        !hasOnlyToolKeys(args, ["target", "retired"]) ||
+        typeof args.target !== "string" ||
+        typeof args.retired !== "boolean")
+        return toolFailure("world_retire requires exactly a target and boolean retired value.");
+    const ref = args.target.replace(/^@/u, "");
+    const target = documentDescriptorByRef(candidate.snapshot, ref);
+    if (target === null)
+        return toolFailure(`Target @${ref} does not exist.`);
+    if (reads.snapshotId !== candidate.snapshot.id ||
+        reads.documents.get(ref) !== null)
+        return toolFailure(`Read @${ref} exactly, or receive the complete document in bootstrap, before retiring or restoring it.`);
+    const revised = candidate.snapshot.revise({
+        commands: [
+            {
+                kind: "retire",
+                document: { documentId: target.documentId },
+                retired: args.retired,
+            },
+        ],
+    });
+    if (!revised.ok || revised.snapshotStatus !== "usable")
+        return toolFailure(worldDocumentRevisionFailureMessage(revised.diagnostics), "candidate");
+    const changed = revised.changes.length > 0;
+    const previousSnapshot = candidate.snapshot;
+    acceptWorldStateRevision(candidate, revised);
+    carryWriteAuthorizations(previousSnapshot, candidate, reads, revised.changes);
+    authorizeRead(reads, candidate.snapshot.id, ref, null);
+    return {
+        ok: true,
+        markdown: changed
+            ? `@${target.shortRef} pending ${args.retired ? "retirement" : "restoration"}`
+            : `@${target.shortRef} unchanged`,
+        candidateWrite: { shortRef: target.shortRef, changed },
+    };
+}
 function nextAvailableStatePath(candidate, parentDirectory, refHint, codec) {
     const directory = parentDirectory === "" ? "" : `${parentDirectory}/`;
     const extension = codec === "yaml" ? "yaml" : "md";
@@ -363,7 +414,7 @@ function assertToolReferenceHandles(value, seen = new WeakSet()) {
         assertToolReferenceHandles(item, seen);
     seen.delete(value);
 }
-function applyPlayCandidateCreate(candidate, authorizations, args) {
+function applyPlayCandidateCreate(candidate, authorizations, args, declaredDirectories) {
     try {
         const parentDirectory = record(args) && typeof args.parent === "string"
             ? parseStateDirectoryHandle(args.parent)
@@ -380,11 +431,8 @@ function applyPlayCandidateCreate(candidate, authorizations, args) {
             !args.aliases.every((alias) => typeof alias === "string") ||
             typeof args.body !== "string")
             throw new PlayDocumentToolFailure("world_create arguments are invalid");
-        const suppliedBytes = Buffer.byteLength(args.body, "utf8");
-        if (suppliedBytes > 64 * 1024)
-            throw new PlayDocumentToolFailure("The world_create body exceeds 64 KiB");
-        if (candidate.suppliedBytes + suppliedBytes > 256 * 1024)
-            throw new PlayDocumentToolFailure("New body content for this model operation exceeds 256 KiB in total");
+        if (!knownStateDirectory(candidate.snapshot, parentDirectory, declaredDirectories))
+            throw new PlayDocumentToolFailure("world_create parent is not a Runtime-known state directory; call state_list and use one of its directory handles");
         const path = nextAvailableStatePath(candidate, parentDirectory, args.refHint, args.codec);
         const command = args.codec === "yaml"
             ? {
@@ -423,7 +471,6 @@ function applyPlayCandidateCreate(candidate, authorizations, args) {
         acceptWorldStateRevision(candidate, revised);
         carryWriteAuthorizations(previousSnapshot, candidate, authorizations, revised.changes);
         authorizeRead(authorizations, candidate.snapshot.id, created.shortRef, null);
-        candidate.suppliedBytes += suppliedBytes;
         return {
             ok: true,
             markdown: `@${created.shortRef} pending write`,
@@ -453,9 +500,6 @@ function carryWriteAuthorizations(previousSnapshot, candidate, authorizations, c
     authorizations.snapshotId = candidate.snapshot.id;
     for (const ref of stale)
         authorizations.documents.delete(ref);
-    for (const [readKey, progress] of authorizations.pendingReads)
-        if (stale.has(progress.shortRef))
-            authorizations.pendingReads.delete(readKey);
 }
 function playCandidateStateChanges(candidate) {
     return fileNativeStateChanges(candidate);
@@ -464,7 +508,6 @@ function documentById(snapshot, id) {
     const result = snapshot.query({
         kind: "read_document",
         document: { documentId: id },
-        maxBytes: 4,
     });
     return result.kind === "read_document" && result.ok ? result.document : null;
 }
@@ -475,36 +518,6 @@ function toolFailure(message, failureKind = "protocol") {
         failureKind,
     };
 }
-function previewContextToolResult(snapshot, history, call) {
-    if (call.name === "state_list")
-        return executeStateList(snapshot, history, call.arguments);
-    if (call.name === "history_list")
-        return executeHistoryList(snapshot, history, call.arguments);
-    if (call.name === "context_list")
-        return executeContextList(snapshot, history, call.arguments);
-    if (call.name === "context_search")
-        return executeContextSearch(snapshot, history, call.arguments);
-    if (call.name === "context_read")
-        return executeContextRead(snapshot, history, call.arguments);
-    return null;
-}
-function contextToolRetryMaximum(call) {
-    if (!record(call.arguments))
-        return call.name === "context_read" ? 8_192 : 1;
-    if (call.name === "context_read")
-        return Number.isInteger(call.arguments.maxBytes) &&
-            Number(call.arguments.maxBytes) >= 4 &&
-            Number(call.arguments.maxBytes) <= 8_192
-            ? Number(call.arguments.maxBytes)
-            : 8_192;
-    const defaultLimit = call.name === "context_search" ? 10 : 20;
-    const maximumLimit = call.name === "context_search" ? 50 : 100;
-    return Number.isInteger(call.arguments.limit) &&
-        Number(call.arguments.limit) >= 1 &&
-        Number(call.arguments.limit) <= maximumLimit
-        ? Number(call.arguments.limit)
-        : defaultLimit;
-}
 function executeContextSearch(snapshot, history, args) {
     if (!record(args) ||
         !hasOnlyToolKeys(args, [
@@ -650,7 +663,26 @@ function parseStateDirectoryHandle(handle) {
         return null;
     }
 }
-function executeStateList(snapshot, history, args) {
+function validStateDirectory(directory) {
+    if (directory.length === 0)
+        return false;
+    try {
+        return (parseStateDirectoryHandle(stateDirectoryHandle(directory)) === directory);
+    }
+    catch {
+        return false;
+    }
+}
+function knownStateDirectory(snapshot, directory, declaredDirectories) {
+    if (directory === "")
+        return true;
+    const relativePrefix = `${directory}/`;
+    if (declaredDirectories.some((declared) => declared === directory || declared.startsWith(relativePrefix)))
+        return true;
+    const logicalPrefix = `${snapshot.logicalRoot}/${relativePrefix}`;
+    return snapshot.files.some(({ path }) => path.startsWith(logicalPrefix));
+}
+function executeStateList(snapshot, history, args, declaredDirectories) {
     if (!record(args) ||
         !hasOnlyToolKeys(args, ["parent", "cursor", "limit"]) ||
         typeof args.parent !== "string" ||
@@ -661,7 +693,7 @@ function executeStateList(snapshot, history, args) {
             ok: false,
             markdown: "# Runtime argument error\n\nstate_list requires an @dir-* parent returned by Runtime and accepts only cursor and limit in addition; use history_list for committed history.",
         };
-    return executeContextList(snapshot, history, { ...args, source: "state" });
+    return executeContextList(snapshot, history, { ...args, source: "state" }, declaredDirectories);
 }
 function executeHistoryList(snapshot, history, args) {
     if (!record(args) ||
@@ -675,7 +707,7 @@ function executeHistoryList(snapshot, history, args) {
         };
     return executeContextList(snapshot, history, { ...args, source: "history" });
 }
-function executeContextList(snapshot, history, args) {
+function executeContextList(snapshot, history, args, declaredDirectories = []) {
     if (!record(args) || (args.source !== "state" && args.source !== "history"))
         return {
             ok: false,
@@ -709,9 +741,16 @@ function executeContextList(snapshot, history, args) {
         const directory = parseStateDirectoryHandle(parent);
         if (directory === null)
             return unexpectedStateQueryResult();
+        if (!knownStateDirectory(snapshot, directory, declaredDirectories))
+            return {
+                ok: false,
+                markdown: "# Runtime argument error\n\nThe parent is not a Runtime-known state directory; call state_list and descend only through its returned directory handles.",
+            };
         const result = snapshot.query({
             kind: "catalog",
             directory,
+            includeRetired: true,
+            declaredDirectories,
             limit,
             ...(typeof args.cursor === "string" || args.cursor === null
                 ? { cursor: args.cursor }
@@ -728,7 +767,7 @@ function executeContextList(snapshot, history, args) {
             }
             if (entry.document === undefined)
                 return "- Damaged document (currently not addressable)";
-            return `- Document @${entry.document.shortRef} · ${entry.document.title} · ${entry.document.codec.toUpperCase()} · ${entry.document.summary}${entry.status === "damaged" ? " · needs repair" : ""}`;
+            return `- Document @${entry.document.shortRef} · ${entry.document.title} · ${entry.document.codec.toUpperCase()} · ${entry.document.summary}${entry.document.retired ? " · retired" : ""}${entry.status === "damaged" ? " · needs repair" : ""}`;
         });
         return {
             ok: true,
@@ -761,24 +800,22 @@ function executeContextList(snapshot, history, args) {
 }
 function executeContextRead(snapshot, history, args) {
     if (!record(args) ||
+        // Frozen contexts created before complete exact reads still advertise
+        // cursor/maxBytes. Accept and ignore those obsolete arguments so an
+        // existing Provider continuation can cross the upgrade boundary.
         !hasOnlyToolKeys(args, ["ref", "cursor", "maxBytes"]) ||
-        typeof args.ref !== "string" ||
-        (args.maxBytes !== undefined && typeof args.maxBytes !== "number") ||
-        !validOptionalCursor(args.cursor))
+        typeof args.ref !== "string")
         return {
             ok: false,
             markdown: "# Runtime argument error\n\nA stable ref returned by list or search is required.",
         };
-    const maxBytes = typeof args.maxBytes === "number" ? args.maxBytes : 8192;
-    if (!Number.isInteger(maxBytes) || maxBytes < 4 || maxBytes > 8192)
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nmaxBytes must be between 4 and 8192.",
-        };
     const historyRefValue = args.ref.replace(/^@/u, "");
     const historyEntry = history.find(({ path }) => historyRef(path) === historyRefValue);
     if (historyEntry !== undefined)
-        return pagedRead(historyRefValue, historyEntry.contents, maxBytes, args.cursor);
+        return {
+            ok: true,
+            markdown: `# Exact read @${historyRefValue}\n\n${historyEntry.contents}\n\n---\nSource: @${historyRefValue}\nComplete: yes`,
+        };
     const handle = parseStateReadHandle(args.ref);
     if (handle === null)
         return {
@@ -788,7 +825,6 @@ function executeContextRead(snapshot, history, args) {
     const resolved = snapshot.query({
         kind: "read_document",
         document: { shortRef: handle.shortRef },
-        maxBytes: 4,
     });
     if (resolved.kind === "error")
         return renderStateQueryFailure(resolved);
@@ -796,19 +832,17 @@ function executeContextRead(snapshot, history, args) {
         return unexpectedStateQueryResult();
     if (handle.path === null)
         return resolved.codec === "markdown"
-            ? readMarkdownDocument(snapshot, resolved.document, maxBytes, args.cursor)
-            : readProjectedNode(snapshot, resolved.document, { yaml: [] }, args.ref, maxBytes, args.cursor, true);
+            ? readMarkdownDocument(snapshot, resolved.document)
+            : readProjectedNode(snapshot, resolved.document, { yaml: [] }, args.ref, true);
     const locator = resolved.codec === "yaml"
         ? { yaml: handle.path.map(parseYamlHandleSegment) }
         : { markdown: handle.path };
-    return readProjectedNode(snapshot, resolved.document, locator, args.ref, maxBytes, args.cursor, false);
+    return readProjectedNode(snapshot, resolved.document, locator, args.ref, false);
 }
-function readMarkdownDocument(snapshot, document, maxBytes, cursor) {
+function readMarkdownDocument(snapshot, document) {
     const result = snapshot.query({
         kind: "read_document",
         document: { shortRef: document.shortRef },
-        maxBytes,
-        ...(typeof cursor === "string" || cursor === null ? { cursor } : {}),
     });
     if (result.kind === "error")
         return renderStateQueryFailure(result);
@@ -816,21 +850,15 @@ function readMarkdownDocument(snapshot, document, maxBytes, cursor) {
         return unexpectedStateQueryResult();
     return {
         ok: true,
-        markdown: `# Exact read @${document.shortRef}\n\n${renderDocumentMetadata(document)}\n[Writable body starts; locators are relative to this point]\n${result.body.trimEnd()}\n[Writable body ${result.page.complete ? "ends" : "continues"}]\n\n---\nScope: state · @${document.shortRef}\nThis page: ${result.page.start}..${result.page.end} / ${result.page.total} bytes\nComplete: ${result.page.complete ? "yes" : "no"}${result.page.nextCursor === null ? "" : `\nNext-page cursor: ${result.page.nextCursor}`}`,
+        markdown: `# Exact read @${document.shortRef}\n\n${renderDocumentMetadata(document)}\n[Writable body starts; locators are relative to this point]\n${result.body.trimEnd()}\n[Writable body ends]\n\n${renderPlayerViewBindings(snapshot, document.shortRef)}\n\n---\nScope: state · @${document.shortRef}\nComplete: yes`,
         readAuthorization: {
             snapshotId: snapshot.id,
-            readKey: readAuthorizationKey(document.shortRef, null, maxBytes),
             shortRef: document.shortRef,
             locator: null,
-            page: {
-                start: result.page.start,
-                end: result.page.end,
-                total: result.page.total,
-            },
         },
     };
 }
-function readProjectedNode(snapshot, document, locator, requestedHandle, maxBytes, cursor, wholeDocument) {
+function readProjectedNode(snapshot, document, locator, requestedHandle, wholeDocument) {
     const result = snapshot.query({
         kind: "select_node",
         document: { shortRef: document.shortRef },
@@ -849,15 +877,24 @@ function readProjectedNode(snapshot, document, locator, requestedHandle, maxByte
     const text = wholeDocument
         ? `${renderDocumentMetadata(document)}\n[Writable body starts; locators are relative to this point]\n${body}\n[Writable body ends]\n`
         : `# ${document.title} · ${renderLocator(result.node.locator)} [${requestedHandle}]\n\n${body}\n`;
-    return pagedStateProjection(snapshot, requestedHandle, text, maxBytes, cursor, document.shortRef, wholeDocument ? null : result.node.locator);
+    return {
+        ok: true,
+        markdown: `# Exact read ${requestedHandle}\n\n${text.trimEnd()}\n\n${renderPlayerViewBindings(snapshot, document.shortRef)}\n\n---\nScope: state · ${requestedHandle}\nComplete: yes`,
+        readAuthorization: {
+            snapshotId: snapshot.id,
+            shortRef: document.shortRef,
+            locator: wholeDocument ? null : result.node.locator,
+        },
+    };
 }
 function renderDocumentMetadata(document) {
     const metadata = stringify({
         title: document.title,
         summary: document.summary,
         aliases: document.aliases,
+        ...(document.retired ? { retired: true } : {}),
     }, { indent: 2, lineWidth: 0 }).trimEnd();
-    return `[Document metadata: not body content; use set_metadata to replace the entire group]\n${metadata}`;
+    return `[Document metadata: not body content; set_metadata updates one or more fields and preserves omitted fields; retired is changed only by world_retire]\n${metadata}`;
 }
 function toolWorldDocumentValue(value) {
     if (Array.isArray(value))
@@ -873,98 +910,6 @@ function toolWorldDocumentValue(value) {
         toolWorldDocumentValue(child),
     ]));
 }
-function pagedStateProjection(snapshot, handle, text, maxBytes, cursor, shortRef, locator) {
-    const scope = JSON.stringify({
-        kind: "state_projected_read",
-        snapshotId: snapshot.id,
-        handle,
-        maxBytes,
-    });
-    const offset = parseStateProjectionCursor(snapshot, cursor, scope);
-    const bytes = Buffer.from(text, "utf8");
-    if (offset === null || offset > bytes.length)
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nThe cursor does not match the current snapshot or complete query criteria.",
-        };
-    const end = safeUtf8ReadEnd(bytes, offset, maxBytes);
-    const complete = end === bytes.length;
-    const page = bytes.subarray(offset, end).toString("utf8");
-    return {
-        ok: true,
-        markdown: `# Exact read ${handle}\n\n${page}\n\n---\nScope: state · ${handle}\nThis page: ${offset}..${end} / ${bytes.length} bytes\nComplete: ${complete ? "yes" : "no"}${complete ? "" : `\nNext-page cursor: ${stateProjectionCursorFor(snapshot, scope, end)}`}`,
-        readAuthorization: {
-            snapshotId: snapshot.id,
-            readKey: readAuthorizationKey(shortRef, locator, maxBytes),
-            shortRef,
-            locator,
-            page: { start: offset, end, total: bytes.length },
-        },
-    };
-}
-function readAuthorizationKey(shortRef, locator, maxBytes) {
-    return JSON.stringify({ shortRef, locator, maxBytes });
-}
-const stateProjectionCursorSecrets = new WeakMap();
-function stateProjectionCursorFor(snapshot, scope, offset) {
-    const payload = Buffer.from(JSON.stringify({ offset }), "utf8").toString("base64url");
-    const signature = createHmac("sha256", stateProjectionCursorSecret(snapshot))
-        .update(snapshot.id)
-        .update("\0")
-        .update(scope)
-        .update("\0")
-        .update(payload)
-        .digest("base64url");
-    return `${payload}.${signature}`;
-}
-function parseStateProjectionCursor(snapshot, cursor, scope) {
-    if (cursor === undefined || cursor === null)
-        return 0;
-    if (typeof cursor !== "string")
-        return null;
-    const parts = cursor.split(".");
-    if (parts.length !== 2)
-        return null;
-    const [payload, suppliedSignature] = parts;
-    if (payload === undefined || suppliedSignature === undefined)
-        return null;
-    try {
-        const supplied = Buffer.from(suppliedSignature, "base64url");
-        if (supplied.toString("base64url") !== suppliedSignature)
-            return null;
-        const expected = createHmac("sha256", stateProjectionCursorSecret(snapshot))
-            .update(snapshot.id)
-            .update("\0")
-            .update(scope)
-            .update("\0")
-            .update(payload)
-            .digest();
-        if (supplied.length !== expected.length ||
-            !timingSafeEqual(supplied, expected))
-            return null;
-        const decoded = Buffer.from(payload, "base64url");
-        if (decoded.toString("base64url") !== payload)
-            return null;
-        const value = JSON.parse(decoded.toString("utf8"));
-        return record(value) &&
-            Object.keys(value).length === 1 &&
-            Number.isSafeInteger(value.offset) &&
-            Number(value.offset) >= 0
-            ? Number(value.offset)
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-function stateProjectionCursorSecret(snapshot) {
-    const existing = stateProjectionCursorSecrets.get(snapshot);
-    if (existing !== undefined)
-        return existing;
-    const created = randomBytes(32);
-    stateProjectionCursorSecrets.set(snapshot, created);
-    return created;
-}
 function parseStateReadHandle(value) {
     const match = /^@([a-z][a-z0-9-]*)(?:#\/(.+))?$/u.exec(value);
     if (match === null)
@@ -1026,33 +971,6 @@ function snippet(text, query) {
 function historyRef(path) {
     return `history-message-${path.replace(/\.md$/u, "")}`;
 }
-function pagedRead(ref, text, maxBytes, cursor) {
-    const scope = JSON.stringify({
-        kind: "read",
-        ref,
-        sha256: createHash("sha256").update(text).digest("hex"),
-        maxBytes,
-    });
-    const offset = parseCursor(cursor, scope);
-    if (offset === null)
-        return {
-            ok: false,
-            markdown: "# Runtime argument error\n\nThe cursor does not match the current read.",
-        };
-    const bytes = Buffer.from(text, "utf8");
-    const end = safeUtf8ReadEnd(bytes, offset, maxBytes);
-    const page = bytes.subarray(offset, end).toString("utf8");
-    return {
-        ok: true,
-        markdown: `# Exact read @${ref}\n\n${page}\n\n---\nSource: @${ref}\nThis page: ${offset}..${end} bytes\nComplete: ${end === bytes.length ? "yes" : "no"}\n${end === bytes.length ? "" : `Next-page cursor: ${cursorFor(scope, end)}`}`,
-    };
-}
-function safeUtf8ReadEnd(bytes, offset, maxBytes) {
-    let end = Math.min(bytes.length, offset + maxBytes);
-    while (end > offset && (bytes[end] ?? 0) >= 0x80 && (bytes[end] ?? 0) < 0xc0)
-        end -= 1;
-    return end;
-}
 function cursorFor(scope, offset) {
     return Buffer.from(JSON.stringify({
         scope: createHash("sha256").update(scope).digest("hex"),