@oxy-hq/sdk 2.11.0 → 2.12.0

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 
-import { $ as loadCustomAppManifest, A as UseSemanticQueryOpts, B as FunctionError, C as UseProcedureRunInput, D as UseQueryOpts, E as UseQueryInput, F as useProcedureRun, G as apiErrorFromResponse, H as FunctionResult, I as useQuery, J as OxyAppFunctionManifest, K as interpretCustomAppError, L as useResolvedManifest, M as useAgentRun, N as useFunction, O as UseQueryResult, P as useOxyApp, Q as _resetCustomAppManifestCacheForTest, R as useSemanticQuery, S as UseFunctionResult, T as UseProcedureRunResult, U as CustomAppErrorReport, V as FunctionLog, W as OxyApiError, X as OxyAppPerformanceManifest, Y as OxyAppManifest, Z as ResolvedCustomAppManifest, _ as SemanticFilter, a as AppFetcher, b as UseAgentRunInput, c as OxyAppProvider, d as OxyChatProps, f as ProcedureProgress, g as SemanticDateRangeOp, h as SemanticArrayOp, i as AgentSqlArtifact, j as UseSemanticQueryResult, k as UseSemanticQueryInput, l as OxyAppProviderProps, m as ProcedureRunState, n as AgentRunEvent, o as OxyAnswer, p as ProcedureResult, q as LoadManifestOptions, r as AgentRunState, s as OxyAnswerProps, t as AgentArtifact, u as OxyChat, v as SemanticScalarOp, w as UseProcedureRunOpts, x as UseAgentRunResult, y as SemanticTimeDimension, z as useTrackEvent } from "./react-CLONxcnA.mjs";
+import { $ as loadCustomAppManifest, A as UseSemanticQueryOpts, B as FunctionError, C as UseProcedureRunInput, D as UseQueryOpts, E as UseQueryInput, F as useProcedureRun, G as apiErrorFromResponse, H as FunctionResult, I as useQuery, J as OxyAppFunctionManifest, K as interpretCustomAppError, L as useResolvedManifest, M as useAgentRun, N as useFunction, O as UseQueryResult, P as useOxyApp, Q as _resetCustomAppManifestCacheForTest, R as useSemanticQuery, S as UseFunctionResult, T as UseProcedureRunResult, U as CustomAppErrorReport, V as FunctionLog, W as OxyApiError, X as OxyAppPerformanceManifest, Y as OxyAppManifest, Z as ResolvedCustomAppManifest, _ as SemanticFilter, a as AppFetcher, b as UseAgentRunInput, c as OxyAppProvider, d as OxyChatProps, f as ProcedureProgress, g as SemanticDateRangeOp, h as SemanticArrayOp, i as AgentSqlArtifact, j as UseSemanticQueryResult, k as UseSemanticQueryInput, l as OxyAppProviderProps, m as ProcedureRunState, n as AgentRunEvent, o as OxyAnswer, p as ProcedureResult, q as LoadManifestOptions, r as AgentRunState, s as OxyAnswerProps, t as AgentArtifact, u as OxyChat, v as SemanticScalarOp, w as UseProcedureRunOpts, x as UseAgentRunResult, y as SemanticTimeDimension, z as useTrackEvent } from "./react-DW7Z96sD.mjs";
+import { C as StorageDownloadUrl, D as StoragePutResult, E as StoragePutOptions, O as StorageUploadUrl, S as OxyWarehouseApi, T as StorageObject, _ as OxyReach, a as OxyEmailApi, b as OxyStorageApi, c as OxyFunctionHandler, d as OxyFunctionUser, f as OxyIdentityKind, g as OxyOrgTeam, h as OxyOrgPlace, i as OxyAirwayApi, k as StorageUploadUrlInput, l as OxyFunctionRequest, m as OxyOrgAssignment, n as EmailSendInput, o as OxyFetchResult, p as OxyOltpApi, r as EmailSendResult, s as OxyFunctionContext, t as EmailAttachment, u as OxyFunctionRow, v as OxySecretsApi, w as StorageListPage, x as OxyTransaction, y as OxySemanticApi } from "./function-context-D8eyZuw_.mjs";
 //#region src/config.d.ts
 /**
  * Configuration for the Oxy SDK
@@ -44,7 +45,15 @@ type EdgeKind = "component" | "driver";
 type DriverDirection = "positive" | "negative" | "unknown";
 type DriverStrength = "strong" | "moderate" | "weak";
 type DriverConfidence = "high" | "medium" | "low";
-type DriverForm = "linear" | "log-log" | "log-linear" | "linear-log";
+/** The shape of a driver relationship.
+ *
+ *  The THIRD hand-maintained mirror of this enum (airlayer's is canonical,
+ *  `web-app/src/types/metricTree.ts` is the second). Nothing enforces that they
+ *  agree, and the last time one fell behind — `oxy-semantic`, five variants
+ *  short — a valid `.view.yml` stopped parsing. A type-only union fails more
+ *  softly: an SDK consumer reading a tree with a quadratic edge just gets a
+ *  union that cannot hold it. Add new shapes here whenever airlayer grows one. */
+type DriverForm = "linear" | "log-log" | "log-linear" | "linear-log" | "quadratic" | "cubic" | "sqrt" | "inverse" | "linear-log-quadratic";
 interface MetricNode {
   id: string;
   view: string;
@@ -53,6 +62,11 @@ interface MetricNode {
   description?: string | null;
   measure_type: string;
   is_composite: boolean;
+  /** Whether this measure can be drilled into. Serialized rather than
+   *  re-derived: `measure_type` misses eligible composites, and edge presence
+   *  over-admits nested / cross-view / multiplicative passthroughs the engine
+   *  refuses. Non-optional — it is on every metric-tree response. */
+  drillable: boolean;
   expr?: string | null;
 }
 interface MetricEdge {
@@ -61,11 +75,18 @@ interface MetricEdge {
   kind: EdgeKind;
   /** Sign of a component edge; omitted (defaults to +1) for most edges. */
   sign?: number;
+  /** Arithmetic operator joining a component child to its parent. Omitted
+   *  when it is `add` — airlayer skips the field at its default — so absent
+   *  MEANS `add`, never "unknown". Only `mul` / `div` are multiplicative;
+   *  `add` / `sub` propagate exactly. */
+  operator?: "add" | "sub" | "mul" | "div";
   direction: DriverDirection;
   strength: DriverStrength;
   confidence: DriverConfidence;
   coefficient?: number | null;
   form: DriverForm;
+  /** Whether `form` was declared in the YAML or inferred by the fit. */
+  form_declared?: boolean;
   intercept?: number | null;
   lag?: number | null;
   description?: string | null;
@@ -75,6 +96,10 @@ interface MetricTree {
   nodes: MetricNode[];
   edges: MetricEdge[];
   root?: string | null;
+  /** Refusals raised while building the tree — a driver declaring both
+   *  `coefficient:` and `coefficients:`, or a wrong-width vector. Absent when
+   *  empty, so a lever that moves nothing still has a way to say why. */
+  warnings?: string[];
 }
 interface SensitivityDriver {
   measure: string;
@@ -107,6 +132,191 @@ interface PredictResult {
   inputs: PredictChange[];
   impacts: PredictImpact[];
 }
+/** node_id → the measure's value over the baseline window. */
+type MeasureValues = Record<string, number>;
+/** A driver edge's coefficient, measured from history by the baseline query.
+ *
+ *  Either `coefficient` is set or `refusal` is — never both, never neither.
+ *  A refusal is a result: it is why a measure downstream of the change shows
+ *  no number. Echo the whole array into `predict` verbatim, refusals included;
+ *  the server ignores entries carrying no coefficient, and filtering them here
+ *  would be a second place for the two sides to disagree. */
+interface FittedDriver {
+  from: string;
+  to: string;
+  lag?: number;
+  /** The form the slope was measured in. The same number reads as dollars per
+   *  dollar under `linear` and as a percent-per-percent elasticity under
+   *  `log-log`, so a bare figure has no unit. */
+  form?: DriverForm;
+  /** Paired observations behind the fit.
+   *
+   *  `| null` because this mirrors an `Option<f64>` on a GIT-PINNED struct:
+   *  `skip_serializing_if` is a serde attribute today, not a guarantee, so a
+   *  reader must accept both encodings. Compare with `!= null`, never
+   *  `!== undefined` — and the type has to admit both, or the safe read looks
+   *  like dead code. Same rule on `t_stat`, `t_stats`, `se_terms` and
+   *  `coefficient` below. */
+  n?: number | null;
+  n_panels?: number;
+  n_nonpositive?: number;
+  /** The FIRST basis term — the whole answer for a single-term form; for a
+   *  shape that can turn it is only the slope, so read `coefficients`.
+   *  `| null` because it is an `Option<f64>` on the wire. */
+  coefficient?: number | null;
+  /** One coefficient per basis term, in basis order. This is what propagation
+   *  evaluates. */
+  coefficients?: number[];
+  se?: number;
+  /** Elements `| null` for the reason stated on `n`. */
+  se_terms?: (number | null)[];
+  /** `| null` for the reason stated on `n`. */
+  t_stat?: number | null;
+  /** `t` per basis term, in basis order — `[1]` is the second basis term, the
+   *  squared one under every shape that can turn. Elements `| null` for the
+   *  reason stated on `n`. */
+  t_stats?: (number | null)[];
+  /** Sufficient statistics of the basis over the rows the fit used. Not
+   *  diagnostic: the fit is per row and a change is a window aggregate, and a
+   *  curved response cannot cross that gap without these. Echo verbatim. */
+  moments?: {
+    n?: number;
+    s1?: number;
+    s2?: number;
+  };
+  /** `[min, max]` driver values observed. A change beyond this spread is
+   *  refused rather than extrapolated. */
+  domain?: [number, number];
+  /** The response sampled as `[change fraction, delta]`. Read this instead of
+   *  interpreting the coefficients — peak, break-even and saturation are all
+   *  properties of these samples, so a reader written against them keeps
+   *  working when a new shape is added. */
+  profile?: [number, number][];
+  form_source?: "declared" | "inferred";
+  /** Every shape considered, scored comparably (AIC in y-space, lower better).
+   *  Empty when the form was declared. `all_terms_significant` false means the
+   *  candidate was never eligible, however good its score. */
+  candidates?: {
+    form: DriverForm;
+    aic: number;
+    all_terms_significant: boolean;
+  }[];
+  refusal?: string;
+}
+/** Why a reachable node has no baseline value. */
+interface UnvaluedNode {
+  id: string;
+  reason?: string | null;
+}
+/** Narrow the baseline to one world-model instance. Omit to value the whole
+ *  population. */
+interface BaselineInstance {
+  entity: string;
+  /** JSON array for a composite key, else a bare scalar. */
+  key: string;
+}
+interface BaselineRequest {
+  /** The nodes you intend to change. Values are fetched for these plus
+   *  everything forward-reachable from them — not the whole tree. */
+  roots: string[];
+  time_dimension: string;
+  /** `[start, end]` inclusive date strings. */
+  period: [string, string];
+  instance?: BaselineInstance | null;
+}
+interface BaselineResponse {
+  values: MeasureValues;
+  unvalued: UnvaluedNode[];
+  resolved_period: [string, string];
+  /** Why the baseline produced no values, in words worth showing. Absent when
+   *  measures were valued normally. */
+  baseline_note?: string | null;
+  /** Coefficients fitted for driver edges that declare none, plus refusals.
+   *  Absent when every reachable driver edge already declares one. */
+  fitted?: FittedDriver[];
+}
+interface PredictOptions {
+  /** Current values for the measures involved. Supplying them lets
+   *  multiplicative edges be sized instead of returned `unquantifiable`. */
+  values?: MeasureValues;
+  /** The baseline's `fitted` array, verbatim. */
+  coefficients?: FittedDriver[];
+}
+type ProjectionGranularity = "day" | "week" | "month";
+/**
+ * The scenario's time axis. `baseline` answers "what is this measure worth
+ * over the window"; this answers "what has it been doing, and what does it do
+ * next".
+ *
+ * The history window is deliberately its own, NOT the baseline's: the
+ * forecaster refuses anything under eight seasonal cycles (56 daily buckets,
+ * 32 weekly, 24 monthly), and a 30-day scenario baseline reused here would
+ * make "no forecast" the normal answer.
+ */
+interface ProjectionRequest {
+  /** Lever node ids. Curves are drawn for these plus everything
+   *  forward-reachable from them — the same set {@link BaselineRequest} values. */
+  roots: string[];
+  time_dimension: string;
+  /** `[start, end]` inclusive date strings for the HISTORY. */
+  period: [string, string];
+  /** Narrow to one world-model instance. Omit to project the whole
+   *  population — same picker the baseline uses. */
+  instance?: BaselineInstance | null;
+  /** Bucket width. Defaults to `day` server-side. */
+  granularity?: ProjectionGranularity;
+  /** Buckets to project past the last historical one. 1..=365; outside that
+   *  it is a 400, never a silent clamp — a horizon quietly truncated reads as
+   *  a forecast that genuinely ends in March. */
+  horizon: number;
+  /** Seasonal periods, in buckets, applied to every measure in the request.
+   *
+   *  Omitting it is not "use the default" — it means *resolve per measure*
+   *  from whatever `.monitor.yml` already watches that series, which is what
+   *  keeps this band the band an anomaly had to breach. Send it only to pin a
+   *  cycle nobody has declared. Each period must be >= 2; `[]` is a 400. */
+  seasonality?: number[];
+}
+interface HistoryPoint {
+  /** Bucket start, `YYYY-MM-DD`. */
+  date: string;
+  value: number;
+}
+interface ForecastPoint {
+  date: string;
+  point: number;
+  /** The prediction interval. `null` / absent means the model returned no
+   *  band — unknown spread, NOT a band of zero width. Never collapse these
+   *  onto `point`: a zero-width band is a claim of certainty nobody made. */
+  lower?: number | null;
+  upper?: number | null;
+}
+/** One measure's baseline curve: what happened, then what comes next.
+ *
+ *  An empty `forecast` carrying a `refusal` is a state, not a gap — most often
+ *  "too little history to fit", or the warehouse refusing this one measure. It
+ *  must never render as a flat forward line, which is what any code defaulting
+ *  the missing curve to "unchanged" would draw. */
+interface MeasureProjection {
+  measure: string;
+  history: HistoryPoint[];
+  forecast: ForecastPoint[];
+  refusal?: string | null;
+  /** The seasonal periods this curve was decomposed against — resolved per
+   *  measure, so two series in one response can legitimately differ. */
+  seasonality: number[];
+}
+interface ProjectionResponse {
+  granularity: ProjectionGranularity;
+  /** Echoed back: the query is expensive and callers cache on it. */
+  resolved_period: [string, string];
+  horizon: number;
+  series: MeasureProjection[];
+  /** Why the WHOLE projection is empty, when it is. Absent when at least one
+   *  measure produced history — a partial failure is each measure's own
+   *  `refusal`, never a banner over curves that are drawing fine. */
+  projection_note?: string | null;
+}
 type SplitKind = {
   type: "component";
   child_measure: string;
@@ -280,9 +490,10 @@ interface TimeDimensionsResponse {
  */
 type RequestFn$1 = <T>(endpoint: string, options?: RequestInit) => Promise<T>;
 /**
- * Client for the `/semantic/metric-tree*` endpoints. Surfaces the four
- * airlayer metric-tree analyses (tree introspection, sensitivity, predict,
- * explain, opportunity) over typed methods.
+ * Client for the `/semantic/metric-tree*` endpoints. Surfaces the airlayer
+ * metric-tree analyses — tree introspection, sensitivity, explain, opportunity
+ * — plus the three legs of scenario forecasting (`baseline` levels,
+ * `predict` propagation, `projection` curves) over typed methods.
  *
  * Construction is internal to {@link OxyClient} — call `client.metricTree`
  * to access an instance rather than building one yourself.
@@ -327,10 +538,45 @@ declare class MetricTreeClient {
    * ```
    */
   getSensitivity(measureId: string): Promise<SensitivityResult>;
+  /**
+   * Value a change's starting point, and measure the coefficients it needs.
+   *
+   * Two warehouse reads: the current value of every node reachable from
+   * `roots`, and — for driver edges that declare no `coefficient:` — a fit
+   * over the window. Both are expensive, which is why they live here and not
+   * in `predict`: `predict` is database-free by design so it can re-run per
+   * keystroke, and it CANNOT measure a coefficient itself.
+   *
+   * That is the whole reason to call this. Pass `fitted` back into `predict`
+   * and an undeclared edge propagates; omit it and `predict` has nothing to
+   * multiply by, so the impact is simply absent — no error, no refusal, just a
+   * downstream measure that never appears.
+   *
+   * @example
+   * ```typescript
+   * const baseline = await client.metricTree.getBaseline({
+   *   roots: ["marketing_spend.total_spend"],
+   *   time_dimension: "orders.order_date",
+   *   period: ["2025-09-01", "2025-09-30"],
+   * });
+   * const result = await client.metricTree.predict(
+   *   [{ measure: "marketing_spend.total_spend", delta: 10000 }],
+   *   { values: baseline.values, coefficients: baseline.fitted }
+   * );
+   * ```
+   */
+  getBaseline(request: BaselineRequest): Promise<BaselineResponse>;
   /**
    * Propagate hypothetical `(measure, delta)` changes upward through the
    * tree. Returns the estimated impact on every downstream measure.
    *
+   * Database-free, so it re-runs cheaply — and so it can only use
+   * coefficients it is GIVEN. Without `options.coefficients` from
+   * {@link getBaseline}, every edge whose `.view.yml` declares no
+   * `coefficient:` contributes nothing and its downstream measures are
+   * silently missing from `impacts`. Without `options.values`, multiplicative
+   * component edges come back `unquantifiable` rather than sized.
+   *
    * @example
    * ```typescript
    * const result = await client.metricTree.predict([
@@ -338,7 +584,37 @@ declare class MetricTreeClient {
    * ]);
    * ```
    */
-  predict(changes: PredictChange[]): Promise<PredictResult>;
+  predict(changes: PredictChange[], options?: PredictOptions): Promise<PredictResult>;
+  /**
+   * Draw the scenario's time axis: bucketed history for the levers and
+   * everything downstream, plus the forward curve the detector's own model
+   * expects next.
+   *
+   * The third leg of scenario forecasting. {@link getBaseline} gives levels
+   * and coefficients, {@link predict} propagates a change with no database at
+   * all, and this gives time — one warehouse query, so treat it like the
+   * baseline: fetch on a window change, not on a lever edit.
+   *
+   * **Returns the BASELINE curve only.** The scenario's second curve is
+   * arithmetic over this and a `predict` result — a proportional shift landing
+   * `lag` buckets in — and is composed client-side deliberately, so editing a
+   * lever costs no query.
+   *
+   * @example
+   * ```typescript
+   * const projection = await client.metricTree.getProjection({
+   *   roots: ["marketing_spend.total_spend"],
+   *   time_dimension: "orders.order_date",
+   *   period: ["2024-09-01", "2025-08-31"],
+   *   granularity: "day",
+   *   horizon: 30,
+   * });
+   * for (const series of projection.series) {
+   *   if (series.refusal) console.warn(series.measure, series.refusal);
+   * }
+   * ```
+   */
+  getProjection(request: ProjectionRequest): Promise<ProjectionResponse>;
   /**
    * Period-over-period root-cause decomposition. Recursively splits the
    * target measure by components and dimensions until the move concentrates.
@@ -735,636 +1011,6 @@ interface CustomAppDebugSnapshot {
  */
 declare function getCustomAppDebug(resolved: ResolvedCustomAppManifest): Promise<CustomAppDebugSnapshot>;
 //#endregion
-//#region src/custom-app/function-context.d.ts
-/**
- * The request passed as the first argument to a function's default export.
- *
- * The host hands the isolate the raw request body as a string (see
- * `req_json` in `runtime.rs`); parse it yourself, e.g.
- * `JSON.parse(req.body || "{}")`. This is intentionally *not* a full Web
- * `Request` — there is no `.json()` / headers object in v1.
- */
-interface OxyFunctionRequest {
-  /** Raw request body as received (JSON string for a JSON POST). */
-  body: string;
-}
-/** A single row from a `ctx.query` / `ctx.queryStream` result. */
-type OxyFunctionRow = Record<string, unknown>;
-/** One org team the caller belongs to, as reported by {@link OxyFunctionUser.teams}. */
-interface OxyOrgTeam {
-  id: string;
-  name: string;
-}
-/**
- * Who — or what — invoked this function.
- *
- * `"system"` means **no caller to attribute this to** — not necessarily "no
- * human caused it". A schedule tick, an Airway transform step, and an operator's
- * manual *Run now* all take this path: they run under the org owner's `id` (the
- * invocation record needs a real user FK) with every caller field absent. So on
- * a manual run a person really did click, and there is still no way to reach
- * them; the platform does not carry the triggering operator through the job
- * queue.
- *
- * Any branch that emails "the person who clicked" or renders a personal view
- * must check this rather than sniff the synthetic `email` — and must have a
- * sensible answer for the case where there is nobody to send to.
- */
-type OxyIdentityKind = "user" | "system";
-/**
- * Identity of the invoking user (route) or the system identity (schedule,
- * Airway step, or a manual job run).
- *
- * Assembled server-side on every invocation from the authenticated session —
- * **nothing on it is client-supplied**, which is the entire reason to read
- * identity here instead of from the request body. See
- * `internal-docs/custom-apps-user-identity.md` for the full contract, including
- * what the client-side `useShellContext()` can and cannot be trusted for.
- */
-interface OxyFunctionUser {
-  /**
-   * `users.id`. On a `"system"` invocation this is the org owner's id and not a
-   * caller — check {@link kind} before attributing anything to it.
-   */
-  id: string;
-  /**
-   * Their email; `schedule+<fn>@system.oxy` when {@link kind} is `"system"`; and
-   * **`null` for a frontline worker** — a crew member enrolled by PIN on a shared
-   * device has no mailbox, and the platform stores none rather than inventing
-   * one. That null is the one field that tells the crew from the office inside
-   * a function, because a worker can never hold org membership (see
-   * `orgRole`, which is absent for them too). Treat it as `string | null` in
-   * app logic; it was typed `string` before the crew existed.
-   */
-  email: string | null;
-  /**
-   * The org that owns this app — the tenant boundary for anything the function
-   * reads or writes.
-   *
-   * Servers before 2026-08-21 mistakenly sent this as `org_id`, so `orgId` read
-   * `undefined` there; both keys are populated now. If your function filters SQL
-   * on it, that is exactly the bug to re-check.
-   */
-  orgId: string;
-  /** Display name. Absent on a `"system"` invocation. User-controlled free text —
-   *  fine for a greeting or an audit row, never a key, and escape it before it
-   *  reaches HTML or SQL. */
-  name?: string;
-  /** Avatar URL. Absent when unset or on a `"system"` invocation. */
-  picture?: string;
-  /**
-   * The caller's role **within this app**, derived server-side from app
-   * membership (with org-owner / Oxy-staff break-glass). Absent when they hold
-   * no membership.
-   *
-   * This is the value to gate a privileged surface on — it cannot be forged by
-   * the client, unlike a query param or a client-side flag:
-   *
-   * ```ts
-   * if (ctx.user.appRole !== "admin") {
-   *   return Response.json({ error: "forbidden" }, { status: 403 });
-   * }
-   * ```
-   *
-   * Note it is deliberately NOT the org role: an app admin administers one app
-   * without holding org-Admin (which also carries billing and member management).
-   *
-   * A `"system"` invocation runs under the org owner, so this reads `"admin"`
-   * there — a schedule carries owner authority by construction. Add a
-   * {@link kind} check when a surface must be human-only.
-   */
-  appRole?: "admin" | "member";
-  /**
-   * The caller's role in the owning **org**. Absent when they reach the app
-   * without an org membership (Oxy staff on break-glass) or on a `"system"`
-   * invocation.
-   *
-   * Informational, not a gate — org standing and app standing are separate
-   * rings. Use it to explain ("ask your org admin to connect a warehouse"), to
-   * label, or to route; gate on {@link appRole}.
-   */
-  orgRole?: "owner" | "admin" | "member";
-  /**
-   * The org teams the caller belongs to, name-sorted, and scoped to this app's
-   * org — teams they hold in other orgs are never reported. Empty when they
-   * belong to none.
-   *
-   * Optional because a server older than 2026-08-21 does not send it: use
-   * `ctx.user.teams?.some(...)`, never `ctx.user.teams.some(...)`, or the
-   * function throws on that server rather than degrading.
-   *
-   * Useful for *shaping* a view (default the Finance team to the finance tab).
-   * Not a permission: a team only grants anything on an app through an app team
-   * grant, which is already folded into {@link appRole}. Gating on a team name
-   * invents a permission the platform cannot revoke.
-   */
-  teams?: OxyOrgTeam[];
-  /**
-   * Whether there is a caller to attribute this invocation to.
-   *
-   * On a current server this is exact — `ctx.user.kind === "system"` is the
-   * check.
-   *
-   * Optional for the same reason as {@link teams}: a server older than
-   * 2026-08-21 does not send it. Note there is no safe *inference* to fall back
-   * on, in either direction — `=== "system"` reads `false` for a cron tick, and
-   * `!== "user"` reads `true` for a real person. An older server genuinely
-   * cannot tell you.
-   *
-   * So if you must support one, don't infer: a schedule invokes the function
-   * with the `input` you configured on it, which is yours to mark.
-   *
-   * ```ts
-   * const body = JSON.parse(req.body || "{}");
-   * const isSystem = ctx.user.kind ? ctx.user.kind === "system" : body._trigger === "schedule";
-   * ```
-   */
-  kind?: OxyIdentityKind;
-}
-/** Result of a `ctx.fetch` call. */
-interface OxyFetchResult {
-  status: number;
-  /** Response body, decoded per the requested {@link OxyFetchInit.encoding}. */
-  body: string;
-  /** Echoes how `body` was encoded (`"utf8"` unless base64 was requested). */
-  encoding?: "utf8" | "base64";
-}
-/**
- * `init` for `ctx.fetch` — the standard `RequestInit` fields the host honours
- * (`method`, `headers`, `body`) plus how to decode the response.
- */
-type OxyFetchInit = RequestInit & {
-  /**
-   * How to decode the response body. `"utf8"` (default) is **lossy for
-   * binary** — every non-UTF-8 byte becomes U+FFFD, so a fetched PDF/PNG comes
-   * back corrupt. Pass `"base64"` for any binary response, e.g. to hand it
-   * straight to an email attachment.
-   */
-  encoding?: "utf8" | "base64";
-};
-/**
- * `ctx.warehouse.*` — one of the app's configured databases by name.
- *
- * The writes require the database in the function's `destinations` allowlist;
- * `query` does not, because that allowlist is about modifying a project's
- * warehouse, and a `postgres_managed` database resolves the read-only analyst
- * for every caller regardless.
- */
-interface OxyWarehouseApi {
-  /**
-   * Read from a named database.
-   *
-   * `ctx.query` only ever reaches the project's DEFAULT database, so this is
-   * how an app reads its own per-org OLTP store, which sits beside whatever
-   * warehouse the project analyses.
-   */
-  query(database: string, sql: string): Promise<{
-    rows: OxyFunctionRow[];
-    truncated: boolean;
-  }>;
-  insert(database: string, table: string, rows: OxyFunctionRow[]): Promise<unknown>;
-  exec(database: string, sql: string): Promise<unknown>;
-  upsert(database: string, table: string, rows: OxyFunctionRow[], conflictColumns: string[]): Promise<unknown>;
-}
-/**
- * The handle `ctx.tx` passes to your callback — a pinned connection with an
- * open transaction.
- *
- * Both methods take **bound parameters** (`$1`, `$2`, …). Never build SQL by
- * concatenating request data: `ctx.warehouse.exec` takes a bare string, but a
- * transaction exists for surfaces that accept end-user input, and placeholders
- * are the only thing that makes that safe.
- *
- * The handle is live only for the duration of the callback. Using it after the
- * callback returns throws — it is not a connection you can stash.
- */
-interface OxyTransaction {
-  /** Run a row-returning statement (including `INSERT … RETURNING`). */
-  query(sql: string, params?: unknown[]): Promise<OxyFunctionRow[]>;
-  /** Run a statement for its effect; resolves to the number of rows affected. */
-  exec(sql: string, params?: unknown[]): Promise<number>;
-}
-/**
- * `ctx.oltp` — read and WRITE the app's OWN per-org OLTP schema (`app_<writer>`)
- * on the managed Postgres tenant, and nothing else.
- *
- * This is the write half `ctx.warehouse` cannot give an app: for a
- * `postgres_managed` database `ctx.warehouse` resolves the read-only analyst
- * (org-wide read, the org's `raw_*` extracts included), so a write authenticates
- * and then fails `permission denied`. `ctx.oltp` resolves the app's **writer**
- * role instead — DML rights scoped to the one `app_<writer>` schema, so it is
- * narrower on reads (no `raw_*`) and finally writable.
- *
- * Gated by the fail-closed `oltp` manifest capability (`"oltp": { "enabled":
- * true }`) — a pure gate. The target schema is derived from the app's own slug
- * (`oltp-bookings` → `app_oltp_bookings`), never named in the manifest, so a
- * manifest cannot point `ctx.oltp` at another app's schema. The store must be
- * provisioned first (ask whoever operates the org). No database name is passed —
- * the app's own store is implicit.
- *
- * Both methods take **bound parameters** (`$1`, `$2`, …). Never build SQL by
- * concatenating request data — a booking form is exactly the surface that takes
- * end-user input, and placeholders are the only thing that makes it safe. Each
- * call auto-commits; a failed statement rolls back.
- *
- * **Cost:** each call opens its own connection to the tenant (a TCP + TLS
- * handshake, and a wake-up if the compute was idle) and its own transaction, so
- * a per-row loop pays that per row. Prefer one statement over many — a
- * multi-row `INSERT`, an `INSERT … SELECT`, or `INSERT … RETURNING` to avoid a
- * follow-up read — and reach for `ctx.oltp` a handful of times per request, not
- * in a hot loop.
- *
- * ```ts
- * const [row] = await ctx.oltp.query(
- *   "INSERT INTO bookings (name, party_size) VALUES ($1, $2) RETURNING id",
- *   [name, partySize],
- * );
- * ```
- */
-interface OxyOltpApi {
-  /** Run a row-returning statement (including `INSERT … RETURNING`). */
-  query(sql: string, params?: unknown[]): Promise<OxyFunctionRow[]>;
-  /** Run a statement for its effect; resolves to the number of rows affected. */
-  exec(sql: string, params?: unknown[]): Promise<number>;
-}
-/** `ctx.secrets` — write app-scoped secrets (gated by the `secrets.write` capability). */
-interface OxySecretsApi {
-  set(key: string, value: string): Promise<void>;
-}
-/** `ctx.semantic` — airlayer-compiled semantic queries (inherits the pre-agg fast path). */
-interface OxySemanticApi {
-  query(spec: Record<string, unknown>): Promise<unknown>;
-}
-/** `ctx.airway` — seed/await an Airway ELT pipeline run. */
-interface OxyAirwayApi {
-  run(pipelineRef: string, variables?: Record<string, unknown> | null): Promise<{
-    runId: string;
-  }>;
-}
-/**
- * Input to `ctx.email.send`. Platform-injected: the sender mailbox (`from`) is
- * platform-controlled and **not** an accepted field — passing it is a typed
- * error. Provide `html` and/or `text` as the body (render a template to HTML
- * with `render` from `@oxy-hq/sdk/email`).
- */
-interface EmailSendInput {
-  /** Recipient address(es). Required. */
-  to: string | string[];
-  /** CC address(es). */
-  cc?: string | string[];
-  /** BCC address(es). */
-  bcc?: string | string[];
-  /** Reply-To address — the only sender-identity field an author may set. */
-  replyTo?: string;
-  /** Subject line. Required. */
-  subject: string;
-  /** HTML body. Provide at least one of `html` / `text`. */
-  html?: string;
-  /** Plain-text body. Provide at least one of `html` / `text`. */
-  text?: string;
-  /**
-   * Optional idempotency key (≤256 chars). Accepted and validated in v1 but a
-   * no-op until the persisted idempotency table lands — adopt it now so
-   * background (retried) sends become exactly-once once it does.
-   */
-  idempotencyKey?: string;
-  /**
-   * Files to attach. Max 20 per send, and **10 MiB decoded in total** — SES
-   * caps a whole message near 40 MB, so for anything larger store the file with
-   * {@link OxyStorageApi} and email a presigned link instead of inlining it.
-   *
-   * `content` is base64 by default; for generated text set
-   * `encoding: "utf8"` and attach the string as-is.
-   */
-  attachments?: EmailAttachment[];
-}
-/** One attachment on {@link EmailSendInput}. */
-interface EmailAttachment {
-  /** Filename shown to the recipient. Required; path separators are stripped. */
-  filename: string;
-  /**
-   * File contents, interpreted per {@link EmailAttachment.encoding} — base64 by
-   * default, which is the only way binary crosses the isolate boundary.
-   */
-  content: string;
-  /**
-   * How `content` is encoded. Defaults to `"base64"`.
-   *
-   * Use `"utf8"` to attach text the function just generated (CSV, JSON, HTML)
-   * — it needs no encoder and is byte-exact for non-ASCII. `btoa` is the wrong
-   * tool there: it encodes U+0080..U+00FF as *Latin1*, so accented text comes
-   * out as mojibake rather than as an error. For binary, take base64 straight
-   * from the source — `ctx.storage.get(key, { encoding: "base64" })` or
-   * `ctx.fetch(url, { encoding: "base64" })` — or {@link bytesToBase64} for a
-   * `Uint8Array` you built yourself.
-   */
-  encoding?: "base64" | "utf8";
-  /** MIME type; defaults to `application/octet-stream`. */
-  contentType?: string;
-  /** Render inline (e.g. an image referenced as `cid:<contentId>`) instead of as a download. */
-  inline?: boolean;
-  /** Content-ID for an inline part, referenced from the HTML body as `cid:<contentId>`. */
-  contentId?: string;
-}
-/** Result of a successful `ctx.email.send`. */
-interface EmailSendResult {
-  /** Provider (SES) message id of the sent message. */
-  messageId: string;
-}
-/** `ctx.email` — send email (gated by the `email.send` capability). */
-interface OxyEmailApi {
-  send(input: EmailSendInput): Promise<EmailSendResult>;
-}
-/** Input to `ctx.storage.getUploadUrl`. */
-interface StorageUploadUrlInput {
-  /**
-   * Destination path inside the app's silo, e.g. `"uploads/q1-report.pdf"`.
-   * Segments are sanitized server-side and cannot escape the silo. Omit to use
-   * `filename`, which is placed under `uploads/`.
-   */
-  pathname?: string;
-  /** Shorthand for `pathname: "uploads/<filename>"`. */
-  filename?: string;
-  /** MIME type; bound into the presigned PUT signature. Inferred when omitted. */
-  contentType?: string;
-  /**
-   * Exact byte length of the upload, bound into the signature — S3 rejects a
-   * body of any other size. Capped by the server's upload ceiling (100 MiB by
-   * default).
-   */
-  contentLength: number;
-  /** Presign lifetime in seconds (default 900; max 604800 — SigV4's own limit). */
-  expiresInSeconds?: number;
-}
-/** A minted presigned upload. */
-interface StorageUploadUrl {
-  /** Presigned PUT — the browser uploads the file bytes directly to this URL. */
-  url: string;
-  /**
-   * The stored key. Record it (e.g. on a row in your warehouse) — it is how you
-   * fetch, list or link to the asset later. A random suffix is added so two
-   * people uploading `report.pdf` don't collide.
-   */
-  key: string;
-  /** ISO-8601 expiry of the presigned URL. */
-  expiresAt: string;
-  /**
-   * Retention tag for this key, present only when your app declares a matching
-   * `storage.retention` rule in `oxy-app.json` (e.g. `"oxy-ttl=30d"`).
-   *
-   * **When present, the upload MUST send it as the `x-amz-tagging` header** — it
-   * is bound into the signature, so omitting it fails the PUT with a signature
-   * mismatch rather than storing an untagged object:
-   *
-   * ```ts
-   * const { url, tagging } = await ctx.storage.getUploadUrl({ ... });
-   * await fetch(url, {
-   *   method: "PUT",
-   *   body: file,
-   *   headers: {
-   *     "Content-Type": file.type,
-   *     ...(tagging ? { "x-amz-tagging": tagging } : {}),
-   *   },
-   * });
-   * ```
-   *
-   * Signing it is deliberate: a browser that could drop the header could opt any
-   * upload out of the app's own retention policy.
-   */
-  tagging?: string;
-}
-/** A minted presigned download. */
-interface StorageDownloadUrl {
-  url: string;
-  expiresAt: string;
-}
-/** One asset in the app's silo. */
-interface StorageObject {
-  key: string;
-  size: number;
-  contentType?: string | null;
-  /** ISO-8601. */
-  lastModified?: string | null;
-}
-/** One page of {@link OxyStorageApi.list}. */
-interface StorageListPage {
-  objects: StorageObject[];
-  /** Pass back as `cursor` to fetch the next page; `null` when complete. */
-  cursor: string | null;
-  hasMore: boolean;
-}
-/** Options for {@link OxyStorageApi.put}. */
-interface StoragePutOptions {
-  /** MIME type. Inferred from the pathname's extension when omitted. */
-  contentType?: string;
-  /**
-   * How `body` is encoded. `"base64"` is what makes **binary** generated assets
-   * (PDF, PNG, Parquet) possible — a UTF-8 string would corrupt them.
-   */
-  encoding?: "utf8" | "base64";
-  /** Append a short random component before the extension to avoid collisions. */
-  addRandomSuffix?: boolean;
-  /**
-   * Replace an existing asset at this path. Defaults to `false` — writing over
-   * an asset by accident is worse than an error, so this is opt-in.
-   */
-  allowOverwrite?: boolean;
-  /** `Cache-Control: max-age=<seconds>` stored on the object. */
-  cacheControlMaxAge?: number;
-}
-/** Result of a `put` (and of `copy`). */
-interface StoragePutResult {
-  key: string;
-  size: number;
-  contentType: string;
-}
-/**
- * `ctx.storage` — this app's **asset store**, covering both kinds of file an app
- * produces, in one silo (`customer-app-storage/<app_id>/`):
- *
- * - **Uploaded** — a human picks a file; `getUploadUrl` mints a presigned PUT and
- *   the browser uploads **straight to S3**, so uploads aren't bounded by the
- *   request-body limit and the bytes never pass through your function.
- * - **Generated** — your function produces the file (a rendered PDF, a CSV
- *   export, a chart PNG) and writes it with `put`, using
- *   `{ encoding: "base64" }` for binary.
- *
- * Gated by the fail-closed `storage.read` / `storage.write` capabilities in
- * `oxy-app.json`. Every asset is private; reads are always presigned and
- * time-boxed. Keys are confined to your app — another app's key is rejected.
- *
- * ```ts
- * // Uploaded: mint a URL, browser PUTs to it, then record `key`.
- * const { url, key } = await ctx.storage.getUploadUrl({
- *   filename: "q1-report.pdf", contentType: "application/pdf", contentLength: size,
- * });
- *
- * // Generated: write a CSV your function just built.
- * const { key } = await ctx.storage.put("generated/jan.csv", csv);
- *
- * // Either way: email a link that outlives the request.
- * const { url: link } = await ctx.storage.getDownloadUrl(key, {
- *   expiresInSeconds: 604800, download: true,
- * });
- * ```
- */
-interface OxyStorageApi {
-  /** Mint a presigned PUT for a browser upload (requires `storage.write`). */
-  getUploadUrl(input: StorageUploadUrlInput): Promise<StorageUploadUrl>;
-  /**
-   * Mint a presigned GET (requires `storage.read`). `download: true` forces a
-   * save-as via `Content-Disposition`, which is what an emailed link wants.
-   */
-  getDownloadUrl(key: string, opts?: {
-    expiresInSeconds?: number;
-    download?: boolean;
-  }): Promise<StorageDownloadUrl>;
-  /**
-   * Write a generated asset (requires `storage.write`). Capped at 6 MiB — for
-   * anything larger, mint a presigned upload URL and stream to it.
-   */
-  put(pathname: string, body: string, opts?: StoragePutOptions): Promise<StoragePutResult>;
-  /** Read an asset back; `null` when absent (requires `storage.read`). */
-  get(key: string, opts?: {
-    encoding?: "utf8" | "base64";
-  }): Promise<{
-    body: string;
-    contentType: string | null;
-    size: number;
-    encoding: string;
-  } | null>;
-  /** Metadata without the body; `null` when absent (requires `storage.read`). */
-  head(key: string): Promise<StorageObject | null>;
-  /**
-   * One page of assets (requires `storage.read`). Paginated deliberately — pass
-   * the returned `cursor` back to walk a large silo without loading it all.
-   */
-  list(opts?: {
-    prefix?: string;
-    limit?: number;
-    cursor?: string;
-  }): Promise<StorageListPage>;
-  /**
-   * Delete one or many assets (requires `storage.write`). Idempotent — deleting
-   * an absent key is a no-op success. `deleted` is the number of keys **accepted**
-   * for deletion (an absent key counts too), not a count of keys that existed.
-   */
-  delete(keyOrKeys: string | string[]): Promise<{
-    deleted: number;
-  }>;
-  /** Server-side copy within the app's silo (requires `storage.write`). */
-  copy(fromKey: string, toPathname: string, opts?: {
-    allowOverwrite?: boolean;
-  }): Promise<StoragePutResult>;
-}
-/**
- * The data-plane context passed as the second argument to a function's default
- * export. Mirrors the host-assembled `ctx` (`__buildCtx` in `runtime.rs`);
- * every member is a host-provided async function bridged to a Rust backend.
- */
-interface OxyFunctionContext {
-  /** Invoking user (route) or system identity (schedule/airway). */
-  user: OxyFunctionUser;
-  /**
-   * The org's people directory. Requires `"org": { "read": true }` in this
-   * function's manifest entry — without it the call is rejected before any
-   * query reaches the database.
-   *
-   * For naming a person: an assignee, a roster entry, who submitted something.
-   * Returns a display name and a role, and deliberately **no email, no phone,
-   * no location**.
-   *
-   * Who is in it: **people who can reach this app**. Org members, plus frontline
-   * workers holding a grant on this app — `kind` tells them apart, so a caller
-   * that must not name a worker can refuse on the field rather than by
-   * convention. A worker's `role` is `null`: that vocabulary is org membership's
-   * and a worker has none.
-   *
-   * REQUIRED, like every sibling here — `oltp`, `secrets`, `email`, `storage`,
-   * `airway` are all gated and all declared required. The binding is
-   * unconditional: `__buildCtx` is a static string that attaches `org` whatever
-   * the manifest says, and the refusal lives in the op, not in the binding. An
-   * optional member would therefore be a lie in the other direction, and under
-   * `strict` it makes `ctx.org.people()` — the spelling in every doc here and
-   * the only one the host binds — fail with "possibly undefined".
-   */
-  org: {
-    people(): Promise<{
-      people: Array<{
-        id: string;
-        name: string;
-        /** The org role, or `null` for a frontline worker. */
-        role: string | null;
-        kind: "member" | "frontline";
-      }>;
-      total: number;
-    }>;
-  };
-  /** Read-only view of the app's configured secrets (project-scoped). */
-  env: Record<string, string>;
-  /** Structured per-invocation logging (captured + surfaced with the response). */
-  log(...args: unknown[]): void;
-  /** Read-only SQL (SELECT/WITH only), function-scoped row cap. Resolves to the rows. */
-  query(sql: string): Promise<OxyFunctionRow[]>;
-  /** Read-only SQL with a higher row cap, yielded to the caller in batches. */
-  queryStream(sql: string, opts?: {
-    batchSize?: number;
-  }): AsyncGenerator<OxyFunctionRow[], void, unknown>;
-  /**
-   * SSRF-allowlisted outbound HTTP with a response-size cap. Pass
-   * `{ encoding: "base64" }` for a binary response — the default UTF-8 decode
-   * corrupts it.
-   */
-  fetch(url: string, init?: OxyFetchInit): Promise<OxyFetchResult>;
-  warehouse: OxyWarehouseApi;
-  /**
-   * Run several statements atomically on one connection: commits when your
-   * callback resolves, rolls back when it throws, and rethrows your error
-   * either way. Resolves to whatever the callback returns.
-   *
-   * `database` must be in this function's manifest `destinations` — a
-   * transaction is a write, and the same fail-closed allowlist applies. Postgres
-   * only; other backends reject `ctx.tx` rather than faking it.
-   *
-   * **Do not catch a failed statement and return normally.** A statement the
-   * server rejects aborts the whole transaction, and `COMMIT` on an aborted
-   * transaction does not fail — Postgres applies nothing and reports success —
-   * so `ctx.tx` refuses to commit and throws instead, naming the statement that
-   * poisoned it. Let the error propagate.
-   *
-   * ```ts
-   * const orderId = await ctx.tx("appdb", async (tx) => {
-   *   const [{ id }] = await tx.query(
-   *     "INSERT INTO orders (table_no) VALUES ($1) RETURNING id",
-   *     [tableNo],
-   *   );
-   *   for (const it of items) {
-   *     await tx.exec(
-   *       "INSERT INTO order_items (order_id, sku, qty) VALUES ($1, $2, $3)",
-   *       [id, it.sku, it.qty],
-   *     );
-   *   }
-   *   return id;
-   * });
-   * ```
-   */
-  tx<T>(database: string, fn: (tx: OxyTransaction) => Promise<T> | T): Promise<T>;
-  /**
-   * Read/write the app's OWN per-org OLTP schema (derived from its slug). The
-   * write half `ctx.warehouse` cannot give an app on a managed database. Gated
-   * by the fail-closed `oltp` manifest capability (`{ enabled: true }`). See
-   * {@link OxyOltpApi}.
-   */
-  oltp: OxyOltpApi;
-  secrets: OxySecretsApi;
-  semantic: OxySemanticApi;
-  airway: OxyAirwayApi;
-  email: OxyEmailApi;
-  storage: OxyStorageApi;
-}
-/** Signature of a function's default export: `export default async (req, ctx) => Response`. */
-type OxyFunctionHandler = (req: OxyFunctionRequest, ctx: OxyFunctionContext) => Promise<Response> | Response;
-//#endregion
 //#region src/custom-app/inject.d.ts
 /**
  * Shape of `window.__OXY_APP__` written by oxy at serve time.
@@ -1432,12 +1078,48 @@ declare function useMetricTree(opts?: UseMetricTreeOpts): MetricTreeHookResult<M
  * measure" question. Pass `null` to stay idle until a measure is chosen.
  */
 declare function useSensitivity(measureId: string | null, opts?: EndpointOpts): MetricTreeHookResult<SensitivityResult>;
+interface UsePredictOpts extends EndpointOpts, PredictOptions {}
 /**
  * Propagate hypothetical `(measure, delta)` changes upward through the
  * tree and return the estimated impact on every downstream measure — a
  * pure metric-tree walk, no warehouse query. Pass `null` to stay idle.
+ *
+ * Because it is database-free it can only use the coefficients it is GIVEN.
+ * Without `opts.coefficients` from {@link useBaseline}, every driver edge
+ * whose `.view.yml` declares no `coefficient:` contributes nothing and its
+ * downstream measures are simply absent from `impacts` — no error, no
+ * refusal. Without `opts.values`, multiplicative component edges come back
+ * `unquantifiable` rather than sized.
  */
-declare function usePredict(changes: PredictChange[] | null, opts?: EndpointOpts): MetricTreeHookResult<PredictResult>;
+declare function usePredict(changes: PredictChange[] | null, opts?: UsePredictOpts): MetricTreeHookResult<PredictResult>;
+/**
+ * Value a scenario's starting point, and measure the coefficients it needs.
+ *
+ * Two warehouse reads: the current value of every node reachable from
+ * `request.roots`, and — for driver edges declaring no `coefficient:` — a fit
+ * over the window. Both are expensive, which is why they live here and not in
+ * {@link usePredict}: predict is database-free by design so it can re-run per
+ * keystroke, and it CANNOT measure a coefficient itself.
+ *
+ * That is the whole reason to call this. Feed `data.values` and `data.fitted`
+ * into `usePredict`; omit them and an undeclared edge propagates nothing.
+ * Pass `null` to stay idle until levers and a period are chosen.
+ */
+declare function useBaseline(request: BaselineRequest | null, opts?: EndpointOpts): MetricTreeHookResult<BaselineResponse>;
+/**
+ * Bucketed history for the levers and everything downstream, plus the forward
+ * curve the forecaster expects next — the scenario's time axis.
+ *
+ * One warehouse query, so it belongs on a window change, not on a lever edit.
+ * It returns the BASELINE curve only: the scenario's second curve is
+ * arithmetic over this and a `usePredict` result — a proportional shift
+ * landing `lag` buckets in — composed client-side precisely so editing a lever
+ * costs no query.
+ *
+ * Treat a series with a `refusal` as a stated absence: it must not render as a
+ * flat forward line. Pass `null` to stay idle.
+ */
+declare function useProjection(request: ProjectionRequest | null, opts?: EndpointOpts): MetricTreeHookResult<ProjectionResponse>;
 /**
  * Period-over-period root-cause decomposition: recursively splits the
  * target measure by components and dimensions until the move concentrates.
@@ -1523,6 +1205,16 @@ interface WorldModel {
 interface WmInstance {
   key: string;
   display: string;
+  /**
+   * The org location this instance is, when the entity is bound to the
+   * locations registry and the key is mapped; absent otherwise.
+   */
+  location?: {
+    id: string;
+    name: string;
+    kind?: string | null;
+    parent_id?: string | null;
+  };
 }
 interface WmInstancesResponse {
   total: number;
@@ -1609,6 +1301,14 @@ interface UseWorldModelInstancesOpts {
   /** Max rows to return (default 50 server-side). */
   limit?: number;
   enabled?: boolean;
+  /**
+   * `"reach"` — only the instances whose place the viewer reaches, filtered
+   * inside the scan so a page is a page of the right set. Needs the entity
+   * bound to the org's locations registry (refused otherwise); an instance
+   * whose key is unmapped is not in anyone's reach. The bundle's own app is
+   * sent along so app-admin standing counts.
+   */
+  scope?: "reach";
 }
 interface UseWorldModelInstancesResult {
   data: WmInstancesResponse | null;
@@ -1732,5 +1432,5 @@ declare function createWorldModel(projectId: string | null, fetcher: AppFetcher)
  */
 declare function useWorldModel(): WorldModelApi;
 //#endregion
-export { type AdditivityClass, type AgentArtifact, type AgentRunEvent, type AgentRunState, type AgentSqlArtifact, AnomaliesClient, type Anomaly, type AnomalyFilter, type AnomalySeverity, type AnomalyStatus, type AppFetcher, type BulkUpdateStatusResponse, type CustomAppDebugSnapshot, type CustomAppErrorReport, type DimensionOpportunity, type DistributionRequest, type DriverAttribution, type DriverConfidence, type DriverDirection, type DriverForm, type DriverStrength, type EdgeKind, type EmailAttachment, type EmailSendInput, type EmailSendResult, type ExpandedNode, type ExplainConfigOverride, type ExplainNode, type ExplainOptions, type ExplainOpts, type ExplainRequest, type ExplainResult, type ExplainSibling, type ExplainWarning, type FunctionError, type FunctionLog, type FunctionResult, type ListAnomaliesOptions, type ListAnomaliesResponse, type LoadManifestOptions, type MetricEdge, type MetricHandle, type MetricNode, type MetricScope, type MetricTree, MetricTreeClient, type MetricTreeHookResult, type OpportunityRequest, type OpportunityResult, type OxyAirwayApi, OxyAnswer, type OxyAnswerProps, OxyApiError, type OxyAppFunctionManifest, type OxyAppLogLevel, type OxyAppLogger, type OxyAppManifest, type OxyAppPerformanceManifest, OxyAppProvider, type OxyAppProviderProps, OxyChat, type OxyChatProps, type OxyEmailApi, type OxyFetchResult, type OxyFunctionContext, type OxyFunctionHandler, type OxyFunctionRequest, type OxyFunctionRow, type OxyFunctionUser, type OxyIdentityKind, type OxyInjectedAppConfig, type OxyOltpApi, type OxyOrgTeam, type OxySecretsApi, type OxySemanticApi, type OxyStorageApi, type OxyTransaction, type OxyWarehouseApi, type PredictChange, type PredictImpact, type PredictResult, type ProcedureProgress, type ProcedureResult, type ProcedureRunState, type ResolvedCustomAppManifest, type ScanFailure, type ScanOptions, type ScanResponse, type SegmentOpportunity, type SemanticArrayOp, type SemanticDateRangeOp, type SemanticFilter, type SemanticScalarOp, type SemanticTimeDimension, type SensitivityDriver, type SensitivityResult, type SizeOpts, type SkippedDimension, type SplitKind, type StorageDownloadUrl, type StorageListPage, type StorageObject, type StoragePutOptions, type StoragePutResult, type StorageUploadUrl, type StorageUploadUrlInput, type TimeDimensionsResponse, type UseAgentRunInput, type UseAgentRunResult, type UseFunctionResult, type UseMeasureBreakdownResult, type UseMetricTreeOpts, type UseProcedureRunInput, type UseProcedureRunOpts, type UseProcedureRunResult, type UseQueryInput, type UseQueryOpts, type UseQueryResult, type UseSemanticQueryInput, type UseSemanticQueryOpts, type UseSemanticQueryResult, type UseWorldModelGraphResult, type UseWorldModelInstancesOpts, type UseWorldModelInstancesResult, type WmBreakdownEdge, type WmBreakdownNode, type WmEntityCount, type WmFilterCountsResponse, type WmInstance, type WmInstancesResponse, type WmMeasureBreakdown, type WmMeasureBreakdownEvent, type WorldModel, type WorldModelApi, type WorldModelDimension, type WorldModelEdge, type WorldModelEntity, type WorldModelInducedMeasure, type WorldModelMeasure, WorldModelScopeUnsupportedError, _resetCustomAppManifestCacheForTest, apiErrorFromResponse, base64ToBytes, bytesToBase64, createWorldModel, getCustomAppDebug, getOxyAppLogger, interpretCustomAppError, loadCustomAppManifest, readInjectedAppConfig, readJsonSseStream, setOxyAppLogger, useAgentRun, useDistribution, useExplain, useFunction, useMeasureBreakdown, useMetricTree, useOpportunity, useOxyApp, usePredict, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useSensitivity, useTimeDimensions, useTrackEvent, useWorldModel, useWorldModelGraph, useWorldModelInstances };
+export { type AdditivityClass, type AgentArtifact, type AgentRunEvent, type AgentRunState, type AgentSqlArtifact, AnomaliesClient, type Anomaly, type AnomalyFilter, type AnomalySeverity, type AnomalyStatus, type AppFetcher, type BaselineInstance, type BaselineRequest, type BaselineResponse, type BulkUpdateStatusResponse, type CustomAppDebugSnapshot, type CustomAppErrorReport, type DimensionOpportunity, type DistributionRequest, type DriverAttribution, type DriverConfidence, type DriverDirection, type DriverForm, type DriverStrength, type EdgeKind, type EmailAttachment, type EmailSendInput, type EmailSendResult, type ExpandedNode, type ExplainConfigOverride, type ExplainNode, type ExplainOptions, type ExplainOpts, type ExplainRequest, type ExplainResult, type ExplainSibling, type ExplainWarning, type FittedDriver, type ForecastPoint, type FunctionError, type FunctionLog, type FunctionResult, type HistoryPoint, type ListAnomaliesOptions, type ListAnomaliesResponse, type LoadManifestOptions, type MeasureProjection, type MeasureValues, type MetricEdge, type MetricHandle, type MetricNode, type MetricScope, type MetricTree, MetricTreeClient, type MetricTreeHookResult, type OpportunityRequest, type OpportunityResult, type OxyAirwayApi, OxyAnswer, type OxyAnswerProps, OxyApiError, type OxyAppFunctionManifest, type OxyAppLogLevel, type OxyAppLogger, type OxyAppManifest, type OxyAppPerformanceManifest, OxyAppProvider, type OxyAppProviderProps, OxyChat, type OxyChatProps, type OxyEmailApi, type OxyFetchResult, type OxyFunctionContext, type OxyFunctionHandler, type OxyFunctionRequest, type OxyFunctionRow, type OxyFunctionUser, type OxyIdentityKind, type OxyInjectedAppConfig, type OxyOltpApi, type OxyOrgAssignment, type OxyOrgPlace, type OxyOrgTeam, type OxyReach, type OxySecretsApi, type OxySemanticApi, type OxyStorageApi, type OxyTransaction, type OxyWarehouseApi, type PredictChange, type PredictImpact, type PredictOptions, type PredictResult, type ProcedureProgress, type ProcedureResult, type ProcedureRunState, type ProjectionGranularity, type ProjectionRequest, type ProjectionResponse, type ResolvedCustomAppManifest, type ScanFailure, type ScanOptions, type ScanResponse, type SegmentOpportunity, type SemanticArrayOp, type SemanticDateRangeOp, type SemanticFilter, type SemanticScalarOp, type SemanticTimeDimension, type SensitivityDriver, type SensitivityResult, type SizeOpts, type SkippedDimension, type SplitKind, type StorageDownloadUrl, type StorageListPage, type StorageObject, type StoragePutOptions, type StoragePutResult, type StorageUploadUrl, type StorageUploadUrlInput, type TimeDimensionsResponse, type UnvaluedNode, type UseAgentRunInput, type UseAgentRunResult, type UseFunctionResult, type UseMeasureBreakdownResult, type UseMetricTreeOpts, type UsePredictOpts, type UseProcedureRunInput, type UseProcedureRunOpts, type UseProcedureRunResult, type UseQueryInput, type UseQueryOpts, type UseQueryResult, type UseSemanticQueryInput, type UseSemanticQueryOpts, type UseSemanticQueryResult, type UseWorldModelGraphResult, type UseWorldModelInstancesOpts, type UseWorldModelInstancesResult, type WmBreakdownEdge, type WmBreakdownNode, type WmEntityCount, type WmFilterCountsResponse, type WmInstance, type WmInstancesResponse, type WmMeasureBreakdown, type WmMeasureBreakdownEvent, type WorldModel, type WorldModelApi, type WorldModelDimension, type WorldModelEdge, type WorldModelEntity, type WorldModelInducedMeasure, type WorldModelMeasure, WorldModelScopeUnsupportedError, _resetCustomAppManifestCacheForTest, apiErrorFromResponse, base64ToBytes, bytesToBase64, createWorldModel, getCustomAppDebug, getOxyAppLogger, interpretCustomAppError, loadCustomAppManifest, readInjectedAppConfig, readJsonSseStream, setOxyAppLogger, useAgentRun, useBaseline, useDistribution, useExplain, useFunction, useMeasureBreakdown, useMetricTree, useOpportunity, useOxyApp, usePredict, useProcedureRun, useProjection, useQuery, useResolvedManifest, useSemanticQuery, useSensitivity, useTimeDimensions, useTrackEvent, useWorldModel, useWorldModelGraph, useWorldModelInstances };
 //# sourceMappingURL=index.d.mts.map