@valbuild/server 0.129.0 → 0.131.0

package/CHANGELOG.md

@@ -1,5 +1,172 @@
 # @valbuild/server
 
+## 0.131.0
+
+### Minor Changes
+
+- [#686](https://github.com/valbuild/val/pull/686) [`0d5857b`](https://github.com/valbuild/val/commit/0d5857b731e11f7e6a011f79297df6485908c31f) Thanks [@freekh](https://github.com/freekh)! - Say `VAL_MODE=memory` where there is no disk, and get a sentence instead of an `EPERM`
+
+  Memory mode — the one for a host that holds the project's source itself — is
+  selected by passing `sourceFiles`, and it has to be: nothing in an environment
+  can supply a project's source, so a mode that an env var could switch on would
+  be a server with no content in it.
+
+  The cost was the failure when a host forgot. Val inferred `fs` mode, `fs` mode
+  went looking for a working tree, and in a Worker isolate the first thing to
+  touch the disk failed:
+
+  ```
+  patch-error /bundle/.val/patches.lock: EPERM
+  ```
+
+  That names a path two layers below the decision that caused it, and nobody
+  reading it would guess "your server was configured for the wrong mode".
+
+  So an environment can now DECLARE that it has no disk:
+
+  ```
+  VAL_MODE=memory
+  ```
+
+  It does not turn memory mode on. It says the host is supposed to be supplying
+  `sourceFiles`, so if none arrive, Val refuses at configuration time and says
+  where to pass them. `VAL_MODE=` counts as unset, the way a shell means it; any
+  other value is refused rather than ignored, since leaving you in `fs` mode is
+  the exact failure this is meant to catch.
+
+  **`initValContent` takes the same options, and this is the release that
+  noticed.** It builds a Val server of its own — these readers resolve content by
+  asking it, not by calling the API over HTTP — so configuring `initValServer`
+  alone left them inferring `fs` mode. On a host with no filesystem that is a
+  reader looking for a working tree that is not there; it went unnoticed because
+  published reads still worked.
+
+  ```ts
+  const patchStore = new InMemoryPatchStore(); // now exported from this package
+
+  const { valApiHandler, draftMode } = initValServer(valModules, config, {
+    sourceFiles: FILES,
+    patchStore,
+    unsafelyAllowUnauthenticated: true,
+  });
+
+  const { fetchValStega } = initValContent(config, valModules, {
+    draftMode,
+    // The same three. Two patch stores are two sets of pending edits, and a
+    // reader that checks a session the host never issues answers itself 401 and
+    // falls back to published content — a draft render showing the live site.
+    sourceFiles: FILES,
+    patchStore,
+    unsafelyAllowUnauthenticated: true,
+  });
+  ```
+
+  All three are optional. Left out, this reader gets its own store and its own
+  answer about authentication, which is right for published content.
+
+  `@valbuild/next` has no memory mode: its `initValServer` takes neither option,
+  so for a Next app `VAL_MODE=memory` names an environment Val cannot serve from,
+  and the error says so.
+
+  Nothing changes for an app that sets none of this: `http` when `VAL_API_KEY`
+  and `VAL_SECRET` are both present, `fs` otherwise, as before.
+
+## 0.130.0
+
+### Minor Changes
+
+- [#684](https://github.com/valbuild/val/pull/684) [`cab4098`](https://github.com/valbuild/val/commit/cab4098969585977b8d7574e86d66fcb01cb1d75) Thanks [@freekh](https://github.com/freekh)! - A third ValOps mode, for a host that already holds its own source
+
+  EXPERIMENTAL. `fs` mode assumes a working tree it can watch and write; `http`
+  mode assumes Val's content service owns the patch chain and that a commit is a
+  git commit. A host that builds and publishes its own output is neither: it holds
+  the source already, it has nowhere to watch, and its "commit" is a new build.
+
+  Forcing such a host into `fs` mode cost three things, all now fixed: `/stat`
+  long-polled against watchers that could never fire, burning CPU for the whole
+  hold to learn nothing;
+  `/api/val/enable` 500'd; and every read of a `.val.ts` went through a shimmed
+  filesystem when the host could simply hand the source over.
+
+  `ValOpsMemory` takes the source as `sourceFiles`, refuses the local binary
+  members by name — this configuration uses Val's remote files — and answers the
+  history members with the same closed `not-supported-in-fs-mode` error `ValOpsFS`
+  gives, so the History UI degrades the way it already knows how rather than
+  inventing a commit list.
+
+  `getStat` still long-polls -- the hold is what paces the client, and an earlier
+  version that answered immediately turned a 20-second poll into a request every
+  6ms -- but it parks on a SIGNAL rather than a timer. This mode owns its store,
+  so it is told when something changes: no timers while parked, and a patch
+  written by another tab is seen at once rather than up to 250ms later.
+
+  Two seams come with it. `commitPrepared` lets a host take what a save produced
+  instead of a git commit, and `publishOverride` lets a publish be something other
+  than a push. Both are opt-in; an app that sets neither behaves exactly as before.
+
+  The in-memory patch store is explicitly **not durable**. It is behind
+  `ValPatchStore`, so a durable implementation is a swap rather than a rewrite,
+  but as shipped a restart loses unpublished patches.
+
+  **Memory mode authenticates.** `ValOps` gained `requiresAuth` alongside
+  `patchesAreLocal`, because one flag was answering two questions: whether a store
+  auto-saves or publishes (behaviour, reported as `mode` and keyed off by the UI),
+  and whether an unauthenticated request may write (security). With two
+  implementations the answers coincided — `fs` is a developer's own machine where
+  no credential exists, `http` is remote — so `getAuth` was written against
+  `patchesAreLocal` and returned anonymous _success_ for a missing cookie, an
+  invalid JWT, an unparseable payload, or no configured secret.
+
+  Memory mode splits them: its store is local, and it runs deployed. It therefore
+  requires a verified session, like `http` mode. A host that authorises requests
+  before Val sees them can opt out with `unsafelyAllowUnauthenticated`, which is
+  spelled that way on purpose and warns at startup. `fs` mode is unchanged.
+
+  Val's own MCP endpoint refuses memory mode outright. It has the same absence fs
+  mode has — no credential, no backend, every permission check on the far side of
+  one — and unlike fs mode it is meant to run deployed, so the existing
+  "development only" and loopback guards refuse nothing. A host in this mode owns
+  its own trust boundary and can offer the tools through it.
+
+  Internally, the routes' `instanceof ValOpsFS` checks meant "is this a local
+  store" — correct with two implementations and silently wrong with three. They are
+  now `ValOps.patchesAreLocal` at all 17 policy sites.
+
+### Patch Changes
+
+- [#684](https://github.com/valbuild/val/pull/684) [`cab4098`](https://github.com/valbuild/val/commit/cab4098969585977b8d7574e86d66fcb01cb1d75) Thanks [@freekh](https://github.com/freekh)! - Stop telling people to run `val login` where a personal access token cannot be used
+
+  A PAT is read from a file in the _server's_ working directory, and only local
+  `fs` mode has one. `resolveRemoteFileAuth` knew that; two things upstream did not.
+
+  `RemoteFilesErrorDialog` was unconditional. Whatever went wrong with remote files,
+  it said "Personal access token file required" and told the reader to run a command
+  in their project root — for a server with no working directory, a directory that
+  does not exist, to produce a file it could not read. The reason was already on the
+  error object and simply never looked at. The dialog now shows only for the two
+  reasons a PAT can actually fix, and everything else gets its own message.
+
+  `resolveRemoteFileAuth` also answered `project-not-configured` for a non-fs mode
+  with no api key, which is wrong twice: the project may be configured perfectly
+  well, and it is the credential that is absent. It answers `api-key-missing` now,
+  already in the wire contract, and that message no longer says "production mode",
+  because every server that is not local dev gives it.
+
+- [#684](https://github.com/valbuild/val/pull/684) [`cab4098`](https://github.com/valbuild/val/commit/cab4098969585977b8d7574e86d66fcb01cb1d75) Thanks [@freekh](https://github.com/freekh)! - `createValApiRouter` no longer puts `fs` in every integration's module graph
+
+  `fs` and `path` were imported at module scope for `safeReadGit`, a local
+  development convenience that scans upwards for a `.git` to guess the commit and
+  branch, and whose only caller is the CLI. A static import put `fs` in the module
+  graph of everything reaching `createValApiRouter` — which is every server
+  integration, including ones that run where there is no filesystem at all.
+
+  Behaviour is unchanged where there is a filesystem.
+
+- Updated dependencies [[`be1e8be`](https://github.com/valbuild/val/commit/be1e8bee673207596b3eb3d9a9886b8ade9b332f), [`8425378`](https://github.com/valbuild/val/commit/8425378c315ea46b5d822f1130b633e0449ff1b0), [`7d13dbc`](https://github.com/valbuild/val/commit/7d13dbced9ea49d8243b6b6cf9854cd1a259501f), [`cab4098`](https://github.com/valbuild/val/commit/cab4098969585977b8d7574e86d66fcb01cb1d75), [`07db94c`](https://github.com/valbuild/val/commit/07db94c23b73c8c0b2b50a30a89926823c2da1d6), [`473a185`](https://github.com/valbuild/val/commit/473a185f70351b44388f3bc1852649e2c1dbe001), [`64f0de3`](https://github.com/valbuild/val/commit/64f0de339b8621cb5a6c422dfe55cae5b2bbe2a0)]:
+  - @valbuild/ui@0.130.0
+  - @valbuild/core@0.130.0
+  - @valbuild/shared@0.130.0
+
 ## 0.129.0
 
 ### Patch Changes

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

@@ -162,7 +162,7 @@ export declare abstract class ValOps {
      * put content in the memo that is not what was written, which is worse than
      * being stale.
      */
-    adoptCommittedSources(analysis: PatchAnalysis & OrderedPatches, preparedCommit: Pick<PreparedCommit, "patchedJsonEntries">): Promise<void>;
+    adoptCommittedSources(analysis: PatchAnalysis & OrderedPatches, preparedCommit: Pick<PreparedCommit, "patchedJsonEntries" | "patchedSourceFiles">): Promise<void>;
     /**
      * Adopt sources that have just been written to disk, and move the SHAs with
      * them.
@@ -401,6 +401,55 @@ export declare abstract class ValOps {
     } | {
         errorType: "patch-head-conflict";
     }>>;
+    /**
+     * Take the `.val.ts` text a commit produced as the new committed source.
+     *
+     * A no-op where {@link getSourceFile} reads something the commit already
+     * wrote — the disk in `fs` mode, the content service in `http` mode. Override
+     * it in a store that holds the source itself. `null` means the commit deleted
+     * the file.
+     */
+    protected adoptPatchedSourceFiles(_files: Record<string, string | null>): void;
+    /**
+     * Whether the patches live HERE, in this server, or in Val's content service.
+     *
+     * Almost everything the routes branch on comes from this one fact, which is
+     * why it is a named property rather than an `instanceof`. If this server owns
+     * the store then there is no content service to authenticate to (so an absent
+     * or unverifiable session is anonymous rather than a 401), no shared store for
+     * a patch group to separate authors in, no deployments to report, and a
+     * "publish" writes what the host does with it rather than pushing a commit. If
+     * it does not, every one of those is the content service's and this server is
+     * relaying.
+     *
+     * There were two implementations when the routes were written and `instanceof
+     * ValOpsFS` meant this; a third made that reading wrong in a way that compiles
+     * silently -- a store that is local, answers none of the checks, and gets the
+     * http path with no content service behind it.
+     *
+     * It is also what `/stat` reports as `mode`. The wire name predates the third
+     * implementation and names a class, but the question the client is asking is
+     * this one: does it auto-save and hide the account panel, or does it publish.
+     */
+    abstract readonly patchesAreLocal: boolean;
+    /**
+     * Whether a request must carry a session this server verified.
+     *
+     * Split out of {@link patchesAreLocal}, which was answering two questions at
+     * once. "Does this store auto-save or publish" is a BEHAVIOUR question, and
+     * it is what `/stat` reports and the UI keys off. "May an unauthenticated
+     * request write here" is a SECURITY question. With two implementations the
+     * answers coincided -- fs is local dev where no credential exists, http is
+     * remote -- so one flag served both and nothing noticed.
+     *
+     * A third implementation splits them. `ValOpsMemory`'s store is local, which
+     * makes the first answer yes, and it is designed to run DEPLOYED, which makes
+     * the second answer no. Reusing one flag gave a deployed host `getAuth`
+     * returning anonymous success for a missing cookie, an invalid JWT, an
+     * unparseable payload, or no configured secret -- on all 29 routes, including
+     * the ones that create patches and publish.
+     */
+    abstract readonly requiresAuth: boolean;
     abstract onInit(baseSha: BaseSha, schemaSha: SchemaSha): Promise<void>;
     abstract fetchPatches<ExcludePatchOps extends boolean>(filters: {
         patchIds?: PatchId[];

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

@@ -10,6 +10,13 @@ export declare class ValOpsFS extends ValOps {
     private readonly rootDir;
     private static readonly VAL_DIR;
     private readonly host;
+    /** The developer's own working tree. See {@link ValOps.patchesAreLocal}. */
+    readonly patchesAreLocal = true;
+    /**
+     * The developer's own machine, where there is no credential to require and
+     * nothing to protect it from. See {@link ValOps.requiresAuth}.
+     */
+    readonly requiresAuth = false;
     constructor(contentUrl: string, rootDir: string, valModules: ValModules, options?: ValOpsOptions);
     /**
      * Change detection for `.jsonValues()` entry files, which no sha can see (their

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

@@ -27,6 +27,10 @@ export declare class ValOpsHttp extends ValOps {
     private readonly branch;
     private readonly authHeaders;
     private readonly root;
+    /** Val's content service owns the store. See {@link ValOps.patchesAreLocal}. */
+    readonly patchesAreLocal = false;
+    /** See {@link ValOps.requiresAuth}. */
+    readonly requiresAuth = true;
     constructor(contentUrl: string, project: string, commitSha: string, // TODO: CommitSha
     branch: string, 
     /**

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

@@ -0,0 +1,306 @@
+import type { ModuleFilePath, PatchId, ValModules } from "@valbuild/core";
+import type { Patch, ParentRef } from "@valbuild/shared/internal";
+import { ValOps, type AuthorId, type BaseSha, type GenericErrorMessage, type MetadataOfType, type OpsMetadata, type OrderedPatches, type OrderedPatchesMetadata, type PatchGroupMembership, type PreparedCommit, type SaveSourceFilePatchResult, type SchemaSha, type SourcesSha, type ValOpsOptions, type WithGenericError } from "./ValOps.js";
+import type { HistoryError } from "./history/HistoryError.js";
+import type { AffectedFile, CommitPage, CommitPatch, HistoricalCommit, StoredModuleVersion } from "./history/types.js";
+import { result } from "@valbuild/core/fp";
+/**
+ * One stored patch. Everything the ordered chain needs and nothing else.
+ */
+export type StoredPatch = {
+    patchId: PatchId;
+    path: ModuleFilePath;
+    patch: Patch;
+    authorId: AuthorId | null;
+    createdAt: string;
+    baseSha: BaseSha;
+};
+/**
+ * One pending binary file: an upload that has not been published yet.
+ *
+ * Keyed by the patch that carries it, exactly as `fs` mode keys the directory
+ * it writes to. The patch's own `file` op holds a hash, not the bytes, so these
+ * arrive on their own request and are joined up by `(patchId, filePath)`.
+ */
+export type StoredFile = {
+    patchId: PatchId;
+    /**
+     * Where the file will live once published.
+     *
+     * For a LOCAL file that is `/public/val/photo.jpg`. For a REMOTE one it is
+     * the path INSIDE the ref, not the ref itself -- `splitRemoteRef` has already
+     * taken it apart by the time the bytes get here, and both readers are keyed
+     * the same way. This is why neither takes `remote` into account: the caller
+     * has resolved that before it asks.
+     */
+    filePath: string;
+    data: Buffer;
+    metadata: MetadataOfType<"file" | "image"> | undefined;
+};
+/**
+ * Where pending patches live.
+ *
+ * The point of the interface: `ValOpsMemory` is not tied to memory. The default
+ * implementation below is explicitly NOT durable -- it dies with the process,
+ * or in a Worker with the isolate -- and a durable one (a Durable Object, whose
+ * single-threaded execution is the lock Val's fs store builds out of a file)
+ * is a swap rather than a rewrite.
+ *
+ * ORDER IS THE CONTRACT. `list()` returns patch ids in the order they were
+ * written, and that order is the chain: entry i's parent is entry i-1. This is
+ * the same decision `ValOpsFS` makes with `patches.log` -- the server decides
+ * where a patch goes, and it goes last -- and it exists for the same reason: an
+ * order held in the patches themselves lets a client working from a stale view
+ * strand every patch behind a parent that never landed.
+ */
+export interface ValPatchStore {
+    list(): Promise<PatchId[]>;
+    get(patchId: PatchId): Promise<StoredPatch | null>;
+    append(patch: StoredPatch): Promise<void>;
+    /** The patches AND every file they carry. */
+    delete(patchIds: PatchId[]): Promise<void>;
+    /**
+     * Hold an uploaded file until its patch is published or dropped.
+     *
+     * Uploads arrive BEFORE the patch record does -- the record's `file` op
+     * carries only a hash, so it would otherwise point at nothing. So a file for
+     * a patch id that does not exist yet is normal and must be accepted. `fs`
+     * mode stages these outside its store and moves them in when the record
+     * lands, because a directory of files with no `patch.json` is indistinguishable
+     * from a patch whose contents were lost, and its repair pass deletes those.
+     * Nothing sweeps this store, so the two-step is not needed here -- at the cost
+     * that bytes uploaded for a patch that is never recorded stay until the store
+     * is dropped.
+     */
+    putFile(file: StoredFile): Promise<void>;
+    getFile(patchId: PatchId, filePath: string): Promise<StoredFile | null>;
+    deleteFile(patchId: PatchId, filePath: string): Promise<void>;
+    /** Every file held for a patch, which is what the publish step uploads. */
+    filesOf(patchId: PatchId): Promise<StoredFile[]>;
+}
+/** The default store. Not durable, deliberately and visibly. */
+export declare class InMemoryPatchStore implements ValPatchStore {
+    private readonly order;
+    private readonly byId;
+    list(): Promise<PatchId[]>;
+    get(patchId: PatchId): Promise<StoredPatch | null>;
+    append(patch: StoredPatch): Promise<void>;
+    delete(patchIds: PatchId[]): Promise<void>;
+    private static fileKey;
+    private readonly files;
+    putFile(file: StoredFile): Promise<void>;
+    getFile(patchId: PatchId, filePath: string): Promise<StoredFile | null>;
+    deleteFile(patchId: PatchId, filePath: string): Promise<void>;
+    filesOf(patchId: PatchId): Promise<StoredFile[]>;
+}
+export type ValOpsMemoryOptions = ValOpsOptions & {
+    /**
+     * The project's source, by path, as the host already holds it.
+     *
+     * This is why the mode exists. `fs` mode reads `.val.ts` off a disk, and a
+     * host that builds and publishes does not have one -- giving it a shimmed
+     * filesystem to read through is what produced `Cannot access 'fs' before
+     * initialization` and a `/stat` that long-polls watchers which cannot fire.
+     * Here the host simply hands the source over.
+     */
+    sourceFiles: Record<string, string>;
+    /** Where pending patches live. Defaults to memory; see ValPatchStore. */
+    patchStore?: ValPatchStore;
+    /**
+     * Serve without authenticating any request. Off by default.
+     *
+     * The name is the documentation. This mode runs deployed, so an
+     * unauthenticated server is one where anyone who can reach the port can
+     * create patches and drive a publish -- which is why the default is to
+     * require a verified session like `http` mode does.
+     *
+     * A host sets this when it has its OWN boundary in front of Val and is
+     * asserting that every request reaching here has already been authorised by
+     * it. That is a real configuration, and it is not one to arrive at by
+     * accident, so it is spelled out rather than inferred and it warns at
+     * startup.
+     */
+    unsafelyAllowUnauthenticated?: boolean;
+    /**
+     * Val's content host, for pushing remote files at publish.
+     *
+     * Only needed by {@link ValOpsMemory.uploadRemoteFiles}. A project with no
+     * `s.image()` never reaches it.
+     */
+    contentUrl?: string;
+};
+/**
+ * A `ValOps` for a host that is neither a developer's machine nor
+ * content.val.build.
+ *
+ * EXPERIMENTAL -- see VAL_PROMPT.md.
+ *
+ * `fs` mode assumes a working tree it can watch and write; `http` mode assumes
+ * the content API owns the patch chain and a commit means a git commit. A host
+ * that builds and publishes its own output is neither: it holds the source
+ * already, it has nowhere to watch, and its "commit" is a new build.
+ *
+ * What this deliberately does NOT do:
+ *
+ * - **No filesystem.** Source comes from `sourceFiles`, patches from a store.
+ * - **No watching.** `getStat` still long-polls -- the hold is what paces the
+ *   client -- but it parks on a signal rather than racing a timer against an
+ *   mtime poll that can never observe anything here. Nothing can edit files
+ *   behind Val's back: source changes only when the host publishes, and that
+ *   replaces the process.
+ * - **Pending binary files, but no PUBLISHED local ones.** An upload is held in
+ *   the patch store like any other pending change, so the Studio can preview it
+ *   before it is published. What this has no answer for is a file that is
+ *   already published and served from a `/public` directory: this configuration
+ *   uses Val's REMOTE files, where a published image lives on the content host
+ *   and the source carries a URL. `getBinaryFile` answers `null` for those --
+ *   a miss, not a fault -- and `getBinaryFileMetadata` refuses by name.
+ * - **No git history.** There is no repository here, so the history methods
+ *   answer `not-supported-in-fs-mode` -- the same closed error `ValOpsFS`
+ *   uses, so the History UI degrades the way it already knows how rather than
+ *   inventing a commit list. See the note above `listCommits`.
+ */
+export declare class ValOpsMemory extends ValOps {
+    /**
+     * The host's own store -- see {@link ValOps.patchesAreLocal}. `true` for the
+     * same reason `fs` mode is: nothing is relayed to a content service, so
+     * there is no session to verify against one and no group to separate authors
+     * in. Where the two differ is not something a route asks about.
+     */
+    readonly patchesAreLocal = true;
+    /**
+     * Required, unless the host explicitly takes the boundary itself.
+     *
+     * `patchesAreLocal` is true here and that is about publishing, not about who
+     * may write -- see {@link ValOps.requiresAuth}.
+     */
+    readonly requiresAuth: boolean;
+    private readonly store;
+    /**
+     * The project's source, keyed WITHOUT a leading slash.
+     *
+     * Two spellings reach this. A host keys by project-relative path
+     * (`src/routes/page.val.ts`) because that is what it built from; Val asks and
+     * commits with a leading slash (`/src/routes/page.val.ts`). Normalised on the
+     * way in so there is one entry per file — holding both spellings would let a
+     * commit update one and leave the other as the stale answer.
+     *
+     * Not `readonly`: a save replaces the files it rewrote. See
+     * {@link adoptPatchedSourceFiles}.
+     */
+    private sourceFiles;
+    private readonly contentUrl;
+    constructor(valModules: ValModules, options: ValOpsMemoryOptions);
+    onInit(): Promise<void>;
+    /**
+     * Requests parked in {@link getStat}, waiting for something to happen.
+     *
+     * See there for why this exists. Resolved and emptied by
+     * {@link announceChange}; never rejected, because a waiter that gives up does
+     * so on its own timeout.
+     */
+    private statWaiters;
+    /**
+     * Writes so far. Sampled before reading, compared after registering.
+     *
+     * The registration is not atomic with the read above it: a patch written
+     * between `currentStat()` and `statWaiters.push` was announced to a list this
+     * waiter was not yet on, so the request slept the full interval with a change
+     * already sitting there. Comparing the count closes that window without a
+     * lock.
+     */
+    private changeCount;
+    /** Wake every parked `getStat`. Called by this instance's own writes. */
+    private announceChange;
+    private currentStat;
+    getStat(params: {
+        baseSha: BaseSha;
+        schemaSha: SchemaSha;
+        patches?: PatchId[];
+    } | null): Promise<{
+        type: "request-again" | "no-change" | "did-change";
+        baseSha: BaseSha;
+        schemaSha: SchemaSha;
+        sourcesSha: SourcesSha;
+        patches: PatchId[];
+    }>;
+    /** Resolves on the next write here, or when the poll interval runs out. */
+    private parkUntilChange;
+    fetchPatches<ExcludePatchOps extends boolean>(filters: {
+        patchIds?: PatchId[];
+        excludePatchOps: ExcludePatchOps;
+    }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
+    protected saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, _parentRef: ParentRef | null, authorId: AuthorId | null, _sessionId: string | null, _patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
+    /** One spelling for a path, whichever the caller used. See sourceFiles. */
+    private static key;
+    /**
+     * A save has rewritten these files; they are the committed source now.
+     *
+     * Without this every save after the first re-reads the source as it was when
+     * this object was built, applies only its own patches to that, and parks a
+     * file that reverts everything saved before it -- with no error, because
+     * applying the patch to the ORIGINAL text succeeds. The Studio auto-saves, so
+     * that is not an edge case: it is most of a session's work.
+     *
+     * `fs` mode gets this for free -- `saveOrUploadFiles` writes the disk that
+     * `getSourceFile` reads. There is no disk here, so it is written down.
+     */
+    protected adoptPatchedSourceFiles(files: Record<string, string | null>): void;
+    protected getSourceFile(path: string): Promise<WithGenericError<{
+        data: string;
+    }>>;
+    deletePatches(patchIds: PatchId[]): Promise<{
+        deleted: PatchId[];
+        errors?: undefined;
+        error?: undefined;
+    }>;
+    /**
+     * Push this commit's pending binary files to Val's content host.
+     *
+     * The half of publishing that `commitPrepared` cannot do. Val's remote files
+     * upload at PUBLISH, not when the image is added: until then the bytes are a
+     * pending change like any other, held by {@link ValPatchStore}. So a publish
+     * has to walk the descriptors and push each one before the source that
+     * references it goes live -- otherwise the new build ships a URL that 404s.
+     *
+     * `ValOpsFS.saveOrUploadFiles` does the same loop, alongside two things this
+     * has no use for: copying LOCAL binaries into a working tree, and writing the
+     * source files (which is `commitPrepared` here). Kept separate rather than
+     * shared, because the shapes only look alike.
+     *
+     * Errors are collected rather than thrown. One image that will not upload
+     * should name itself and leave the rest of the publish decidable, rather than
+     * failing a save that has already applied its patches.
+     */
+    uploadRemoteFiles(preparedCommit: Pick<PreparedCommit, "patchedBinaryFilesDescriptors">, auth: {
+        apiKey: string;
+    } | {
+        pat: string;
+    }): Promise<{
+        uploaded: string[];
+        errors: Record<string, GenericErrorMessage>;
+    }>;
+    private remoteOnly;
+    saveBase64EncodedBinaryFileFromPatch(filePath: string, _parentRef: ParentRef, patchId: PatchId, data: string | null, _type: "file" | "image", metadata: MetadataOfType<"file" | "image"> | undefined): Promise<WithGenericError<{
+        patchId: PatchId;
+        filePath: string;
+    }>>;
+    getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, _remote?: boolean): Promise<Buffer | null>;
+    protected getBase64EncodedBinaryFileMetadataFromPatch<T extends "file" | "image">(filePath: string, type: T, patchId: PatchId, _remote?: boolean): Promise<OpsMetadata<T>>;
+    getBinaryFile(_filePathOrRef: string): Promise<Buffer | null>;
+    protected getBinaryFileMetadata<T extends "file" | "image">(_filePath: string, _type: T): Promise<OpsMetadata<T>>;
+    listCommits(): Promise<result.Result<CommitPage, HistoryError>>;
+    getCommitPatches(): Promise<result.Result<{
+        commit: HistoricalCommit;
+        patches: CommitPatch[];
+    }, HistoryError>>;
+    getCommitModules(): Promise<result.Result<{
+        modules: StoredModuleVersion[];
+        complete: boolean;
+    }, HistoryError>>;
+    getCommitAffectedFiles(): Promise<result.Result<AffectedFile[], HistoryError>>;
+    getFileAtCommit(): Promise<result.Result<Buffer, HistoryError>>;
+    gitPathOfModule(_moduleFilePath: ModuleFilePath): result.Result<string, HistoryError>;
+}
+/** Kept exported so a host can name the error shape it may get back. */
+export type ValOpsMemoryError = GenericErrorMessage;

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

@@ -7,6 +7,8 @@ type Versions = {
         next?: string;
     };
 };
+import type { ValPatchStore } from "./ValOpsMemory.js";
+import type { CommitContext, CommitResult } from "./ValServer.js";
 export type ValApiOptions = ValServerOverrides & ValConfig & Versions;
 type ValServerOverrides = Partial<{
     /**
@@ -46,6 +48,41 @@ type ValServerOverrides = Partial<{
      * If both is missing, it will default to "local".
      */
     mode: "proxy" | "local";
+    /**
+     * The project's source, by path -- and, by being present, the choice of an
+     * in-memory store over the local filesystem.
+     *
+     * EXPERIMENTAL. For a host that HOLDS the project's source rather than having
+     * it on a disk: it hands it over here, patches live in `patchStore`, and a
+     * publish is whatever `commitPrepared` does with the files. See
+     * `ValOpsMemory`.
+     *
+     * Selected by presence rather than by a `mode` value because unlike "local"
+     * and "proxy" this one cannot be inferred from the environment -- there is
+     * nothing to infer it FROM, and a mode that can be turned on without
+     * supplying the source would be a server with no content in it.
+     *
+     * An environment that has no disk can still say it EXPECTS this, by setting
+     * `VAL_MODE=memory`. That does not select the mode; it makes forgetting to
+     * pass the source an error here rather than an `EPERM` from `fs` mode two
+     * layers down.
+     */
+    sourceFiles: Record<string, string>;
+    /**
+     * Serve memory mode without authenticating any request. Off by default.
+     *
+     * Set this only when the host authorises every request before it reaches
+     * Val. Without it, memory mode requires a verified session like `http` mode
+     * does -- unlike `fs` mode, this one runs deployed, so an unauthenticated
+     * server is one where anyone who can reach the port can create patches and
+     * trigger a publish.
+     */
+    unsafelyAllowUnauthenticated?: boolean;
+    /**
+     * Where pending patches live, with {@link sourceFiles}. Defaults to memory,
+     * which is not durable -- see `ValPatchStore`.
+     */
+    patchStore: ValPatchStore;
     /**
      * Current git commit.
      *
@@ -113,7 +150,32 @@ type ValServerOverrides = Partial<{
      */
     disableCache?: boolean;
 }>;
-export declare function createValServer(valModules: ValModules, route: string, opts: ValApiOptions, config: ValConfig, callbacks: ValServerCallbacks, formatter?: (code: string, filePath: string) => string | Promise<string>): Promise<ValServer>;
+export declare function createValServer(valModules: ValModules, route: string, opts: ValApiOptions, config: ValConfig, callbacks: ValServerCallbacks, formatter?: (code: string, filePath: string) => string | Promise<string>, 
+/**
+ * Called after a save has applied its patches. EXPERIMENTAL — see
+ * `ValServerOptions.commitPrepared`.
+ */
+commitPrepared?: (commit: {
+    patchedSourceFiles: Record<string, string | null>;
+}) => Promise<void>, 
+/**
+ * What a publish does in http mode. EXPERIMENTAL — see
+ * `ValServerOptions.publishOverride`.
+ */
+publishOverride?: (context: CommitContext) => Promise<CommitResult>): Promise<ValServer>;
+/**
+ * `fs` and `path` are imported INSIDE this function, not at the top of the file.
+ *
+ * This is the only thing in this module that touches either, and it is a local
+ * development convenience: scanning upwards for a `.git` to guess the commit and
+ * branch. A static import put `fs` in the module graph of everything reaching
+ * `createValApiRouter` -- which is every server integration, including ones that
+ * run where there is no filesystem. Workerd provides no `fs`, so such a build
+ * could not be bundled at all without stubbing it.
+ *
+ * The `await import` costs nothing here: the only caller is the CLI, on a
+ * machine that has both.
+ */
 export declare function safeReadGit(cwd: string): Promise<{
     commit?: string;
     branch?: string;