narraeon 0.1.0

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

@@ -0,0 +1,1121 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
+import { stringify } from "yaml";
+import { PromptCompilationError, } from "../prompt/FileNativePromptCompiler.js";
+import {} from "../world/WorldDocumentStore.js";
+import { acceptWorldStateRevision, beginWorldStateRevision, fileNativeStateChanges, worldDocumentRevisionFailureMessage, } from "../world/WorldStateRevision.js";
+class PlayDocumentToolFailure extends Error {
+    failureKind;
+    constructor(message, failureKind = "protocol") {
+        super(message);
+        this.name = "PlayDocumentToolFailure";
+        this.failureKind = failureKind;
+    }
+}
+/**
+ * One operation-bound document context for the play call chain. Product flows
+ * submit tool calls here; document parsing, identity, lookup, locator semantics
+ * and revision mechanics remain behind WorldDocumentStore.open/query/revise.
+ */
+export class FileNativePlayDocuments {
+    #candidate;
+    #reads;
+    constructor(files) {
+        this.#candidate = openPlayCandidate({ ...files });
+        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);
+    }
+    authorizationCheckpoint() {
+        return {
+            schemaVersion: 1,
+            kind: "play_document_authorizations",
+            stateFingerprint: fingerprintStateFiles(this.#candidate.files),
+            documents: [...this.#reads.documents.entries()]
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([shortRef, locators]) => ({
+                shortRef,
+                locators: locators === null
+                    ? null
+                    : locators
+                        .filter((locator, index, all) => all.findIndex((candidate) => sameLocator(candidate, locator)) === index)
+                        .map((locator) => structuredClone(locator)),
+            })),
+        };
+    }
+    restoreAuthorizationCheckpoint(checkpoint) {
+        if (!isPlayDocumentAuthorizationCheckpoint(checkpoint))
+            throw new TypeError("The play-document authorization checkpoint has an invalid format");
+        if (checkpoint.stateFingerprint !==
+            fingerprintStateFiles(this.#candidate.files))
+            throw new TypeError("The play-document authorization checkpoint does not match the current state");
+        const documents = new Map();
+        for (const { shortRef, locators } of checkpoint.documents) {
+            if (documentDescriptorByRef(this.#candidate.snapshot, shortRef) === null)
+                throw new TypeError(`The play-document authorization checkpoint refers to missing @${shortRef}`);
+            const restoredLocators = locators?.map((locator) => {
+                const selected = this.#candidate.snapshot.query({
+                    kind: "select_node",
+                    document: { shortRef },
+                    locator,
+                });
+                if (selected.kind !== "select_node" || !selected.ok)
+                    throw new TypeError(`The play-document authorization checkpoint refers to a missing node in @${shortRef}`);
+                return structuredClone(selected.node.locator);
+            });
+            documents.set(shortRef, restoredLocators ?? null);
+        }
+        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 === "context_list")
+            return executeContextList(this.#candidate.snapshot, history, call.arguments);
+        if (call.name === "context_read") {
+            const result = executeContextRead(this.#candidate.snapshot, history, call.arguments);
+            authorizeToolRead(this.#reads, this.#candidate.snapshot, result);
+            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 toolFailure(`The current document context does not accept ${call.name}`);
+    }
+    stateChanges() {
+        return playCandidateStateChanges(this.#candidate);
+    }
+    /**
+     * The current revision has been accepted by Authority. Keep using the same
+     * snapshot and read authorizations, but make subsequent writes relative to
+     * this new committed baseline instead of replaying the old diff.
+     */
+    acceptCommittedState() {
+        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)
+            continue;
+        if (readAuthorization.locator === null) {
+            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);
+        }
+        else {
+            const selected = snapshot.query({
+                kind: "select_node",
+                document: { shortRef: readAuthorization.shortRef },
+                locator: readAuthorization.locator,
+            });
+            if (selected.kind === "select_node" && selected.ok)
+                authorizeRead(result, snapshot.id, selected.document.shortRef, selected.node.locator);
+        }
+    }
+    return result;
+}
+function authorizeRead(authorizations, snapshotId, ref, locator) {
+    if (authorizations.snapshotId !== snapshotId)
+        return;
+    if (locator === null)
+        authorizations.documents.set(ref, null);
+    else if (authorizations.documents.get(ref) !== null)
+        authorizations.documents.set(ref, [
+            ...(authorizations.documents.get(ref) ?? []),
+            locator,
+        ]);
+}
+function authorizeToolRead(authorizations, snapshot, result) {
+    const authorization = result.readAuthorization;
+    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);
+}
+function sameLocator(left, right) {
+    if (left === null || right === null)
+        return left === right;
+    const leftPath = "yaml" in left ? left.yaml : left.markdown;
+    const rightPath = "yaml" in right ? right.yaml : right.markdown;
+    return ("yaml" in left === "yaml" in right &&
+        leftPath.length === rightPath.length &&
+        leftPath.every((segment, index) => segment === rightPath[index]));
+}
+function parseYamlHandleSegment(segment) {
+    return /^(?:0|[1-9][0-9]*)$/u.test(segment) ? Number(segment) : segment;
+}
+function openPlayCandidate(files) {
+    return {
+        ...beginWorldStateRevision(files),
+        suppliedBytes: 0,
+    };
+}
+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;
+}
+function applyPlayCandidatePatch(candidate, reads, args) {
+    if (!record(args) ||
+        typeof args.target !== "string" ||
+        !Array.isArray(args.edits) ||
+        args.edits.length < 1 ||
+        args.edits.length > 32)
+        return toolFailure("world_patch requires a target and 1 to 32 edits.");
+    const ref = args.target.replace(/^@/u, "");
+    const target = documentDescriptorByRef(candidate.snapshot, ref);
+    if (target === null)
+        return toolFailure(`Target @${ref} does not exist.`);
+    const retainedAuthorization = reads.documents.get(ref);
+    if (reads.snapshotId !== candidate.snapshot.id ||
+        retainedAuthorization === undefined ||
+        !editsAreAuthorized(retainedAuthorization, args.edits))
+        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: [
+                {
+                    kind: "patch",
+                    document: { documentId: target.documentId },
+                    edits: args.edits,
+                },
+            ],
+        });
+        if (!revised.ok || revised.snapshotStatus !== "usable")
+            throw new PlayDocumentToolFailure(worldDocumentRevisionFailureMessage(revised.diagnostics), "candidate");
+        const changed = revised.changes.length > 0;
+        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);
+        return {
+            ok: true,
+            markdown: receipt,
+            candidateWrite: { shortRef: target.shortRef, changed },
+        };
+    }
+    catch (error) {
+        if (error instanceof PlayDocumentToolFailure)
+            return toolFailure(error.message, error.failureKind);
+        throw error;
+    }
+}
+function editsAreAuthorized(authorization, edits) {
+    if (authorization === null)
+        return true;
+    if (authorization === undefined)
+        return false;
+    return edits.every((edit) => {
+        if (!record(edit) || edit.op === "set_metadata" || !record(edit.locator))
+            return false;
+        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) => {
+                const path = "yaml" in allowed ? allowed.yaml : allowed.markdown;
+                return (requested.codec in allowed &&
+                    path.every((segment, index) => requested.path[index] === segment));
+            }));
+    });
+}
+function formatToolRevisionReceipt(shortRef, changes) {
+    if (changes.length > 1)
+        throw new Error("A world_patch revision must affect only its target document");
+    return changes.length === 1
+        ? `@${shortRef} pending write`
+        : `@${shortRef} unchanged`;
+}
+function nextAvailableStatePath(candidate, parentDirectory, refHint, codec) {
+    const directory = parentDirectory === "" ? "" : `${parentDirectory}/`;
+    const extension = codec === "yaml" ? "yaml" : "md";
+    for (let suffix = 1;; suffix += 1) {
+        const suffixText = suffix === 1 ? "" : `-${suffix}`;
+        const fileName = `${refHint.slice(0, 32 - suffixText.length)}${suffixText}`;
+        const path = `state/${directory}${fileName}.${extension}`;
+        if (candidate.files[path] === undefined)
+            return path;
+    }
+}
+function assertToolReferenceHandles(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object")
+        return;
+    if (seen.has(value))
+        throw new PlayDocumentToolFailure("Tool arguments must not contain circular references");
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertToolReferenceHandles(item, seen);
+        seen.delete(value);
+        return;
+    }
+    if (!record(value))
+        throw new PlayDocumentToolFailure("Tool arguments may contain only plain objects");
+    if (Object.hasOwn(value, "$ref") &&
+        (Object.keys(value).length !== 1 ||
+            typeof value.$ref !== "string" ||
+            !value.$ref.startsWith("@")))
+        throw new PlayDocumentToolFailure("$ref must use an @short-ref returned by the Runtime, and a reference object cannot contain other fields");
+    for (const item of Object.values(value))
+        assertToolReferenceHandles(item, seen);
+    seen.delete(value);
+}
+function applyPlayCandidateCreate(candidate, authorizations, args) {
+    try {
+        const parentDirectory = record(args) && typeof args.parent === "string"
+            ? parseStateDirectoryHandle(args.parent)
+            : null;
+        if (!record(args) ||
+            typeof args.parent !== "string" ||
+            parentDirectory === null ||
+            (args.codec !== "yaml" && args.codec !== "markdown") ||
+            typeof args.refHint !== "string" ||
+            !/^[a-z][a-z0-9-]{1,31}$/u.test(args.refHint) ||
+            typeof args.title !== "string" ||
+            typeof args.summary !== "string" ||
+            !Array.isArray(args.aliases) ||
+            !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");
+        const path = nextAvailableStatePath(candidate, parentDirectory, args.refHint, args.codec);
+        const command = args.codec === "yaml"
+            ? {
+                kind: "create",
+                temporaryName: "created",
+                logicalPath: path,
+                codec: "yaml",
+                refHint: args.refHint,
+                title: args.title,
+                summary: args.summary,
+                aliases: args.aliases,
+                body: args.body,
+            }
+            : {
+                kind: "create",
+                temporaryName: "created",
+                logicalPath: path,
+                codec: "markdown",
+                refHint: args.refHint,
+                title: args.title,
+                summary: args.summary,
+                aliases: args.aliases,
+                body: args.body,
+            };
+        if (command.codec === "yaml")
+            assertToolReferenceHandles(command.body);
+        const revised = candidate.snapshot.revise({
+            commands: [command],
+        });
+        if (!revised.ok || revised.snapshotStatus !== "usable")
+            throw new PlayDocumentToolFailure(worldDocumentRevisionFailureMessage(revised.diagnostics), "candidate");
+        const created = revised.changes.find(({ before }) => before === null);
+        if (created === undefined)
+            throw new Error("The world_create revision did not return a newly created document change");
+        const previousSnapshot = candidate.snapshot;
+        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`,
+            candidateWrite: { shortRef: created.shortRef, changed: true },
+        };
+    }
+    catch (error) {
+        if (error instanceof PlayDocumentToolFailure)
+            return toolFailure(error.message, error.failureKind);
+        throw error;
+    }
+}
+/**
+ * Move read authorizations onto the revised snapshot. Only the documents this
+ * revision actually rewrote go stale — everything else is byte-identical in the
+ * new snapshot, so a model that read several documents and then patches one of
+ * them keeps the right to write the others in the same model response.
+ */
+function carryWriteAuthorizations(previousSnapshot, candidate, authorizations, changes) {
+    const stale = new Set();
+    for (const change of changes) {
+        stale.add(change.shortRef);
+        const previous = documentById(previousSnapshot, change.documentId);
+        if (previous !== null)
+            stale.add(previous.shortRef);
+    }
+    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);
+}
+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;
+}
+function toolFailure(message, failureKind = "protocol") {
+    return {
+        ok: false,
+        markdown: `# Runtime tool rejected\n\n${message}`,
+        failureKind,
+    };
+}
+function previewContextToolResult(snapshot, history, call) {
+    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, [
+            "source",
+            "query",
+            "caseSensitive",
+            "within",
+            "limit",
+            "cursor",
+        ]) ||
+        (args.source !== "state" && args.source !== "history") ||
+        typeof args.query !== "string" ||
+        args.query.length < 1 ||
+        args.query.length > 256 ||
+        (args.caseSensitive !== undefined &&
+            typeof args.caseSensitive !== "boolean") ||
+        (args.within !== undefined && typeof args.within !== "string") ||
+        (args.limit !== undefined && typeof args.limit !== "number") ||
+        !validOptionalCursor(args.cursor))
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\ncontext_search accepts only a literal query and strict source, within, caseSensitive, limit, and cursor arguments; semantic filters are not accepted.",
+        };
+    const caseSensitive = args.caseSensitive === true;
+    const query = args.query;
+    const limit = typeof args.limit === "number" ? args.limit : 10;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nlimit must be between 1 and 50.",
+        };
+    if (args.source === "state")
+        return searchState(snapshot, {
+            query,
+            caseSensitive,
+            ...(args.within === undefined ? {} : { within: args.within }),
+            limit,
+            ...(typeof args.cursor === "string" || args.cursor === null
+                ? { cursor: args.cursor }
+                : {}),
+        });
+    const source = history.map(({ path, contents }) => [
+        historyRef(path),
+        contents,
+        [`history-commit-${path.split("-")[0] ?? ""}`],
+    ]);
+    const normalizedQuery = normalizeSearch(query, caseSensitive);
+    const within = typeof args.within === "string" ? args.within.replace(/^@/u, "") : null;
+    const allHits = source.filter(([ref, text, parentScopes]) => (within === null || ref === within || parentScopes.includes(within)) &&
+        normalizeSearch(text, caseSensitive).includes(normalizedQuery));
+    const scope = JSON.stringify({
+        kind: "search",
+        source: "history",
+        query,
+        caseSensitive,
+        within: args.within ?? null,
+        limit,
+    });
+    const offset = parseCursor(args.cursor, scope);
+    if (offset === null)
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nThe cursor does not match the search criteria or endpoint.",
+        };
+    const hits = allHits.slice(offset, offset + limit);
+    const complete = offset + hits.length >= allHits.length;
+    const renderedHits = hits
+        .map(([ref, text]) => `- @${ref}\n  Exact-match excerpt:\n${quoteMarkdown(snippet(text, query), "  ")}`)
+        .join("\n");
+    return {
+        ok: true,
+        markdown: `# Literal search\n\nScope: history${args.within === undefined ? "" : ` · ${args.within}`}\nNormalization: ${caseSensitive ? "original text" : "NFKC + case folding"}\nTotal matches: ${allHits.length}\n${renderedHits || "Zero literal matches do not prove that the fact is absent from the world."}\n\n---\nThis page: ${offset}..${offset + hits.length} / ${allHits.length} matches\nComplete: ${complete ? "yes" : "no"}${complete ? "" : `\nNext-page cursor: ${cursorFor(scope, offset + hits.length)}`}`,
+    };
+}
+function searchState(snapshot, input) {
+    const within = parseStateSearchScope(input.within);
+    if (within === invalidStateHandle)
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nA state search scope must be an @dir-* or document @short-ref returned by the Runtime.",
+        };
+    const result = snapshot.query({
+        kind: "literal_search",
+        query: input.query,
+        caseSensitive: input.caseSensitive,
+        ...(within === undefined ? {} : { within }),
+        limit: input.limit,
+        ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+    });
+    if (result.kind === "error")
+        return renderStateQueryFailure(result);
+    if (result.kind !== "literal_search")
+        return unexpectedStateQueryResult();
+    const renderedHits = result.matches
+        .map(({ document, referenceProjection, range }) => `- @${document.shortRef} · ${document.title} · line ${range.start.line}, column ${range.start.column}\n  Exact match: ${JSON.stringify(referenceProjection.text)}\n  Exact-match excerpt (mechanical references appear as @short-refs):\n${quoteMarkdown(referenceProjection.excerpt, "  ")}`)
+        .join("\n");
+    const scope = input.within === undefined ? "state" : `state · ${input.within}`;
+    return {
+        ok: true,
+        markdown: `# Literal search\n\nScope: ${scope}\nNormalization: ${input.caseSensitive ? "original text" : "NFKC + case folding"}\nCoverage: ${result.coverage.status === "complete" ? "complete" : `partial (${result.coverage.excludedDocuments} damaged documents excluded)`}\nTotal matches: ${result.page.total}\n${renderedHits || "Zero literal matches do not prove that the fact is absent from the world."}\n\n---\nThis page: ${result.page.start}..${result.page.end} / ${result.page.total} matches\nComplete: ${result.page.complete ? "yes" : "no"}${result.page.nextCursor === null ? "" : `\nNext-page cursor: ${result.page.nextCursor}`}`,
+    };
+}
+const invalidStateHandle = Symbol("invalid-state-handle");
+function parseStateSearchScope(handle) {
+    if (handle === undefined)
+        return undefined;
+    const directory = parseStateDirectoryHandle(handle);
+    if (directory !== null)
+        return { directory };
+    const document = /^@([a-z][a-z0-9-]*)$/u.exec(handle);
+    return document === null
+        ? invalidStateHandle
+        : { document: { shortRef: document[1] } };
+}
+function stateDirectoryHandle(directory) {
+    if (directory === "")
+        return "@dir-/";
+    const encoded = directory.split("/").map(encodeURIComponent).join("/");
+    return `@dir-/${encoded}`;
+}
+function parseStateDirectoryHandle(handle) {
+    if (handle === "@dir-/")
+        return "";
+    if (!handle.startsWith("@dir-/") || handle.length === "@dir-/".length)
+        return null;
+    try {
+        const directory = handle
+            .slice("@dir-/".length)
+            .split("/")
+            .map(decodeURIComponent)
+            .join("/");
+        if (directory
+            .split("/")
+            .some((segment) => segment === "" ||
+            segment === "." ||
+            segment === ".." ||
+            segment.includes("\\")) ||
+            stateDirectoryHandle(directory) !== handle)
+            return null;
+        return directory;
+    }
+    catch {
+        return null;
+    }
+}
+function executeContextList(snapshot, history, args) {
+    if (!record(args) || (args.source !== "state" && args.source !== "history"))
+        return {
+            ok: false,
+            markdown: '# Runtime argument error\n\nUse {source:"state", parent:"@dir-/"} for state directories and {source:"history", order:"newest_first"} for history.',
+        };
+    const allowedKeys = ["source", "parent", "order", "cursor", "limit"];
+    const invalidStateShape = args.source === "state" &&
+        (typeof args.parent !== "string" ||
+            parseStateDirectoryHandle(args.parent) === null ||
+            args.order !== undefined);
+    const invalidHistoryShape = args.source === "history" &&
+        (args.parent !== undefined ||
+            (args.order !== "newest_first" && args.order !== "oldest_first"));
+    if (!hasOnlyToolKeys(args, allowedKeys) ||
+        invalidStateShape ||
+        invalidHistoryShape ||
+        (args.limit !== undefined && typeof args.limit !== "number") ||
+        !validOptionalCursor(args.cursor))
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nstate must use an @dir-* parent returned by the Runtime and omit order; history must use newest_first or oldest_first order and omit parent.",
+        };
+    const limit = typeof args.limit === "number" ? args.limit : 20;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nlimit must be between 1 and 100.",
+        };
+    if (args.source === "state") {
+        const parent = args.parent;
+        const directory = parseStateDirectoryHandle(parent);
+        if (directory === null)
+            return unexpectedStateQueryResult();
+        const result = snapshot.query({
+            kind: "catalog",
+            directory,
+            limit,
+            ...(typeof args.cursor === "string" || args.cursor === null
+                ? { cursor: args.cursor }
+                : {}),
+        });
+        if (result.kind === "error")
+            return renderStateQueryFailure(result);
+        if (result.kind !== "catalog")
+            return unexpectedStateQueryResult();
+        const entries = result.entries.map((entry) => {
+            if (entry.kind === "directory") {
+                const relative = entry.logicalPath.slice(`${snapshot.logicalRoot}/`.length);
+                return `- Directory ${stateDirectoryHandle(relative)}`;
+            }
+            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 {
+            ok: true,
+            markdown: `# Directory listing\n\nScope: state · ${parent}\nCoverage: ${result.coverage.status === "complete" ? "complete" : "partial"}\n${entries.join("\n") || "(empty)"}\n\n---\nThis page: ${result.page.start}..${result.page.end} / ${result.page.total} items\nComplete: ${result.page.complete ? "yes" : "no"}${result.page.nextCursor === null ? "" : `\nNext-page cursor: ${result.page.nextCursor}`}`,
+        };
+    }
+    const entries = [...history]
+        .sort((a, b) => (args.order ?? "newest_first") === "oldest_first"
+        ? a.path.localeCompare(b.path)
+        : b.path.localeCompare(a.path))
+        .map(({ path, contents }) => `- @${historyRef(path)}, ${Buffer.byteLength(contents, "utf8")} bytes`);
+    const scope = JSON.stringify({
+        kind: "list",
+        source: "history",
+        order: args.order,
+        limit,
+    });
+    const offset = parseCursor(args.cursor, scope);
+    if (offset === null)
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nThe cursor does not match the listing criteria or endpoint.",
+        };
+    const page = entries.slice(offset, offset + limit);
+    const complete = offset + page.length >= entries.length;
+    return {
+        ok: true,
+        markdown: `# Directory listing\n\nScope: history · ${String(args.order)}\n${page.join("\n") || "(empty)"}\n\n---\nThis page: ${offset}..${offset + page.length} / ${entries.length} items\nComplete: ${complete ? "yes" : "no"}${complete ? "" : `\nNext-page cursor: ${cursorFor(scope, offset + page.length)}`}`,
+    };
+}
+function executeContextRead(snapshot, history, args) {
+    if (!record(args) ||
+        !hasOnlyToolKeys(args, ["ref", "cursor", "maxBytes"]) ||
+        typeof args.ref !== "string" ||
+        (args.maxBytes !== undefined && typeof args.maxBytes !== "number") ||
+        !validOptionalCursor(args.cursor))
+        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);
+    const handle = parseStateReadHandle(args.ref);
+    if (handle === null)
+        return {
+            ok: false,
+            markdown: "# Runtime argument error\n\nAn exact state read requires a document @short-ref or one of its #/logical nodes.",
+        };
+    const resolved = snapshot.query({
+        kind: "read_document",
+        document: { shortRef: handle.shortRef },
+        maxBytes: 4,
+    });
+    if (resolved.kind === "error")
+        return renderStateQueryFailure(resolved);
+    if (resolved.kind !== "read_document")
+        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);
+    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);
+}
+function readMarkdownDocument(snapshot, document, maxBytes, cursor) {
+    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);
+    if (result.kind !== "read_document")
+        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}`}`,
+        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) {
+    const result = snapshot.query({
+        kind: "select_node",
+        document: { shortRef: document.shortRef },
+        locator,
+    });
+    if (result.kind === "error")
+        return renderStateQueryFailure(result);
+    if (result.kind !== "select_node")
+        return unexpectedStateQueryResult();
+    const body = result.node.codec === "yaml"
+        ? stringify(toolWorldDocumentValue(result.node.value), {
+            indent: 2,
+            lineWidth: 0,
+        }).trimEnd()
+        : result.node.markdown.trimEnd();
+    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);
+}
+function renderDocumentMetadata(document) {
+    const metadata = stringify({
+        title: document.title,
+        summary: document.summary,
+        aliases: document.aliases,
+    }, { indent: 2, lineWidth: 0 }).trimEnd();
+    return `[Document metadata: not body content; use set_metadata to replace the entire group]\n${metadata}`;
+}
+function toolWorldDocumentValue(value) {
+    if (Array.isArray(value))
+        return value.map(toolWorldDocumentValue);
+    if (!record(value))
+        return value;
+    if (typeof value.$ref === "string" &&
+        record(value.target) &&
+        typeof value.target.shortRef === "string")
+        return { $ref: `@${value.target.shortRef}` };
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+        key,
+        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)
+        return null;
+    try {
+        return {
+            shortRef: match[1],
+            path: match[2] === undefined
+                ? null
+                : match[2].split("/").map(decodeURIComponent),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function renderLocator(locator) {
+    return "yaml" in locator
+        ? `yaml:${locator.yaml.join("/")}`
+        : `markdown:${locator.markdown.join("/")}`;
+}
+function renderStateQueryFailure(result) {
+    return {
+        ok: false,
+        markdown: `# Runtime argument error\n\n${result.diagnostics.map(({ code, message }) => `${code}: ${message}`).join("\n")}`,
+    };
+}
+function unexpectedStateQueryResult() {
+    return {
+        ok: false,
+        markdown: "# Runtime tool rejected\n\nThe world-document query returned an incompatible result type.",
+    };
+}
+function quoteMarkdown(value, indent = "") {
+    return value
+        .split("\n")
+        .map((line) => `${indent}> ${line}`)
+        .join("\n");
+}
+function hasOnlyToolKeys(value, allowed) {
+    const keys = new Set(allowed);
+    return Object.keys(value).every((key) => keys.has(key));
+}
+function validOptionalCursor(value) {
+    return value === undefined || value === null || typeof value === "string";
+}
+function normalizeSearch(value, caseSensitive) {
+    const normalized = value.normalize("NFKC");
+    return caseSensitive ? normalized : normalized.toLocaleLowerCase("und");
+}
+function snippet(text, query) {
+    const position = text
+        .normalize("NFKC")
+        .toLocaleLowerCase("und")
+        .indexOf(query.normalize("NFKC").toLocaleLowerCase("und"));
+    const start = Math.max(0, position - 120);
+    return text.slice(start, start + 240).replace(/\s+/gu, " ");
+}
+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"),
+        offset,
+    }), "utf8").toString("base64url");
+}
+function parseCursor(cursor, scope) {
+    if (cursor === undefined || cursor === null)
+        return 0;
+    if (typeof cursor !== "string")
+        return null;
+    try {
+        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!record(value) ||
+            value.scope !== createHash("sha256").update(scope).digest("hex") ||
+            !Number.isSafeInteger(value.offset) ||
+            Number(value.offset) < 0)
+            return null;
+        return Number(value.offset);
+    }
+    catch {
+        return null;
+    }
+}
+export function parseNarrative(args) {
+    if (!record(args) ||
+        typeof args.text !== "string" ||
+        args.text.length < 1 ||
+        args.text.length > 24_000)
+        throw new PromptCompilationError("narrative_invalid", "Narrative text must contain 1 to 24,000 Unicode characters");
+    return args.text;
+}
+export function fingerprintControl(files) {
+    const hash = createHash("sha256");
+    for (const [path, contents] of Object.entries(files)
+        .filter(([path]) => path.startsWith("control/"))
+        .sort(([a], [b]) => a.localeCompare(b)))
+        hash.update(path).update("\0").update(contents).update("\0");
+    return `sha256:${hash.digest("hex")}`;
+}
+export function isPlayDocumentAuthorizationCheckpoint(value) {
+    if (!record(value) ||
+        !hasExactKeys(value, [
+            "schemaVersion",
+            "kind",
+            "stateFingerprint",
+            "documents",
+        ]) ||
+        value.schemaVersion !== 1 ||
+        value.kind !== "play_document_authorizations" ||
+        typeof value.stateFingerprint !== "string" ||
+        !/^sha256:[0-9a-f]{64}$/u.test(value.stateFingerprint) ||
+        !Array.isArray(value.documents) ||
+        value.documents.length > 100_000)
+        return false;
+    const refs = new Set();
+    for (const document of value.documents) {
+        if (!record(document) ||
+            !hasExactKeys(document, ["shortRef", "locators"]) ||
+            typeof document.shortRef !== "string" ||
+            !/^[a-z][a-z0-9-]*$/u.test(document.shortRef) ||
+            refs.has(document.shortRef) ||
+            (document.locators !== null &&
+                (!Array.isArray(document.locators) ||
+                    document.locators.length > 100_000 ||
+                    !document.locators.every(isPersistedAuthorizedLocator))))
+            return false;
+        refs.add(document.shortRef);
+    }
+    return true;
+}
+function fingerprintStateFiles(files) {
+    const hash = createHash("sha256");
+    for (const [path, contents] of Object.entries(files)
+        .filter(([path]) => path.startsWith("state/"))
+        .sort(([left], [right]) => left.localeCompare(right)))
+        hash.update(path).update("\0").update(contents).update("\0");
+    return `sha256:${hash.digest("hex")}`;
+}
+function isPersistedAuthorizedLocator(value) {
+    if (!record(value))
+        return false;
+    if (hasExactKeys(value, ["yaml"]))
+        return (Array.isArray(value.yaml) &&
+            value.yaml.length <= 64 &&
+            value.yaml.every((segment) => typeof segment === "string" ||
+                (Number.isSafeInteger(segment) && Number(segment) >= 0)));
+    if (hasExactKeys(value, ["markdown"]))
+        return (Array.isArray(value.markdown) &&
+            value.markdown.length <= 64 &&
+            value.markdown.every((segment) => typeof segment === "string"));
+    return false;
+}
+function hasExactKeys(value, expected) {
+    const keys = Object.keys(value);
+    return (keys.length === expected.length &&
+        expected.every((key) => Object.hasOwn(value, key)));
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}