@valbuild/server 0.121.0 → 0.122.0

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

@@ -0,0 +1,366 @@
+import type { ExternalItemOf, ExternalLabelOf, ExternalReadonlyOf, ExternalRecordSrc, InferValModuleType, Json, JsonOf, ModuleFilePath, ValModule } from "@valbuild/core";
+/**
+ * The type surface of an external record's adapter.
+ *
+ * Nothing here runs: phase 0 is the contract, and the registry that executes it
+ * arrives with the read endpoints. What the contract has to get right now is the
+ * shape, because every adapter written against it is a compatibility promise.
+ *
+ * Four kinds of method, and each is required or not for one reason:
+ *
+ * - **Read** — `keys`, `get`. Cannot be built out of anything else, so always
+ *   required.
+ * - **Write** — `put`, `delete`. Likewise, and they move together: required on a
+ *   writable record, forbidden on a `.readonly()` one.
+ * - **Derived** — `count`, `search`. Computable from the read methods, so
+ *   omitting one costs performance, never capability. `false` declines the
+ *   fallback; that is the only thing `false` ever means here.
+ * - **Media** — `putFile`, `getFile`. A pair, and required by the item SCHEMA
+ *   rather than by this type (see `hasMediaSchema`).
+ */
+/**
+ * Brands the result envelope so a bare value can be accepted alongside it.
+ *
+ * A symbol rather than a property name because `get` returns
+ * `Record<key, Item>` — a record that can perfectly well contain a key called
+ * `kind`. The envelope never crosses the wire (it travels in-process between
+ * adapter and Val), so there is no serialization cost to it.
+ */
+export declare const EXTERNAL_RESULT: unique symbol;
+export type ExternalIssue = {
+    message: string;
+    /**
+     * Whether repeating the operation could succeed.
+     *
+     * Only the adapter can tell a transient 429 from a permanent 404, so only the
+     * adapter sets this. A THROWN error is never retried: Val cannot tell a rate
+     * limit from a `TypeError`, and retrying a bug three times only fails slower.
+     */
+    retryable?: boolean;
+    /** Names the entry when the problem is one key's, not the whole call's. */
+    key?: string;
+    cause?: unknown;
+};
+export type ExternalResult<T> = {
+    readonly [EXTERNAL_RESULT]: true;
+} & ({
+    kind: "ok";
+    value: T;
+    warnings?: ExternalIssue[];
+} | {
+    kind: "err";
+    error: ExternalIssue;
+});
+/**
+ * What every adapter method may return: the value on its own, or the envelope.
+ *
+ * A bare value means "ok, nothing to report", which keeps the common path one
+ * line. Errors can be thrown instead of returned — the envelope is for a failure
+ * worth classifying, or a success worth annotating.
+ */
+export type Returns<T> = T | ExternalResult<T>;
+/**
+ * Wrap a value as a successful result, optionally with warnings.
+ *
+ * `NoInfer` is load-bearing, not decoration. Without it `T` is inferred FROM the
+ * argument, and an object literal that infers its own type is not contextually
+ * typed by the adapter's contract — so `title` inside `ok({ a: { title } })` is a
+ * fresh property that happens to be named `title`, with no declaration link back
+ * to `title: s.string()` in the schema. "Find all references" on the schema field
+ * then stops at the page that reads it and never reaches the adapter that
+ * produces it. `NoInfer` blocks that inference, leaving the contextual return
+ * type as the only source for `T`, which is what restores the link (and, as a
+ * bonus, makes a typo report the offending property rather than the whole
+ * return value).
+ *
+ * `externalNavigation.test.ts` guards this; nothing else would notice.
+ *
+ * The cost: `ok(...)` in a position with NO contextual type — a helper without a
+ * return type annotation — infers `unknown` instead of the argument's type, and
+ * fails where the helper is used rather than where it is written. Annotate the
+ * helper's return type, or inline it.
+ */
+export declare function ok<T>(value: NoInfer<T>, warnings?: ExternalIssue[]): ExternalResult<T>;
+export declare function err(issue: ExternalIssue): ExternalResult<never>;
+export declare function isExternalResult<T>(value: Returns<T>): value is ExternalResult<T>;
+export type ExternalAuthor = {
+    /** Always present. */
+    id: string;
+    /**
+     * Present when Val knows it — the profile shape has it optional, so an
+     * adapter keying only on email would break for a user without one.
+     */
+    email?: string;
+};
+/**
+ * What every adapter method is told about the call it is serving.
+ *
+ * `tx` is present only when the adapter declared an `around`; a store with no
+ * transaction seam has nothing to put there and nothing to ignore.
+ */
+export type ExternalCtx<Tx> = {
+    moduleFilePath: ModuleFilePath;
+    /** Who is editing. Anything richer is the adapter's to resolve. */
+    author?: ExternalAuthor;
+    /**
+     * 1 on the first call, 2 on the first retry.
+     *
+     * Not only for logging: an adapter can widen a timeout, skip a read replica
+     * that may be lagging, bypass a cache, or give up on its own terms.
+     */
+    attempt: number;
+} & ([Tx] extends [never] ? {
+    tx?: undefined;
+} : {
+    tx: Tx;
+});
+export type ExternalKeyPage = {
+    keys: string[];
+    /** `null` means this was the last page. */
+    cursor: string | null;
+};
+/**
+ * How a page should be ordered.
+ *
+ * Records are unordered today and sorting is coming; the parameter lands now
+ * because adding one to `keys` later would break every adapter that exists by
+ * then. Val passes `undefined` until sorting ships, and an adapter may ignore it.
+ *
+ * Two rules for whoever implements it:
+ *
+ * - **A cursor is only valid for the sort that issued it.** Key-ordered paging
+ *   is `where key > cursor`; sorted paging is `where (field, key) > (…, …)`.
+ *   Val pairs the cursor with a hash of the sort and restarts rather than
+ *   replaying a mismatched one.
+ * - **The key is always the last sort term.** Ordering by a non-unique field
+ *   without a tiebreaker lets rows shift between pages, so page 2 can skip or
+ *   repeat an entry while both pages look fine on their own.
+ */
+export type ExternalSort = {
+    /**
+     * A path into the ITEM: `["publishedAt"]`, `["author", "name"]`. Absent means
+     * order by the entry key, which is the only order there is today.
+     */
+    path?: string[];
+    direction: "asc" | "desc";
+};
+export type ExternalSearchHit<Item> = {
+    key: string;
+    /**
+     * Where it matched, relative to the item. A store that only knows "this row
+     * matched" omits it; the Studio uses it to show the field, not just the row.
+     */
+    path?: string[];
+    /**
+     * The entry as the store has it.
+     *
+     * Val applies pending patches on top before deciding the hit still stands —
+     * which is the whole reason to return it. A delegated search sees only
+     * PUBLISHED content, so without the value there is no way to drop a hit whose
+     * draft edit removed the matching text.
+     */
+    value?: Item;
+};
+export type ExternalSearchPage<Item> = {
+    hits: ExternalSearchHit<Item>[];
+    cursor: string | null;
+};
+export type ExternalFile = {
+    /**
+     * The path Val chose — `${directory}/${createFilename(...)}` — which is the
+     * same name a local or remote file would have got.
+     *
+     * An INPUT, not something the adapter invents: the stored ref embeds this
+     * path, so a gallery can be moved back to local storage by writing the bytes
+     * where the ref already says they belong.
+     */
+    path: string;
+    bytes: Uint8Array;
+    filename: string;
+    mimeType: string;
+    /** Content address. Make `putFile` idempotent on it, so a retry re-uses. */
+    sha256: string;
+};
+type AnyExternalModule = ValModule<ExternalRecordSrc>;
+/** Read methods. Always required. */
+type ReadMethods<Item, Tx> = {
+    keys(args: {
+        cursor: string | null;
+        limit: number;
+        sort?: ExternalSort;
+    }, ctx: ExternalCtx<Tx>): Promise<Returns<ExternalKeyPage>>;
+    get(keys: string[], ctx: ExternalCtx<Tx>): Promise<Returns<Record<string, Item | null>>>;
+};
+/**
+ * Write methods. Required together, and forbidden together on `.readonly()`.
+ *
+ * `put` must be an UPSERT keyed by the entry key and `delete` must tolerate an
+ * absent key, because a publish may be replayed: retry re-runs the whole scope
+ * where there is a transaction, and the individual call where there is not.
+ */
+type WriteMethods<Item, Tx> = {
+    put(entries: Record<string, Item>, ctx: ExternalCtx<Tx> & {
+        /**
+         * What `putFile` returned, keyed by the path it was given.
+         *
+         * Path rather than sha256 because the entry references its file by path
+         * and carries no hash — keying by hash would need a second map. The sha is
+         * a field, for an adapter doing content-addressed bookkeeping.
+         */
+        uploads: Record<string, {
+            sha256: string;
+            data?: Json;
+        }>;
+    }): Promise<Returns<void>>;
+    delete(keys: string[], ctx: ExternalCtx<Tx>): Promise<Returns<void>>;
+};
+/**
+ * Named so the compiler prints the reason. A bare `never` would report only
+ * "not assignable to type 'undefined'", which tells nobody anything.
+ */
+export type ReadonlyRecordHasNoWrites = {
+    readonly __val_error: "this record is .readonly(): remove put and delete, or remove .readonly() from the schema";
+};
+/** Derived and media methods, and the sort declaration. */
+type OptionalMethods<Item, Tx> = {
+    /**
+     * Three modes. A function delegates; `false` declines; omitted means Val
+     * counts by paging `keys` and summing, cached and bounded.
+     */
+    count?: false | ((ctx: ExternalCtx<Tx>) => Promise<Returns<number>>);
+    /**
+     * Three modes, as `count`. Omitted, Val answers from the entries it has
+     * already seen and labels the result partial — it does not fetch a whole store
+     * on the editor's behalf. `false` declines even that.
+     */
+    search?: false | ((query: {
+        text: string;
+        cursor: string | null;
+        limit: number;
+        sort?: ExternalSort;
+    }, ctx: ExternalCtx<Tx>) => Promise<Returns<ExternalSearchPage<Item>>>);
+    /**
+     * Which item paths this store can order by. `true` for any field. Absent
+     * means key order only — all any store can promise, and all a bucket can do.
+     */
+    sortable?: true | string[][];
+    /**
+     * The most keys this store will list per call, and the most one `get` may
+     * carry.
+     *
+     * Chunking hints for the fetcher, NOT ceilings the UI sees: if the Studio asks
+     * for 50 and the store lists 10 at a time, Val makes five calls and returns
+     * 50. Page size belongs to the Studio, which must not be able to tell how a
+     * record is stored.
+     */
+    maxPageSize?: number;
+    maxBatchSize?: number;
+    /**
+     * A token that changes when anything in this record changes — `max(updated_at)`,
+     * a sequence number, an ETag. Polled on the poll that already exists. Absent
+     * costs freshness, never function: Val re-reads on navigation.
+     */
+    version?(ctx: ExternalCtx<Tx>): Promise<Returns<string>>;
+    /** Stores bytes at the path Val chose. Paired with `getFile`. */
+    putFile?(file: ExternalFile, ctx: ExternalCtx<Tx>): Promise<Returns<{
+        data?: Json;
+    }>>;
+    /** Reads them back. If an adapter can store bytes it must return them. */
+    getFile?(path: string, ctx: ExternalCtx<Tx>): Promise<Returns<Uint8Array | null>>;
+};
+/** The item type an external module's entries hold, loosened as JSON allows. */
+export type ItemOfModule<M extends AnyExternalModule> = JsonOf<ExternalItemOf<InferValModuleType<M>>>;
+/**
+ * The adapter a given external module needs.
+ *
+ * Writes are required or forbidden by the module's own `.readonly()`, read off
+ * the source marker's phantom.
+ */
+export type AdapterFor<M extends AnyExternalModule, Tx> = ReadMethods<ItemOfModule<M>, Tx> & OptionalMethods<ItemOfModule<M>, Tx> & (ExternalReadonlyOf<InferValModuleType<M>> extends true ? {
+    put?: ReadonlyRecordHasNoWrites;
+    delete?: ReadonlyRecordHasNoWrites;
+} : WriteMethods<ItemOfModule<M>, Tx>);
+declare const BoundTag: unique symbol;
+/** What `entry()` returns: a module and its adapter, checked against each other. */
+export type BoundExternalRecord<M> = {
+    readonly [BoundTag]: M;
+};
+export type ExternalRecords = {
+    readonly __brand: "ExternalRecords";
+};
+export type ExternalBuilder<Tx> = {
+    /**
+     * Bind an adapter to a module.
+     *
+     * A call rather than an object literal on purpose: `module` is inferred from
+     * the first argument, so `AdapterFor` RESOLVES for the second and TypeScript
+     * records the declaration link between a schema field and the adapter that
+     * produces it. Inside a single object literal the module stays a deferred type
+     * parameter, the adapter type never resolves, and "find all references" on a
+     * schema field stops reaching the adapter.
+     */
+    entry<M extends AnyExternalModule>(module: M, adapter: AdapterFor<M, Tx>): BoundExternalRecord<M>;
+    /**
+     * Collect the bindings. The key must equal the schema's own `.external(label)`.
+     */
+    modules<E extends Record<string, BoundExternalRecord<AnyExternalModule>>>(entries: E & {
+        [K in keyof E]: E[K] extends BoundExternalRecord<infer M extends AnyExternalModule> ? ExternalLabelOf<InferValModuleType<M>> extends K ? E[K] : BoundExternalRecord<ValModule<ExternalRecordSrc<unknown, K & string>>> : never;
+    }): ExternalRecords;
+};
+export type ExternalDefinition<Tx> = {
+    /**
+     * One scope per request, so a 50-key batch is one transaction and one query
+     * rather than fifty. Composes with any `withTransaction(cb)` API.
+     *
+     * Optional: a store with no transaction seam — a bucket, a REST API — simply
+     * omits it, and `ctx` then has no `tx`.
+     *
+     * Retry scope follows from this. WITH `around`, Val re-enters the whole scope,
+     * because a database aborts a transaction on its first error and answers
+     * everything after it with "current transaction is aborted". WITHOUT it, Val
+     * repeats the single operation, which is both correct and far cheaper.
+     */
+    around?: <R>(run: (tx: Tx) => Promise<R>) => Promise<R>;
+    /**
+     * Retry policy. Return the delay in ms, or `false` to give up.
+     *
+     * A policy function, not a re-implementation of the loop. Defaults to three
+     * attempts with exponential backoff. `false` disables retries entirely.
+     */
+    retry?: false | {
+        attempts: number;
+        backoff?: (attempt: number) => number;
+    } | ((attempt: number, issue: ExternalIssue) => number | false);
+    /** Fired after a publish, so an app that caches can purge what changed. */
+    onPublished?: (event: {
+        label: string;
+        keys: string[];
+    }) => Promise<void> | void;
+    /**
+     * How far the derived `count` walk may page before answering "200,000+".
+     * Keys only — it never fetches entry content.
+     */
+    countPageLimit?: number;
+};
+/**
+ * Declare the adapters for this project's external records.
+ *
+ * `Tx` is given explicitly: `around` offers the compiler no inference site,
+ * since `run` is a callback you CALL rather than one whose signature you write.
+ * One type argument, in one place, and every inline adapter then gets `tx`,
+ * `cursor`, `limit` and the row shape correctly typed.
+ *
+ * @example
+ * const { entry, modules } = defineExternal<typeof sql>({
+ *   around: (run) => sql.begin(run),
+ * });
+ *
+ * export default modules({
+ *   posts: entry(postsVal, { keys, get, put, delete: del, search: false }),
+ * });
+ *
+ * @example a store with no transaction
+ * const { entry, modules } = defineExternal();
+ */
+export declare function defineExternal<Tx = never>(definition?: ExternalDefinition<Tx>): ExternalBuilder<Tx>;
+export {};

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

@@ -164,6 +164,19 @@ export declare function handleRemoteFileCheck(): Promise<FixHandlerResult>;
 export declare function handleUniqueFolderCheck(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleCheckAllFiles(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleJsonValuesExtractEntry(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * `external:upload` under `val validate --fix`: refuse, and say what to run.
+ *
+ * Every other fix in this registry rewrites something inside the repository —
+ * reversible, visible in a diff, wrong by at most one commit. This one would
+ * write entries into a live external store: not in a diff, not undone by
+ * `git revert`, and against production indistinguishable from an editor's
+ * publish. So a blanket `--fix` must never apply it.
+ *
+ * `fixableErrorMessage` rather than a plain error, because the error IS fixable
+ * — just not by this command.
+ */
+export declare function handleExternalUpload(): Promise<FixHandlerResult>;
 export declare const currentFixHandlers: Record<Exclude<ValidationFix, "keyof:check-keys" | "router:check-route">, FixHandler>;
 export declare const fixHandlers: Record<string, FixHandler>;
 export declare function createDefaultValFSHost(): IValFSHost;

package/dist/declarations/src/history/HistoryError.d.ts

@@ -0,0 +1,90 @@
+import type { ModuleFilePath } from "@valbuild/core";
+/**
+ * Everything that can go wrong reading, replaying or restoring history.
+ *
+ * There is a lot of it, which is the point of making it one closed union rather
+ * than strings: reading a commit means reaching a content host, finding the
+ * commit, reading what was recorded for each of its modules, and asking whether
+ * this version of Val can make sense of the schema it was stored under. Each of
+ * those fails differently, and a caller deciding what to SHOW needs to know
+ * which.
+ *
+ * Every member has a producer. The union once carried five more - a module
+ * removed from the project, an op that would not replay, a value that no longer
+ * fits today's schema, a field the schema no longer defines, and ops from a
+ * core version known to replay wrongly. All five belonged to reconstructing a
+ * commit by replaying patches against a parsed source; storing the data ended
+ * that, and a member nothing can produce is a state the Studio writes handling
+ * for and never sees.
+ *
+ * ## The rule
+ *
+ * Whole-commit failures are the `err` channel. Per-module and per-patch
+ * failures ride along inside the `ok` payload.
+ *
+ * A commit that cannot be found or read at all has nothing to show. But one
+ * unparseable module out of ten does not make the other nine unreadable, and
+ * collapsing the whole view because of it would hide exactly the information
+ * someone needs to see - that this module is the broken one.
+ */
+export type HistoryError = 
+/** No such commit, or not one Val created. Nothing will make it readable. */
+{
+    kind: "commit-not-found";
+    commitSha: string;
+}
+/**
+ * The commit says it has an archive and the archive is missing or malformed.
+ * Distinct from a commit that predates archiving, which is not an error.
+ */
+ | {
+    kind: "archive-unreadable";
+    commitSha: string;
+    message: string;
+}
+/**
+ * Nothing was stored for this module at this commit - a commit made before
+ * history was recorded, or by a Val too old to send it. NOT the same as an
+ * empty module, which is why it is reported rather than defaulted.
+ */
+ | {
+    kind: "source-unavailable";
+    moduleFilePath: ModuleFilePath;
+}
+/**
+ * The schema stored with this commit is not one this version of Val can read.
+ *
+ * Expected, and NOT anyone's mistake: schemas are stored as written, and Val's
+ * schema format is allowed to move. An older project opened in a newer Val -
+ * or the reverse - can hit this, and the honest thing is to say the commit
+ * cannot be shown HERE rather than to imply the data is damaged. Everything
+ * else about the commit still reads.
+ */
+ | {
+    kind: "schema-unreadable";
+    moduleFilePath: ModuleFilePath;
+    message: string;
+}
+/** A binary file or `*.val.json` entry could not be read at that commit. */
+ | {
+    kind: "file-unavailable";
+    gitPath: string;
+    message: string;
+}
+/** History needs the content host; local FS mode has git instead. */
+ | {
+    kind: "not-supported-in-fs-mode";
+}
+/** Could not reach the content host at all. */
+ | {
+    kind: "transport";
+    message: string;
+};
+export declare function historyErrorMessage(error: HistoryError): string;
+/**
+ * Whether an error is about the whole commit rather than one part of it.
+ *
+ * The `err`/`ok`-payload split above, as a predicate, so callers do not
+ * re-derive it and disagree.
+ */
+export declare function isWholeCommitError(error: HistoryError): boolean;

package/dist/declarations/src/history/types.d.ts

@@ -0,0 +1,126 @@
+import type { JSONValue } from "@valbuild/core/patch";
+import type { ModuleFilePath, PatchId, SerializedSchema, SourcePath } from "@valbuild/core";
+import type { HistoryError } from "./HistoryError.js";
+/** One commit, as history lists it. */
+export type HistoricalCommit = {
+    commitSha: string;
+    parentCommitSha: string;
+    clientCommitSha: string;
+    branch: string;
+    createdBranch: string | null;
+    creator: string | null;
+    message: string | null;
+    createdAt: string;
+    seqNum: string;
+    patchCount: number;
+    /**
+     * Whether this commit's record was stored. False for commits made before
+     * history was recorded: their patches are still readable, but not the
+     * pre-commit sources a restore replays against.
+     */
+    hasArchive: boolean;
+};
+export type CommitPage = {
+    commits: HistoricalCommit[];
+    /** Pass as `cursor` for the next page. `null` when there are no more. */
+    nextCursor: string | null;
+};
+export type CommitPatch = {
+    patchId: PatchId;
+    moduleFilePath: ModuleFilePath;
+    patch: unknown;
+    authorId: string | null;
+    createdAt: string;
+    baseSha: string;
+    coreVersion: string;
+};
+export type FileChange = "added" | "modified" | "deleted";
+export type AffectedFile = {
+    kind: "module-source" | "json-entry" | "binary";
+    gitPath: string;
+    change: FileChange;
+} | {
+    kind: "remote-binary";
+    ref: string;
+    change: FileChange;
+};
+/**
+ * A binary file this commit touched - named, not fetched.
+ *
+ * `url` is where the bytes are IF something needs them. Nothing downloads a
+ * commit's images to show that the commit changed them; the descriptor is
+ * enough to render a row, and only an `<img src>` that actually mounts pays.
+ */
+export type BinaryFileRef = {
+    gitPath: string;
+    change: FileChange;
+    remote: boolean;
+    url: string;
+};
+/**
+ * A module as one commit left it.
+ *
+ * Both halves are stored rather than derived. `source` is the module's data,
+ * recorded at the commit - not recovered by parsing the `.val.ts` git holds,
+ * because that is code and parsing code is best-effort and rots. `schema` is
+ * the schema the data was written against, which nothing in the current
+ * checkout has once the schema has moved on, and without which the module
+ * cannot be RENDERED as it was - only guessed at.
+ */
+export type HistoricalModule = {
+    /** The module's data at this commit. `null` if deleted, or unreadable — see `failures`. */
+    source: JSONValue | null;
+    /**
+     * The schema at this commit, if this version of Val can read it.
+     *
+     * `null` with a `schema-unreadable` failure means the stored schema is from a
+     * Val whose schema format this one does not know. Expected rather than
+     * broken, and reported so the Studio can say so kindly.
+     */
+    schema: SerializedSchema | null;
+    patchIds: PatchId[];
+    /**
+     * What this commit changed here, taken from the ops themselves.
+     *
+     * The ops ARE the change, so this needs no before-state and no replay - which
+     * is what let the static parser and the patch replay go.
+     */
+    changedPaths: SourcePath[];
+    /** Per-module problems. Collected, never thrown - see HistoryError. */
+    failures: HistoryError[];
+};
+/**
+ * A commit, reconstructed.
+ *
+ * Deliberately says nothing about the CURRENT source or schema, so it can never
+ * change for a given commit sha - which is what lets it be cached forever. The
+ * comparison against today lives in `HistoricalComparison`.
+ */
+export type HistoricalPatchSet = {
+    commit: HistoricalCommit;
+    modules: Record<ModuleFilePath, HistoricalModule>;
+    patches: CommitPatch[];
+    /** `*.val.json` entry contents at this commit, keyed by git path. */
+    jsonEntries: Record<string, JSONValue>;
+    binaryFiles: BinaryFileRef[];
+    /** Problems that are about the commit but did not stop it being read. */
+    warnings: HistoryError[];
+};
+/**
+ * One module's stored version, exactly as the content service returns it.
+ *
+ * `schema` is `unknown` on purpose: the content service stores it opaquely and
+ * cannot vouch for it, so it arrives unvalidated and is checked HERE, where the
+ * schema format is actually known. That check is what turns "a project written
+ * by a different Val" into a sentence rather than a crash.
+ */
+export type StoredModuleVersion = {
+    moduleFilePath: ModuleFilePath;
+    commitSha: string;
+    sourceSha: string | null;
+    schemaSha: string;
+    source: JSONValue | null;
+    schema: unknown;
+    /** We hold the hash but not the object. Distinct from a deleted module. */
+    unavailable: boolean;
+};

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

@@ -1,4 +1,6 @@
 export { createService, Service } from "./Service.js";
+export { defineExternal, ok, err, isExternalResult, EXTERNAL_RESULT, } from "./externalRecords.js";
+export type { AdapterFor, BoundExternalRecord, ExternalAuthor, ExternalBuilder, ExternalCtx, ExternalDefinition, ExternalFile, ExternalIssue, ExternalKeyPage, ExternalRecords, ExternalResult, ExternalSearchHit, ExternalSearchPage, ExternalSort, ItemOfModule, ReadonlyRecordHasNoWrites, Returns, } from "./externalRecords.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
 export { createValTools } from "./tools/index.js";
 export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./tools/index.js";
@@ -15,7 +17,7 @@ export { formatSyntaxErrorTree } from "./patch/ts/syntax.js";
 export { analyzeValModule } from "./patch/ts/valModule.js";
 export type { ValModuleAnalysis } from "./patch/ts/valModule.js";
 export { createFixPatch } from "./createFixPatch.js";
-export { fixHandlers, currentFixHandlers, createDefaultValFSHost, handleFileMetadata, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleRemoteFileDownload, handleRemoteFileCheck, handleUniqueFolderCheck, handleCheckAllFiles, handleJsonValuesExtractEntry, } from "./fixHandlers.js";
+export { fixHandlers, currentFixHandlers, createDefaultValFSHost, handleFileMetadata, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleRemoteFileDownload, handleRemoteFileCheck, handleUniqueFolderCheck, handleCheckAllFiles, handleJsonValuesExtractEntry, handleExternalUpload, } from "./fixHandlers.js";
 export type { FixHandler, FixHandlerContext, FixHandlerResult, IValRemote, ValidationEvent, ValidationError, ValModule, } from "./fixHandlers.js";
 export * from "./jwt.js";
 export type { ValServer } from "./ValServer.js";