@lunora/advisor 0.0.0 → 1.0.0-alpha.2

package/dist/index.d.mts

@@ -0,0 +1,1451 @@
+import { Schema } from '@lunora/server';
+/**
+* One `httpRoute.<verb>("/admin/…")` REST route on an admin/privileged-looking
+* path, with whether its handler references an auth/admin guard — the input the
+* `admin_route_without_guard` lint consumes. Produced by the codegen feeder;
+* runtime callers don't supply it, so the lint finds nothing there.
+*/
+interface AdvisorAdminRoute {
+  /** The exported binding name of the route handler. */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** HTTP verb the route binds to (uppercased), e.g. `"POST"`. */
+  method: string;
+  /** The route path, e.g. `/admin/users`. */
+  path: string;
+  /** `true` when the handler references an auth/session/admin guard. */
+  usesGuard: boolean;
+}
+/**
+* One public procedure's argument validators reduced to the input-safety facts
+* the `public_arg_uses_any` and `unbounded_string_arg` lints consume: which args
+* are declared `v.any()` (unvalidated input) and which `v.string()` args carry no
+* length bound (a DoS / storage-abuse vector). Produced by the codegen feeder for
+* public procedures only; internal functions take server-trusted input. Runtime
+* callers don't supply it, so the lints find nothing there.
+*/
+interface AdvisorArgumentValidator {
+  /** Arg names declared as `v.any()`. */
+  anyArgs: ReadonlyArray<string>;
+  /** The exported binding name of the procedure (e.g. `updateProfile`). */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** 1-based line of the registration call, or `0` when unknown. */
+  line: number;
+  /** Arg names declared as `v.string()` with no statically-visible max-length bound. */
+  unboundedStringArgs: ReadonlyArray<string>;
+}
+/**
+* One `ctx.authApi.&lt;method>(...)` call discovered in a function body — the input
+* the `auth_api_call_without_headers` lint consumes. Produced by the codegen
+* feeder; runtime callers don't supply it, so the lint finds nothing there.
+*/
+interface AdvisorAuthApiCall {
+  /** The exported function performing the call (e.g. `createOrg`). */
+  exportName: string;
+  /** Source file the call appears in (relative to the lunora dir, no extension). */
+  file: string;
+  /** True when the call's argument object includes a `headers` property. */
+  hasHeaders: boolean;
+  /** 1-based line of the call, or `0` when unknown. */
+  line: number;
+  /** The better-auth method invoked (e.g. `banUser`); empty when not statically known. */
+  method: string;
+}
+/**
+* One container declaration discovered in `lunora/containers.ts` — the input
+* the `container_*` lints consume. Produced by the codegen feeder (which lifts
+* the static fields of each `defineContainer({...})` export); runtime callers
+* don't supply it, so the container lints simply find nothing there.
+*
+* A structural subset of codegen's `ContainerIR`, so the feeder can pass the
+* IR array straight through without conversion (mirrors how `AdvisorQueryRead`
+* tracks `QueryReadIR`).
+*/
+interface AdvisorContainer {
+  /**
+  * Whether outbound internet was explicitly configured. `undefined` means
+  * the field was omitted (platform default `true`) or wasn't a static literal.
+  */
+  enableInternet?: boolean;
+  /** The `lunora/containers.ts` export name, e.g. `transcoder`. */
+  exportName: string;
+  /** Declared `instanceType`: a named size, or a custom `{ vcpu, memoryMib, diskMb }`. */
+  instanceType?: string | {
+    diskMb?: number;
+    memoryMib?: number;
+    vcpu?: number;
+  };
+  /** Declared `maxInstances` cap, when present. */
+  maxInstances?: number;
+  /** Declared `sleepAfter` value, when a static literal. */
+  sleepAfter?: number | string;
+}
+/**
+* One `ctx.sql` access discovered lexically inside a `query(...)` or
+* `mutation(...)` handler body — the input the `hyperdrive_outside_action` lint
+* consumes. Produced by the codegen feeder, which walks each exported function's
+* handler with ts-morph and records reads of the Hyperdrive `ctx.sql` surface
+* (`ctx.sql(...)`, `ctx.sql.query(...)`).
+*
+* Hyperdrive points at an **external** database Lunora does not own: a `ctx.sql`
+* call is a network round-trip with a mutable result (non-deterministic, like
+* `fetch`) and its writes are invisible to Lunora live queries. It therefore
+* belongs **only** in `action(...)` handlers. Calls inside `action(...)` are
+* intentionally **not** recorded — actions are the escape hatch. Runtime callers
+* don't supply this, so the lint finds nothing there.
+*/
+interface AdvisorHyperdriveCall {
+  /** The accessed `ctx.sql` surface, e.g. `ctx.sql.query` / `ctx.sql`. */
+  callee: string;
+  /** The exported function performing the access (e.g. `listCustomers`). */
+  exportName: string;
+  /** Source file the access appears in (relative to the lunora dir, no extension). */
+  file: string;
+  /** Which procedure kind the access lives in — only `query`/`mutation` are flagged; actions are exempt. */
+  kind: "mutation" | "query";
+  /** 1-based line of the access, or `0` when unknown. */
+  line: number;
+}
+/**
+* Observed read signal over a table — the input the `index_utilization` runtime
+* lint consumes. Produced by the studio backend from each shard's recorded
+* metrics.
+*
+* `AdvisorTableScan` comes straight from the per-`(function, table)` full-scan
+* attribution the runtime already records (`__lunora_metrics_scans`, surfaced as
+* `FunctionCallStat.scannedTables`). Each entry is a table the app read with no
+* index — a hot one points at a missing index.
+*
+* `AdvisorIndexHit` is the per-declared-index hit count. The runtime now records
+* this in the durable `__lunora_metrics_index` table (stamped on every index use
+* via `onIndexUse`) and surfaces it through the `getMetrics` admin RPC; the
+* studio sums the per-shard arrays and feeds them as `context.indexHits`, and the
+* lint flags a declared index with zero recorded reads as dead. When the feed is
+* absent (a static caller, or a shard that recorded nothing) the dead-index half
+* is a no-op and only the hot-scan half runs off the scan attribution.
+*/
+/**
+* Per-table full-scan volume observed over the window — a read that hit no
+* index. Sourced from `FunctionCallStat.scannedTables` aggregated across
+* functions and shards. Runtime callers supply this; static callers don't, so
+* the hot-scan half of the lint finds nothing there.
+*/
+interface AdvisorTableScan {
+  /** Total full-scans of `table` over the observed window. */
+  scans: number;
+  /** The full-scanned table. */
+  table: string;
+}
+/**
+* Per-declared-index hit count observed over the window — how many recorded
+* reads used the index to narrow.
+*
+* Produced by the runtime: every index use (`onIndexUse` in the DO) bumps a
+* per-`(table, index)` counter in the durable `__lunora_metrics_index` table, the
+* complement of the full-*scan* attribution in `__lunora_metrics_scans`. The
+* `getMetrics` admin RPC surfaces it per shard; the studio sums the arrays across
+* shards and passes them as `context.indexHits`. A declared index that appears
+* with `reads: 0` (or is absent entirely after the schema reconciliation) is dead
+* for the window.
+*/
+interface AdvisorIndexHit {
+  /** The declared index name. */
+  index: string;
+  /** Recorded reads that used this index to narrow over the observed window. */
+  reads: number;
+  /** The table the index is declared on. */
+  table: string;
+}
+/**
+* One `ctx.db.insert("table", …)` write discovered in a function body — the
+* write-side analog of `AdvisorQueryRead`, the input the
+* `table_without_insert` lint consumes. Produced by the codegen feeder (which
+* attributes each insert to the exported function performing it); runtime callers
+* don't supply it, so the lint simply finds nothing there.
+*/
+interface AdvisorInsertWrite {
+  /** The exported function performing the insert (e.g. `send`). */
+  exportName: string;
+  /** Source file the insert appears in (relative to the lunora dir, no extension). */
+  file: string;
+  /** 1-based line of the `insert(...)` call, or `0` when unknown. */
+  line: number;
+  /** The inserted table; empty when the `insert(...)` argument is not a string literal. */
+  table: string;
+}
+/**
+* One procedure (query / mutation / action) discovered in the lunora source,
+* reduced to the facts the `mask_uncovered_pii_column` lint needs: whether the
+* procedure's builder chain includes `.use(mask(...))`, which `(table, column)`
+* pairs that mask declares, and which tables the procedure reads or writes.
+* Produced by the codegen feeder; runtime callers don't supply it, so the lint
+* finds nothing there. The column-level twin of `AdvisorRlsProcedure`.
+*/
+interface AdvisorMaskProcedure {
+  /** The exported binding name of the procedure (e.g. `listUsers`). */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /**
+  * The `(table, column)` pairs declared by the `mask(policies)` object passed
+  * to `.use(mask(...))` in this procedure's builder chain. Empty when the
+  * policies argument is not a statically-readable object literal
+  * (conservative: `usesMask` is still `true`).
+  */
+  maskColumns: ReadonlyArray<{
+    column: string;
+    table: string;
+  }>;
+  /** Tables read by the procedure via `ctx.db.query("table")` / `ctx.db.findMany(...)` etc. */
+  tablesRead: ReadonlyArray<string>;
+  /** Tables written by the procedure via `ctx.db.insert("table", …)` / `ctx.db.patch(...)` etc. */
+  tablesWritten: ReadonlyArray<string>;
+  /**
+  * `true` when the procedure's builder chain includes `.use(mask(...))` — the
+  * `mask` callee is identified by name from `@lunora/server`. `false` when no
+  * `.use(mask(...))` is found in the chain (or the procedure uses the bare
+  * `query({...})` factory form, which never carries a builder chain at all).
+  */
+  usesMask: boolean;
+  /** `"internal"` when the procedure uses `internalQuery` / `internalMutation` / `internalAction`. */
+  visibility: "internal" | "public";
+}
+/**
+* One non-deterministic API call discovered lexically inside a `query(...)` or
+* `mutation(...)` handler body — the input the `nondeterministic_query_mutation`
+* lint consumes. Produced by the codegen feeder, which walks each exported
+* function's handler with ts-morph and records calls to `Date.now`,
+* `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues`, and `fetch`.
+* Calls inside `action(...)` handlers are intentionally **not** recorded — actions
+* are the determinism escape hatch. Runtime callers don't supply this, so the
+* lint finds nothing there.
+*/
+interface AdvisorNondeterministicCall {
+  /** The non-deterministic API invoked, e.g. `Date.now` / `Math.random` / `crypto.randomUUID` / `fetch`. */
+  callee: string;
+  /** The exported function performing the call (e.g. `sendMessage`). */
+  exportName: string;
+  /** Source file the call appears in (relative to the lunora dir, no extension). */
+  file: string;
+  /** Which procedure kind the call lives in — only `query`/`mutation` handlers are non-deterministic; actions are exempt. */
+  kind: "mutation" | "query";
+  /** 1-based line of the call, or `0` when unknown. */
+  line: number;
+}
+/**
+* One procedure (query / mutation / action) reduced to the protective middlewares
+* its builder chain installs plus the behavioural facts that decide whether a
+* guard is expected — the input the `public_mutation_without_ratelimit` and
+* `user_creating_mutation_without_captcha` lints consume. A `protectPublic({...})`
+* bundle is unwrapped by the feeder: its keys set `usesRateLimit`/`usesCaptcha`
+* exactly as the standalone `.use(...)` steps would. Produced by the codegen
+* feeder; runtime callers don't supply it, so the lints find nothing there.
+*/
+interface AdvisorProcedureProtection {
+  /** `true` when the handler references `ctx.mail` / `ctx.email` (sends mail). */
+  callsMail: boolean;
+  /** The exported binding name of the procedure (e.g. `signUp`). */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** Registration kind — `query` is read-only; `mutation`/`action` are write-shaped. */
+  kind: "action" | "mutation" | "query";
+  /** `true` when the chain carries `.use(verifyTurnstile(...))` or a `protectPublic({ captcha })` bundle. */
+  usesCaptcha: boolean;
+  /** `true` when the chain carries `.use(mask(...))`. */
+  usesMask: boolean;
+  /** `true` when the chain carries `.use(rateLimit(...))` or a `protectPublic({ rateLimit })` bundle. */
+  usesRateLimit: boolean;
+  /** `true` when the chain carries `.use(rls(...))`. */
+  usesRls: boolean;
+  /** `"internal"` when the procedure uses `internalQuery` / `internalMutation` / `internalAction`. */
+  visibility: "internal" | "public";
+  /** `true` when the handler inserts into a user/session/account-shaped table. */
+  writesUserTable: boolean;
+}
+/**
+* One query read discovered in a function body — the input the
+* `filter_without_index` lint consumes. Produced by the codegen feeder (which
+* parses `ctx.db.query("table")…` chains from the AST); runtime callers don't
+* supply it, so the lint simply finds nothing there.
+*/
+interface AdvisorQueryRead {
+  /** Source file the read appears in (relative to the lunora dir, no extension). */
+  file: string;
+  /** True when the chain calls `.filter(...)`. */
+  hasFilter: boolean;
+  /** True when the chain narrows with `.withIndex(...)` or `.withSearchIndex(...)`. */
+  hasIndex: boolean;
+  /** 1-based line of the `query(...)` call, or `0` when unknown. */
+  line: number;
+  /** The queried table; empty when the `query(...)` argument is not a string literal. */
+  table: string;
+}
+/**
+* One `ctx.r2sql` access discovered lexically inside a `query(...)` or
+* `mutation(...)` handler body — the input the `r2sql_outside_action` lint
+* consumes. Produced by the codegen feeder, which walks each exported function's
+* handler with ts-morph and records reads of the R2 SQL `ctx.r2sql` surface
+* (`ctx.r2sql.query(...)`, `ctx.r2sql.from(...)`, …).
+*
+* R2 SQL queries Apache Iceberg tables over an **external** REST endpoint Lunora
+* does not own (there is no Workers binding): a `ctx.r2sql` call is a network
+* round-trip with a mutable result (non-deterministic, like `fetch`) and its
+* reads are invisible to Lunora live queries. It therefore belongs **only** in
+* `action(...)` handlers. Calls inside `action(...)` are intentionally **not**
+* recorded — actions are the escape hatch. Runtime callers don't supply this, so
+* the lint finds nothing there.
+*/
+interface AdvisorR2sqlCall {
+  /** The accessed `ctx.r2sql` surface, e.g. `ctx.r2sql.query` / `ctx.r2sql.from`. */
+  callee: string;
+  /** The exported function performing the access (e.g. `topPerRegion`). */
+  exportName: string;
+  /** Source file the access appears in (relative to the lunora dir, no extension). */
+  file: string;
+  /** Which procedure kind the access lives in — only `query`/`mutation` are flagged; actions are exempt. */
+  kind: "mutation" | "query";
+  /** 1-based line of the access, or `0` when unknown. */
+  line: number;
+}
+/**
+* One procedure (query / mutation / action) discovered in the lunora source,
+* reduced to the facts the `rls_uncovered_table` lint needs: whether the
+* procedure's builder chain includes `.use(rls(...))`, and which tables the
+* procedure reads or writes. Produced by the codegen feeder; runtime callers
+* don't supply it, so the lint finds nothing there.
+*/
+interface AdvisorRlsProcedure {
+  /** The exported binding name of the procedure (e.g. `listDocuments`). */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /**
+  * Tables explicitly named in the `rls(policies)` array passed to `.use(rls(...))`
+  * in this procedure's builder chain. Empty when the policies argument is not a
+  * statically-readable array literal (conservative: `usesRls` is still `true`).
+  */
+  rlsTables: ReadonlyArray<string>;
+  /** Tables read by the procedure via `ctx.db.query("table")` / `ctx.db.findMany(...)` etc. */
+  tablesRead: ReadonlyArray<string>;
+  /** Tables written by the procedure via `ctx.db.insert("table", …)` / `ctx.db.patch(...)` etc. */
+  tablesWritten: ReadonlyArray<string>;
+  /**
+  * `true` when the procedure's builder chain includes `.use(rls(...))` — the
+  * `rls` callee is identified by name from `@lunora/server`. `false` when no
+  * `.use(rls(...))` is found in the chain (or the procedure uses the bare
+  * `query({...})` factory form, which never carries a builder chain at all).
+  */
+  usesRls: boolean;
+  /** `"internal"` when the procedure uses `internalQuery` / `internalMutation` / `internalAction`. */
+  visibility: "internal" | "public";
+}
+/**
+* Normalized, feeder-agnostic view of a schema that lints run against. Both the
+* runtime `@lunora/server` {@link Schema} (record-shaped) and `@lunora/codegen`'s
+* `SchemaIR` (array-shaped, AST-derived) collapse to this same shape, so a lint
+* is written once and runs in either place. It carries only what the lints
+* read — tables, their columns, indexes, and relations.
+*/
+interface AdvisorSchema {
+  tables: ReadonlyArray<AdvisorTable>;
+}
+/** A table plus the column/index/relation metadata lints inspect. */
+interface AdvisorTable {
+  /**
+  * `true` when the table is written outside Lunora's discoverable insert path
+  * — declared via `.externallyManaged()` (e.g. `@lunora/auth`'s better-auth
+  * tables, `@lunora/ratelimit`'s store). Insert-path lints
+  * (`table_without_insert`) skip such tables. Defaults to `false`.
+  */
+  externallyManaged?: boolean;
+  /**
+  * Declared column names (the `defineTable({...})` keys). Excludes the
+  * framework-managed system fields `_id` / `_creationTime`, which every table
+  * has implicitly — lints that resolve a column treat those as always valid.
+  */
+  fields: ReadonlyArray<string>;
+  /** Every declared index, across all kinds (secondary / search / rank / vector). */
+  indexes: ReadonlyArray<AdvisorIndex>;
+  /** Table name. */
+  name: string;
+  /**
+  * Column names that are optional or nullable and therefore may legally hold
+  * `null` / `undefined` in stored rows. Populated by {@link fromServerSchema}
+  * from the runtime validator graph (`v.optional(...)` → kind `"optional"`;
+  * `.nullable()` → `column.notNull === false`). When absent (e.g. from the
+  * codegen feeder, which does not supply this field), constraint lints that
+  * check NOT NULL should skip the check entirely or treat every field as
+  * required (the codegen feeder never runs runtime lints anyway).
+  */
+  optionalFields?: ReadonlySet<string>;
+  /** Declared relations (`.relations((r) => …)`). */
+  relations: ReadonlyArray<AdvisorRelation>;
+}
+/**
+* One declared index, flattened across Lunora's index kinds so a single lint can
+* reason about every column an index touches. `kind` distinguishes the DSL that
+* declared it — only `index` (a btree secondary index) covers a foreign-key
+* equality lookup, so the FK lint filters on it. `fields` is every column the
+* index references (a secondary index's columns; a search index's text +
+* filter fields; a rank index's sort + partition fields; a vector index's
+* source field). `unique` is set only for unique secondary indexes.
+*/
+interface AdvisorIndex {
+  fields: ReadonlyArray<string>;
+  kind: "index" | "rank" | "search" | "vector";
+  name: string;
+  unique?: boolean;
+}
+/**
+* One declared relation. For a `one` relation the FK column `field` lives on
+* the holding table; for `many` it lives on the target. `name` is the accessor
+* the relation is loaded under.
+*/
+interface AdvisorRelation {
+  field: string;
+  kind: "many" | "one";
+  name: string;
+  onDelete?: "cascade" | "restrict" | "set null";
+  references: string;
+  table: string;
+}
+/**
+* Adapt the runtime `@lunora/server` {@link Schema} into an {@link AdvisorSchema}.
+* Runtime callers (the studio backend, a live shard) hold the real schema
+* object; this collapses its record-keyed `tables`/`relationMap` into the array
+* form lints consume and flattens the per-kind index arrays into one list. The
+* codegen feeder builds the same shape from its AST IR independently (it never
+* imports `@lunora/server`).
+*/
+declare const fromServerSchema: (schema: Schema) => AdvisorSchema;
+/**
+* One secret-shaped string literal discovered in the lunora source — the input
+* the `hardcoded_secret` lint consumes. The full value is never carried; only a
+* redacted {@link AdvisorSecretLiteral.preview}. Produced by the codegen feeder
+* (complementing the pre-commit `vis secrets` scan); runtime callers don't supply
+* it, so the lint finds nothing there.
+*/
+interface AdvisorSecretLiteral {
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** Heuristic that matched, e.g. `stripe_live_key` / `aws_access_key` / `private_key` / `high_entropy`. */
+  kind: string;
+  /** 1-based line of the literal, or `0` when unknown. */
+  line: number;
+  /** Redacted preview (first few chars + length) — never the full secret. */
+  preview: string;
+}
+/**
+* One shard's observed traffic share — the input the `hot_shard` runtime lint
+* consumes. Produced by the studio backend, which fans out over a sharded
+* function's shards and reads each shard's recorded request volume from the
+* durable `__lunora_metrics` accumulator (`SUM(calls)`) — or, equivalently, the
+* per-shard request-log count. Codegen and other static callers don't supply
+* it, so the lint simply finds nothing there.
+*
+* The lint is a pure function over its context, so it can't fan out over shards
+* itself; the caller does the cross-shard read and hands the aggregated
+* distribution here, exactly as the codegen feeder hands `AdvisorQueryRead`s for
+* the static query lints.
+*/
+interface AdvisorShardTraffic {
+  /**
+  * The sharded function group these shards belong to, when the caller scopes
+  * the distribution to one `.shardBy(...)` function. Used only to name the
+  * finding; empty when the traffic is the whole deployment's shard set.
+  */
+  group?: string;
+  /** Total requests (function dispatches) recorded against this shard over the observed window. */
+  requests: number;
+  /**
+  * The shard key (the Durable Object id name) traffic was attributed to —
+  * a user / tenant / room id, depending on the `.shardBy(...)` key. Empty for
+  * the unnamed root DO.
+  */
+  shardKey: string;
+}
+/**
+* One `ctx.sql` tagged-template interpolation that splices an unparameterized
+* string-building expression into the query — the input the `sql_injection_risk`
+* lint consumes. A `${…}` placeholder that simply names a value is bound as a
+* parameter by the Hyperdrive driver and is *not* recorded; only in-place string
+* construction (`"… " + raw`, a nested template literal) reaches here. Produced by
+* the codegen feeder; runtime callers don't supply it, so the lint finds nothing
+* there.
+*/
+interface AdvisorSqlInterpolation {
+  /** The exported binding name of the procedure performing the `ctx.sql` call. */
+  exportName: string;
+  /** Source file relative to the lunora dir, no extension. */
+  file: string;
+  /** 1-based line of the interpolation, or `0` when unknown. */
+  line: number;
+}
+/**
+* A bounded sample of rows from one table, fed into the constraint-validator
+* lint by the studio backend (via `readTablePage`). The cap prevents unbounded
+* scans while still catching obvious violations on small-to-medium tables.
+*
+* The studio notes the cap to the operator when the row count exceeds it
+* (`truncated: true`), so violations on rows beyond the sample window are not
+* silently missed — the finding description mentions the cap.
+*/
+interface AdvisorTableSample {
+  /** The cap applied; equals `rows.length` when not truncated. */
+  readonly cap: number;
+  /**
+  * The row ids of every existing row in this table (bounded to `cap`), used
+  * for FK referential-integrity checks: if a FK value does not appear in the
+  * target table's `existingIds`, it is a dangling reference.
+  */
+  readonly existingIds: ReadonlySet<string>;
+  /** Sampled rows (up to `cap`). Each row includes `_id` and all declared columns. */
+  readonly rows: ReadonlyArray<Record<string, unknown>>;
+  /** The table's name. */
+  readonly table: string;
+  /** Whether more rows exist beyond the cap. */
+  readonly truncated: boolean;
+}
+/**
+* The two workflow-shaped inputs the `workflow_*` lints consume, produced by the
+* codegen feeder. {@link AdvisorWorkflow} is the declaration side (one per
+* `defineWorkflow` export in `lunora/workflows.ts`); {@link AdvisorWorkflowCall}
+* is the use side (one per `ctx.workflows.get("name")` call discovered in a
+* function body). Runtime callers don't supply either, so the workflow lints
+* simply find nothing there.
+*
+* Both are structural subsets of codegen's `WorkflowIR` / `WorkflowCallIR`, so
+* the feeder passes the IR arrays straight through without conversion (mirrors
+* how `AdvisorContainer` tracks `ContainerIR` and `AdvisorInsertWrite` tracks
+* `InsertWriteIR`).
+*/
+/** One workflow declared via a `defineWorkflow()` export in `lunora/workflows.ts`. */
+interface AdvisorWorkflow {
+  /** The `lunora/workflows.ts` export name, e.g. `orderPipeline`. */
+  exportName: string;
+}
+/** One `ctx.workflows.get("name")` call discovered in a function body. */
+interface AdvisorWorkflowCall {
+  /** The exported function performing the call (e.g. `create`). */
+  exportName: string;
+  /** Source file the call appears in (relative to the lunora dir, no extension). */
+  file: string;
+  /** 1-based line of the `get(...)` call, or `0` when unknown. */
+  line: number;
+  /** The referenced workflow export name; empty when the `get(...)` argument is not a string literal. */
+  workflow: string;
+}
+/**
+* Severity of a finding, mirroring splinter's `level`. `ERROR` is a definite
+* problem, `WARN` a likely one, `INFO` an advisory nudge.
+*/
+type Level = "ERROR" | "INFO" | "WARN";
+/**
+* Who the finding concerns, mirroring splinter's `facing`. `EXTERNAL` findings
+* affect clients of the app (performance/security a user can feel); `INTERNAL`
+* ones are operator-only hygiene.
+*/
+type Facing = "EXTERNAL" | "INTERNAL";
+/**
+* Concern bucket a lint belongs to. `SCHEMA` covers shape/correctness nits that
+* are neither a perf nor a security issue (missing primary key, duplicate
+* index). `PERFORMANCE` and `SECURITY` match splinter's two categories.
+*/
+type Category = "PERFORMANCE" | "SCHEMA" | "SECURITY";
+/**
+* Where a lint draws its evidence from.
+*
+* `static` runs against the declared {@link AdvisorSchema} alone (tables,
+* indexes, relations) — deterministic, runnable at codegen/build time, and
+* catches a problem _before_ it ships. This is the edge Lunora has over a
+* live-DB-only advisor like Supabase's.
+*
+* `runtime` needs observed signal from a running shard (full-scan attribution,
+* function call stats). Added in a later slice; the context grows optional
+* fields the runtime lints read.
+*/
+type LintSource = "runtime" | "static";
+/**
+* One emitted advisory, shaped after splinter's lint-view row so the studio
+* Advisors table can render any lint uniformly. `cacheKey` is a stable,
+* content-derived id used to dedup across runs and to let an operator dismiss a
+* specific finding without silencing the whole lint.
+*/
+interface Finding {
+  /** Stable identifier for dedup/dismissal across runs. */
+  cacheKey: string;
+  /** The lint's concern buckets (usually one). */
+  categories: Category[];
+  /** Human-readable explanation of the rule in general terms. */
+  description: string;
+  /** The specific violation message for _this_ occurrence. */
+  detail: string;
+  /** Who the finding concerns. */
+  facing: Facing;
+  /** Severity. */
+  level: Level;
+  /** Structured context (table, field, index, …) for the UI and deep links. */
+  metadata: Record<string, unknown>;
+  /** The lint id that produced this finding, e.g. `unindexed_foreign_key`. */
+  name: string;
+  /** How to fix it — a doc URL or short imperative guidance. */
+  remediation: string;
+  /** Short headline for the finding. */
+  title: string;
+}
+/**
+* Everything a lint may inspect. Static lints read only {@link LintContext.schema};
+* runtime lints will additionally read observed-signal fields added here later.
+*/
+interface LintContext {
+  /**
+  * `httpRoute.&lt;verb>("/admin/…")` routes on admin/privileged-looking paths and
+  * whether each references an auth/admin guard — the `admin_route_without_guard`
+  * input. Supplied by the codegen feeder; absent for runtime callers, where the
+  * lint finds nothing.
+  */
+  adminRoutes?: ReadonlyArray<AdvisorAdminRoute>;
+  /**
+  * Per-public-procedure argument validators that weaken input safety — the
+  * `public_arg_uses_any` (`v.any()` args) and `unbounded_string_arg` (length-less
+  * `v.string()` args) input. Supplied by the codegen feeder for public procedures
+  * only; absent for runtime callers, where the lints find nothing.
+  */
+  argValidators?: ReadonlyArray<AdvisorArgumentValidator>;
+  /**
+  * `ctx.authApi.&lt;method>(...)` calls discovered in function bodies (the
+  * `auth_api_call_without_headers` input). Supplied by the codegen feeder; absent
+  * for runtime callers, where the lint finds nothing.
+  */
+  authApiCalls?: ReadonlyArray<AdvisorAuthApiCall>;
+  /**
+  * Containers declared in `lunora/containers.ts` — the `container_*` lint
+  * input. Supplied by the codegen feeder; absent for runtime callers, where
+  * the container lints find nothing.
+  */
+  containers?: ReadonlyArray<AdvisorContainer>;
+  /**
+  * Hyperdrive `ctx.sql` accesses discovered lexically inside `query`/`mutation`
+  * handler bodies — the `hyperdrive_outside_action` input. Supplied by the
+  * codegen feeder, which omits `action` handlers (where `ctx.sql` is the typed,
+  * intended surface); absent for runtime callers, where the lint finds nothing.
+  */
+  hyperdriveCalls?: ReadonlyArray<AdvisorHyperdriveCall>;
+  /**
+  * Per-declared-index hit counts observed at runtime (the dead-index half of
+  * the `index_utilization` lint input). Supplied by the studio backend, which
+  * sums the per-`(table, index)` reads each shard records in the durable
+  * `__lunora_metrics_index` table and surfaces through the `getMetrics` admin
+  * RPC (see {@link AdvisorIndexHit}). Absent for static callers, where the
+  * dead-index check finds nothing.
+  */
+  indexHits?: ReadonlyArray<AdvisorIndexHit>;
+  /**
+  * Insert writes discovered in function bodies (the `table_without_insert`
+  * input). Supplied by the codegen feeder; absent for runtime callers, where
+  * the write-shaped lints simply find nothing.
+  */
+  inserts?: ReadonlyArray<AdvisorInsertWrite>;
+  /**
+  * Per-procedure column-masking usage discovered in function bodies (the
+  * `mask_uncovered_pii_column` input). Carries whether each procedure's builder
+  * chain includes `.use(mask(...))`, which `(table, column)` pairs its mask
+  * policy declares, and which tables the procedure reads/writes. Supplied by
+  * the codegen feeder; absent for runtime callers, where the lint finds
+  * nothing.
+  */
+  maskProcedures?: ReadonlyArray<AdvisorMaskProcedure>;
+  /**
+  * Non-deterministic API calls (`Date.now`, `Math.random`,
+  * `crypto.randomUUID`, `crypto.getRandomValues`, `fetch`) discovered lexically
+  * inside `query`/`mutation` handler bodies — the `nondeterministic_query_mutation`
+  * input. Supplied by the codegen feeder, which omits `action` handlers (their
+  * non-determinism is intentional); absent for runtime callers, where the lint
+  * finds nothing.
+  */
+  nondeterministicCalls?: ReadonlyArray<AdvisorNondeterministicCall>;
+  /**
+  * Per-procedure protective-middleware snapshots — the
+  * `public_mutation_without_ratelimit` and `user_creating_mutation_without_captcha`
+  * input. Records which `.use(...)` guards (`rateLimit`, captcha, `rls`, `mask`,
+  * the `protectPublic` bundle) each procedure carries and whether it writes a
+  * user table or sends mail. Supplied by the codegen feeder; absent for runtime
+  * callers, where the lints find nothing.
+  */
+  procedureProtections?: ReadonlyArray<AdvisorProcedureProtection>;
+  /**
+  * Query reads discovered in function bodies (the `filter_without_index`
+  * input). Supplied by the codegen feeder; absent for runtime callers, where
+  * the query-shaped lints simply find nothing.
+  */
+  queries?: ReadonlyArray<AdvisorQueryRead>;
+  /**
+  * R2 SQL `ctx.r2sql` accesses discovered lexically inside `query`/`mutation`
+  * handler bodies — the `r2sql_outside_action` input. Supplied by the codegen
+  * feeder, which omits `action` handlers (where `ctx.r2sql` is the typed,
+  * intended surface); absent for runtime callers, where the lint finds nothing.
+  */
+  r2sqlCalls?: ReadonlyArray<AdvisorR2sqlCall>;
+  /**
+  * Per-procedure RLS usage discovered in function bodies (the
+  * `rls_uncovered_table` input). Carries whether each procedure's builder chain
+  * includes `.use(rls(...))`, which tables the procedure reads/writes, and which
+  * tables its RLS policy array names. Supplied by the codegen feeder; absent for
+  * runtime callers, where the lint finds nothing.
+  */
+  rlsProcedures?: ReadonlyArray<AdvisorRlsProcedure>;
+  /** The declared schema under audit, normalized to the feeder-agnostic {@link AdvisorSchema}. */
+  schema: AdvisorSchema;
+  /**
+  * Secret-shaped string literals discovered in the lunora source — the
+  * `hardcoded_secret` input. Each carries only a redacted preview, never the
+  * full value. Supplied by the codegen feeder; absent for runtime callers,
+  * where the lint finds nothing.
+  */
+  secretLiterals?: ReadonlyArray<AdvisorSecretLiteral>;
+  /**
+  * Per-shard observed traffic — the `hot_shard` lint input. Supplied by the
+  * studio backend, which fans out over a sharded function's shards and reads
+  * each shard's recorded request volume from the durable `__lunora_metrics`
+  * accumulator. Absent for static callers, where the lint finds nothing.
+  */
+  shardTraffic?: ReadonlyArray<AdvisorShardTraffic>;
+  /**
+  * `ctx.sql` tagged-template interpolations that splice an unparameterized
+  * string-building expression into the query — the `sql_injection_risk` input.
+  * Supplied by the codegen feeder; absent for runtime callers, where the lint
+  * finds nothing.
+  */
+  sqlInterpolations?: ReadonlyArray<AdvisorSqlInterpolation>;
+  /**
+  * Bounded row samples per table — the `constraint_validator` lint input.
+  * Supplied by the studio backend, which reads up to the configured row cap
+  * from each table via `readTablePage` and assembles the existing-id set for
+  * FK referential-integrity checks. Absent for static callers or codegen
+  * feeders, where the constraint lint simply finds nothing.
+  *
+  * Each entry carries `existingIds` (every `_id` in the sample window) so
+  * FK columns can be cross-checked across tables in O(1) per value. When
+  * `truncated` is `true`, violations on rows beyond the cap are not reported
+  * — the finding description notes the sample cap so the operator understands
+  * the bounded window.
+  */
+  tableSamples?: ReadonlyArray<AdvisorTableSample>;
+  /**
+  * Per-table full-scan volume observed at runtime (the hot-scan half of the
+  * `index_utilization` lint input). Sourced from the per-`(function, table)`
+  * full-scan attribution the runtime records (`__lunora_metrics_scans`,
+  * surfaced as `FunctionCallStat.scannedTables`), aggregated across functions
+  * and shards. Absent for static callers, where the lint finds nothing.
+  */
+  tableScans?: ReadonlyArray<AdvisorTableScan>;
+  /**
+  * `ctx.workflows.get("name")` call sites discovered in function bodies — the
+  * use-side input the `workflow_unused` and `workflow_unknown_target` lints
+  * cross-reference against {@link LintContext.workflows}. Supplied by the
+  * codegen feeder; absent for runtime callers, where the workflow lints find
+  * nothing.
+  */
+  workflowCalls?: ReadonlyArray<AdvisorWorkflowCall>;
+  /**
+  * Workflows declared via `defineWorkflow` exports in `lunora/workflows.ts` —
+  * the declaration-side input for the `workflow_*` lints. Supplied by the
+  * codegen feeder; absent for runtime callers, where the workflow lints find
+  * nothing.
+  */
+  workflows?: ReadonlyArray<AdvisorWorkflow>;
+}
+/**
+* A single advisory rule. `run` is pure over its {@link LintContext} so lints are
+* trivially testable and order-independent. Each rule owns the static metadata
+* (`name`/`title`/…) that its findings inherit, keeping individual `Finding`
+* construction to just the per-occurrence `detail`/`metadata`/`cacheKey`.
+*/
+interface Lint {
+  /** Concern buckets every finding from this lint carries. */
+  categories: Category[];
+  /** General-purpose description shared by every finding. */
+  description: string;
+  /** Default audience for this lint's findings. */
+  facing: Facing;
+  /** Default severity for this lint's findings. */
+  level: Level;
+  /** Unique lint id, snake_case (e.g. `unindexed_foreign_key`). */
+  name: string;
+  /** Fix guidance shared by every finding. */
+  remediation: string;
+  /** Produce zero or more findings for the given context. */
+  run: (context: LintContext) => Finding[];
+  /** Evidence source — see {@link LintSource}. */
+  source: LintSource;
+  /** Short headline shared by every finding. */
+  title: string;
+}
+/**
+* Minimal structural view of the `@lunora/analytics` SQL client — just its
+* `query(sql)` method. Kept structural (not an `import type` from
+* `@lunora/analytics`) so the advisor needn't depend on the analytics package;
+* the real `AnalyticsSqlClient` satisfies it, as does a plain test double.
+*/
+interface AnalyticsMetricsSource {
+  query: (sql: string) => Promise<{
+    rows: ReadonlyArray<Record<string, unknown>>;
+  }>;
+}
+/**
+* The AE event-name + dimension-column contract the runtime writes and this
+* reader reads. `blob1` is the event name; dimensions start at `blob2`.
+*/
+declare const AE_METRIC_EVENTS: {
+  /** `lunora.index.hit` — one row per `(table, index)` use. `blob2`=table, `blob3`=index. */
+  readonly indexHit: {
+    readonly event: "lunora.index.hit";
+    readonly index: "blob3";
+    readonly table: "blob2";
+  };
+  /** `lunora.shard.request` — one row per shard dispatch. `blob2`=shardKey, `blob3`=group. */
+  readonly shardRequest: {
+    readonly event: "lunora.shard.request";
+    readonly group: "blob3";
+    readonly shardKey: "blob2";
+  };
+  /** `lunora.table.scan` — one row per full-scan. `blob2`=table. */
+  readonly tableScan: {
+    readonly event: "lunora.table.scan";
+    readonly table: "blob2";
+  };
+};
+/** Options for the AE-backed runtime-metrics feeder. */
+interface AnalyticsMetricsOptions {
+  /** The AE dataset (the wrangler `analytics_engine_datasets[].dataset`) to read from. */
+  dataset: string;
+  /**
+  * Declared index names per table, used to synthesise the `reads: 0` rows the
+  * `index_utilization` dead-index half needs. AE only stores rows for indexes
+  * that were *used*, so a never-hit index has no AE row at all; supplying the
+  * declared set lets the reader emit an explicit `reads: 0` entry for any
+  * declared index absent from the AE hit feed. Omit it to report only the
+  * positive hit counts AE returns.
+  */
+  declaredIndexes?: ReadonlyArray<{
+    index: string;
+    table: string;
+  }>;
+  /**
+  * Restrict the shard-traffic read to one sharded-function group (`blob3`).
+  * Omit to read the whole deployment's shard set.
+  */
+  group?: string;
+}
+/** The runtime-lint input arrays this module reconstructs from AE. */
+interface AnalyticsRuntimeMetrics {
+  indexHits: AdvisorIndexHit[];
+  shardTraffic: AdvisorShardTraffic[];
+  tableScans: AdvisorTableScan[];
+}
+/**
+* Reconstruct the runtime-lint input arrays (`shardTraffic` / `tableScans` /
+* `indexHits`) from the Analytics Engine SQL API. The three reads run
+* concurrently; each degrades to an empty array on a query failure, so a
+* partially-misconfigured read path still returns what it can.
+*
+* Feed the result into a {@link LintContext} alongside the declared schema:
+*
+* ```ts
+* const metrics = await loadAnalyticsRuntimeMetrics(client, { dataset: "ANALYTICS" });
+* runAdvisor({ schema, ...metrics }, { source: "runtime" });
+* ```
+*/
+declare const loadAnalyticsRuntimeMetrics: (source: AnalyticsMetricsSource, options: AnalyticsMetricsOptions) => Promise<AnalyticsRuntimeMetrics>;
+/**
+* Constraint validator — flag rows that violate declared FK / NOT NULL / UNIQUE
+* constraints by cross-checking sampled row data against the schema.
+*
+* This lint reads the `context.tableSamples` feed (bounded row samples supplied
+* by the studio backend via `readTablePage`) and the declared schema. Three
+* families of check run over each sample:
+*
+* FK referential integrity: for every `one` relation the holding table declares,
+* check that each sampled row's FK column value appears in the target table's
+* sampled id set. A dangling value means no target row exists for the reference.
+*
+* NOT NULL / non-optional columns: the lint surfaces rows with null/undefined in
+* declared fields — inserted before a column was added or via raw import.
+*
+* UNIQUE index violations: for each declared unique secondary index, check the
+* sampled rows for duplicate values across the index's columns.
+*
+* All checks are bounded by the cap in each sample; the lint never triggers an
+* additional read. When a sample is truncated, findings note the caveat.
+*/
+declare const constraintValidator: Lint;
+/**
+* `hot_shard` — flag a shard whose request share is disproportionately high.
+*
+* Sharding (`.shardBy(key)`) spreads state and load across many Durable Objects
+* by user / tenant / room. Its whole value is *even* distribution: when one
+* shard absorbs a dominant fraction of traffic, that single DO becomes the
+* bottleneck (one request stream, one SQLite, one WS fan-out) while its siblings
+* idle — the hot-key skew sharding is meant to avoid. That usually means the
+* shard key has too little cardinality, or one entity is unusually busy and
+* needs its own split.
+*
+* The per-shard request volume comes from the runtime feeder
+* (`context.shardTraffic`): the studio backend fans out over the function's
+* shards and reads each shard's recorded `__lunora_metrics` call total. The lint
+* is pure over that distribution, so it only fires once the window has more than
+* one shard and enough total requests (`MIN_TOTAL_REQUESTS`) for the proportion
+* to be trustworthy.
+*/
+declare const hotShard: Lint;
+/**
+* `index_utilization` — flag indexes the workload doesn't pay for. Two
+* complementary checks over recorded reads.
+*
+* Dead index — a declared index that recorded reads never used. An unused index
+* is pure overhead: every write maintains it, every byte of storage holds it,
+* and nothing reads through it. Fired off the per-index hit feed
+* (`context.indexHits`); a declared index whose recorded `reads` is `0` is dead.
+* The runtime records this in the durable `__lunora_metrics_index` table (every
+* index use stamps a per-`(table, index)` counter via `onIndexUse`) and surfaces
+* it through the `getMetrics` admin RPC; the studio sums the per-shard arrays
+* into `context.indexHits` (see `AdvisorIndexHit`). The counter is cumulative and
+* never decays, so a non-zero index never reverts to "dead" — `reads: 0` means
+* the index has not been used once since the counter was created.
+*
+* Hot unindexed scan — a table read hot with no index at all. Fired off the
+* full-scan attribution the runtime does record (`context.tableScans`, sourced
+* from `__lunora_metrics_scans` / `FunctionCallStat.scannedTables`): a table
+* whose scan count clears `HOT_SCAN_THRESHOLD` is one the app keeps
+* full-scanning, the runtime-confirmed counterpart to the static
+* `filter_without_index` advisory.
+*/
+declare const indexUtilization: Lint;
+/**
+* Flags an `httpRoute` on an admin/privileged-looking path whose handler shows no
+* auth/admin guard.
+*
+* REST routes (unlike queries/mutations) aren't covered by RLS — they run whatever
+* the handler does, so an `/admin/*` (or `/internal/*`, `/_*`) route with no
+* session/admin check is an open privilege door: anyone who can reach the URL can
+* invoke it. The handler must assert an authenticated, authorized caller
+* (`ctx.auth` / `getSession` / a `requireAdmin`-style guard) before doing
+* privileged work.
+*
+* Detection is heuristic: the feeder records whether the handler body references
+* any known guard token. Runs only when the codegen feeder supplies route evidence
+* (`context.adminRoutes`); a runtime caller flags nothing.
+*/
+declare const adminRouteWithoutGuard: Lint;
+/**
+* Flags a `ctx.authApi.&lt;method>(...)` call whose argument object omits `headers`.
+*
+* `@lunora/auth`'s `withAuthPlugins` middleware attaches the full privileged
+* better-auth API to `ctx.authApi` — `banUser`, `setRole`, impersonation,
+* `createOrganization`, `removeMember`, etc. better-auth authorizes these calls
+* from the caller's session carried in the `headers` you pass. Called
+* **without** `headers`, better-auth treats the invocation as a trusted
+* server-to-server call and **skips session authorization entirely**. So a
+* header-less `ctx.authApi.banUser({ body })` runs with full privileges
+* regardless of who the caller is — an authorization bypass.
+*
+* This lint runs when the codegen feeder has supplied call evidence
+* (`context.authApiCalls` present); a runtime caller with no evidence flags
+* nothing rather than raising false alarms.
+*/
+declare const authApiCallWithoutHeaders: Lint;
+/**
+* Detect FK cycles in the declared relation graph via a DFS.
+*
+* A "circular FK" exists when a chain of `one` relations forms a loop — for
+* example `A.authorId → B`, `B.ownerId → C`, `C.postId → A`. Such cycles can
+* cause unexpected behavior during DELETE operations: a CASCADE chain may loop
+* forever (or deadlock), and even a RESTRICT cycle prevents deletion of any row
+* in the loop without temporarily disabling constraints.
+*
+* Only `one` relations are followed because they are the side that owns the FK
+* column (the `field` lives on the holding table). `many` relations point back
+* to the same edge from the opposite side and would cause every edge to be
+* double-counted; skipping them gives the correct directed graph.
+*
+* A single-table self-reference (`A.parentId → A`) is **not** reported: a
+* self-referential FK is the canonical, intentional shape for trees/hierarchies
+* (categories, org charts, threaded comments), so flagging every such schema
+* would be noise. Only multi-table cycles — the ones the description illustrates
+* — are surfaced.
+*
+* Each unique cycle is reported once: the cycle path is canonicalized to its
+* lexicographically smallest rotation so two DFS traversals that enter the same
+* ring at different nodes emit the same cacheKey and detail. A representative
+* cycle is reported for each distinct simple cycle in the graph; overlapping or
+* chord cycles that share interior nodes are each detected independently.
+*/
+declare const circularFk: Lint;
+/**
+* Flags a container declared on a large instance type. The big `standard-3` /
+* `standard-4` sizes (and large custom shapes) are billed on their provisioned
+* memory + disk for the whole time an instance runs, so an over-provisioned
+* container is a standing cost. Informational — a real workload may need it —
+* but worth surfacing so the choice is deliberate.
+*/
+declare const containerOversizedInstance: Lint;
+/**
+* Flags a container that leaves outbound internet access at the platform
+* default (`enableInternet: true`). Egress is billed per GB and an open
+* outbound path widens the attack surface, so a container that doesn't call
+* external services should set `enableInternet: false` explicitly. We can't
+* tell from config whether egress is actually used, so this is an INFO nudge to
+* make the choice deliberate, not an error.
+*
+* Only fires when the field was omitted (or a non-literal we couldn't read) —
+* an explicit `enableInternet: true` is treated as a deliberate opt-in and left
+* alone.
+*/
+declare const containerPublicInternet: Lint;
+/**
+* Lunora port of splinter's `0009_duplicate_index`.
+*
+* A btree secondary index is redundant when another index already serves every
+* lookup it does — i.e. its columns are a leading prefix of the other's
+* (SQLite's leftmost-prefix rule means `["a", "b"]` already covers `["a"]`).
+* Exact duplicates are the degenerate case. A redundant index is pure overhead:
+* extra storage and a write amplified on every insert/update/delete.
+*
+* Only `kind: "index"` participates — search/rank/vector indexes are distinct
+* structures, never redundant with a btree. A `unique` index is never reported
+* as redundant even when its columns are a prefix: it enforces a constraint the
+* covering index does not, so dropping it would change behavior.
+*/
+declare const duplicateIndex: Lint;
+/**
+* Flags a secondary index declared with no columns (`.index("x", [])`). The
+* `.index(name, fields)` builder types `fields` as `string[]`, not
+* `keyof Shape[]`, so an empty array slips past the compiler — but an index over
+* zero columns indexes nothing and can never narrow a read. Almost always a
+* leftover from a refactor. (Search / rank / vector indexes always carry at
+* least one field by construction, so only `kind: "index"` is checked.)
+*/
+declare const emptyIndex: Lint;
+/**
+* Flags a query read that calls `.filter()` without first narrowing with
+* `.withIndex()` / `.withSearchIndex()`. Such a read loads *every* row of the
+* table and applies the predicate in memory — a full table scan that degrades
+* linearly as the table grows. The healthy pattern is `.withIndex(...)` to
+* narrow, then `.filter(...)` only for predicates the index can't express
+* (which is why an indexed read with a trailing `.filter()` is NOT flagged).
+*
+* The query reads come from the codegen feeder, which parses
+* `ctx.db.query("table")…` chains out of function bodies. Runtime callers supply
+* no `queries`, so this lint is a no-op there.
+*/
+declare const filterWithoutIndex: Lint;
+/**
+* Flags a secret-shaped string literal checked into the lunora source.
+*
+* A live API key, access key, private key, or high-entropy token committed to the
+* codebase leaks the moment the repo is cloned, forked, or its history is read —
+* and rotating it means a redeploy. Secrets belong in `.dev.vars` locally and
+* `wrangler secret put` in production, read at runtime via `env`. This lint
+* surfaces the same class of finding the pre-commit `vis secrets` gate catches,
+* inside the studio Advisors table.
+*
+* Runs only when the codegen feeder supplies secret evidence
+* (`context.secretLiterals`); a runtime caller flags nothing. One finding per
+* literal.
+*/
+declare const hardcodedSecret: Lint;
+/**
+* Flags a Hyperdrive `ctx.sql` access inside a `query(...)` or `mutation(...)`
+* handler body.
+*
+* Hyperdrive (`@lunora/hyperdrive`) points at an **external** Postgres/MySQL
+* database Lunora does not own. A `ctx.sql` query is a network round-trip with a
+* mutable result — non-deterministic, exactly like `fetch` — so it breaks the
+* determinism the coordinator relies on when it re-runs a query on subscription
+* re-evaluation or a mutation on OCC retry. Worse, external writes are invisible
+* to the DO/SQLite change-feed, so a subscription will never re-fire on them.
+* `ctx.sql` is therefore wired onto `ActionCtx` **only** and belongs exclusively
+* in `action(...)` handlers; using it in a query/mutation is the same class of
+* bug as `fetch`/`Date.now`.
+*
+* This is the enforcement teeth behind the action-only rule — runtime
+* enforcement is still absent (see `MEMORY.md` "Query/mutation determinism not
+* enforced"), so the lint is the guardrail.
+*
+* This lint runs when the codegen feeder has supplied access evidence
+* (`context.hyperdriveCalls` present); a runtime caller with no evidence flags
+* nothing rather than raising false alarms. The feeder records accesses only
+* inside `query`/`mutation` handlers, so `action(...)` bodies never reach here.
+*/
+declare const hyperdriveOutsideAction: Lint;
+/**
+* A correctness lint with no splinter analogue — it exploits Lunora's static
+* edge: the schema is fully declared, so a typo'd index column is catchable at
+* codegen time rather than surfacing as a runtime error or a silently
+* never-matching index.
+*
+* Every index (secondary / search / rank / vector) names the columns it covers;
+* each must be a declared column of the table (or a system field). A reference
+* to an unknown column is almost always a typo or a column that was renamed
+* without updating the index.
+*/
+declare const indexReferencesUnknownField: Lint;
+/**
+* Flags a public procedure that reads a table for which at least one other
+* procedure declares a column mask (evidence the developer decided that table
+* carries sensitive columns), but whose own builder chain does NOT include
+* `.use(mask(...))`.
+*
+* Lunora masking is **opt-in per procedure**: a `mask(policies)` object only
+* redacts columns inside procedures whose builder chain includes
+* `.use(mask(policies))`. A procedure without it returns the raw column value —
+* even when another procedure in the same app declares that column maskable.
+* This is the "one procedure masks `users.email`, another leaks it" failure
+* mode, the column-level sibling of `rls_uncovered_table`.
+*
+* **Granularity**: the lint is table-granular, not column-precise. Statically
+* proving that a procedure *returns* a specific masked column would need
+* return-shape analysis that is infeasible over the IR; instead the lint flags a
+* public procedure that *reads* a mask-covered table without any
+* `.use(mask(...))` of its own, and the finding lists the masked columns the
+* developer flagged elsewhere. Only reads are considered — masking is a
+* read/return-path concern, so writes never trigger it.
+*
+* **Scope**: only `public` procedures are flagged. `internal*` procedures
+* (e.g. `internalQuery`, `internalMutation`) intentionally bypass masking, so
+* flagging them would produce only noise. Remediation text notes this exemption.
+*
+* **Evidence supply**: this lint runs only when the codegen feeder has supplied
+* `context.maskProcedures`; a runtime caller with no evidence flags nothing
+* rather than raising false alarms.
+*
+* **Conservative policy detection**: when a procedure calls `mask(policies)`
+* with a non-literal object (a variable reference), the feeder cannot statically
+* enumerate the masked `(table, column)` pairs. In that case the procedure is
+* still marked `usesMask: true` (so it is NOT itself flagged), but its pairs
+* contribute nothing to the masked-column map. The lint may under-report (false
+* negatives) when policies are extracted into named constants, but never
+* over-reports (no false positives).
+*/
+declare const maskUncoveredPiiColumn: Lint;
+/**
+* Flags a non-deterministic API call inside a `query(...)` or `mutation(...)`
+* handler body.
+*
+* Lunora queries and mutations must be **deterministic**: the coordinator may
+* re-run a mutation on optimistic-concurrency (OCC) retry and a query on
+* subscription re-evaluation, so a handler that reads wall-clock time, draws
+* randomness, or hits the network can produce different results on each run —
+* breaking read-your-writes, cache invalidation, and replayable history.
+* `Date.now`, `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues`, and
+* `fetch` are therefore disallowed in query/mutation handlers and belong in an
+* `action(...)`, which runs exactly once and may use ambient/non-deterministic
+* APIs freely (pass the result into a mutation as an argument).
+*
+* This lint runs when the codegen feeder has supplied call evidence
+* (`context.nondeterministicCalls` present); a runtime caller with no evidence
+* flags nothing rather than raising false alarms. The feeder records calls only
+* inside `query`/`mutation` handlers, so `action(...)` bodies never reach here.
+*/
+declare const nondeterministicQueryMutation: Lint;
+/**
+* Flags an RLS policy whose `table` names a table that does not exist in the
+* schema.
+*
+* A policy is bound to a table by a plain string (`definePolicy({ table:
+* "documents", … })`). The `rls()` middleware only applies a policy to reads and
+* writes of that exact table name — so a typo, a stale name after a rename, or a
+* copy-paste mistake produces a policy that silently matches **nothing**. The
+* table the developer believes is gated is left completely ungated, which is a
+* security gap, not a mere dead-code wart: every read of the real table returns
+* unrestricted rows and every write is allowed.
+*
+* This is strictly worse than `rls_uncovered_table` (a procedure forgetting the
+* middleware): here the middleware *is* wired up, the policy *is* in the list,
+* and it still does nothing — the failure is invisible at every call site.
+*
+* **Evidence supply**: like `rls_uncovered_table`, this runs only when the
+* codegen feeder supplies `context.rlsProcedures`. The covered-table names come
+* from each procedure's statically-read `rls(policies)` array (`rlsTables`); a
+* policies argument that isn't a literal array contributes no names, so the lint
+* under-reports rather than raising false alarms.
+*/
+declare const policyReferencesUnknownTable: Lint;
+/**
+* Flags a `v.any()` argument on a public procedure.
+*
+* `v.any()` disables validation: the field accepts arbitrary, untyped,
+* arbitrarily-large input straight from an untrusted client. That defeats the
+* end-to-end type safety Lunora exists to provide and opens the door to injection,
+* prototype pollution, and oversized-payload abuse. Public input should be a
+* precise validator (`v.object`, `v.string`, `v.union`, …).
+*
+* Runs only when the codegen feeder supplies arg evidence
+* (`context.argValidators`, public procedures only); a runtime caller flags
+* nothing. One finding per offending arg.
+*/
+declare const publicArgumentUsesAny: Lint;
+/**
+* Flags a public `mutation`/`action` whose builder chain installs no rate limit.
+*
+* Every publicly-callable write is a flood target: without a `rateLimit`
+* middleware a single client can hammer it to exhaust D1 writes, send-mail quota,
+* or paid credits, and brute-force auth-shaped endpoints (login / reset / OTP).
+* Lunora ships `rateLimit()` (`@lunora/ratelimit`) and the `protectPublic({...})`
+* bundle for exactly this; this lint fires when neither is present on a public
+* write.
+*
+* Runs only when the codegen feeder supplies protection evidence
+* (`context.procedureProtections`); a runtime caller with no evidence flags
+* nothing. `query` is read-only and excluded; internal functions are
+* server-called and excluded.
+*/
+declare const publicMutationWithoutRatelimit: Lint;
+/**
+* Flags an R2 SQL `ctx.r2sql` access inside a `query(...)` or `mutation(...)`
+* handler body.
+*
+* R2 SQL (`@lunora/r2sql`) queries Apache Iceberg tables over an **external**
+* REST endpoint Lunora does not own — there is no Workers binding, every query
+* is an HTTPS round-trip. A `ctx.r2sql` query is therefore non-deterministic
+* (exactly like `fetch`), which breaks the determinism the coordinator relies on
+* when it re-runs a query on subscription re-evaluation or a mutation on OCC
+* retry. And R2 SQL reads are invisible to the DO/SQLite change-feed, so a
+* subscription will never re-fire on them. `ctx.r2sql` is therefore wired onto
+* `ActionCtx` **only** and belongs exclusively in `action(...)` handlers; using
+* it in a query/mutation is the same class of bug as `fetch`/`Date.now`.
+*
+* This mirrors `hyperdrive_outside_action` — the action-only enforcement teeth
+* for external, non-reactive I/O. Runtime enforcement is still absent (see
+* `MEMORY.md` "Query/mutation determinism not enforced"), so the lint is the
+* guardrail.
+*
+* This lint runs when the codegen feeder has supplied access evidence
+* (`context.r2sqlCalls` present); a runtime caller with no evidence flags nothing
+* rather than raising false alarms. The feeder records accesses only inside
+* `query`/`mutation` handlers, so `action(...)` bodies never reach here.
+*/
+declare const r2sqlOutsideAction: Lint;
+/**
+* A correctness lint covering the columns a relation wires together: the FK
+* `field` and the `references` column must each exist on their respective
+* tables, or the join can never resolve. Caught here at codegen time rather
+* than as a runtime failure.
+*/
+declare const relationReferencesUnknownField: Lint;
+/**
+* A correctness lint: every relation declared via `.relations((r) => …)` names a
+* target table, which must exist in the schema. A target that resolves to no
+* table is a typo or a reference to a table that was removed/renamed — the
+* relation can never load. Caught here at codegen time rather than at runtime.
+*
+* (Extension tables are already namespaced and their relation targets rewritten
+* by the time the schema reaches a lint, so a surviving unknown target is a real
+* miss, not an unresolved cross-package reference.)
+*/
+declare const relationReferencesUnknownTable: Lint;
+/**
+* Flags a public procedure that reads or writes a table named in at least one
+* other procedure's `rls(policies)` list, but whose own builder chain does NOT
+* include `.use(rls(...))`.
+*
+* Lunora RLS is **opt-in per procedure**: a policy list only takes effect
+* inside procedures whose builder chain includes `.use(rls(policies))`. A
+* procedure without it sees the raw, unwrapped `ctx.db` and silently bypasses
+* every policy in the list — even when another procedure in the same app
+* declares that table as policy-gated.
+*
+* The lint surfaces the most dangerous subclass of this failure mode: a table
+* that the developer explicitly decided to gate with RLS (evidenced by naming
+* it in at least one procedure's policy list) is nonetheless accessible
+* without restriction from a procedure that forgot the `.use(rls(...))` call.
+*
+* **Scope**: only `public` procedures are flagged. `internal*` procedures
+* (e.g. `internalQuery`, `internalMutation`) are intentional server-side
+* helpers that legitimately bypass the user-facing RLS gate, so flagging them
+* would produce only noise. Remediation text notes this exemption so authors
+* know to use `internalQuery`/`internalMutation`/`internalAction` when they
+* truly need unwrapped access.
+*
+* **Evidence supply**: this lint runs only when the codegen feeder has supplied
+* `context.rlsProcedures`; a runtime caller with no evidence flags nothing
+* rather than raising false alarms.
+*
+* **Conservative policy-table detection**: when a procedure calls
+* `rls(policies)` with a non-literal array (a variable reference), the feeder
+* cannot statically enumerate the covered tables. In that case the procedure is
+* still marked `usesRls: true` (so it is NOT itself flagged), but its tables
+* contribute nothing to `policyCoveredTables`. This means the lint may
+* under-report (false negatives) when policies are extracted into named
+* constants, but it never over-reports (no false positives).
+*/
+declare const rlsUncoveredTable: Lint;
+/**
+* Flags a `ctx.sql` tagged-template that splices an unparameterized
+* string-building expression into the query.
+*
+* The Hyperdrive `ctx.sql\`…\`` driver binds each `${value}` placeholder as a
+* query parameter — safe by construction. But a placeholder that *builds* a string
+* in place (`ctx.sql\`… ${"WHERE name='" + name + "'"}\``, or a nested template
+* literal) splices raw, attacker-controlled text into the SQL, reopening classic
+* SQL injection. The fix is always to pass the value through a placeholder so the
+* driver parameterizes it.
+*
+* Runs only when the codegen feeder supplies interpolation evidence
+* (`context.sqlInterpolations`); a runtime caller flags nothing. One finding per
+* interpolation.
+*/
+declare const sqlInjectionRisk: Lint;
+/**
+* Flags a declared table that no function inserts into.
+*
+* Using `@lunora/codegen`'s write-side discovery (the analog of the read
+* discovery that feeds `filter_without_index`), this lint cross-references every
+* schema table against the set of tables some exported function writes via
+* `ctx.db.insert("&lt;table>", …)`. A table with no such write either is dead schema
+* or is populated through a path the static analysis can't see — a migration/seed,
+* cross-region replication, the `ctx.orm.insert(...)` builder, or a trusted
+* snapshot import. Hence `INFO`/`INTERNAL`: a nudge to confirm intent, not an error.
+*
+* A table declared `.externallyManaged()` is skipped — that flag is the explicit
+* acknowledgement that its rows are written outside Lunora (an adapter/migration/
+* middleware), so `@lunora/auth`'s better-auth tables and `@lunora/ratelimit`'s
+* store never flag here.
+*
+* Only runs when the write feeder supplied evidence (`context.inserts` present);
+* a runtime caller with no insert signal flags nothing rather than every table.
+*/
+declare const tableWithoutInsert: Lint;
+/**
+* Flags a public `v.string()` argument with no length bound.
+*
+* A string field that accepts an unbounded value lets a client send megabytes of
+* text per request — inflating storage, blowing the row/document size budget, and
+* driving CPU/memory on every handler that processes it. A `.check()`/`.meta()`
+* max-length bound caps the blast radius. Advisory (INFO): a deliberately-open
+* free-text field is sometimes legitimate, so this nudges rather than blocks.
+*
+* Runs only when the codegen feeder supplies arg evidence
+* (`context.argValidators`, public procedures only); a runtime caller flags
+* nothing. One finding per offending arg.
+*/
+declare const unboundedStringArgument: Lint;
+/**
+* Lunora port of splinter's `0001_unindexed_foreign_keys`.
+*
+* A `one` (many-to-one) relation declares a foreign-key column (`relation.field`)
+* on the holder table pointing at the target's `references` column. If no index
+* leads with that column, every read that filters or joins on the FK degrades to
+* a full table scan — the canonical silent performance cliff as a table grows.
+*
+* Coverage follows SQLite's leftmost-prefix rule: a composite index
+* `["authorId", "createdAt"]` covers lookups on `authorId`, so the FK is
+* satisfied when it is the *leading* column of any declared index. `many`
+* relations are skipped here — their FK lives on the opposite table and is
+* caught when that table's own `one` side is audited.
+*/
+declare const unindexedForeignKey: Lint;
+/**
+* The to-many counterpart of `unindexed_foreign_key`.
+*
+* A `many` relation declares its foreign-key column (`relation.field`) on the
+* target table — `users.posts = r.many("posts", { field: "authorId" })` puts
+* `authorId` on `posts`. A relation predicate over that relation (`{ posts: {
+* some|none|every: W } }` in a `where`/RLS policy) and a `with:` child load both
+* resolve by querying the target table on that FK column, so an unindexed FK
+* there is the same silent full-scan cliff `unindexed_foreign_key` warns about —
+* just on the other side of the relation.
+*
+* `unindexed_foreign_key` only audits a table's own `one` relations, so it
+* catches this column **only when the target table declares the inverse `one`
+* relation** (`posts.author = r.one("users", { field: "authorId" })`). A
+* one-directional `many` (declared on the parent, with no inverse `one` on the
+* child) slips through — that exact gap is this lint's job. To stay strictly
+* complementary it skips any FK the target already covers via its own `one`
+* relation (reported there) and only fires on the otherwise-unaudited column.
+*/
+declare const unindexedRelationTarget: Lint;
+/**
+* Flags a public `mutation`/`action` that creates a user/session or sends mail but
+* installs no CAPTCHA / bot check.
+*
+* Endpoints that mint accounts or trigger emails are the classic automated-abuse
+* surface: credential-stuffing sign-ups, mailbox-flooding "forgot password" loops,
+* and disposable-account farming. A server-verified human check (Turnstile) in
+* front of them is the defense. Lunora ships `verifyTurnstile()` (`@lunora/auth`)
+* and the `protectPublic({ captcha })` bundle; this lint fires when a public
+* procedure writes a user/session/account-shaped table (or references `ctx.mail`)
+* with no captcha middleware.
+*
+* Runs only when the codegen feeder supplies protection evidence
+* (`context.procedureProtections`); a runtime caller with no evidence flags
+* nothing.
+*/
+declare const userCreatingMutationWithoutCaptcha: Lint;
+/**
+* A correctness lint: every `ctx.workflows.get("name")` call must reference a
+* workflow that exists — i.e. a `defineWorkflow` export in `lunora/workflows.ts`.
+* A `.get("x")` whose `"x"` resolves to no declared workflow is a typo or a
+* reference to a workflow that was removed/renamed; codegen wires the typed
+* `ctx.workflows` accessor off the declared set, so the call throws at runtime.
+* Caught here at codegen time instead.
+*
+* Calls with a non-literal name (`workflow === ""`) are skipped — they can't be
+* statically resolved, so they're neither confirmed-unknown here nor counted as
+* a typo. Only runs when both feeders supplied evidence (declared workflows and
+* discovered calls); a runtime caller flags nothing.
+*/
+declare const workflowUnknownTarget: Lint;
+/**
+* Flags a declared workflow that nothing starts.
+*
+* Cross-references every `defineWorkflow` export against the set of workflow
+* names some function references via `ctx.workflows.get("&lt;name>")`. A workflow
+* with no such call is either dead code (declared, deployed as a billable
+* `WorkflowEntrypoint`, never triggered) or is started through a path the static
+* analysis can't see — the Cloudflare REST API, a `wrangler` invocation, or a
+* cross-service binding. Hence `INFO`/`INTERNAL`: a nudge to confirm intent.
+*
+* Suppressed entirely when any call uses a non-literal name
+* (`ctx.workflows.get(someVariable)`), because a dynamic dispatch could target
+* any declared workflow — flagging "unused" workflows then would be a false
+* positive. Only runs when the declaration feeder supplied evidence
+* (`context.workflows` present); a runtime caller flags nothing.
+*/
+declare const workflowUnused: Lint;
+/**
+* Every lint that runs against the declared schema (and, for
+* `filter_without_index`, the discovered query reads) — no running shard
+* required. Correctness lints (`*_unknown_*`, `empty_index`) come first so a
+* broken schema's errors surface above the performance advisories.
+*/
+declare const STATIC_LINTS: ReadonlyArray<Lint>;
+/**
+* Every lint that needs observed runtime signal (recorded metrics) rather than
+* just the declared schema. They read the feeder-supplied
+* {@link LintContext.shardTraffic} / {@link LintContext.tableScans} /
+* {@link LintContext.indexHits}; absent that signal (a static caller) each is a
+* no-op. Run them with `runAdvisor(ctx, { source: "runtime" })` against a live
+* deployment's aggregated metrics.
+*/
+declare const RUNTIME_LINTS: ReadonlyArray<Lint>;
+/** The default lint set: the static lints, then the runtime lints. A caller filters by `source` to run one tier. */
+declare const ALL_LINTS: ReadonlyArray<Lint>;
+/** Options for {@link runAdvisor}. */
+interface RunAdvisorOptions {
+  /** Lints to run (default: {@link ALL_LINTS}). */
+  lints?: ReadonlyArray<Lint>;
+  /** Restrict to a single evidence source — e.g. `"static"` at codegen time. */
+  source?: LintSource;
+}
+/**
+* Run lints against a context and return their findings in lint-declaration
+* order. Filtering by {@link RunAdvisorOptions.source} lets a caller run only
+* `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 AdvisorArgumentValidator, type AdvisorAuthApiCall, type AdvisorContainer, type AdvisorHyperdriveCall, type AdvisorIndex, type AdvisorIndexHit, type AdvisorInsertWrite, type AdvisorMaskProcedure, type AdvisorNondeterministicCall, type AdvisorProcedureProtection, type AdvisorQueryRead, type AdvisorR2sqlCall, type AdvisorRelation, type AdvisorRlsProcedure, type AdvisorSchema, type AdvisorSecretLiteral, type AdvisorShardTraffic, type AdvisorSqlInterpolation, type AdvisorTable, type AdvisorTableSample, type AdvisorTableScan, type AdvisorWorkflow, type AdvisorWorkflowCall, 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, adminRouteWithoutGuard, authApiCallWithoutHeaders, circularFk, constraintValidator, containerOversizedInstance, containerPublicInternet, duplicateIndex, emptyIndex, filterWithoutIndex, fromServerSchema, hardcodedSecret, hotShard, hyperdriveOutsideAction, indexReferencesUnknownField, indexUtilization, loadAnalyticsRuntimeMetrics, maskUncoveredPiiColumn, nondeterministicQueryMutation, policyReferencesUnknownTable, publicArgumentUsesAny, publicMutationWithoutRatelimit, r2sqlOutsideAction, relationReferencesUnknownField, relationReferencesUnknownTable, rlsUncoveredTable, runAdvisor, sqlInjectionRisk, tableWithoutInsert, unboundedStringArgument, unindexedForeignKey, unindexedRelationTarget, userCreatingMutationWithoutCaptcha, workflowUnknownTarget, workflowUnused };