narraeon 0.4.0 → 0.5.1

package/dist/node/runtime/artifact/FileNativeArtifactStore.js

@@ -1,10 +1,12 @@
+import { WorldExtensionRequests } from "../extension/WorldExtensionRequests.js";
+import { isWorldExtensionControl, } from "../../protocol/worldExtensions.js";
 import { Buffer } from "node:buffer";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, open, readdir, readFile, readlink, rename, rm, stat, } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
-import { validatePlayPresetArtifactPayload, } from "../play/FileNativePlayPresetStore.js";
+import { validatePlayPresetArtifactPayload, isFrozenArtifactPresentation, } from "../play/FileNativePlayPresetStore.js";
 export class ArtifactStoreInvariantError extends Error {
     constructor(message, options) {
         super(message, options);
@@ -26,11 +28,163 @@ const maxPayloadBytes = 4 * 1024 * 1024;
  */
 export class FileNativeArtifactStore {
     #root;
+    #extensionControls;
+    #worldsRoot;
     #memoryRecords = new Map();
     #memoryEvents = new Map();
     #mutationContext = new AsyncLocalStorage();
     constructor(dataRoot) {
         this.#root = join(resolve(dataRoot), "artifact-store");
+        this.#extensionControls = new WorldExtensionRequests(join(resolve(dataRoot), "worlds-file-native"));
+        this.#worldsRoot = join(resolve(dataRoot), "worlds-file-native");
+    }
+    /** Control acceptance and artifact publication share one persistent lock.
+     * Callers holding the Authority lock always acquire it before this lock. */
+    static withWorldControlsMutation(dataRoot, worldId, action) {
+        return withArtifactWorldLock(artifactWorldLockPath(dataRoot, worldId), action);
+    }
+    /** The immutable closure publishes atomically with the derived world. */
+    async stageFork(input) {
+        await this.#withWorldMutation(input.sourceWorldId, async () => {
+            const projection = await this.readActiveProjection(input.sourceWorldId, undefined, input.timeline);
+            const retained = new Set(projection
+                .filter((item) => item.save === "commit" && item.attachment !== undefined)
+                .map((item) => item.recordId));
+            const effective = (await this.#effectiveRecords(input.sourceWorldId)).filter(({ record }) => retained.has(record.recordId));
+            const operations = [];
+            const records = [];
+            const events = [];
+            let sequence = Math.max(0, ...effective.map(({ record }) => record.sequence));
+            for (const { record, head } of effective) {
+                const source = (await this.#readOperation(record.operationId));
+                const operationId = `artifact-fork:${input.targetWorldId}:${identityHash(record.operationId)}`;
+                if (!operations.some((operation) => operation.context.operationId === operationId)) {
+                    operations.push({
+                        ...source,
+                        context: {
+                            ...source.context,
+                            worldId: input.targetWorldId,
+                            operationId,
+                        },
+                    });
+                }
+                const copy = {
+                    ...record,
+                    worldId: input.targetWorldId,
+                    operationId,
+                    sequence: record.sequence,
+                };
+                copy.recordFingerprint = rawRecordFingerprint(copy);
+                records.push(copy);
+                events.push({
+                    schemaVersion: 1,
+                    kind: "activate",
+                    sequence: ++sequence,
+                    operationId,
+                    recordId: copy.recordId,
+                });
+                events.push({
+                    schemaVersion: 1,
+                    kind: "bind_head",
+                    sequence: ++sequence,
+                    operationId,
+                    recordId: copy.recordId,
+                    head: head,
+                });
+            }
+            const snapshot = {
+                schemaVersion: 1,
+                worldId: input.targetWorldId,
+                operations,
+                records,
+                events,
+            };
+            await mkdir(join(input.targetWorldRoot, "runtime"), { recursive: true });
+            await writeDurableJson(join(input.targetWorldRoot, "runtime", "artifact-fork.json"), snapshot, true);
+        });
+    }
+    async #ensureForkRestored(worldId) {
+        if (dirname(resolve(this.#worldsRoot, worldId)) !== this.#worldsRoot)
+            return;
+        try {
+            await stat(join(this.#worldRoot(worldId), "fork-restored.json"));
+            return;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        try {
+            await stat(join(this.#worldsRoot, worldId, "runtime", "artifact-fork.json"));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return;
+            throw error;
+        }
+        await this.#withWorldMutation(worldId, () => Promise.resolve());
+    }
+    async #restoreFork(worldId) {
+        if (dirname(resolve(this.#worldsRoot, worldId)) !== this.#worldsRoot)
+            return;
+        const marker = join(this.#worldRoot(worldId), "fork-restored.json");
+        try {
+            await readFile(marker);
+            return;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        let snapshot;
+        try {
+            snapshot = parseArtifactJson(await readFile(join(this.#worldsRoot, worldId, "runtime", "artifact-fork.json"), "utf8"), "artifact fork");
+        }
+        catch (error) {
+            if (isMissing(error))
+                return;
+            throw error;
+        }
+        if (!isRecord(snapshot) ||
+            !hasExactKeys(snapshot, [
+                "schemaVersion",
+                "worldId",
+                "operations",
+                "records",
+                "events",
+            ]) ||
+            snapshot.schemaVersion !== 1 ||
+            snapshot.worldId !== worldId ||
+            !Array.isArray(snapshot.operations) ||
+            !Array.isArray(snapshot.records) ||
+            !Array.isArray(snapshot.events))
+            throw new ArtifactStoreCorruptionError("Artifact fork snapshot is invalid");
+        for (const operation of snapshot.operations) {
+            assertOperation(operation);
+            if (operation.context.worldId !== worldId)
+                throw new ArtifactStoreCorruptionError("Artifact fork world mismatch");
+        }
+        for (const record of snapshot.records) {
+            assertRawRecord(record);
+            if (record.worldId !== worldId ||
+                !snapshot.operations.some((operation) => operation.context.operationId === record.operationId))
+                throw new ArtifactStoreCorruptionError("Artifact fork record mismatch");
+        }
+        for (const event of snapshot.events) {
+            assertEvent(event);
+            if (!snapshot.records.some((record) => record.recordId === event.recordId &&
+                record.operationId === event.operationId))
+                throw new ArtifactStoreCorruptionError("Artifact fork event mismatch");
+        }
+        // No mutation can start until this idempotent restore finishes under the world lock.
+        for (const operation of snapshot.operations)
+            await this.#writeOperation(operation);
+        for (const record of snapshot.records)
+            await writeDurableJson(join(this.#worldRoot(worldId), "records", artifactSequenceFileName(record.sequence)), record, false);
+        for (const event of snapshot.events)
+            await writeDurableJson(join(this.#worldRoot(worldId), "events", artifactSequenceFileName(event.sequence)), event, false);
+        await mkdir(this.#worldRoot(worldId), { recursive: true });
+        await writeDurableJson(marker, { schemaVersion: 1 }, false);
     }
     async beginOperation(context) {
         return this.#withWorldMutation(context.worldId, () => this.#beginOperation(context));
@@ -106,6 +260,22 @@ export class FileNativeArtifactStore {
             operation.status === "completed" ||
             operation.artifactProjectionStatus === "superseded")
             return;
+        const mounts = [
+            ...new Set(Object.values(context.frozenPresentations ?? {})
+                .map((item) => item.mount)
+                .concat(context.frozenResources?.mount === undefined
+                ? []
+                : [context.frozenResources.mount])),
+        ];
+        operation.requests = [
+            ...(operation.requests ?? []).filter((item) => item.requestId !== context.requestId),
+            {
+                requestId: context.requestId,
+                displayName: context.displayName ?? context.requestId,
+                mounts,
+                status: "running",
+            },
+        ];
         const current = operation.requestAttempts[context.requestId];
         if (current !== undefined && context.requestAttempt < current)
             return;
@@ -139,6 +309,19 @@ export class FileNativeArtifactStore {
             await this.#appendRecordEvent(record, event);
         }
     }
+    async finishRequest(context, failed) {
+        await this.#withWorldMutation(context.worldId, async () => {
+            const operation = await this.#readOperation(context.operationId);
+            if (operation?.requestAttempts[context.requestId] !== context.requestAttempt)
+                return;
+            await this.#writeOperation({
+                ...operation,
+                requests: (operation.requests ?? []).map((item) => item.requestId === context.requestId
+                    ? { ...item, status: failed ? "failed" : "completed" }
+                    : item),
+            });
+        });
+    }
     async reconcileHead(worldId, head, exceptOperationId) {
         return this.#withWorldMutation(worldId, () => this.#reconcileHead(worldId, head, exceptOperationId));
     }
@@ -257,7 +440,9 @@ export class FileNativeArtifactStore {
         if (totalBytes + payloadBytes > input.context.maxArtifactBytes)
             return artifactFailure("Follow-up request artifacts exceed maxArtifactBytes");
         const record = await this.#newRecord(input, declaration, payload.value, fingerprint, callFingerprint);
-        const stale = isStaleOperation(operation) || staleAttempt;
+        const stale = isStaleOperation(operation) ||
+            staleAttempt ||
+            !(await this.#extensionControls.visible(record.worldId, record));
         if (declaration.save === "none") {
             const records = this.#memoryRecords.get(input.context.operationId) ?? [];
             records.push(record);
@@ -337,7 +522,9 @@ export class FileNativeArtifactStore {
             event.operationId === record.operationId &&
             event.recordId === record.recordId &&
             (head === undefined || event.head === head));
-        const stale = isStaleOperation(operation) || currentAttempt !== record.requestAttempt;
+        const stale = isStaleOperation(operation) ||
+            currentAttempt !== record.requestAttempt ||
+            !(await this.#extensionControls.visible(record.worldId, record));
         if (stale) {
             if (!hasEvent("supersede"))
                 await this.#appendRecordEvent(record, {
@@ -416,7 +603,9 @@ export class FileNativeArtifactStore {
             };
         }
         const staleAttempt = currentAttempt !== input.context.requestAttempt;
-        if (isStaleOperation(operation) || staleAttempt) {
+        if (isStaleOperation(operation) ||
+            staleAttempt ||
+            !(await this.#extensionControls.visible(input.context.worldId, input.context))) {
             const event = {
                 schemaVersion: 1,
                 kind: "ignored_call",
@@ -707,6 +896,7 @@ export class FileNativeArtifactStore {
         return operation === null ? null : summary(operation);
     }
     async readExtensionSummaries(worldId) {
+        await this.#ensureForkRestored(worldId);
         return (await this.#operationsForWorld(worldId))
             .filter((operation) => operation.status !== "core_failed" &&
             !(operation.status === "completed" &&
@@ -744,7 +934,8 @@ export class FileNativeArtifactStore {
         await this.#writeOperation(next);
         return summary(next);
     }
-    async readActiveProjection(worldId, channel) {
+    async readActiveProjection(worldId, channel, timeline) {
+        await this.#ensureForkRestored(worldId);
         const effective = await this.#effectiveRecords(worldId);
         const operationStates = new Map();
         for (const item of effective)
@@ -762,6 +953,12 @@ export class FileNativeArtifactStore {
             if (operation === undefined ||
                 operation.artifactProjectionStatus === "superseded")
                 return false;
+            if (timeline !== undefined &&
+                operation.context.attachment !== undefined &&
+                !timeline.some((target) => target.contextId === operation.context.attachment?.contextId &&
+                    target.eventId === operation.context.attachment?.eventId &&
+                    target.head === operation.context.attachment?.head))
+                return false;
             if (record.projection === "transient" && !isActiveInteraction(operation))
                 return false;
             if (record.save === "operation" && operation?.status === "completed")
@@ -770,8 +967,17 @@ export class FileNativeArtifactStore {
                 return false;
             return true;
         });
-        const selected = selectProjection(active);
+        const visible = await Promise.all(active.map(async (item) => (await this.#extensionControls.visible(worldId, item.record))
+            ? item
+            : null));
+        const selected = selectProjection(visible.filter((item) => item !== null));
         return selected.map(({ record, head }) => ({
+            ...(operationStates.get(record.operationId)?.context.attachment ===
+                undefined
+                ? {}
+                : {
+                    attachment: structuredClone(operationStates.get(record.operationId).context.attachment),
+                }),
             recordId: record.recordId,
             worldId: record.worldId,
             operationId: record.operationId,
@@ -788,6 +994,12 @@ export class FileNativeArtifactStore {
             ...(record.rendererRevision === undefined
                 ? {}
                 : { rendererRevision: record.rendererRevision }),
+            ...(record.extensionControl === undefined
+                ? {}
+                : { extensionControl: structuredClone(record.extensionControl) }),
+            ...(record.frozenPresentation === undefined
+                ? {}
+                : { frozenPresentation: structuredClone(record.frozenPresentation) }),
             payload: structuredClone(record.payload),
             projection: record.projection,
             save: record.save,
@@ -796,11 +1008,21 @@ export class FileNativeArtifactStore {
         }));
     }
     async readDebug(worldId, operationId) {
+        await this.#ensureForkRestored(worldId);
         const effective = await this.#effectiveRecords(worldId);
+        const operations = new Map((await this.#operationsForWorld(worldId)).map((operation) => [
+            operation.context.operationId,
+            operation,
+        ]));
         return effective
             .filter(({ record }) => operationId === undefined || record.operationId === operationId)
             .sort((left, right) => left.record.sequence - right.record.sequence)
             .map(({ record, status, head }) => ({
+            ...(operations.get(record.operationId)?.context.attachment === undefined
+                ? {}
+                : {
+                    attachment: structuredClone(operations.get(record.operationId).context.attachment),
+                }),
             recordId: record.recordId,
             sequence: record.sequence,
             operationId: record.operationId,
@@ -823,6 +1045,12 @@ export class FileNativeArtifactStore {
             save: record.save,
             projection: record.projection,
             payloadBytes: byteLength(record.payload, record.contentType),
+            ...(record.extensionControl === undefined
+                ? {}
+                : { extensionControl: structuredClone(record.extensionControl) }),
+            ...(record.frozenPresentation === undefined
+                ? {}
+                : { frozenPresentation: structuredClone(record.frozenPresentation) }),
             payload: structuredClone(record.payload),
             payloadFingerprint: record.payloadFingerprint,
             status,
@@ -854,6 +1082,23 @@ export class FileNativeArtifactStore {
             ...(declaration.rendererRevision === undefined
                 ? {}
                 : { rendererRevision: declaration.rendererRevision }),
+            ...(input.context.extensionControl === undefined
+                ? {}
+                : {
+                    extensionControl: structuredClone(input.context.extensionControl),
+                }),
+            ...(input.context.frozenPresentations?.[declaration.name] !== undefined
+                ? {
+                    frozenPresentation: structuredClone(input.context.frozenPresentations[declaration.name]),
+                }
+                : input.context.frozenResources === undefined
+                    ? {}
+                    : {
+                        frozenPresentation: {
+                            ...structuredClone(input.context.frozenResources),
+                            declaration: structuredClone(declaration),
+                        },
+                    }),
             payload: structuredClone(payload),
             save: declaration.save,
             projection: declaration.strategy,
@@ -1178,12 +1423,18 @@ export class FileNativeArtifactStore {
         const active = this.#mutationContext.getStore();
         if (active?.has(worldId) === true)
             return action();
-        return withArtifactWorldLock(join(this.#root, "locks", identityHash(worldId)), () => this.#mutationContext.run(new Set([...(active ?? []), worldId]), action));
+        return withArtifactWorldLock(artifactWorldLockPath(dirname(this.#root), worldId), () => this.#mutationContext.run(new Set([...(active ?? []), worldId]), async () => {
+            await this.#restoreFork(worldId);
+            return action();
+        }));
     }
     #worldRoot(worldId) {
         return join(this.#root, "worlds", identityHash(worldId));
     }
 }
+function artifactWorldLockPath(dataRoot, worldId) {
+    return join(resolve(dataRoot), "runtime-locks", "artifacts", identityHash(worldId));
+}
 const artifactWorldLockStaleMilliseconds = 30_000;
 const artifactWorldLockWaitMilliseconds = 30_000;
 async function withArtifactWorldLock(path, action) {
@@ -1489,6 +1740,9 @@ function artifactCallFingerprint(toolName, context, parameters) {
         playPresetId: context.playPresetId,
         playPresetRevision: context.playPresetRevision,
         playPresetScriptsEnabled: context.playPresetScriptsEnabled,
+        ...(context.extensionControl === undefined
+            ? {}
+            : { extensionControl: context.extensionControl }),
         requestId: context.requestId,
         requestAttempt: context.requestAttempt,
         parameters,
@@ -1570,6 +1824,12 @@ function artifactSequenceFileName(sequence) {
 }
 function summary(operation) {
     return {
+        ...(operation.context.attachment === undefined
+            ? {}
+            : { attachment: structuredClone(operation.context.attachment) }),
+        ...(operation.requests === undefined
+            ? {}
+            : { requests: structuredClone(operation.requests) }),
         operationId: operation.context.operationId,
         status: operation.extensionStatus,
         ...(operation.message === undefined ? {} : { message: operation.message }),
@@ -1604,8 +1864,10 @@ function assertContext(context) {
             "playPresetId",
             "playPresetRevision",
             "playPresetScriptsEnabled",
-        ]))
+        ], ["attachment"]))
         throw new ArtifactStoreInvariantError("Artifact operation context has an invalid structure");
+    if (context.attachment !== undefined && !validAttachment(context.attachment))
+        throw new ArtifactStoreInvariantError("Artifact reply attachment is invalid");
     for (const [key, value] of Object.entries({
         worldId: context.worldId,
         parentHead: context.parentHead,
@@ -1629,7 +1891,13 @@ function assertRequestContext(context) {
         playPresetId: context.playPresetId,
         playPresetRevision: context.playPresetRevision,
         playPresetScriptsEnabled: context.playPresetScriptsEnabled,
+        ...(context.attachment === undefined
+            ? {}
+            : { attachment: context.attachment }),
     });
+    if (context.extensionControl !== undefined &&
+        !isWorldExtensionControl(context.extensionControl))
+        throw new ArtifactStoreInvariantError("Invalid extension control generation");
     if (context.requestId.trim() === "" ||
         !Number.isInteger(context.requestAttempt))
         throw new ArtifactStoreInvariantError("Artifact request attempt is invalid");
@@ -1637,7 +1905,9 @@ function assertRequestContext(context) {
         throw new ArtifactStoreInvariantError("Artifact request-attempt budget is invalid");
 }
 function sameContext(left, right) {
-    return (left.worldId === right.worldId &&
+    return (stableSerialize(left.attachment ?? null) ===
+        stableSerialize(right.attachment ?? null) &&
+        left.worldId === right.worldId &&
         left.parentHead === right.parentHead &&
         left.operationId === right.operationId &&
         left.playPresetId === right.playPresetId &&
@@ -1672,7 +1942,17 @@ function assertRawRecord(record) {
             "payloadFingerprint",
             "recordFingerprint",
             "status",
-        ], ["key", "renderer", "rendererRevision"]) ||
+        ], [
+            "key",
+            "renderer",
+            "rendererRevision",
+            "frozenPresentation",
+            "extensionControl",
+        ]) ||
+        (record.extensionControl !== undefined &&
+            !isWorldExtensionControl(record.extensionControl)) ||
+        (record.frozenPresentation !== undefined &&
+            !isFrozenArtifactPresentation(record.frozenPresentation)) ||
         record.schemaVersion !== 1 ||
         !isNonEmptyString(record.recordId) ||
         !Number.isSafeInteger(record.sequence) ||
@@ -1733,7 +2013,29 @@ function assertOperation(operation) {
             "completedRequests",
             "artifactProjectionStatus",
             "requestAttempts",
-        ], ["message", "head"]) ||
+        ], ["message", "head", "requests"]) ||
+        (operation.requests !== undefined &&
+            (!Array.isArray(operation.requests) ||
+                !operation.requests.every((item) => isRecord(item) &&
+                    hasExactKeys(item, [
+                        "requestId",
+                        "displayName",
+                        "mounts",
+                        "status",
+                    ]) &&
+                    isNonEmptyString(item.requestId) &&
+                    isNonEmptyString(item.displayName) &&
+                    Array.isArray(item.mounts) &&
+                    item.mounts.every((mount) => typeof mount === "string" &&
+                        [
+                            "story",
+                            "sidebar",
+                            "composer_above",
+                            "composer_below",
+                            "overlay",
+                            "debug",
+                        ].includes(mount)) &&
+                    ["running", "completed", "failed"].includes(item.status)))) ||
         operation.schemaVersion !== 1 ||
         !isRecord(context) ||
         !hasExactKeys(context, [
@@ -1743,7 +2045,9 @@ function assertOperation(operation) {
             "playPresetId",
             "playPresetRevision",
             "playPresetScriptsEnabled",
-        ]) ||
+        ], ["attachment"]) ||
+        (context.attachment !== undefined &&
+            !validAttachment(context.attachment)) ||
         !isNonEmptyString(context.worldId) ||
         !isNonEmptyString(context.parentHead) ||
         !isNonEmptyString(context.operationId) ||
@@ -1912,3 +2216,13 @@ function isMissing(error) {
 function isAlreadyExists(error) {
     return isRecord(error) && error.code === "EEXIST";
 }
+function validAttachment(value) {
+    return (isRecord(value) &&
+        hasExactKeys(value, ["contextId", "eventId", "runId", "head"]) &&
+        isNonEmptyString(value.head) &&
+        isNonEmptyString(value.contextId) &&
+        isNonEmptyString(value.runId) &&
+        typeof value.eventId === "number" &&
+        Number.isSafeInteger(value.eventId) &&
+        value.eventId > 0);
+}

package/dist/node/runtime/authoring/AuthoringRequestSnapshot.js

@@ -0,0 +1,63 @@
+import { isPlayPresetBinding, } from "../play/FileNativePlayPresetStore.js";
+export function validAuthoringRequests(value, validPrompt, session) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        !Array.isArray(session.modelItems) ||
+        !Array.isArray(session.completedRequestIds))
+        return false;
+    const items = session.modelItems;
+    const completed = session.completedRequestIds;
+    const ids = new Set();
+    let previous = -1;
+    let lastRequestId;
+    const valid = value.every((raw) => {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return false;
+        const item = raw;
+        if (Object.keys(item).length !== 4 ||
+            typeof item.requestId !== "string" ||
+            !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/u.test(item.requestId) ||
+            ids.has(item.requestId) ||
+            !Number.isSafeInteger(item.modelItemStart) ||
+            item.modelItemStart <= previous ||
+            !(item.requestId === session.activeRequestId ||
+                completed.includes(item.requestId)) ||
+            !isUserItem(items[item.modelItemStart]) ||
+            !validPrompt(item.bootstrap) ||
+            !isPlayPresetBinding(item.playPreset))
+            return false;
+        ids.add(item.requestId);
+        lastRequestId = item.requestId;
+        previous = item.modelItemStart;
+        return true;
+    });
+    return (valid &&
+        (session.activeRequestId === null ||
+            lastRequestId === session.activeRequestId));
+}
+function isUserItem(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "kind" in value &&
+        value.kind === "user");
+}
+export function authoringRequestPreviews(session) {
+    const requests = session.requests ?? [];
+    const legacy = requests.length === 0 || requests[0].modelItemStart > 0;
+    return [
+        ...(legacy
+            ? [
+                {
+                    requestId: session.creationRequestId,
+                    compilation: structuredClone(session.bootstrap),
+                    legacyBootstrap: true,
+                },
+            ]
+            : []),
+        ...requests.map(({ requestId, bootstrap }) => ({
+            requestId,
+            compilation: structuredClone(bootstrap),
+            legacyBootstrap: false,
+        })),
+    ];
+}