@intentius/chant-lexicon-grafana 0.124.31 → 0.124.33

package/dist/api/apply.js

@@ -0,0 +1,320 @@
+/**
+ * The Grafana API applier (#2948): folders, library panels and dashboards
+ * written over Grafana's HTTP API, stamped with chant's ownership labels,
+ * and an owned-only prune.
+ *
+ * ## The API path
+ *
+ * The server's dashboard API is discovered once per client
+ * (`dashboardApi` in ./dashboards.ts, shared with observe):
+ *
+ * - **Grafana 12.4 and 13.x**: `dashboard.grafana.app` (`v1beta1` on 12.4,
+ *   `v1` on 13.x). A dashboard is created with `POST` to the collection and
+ *   updated with `PUT` to its name, without a `resourceVersion`, which both
+ *   versions accept as an unconditional update. The resource carries the
+ *   classic JSON in `spec`, chant's labels in `metadata.labels`
+ *   (`grafanaOwnershipLabels`, the marker observe reads back), and its
+ *   folder in the `grafana.app/folder` annotation.
+ * - **Grafana 11**: `POST /api/dashboards/db` with `overwrite: true` and the
+ *   folder's uid. There is no metadata channel, so nothing is stamped and
+ *   nothing is pruned: the prune reports both kinds as `not-prunable`.
+ *
+ * Folders are ./folders.ts and library panels ./library-panels.ts. The write
+ * order is folders (parents first), then library panels, then dashboards, so
+ * nothing is written before what it references.
+ *
+ * ## Unchanged
+ *
+ * Every write is preceded by a read, and a resource whose live content
+ * already covers what would be sent (./converge.ts), with the same folder
+ * and labels, is `unchanged` and not written.
+ *
+ * ## Prune
+ *
+ * Only with `prune`, and only what carries this project's marker: chant's
+ * managed-by label with the same stack and the same env (an env-less marker
+ * matches only an env-less apply). Dashboards go first, then folders, a
+ * child before its parent, and a folder that still holds anything after
+ * that (a dashboard saved into it in the UI, a library panel) is left, as
+ * `not-prunable` with what it holds. Library panels are never pruned: their
+ * API has no labels.
+ */
+import { hasOwnershipMarker } from "@intentius/chant/ownership";
+import { GrafanaApiError } from "./client.js";
+import { DASHBOARD_GROUP, classicDashboardOf, dashboardApi, dashboardPath, listDashboards, readDashboard } from "./dashboards.js";
+import { FOLDER_ANNOTATION, childrenFirst, deleteFolder, ensureFolder, folderApi, folderContentCount, listFolders, resolveFolders, send, } from "./folders.js";
+import { ensureLibraryPanel, libraryPanelsOf, withoutExportKeys } from "./library-panels.js";
+import { converged } from "./converge.js";
+import { GRAFANA_OWNERSHIP_KEYS, grafanaOwnershipLabels } from "../ownership.js";
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** The kinds the applier names in its result: Grafana's own type names. */
+export const GRAFANA_APPLY_KINDS = {
+    dashboard: "Dashboard",
+    folder: "Folder",
+    libraryPanel: "LibraryPanel",
+    /** An `__elements` entry that is not a panel (a library variable), which the applier cannot write. */
+    libraryElement: "LibraryElement",
+};
+function sameJson(a, b) {
+    return converged(a, b) && converged(b, a);
+}
+/**
+ * Turn built dashboards into an apply plan: the folders they name (each
+ * level of a path, with its parent) and the build's own `folders` (its
+ * index lists every one, `Folder`s holding no dashboard included), the
+ * library panels their `__elements` carry, and the dashboards themselves.
+ * Throws on a plan no apply could satisfy: a dashboard with no uid, two
+ * dashboards with one uid, two folders with one uid, or one library panel
+ * uid with two models.
+ */
+export function planFromDashboards(dashboards, declaredFolders = []) {
+    const resolved = resolveFolders({
+        declared: [
+            ...declaredFolders.flatMap((f) => (f.path ? [{ uid: f.uid, path: f.path }] : [])),
+            ...dashboards.flatMap((d) => (d.folder && d.folderUid ? [{ uid: d.folderUid, path: d.folder }] : [])),
+        ],
+        paths: dashboards.map((d) => d.folder),
+    });
+    const folders = resolved.folders;
+    const libraryPanels = new Map();
+    const unsupported = [];
+    const out = [];
+    const seen = new Set();
+    for (const d of dashboards) {
+        const uid = d.json.uid;
+        if (typeof uid !== "string" || uid === "")
+            throw new Error(`grafana apply: dashboard "${String(d.json.title ?? "?")}" has no uid`);
+        if (seen.has(uid))
+            throw new Error(`grafana apply: two dashboards have the uid "${uid}"`);
+        seen.add(uid);
+        const inFolder = d.folderUid ?? resolved.uidOf(d.folder);
+        const { panels, skipped } = libraryPanelsOf(d.json, inFolder);
+        for (const p of panels) {
+            const prior = libraryPanels.get(p.uid);
+            if (prior && (prior.name !== p.name || !sameJson(prior.model, p.model))) {
+                throw new Error(`grafana apply: library panel "${p.uid}" is carried by more than one dashboard with different content`);
+            }
+            if (!prior)
+                libraryPanels.set(p.uid, p);
+        }
+        for (const name of skipped) {
+            unsupported.push({ kind: GRAFANA_APPLY_KINDS.libraryElement, name, detail: `dashboard "${uid}" carries it in __elements, and only library panels (kind 1) can be applied` });
+        }
+        out.push({ uid, json: withoutExportKeys(d.json), ...(inFolder ? { folderUid: inFolder } : {}) });
+    }
+    return { folders: parentsFirst(folders), libraryPanels: [...libraryPanels.values()], dashboards: out, unsupported };
+}
+function parentsFirst(folders) {
+    const byUid = new Map(folders.map((f) => [f.uid, f]));
+    const out = [];
+    const done = new Set();
+    const visit = (f, active) => {
+        if (done.has(f.uid))
+            return;
+        if (active.has(f.uid))
+            throw new Error(`grafana apply: folder "${f.uid}" is its own ancestor`);
+        active.add(f.uid);
+        const parent = f.parentUid ? byUid.get(f.parentUid) : undefined;
+        if (parent)
+            visit(parent, active);
+        done.add(f.uid);
+        out.push(f);
+    };
+    for (const f of folders)
+        visit(f, new Set());
+    return out;
+}
+/** Every resource in a plan, as `{ kind, name }`: what the result must account for. */
+export function planRefs(plan) {
+    return [
+        ...plan.folders.map((f) => ({ kind: GRAFANA_APPLY_KINDS.folder, name: f.uid })),
+        ...plan.libraryPanels.map((p) => ({ kind: GRAFANA_APPLY_KINDS.libraryPanel, name: p.uid })),
+        ...plan.dashboards.map((d) => ({ kind: GRAFANA_APPLY_KINDS.dashboard, name: d.uid })),
+        ...plan.unsupported.map((u) => ({ kind: u.kind, name: u.name })),
+    ];
+}
+function apiLabel(api) {
+    return api.kind === "apis" ? `apis/${api.version}` : "legacy";
+}
+/** The labels an apply stamps: the full marker, or only managed-by when no stack is known. */
+export function stampLabels(marker) {
+    return marker ? grafanaOwnershipLabels(marker) : { [GRAFANA_OWNERSHIP_KEYS.managedBy]: "chant" };
+}
+/** True when `labels` carry exactly this project's marker: chant's, this stack, this env. */
+export function carriesMarker(labels, marker) {
+    if (!hasOwnershipMarker(labels, GRAFANA_OWNERSHIP_KEYS))
+        return false;
+    return labels[GRAFANA_OWNERSHIP_KEYS.stack] === marker.stack && (labels[GRAFANA_OWNERSHIP_KEYS.env] ?? undefined) === (marker.env || undefined);
+}
+function sameLabels(live, want) {
+    return Object.entries(want).every(([k, v]) => live[k] === v);
+}
+/** The spec sent for a dashboard: its JSON without the identity keys the resource carries elsewhere. */
+function specOf(json) {
+    const { id: _id, uid: _uid, version: _version, ...spec } = json;
+    return spec;
+}
+/**
+ * Create or update one dashboard. Unchanged, with nothing written, when the
+ * live dashboard already covers the JSON and sits in the same folder with
+ * the same labels.
+ */
+export async function ensureDashboard(client, plan, labels) {
+    const api = await dashboardApi(client);
+    const read = await readDashboard(client, plan.uid);
+    const live = "present" in read ? read.present : undefined;
+    const address = dashboardPath(api, client.namespace, plan.uid);
+    const classic = live ? classicDashboardOf(live) : undefined;
+    const sameFolder = (live?.folderUid ?? "") === (plan.folderUid ?? "");
+    const sameContent = classic !== undefined && "json" in classic && converged(plan.json, classic.json, { dashboard: true });
+    if (api.kind === "apis") {
+        if (live && sameContent && sameFolder && sameLabels(live.labels, labels))
+            return { action: "unchanged", address };
+        // Labels are merged, so a label another tool put on the dashboard stays.
+        const metadata = {
+            name: plan.uid,
+            labels: { ...(live?.labels ?? {}), ...labels },
+            ...(plan.folderUid ? { annotations: { [FOLDER_ANNOTATION]: plan.folderUid } } : {}),
+        };
+        const resource = { apiVersion: `${DASHBOARD_GROUP}/${api.version}`, kind: "Dashboard", metadata, spec: specOf(plan.json) };
+        if (live) {
+            await send(client, "PUT", address, resource);
+            return { action: "updated", address };
+        }
+        await send(client, "POST", address.slice(0, address.lastIndexOf("/")), resource);
+        return { action: "created", address };
+    }
+    if (live && sameContent && sameFolder)
+        return { action: "unchanged", address };
+    const { id: _id, version: _version, ...dashboard } = plan.json;
+    await send(client, "POST", "/api/dashboards/db", {
+        dashboard: { ...dashboard, uid: plan.uid },
+        folderUid: plan.folderUid ?? "",
+        overwrite: true,
+        message: "chant apply",
+    });
+    return { action: live ? "updated" : "created", address };
+}
+/** Delete one dashboard over `/apis`. False when it was already gone. */
+async function deleteDashboard(client, address) {
+    const res = await client.http("DELETE", address);
+    if (res.status === 404)
+        return false;
+    if (res.status < 200 || res.status >= 300)
+        throw new GrafanaApiError(res.status, "DELETE", address, res.json);
+    return true;
+}
+function checkAborted(signal) {
+    if (signal?.aborted)
+        throw new Error("grafana apply aborted");
+}
+/**
+ * Apply `plan` to the Grafana behind `client`. Throws `GrafanaApiError` when
+ * a write fails; a refused first read (401/403) is returned instead, with
+ * every resource `no-credentials`, since nothing was written.
+ */
+export async function applyGrafana(client, plan, opts = {}) {
+    const outcome = {
+        target: client.target.source,
+        api: "",
+        applied: [],
+        pruned: [],
+        notAttempted: plan.unsupported.map((u) => ({ kind: u.kind, name: u.name, reason: "unsupported-kind", detail: u.detail })),
+        notPrunable: [],
+    };
+    let api;
+    try {
+        api = await dashboardApi(client);
+    }
+    catch (err) {
+        if (err instanceof GrafanaApiError && err.verdict === "refused") {
+            const detail = `${err.message} (the credentials for ${client.target.source} were refused)`;
+            for (const ref of planRefs(plan)) {
+                if (!plan.unsupported.some((u) => u.kind === ref.kind && u.name === ref.name))
+                    outcome.notAttempted.push({ ...ref, reason: "no-credentials", detail });
+            }
+            return outcome;
+        }
+        throw err;
+    }
+    outcome.api = apiLabel(api);
+    const labels = stampLabels(opts.marker);
+    for (const folder of plan.folders) {
+        checkAborted(opts.signal);
+        const r = await ensureFolder(client, folder, labels);
+        outcome.applied.push({ kind: GRAFANA_APPLY_KINDS.folder, name: folder.uid, action: r.action, address: r.address });
+    }
+    for (const panel of plan.libraryPanels) {
+        checkAborted(opts.signal);
+        const r = await ensureLibraryPanel(client, panel);
+        outcome.applied.push({ kind: GRAFANA_APPLY_KINDS.libraryPanel, name: panel.uid, action: r.action, address: r.address });
+    }
+    for (const dashboard of plan.dashboards) {
+        checkAborted(opts.signal);
+        const r = await ensureDashboard(client, dashboard, labels);
+        outcome.applied.push({ kind: GRAFANA_APPLY_KINDS.dashboard, name: dashboard.uid, action: r.action, address: r.address });
+    }
+    if (opts.prune)
+        await prune(client, plan, api, opts, outcome);
+    return outcome;
+}
+async function prune(client, plan, api, opts, outcome) {
+    const marker = opts.marker;
+    if (plan.libraryPanels.length > 0) {
+        outcome.notPrunable.push({ kind: GRAFANA_APPLY_KINDS.libraryPanel, detail: "the library elements API has no labels, so a library panel cannot carry chant's marker" });
+    }
+    if (!marker) {
+        const detail = "no ownership stack: set ownership.stack in chant.config.ts, or pass stack, so the prune can tell this project's resources from another's";
+        outcome.notPrunable.push({ kind: GRAFANA_APPLY_KINDS.dashboard, detail }, { kind: GRAFANA_APPLY_KINDS.folder, detail });
+        return;
+    }
+    if (api.kind === "legacy") {
+        outcome.notPrunable.push({ kind: GRAFANA_APPLY_KINDS.dashboard, detail: "this Grafana has no dashboard.grafana.app API (Grafana 11), and /api/dashboards has no labels to read the marker from" });
+    }
+    else {
+        const keep = new Set(plan.dashboards.map((d) => d.uid));
+        for (const live of await listDashboards(client)) {
+            if (keep.has(live.uid) || !carriesMarker(live.labels, marker))
+                continue;
+            checkAborted(opts.signal);
+            const address = dashboardPath(api, client.namespace, live.uid);
+            outcome.pruned.push({ kind: GRAFANA_APPLY_KINDS.dashboard, name: live.uid, deleted: await deleteDashboard(client, address), address });
+        }
+    }
+    const fApi = await folderApi(client);
+    if (fApi.kind === "legacy") {
+        outcome.notPrunable.push({ kind: GRAFANA_APPLY_KINDS.folder, detail: "this Grafana has no folder.grafana.app API, and /api/folders has no labels to read the marker from" });
+        return;
+    }
+    const keep = new Set(plan.folders.map((f) => f.uid));
+    const orphans = (await listFolders(client)).filter((f) => !keep.has(f.uid) && carriesMarker(f.labels, marker));
+    for (const folder of childrenFirst(orphans)) {
+        checkAborted(opts.signal);
+        const held = await folderContentCount(client, folder.uid);
+        if (held > 0) {
+            outcome.notAttempted.push({
+                kind: GRAFANA_APPLY_KINDS.folder,
+                name: folder.uid,
+                reason: "not-prunable",
+                detail: `folder "${folder.title}" is this project's and no longer declared, but still holds ${held} item(s) chant does not prune (a dashboard saved into it, a library panel); it is left`,
+            });
+            continue;
+        }
+        outcome.pruned.push({ kind: GRAFANA_APPLY_KINDS.folder, name: folder.uid, deleted: await deleteFolder(client, folder), address: folder.address });
+    }
+}
+/** Parse a stored dashboard JSON file's content; throws with the file name when it is not a JSON object. */
+export function parseDashboardFile(content, file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        throw new Error(`grafana apply: ${file} is not JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (!isObject(parsed))
+        throw new Error(`grafana apply: ${file} is not a dashboard JSON object`);
+    return parsed;
+}

package/dist/api/bind.js

@@ -0,0 +1,44 @@
+/**
+ * Binding a client for one environment: the config lookup, the target, the
+ * transport. Shared by observe, export and (#2948) apply, so all three read
+ * and write the same Grafana.
+ */
+import { GrafanaApiError, GrafanaClient, grafanaHttp } from "./client.js";
+import { isUnresolvedTarget, resolveGrafanaTarget } from "../config.js";
+/** A target that could not be resolved, thrown by {@link bindGrafana} and classified by {@link classifyGrafanaFailure}. */
+export class GrafanaBindingError extends Error {
+    constructor(unresolved) {
+        super(unresolved.detail);
+        this.unresolved = unresolved;
+        this.name = "GrafanaBindingError";
+    }
+}
+async function loadConfig(cwd) {
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        return (await loadChantConfig(cwd)).config;
+    }
+    catch {
+        // No project config (an ad-hoc export): the environment variables still bind.
+        return undefined;
+    }
+}
+/** Resolve the environment's target and return a client for it. Throws {@link GrafanaBindingError} when there is none. */
+export async function bindGrafana(options = {}) {
+    const config = options.config ?? (await loadConfig(options.cwd ?? process.cwd()));
+    const target = resolveGrafanaTarget({ environment: options.environment, config, env: options.env });
+    if (isUnresolvedTarget(target))
+        throw new GrafanaBindingError(target);
+    return new GrafanaClient(options.http ?? grafanaHttp(target), target);
+}
+/** What a failed bind or read means, in the observation vocabulary. */
+export function classifyGrafanaFailure(err) {
+    if (err instanceof GrafanaBindingError)
+        return { reason: err.unresolved.reason, detail: err.unresolved.detail };
+    if (err instanceof GrafanaApiError) {
+        return err.verdict === "refused"
+            ? { reason: "no-credentials", detail: `${err.message} (the credentials were refused)` }
+            : { reason: "read-failed", detail: err.message };
+    }
+    return { reason: "read-failed", detail: err instanceof Error ? err.message.split("\n")[0] : String(err) };
+}

package/dist/api/client.js

@@ -0,0 +1,113 @@
+/**
+ * The Grafana HTTP transport (#2946): one client for observe, export and,
+ * later, the API applier (#2948), so all three reach the same instance with
+ * the same credentials.
+ *
+ * `GrafanaHttp` is the seam. The default is `fetch` against a resolved
+ * target (./target.ts); a test hands in a function that answers by path, so
+ * nothing needs a module mock.
+ *
+ * Status mapping is in one place ({@link statusVerdict}): a 404 is the only
+ * answer that means "not there", 401/403 mean the credentials were refused,
+ * and anything else that is not a 2xx is a failed read. A reader that turned
+ * a 500 or a refused token into "absent" would have `chant lifecycle plan`
+ * propose creating a dashboard that is running.
+ */
+/** The API namespace for a target (see {@link GrafanaTarget.namespace}). */
+export function namespaceOf(target) {
+    if (target.namespace)
+        return target.namespace;
+    const org = target.orgId ?? 1;
+    return org === 1 ? "default" : `org-${org}`;
+}
+function authHeader(auth) {
+    if (!auth)
+        return {};
+    if ("token" in auth)
+        return { authorization: `Bearer ${auth.token}` };
+    return { authorization: `Basic ${Buffer.from(`${auth.user}:${auth.password}`).toString("base64")}` };
+}
+/** The default transport: `fetch` against the target, JSON in and out. */
+export function grafanaHttp(target, fetchImpl = fetch) {
+    const base = target.url.replace(/\/+$/, "");
+    const headers = {
+        accept: "application/json",
+        ...authHeader(target.auth),
+        ...(target.orgId !== undefined ? { "x-grafana-org-id": String(target.orgId) } : {}),
+    };
+    return async (method, path, body) => {
+        const res = await fetchImpl(`${base}${path}`, {
+            method,
+            headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await res.text();
+        let json;
+        if (text !== "") {
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = undefined;
+            }
+        }
+        return { status: res.status, json };
+    };
+}
+export function statusVerdict(status) {
+    if (status >= 200 && status < 300)
+        return "ok";
+    if (status === 404)
+        return "not-found";
+    if (status === 401 || status === 403)
+        return "refused";
+    return "failed";
+}
+/** A non-2xx answer, with enough to classify it and to say where it came from. */
+export class GrafanaApiError extends Error {
+    constructor(status, method, path, body) {
+        const message = body && typeof body === "object" && typeof body.message === "string" ? body.message : "";
+        super(`${method} ${path} returned ${status}${message ? `: ${message}` : ""}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.name = "GrafanaApiError";
+        this.verdict = statusVerdict(status);
+    }
+}
+/**
+ * A bound client: the transport, the target it reaches, and per-client
+ * caches (the API version a server serves, folder titles) so N reads do not
+ * repeat the same lookup.
+ */
+export class GrafanaClient {
+    constructor(http, target) {
+        this.http = http;
+        this.target = target;
+        this.memo = new Map();
+    }
+    get namespace() {
+        return namespaceOf(this.target);
+    }
+    /** GET, returning the body; undefined on 404; throws {@link GrafanaApiError} on any other non-2xx. */
+    async get(path) {
+        const res = await this.http("GET", path);
+        const verdict = statusVerdict(res.status);
+        if (verdict === "ok")
+            return res.json;
+        if (verdict === "not-found")
+            return undefined;
+        throw new GrafanaApiError(res.status, "GET", path, res.json);
+    }
+    /** Run `fn` once per key for this client's lifetime; concurrent callers share the promise. */
+    once(key, fn) {
+        let p = this.memo.get(key);
+        if (!p) {
+            p = fn();
+            this.memo.set(key, p);
+            // A failed lookup is not cached: the next caller asks again.
+            p.catch(() => this.memo.delete(key));
+        }
+        return p;
+    }
+}

package/dist/api/converge.js

@@ -0,0 +1,61 @@
+/**
+ * Whether what Grafana holds already is what the applier would write
+ * (#2948), so a re-apply reports `unchanged` and writes nothing.
+ *
+ * Grafana does not answer this itself: a `PUT` of identical content still
+ * bumps `generation` and `resourceVersion` (measured on 12.4.11 and 13.2.2),
+ * so a no-op cannot be told from an update after the fact. And the stored
+ * dashboard is not the one sent: Grafana fills in defaults
+ * (`fiscalYearStartMonth: 0`, `links: []`, `timepicker: {}`, ...), adds the
+ * built-in annotation, drops `null`s and empty `options`, and may migrate
+ * `schemaVersion`.
+ *
+ * So the test is one-sided: every value the applier would send must be in
+ * the live object, equal, and anything Grafana added on top is ignored. An
+ * array must match element for element, since a panel added in the UI is a
+ * change. The noise is the same list the drift hooks carry (#2946):
+ *
+ * - `null` and empty objects sent are satisfied by an absent key;
+ * - the built-in "Annotations & Alerts" annotation is ignored on both sides;
+ * - `id`, `version` and `uid` at the top level are identity, not content, and
+ *   `schemaVersion` is Grafana's to migrate.
+ */
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Top-level dashboard keys that are identity or Grafana-managed, never content. */
+export const IDENTITY_KEYS = ["id", "uid", "version", "schemaVersion"];
+function isBuiltInAnnotation(v) {
+    return isObject(v) && (v.builtIn === 1 || v.builtIn === true);
+}
+function covers(want, live, path) {
+    if (want === null || want === undefined)
+        return live === null || live === undefined;
+    if (Array.isArray(want)) {
+        if (!Array.isArray(live))
+            return want.length === 0 && live === undefined;
+        const annotations = path[path.length - 1] === "list" && path[path.length - 2] === "annotations";
+        const w = annotations ? want.filter((a) => !isBuiltInAnnotation(a)) : want;
+        const l = annotations ? live.filter((a) => !isBuiltInAnnotation(a)) : live;
+        return w.length === l.length && w.every((x, i) => covers(x, l[i], [...path, String(i)]));
+    }
+    if (isObject(want)) {
+        if (live === undefined || live === null)
+            return Object.values(want).every((v) => covers(v, undefined, path));
+        if (!isObject(live))
+            return false;
+        return Object.entries(want).every(([k, v]) => covers(v, live[k], [...path, k]));
+    }
+    return want === live;
+}
+/**
+ * True when `live` already holds everything in `want`. For a dashboard,
+ * the top-level identity keys ({@link IDENTITY_KEYS}) are left out of the
+ * comparison.
+ */
+export function converged(want, live, opts = {}) {
+    if (!opts.dashboard || !isObject(want))
+        return covers(want, live, []);
+    const content = Object.fromEntries(Object.entries(want).filter(([k]) => !IDENTITY_KEYS.includes(k)));
+    return covers(content, live, []);
+}