superbee 0.4.2-pre.4 → 0.4.3-pre.1

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.2-pre.4" }, source: { commit: "2809f64a406f710381dcf6ad72a408742af7bf2d", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.1" }, source: { commit: "0c5c7f2b2437d3e33a4aa707f13704e9896482a6", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -6070,15 +6070,15 @@ function lexicalPosixHookTokens(command) {
     const raw = command.slice(start, i);
     const current = renderGeneratedHookToken(token);
     const historical = renderHistoricalDoubleQuotedHookToken(token);
-    const envelope2 = raw === current ? "current" : raw === historical ? "historical_double" : void 0;
-    if (!envelope2) return void 0;
-    tokens.push({ raw, value: token, envelope: envelope2 });
+    const envelope3 = raw === current ? "current" : raw === historical ? "historical_double" : void 0;
+    if (!envelope3) return void 0;
+    tokens.push({ raw, value: token, envelope: envelope3 });
     if (i < command.length) {
       i += 1;
       if (i === command.length || command[i] === " ") return void 0;
     }
   }
-  if (tokens.some(({ envelope: envelope2 }) => envelope2 === "historical_double")) {
+  if (tokens.some(({ envelope: envelope3 }) => envelope3 === "historical_double")) {
     const exactHistoricalCommand = tokens.length === 2 && tokens[0]?.envelope === "historical_double" && tokens[1]?.envelope === "current" && tokens[1]?.raw === "session-start";
     if (!exactHistoricalCommand) return void 0;
   }
@@ -7980,8 +7980,8 @@ function render(value, mode) {
 `;
   }
 }
-function renderErrorEnvelope(envelope2) {
-  return `${encode(envelope2)}
+function renderErrorEnvelope(envelope3) {
+  return `${encode(envelope3)}
 `;
 }
 function renderUsage(usage3) {
@@ -8892,8 +8892,8 @@ function assertValidExpectedVersion(expectedVersion) {
 }
 async function refusesIdentity(res) {
   try {
-    const envelope2 = await res.json();
-    return envelope2?.error?.code === "USAGE" && envelope2.error.message === IDENTITY_UNSUPPORTED;
+    const envelope3 = await res.json();
+    return envelope3?.error?.code === "USAGE" && envelope3.error.message === IDENTITY_UNSUPPORTED;
   } catch {
     return false;
   }
@@ -8911,8 +8911,8 @@ function etagForm(token) {
 async function namesMalformedDocument(res) {
   if (res.status !== 500) return false;
   try {
-    const envelope2 = await res.clone().json();
-    return typeof envelope2?.error?.details?.malformed?.reason === "string";
+    const envelope3 = await res.clone().json();
+    return typeof envelope3?.error?.details?.malformed?.reason === "string";
   } catch {
     return false;
   }
@@ -9006,26 +9006,26 @@ var init_remote_backend = __esm({
       }
       /** Parse a non-2xx response into the typed error the engine expects. */
       async toError(res, fallbackId) {
-        let envelope2 = null;
+        let envelope3 = null;
         try {
-          envelope2 = await res.json();
+          envelope3 = await res.json();
         } catch {
-          envelope2 = null;
+          envelope3 = null;
         }
         if (res.status === 412) {
-          const expected = envelope2?.error?.details?.expected ?? null;
-          const actual = envelope2?.error?.details?.actual ?? null;
+          const expected = envelope3?.error?.details?.expected ?? null;
+          const actual = envelope3?.error?.details?.actual ?? null;
           return new VersionConflict(fallbackId, expected, actual);
         }
-        const malformedDoc = envelope2?.error?.details?.malformed;
+        const malformedDoc = envelope3?.error?.details?.malformed;
         if (malformedDoc && typeof malformedDoc.reason === "string") {
           return new MalformedDocumentError(
             typeof malformedDoc.id === "string" ? malformedDoc.id : fallbackId,
             new Error(malformedDoc.reason)
           );
         }
-        const message = envelope2?.error?.message ?? `wire request failed with status ${res.status}`;
-        const code3 = envelope2?.error?.code ?? (res.status === 401 ? "AUTH_REQUIRED" : res.status >= 500 ? "RUNTIME" : "USAGE");
+        const message = envelope3?.error?.message ?? `wire request failed with status ${res.status}`;
+        const code3 = envelope3?.error?.code ?? (res.status === 401 ? "AUTH_REQUIRED" : res.status >= 500 ? "RUNTIME" : "USAGE");
         return new RemoteError(message, code3, res.status);
       }
       async read(id) {
@@ -9048,8 +9048,8 @@ var init_remote_backend = __esm({
         if (res.status === 404) {
           let missing2 = [];
           try {
-            const envelope2 = await res.json();
-            missing2 = envelope2.error.details?.missing ?? [];
+            const envelope3 = await res.json();
+            missing2 = envelope3.error.details?.missing ?? [];
           } catch {
           }
           throw notFound3(missing2[0] ?? ids[0]);
@@ -11728,6 +11728,184 @@ var init_governed_body_write = __esm({
   }
 });
 
+// ../core/src/kind-coverage.ts
+function bodyProse(body) {
+  let relatedLevel;
+  for (const line2 of body.split("\n")) {
+    const text5 = line2.trim();
+    const heading = /^(#{1,6})[ \t]+(.+?)\s*#*\s*$/.exec(text5);
+    if (heading) {
+      const level2 = heading[1].length;
+      if (relatedLevel !== void 0 && level2 <= relatedLevel) relatedLevel = void 0;
+      if (heading[2].trim().toLowerCase() === "related" && relatedLevel === void 0) relatedLevel = level2;
+      continue;
+    }
+    if (relatedLevel !== void 0) continue;
+    const prose = text5.replace(/^[-*] +/, "");
+    if (!prose) continue;
+    const links = extractMarkdownLinks(prose);
+    if (!(links.length === 1 && prose === `[${links[0].text}](${links[0].href})`)) return true;
+  }
+  return false;
+}
+function fieldStats(docs, value) {
+  let present = 0, sentinels = 0, used = 0;
+  for (const doc2 of docs) {
+    const v2 = value(doc2);
+    if (v2 !== void 0) used++;
+    if (filled(v2)) present++;
+    else if (sentinel(v2)) sentinels++;
+  }
+  return { present: used, filled: present, sentinel: sentinels, empty: docs.length - present - sentinels, rate: ratio(present, docs.length) };
+}
+function checkedOn(kind2, docs, now) {
+  const buckets = { future: 0, "0-7d": 0, "8-30d": 0, "31-90d": 0, "91-180d": 0, "181-365d": 0, ">365d": 0 };
+  let missing2 = 0, invalid = 0, older = 0;
+  const horizon = freshnessHorizonMs(kind2);
+  for (const doc2 of docs) {
+    const value = doc2.frontmatter.checked_on;
+    if (!filled(value)) {
+      missing2++;
+      continue;
+    }
+    const ms = typeof value === "string" ? parseTimestamp(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00Z` : value, "0.2") : null;
+    if (ms === null) {
+      invalid++;
+      continue;
+    }
+    const ageMs2 = now.getTime() - ms;
+    const days = Math.floor(ageMs2 / DAY);
+    const bucket = days < 0 ? "future" : days <= 7 ? "0-7d" : days <= 30 ? "8-30d" : days <= 90 ? "31-90d" : days <= 180 ? "91-180d" : days <= 365 ? "181-365d" : ">365d";
+    buckets[bucket]++;
+    if (horizon !== void 0 && ageMs2 > horizon) older++;
+  }
+  return { clock: "checked_on", horizon: kind2.freshnessHorizon ?? null, horizon_ms: horizon ?? null, missing: missing2, invalid, buckets, older_than_horizon: horizon === void 0 ? null : older };
+}
+function sourceStats(docs) {
+  const domains = /* @__PURE__ */ new Map();
+  const distribution2 = { "0": 0, "1": 0, "2": 0, "3": 0, "4": 0, "5+": 0 };
+  let total = 0, zero2 = 0, invalid = 0, nonUrl = 0;
+  for (const doc2 of docs) {
+    const raw = doc2.frontmatter.sources;
+    const list4 = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
+    let count5 = 0;
+    for (const item of list4) {
+      const resource = typeof item === "string" ? item : item && typeof item === "object" && !Array.isArray(item) ? item.resource : void 0;
+      if (typeof resource !== "string" || !filled(resource)) {
+        invalid++;
+        continue;
+      }
+      count5++;
+      try {
+        const domain3 = new URL(resource).hostname.toLowerCase().replace(/^www\./, "");
+        if (!domain3) {
+          nonUrl++;
+          continue;
+        }
+        domains.set(domain3, (domains.get(domain3) ?? 0) + 1);
+      } catch {
+        nonUrl++;
+      }
+    }
+    if (!count5) zero2++;
+    total += count5;
+    distribution2[count5 >= 5 ? "5+" : String(count5)]++;
+  }
+  const ordered = [...domains].sort((a, b) => b[1] - a[1] || compare(a[0], b[0]));
+  return { zero: zero2, total, invalid_entries: invalid, non_url_resources: nonUrl, per_record: distribution2, distinct_domains: domains.size, domains_shown: Math.min(domains.size, DOMAIN_LIMIT), top_domains: ordered.slice(0, DOMAIN_LIMIT).map(([domain3, sources]) => ({ domain: domain3, sources })) };
+}
+function kindCoverage(registry2, documents, options) {
+  if (!Number.isFinite(options.now.getTime())) throw new TypeError("Coverage now must be a valid date");
+  const docs = [...documents].sort((a, b) => compare(a.id, b.id));
+  const index2 = new Map(docs.map((doc2) => [doc2.id, doc2]));
+  const edges = new Map(docs.map((doc2) => [doc2.id, parseLinksFromDoc(doc2)]));
+  const inbound = new Set([...edges.values()].flat().map((link4) => link4.to));
+  const groups = /* @__PURE__ */ new Map();
+  for (const doc2 of docs) {
+    const type = doc2.frontmatter.type;
+    const group = groups.get(type) ?? [];
+    group.push(doc2);
+    groups.set(type, group);
+  }
+  const kinds2 = [...registry2.kinds.values()].filter((kind2) => options.kind === void 0 || kind2.governs === options.kind).map((kind2) => {
+    const records = groups.get(kind2.governs) ?? [];
+    const authoring = projectKindForAuthoring(options.okfVersion, kind2);
+    const fields2 = [.../* @__PURE__ */ new Set([...authoring.fields.required, ...authoring.fields.optional])].sort(compare);
+    const stats = fields2.map((field) => ({ field, required: authoring.fields.required.includes(field), ...fieldStats(records, (doc2) => readKindField(options.okfVersion, kind2, doc2.frontmatter, field)) }));
+    const declaredStorage = new Set(fields2.map((field) => resolveKindFieldCoordinate(options.okfVersion, kind2, field)?.storageField ?? field));
+    const undeclared = /* @__PURE__ */ new Map(), envelopes = /* @__PURE__ */ new Map();
+    for (const doc2 of records) for (const key2 of Object.keys(doc2.frontmatter)) {
+      if (envelope(key2)) {
+        envelopes.set(key2, (envelopes.get(key2) ?? 0) + 1);
+        continue;
+      }
+      if (!declaredStorage.has(key2)) {
+        const ids = undeclared.get(key2) ?? [];
+        ids.push(doc2.id);
+        undeclared.set(key2, ids);
+      }
+    }
+    const relations = /* @__PURE__ */ new Map();
+    let citations = 0, dangling = 0, withLinks = 0;
+    const danglingExamples = [];
+    for (const doc2 of records) {
+      const links = edges.get(doc2.id);
+      if (links.length) withLinks++;
+      for (const link4 of links) {
+        const target3 = index2.get(link4.to);
+        if (!target3) {
+          dangling++;
+          if (danglingExamples.length < EXAMPLES) danglingExamples.push(doc2.id);
+        }
+        if (!Object.hasOwn(kind2.links ?? {}, link4.text)) {
+          citations++;
+          continue;
+        }
+        const targetKind = target3?.frontmatter.type ?? null;
+        const key2 = JSON.stringify([link4.text, targetKind]);
+        const row4 = relations.get(key2) ?? { relation: link4.text, target_kind: targetKind, target_matches: targetKind === null ? null : targetKind === kind2.links[link4.text], records: /* @__PURE__ */ new Set(), links: 0 };
+        row4.records.add(doc2.id);
+        row4.links++;
+        relations.set(key2, row4);
+      }
+    }
+    const used = new Set([...relations.values()].map((row4) => row4.relation));
+    return {
+      governs: kind2.governs,
+      records: records.length,
+      coverage: { fields: stats, body_prose: { filled: records.filter((doc2) => bodyProse(doc2.body)).length, rate: ratio(records.filter((doc2) => bodyProse(doc2.body)).length, records.length) } },
+      drift: { undeclared: [...undeclared].sort(([a], [b]) => compare(a, b)).map(([key2, ids]) => ({ key: key2, records: ids.length, rate: ratio(ids.length, records.length), examples: ids.slice(0, EXAMPLES), examples_total: ids.length })), declared_unused: stats.filter((row4) => row4.present === 0).map((row4) => row4.field), envelope: [...envelopes].sort(([a], [b]) => compare(a, b)).map(([key2, records2]) => ({ key: key2, records: records2 })) },
+      links: { with_links: withLinks, typed: [...relations.values()].sort((a, b) => compare(a.relation, b.relation) || compare(a.target_kind ?? "", b.target_kind ?? "")).map((row4) => ({ relation: row4.relation, target_kind: row4.target_kind, target_matches: row4.target_matches, records: row4.records.size, links: row4.links, rate: ratio(row4.records.size, records.length) })), untyped_citations: citations, declared_never_used: Object.keys(kind2.links ?? {}).filter((relation) => !used.has(relation)).sort(compare), dangling, dangling_examples: danglingExamples, no_inbound: records.filter((doc2) => !inbound.has(doc2.id)).length },
+      freshness: checkedOn(kind2, records, options.now),
+      sources: sourceStats(records)
+    };
+  });
+  return { now: options.now.toISOString(), documents: docs.length, undeclared_kinds: [...groups.keys()].filter((type) => !registry2.kinds.has(type)).sort(compare), kinds: kinds2 };
+}
+var SENTINELS, EXAMPLES, DOMAIN_LIMIT, DAY, compare, ratio, empty, sentinel, filled, envelope;
+var init_kind_coverage = __esm({
+  "../core/src/kind-coverage.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_document_field_actions();
+    init_kinds();
+    init_links();
+    init_managed_document_metadata();
+    init_freshness();
+    SENTINELS = /* @__PURE__ */ new Set(["unknown", "n/a", "na", "none", "tbd", "null", "-", "?"]);
+    EXAMPLES = 3;
+    DOMAIN_LIMIT = 15;
+    DAY = 864e5;
+    compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+    ratio = (n, total) => total ? Math.round(n / total * 1e4) / 1e4 : null;
+    empty = (value) => value == null || typeof value === "string" && value.trim() === "" || (Array.isArray(value) ? value.length === 0 : typeof value === "object" && Object.keys(value).length === 0);
+    sentinel = (value) => typeof value === "string" && SENTINELS.has(value.trim().toLowerCase());
+    filled = (value) => !empty(value) && !sentinel(value);
+    envelope = (key2) => isManagedDocumentMetadataField(key2) || isStandardDocumentSetField(key2, "0.2") || key2 === "sources" || key2 === "tags";
+  }
+});
+
 // ../core/src/index.ts
 var init_src = __esm({
   "../core/src/index.ts"() {
@@ -11771,6 +11949,7 @@ var init_src = __esm({
     init_document_mutation();
     init_kind_field_mutation();
     init_managed_document_metadata();
+    init_kind_coverage();
   }
 });
 
@@ -15822,12 +16001,12 @@ function resolveCompatibleScalarEnv(opts) {
   const env = opts.env ?? process.env;
   const present = [opts.canonical, opts.legacy].filter((name) => hasOwn4(env, name)).map((name) => ({ name, value: (env[name] ?? "").trim() }));
   if (!present.length) return void 0;
-  const empty2 = present.filter((entry) => entry.value === "");
-  if (opts.requireNonEmpty && empty2.length) {
-    const sources = empty2.map((entry) => entry.name).join(" and ");
+  const empty3 = present.filter((entry) => entry.value === "");
+  if (opts.requireNonEmpty && empty3.length) {
+    const sources = empty3.map((entry) => entry.name).join(" and ");
     throw new CliError(
       "USAGE",
-      `${sources} ${empty2.length === 1 ? "was" : "were"} given an empty value - pass a ${opts.label} or unset the environment variable.`,
+      `${sources} ${empty3.length === 1 ? "was" : "were"} given an empty value - pass a ${opts.label} or unset the environment variable.`,
       opts.help ? { help: opts.help } : {}
     );
   }
@@ -17513,7 +17692,7 @@ var init_command_spec = __esm({
           {
             id: "kinds",
             leaves: [publicLeaf("kinds", "kinds", zero, 14, DIR_SURFACE)],
-            usage: "kinds [--dir <path>] [--remote <url>]",
+            usage: "kinds [--coverage [--kind <Kind>] [--now <ISO>]] [--dir <path>] [--remote <url>]",
             summary: "List the kind conventions this bundle declares (purpose, described fields, exact required body headings, typed-link vocabulary, horizon)"
           },
           {
@@ -25772,10 +25951,10 @@ function boundedLines(body, maximum) {
   );
 }
 function decodeDocumentRead(id, body, route) {
-  const envelope2 = body;
-  const data = envelope2?.data;
+  const envelope3 = body;
+  const data = envelope3?.data;
   const document4 = data?.document;
-  if (envelope2?.operationId !== "documents.read.v1" || envelope2.ok !== true || typeof data !== "object" || data === null || !isContentVersion(data.version) || typeof document4 !== "object" || document4 === null || document4.id !== id || typeof document4.frontmatter !== "object" || document4.frontmatter === null || Array.isArray(document4.frontmatter) || typeof document4.body !== "string")
+  if (envelope3?.operationId !== "documents.read.v1" || envelope3.ok !== true || typeof data !== "object" || data === null || !isContentVersion(data.version) || typeof document4 !== "object" || document4 === null || document4.id !== id || typeof document4.frontmatter !== "object" || document4.frontmatter === null || Array.isArray(document4.frontmatter) || typeof document4.body !== "string")
     throw malformed("document read answered an envelope that is not documents.read.v1's result for this document", route);
   return { doc: { id, frontmatter: document4.frontmatter, body: document4.body }, version: data.version };
 }
@@ -25792,9 +25971,9 @@ function decodeDocumentHistory(request3, body, route) {
   const fail4 = (why) => {
     throw malformed(`history answered ${why}`, route);
   };
-  const envelope2 = body;
-  if (envelope2?.operationId !== HISTORY_OPERATION_ID || envelope2.ok !== true) fail4(`an envelope that is not ${HISTORY_OPERATION_ID}'s result`);
-  const data = envelope2.data;
+  const envelope3 = body;
+  if (envelope3?.operationId !== HISTORY_OPERATION_ID || envelope3.ok !== true) fail4(`an envelope that is not ${HISTORY_OPERATION_ID}'s result`);
+  const data = envelope3.data;
   if (typeof data !== "object" || data === null || Array.isArray(data)) fail4("without its data");
   if (data.documentId !== request3.documentId) fail4("for another document");
   if (!Array.isArray(data.versions) || data.versions.length > request3.limit) fail4("more versions than asked for, or none as a list");
@@ -25836,10 +26015,10 @@ function decodeDocumentHistory(request3, body, route) {
   return Object.freeze({ documentId: request3.documentId, versions: Object.freeze(versions), more: data.more, ...total === void 0 ? {} : { total } });
 }
 function operationRefusal(body, operationId, route) {
-  const envelope2 = body;
-  if (envelope2?.ok !== false) return void 0;
-  const error51 = envelope2.error;
-  if (envelope2.operationId !== operationId || typeof error51 !== "object" || error51 === null || typeof error51.code !== "string" || !REFUSAL_CODE.test(error51.code))
+  const envelope3 = body;
+  if (envelope3?.ok !== false) return void 0;
+  const error51 = envelope3.error;
+  if (envelope3.operationId !== operationId || typeof error51 !== "object" || error51 === null || typeof error51.code !== "string" || !REFUSAL_CODE.test(error51.code))
     throw malformed(`answered a refusal that is not ${operationId}'s`, route);
   return refusalOf(error51.code, error51.message, error51.retryable);
 }
@@ -30216,10 +30395,10 @@ function ffSwallowToError(reason, inv, boardPath) {
 function syncEnvelope(home2, counts = {}) {
   return { home: home2, sent: counts.sent ?? 0, received: counts.received ?? 0, conflicts: counts.conflicts ?? 0, held: counts.held ?? 0, next: counts.next ?? [] };
 }
-function withSyncEnvelope(receipt3, envelope2) {
+function withSyncEnvelope(receipt3, envelope3) {
   const out = { ...receipt3 };
   if (!("schema_version" in out)) out.schema_version = SYNC_RECEIPT_SCHEMA_VERSION;
-  for (const key2 of SYNC_ENVELOPE_KEYS) if (!(key2 in out)) out[key2] = envelope2[key2];
+  for (const key2 of SYNC_ENVELOPE_KEYS) if (!(key2 in out)) out[key2] = envelope3[key2];
   return out;
 }
 function syncVerbNotApplicable(flags, home2, why, help2) {
@@ -31141,8 +31320,8 @@ async function showIncoming(id, values, deps, route) {
   try {
     await run();
   } catch (err) {
-    const { envelope: envelope2 } = toExit(err);
-    stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3 } = toExit(err);
+    stderr(renderErrorEnvelope(envelope3));
     throw asHandled(err);
   }
 }
@@ -35607,8 +35786,8 @@ async function sync(argv2, deps = {}) {
   try {
     await run();
   } catch (err) {
-    const { envelope: envelope2, handled } = toExit(err);
-    if (!handled) stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3, handled } = toExit(err);
+    if (!handled) stderr(renderErrorEnvelope(envelope3));
     throw handled ? err : asHandled(err);
   }
 }
@@ -35958,8 +36137,8 @@ async function failGate(run, board, commitResult, delta, reason, details) {
   );
   partial2.code = "GATE_FAILED";
   partial2.help = help2;
-  const envelope2 = syncEnvelope("git", { received: delta.originDelta.length, next: [`${run.inv} sync`] });
-  run.stdout(render(withSyncEnvelope(partial2, envelope2), run.mode));
+  const envelope3 = syncEnvelope("git", { received: delta.originDelta.length, next: [`${run.inv} sync`] });
+  run.stdout(render(withSyncEnvelope(partial2, envelope3), run.mode));
   await writeAwarenessCache(board.key, board.boardPath, delta.changes, delta.reanchorNote);
   throw new CliError("GATE_FAILED", `the sync gate ${reason}; nothing was pushed`, {
     help: help2,
@@ -36003,8 +36182,8 @@ function reportHeld(run, board, delta, held2, where, notPulled) {
   receipt3.held_documents = held2.map((doc2) => ({ id: doc2.id, path: doc2.relPath, reason: doc2.reason, detail: doc2.detail }));
   const fix = `fix the lines between the --- markers of ${held2.map((doc2) => doc2.relPath).join(", ")} (quote any value that contains ': '), check with ${run.inv} status, then run ${run.inv} sync`;
   receipt3.held_help = `not published: the YAML frontmatter of these documents does not parse, and publishing it would break every reader of the board, so this sync sent nothing. Your files are untouched; ${fix}` + (where === "committed locally" ? " (the fix is committed on top and both go out together)" : "");
-  const envelope2 = syncEnvelope("git", { received: delta.originDelta.length, held: held2.length, next: [`${run.inv} sync`] });
-  run.stdout(render(withSyncEnvelope(receipt3, envelope2), run.mode));
+  const envelope3 = syncEnvelope("git", { received: delta.originDelta.length, held: held2.length, next: [`${run.inv} sync`] });
+  run.stdout(render(withSyncEnvelope(receipt3, envelope3), run.mode));
   throw new CliError(
     "CONFLICT",
     `${held2.length} document(s) have invalid frontmatter (${held2.map((doc2) => doc2.id).join(", ")}); nothing was published`,
@@ -47352,7 +47531,7 @@ function visitParents(tree, test, visitor, reverse) {
     }
     return visit2;
     function visit2() {
-      let result3 = empty;
+      let result3 = empty2;
       let subresult;
       let offset;
       let grandparents;
@@ -47391,16 +47570,16 @@ function toResult(value) {
   if (typeof value === "number") {
     return [CONTINUE, value];
   }
-  return value === null || value === void 0 ? empty : [value];
+  return value === null || value === void 0 ? empty2 : [value];
 }
-var empty, CONTINUE, EXIT2, SKIP;
+var empty2, CONTINUE, EXIT2, SKIP;
 var init_lib5 = __esm({
   "../../node_modules/unist-util-visit-parents/lib/index.js"() {
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
     init_unist_util_is();
     init_color_node();
-    empty = [];
+    empty2 = [];
     CONTINUE = true;
     EXIT2 = false;
     SKIP = "skip";
@@ -48375,11 +48554,11 @@ var require_react_production = __commonJS({
         _init: lazyInitializer
       };
     };
-    exports.memo = function(type, compare) {
+    exports.memo = function(type, compare2) {
       return {
         $$typeof: REACT_MEMO_TYPE,
         type,
-        compare: void 0 === compare ? null : compare
+        compare: void 0 === compare2 ? null : compare2
       };
     };
     exports.startTransition = function(scope) {
@@ -49307,18 +49486,18 @@ var require_react_development = __commonJS({
         lazyType2._debugInfo = [{ awaited: ioInfo }];
         return lazyType2;
       };
-      exports.memo = function(type, compare) {
+      exports.memo = function(type, compare2) {
         null == type && console.error(
           "memo: The first argument must be a component. Instead received: %s",
           null === type ? "null" : typeof type
         );
-        compare = {
+        compare2 = {
           $$typeof: REACT_MEMO_TYPE,
           type,
-          compare: void 0 === compare ? null : compare
+          compare: void 0 === compare2 ? null : compare2
         };
         var ownName;
-        Object.defineProperty(compare, "displayName", {
+        Object.defineProperty(compare2, "displayName", {
           enumerable: false,
           configurable: true,
           get: function() {
@@ -49329,7 +49508,7 @@ var require_react_development = __commonJS({
             type.name || type.displayName || (Object.defineProperty(type, "name", { value: name }), type.displayName = name);
           }
         });
-        return compare;
+        return compare2;
       };
       exports.startTransition = function(scope) {
         var prevTransition = ReactSharedInternals.T, currentTransition = {};
@@ -76362,8 +76541,8 @@ async function docRead(argv2, deps) {
   try {
     await docReadInner(argv2, deps);
   } catch (err) {
-    const { envelope: envelope2, handled } = toExit(err);
-    if (!handled) stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3, handled } = toExit(err);
+    if (!handled) stderr(renderErrorEnvelope(envelope3));
     throw handled ? err : asHandled(err);
   }
 }
@@ -76558,8 +76737,8 @@ async function docReadInner(argv2, deps) {
       }
       stdout(formatFieldValue(resolveField(parsed2, version4, field, id)));
     } catch (err) {
-      const { envelope: envelope2 } = toExit(err);
-      stderr(renderErrorEnvelope(envelope2));
+      const { envelope: envelope3 } = toExit(err);
+      stderr(renderErrorEnvelope(envelope3));
       throw asHandled(err);
     }
     return;
@@ -77164,7 +77343,7 @@ function fields(value, required2, optional2 = []) {
   requireValue(required2.every((key2) => Object.hasOwn(value, key2)));
   requireValue(Object.keys(value).every((key2) => required2.includes(key2) || optional2.includes(key2)));
 }
-function envelope(value, schema) {
+function envelope2(value, schema) {
   const data = record3(value);
   requireValue(typeof data.schemaVersion === "string");
   requireValue(data.schemaVersion === schema, "unsupported_version");
@@ -77182,7 +77361,7 @@ function nullableVersion(value) {
   return value === null ? null : version2(value);
 }
 function target2(value) {
-  const data = envelope(value, "superbee.document-target.v1");
+  const data = envelope2(value, "superbee.document-target.v1");
   fields(data, ["schemaVersion", "authority", "bundleKey", "documentId"]);
   const authority = record3(data.authority);
   let parsedAuthority;
@@ -77221,12 +77400,12 @@ function provenance(value) {
   return data.state === "local-pending" ? { state: "local-pending", ...common } : { state: "local-conflict", ...common, remote: nullableVersion(data.remote) };
 }
 function observation(value) {
-  const data = envelope(value, "superbee.document-observation.v1");
+  const data = envelope2(value, "superbee.document-observation.v1");
   fields(data, ["schemaVersion", "target", "provenance", "lifecycle"]);
   return { schemaVersion: "superbee.document-observation.v1", target: target2(data.target), provenance: provenance(data.provenance), lifecycle: lifecycle(data.lifecycle) };
 }
 function request2(value) {
-  const data = envelope(value, "superbee.present-document.v1");
+  const data = envelope2(value, "superbee.present-document.v1");
   fields(data, ["schemaVersion", "operation", "invocationId", "target"], ["referenceVersion", "expectedLifecycle"]);
   requireValue(data.operation === "present_document");
   const expectedLifecycle = Object.hasOwn(data, "expectedLifecycle") ? lifecycle(data.expectedLifecycle) : void 0;
@@ -77258,7 +77437,7 @@ function presentation(value) {
   }
 }
 function receipt(value, expected) {
-  const data = envelope(value, "superbee.present-document-receipt.v1");
+  const data = envelope2(value, "superbee.present-document-receipt.v1");
   requireValue(typeof data.ok === "boolean");
   fields(data, ["schemaVersion", "operation", "invocationId", "target", "ok", data.ok ? "presentation" : "error"]);
   requireValue(data.operation === "present_document");
@@ -83519,8 +83698,8 @@ async function pull2(argv2, deps = {}) {
   try {
     await runToTarget();
   } catch (err) {
-    const { envelope: envelope2 } = toExit(err);
-    stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3 } = toExit(err);
+    stderr(renderErrorEnvelope(envelope3));
     throw asHandled(err);
   }
 }
@@ -85425,6 +85604,9 @@ async function kinds(argv2, deps = {}) {
     () => parseArgs20({
       args: argv2,
       options: {
+        coverage: { type: "boolean" },
+        kind: { type: "string" },
+        now: { type: "string" },
         dir: { type: "string" },
         remote: { type: "string" },
         json: { type: "boolean" },
@@ -85438,6 +85620,13 @@ async function kinds(argv2, deps = {}) {
     stdout(renderUsage(KINDS_USAGE));
     return;
   }
+  if (!values.coverage && (values.kind !== void 0 || values.now !== void 0)) {
+    throw new CliError("USAGE", "--kind and --now require --coverage");
+  }
+  if (values.coverage && values.remote !== void 0) throw new CliError("USAGE", "Kind coverage reads local bundles only; omit --remote");
+  const nowText = values.now;
+  const nowMs = nowText === void 0 ? Date.now() : parseTimestamp(/^\d{4}-\d{2}-\d{2}$/.test(nowText) ? `${nowText}T00:00:00Z` : nowText, "0.2");
+  if (nowMs === null) throw new CliError("USAGE", "--now requires a valid ISO date or explicit-zone instant");
   const bundle = await openBundle(values.dir, await resolveRemoteFlag(values.remote, values.dir));
   const [registry2, okfVersion] = await Promise.all([
     loadKinds(bundle),
@@ -85446,7 +85635,20 @@ async function kinds(argv2, deps = {}) {
   const declared = [...registry2.kinds.values()];
   const ordered = declared.some((kind2) => kind2.order !== void 0) ? declared : declared.sort((a, b) => a.governs.localeCompare(b.governs));
   const rows = ordered.map((kind2) => toRow(kind2, okfVersion));
+  if (values.coverage && values.kind !== void 0 && !registry2.kinds.has(values.kind)) {
+    throw new CliError("USAGE", "--kind must name an exact declared Kind");
+  }
   const out = { count: rows.length, kinds: rows };
+  if (values.coverage) {
+    const skipped = [];
+    const documents = await query2(bundle, {}, { onSkip: ({ id }) => skipped.push(id) });
+    const measurements = kindCoverage(registry2, documents, { now: new Date(nowMs), okfVersion, kind: values.kind });
+    const byKind = new Map(measurements.kinds.map((row4) => [row4.governs, row4]));
+    const selected2 = rows.filter((row4) => byKind.has(String(row4.governs))).map((row4) => ({ ...row4, ...byKind.get(String(row4.governs)) }));
+    out.count = selected2.length;
+    out.kinds = selected2;
+    out.coverage = { now: measurements.now, documents: measurements.documents, complete: skipped.length === 0, skipped_documents: skipped.length, skipped_examples: skipped.sort().slice(0, 3), undeclared_kinds: measurements.undeclared_kinds };
+  }
   if (registry2.warnings.length > 0) out.warnings = registry2.warnings;
   if (rows.length === 0) {
     out.help = [`${cliInvocation()} new "<Kind>" <id> --<field> <value>  (once a kind is declared)`];
@@ -85459,6 +85661,7 @@ var init_kinds2 = __esm({
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
+    init_errors4();
     init_output2();
     init_src();
     init_bundle2();
@@ -85470,6 +85673,7 @@ var init_kinds2 = __esm({
 
 Usage:
   superbee kinds [--dir <path>] [--remote <url>]
+  superbee kinds --coverage [--kind <Kind>] [--now <ISO instant or date>] [--dir <path>] [--json]
 
 A kind convention is a plain OKF doc (type: Convention) under conventions/ declaring a document
 kind's purpose, required/optional fields and their descriptions, allowed enum values, typed-link vocabulary, expected body
@@ -85528,7 +85732,22 @@ A misshaped or misplaced key here is a non-fatal registry warning (visible in 'k
 output), never a silent no-op. See 'superbee doc read conventions/context-note' on any
 --init'd bundle for a full worked example with a values: enum and sections:.
 
+Coverage is local and read-only: group all readable concepts by actual type, using the same
+registry, logical field aliases and concept-link resolver. Filled excludes null, blank strings,
+empty lists/maps and case-insensitive unknown/n/a/na/none/tbd/null/-/? sentinels; it is a measurement,
+not required-field validation. Zero-record rates are null. Body prose excludes headings, standalone
+links and Related sections at any ATX heading level (including descendants until the next same
+or higher-level heading). This is line measurement, not Markdown rendering. Drift separates standard/envelope fields. Typed links use exact
+Kind-declared labels; other concept links are untyped citations, not undeclared relation violations.
+Freshness measures checked_on domain date metadata against the Kind's minute/hour/day horizon,
+not its meaningful-change clock. Missing/invalid dates and absent horizons remain explicit.
+Examples are capped at 3 per drift field; source domains at 15 with total/shown counts. A skipped
+malformed document makes coverage partial; no remote, sync or network access is performed.
+
 Options:
+  --coverage           Add per-Kind field, drift, link, freshness and source measurements
+  --kind <Kind>        Select one exact declared type (requires --coverage)
+  --now <ISO>          Fixed UTC date or explicit-zone instant for coverage (requires --coverage)
   --dir <path>          Bundle directory (default: discovered from the cwd)
   --remote <url>        Talk to a wire-protocol server instead of a local bundle
                          (mutually exclusive with --dir; remote access is always explicit)
@@ -92145,12 +92364,12 @@ function cleanRegex(source) {
   return source.slice(start, end);
 }
 function floatSafeRemainder2(val, step) {
-  const ratio = val / step;
-  const roundedRatio = Math.round(ratio);
-  const tolerance = Number.EPSILON * Math.max(Math.abs(ratio), 1);
-  if (Math.abs(ratio - roundedRatio) < tolerance)
+  const ratio2 = val / step;
+  const roundedRatio = Math.round(ratio2);
+  const tolerance = Number.EPSILON * Math.max(Math.abs(ratio2), 1);
+  if (Math.abs(ratio2 - roundedRatio) < tolerance)
     return 0;
-  return ratio - roundedRatio;
+  return ratio2 - roundedRatio;
 }
 function defineLazy(object5, key2, getter) {
   let value = void 0;
@@ -119053,8 +119272,8 @@ var require_formats = __commonJS({
     init_define_SUPERBEE_UPDATE_POLICY();
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.formatNames = exports.fastFormats = exports.fullFormats = void 0;
-    function fmtDef(validate, compare) {
-      return { validate, compare };
+    function fmtDef(validate, compare2) {
+      return { validate, compare: compare2 };
     }
     exports.fullFormats = {
       // date: http://tools.ietf.org/html/rfc3339#section-5.6
@@ -125440,8 +125659,8 @@ async function mcp(argv2, deps = {}) {
   try {
     await mcpInner(argv2, deps);
   } catch (error51) {
-    const { envelope: envelope2, handled } = toExit(error51);
-    if (!handled) stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3, handled } = toExit(error51);
+    if (!handled) stderr(renderErrorEnvelope(envelope3));
     throw handled ? error51 : asHandled(error51);
   }
 }
@@ -128894,8 +129113,8 @@ async function postRoute(context, route, body, writeRequest) {
     }
     throw hostedFailure(error52, target3, resume2);
   }
-  const envelope2 = answer2.body ?? {};
-  const error51 = envelope2.error;
+  const envelope3 = answer2.body ?? {};
+  const error51 = envelope3.error;
   const code3 = typeof error51 === "string" ? error51 : typeof error51?.code === "string" ? error51.code : null;
   const message = typeof error51?.message === "string" ? error51.message : "";
   if (answer2.status === 503 && code3 === "write_outcome_unknown") throw unknown3();
@@ -128905,10 +129124,10 @@ async function postRoute(context, route, body, writeRequest) {
       help: "a later release of the host offers it; until then do this in the Superbee app"
     });
   }
-  if (answer2.status === 200 && envelope2.ok === true && typeof envelope2.data === "object" && envelope2.data !== null && !Array.isArray(envelope2.data)) {
-    return { ok: true, data: envelope2.data };
+  if (answer2.status === 200 && envelope3.ok === true && typeof envelope3.data === "object" && envelope3.data !== null && !Array.isArray(envelope3.data)) {
+    return { ok: true, data: envelope3.data };
   }
-  if (answer2.status === 200 && envelope2.ok === false && code3 !== null) return { ok: false, code: code3, message };
+  if (answer2.status === 200 && envelope3.ok === false && code3 !== null) return { ok: false, code: code3, message };
   throw hostedFailure(new RemoteError(`hosted ${route} answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), target3, resume2);
 }
 function accessRefusal(code3, hostMessage, subject) {
@@ -129280,8 +129499,8 @@ async function catalog(argv2, deps = {}) {
     try {
       await catalogInner(argv2, deps);
     } catch (err) {
-      const { envelope: envelope2, handled } = toExit(err);
-      if (!handled) stderr(renderErrorEnvelope(envelope2));
+      const { envelope: envelope3, handled } = toExit(err);
+      if (!handled) stderr(renderErrorEnvelope(envelope3));
       throw handled ? err : asHandled(err);
     }
     return;
@@ -134510,7 +134729,7 @@ function packParts(content3, versions) {
   const parts = [];
   let part = null;
   let size = 0;
-  const envelope2 = 512;
+  const envelope3 = 512;
   for (const version4 of new Set(versions)) {
     const object5 = content3.objects.get(version4);
     if (!object5) continue;
@@ -134518,7 +134737,7 @@ function packParts(content3, versions) {
     if (part === null || part.versions.length >= bounds.partObjects || size + bytes > bounds.partTargetBytes) {
       part = { documents: [], reserved: [], history: [], versions: [] };
       parts.push(part);
-      size = envelope2;
+      size = envelope3;
     }
     if (object5.kind === "documents") part.documents.push(object5.value);
     else if (object5.kind === "reserved") part.reserved.push(object5.value);
@@ -134642,19 +134861,19 @@ async function runStagedCreate(request3) {
     }
   }
   function read(name, answer2) {
-    const envelope2 = answer2.body ?? {};
-    const code3 = typeof envelope2.error?.code === "string" ? envelope2.error.code : null;
-    const message = typeof envelope2.error?.message === "string" ? envelope2.error.message : "";
-    if (answer2.status === 200 && envelope2.ok === true && typeof envelope2.data === "object" && envelope2.data !== null) return envelope2.data;
-    if (answer2.status === 200 && envelope2.ok === false && code3 === "staged_manifest_missing") return "no_manifest";
-    if (answer2.status === 200 && envelope2.ok === false && code3 === "request_conflict" && envelope2.error?.retryable === true) return "busy";
-    if (answer2.status === 200 && envelope2.ok === false && code3 === "validation_failed" && VERSION_MISMATCH.test(message)) {
+    const envelope3 = answer2.body ?? {};
+    const code3 = typeof envelope3.error?.code === "string" ? envelope3.error.code : null;
+    const message = typeof envelope3.error?.message === "string" ? envelope3.error.message : "";
+    if (answer2.status === 200 && envelope3.ok === true && typeof envelope3.data === "object" && envelope3.data !== null) return envelope3.data;
+    if (answer2.status === 200 && envelope3.ok === false && code3 === "staged_manifest_missing") return "no_manifest";
+    if (answer2.status === 200 && envelope3.ok === false && code3 === "request_conflict" && envelope3.error?.retryable === true) return "busy";
+    if (answer2.status === 200 && envelope3.ok === false && code3 === "validation_failed" && VERSION_MISMATCH.test(message)) {
       throw new CliError("RUNTIME", `${client.target.origin} stores an object differently from this CLI (client/host contract mismatch)`, {
         details: { reason: "staged_mismatch", route: name, host_message: message, host: client.target.origin, request_id: requestId2, retryable: false },
         help: `upgrade Superbee (npm install -g superbee), then re-run the same command, which resumes this creation: ${request3.resume}`
       });
     }
-    if (answer2.status === 200 && envelope2.ok === false && code3 !== null) throw new StagedRefusal(code3, message, reserved, name);
+    if (answer2.status === 200 && envelope3.ok === false && code3 !== null) throw new StagedRefusal(code3, message, reserved, name);
     if (answer2.status === 429 && code3 === "bundle_create_limit") throw new StagedRefusal(code3, message, reserved, name);
     if (answer2.status === 400 && !reserved) throw new StagedRefusal(code3 ?? "invalid_input", message || `the host refused ${name} as malformed`, false, name);
     throw hostedFailure(new RemoteError(`hosted ${name} answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), client.target, request3.resume);
@@ -135049,9 +135268,9 @@ async function sendCreation(plan, context) {
     }
     throw hostedFailure(error51, target3, yesCommand);
   }
-  const envelope2 = answer2.body ?? {};
-  const code3 = typeof envelope2.error?.code === "string" ? envelope2.error.code : null;
-  const hostMessage = typeof envelope2.error?.message === "string" ? envelope2.error.message : "";
+  const envelope3 = answer2.body ?? {};
+  const code3 = typeof envelope3.error?.code === "string" ? envelope3.error.code : null;
+  const hostMessage = typeof envelope3.error?.message === "string" ? envelope3.error.message : "";
   if (answer2.status === 503 && code3 === "write_outcome_unknown") {
     throw new CliError("TRANSIENT", `${target3.origin} may have partly created '${bundleId}'`, {
       details: { reason: "write_outcome_unknown", bundle_id: bundleId, workspace, host: target3.origin, request_id: requestId2, retryable: true },
@@ -135063,16 +135282,16 @@ async function sendCreation(plan, context) {
     if (forgettable) await clearPendingCreate(home2, canonical2, bundleId);
     throw createRefusal(code3, hostMessage, refusalContext);
   }
-  if (answer2.status === 200 && envelope2.ok === false && code3 !== null) {
+  if (answer2.status === 200 && envelope3.ok === false && code3 !== null) {
     if (code3 !== "request_conflict" && forgettable) await clearPendingCreate(home2, canonical2, bundleId);
     throw createRefusal(code3, hostMessage, refusalContext);
   }
-  if (answer2.status !== 200 || envelope2.ok !== true || typeof envelope2.data !== "object" || envelope2.data === null) {
+  if (answer2.status !== 200 || envelope3.ok !== true || typeof envelope3.data !== "object" || envelope3.data === null) {
     if (answer2.status === 400 && forgettable) await clearPendingCreate(home2, canonical2, bundleId);
     throw hostedFailure(new RemoteError(`hosted bundle-create answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), target3, yesCommand);
   }
   await clearPendingCreate(home2, canonical2, bundleId);
-  return envelope2.data;
+  return envelope3.data;
 }
 async function publish(argv2, partial2 = {}) {
   const deps = publishDeps(partial2);
@@ -135800,7 +136019,7 @@ async function main(argv2) {
       await main(hoisted);
       return;
     }
-    const envelope2 = toEnvelope(
+    const envelope3 = toEnvelope(
       new CliError(
         "USAGE",
         `options must follow the command (e.g. '${cliInvocation()} ${commandWords(command)} \u2026').`,
@@ -135809,7 +136028,7 @@ async function main(argv2) {
         }
       )
     );
-    process.stdout.write(renderErrorEnvelope(envelope2));
+    process.stdout.write(renderErrorEnvelope(envelope3));
     process.exitCode = 2;
     return;
   }
@@ -135829,8 +136048,8 @@ async function main(argv2) {
     },
     renderUnknownCommand: (cmd) => renderErrorEnvelope(toEnvelope(unknownCommandError(cmd))),
     formatError: (err) => {
-      const { exitCode, envelope: envelope2, handled } = toExit(err);
-      return { output: handled ? "" : renderErrorEnvelope(envelope2), exitCode };
+      const { exitCode, envelope: envelope3, handled } = toExit(err);
+      return { output: handled ? "" : renderErrorEnvelope(envelope3), exitCode };
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.2-pre.4",
+  "version": "0.4.3-pre.1",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [