@soleur/opencode 0.0.0-stage → 1.0.0

package/lib/heartbeat-manifest.ts

@@ -0,0 +1,342 @@
+// The heartbeat arming manifest (#6242 Audit Matrix Deliverable A; extracted from
+// heartbeat-reprovision-parity.test.ts for #6537).
+//
+// A heartbeat's "what feeds this?" answer used to live in a code COMMENT. #6537: the registry's
+// said a probe cron had shipped; it had never been written, and the monitor sat inert for 9 days.
+// A comment cannot fail CI, so `feeder` below is EXECUTABLE — every arming claim is a file plus a
+// syntactic construct the parity test greps on every run. See ADR-117 for the decision, the
+// rejected alternatives, and the states this does NOT cover.
+
+/** How a heartbeat's ping is armed — keyed on the MONITORED HOST'S REMEDIATION (CTO, #6242). */
+export type Arming =
+  | "dedicated-host-boot"
+  | "web-host-cron"
+  | "app-emit"
+  | "external-probe";
+
+/**
+ * What actually emits the ping.
+ *
+ * `cron`/`timer` carry EVIDENCE: a file, and the **arming construct** within it — the line that
+ * actually causes the feeder to run (`systemctl enable --now <unit>`, a `- path: /etc/cron.d/<x>`
+ * drop-in). Deliberately NOT the unit's bare name: `inngest-heartbeat.timer` appears three times
+ * in its bootstrap script, and one of them is a comment — so a bare-name check stays green after
+ * the arming line is deleted, i.e. prose alone would satisfy the guard built to kill prose.
+ * Matching runs against a COMMENT-STRIPPED view for the same reason.
+ *
+ * A `cron` row may instead name a WORKFLOW (`.github/workflows/<x>.yml`) and the `bash scripts/<x>.sh`
+ * line that runs the verifier (ADR-117 amendment 2026-10-11): `checkFeeders` then also requires a
+ * `schedule:` trigger or a `WATCHDOG_DISPATCH_TABLE` row, and that the script exists.
+ *
+ * `none` is the honest declaration that nothing pings this heartbeat yet. It is not a loophole: it
+ * costs a `tracking_issue`, and the guard asserts the heartbeat has no feeder by EITHER delivery
+ * route this repo uses (see `feederDeliveryProbes`).
+ */
+export type Feeder =
+  | {
+      kind: "cron" | "timer";
+      /** `file` is repo-root-relative; `pattern` is matched as a FIXED string (grep -F). */
+      evidence: { file: string; pattern: string };
+    }
+  | {
+      kind: "none";
+      /**
+       * The Doppler secret holding this heartbeat's ping URL, or null if none is provisioned.
+       * When non-null the guard asserts it has zero DEREFERENCING consumers.
+       */
+      url_secret: string | null;
+      /** The issue that owns building the feeder — or deleting the heartbeat. */
+      tracking_issue: number;
+    };
+
+export interface ManifestEntry {
+  /** The resource name (betteruptime_heartbeat.<name>). */
+  name: string;
+  arming: Arming;
+  /** DECLARED paused value; asserted equal to the value parsed from the .tf source. */
+  paused: boolean;
+  /** What pings it. Executable — see the Feeder docstring. */
+  feeder: Feeder;
+  /**
+   * Required IFF arming === "dedicated-host-boot". `choice` is the apply_target option; `server`
+   * is the `hcloud_server.<host>` the job -replaces.
+   */
+  replace_target?: { choice: string; server: string };
+  /** Required for every entry whose arming is NOT dedicated-host-boot. */
+  exempt_reason?: string;
+  /**
+   * Declares that this heartbeat's arming is DELIBERATELY deferred (created paused in Better Stack,
+   * to be armed out-of-band later — ADR-117 "FED-but-inert", a legal state at merge). When set, the
+   * nightly live-reconcile (#6549 item 2) does NOT raise the `fed-but-paused` alert for this row: a
+   * paused-yet-fed monitor is EXPECTED during the owner's deferred-arming window. It costs an owning
+   * issue — the honest-declaration idiom mirrors `feeder:{kind:"none", tracking_issue}`. Remove it
+   * (at cutover/arming) and a still-paused fed monitor fires for real. It does NOT suppress the
+   * `absent-live` alert — a declared-but-not-applied monitor is still surfaced.
+   */
+  arming_pending?: { tracking_issue: number };
+}
+
+/**
+ * Regexes that detect a feeder for `<name>`, one per delivery route this repo actually uses.
+ * An unfed (`kind:"none"`) row must match NEITHER. Both are needed:
+ *
+ *  - **deref**: the feeder reads the URL from a Doppler secret (`$INNGEST_HEARTBEAT_URL` in
+ *    inngest-bootstrap.sh — the live, armed precedent). Anchored on the DEREFERENCE, never the
+ *    bare name: a bare-name grep also matches the secret's own `name = "..."` definition and
+ *    plain prose, so it reports feeders that do not exist — the very fiction being replaced.
+ *  - **bake**: the feeder gets the URL baked in via `templatefile` (`liveness_heartbeat_url =
+ *    betteruptime_heartbeat.registry_prd.url`), dereferencing nothing. This is the route #6537
+ *    itself introduced, so a deref-only guard would be blind to the exact shape this repo now
+ *    treats as canonical. `value = ...` is excluded: that is a doppler_secret/output DEFINITION,
+ *    not a delivery into a template.
+ */
+export function feederDeliveryProbes(name: string, urlSecret: string | null): RegExp[] {
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const probes: RegExp[] = [
+    new RegExp(`^\\s*(?!value\\s*=)[A-Za-z0-9_]+\\s*=\\s*betteruptime_heartbeat\\.${esc(name)}\\.url`, "m"),
+  ];
+  if (urlSecret) probes.push(new RegExp(`\\$\\{?${esc(urlSecret)}\\}?`));
+  return probes;
+}
+
+// One row per heartbeat. Adding a heartbeat to the .tf files WITHOUT adding a row here FAILS the
+// discovered⊆manifest assertion.
+export const MANIFEST: ManifestEntry[] = [
+  {
+    name: "github_webhook_sig_failures",
+    arming: "app-emit",
+    paused: true,
+    // Its source comment claimed the webhook route "deliberately pings" this. Nothing does.
+    feeder: { kind: "none", url_secret: null, tracking_issue: 6549 },
+    exempt_reason:
+      "app/container would emit the ping; remediation is a container ci-deploy, not a dedicated-host reprovision. count=0 under the free tier (betterstack_paid_tier=false), so it is not provisioned live.",
+  },
+  {
+    name: "github_api_429_sustained",
+    arming: "app-emit",
+    paused: true,
+    // Structurally the same unfed shape as its sibling above, at a different cadence (900/120 vs
+    // 300/60) — and it never carried the false ping claim; that sat on only one of the two.
+    feeder: { kind: "none", url_secret: null, tracking_issue: 6549 },
+    exempt_reason:
+      "app/container would emit the ping; remediation is a container ci-deploy, not a dedicated-host reprovision. count=0 under the free tier (betterstack_paid_tier=false), so it is not provisioned live.",
+  },
+  {
+    name: "workspaces_luks",
+    // #6604 — the daily /workspaces LUKS at-rest probe heartbeat. Two pushers feed it:
+    //   1. luks-monitor.timer on web-1, delivered and armed by terraform_data.luks_monitor_install
+    //      (workspaces-luks.tf) in the per-merge SSH apply (#8706). Until #8706 the only installer
+    //      was the cutover script's tail, which no real cutover reached, so this pusher never ran
+    //      (ADR-119 addendum 2026-09-27; ADR-117 amendment 2026-09-27).
+    //      Terraform is the PRIMARY installer. The cutover tail still installs the same files, so it
+    //      stays a redundant second installer for a future re-cut.
+    //   2. The daily workspaces-luks-verify.yml job, which ships its own copy of luks-monitor.sh.
+    // The shared beat cannot tell them apart. The runtime proof that pusher 1 runs is
+    // logtail_exploration_alert.luks_monitor_host_timer_dark (betterstack-logs-alerts.tf).
+    // web-1 is cx33-unrebuildable and never re-runs cloud-init, so there is NO host-replace path:
+    // web-host-cron, NOT dedicated-host-boot, and the replace_target requirement does not fire.
+    arming: "web-host-cron",
+    paused: true,
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/workspaces-luks.tf",
+        pattern: "systemctl enable --now luks-monitor.timer",
+      },
+    },
+    // No `arming_pending`: it is ARMED. This row carried `arming_pending: { tracking_issue: 6604 }`
+    // while the monitor waited for the cutover's first measured beat. The beat has pushed since
+    // 2026-08-04 (runbook workspaces-luks-cutover-6604.md, "Failure signals"), and a read-only
+    // GET /api/v2/heartbeats/478794 on 2026-09-27 (#8706) read soleur-workspaces-luks-prd
+    // `paused:false status:up`. Removal follows OBSERVED arming, not #6604 closing (the
+    // inngest_consumer precedent), so the live reconcile's `fed-but-paused` alarm is re-armed for
+    // this row: a pause from here on is a real finding. `paused: true` above is SOURCE state only.
+    exempt_reason:
+      "web-host-resident feeder (luks-monitor.timer on web-1) delivered and armed by the SSH terraform_data provisioner (terraform_data.luks_monitor_install, #8706) as the PRIMARY installer; the cutover script's tail still installs the same files as a redundant second installer for a future re-cut, and web-1 cloud-init boot is NOT a path — web-1 is cx33-unrebuildable and never re-runs cloud-init, so there is NO <host>-host-replace path. The second pusher is the workspaces-luks-verify.yml job; the runtime proof that the host timer fires is logtail_exploration_alert.luks_monitor_host_timer_dark. Not dedicated-host-boot, so ADR-103's replace_target requirement correctly does not fire.",
+  },
+  {
+    name: "git_data_prd",
+    arming: "web-host-cron",
+    paused: true,
+    // #5274 PR C (#6548) SHIPPED the web-host probe — so this row is FLIPPED from the former
+    // {kind:"none", tracking_issue:6548} to a fed timer. The forcing function #6537 lacked fired
+    // exactly as designed: shipping web-git-data-probe.sh (which dereferences GIT_DATA_HEARTBEAT_URL)
+    // reddened the "still unfed by BOTH routes" tripwire, forcing this reconciliation. The feeder is
+    // the SSH-provisioner-delivered timer (terraform_data.git_data_probe_install in server.tf).
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/server.tf",
+        pattern: "systemctl enable --now web-git-data-probe.timer",
+      },
+    },
+    exempt_reason:
+      "web-host-resident feeder (web-git-data-probe.timer on web-1), delivered by the SSH terraform_data provisioner — NOT a git-data cloud-init cron. Reprovisioning git-data would not arm it; its remediation is web-host ci-deploy/provision. (git-data-host-replace exists for immutable-redeploy compliance, not to arm this heartbeat.)",
+  },
+  {
+    name: "web_zot_consumer",
+    // #6438 §1 — the zot CONSUMER-perspective serviceability probe. web-host-cron (NOT dedicated-
+    // host-boot): web-1 is cx33-unrebuildable and never re-runs cloud-init, so the feeder is
+    // delivered by an SSH terraform_data provisioner — there is NO <host>-host-replace path, and
+    // ADR-103's replace_target requirement correctly does not fire (mirrors workspaces_luks/
+    // git_data_prd). for_each var.web_hosts, so the discovered resource name is web_zot_consumer.
+    arming: "web-host-cron",
+    // paused in source (ignore_changes=[paused]); the apply-workflow arm gate PATCHes it live after
+    // a measured beat (ADR-117 automated). Source stays paused, so this stays true (mirrors
+    // inngest_prd/registry_prd: source paused, live unpaused after a one-time measured PATCH).
+    paused: true,
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/server.tf",
+        pattern: "systemctl enable --now web-zot-consumer-probe.timer",
+      },
+    },
+    exempt_reason:
+      "web-host-resident feeder (web-zot-consumer-probe.timer on web-1) delivered by the SSH terraform_data provisioner (terraform_data.zot_consumer_probe_install), NOT web-1 cloud-init boot — web-1 is cx33-unrebuildable and never re-runs cloud-init, so there is NO <host>-host-replace path. Not dedicated-host-boot, so ADR-103's replace_target requirement correctly does not fire.",
+  },
+  {
+    name: "web_nic_guard",
+    // #6438 §3 — the private-NIC self-report's dedicated liveness beat (pinged every healthy guard
+    // run so the SOLEUR_PRIVATE_NIC emitter is observable-when-healthy). Same web-host-cron/SSH-
+    // provisioner delivery + arming shape as web_zot_consumer above; PERMANENT and independent of
+    // the zot beat (distinct failure domain — folding would re-introduce OR-masking).
+    arming: "web-host-cron",
+    paused: true,
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/server.tf",
+        pattern: "systemctl enable --now web-private-nic-guard.timer",
+      },
+    },
+    exempt_reason:
+      "web-host-resident feeder (web-private-nic-guard.timer on web-1) delivered by the SSH terraform_data provisioner (terraform_data.private_nic_guard_install), NOT web-1 cloud-init boot — web-1 is cx33-unrebuildable. No <host>-host-replace path, so ADR-103's replace_target requirement correctly does not fire.",
+  },
+  {
+    name: "inngest_consumer",
+    // #7228 — the inngest CONSUMER-perspective serviceability beat. web-host-cron, not
+    // dedicated-host-boot, and that is the entire point of the design: its feeder runs on web-1
+    // and reads 10.0.1.40:8288 over the private net, so it detects a dark dedicated host WITHOUT
+    // depending on that host's bootstrap having run and WITHOUT a host replace. web-1 is
+    // cx33-unrebuildable and never re-runs cloud-init, so delivery is the SSH terraform_data
+    // provisioner and ADR-103's replace_target requirement correctly does not fire (mirrors
+    // web_zot_consumer / git_data_prd / workspaces_luks).
+    arming: "web-host-cron",
+    paused: true,
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/server.tf",
+        pattern: "systemctl enable --now inngest-consumer-probe.timer",
+      },
+    },
+    // No `arming_pending`: it is ARMED. This row carried `arming_pending: { tracking_issue: 7462 }`
+    // while the dedicated inngest host had not bound :8288 (the probe correctly suppressed every
+    // beat), and its removal was to follow OBSERVED arming, not #7462 closing. Observed 2026-09-15
+    // (#7884 review, read-only GET /api/v2/heartbeats): soleur-inngest-consumer-prd id 482259
+    // `paused:false status:up`, with #7462 CLOSED 2026-08-20. So the twice-daily live reconcile's
+    // `fed-but-paused` alarm is re-armed for this row: a pause from here on is a real finding.
+    exempt_reason:
+      "web-host-resident feeder (inngest-consumer-probe.timer on web-1) delivered by the SSH terraform_data provisioner (terraform_data.inngest_consumer_probe_install), NOT cloud-init boot on either host. It monitors the dedicated inngest host from the consumer side precisely so that arming it never requires an inngest-host-replace, so ADR-103's replace_target requirement correctly does not fire.",
+  },
+  {
+    name: "inngest_prd",
+    arming: "dedicated-host-boot",
+    // Source says paused=true; LIVE is paused=false / up (self-pulled from /api/v2/heartbeats).
+    // That divergence is the proof that source is not live: Terraform never sets paused=false, and
+    // ignore_changes=[paused] means it never reverts one. It was armed out-of-band once its feeder
+    // existed — exactly the step registry_prd never got.
+    paused: true,
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/inngest-bootstrap.sh",
+        pattern: "systemctl enable --now inngest-heartbeat.timer",
+      },
+    },
+    replace_target: { choice: "inngest-host-replace", server: "hcloud_server.inngest" },
+  },
+  {
+    name: "registry_prd",
+    // #6537: was `web-host-cron` + an exempt_reason citing an unshipped probe cron — the
+    // classification was the bug's hiding place. It is armed by the registry's OWN cloud-init now,
+    // so it is dedicated-host-boot, which makes ADR-103's replace_target requirement fire. That is
+    // intended: cloud-init is per-instance, so the feeder reaches the host only on a fresh boot.
+    arming: "dedicated-host-boot",
+    // Stays paused in source; live arming is a one-time API PATCH after a real beat is measured.
+    paused: true,
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/cloud-init-registry.yml",
+        pattern: "systemctl enable --now zot-liveness-heartbeat.timer",
+      },
+    },
+    replace_target: { choice: "registry-host-replace", server: "hcloud_server.registry" },
+  },
+  {
+    name: "git_data_host_prd",
+    // #9438: the git-data HOST's own recurring liveness beat (git-data-liveness.timer), distinct
+    // from git_data_prd above, which is fed by a web-host cron and proves only that some web host
+    // can open a TCP connection to the port. Armed by the host's OWN cloud-init, so it is
+    // dedicated-host-boot, which makes ADR-103's replace_target requirement fire: cloud-init is
+    // per-instance, so the feeder reaches the host only on a fresh boot (git-data-host-replace).
+    arming: "dedicated-host-boot",
+    // Born paused and stays paused in source; live arming is the owner-authorized, measured
+    // arm step after the replaced host's first beats (ADR-117, ADR-283).
+    paused: true,
+    feeder: {
+      kind: "timer",
+      evidence: {
+        file: "apps/web-platform/infra/cloud-init-git-data.yml",
+        pattern: "systemctl enable --now git-data-liveness.timer",
+      },
+    },
+    replace_target: { choice: "git-data-host-replace", server: "hcloud_server.git_data" },
+    // No `arming_pending` (record PR for #9438). This row carried `arming_pending: { tracking_issue: 9438 }`
+    // while the monitor was paused-yet-fed between the host replace and the arm. On 2026-10-12 a measured
+    // arm (`arm-heartbeats.sh --arm-one`, #9980) read `up` within 11 s; the verdict and the pre/post
+    // `--status` reads are on #9438. That is a dated record: the live state is read from Better Stack, not
+    // from this file. `paused: true` above stays: it is the source `.tf` state (born paused).
+  },
+  {
+    name: "registry_disk_prd",
+    arming: "dedicated-host-boot",
+    paused: false,
+    // The #6238 exemplar. NOTE its scope, which #6537 mis-stated: it pings on `df` alone, so it
+    // alarms HOST death by absence but stays GREEN with zot dead. registry_prd covers that gap.
+    // A cron.d drop-in is armed by existing, so its `- path:` delivery IS the arming construct.
+    feeder: {
+      kind: "cron",
+      evidence: {
+        file: "apps/web-platform/infra/cloud-init-registry.yml",
+        pattern: "- path: /etc/cron.d/zot-disk-heartbeat",
+      },
+    },
+    replace_target: { choice: "registry-host-replace", server: "hcloud_server.registry" },
+  },
+  {
+    name: "inngest_server_probe",
+    // #8516 — the dead-probe sibling of logtail_exploration_alert.inngest_luks_wrong_volume:
+    // a pusher beats it only while a fresh host_role=dedicated inngest-server-probe row
+    // reaches the warehouse (hourly emission cadence; period 3600 + grace 1800). FED and ARMED.
+    // No `arming_pending` (record PR for #9703). This row carried `arming_pending: { tracking_issue: 9703 }`
+    // while the monitor was paused-yet-fed. On 2026-10-12 the runbook arm block unpaused it; its read-back
+    // was `status=up paused=false`, and the feeder (scripts/inngest-probe-heartbeat-feeder.sh) then reported
+    // `verdict=beat` on runs 38264380002 (forced), 38265381453 and 38267189184 (clock-dispatched). That is a
+    // dated record: the live state is read from Better Stack, not from this file. `paused: true` below stays:
+    // it is the source `.tf` state (born paused).
+    arming: "external-probe",
+    paused: true,
+    feeder: {
+      kind: "cron",
+      evidence: {
+        file: ".github/workflows/scheduled-inngest-probe-heartbeat.yml",
+        pattern: "bash scripts/inngest-probe-heartbeat-feeder.sh",
+      },
+    },
+    exempt_reason:
+      "fed and armed (2026-10-12, #9703) — the feeder is a repo-side verifier workflow, remediation never requires an inngest-host-replace, precisely because a host push cannot see Vector-allowlist or sink failures (#6780). Not dedicated-host-boot, so ADR-103's replace_target requirement correctly does not fire.",
+  },
+];

package/lib/kb-coverage.ts

@@ -0,0 +1,252 @@
+// Coverage summary for /soleur:sync (#7332, plan Phase 3).
+//
+// Reports what Soleur EXPECTS a knowledge base to contain versus what is PRESENT,
+// as a deterministic committed artifact plus a stdout marker.
+//
+// ‼️ WORDING IS A HARD CONSTRAINT, NOT A STYLE PREFERENCE. This file lands in the
+// CUSTOMER's own repository, committed, timestamped by git, and permanently
+// blamed. "missing: privacy policy" is a durable, discoverable assertion that a
+// business lacks a compliance artifact — written by us, about them, into a record
+// they cannot erase. "no `privacy-policy.md` present in this knowledge base" says
+// the same operational thing about OUR expectation without asserting anything
+// about their business. Every string below is written to that rule and a test
+// enforces both halves of it (no deficiency framing AND the expectation phrasing
+// present) — because a report can easily carry the right header and still emit a
+// deficiency bullet per row.
+//
+// ‼️ DETERMINISM IS REQUIRED. No timestamp, no run id, sorted ordering. An
+// unchanged KB must render byte-identically or every sync emits a one-field diff
+// forever. knowledge-base/INDEX.md is the in-repo warning for exactly this shape.
+//
+// OBSERVABILITY: layer 7 (`cli-stdout-artifact`). The marker is emitted TWICE —
+// on stdout, where the agent and operator read it in-session, and as a line in
+// this artifact, so it survives the session. There is no Soleur-side sink for a
+// self-hosted CLI run and there must not be one (ADR-171 §Observability
+// boundary), which is why the durable artifact IS the queryable surface. The
+// marker therefore carries COUNTS ONLY: no path, no filename, no repo URL.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Marker sentinel. Kept identical on both surfaces so one grep finds either. */
+export const PRODUCERS_MARKER = "SOLEUR_KB_SYNC_PRODUCERS";
+export const ERROR_MARKER = "SOLEUR_KB_SYNC_ERROR";
+
+/**
+ * The five counts, in emission order. Exported so the drift guard can assert the
+ * stdout marker and the artifact's marker line carry a byte-identical field set —
+ * the plan's discoverability_test greps the ARTIFACT, so a divergence would make
+ * that test silently verify something other than what the run reported.
+ */
+export const MARKER_FIELDS = [
+  "c4_elements",
+  "c4_relationships",
+  "domain_model_rows",
+  "coverage_present",
+  "coverage_expected",
+] as const;
+
+/**
+ * ‼️ EVERY FIELD HERE IS A FUNCTION OF KB STATE, NEVER OF THE RUN.
+ *
+ * That is the invariant that makes this artifact deterministic, and the original
+ * design broke it in one place: `domain_model_rows` meant "rows appended by THIS
+ * run", which is N on a fresh register and 0 on the next sync once dedup no-ops.
+ * Since the marker is embedded in the committed file, an unchanged KB produced a
+ * guaranteed one-field diff on every second sync — AC11's byte-stability claim was
+ * false by construction, and the determinism test passed only because its fixture
+ * handed identical counts to both runs.
+ *
+ * The field now means "rows the register currently HOLDS", which is state, so
+ * determinism follows from the definition instead of from a fixture. Run-scoped
+ * facts ("appended 3 rows this run") belong on stdout, which is where run-scoped
+ * facts belong — the artifact is a snapshot, the stream is a log.
+ *
+ * Corollary for callers: derive these counts, do not pass them in. Flags that can be
+ * forgotten reconstruct the same failure — an absent `--c4-elements` silently
+ * produced `c4_elements=0`, byte-identical to the plan's headline failure mode.
+ */
+export type CoverageSources = {
+  /** Rendered model, if committed. Absent/unparseable ⇒ zeros, reported honestly. */
+  modelJson: string | null;
+  /** The domain-model register, if present. */
+  registerMarkdown: string | null;
+};
+
+export type ProducerCounts = Record<(typeof MARKER_FIELDS)[number], number>;
+
+/**
+ * What Soleur expects a populated knowledge base to contain, KB-relative.
+ *
+ * ‼️ Every entry must be a path a Soleur producer ACTUALLY writes. This shipped with
+ * `overview/constitution.md` while sync.md's Definition Sync reads and writes
+ * `project/constitution.md`, so Soleur's own knowledge base would have reported a
+ * permanent "no constitution present" line against a file one directory away — in
+ * every customer repo. Nothing caught it because every test indexed the constant it
+ * was pinning (`[0]`, `[1]`, `.length`), which is self-referential. A parity test now
+ * pins the constitution entry against sync.md.
+ *
+ * PR 1 keeps this a static list. PR 2 replaces it with the blueprint manifest —
+ * that substitution is the ONLY coupling between the two PRs, which is why the
+ * shape here is deliberately just an ordered string list.
+ *
+ * Sorted at module scope so ordering can never depend on edit history.
+ */
+export const EXPECTED_KB_PATHS: readonly string[] = [
+  "engineering/architecture/diagrams/model.likec4.json",
+  "engineering/architecture/domain-model.md",
+  "project/constitution.md",
+  "product/prd",
+  "project/README.md",
+  "project/components",
+  "project/learnings",
+  "project/rule-metrics.json",
+  "project/specs",
+].slice().sort();
+
+export type CoverageEntry = { path: string; present: boolean };
+
+/** Probe each expected path under `kbRoot`. Order is the sorted expected order. */
+export function assessCoverage(kbRoot: string): CoverageEntry[] {
+  return EXPECTED_KB_PATHS.map((path) => ({ path, present: existsSync(join(kbRoot, path)) }));
+}
+
+/**
+ * Count the rows the register currently holds under `## Auto-inferred (unreviewed)`.
+ *
+ * Auto-inferred ONLY — the curated `## Business Rules` table is hand-authored and is
+ * not coverage this sync produced, so counting it would make the number move when a
+ * human edits the register rather than when sync does.
+ *
+ * Stops at the next `## ` heading so a register whose Auto-inferred section precedes
+ * the curated one does not spill into it — the same section-boundary bug that let
+ * write-row append into the curated table.
+ */
+export function countAutoInferredRows(registerMarkdown: string | null): number {
+  if (!registerMarkdown) return 0;
+  let inSection = false;
+  let rows = 0;
+  for (const line of registerMarkdown.split("\n")) {
+    if (/^## Auto-inferred \(unreviewed\)/.test(line)) {
+      inSection = true;
+      continue;
+    }
+    if (inSection && /^## /.test(line)) break;
+    if (!inSection) continue;
+    // A data row: starts with `|`, and is neither the header nor the `|---` rule.
+    if (/^\|/.test(line) && !/^\|[\s-]*-[\s-]*\|/.test(line) && !/^\|\s*Anchor\s*\|/.test(line)) {
+      rows++;
+    }
+  }
+  return rows;
+}
+
+/**
+ * Derive every marker count from KB state. See `CoverageSources` for why these are
+ * derived rather than passed in.
+ */
+export function deriveCounts(
+  entries: CoverageEntry[],
+  sources: CoverageSources,
+): ProducerCounts {
+  const model = sources.modelJson
+    ? (() => {
+        try {
+          const m = JSON.parse(sources.modelJson) as Record<string, unknown>;
+          const size = (v: unknown) =>
+            v && typeof v === "object" && !Array.isArray(v) ? Object.keys(v).length : 0;
+          return { elements: size(m.elements), relationships: size(m.relations) };
+        } catch {
+          return { elements: 0, relationships: 0 };
+        }
+      })()
+    : { elements: 0, relationships: 0 };
+
+  return {
+    c4_elements: model.elements,
+    c4_relationships: model.relationships,
+    domain_model_rows: countAutoInferredRows(sources.registerMarkdown),
+    coverage_present: entries.filter((e) => e.present).length,
+    coverage_expected: entries.length,
+  };
+}
+
+/** Collapse to one line — a marker must be greppable as a single record. */
+function oneLine(s: string): string {
+  return s.replace(/\s+/g, " ").trim();
+}
+
+/** The stdout marker. Counts only, in `MARKER_FIELDS` order. */
+export function formatProducersMarker(counts: ProducerCounts): string {
+  const fields = MARKER_FIELDS.map((f) => `${f}=${counts[f]}`).join(" ");
+  return `${PRODUCERS_MARKER} ${fields}`;
+}
+
+/** The failure marker. Not `reportSilentFallback` — nothing under plugins/ imports Sentry. */
+export function formatErrorMarker(producer: string, reason: string): string {
+  return oneLine(`${ERROR_MARKER} producer=${producer} reason="${oneLine(reason)}"`);
+}
+
+/**
+ * Render the committed artifact.
+ *
+ * `degraded` rows are recorded here as well as on stdout, so a failed run survives
+ * the session — on this surface stdout is the only other signal and it evaporates.
+ */
+export function renderCoverageMarkdown(
+  entries: CoverageEntry[],
+  counts: ProducerCounts,
+  degraded: string[] = [],
+): string {
+  const present = entries.filter((e) => e.present);
+  const notPresent = entries.filter((e) => !e.present);
+
+  const out: string[] = [
+    "# Knowledge base coverage",
+    "",
+    "What Soleur looks for in a knowledge base, and what is present in this one.",
+    "This is a description of Soleur's expectations — it is not an assessment of",
+    "the business, and it is not a compliance finding. Generated by",
+    "`/soleur:sync`; regenerated on every run.",
+    "",
+    `## Present (${present.length} of ${entries.length})`,
+    "",
+  ];
+
+  if (present.length === 0) {
+    out.push("- none of the expected entries are present yet");
+  } else {
+    for (const e of present) out.push(`- \`${e.path}\``);
+  }
+
+  out.push("", "## Not present", "");
+
+  if (notPresent.length === 0) {
+    out.push("- every expected entry is present");
+  } else {
+    // The exact expectation-vs-presence phrasing. Do not reword to a deficiency
+    // form — see the file header.
+    for (const e of notPresent) {
+      out.push(`- no \`${e.path}\` present in this knowledge base`);
+    }
+  }
+
+  if (degraded.length > 0) {
+    out.push("", "## Producers reporting degraded", "");
+    for (const d of degraded.slice().sort()) out.push(`- ${oneLine(d)}`);
+  }
+
+  out.push(
+    "",
+    "## Run counts",
+    "",
+    "Emitted identically on sync stdout, so this artifact and the run agree.",
+    "",
+    "```",
+    formatProducersMarker(counts),
+    "```",
+    "",
+  );
+
+  return out.join("\n");
+}