@lunora/advisor 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/index.d.mts

@@ -285,6 +285,33 @@ interface AdvisorQueryRead {
   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
@@ -657,6 +684,13 @@ interface LintContext {
   */
   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
@@ -1172,6 +1206,31 @@ declare const publicArgumentUsesAny: Lint;
 */
 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
@@ -1389,4 +1448,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 AdvisorArgumentValidator, type AdvisorAuthApiCall, type AdvisorContainer, type AdvisorHyperdriveCall, type AdvisorIndex, type AdvisorIndexHit, type AdvisorInsertWrite, type AdvisorMaskProcedure, type AdvisorNondeterministicCall, type AdvisorProcedureProtection, type AdvisorQueryRead, 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, relationReferencesUnknownField, relationReferencesUnknownTable, rlsUncoveredTable, runAdvisor, sqlInjectionRisk, tableWithoutInsert, unboundedStringArgument, unindexedForeignKey, unindexedRelationTarget, userCreatingMutationWithoutCaptcha, workflowUnknownTarget, workflowUnused };
+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 };

package/dist/index.d.ts

@@ -285,6 +285,33 @@ interface AdvisorQueryRead {
   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
@@ -657,6 +684,13 @@ interface LintContext {
   */
   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
@@ -1172,6 +1206,31 @@ declare const publicArgumentUsesAny: Lint;
 */
 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
@@ -1389,4 +1448,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 AdvisorArgumentValidator, type AdvisorAuthApiCall, type AdvisorContainer, type AdvisorHyperdriveCall, type AdvisorIndex, type AdvisorIndexHit, type AdvisorInsertWrite, type AdvisorMaskProcedure, type AdvisorNondeterministicCall, type AdvisorProcedureProtection, type AdvisorQueryRead, 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, relationReferencesUnknownField, relationReferencesUnknownTable, rlsUncoveredTable, runAdvisor, sqlInjectionRisk, tableWithoutInsert, unboundedStringArgument, unindexedForeignKey, unindexedRelationTarget, userCreatingMutationWithoutCaptcha, workflowUnknownTarget, workflowUnused };
+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 };

package/dist/index.mjs

@@ -17,6 +17,7 @@ import nondeterministicQueryMutation from './packem_shared/nondeterministicQuery
 import policyReferencesUnknownTable from './packem_shared/policyReferencesUnknownTable-DtaIEovd.mjs';
 import publicArgumentUsesAny from './packem_shared/publicArgumentUsesAny-C71b2NCf.mjs';
 import publicMutationWithoutRatelimit from './packem_shared/publicMutationWithoutRatelimit-xBpJ6GWK.mjs';
+import r2sqlOutsideAction from './packem_shared/r2sqlOutsideAction-CtqxvMuV.mjs';
 import relationReferencesUnknownField from './packem_shared/relationReferencesUnknownField-YznyXt_7.mjs';
 import relationReferencesUnknownTable from './packem_shared/relationReferencesUnknownTable-DrorpKYe.mjs';
 import rlsUncoveredTable from './packem_shared/rlsUncoveredTable-CxEfZ5eZ.mjs';
@@ -46,6 +47,7 @@ const STATIC_LINTS = [
   filterWithoutIndex,
   nondeterministicQueryMutation,
   hyperdriveOutsideAction,
+  r2sqlOutsideAction,
   authApiCallWithoutHeaders,
   policyReferencesUnknownTable,
   rlsUncoveredTable,
@@ -74,4 +76,4 @@ const runAdvisor = (context, options = {}) => {
   return findings;
 };
 
-export { ALL_LINTS, RUNTIME_LINTS, STATIC_LINTS, adminRouteWithoutGuard, authApiCallWithoutHeaders, circularFk, constraintValidator, containerOversizedInstance, containerPublicInternet, duplicateIndex, emptyIndex, filterWithoutIndex, hardcodedSecret, hotShard, hyperdriveOutsideAction, indexReferencesUnknownField, indexUtilization, maskUncoveredPiiColumn, nondeterministicQueryMutation, policyReferencesUnknownTable, publicArgumentUsesAny, publicMutationWithoutRatelimit, relationReferencesUnknownField, relationReferencesUnknownTable, rlsUncoveredTable, runAdvisor, sqlInjectionRisk, tableWithoutInsert, unboundedStringArgument, unindexedForeignKey, unindexedRelationTarget, userCreatingMutationWithoutCaptcha, workflowUnknownTarget, workflowUnused };
+export { ALL_LINTS, RUNTIME_LINTS, STATIC_LINTS, adminRouteWithoutGuard, authApiCallWithoutHeaders, circularFk, constraintValidator, containerOversizedInstance, containerPublicInternet, duplicateIndex, emptyIndex, filterWithoutIndex, hardcodedSecret, hotShard, hyperdriveOutsideAction, indexReferencesUnknownField, indexUtilization, maskUncoveredPiiColumn, nondeterministicQueryMutation, policyReferencesUnknownTable, publicArgumentUsesAny, publicMutationWithoutRatelimit, r2sqlOutsideAction, relationReferencesUnknownField, relationReferencesUnknownTable, rlsUncoveredTable, runAdvisor, sqlInjectionRisk, tableWithoutInsert, unboundedStringArgument, unindexedForeignKey, unindexedRelationTarget, userCreatingMutationWithoutCaptcha, workflowUnknownTarget, workflowUnused };

package/dist/packem_shared/r2sqlOutsideAction-CtqxvMuV.mjs

@@ -0,0 +1,30 @@
+import { e as emit } from './finding-Dm_zvzS1.mjs';
+
+const r2sqlOutsideAction = {
+  categories: ["SCHEMA"],
+  description: "A `query`/`mutation` handler accesses R2 SQL via `ctx.r2sql`. R2 SQL queries external Apache Iceberg tables over REST (no Workers binding): queries are non-deterministic (like `fetch`) and the reads are invisible to live queries. `ctx.r2sql` is available on `ActionCtx` only and must be confined to `action` handlers.",
+  facing: "EXTERNAL",
+  level: "WARN",
+  name: "r2sql_outside_action",
+  remediation: "Move the `ctx.r2sql` access into an `action(...)` (the only context where it is typed), where external I/O is allowed. If a query/mutation needs the data, have the action read it via `ctx.r2sql` and write a projection into a `defineSchema` DO/D1 table — that write is tracked by live queries, whereas R2 SQL is not.",
+  run: (context) => {
+    if (context.r2sqlCalls === void 0) {
+      return [];
+    }
+    const findings = [];
+    for (const call of context.r2sqlCalls) {
+      findings.push(
+        emit(r2sqlOutsideAction, {
+          cacheKey: `r2sql_outside_action:${call.file}:${call.line.toString()}:${call.callee}`,
+          detail: `\`${call.callee}(…)\` in ${call.exportName} (${call.file}:${call.line.toString()}) runs inside a ${call.kind} handler — R2 SQL's \`ctx.r2sql\` is non-deterministic and non-reactive, so it is available only in actions. Move the external query into an \`action\` and project the result into a Lunora table if a query/mutation needs it.`,
+          metadata: { callee: call.callee, exportName: call.exportName, file: call.file, kind: call.kind, line: call.line }
+        })
+      );
+    }
+    return findings;
+  },
+  source: "static",
+  title: "R2 SQL `ctx.r2sql` used outside an action"
+};
+
+export { r2sqlOutsideAction as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/advisor",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "Schema & query lints (splinter-style advisors) for Lunora, feeding the Studio Advisors view",
   "keywords": [
     "advisor",