@valbuild/shared 0.121.0 → 0.122.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # @valbuild/shared
 
+## 0.122.0
+
+### Minor Changes
+
+- [#563](https://github.com/valbuild/val/pull/563) [`be32261`](https://github.com/valbuild/val/commit/be32261af19db8018bc37b180d903416018c0b79) Thanks [@freekh](https://github.com/freekh)! - See how a module looked at any past commit, and restore from it by pointing at it
+
+  Val could publish edits but never look back. Now every commit is a durable
+  record you can open, and any part of it can be put back.
+
+  **Open a commit and the Studio splits in two.** The left half is the Studio
+  itself — same navigation, same fields, same everything, because it _is_ the
+  editor rather than a copy of it. The right half shows the project as that commit
+  left it. On a phone the two become one pane and a toggle.
+
+  **Restoring is directed: you point at the old value, then at where it goes.**
+  Val does not try to work out which of today's fields corresponds to which of the
+  commit's. It cannot be sure — array items splice, schemas move — and a restore
+  that guesses wrong writes into the wrong place and looks like it worked. Two
+  picks leave nothing to guess. You can restore across paths, so last month's
+  headline can become today's tagline.
+
+  Before you click, every field on the "now" side says whether it can hold the
+  value you picked, and a field that cannot explains why when you click it rather
+  than doing nothing. A changed union is not itself a blocker: what matters is
+  whether the value's own shape is still allowed, so a union that gained a case
+  restores fine and one that lost the case you are restoring does not.
+
+  Rich text can be restored but is marked "probably fits" rather than confirmed —
+  comparing every mark and block against the options a schema allows is not done
+  yet, and saying so is better than a confident answer we cannot back. It is
+  checked properly the moment you commit to it: before anything is staged, the old
+  value is checked against the field it is going into, and a value that cannot be
+  that field is refused with the reason. A value that is the right shape but
+  breaks a rule about its content — a name too short for its `minLength` — is
+  staged and then held at publish, the same as if you had typed it, because a
+  restore should not be stricter than typing.
+
+  **A whole module can be put back on its own**, from a commit that changed
+  several, without reverting the rest of the commit.
+
+  **Restores are staged, not applied.** They land in pending changes, are reviewed
+  beside every other edit, and go out with the next publish. There is also "put
+  everything back", for when a whole publish was the mistake.
+
+  To make this possible, publishing now records each changed module's data and the
+  schema it was written against. Not the `.val.ts` — git already keeps that, but
+  it is code, and turning code back into data means parsing it, which is
+  best-effort and stops working as TypeScript, your runtime and Val move on. The
+  schema is kept because a value on its own cannot be drawn: showing a module as it
+  was at a commit whose schema has since changed needs _that commit's_ schema, and
+  nothing in your current checkout has it.
+
+  Things it will not pretend about: a module the commit did not touch says so
+  rather than showing today's value; a module saved by a different version of Val
+  says the version differs and that nothing is lost; a commit made before Val
+  started recording history disables restore with the reason next to it. Images
+  and files are restored by re-uploading them, since the bytes at an old commit
+  may no longer be on your branch.
+
+  History requires the Val content service. In filesystem mode it reports
+  `not-supported-in-fs-mode` rather than faking it from git, which has the files
+  but not which of a commit's changes were one editor's work.
+
+### Patch Changes
+
+- [#618](https://github.com/valbuild/val/pull/618) [`da6794f`](https://github.com/valbuild/val/commit/da6794f3dbd77d49ccfe780b359bab1689ee1b11) Thanks [@freekh](https://github.com/freekh)! - Remove the unused `GET /api/val/session` endpoint.
+
+  Nothing called it. The Studio reads the profile id from `/stat`, and in proxy
+  mode the route proxied to `${VAL_BUILD_URL}/api/val/${project}/auth/session`,
+  an upstream route that no longer exists — so calling it by hand returned a 500
+  rather than a session. It is gone from both the route declarations in
+  `@valbuild/shared` and the implementation in `@valbuild/server`.
+
+  Session cookie handling itself is unchanged: `/authorize`, `/callback` and
+  `/logout` still set and clear `val_session` as before.
+
 ## 0.121.0
 
 ### Minor Changes

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

@@ -273,46 +273,6 @@ export declare const Api: {
             }, z.core.$strip>;
         };
     };
-    "/session": {
-        GET: {
-            req: {
-                cookies: {
-                    val_session: z.ZodOptional<z.ZodString>;
-                };
-            };
-            res: z.ZodUnion<readonly [z.ZodObject<{
-                status: z.ZodLiteral<200>;
-                json: z.ZodObject<{
-                    mode: z.ZodUnion<readonly [z.ZodLiteral<"local">, z.ZodLiteral<"proxy">]>;
-                    enabled: z.ZodBoolean;
-                }, z.core.$strip>;
-            }, z.core.$strip>, z.ZodObject<{
-                status: z.ZodUnion<readonly [z.ZodLiteral<400>, z.ZodLiteral<401>, z.ZodLiteral<403>, z.ZodLiteral<404>, z.ZodLiteral<500>, z.ZodLiteral<501>]>;
-                json: z.ZodObject<{
-                    message: z.ZodString;
-                }, z.core.$strip>;
-            }, z.core.$strip>, z.ZodObject<{
-                status: z.ZodLiteral<401>;
-                json: z.ZodObject<{
-                    message: z.ZodString;
-                    details: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-                        reason: z.ZodString;
-                    }, z.core.$strip>, z.ZodObject<{
-                        sub: z.ZodString;
-                        exp: z.ZodNumber;
-                        token: z.ZodString;
-                        org: z.ZodString;
-                        project: 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>]>;
-        };
-    };
     "/logout": {
         GET: {
             req: {
@@ -980,7 +940,7 @@ export declare const Api: {
                             message: z.ZodString;
                             value: z.ZodOptional<z.ZodUnknown>;
                             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" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "jsonValues:extract-entry", 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" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "jsonValues:extract-entry", unknown>>>>;
+                            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" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "jsonValues:extract-entry" | "external:upload", 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" | "keyof:check-keys" | "router:check-route" | "images:check-unique-folder" | "files:check-unique-folder" | "images:check-all-files" | "files:check-all-files" | "jsonValues:extract-entry" | "external:upload", unknown>>>>;
                         }, z.core.$strip>>>>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>;
@@ -1096,6 +1056,309 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    "/history/commits": {
+        GET: {
+            req: {
+                query: {
+                    branch: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    limit: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>, z.ZodTransform<number, string>>>;
+                    /** The previous page's `nextCursor`. */
+                    cursor: 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;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    commits: z.ZodArray<z.ZodObject<{
+                        commitSha: z.ZodString;
+                        parentCommitSha: z.ZodString;
+                        clientCommitSha: z.ZodString;
+                        branch: z.ZodString;
+                        createdBranch: z.ZodNullable<z.ZodString>;
+                        creator: z.ZodNullable<z.ZodString>;
+                        message: z.ZodNullable<z.ZodString>;
+                        createdAt: z.ZodString;
+                        seqNum: z.ZodString;
+                        patchCount: z.ZodNumber;
+                        hasArchive: z.ZodBoolean;
+                    }, z.core.$strip>>;
+                    nextCursor: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /**
+     * One commit, reconstructed. IMMUTABLE for a given sha - it says nothing
+     * about the current source or schema, which is what lets it be cached
+     * forever and what makes comparing many commits cheap.
+     */
+    "/history/commit": {
+        GET: {
+            req: {
+                query: {
+                    commit_sha: 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;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    commit: z.ZodObject<{
+                        commitSha: z.ZodString;
+                        parentCommitSha: z.ZodString;
+                        clientCommitSha: z.ZodString;
+                        branch: z.ZodString;
+                        createdBranch: z.ZodNullable<z.ZodString>;
+                        creator: z.ZodNullable<z.ZodString>;
+                        message: z.ZodNullable<z.ZodString>;
+                        createdAt: z.ZodString;
+                        seqNum: z.ZodString;
+                        patchCount: z.ZodNumber;
+                        hasArchive: z.ZodBoolean;
+                    }, z.core.$strip>;
+                    modules: z.ZodRecord<z.ZodString, z.ZodObject<{
+                        source: z.ZodNullable<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
+                        schema: z.ZodNullable<z.ZodType<import("@valbuild/core").SerializedSchema, unknown, z.core.$ZodTypeInternals<import("@valbuild/core").SerializedSchema, unknown>>>;
+                        patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                        changedPaths: z.ZodArray<z.ZodString>;
+                        failures: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                            kind: z.ZodLiteral<"commit-not-found">;
+                            commitSha: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"archive-unreadable">;
+                            commitSha: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"source-unavailable">;
+                            moduleFilePath: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"schema-unreadable">;
+                            moduleFilePath: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"file-unavailable">;
+                            gitPath: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"not-supported-in-fs-mode">;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"transport">;
+                            message: z.ZodString;
+                        }, z.core.$strip>], "kind">>;
+                    }, 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>>;
+                        moduleFilePath: z.ZodString;
+                        patch: z.ZodUnknown;
+                        authorId: z.ZodNullable<z.ZodString>;
+                        createdAt: z.ZodString;
+                        baseSha: z.ZodString;
+                        coreVersion: z.ZodString;
+                    }, z.core.$strip>>;
+                    jsonEntries: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    binaryFiles: z.ZodArray<z.ZodObject<{
+                        gitPath: z.ZodString;
+                        change: z.ZodUnion<readonly [z.ZodLiteral<"added">, z.ZodLiteral<"modified">, z.ZodLiteral<"deleted">]>;
+                        remote: z.ZodBoolean;
+                        url: z.ZodString;
+                    }, z.core.$strip>>;
+                    warnings: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                        kind: z.ZodLiteral<"commit-not-found">;
+                        commitSha: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"archive-unreadable">;
+                        commitSha: z.ZodString;
+                        message: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"source-unavailable">;
+                        moduleFilePath: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"schema-unreadable">;
+                        moduleFilePath: z.ZodString;
+                        message: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"file-unavailable">;
+                        gitPath: z.ZodString;
+                        message: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"not-supported-in-fs-mode">;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"transport">;
+                        message: z.ZodString;
+                    }, z.core.$strip>], "kind">>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /**
+     * ONE module, as of a commit — including a commit that did not change it.
+     *
+     * `/history/commit` covers what a commit changed, which is the narrow case:
+     * navigate the history pane to anything else and there would be nothing to
+     * show. This answers "how did this module look at that point", which is the
+     * question someone comparing two panes is actually asking. Immutable for the
+     * same reason: what a commit left behind cannot change.
+     */
+    "/history/module": {
+        GET: {
+            req: {
+                query: {
+                    commit_sha: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    module_file_path: 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;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    moduleFilePath: z.ZodString;
+                    module: z.ZodNullable<z.ZodObject<{
+                        source: z.ZodNullable<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
+                        schema: z.ZodNullable<z.ZodType<import("@valbuild/core").SerializedSchema, unknown, z.core.$ZodTypeInternals<import("@valbuild/core").SerializedSchema, unknown>>>;
+                        patchIds: z.ZodArray<z.ZodString & z.ZodType<import("@valbuild/core").PatchId, string, z.core.$ZodTypeInternals<import("@valbuild/core").PatchId, string>>>;
+                        changedPaths: z.ZodArray<z.ZodString>;
+                        failures: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                            kind: z.ZodLiteral<"commit-not-found">;
+                            commitSha: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"archive-unreadable">;
+                            commitSha: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"source-unavailable">;
+                            moduleFilePath: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"schema-unreadable">;
+                            moduleFilePath: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"file-unavailable">;
+                            gitPath: z.ZodString;
+                            message: z.ZodString;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"not-supported-in-fs-mode">;
+                        }, z.core.$strip>, z.ZodObject<{
+                            kind: z.ZodLiteral<"transport">;
+                            message: z.ZodString;
+                        }, z.core.$strip>], "kind">>;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /**
+     * One file as it was at one commit.
+     *
+     * The lazy half: `/history/commit` NAMES a commit's binary files and this is
+     * where their bytes come from, so nothing is fetched until an `<img>`
+     * actually mounts. A file at a fixed commit cannot change, so the response is
+     * immutable and the browser's own cache handles flipping between commits.
+     */
+    "/history/files": {
+        GET: {
+            req: {
+                query: {
+                    commit_sha: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    path: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    remote: 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<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                body: z.ZodCustom<import("node:stream/web").ReadableStream<unknown>, import("node:stream/web").ReadableStream<unknown>>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/files": {
         GET: {
             req: {

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

@@ -3,11 +3,13 @@ export * from "./server/types.js";
 export * from "./ValClient.js";
 export * from "./ValUrls.js";
 export * from "./ApiRoutes.js";
+export * from "./schema/compatibility.js";
 export * from "./newestCommitSha.js";
 export * from "./zod/Patch.js";
 export * from "./sessionStorage.js";
 export * from "./SharedValConfig.js";
 export * from "./zod/ValCommit.js";
+export * from "./zod/History.js";
 export * from "./zod/ValDeployment.js";
 export * from "./getSitemapTree.js";
 export * from "./parseRoutePattern.js";

package/dist/declarations/src/internal/schema/compatibility.d.ts

@@ -0,0 +1,62 @@
+import type { Json, SerializedSchema } from "@valbuild/core";
+/**
+ * Can this value, taken from one schema, be written into another?
+ *
+ * The question restore asks, and it is NOT the question validation asks.
+ * Validation checks a value against the schema it belongs to. This compares two
+ * schemas — the one a value was stored under and the one it is being written
+ * into — because a restore moves a value across a schema change, and possibly
+ * across paths.
+ *
+ * Three answers, not two. `unknown` is where the comparison genuinely cannot
+ * decide, and it exists so that an editor is told "we are not sure" rather than
+ * being given a confident answer we made up. Treating unknown as compatible
+ * writes values that break; treating it as incompatible blocks restores that
+ * would have been fine.
+ */
+export type Compatibility = {
+    status: "compatible";
+} | {
+    status: "incompatible";
+    reason: IncompatibleReason;
+} | {
+    status: "unknown";
+    message: string;
+};
+export type IncompatibleReason = {
+    kind: "type-changed";
+    from: string;
+    to: string;
+} | {
+    kind: "no-matching-variant";
+    variants: string[];
+} | {
+    kind: "unknown-field";
+    keys: string[];
+} | {
+    kind: "missing-required";
+    keys: string[];
+} | {
+    kind: "not-optional";
+} | {
+    kind: "literal-changed";
+    from: string;
+    to: string;
+} | {
+    kind: "different-module";
+    from: string;
+    to: string;
+};
+/**
+ * A sentence an editor can act on, for the popup that explains a refusal.
+ *
+ * Kept beside the reasons rather than in the UI so that adding a reason without
+ * wording for it is a type error rather than a blank dialog.
+ */
+export declare function explainIncompatible(reason: IncompatibleReason): string;
+export declare function checkCompatibility(from: {
+    schema: SerializedSchema;
+    value: Json;
+}, to: {
+    schema: SerializedSchema;
+}): Compatibility;