@valbuild/core 0.121.0 → 0.124.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @valbuild/core
 
+## 0.124.0
+
+### Minor Changes
+
+- [#622](https://github.com/valbuild/val/pull/622) [`aa89fc2`](https://github.com/valbuild/val/commit/aa89fc26de7028b3c5a1666b99afc03b39e92769) Thanks [@freekh](https://github.com/freekh)! - **Breaking:** `s.images()` and `s.files()` no longer take a `remote` option. Use
+  `.remote()`, the same way `s.image()` and `s.file()` already did.
+
+  ```ts
+  // before
+  s.images({ directory: "/public/val/images", remote: true });
+  s.files({
+    directory: "/public/val/docs",
+    accept: "application/pdf",
+    remote: true,
+  });
+
+  // after
+  s.images({ directory: "/public/val/images" }).remote();
+  s.files({
+    directory: "/public/val/docs",
+    accept: "application/pdf",
+  }).remote();
+  ```
+
+  Behaviour is unchanged — remote is still off unless asked for. This only makes
+  remote one thing spelled one way across all four media schemas, instead of an
+  option on the two collections and a method on the two fields. `remote: false`
+  has no replacement because it was the default; drop it.
+
 ## 0.121.0
 
 ### Minor Changes

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

@@ -3,13 +3,14 @@ export { modules, type ValModules } from "./modules.js";
 export { extractValModules, computeValModuleShas, type ExtractedValModules, type ValModuleShaEntry, type ValModuleShas, type ExtractedModuleError, } from "./extractValModules.js";
 export type { InitVal, ValConfig, ValConstructor, ContentConstructor, } from "./initVal.js";
 export { Schema, type SerializedSchema, type SelectorOfSchema } from "./schema/index.js";
-export { hasRemoteFileSchema } from "./schema/hasRemoteFileSchema.js";
+export { hasRemoteFileSchema, hasMediaSchema, } from "./schema/hasRemoteFileSchema.js";
 export type { ImageMetadata, ImageEncodeOption, ImageEncodeOptions, } from "./schema/image.js";
 export type { FileMetadata } from "./schema/file.js";
 export type { ValModule, SerializedModule, InferValModuleType } from "./module.js";
 export type { SourceObject, SourcePrimitive, Source } from "./source/index.js";
 export type { FileSource } from "./source/media.js";
 export type { JsonSource, JsonOf, JsonImportThunk } from "./source/json.js";
+export type { ExternalRecordSrc, ExternalRecordWritableSrc, ExternalItemOf, ExternalLabelOf, ExternalReadonlyOf, } from "./source/external.js";
 export type { RemoteRef } from "./source/remote.js";
 export { DEFAULT_VAL_REMOTE_HOST } from "./schema/remote.js";
 export type { RawString } from "./schema/string.js";
@@ -35,6 +36,8 @@ import { getMimeType, mimeTypeToFileExt, filenameToMimeType, mimeTypeMatchesAcce
 import { type ImageMetadata } from "./schema/image.js";
 import { type FileMetadata } from "./schema/file.js";
 import { isJson, getJsonImport, resolveJsonValues } from "./source/json.js";
+import { isExternal, hasInlineExternalEntries } from "./source/external.js";
+import { createExternalFileRef, splitExternalFileRef, isExternalFileRef } from "./source/externalRef.js";
 import { createRemoteRef } from "./source/remote.js";
 import { getValidationBasis, getValidationHash } from "./remote/validationBasis.js";
 import { getFileHash, hashToRemoteFileHash } from "./remote/fileHash.js";
@@ -111,6 +114,11 @@ declare const Internal: {
     isJson: typeof isJson;
     getJsonImport: typeof getJsonImport;
     resolveJsonValues: typeof resolveJsonValues;
+    isExternal: typeof isExternal;
+    hasInlineExternalEntries: typeof hasInlineExternalEntries;
+    createExternalFileRef: typeof createExternalFileRef;
+    splitExternalFileRef: typeof splitExternalFileRef;
+    isExternalFileRef: typeof isExternalFileRef;
     createValPathOfItem: typeof createValPathOfItem;
     getSHA256Hash: (bits: Uint8Array) => string;
     initSchema: typeof initSchema;

package/dist/declarations/src/initVal.d.ts

@@ -2,9 +2,11 @@ import { define } from "./module.js";
 import { InitSchema } from "./initSchema.js";
 import { getValPath as getPath } from "./val/index.js";
 import { json } from "./source/json.js";
+import { external } from "./source/external.js";
 export type ContentConstructor = {
     define: typeof define;
     json: typeof json;
+    external: typeof external;
 };
 export type ValConstructor = {
     unstable_getPath: typeof getPath;

package/dist/declarations/src/module.d.ts

@@ -1,6 +1,7 @@
 import { Schema, SelectorOfSchema, SerializedSchema } from "./schema/index.js";
 import { GenericSelector, SelectorOf, SelectorSource } from "./selector/index.js";
 import { Source } from "./source/index.js";
+import { ExternalRecordSrc } from "./source/external.js";
 import { ModuleFilePath, ModulePath, SourcePath } from "./val/index.js";
 import { Json } from "./Json.js";
 import { RawString } from "./schema/string.js";
@@ -15,8 +16,24 @@ export type ReplaceRawStringWithString<T extends SelectorSource> = SelectorSourc
 } ? {
     [key in keyof T]: ReplaceRawStringWithString<T[key]>;
 } : T extends SelectorSource[] ? ReplaceRawStringWithString<T[number]>[] : T;
+/**
+ * What may be WRITTEN as an external record's source, on top of the marker.
+ *
+ * Entries inline in the `.val.ts` are accepted on purpose — the same call
+ * `.jsonValues()` makes for the same reason: pasting content straight into the
+ * module is the natural first thing to write, and a type error there is a dead
+ * end, because the author cannot see what to write instead. Validation reports
+ * them as an `external:upload` fix, and they are readable at runtime meanwhile.
+ *
+ * Widened HERE rather than in the schema's own source type so that the MODULE
+ * stays typed on the marker alone. An adapter is bound to a module, and a module
+ * whose type were "marker or plain record" would be indistinguishable from an
+ * ordinary record — which would let `entry()` accept a module that is not
+ * external at all.
+ */
+type InlineEntriesFor<S> = S extends ExternalRecordSrc<infer Item, string, boolean> ? Record<string, Item> : never;
 export declare function define<T extends Schema<SelectorSource>>(id: string, // TODO: `/${string}`
-schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
+schema: T, source: ReplaceRawStringWithString<SelectorOfSchema<T>> | InlineEntriesFor<SelectorOfSchema<T>>): ValModule<SelectorOfSchema<T>>;
 export declare function getSource<T extends Source>(valModule: ValModule<T>): T;
 /**
  * Whether `value` is a Val module, i.e. something {@link define} produced.

package/dist/declarations/src/schema/files.d.ts

@@ -21,11 +21,6 @@ export type FilesOptions = {
      * a directory with every other one.
      */
     directory: "/public" | `/public/${string}`;
-    /**
-     * Whether remote files are allowed
-     * @default false
-     */
-    remote?: boolean;
 };
 /**
  * Metadata for a file entry in the files record
@@ -43,6 +38,8 @@ type FilesItemSrc = {
 /**
  * Define a collection of files.
  *
+ * Remote is off by default: call `.remote()` on the result to allow remote files.
+ *
  * @example
  * ```typescript
  * const schema = s.files({

package/dist/declarations/src/schema/hasRemoteFileSchema.d.ts

@@ -5,9 +5,10 @@ import type { SerializedSchema } from "./index.js";
  * The one answer to that question. There used to be two — `hasRemoteFileSchema`
  * in the server, gating whether `/save` demands remote credentials, and
  * `findRequiredRemoteFiles` in the Studio, gating the `/remote/settings` fetch —
- * and they disagreed about `s.images({ remote: true })`: the Studio's counted a
- * remote media record, the server's did not, because a media collection
- * serializes as a `record` of metadata rather than as an image schema.
+ * and they disagreed about `s.images({ ... }).remote()`: the Studio's version
+ * counted a remote media record, the server's did not, because a media
+ * collection serializes as a `record` of metadata rather than as an image
+ * schema.
  *
  * The server's answer was the wrong one, and silently so. With it false,
  * `/save` runs `saveOrUploadFiles` in `skip-remote` mode, and that mode does not
@@ -32,3 +33,20 @@ import type { SerializedSchema } from "./index.js";
  * instead would reintroduce exactly the silent skip described above.
  */
 export declare function hasRemoteFileSchema(schema: SerializedSchema): boolean;
+/**
+ * Does this schema hold any media at all — remote or not?
+ *
+ * The sibling of {@link hasRemoteFileSchema}, and the same walk minus the
+ * `remote` predicate. It answers the question an external record has to ask
+ * before it will accept a binding: an item schema containing media needs a
+ * `putFile`/`getFile` pair, and without one that is a schema error.
+ *
+ * It is a walk over the SERIALIZED schema for the reasons given above, and for
+ * one more that is specific to this question: the two cases most likely to be
+ * missed are invisible to a value type. A media collection (`s.images()` /
+ * `s.files()`) serializes as a record of metadata with no image schema inside
+ * it, and a richtext inline image lives in a constructor argument. A check
+ * written against the item TYPE would silently pass both — and the gallery case
+ * already has a data-loss incident attached to it (see above).
+ */
+export declare function hasMediaSchema(schema: SerializedSchema): boolean;

package/dist/declarations/src/schema/images.d.ts

@@ -35,11 +35,6 @@ export type ImagesOptions<Accept extends `image/${string}`> = {
      * - s.record(s.string(), s.string()) for locale-based alt text
      */
     alt?: AltSchema;
-    /**
-     * Whether remote images are allowed
-     * @default false
-     */
-    remote?: boolean;
     /**
      * Re-encode uploads in the browser before they are uploaded.
      *
@@ -79,7 +74,7 @@ type ImagesItemSrc = {
  *
  * `directory` is required — it decides where uploads land, so it is not something
  * to be inferred. The rest defaults: any image type (`"image/*"`), nullable alt
- * text, remote disabled.
+ * text, remote disabled. Call `.remote()` on the result to allow remote images.
  *
  * @example
  * ```typescript

package/dist/declarations/src/schema/record.d.ts

@@ -4,6 +4,7 @@ import { FieldRender } from "../render.js";
 import { ValRouter } from "../router.js";
 import { SelectorSource } from "../selector/index.js";
 import { JsonOf, JsonSource } from "../source/json.js";
+import { ExternalRecordSrc } from "../source/external.js";
 import { ModuleFilePath, SourcePath } from "../val/index.js";
 import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
 import type { ImageEncodeOption } from "./image.js";
@@ -38,6 +39,12 @@ export type SerializedRecordSchema = {
     encode?: ImageEncodeOption;
     alt?: SerializedSchema;
     jsonValues?: boolean;
+    /**
+     * The label from `.external(label)`. Its presence is what marks the record as
+     * externally stored; the value names the binding a reader — or a model — can
+     * grep for. See `source/external.ts`.
+     */
+    external?: string;
     readonly?: boolean;
     hidden?: boolean;
     description?: string;
@@ -56,7 +63,13 @@ export type SerializedRecordSchema = {
  * authoring.
  */
 export type JsonValuesRecordSrc<T extends Schema<SelectorSource>, K extends Schema<string>> = Record<SelectorOfSchema<K>, JsonSource<JsonOf<SelectorOfSchema<T>>> | SelectorOfSchema<T>>;
-export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Schema<string>, Src extends Record<SelectorOfSchema<K>, SelectorOfSchema<T>> | JsonValuesRecordSrc<T, K> | null> extends Schema<Src> {
+export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Schema<string>, Src extends Record<SelectorOfSchema<K>, SelectorOfSchema<T>> | JsonValuesRecordSrc<T, K> | ExternalRecordSrc | null, 
+/**
+ * Whether `.readonly()` was called. It rides in the type — not only in
+ * `isReadonly` — because `.external()` freezes it into the source marker, and
+ * the adapter's write methods are required or forbidden on the strength of it.
+ */
+RO extends boolean = false> extends Schema<Src> {
     private readonly item;
     private readonly opt;
     private readonly customValidateFunctions;
@@ -70,9 +83,31 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     private readonly isJsonValues;
     private readonly previewInput;
     private readonly renderInput;
+    /**
+     * Set by `.external(label)`; the entries live behind that adapter.
+     *
+     * LAST on purpose: every other `new RecordSchema(...,
+      this.externalLabel,
+    )` in the codebase
+     * passes its arguments positionally, so a new parameter anywhere else
+     * silently shifts `previewInput` and `renderInput` at each of those call
+     * sites.
+     */
+    private readonly externalLabel;
     constructor(item: T, opt?: boolean, customValidateFunctions?: CustomValidateFunction<Src>[], currentRouter?: ValRouter | null, keySchema?: Schema<string> | null, mediaOptions?: MediaOptions | undefined, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, 
     /** When true, entry values are lazily loaded {@link JsonSource} thunks. */
-    isJsonValues?: boolean, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | null);
+    isJsonValues?: boolean, previewInput?: ItemPreviewInput<Src> | null, renderInput?: FieldRender | null, 
+    /**
+     * Set by `.external(label)`; the entries live behind that adapter.
+     *
+     * LAST on purpose: every other `new RecordSchema(...,
+      this.externalLabel,
+    )` in the codebase
+     * passes its arguments positionally, so a new parameter anywhere else
+     * silently shifts `previewInput` and `renderInput` at each of those call
+     * sites.
+     */
+    externalLabel?: string | null);
     describe(description: string | null): RecordSchema<T, K, Src>;
     validate(validationFunction: (src: Src) => false | string): RecordSchema<T, K, Src>;
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
@@ -84,7 +119,17 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
     private validateMediaMimeType;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): RecordSchema<T, K, Src | null>;
-    readonly(isReadonly?: boolean): RecordSchema<T, K, Src>;
+    /**
+     * A record you can look at but not change.
+     *
+     * The flag rides in the TYPE as well as in the instance, so `.external()` can
+     * freeze it into the source marker and the adapter's write methods become
+     * required or forbidden on the strength of it. That is also why `.readonly()`
+     * must come BEFORE `.external()`: afterwards the value is a `Schema`, and
+     * there is no `.readonly()` left to call — which is the error the compiler
+     * gives, and a clearer one than a runtime throw.
+     */
+    readonly<B extends boolean = true>(isReadonly?: B): RecordSchema<T, K, Src, B>;
     hidden(isHidden?: boolean): RecordSchema<T, K, Src>;
     router(router: ValRouter): RecordSchema<T, K, Src>;
     remote(): RecordSchema<T, K, Src>;
@@ -103,6 +148,37 @@ export declare class RecordSchema<T extends Schema<SelectorSource>, K extends Sc
      * substitution and content validation are all root-only.
      */
     jsonValues(): RecordSchema<T, K, JsonValuesRecordSrc<T, K>>;
+    /**
+     * Store this record's entries behind an adapter — a database, an HTTP API, a
+     * bucket — instead of in the module.
+     *
+     * Available on every record-derived schema, which is `s.record()`,
+     * `s.router()`, `s.images()` and `s.files()` alike: a router is a
+     * `RecordSchema` with a `ValRouter`, a gallery one with media options, so all
+     * four get external storage from this one method.
+     *
+     * `label` does not address the binding — the registry is keyed by module, and
+     * so is the wire protocol. It exists so a reader of the schema can see what
+     * backs it, and it is checked against the binding that claims it, so the two
+     * cannot drift.
+     *
+     * Only supported on a module's ROOT record, exactly as `.jsonValues()` is: a
+     * nested external record would leave a hole in the middle of a module's
+     * source, and the Studio, patching and validation all assume a module's
+     * source is complete apart from its entries.
+     */
+    external<L extends string>(label: L): RecordSchema<T, K, ExternalRecordSrc<SelectorOfSchema<T>, L, RO>, RO>;
+    /**
+     * An external record's source is either the `c.external()` marker or entries
+     * still written inline in the `.val.ts`.
+     *
+     * Inline entries are NOT a type error (see `ExternalRecordWritableSrc`), so
+     * this is where they surface: as an `external:upload` fix, per key, the way
+     * `.jsonValues()` reports an un-extracted entry. Reporting per key rather than
+     * once for the record is what lets the fix be applied to one entry, and what
+     * puts the error at a path the editor can navigate to.
+     */
+    private validateExternal;
     private getRouterValidations;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedRecordSchema;

package/dist/declarations/src/schema/validation/ValidationFix.d.ts

@@ -1,2 +1,2 @@
-export declare const ValidationFix: readonly ["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"];
+export declare const ValidationFix: readonly ["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"];
 export type ValidationFix = (typeof ValidationFix)[number];

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

@@ -12,11 +12,12 @@ import { MediaSource } from "../source/media.js";
 import { AllRichTextOptions, RichTextSource } from "../source/richtext.js";
 import { RichTextSelector } from "./richtext.js";
 import { JsonSource } from "../source/json.js";
+import { ExternalRecordSrc } from "../source/external.js";
 import { SettingsSource } from "../source/settings.js";
-export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends SettingsSource ? GenericSelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
+export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends ExternalRecordSrc ? GenericSelector<T> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends SettingsSource ? GenericSelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
 export type SelectorSource = SourcePrimitive | undefined | readonly SelectorSource[] | {
     [key: string]: SelectorSource;
-} | MediaSource | JsonSource | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

package/dist/declarations/src/source/external.d.ts

@@ -0,0 +1,91 @@
+import { Source, VAL_EXTENSION } from "./index.js";
+/**
+ * The string used as the `_type` discriminator of an {@link ExternalRecordSrc}.
+ */
+export declare const EXTERNAL_VAL_EXTENSION_TAG: "external";
+/**
+ * Type-level-only slots. Declared here rather than reusing `PhantomType`
+ * (`source/index.ts`) because three separate facts have to ride along, and that
+ * helper carries one.
+ *
+ * None of them exist at runtime: `c.external()` produces `{ _type: "external" }`
+ * and nothing else.
+ */
+declare const ExternalItem: unique symbol;
+declare const ExternalLabel: unique symbol;
+declare const ExternalReadonly: unique symbol;
+/**
+ * The source of a record whose entries live behind an adapter — a database, an
+ * HTTP API, a bucket — instead of in the module.
+ *
+ * This is what `c.external()` returns, and it is the counterpart of the
+ * `c.json(() => import(...))` marker a `.jsonValues()` entry carries: a value
+ * that says "the content is not here" without saying anything about what is.
+ * The schema says *which* adapter (`.external("posts")`); this says *that* the
+ * entries are elsewhere, which is what every source-walking consumer needs to
+ * know without holding a schema.
+ *
+ * Three phantom parameters, each earning its place:
+ *
+ * - `T` — the item type. Without it `c.define` would return a module whose type
+ *   is "a marker", the item type would be gone, and an adapter could not be
+ *   typed from the schema at all.
+ * - `L` — the label from `.external(label)`, so a binding can be checked against
+ *   the schema that declared it.
+ * - `RO` — whether the schema said `.readonly()`, which decides whether the
+ *   adapter must implement writes or is forbidden from doing so.
+ *
+ * The defaults are the WIDEST instantiation on purpose: the bare name appears in
+ * the `Source` and `SelectorSource` unions, and every narrower instantiation has
+ * to be assignable to it. The `external()` factory below defaults the other way,
+ * exactly as `JsonSource<T = unknown>` and `json<T = Json>()` do.
+ */
+export type ExternalRecordSrc<T = unknown, L extends string = string, RO extends boolean = boolean> = {
+    readonly [VAL_EXTENSION]: typeof EXTERNAL_VAL_EXTENSION_TAG;
+} & {
+    readonly [ExternalItem]: T;
+    readonly [ExternalLabel]: L;
+    readonly [ExternalReadonly]: RO;
+};
+/**
+ * The marker written as a module's source when its record is `.external()`.
+ *
+ * Takes no arguments: everything it carries is inferred from the schema it is
+ * checked against in `c.define`. The assertion mirrors `json()` — the phantom
+ * slots are symbol-keyed and have no runtime representation, so there is nothing
+ * to construct for them.
+ */
+export declare function external<T = never, L extends string = string, RO extends boolean = false>(): ExternalRecordSrc<T, L, RO>;
+export declare function isExternal(obj: unknown): obj is ExternalRecordSrc;
+/**
+ * The item type an external record holds, read back off a module.
+ *
+ * `GenericSelector` is not imported here — that would be a cycle through
+ * `../selector` — so this is written against the phantom slot directly and the
+ * selector-shaped overloads live where the selector types do.
+ */
+export type ExternalItemOf<S> = S extends ExternalRecordSrc<infer I, string, boolean> ? I : never;
+/** The label an external record was declared with. */
+export type ExternalLabelOf<S> = S extends ExternalRecordSrc<unknown, infer L, boolean> ? L : never;
+/** Whether the schema behind an external record said `.readonly()`. */
+export type ExternalReadonlyOf<S> = S extends ExternalRecordSrc<unknown, string, infer RO> ? RO : never;
+/**
+ * The source of an external record as it may be WRITTEN.
+ *
+ * Either the marker, or entries inline in the `.val.ts`. Inline entries are
+ * accepted by the type on purpose, for the same reason `.jsonValues()` accepts
+ * them (see `JsonValuesRecordSrc`): pasting content straight into the module is
+ * the natural first thing to write, and a type error there is a dead end — the
+ * author cannot see what to write instead. Validation reports the inline entries
+ * as an `external:upload` fix instead, so the mistake is repaired rather than
+ * blocking authoring, and they are readable at runtime meanwhile.
+ */
+export type ExternalRecordWritableSrc<Item, Key extends string = string, L extends string = string, RO extends boolean = boolean> = ExternalRecordSrc<Item, L, RO> | Record<Key, Item>;
+/**
+ * Is this module source an external record that still has entries written
+ * inline? Used by validation to raise `external:upload`.
+ */
+export declare function hasInlineExternalEntries(source: Source): source is {
+    [key: string]: Source;
+};
+export {};

package/dist/declarations/src/source/externalRef.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The reference stored for a file whose bytes live behind an external adapter.
+ *
+ * Deliberately the same shape of idea as a remote ref (`remote/splitRemoteRef`):
+ * a URL-ish string that **ends with the file's virtual path**, so the file's
+ * logical identity survives wherever its bytes happen to be.
+ *
+ *     /api/val/external/documents/f/{fileHash}/p/public/val/documents/report_a1b2c.pdf
+ *      \__________________________/ \________/   \_______________________________/
+ *              route + label          content        the path a LOCAL file
+ *                                     address        would have had
+ *
+ * Three things follow from that shape, and each is load-bearing:
+ *
+ * - **`media.ts` needs no change.** `isRemote` is `!path.startsWith("/public")`,
+ *   and this does not, so `Internal.mediaUrl` returns the ref as-is and Val's
+ *   route serves it. The media rule that has been got wrong repeatedly is left
+ *   exactly alone.
+ * - **Moving between storage modes is mechanical.** External → local reads the
+ *   `public/…` suffix back out, fetches the bytes and writes them there; local →
+ *   external uploads the file already at that path. Nothing is renamed.
+ * - **The filename is Val's, not the adapter's**, produced by the same
+ *   `createFilename` a local or remote file uses — so the same bytes get the
+ *   same name under all three storage modes.
+ */
+export type ExternalFileRefParts = {
+    /** The `.external(label)` of the record the file belongs to. */
+    label: string;
+    /** SHA-256 of the bytes. Content-addressed, so a retried publish re-uses. */
+    fileHash: string;
+    /** The virtual path, WITHOUT a leading slash: `public/val/...`. */
+    filePath: `public/${string}`;
+};
+export declare function createExternalFileRef({ label, fileHash, filePath, }: {
+    label: string;
+    fileHash: string;
+    /** Accepts the path as it is written in a module: `/public/val/...`. */
+    filePath: string;
+}): string;
+export declare function splitExternalFileRef(ref: string): ({
+    status: "success";
+} & ExternalFileRefParts) | {
+    status: "error";
+    error: string;
+};
+export declare function isExternalFileRef(ref: string): boolean;

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

@@ -1,8 +1,9 @@
+import { ExternalRecordSrc } from "./external.js";
 import { JsonSource } from "./json.js";
 import { MediaSource } from "./media.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
 import { SettingsSource } from "./settings.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | SettingsSource | RichTextSource<RichTextOptions>;
+export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {
@@ -22,7 +23,7 @@ export type SourceObject = {
 export type SourceArray = readonly Source[];
 export type SourcePrimitive = string | number | boolean | null;
 export declare const VAL_EXTENSION: "_type";
-export declare function getValExtension(source: Source): false | "" | 0 | "json" | null | undefined;
+export declare function getValExtension(source: Source): false | "" | 0 | "json" | "external" | null | undefined;
 /**
  * A phantom type parameter is one that doesn't show up at runtime, but is checked statically (and only) at compile time.
  *