@valbuild/core 0.120.0 → 0.124.0

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,8 +119,18 @@ 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(): RecordSchema<T, K, Src>;
-    hidden(): 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/richtext.d.ts

@@ -40,8 +40,8 @@ export declare class RichTextSchema<O extends RichTextOptions, Src extends RichT
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     private recursiveAssert;
     nullable(): RichTextSchema<O, Src | null>;
-    readonly(): RichTextSchema<O, Src>;
-    hidden(): RichTextSchema<O, Src>;
+    readonly(isReadonly?: boolean): RichTextSchema<O, Src>;
+    hidden(isHidden?: boolean): RichTextSchema<O, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -71,8 +71,8 @@ export declare class RouteSchema<Src extends string | null> extends Schema<Src>
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): RouteSchema<Src | null>;
-    readonly(): RouteSchema<Src>;
-    hidden(): RouteSchema<Src>;
+    readonly(isReadonly?: boolean): RouteSchema<Src>;
+    hidden(isHidden?: boolean): RouteSchema<Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * How this field is laid out in the editor when it is the item of an array

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

@@ -0,0 +1,102 @@
+import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
+import { PreviewScope, ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
+import { SelectorSource } from "../selector/index.js";
+import { SettingsSource } from "../source/settings.js";
+import { ModuleFilePath, SourcePath } from "../val/index.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+export type SerializedSettingsSchema = {
+    type: "settings";
+    /**
+     * The sections this settings schema knows about, keyed by name.
+     *
+     * Carried in full rather than reconstructed from the Val version, so a Studio
+     * that predates a section still deserializes the schema (it renders what it
+     * recognises and leaves the rest alone) instead of failing on an unknown
+     * shape.
+     */
+    items: Record<string, SerializedSchema>;
+    opt: boolean;
+    /**
+     * Present in the shape, never set by `s.settings()`.
+     *
+     * `render` and `preview` say how a value is drawn where it is an ITEM of an
+     * array or a record, and `customValidate` marks a user's `validate` closure. A
+     * settings module is not an item, and `s.settings()` takes no arguments to
+     * declare any of the three with — so nothing writes them.
+     *
+     * They are declared anyway, and with their real types rather than `never`, for
+     * two reasons: reading `schema.render` off a `SerializedSchema` has to stay
+     * legal (`isInlineRender` does exactly that), and a `?: never` member is typed
+     * `undefined`, which makes the whole `SerializedSchema` union stop being
+     * assignable to `Json` — and serialized schemas travel to the Studio and to
+     * the MCP tools as JSON.
+     */
+    render?: FieldRender;
+    preview?: true;
+    customValidate?: boolean;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+/**
+ * An object whose keys are all optional: absent means unset.
+ *
+ * Both the settings module itself and each of its sections are this. See
+ * {@link SettingsSource} for why settings cannot be an object schema, and
+ * {@link settings} for what a settings module holds.
+ *
+ * There is no `describe`, `validate`, `render` or `preview` on purpose: the
+ * shape is Val's, not the schema author's — `s.settings()` takes no arguments —
+ * and the Studio renders each section with a UI built for it.
+ */
+export declare class SettingsSchema<Src extends {
+    [key: string]: SelectorSource;
+} | null> extends Schema<Src> {
+    private readonly items;
+    private readonly opt;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    constructor(items: Record<string, Schema<SelectorSource>>, opt?: boolean, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined);
+    protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
+    nullable(): SettingsSchema<Src | null>;
+    readonly(): SettingsSchema<Src>;
+    hidden(): SettingsSchema<Src>;
+    protected executeCustomValidateAt(): ValidationError[];
+    protected executeSerialize(): SerializedSchema;
+    protected executePreview(sourcePath: SourcePath | ModuleFilePath, src: Src, scope?: PreviewScope): ReifiedPreview;
+}
+/**
+ * Define the project's settings.
+ *
+ * One settings module per project, at the root of the content tree — a module
+ * file path with no directory segment, `/settings.val.ts` by convention:
+ *
+ * ```typescript
+ * export default c.define("/settings.val.ts", s.settings(), {});
+ * ```
+ *
+ * Every section is optional, so `{}` is a complete settings module and stays
+ * one as sections are added. Fill in what the project needs:
+ *
+ * ```typescript
+ * export default c.define("/settings.val.ts", s.settings(), {
+ *   assistant: {
+ *     enabled: true,
+ *     context: "Val is a CMS for developers. British English, and 'Val' is never 'VAL'.",
+ *     tone: "Plain and direct. No exclamation marks, sentence case in headings.",
+ *   },
+ * });
+ * ```
+ *
+ * The Studio edits it under the cog at the foot of the left rail, and the
+ * assistant is told `assistant.context` and `assistant.tone` on every message.
+ *
+ * `s.settings()` takes no arguments: the shape is Val's, which is what lets the
+ * Studio render a UI built for each field rather than a generic form. A
+ * project's own global content — a site name, social links — belongs in a
+ * module of its own.
+ */
+export declare function settings(): SettingsSchema<SettingsSource>;

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

@@ -82,8 +82,8 @@ export declare class StringSchema<Src extends string | null> extends Schema<Src>
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): StringSchema<Src | null>;
-    readonly(): StringSchema<Src>;
-    hidden(): StringSchema<Src>;
+    readonly(isReadonly?: boolean): StringSchema<Src>;
+    hidden(isHidden?: boolean): StringSchema<Src>;
     raw(): StringSchema<Src extends null ? RawString | null : RawString>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     protected executeSerialize(): SerializedSchema;

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

@@ -56,8 +56,8 @@ export declare class UnionSchema<Key extends string | Schema<string>, T extends
     protected executeValidate(path: SourcePath, src: Src): ValidationErrors;
     protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<Src>;
     nullable(): UnionSchema<Key, T, Src | null>;
-    readonly(): UnionSchema<Key, T, Src>;
-    hidden(): UnionSchema<Key, T, Src>;
+    readonly(isReadonly?: boolean): UnionSchema<Key, T, Src>;
+    hidden(isHidden?: boolean): UnionSchema<Key, T, Src>;
     protected executeCustomValidateAt(path: SourcePath, src: Src): ValidationError[];
     /**
      * The variant schema a value takes, for a TAGGED union (string `key`). `null`

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,10 +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";
-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 string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
+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 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 | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

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

@@ -0,0 +1,60 @@
+import { SerializedSchema } from "./schema/index.js";
+import { ModuleFilePath } from "./val/index.js";
+/**
+ * Where a settings module goes unless a project has a reason not to.
+ *
+ * A convention, not a rule: any module file path at the root of the content
+ * tree may hold `s.settings()` — see {@link resolveSettingsModule}.
+ */
+export declare const SETTINGS_MODULE_CONVENTION: ModuleFilePath;
+/**
+ * Whether a module file path is at the root of the content tree.
+ *
+ * `/settings.val.ts` is; `/content/settings.val.ts` is not. The settings module
+ * is the project's, not a folder's, and a project-wide setting found three
+ * directories down reads as one section's — so the position is part of what it
+ * means.
+ */
+export declare function isRootModuleFilePath(moduleFilePath: string): boolean;
+export type ResolvedSettingsModule = {
+    /**
+     * The project's settings module, if it has exactly one valid one.
+     *
+     * `null` both when there is no settings module and when what there is cannot
+     * be used (nested, or ambiguous). A caller that reads settings therefore does
+     * not have to consider the broken cases: it gets nothing, and the errors are
+     * reported by whoever is in a position to report them.
+     */
+    moduleFilePath: ModuleFilePath | null;
+    /**
+     * What is wrong with how settings are declared, ready to print.
+     *
+     * Empty in the ordinary cases — one settings module, or none. Reported as
+     * MODULE errors, each attributed to the file it is about: extraction appends
+     * them, which is what puts them in front of the reader in all three places at
+     * once — the dev server refuses to serve sources with a module error,
+     * `val validate` reports them against the file, and the Studio shows them.
+     *
+     * A duplicate produces one error per offending module, each naming all of
+     * them, so the message is there whichever of the files you happen to open.
+     */
+    errors: SettingsModuleError[];
+};
+/**
+ * Structurally an `ExtractedModuleError`, declared here rather than imported to
+ * keep `extractValModules` -> `settingsModule` a one-way dependency.
+ */
+export type SettingsModuleError = {
+    message: string;
+    path: ModuleFilePath;
+};
+/**
+ * Find the project's settings module among all its schemas.
+ *
+ * One per project, at the root: a settings module in a subdirectory is an
+ * error, and so is a second one. Both are reported rather than resolved by
+ * picking a winner — a project with two settings modules has a question to
+ * answer, and answering it by sort order means the answer changes when a file
+ * is renamed.
+ */
+export declare function resolveSettingsModule(schemas: Record<ModuleFilePath, SerializedSchema> | Record<ModuleFilePath, SerializedSchema | undefined>): ResolvedSettingsModule;

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,7 +1,9 @@
+import { ExternalRecordSrc } from "./external.js";
 import { JsonSource } from "./json.js";
 import { MediaSource } from "./media.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | RichTextSource<RichTextOptions>;
+import { SettingsSource } from "./settings.js";
+export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {
@@ -21,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.
  *

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

@@ -0,0 +1,94 @@
+/**
+ * The source of the project's settings module — `s.settings()`.
+ *
+ * **Every key is optional, at every level, and that is the whole point.** A
+ * settings module is written as
+ *
+ * ```typescript
+ * export default c.define("/settings.val.ts", s.settings(), {});
+ * ```
+ *
+ * and `{}` has to keep validating as sections are added to it. A project that
+ * never touched the assistant's settings should not have to edit its settings
+ * file the day `locales` or `permissions` land.
+ *
+ * That is why settings is not sugar over `s.object()`: an object schema errors
+ * with `Expected key 'assistant' not found in object` for any absent key (see
+ * `ObjectSchema.executeAssert`), and `.nullable()` permits `null`, not absence.
+ * `SettingsSchema` gives absent keys the meaning "unset" instead.
+ *
+ * `null` means unset too, so the editor can clear a field it has already
+ * written without removing the key.
+ */
+export type SettingsSource = {
+    assistant?: AssistantSettingsSource;
+};
+/**
+ * The assistant: whether editors have one, and what it is told about the
+ * project on every message.
+ *
+ * `context` and `tone` are prose the model reads, not instructions Val
+ * interprets, and both are capped (see {@link ASSISTANT_SETTINGS_MAX_LENGTH}):
+ * they are prepended to every request the chat makes, so an unbounded field
+ * here is an unbounded cost on every turn.
+ */
+export type AssistantSettingsSource = {
+    /**
+     * Whether editors have an assistant in this project.
+     *
+     * Three states, not two — see {@link assistantAvailability}, which is the one
+     * place that reads them. Unset is NOT "on": it is "nobody has decided", and
+     * the Studio treats that as an offer rather than as an answer.
+     */
+    enabled?: boolean | null;
+    /**
+     * Background the model would otherwise have to guess: what this site is, who
+     * runs it, what the product does, names and spellings that matter.
+     */
+    context?: string | null;
+    /**
+     * How the model should write when it writes content — formal or playful,
+     * British or American, sentence case in headings, no exclamation marks.
+     *
+     * Named `tone` rather than `toneOfVoice` so it reads as one hint among
+     * several inside `assistant`, leaving room for siblings (`audience`,
+     * `glossary`) rather than a field that looks like it should absorb them.
+     */
+    tone?: string | null;
+};
+/**
+ * The cap on each of the assistant's prose fields, in characters.
+ *
+ * Roughly a thousand tokens each. Generous enough for a paragraph of
+ * background and a house style, small enough that the two of them together do
+ * not dominate the system prompt they are appended to.
+ */
+export declare const ASSISTANT_SETTINGS_MAX_LENGTH = 4000;
+/**
+ * Whether a project has an assistant — and the answer is not a boolean.
+ *
+ * - `"on"`: use it.
+ * - `"off"`: every trace of it goes. No button in the top bar, no row in the
+ *   quick actions, no panel, nothing sent. A project that says `false` has
+ *   decided, and the Studio does not keep offering.
+ * - `"unconfigured"`: nobody has said. The affordances are SHOWN, and asking to
+ *   use the assistant asks to turn it on first. That is the difference between
+ *   this and `"off"`, and the reason `enabled` is a tri-state: hiding an
+ *   unconfigured assistant means nobody discovers it, and quietly enabling one
+ *   means a project starts sending its content to a model because it did not
+ *   know to say no.
+ *
+ * A project with NO settings module is `"on"`. There is nowhere to record a
+ * decision, so there is nothing to prompt for and nothing to prompt INTO — the
+ * prompt writes to a settings module, and that project has none.
+ *
+ * This is the only answer to "does this project have an assistant":
+ * `config.ai.chat` is gone, and with it the chat's title, description and
+ * suggestions, which nothing replaces. The AI commit-message summariser is
+ * deliberately not part of this — `config.ai.commitMessages` stays where it is,
+ * and gets settings of its own later.
+ */
+export type AssistantAvailability = "on" | "off" | "unconfigured";
+export declare function assistantAvailability(
+/** The settings module's source, or `undefined` where the project has none. */
+settings: SettingsSource | undefined): AssistantAvailability;