pi-llama-cpp 0.14.0 → 0.16.0

package/src/models/llamaSwapModel.ts

@@ -0,0 +1,90 @@
+import { FALLBACK_CTX } from "../constants";
+import { Mode } from "../enums/mode";
+import { Status } from "../enums/status";
+import { BaseModel } from "./baseModel";
+
+export class LlamaSwapModel extends BaseModel {
+  get mode(): Mode {
+    return Mode.LLAMASWAP;
+  }
+
+  override get name(): string {
+    // llama-swap adds a `llamaswap` key inside `meta` with aliases;
+    // fall back to the standard aliases array, then to id
+    return (
+      this.model.meta?.llamaswap?.aliases?.[0] ??
+      this.model.aliases?.[0] ??
+      this.model.id
+    );
+  }
+
+  /**
+   * Retrieves the context size of the model.
+   * An override's `contextSize` takes precedence; otherwise reads
+   * `meta.n_ctx` from the llama-swap `/v1/models` response,
+   * falling back to `FALLBACK_CTX`.
+   *
+   * @returns The context size
+   */
+  protected override async getContextSize(): Promise<number> {
+    const overridden = this.server.findOverrideForModel(this.id)?.contextSize;
+    if (overridden && overridden > 0) return overridden;
+
+    const { data } = await this.server.fetchModels();
+    const model = data.find((m) => m.id === this.id);
+
+    return model?.meta?.n_ctx ?? FALLBACK_CTX;
+  }
+
+  /**
+   * Detects the capabilities of the model.
+   * An override's `capabilities` fully replaces detection.
+   *
+   * @returns An array of capabilities, as expected by Pi
+   */
+  override async getCapabilities(): Promise<("text" | "image")[]> {
+    const overridden = this.server.findOverrideForModel(this.id)?.capabilities;
+    if (overridden) return overridden;
+
+    const { data } = await this.server.fetchModels();
+    const model = data.find((m) => m.id === this.id);
+
+    const inputModalities = model?.architecture?.input_modalities ?? [];
+    return inputModalities.includes("image") ? ["text", "image"] : ["text"];
+  }
+
+  /**
+   * Detects the load status of a model.
+   * For simplicity, we'll only handle loaded/unloaded
+   *
+   * @returns The current {@link Status}
+   */
+  override async getStatus(): Promise<Status> {
+    const { data } = await this.server.fetchModels();
+    const model = data.find((m) => m.id === this.id);
+
+    return model?.status?.value === "loaded" ? Status.LOADED : Status.UNLOADED;
+  }
+
+  /**
+   * Loads the model in the llama-swap server
+   */
+  override async load(): Promise<void> {
+    const status = await this.getStatus();
+    if (status === Status.LOADED) return;
+
+    try {
+      await this.server.llamaSwapLoad(this.id);
+    } catch (err) {
+      console.warn({ err });
+      throw new Error(`Model loading failed: ${this.id}`);
+    }
+  }
+
+  /**
+   * Unloads the model in the llama-swap server
+   */
+  override async unload(): Promise<void> {
+    await this.server.llamaSwapUnload(this.id);
+  }
+}

package/src/models/routerModel.ts

@@ -26,7 +26,7 @@ export class RouterModel extends BaseModel {
    *
    * In exchange, it will allow unloaded models to be correctly shown as "unloaded".
    */
-  protected async pollStatus(startTime = Date.now()): Promise<void> {
+  protected override async pollStatus(startTime = Date.now()): Promise<void> {
     let elapsed = 0;
     const limit = 5000;
 
@@ -52,7 +52,7 @@ export class RouterModel extends BaseModel {
    *
    * @returns The context size in tokens
    */
-  protected async getContextSize(): Promise<number> {
+  protected override async getContextSize(): Promise<number> {
     // We can get a more accurate context size if the model is already loaded
     if ((await this.getStatus()) === Status.LOADED) {
       return super.getContextSize();

package/src/models/singleModel.ts

@@ -2,11 +2,11 @@ import { Mode } from "../enums/mode";
 import { BaseModel } from "./baseModel";
 
 export class SingleModel extends BaseModel {
-  get mode(): Mode {
+  override get mode(): Mode {
     return Mode.SINGLE;
   }
 
-  protected async getCapabilities(): Promise<("text" | "image")[]> {
+  protected override async getCapabilities(): Promise<("text" | "image")[]> {
     try {
       return await super.getCapabilities();
     } catch {

package/src/server.ts

@@ -8,6 +8,7 @@ import { Mode } from "./enums/mode";
 import { ServerStatus } from "./enums/serverStatus";
 import { ModelsEndpoint } from "./interfaces/endpoints/models";
 import {
+  LlamaSwapPropsError,
   PropsEndpoint,
   PropsModelEndpoint,
 } from "./interfaces/endpoints/props";
@@ -16,6 +17,7 @@ import type { ModelOverride } from "./interfaces/settings";
 import type { LlamaSettingsManager } from "./managers/settings";
 import { BaseModel } from "./models/baseModel";
 import { LegacyModel } from "./models/legacyModel";
+import { LlamaSwapModel } from "./models/llamaSwapModel";
 import { RouterModel } from "./models/routerModel";
 import { SingleModel } from "./models/singleModel";
 import { SSEManager } from "./sse/manager";
@@ -52,8 +54,8 @@ export class Server {
     // in ServerManager), so no lazy fallback is needed. initialize()
     // rebuilds the client to re-resolve the API key.
     this.apiClient =
-      deps.createApiClient?.(this.getApiKey()) ??
-      new ApiClient(options.baseUrl, this.getApiKey());
+      deps.createApiClient?.(this.apiKey) ??
+      new ApiClient(options.baseUrl, this.apiKey);
   }
 
   /** Base URL of this server endpoint. */
@@ -119,10 +121,8 @@ export class Server {
   /**
    * Retrieves the API key from the config resolver.
    * Tries custom ID first, then falls back to URL-based ID.
-   *
-   * @returns The API key
    */
-  getApiKey(): string {
+  get apiKey(): string {
     // Try custom ID first
     if (this.options.customId) {
       const key = this.settings.resolveApiKey(this.options.customId);
@@ -137,10 +137,9 @@ export class Server {
    * Clears the cache first so we always fetch fresh data.
    */
   async initialize() {
-    const apiKey = this.getApiKey();
     this.apiClient =
-      this.deps.createApiClient?.(apiKey) ??
-      new ApiClient(this.baseUrl, apiKey);
+      this.deps.createApiClient?.(this.apiKey) ??
+      new ApiClient(this.baseUrl, this.apiKey);
     this.sse = this.deps.createSSEManager?.(this) ?? new SSEManager(this);
     const { data } = await this.fetchModels();
     const mode = await this.detectServerMode(data);
@@ -150,6 +149,7 @@ export class Server {
       [Mode.ROUTER]: RouterModel,
       [Mode.LEGACY]: LegacyModel,
       [Mode.SINGLE]: SingleModel,
+      [Mode.LLAMASWAP]: LlamaSwapModel,
     }[mode];
 
     const models: BaseModel[] = data.map((m) => new modelCtor(m, this));
@@ -166,9 +166,12 @@ export class Server {
    * @returns The detected mode
    */
   private async detectServerMode(data: ModelsEndpoint["data"]): Promise<Mode> {
-    const { role } = await this.fetchServerProps();
+    const serverProps = await this.fetchServerProps();
 
-    if (role === "router") return Mode.ROUTER;
+    if ("src" in serverProps && serverProps.src === "llama-swap")
+      return Mode.LLAMASWAP;
+    if ("role" in serverProps && serverProps.role === "router")
+      return Mode.ROUTER;
     if ("max_model_len" in data[0]) return Mode.LEGACY;
     return Mode.SINGLE;
   }
@@ -185,7 +188,7 @@ export class Server {
    * @returns The server status
    */
   async isReady(timeout: number): Promise<ServerStatus> {
-    return checkServerHealth(this.baseUrl, timeout, this.getApiKey());
+    return checkServerHealth(this.baseUrl, timeout, this.apiKey);
   }
 
   /**
@@ -200,12 +203,16 @@ export class Server {
   }
 
   /**
-   * Fetches general properties of the server
+   * Fetches general properties of the server.
+   * llama-server returns {@link PropsEndpoint}; llama-swap returns
+   * {@link LlamaSwapPropsError} (an error response with a `src` discriminator).
    *
-   * @return The properties of the server
+   * @return The server properties
    */
-  async fetchServerProps(): Promise<PropsEndpoint> {
-    return await this.apiClient.get<PropsEndpoint>("/props?autoload=false");
+  async fetchServerProps(): Promise<PropsEndpoint | LlamaSwapPropsError> {
+    return await this.apiClient.get<PropsEndpoint | LlamaSwapPropsError>(
+      "/props?autoload=false",
+    );
   }
 
   /**
@@ -261,4 +268,24 @@ export class Server {
       model,
     });
   }
+
+  /**
+   * Loads a model on a llama-swap server (GET /upstream/{id}).
+   *
+   * @param model The model ID to load
+   */
+  async llamaSwapLoad(model: string): Promise<void> {
+    this.apiClient.clearCache();
+    await this.apiClient.rawGet(`/upstream/${model}`);
+  }
+
+  /**
+   * Unloads a model on a llama-swap server (POST /api/models/unload/{id}).
+   *
+   * @param model The model ID to unload
+   */
+  async llamaSwapUnload(model: string): Promise<void> {
+    this.apiClient.clearCache();
+    await this.apiClient.rawPost(`/api/models/unload/${model}`);
+  }
 }

package/src/sse/manager.ts

@@ -46,7 +46,7 @@ export class SSEManager {
     try {
       const response = await fetch(this.sseEndpoint, {
         method: "GET",
-        headers: buildAuthHeaders(this.server.getApiKey()),
+        headers: buildAuthHeaders(this.server.apiKey),
         signal: AbortSignal.timeout(await this.server.getServerTimeout()),
       });
       this.sseSupported =
@@ -78,7 +78,7 @@ export class SSEManager {
     this.modelCallbacks.set(modelId, callbacks);
 
     // Create SSE client if not already created
-    this.sseClient ??= new SSEClient(this.sseEndpoint, this.server.getApiKey());
+    this.sseClient ??= new SSEClient(this.sseEndpoint, this.server.apiKey);
 
     // Subscribe a single dispatching callback to the SSE client
     if (!this.sseSubscribers.has(modelId)) {

package/src/ui/dialog/confirm.ts

@@ -39,7 +39,7 @@ export class ConfirmDialog extends BaseDialog {
 
   // -- helpers -------------------------------------------------------------------
 
-  protected get inputTarget() {
+  protected override get inputTarget() {
     return this.list;
   }
 }

package/src/ui/dialog/input.ts

@@ -36,7 +36,7 @@ export class InputDialog extends BaseDialog {
 
   // -- helpers -------------------------------------------------------------------
 
-  protected get inputTarget() {
+  protected override get inputTarget() {
     return this.input;
   }
 

package/src/ui/editors/editorOptions.ts

@@ -1,4 +1,7 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionUIContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
 import type { KeybindingsManager, TUI } from "@earendil-works/pi-tui";
 import type { LlamaServer } from "../../interfaces/settings";
 
@@ -32,6 +35,10 @@ export interface SettingsListEditorOptions {
 export interface ServerSettingsListOptions extends SettingsListEditorOptions {
   /** Timeout (ms) for health checks. Defaults to 1000ms if not provided. */
   serverTimeout?: number;
+  /** Resolves the API key for a server (used for auth probing). */
+  authResolver?: (server: LlamaServer) => Promise<string>;
+  /** UI context for notifications (used to warn about auth-required servers). */
+  ui?: ExtensionUIContext;
 }
 
 /**

package/src/ui/editors/itemBuilder.ts

@@ -30,7 +30,7 @@ export abstract class ItemBuilder<TEntry, TField extends SettingField<TEntry>> {
       description: def.description,
       currentValue: def.currentValue(entry),
     };
-    return this.decorate(def, entry, base);
+    return this.decorate(def, base);
   }
 
   /** Builds the `SettingItem` array for one entry's editable fields. */
@@ -39,9 +39,5 @@ export abstract class ItemBuilder<TEntry, TField extends SettingField<TEntry>> {
   }
 
   /** Adds field-type-specific columns (e.g. submenu or fixed values). */
-  protected abstract decorate(
-    def: TField,
-    entry: TEntry,
-    base: SettingItem,
-  ): SettingItem;
+  protected abstract decorate(def: TField, base: SettingItem): SettingItem;
 }

package/src/ui/editors/listEditor.ts

@@ -66,9 +66,6 @@ export abstract class ListEditor<
     | "emptyServers"
     | "emptyOverrideEntries";
 
-  /** Total item count (entries or servers) for selection clamping. */
-  protected abstract getCurrentCount(): number;
-
   /** Returns the id for a row at the given index. */
   protected abstract getRowId(index: number): string;
 
@@ -78,6 +75,12 @@ export abstract class ListEditor<
   /** Title for the delete confirmation dialog (e.g. "Delete server"). */
   protected abstract get deleteTitle(): string;
 
+  /** Returns the number of items in the current list. Override when the
+   * list items don't directly correspond to `options.servers`. */
+  protected getCount(): number {
+    return this.options.servers.length;
+  }
+
   // -- hooks -----------------------------------------------------------------
 
   /**
@@ -111,10 +114,7 @@ export abstract class ListEditor<
 
   handleInput(data: string): void {
     // Delegate to the open modal dialog, if any
-    if (this.activeDialog) {
-      this.activeDialog.handleInput(data);
-      return;
-    }
+    if (this.delegateToDialogInput(data)) return;
 
     // Delegate to settingsList if a submenu is open
     if (this.submenuOpen && this.settingsList) {
@@ -134,15 +134,11 @@ export abstract class ListEditor<
     }
     if (kb.matches(data, "tui.select.up")) {
       this.selectedIndex =
-        this.selectedIndex === 0
-          ? this.getCurrentCount() - 1
-          : this.selectedIndex - 1;
+        this.selectedIndex === 0 ? this.getCount() - 1 : this.selectedIndex - 1;
     }
     if (kb.matches(data, "tui.select.down")) {
       this.selectedIndex =
-        this.selectedIndex === this.getCurrentCount() - 1
-          ? 0
-          : this.selectedIndex + 1;
+        this.selectedIndex === this.getCount() - 1 ? 0 : this.selectedIndex + 1;
     }
     if (data === "a") {
       this.beginAdd();
@@ -164,7 +160,7 @@ export abstract class ListEditor<
     // Empty list hint
     if (!this.settingsList) return ["Loading..."];
     const lines = this.settingsList.render(width);
-    if (this.getCurrentCount() === 0) {
+    if (this.getCount() === 0) {
       lines[lines.length - 1] = getSettingsListTheme().hint(
         HINTS[this.emptyHintKey],
       );
@@ -174,6 +170,18 @@ export abstract class ListEditor<
 
   // -- helpers ---------------------------------------------------------------
 
+  /**
+   * If a dialog is open, delegates input to it and returns true;
+   * otherwise returns false. Used to short-circuit handleInput.
+   */
+  private delegateToDialogInput(data: string): boolean {
+    if (this.activeDialog) {
+      this.activeDialog.handleInput(data);
+      return true;
+    }
+    return false;
+  }
+
   /**
    * Rebuilds the list and places the cursor on `targetIndex`.
    * Subclasses call this after add/delete/persist to refresh the UI.
@@ -181,9 +189,10 @@ export abstract class ListEditor<
   protected async rebuildList(targetIndex: number): Promise<void> {
     const list = await this.buildSettingsList();
     this.settingsList = list;
-    const count = this.getCurrentCount();
+    const count = this.getCount();
     if (count === 0) {
       this.selectedIndex = 0;
+      this.options.tui.requestRender();
       return;
     }
     this.selectedIndex = Math.min(targetIndex, count - 1);

package/src/ui/editors/override/entryEditor.ts

@@ -1,11 +1,11 @@
 import type { SettingItem, SettingsList } from "@earendil-works/pi-tui";
+import type { LlamaServer, ModelOverride } from "../../../interfaces/settings";
 import { FIELDS, FieldMessages, HINTS, TITLES } from "../../strings";
 import type { OverrideSettingsListOptions } from "../editorOptions";
 import { ListEditor } from "../listEditor";
 import { SettingsListFactory } from "../settingsListFactory";
 import { OverrideEntry } from "./entry";
-import { OverrideFields, OverrideSummary } from "./fields";
-import { OverrideEntryMutator } from "./handlers";
+import { OverrideFields, OverrideSummary } from "./fields/index";
 import { OverrideItemBuilder } from "./itemBuilder";
 
 /**
@@ -31,21 +31,21 @@ export class OverrideEntryListEditor extends ListEditor<OverrideSettingsListOpti
 
   /** Esc steps back to the server list, not out of the whole dialog —
    * `options.done` is the top-level close (shared options object). */
-  protected close(): void {
+  protected override close(): void {
     this.done();
   }
 
   // -- abstract hooks -------------------------------------------------------
 
-  protected buildSettingsList(): SettingsList {
+  protected override buildSettingsList(): SettingsList {
     const builder = new OverrideItemBuilder(this.dialogs);
-    const items: SettingItem[] = this.mutator.entries().map((entry, i) => ({
+    const items: SettingItem[] = this.entries().map((entry, i) => ({
       id: `entry-${i}`,
       label: entry.pattern,
       description: HINTS.overrideEntryRow,
       currentValue: OverrideSummary.of(entry.override),
       submenu: (_cv, done) => {
-        const current = this.mutator.entries()[i] ?? entry;
+        const current = this.entries()[i] ?? entry;
         const fieldItems = builder.buildFieldItems(current);
         const fieldList = SettingsListFactory.create(
           fieldItems,
@@ -75,7 +75,7 @@ export class OverrideEntryListEditor extends ListEditor<OverrideSettingsListOpti
     field: string,
     value: string,
   ): void {
-    const result = this.mutator.applyFieldChange(entryIndex, field, value);
+    const result = this.applyFieldChange(entryIndex, field, value);
     if (!result) return;
 
     this.commitFieldChange(
@@ -103,7 +103,7 @@ export class OverrideEntryListEditor extends ListEditor<OverrideSettingsListOpti
     );
   }
 
-  protected beginAdd(): void {
+  protected override beginAdd(): void {
     this.openDialog(
       this.dialogs.input({
         title: TITLES.addOverride,
@@ -119,9 +119,9 @@ export class OverrideEntryListEditor extends ListEditor<OverrideSettingsListOpti
     );
   }
 
-  protected deleteSelected(): void {
+  protected override deleteSelected(): void {
     const idx = this.selectedIndex;
-    const next = this.mutator.removeEntry(idx);
+    const next = this.removeEntry(idx);
     void this.persistSnapshot(next, () => {
       this.rebuildList(idx);
       this.options.onChanged?.();
@@ -129,36 +129,118 @@ export class OverrideEntryListEditor extends ListEditor<OverrideSettingsListOpti
     });
   }
 
-  protected readonly emptyHintKey = "emptyOverrideEntries" as const;
+  protected override readonly emptyHintKey = "emptyOverrideEntries" as const;
 
-  protected getCurrentCount(): number {
-    return this.mutator.entries().length;
+  protected override getCount(): number {
+    return this.entries().length;
   }
 
-  protected getRowId(index: number): string {
+  protected override getRowId(index: number): string {
     return `entry-${index}`;
   }
 
-  protected getRowLabel(index: number): string {
-    return this.mutator.entries()[index]?.pattern ?? "";
+  protected override getRowLabel(index: number): string {
+    return this.entries()[index]?.pattern ?? "";
   }
 
-  protected get deleteTitle(): string {
+  protected override get deleteTitle(): string {
     return TITLES.deleteOverride;
   }
 
   // -- helpers ---------------------------------------------------------------
 
-  /** Fresh mutator over the current servers snapshot — `persistSnapshot`
-   * replaces `options.servers` in place, so instances can't be cached. */
-  private get mutator(): OverrideEntryMutator {
-    return new OverrideEntryMutator(this.options.servers, this.serverIndex);
+  /** The server's override entries, in map iteration order. */
+  private entries(): OverrideEntry[] {
+    return OverrideEntry.listFrom(this.options.servers[this.serverIndex]);
+  }
+
+  /** Handles a field commit from an override entry's submenu. Returns
+   * `null` when the entry doesn't exist (stale index — no-op). */
+  private applyFieldChange(
+    entryIndex: number,
+    field: string,
+    value: string,
+  ): { next: LlamaServer[]; updatedOverride: ModelOverride } | null {
+    const entry = this.entries()[entryIndex];
+    if (!entry) return null;
+
+    // Pattern field: rename the pattern key, keep the override object
+    if (field === "pattern") {
+      return {
+        next: this.updateEntry(entryIndex, value, entry.override),
+        updatedOverride: entry.override,
+      };
+    }
+
+    // Other fields: let the field definition apply itself
+    const updatedOverride: ModelOverride = { ...entry.override };
+    OverrideFields.byId(field).apply(updatedOverride, value);
+
+    return {
+      next: this.updateEntry(entryIndex, entry.pattern, updatedOverride),
+      updatedOverride,
+    };
+  }
+
+  /** Adds a new override entry with a uniquified pattern. */
+  private addEntry(pattern: string): LlamaServer[] {
+    const server = this.options.servers[this.serverIndex];
+    if (!server) return this.options.servers;
+
+    const existing = new Set(Object.keys(server.overrides ?? {}));
+    let uniquePattern = pattern;
+    let n = 2;
+    while (existing.has(uniquePattern)) {
+      uniquePattern = `${pattern}-${n++}`;
+    }
+
+    return this.withServer((s) => ({
+      ...s,
+      overrides: { ...s.overrides, [uniquePattern]: {} },
+    }));
+  }
+
+  /** Removes the entry at `entryIndex`. */
+  private removeEntry(entryIndex: number): LlamaServer[] {
+    return this.withServer((s) => ({
+      ...s,
+      overrides: Object.fromEntries(
+        Object.entries(s.overrides ?? {}).filter((_, j) => j !== entryIndex),
+      ),
+    }));
+  }
+
+  /** Returns the servers with the target server replaced by
+   * `fn(server)`. Immutable. */
+  private withServer(fn: (server: LlamaServer) => LlamaServer): LlamaServer[] {
+    return this.options.servers.map((server, i) =>
+      i === this.serverIndex ? fn(server) : server,
+    );
+  }
+
+  /** Replaces the entry at `entryIndex` with `pattern → override` in a
+   * single mutation — used both for renaming the pattern and for editing
+   * its fields. The entry keeps its position in the map's iteration
+   * order. Immutable. */
+  private updateEntry(
+    entryIndex: number,
+    pattern: string,
+    override: ModelOverride,
+  ): LlamaServer[] {
+    return this.withServer((s) => ({
+      ...s,
+      overrides: Object.fromEntries(
+        Object.entries(s.overrides ?? {}).map(([k, v], j) =>
+          j === entryIndex ? [pattern, override] : [k, v],
+        ),
+      ),
+    }));
   }
 
   private async saveAdd(pattern: string): Promise<void> {
-    const next = this.mutator.addEntry(pattern);
+    const next = this.addEntry(pattern);
     await this.persistSnapshot(next, () => {
-      this.rebuildList(this.mutator.entries().length - 1);
+      this.rebuildList(this.entries().length - 1);
       this.options.onChanged?.();
       this.options.tui.requestRender();
     });

package/src/ui/editors/override/fields/base.ts

@@ -0,0 +1,53 @@
+import type { ModelOverride } from "../../../../interfaces/settings";
+import { SettingField } from "../../settingField";
+import { OverrideEntry } from "../entry";
+
+/** Type of a field: "input" for free-text, "finite" for fixed options */
+export type FieldType = "input" | "finite";
+
+/** Validation function for input fields */
+export type InputValidator = (raw: string) => string | null;
+
+/**
+ * Abstract base class for one editable field of a model override entry
+ * (Template Method): each subclass owns its display format, validation
+ * and apply logic in a single place, so the parse/format round-trips
+ * can't drift. Extends the shared {@link SettingField} base (id, label,
+ * description, placeholder from the FIELDS registry).
+ */
+export abstract class OverrideField extends SettingField<OverrideEntry> {
+  /** Field type: "input" for free-text, "finite" for fixed options. */
+  abstract readonly type: FieldType;
+
+  /**
+   * Canonical display label for this field — the single source of truth
+   * for both the field rows' `currentValue` and the post-commit refresh
+   * of an open field submenu, so the two can't drift.
+   */
+  abstract displayValue(entry: OverrideEntry): string;
+
+  /** Current value shown in the row — defaults to `displayValue`. */
+  currentValue(entry: OverrideEntry): string {
+    return this.displayValue(entry);
+  }
+
+  /** For "input" fields: validation function for committed values. */
+  abstract readonly validate: InputValidator;
+
+  /** For "finite" fields: the fixed options (undefined for "input"). */
+  readonly options: readonly string[] | undefined = undefined;
+
+  /** Applies a committed value to the override object. The pattern key
+   * rename is handled separately by the mutator (default: no-op). */
+  apply(_override: ModelOverride, _value: string): void {
+    // no-op — override in subclasses that need to mutate the override
+  }
+
+  /** One `term: value` part of the entry-row summary (see
+   * {@link OverrideSummary.of}), or `null` when the field shouldn't
+   * appear (unset/zero values — each field decides). The pattern is the
+   * row label, so it never contributes a part; the default is `null`. */
+  summaryPart(_override: ModelOverride): string | null {
+    return null;
+  }
+}