narraeon 0.1.0

package/dist/node/runtime/extension/FrontendExtensionBundle.js

@@ -0,0 +1,229 @@
+import { parsePlayPresetRegexAsset, } from "../play/FileNativePlayPresetStore.js";
+export function projectArtifactForFrontend(artifact, binding, failure = "missing_revision") {
+    const preset = {
+        id: artifact.playPresetId,
+        revision: artifact.playPresetRevision,
+    };
+    if (binding === null)
+        return missingBundle(preset, "The frozen play-preset revision is unavailable and cannot be replaced with the current revision", failure);
+    if (binding.id !== artifact.playPresetId ||
+        binding.revision !== artifact.playPresetRevision)
+        return missingBundle(preset, "The play-preset binding does not match the artifact's frozen identity", "invalid_revision");
+    const followup = binding.definition.followups.find(({ id }) => id === artifact.requestId);
+    const declaration = followup?.artifacts.find(({ name }) => name === artifact.output);
+    if (declaration === undefined)
+        return {
+            ...missingBundle(preset, "The artifact declaration is missing from the frozen revision"),
+            status: "missing_declaration",
+        };
+    if (!artifactMatchesDeclaration(artifact, declaration))
+        return {
+            ...missingBundle(preset, "The raw artifact contract does not match the frozen declaration", "invalid_revision"),
+            status: "invalid_revision",
+        };
+    try {
+        const frozenBinding = {
+            ...binding,
+            scriptsEnabled: artifact.playPresetScriptsEnabled,
+        };
+        const regex = declaration.regex
+            ? parsePlayPresetRegexAsset(frozenBinding.files[declaration.regex] ??
+                (() => {
+                    throw new Error("The frozen regex resource does not exist");
+                })(), declaration.regex)
+            : [];
+        const renderer = resolveRenderer(declaration, frozenBinding);
+        const mount = frozenBinding.definition.mounts.find(({ channel }) => channel === declaration.channel)?.mount;
+        return {
+            status: "ready",
+            preset,
+            source: "artifact",
+            authority: "non_authoritative_artifact",
+            lifecycle: "operation_frozen",
+            ...(mount === undefined ? {} : { mount }),
+            declaration: declarationView(declaration),
+            regex,
+            ...(renderer === undefined ? {} : { renderer }),
+            trustedLocalCode: artifact.playPresetScriptsEnabled,
+            fallback: "none",
+        };
+    }
+    catch {
+        return {
+            ...missingBundle(preset, "The frozen extension resource is invalid", "invalid_revision"),
+            status: "invalid_revision",
+        };
+    }
+}
+/**
+ * Project a current-preset player-view panel through the same frozen-resource
+ * bundle seam as follow-up artifacts. Its lifecycle is explicit: it follows the
+ * currently selected preset, while historical artifacts continue to use their
+ * own operation-frozen revision.
+ */
+export function projectPlayerViewPanelForFrontend(panel, binding, failure = "missing_revision") {
+    const preset = binding === null
+        ? { id: "unknown", revision: "unknown" }
+        : { id: binding.id, revision: binding.revision };
+    if (binding === null)
+        return {
+            ...missingBundle(preset, "The current play-preset revision is unavailable, and player-view panels cannot use another revision", failure),
+            source: "player_view",
+            lifecycle: "current_preset",
+        };
+    try {
+        const regex = panel.regex
+            ? parsePlayPresetRegexAsset(binding.files[panel.regex] ??
+                (() => {
+                    throw new Error("The frozen regex resource does not exist");
+                })(), panel.regex)
+            : [];
+        const renderer = resolvePlayerViewRenderer(panel, binding);
+        return {
+            status: "ready",
+            preset,
+            source: "player_view",
+            authority: "committed_player_view_projection",
+            lifecycle: "current_preset",
+            mount: panel.mount,
+            declaration: {
+                outputName: panel.id,
+                channel: panel.channel,
+                key: panel.key,
+                contentType: "application/json",
+                projection: "upsert",
+                save: "none",
+                invalidation: "never",
+                required: false,
+                maxEmits: 1,
+                rendererMode: panel.rendererMode,
+            },
+            regex,
+            ...(renderer === undefined ? {} : { renderer }),
+            trustedLocalCode: renderer?.trustedLocalCode ?? false,
+            fallback: "none",
+        };
+    }
+    catch (error) {
+        return {
+            ...missingBundle(preset, error instanceof Error
+                ? error.message
+                : "The frozen player-view panel resource is invalid", "invalid_revision"),
+            source: "player_view",
+            lifecycle: "current_preset",
+        };
+    }
+}
+function artifactMatchesDeclaration(artifact, declaration) {
+    return (artifact.output === declaration.name &&
+        artifact.channel === declaration.channel &&
+        (artifact.key ?? undefined) === (declaration.key ?? undefined) &&
+        artifact.contentType === declaration.contentType &&
+        artifact.projection === declaration.strategy &&
+        artifact.save === declaration.save &&
+        (artifact.renderer ?? undefined) === (declaration.renderer ?? undefined) &&
+        (artifact.rendererRevision ?? undefined) ===
+            (declaration.rendererRevision ?? undefined));
+}
+export function projectDebugArtifactForFrontend(artifact, binding, failure = "missing_revision") {
+    return projectArtifactForFrontend(artifact, binding, failure);
+}
+function declarationView(declaration) {
+    return {
+        outputName: declaration.name,
+        channel: declaration.channel,
+        ...(declaration.key === undefined ? {} : { key: declaration.key }),
+        contentType: declaration.contentType,
+        projection: declaration.strategy,
+        save: declaration.save,
+        invalidation: declaration.invalidation,
+        required: declaration.required,
+        maxEmits: declaration.maxEmits,
+        ...(declaration.payloadContract === undefined
+            ? {}
+            : { payloadContract: structuredClone(declaration.payloadContract) }),
+        rendererMode: declaration.rendererMode ?? "document",
+    };
+}
+function resolveRenderer(declaration, binding) {
+    const mode = declaration.rendererMode ?? "document";
+    const rendererSource = declaration.renderer
+        ? binding.files[declaration.renderer]
+        : undefined;
+    if (declaration.renderer !== undefined && rendererSource === undefined)
+        throw new Error("The frozen renderer resource does not exist");
+    const scriptSources = (declaration.scripts ?? []).map((path) => {
+        const source = binding.files[path];
+        if (source === undefined)
+            throw new Error("The frozen script resource does not exist");
+        return source;
+    });
+    const scripts = binding.scriptsEnabled ? scriptSources : [];
+    const assets = (declaration.assets ?? []).map((path) => {
+        const source = binding.files[path];
+        if (source === undefined)
+            throw new Error("The frozen asset resource does not exist");
+        // This is a frozen, author-visible logical asset id, not a machine path.
+        // Keeping the preset-relative declaration key stable lets app renderers
+        // refer to `window.__NARRAEON_ASSETS__[id]` across exchanges/revisions.
+        return { id: path, source };
+    });
+    if (rendererSource === undefined &&
+        scripts.length === 0 &&
+        assets.length === 0)
+        return undefined;
+    return {
+        mode,
+        ...(declaration.rendererRevision === undefined
+            ? {}
+            : { revision: declaration.rendererRevision }),
+        ...(rendererSource === undefined ? {} : { document: rendererSource }),
+        scripts,
+        assets,
+        trustedLocalCode: binding.scriptsEnabled,
+    };
+}
+function resolvePlayerViewRenderer(panel, binding) {
+    const rendererSource = panel.renderer
+        ? binding.files[panel.renderer]
+        : undefined;
+    if (panel.renderer !== undefined && rendererSource === undefined)
+        throw new Error("The frozen player-view renderer resource does not exist");
+    const scriptSources = (panel.scripts ?? []).map((path) => {
+        const source = binding.files[path];
+        if (source === undefined)
+            throw new Error("The frozen player-view script resource does not exist");
+        return source;
+    });
+    const scripts = binding.scriptsEnabled ? scriptSources : [];
+    const assets = (panel.assets ?? []).map((path) => {
+        const source = binding.files[path];
+        if (source === undefined)
+            throw new Error("The frozen player-view asset resource does not exist");
+        return { id: path, source };
+    });
+    if (rendererSource === undefined &&
+        scripts.length === 0 &&
+        assets.length === 0)
+        return undefined;
+    return {
+        mode: panel.rendererMode,
+        ...(panel.rendererRevision === undefined
+            ? {}
+            : { revision: panel.rendererRevision }),
+        ...(rendererSource === undefined ? {} : { document: rendererSource }),
+        scripts,
+        assets,
+        trustedLocalCode: binding.scriptsEnabled,
+    };
+}
+function missingBundle(preset, diagnostic, status = "missing_revision") {
+    return {
+        status,
+        preset,
+        regex: [],
+        trustedLocalCode: false,
+        fallback: "raw",
+        diagnostic,
+    };
+}

package/dist/node/runtime/extension/PlayerViewPanelProjector.js

@@ -0,0 +1,121 @@
+import { projectPlayerViewPanelForFrontend, } from "./FrontendExtensionBundle.js";
+/**
+ * Deep projection seam for author-declared panels backed by committed player
+ * views.  The projector only receives the already-safe view result; it never
+ * opens world files or guesses a selector.  The selected preset is explicit
+ * current-preset state, unlike operation-frozen artifact bundles.
+ */
+export function projectPlayerViewPanels(input) {
+    return input.binding.definition.playerViewPanels.map((panel) => projectPanel(panel, input));
+}
+function projectPanel(panel, input) {
+    const view = input.playerViews.views.find((candidate) => candidate.id === panel.source.view);
+    const diagnostics = input.playerViews.diagnostics
+        .filter((diagnostic) => diagnostic.viewId === undefined ||
+        diagnostic.viewId === panel.source.view)
+        .map((diagnostic) => ({ ...diagnostic }));
+    const items = selectItems(view, panel);
+    const addUnresolved = (itemId, message) => {
+        if (diagnostics.some((diagnostic) => diagnostic.code === "unresolved_selector" &&
+            diagnostic.viewId === panel.source.view &&
+            diagnostic.itemId === itemId))
+            return;
+        diagnostics.push({
+            code: "unresolved_selector",
+            viewId: panel.source.view,
+            ...(itemId === undefined ? {} : { itemId }),
+            message,
+        });
+    };
+    if (view === undefined)
+        addUnresolved(undefined, `The exact player view cannot currently be resolved: ${panel.source.view}`);
+    const selectedItemIds = new Set(items.map(({ id }) => id));
+    for (const itemId of panel.source.itemIds ?? [])
+        if (!selectedItemIds.has(itemId))
+            addUnresolved(itemId, `The exact selector cannot currently be resolved: ${panel.source.view}/${itemId}`);
+    for (const group of panel.config.groups)
+        for (const itemId of group.itemIds)
+            if (!selectedItemIds.has(itemId))
+                addUnresolved(itemId, `An item referenced by the player-view group cannot currently be resolved: ${panel.source.view}/${itemId}`);
+    const frontend = projectPlayerViewPanelForFrontend(panel, input.binding);
+    const payload = {
+        panelId: panel.id,
+        title: panel.config.title ?? view?.title ?? panel.source.view,
+        viewId: panel.source.view,
+        items: items.map(({ id, label, value }) => ({
+            id,
+            label,
+            value: toArtifactPayload(value),
+        })),
+        config: {
+            layout: panel.config.layout,
+            theme: panel.config.theme,
+            empty: panel.config.empty,
+            emptyMessage: panel.config.emptyMessage,
+            groups: panel.config.groups.map((group) => ({
+                id: group.id,
+                label: group.label,
+                itemIds: [...group.itemIds],
+            })),
+        },
+        diagnostics: diagnostics.map((diagnostic) => ({ ...diagnostic })),
+        provenance: {
+            kind: "committed_player_view_projection",
+            lifecycle: "current_preset",
+            head: input.head,
+        },
+    };
+    return {
+        panelId: panel.id,
+        worldId: input.worldId,
+        preset: { id: input.binding.id, revision: input.binding.revision },
+        lifecycle: "current_preset",
+        source: {
+            kind: "player_view",
+            viewId: panel.source.view,
+            ...(panel.source.itemIds === undefined
+                ? {}
+                : { itemIds: [...panel.source.itemIds] }),
+        },
+        authority: "committed_player_view_projection",
+        head: input.head,
+        channel: panel.channel,
+        key: panel.key,
+        contentType: "application/json",
+        payload,
+        projection: "upsert",
+        diagnostics,
+        frontend,
+    };
+}
+function selectItems(view, panel) {
+    if (view === undefined)
+        return [];
+    if (panel.source.itemIds === undefined)
+        return view.items;
+    const byId = new Map(view.items.map((item) => [item.id, item]));
+    return panel.source.itemIds.flatMap((id) => {
+        const item = byId.get(id);
+        return item === undefined ? [] : [item];
+    });
+}
+function toArtifactPayload(value, depth = 0) {
+    if (depth > 16)
+        return "[UI depth limit reached]";
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean")
+        return value;
+    if (Array.isArray(value))
+        return value.map((entry) => toArtifactPayload(entry, depth + 1));
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+            key,
+            toArtifactPayload(child, depth + 1),
+        ]));
+    return "[Unable to display]";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/node/runtime/model/AiFailureLog.js

@@ -0,0 +1,332 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, chmod, mkdir, readFile, rename, writeFile, } from "node:fs/promises";
+import { basename, join } from "node:path";
+export const aiFailureLogFormat = "narraeon.ai-failure-log/v1";
+/**
+ * Append-only, failure-triggered Provider diagnostics.
+ *
+ * No successful request creates a file. Once an operation fails, the triggering
+ * exchange and every later exchange are retained until the caller marks the
+ * operation repaired. State files make that recording window survive a Runtime
+ * restart. API credentials and request headers never enter the capture.
+ */
+export class FileNativeAiFailureLog {
+    #root;
+    #stateRoot;
+    constructor(root) {
+        this.#root = root;
+        this.#stateRoot = join(root, ".state");
+    }
+    async recordFailure(input) {
+        if (input.failures.length === 0)
+            return;
+        await this.#bestEffort(async () => {
+            const traceKey = failureTraceKey(input.exchange);
+            let state = await this.#readState(traceKey);
+            if (state === null || state.status === "resolved")
+                state = await this.#startIncident(traceKey, input.exchange);
+            else
+                state = await this.#appendExchange(state, input.exchange);
+            await this.#appendLine(state, {
+                type: "failure",
+                recordedAt: new Date().toISOString(),
+                failures: cloneJson(input.failures),
+            });
+            await this.#writeState({
+                ...state,
+                status: "active",
+                updatedAt: new Date().toISOString(),
+            });
+        });
+    }
+    async recordExchangeIfActive(exchange) {
+        await this.#bestEffort(async () => {
+            const state = await this.#readState(failureTraceKey(exchange));
+            if (state?.status !== "active")
+                return;
+            await this.#appendExchange(state, exchange);
+        });
+    }
+    async resolve(input) {
+        await this.#bestEffort(async () => {
+            const traceKey = failureTraceKey(input.exchange);
+            const current = await this.#readState(traceKey);
+            if (current?.status !== "active")
+                return;
+            const state = await this.#appendExchange(current, input.exchange);
+            const recordedAt = new Date().toISOString();
+            await this.#appendLine(state, {
+                type: "resolved",
+                recordedAt,
+                message: input.message,
+                ...(input.details === undefined
+                    ? {}
+                    : { details: cloneJson(input.details) }),
+            });
+            await this.#writeState({
+                ...state,
+                status: "resolved",
+                updatedAt: recordedAt,
+            });
+        });
+    }
+    async #startIncident(traceKey, exchange) {
+        await this.#prepareRoots();
+        const incidentId = randomUUID();
+        const startedAt = new Date().toISOString();
+        const logFile = `${fileTimestamp(startedAt)}-${incidentId}.jsonl`;
+        const state = {
+            format: aiFailureLogFormat,
+            traceKey,
+            incidentId,
+            logFile,
+            status: "active",
+            lastCaptureId: exchange.captureId,
+            updatedAt: startedAt,
+        };
+        const initial = [
+            {
+                type: "incident",
+                format: aiFailureLogFormat,
+                incidentId,
+                traceKey,
+                startedAt,
+            },
+            {
+                type: "exchange",
+                recordedAt: startedAt,
+                exchange: cloneJson(exchange),
+            },
+        ]
+            .map((value) => JSON.stringify(value))
+            .join("\n");
+        await writeFile(join(this.#root, logFile), `${initial}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await chmod(join(this.#root, logFile), 0o600);
+        await this.#writeState(state);
+        return state;
+    }
+    async #appendExchange(state, exchange) {
+        if (state.lastCaptureId === exchange.captureId)
+            return state;
+        const recordedAt = new Date().toISOString();
+        await this.#appendLine(state, {
+            type: "exchange",
+            recordedAt,
+            exchange: cloneJson(exchange),
+        });
+        const next = {
+            ...state,
+            lastCaptureId: exchange.captureId,
+            updatedAt: recordedAt,
+        };
+        await this.#writeState(next);
+        return next;
+    }
+    async #appendLine(state, value) {
+        const path = join(this.#root, basename(state.logFile));
+        await appendFile(path, `${JSON.stringify(value)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await chmod(path, 0o600);
+    }
+    async #readState(traceKey) {
+        const path = this.#statePath(traceKey);
+        let source;
+        try {
+            source = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (hasErrorCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+        const value = JSON.parse(source);
+        if (!isIncidentState(value, traceKey))
+            return null;
+        return value;
+    }
+    async #writeState(state) {
+        await this.#prepareRoots();
+        const path = this.#statePath(state.traceKey);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        await writeFile(temporary, `${JSON.stringify(state)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(temporary, path);
+        await chmod(path, 0o600);
+    }
+    async #prepareRoots() {
+        await mkdir(this.#root, { recursive: true, mode: 0o700 });
+        await mkdir(this.#stateRoot, { recursive: true, mode: 0o700 });
+        await Promise.all([
+            chmod(this.#root, 0o700),
+            chmod(this.#stateRoot, 0o700),
+        ]);
+    }
+    #statePath(traceKey) {
+        const name = createHash("sha256").update(traceKey).digest("hex");
+        return join(this.#stateRoot, `${name}.json`);
+    }
+    async #bestEffort(operation) {
+        try {
+            await operation();
+        }
+        catch {
+            // Diagnostics must never change Provider or Runtime authority semantics.
+        }
+    }
+}
+/** Mutable capture used only for the lifetime of one Provider request. */
+export class AiExchangeCapture {
+    #base;
+    #responseChunks = [];
+    #response;
+    #reasoning = "";
+    constructor(input) {
+        this.#base = {
+            captureId: randomUUID(),
+            provider: input.provider,
+            endpoint: safeEndpoint(input.endpoint),
+            context: cloneJson(input.context),
+            request: {
+                method: "POST",
+                contentType: "application/json",
+                body: input.requestBody,
+            },
+        };
+    }
+    observeReasoning(text) {
+        this.#reasoning += text;
+    }
+    setReasoning(text) {
+        if (text !== undefined)
+            this.#reasoning = text;
+    }
+    captureResponse(response) {
+        this.#response = {
+            status: response.status,
+            statusText: response.statusText,
+            contentType: response.headers.get("content-type"),
+            bodyComplete: response.body === null,
+        };
+        if (response.body === null)
+            return response;
+        const reader = response.body.getReader();
+        const captured = new ReadableStream({
+            pull: async (controller) => {
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        if (this.#response !== undefined)
+                            this.#response.bodyComplete = true;
+                        controller.close();
+                        return;
+                    }
+                    this.#responseChunks.push(Buffer.from(value));
+                    controller.enqueue(value);
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+            cancel: async (reason) => {
+                try {
+                    await reader.cancel(reason);
+                }
+                catch {
+                    // The caller's Provider classification remains authoritative.
+                }
+            },
+        });
+        return new Response(captured, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    }
+    snapshot() {
+        return {
+            ...cloneJson(this.#base),
+            ...(this.#response === undefined
+                ? {}
+                : {
+                    response: {
+                        ...cloneJson(this.#response),
+                        body: Buffer.concat(this.#responseChunks).toString("utf8"),
+                    },
+                }),
+            ...(this.#reasoning === "" ? {} : { reasoning: this.#reasoning }),
+        };
+    }
+}
+export function errorDescription(error) {
+    if (!(error instanceof Error))
+        return { name: "UnknownError", message: String(error) };
+    return {
+        name: error.name,
+        message: error.message,
+        ...(error.stack === undefined ? {} : { stack: error.stack }),
+        ...(error.cause === undefined ? {} : { cause: describeCause(error.cause) }),
+    };
+}
+function describeCause(cause) {
+    if (cause instanceof Error)
+        return `${cause.name}: ${cause.message}`;
+    if (typeof cause === "string")
+        return cause;
+    if (typeof cause === "number" ||
+        typeof cause === "bigint" ||
+        typeof cause === "boolean" ||
+        typeof cause === "symbol")
+        return String(cause);
+    if (cause === null)
+        return "null";
+    try {
+        return JSON.stringify(cause) ?? "undefined";
+    }
+    catch {
+        return "[unserializable cause]";
+    }
+}
+function failureTraceKey(exchange) {
+    const { scope, operationId, requestId } = exchange.context;
+    if (scope === "play_followup")
+        return [scope, operationId ?? "", requestId ?? exchange.endpoint].join("\0");
+    return [scope, operationId ?? requestId ?? exchange.endpoint].join("\0");
+}
+function safeEndpoint(url) {
+    return `${url.protocol}//${url.host}${url.pathname}`;
+}
+function fileTimestamp(value) {
+    return value.replaceAll(":", "-");
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isIncidentState(value, traceKey) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.format === aiFailureLogFormat &&
+        value.traceKey === traceKey &&
+        typeof value.incidentId === "string" &&
+        typeof value.logFile === "string" &&
+        (value.status === "active" ||
+            value.status === "resolved") &&
+        (value.lastCaptureId === null ||
+            typeof value.lastCaptureId === "string") &&
+        typeof value.updatedAt === "string");
+}
+function hasErrorCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}