@genee/omp-opsx-addon 0.7.0 → 0.9.0

package/lib/concurrency-writer.ts

@@ -0,0 +1,894 @@
+/**
+ * Concurrency writer — the writing half of `provider-concurrency-control`
+ * (spec Requirement「并发上限写入与跨进程单写者」, design D5/D6, tasks 4.1–4.9).
+ *
+ * Three responsibilities, all deterministic given their injected ports:
+ *
+ *  1. **共享现值读取** — {@link readManagedLimits} reads
+ *     `providers.maxInFlightRequests` out of the config root `config.yml`
+ *     (YAML) and reports the current integer per managed provider (`null` =
+ *     no value on disk).
+ *  2. **门限 + 读-合并-写** — {@link shouldWriteLimit} enforces
+ *     `|new − old| >= 1 && 距上次成功写入 > concurrency_write_min_interval_ms`;
+ *     {@link writeManagedLimit} then does a locked read-merge-write that
+ *     splices *only* the target provider's value textually, so every other
+ *     key (other providers, `providers.*`, `task.*`, `retry.*`, comments,
+ *     formatting) stays byte-identical, and lands the result with tmp+rename.
+ *     The `<file>.lock` protocol mirrors `lib/usage-poller.ts`
+ *     (`openSync(lockPath,'wx')`, stale > 5s stealable, in-lock re-read,
+ *     readers lock-free).
+ *  3. **跨进程单写者** — {@link createLease} takes writer eligibility:
+ *     Redis `SET key owner NX PX ttl` over the existing
+ *     `RedisClient.pipeline()` command surface, degrading to a config-root
+ *     file lease (`O_EXCL` atomic create + mtime expiry takeover), and finally
+ *     to read-only + warn when *neither* is available (`held: false`,
+ *     `mode: 'readonly'` — the caller MUST NOT write, MUST NOT fall back to
+ *     unlimited).
+ *     {@link resolveTakeoverStart} gives the takeover/`L` start value: the
+ *     shared value clamped to `[floor, ceiling]` — never this process's
+ *     `initial`/`concurrency_start`.
+ *
+ * Every IO touchpoint is an injected port (file system / redis / settings) so
+ * the module and its tests run without real IO; {@link nodeWriterFileSystem} is
+ * the production file-system adapter and the assembly layer may pass it
+ * explicitly or substitute its own.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, writeSync } from 'fs';
+import { dirname } from 'path';
+import { YAML } from 'bun';
+import { clampLimit } from './concurrency-tuner.js';
+import { canonicalizeProvider } from './usage-resolver.js';
+
+/** Sink for degradation notices; defaults to a no-op. */
+export type Warn = (message: string) => void;
+
+const NO_WARN: Warn = () => {};
+
+/** `<file>.lock` staleness threshold — same value/protocol as `lib/usage-poller.ts`. */
+export const WRITE_LOCK_STALE_MS = 5_000;
+/** Lease TTL used when the caller passes a non-positive `ttlMs`. */
+export const DEFAULT_LEASE_TTL_MS = 60_000;
+
+const WRITE_LOCK_RETRY_MS = 10;
+const WRITE_LOCK_ATTEMPTS = 5;
+const FILE_LEASE_ATTEMPTS = 3;
+
+function message(err: unknown): string {
+    return err instanceof Error ? err.message : String(err);
+}
+
+function codeOf(err: unknown): string | null {
+    const code = (err as { code?: unknown } | null)?.code;
+    return typeof code === 'string' ? code : null;
+}
+
+function sleepSync(ms: number): void {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    } catch {
+        const until = Date.now() + ms;
+        while (Date.now() < until) { /* spin */ }
+    }
+}
+
+// ── injectable file system port ─────────────────────────────────────
+
+/**
+ * The file-system surface this module needs. `openExclusive` MUST be an atomic
+ * exclusive create and MUST throw an error with `code === 'EEXIST'` when the
+ * path already exists — any other failure code means the file system cannot do
+ * atomic creation at all, which downgrades the lease to read-only.
+ */
+export interface WriterFileSystemPort {
+    /** File contents, or `null` when unreadable/absent. */
+    readFile(path: string): string | null;
+    writeFile(path: string, content: string): void;
+    rename(from: string, to: string): void;
+    /** Remove a file, ignoring absence. */
+    remove(path: string): void;
+    /** Best-effort recursive directory creation. */
+    ensureDir(dir: string): void;
+    /** `O_EXCL` create + write; throws `EEXIST` when held. */
+    openExclusive(path: string, contents: string): void;
+    /** mtime in epoch ms, or `null` when absent. */
+    statMtimeMs(path: string): number | null;
+    /** Set mtime (lease renewal). */
+    touch(path: string, mtimeMs: number): void;
+}
+
+/**
+ * Production file-system adapter (node `fs`).
+ *
+ * The mutations here are synchronous (`writeFileSync` / `renameSync` /
+ * `mkdirSync`). Known tradeoff, accepted for now: the concurrency control loop
+ * writes at most once per evaluation window (≥ 30 s apart, and only when the
+ * body actually changed), and a measured `writeFile` + `rename` of the body
+ * costs ≈0.10 ms median / ≈0.12 ms p90 (255-byte state file) and ≈0.09 ms /
+ * ≈0.14 ms (config patch) on the target machine — far below the cadence it
+ * sits on, so the render tick's fire-and-forget call is not worth an async IO
+ * pipeline (whose blast radius covers the whole writer/lease protocol).
+ * Revisit if the body grows, or the loop gains a sub-second cadence.
+ */
+export const nodeWriterFileSystem: WriterFileSystemPort = {
+    readFile(path) {
+        try {
+            return readFileSync(path, 'utf-8');
+        } catch {
+            return null;
+        }
+    },
+    writeFile(path, content) {
+        writeFileSync(path, content, 'utf-8');
+    },
+    rename(from, to) {
+        renameSync(from, to);
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+    ensureDir(dir) {
+        mkdirSync(dir, { recursive: true });
+    },
+    openExclusive(path, contents) {
+        const fd = openSync(path, 'wx');
+        try {
+            writeSync(fd, contents);
+        } catch (err) {
+            try { closeSync(fd); } catch { /* ignore */ }
+            try { rmSync(path, { force: true }); } catch { /* ignore */ }
+            throw err;
+        }
+        closeSync(fd);
+    },
+    statMtimeMs(path) {
+        try {
+            return statSync(path).mtimeMs;
+        } catch {
+            return null;
+        }
+    },
+    touch(path, mtimeMs) {
+        const at = new Date(mtimeMs);
+        utimesSync(path, at, at);
+    },
+};
+
+// ── shared-value read (4.1) ─────────────────────────────────────────
+
+/** Current shared limit for one managed provider (`null` = no value on disk). */
+export interface ManagedLimitValue {
+    provider: string;
+    value: number | null;
+}
+
+/**
+ * Canonical provider → current *integer* value found in
+ * `providers.maxInFlightRequests`. Values that are not positive integers
+ * (floats, strings, nulls) are treated as absent — they cannot serve as a
+ * write baseline.
+ */
+function diskLimitValues(text: string, warn: Warn = NO_WARN): Record<string, number> {
+    let parsed: unknown;
+    try {
+        parsed = YAML.parse(text);
+    } catch (err) {
+        warn(`[omp-opsx-addon] concurrency: config is not readable as YAML (${message(err)}); treating limits as absent`);
+        return {};
+    }
+    const limits = (parsed as { providers?: { maxInFlightRequests?: unknown } } | null | undefined)
+        ?.providers?.maxInFlightRequests;
+    if (!limits || typeof limits !== 'object' || Array.isArray(limits)) return {};
+    const out: Record<string, number> = {};
+    for (const [id, value] of Object.entries(limits as Record<string, unknown>)) {
+        if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) continue;
+        const canonical = canonicalizeProvider(id.trim());
+        if (!canonical) continue;
+        out[canonical] = value;
+    }
+    return out;
+}
+
+/**
+ * Read the current shared value for each requested provider out of
+ * `configPath` (`providers.maxInFlightRequests`).
+ *
+ * Returns one row per requested provider, in request order, with the
+ * canonicalized provider id; `value: null` means「无现值」(key absent, or the
+ * entry is not a positive integer). A missing/unparseable config yields all
+ * `null`s — callers treat that as `initial`/`concurrency_start`, never as
+ * unlimited.
+ */
+export function readManagedLimits(
+    configPath: string,
+    providers: readonly string[],
+    fileSystem: WriterFileSystemPort = nodeWriterFileSystem,
+    warn: Warn = NO_WARN,
+): ManagedLimitValue[] {
+    const text = fileSystem.readFile(configPath);
+    if (text === null) return providers.map((provider) => ({ provider: canonicalizeProvider(provider.trim()), value: null }));
+    const parsedValues = diskLimitValues(text, warn);
+    return providers.map((provider) => {
+        const canonical = canonicalizeProvider(provider.trim());
+        const value = parsedValues[canonical];
+        return { provider: canonical, value: typeof value === 'number' ? value : null };
+    });
+}
+
+/**
+ * Merge one provider's new limit into the **complete** per-provider map.
+ * `providers.maxInFlightRequests` is a whole-key override on the host side, so
+ * every caller MUST pass the full map (this is the map that goes to
+ * `settings.override` and to {@link writeManagedLimit}).
+ */
+export function buildMergedMap(
+    current: Record<string, number>,
+    provider: string,
+    value: number,
+): Record<string, number> {
+    const key = canonicalizeProvider(provider.trim()) || provider.trim();
+    return { ...current, [key]: value };
+}
+
+// ── write threshold (4.2) ───────────────────────────────────────────
+
+export interface WriteGateArgs {
+    /** Target `L` for this evaluation window. */
+    newValue: number;
+    /** Shared current value; `null` when the provider has no key yet. */
+    oldValue: number | null;
+    /** Epoch ms of this provider's last successful write (`0`/`null` = never). */
+    lastWriteAt: number | null;
+    /** Current epoch ms (injected clock). */
+    now: number;
+    /** `concurrency_write_min_interval_ms`. */
+    minIntervalMs: number;
+}
+
+export interface WriteGateDecision {
+    write: boolean;
+    /** `'unchanged'` = `|Δ| < 1`; `'too-soon'` = within the write interval. */
+    reason?: 'unchanged' | 'too-soon';
+}
+
+/**
+ * Write gate: a write needs `|new − old| >= 1` **and** more than
+ * `minIntervalMs` since this provider's last successful write. A provider with
+ * no current value (`oldValue === null`) has nothing to compare against, and a
+ * provider never written has no interval to respect — both pass the gate.
+ */
+export function shouldWriteLimit(args: WriteGateArgs): WriteGateDecision {
+    const { newValue, oldValue, lastWriteAt, now, minIntervalMs } = args;
+    if (oldValue !== null && Math.abs(newValue - oldValue) < 1) return { write: false, reason: 'unchanged' };
+    const interval = Number.isFinite(minIntervalMs) && minIntervalMs > 0 ? minIntervalMs : 0;
+    if (lastWriteAt !== null && lastWriteAt > 0 && now - lastWriteAt <= interval) return { write: false, reason: 'too-soon' };
+    return { write: true };
+}
+
+/**
+ * `L` start value for a process that just acquired (or took over) the lease:
+ * the shared value clamped to `[floor, ceiling]`, falling back to
+ * `concurrency_start` only when no shared value exists. This is what keeps a
+ * handover from resurrecting the new writer's stale local trajectory.
+ */
+export function resolveTakeoverStart(
+    sharedValue: number | null,
+    options: { floor: number; ceiling: number; start: number },
+): number {
+    const base = sharedValue === null ? options.start : sharedValue;
+    return clampLimit(base, options.floor, options.ceiling);
+}
+
+// ── block splice: write only the target provider's value (4.3/4.8) ──
+
+interface LimitEntry {
+    /** Entry line index. */
+    line: number;
+    /** Leading whitespace of the entry line. */
+    indent: string;
+    /** Raw key text as written (quotes preserved). */
+    rawId: string;
+    /** Canonical provider id. */
+    canonical: string;
+    /** Index where the value text starts / ends on the entry line. */
+    valueStart: number;
+    valueEnd: number;
+}
+
+interface LimitBlock {
+    /** `providers:` line index / indent, or -1 when the key is absent. */
+    providersLine: number;
+    providersIndent: string;
+    /** Insertion point just past the last non-blank line of the `providers` block. */
+    providersEnd: number;
+    /** `maxInFlightRequests:` line index, or -1 when absent. */
+    keyLine: number;
+    keyIndent: string;
+    /** Text after the colon when the mapping is inline (`{}` / `{a: 1}`). */
+    inline: string;
+    entries: LimitEntry[];
+    /** Insertion point just past the last non-blank line of the mapping block. */
+    end: number;
+}
+
+const KEY_LINE_RE = /^(\s*)([^#\s][^:]*?)\s*:(.*)$/;
+// Entry line: indent, key, separator, value token, untouched remainder (e.g. a
+// trailing `# comment`) — only the value token is ever replaced.
+const ENTRY_RE = /^(\s*)([^#\s][^:]*?)(\s*:\s*)(\S*)(.*)$/;
+
+function indentWidth(line: string): number {
+    const m = /^\s*/.exec(line);
+    return m ? m[0].length : 0;
+}
+
+/** Locate `providers.maxInFlightRequests` and its entries in the raw text. */
+function parseLimitBlock(text: string): LimitBlock {
+    const lines = text.split('\n');
+    const block: LimitBlock = {
+        providersLine: -1,
+        providersIndent: '',
+        providersEnd: 0,
+        keyLine: -1,
+        keyIndent: '',
+        inline: '',
+        entries: [],
+        end: 0,
+    };
+
+    for (let i = 0; i < lines.length; i++) {
+        const m = KEY_LINE_RE.exec(lines[i]);
+        if (!m || m[1].length !== 0 || m[2].trim() !== 'providers') continue;
+        block.providersLine = i;
+        block.providersIndent = m[1];
+        // Last non-blank line of the `providers` block (its children have a deeper indent).
+        block.providersEnd = i + 1;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (indentWidth(lines[j]) <= 0 && lines[j].trim() !== '') break;
+            if (lines[j].trim() !== '') block.providersEnd = j + 1;
+        }
+        break;
+    }
+    if (block.providersLine < 0) return block;
+
+    for (let i = block.providersLine + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() !== '' && indentWidth(line) <= block.providersIndent.length) break;
+        const m = KEY_LINE_RE.exec(line);
+        if (!m || m[2].trim() !== 'maxInFlightRequests') continue;
+        block.keyLine = i;
+        block.keyIndent = m[1];
+        block.inline = m[3].trim();
+        block.end = i + 1;
+        for (let j = i + 1; j < lines.length; j++) {
+            const entryLine = lines[j];
+            if (entryLine.trim() !== '' && indentWidth(entryLine) <= m[1].length) break;
+            if (entryLine.trim() === '') continue;
+            block.end = j + 1;
+            const em = ENTRY_RE.exec(entryLine);
+            if (!em) continue; // comment or nested mapping — preserved verbatim, not an entry
+            const rawId = em[2].trim();
+            const valueStart = em[1].length + em[2].length + em[3].length;
+            const valueEnd = valueStart + em[4].length;
+            block.entries.push({
+                line: j,
+                indent: em[1],
+                rawId,
+                canonical: canonicalizeProvider(rawId.replace(/^["']|["']$/g, '').trim()),
+                valueStart,
+                valueEnd,
+            });
+        }
+        break;
+    }
+    return block;
+}
+
+/**
+ * Splice `values` into the limits mapping of `text`, returning the new text.
+ * Existing entry lines are rewritten **only** when their value actually
+ * changes (so untouched providers stay byte-identical); new providers are
+ * appended at the end of the mapping; a block/inline/absent mapping is
+ * normalized to block style. Nothing outside the mapping is touched.
+ */
+function renderLimitBlock(text: string, block: LimitBlock, values: Map<string, number>): string {
+    const lines = text.split('\n');
+    const childIndent = `${block.keyIndent}  `;
+
+    // Mapping key absent entirely → create it (and `providers:` when needed).
+    if (block.keyLine < 0) {
+        const entries = [...values].map(([id, value]) => `${childIndent}  ${id}: ${value}`);
+        const created = [`${childIndent}maxInFlightRequests:`, ...entries];
+        if (block.providersLine >= 0) {
+            lines.splice(block.providersEnd, 0, ...created);
+            return lines.join('\n');
+        }
+        const at = lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
+        const sep = lines.length > 0 && lines[0] !== '' ? [''] : [];
+        lines.splice(at, 0, ...sep, 'providers:', ...created);
+        return lines.join('\n');
+    }
+
+    // Inline mapping (`maxInFlightRequests: {}` / `{a: 1}`): expand to block
+    // style so entries can be updated textually. Values are preserved; only
+    // this one line's formatting changes.
+    if (block.inline !== '') {
+        const entries = [...values].map(([id, value]) => `${childIndent}${id}: ${value}`);
+        lines.splice(block.keyLine, 1, `${block.keyIndent}maxInFlightRequests:`, ...entries);
+        return lines.join('\n');
+    }
+
+    const present = new Set(block.entries.map((entry) => entry.canonical));
+    for (const entry of block.entries) {
+        const value = values.get(entry.canonical);
+        if (value === undefined) continue;
+        const line = lines[entry.line];
+        const rebuilt = `${line.slice(0, entry.valueStart)}${value}${line.slice(entry.valueEnd)}`;
+        if (rebuilt !== line) lines[entry.line] = rebuilt;
+    }
+
+    const extra = [...values].filter(([id]) => !present.has(id));
+    if (extra.length > 0) {
+        const entryIndent = block.entries.length > 0 ? block.entries[0].indent : childIndent;
+        const appended = extra.map(([id, value]) => `${entryIndent}${id}: ${value}`);
+        lines.splice(block.end, 0, ...appended);
+    }
+    return lines.join('\n');
+}
+
+// ── cross-process write lock, mirroring lib/usage-poller.ts (4.3) ───
+
+type LockOutcome = { release: () => void } | { reason: 'lock-busy' | 'lock-unavailable' };
+
+/**
+ * Exclusive `<file>.lock` acquire: `O_EXCL` create, steal locks older than
+ * {@link WRITE_LOCK_STALE_MS}, retry briefly while a live holder exists (the
+ * lock queues plugin writers; the host's own writes converge via read-merge-write
+ * + atomic rename instead of this lock). Returns a release fn, or the reason
+ * the caller must skip the write.
+ */
+function acquireWriteLock(
+    lockPath: string,
+    fileSystem: WriterFileSystemPort,
+    now: number,
+    sleep: (ms: number) => void,
+): LockOutcome {
+    for (let attempt = 0; attempt < WRITE_LOCK_ATTEMPTS; attempt++) {
+        try {
+            fileSystem.openExclusive(lockPath, String(process.pid));
+            return {
+                release: () => {
+                    try { fileSystem.remove(lockPath); } catch { /* already gone */ }
+                },
+            };
+        } catch (err) {
+            if (codeOf(err) !== 'EEXIST') {
+                // Not contention: this file system cannot do atomic creation.
+                return { reason: 'lock-unavailable' };
+            }
+            const mtime = fileSystem.statMtimeMs(lockPath);
+            if (mtime === null) continue; // lock vanished between create and stat — retry now
+            if (now - mtime > WRITE_LOCK_STALE_MS) {
+                try { fileSystem.remove(lockPath); } catch { /* raced */ }
+                continue;
+            }
+            if (attempt < WRITE_LOCK_ATTEMPTS - 1) sleep(WRITE_LOCK_RETRY_MS);
+        }
+    }
+    return { reason: 'lock-busy' };
+}
+
+// ── read-merge-write (4.3) + settings hot apply (4.4) ───────────────
+
+export interface WriteManagedLimitArgs {
+    /** Config root `config.yml`. */
+    configPath: string;
+    /** The one provider this write changes. */
+    provider: string;
+    /**
+     * Intended map (see {@link buildMergedMap}). **Only `merged[provider]` is
+     * used**: every other key comes from the in-lock re-read, so a stale caller
+     * snapshot cannot roll back a peer's change to another provider.
+     */
+    merged: Record<string, number>;
+    /** Write-lock path; defaults to `<configPath>.lock`. */
+    lockPath?: string;
+    /** Epoch ms used for lock staleness (tests inject it); defaults to `Date.now()`. */
+    now?: number;
+    fileSystem?: WriterFileSystemPort;
+    /** Sleep used between lock retries; defaults to a synchronous sleep. */
+    sleep?: (ms: number) => void;
+    warn?: Warn;
+}
+
+export interface WriteManagedLimitResult {
+    written: boolean;
+    /** Why nothing was written: `unchanged` | `config-missing` | `invalid-provider` | `invalid-value` | `lock-busy` | `lock-unavailable` | `write-failed`. */
+    reason?: string;
+    /** The merged map that was persisted (canonical provider → value). */
+    limits?: Record<string, number>;
+}
+
+let writeSeq = 0;
+
+/**
+ * Locked atomic read-merge-write of `providers.maxInFlightRequests`.
+ *
+ * Inside the lock the file is re-read and only the **target** provider's value
+ * is taken from the caller; every other key keeps its freshly-read on-disk
+ * value. The caller's map is a snapshot from earlier in the evaluation tick, so
+ * applying it wholesale would roll back a peer's concurrent change to a
+ * *different* provider — the whole point of read-merge-write. Only the changed
+ * entry lines are rewritten, so the rest of the file stays byte-identical and a
+ * host write to another key between our read and our write is never lost. The
+ * payload lands via `tmp` + `rename`. When the merge yields no textual change,
+ * nothing is written at all (no tmp file, no mtime bump).
+ */
+export function writeManagedLimit(args: WriteManagedLimitArgs): WriteManagedLimitResult {
+    const fileSystem = args.fileSystem ?? nodeWriterFileSystem;
+    const warn = args.warn ?? NO_WARN;
+    const configPath = args.configPath;
+    const now = args.now ?? Date.now();
+
+    if (fileSystem.readFile(configPath) === null) {
+        warn(`[omp-opsx-addon] concurrency: config ${configPath} is not readable; limit write skipped`);
+        return { written: false, reason: 'config-missing' };
+    }
+
+    const lock = acquireWriteLock(args.lockPath ?? `${configPath}.lock`, fileSystem, now, args.sleep ?? sleepSync);
+    if ('reason' in lock) {
+        warn(
+            lock.reason === 'lock-busy'
+                ? `[omp-opsx-addon] concurrency: write lock ${args.lockPath ?? `${configPath}.lock`} is held; limit write skipped (retried next window)`
+                : `[omp-opsx-addon] concurrency: atomic lock creation unavailable; limit write skipped`,
+        );
+        return { written: false, reason: lock.reason };
+    }
+
+    try {
+        const current = fileSystem.readFile(configPath);
+        if (current === null) {
+            warn(`[omp-opsx-addon] concurrency: config ${configPath} became unreadable; limit write skipped`);
+            return { written: false, reason: 'config-missing' };
+        }
+        const target = canonicalizeProvider(String(args.provider ?? '').trim());
+        if (!target) {
+            warn('[omp-opsx-addon] concurrency: limit write skipped — no target provider given');
+            return { written: false, reason: 'invalid-provider' };
+        }
+        const targetValue = (args.merged ?? {})[target];
+        if (typeof targetValue !== 'number' || !Number.isSafeInteger(targetValue) || targetValue < 1) {
+            warn(`[omp-opsx-addon] concurrency: skipping ${target}: merged value ${JSON.stringify(targetValue)} is not a positive integer`);
+            return { written: false, reason: 'invalid-value' };
+        }
+        const values = new Map<string, number>(Object.entries(diskLimitValues(current)));
+        values.set(target, targetValue);
+
+        const block = parseLimitBlock(current);
+        const next = renderLimitBlock(current, block, values);
+        const limits = Object.fromEntries(values);
+        if (next === current) return { written: false, reason: 'unchanged', limits };
+
+        fileSystem.ensureDir(dirname(configPath));
+        const tmp = `${configPath}.tmp-${process.pid}-${writeSeq++}`;
+        fileSystem.writeFile(tmp, next);
+        fileSystem.rename(tmp, configPath);
+        return { written: true, limits };
+    } catch (err) {
+        warn(`[omp-opsx-addon] concurrency: limit write to ${configPath} failed (${message(err)}); keeping the previous value`);
+        return { written: false, reason: 'write-failed' };
+    } finally {
+        lock.release();
+    }
+}
+
+/**
+ * Injected host settings port (`pi.pi.settings`), narrowed to the call we make.
+ */
+export interface SettingsPort {
+    override(path: string, value: unknown): void;
+}
+
+export interface ApplyLimitArgs {
+    settings: SettingsPort;
+    /** Complete per-provider map (see {@link buildMergedMap}). */
+    merged: Record<string, number>;
+    provider: string;
+    value: number;
+    warn?: Warn;
+}
+
+export interface ApplyLimitResult {
+    applied: boolean;
+    /** `invalid-provider` | `invalid-merged` | `settings-unavailable` | `override-failed`. */
+    reason?: string;
+}
+
+/**
+ * Hot-apply the shared map in this process via
+ * `settings.override('providers.maxInFlightRequests', merged)`.
+ *
+ * `providers.maxInFlightRequests` is a **whole-key override**, so the second
+ * argument MUST be the complete per-provider map — passing only the target
+ * provider's value would clear every other provider's limit. The map is
+ * validated before the call: refusing an all-or-nothing override is safe
+ * (the caller keeps the previous value), while a partial map would silently
+ * make the omitted providers unlimited. When the API throws (host schema moved
+ * on), the persisted config is untouched — the host config watcher picks the
+ * value up — and the failure is warned, never fatal.
+ */
+export function applyLimit(args: ApplyLimitArgs): ApplyLimitResult {
+    const warn = args.warn ?? NO_WARN;
+    const settings = args.settings;
+    if (!settings || typeof settings.override !== 'function') {
+        warn('[omp-opsx-addon] concurrency: settings.override unavailable; skipping hot apply (config file value still applies)');
+        return { applied: false, reason: 'settings-unavailable' };
+    }
+    const provider = canonicalizeProvider(args.provider.trim());
+    if (!provider) {
+        warn('[omp-opsx-addon] concurrency: cannot hot-apply an empty provider id');
+        return { applied: false, reason: 'invalid-provider' };
+    }
+    const payload = buildMergedMap(args.merged ?? {}, provider, args.value);
+    for (const [id, value] of Object.entries(payload)) {
+        if (!id || typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+            warn(`[omp-opsx-addon] concurrency: refusing settings.override — invalid map entry ${JSON.stringify(id)}: ${JSON.stringify(value)}`);
+            return { applied: false, reason: 'invalid-merged' };
+        }
+    }
+    try {
+        settings.override('providers.maxInFlightRequests', payload);
+        return { applied: true };
+    } catch (err) {
+        warn(`[omp-opsx-addon] concurrency: settings.override failed (${message(err)}); the host config watcher will apply the persisted value`);
+        return { applied: false, reason: 'override-failed' };
+    }
+}
+
+// ── writer lease: Redis NX/PX → file lease → read-only (4.5–4.7) ────
+
+/** Redis lease mechanism: satisfied by `lib/usage-redis-client.ts`'s `RedisClient`. */
+export interface LeaseRedisPort {
+    pipeline(commands: string[][]): Promise<readonly unknown[]>;
+}
+
+export type LeaseMode = 'redis' | 'file' | 'readonly';
+
+export interface CreateLeaseArgs {
+    /** Redis client, or `null`/absent to go straight to the file lease. */
+    redis?: LeaseRedisPort | null;
+    /** File-lease path (config root), reused for takeover staleness. */
+    lockPath: string;
+    /** Lease owner: `pid` + process start time. */
+    owner: string;
+    /** `concurrency_lease_ttl_ms`. */
+    ttlMs: number;
+    /** Injected clock (epoch ms). */
+    now: () => number;
+    /** Redis key override; defaults to {@link defaultLeaseKey}. */
+    redisKey?: string;
+    fileSystem?: WriterFileSystemPort;
+    warn?: Warn;
+}
+
+/**
+ * Lease handle. `held`/`mode` are a snapshot of the acquisition; `renew()`
+ * returns `false` once the lease was lost (takeover by a peer, TTL expiry, or a
+ * Redis failure) and the holder MUST stop writing.
+ */
+export interface LeaseHandle {
+    held: boolean;
+    mode: LeaseMode;
+    /**
+     * Owner id of the lease as this process last observed it: its own `owner`
+     * while held, the peer's id when a peer holds it, `null` when unknown
+     * (nobody holds it, or the mechanism cannot report it). Read-only diagnostic
+     * surface — a non-writer's summary shows *who* holds the lease, not just
+     * that it is not this process.
+     */
+    readonly holderId: string | null;
+    renew(): Promise<boolean>;
+    release(): Promise<void>;
+}
+
+const NOT_HELD = (mode: LeaseMode, holderId: string | null = null): LeaseHandle => ({
+    held: false,
+    mode,
+    holderId,
+    renew: async () => false,
+    release: async () => {},
+});
+
+/**
+ * Redis lease key for one config root, derived from the lease file's directory
+ * (`opsx:concurrency:tuner:<configRootHash>`).
+ */
+export function defaultLeaseKey(lockPath: string): string {
+    const root = dirname(lockPath);
+    // FNV-1a 32-bit — stable across processes, no crypto import needed.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < root.length; i++) {
+        hash ^= root.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `opsx:concurrency:tuner:${hash.toString(16).padStart(8, '0')}`;
+}
+
+function redisLease(
+    redis: LeaseRedisPort,
+    key: string,
+    owner: string,
+    ttlMs: number,
+    now: () => number,
+    warn: Warn,
+): LeaseHandle {
+    let held = true;
+    let holderId: string | null = owner;
+    let expiresAt = now() + ttlMs;
+    return {
+        held: true,
+        mode: 'redis',
+        get holderId(): string | null {
+            // While held, the holder is this process; after stepping down the
+            // field carries the last owner we observed (the peer, or `null`).
+            return held ? owner : holderId;
+        },
+        async renew(): Promise<boolean> {
+            if (!held) return false;
+            // Past our own estimate the key may already have been taken over:
+            // renewing then would steal the lease back from a live peer.
+            if (now() >= expiresAt) {
+                held = false;
+                holderId = null;
+                return false;
+            }
+            try {
+                // Compare-then-extend. `SET ... XX` alone would also refresh a
+                // peer's lease if ours expired unnoticed in between.
+                const current = (await redis.pipeline([['GET', key]]))[0];
+                if (current !== owner) {
+                    // Remember *who* holds it now so the summary can name the peer.
+                    holderId = typeof current === 'string' && current !== '' ? current : null;
+                    held = false;
+                    return false;
+                }
+                const reply = (await redis.pipeline([['SET', key, owner, 'PX', String(ttlMs), 'XX']]))[0];
+                if (reply !== 'OK' && reply !== 'ok') {
+                    held = false;
+                    holderId = null;
+                    return false;
+                }
+                expiresAt = now() + ttlMs;
+                return true;
+            } catch (err) {
+                warn(`[omp-opsx-addon] concurrency: lease renewal failed (${message(err)}); stepping down to non-writer`);
+                held = false;
+                holderId = null;
+                return false;
+            }
+        },
+        async release(): Promise<void> {
+            if (!held) return;
+            held = false;
+            holderId = null;
+            try {
+                await redis.pipeline([['DEL', key]]);
+            } catch { /* TTL will clean it up */ }
+        },
+    };
+}
+
+function fileLeaseHandle(
+    fileSystem: WriterFileSystemPort,
+    lockPath: string,
+    owner: string,
+    ttlMs: number,
+    now: () => number,
+    warn: Warn,
+): LeaseHandle {
+    let held = false;
+    let holderId: string | null = null;
+    let unsupported: string | null = null;
+    for (let attempt = 0; attempt < FILE_LEASE_ATTEMPTS; attempt++) {
+        try {
+            fileSystem.openExclusive(lockPath, owner);
+            held = true;
+            break;
+        } catch (err) {
+            if (codeOf(err) !== 'EEXIST') {
+                unsupported = codeOf(err) ?? message(err);
+                break;
+            }
+            const mtime = fileSystem.statMtimeMs(lockPath);
+            if (mtime === null) continue; // vanished — retry immediately
+            if (now() - mtime > ttlMs) {
+                try { fileSystem.remove(lockPath); } catch { /* raced */ }
+                continue; // stale holder → take over
+            }
+            break; // a live peer holds the lease
+        }
+    }
+    if (!held) {
+        if (unsupported !== null) {
+            warn(`[omp-opsx-addon] concurrency: file lease unavailable (${unsupported}) and Redis unusable; control loop degraded to read-only`);
+            return NOT_HELD('readonly');
+        }
+        // A live peer holds the lock: its owner id is the lock file's body, so a
+        // non-writer can name the holder instead of reporting an anonymous「有主」.
+        const peer = fileSystem.readFile(lockPath);
+        return NOT_HELD('file', typeof peer === 'string' && peer !== '' ? peer : null);
+    }
+    return {
+        held: true,
+        mode: 'file',
+        get holderId(): string | null {
+            return held ? owner : holderId;
+        },
+        async renew(): Promise<boolean> {
+            if (!held) return false;
+            const current = fileSystem.readFile(lockPath);
+            if (current !== owner) {
+                held = false;
+                holderId = typeof current === 'string' && current !== '' ? current : null;
+                return false;
+            }
+            try {
+                fileSystem.touch(lockPath, now());
+                return true;
+            } catch (err) {
+                warn(`[omp-opsx-addon] concurrency: file lease renewal failed (${message(err)}); stepping down to non-writer`);
+                held = false;
+                holderId = null;
+                return false;
+            }
+        },
+        async release(): Promise<void> {
+            if (!held) return;
+            held = false;
+            holderId = null;
+            if (fileSystem.readFile(lockPath) === owner) {
+                try { fileSystem.remove(lockPath); } catch { /* already gone */ }
+            }
+        },
+    };
+}
+
+/**
+ * Acquire writer eligibility for this process.
+ *
+ * 1. Redis available → `SET <key> <owner> NX PX <ttl>` through the existing
+ *    `pipeline()` command surface (no client-command extension); a `null`
+ *    reply means a peer holds the lease → `held: false`, `mode: 'redis'`.
+ * 2. Redis absent/failing → file lease at `lockPath` (`O_EXCL` + mtime expiry
+ *    takeover) → `mode: 'file'`.
+ * 3. Neither available → `held: false`, `mode: 'readonly'` **plus warn**: the
+ *    caller MUST NOT write anything and MUST NOT drop managed keys.
+ */
+export async function createLease(args: CreateLeaseArgs): Promise<LeaseHandle> {
+    const fileSystem = args.fileSystem ?? nodeWriterFileSystem;
+    const warn = args.warn ?? NO_WARN;
+    const ttlMs = Number.isFinite(args.ttlMs) && args.ttlMs > 0 ? args.ttlMs : DEFAULT_LEASE_TTL_MS;
+    const owner = args.owner;
+
+    if (args.redis && typeof args.redis.pipeline === 'function') {
+        const key = args.redisKey ?? defaultLeaseKey(args.lockPath);
+        try {
+            const reply = (await args.redis.pipeline([['SET', key, owner, 'NX', 'PX', String(ttlMs)]]))[0];
+            if (reply === 'OK' || reply === 'ok') return redisLease(args.redis, key, owner, ttlMs, args.now, warn);
+            // A peer won the race: `GET` names it so the summary shows *who*
+            // holds the lease rather than an anonymous non-writer.
+            let holder: string | null = null;
+            try {
+                const current = (await args.redis.pipeline([['GET', key]]))[0];
+                holder = typeof current === 'string' && current !== '' ? current : null;
+            } catch { /* holder unknown — the lease still is not ours */ }
+            return NOT_HELD('redis', holder);
+        } catch (err) {
+            warn(`[omp-opsx-addon] concurrency: Redis lease unavailable (${message(err)}); falling back to the file lease`);
+        }
+    }
+
+    try {
+        fileSystem.ensureDir(dirname(args.lockPath));
+    } catch { /* the open below decides whether atomic creation works */ }
+    return fileLeaseHandle(fileSystem, args.lockPath, owner, ttlMs, args.now, warn);
+}