narraeon 0.4.0 → 0.5.0

package/dist/node/runtime/world/FileNativeWorldStore.js

@@ -1,3 +1,7 @@
+import { FileNativeArtifactStore } from "../artifact/FileNativeArtifactStore.js";
+import { WorldExtensionRequests } from "../extension/WorldExtensionRequests.js";
+import { WorldExtensionControls, extensionDefinitions, } from "../extension/WorldExtensionControls.js";
+import { PackageScriptPermissions } from "../extension/PackageScriptPermissions.js";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -29,10 +33,13 @@ export class FileNativeWorldNotFoundError extends Error {
     }
 }
 export class FileNativeWorldStore {
+    extensionRequests;
+    #documentMaintenanceCache = new Map();
     #worldsRoot;
     #operationsRoot;
     #promptCompiler;
     #activeControlUsers = new Map();
+    #openingWorldRevisions = new Set();
     operations;
     playTimeline;
     playAdvances;
@@ -42,6 +49,7 @@ export class FileNativeWorldStore {
     constructor(dataRoot, options = {}) {
         const root = resolve(dataRoot);
         this.#worldsRoot = join(root, "worlds-file-native");
+        this.extensionRequests = new WorldExtensionRequests(this.#worldsRoot);
         this.#operationsRoot = join(root, "operations");
         this.#promptCompiler =
             options.promptCompiler ?? new FileNativePromptCompiler();
@@ -154,15 +162,56 @@ export class FileNativeWorldStore {
                 throw new FileNativeWorldNotFoundError({ cause: error });
             throw error;
         }
-        return this.operations.withExclusiveWorldStateMutation(worldId, async () => {
+        return this.operations.withExclusiveWorldStateMutation(worldId, () => this.operations.withWorldAuthorityLock(worldId, async () => {
             await rm(root, { recursive: true, force: true });
             this.#currentStorage.delete(worldId);
             return { deleted: true };
-        });
+        }));
+    }
+    async extensionControls(worldId, binding, locale, change) {
+        assertIdentity(worldId, "World ID");
+        const head = await this.currentHead(worldId);
+        const [control, playerViews] = await Promise.all([
+            this.readSurface(worldId, "control"),
+            this.renderPlayerViewsAtHead(worldId, head),
+        ]);
+        const definitions = extensionDefinitions(binding, control.map((file) => ({ ...file, path: `control/${file.path}` })), playerViews.views, locale);
+        return this.operations.withWorldAuthorityLock(worldId, () => FileNativeArtifactStore.withWorldControlsMutation(dirname(this.#worldsRoot), worldId, async () => {
+            // Definitions were loaded before taking the lock; deletion may have
+            // completed while this reader was waiting. Never recreate its shell.
+            await readPublicationAt(join(this.#worldsRoot, worldId));
+            const view = await WorldExtensionControls.resolve(join(this.#worldsRoot, worldId), definitions, binding.id, change);
+            await this.extensionRequests.changed(worldId);
+            return view;
+        }));
+    }
+    async extensionControlsRevision(worldId) {
+        assertIdentity(worldId, "World ID");
+        return (await WorldExtensionControls.read(join(this.#worldsRoot, worldId)))
+            .revision;
+    }
+    async readPackageScriptGrants(worldId) {
+        assertIdentity(worldId, "World ID");
+        await this.currentHead(worldId);
+        return PackageScriptPermissions.read(join(this.#worldsRoot, worldId));
+    }
+    async packageScriptPermissions(worldId, enabled) {
+        assertIdentity(worldId, "World ID");
+        const files = (await this.readSurface(worldId, "control")).map((file) => ({
+            ...file,
+            path: `control/${file.path}`,
+        }));
+        const root = join(this.#worldsRoot, worldId);
+        if (enabled !== undefined)
+            await PackageScriptPermissions.write(root, enabled ? PackageScriptPermissions.currentGrants(files) : []);
+        return PackageScriptPermissions.status(files, await PackageScriptPermissions.read(root));
     }
     async createFromContentPackage(input) {
         assertIdentity(input.operationId, "operation ID");
         assertIdentity(input.sourcePackageId, "Content-package local identity");
+        if (input.sourcePackageTitle !== input.sourcePackageTitle.trim() ||
+            !validWorldName(input.sourcePackageTitle))
+            throw new FileNativeWorldCreationError("content_package_title_invalid", "The source content package has no valid standalone title");
         const inspection = inspectContentPackageCurrentTree(input.packageFiles);
         if (inspection.status !== "usable") {
             throw new FileNativeWorldCreationError("content_package_needs_repair", `Only a content package that passes all validation can create a world: ${inspection.issues
@@ -191,10 +240,12 @@ export class FileNativeWorldStore {
             ...input,
             packageFiles,
         };
-        const sourceFingerprint = fingerprint(packageFiles);
+        const legacySourceFingerprint = fingerprint(packageFiles);
+        const sourceFingerprint = contentPackageCreationFingerprint(input.sourcePackageTitle, packageFiles);
         const previous = await this.#readPublication(input.operationId);
         if (previous !== null) {
-            if (previous.sourceFingerprint !== sourceFingerprint) {
+            if (previous.sourceFingerprint !== sourceFingerprint &&
+                previous.sourceFingerprint !== legacySourceFingerprint) {
                 throw new FileNativeWorldCreationError("operation_conflict", "The same operation ID is bound to a different creation payload");
             }
             const preview = this.#preview(boundInput, previous.worldId);
@@ -221,6 +272,7 @@ export class FileNativeWorldStore {
             ];
             await writeSurface(stagingRoot, "state", state);
             await writeSurface(stagingRoot, "control", control);
+            await PackageScriptPermissions.write(stagingRoot, (input.packageScriptGrants ?? []).filter((grant) => PackageScriptPermissions.currentGrants(packageFiles).includes(grant)));
             await mkdir(join(stagingRoot, "history"), { recursive: true });
             await mkdir(join(stagingRoot, "runtime"), { recursive: true });
             await writeIdempotentText(join(stagingRoot, "history", historySurfaceFiles([openingMessage])[0].path), openingMessage.exactText);
@@ -257,7 +309,7 @@ export class FileNativeWorldStore {
             const publication = {
                 schemaVersion: 1,
                 worldId,
-                title: inspection.displayName,
+                title: input.sourcePackageTitle,
                 parentEndpoint: "genesis",
                 operationId: input.operationId,
                 sourceFingerprint,
@@ -275,7 +327,8 @@ export class FileNativeWorldStore {
             await rm(stagingRoot, { recursive: true, force: true }).catch(() => undefined);
             const recovered = await this.#readPublication(input.operationId);
             if (recovered !== null) {
-                if (recovered.sourceFingerprint === sourceFingerprint) {
+                if (recovered.sourceFingerprint === sourceFingerprint ||
+                    recovered.sourceFingerprint === legacySourceFingerprint) {
                     return {
                         outcome: "created",
                         world: await this.#currentSummary(recovered),
@@ -348,18 +401,117 @@ export class FileNativeWorldStore {
     }
     async saveControlDraft(worldId, files) {
         assertIdentity(worldId, "World ID");
-        await this.ensureCurrentStorage(worldId);
-        const root = join(this.#worldsRoot, worldId);
-        await readPublicationAt(root);
         for (const file of files)
             assertRelativePath(file.path);
-        const staging = join(root, `runtime/.control-draft-${randomUUID()}`);
-        await writeSurface(staging, "control", files);
-        const final = join(root, "runtime/control-draft");
-        await rm(final, { recursive: true, force: true });
-        await rename(join(staging, "control"), final);
-        await rm(staging, { recursive: true, force: true });
-        return { fingerprint: fingerprint(files) };
+        try {
+            return await this.operations.withExclusiveWorldStateMutation(worldId, async () => {
+                await this.ensureCurrentStorage(worldId);
+                const root = join(this.#worldsRoot, worldId);
+                await readPublicationAt(root);
+                const staging = join(root, `runtime/.control-draft-${randomUUID()}`);
+                await writeSurface(staging, "control", files);
+                const final = join(root, "runtime/control-draft");
+                await rm(final, { recursive: true, force: true });
+                await rename(join(staging, "control"), final);
+                await rm(staging, { recursive: true, force: true });
+                return { fingerprint: fingerprint(files) };
+            });
+        }
+        catch (error) {
+            if (error instanceof WorldOperationBusyError)
+                throw new FileNativeWorldCreationError("operation_conflict", "World control drafts are locked while a world revision is open");
+            throw error;
+        }
+    }
+    async acquireWorldRevisionLock(worldId, epochId) {
+        if ((this.#activeControlUsers.get(worldId)?.size ?? 0) > 0 ||
+            this.#openingWorldRevisions.has(worldId))
+            return { kind: "busy" };
+        this.#openingWorldRevisions.add(worldId);
+        try {
+            return await this.operations.acquireWorldRevision(worldId, epochId);
+        }
+        finally {
+            this.#openingWorldRevisions.delete(worldId);
+        }
+    }
+    readWorldRevisionLock(worldId) {
+        return this.operations.readWorldRevisionLock(worldId);
+    }
+    releaseWorldRevisionLock(handle) {
+        return this.operations.releaseWorldRevision(handle);
+    }
+    async assertWorldRevisionUnlocked(worldId) {
+        try {
+            await this.operations.assertWorldRevisionUnlocked(worldId);
+        }
+        catch (error) {
+            if (error instanceof WorldOperationBusyError)
+                throw new FileNativeWorldCreationError("operation_conflict", "World play and other changes are locked while a world revision is open");
+            throw error;
+        }
+    }
+    async bindWorldRevision(handle) {
+        return this.operations.withWorldRevisionLock(handle, () => this.bindPlayCallChain(handle.worldId));
+    }
+    /** Replace control while the matching revision epoch retains exclusive ownership. */
+    async replaceWorldRevisionControl(input) {
+        for (const file of input.files)
+            assertRelativePath(file.path);
+        return this.operations.withWorldRevisionLock(input.handle, async () => {
+            if ((this.#activeControlUsers.get(input.handle.worldId)?.size ?? 0) > 0)
+                throw new FileNativeWorldCreationError("operation_conflict", "World control is frozen by another operation");
+            const root = join(this.#worldsRoot, input.handle.worldId);
+            const currentPath = join(root, "control");
+            const runtimeRoot = join(root, "runtime");
+            const stagingRoot = join(runtimeRoot, `.revision-control-${input.handle.epochId}-next`);
+            const stagedPath = join(stagingRoot, "control");
+            const previousPath = join(runtimeRoot, `.revision-control-${input.handle.epochId}-previous`);
+            let current = await readTree(currentPath);
+            let currentFingerprint = fingerprint(current);
+            const nextFingerprint = fingerprint(input.files);
+            if (currentFingerprint === nextFingerprint) {
+                await rm(stagingRoot, { recursive: true, force: true });
+                await rm(previousPath, { recursive: true, force: true });
+                await syncDirectory(runtimeRoot);
+                return { fingerprint: nextFingerprint };
+            }
+            const previous = await readTree(previousPath);
+            const staged = await readTree(stagedPath);
+            if (current.length === 0 &&
+                fingerprint(previous) === input.expectedFingerprint) {
+                if (fingerprint(staged) === nextFingerprint) {
+                    await rename(stagedPath, currentPath);
+                    await syncDirectory(root);
+                    await syncDirectory(stagingRoot);
+                    await rm(previousPath, { recursive: true, force: true });
+                    await rm(stagingRoot, { recursive: true, force: true });
+                    await syncDirectory(runtimeRoot);
+                    return { fingerprint: nextFingerprint };
+                }
+                await rename(previousPath, currentPath);
+                await syncDirectory(root);
+                await syncDirectory(runtimeRoot);
+                current = await readTree(currentPath);
+                currentFingerprint = fingerprint(current);
+            }
+            if (currentFingerprint !== input.expectedFingerprint)
+                throw new FileNativeWorldCreationError("operation_conflict", "World control changed after this revision epoch opened");
+            await rm(stagingRoot, { recursive: true, force: true });
+            await rm(previousPath, { recursive: true, force: true });
+            await writeSurface(stagingRoot, "control", input.files);
+            await durableTree(stagingRoot);
+            await rename(currentPath, previousPath);
+            await syncDirectory(root);
+            await syncDirectory(runtimeRoot);
+            await rename(stagedPath, currentPath);
+            await syncDirectory(root);
+            await syncDirectory(stagingRoot);
+            await rm(previousPath, { recursive: true, force: true });
+            await rm(stagingRoot, { recursive: true, force: true });
+            await syncDirectory(runtimeRoot);
+            return { fingerprint: nextFingerprint };
+        });
     }
     async previewControlDraft(worldId, prompt) {
         const { state, draft } = await this.#readControlDraft(worldId);
@@ -429,6 +581,8 @@ export class FileNativeWorldStore {
     freezeControl(worldId, operationId) {
         assertIdentity(worldId, "World ID");
         assertIdentity(operationId, "operation ID");
+        if (this.#openingWorldRevisions.has(worldId))
+            throw new FileNativeWorldCreationError("operation_conflict", "World control is locked while a world revision opens");
         const users = this.#activeControlUsers.get(worldId) ?? new Set();
         users.add(operationId);
         this.#activeControlUsers.set(worldId, users);
@@ -518,6 +672,7 @@ export class FileNativeWorldStore {
                     }, {}),
                     additionalMaterials: materials?.items ?? [],
                     history: materializedHistoryRecord(history),
+                    narrativeCheckpoint: await authorityStore.readNarrativeCheckpoint(),
                 };
             });
         }
@@ -527,6 +682,32 @@ export class FileNativeWorldStore {
             throw error;
         }
     }
+    /**
+     * Bind an immutable historical endpoint with the world's current control
+     * surface. This is the same semantic input as a fresh context started while
+     * that endpoint was current, without rematerializing it over today's head.
+     */
+    async bindPlayCallChainAt(worldId, head) {
+        assertIdentity(worldId, "World ID");
+        const [endpoint, control] = await Promise.all([
+            this.recoverEndpoint(worldId, head),
+            this.readSurface(worldId, "control"),
+        ]);
+        return {
+            worldId,
+            parentHead: endpoint.head,
+            files: [...endpoint.state, ...control].reduce((files, { path, contents }, index) => {
+                files[`${index < endpoint.state.length ? "state" : "control"}/${path}`] = contents;
+                return files;
+            }, {}),
+            additionalMaterials: structuredClone(endpoint.additionalMaterials),
+            narrativeCheckpoint: endpoint.narrativeCheckpoint,
+            history: Object.fromEntries(endpoint.history.map(({ messageId, exactText }) => [
+                messageId,
+                exactText,
+            ])),
+        };
+    }
     async reserveOperation(operationId) {
         assertIdentity(operationId, "operation ID");
         await mkdir(this.#operationsRoot, { recursive: true, mode: 0o700 });
@@ -569,6 +750,7 @@ export class FileNativeWorldStore {
                 state: recovered.state,
                 history: recovered.history,
                 additionalMaterials: recovered.additionalMaterials,
+                narrativeCheckpoint: recovered.narrativeCheckpoint,
             };
         }
         catch (error) {
@@ -654,6 +836,8 @@ export class FileNativeWorldStore {
                 const selected = await new FileNativeAuthorityV3(staging).recoverHeadResult();
                 await writeSurface(staging, "state", selected.state);
                 await writeSurface(staging, "control", control);
+                await PackageScriptPermissions.write(staging, await PackageScriptPermissions.read(sourceRoot));
+                await WorldExtensionControls.copy(sourceRoot, staging);
                 await mkdir(join(staging, "history"), { recursive: true });
                 for (const file of historySurfaceFiles(selected.history))
                     await writeIdempotentText(join(staging, "history", file.path), file.contents);
@@ -809,6 +993,16 @@ export class FileNativeWorldStore {
         if (!/^sha256:[a-f0-9]{64}$/u.test(input.requestFingerprint))
             throw new TypeError("Timeline-revision request fingerprint is invalid");
         await this.ensureCurrentStorage(input.worldId);
+        try {
+            return await this.operations.withExclusiveWorldStateMutation(input.worldId, () => this.#reviseTimelineUnlocked(input));
+        }
+        catch (error) {
+            if (error instanceof WorldOperationBusyError)
+                throw new FileNativeWorldCreationError("operation_conflict", "Timeline editing is locked while a world revision is open");
+            throw error;
+        }
+    }
+    async #reviseTimelineUnlocked(input) {
         const existing = await this.getOperationOutcome(input.operationId);
         if (isCommittedOutcome(existing)) {
             const fact = await new FileNativeAuthorityV3(join(this.#worldsRoot, existing.worldId)).authorityFactAt(existing.head);
@@ -864,6 +1058,9 @@ export class FileNativeWorldStore {
                         operationReserved = await this.reserveOperation(input.operationId);
                 }
                 return this.#commitHistoryChange({
+                    ...(input.worldClock === undefined
+                        ? {}
+                        : { worldClock: input.worldClock }),
                     operationId: input.operationId,
                     worldId: input.worldId,
                     parentHead: input.parentHead,
@@ -872,11 +1069,19 @@ export class FileNativeWorldStore {
                     mode: "correction",
                     historyAppend: [],
                     operationReserved,
+                    ...(input.validationControl === undefined
+                        ? {}
+                        : { validationControl: input.validationControl }),
                 });
             };
-            return input.stateOperationClaim === undefined
-                ? await this.operations.withExclusiveWorldStateMutation(input.worldId, commit)
-                : await this.operations.withCorrectionWorldClaim(input.stateOperationClaim, commit);
+            if (input.stateOperationClaim !== undefined &&
+                input.worldRevisionLock !== undefined)
+                throw new TypeError("A correction cannot use two world-operation claims");
+            if (input.worldRevisionLock !== undefined)
+                return await this.operations.withWorldRevisionLock(input.worldRevisionLock, commit);
+            if (input.stateOperationClaim !== undefined)
+                return await this.operations.withCorrectionWorldClaim(input.stateOperationClaim, commit);
+            return await this.operations.withExclusiveWorldStateMutation(input.worldId, commit);
         }
         catch (error) {
             if (error instanceof WorldOperationBusyError)
@@ -893,11 +1098,18 @@ export class FileNativeWorldStore {
         await this.ensureCurrentStorage(input.worldId);
         if (input.historyAppend.length === 0 && input.stateChanges.length === 0)
             throw new TypeError("A call-chain commit cannot omit both narrative and state changes");
-        return this.#commitHistoryChange({
-            ...input,
-            nextMaterials: worldNeutralMaterials(input.worldId, input.nextMaterials),
-            mode: "play",
-        });
+        try {
+            return await this.operations.withExclusiveWorldStateMutation(input.worldId, () => this.#commitHistoryChange({
+                ...input,
+                nextMaterials: worldNeutralMaterials(input.worldId, input.nextMaterials),
+                mode: "play",
+            }));
+        }
+        catch (error) {
+            if (error instanceof WorldOperationBusyError)
+                throw new FileNativeWorldCreationError("operation_conflict", "Play is locked while a world revision is open");
+            throw error;
+        }
     }
     async #commitHistoryChange(input) {
         const existing = await this.getOperationOutcome(input.operationId);
@@ -955,7 +1167,7 @@ export class FileNativeWorldStore {
                 const materialized = await readOptionalJson(join(root, "runtime", "materialized-head.json"));
                 if ((materialized?.head ?? "genesis") !== authority.head)
                     throw new FileNativeWorldCreationError("operation_conflict", "The world has accepted but unrepaired materialization; new competing writes are forbidden");
-                const [basisState, currentControl] = await Promise.all([
+                const [basisState, storedControl] = await Promise.all([
                     authorityStore.recoverState(input.timelineRevision?.restoresHead ?? authority.head),
                     readTree(join(root, "control")),
                 ]);
@@ -983,7 +1195,7 @@ export class FileNativeWorldStore {
                         path: `world/${path}`,
                         contents,
                     })),
-                    ...currentControl.map(({ path, contents }) => ({
+                    ...(input.validationControl ?? storedControl).map(({ path, contents }) => ({
                         path: `control/${path}`,
                         contents,
                     })),
@@ -994,6 +1206,12 @@ export class FileNativeWorldStore {
                     await authorityStore.discardUnacceptedNextEpoch();
                 crashAtFileNativeAuthorityEdge("before_commit_acceptance");
                 const preparedAppend = await authorityStore.prepareAppend({
+                    ...(input.playContext === undefined
+                        ? {}
+                        : { playContext: input.playContext }),
+                    ...(input.worldClock === undefined
+                        ? {}
+                        : { worldClock: input.worldClock }),
                     operationId: input.operationId,
                     parentHead: input.parentHead,
                     ...(input.timelineRevision === undefined
@@ -1003,6 +1221,9 @@ export class FileNativeWorldStore {
                     historyAppend: input.historyAppend,
                     stateChanges: structuredClone(input.stateChanges),
                     nextMaterials: input.nextMaterials,
+                    ...(input.narrativeCheckpoint === undefined
+                        ? {}
+                        : { narrativeCheckpoint: input.narrativeCheckpoint }),
                     ...(input.mode === "correction"
                         ? {
                             correctionTargets: input.stateChanges.map(({ documentId }) => documentId),
@@ -1071,6 +1292,37 @@ export class FileNativeWorldStore {
         const authority = await new FileNativeAuthorityV3(root).readHistory();
         return structuredClone(authority);
     }
+    async inspectDocumentMaintenance(worldId, head) {
+        try {
+            return {
+                documentMaintenance: await this.readDocumentMaintenance(worldId, head),
+            };
+        }
+        catch (error) {
+            return {
+                documentMaintenance: {},
+                documentMaintenanceUnavailableReason: error instanceof Error
+                    ? error.message
+                    : "Document diagnostics unavailable",
+            };
+        }
+    }
+    async readDocumentMaintenance(worldId, head) {
+        assertIdentity(worldId, "World ID");
+        await this.ensureCurrentStorage(worldId);
+        const root = join(this.#worldsRoot, worldId);
+        await readPublicationAt(root);
+        const authority = new FileNativeAuthorityV3(root);
+        const selectedHead = head ?? (await authority.readHead()).head;
+        let cache = this.#documentMaintenanceCache.get(worldId);
+        if (cache === undefined) {
+            cache = new Map();
+            if (this.#documentMaintenanceCache.size >= 8)
+                this.#documentMaintenanceCache.delete(this.#documentMaintenanceCache.keys().next().value);
+            this.#documentMaintenanceCache.set(worldId, cache);
+        }
+        return readDocumentMaintenanceFacts(authority, selectedHead, cache);
+    }
     async readAuthorityEndpoint(worldId, endpoint) {
         const recovered = await this.recoverEndpoint(worldId, endpoint);
         return {
@@ -1206,7 +1458,6 @@ function assertEquivalentWorldDocumentSnapshots(contentDocuments, worldState) {
                 document: {
                     logicalPath: `state/${document.path.slice("world/".length)}`,
                 },
-                maxBytes: 4,
             });
             return (!result.ok ||
                 result.kind !== "read_document" ||
@@ -1265,6 +1516,16 @@ function fingerprint(files) {
     }
     return `sha256:${hash.digest("hex")}`;
 }
+function contentPackageCreationFingerprint(title, files) {
+    const hash = createHash("sha256");
+    hash
+        .update("narraeon.file-native-world-creation/v2")
+        .update("\0")
+        .update(title)
+        .update("\0")
+        .update(fingerprint(files));
+    return `sha256:${hash.digest("hex")}`;
+}
 function operationDigest(operationId) {
     return createHash("sha256").update(operationId).digest("hex");
 }
@@ -1634,6 +1895,8 @@ function authorityCommitMatchesInput(commit, input) {
         ? input.stateChanges.map(({ documentId }) => documentId)
         : undefined;
     return (commit.mode === input.mode &&
+        commit.playContext === input.playContext &&
+        commit.worldClock === input.worldClock &&
         commit.auditParent.head === input.parentHead &&
         commit.timelineParent.head ===
             (input.timelineRevision?.restoresHead ?? input.parentHead) &&
@@ -1641,6 +1904,7 @@ function authorityCommitMatchesInput(commit, input) {
         stateChangesMatch &&
         isDeepStrictEqual(commit.nextAdditionalMaterials, input.nextMaterials) &&
         isDeepStrictEqual(commit.timelineRevision, input.timelineRevision) &&
+        isDeepStrictEqual(commit.narrativeCheckpoint, input.narrativeCheckpoint) &&
         isDeepStrictEqual(commit.correctionTargets, expectedCorrection) &&
         commit.corrects ===
             (input.mode === "correction" ? input.parentHead : undefined));
@@ -1857,3 +2121,4 @@ function crashAtFileNativeAuthorityEdge(edge) {
         process.kill(process.pid, "SIGKILL");
     }
 }
+import { readDocumentMaintenanceFacts, } from "./WorldDocumentMaintenance.js";

package/dist/node/runtime/world/PlayerViewBindings.js

@@ -0,0 +1,30 @@
+import { PlayerViewRenderer } from "./PlayerViewRenderer.js";
+/** An annotation about UI reads, never document content or write permission. */
+export function renderPlayerViewBindings(snapshot, shortRef, locale = "en") {
+    const control = snapshot.files.find(({ path }) => path === "control/player-views.yaml")?.contents;
+    if (control === undefined)
+        return "";
+    const { bindings } = new PlayerViewRenderer().inspect({ snapshot, control });
+    const selected = bindings.filter((binding) => shortRef === undefined || binding.shortRef === shortRef);
+    if (selected.length === 0)
+        return "";
+    const zh = locale === "zh-CN";
+    return [
+        zh
+            ? "## 玩家视图读取绑定（Runtime 标记，非正文）"
+            : "## Player-view read bindings (Runtime annotation, outside document bodies)",
+        zh
+            ? "以下范围直接用于玩家界面；这里只标明读取绑定，不授予读取或写入权限，也不展开引用目标。"
+            : "These scopes feed the player interface. This annotation grants no read or write permission and does not expand reference targets.",
+        ...selected.map(({ viewTitle, label, shortRef: ref, locator }) => {
+            const scope = locator === null
+                ? zh
+                    ? "（整份文档）"
+                    : " (whole document)"
+                : "yaml" in locator
+                    ? `#yaml:${JSON.stringify(locator.yaml)}`
+                    : `#markdown:${JSON.stringify(locator.markdown)}`;
+            return `- ${viewTitle} · ${label} → @${ref}${scope}`;
+        }),
+    ].join("\n");
+}

package/dist/node/runtime/world/PlayerViewRenderer.js

@@ -2,16 +2,22 @@ import { parseDocument } from "yaml";
 const maxItemsPerView = 128;
 const maxRenderedBytesPerView = 64 * 1024;
 const maxRenderedDepth = 16;
-const maxDocumentReadBytes = 65_536;
 export class PlayerViewRenderer {
     render(input) {
+        const { views, diagnostics } = this.inspect(input);
+        return { views, diagnostics };
+    }
+    /** Binding facts come from the exact successful UI selections. */
+    inspect(input) {
         const diagnostics = [];
+        const bindings = [];
         const control = parseControlYaml(input.control);
         if (!isRecord(control) ||
             control.format !== "narraeon.player-views/v1" ||
             !Array.isArray(control.views)) {
             return {
                 views: [],
+                bindings,
                 diagnostics: [
                     {
                         code: "invalid_control",
@@ -73,10 +79,18 @@ export class PlayerViewRenderer {
                 }
                 renderedBytes += itemBytes;
                 view.items.push(resolved.item);
+                bindings.push({
+                    viewId: view.id,
+                    viewTitle: view.title,
+                    itemId: resolved.item.id,
+                    label: resolved.item.label,
+                    shortRef: resolved.shortRef,
+                    locator: resolved.locator,
+                });
             }
             views.push(view);
         }
-        return { views, diagnostics };
+        return { views, diagnostics, bindings };
     }
 }
 function resolveItem(item, snapshot) {
@@ -99,6 +113,8 @@ function resolveItem(item, snapshot) {
         return wholeDocument.ok
             ? {
                 ok: true,
+                shortRef: wholeDocument.shortRef,
+                locator: null,
                 item: {
                     id: itemId,
                     label: item.label,
@@ -131,6 +147,8 @@ function resolveItem(item, snapshot) {
         };
     return {
         ok: true,
+        shortRef: selected.scope.document.shortRef,
+        locator: selected.node.locator,
         item: {
             id: itemId,
             label: item.label,
@@ -152,7 +170,6 @@ function resolveWholeDocument(snapshot, selector, handle, expectedCodec) {
     const read = snapshot.query({
         kind: "read_document",
         document: selector,
-        maxBytes: maxDocumentReadBytes,
     });
     if (read.kind === "error")
         return selectionFailure(read, handle);
@@ -169,37 +186,13 @@ function resolveWholeDocument(snapshot, selector, handle, expectedCodec) {
             message: "The selector codec does not match the target document",
         };
     if (read.codec === "markdown")
-        return readWholeMarkdown(snapshot, selector, handle, read);
-    return selectYamlRoot(snapshot, selector, handle);
-}
-function readWholeMarkdown(snapshot, selector, handle, firstPage) {
-    let page = firstPage;
-    const chunks = [page.body];
-    while (!page.page.complete) {
-        if (page.page.nextCursor === null)
-            return {
-                ok: false,
-                code: "unresolved_selector",
-                message: "The exact selector cannot currently be resolved",
-            };
-        const nextPage = snapshot.query({
-            kind: "read_document",
-            document: selector,
-            maxBytes: maxDocumentReadBytes,
-            cursor: page.page.nextCursor,
-        });
-        if (nextPage.kind === "error")
-            return selectionFailure(nextPage, handle);
-        if (nextPage.kind !== "read_document" || nextPage.codec !== "markdown")
-            return {
-                ok: false,
-                code: "unresolved_selector",
-                message: "The exact selector cannot currently be resolved",
-            };
-        chunks.push(nextPage.body);
-        page = nextPage;
-    }
-    return { ok: true, value: chunks.join("").trim() };
+        return {
+            ok: true,
+            value: read.body.trim(),
+            shortRef: read.document.shortRef,
+        };
+    const root = selectYamlRoot(snapshot, selector, handle);
+    return root.ok ? { ...root, shortRef: read.document.shortRef } : root;
 }
 function selectYamlRoot(snapshot, selector, handle) {
     const selected = snapshot.query({