@lunora/advisor 1.0.0-alpha.54 → 1.0.0-alpha.56

package/README.md

@@ -93,6 +93,59 @@ const findings = runAdvisor({ schema: fromServerSchema(schema), ...metrics }, {
 
 A missing metric degrades to an empty array rather than throwing, so a partially configured read path still returns what it can.
 
+### Observability map (score, coverage, baseline)
+
+`runAdvisor` answers "what is wrong?". `scoreAdvisor` answers "how are we doing, and did it get worse?" — a scored coverage map over your procedures. It is a pure function over findings you already have, so it never re-runs a lint:
+
+```ts
+import { fromServerSchema, runAdvisor, scoreAdvisor } from "@lunora/advisor";
+
+import schema from "./lunora/schema";
+
+const context = { schema: fromServerSchema(schema) };
+const findings = runAdvisor(context, { source: "static" });
+const map = scoreAdvisor(context.procedureProtections ?? [], findings);
+
+console.log(map.score, map.grade); // e.g. 84 "good"
+console.log(map.summary); // { clean: 9, exempt: 0, failing: 1, procedures: 12, rulesFired: 6, warned: 2 }
+```
+
+Each procedure starts at 100 and loses each fired **rule's** weight (`Lint.weight`, else a severity ladder: `ERROR` 20 / `WARN` 10 / `INFO` 5) — charged once however many times that rule fires — then rolls up into a weighted global mean: public handlers count double, internal ones and queries half. Findings that name no procedure (schema shape, wrangler config) land in a project bucket weighted against the procedure population, so schema debt genuinely moves the grade.
+
+The verdicts are `clean` / `warned` / `failing` / `exempt` — named for severity, because the score is driven by every lint family rather than an observability family.
+
+Commit the map and gate CI on it:
+
+```ts
+import { compareToBaseline, parseAdvisorMap } from "@lunora/advisor";
+
+const baseline = parseAdvisorMap(JSON.parse(await readFile("lunora.advisor.map.json", "utf8")));
+
+if (baseline === undefined) {
+    // Missing, hand-edited, or written by an older MAP_VERSION. Fail loudly —
+    // treating it as "no regression" would silently disable the gate forever.
+    throw new Error("advisor baseline is unreadable; regenerate lunora.advisor.map.json");
+}
+
+const diff = compareToBaseline(map, baseline);
+
+// `comparable` must be narrowed before `regressed` is reachable, so a stale
+// baseline cannot read as a clean run.
+if (!diff.comparable) {
+    throw new Error(`advisor baseline not comparable: ${diff.reason}`);
+}
+
+// Five independent signals: the global score fell, an existing procedure got
+// worse, one started failing, one's findings grew without its score moving, or
+// the project bucket gained findings. The growth signals matter because a rule is
+// charged once however many times it fires, and the project score saturates at 0.
+if (diff.regressed) {
+    process.exitCode = 1;
+}
+```
+
+`@lunora/codegen` exposes `toAdvisorContext()` to build the context straight from the feeder, and `lunora advisor` wraps all of this as a command. Full reference for the scoring, verdicts, and the baseline gate is in the [package docs](https://lunora.sh/docs/packages/advisor).
+
 > This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/studio)**.
 
 ## Related

package/dist/index.d.mts

@@ -814,36 +814,6 @@ interface AdvisorOwnerFieldWrite {
   /** The `ctx.db` write method (`insert` / `replace` / `patch` / `insertManyUnsafe`). */
   method: string;
 }
-/**
- * One branching `defineShape({ where })` / `definePolicy({ when })` predicate arm
- * that returns an unrestricted predicate — the `unrestricted_where_branch` lint
- * input.
- *
- * A row predicate returns a *filter*, not a boolean, so the denial arm has to be a
- * predicate matching **no** rows: `deny()` / `{ OR: [] }`, a disjunction over zero
- * branches. The plausible-looking `{}` is its exact opposite — it matches every row,
- * so an arm meaning "this caller sees nothing" silently replicates or exposes the
- * whole table, with no error and no log line.
- *
- * Only reported for a *branching* predicate: a single-exit `where: () => ({})` is an
- * author deliberately replicating everything, which is legitimate. Produced by the
- * codegen feeder; runtime callers don't supply it, so the lint finds nothing there.
- * Structurally identical to `UnrestrictedWhereBranchIR`.
- */
-interface AdvisorUnrestrictedWhereBranch {
-  /** The exported binding name of the shape / policy the predicate belongs to. */
-  exportName: string;
-  /** Source file relative to the lunora dir, no extension. */
-  file: string;
-  /** Which unrestricted form was returned. */
-  form: "empty-object" | "undefined";
-  /** The config key carrying the predicate (`where` for a shape, `when` for a policy). */
-  key: string;
-  /** 1-based line of the offending returned expression. */
-  line: number;
-  /** The declaring call (`defineShape` / `definePolicy`). */
-  owner: string;
-}
 /**
  * One payment webhook-adapter construction (`createStripeAdapter` /
  * `createPolarAdapter` / `createAutumnAdapter` / `createDodoPaymentsAdapter`) —
@@ -906,12 +876,24 @@ interface AdvisorPrivilegedDispatch {
 interface AdvisorProcedureProtection {
   /** `true` when the handler references `ctx.mail` / `ctx.email` (sends mail). */
   callsMail: boolean;
+  /** `true` when the handler emits a structured observability event (`ctx.log` / `ctx.span` / `ctx.trace`). */
+  emitsEvent?: boolean;
+  /**
+   * `true` when the source carries a `// lunora-advisor-exempt` directive above
+   * the export — the developer's explicit opt-out. The row still appears in the
+   * map, marked `exempt`, but pulls no weight.
+   */
+  exempt?: boolean;
+  /** The `-- reason` from the directive, so an exemption is argued rather than silent. */
+  exemptReason?: string;
   /** The exported binding name of the procedure (e.g. `signUp`). */
   exportName: string;
   /** `true` when the handler fans work out to a privileged, cost-bearing dispatch surface (scheduler `runAfter`/`runAt`, a queue producer send, or a workflow create). Read by the privileged-fanout lint, paired with public visibility and no rate limit. */
   fanOut: boolean;
   /** Source file relative to the lunora dir, no extension. */
   file: string;
+  /** `true` when the handler wraps work in `try`/`catch`. */
+  handlesErrors?: boolean;
   /**
    * `true` when the procedure declares an email-shaped argument. Read by the
    * `signup_mutation_without_disposable_gating` lint: `emailGateMiddleware`
@@ -924,6 +906,12 @@ interface AdvisorProcedureProtection {
   hasEmailArg?: boolean;
   /** Registration kind — `query` is read-only; `mutation`/`action` are write-shaped. */
   kind: "action" | "mutation" | "query";
+  /** `true` when the handler runs any AI generation, bounded or not. */
+  runsAiGeneration?: boolean;
+  /** `true` when the handler reaches an outbound surface (`ctx.fetch`, mail, queues, storage, sql, ai, …) that can fail. */
+  reachesOutbound?: boolean;
+  /** `true` when the handler throws a bare `new Error(...)` rather than a coded `LunoraError`. */
+  throwsBareError?: boolean;
   /** `true` when the handler runs an AI generation (`generateText`/`streamText`/`generateObject`/`streamObject`) with no `maxOutputTokens` bound. Read by the `ai_unbounded_generation_public` lint (paired with public visibility). */
   unboundedAiGeneration: boolean;
   /** `true` when the chain carries `.use(verifyTurnstile(...))` or a `protectPublic({ captcha })` bundle. */
@@ -950,6 +938,16 @@ interface AdvisorProcedureProtection {
  * supply it, so the lint simply finds nothing there.
  */
 interface AdvisorQueryRead {
+  /**
+   * The exported procedure the read sits in, when the feeder could resolve one.
+   * Carried so the advisor map can attribute the finding to that procedure's row
+   * rather than to the project bucket; a read outside any export (module scope)
+   * legitimately has none.
+   *
+   * Optional so a feeder predating this field still typechecks — such a run
+   * simply attributes project-wide, exactly as before.
+   */
+  exportName?: string;
   /** Source file the read appears in (relative to the lunora dir, no extension). */
   file: string;
   /** True when the chain calls `.filter(...)`. */
@@ -1468,6 +1466,36 @@ interface AdvisorTableSample {
   /** Whether more rows exist beyond the cap. */
   readonly truncated: boolean;
 }
+/**
+ * One branching `defineShape({ where })` / `definePolicy({ when })` predicate arm
+ * that returns an unrestricted predicate — the `unrestricted_where_branch` lint
+ * input.
+ *
+ * A row predicate returns a *filter*, not a boolean, so the denial arm has to be a
+ * predicate matching **no** rows: `deny()` / `{ OR: [] }`, a disjunction over zero
+ * branches. The plausible-looking `{}` is its exact opposite — it matches every row,
+ * so an arm meaning "this caller sees nothing" silently replicates or exposes the
+ * whole table, with no error and no log line.
+ *
+ * Only reported for a *branching* predicate: a single-exit `where: () => ({})` is an
+ * author deliberately replicating everything, which is legitimate. Produced by the
+ * codegen feeder; runtime callers don't supply it, so the lint finds nothing there.
+ * Structurally identical to `UnrestrictedWhereBranchIR`.
+ */
+interface AdvisorUnrestrictedWhereBranch {
+  /** The exported binding name of the shape / policy the predicate belongs to. */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** Which unrestricted form was returned. */
+  form: "empty-object" | "undefined";
+  /** The config key carrying the predicate (`where` for a shape, `when` for a policy). */
+  key: string;
+  /** 1-based line of the offending returned expression. */
+  line: number;
+  /** The declaring call (`defineShape` / `definePolicy`). */
+  owner: string;
+}
 /**
  * One `ctx.vectors.<method>(indexName, input)` call whose `input.namespace` is
  * derived from the handler's `args` with no server-side scoping — the input the
@@ -1912,12 +1940,6 @@ interface LintContext {
    * absent for runtime callers, where the lint finds nothing.
    */
   ownerFieldWrites?: ReadonlyArray<AdvisorOwnerFieldWrite>;
-  /**
-   * Branching shape/policy predicate arms returning an unrestricted filter (`{}` /
-   * `undefined`) — the `unrestricted_where_branch` lint input. Supplied by the
-   * codegen feeder only.
-   */
-  unrestrictedWhereBranches?: ReadonlyArray<AdvisorUnrestrictedWhereBranch>;
   /**
    * Payment webhook-adapter constructions (`createStripeAdapter` /
    * `createPolarAdapter` / `createAutumnAdapter` / `createDodoPaymentsAdapter`) — the payment-webhook wide-tolerance lint's input. Each row's
@@ -2090,6 +2112,12 @@ interface LintContext {
    * and shards. Absent for static callers, where the lint finds nothing.
    */
   tableScans?: ReadonlyArray<AdvisorTableScan>;
+  /**
+   * Branching shape/policy predicate arms returning an unrestricted filter (`{}` /
+   * `undefined`) — the `unrestricted_where_branch` lint input. Supplied by the
+   * codegen feeder only.
+   */
+  unrestrictedWhereBranches?: ReadonlyArray<AdvisorUnrestrictedWhereBranch>;
   /**
    * `ctx.vectors.&lt;method>(index, { namespace, … })` calls whose `namespace` is
    * derived from the handler's `args` with no server-side scoping — the
@@ -2322,6 +2350,21 @@ declare const indexUtilization: Lint;
  * arg-derived `ctx.fetch` call.
  */
 declare const actionFetchSsrf: Lint;
+/**
+ * Flags an `action` that reaches an outbound surface with no `try`/`catch`
+ * anywhere in its body.
+ *
+ * Actions are where Lunora talks to things it does not control — `ctx.fetch`,
+ * mail, queues, storage, external SQL, AI. Every one of those fails routinely
+ * (timeout, 5xx, quota), and an uncaught rejection there surfaces to the caller
+ * as an opaque failure with no indication of which dependency broke. Catching it
+ * is what lets the handler add that context, or degrade instead of failing.
+ *
+ * Only `action` is checked: queries and mutations run inside the Durable Object
+ * and cannot reach these surfaces. Runs only when the codegen feeder supplies
+ * procedure evidence.
+ */
+declare const actionWithoutErrorHandling: Lint;
 /**
  * Flags an `httpRoute` on an admin/privileged-looking path whose handler shows no
  * auth/admin guard.
@@ -2359,6 +2402,22 @@ declare const adminRouteWithoutGuard: Lint;
  * arg-derived, unscoped `ctx.ai.run` call.
  */
 declare const aiRawRunEscapeHatch: Lint;
+/**
+ * Flags a procedure that runs an AI generation but emits no structured event.
+ *
+ * Model calls are the least reproducible thing in an app and the only one that
+ * bills per invocation: the same input can return a different answer tomorrow,
+ * and a runaway loop is a cost incident rather than an outage. Without an event
+ * recording that the call happened there is no way to attribute spend, compare a
+ * bad answer against the prompt that produced it, or notice a retry storm.
+ *
+ * Keyed on whether the handler runs a model at all — bounded or not. An earlier
+ * cut reused the `unboundedAiGeneration` / raw-run signals, which meant the
+ * correctly-bounded `generateText({ …, maxOutputTokens })` — the common case, and
+ * the one this rule exists for — was never flagged, while procedures another lint
+ * had already caught were charged twice.
+ */
+declare const aiRunWithoutLogging: Lint;
 /**
  * Flags a `generateText` / `streamText` call whose model input is user-derived
  * **and** whose model-callable `tools` reach a privileged side effect.
@@ -2476,6 +2535,30 @@ declare const authCsrfCheckDisabled: Lint;
  * call.
  */
 declare const authEmailVerificationDisabled: Lint;
+/**
+ * Flags a `createAuth({...})` call that loads `scim()` on an adapter with no native
+ * transactions.
+ *
+ * `@better-auth/scim` refuses to serve at all unless its adapter exposes a
+ * `transaction` function — its provisioning writes go through a read-then-conditional-write
+ * decommission lease. `lunoraD1Adapter` and `lunoraAuthAdapter` are single-table CRUD,
+ * and D1 has no interactive transactions to expose in the first place, so this pairing
+ * throws on the first SCIM request:
+ *
+ * ```
+ * BetterAuthError: The scim plugin requires a database adapter with native transaction support.
+ * ```
+ *
+ * This exists because the combination shipped in real documentation once. It is not a
+ * subtle misconfiguration — it is a deployment where directory sync cannot work at all —
+ * and it is entirely visible at build time, so there is no reason for the first
+ * indication to be a 500 from an IdP's provisioning call.
+ *
+ * Runs only when the codegen feeder supplies auth-config evidence
+ * (`context.authConfigs`), and only for an analyzable config; an opaque one could pass
+ * a different `database` and is skipped rather than guessed at.
+ */
+declare const authScimWithoutTransactions: Lint;
 /**
  * Flags a `createAuth({...})` call whose `advanced.useSecureCookies` is
  * explicitly `false`.
@@ -2515,30 +2598,6 @@ declare const authSecureCookiesDisabled: Lint;
  * call.
  */
 declare const authSessionFreshageZero: Lint;
-/**
- * Flags a `createAuth({...})` call that loads `scim()` on an adapter with no native
- * transactions.
- *
- * `@better-auth/scim` refuses to serve at all unless its adapter exposes a
- * `transaction` function — its provisioning writes go through a read-then-conditional-write
- * decommission lease. `lunoraD1Adapter` and `lunoraAuthAdapter` are single-table CRUD,
- * and D1 has no interactive transactions to expose in the first place, so this pairing
- * throws on the first SCIM request:
- *
- * ```
- * BetterAuthError: The scim plugin requires a database adapter with native transaction support.
- * ```
- *
- * This exists because the combination shipped in real documentation once. It is not a
- * subtle misconfiguration — it is a deployment where directory sync cannot work at all —
- * and it is entirely visible at build time, so there is no reason for the first
- * indication to be a 500 from an IdP's provisioning call.
- *
- * Runs only when the codegen feeder supplies auth-config evidence
- * (`context.authConfigs`), and only for an analyzable config; an opaque one could pass
- * a different `database` and is skipped rather than guessed at.
- */
-declare const authScimWithoutTransactions: Lint;
 /**
  * Flags a `createAuth({...})` call whose `trustedOrigins` array literal
  * contains a `"*"` entry.
@@ -2694,6 +2753,19 @@ declare const duplicateIndex: Lint;
  * least one field by construction, so only `kind: "index"` is checked.)
  */
 declare const emptyIndex: Lint;
+/**
+ * Flags a procedure that throws a bare `new Error(...)`.
+ *
+ * A bare `Error` crosses the RPC boundary as an opaque message: the client
+ * cannot branch on it, `@lunora/fingerprint` cannot group it into an issue, and
+ * the message itself is free text that changes whenever someone edits the
+ * string. `LunoraError` carries a stable code from `ERROR_CATALOG`, which is
+ * what makes an error both matchable on the client and groupable in Studio.
+ *
+ * Runs only when the codegen feeder supplies procedure evidence; a runtime
+ * caller with no evidence flags nothing.
+ */
+declare const errorWithoutCatalog: Lint;
 /**
  * Flags a misconfigured CDC export sink (plan 170) — a `defineExportSink` /
  * `webhookExportSink` / `r2Sink` construction with a required config field
@@ -3378,6 +3450,23 @@ declare const privilegedDispatchUnvalidatedPayload: Lint;
  * per unguarded public fan-out procedure.
  */
 declare const privilegedFanoutFromPublicProcedure: Lint;
+/**
+ * Flags a public `mutation`/`action` whose handler emits no structured
+ * observability event.
+ *
+ * When one of these fails in production you get a stack trace and nothing about
+ * the request that caused it — no ids, no tenant, no outcome. `ctx.log` /
+ * `ctx.span` attach that context to the invocation, so the failure is
+ * searchable instead of merely visible. Reads are excluded: a `query` that
+ * returns the wrong rows is diagnosable from its arguments, while a write that
+ * half-succeeded is not.
+ *
+ * Runs only when the codegen feeder supplies procedure evidence; a runtime
+ * caller with no evidence flags nothing. The feeder reports "no event" only when
+ * it could read the body, so a procedure whose handler it cannot analyze is left
+ * alone rather than nagged.
+ */
+declare const procedureWithoutStructuredEvent: Lint;
 /**
  * Flags a `v.any()` argument on a public procedure.
  *
@@ -3982,6 +4071,253 @@ declare const workflowUnknownTarget: Lint;
  * (`context.workflows` present); a runtime caller flags nothing.
  */
 declare const workflowUnused: Lint;
+/** Letter band for a 0–100 score. */
+type Grade = "at-risk" | "excellent" | "good" | "needs-work";
+/**
+ * How a single procedure came out of the lints that apply to it.
+ *
+ * Named for severity rather than instrumentation, because the score is driven by
+ * every lint family (security, performance, schema): a verdict like
+ * "uninstrumented" would claim something the map does not measure, and would
+ * report a security regression as a telemetry gap. `clean` means no lint fired.
+ * `exempt` rows pull no weight.
+ */
+type Coverage = "clean" | "exempt" | "failing" | "warned";
+/**
+ * One *rule* that fired against a procedure, reduced to its score contribution.
+ *
+ * Deduplicated by lint: a rule that fires on five call sites is one check with
+ * `occurrences: 5`, costing its weight once. Counting occurrences instead would
+ * let a single rule zero a procedure and would fill the artifact with identical
+ * rows.
+ */
+interface CheckResult {
+  /** Worst severity seen across this rule's occurrences. */
+  level: Level;
+  /** The lint id that fired, e.g. `unindexed_foreign_key`. */
+  name: string;
+  /** How many findings this rule produced on the procedure (>= 1). */
+  occurrences: number;
+  /** Points subtracted from the procedure's score — charged once, not per occurrence. */
+  weight: number;
+}
+/** How much a procedure's failures matter — see `classifySensitivity`. */
+type SensitivityLevel = "high" | "none";
+/** A procedure's sensitivity plus the declarations that produced it. */
+interface Sensitivity {
+  /** `high` when any signal fired; `none` means no signal, not "safe". */
+  level: SensitivityLevel;
+  /** Human-readable signals, e.g. "writes an identity table". Empty when `none`. */
+  reasons: string[];
+}
+/** One scored procedure — the unit the map is built from. */
+interface ProcedureScore {
+  /** Rules that fired against this procedure, sorted by `name`. */
+  checks: CheckResult[];
+  /** Verdict derived from {@link ProcedureScore.score}. */
+  coverage: Coverage;
+  /** Why this row is `exempt`, when a source directive said so. Empty when none was given. */
+  exemptReason?: string;
+  /** Exported binding name, e.g. `sendMessage`. */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** Stable `file#exportName` identity — the baseline diff key. */
+  id: string;
+  /** Registration kind. */
+  kind: "action" | "mutation" | "query";
+  /** 0–100, starting at 100 less each fired rule's weight. */
+  score: number;
+  /** How much this procedure's failures matter, and why. */
+  sensitivity: Sensitivity;
+  /** Public (client-callable) or internal (server-called). */
+  visibility: "internal" | "public";
+  /** This row's weight in the global mean — see `procedureWeight`. */
+  weight: number;
+}
+/**
+ * Findings that name no procedure — schema-shape and project-wide lints
+ * (missing index, circular FK, plaintext wrangler secret), plus any finding
+ * whose `file`/`exportName` matches no declared procedure.
+ *
+ * Folded into the global mean at a weight proportional to the procedure
+ * population (see `projectWeight`) so schema debt genuinely moves the grade.
+ * Because this single score saturates at 0, `compareToBaseline` also diffs
+ * `checks.length` — otherwise new schema errors would be free once the bucket
+ * bottoms out.
+ */
+interface ProjectScore {
+  /** Rules that fired at project level, sorted by `name`. */
+  checks: CheckResult[];
+  /** 0–100, same formula as a procedure. */
+  score: number;
+}
+/** Coverage tallies for the summary line and the Studio matrix header. */
+interface MapSummary {
+  /** Procedures with no lint firing. */
+  clean: number;
+  /** Procedures excluded from scoring. */
+  exempt: number;
+  /** Procedures scoring below the failing floor. */
+  failing: number;
+  /** Total procedures in the map, exempt included. */
+  procedures: number;
+  /** Findings attributed to a scored row, after per-rule deduplication. */
+  rulesFired: number;
+  /** Procedures scoring at or above the failing floor, but not clean. */
+  warned: number;
+}
+/**
+ * The `lunora.advisor.map.json` artifact — the unit a baseline is diffed
+ * against and the Studio health panel renders.
+ */
+interface AdvisorMap {
+  /**
+   * ISO-8601 stamp. Defaults to the current time; pass
+   * `ScoreAdvisorOptions.generatedAt` explicitly when the artifact must be
+   * byte-stable (tests, reproducible builds) — everything else in the map is
+   * a pure function of the findings.
+   */
+  generatedAt: string;
+  /** Band for {@link AdvisorMap.score}. */
+  grade: Grade;
+  /** Per-procedure rows, sorted by `id` for a stable diff. */
+  procedures: ProcedureScore[];
+  /** Findings not attributable to a procedure. */
+  project: ProjectScore;
+  /** Weighted mean over non-exempt procedures plus the project entry, 0–100. */
+  score: number;
+  /** Coverage tallies. */
+  summary: MapSummary;
+  /** Artifact shape version; bump on a breaking change so an old baseline is rejected rather than mis-read. */
+  version: number;
+}
+/** One procedure whose score moved between the baseline and the current map. */
+interface ProcedureDelta {
+  /** Score in the current map. */
+  after: number;
+  /** Score in the baseline. */
+  before: number;
+  /** `file#exportName`. */
+  id: string;
+}
+/**
+ * The verdict a CI gate acts on.
+ *
+ * A discriminated union on purpose: the obvious shape (a flat object with
+ * `comparable: boolean` and `regressed: false` when incomparable) reads as
+ * "no regression" for a missing, stale, or corrupt baseline, so a gate written
+ * as `if (diff.regressed)` silently passes forever after a `MAP_VERSION` bump.
+ * Forcing the caller to narrow makes that mistake unrepresentable.
+ */
+type BaselineComparison = {
+  comparable: false;
+  /** Why no comparison was possible — a gate should treat this as "cannot verify", not "clean". */
+  reason: "version-mismatch";
+} | {
+  comparable: true;
+  /** Procedures present in both maps whose score fell, sorted by `id`. */
+  dropped: ProcedureDelta[];
+  /** Procedures that are `failing` now and were not before — new rows included. */
+  newFailing: string[];
+  /** `true` when the project bucket gained rules or occurrences, even if its saturated score did not move. */
+  projectRegressed: boolean;
+  /** `true` when any signal above fired. */
+  regressed: boolean;
+  /** Current global score less the baseline's; negative is a regression. */
+  scoreDelta: number;
+  /**
+   * Procedures whose score held but whose findings grew — a new rule fired,
+   * or an existing one fired at more call sites. Scoring charges a rule once
+   * however many times it fires, so without this signal "same rule, five more
+   * violations" would look identical to the baseline.
+   */
+  worsened: string[];
+};
+/**
+ * Diff a freshly-scored map against a committed one.
+ *
+ * Five independent regression signals, any of which fails a gate: the global
+ * score fell, a procedure that existed before got worse, a procedure started
+ * failing, a procedure's findings grew without its score moving, or the project
+ * bucket gained findings. The per-procedure signals matter because a refactor can
+ * leave the global mean flat while gutting one handler; the growth signals matter
+ * because a rule is charged once however many times it fires, and the project
+ * score saturates at 0 — without them, new violations would be free.
+ */
+declare const compareToBaseline: (current: AdvisorMap, baseline: AdvisorMap) => BaselineComparison;
+/**
+ * Narrow a parsed `lunora.advisor.map.json` to an {@link AdvisorMap}, returning
+ * `undefined` when it is not one this build can read.
+ *
+ * Validates *shape* — the header and every procedure row — because
+ * `compareToBaseline` dereferences `entry.id` / `entry.score` /
+ * `entry.coverage`: a truncated or merge-conflicted baseline with a `null` row
+ * would otherwise crash the gate, and a row of `{}` would compare as a silent
+ * no-op. Non-finite scores are rejected for the same reason — `NaN < 0` is
+ * `false`, which reads as "no regression".
+ *
+ * Version *policy* deliberately lives in {@link compareToBaseline}, not here.
+ * Rejecting a mismatch in both places made that function's `comparable: false`
+ * arm unreachable through every shipped path, so the union that exists to stop a
+ * stale baseline reading as "clean" was never exercised. Here we only require a
+ * version to be present and finite.
+ */
+declare const parseAdvisorMap: (value: unknown) => AdvisorMap | undefined;
+/** Band a 0–100 score. */
+declare const gradeFromScore: (score: number) => Grade;
+/**
+ * Codepoint ordering. `localeCompare` would sort by the host's `LANG`/`LC_ALL`,
+ * so the same repo scored on a Danish-locale runner emits a different row order
+ * than an `en_US` one — the committed artifact would churn and a
+ * `git diff --exit-code` gate would fail for no reason. Ordering must be a
+ * property of the data, not the machine.
+ */
+declare const byCodepoint: (a: string, b: string) => number;
+/**
+ * {@link AdvisorMap.version} this build emits. Bump on a breaking shape change
+ * so `compareToBaseline` rejects a stale artifact instead of mis-reading it.
+ */
+declare const MAP_VERSION = 1;
+/** Options for {@link scoreAdvisor}. */
+interface ScoreAdvisorOptions {
+  /**
+   * Procedure ids (`file#exportName`) to exclude from scoring, for a caller
+   * that computes exemptions itself. Source-level `// lunora-advisor-exempt`
+   * directives are honoured independently; the two compose.
+   */
+  exempt?: ReadonlyArray<string>;
+  /**
+   * Stamp written to {@link AdvisorMap.generatedAt}. Defaults to now; pass it
+   * explicitly when the map must be byte-stable (tests, reproducible builds).
+   */
+  generatedAt?: string;
+}
+/**
+ * Roll a lint run up into a scored coverage map (see the package's
+ * `docs/index.mdx` for the scoring rules and the baseline gate).
+ *
+ * Pure: it re-reads the `findings` a caller already got from `runAdvisor` rather
+ * than running lints itself, so scoring never double-runs a rule and the lint
+ * core stays untouched. Findings are attributed to a procedure via their
+ * `metadata.file` + `metadata.exportName`; everything else lands in the project
+ * bucket, which is folded into the global mean at a weight proportional to the
+ * procedure population so schema debt genuinely moves the grade.
+ *
+ * Takes the procedure list directly rather than a `LintContext`: it reads no
+ * other feeder, and asking for the whole context forced callers with only a
+ * procedure array to fabricate an empty schema.
+ */
+declare const scoreAdvisor: (procedures: ReadonlyArray<AdvisorProcedureProtection>, findings: ReadonlyArray<Finding>, options?: ScoreAdvisorOptions) => AdvisorMap;
+/**
+ * Classify how much a procedure's failures matter, from the protective
+ * declarations and behavioural facts the feeder already collected.
+ *
+ * Runs before any rule so a lint can gate on it, and feeds the global weighting:
+ * a handler touching identity, mail, or tenant-scoped rows pulls harder on the
+ * grade than a plain read. `none` means no signal fired — not "safe".
+ */
+declare const classifySensitivity: (procedure: AdvisorProcedureProtection) => Sensitivity;
 /**
  * Every lint that runs against the declared schema (and, for
  * `filter_without_index`, the discovered query reads) — no running shard
@@ -4013,4 +4349,4 @@ interface RunAdvisorOptions {
  * `static` lints at build time and defer `runtime` lints to a live shard.
  */
 declare const runAdvisor: (context: LintContext, options?: RunAdvisorOptions) => Finding[];
-export { AE_METRIC_EVENTS, ALL_LINTS, type AdvisorAdminRoute, type AdvisorAiRawRun, type AdvisorAiToolSideEffect, type AdvisorArgumentDerivedFetch, type AdvisorArgumentValidator, type AdvisorAuthApiCall, type AdvisorAuthConfig, type AdvisorBrowserUrlAccess, type AdvisorConfigCall, type AdvisorContainer, type AdvisorContainerKeyAccess, type AdvisorContainerOverride, type AdvisorExportSink, type AdvisorFailOpenGuard, type AdvisorFlagSecurityDefault, type AdvisorGeoIndexUsage, type AdvisorHttpActionGuard, type AdvisorHttpHeaderWrite, type AdvisorHyperdriveCall, type AdvisorIdentityClaimRead, type AdvisorImageDeliveryUrlAccess, type AdvisorIndex, type AdvisorIndexHit, type AdvisorInsertWrite, type AdvisorKvKeyAccess, type AdvisorMailRecipientAccess, type AdvisorMaskProcedure, type AdvisorMaskStrategy, type AdvisorMutatorWrite, type AdvisorNondeterministicCall, type AdvisorNormalizeIdAuthorization, type AdvisorNotifyCall, type AdvisorNotifyConfig, type AdvisorOwnerFieldWrite, type AdvisorPaymentWebhook, type AdvisorPrivilegedDispatch, type AdvisorProcedureProtection, type AdvisorQueryRead, type AdvisorQueue, type AdvisorQueueTuning, type AdvisorR2sqlCall, type AdvisorRatelimitKeySelector, type AdvisorRawRowReturn, type AdvisorRelation, type AdvisorRelationLoad, type AdvisorRlsProcedure, type AdvisorSchema, type AdvisorSecretLiteral, type AdvisorShape, type AdvisorShardTraffic, type AdvisorSoftDeleteRead, type AdvisorSqlInterpolation, type AdvisorStorageKeyAccess, type AdvisorStorageUpload, type AdvisorTable, type AdvisorTableSample, type AdvisorTableScan, type AdvisorVectorNamespaceAccess, type AdvisorWorkflow, type AdvisorWorkflowCall, type AdvisorWranglerVariable, type AnalyticsMetricsOptions, type AnalyticsMetricsSource, type AnalyticsRuntimeMetrics, type Category, type Facing, type Finding, type Level, type Lint, type LintContext, type LintSource, RUNTIME_LINTS, RunAdvisorOptions, STATIC_LINTS, actionFetchSsrf, adminRouteWithoutGuard, aiRawRunEscapeHatch, aiToolSideEffectPromptInjection, aiUnboundedGenerationPublic, allowUnauthenticatedShardAccessEnabled, authApiCallWithoutHeaders, authCsrfCheckDisabled, authEmailVerificationDisabled, authScimWithoutTransactions, authSecureCookiesDisabled, authSessionFreshageZero, authTrustedOriginsWildcard, browserAllowPrivateTargets, browserUserUrlWithoutAllowlist, circularFk, constraintValidator, containerInstanceKeyFromUserInput, containerOversizedInstance, containerPublicInternet, containerRuntimeEgressRelaxation, containerStartEnableInternetOverride, dedupeCacheKeys, duplicateIndex, emptyIndex, exportSinkMisconfigured, externalSourceIncrementalNoDeletePath, externalSourceOnGlobal, externalSourceUnscoped, filterWithoutIndex, flagGatesSecurityWithUnsafeDefault, fromServerSchema, geoIndexFieldNotGeopoint, geoIndexUnused, hardcodedSecret, hotShard, httpActionMissingAuthGuard, httpActionResponseHeaderInjection, hyperdriveOutsideAction, identityUndeclaredClaimTrusted, imagesUrlSourceFromUserInput, indexReferencesUnknownField, indexUtilization, insertManyUnsafeUserData, kvUnscopedUserKeyIdor, loadAnalyticsRuntimeMetrics, mailInboundDispatchWithoutVerify, mailRecipientFromRequestInput, maskUncoveredPiiColumn, maskWeakHashStrategyOnPii, maskedRelationLeakViaWith, mutatorFullRowReplace, nondeterministicQueryMutation, normalizeIdUsedAsAuthorization, notifyMissingPushConfig, notifySendOutsideAction, outputProjectionMissingOnPublicRead, ownerFieldFromArgsNotAuth, paymentCreateWithoutAuthorize, paymentWebhookWideTolerance, plaintextSecretInWranglerVariables, policyReferencesUnknownTable, privilegedDispatchUnvalidatedPayload, privilegedFanoutFromPublicProcedure, publicArgumentUsesAny, publicMutationWithoutRatelimit, publicTableRlsOptoutConfusion, queueWithoutDlq, r2sqlOutsideAction, ratelimitDefaultMemoryStore, ratelimitKeySpoofableOrGlobal, ratelimitMiddlewareFailOpen, relationReferencesUnknownField, relationReferencesUnknownTable, rlsUncoveredTable, runAdvisor, shapeTargetsGlobalTable, shapeUnknownTable, signupMutationWithoutDisposableGating, softDeleteIncludeDeletedFromArgs, sqlInjectionRisk, storageGenerateUploadUrlNoContentTypePin, storageKeyFromUserArgs, storagePresignedUrlForPrivateContent, storageUploadWithoutContentTypeAllowlist, storageUploadWithoutMaxSize, tableWithoutInsert, ttlFieldNotTimestamp, unboundedStringArgument, unindexedForeignKey, unindexedRelationTarget, unrestrictedWhereBranch, userCreatingMutationWithoutCaptcha, vectorsNamespaceFromUserInput, workflowDuplicateStepName, workflowUnknownTarget, workflowUnused };
+export { AE_METRIC_EVENTS, ALL_LINTS, type AdvisorAdminRoute, type AdvisorAiRawRun, type AdvisorAiToolSideEffect, type AdvisorArgumentDerivedFetch, type AdvisorArgumentValidator, type AdvisorAuthApiCall, type AdvisorAuthConfig, type AdvisorBrowserUrlAccess, type AdvisorConfigCall, type AdvisorContainer, type AdvisorContainerKeyAccess, type AdvisorContainerOverride, type AdvisorExportSink, type AdvisorFailOpenGuard, type AdvisorFlagSecurityDefault, type AdvisorGeoIndexUsage, type AdvisorHttpActionGuard, type AdvisorHttpHeaderWrite, type AdvisorHyperdriveCall, type AdvisorIdentityClaimRead, type AdvisorImageDeliveryUrlAccess, type AdvisorIndex, type AdvisorIndexHit, type AdvisorInsertWrite, type AdvisorKvKeyAccess, type AdvisorMailRecipientAccess, type AdvisorMap, type AdvisorMaskProcedure, type AdvisorMaskStrategy, type AdvisorMutatorWrite, type AdvisorNondeterministicCall, type AdvisorNormalizeIdAuthorization, type AdvisorNotifyCall, type AdvisorNotifyConfig, type AdvisorOwnerFieldWrite, type AdvisorPaymentWebhook, type AdvisorPrivilegedDispatch, type AdvisorProcedureProtection, type AdvisorQueryRead, type AdvisorQueue, type AdvisorQueueTuning, type AdvisorR2sqlCall, type AdvisorRatelimitKeySelector, type AdvisorRawRowReturn, type AdvisorRelation, type AdvisorRelationLoad, type AdvisorRlsProcedure, type AdvisorSchema, type AdvisorSecretLiteral, type AdvisorShape, type AdvisorShardTraffic, type AdvisorSoftDeleteRead, type AdvisorSqlInterpolation, type AdvisorStorageKeyAccess, type AdvisorStorageUpload, type AdvisorTable, type AdvisorTableSample, type AdvisorTableScan, type AdvisorVectorNamespaceAccess, type AdvisorWorkflow, type AdvisorWorkflowCall, type AdvisorWranglerVariable, type AnalyticsMetricsOptions, type AnalyticsMetricsSource, type AnalyticsRuntimeMetrics, type BaselineComparison, type Category, type CheckResult, type Coverage, type Facing, type Finding, type Grade, type Level, type Lint, type LintContext, type LintSource, MAP_VERSION, type MapSummary, type ProcedureDelta, type ProcedureScore, type ProjectScore, RUNTIME_LINTS, RunAdvisorOptions, STATIC_LINTS, type ScoreAdvisorOptions, type Sensitivity, type SensitivityLevel, actionFetchSsrf, actionWithoutErrorHandling, adminRouteWithoutGuard, aiRawRunEscapeHatch, aiRunWithoutLogging, aiToolSideEffectPromptInjection, aiUnboundedGenerationPublic, allowUnauthenticatedShardAccessEnabled, authApiCallWithoutHeaders, authCsrfCheckDisabled, authEmailVerificationDisabled, authScimWithoutTransactions, authSecureCookiesDisabled, authSessionFreshageZero, authTrustedOriginsWildcard, browserAllowPrivateTargets, browserUserUrlWithoutAllowlist, byCodepoint, circularFk, classifySensitivity, compareToBaseline, constraintValidator, containerInstanceKeyFromUserInput, containerOversizedInstance, containerPublicInternet, containerRuntimeEgressRelaxation, containerStartEnableInternetOverride, dedupeCacheKeys, duplicateIndex, emptyIndex, errorWithoutCatalog, exportSinkMisconfigured, externalSourceIncrementalNoDeletePath, externalSourceOnGlobal, externalSourceUnscoped, filterWithoutIndex, flagGatesSecurityWithUnsafeDefault, fromServerSchema, geoIndexFieldNotGeopoint, geoIndexUnused, gradeFromScore, hardcodedSecret, hotShard, httpActionMissingAuthGuard, httpActionResponseHeaderInjection, hyperdriveOutsideAction, identityUndeclaredClaimTrusted, imagesUrlSourceFromUserInput, indexReferencesUnknownField, indexUtilization, insertManyUnsafeUserData, kvUnscopedUserKeyIdor, loadAnalyticsRuntimeMetrics, mailInboundDispatchWithoutVerify, mailRecipientFromRequestInput, maskUncoveredPiiColumn, maskWeakHashStrategyOnPii, maskedRelationLeakViaWith, mutatorFullRowReplace, nondeterministicQueryMutation, normalizeIdUsedAsAuthorization, notifyMissingPushConfig, notifySendOutsideAction, outputProjectionMissingOnPublicRead, ownerFieldFromArgsNotAuth, parseAdvisorMap, paymentCreateWithoutAuthorize, paymentWebhookWideTolerance, plaintextSecretInWranglerVariables, policyReferencesUnknownTable, privilegedDispatchUnvalidatedPayload, privilegedFanoutFromPublicProcedure, procedureWithoutStructuredEvent, publicArgumentUsesAny, publicMutationWithoutRatelimit, publicTableRlsOptoutConfusion, queueWithoutDlq, r2sqlOutsideAction, ratelimitDefaultMemoryStore, ratelimitKeySpoofableOrGlobal, ratelimitMiddlewareFailOpen, relationReferencesUnknownField, relationReferencesUnknownTable, rlsUncoveredTable, runAdvisor, scoreAdvisor, shapeTargetsGlobalTable, shapeUnknownTable, signupMutationWithoutDisposableGating, softDeleteIncludeDeletedFromArgs, sqlInjectionRisk, storageGenerateUploadUrlNoContentTypePin, storageKeyFromUserArgs, storagePresignedUrlForPrivateContent, storageUploadWithoutContentTypeAllowlist, storageUploadWithoutMaxSize, tableWithoutInsert, ttlFieldNotTimestamp, unboundedStringArgument, unindexedForeignKey, unindexedRelationTarget, unrestrictedWhereBranch, userCreatingMutationWithoutCaptcha, vectorsNamespaceFromUserInput, workflowDuplicateStepName, workflowUnknownTarget, workflowUnused };