@volter/twin-world 0.1.0 → 0.1.2

package/src/covers.ts

@@ -0,0 +1,724 @@
+// `volter-world covers <world> --repo <path>` — the room-setup COVERAGE PROOF (the twin
+// half of the "room ensure params" doctrine): prove that every external vendor an
+// application repo talks to has a twin IN the named world, so an agent working in that
+// room can never silently reach a real vendor the world forgot to twin.
+//
+// Detection (repo side) reuses inspect-project's signals: every package.json across the
+// root + all workspace members (pnpm/yarn/npm/bun), mapped through SDK_TWINS, plus
+// vendor-shaped env names in committed .env* files and direct literal fetch destinations
+// in production source (a repo may use a vendor without declaring its SDK).
+//
+// Matching (world side) reads the world's INSTANCE when one exists (.volter/worlds/<name>/
+// instance.json — the truth for a booted world) and falls back to the stable CONFIG
+// (worlds/configs/<name>.json) so the proof also works pre-boot.
+//
+// LOUD FAILURE SEMANTICS — this is a proof, not a report:
+//   exit 0  ⇔ every detected vendor is covered AND nothing external-service-shaped is
+//             unaccounted for. A vendor with no twin in the world → MISSING → exit 1.
+//             A twin that IS in the world but that no traffic can reach (its service
+//             resolves to no injector vendor and exposes no app-read endpoint env — the
+//             LibreChat AWS_TWIN_URL trap) → UNINTERCEPTABLE → exit 1: presence is not
+//             coverage. An external-service-shaped dep/env var with no vendor mapping →
+//             unknown-sdk → exit 1 by default (`--allow-unknown` downgrades to a warning:
+//             unknowns still print, but stop failing the proof).
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadWorldConfig } from './configs.ts';
+import { injectableVendorKeys, loadInject, twinUrlVendorFor } from './inject-map.ts';
+import { projectDependencies, projectEnvNames, projectFetchUrls, projectNpmRegistries, PYPI_TWINS, SDK_TWINS } from './project-inspect.ts';
+import { overlayCoversMaps } from './pack-facts.ts';
+import { statusWorld } from './runtime.ts';
+import type { WorldServiceConfig } from './schema.ts';
+
+export type CoverageStatus = 'covered' | 'missing' | 'uninterceptable' | 'unknown-sdk' | 'acknowledged';
+
+export type CoverageRow = {
+  /** vendor key for mapped vendors; the raw dep/env name for unknown-sdk rows */
+  vendor: string;
+  /** how the repo betrayed the vendor, e.g. 'npm: stripe' / 'env: STRIPE_SECRET_KEY' */
+  detectedVia: string[];
+  /** the matching world service/env identifier when covered, else null */
+  twinInWorld: string | null;
+  status: CoverageStatus;
+};
+
+export type CoverageReport = {
+  world: string;
+  /** 'instance' when a booted/recorded instance was read; 'config' for the stable config */
+  worldSource: 'instance' | 'config';
+  worldPath: string;
+  repo: string;
+  twinsInWorld: string[];
+  rows: CoverageRow[];
+  covered: string[];
+  missing: string[];
+  /** vendors whose twin IS in the world but nothing can route vendor traffic to it (the
+   * service resolves to no injector vendor and exposes no app-read endpoint env) — the
+   * LibreChat AWS_TWIN_URL trap. Fails the proof: a twin nothing reaches covers nothing. */
+  uninterceptable: string[];
+  unknown: string[];
+  acknowledged: { vendor: string; reason: string }[];
+  allowUnknown: boolean;
+  ok: boolean;
+};
+
+/** identifiers are compared case/punctuation-insensitively: 's3', 'S3_TWIN_URL' stem,
+ * a 'stripe' service id and the 'ai-gateway' pack name all normalize cleanly. */
+function normalizeId(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/** Which world-side identifiers (normalized service ids / *_TWIN_URL stems / pack names)
+ * count as covering a vendor. Default: the vendor key itself. Extras cover the packs whose
+ * world identity differs from the SDK vendor key (the consolidated aws twin answers as
+ * s3/dynamodb/timestream; cookbook supabase worlds inject SUPABASE_MGMT_TWIN_URL). */
+const VENDOR_WORLD_IDS: Record<string, string[]> = {
+  // (empty — every entry has moved onto its pack descriptor. See the note below.)
+};
+
+function worldIdsFor(vendor: string): string[] {
+  return VENDOR_WORLD_IDS[vendor] ?? [normalizeId(vendor)];
+}
+
+/**
+ * The INJECTOR vendor keys that can carry this vendor's traffic, in a stable order — the single
+ * source of truth for "can zero-edit interception work here, and under which `*_TWIN_URL` name?".
+ *
+ * Read from `@volter/twin/inject`'s own VENDOR_HOSTS table (never a re-encoding of it), and
+ * filtered through the same `VENDOR_WORLD_IDS` aliasing the proof matches with: `aws` yields
+ * `['s3','dynamodb','timestream']` (the consolidated twin's real keys — `AWS_TWIN_URL` is the
+ * inert trap), `stripe` yields `['stripe']`, and a pack in vendor-hosts.test.ts's
+ * descriptor hostsNone ruling yields `[]`.
+ *
+ * Two callers, one answer: `covers` uses it to decide whether an UNINTERCEPTABLE finding is a
+ * fixable wiring bug (keys exist) or an acknowledgeable allowlist gap (none do), and `init` uses
+ * it to DERIVE the canonical `injectEnv` it emits — so an emitted world can never claim a
+ * `*_TWIN_URL` var the injector does not read.
+ */
+export function injectorVendorKeysFor(vendor: string): string[] {
+  const worldIds = new Set(worldIdsFor(vendor));
+  return [...injectableVendorKeys()].filter((key) => worldIds.has(normalizeId(key)));
+}
+
+/** Shell-safe env name read by the injector for a vendor key, including hyphenated keys. */
+export function injectorEnvNameForKey(key: string): string {
+  return `${key.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_TWIN_URL`;
+}
+
+/** Vendor-shaped env var detection (the secondary signal). The var must end in a
+ * credential/endpoint suffix; the remaining stem (framework prefixes stripped,
+ * normalized) is looked up here. */
+// Exported for scripts/packless-claims.test.ts, which checks the packless registry against
+// the OVERLAID map (legacy entries + descriptor adoption.envStems in one view) — importing
+// the real map is unbreakable by formatting, unlike the source-parsing it replaced (§9
+// skeptic M3, 2026-08-31: a reflow or quote-style change silently emptied the parsed set).
+export const ENV_STEM_VENDORS: Record<string, string> = {
+  // (empty — every entry has moved onto its pack descriptor. See the note below.)
+};
+
+const ENV_FRAMEWORK_PREFIX = /^(NEXT_PUBLIC_|VITE_|REACT_APP_|EXPO_PUBLIC_|NUXT_PUBLIC_|PUBLIC_)/;
+
+/** Broad credential/endpoint suffixes — used to derive a stem for KNOWN-vendor detection
+ * (a false stem is harmless: it only counts when the stem hits ENV_STEM_VENDORS). */
+const ENV_SUFFIX_BROAD =
+  /_(ACCESS_KEY_ID|SECRET_ACCESS_KEY|SERVICE_ROLE_KEY|PUBLISHABLE_KEY|WEBHOOK_SECRET|SIGNING_SECRET|CLIENT_SECRET|CLIENT_ID|CONSUMER_KEY|ACCOUNT_SID|OAUTH_TOKEN|AUTH_TOKEN|ACCESS_TOKEN|BEARER_TOKEN|BOT_TOKEN|API_TOKEN|API_SECRET|API_KEY|APIKEY|SECRET_KEY|API_URL|BASE_URL|REST_URL|SECRET|TOKEN|KEY|DSN)$/;
+
+/** Narrow, unmistakably vendor-shaped suffixes — a var with one of these whose stem maps
+ * to NO known vendor is an unknown external service and fails the proof. (Deliberately
+ * excludes bare _SECRET/_TOKEN/_KEY: JWT_SECRET / SESSION_SECRET are app-local. _REST_URL
+ * is here on purpose: it is a hosted-service endpoint shape — UPSTASH_REDIS_REST_URL
+ * produced NO row at all in the Dub blind-adoption run. _CLIENT_ID/_CLIENT_SECRET/
+ * _CONSUMER_KEY are here on purpose too: they are the OAuth-app credential shape, and
+ * before they were strict the Cal.com blind run silently dropped NINE OAuth vendors —
+ * ZOOM_CLIENT_ID, MS_GRAPH_CLIENT_SECRET, SALESFORCE_CONSUMER_KEY, GOOGLE_CLIENT_ID, … —
+ * from a proof that exited 0. The env-detection heuristic was structurally biased against
+ * exactly the vendor class integration-heavy apps are made of.) */
+const ENV_SUFFIX_STRICT = /_(API_KEY|APIKEY|API_TOKEN|API_SECRET|OAUTH_TOKEN|CLIENT_ID|CLIENT_SECRET|CONSUMER_KEY|ACCOUNT_SID|DSN|REST_URL)$/;
+
+/** App-local stems that must never be flagged as an unknown vendor. `redis` is deliberately
+ * NOT here: a redis-stemmed var only reaches this lookup through a vendor-shaped suffix
+ * (e.g. REDIS_REST_URL — hosted Redis, an external service), while plain local-Redis vars
+ * (REDIS_URL, REDIS_HOST, REDIS_PASSWORD) never match ENV_SUFFIX_STRICT in the first place. */
+const ENV_STEM_IGNORE = new Set([
+  'jwt', 'session', 'auth', 'nextauth', 'app', 'api', 'admin', 'internal', 'server', 'client',
+  'cookie', 'csrf', 'encryption', 'webhook', 'test', 'dev', 'local', 'demo', 'example', 'my',
+  'database', 'db', 'postgres', 'mysql', 'mongo', 'smtp', 'volter', 'twin', 'world',
+  // generic IdP-config stems: OAUTH_CLIENT_ID / OIDC_CLIENT_SECRET name a PROTOCOL role, not a
+  // vendor — now that _CLIENT_ID/_CLIENT_SECRET are strict suffixes these would otherwise raise
+  // a false unknown-vendor alarm on every app with a generic OAuth config block. Vendor-named
+  // stems (ZOOM_, SALESFORCE_, GOOGLE_, …) still surface.
+  'oauth', 'oidc',
+]);
+
+function envVendorStem(name: string, suffix: RegExp): string | null {
+  const stripped = name.replace(ENV_FRAMEWORK_PREFIX, '');
+  const match = stripped.match(suffix);
+  if (!match || match.index === undefined || match.index === 0) return null;
+  return normalizeId(stripped.slice(0, match.index));
+}
+
+/** Is this env NAME shaped like a CREDENTIAL/endpoint at all (any broad vendor suffix)? The
+ * question `init` asks before deciding whether a value in a repo's `.env.example` may be copied
+ * verbatim: `APP_NAME` may, `ANYTHING_SECRET` may not — a committed example file is exactly where
+ * live keys hide (the ponder blind-adoption run found real ones), so a credential-shaped name is
+ * ALWAYS replaced by a fake, whether or not its stem maps to a vendor this repo twins. Exported
+ * from here so the emission path and the proof read ONE definition of "credential-shaped". */
+export function isCredentialShapedEnvName(name: string): boolean {
+  return ENV_SUFFIX_BROAD.test(name.replace(ENV_FRAMEWORK_PREFIX, ''));
+}
+
+/** The vendor a credential-shaped env NAME betrays, or null. Same broad-suffix route the
+ * coverage proof's secondary signal uses (`STRIPE_SECRET_KEY` → 'stripe'). */
+export function envNameVendor(name: string): string | null {
+  // ⚠️ This deliberately does NOT claim the SMTP host/URL vars, even though `detectRepoVendors`
+  // below detects them as vendor `smtp`. The two functions answer DIFFERENT questions, and §9
+  // found both halves of that the hard way:
+  //   • round 1 called the divergence an inconsistency ("one answer per name");
+  //   • round 2 showed what happens when you remove it. This function's only caller is `init`'s
+  //     env emission (`init.ts`), which REPLACES a credential-shaped value with `twin-fake-<name>`.
+  //     Claiming `SMTP_URL`/`EMAIL_SERVER` here turned NextAuth's `smtp://user:pass@host:port` into
+  //     `twin-fake-email-server`, which `new URL(...)` cannot parse — breaking the app to protect a
+  //     value that was never a credential in the first place.
+  // So: this asks "is this name a VENDOR CREDENTIAL that must be faked?" (a hostname is not), while
+  // `detectRepoVendors` asks "which vendors does this repo talk to?" (the mail path certainly is
+  // one). Same string, two honest answers.
+  const stem = envVendorStem(name, ENV_SUFFIX_BROAD);
+  return stem === null ? null : ENV_STEM_VENDORS[stem] ?? null;
+}
+
+/** SMTP-shaped env names — the raw-protocol mail path (nodemailer et al.) the HTTP-vendor
+ * heuristics above are structurally blind to. The Cal.com blind run's booking-confirmation
+ * mail (EMAIL_SERVER_HOST/EMAIL_SERVER_PORT) was invisible to the proof while being the
+ * single most important vendor touchpoint of the app. Conservative stem+suffix approach:
+ * only the HOST/URL forms count (`SMTP_HOST`, `MAILGUN_SMTP_HOST`, `SMTP_URL`, and
+ * NextAuth/nodemailer's `EMAIL_SERVER`/`EMAIL_SERVER_HOST` connection forms) — a bare
+ * SMTP_USER/_PASSWORD without a host proves nothing and would duplicate rows.
+ *
+ * This signal used to surface as unknown-sdk ('smtp') because no SMTP twin existed — the honest
+ * outcome at the time. The `smtp` pack now twins the protocol, so it is a DETECTED vendor and a
+ * world that runs an smtp service covers it. What has NOT changed is why the signal has to be a
+ * dedicated route at all: SMTP is intercepted through the app-read env name itself, not through a
+ * host the injector rewrites, so the env var IS the touchpoint rather than a hint about one.
+ * (The 'smtp' entry in ENV_STEM_IGNORE guards the generic-suffix stem route; this signal is
+ * deliberate and separate.) */
+function isSmtpEnvSignal(name: string): boolean {
+  const stripped = name.replace(ENV_FRAMEWORK_PREFIX, '');
+  return /(^|_)SMTP_(HOST|URL)$/.test(stripped) || /^EMAIL_SERVER(_HOST)?$/.test(stripped);
+}
+
+/** npm scopes whose EVERY package is one vendor's client surface — an unmapped
+ * satellite package (`@sentry/cli`, `@datadog/browser-logs`, `@octokit/graphql`)
+ * still detects (and is covered by) that vendor's twin. Deliberately NOT `@aws-sdk`
+ * or `@azure`/`@google-cloud`: those scopes span many services and the consolidated
+ * twins only model some of them — unmapped clients there must stay unknown-sdk. */
+const SDK_SCOPE_VENDORS: Record<string, string> = {
+  // (empty — every entry has moved onto its pack descriptor. See the note below.)
+};
+// TWIN-PACK-CONTRACT migration, COMPLETE for these three tables: every pack declares its own
+// scopes / env stems / world ids (`adoption` on its descriptor, compiled into the committed
+// pack-facts artifact), and all three literals above are now empty — they are populated entirely
+// by the overlay below. They are kept as the overlay's targets, not as homes: the object identity
+// is what every use site already reads, so nothing downstream changed. Do NOT re-add an entry
+// here; a fact declared in both homes throws at module init.
+overlayCoversMaps({ scopeVendors: SDK_SCOPE_VENDORS, envStemVendors: ENV_STEM_VENDORS, vendorWorldIds: VENDOR_WORLD_IDS });
+
+export function scopeVendorFor(name: string): string | undefined {
+  const entry = Object.entries(SDK_SCOPE_VENDORS).find(([prefix]) => name === prefix || name.startsWith(prefix));
+  return entry?.[1];
+}
+
+/** npm scopes holding at least one twin-mapped package (from SDK_TWINS' scoped keys and
+ * SDK_SCOPE_VENDORS). An UNMAPPED sibling from such a scope is almost always another external
+ * surface of the same platform — in the Dub blind-adoption run, `@upstash/redis` and
+ * `@upstash/ratelimit` produced NO row at all while `@upstash/qstash` was mapped, a silent
+ * blind spot. Such siblings surface as unknown-sdk instead of disappearing. */
+const MAPPED_SCOPES: ReadonlySet<string> = new Set(
+  [...Object.keys(SDK_TWINS), ...Object.keys(SDK_SCOPE_VENDORS)]
+    .filter((name) => name.startsWith('@'))
+    .map((name) => `${name.split('/')[0]}/`),
+);
+
+export function isMappedScopeSibling(name: string): boolean {
+  if (knownExternalServices().notExternal[name] !== undefined) return false;
+  return [...MAPPED_SCOPES].some((scope) => name.startsWith(scope));
+}
+
+/**
+ * THE PACKLESS-VENDOR REGISTRY — `known-external-services.json`, shipped inside this package.
+ * ONE home for the knowledge that used to live in three inline sets here (NOT_AN_EXTERNAL_
+ * SERVICE, UNKNOWN_DEP_KNOWN_SERVICES, UNKNOWN_DEP_PATTERNS) plus the 2026-08-31 census
+ * rulings: `deps`/`envStems` are external-service signals the catalog KNOWS but has no pack
+ * for (`disposition: 'demanded'` stays a LOUD coverage gap — the demand queue;
+ * `'acknowledged'` was adjudicated acceptable and auto-acknowledges with its recorded
+ * reason); `notExternal` suppresses vendor-adjacent glue (protocol/type/UI helpers, auth
+ * libraries); `patterns` are the external-shape heuristics. AN ENTRY DIES THE DAY ITS PACK
+ * IS BORN — scripts/packless-claims.test.ts enforces disjointness with pack adoption and
+ * SDK_TWINS (the `@planetscale/database`/twin#255 lesson, mechanized). Lazy + cached like
+ * pack-facts.ts's loader — though note this module ALREADY does module-scope I/O via the
+ * overlayCoversMaps call below, so laziness here is consistency, not a load-bearing
+ * invariant (§9 round two L1).
+ */
+export type PacklessDisposition = 'demanded' | 'acknowledged';
+export type PacklessEntry = { disposition: PacklessDisposition; reason: string };
+export type KnownExternalServices = {
+  deps: Record<string, PacklessEntry>;
+  envStems: Record<string, PacklessEntry>;
+  notExternal: Record<string, string>;
+  patterns: Array<{ pattern: string; reason: string }>;
+};
+
+let registryCache: KnownExternalServices | undefined;
+export function knownExternalServices(): KnownExternalServices {
+  if (registryCache === undefined) {
+    const path = join(dirname(fileURLToPath(import.meta.url)), '..', 'known-external-services.json');
+    registryCache = JSON.parse(readFileSync(path, 'utf8')) as KnownExternalServices;
+  }
+  return registryCache;
+}
+
+let patternCache: RegExp[] | undefined;
+function unknownDepPatterns(): RegExp[] {
+  patternCache ??= knownExternalServices().patterns.map((p) => new RegExp(p.pattern));
+  return patternCache;
+}
+
+function isExternalServiceShapedDep(name: string): boolean {
+  const registry = knownExternalServices();
+  if (registry.notExternal[name] !== undefined) return false;
+  if (registry.deps[name] !== undefined) return true;
+  return unknownDepPatterns().some((pattern) => pattern.test(name));
+}
+
+/** The registry's STANDING acknowledgment for an unknown-signal name (npm dep or env stem),
+ * or null when the signal is unlisted or listed as a demanded (loud) gap. Exported for init,
+ * whose plan partitions the same signals the proof does.
+ *
+ * DEMANDED ANYWHERE WINS: the unknown map merges npm deps, env stems and registry-host ids
+ * under one key space, so a name listed in BOTH registry sections must never let one
+ * section's acknowledgment quiet the other's demanded gap (§9 round two H5, 2026-08-31: an
+ * acknowledged dep entry silently green-lit a repo whose only signal was the same-named
+ * DEMANDED env stem). Loud beats quiet; the gate also refuses conflicting dispositions. */
+export function registryAcknowledgedReason(name: string): string | null {
+  const registry = knownExternalServices();
+  const entries = [registry.deps[name], registry.envStems[name]].filter(
+    (entry): entry is PacklessEntry => entry !== undefined,
+  );
+  if (entries.length === 0 || entries.some((entry) => entry.disposition !== 'acknowledged')) return null;
+  return entries[0]!.reason;
+}
+
+export type WorldTwinId = {
+  /** display label (e.g. 'stripe (twin service)') */
+  label: string;
+  /** whether traffic can actually REACH the twin behind this identifier: the injector/proxy
+   * intercepts its vendor hosts, or the service exposes app-read endpoint env. A twin that is
+   * merely present — reachable by nothing — must not count as coverage (the LibreChat
+   * AWS_TWIN_URL trap: the injectEnv looked wired but the injector reads no `aws` vendor). */
+  interceptable: boolean;
+};
+
+type WorldTwinInventory = {
+  source: 'instance' | 'config';
+  path: string;
+  /** normalized identifier → id record (e.g. 'stripe' → { label: 'stripe (service)', … }) */
+  ids: Map<string, WorldTwinId>;
+};
+
+function addId(ids: Map<string, WorldTwinId>, key: string, label: string, interceptable: boolean): void {
+  const existing = ids.get(key);
+  if (!existing) ids.set(key, { label, interceptable });
+  // first label wins (stable output), but interceptability is an OR across contributors: a
+  // second service that CAN be reached upgrades the id.
+  else if (interceptable && !existing.interceptable) existing.interceptable = true;
+}
+
+function addServiceIds(
+  ids: Map<string, WorldTwinId>,
+  service: {
+    id: string;
+    type?: string;
+    injectEnv?: string;
+    injectEnvTemplates?: Record<string, string>;
+    cliRedirect?: unknown;
+    /** instance-path services carry their injected vars here instead of the config fields */
+    env?: Record<string, string>;
+    command?: string | string[];
+    args?: string[];
+    colocate?: { module: string };
+  },
+): void {
+  const type = service.type ?? 'twin';
+  const commandParts = [
+    ...(Array.isArray(service.command) ? service.command : service.command ? [service.command] : []),
+    ...(service.args ?? []),
+    ...(service.colocate ? [service.colocate.module] : []),
+  ];
+  const packNames = commandParts.flatMap((part) => {
+    const fromPath = part.match(/packages\/twin\/([a-z0-9-]+)\//);
+    const fromBin = part.match(/^world-([a-z0-9-]+)$/);
+    const fromPkg = part.match(/^@volter\/twin-([a-z0-9-]+)$/);
+    return [fromPath?.[1], fromBin?.[1], fromPkg?.[1]].filter((name): name is string => name !== undefined);
+  });
+  // How would traffic actually reach this twin?
+  //   • the injector/ambient proxy intercepts its vendor hosts — true when its injectEnv is a
+  //     `*_TWIN_URL` var the injector reads, or its service id / pack name IS an injector
+  //     vendor key (the consolidated aws twin's `s3` service id, for example);
+  //   • OR the app/CLI reads its endpoint env directly — external services (discovered env),
+  //     injectEnvTemplates (LIVEKIT_URL=…), cliRedirect, or a non-`*_TWIN_URL` injectEnv.
+  // A twin service with NEITHER is present but unreachable: interceptable=false.
+  const vendorKeys = new Set([...injectableVendorKeys()].map(normalizeId));
+  const envKeys = Object.keys(service.env ?? {}); // instance-path evidence of the same wiring
+  const injectorReads =
+    (service.injectEnv !== undefined && twinUrlVendorFor(service.injectEnv) !== null) ||
+    envKeys.some((key) => twinUrlVendorFor(key) !== null);
+  const appConfigured =
+    type === 'external' ||
+    service.cliRedirect !== undefined ||
+    Object.keys(service.injectEnvTemplates ?? {}).length > 0 ||
+    (service.injectEnv !== undefined && !/_TWIN_URL$/.test(service.injectEnv)) ||
+    envKeys.some((key) => !/_TWIN_URL$/.test(key));
+  const hostMatched =
+    vendorKeys.has(normalizeId(service.id)) || packNames.some((pack) => vendorKeys.has(normalizeId(pack)));
+  const interceptable = injectorReads || appConfigured || hostMatched;
+  // twin + external services cover their vendor by identity; a plain 'process'
+  // service only counts via an explicit twin marker (injectEnv/*_TWIN_URL, pack path).
+  if (type === 'twin' || type === 'external') {
+    const label = type === 'twin' ? `${service.id} (twin service)` : `${service.id} (external service)`;
+    addId(ids, normalizeId(service.id), label, interceptable);
+  }
+  if (service.injectEnv) {
+    const stem = service.injectEnv.match(/^(.+)_TWIN_URL$/);
+    if (stem) addId(ids, normalizeId(stem[1]!), `${service.id} (${service.injectEnv})`, interceptable);
+  }
+  for (const pack of packNames) {
+    addId(ids, normalizeId(pack), `${service.id} (pack ${pack})`, interceptable);
+  }
+}
+
+/** The twins actually IN the named world: instance first (the booted truth), stable
+ * config as the pre-boot fallback. Throws loudly when the world resolves to neither. */
+export function worldTwinInventory(world: string, root: string): WorldTwinInventory {
+  let instanceError: string | undefined;
+  try {
+    const status = statusWorld(world, root);
+    const ids = new Map<string, WorldTwinId>();
+    for (const service of Object.values(status.services)) addServiceIds(ids, service);
+    for (const key of Object.keys(status.env)) {
+      const stem = key.match(/^(.+)_TWIN_URL$/);
+      // a bare env `*_TWIN_URL` var is only a REACHABLE twin when the injector reads it
+      if (stem) addId(ids, normalizeId(stem[1]!), `env ${key}`, twinUrlVendorFor(key) !== null);
+    }
+    return { source: 'instance', path: `${status.dirs.instance}/instance.json`, ids };
+  } catch (error) {
+    instanceError = error instanceof Error ? error.message : String(error);
+  }
+  try {
+    const { path, config } = loadWorldConfig(world, root);
+    const ids = new Map<string, WorldTwinId>();
+    for (const service of config.services as WorldServiceConfig[]) addServiceIds(ids, service);
+    return { source: 'config', path, ids };
+  } catch (error) {
+    const configError = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `volter-world covers: world "${world}" not found as an instance or a config.\n` +
+      `  instance: ${instanceError}\n  config: ${configError}`,
+    );
+  }
+}
+
+export type CoverageOptions = {
+  root?: string;
+  allowUnknown?: boolean;
+  /**
+   * vendor → reason: vendors the operator ACKNOWLEDGES need no twin in this world — e.g. an SDK
+   * used verifier-only (svix's Webhook verifies incoming signatures locally and never calls out).
+   * An acknowledged vendor downgrades missing/unknown-sdk to status 'acknowledged' (reason shown,
+   * never silent); a reason is REQUIRED — an empty one throws.
+   *
+   * UNINTERCEPTABLE splits in two (the Cal.com svix finding):
+   *   • an injector vendor key EXISTS for the vendor and the wiring is merely wrong (the LibreChat
+   *     AWS_TWIN_URL trap) — a config bug, NOT acknowledgeable: the acknowledgment is refused
+   *     loudly on the row and the proof stays red until the wiring is fixed;
+   *   • NO injector key exists at all (the pack is in its descriptor's hostsNone ruling
+   *     allowlist — ~15 packs wire by explicit endpoint config only) — acknowledgeable WITH a
+   *     reason. Before this, the only route to green was DELETING the twin from the world and
+   *     acknowledging it as un-twinned, which made the config LESS truthful than the red proof.
+   */
+  acknowledge?: Record<string, string>;
+};
+
+/** What a repo BETRAYS about the external services it talks to — the repo half of the coverage
+ * proof, split out so `init` (which must EMIT a twin per detected vendor) and `covers` (which must
+ * PROVE one exists) can never drift apart by re-encoding detection twice. */
+export type RepoVendorSignals = {
+  /** vendor key → the sources that betrayed it (`npm: stripe`, `env: STRIPE_SECRET_KEY`,
+   * `fetch: src/billing.ts:12 -> api.stripe.com`) */
+  detected: Map<string, string[]>;
+  /** external-service-shaped signal with NO vendor mapping → its sources (dep name, or env stem) */
+  unknown: Map<string, string[]>;
+};
+
+/** Detect every vendor (and every unmapped external-service-shaped signal) an application repo
+ * betrays: mapped npm dependencies across the root + all workspace members, vendor-shaped env
+ * names in committed `.env*` files, the SMTP/raw-protocol signal, and literal vendor URLs passed
+ * directly to fetch in production source. URL attribution reads the injector's VENDOR_HOSTS table
+ * rather than re-encoding host rules here. Insertion order follows the sorted dependency, env-name,
+ * and source lists, so callers that preserve it are deterministic. */
+export function detectRepoVendors(repoPath: string): RepoVendorSignals {
+  const repo = resolve(repoPath);
+  const dependencies = projectDependencies(repo);
+  const envNames = projectEnvNames(repo);
+  const npmRegistries = projectNpmRegistries(repo);
+
+  // vendor → detection sources
+  const detected = new Map<string, string[]>();
+  const mappedDeps = new Set<string>();
+  for (const dependency of dependencies) {
+    // `pypi:<name>` is the Python half (project-inspect's PYPI_TWINS, descriptors' adoption.pypi).
+    const py = dependency.startsWith('pypi:') ? dependency.slice(5) : undefined;
+    const vendor = py !== undefined ? PYPI_TWINS[py]?.vendor : (SDK_TWINS[dependency]?.vendor ?? scopeVendorFor(dependency));
+    if (vendor === undefined) continue;
+    mappedDeps.add(dependency);
+    detected.set(vendor, [...(detected.get(vendor) ?? []), py !== undefined ? `pypi: ${py}` : `npm: ${dependency}`]);
+  }
+  for (const name of envNames) {
+    if (/_TWIN_URL$/.test(name) || /^VOLTER_/.test(name)) continue;
+    // The raw-protocol mail path. This used to fall through to `unknown` because no SMTP twin
+    // existed, which was the honest answer THEN; the `smtp` pack now twins it, so the same signal
+    // is a DETECTED vendor and a world carrying an smtp service covers it. (The env NAME is the
+    // whole interception story here — there is no host for the injector to rewrite, so
+    // SMTP_HOST/EMAIL_SERVER_HOST pointed at the twin's listener is what redirects the app.)
+    if (isSmtpEnvSignal(name)) {
+      // NB this sits BEFORE the stem lookup, so a vendor-NAMED mail host (`POSTMARK_SMTP_HOST`,
+      // `MAILGUN_SMTP_HOST`) attributes to the `smtp` twin rather than to that vendor's HTTP pack.
+      // Deliberate: the var names an SMTP endpoint, and pointing it at the twin's listener is what
+      // actually redirects the mail — postmark's REST twin would not receive it.
+      detected.set('smtp', [...(detected.get('smtp') ?? []), `env: ${name}`]);
+      continue;
+    }
+    const stem = envVendorStem(name, ENV_SUFFIX_BROAD);
+    const vendor = stem === null ? undefined : ENV_STEM_VENDORS[stem];
+    if (vendor) detected.set(vendor, [...(detected.get(vendor) ?? []), `env: ${name}`]);
+  }
+
+  // The npm registry injector deliberately owns only npmjs.org and GitHub Packages. A custom
+  // configured registry is a distinct uncovered destination even when NPM_TOKEN also detects the
+  // official npm twin; treating the credential as coverage would silently send private-registry
+  // traffic to the real network.
+  const officialNpmHosts = new Set(['registry.npmjs.org', 'npm.pkg.github.com']);
+  for (const registry of npmRegistries) {
+    const hostname = new URL(registry.url).hostname.toLowerCase();
+    if (officialNpmHosts.has(hostname)) {
+      detected.set('npm-registry', [...(detected.get('npm-registry') ?? []), `registry: ${registry.source} -> ${hostname}`]);
+    }
+  }
+
+  // Raw-fetch vendor discovery. A hand-written client has no SDK dependency, and its credential
+  // may use a project-specific name; the literal destination is the one unambiguous signal left.
+  // Match it through the injector's OWN predicates, including pathname-aware shared hosts.
+  const knownVendorById = new Map<string, string>();
+  for (const vendor of [
+    ...Object.values(SDK_TWINS).map((entry) => entry.vendor),
+    ...Object.values(ENV_STEM_VENDORS),
+    ...Object.keys(VENDOR_WORLD_IDS),
+  ]) knownVendorById.set(normalizeId(vendor), vendor);
+  const canonicalVendor = (injectorKey: string): string | null => {
+    const key = normalizeId(injectorKey);
+    for (const [vendor, ids] of Object.entries(VENDOR_WORLD_IDS)) {
+      if (ids.includes(key)) return vendor;
+    }
+    return knownVendorById.get(key) ?? null;
+  };
+  const vendorHosts = loadInject().VENDOR_HOSTS;
+  for (const signal of projectFetchUrls(repo)) {
+    const url = new URL(signal.url);
+    const vendors = new Set<string>();
+    for (const [injectorKey, matches] of Object.entries(vendorHosts)) {
+      if (!matches(url.hostname, url.pathname)) continue;
+      const vendor = canonicalVendor(injectorKey);
+      if (vendor !== null) vendors.add(vendor);
+    }
+    for (const vendor of [...vendors].sort()) {
+      const source = `fetch: ${signal.source} -> ${url.hostname}`;
+      detected.set(vendor, [...(detected.get(vendor) ?? []), source]);
+    }
+  }
+
+  // unknown external-service-shaped signals (no vendor mapping). A dep from a scope with a
+  // twin-mapped sibling counts even when its own name is not service-shaped — the Dub run's
+  // @upstash/redis + @upstash/ratelimit disappeared exactly here while @upstash/qstash mapped.
+  const unknown = new Map<string, string[]>();
+  for (const registry of npmRegistries) {
+    const hostname = new URL(registry.url).hostname.toLowerCase();
+    if (officialNpmHosts.has(hostname)) continue;
+    const id = `npm-registry@${hostname}`;
+    unknown.set(id, [...(unknown.get(id) ?? []), `registry: ${registry.source} -> ${hostname}`]);
+  }
+  for (const dependency of dependencies) {
+    if (mappedDeps.has(dependency)) continue;
+    if (isExternalServiceShapedDep(dependency) || isMappedScopeSibling(dependency)) {
+      unknown.set(dependency, [...(unknown.get(dependency) ?? []), `npm: ${dependency}`]);
+    }
+  }
+  for (const name of envNames) {
+    if (/_TWIN_URL$/.test(name) || /^VOLTER_/.test(name)) continue;
+    if (isSmtpEnvSignal(name)) continue; // now a DETECTED vendor (above), no longer an unknown
+    const stem = envVendorStem(name, ENV_SUFFIX_STRICT);
+    if (stem === null || ENV_STEM_VENDORS[stem] || ENV_STEM_IGNORE.has(stem)) continue;
+    // The registry's notExternal suppressions apply to ENV STEMS too — the census adjudicated
+    // 40 app-internal stems ("names no vendor") that this loop kept flagging because only the
+    // dep-side checks consulted the registry (§9 round two H4, 2026-08-31: 17 of 18 formally
+    // dead stems still failed the proof).
+    if (knownExternalServices().notExternal[stem] !== undefined) continue;
+    unknown.set(stem, [...(unknown.get(stem) ?? []), `env: ${name}`]);
+  }
+  return { detected, unknown };
+}
+
+export function coverWorld(world: string, repoPath: string, options: CoverageOptions = {}): CoverageReport {
+  const root = resolve(options.root ?? process.cwd());
+  const allowUnknown = options.allowUnknown ?? false;
+  const acknowledge = options.acknowledge ?? {};
+  for (const [vendor, reason] of Object.entries(acknowledge)) {
+    if (!reason.trim()) throw new Error(`covers: --acknowledge ${vendor} requires a non-empty reason (vendor=reason)`);
+  }
+  const repo = resolve(repoPath);
+  const inventory = worldTwinInventory(world, root);
+
+  const { detected, unknown: unknownSources } = detectRepoVendors(repo);
+
+  // Does ANY injector vendor key exist for this vendor? Decides whether an UNINTERCEPTABLE
+  // finding is acknowledgeable: a key that exists means the twin COULD be intercepted and the
+  // wiring is merely wrong (fix it, don't acknowledge it); no key at all means the pack is a
+  // stated vendor-hosts allowlist gap (explicit-endpoint wiring only) and a world that still
+  // declares the twin may honestly acknowledge the finding rather than delete the twin.
+  const injectorKeysFor = injectorVendorKeysFor;
+
+  const rows: CoverageRow[] = [];
+  const covered: string[] = [];
+  const acknowledged: { vendor: string; reason: string }[] = [];
+  const missing: string[] = [];
+  const uninterceptable: string[] = [];
+  for (const [vendor, sources] of [...detected.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    // a vendor is only COVERED by a twin traffic can actually reach; a present-but-unreachable
+    // twin (no injector vendor, no app-read endpoint env) is a distinct, failing status.
+    const candidates = worldIdsFor(vendor).filter((id) => inventory.ids.has(id));
+    const matchId = candidates.find((id) => inventory.ids.get(id)!.interceptable) ?? candidates[0];
+    const match = matchId === undefined ? null : inventory.ids.get(matchId)!;
+    let status: CoverageStatus = match === null ? 'missing' : match.interceptable ? 'covered' : 'uninterceptable';
+    let ackRefused: string | undefined;
+    if (acknowledge[vendor] !== undefined) {
+      if (status === 'missing') status = 'acknowledged';
+      else if (status === 'uninterceptable') {
+        const keys = injectorKeysFor(vendor);
+        if (keys.length === 0) status = 'acknowledged';
+        else {
+          ackRefused =
+            `acknowledge REFUSED: injector key(s) ${keys.join('/')} exist for this vendor — the twin CAN be intercepted, ` +
+            `the wiring is merely wrong. Fix it (${keys.map(injectorEnvNameForKey).join(' / ')}) instead of acknowledging`;
+        }
+      }
+    }
+    if (status === 'covered') covered.push(vendor);
+    else if (status === 'missing') missing.push(vendor);
+    else if (status === 'acknowledged') acknowledged.push({ vendor, reason: acknowledge[vendor]! });
+    else uninterceptable.push(vendor);
+    rows.push({
+      vendor,
+      detectedVia:
+        status === 'acknowledged'
+          ? [...sources, `acknowledged: ${acknowledge[vendor]}`]
+          : ackRefused !== undefined
+            ? [...sources, ackRefused]
+            : sources,
+      twinInWorld: match === null ? null : match.label,
+      status,
+    });
+  }
+  const unknown: string[] = [];
+  for (const [name, sources] of [...unknownSources.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (acknowledge[name] !== undefined) {
+      acknowledged.push({ vendor: name, reason: acknowledge[name]! });
+      rows.push({ vendor: name, detectedVia: [...sources, `acknowledged: ${acknowledge[name]}`], twinInWorld: null, status: 'acknowledged' });
+      continue;
+    }
+    // STANDING acknowledgments from the packless-vendor registry: a signal the census rulings
+    // adjudicated acceptable (config-time adapters, per-repo-judged surfaces) acknowledges
+    // itself with the RECORDED reason — the same status a per-run `--acknowledge` grants, but
+    // sourced from committed adjudication instead of a flag. Demanded registry entries fall
+    // through to unknown-sdk on purpose: known-but-packless is still an uncovered vendor.
+    const standing = registryAcknowledgedReason(name);
+    if (standing !== null) {
+      acknowledged.push({ vendor: name, reason: standing });
+      rows.push({ vendor: name, detectedVia: [...sources, `acknowledged (registry): ${standing}`], twinInWorld: null, status: 'acknowledged' });
+      continue;
+    }
+    unknown.push(name);
+    rows.push({ vendor: name, detectedVia: sources, twinInWorld: null, status: 'unknown-sdk' });
+  }
+
+  return {
+    world,
+    worldSource: inventory.source,
+    worldPath: inventory.path,
+    repo,
+    twinsInWorld: [...inventory.ids.values()].map((id) => id.label).sort(),
+    rows,
+    covered,
+    missing,
+    uninterceptable,
+    unknown,
+    acknowledged,
+    allowUnknown,
+    ok: missing.length === 0 && uninterceptable.length === 0 && (allowUnknown || unknown.length === 0),
+  };
+}
+
+export function formatCoverageReport(report: CoverageReport): string {
+  const lines: string[] = [];
+  lines.push(`World ${report.world} (${report.worldSource}: ${report.worldPath})`);
+  lines.push(`Repo  ${report.repo}`);
+  lines.push('');
+  const header = ['vendor', 'detected-via', 'twin-in-world', 'status'];
+  const cells = report.rows.map((row) => [
+    row.vendor,
+    row.detectedVia.join('; '),
+    row.twinInWorld ?? '-',
+    row.status === 'missing' ? 'MISSING' : row.status === 'uninterceptable' ? 'UNINTERCEPTABLE' : row.status,
+  ]);
+  const widths = header.map((title, column) => Math.max(title.length, ...cells.map((row) => row[column]!.length)));
+  const renderRow = (row: string[]): string => row.map((cell, column) => cell.padEnd(widths[column]!)).join(' | ').trimEnd();
+  lines.push(renderRow(header));
+  lines.push(widths.map((width) => '-'.repeat(width)).join('-|-'));
+  for (const row of cells) lines.push(renderRow(row));
+  if (report.rows.length === 0) lines.push('(no external vendor dependencies detected in the repo)');
+  lines.push('');
+  if (report.missing.length > 0) {
+    lines.push(`NOT COVERED: ${report.missing.length} vendor(s) with no twin in world ${report.world}: ${report.missing.join(', ')}`);
+    lines.push(`  add the missing twin service(s) to the world config, then re-run the proof.`);
+  }
+  if (report.uninterceptable.length > 0) {
+    lines.push(`UNINTERCEPTABLE: ${report.uninterceptable.length} vendor(s) have a twin in world ${report.world} that no traffic can reach: ${report.uninterceptable.join(', ')}`);
+    lines.push(`  the twin is present, but its service resolves to no injector vendor (VENDOR_HOSTS in @volter/twin/inject) and exposes no app-read endpoint env — SDK calls would go to the REAL vendor. Use the injector's vendor keys for injectEnv (e.g. S3_TWIN_URL, not AWS_TWIN_URL) or wire explicit endpoint env, then re-run the proof. If NO injector key exists for the vendor at all (a stated vendor-hosts allowlist gap), --acknowledge vendor=reason is accepted; when a key exists, acknowledgment is refused — fix the wiring.`);
+  }
+  if (report.unknown.length > 0) {
+    const verdict = report.allowUnknown ? 'WARNING (allowed by --allow-unknown)' : 'UNKNOWN-SDK: fails the proof';
+    lines.push(`${verdict}: ${report.unknown.length} external-service-shaped signal(s) with no twin mapping: ${report.unknown.join(', ')}`);
+    if (!report.allowUnknown) lines.push('  map them in SDK_TWINS (packages/twin/world-runtime/src/project-inspect.ts) or rerun with --allow-unknown.');
+  }
+  // Acknowledgments are part of the verdict, not fine print: a proof that passed WITH
+  // acknowledged rows must say so (and how many were standing/registry vs per-run flags) —
+  // "COVERED" alone would overstate a world whose acknowledged vendors have no twin at all
+  // (§9 round two M1, 2026-08-31: CoverageReport.acknowledged had no production consumer).
+  if (report.acknowledged.length > 0) {
+    lines.push(`ACKNOWLEDGED: ${report.acknowledged.length} signal(s) accepted with recorded reasons (no twin): ${report.acknowledged.map((a) => a.vendor).join(', ')}`);
+  }
+  lines.push(report.ok
+    ? report.acknowledged.length > 0
+      ? `COVERED (with ${report.acknowledged.length} acknowledgment(s)): every other detected vendor has a twin in world ${report.world}.`
+      : `COVERED: every detected vendor has a twin in world ${report.world}.`
+    : `PROOF FAILED for world ${report.world}.`);
+  return `${lines.join('\n')}\n`;
+}