@volter/world-runtime 2.0.0

package/dist/src/covers.d.ts

@@ -0,0 +1,183 @@
+import { type WorldSelection, type WorldUsage } from './schema.js';
+export type CoverageStatus = 'covered' | 'missing' | 'uninterceptable' | 'unknown-sdk' | 'acknowledged' | 'excluded';
+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[];
+    /** Transport from pack metadata, or a separately required native connection. */
+    connection?: 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;
+    }[];
+    excluded: string[];
+    allowUnknown: boolean;
+    ok: boolean;
+};
+/**
+ * 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/world-core/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 declare function injectorVendorKeysFor(vendor: string): string[];
+/** Shell-safe env name read by the injector for a vendor key, including hyphenated keys. */
+export declare function injectorEnvNameForKey(key: string): string;
+/** 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. */
+export declare const ENV_STEM_VENDORS: Record<string, string>;
+/** 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 declare function isCredentialShapedEnvName(name: string): boolean;
+/** 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 declare function envNameVendor(name: string): string | null;
+export declare function scopeVendorFor(name: string): string | undefined;
+export declare function isMappedScopeSibling(name: string): boolean;
+/**
+ * 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;
+    }>;
+};
+export declare function knownExternalServices(): KnownExternalServices;
+/** 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 declare function registryAcknowledgedReason(name: string): string | null;
+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>;
+    connections: Map<string, {
+        protocol: string | null;
+        label: string;
+    }>;
+    /** Saved policy at boot/config time; absent means legacy all-signals coverage. */
+    selection?: WorldSelection;
+    declared: Map<string, WorldTwinId>;
+};
+/** 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 declare function worldTwinInventory(world: string, root: string): WorldTwinInventory;
+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[]>;
+    uses: Map<string, Array<{
+        usage: WorldUsage;
+        evidence: string;
+    }>>;
+    unknownUses: Map<string, Array<{
+        usage: WorldUsage;
+        evidence: 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 declare function detectRepoVendors(repoPath: string): RepoVendorSignals;
+export declare function coverWorld(world: string, repoPath: string, options?: CoverageOptions): CoverageReport;
+export declare function formatCoverageReport(report: CoverageReport): string;
+export {};