@khorsheed/dsh-local-agent 0.1.0-rc.6

package/lib/types/member-inbox.js

@@ -0,0 +1,225 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Durable human input; the provider FIFO remains the sole execution order. */
+export class MemberInbox {
+    directory;
+    execute;
+    onError;
+    states = new Map();
+    active = new Map();
+    storageErrors = new Map();
+    closed = false;
+    constructor(directory, execute, onError) {
+        this.directory = directory;
+        this.execute = execute;
+        this.onError = onError;
+    }
+    path(memberId) { return join(this.directory, createHash('sha256').update(memberId).digest('hex') + '.json'); }
+    load(memberId) {
+        const known = this.states.get(memberId);
+        if (known !== undefined)
+            return known;
+        let raw;
+        try {
+            raw = readFileSync(this.path(memberId), 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const empty = { memberId, paused: false, messages: [] };
+            this.states.set(memberId, empty);
+            return empty;
+        }
+        const stored = JSON.parse(raw);
+        const state = stored?.state;
+        const statuses = ['queued', 'running', 'done', 'failed', 'cancelled', 'uncertain'];
+        if (stored?.version !== 1 || state?.memberId !== memberId || typeof state.paused !== 'boolean' || !Array.isArray(state.messages)
+            || state.messages.some(row => typeof row?.id !== 'string' || typeof row.text !== 'string' || !statuses.includes(row.status)
+                || !Number.isFinite(row.createdAt) || !Number.isFinite(row.updatedAt) || (row.error !== undefined && typeof row.error !== 'string'))
+            || new Set(state.messages.map(row => row.id)).size !== state.messages.length)
+            throw new Error('Invalid member inbox; admission is blocked');
+        const recovered = structuredClone(state);
+        for (const row of recovered.messages)
+            if (row.status === 'running') {
+                row.status = 'uncertain';
+                row.error = 'Host restarted before durable settlement; reconcile this input before continuing';
+            }
+        if (recovered.messages.some(row => row.status === 'queued' || row.status === 'uncertain'))
+            recovered.paused = true;
+        this.save(recovered);
+        return recovered;
+    }
+    save(state) {
+        const path = this.path(state.memberId);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+            const fd = openSync(temporary, 'wx', 0o600);
+            try {
+                writeFileSync(fd, JSON.stringify({ version: 1, state }));
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(temporary, path);
+            const directory = openSync(this.directory, 'r');
+            try {
+                fsyncSync(directory);
+            }
+            finally {
+                closeSync(directory);
+            }
+            this.states.set(state.memberId, state);
+            this.storageErrors.delete(state.memberId);
+        }
+        catch (error) {
+            this.storageErrors.set(state.memberId, String(error));
+            throw error;
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    read(memberId) {
+        const state = structuredClone(this.load(memberId));
+        const error = this.storageErrors.get(memberId);
+        return error === undefined ? state : { ...state, error };
+    }
+    assertAdmission(memberId) {
+        if (this.storageErrors.has(memberId))
+            throw new Error('Member inbox persistence failed; reconcile storage before admission');
+        const state = this.load(memberId);
+        if (state.messages.some(row => row.status === 'uncertain'))
+            throw new Error('A member input has an uncertain outcome; reconcile before continuing');
+        if (state.paused && state.messages.some(row => row.status === 'queued'))
+            throw new Error('Member inbox is paused; resume or cancel queued inputs first');
+    }
+    enqueue(memberId, text, requestId) {
+        if (this.closed)
+            throw new Error('Member inbox is closed');
+        if (text.trim() === '' || requestId.trim() === '')
+            throw new Error('Member input and request ID must be non-empty');
+        const state = this.read(memberId);
+        const previous = state.messages.find(row => row.id === requestId);
+        if (previous !== undefined) {
+            if (previous.text !== text)
+                throw new Error('Member input request ID was already used for different text');
+            return previous;
+        }
+        if (state.messages.filter(row => row.status === 'queued').length >= 100)
+            throw new Error('Member inbox has reached its 100 queued input limit');
+        const row = { id: requestId, text, status: 'queued', createdAt: Date.now(), updatedAt: Date.now() };
+        state.messages.push(row);
+        this.save(state);
+        this.pump(memberId);
+        return structuredClone(row);
+    }
+    pause(memberId) {
+        const state = this.read(memberId);
+        state.paused = true;
+        this.save(state);
+        for (const row of state.messages)
+            if (row.status === 'queued')
+                this.active.get(`${memberId}:${row.id}`)?.controller.abort(new Error('Inbox paused'));
+    }
+    resume(memberId) {
+        if (this.storageErrors.has(memberId)) {
+            this.states.delete(memberId);
+            this.storageErrors.delete(memberId);
+        }
+        const state = this.read(memberId);
+        if (state.messages.some(row => row.status === 'uncertain'))
+            throw new Error('Reconcile uncertain inputs before resuming');
+        state.paused = false;
+        this.save(state);
+        this.pump(memberId);
+    }
+    cancelStarting(memberId) {
+        const row = this.load(memberId).messages.find(input => input.status === 'running');
+        const entry = row === undefined ? undefined : this.active.get(`${memberId}:${row.id}`);
+        if (entry === undefined)
+            return false;
+        entry.controller.abort(new Error('Member input stopped'));
+        return true;
+    }
+    cancel(memberId, id) {
+        const state = this.read(memberId);
+        const row = state.messages.find(row => row.id === id);
+        if (row?.status !== 'queued')
+            throw new Error('Only a queued input can be cancelled here; use member Stop for a running turn');
+        row.status = 'cancelled';
+        row.updatedAt = Date.now();
+        this.save(state);
+        this.active.get(`${memberId}:${id}`)?.controller.abort(new Error('Queued input cancelled'));
+    }
+    reconcile(memberId, id, outcome, evidence) {
+        const state = this.read(memberId);
+        const row = state.messages.find(row => row.id === id);
+        if (row?.status !== 'uncertain' || evidence.trim() === '')
+            throw new Error('Reconciliation requires an uncertain input and evidence');
+        row.status = outcome;
+        row.error = evidence.trim();
+        row.updatedAt = Date.now();
+        this.save(state);
+    }
+    update(memberId, id, update) {
+        const state = this.read(memberId);
+        const row = state.messages.find(row => row.id === id);
+        if (row === undefined)
+            throw new Error('Member input disappeared');
+        update(row);
+        row.updatedAt = Date.now();
+        this.save(state);
+    }
+    pump(memberId) {
+        if (this.closed || this.storageErrors.has(memberId))
+            return;
+        const state = this.load(memberId);
+        if (state.paused || state.messages.some(row => row.status === 'uncertain'))
+            return;
+        for (const row of state.messages) {
+            const key = `${memberId}:${row.id}`;
+            if (row.status !== 'queued' || this.active.has(key))
+                continue;
+            const controller = new AbortController();
+            this.active.set(key, { memberId, controller });
+            void (async () => {
+                try {
+                    const run = await this.execute(memberId, row.text, controller.signal, () => {
+                        controller.signal.throwIfAborted();
+                        this.assertAdmission(memberId);
+                        this.update(memberId, row.id, input => { if (input.status !== 'queued')
+                            throw new Error('Input is no longer queued'); input.status = 'running'; });
+                    });
+                    const result = await run.result;
+                    if (!this.closed)
+                        this.update(memberId, row.id, input => { input.status = result.stopReason === 'aborted' ? 'cancelled' : result.stopReason === 'completed' ? 'done' : 'failed'; });
+                }
+                catch (error) {
+                    if (!this.closed) {
+                        const current = this.load(memberId);
+                        const status = current.messages.find(input => input.id === row.id)?.status;
+                        if (!(controller.signal.aborted && current.paused && status === 'queued') && status !== 'cancelled') {
+                            this.update(memberId, row.id, input => { input.status = controller.signal.aborted ? 'cancelled' : 'failed'; input.error = String(error); });
+                        }
+                    }
+                }
+                finally {
+                    this.active.delete(key);
+                    if (!this.closed)
+                        this.pump(memberId);
+                }
+            })().catch(this.onError);
+        }
+    }
+    dispose() { this.closed = true; for (const entry of this.active.values())
+        entry.controller.abort(new Error('Inbox disposed')); this.active.clear(); }
+}

package/lib/types/model-directory.d.ts

@@ -0,0 +1,43 @@
+import type { LocalAgentModelDirectory, LocalAgentModelDirectoryData } from './types.ts';
+/** File metadata only: credential bytes and URL credentials never enter cache keys. */
+export declare function modelDirectoryContextKey(context: {
+    provider: string;
+    homeDir: string;
+    cwd: string;
+    cli: readonly string[];
+    files: readonly string[];
+    endpoint?: string;
+}): string;
+/** Native facts win; configured candidates and historical suggestions retain provenance. */
+export declare function extendModelDirectory(directory: LocalAgentModelDirectory, configuration: readonly (string | undefined)[], history: readonly (string | undefined)[]): LocalAgentModelDirectory;
+/**
+ * Shared mechanics only: providers own discovery and supply a non-secret
+ * context key covering scope, endpoint, configuration, cwd and CLI identity.
+ * Failed refreshes keep the last successful data. Invalidation fences stale
+ * in-flight replies, including account changes while a probe is running.
+ */
+export declare class ModelDirectoryCache {
+    private readonly options;
+    private readonly entries;
+    private revision;
+    private disposed;
+    constructor(options: {
+        load: (context: string, signal: AbortSignal) => Promise<LocalAgentModelDirectoryData>;
+        ttlMs?: number;
+        retryMs?: number;
+        maxEntries?: number;
+        now?: () => number;
+        onError?: (error: unknown) => void;
+    });
+    private now;
+    private entry;
+    private publish;
+    read(key: string): LocalAgentModelDirectory;
+    refresh(key: string): Promise<LocalAgentModelDirectory>;
+    /** Same context changed on disk. New identities should use a different key. */
+    invalidate(key: string): void;
+    /** Initial snapshot plus coalesced updates; no retained event queue. */
+    follow(key: string | (() => string), signal: AbortSignal): AsyncIterable<LocalAgentModelDirectory>;
+    dispose(): void;
+}
+//# sourceMappingURL=model-directory.d.ts.map

package/lib/types/model-directory.js

@@ -0,0 +1,192 @@
+import { statSync } from 'node:fs';
+import { cliExecutableIdentity } from './cli-version.js';
+/** File metadata only: credential bytes and URL credentials never enter cache keys. */
+export function modelDirectoryContextKey(context) {
+    const files = context.files.map(path => {
+        try {
+            const stat = statSync(path);
+            return [path, stat.ino, stat.mtimeMs, stat.ctimeMs, stat.size];
+        }
+        catch {
+            return [path, 'absent'];
+        }
+    });
+    let endpoint;
+    if (context.endpoint !== undefined) {
+        try {
+            const url = new URL(context.endpoint);
+            endpoint = url.origin + url.pathname;
+        }
+        catch {
+            endpoint = 'invalid-endpoint';
+        }
+    }
+    return JSON.stringify({ provider: context.provider, homeDir: context.homeDir, cwd: context.cwd, cli: cliExecutableIdentity(context.cli), files, endpoint });
+}
+/** Native facts win; configured candidates and historical suggestions retain provenance. */
+export function extendModelDirectory(directory, configuration, history) {
+    const entries = new Map(directory.entries.map(entry => [entry.value, entry]));
+    for (const [source, values] of [['configuration', configuration], ['history', history]]) {
+        for (const candidate of values) {
+            const value = candidate?.trim();
+            if (value !== undefined && value !== '' && !entries.has(value))
+                entries.set(value, { value, label: value, source });
+        }
+    }
+    return { ...directory, entries: [...entries.values()] };
+}
+/**
+ * Shared mechanics only: providers own discovery and supply a non-secret
+ * context key covering scope, endpoint, configuration, cwd and CLI identity.
+ * Failed refreshes keep the last successful data. Invalidation fences stale
+ * in-flight replies, including account changes while a probe is running.
+ */
+export class ModelDirectoryCache {
+    options;
+    entries = new Map();
+    revision = 0;
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    now() { return (this.options.now ?? Date.now)(); }
+    entry(key) {
+        let entry = this.entries.get(key);
+        if (entry === undefined) {
+            entry = {
+                snapshot: { entries: [], complete: false, customInput: true, status: 'loading', refreshing: false, revision: ++this.revision },
+                nextAttemptAt: 0, generation: 0, listeners: new Set(),
+            };
+            this.entries.set(key, entry);
+        }
+        // Configuration and credential rotations produce new identities. Retain
+        // active subscriptions/probes, but do not accumulate every old identity.
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        for (const [candidate, value] of this.entries) {
+            if (this.entries.size <= Math.max(1, this.options.maxEntries ?? 128))
+                break;
+            if (candidate !== key && value.listeners.size === 0 && value.pending === undefined)
+                this.entries.delete(candidate);
+        }
+        return entry;
+    }
+    publish(entry, snapshot) {
+        entry.snapshot = { ...snapshot, revision: ++this.revision };
+        for (const listener of entry.listeners)
+            listener();
+    }
+    read(key) {
+        const entry = this.entry(key);
+        if (!this.disposed && this.now() >= entry.nextAttemptAt)
+            void this.refresh(key);
+        return entry.snapshot;
+    }
+    refresh(key) {
+        const entry = this.entry(key);
+        if (this.disposed)
+            return Promise.resolve(entry.snapshot);
+        if (entry.pending !== undefined)
+            return entry.pending;
+        const generation = ++entry.generation;
+        const controller = new AbortController();
+        entry.controller = controller;
+        this.publish(entry, {
+            ...entry.snapshot, refreshing: true,
+            status: entry.snapshot.refreshedAt === undefined ? 'loading' : 'stale',
+        });
+        const pending = Promise.resolve().then(() => this.options.load(key, controller.signal)).then(data => {
+            if (this.disposed || generation !== entry.generation)
+                return entry.snapshot;
+            entry.nextAttemptAt = this.now() + (this.options.ttlMs ?? 300_000);
+            this.publish(entry, {
+                ...data, status: data.unsupported === true ? 'unsupported' : 'ready',
+                refreshing: false, refreshedAt: this.now(),
+            });
+            return entry.snapshot;
+        }, error => {
+            if (this.disposed || generation !== entry.generation)
+                return entry.snapshot;
+            this.options.onError?.(error);
+            entry.nextAttemptAt = this.now() + (this.options.retryMs ?? this.options.ttlMs ?? 30_000);
+            this.publish(entry, {
+                ...entry.snapshot, status: entry.snapshot.refreshedAt === undefined ? 'error' : 'stale',
+                refreshing: false, reason: error instanceof Error ? error.message : 'Model discovery failed',
+            });
+            return entry.snapshot;
+        }).finally(() => {
+            if (generation === entry.generation) {
+                delete entry.pending;
+                delete entry.controller;
+            }
+        });
+        entry.pending = pending;
+        return pending;
+    }
+    /** Same context changed on disk. New identities should use a different key. */
+    invalidate(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined || this.disposed)
+            return;
+        entry.generation++;
+        entry.controller?.abort();
+        delete entry.pending;
+        delete entry.controller;
+        entry.nextAttemptAt = 0;
+        this.publish(entry, {
+            ...entry.snapshot, refreshing: false,
+            status: entry.snapshot.refreshedAt === undefined ? 'loading' : 'stale',
+        });
+        if (entry.listeners.size > 0)
+            void this.refresh(key);
+    }
+    /** Initial snapshot plus coalesced updates; no retained event queue. */
+    async *follow(key, signal) {
+        if (signal.aborted || this.disposed)
+            return;
+        const currentKey = () => typeof key === 'string' ? key : key();
+        let entry = this.entry(currentKey());
+        let wake;
+        const notify = () => { wake?.(); wake = undefined; };
+        entry.listeners.add(notify);
+        signal.addEventListener('abort', notify, { once: true });
+        // Re-check native config/auth file identities and TTL while a picker stays open.
+        const timer = setInterval(notify, 1_000);
+        timer.unref();
+        let revision = -1;
+        try {
+            while (!signal.aborted && !this.disposed) {
+                const activeKey = currentKey();
+                const active = this.entry(activeKey);
+                if (active !== entry) {
+                    entry.listeners.delete(notify);
+                    entry = active;
+                    entry.listeners.add(notify);
+                }
+                const snapshot = this.read(activeKey);
+                if (snapshot.revision !== revision) {
+                    revision = snapshot.revision;
+                    yield snapshot;
+                }
+                else {
+                    await new Promise(resolve => { wake = resolve; });
+                }
+            }
+        }
+        finally {
+            entry.listeners.delete(notify);
+            signal.removeEventListener('abort', notify);
+            clearInterval(timer);
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        for (const entry of this.entries.values()) {
+            entry.generation++;
+            entry.controller?.abort();
+            for (const listener of entry.listeners)
+                listener();
+        }
+        this.entries.clear();
+    }
+}

package/lib/types/prepared-members.d.ts

@@ -0,0 +1,15 @@
+import type { LocalAgentMemberBinding } from './types.ts';
+export interface PreparedMemberRecord {
+    version: 1;
+    binding: LocalAgentMemberBinding;
+    phase: 'preparing' | 'ready' | 'starting' | 'used';
+}
+/** Preparation identity survives restart independently of a not-yet-created native transcript. */
+export declare class PreparedMembers {
+    private readonly directory;
+    constructor(directory: string);
+    private path;
+    read(id: string): PreparedMemberRecord | undefined;
+    write(record: PreparedMemberRecord): void;
+}
+//# sourceMappingURL=prepared-members.d.ts.map

package/lib/types/prepared-members.js

@@ -0,0 +1,61 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Preparation identity survives restart independently of a not-yet-created native transcript. */
+export class PreparedMembers {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    path(id) { return join(this.directory, createHash('sha256').update(id).digest('hex') + '.json'); }
+    read(id) {
+        let text;
+        try {
+            text = readFileSync(this.path(id), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        const raw = JSON.parse(text);
+        if (raw?.version !== 1 || !['preparing', 'ready', 'starting', 'used'].includes(raw.phase)
+            || raw.binding?.childSessionId !== id || ['provider', 'parentSessionId', 'cwd'].some(key => typeof raw.binding[key] !== 'string')
+            || ['scope', 'model', 'effort', 'configurationLock'].some(key => raw.binding[key] !== undefined && typeof raw.binding[key] !== 'string')) {
+            throw new Error('Invalid prepared member identity; native admission is blocked');
+        }
+        return raw;
+    }
+    write(record) {
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const path = this.path(record.binding.childSessionId);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            const fd = openSync(temporary, 'wx', 0o600);
+            try {
+                writeFileSync(fd, JSON.stringify(record));
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(temporary, path);
+            const directory = openSync(this.directory, 'r');
+            try {
+                fsyncSync(directory);
+            }
+            finally {
+                closeSync(directory);
+            }
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+}

package/lib/types/settings-face.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Dual-line settings face for the family providers: one read/watch contract
+ * over the two host settings generations, probed by capability, never by
+ * version.
+ *
+ * - 0.1.5: `settings.register(ns, schema, { base })` returns a namespace scope
+ *   whose `get()` resolves schema defaults ← composition base ← user layer and
+ *   whose `watch` round-trips every write. That scope IS the face.
+ * - 0.1.7-rc.1 (`SettingsForms`): the settings fields live on the provider's
+ *   own plugin Config as `.volatile()` fields — writes ride the profile patch,
+ *   the running fiber's Volatile references track them without a remount, and
+ *   `settings/document-updated` is the change channel. `get()` unwraps the
+ *   Volatile references; `watch` re-reads on a matching namespace update.
+ *
+ * The legacy arm keeps old `settings.yaml` values working untouched; on rc.1
+ * the official one-shot import moves the same-named section into the row's
+ * config, which the volatile read then serves.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The resolved settings document one provider consumes. */
+export interface SettingsFace<T> {
+    /** Read the current resolved settings. */
+    get(): T;
+    /**
+     * Observe settings replacements. The listener receives the freshly re-read
+     * value on every change (own writes round-trip too, exactly like the 0.1.5
+     * namespace scope).
+     * @returns the unwatch disposer.
+     */
+    watch(listener: (next: T) => void): () => void;
+}
+/**
+ * Unwrap one volatile config reference (rc.1 wraps each `.volatile()` field
+ * in a `{ get() }` reference) or pass a plain value through (0.1.5's
+ * schemastery has no `.volatile()`, so the field resolves bare there).
+ * @param field - the config field as the fiber received it.
+ * @returns the plain value.
+ */
+export declare function vol<T>(field: T | {
+    get(): T;
+}): T;
+/**
+ * Resolve the provider's settings face for the host line actually serving.
+ * @param ctx - the provider's plugin context (`settings` injected).
+ * @param options.namespace - the settings namespace; identical to the plugin
+ *   row id, which is what rc.1's `settings/document-updated` emits and what
+ *   the rc.1 legacy import maps the old settings.yaml section onto.
+ * @param options.legacySchema - the 0.1.5 namespace schema (plain fields).
+ * @param options.legacyBase - the 0.1.5 composition base, built from the
+ *   deployment's plugin config exactly as before.
+ * @param options.read - the rc.1 read: unwrap the row config's volatile
+ *   fields into the same resolved shape.
+ * @returns the face both arms share.
+ */
+export declare function settingsFace<T>(ctx: Context, options: {
+    namespace: string;
+    legacySchema: unknown;
+    legacyBase: Record<string, unknown>;
+    read: () => T;
+}): SettingsFace<T>;
+//# sourceMappingURL=settings-face.d.ts.map

package/lib/types/settings-face.js

@@ -0,0 +1,61 @@
+/**
+ * Dual-line settings face for the family providers: one read/watch contract
+ * over the two host settings generations, probed by capability, never by
+ * version.
+ *
+ * - 0.1.5: `settings.register(ns, schema, { base })` returns a namespace scope
+ *   whose `get()` resolves schema defaults ← composition base ← user layer and
+ *   whose `watch` round-trips every write. That scope IS the face.
+ * - 0.1.7-rc.1 (`SettingsForms`): the settings fields live on the provider's
+ *   own plugin Config as `.volatile()` fields — writes ride the profile patch,
+ *   the running fiber's Volatile references track them without a remount, and
+ *   `settings/document-updated` is the change channel. `get()` unwraps the
+ *   Volatile references; `watch` re-reads on a matching namespace update.
+ *
+ * The legacy arm keeps old `settings.yaml` values working untouched; on rc.1
+ * the official one-shot import moves the same-named section into the row's
+ * config, which the volatile read then serves.
+ */
+/**
+ * Unwrap one volatile config reference (rc.1 wraps each `.volatile()` field
+ * in a `{ get() }` reference) or pass a plain value through (0.1.5's
+ * schemastery has no `.volatile()`, so the field resolves bare there).
+ * @param field - the config field as the fiber received it.
+ * @returns the plain value.
+ */
+export function vol(field) {
+    if (field !== null && typeof field === 'object' && typeof field.get === 'function') {
+        return field.get();
+    }
+    return field;
+}
+/**
+ * Resolve the provider's settings face for the host line actually serving.
+ * @param ctx - the provider's plugin context (`settings` injected).
+ * @param options.namespace - the settings namespace; identical to the plugin
+ *   row id, which is what rc.1's `settings/document-updated` emits and what
+ *   the rc.1 legacy import maps the old settings.yaml section onto.
+ * @param options.legacySchema - the 0.1.5 namespace schema (plain fields).
+ * @param options.legacyBase - the 0.1.5 composition base, built from the
+ *   deployment's plugin config exactly as before.
+ * @param options.read - the rc.1 read: unwrap the row config's volatile
+ *   fields into the same resolved shape.
+ * @returns the face both arms share.
+ */
+export function settingsFace(ctx, options) {
+    const legacy = ctx.get('settings');
+    if (legacy !== undefined && typeof legacy.register === 'function') {
+        return legacy.register(options.namespace, options.legacySchema, { base: options.legacyBase });
+    }
+    return {
+        get: options.read,
+        watch: (listener) => {
+            const dispose = ctx.on('settings/document-updated', (ns) => {
+                if (ns !== options.namespace)
+                    return;
+                listener(options.read());
+            });
+            return () => { dispose(); };
+        },
+    };
+}