@valbuild/shared 0.150.20 → 0.152.0

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -512,6 +512,75 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    /**
+     * What each module IS, right now: its version (`schema`, `base`, `chain`),
+     * and the project version that is relative to. What `/stat` answers, per
+     * module; see `docs/plans/one-content-model.md`, "The Studio loads
+     * everything from one place".
+     *
+     * It has its own ETag, so a client that sends it back (`If-None-Match`)
+     * gets a 304 and no body while nothing has moved. Computed from versions
+     * kept as content changes: answering it hashes nothing.
+     *
+     * "Since `seq` N" (`?since=N`, with the ETag of the manifest the client
+     * holds, which was answered at `seq` N, as `If-None-Match`): the modules
+     * whose version moved since that manifest, and no others, with `since: N`
+     * on the answer to say it is a delta. The ETag is in the body too (`tag`),
+     * for a client that reads answers through `ValClient`, which hands over
+     * the body and not the headers. Answered whole -- no `since` -- when the server no
+     * longer holds the manifest that ETag names (another process, another
+     * build, too long ago), and by a server of the release before, which
+     * ignores the parameter. Optional both ways.
+     */
+    "/manifest": {
+        GET: {
+            req: {
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+                headers: {
+                    "if-none-match": z.ZodOptional<z.ZodString>;
+                };
+                query: {
+                    since: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    project: z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>;
+                    modules: z.ZodRecord<z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>, z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>>;
+                    tag: z.ZodOptional<z.ZodString>;
+                    since: z.ZodOptional<z.ZodNumber>;
+                    superseded: z.ZodOptional<z.ZodBoolean>;
+                    registry: z.ZodOptional<z.ZodObject<{
+                        entry: z.ZodString;
+                        core: z.ZodString;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<304>;
+                json: z.ZodOptional<z.ZodNull>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/stat": {
         POST: {
             req: {
@@ -580,6 +649,10 @@ export declare const Api: {
                         branch: z.ZodString;
                     }, z.core.$strip>>;
                     historyBranch: z.ZodOptional<z.ZodString>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>, z.ZodObject<{
                     type: z.ZodLiteral<"use-websocket">;
                     url: z.ZodString;
@@ -634,6 +707,10 @@ export declare const Api: {
                         branch: z.ZodString;
                     }, z.core.$strip>>;
                     historyBranch: z.ZodOptional<z.ZodString>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>]>;
             }, z.core.$strip>]>;
         };
@@ -675,11 +752,17 @@ export declare const Api: {
                 cookies: {
                     val_session: z.ZodOptional<z.ZodString>;
                 };
+                headers: {
+                    "if-none-match": z.ZodOptional<z.ZodString>;
+                };
             };
-            res: z.ZodObject<{
+            res: z.ZodUnion<readonly [z.ZodObject<{
                 status: z.ZodNumber;
                 json: z.ZodUnknown;
-            }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<304>;
+                json: z.ZodOptional<z.ZodNull>;
+            }, z.core.$strip>]>;
         };
         POST: {
             req: {
@@ -1182,6 +1265,22 @@ export declare const Api: {
                     }, z.core.$strip>]>;
                     headVersion: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<502>;
+                json: z.ZodObject<{
+                    type: z.ZodLiteral<"service-error">;
+                    message: z.ZodString;
+                    details: z.ZodOptional<z.ZodString>;
+                    newPatchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                    parentRef: z.ZodUnion<readonly [z.ZodObject<{
+                        type: z.ZodLiteral<"head">;
+                        headBaseSha: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        type: z.ZodLiteral<"patch">;
+                        patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
+                    }, z.core.$strip>]>;
+                    headVersion: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
                 json: z.ZodObject<{
@@ -1232,6 +1331,7 @@ export declare const Api: {
                     error: z.ZodObject<{
                         message: z.ZodString;
                     }, z.core.$strip>;
+                    details: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
@@ -1284,6 +1384,10 @@ export declare const Api: {
                     errors: z.ZodOptional<z.ZodRecord<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>, z.ZodObject<{
                         message: z.ZodString;
                     }, z.core.$strip>>>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>;
             }, z.core.$strip>]>;
         };
@@ -1326,6 +1430,15 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    /**
+     * @deprecated The whole tree. Nothing of this release asks it: the Studio
+     * reads modules by version (`GET /manifest`, `GET /modules/~`), the draft
+     * readers and MCP read the head in-process. Kept, with `exclude_patches`
+     * (`BaseAlignment`'s fetch) and the ignored `validate_sources` and
+     * `validate_binary_files`, for a Studio of the release before; goes in the
+     * release after the one that ships this (see "Release-delayed deletions"
+     * in `docs/plans/one-content-model.md`).
+     */
     "/sources/~": {
         PUT: {
             req: {
@@ -1397,8 +1510,153 @@ export declare const Api: {
                             fatal: z.ZodOptional<z.ZodBoolean>;
                             fixes: z.ZodOptional<z.ZodArray<z.ZodType<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "video:add-metadata" | "video:upload-remote" | "video:download-remote" | "videos:add-metadata" | "videos:check-remote" | "videos:upload-remote" | "keyof:check-keys" | "image:check-gallery" | "file:check-gallery" | "video:check-gallery" | "router:check-route" | "locale:check-locale" | "router:check-locale-param" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "videos:check-unique-folder" | "videos:check-all-files" | "jsonValues:extract-entry" | "record:fill-keys" | "external:upload" | "view:check-module" | "remote:rewrite-host", unknown, z.core.$ZodTypeInternals<"image:add-metadata" | "image:check-metadata" | "image:upload-remote" | "image:download-remote" | "image:check-remote" | "images:check-remote" | "images:upload-remote" | "file:add-metadata" | "file:check-metadata" | "file:upload-remote" | "file:download-remote" | "file:check-remote" | "files:check-remote" | "files:upload-remote" | "video:add-metadata" | "video:upload-remote" | "video:download-remote" | "videos:add-metadata" | "videos:check-remote" | "videos:upload-remote" | "keyof:check-keys" | "image:check-gallery" | "file:check-gallery" | "video:check-gallery" | "router:check-route" | "locale:check-locale" | "router:check-locale-param" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "videos:check-unique-folder" | "videos:check-all-files" | "jsonValues:extract-entry" | "record:fill-keys" | "external:upload" | "view:check-module" | "remote:rewrite-host", unknown>>>>;
                         }, z.core.$strip>>>>;
+                        version: z.ZodOptional<z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                        }, z.core.$strip>>;
+                    }, z.core.$strip>>;
+                    project: z.ZodOptional<z.ZodObject<{
+                        build: z.ZodString;
+                        seq: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /**
+     * One module by version: phase 6 of `docs/plans/one-content-model.md`
+     * ("The Studio loads everything from one place"). `GET /modules/~<path>`,
+     * with `v` the version wanted as its `moduleKey` (the newest when absent;
+     * a base is a version with the empty chain) and `have` the version the
+     * caller holds: when the caller's chain is a start of the answer's under
+     * the same schema and base, the answer is the patches from it (`delta`),
+     * otherwise the whole module. An answer for an asked `v` is immutable.
+     */
+    "/modules/~": {
+        GET: {
+            req: {
+                path: z.ZodString;
+                query: {
+                    v: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                    have: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                    current: z.ZodOptional<z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
                     }, z.core.$strip>>;
                 }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                headers: z.ZodOptional<z.ZodObject<{
+                    "Cache-Control": z.ZodString;
+                }, z.core.$strip>>;
+                json: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"module">;
+                    version: z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>;
+                    source: z.ZodAny;
+                    entries: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        content: z.ZodAny;
+                        version: z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                            key: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        deleted: z.ZodLiteral<true>;
+                        version: z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                            key: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        error: z.ZodString;
+                        patchId: z.ZodOptional<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                        version: z.ZodObject<{
+                            schema: z.ZodString;
+                            base: z.ZodString;
+                            chain: z.ZodString;
+                            key: z.ZodString;
+                        }, z.core.$strip>;
+                    }, z.core.$strip>]>>;
+                    patches: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>>;
+                    failed: z.ZodOptional<z.ZodObject<{
+                        patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
+                        message: z.ZodString;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"delta">;
+                    from: z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>;
+                    to: z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>;
+                    patches: z.ZodArray<z.ZodObject<{
+                        patchId: z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>;
+                        patch: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                            op: z.ZodLiteral<"add">;
+                            path: z.ZodArray<z.ZodString>;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"remove">;
+                            path: z.ZodTuple<[z.ZodString], z.ZodString>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"replace">;
+                            path: z.ZodArray<z.ZodString>;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"move">;
+                            from: z.ZodTuple<[z.ZodString], z.ZodString>;
+                            path: z.ZodArray<z.ZodString>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"copy">;
+                            from: z.ZodArray<z.ZodString>;
+                            path: z.ZodArray<z.ZodString>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"test">;
+                            path: z.ZodArray<z.ZodString>;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                        }, z.core.$strict>, z.ZodObject<{
+                            op: z.ZodLiteral<"file">;
+                            path: z.ZodArray<z.ZodString>;
+                            filePath: z.ZodString;
+                            value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+                            remote: z.ZodBoolean;
+                            nestedFilePath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                            metadata: z.ZodOptional<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
+                        }, z.core.$strict>], "op">>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>]>;
             }, z.core.$strip>]>;
         };
     };
@@ -2259,6 +2517,11 @@ export declare const Api: {
                     path: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
                     key: z.ZodString;
                     content: z.ZodAny;
+                    version: z.ZodOptional<z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<200>;
@@ -2276,6 +2539,11 @@ export declare const Api: {
                     offset: z.ZodOptional<z.ZodNumber>;
                     limit: z.ZodOptional<z.ZodNumber>;
                     total: z.ZodOptional<z.ZodNumber>;
+                    version: z.ZodOptional<z.ZodObject<{
+                        schema: z.ZodString;
+                        base: z.ZodString;
+                        chain: z.ZodString;
+                    }, z.core.$strip>>;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
                 status: z.ZodLiteral<400>;

package/dist/declarations/src/internal/aiTools/toolNames.d.ts

@@ -1,2 +1,2 @@
-export declare const toolNames: readonly ["get_all_schema", "get_source", "search_content", "validate_content", "create_patch", "add_session_image_to_gallery", "remove_image_gallery_entry", "navigate_to", "get_current_context", "get_patches", "get_source_path_from_route", "set_session_name", "show_compare_view", "ask_user_question", "duplicate_source", "empty_at_path", "count_entries", "get_record_keys", "list_sketchpads", "create_sketchpad", "read_sketchpad", "write_sketchpad"];
+export declare const toolNames: readonly ["get_all_schema", "get_source", "search_content", "validate_content", "create_patch", "add_session_image_to_gallery", "remove_image_gallery_entry", "convert_session_image", "navigate_to", "get_current_context", "get_patches", "get_source_path_from_route", "set_session_name", "show_compare_view", "ask_user_question", "duplicate_source", "empty_at_path", "count_entries", "get_record_keys", "list_sketchpads", "create_sketchpad", "read_sketchpad", "write_sketchpad", "highlight_sketchpad_blocks", "clear_sketchpad_highlights"];
 export type ToolName = (typeof toolNames)[number];

package/dist/declarations/src/internal/content/applyChain.d.ts

@@ -0,0 +1,124 @@
+import { type PatchId } from "@valbuild/core";
+import type { SerializedSchema } from "@valbuild/core";
+import { type Operation, type Patch, type ReadonlyJSONValue } from "@valbuild/core/patch";
+/** What one `.jsonValues()` entry is at a point in a module's chain. */
+export type EntryState = 
+/** Its content, known. */
+{
+    kind: "content";
+    content: ReadonlyJSONValue;
+}
+/**
+ * The content of the BASE entry `from` (its own key, or the one it was
+ * moved or copied from), with `ops` on top: an entry nobody has loaded,
+ * whose edits are held until somebody does ({@link resolveEntry}).
+ */
+ | {
+    kind: "waiting";
+    from: string;
+    ops: HeldOps | null;
+}
+/** Removed, or moved away. */
+ | {
+    kind: "deleted";
+}
+/** An op on it could not be applied. Sticky, as a module's failure is. */
+ | {
+    kind: "error";
+    patchId: PatchId;
+    message: string;
+};
+/**
+ * The ops held for an entry, newest first: a list that is extended without
+ * copying, so a chain of N edits to an entry nobody loaded costs N, not N².
+ */
+export type HeldOps = {
+    readonly op: Operation;
+    readonly patchId: PatchId;
+    readonly before: HeldOps | null;
+};
+/**
+ * A module's content: its source, and what its `.jsonValues()` entries are.
+ *
+ * `entries` holds only the entries the chain has touched. An entry it has
+ * not is the base's: `waiting` on its own key with nothing held, as long as
+ * the source has its marker ({@link entryState}). So a module with no
+ * entries, or a chain that never touches one, costs nothing here.
+ */
+export type ModuleContent = {
+    readonly source: ReadonlyJSONValue;
+    readonly entries: ReadonlyMap<string, EntryState>;
+};
+/** One patch of a module's chain. */
+export type PatchRecord = {
+    readonly patchId: PatchId;
+    readonly patch: Patch;
+};
+export type PatchRecordResult = {
+    status: "applied";
+    module: ModuleContent;
+} | {
+    status: "failed";
+    patchId: PatchId;
+    message: string;
+};
+/** A module's content with nothing applied yet: its base. */
+export declare function baseModuleContent(source: ReadonlyJSONValue): ModuleContent;
+/**
+ * The work the engine has done in this process: patches applied
+ * (`engine:apply-patch`) and bytes copied (`engine:clone-bytes`, see
+ * {@link SLOT_BYTES}). A test takes it before and after; never reset, so two
+ * readers of it cannot disturb each other.
+ */
+export declare function engineWork(): {
+    applyPatch: number;
+    cloneBytes: number;
+};
+/**
+ * Applies one patch to a module's content. Nothing is mutated: the module
+ * passed in is still what it was, and the one returned shares every subtree
+ * the patch did not touch.
+ *
+ * `failed` means the patch does not apply, and then none of it does: half a
+ * patch is half an edit. The caller stops the module's chain there.
+ *
+ * `schema` is the module's serialized schema: it says which ops reach into a
+ * `.jsonValues()` entry. Without one, every op is an op on the source.
+ */
+export declare function applyPatchRecord(module: ModuleContent, record: PatchRecord, schema: SerializedSchema | undefined): PatchRecordResult;
+/**
+ * A module's chain: every patch in order, stopping at the first that does
+ * not apply. `applied` is how many did, so the chain the content is AT is
+ * the first `applied` ids -- what its version names.
+ */
+export declare function applyChain(module: ModuleContent, records: readonly PatchRecord[], schema: SerializedSchema | undefined): {
+    module: ModuleContent;
+    applied: number;
+    failed: {
+        patchId: PatchId;
+        message: string;
+    } | null;
+};
+/**
+ * What an entry is in this module: what the chain made it, or -- for one the
+ * chain never touched -- the base's, if the source has its marker.
+ */
+export declare function entryState(module: ModuleContent, key: string): EntryState | undefined;
+/** An entry's content, read. */
+export type EntryContent = {
+    kind: "content";
+    content: ReadonlyJSONValue;
+} | {
+    kind: "missing";
+} | {
+    kind: "error";
+    message: string;
+    patchId?: PatchId;
+};
+/**
+ * An entry's content: what {@link entryState} says, with what it was waiting
+ * for applied. `baseContentOf` is the BASE content of an entry by key (its
+ * `*.val.json`, or what a save left there), `undefined` for one the base does
+ * not have.
+ */
+export declare function resolveEntry(key: string, state: EntryState | undefined, baseContentOf: (key: string) => ReadonlyJSONValue | undefined): EntryContent;

package/dist/declarations/src/internal/content/buildRegistry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where a build's `val.modules` registry can be imported from: phase 9 of
+ * `docs/plans/one-content-model.md`, "Reloading the schema while the Studio
+ * runs".
+ *
+ * A build made by `@valbuild/tanstack-build` (every build the platform
+ * serves) emits its `val.modules` as an ES module of its own beside its
+ * client chunks, named after the build: `/_app/val-modules-<build>.js`,
+ * whose default export is the registry. The server running that build knows
+ * its name (`VAL_BUILD`, Val's `publishBuild`) and names the entry on
+ * `GET /manifest` (`registry`), so a Studio opened on an older build imports
+ * the new one's code and reloads it in place (`HostStore.reloadCode`)
+ * instead of being told to reload the page.
+ *
+ * The convention is the builder's and this file's together: the builder
+ * writes the file (`valModulesEntryFile` in `@valbuild/tanstack-build`, which
+ * does not depend on this package), and each side pins the same literal,
+ * `val-modules-<build>.js` (`buildRegistry.test.ts` here, `valModules.test.ts`
+ * there).
+ */
+/** The file a build's registry is emitted as, among its client chunks. */
+export declare function valModulesEntryFile(build: string): string;
+/** Where a build served by the platform serves its registry. */
+export declare function valModulesEntryPath(build: string): string;
+/**
+ * What `GET /manifest` says about the code of the build that answered:
+ * where its registry is, and which Val it runs. A Studio running another
+ * Val cannot take the build's code in (its own stores would run against a
+ * new core), so it reloads itself instead (`other-val-version`).
+ */
+export type BuildRegistry = {
+    /** The registry's entry, from the site's origin. */
+    entry: string;
+    /** `@valbuild/core`'s version, as the build runs it. */
+    core: string;
+};

package/dist/declarations/src/internal/content/jsonValuesOps.d.ts

@@ -0,0 +1,110 @@
+import { type SerializedSchema } from "@valbuild/core";
+import { result } from "@valbuild/core/fp";
+import { PatchError, type JSONValue, type Operation } from "@valbuild/core/patch";
+/**
+ * Classification of a single patch op against a module's serialized schema,
+ * used by the commit flow to route ops for `.jsonValues()` records:
+ *
+ * - `normal`: the op does not descend into a `.jsonValues()` entry; apply it to
+ *   the `.val.ts` as usual.
+ * - `entry`: the op targets a `.jsonValues()` entry. `recordPath` is the path to
+ *   the record within the module source (empty for a root record/router),
+ *   `entryKey` is the entry key, and `subPath` is the remaining path inside the
+ *   entry (empty when the op targets the entry value itself, e.g. add/remove of
+ *   the whole entry).
+ */
+export type JsonValuesOpClass = {
+    kind: "normal";
+} | {
+    kind: "entry";
+    recordPath: string[];
+    entryKey: string;
+    subPath: string[];
+};
+/**
+ * Walks the serialized schema following the op path. When a `.jsonValues()`
+ * record is encountered, the next path segment is the entry key and everything
+ * after it lives inside the entry's `*.val.json` (so it does not touch the
+ * `.val.ts`). Returns `{ kind: "normal" }` when the op never enters a
+ * `.jsonValues()` record.
+ */
+export declare function classifyJsonValuesOp(schema: SerializedSchema, opPath: string[]): JsonValuesOpClass;
+/**
+ * Is this op a write of the WHOLE record at the root of a `.jsonValues()`
+ * module?
+ *
+ * The one op {@link classifyJsonValuesOp} cannot classify: it finds the entry
+ * key by walking the op path, and the root path has no segments to walk, so a
+ * root write reads as `normal` and gets applied to the `.val.ts` - writing
+ * markers over the `c.json(() => import(...))` calls that make the entries load
+ * at all. {@link expandJsonValuesRootOp} turns it into ops that DO name a key,
+ * which everything downstream already handles.
+ *
+ * `add` counts as well as `replace`: at the root both mean "the document is now
+ * this" (see `JSONOps`), so both have to be expanded or the unexpanded one is
+ * the same bug again.
+ *
+ * The value has to BE a record, and that is part of the question rather than a
+ * check inside the expansion: a `.jsonValues()` record can be nullable, and
+ * `null` at the root means the module no longer has a record at all - there are
+ * no entries to write, and it is an ordinary `.val.ts` write, exactly as it was
+ * before any of this existed. Same for any other non-record value: not a
+ * whole-record write, so not this conversion's to route.
+ */
+export declare function isJsonValuesRootOp(schema: SerializedSchema, op: Operation): boolean;
+/**
+ * One entry as it stands right now, for {@link expandJsonValuesRootOp} to
+ * expand against.
+ *
+ * The key set decides add-vs-replace-vs-remove. The content, where the caller
+ * has it, decides whether an op is emitted at all: an entry whose content is
+ * already what the root write says is left alone rather than rewritten, so
+ * putting a module back does not touch every `*.val.json` it did not change.
+ * `undefined` means "this entry exists, content unknown" - which is what the
+ * Studio's draft source has, because the source holds markers - and yields a
+ * `replace`, the safe answer.
+ */
+export type CurrentJsonEntries = ReadonlyMap<string, JSONValue | undefined>;
+/**
+ * Fans a whole-record write at a `.jsonValues()` module's root out into ops
+ * that each name an entry key.
+ *
+ * This is THE conversion, and it has exactly one implementation on purpose: the
+ * commit flow (`ValOps.prepare`) and the engine that builds draft content
+ * (`applyPatchRecord`) both expand through here, so a draft
+ * cannot show something other than what publishing writes. A second
+ * implementation of the same rule would differ silently, which is the whole
+ * failure mode this exists to prevent.
+ *
+ * The value must be the entries' CONTENT. A module's Source is markers, not
+ * content, so a Source handed over here is refused rather than written: that is
+ * the shape of the original bug (a revert replaying the archived Source), and
+ * it is not recoverable afterwards - the markers replace the entries' content
+ * on disk.
+ */
+export declare function expandJsonValuesRootOp(op: Operation, currentEntries: CurrentJsonEntries): result.Result<Operation[], PatchError>;
+/**
+ * What a whole-record write says about ONE entry: the same rule
+ * {@link expandJsonValuesRootOp} applies to all of them.
+ *
+ * For a reader that is about one entry. Expanding the whole record to find the
+ * one op that names its key costs an op per entry per entry read - the record
+ * squared, on exactly the large records this feature is for. The rule itself is
+ * `writeForEntry`, shared with the expansion above, so the two cannot come to
+ * disagree; only the loop around it differs.
+ *
+ * `null` means the write says nothing about this entry: it holds that content
+ * already, or the record does not name it and it does not exist.
+ */
+export declare function expandJsonValuesRootOpForKey(op: Operation, entryKey: string, currentEntries: CurrentJsonEntries): result.Result<Operation | null, PatchError>;
+/**
+ * Rebases a patch op that targets a `.jsonValues()` entry's content so its paths
+ * are relative to the entry's `*.val.json` root (drops the record + entry-key
+ * prefix). Used to replay the op against the backing JSON file.
+ */
+export declare function rebaseContentOp(op: Operation, prefixLen: number): result.Result<Operation, PatchError>;
+/**
+ * The entry a path names when it names a WHOLE entry of the root
+ * `.jsonValues()` record, and `undefined` for anything else.
+ */
+export declare function wholeEntryKey(serializedSchema: SerializedSchema | undefined, path: string[]): string | undefined;