@lunora/codegen 1.0.0-alpha.256 → 1.0.0-alpha.258

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AdvisorExportSink, AdvisorGeoIndexUsage, AdvisorNotifyCall, AdvisorNotifyConfig, Finding, LintContext, AdvisorProcedureProtection } from '@lunora/advisor';
+import { AdvisorCallSiteScope, AdvisorExportSink, AdvisorGeoIndexUsage, AdvisorNotifyCall, AdvisorNotifyConfig, Finding, LintContext, AdvisorProcedureProtection } from '@lunora/advisor';
 export type { Finding } from '@lunora/advisor';
 import { Project, SourceFile, Node } from 'ts-morph';
 import { LunoraError } from '@lunora/errors';
@@ -819,6 +819,14 @@ interface WorkflowIR {
   };
   /** The `lunora/workflows.ts` export name, e.g. `orderPipeline`. */
   exportName: string;
+  /**
+   * The file declaring the `handler:` when it is a function passed by reference
+   * and declared in another file — the file {@link WorkflowIR.steps}' lines are
+   * in. Lunora-relative inside `lunora/`, project-relative outside it.
+   */
+  handlerFile?: string;
+  /** See {@link HandlerSiteIR}. */
+  handlerSite?: HandlerSiteIR;
   /** Static `limits` literal → `exports.<Class>.limits`. */
   limits?: {
     steps?: number;
@@ -841,7 +849,8 @@ interface WorkflowIR {
    * call. Feeds the duplicate-step-name lint, which flags a name used twice
    * (Cloudflare memoizes by name, so the second call silently returns the
    * first's cached result). Calls with a non-literal name are omitted (not
-   * statically comparable).
+   * statically comparable). A handler passed by reference is followed to its
+   * declaration; the lines are then in {@link WorkflowIR.handlerFile}.
    */
   steps: ReadonlyArray<WorkflowStepIR>;
 }
@@ -924,6 +933,8 @@ interface QueueIR {
   bindingName: string;
   /** The `lunora/queues.ts` export name, e.g. `emailQueue`. */
   exportName: string;
+  /** See {@link HandlerSiteIR}. */
+  handlerSite?: HandlerSiteIR;
   /** How the queue is consumed: `"push"` (a worker `queue()` handler) or `"pull"` (external HTTP). */
   mode: "pull" | "push";
   /**
@@ -981,6 +992,43 @@ interface ModuleIR {
   /** Tables the module declares it owns (`defineModule({ tables })`); empty when it declares none. */
   tables: ReadonlyArray<string>;
 }
+/**
+ * Who a discovered call site runs on behalf of — the one attribution every
+ * per-call-site IR carries (see `discover/attribution`).
+ *
+ * `export`: lexically inside an exported top-level declaration. `name` is the
+ * EXPORTED name — `export const send = …` → `send`, `export default …` →
+ * `default`, `const run = …; export { run as start }` → `start`.
+ *
+ * `helper`: inside a top-level, non-exported `function` / `const` of the same
+ * file. `callers` are the exports that reach it through same-file value
+ * references (a call, or the helper passed on as a value), transitively and
+ * sorted; a type-only reference (`typeof helper`) does not count. Empty for an
+ * orphan helper no export reaches. `untracked` is set when code attribution
+ * cannot follow — module scope, a class body, a destructured declaration — also
+ * reaches the helper, so `callers` is incomplete.
+ *
+ * `module`: outside every top-level `function` / `const` — module scope, or a
+ * class body.
+ *
+ * A site is recorded once; consumers fan out over its callers. The advisor's
+ * `AdvisorCallSiteScope` is the same type, so feeder rows pass straight through.
+ */
+type CallSiteScope = AdvisorCallSiteScope;
+/**
+ * Where a queue or workflow `handler:` passed by reference is declared, when it is
+ * exported from a lunora source file — `defineWorkflow({ handler: onboard })` with
+ * `onboard` exported from `lunora/onboarding/flow.ts` gives
+ * `{ exportName: "onboard", file: "onboarding/flow" }`. The architecture graph
+ * attributes that export's own call sites to the queue or workflow node, so its
+ * calls are not reported as "not a registered function". `exportName` is the
+ * exported name (`export { run as start }` → `start`).
+ */
+interface HandlerSiteIR {
+  exportName: string;
+  /** Source file relative to `<projectRoot>/lunora/`, without extension. */
+  file: string;
+}
 /**
  * A sibling Worker the app calls through a Cloudflare service binding, declared in
  * `lunora.config.*` `services` (plan 457). Becomes a wrangler `services[]` entry,
@@ -1054,12 +1102,12 @@ interface FlagsIR {
  * unused-workflow heuristic rather than producing a false positive).
  */
 interface WorkflowCallIR {
-  /** Export binding name of the function performing the call, e.g. `create`. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension (the api namespace). */
   file: string;
   /** 1-based line of the `get(...)` call. */
   line: number;
+  /** Who the call runs on behalf of. */
+  scope: CallSiteScope;
   /** The referenced workflow export name, or `""` when the argument is not a string literal. */
   workflow: string;
 }
@@ -1071,8 +1119,6 @@ interface WorkflowCallIR {
  * dynamic table — not lintable).
  */
 interface QueryReadIR {
-  /** Exported procedure the read sits in, or `""` at module scope. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /**
@@ -1088,6 +1134,8 @@ interface QueryReadIR {
   hasIndex: boolean;
   /** 1-based line of the `query(...)` call. */
   line: number;
+  /** Who the read runs on behalf of. */
+  scope: CallSiteScope;
   /** Queried table name, or `""` when the argument is not a string literal. */
   table: string;
   /**
@@ -1111,8 +1159,6 @@ interface QueryReadIR {
  * `AdvisorInsertWrite`.
  */
 interface AuthApiCallIR {
-  /** Export binding name of the function performing the call, e.g. "createOrg". */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** True when the call's argument object includes a `headers` property. */
@@ -1121,6 +1167,8 @@ interface AuthApiCallIR {
   line: number;
   /** The better-auth method invoked (e.g. `banUser`); empty when not statically known. */
   method: string;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * A table write other than a plain `ctx.db.insert(...)` (see {@link InsertWriteIR}):
@@ -1129,15 +1177,18 @@ interface AuthApiCallIR {
  * edges and the `cross_module_table_write` lint.
  */
 interface TableWriteIR {
-  /** Export binding name of the function performing the write. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the call. */
   line: number;
   /** The writer method called, e.g. `patch`, `deleteMany`, `upsert`. */
   method: string;
-  /** Target table; `""` when it can't be read (an untyped id, a non-literal name). */
+  /** Who the write runs on behalf of. */
+  scope: CallSiteScope;
+  /**
+   * Target table; `""` when it can't be read (an untyped id, a non-literal
+   * name). A union id (`Id<"a"> | Id<"b">`) gives one record per table.
+   */
   table: string;
 }
 /**
@@ -1148,12 +1199,12 @@ interface TableWriteIR {
  * {@link InsertWriteIR.table} is `""` when the argument is not a string literal.
  */
 interface InsertWriteIR {
-  /** Export binding name of the function performing the insert, e.g. "send". */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension (the api namespace). */
   file: string;
   /** 1-based line of the `insert(...)` call. */
   line: number;
+  /** Who the insert runs on behalf of. */
+  scope: CallSiteScope;
   /** Target table name, or `""` when the argument is not a string literal. */
   table: string;
 }
@@ -1552,12 +1603,12 @@ interface SecretLiteralIR {
  * identical to `AdvisorSqlInterpolation`.
  */
 interface SqlInterpolationIR {
-  /** Export binding name of the procedure performing the `ctx.sql` call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the interpolation, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.fetch(url, …)` call inside an action whose URL argument is derived
@@ -1569,12 +1620,12 @@ interface SqlInterpolationIR {
  * identical to `AdvisorArgumentDerivedFetch`.
  */
 interface ArgumentDerivedFetchIR {
-  /** Export binding name of the action performing the `ctx.fetch` call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `ctx.fetch` call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.kv.<method>(key, …)` call whose namespace key is derived from the
@@ -1587,14 +1638,14 @@ interface ArgumentDerivedFetchIR {
  * prefix, not a per-entry key). Structurally identical to `AdvisorKvKeyAccess`.
  */
 interface KvKeyAccessIR {
-  /** Export binding name of the procedure performing the `ctx.kv` access. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `ctx.kv` call, or `0` when unknown. */
   line: number;
   /** The `ctx.kv` method invoked: `get` / `getRaw` / `getWithMetadata` / `put` / `delete`. */
   method: string;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /**
    * Visibility of the enclosing procedure. `internal` procedures have no
    * untrusted caller by construction — see `owner_field_from_args_not_auth`'s
@@ -1636,8 +1687,6 @@ interface UnrestrictedWhereBranchIR {
   owner: string;
 }
 interface OwnerFieldWriteIR {
-  /** Export binding name of the procedure performing the write. */
-  exportName: string;
   /** The identity column being written from `args` (e.g. `userId`). */
   field: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
@@ -1648,7 +1697,9 @@ interface OwnerFieldWriteIR {
   method: string;
   /**
    * The enclosing `defineMutator` declared this very column as its `owner`, AND
-   * the value written resolves to that same `args[owner]`.
+   * the value written resolves, by symbol, to that same `args[owner]` of the
+   * `server` impl's own 2nd parameter. A nested closure's or a helper's own
+   * `args` (or any binding shadowing it) never qualifies.
    *
    * `applyOwnerScope` requires a verified identity, rejects a client-supplied
    * value that disagrees with it, and overwrites the column with the verified
@@ -1663,6 +1714,8 @@ interface OwnerFieldWriteIR {
    * is a real IDOR and stays reportable.
    */
   ownerScoped?: true;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /**
    * Visibility of the enclosing procedure. `internal` procedures are not
    * reachable by a caller, so the lint's premise ("any caller can write rows
@@ -1683,14 +1736,14 @@ interface OwnerFieldWriteIR {
  * Structurally identical to `AdvisorStorageKeyAccess`.
  */
 interface StorageKeyAccessIR {
-  /** Export binding name of the procedure performing the storage call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the storage call, or `0` when unknown. */
   line: number;
   /** The bucket method invoked with the arg-derived key, e.g. `get` / `put` / `delete` / `download`. */
   method: string;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /**
    * Visibility of the enclosing procedure. `internal` procedures have no
    * untrusted caller by construction — see `owner_field_from_args_not_auth`'s
@@ -1712,14 +1765,14 @@ interface StorageKeyAccessIR {
  * identical to `AdvisorContainerKeyAccess`.
  */
 interface ContainerKeyAccessIR {
-  /** Export binding name of the procedure performing the `ctx.containers` access. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `ctx.containers.*.get` call, or `0` when unknown. */
   line: number;
   /** The container accessor method invoked — always `get`. */
   method: string;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.ai.run(model, …)` call whose model-id argument is derived from the handler's
@@ -1732,12 +1785,12 @@ interface ContainerKeyAccessIR {
  * normal usage and is never inspected). Structurally identical to `AdvisorAiRawRun`.
  */
 interface AiRawRunIR {
-  /** Export binding name of the procedure performing the `ctx.ai.run` call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `ctx.ai.run` call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.vectors.<method>(indexName, input)` call whose `input.namespace` is derived
@@ -1750,14 +1803,14 @@ interface AiRawRunIR {
  * here. Structurally identical to `AdvisorVectorNamespaceAccess`.
  */
 interface VectorNamespaceAccessIR {
-  /** Export binding name of the procedure performing the `ctx.vectors` access. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `ctx.vectors` call, or `0` when unknown. */
   line: number;
   /** The `ctx.vectors` method invoked: `query` / `upsert` / `upsertNow`. */
   method: string;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.mail`/`ctx.email` `send`/`queue` call whose recipient field (`to`/`cc`/`bcc`)
@@ -1770,14 +1823,14 @@ interface VectorNamespaceAccessIR {
  * `AdvisorMailRecipientAccess`.
  */
 interface MailRecipientAccessIR {
-  /** Export binding name of the procedure performing the `ctx.mail`/`ctx.email` call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `ctx.mail`/`ctx.email` call, or `0` when unknown. */
   line: number;
   /** The mailer method invoked: `send` / `queue`. */
   method: string;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.browser.<method>(url, …)` call whose navigation URL (`arguments[0]`)
@@ -1788,14 +1841,14 @@ interface MailRecipientAccessIR {
  * `resolveDns`. Structurally identical to `AdvisorBrowserUrlAccess`.
  */
 interface BrowserUrlAccessIR {
-  /** Export binding name of the procedure performing the `ctx.browser` call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `ctx.browser` call, or `0` when unknown. */
   line: number;
   /** The browser method invoked: `content` / `pdf` / `scrape` / `screenshot`. */
   method: string;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One runtime container-override call: a `<handle>.start({ enableInternet: true, … })`
@@ -1809,14 +1862,14 @@ interface BrowserUrlAccessIR {
 interface ContainerOverrideIR {
   /** e.g. the egress method name, or `"enableInternet: true"`. */
   detail: string;
-  /** Export binding name of the procedure performing the call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** Which override shape matched. */
   kind: "egress_relaxation" | "enable_internet";
   /** 1-based line of the call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `buildImageDeliveryUrl({ key, … })` call (`@lunora/bindings/images`) whose
@@ -1832,12 +1885,12 @@ interface ContainerOverrideIR {
  * identical to `AdvisorImageDeliveryUrlAccess`.
  */
 interface ImageDeliveryUrlAccessIR {
-  /** Export binding name of the procedure performing the `buildImageDeliveryUrl` call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `buildImageDeliveryUrl` call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `createAuth({...})` call's configuration snapshot — the shared input for
@@ -1858,8 +1911,6 @@ interface AuthConfigIR {
   disableCsrfCheck: boolean;
   /** `emailAndPassword.enabled === true`. */
   emailPasswordEnabled: boolean;
-  /** Export binding name enclosing the `createAuth(...)` call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the `createAuth(...)` call, or `0` when unknown. */
@@ -1869,6 +1920,8 @@ interface AuthConfigIR {
   /** `trustedOrigins` array literal contains a `"*"` element. */
   /** `plugins` includes `scim(...)` while `database` is a non-transactional Lunora adapter — a combination that throws at runtime. */
   scimOnNonTransactionalAdapter: boolean;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /** `advanced.useSecureCookies === false`. */
   secureCookiesDisabled: boolean;
   /** `session.freshAge === 0` (explicit literal). */
@@ -1890,14 +1943,14 @@ interface AuthConfigIR {
 interface RatelimitKeySelectorIR {
   /** The `rateLimit`/`dbRateLimit` callee invoked. */
   callee: string;
-  /** Export binding name of the procedure whose `.use(...)` chain carries the call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** The rate limit's `name` argument (the second positional argument), or `""` when not a string literal. */
   limitName: string;
   /** 1-based line of the `rateLimit`/`dbRateLimit` call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One payload-derived privileged dispatch — a `ctx.run`/`context.run` back into a
@@ -1915,10 +1968,10 @@ interface PrivilegedDispatchIR {
   dispatchKind: "queue" | "workflow";
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
-  /** Export binding name of the handler performing the dispatch. */
-  handlerExport: string;
   /** 1-based line of the dispatch call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /** Export name of the dispatched target (`send` in `api.messages.send`). */
   targetExport: string;
   /** File path of the dispatched target relative to `lunora/` (`messages` in `api.messages.send`). */
@@ -1959,8 +2012,6 @@ interface StorageUploadIR {
   analyzable: boolean;
   /** Numeric literal value of an `expiresInSeconds` option, when statically known (`getSignedUrl` / `getPresignedUrl` only). */
   expiresInSeconds?: number;
-  /** Export binding name of the procedure performing the call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the call, or `0` when unknown. */
@@ -1969,6 +2020,8 @@ interface StorageUploadIR {
   method: "generateUploadUrl" | "getPresignedUrl" | "getSignedUrl" | "store" | "upload";
   /** Options-object keys present at the call site (empty when not `analyzable`, or when no options argument was passed). */
   presentKeys: string[];
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One discovered `httpAction`/`httpRoute` handler in `lunora/` that performs a
@@ -1982,8 +2035,6 @@ interface StorageUploadIR {
  * `AdvisorHttpActionGuard`.
  */
 interface HttpActionGuardIR {
-  /** Export binding name of the handler (or `"<module>"` when mounted inline / not a named binding). */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** Which HTTP surface the handler is: a raw `httpAction` or a typed `httpRoute` route. */
@@ -1994,6 +2045,8 @@ interface HttpActionGuardIR {
   method?: string;
   /** `true` when the handler reads `ctx.auth` (a direct member access or a `const { auth } = ctx` destructure). */
   readsAuth: boolean;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /** The first side effect found, as a stable label: `runMutation`, `runAction`, or `db.<method>`. */
   sideEffect: string;
 }
@@ -2012,14 +2065,14 @@ interface HttpActionGuardIR {
  * identical to `AdvisorHttpHeaderWrite`.
  */
 interface HttpHeaderWriteIR {
-  /** Export binding name of the enclosing handler, or `"<module>"` when mounted inline. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** The header name being written (`"location"`), or `""` when the key is not a string literal. */
   headerName: string;
   /** 1-based line of the request-tainted header value. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /** How the header was written. */
   via: "headers-append" | "headers-ctor" | "headers-set" | "response-init";
 }
@@ -2037,8 +2090,6 @@ interface HttpHeaderWriteIR {
 interface FailOpenGuardIR {
   /** The middleware factory at the call site: `rateLimit` / `dbRateLimit` / `verifyTurnstileMiddleware`. */
   callee: string;
-  /** Export binding name of the procedure the guard is attached to, or `"<module>"` at file scope. */
-  exportName: string;
   /** `true` only when the options literal set `failOpen: true` as a boolean literal; a non-literal or absent option is treated as fail-closed. */
   failOpen: boolean;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
@@ -2047,6 +2098,8 @@ interface FailOpenGuardIR {
   limitName: string;
   /** 1-based line of the middleware call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.flags.boolean("key", <boolean-literal>)` read in `lunora/` — the
@@ -2060,14 +2113,14 @@ interface FailOpenGuardIR {
 interface FlagSecurityDefaultIR {
   /** The boolean-literal default returned on a provider outage (fail-open value). */
   defaultValue: boolean;
-  /** Export binding name of the procedure performing the flag read, or `"<module>"` at file scope. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** The flag key — the first string-literal argument of `ctx.flags.boolean`. */
   key: string;
   /** 1-based line of the `ctx.flags.boolean` call, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One `ctx.flags` read lexically inside a `query(...)` handler — the
@@ -2101,14 +2154,14 @@ interface FlagReadIR {
  * Structurally identical to `AdvisorAiToolSideEffect`.
  */
 interface AiToolSideEffectIR {
-  /** Export binding name of the procedure performing the call. */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the generation call, or `0` when unknown. */
   line: number;
   /** The generation entrypoint invoked. */
   method: "generateText" | "streamText";
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /** The privileged side-effect sink a model-callable tool reaches (`ctx.db.insert`, `ctx.run`, `ctx.fetch`, …). */
   sideEffect: string;
   /** `true` when a model-input option is derived from the handler's `args` (a bare `args.x`, or a name destructured from `args`). */
@@ -2125,14 +2178,14 @@ interface AiToolSideEffectIR {
 interface IdentityClaimReadIR {
   /** `true` when `key` is a declared claim (in the `defineIdentity` contract, or the always-present `userId`). */
   declared: boolean;
-  /** Export binding name of the enclosing declaration (`<module>` at file scope). */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** The claim key read off the identity bag. */
   key: string;
   /** 1-based line of the read, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
 }
 /**
  * One payment webhook-adapter construction in `lunora/` (`createStripeAdapter` /
@@ -2145,12 +2198,12 @@ interface IdentityClaimReadIR {
 interface PaymentWebhookIR {
   /** The adapter factory invoked. */
   callee: "createAutumnAdapter" | "createDodoPaymentsAdapter" | "createPolarAdapter" | "createStripeAdapter";
-  /** Export binding name of the enclosing declaration (`<module>` at file scope). */
-  exportName: string;
   /** Source file relative to `<projectRoot>/lunora/`, without extension. */
   file: string;
   /** 1-based line of the construction, or `0` when unknown. */
   line: number;
+  /** Who the site runs on behalf of — see {@link CallSiteScope}. */
+  scope: CallSiteScope;
   /** Statically-known `webhookToleranceSeconds` literal, when present and a plain numeric literal. */
   toleranceSeconds?: number;
 }
@@ -3184,8 +3237,7 @@ declare const discoverAgents: (project: Project, lunoraDirectory: string) => Age
 declare const listLunoraSourceFiles: (directory: string) => string[];
 /**
  * Discover `ctx.authApi.<method>(...)` (and bare `authApi.<method>(...)`) calls
- * under the lunora source directory and attribute each to the exported function
- * (and file) performing it. Calls outside an exported declaration are dropped.
+ * under the lunora source directory, each with its `CallSiteScope`.
  */
 declare const discoverAuthApiCalls: (project: Project, lunoraDirectory: string) => AuthApiCallIR[];
 /** The only file containers may be declared in — mirrors `lunora/crons.ts`. */
@@ -3244,10 +3296,11 @@ declare const discoverHttpRoutes: (project: Project, lunoraDirectory: string) =>
  */
 declare const discoverHyperdriveCalls: (project: Project, lunoraDirectory: string) => ContextPropertyCallIR[];
 /**
- * Discover `ctx.db.insert("table", …)` writes under the lunora source directory
- * and attribute each to the exported function (and file) performing it. Calls
- * with a non-literal table argument, or outside an exported declaration, are
- * dropped (`table === ""` / no enclosing export).
+ * Discover `ctx.db.insert("table", …)` writes under the lunora source directory,
+ * one record per call site with its `CallSiteScope` — so an insert inside a
+ * same-file helper carries the exports calling the helper, and one in a helper
+ * no export calls is kept rather than lost. A non-literal table argument is kept
+ * with `table: ""`.
  */
 declare const discoverInserts: (project: Project, lunoraDirectory: string) => InsertWriteIR[];
 /**
@@ -3330,7 +3383,8 @@ declare const discoverNotifyConfig: (project: Project, lunoraDirectory: string)
 declare const readPackageDependencies: (projectRoot: string) => Set<string> | undefined;
 /**
  * Discover every `ctx.db.query("table")…` read under the lunora source directory
- * and reduce each to a {@link QueryReadIR}.
+ * and reduce each to a {@link QueryReadIR}, one per read site with its
+ * `CallSiteScope`.
  *
  * Reads without a `.filter()` are kept too. They are never
  * `filter_without_index` candidates (that lint gates on `hasFilter`), but an