@fonoster/common 0.27.0 → 0.30.0

package/dist/registry/cli.js

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usesDatabase = void 0;
+exports.run = run;
+exports.runWithDatabase = runWithDatabase;
+exports.runTraced = runTraced;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const fs = __importStar(require("fs"));
+const telemetry_1 = require("../telemetry");
+const Dispatcher_1 = require("../webhooks/Dispatcher");
+const events_1 = require("../webhooks/events");
+const prisma_1 = require("../webhooks/prisma");
+const prisma_2 = require("./prisma");
+const Registry_1 = require("./Registry");
+const stores_1 = require("./stores");
+function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a.startsWith("--") || /^-[a-z]$/.test(a)) {
+            // `--name value`, `--flag`, or a short `-f value` (plan -f, apply -f).
+            const key = a.replace(/^--?/, "");
+            const next = rest[i + 1];
+            if (next === undefined || next.startsWith("--"))
+                flags[key] = true;
+            else {
+                flags[key] = next;
+                i++;
+            }
+        }
+        else
+            positional.push(a);
+    }
+    return { command, positional, flags };
+}
+/** The command line as audited: database flags (they may carry credentials in URLs) left out. */
+function commandLine(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--database-url" || argv[i] === "--store") {
+            i++;
+            continue;
+        }
+        out.push(/\s/.test(argv[i]) ? JSON.stringify(argv[i]) : argv[i]);
+    }
+    return `fonoster-registry ${out.join(" ")}`;
+}
+const list = (v) => typeof v === "string"
+    ? v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+const str = (v, name) => {
+    if (typeof v !== "string")
+        throw new Registry_1.RegistryError(`--${name} is required`);
+    return v;
+};
+const HELP = `fonoster-registry <command>
+
+  add-provider <id> --adapter <a> --capabilities stt,tts --credential-ref <name>
+  add-model <provider/model> --type stt|tts|llm [--features a,b] [--languages en,es] [--settings s]
+  add-voice <provider/voice> --models <m1,m2> [--language en] [--gender female]
+  deprecate-provider|deprecate-model|deprecate-voice <id> --replacement <id> --retire-on YYYY-MM-DD
+  retire-provider|retire-model|retire-voice <id> [--voice-map old=new,...] --yes
+  usage <id> | list [provider|model|voice] | show <id> | history [<id>]
+  export | plan -f <file> | apply -f <file>
+
+  --store file|database   where the catalog lives (default: FONOSTER_REGISTRY_STORE or file)
+  --database-url <url>    with --store database (default: FONOSTER_REGISTRY_DATABASE_URL)`;
+const DB_FLAGS = ["store", "database-url"];
+/** The options each write command accepts (by command without its kind). */
+const OPTIONS = {
+    add: [
+        "adapter",
+        "capabilities",
+        "credential-ref",
+        "type",
+        "features",
+        "languages",
+        "settings",
+        "models",
+        "language",
+        "gender"
+    ],
+    deprecate: ["replacement", "retire-on"],
+    retire: ["voice-map", "yes"]
+};
+/** Runs one command against the JSON file store (synchronous; the default store). */
+function run(argv, out = console.log) {
+    var _a;
+    const { command, positional, flags } = parseArgs(argv);
+    for (const f of DB_FLAGS)
+        delete flags[f];
+    const registry = new Registry_1.Registry({
+        store: new stores_1.FileRegistryStore((_a = process.env.FONOSTER_REGISTRY_FILE) !== null && _a !== void 0 ? _a : "registry.json"),
+        testMode: process.env.FONOSTER_TEST_MODE === "true",
+        commandLine: commandLine(argv)
+    });
+    return execute(registry, command, positional, flags, out);
+}
+const usesDatabase = (argv) => {
+    var _a, _b;
+    const { flags } = parseArgs(argv);
+    return (((_b = (_a = flags.store) !== null && _a !== void 0 ? _a : process.env.FONOSTER_REGISTRY_STORE) !== null && _b !== void 0 ? _b : "file") ===
+        "database");
+};
+exports.usesDatabase = usesDatabase;
+/**
+ * Runs one command against the control-plane database: loads the catalog and usages, runs the
+ * command, then waits for every write, records skipped rewrites in the audit log and sends due
+ * `provider.deprecated` webhooks once (retries are adopted by a running dispatcher).
+ */
+function runWithDatabase(argv_1) {
+    return __awaiter(this, arguments, void 0, function* (argv, out = console.log, deps = {}) {
+        var _a, _b, _c, _d;
+        const { command, positional, flags } = parseArgs(argv);
+        for (const f of DB_FLAGS)
+            delete flags[f];
+        const url = (_a = parseArgs(argv).flags["database-url"]) !== null && _a !== void 0 ? _a : process.env.FONOSTER_REGISTRY_DATABASE_URL;
+        if (!deps.prisma && !url) {
+            out("error: --database-url or FONOSTER_REGISTRY_DATABASE_URL is required");
+            return 1;
+        }
+        const encryptionKey = process.env.FONOSTER_REGISTRY_ENCRYPTION_KEY;
+        const prisma = (_b = deps.prisma) !== null && _b !== void 0 ? _b : (0, prisma_2.openPrismaClient)({ url: url, encryptionKey });
+        try {
+            const store = yield prisma_2.PrismaRegistryStore.open(prisma);
+            const hooks = deps.prisma || encryptionKey
+                ? yield prisma_1.PrismaWebhookStore.open(prisma)
+                : undefined;
+            const dispatcher = hooks && new Dispatcher_1.WebhookDispatcher({ store: hooks });
+            const usages = yield prisma_2.PrismaUsageSource.open(prisma, {
+                onNotice: (workspace, n) => {
+                    if (n.type === "provider.deprecated")
+                        dispatcher === null || dispatcher === void 0 ? void 0 : dispatcher.publish((0, events_1.providerDeprecated)(workspace, {
+                            id: String(n.id),
+                            replacement: String(n.replacement),
+                            retireOn: String(n.retireOn)
+                        }));
+                }
+            });
+            const registry = new Registry_1.Registry({
+                store,
+                usages,
+                actor: deps.actor,
+                testMode: process.env.FONOSTER_TEST_MODE === "true",
+                commandLine: commandLine(argv)
+            });
+            const sessions = command === "usage" && positional[0]
+                ? yield sessionCounts(prisma, positional[0])
+                : undefined;
+            const code = execute(registry, command, positional, flags, out, sessions);
+            yield usages.flush();
+            for (const c of usages.conflicts) {
+                out(`skipped ${c.usage.config.kind} ${c.usage.config.name}: ${c.reason}`);
+                store.audit({
+                    at: new Date().toISOString(),
+                    actor: (_d = (_c = deps.actor) !== null && _c !== void 0 ? _c : process.env.USER) !== null && _d !== void 0 ? _d : "operator",
+                    action: "rewrite-skipped",
+                    target: positional[0],
+                    details: { workspace: c.usage.workspace, config: c.usage.config }
+                });
+            }
+            yield store.flush();
+            if (dispatcher && hooks) {
+                yield dispatcher.runDue();
+                yield hooks.flush();
+            }
+            else if (command.startsWith("deprecate-")) {
+                out("note: no webhooks sent (set FONOSTER_REGISTRY_ENCRYPTION_KEY); notices were stored");
+            }
+            return code;
+        }
+        finally {
+            if (!deps.prisma)
+                yield prisma.$disconnect();
+        }
+    });
+}
+function execute(registry, command, positional, flags, out, sessions) {
+    var _a, _b;
+    const id = positional[0];
+    const printImpact = (lines) => lines.length
+        ? lines.forEach((l) => {
+            // The count goes before an action hint: "... (3 apps) → needs --voice-map ...".
+            const [what, hint] = l.text.split(" → ");
+            out(`${l.mark} ${what} (${l.count} apps)${hint ? ` → ${hint}` : ""}`);
+        })
+        : out("no configs use it");
+    try {
+        // Write commands take only their own options: anything else (`--api-key`) is refused before
+        // it can reach the catalog (spec "A key cannot be smuggled into the catalog").
+        const allowed = OPTIONS[command.replace(/-(provider|model|voice)$/, "")];
+        const unknown = allowed && Object.keys(flags).find((f) => !allowed.includes(f));
+        if (unknown)
+            throw new Registry_1.RegistryError(`unknown option: --${unknown}`);
+        switch (command) {
+            case "add-provider": {
+                registry.addProvider({
+                    id,
+                    adapter: str(flags.adapter, "adapter"),
+                    capabilities: list(flags.capabilities),
+                    credentialRef: str(flags["credential-ref"], "credential-ref")
+                });
+                break;
+            }
+            case "add-model":
+                registry.addModel({
+                    id,
+                    type: str(flags.type, "type"),
+                    features: list(flags.features),
+                    languages: list(flags.languages),
+                    settings: list(flags.settings)
+                });
+                break;
+            case "add-voice":
+                registry.addVoice({
+                    id,
+                    models: list(flags.models),
+                    language: flags.language,
+                    gender: flags.gender
+                });
+                break;
+            case "deprecate-provider":
+            case "deprecate-model":
+            case "deprecate-voice":
+                printImpact(registry.deprecate(command.split("-")[1], id, str(flags.replacement, "replacement"), str(flags["retire-on"], "retire-on")).lines);
+                break;
+            case "retire-provider":
+            case "retire-model":
+            case "retire-voice": {
+                const voiceMap = Object.fromEntries(list(flags["voice-map"]).map((p) => p.split("=")));
+                if (flags.yes !== true) {
+                    const entry = registry.show(id);
+                    out(`this rewrites every compatible config to ${entry.replacement}; run again with --yes to retire ${id}`);
+                    printImpact(registry.impact(id, (_a = entry.replacement) !== null && _a !== void 0 ? _a : "", voiceMap).lines);
+                    return 1;
+                }
+                printImpact(registry.retire(command.split("-")[1], id, voiceMap).lines);
+                break;
+            }
+            case "usage": {
+                const usages = registry.usage(id);
+                if (!usages.length)
+                    out("no configs use it");
+                if (!sessions) {
+                    for (const u of usages)
+                        out(`${u.workspace}\t${u.config.kind}\t${u.config.name}`);
+                    break;
+                }
+                // With the database: per workspace, its sessions that resolved the id in the last 30
+                // days (from the gateways' registry.used events, LO-B11), then its configs.
+                const workspaces = [
+                    ...new Set([
+                        ...usages.map((u) => u.workspace),
+                        ...Object.keys(sessions)
+                    ])
+                ].sort();
+                for (const w of workspaces) {
+                    out(`${w}\tsessions (30 days)\t${(_b = sessions[w]) !== null && _b !== void 0 ? _b : 0}`);
+                    for (const u of usages.filter((x) => x.workspace === w))
+                        out(`${w}\t${u.config.kind}\t${u.config.name}`);
+                }
+                break;
+            }
+            case "list":
+                for (const e of registry.list(positional[0]))
+                    out(`${e.kind}\t${e.id}\t${e.state}`);
+                break;
+            case "show":
+                out(JSON.stringify(registry.show(id), null, 2));
+                break;
+            case "history":
+                // Newest first (spec "Every write is audited").
+                for (const h of [...registry.history(id)].reverse())
+                    out(`${h.at}\t${h.actor}\t${h.action}\t${h.target}`);
+                break;
+            case "export":
+                out(registry.export().trimEnd());
+                break;
+            case "plan":
+            case "apply": {
+                const file = fs.readFileSync(str(flags.f, "f"), "utf8");
+                const lines = command === "plan" ? registry.plan(file) : registry.apply(file);
+                out(lines.length ? lines.join("\n") : "no changes");
+                break;
+            }
+            default:
+                out(HELP);
+                return command === "help" ? 0 : 1;
+        }
+        return 0;
+    }
+    catch (e) {
+        if (e instanceof Registry_1.RegistryError) {
+            out(`error: ${e.message}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+/**
+ * Runs one command with telemetry (add-platform 2.5): a `registry.command` span and a
+ * `fonoster.registry.commands` count by command and outcome, flushed before returning. Off unless
+ * an OTLP endpoint is set.
+ */
+function runTraced(argv_1) {
+    return __awaiter(this, arguments, void 0, function* (argv, env = process.env) {
+        var _a;
+        const telemetry = (0, telemetry_1.initTelemetry)("fonoster-registry", undefined, env);
+        const command = (_a = argv[0]) !== null && _a !== void 0 ? _a : "help";
+        const store = (0, exports.usesDatabase)(argv) ? "database" : "file";
+        const span = telemetry.startSpan("registry.command", {
+            "fonoster.registry.command": command,
+            "fonoster.registry.store": store
+        });
+        let code = 1;
+        let error;
+        try {
+            code = (0, exports.usesDatabase)(argv) ? yield runWithDatabase(argv) : run(argv);
+            return code;
+        }
+        catch (e) {
+            error = e.message;
+            throw e;
+        }
+        finally {
+            telemetry.count("fonoster.registry.commands", 1, {
+                command,
+                outcome: code === 0 ? "ok" : "error"
+            });
+            span.end(undefined, error);
+            yield telemetry.shutdown();
+        }
+    });
+}
+/** Sessions per workspace that resolved an id in the last 30 days (registry_usage). */
+function sessionCounts(prisma_3, id_1) {
+    return __awaiter(this, arguments, void 0, function* (prisma, id, now = new Date()) {
+        if (!prisma.registryUsage)
+            return undefined;
+        const since = new Date(now.getTime() - 30 * 24 * 3600 * 1000);
+        const rows = yield prisma.registryUsage.groupBy({
+            by: ["accessKeyId"],
+            where: {
+                catalogId: id,
+                day: { gte: new Date(since.toISOString().slice(0, 10)) }
+            },
+            _sum: { sessions: true }
+        });
+        return Object.fromEntries(rows.map((r) => { var _a; return [r.accessKeyId, (_a = r._sum.sessions) !== null && _a !== void 0 ? _a : 0]; }));
+    });
+}
+// Run when executed as the fonoster-registry binary.
+// eslint-disable-next-line no-undef
+if (require.main === module) {
+    runTraced(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+        console.error(`error: ${e.message}`);
+        process.exit(1);
+    });
+}

package/dist/{assistants/audioFiltersSchema.js → registry/features.d.ts}

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.audioFiltersSchema = void 0;
 /**
  * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
  * http://github.com/fonoster/fonoster
@@ -19,14 +16,16 @@ exports.audioFiltersSchema = void 0;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-const zod_1 = require("zod");
-// Audio filters run in the Media Server. Options carry tuning values only;
-// credentials live in the Media Server's environment, never in this config,
-// so assistant files stay safe to commit and share.
-const audioFiltersSchema = zod_1.z
-    .array(zod_1.z.object({
-    name: zod_1.z.string().min(1, { message: "An audio filter name is required" }),
-    options: zod_1.z.record(zod_1.z.unknown()).optional()
-}))
-    .default([]);
-exports.audioFiltersSchema = audioFiltersSchema;
+import { Capability } from "./types";
+/**
+ * The feature vocabulary (add-provider-registry, P8). Hard features are needed for a config to
+ * work at all; soft ones only degrade it (and their settings are dropped on retirement).
+ */
+export declare const FEATURES: Record<Capability, Record<string, "hard" | "soft">>;
+export declare function unknownFeatures(type: Capability, features: string[]): string[];
+/** Hard requirements derived from an assistant config: tools need tool calling, replies stream. */
+export declare function assistantRequirements(assistant: {
+    languageModel?: {
+        tools?: unknown[];
+    };
+}): string[];

package/dist/registry/features.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEATURES = void 0;
+exports.unknownFeatures = unknownFeatures;
+exports.assistantRequirements = assistantRequirements;
+/**
+ * The feature vocabulary (add-provider-registry, P8). Hard features are needed for a config to
+ * work at all; soft ones only degrade it (and their settings are dropped on retirement).
+ */
+exports.FEATURES = {
+    llm: {
+        "tool-calling": "hard",
+        streaming: "hard",
+        "json-mode": "soft",
+        vision: "soft"
+    },
+    tts: { streaming: "hard", "word-timings": "soft", ssml: "soft" },
+    stt: {
+        streaming: "hard",
+        "interim-results": "soft",
+        "word-timings": "soft",
+        "turn-detection": "soft",
+        multilingual: "soft"
+    }
+};
+function unknownFeatures(type, features) {
+    return features.filter((f) => !(f in exports.FEATURES[type]));
+}
+/** Hard requirements derived from an assistant config: tools need tool calling, replies stream. */
+function assistantRequirements(assistant) {
+    var _a, _b;
+    const req = ["streaming"];
+    if (((_b = (_a = assistant.languageModel) === null || _a === void 0 ? void 0 : _a.tools) !== null && _b !== void 0 ? _b : []).length)
+        req.push("tool-calling");
+    return req;
+}

package/dist/{assistants/LanguageModelProvider.d.ts → registry/index.d.ts}

@@ -16,11 +16,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-declare enum LanguageModelProvider {
-    OPENAI = "openai",
-    GROQ = "groq",
-    OLLAMA = "ollama",
-    GOOGLE = "google",
-    ANTHROPIC = "anthropic"
-}
-export { LanguageModelProvider };
+export * from "./features";
+export * from "./Registry";
+export * from "./stores";
+export * from "./types";
+export * from "./prisma";
+export * from "./workspaceKeys";

package/dist/registry/index.js

@@ -0,0 +1,40 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+__exportStar(require("./features"), exports);
+__exportStar(require("./Registry"), exports);
+__exportStar(require("./stores"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./prisma"), exports);
+__exportStar(require("./workspaceKeys"), exports);

package/dist/registry/prisma.d.ts

@@ -0,0 +1,67 @@
+import { MemoryRegistryStore } from "./stores";
+import { AuditEntry, CatalogEntry, Usage, UsageSource } from "./types";
+export type PrismaLike = any;
+export declare class PrismaRegistryStore extends MemoryRegistryStore {
+    private readonly prisma;
+    private readonly writes;
+    private constructor();
+    /** Opens the store with the current catalog and audit log loaded. */
+    static open(prisma: PrismaLike): Promise<PrismaRegistryStore>;
+    /** Reloads the catalog (and audit log) from the database, after pending writes. */
+    refresh(): Promise<void>;
+    put(entry: CatalogEntry): void;
+    audit(entry: AuditEntry): void;
+    /** Waits for every queued write; throws the first failure. */
+    flush(): Promise<void>;
+}
+export type RewriteConflict = {
+    usage: Usage;
+    reason: string;
+};
+export type PrismaUsageSourceOptions = {
+    /** Receives every notice after it is stored (e.g. to send provider.deprecated webhooks). */
+    onNotice?: (workspace: string, notice: Record<string, unknown>) => void;
+};
+/**
+ * Usages of catalog ids in apps (speech defaults: voice, TTS and STT models) and assistants (the
+ * Autopilot assistant in an app's Intelligence config: `languageModel.model`, and
+ * `conversationSettings.voice`). Legacy rows with raw vendor names are not usages until migrated
+ * to catalog ids (task 5.1).
+ */
+export declare class PrismaUsageSource implements UsageSource {
+    private readonly prisma;
+    private readonly options;
+    private rows;
+    private readonly origins;
+    private readonly writes;
+    /** Rewrites skipped because the config changed after it was read. */
+    readonly conflicts: RewriteConflict[];
+    private constructor();
+    static open(prisma: PrismaLike, options?: PrismaUsageSourceOptions): Promise<PrismaUsageSource>;
+    refresh(): Promise<void>;
+    find(id: string): Usage[];
+    /**
+     * Queues the rewrite. The write only applies if the field still holds the value read; otherwise
+     * it is skipped, audited by the caller's flush report (`conflicts`), and the config keeps its id.
+     */
+    rewrite(usage: Usage, change: {
+        model?: string;
+        voice?: string;
+        dropSettings: string[];
+    }): boolean;
+    notify(workspace: string, notice: Record<string, unknown>): void;
+    /** Waits for every queued write; throws the first failure. */
+    flush(): Promise<void>;
+}
+export type PrismaClientOptions = {
+    url: string;
+    /** Encrypts `/// @encrypted` columns (the apiserver's CLOAK key); needed to read app secrets. */
+    encryptionKey?: string;
+    /** Module of a client generated from the apiserver schema (default `@prisma/client`). */
+    clientModule?: string;
+};
+/**
+ * Opens a Prisma client generated from the apiserver's schema, with field encryption when a key
+ * is given. Loaded at run time so `@fonoster/common` does not depend on a generated client.
+ */
+export declare function openPrismaClient(options: PrismaClientOptions): PrismaLike;