@snaptrude/plugin-core 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -35,6 +35,7 @@
     "test": "node --test test/*.test.mjs",
     "generate:manifest": "node scripts/generate-manifest.mjs",
     "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
-    "generate:manifest:all": "node scripts/generate-manifest.mjs --all"
+    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
+    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
   }
 }

package/scripts/generate-manifest.mjs

@@ -45,6 +45,43 @@ function examplePromptsOf(jsDoc) {
     .filter(Boolean)
 }
 
+/**
+ * The single `@performance` note on a method's JSDoc, if any.
+ *
+ * A short throughput hint the discovery layer surfaces so a code generator picks
+ * the bulk/array API over a per-item loop (each API call is one host round-trip).
+ * Authored on the plural/array methods; absent on everything else (the field is
+ * omitted from the manifest entry entirely when there is no tag, to keep the diff
+ * — and the LLM's attention — on the methods where it matters).
+ */
+function performanceOf(jsDoc) {
+  if (!jsDoc) return ""
+  const tag = jsDoc.getTags().find((t) => t.getTagName() === "performance")
+  return (tag?.getCommentText() ?? "").replace(/\s+/g, " ").trim()
+}
+
+/**
+ * The `@deprecated` marker for a method, or "" when the method is not deprecated.
+ *
+ * When the tag text names a replacement API as a dotted path — conventionally in
+ * backticks, e.g. `` `core.handles.release([profile])` `` — we surface just that
+ * path (call/array suffix stripped) so the discovery layer can point callers
+ * straight at the successor. Otherwise we fall back to the tag's prose, or `true`
+ * when the tag carries no comment. Methods with no `@deprecated` tag return "" and
+ * get NO key in the manifest (the spread of "" is dropped), keeping the diff lean.
+ */
+function deprecatedOf(jsDoc) {
+  if (!jsDoc) return ""
+  const tag = jsDoc.getTags().find((t) => t.getTagName() === "deprecated")
+  if (!tag) return ""
+  const text = (tag.getCommentText() ?? "").replace(/\s+/g, " ").trim()
+  for (const span of text.match(/`[^`]+`/g) ?? []) {
+    const path = span.match(/[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+/)
+    if (path) return path[0]
+  }
+  return text || true
+}
+
 /** Strip the `PluginApiReturn<...>` wrapper to the inner result type text. */
 function unwrapReturn(text) {
   if (!text) return "void"
@@ -83,6 +120,8 @@ export function buildManifest({ includeOptional = false } = {}) {
       const name = method.getName()
       const jsDoc = method.getJsDocs().at(-1) ?? null
       const param = method.getParameters()[0]
+      const performance = performanceOf(jsDoc)
+      const deprecated = deprecatedOf(jsDoc)
       leaves.push({
         path: `${pathPrefix}${name}`,
         namespace: pathPrefix.replace(/\.$/, ""),
@@ -90,6 +129,8 @@ export function buildManifest({ includeOptional = false } = {}) {
         examplePrompts: examplePromptsOf(jsDoc),
         argsType: param?.getTypeNode()?.getText() ?? null,
         resultType: unwrapReturn(method.getReturnTypeNode()?.getText()),
+        ...(performance ? { performance } : {}),
+        ...(deprecated ? { deprecated } : {}),
       })
     }
 
@@ -117,6 +158,8 @@ export function buildManifest({ includeOptional = false } = {}) {
         // An optional author-ahead leaf, written as a function-property.
         const jsDoc = prop.getJsDocs().at(-1) ?? null
         const param = typeNode.getParameters()[0]
+        const performance = performanceOf(jsDoc)
+        const deprecated = deprecatedOf(jsDoc)
         leaves.push({
           path: `${pathPrefix}${prop.getName()}`,
           namespace: pathPrefix.replace(/\.$/, ""),
@@ -124,6 +167,8 @@ export function buildManifest({ includeOptional = false } = {}) {
           examplePrompts: examplePromptsOf(jsDoc),
           argsType: param?.getTypeNode()?.getText() ?? null,
           resultType: unwrapReturn(typeNode.getReturnTypeNode()?.getText()),
+          ...(performance ? { performance } : {}),
+          ...(deprecated ? { deprecated } : {}),
         })
       }
     }

package/src/api/analysis/daylight.ts

@@ -0,0 +1,470 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginWeatherSourceMeta } from "./weather"
+
+/**
+ * Analysis daylight — standards-grade annual daylight metrics (IES LM-83).
+ *
+ * Runs an annual daylight simulation over per-space sensor grids and returns
+ * **numeric** per-sensor and aggregate metrics — no textures, no heatmap, no
+ * model mutation. Two metrics are supported: **ASE** (Annual Sunlight
+ * Exposure) and **sDA** (Spatial Daylight Autonomy, sDA300/50%).
+ *
+ * **Run semantics.** `metrics: ["ASE"]` runs **synchronously** — `compute`
+ * returns the full result directly, no `runId`. Any request including
+ * `"sDA"` (alone or with ASE) runs **asynchronously**: `compute` submits the
+ * job and immediately returns `{ status: "running", runId, sensors: [],
+ * aggregates: [] }`; call {@linkcode PluginAnalysisDaylightApi.poll} with the
+ * `runId` until `status` is `"complete"` (or `"failed"`).
+ *
+ * **Blind operation.** sDA is computed WITH dynamic blind operation per the
+ * IES LM-83 2% rule: windows are grouped by storey + facade orientation, and
+ * for every occupied hour blind groups close (default 5% diffuse
+ * transmittance) until no more than 2% of the analysis points receive direct
+ * sun. This API **operates the blinds for you** — sDA without blind operation
+ * is not LM-83-compliant, so there is no switch to turn it off. The run's
+ * `provenance.blinds` reports the groups, their closed hours, and any hours
+ * where no combination satisfies the rule.
+ *
+ * **Surface optics.** The optional `optics` arg overrides surface optics.
+ * Resolution order per surface: per-material (`optics.materials`, keyed by
+ * material **name** as shown in Snaptrude) → per-category
+ * (`optics.categories`) → LM-83/convention defaults:
+ *
+ * | Category | Default | Property |
+ * |---|---|---|
+ * | `wall` | `0.5` | reflectance |
+ * | `ceiling` | `0.7` | reflectance |
+ * | `floor` | `0.2` | reflectance |
+ * | `furniture` | `0.5` | reflectance |
+ * | `glazing` | `0.65` | transmittance (Tvis) |
+ * | `context` | `0.2` | reflectance |
+ * | blinds (closed) | `0.05` | diffuse transmittance |
+ *
+ * Glazing takes visible **transmittance** (Tvis) exactly as manufacturers
+ * quote it; the backend converts it to Radiance glass transmissivity
+ * internally.
+ *
+ * Every result carries a full `provenance` echo (weather file, thresholds,
+ * grid, location, resolved optics, blind operation, warnings, excluded
+ * spaces) plus `modelRevision` + `inputHash` for staleness. Positions are
+ * **world plan-space** coordinates.
+ *
+ * `compute` is write-gated and Pro-gated host-side, exactly like
+ * {@linkcode PluginAnalysisIlluminanceApi.compute}.
+ *
+ * Accessed via `snaptrude.analysis.daylight`.
+ */
+export abstract class PluginAnalysisDaylightApi {
+  constructor() {}
+
+  /**
+   * Compute annual daylight metrics for the model's spaces.
+   *
+   * Sensors are laid out per-space from the `grid` spec; request the metrics
+   * you want in `metrics` (`["ASE"]`, `["sDA"]`, or both). ASE-only runs are
+   * **synchronous** and return the full result directly. Any run including
+   * `"sDA"` is **asynchronous**: this returns `{ status: "running", runId,
+   * sensors: [], aggregates: [] }` immediately — pass the `runId` to
+   * {@linkcode PluginAnalysisDaylightApi.poll} until the run completes.
+   * sDA is computed with LM-83 dynamic blind operation (see the class doc);
+   * pass `optics` to override surface reflectances / glazing transmittance.
+   *
+   * @param args - {@linkcode PluginDaylightComputeArgs}: the `standard`
+   *   (`"IES-LM-83-23"`), the `metrics` to compute, an optional occupancy
+   *   `schedule`, optional surface `optics` overrides, and the sensor `grid`
+   *   spec.
+   * @returns A {@linkcode PluginDaylightResults} — per-sensor `sensors`,
+   *   scope-rolled `aggregates`, the full `provenance` echo, `nextCursor`
+   *   (`null` when all sensors fit in one page), and `runId` on
+   *   asynchronous (sDA) runs.
+   * @throws When the workspace is not on a **Pro** plan.
+   * @throws When plugin writes are disabled.
+   * @throws When the project has no geo-located site (no location to compute
+   *   daylight for) or no spaces to analyse.
+   *
+   * @examplePrompt Run an LM-83 ASE daylight analysis on all my spaces
+   * @examplePrompt Which rooms fail annual sunlight exposure?
+   * @examplePrompt Compute ASE with a 0.6m sensor grid at desk height
+   * @examplePrompt Run an LM-83 sDA analysis with blinds operated
+   * @examplePrompt Which spaces meet sDA300/50%?
+   * @examplePrompt Compute sDA with 70% reflective ceilings and Tvis 0.6 glazing
+   *
+   * # Example
+   * ```ts
+   * let res = await snaptrude.analysis.daylight.compute({
+   *   standard: "IES-LM-83-23",
+   *   metrics: ["sDA", "ASE"],
+   *   grid: { spacingM: 0.6, workplaneHeightM: 0.76, boundaryOffsetM: 0.5 },
+   *   optics: { materials: { "Glass - Clear": { transmittance: 0.6 } } },
+   * })
+   * const runId = res.runId
+   * while (res.status === "running" && runId) {
+   *   await new Promise((r) => setTimeout(r, 5000))
+   *   res = await snaptrude.analysis.daylight.poll({ runId })
+   * }
+   * const failing = res.aggregates.filter(
+   *   (a) => a.scope === "space" && (a.sdaPercent ?? 0) < 55,
+   * )
+   * ```
+   */
+  public abstract compute(
+    args: PluginDaylightComputeArgs,
+  ): PluginApiReturn<PluginDaylightResults>
+
+  /**
+   * Poll an asynchronous daylight run started by
+   * {@linkcode PluginAnalysisDaylightApi.compute}.
+   *
+   * Returns the same {@linkcode PluginDaylightResults} shape as `compute`:
+   * `status: "running"` while the job is in flight (empty `sensors` /
+   * `aggregates`), `"complete"` with the full data once done. Poll every few
+   * seconds — an annual sDA simulation takes minutes, not milliseconds.
+   * Completed results page sensors exactly like a synchronous run: follow
+   * `nextCursor` via the `cursor` arg.
+   *
+   * @param args - {@linkcode PluginDaylightPollArgs}: the `runId` returned by
+   *   `compute`, plus an optional sensor-page `cursor`.
+   * @returns A {@linkcode PluginDaylightResults} for the run.
+   * @throws When the `runId` is unknown, or when the run failed (surfaced as
+   *   a typed `OPERATION_FAILED`).
+   *
+   * @examplePrompt Check whether my sDA run has finished
+   * @examplePrompt Get the results of the daylight run
+   */
+  public abstract poll(
+    args: PluginDaylightPollArgs,
+  ): PluginApiReturn<PluginDaylightResults>
+}
+
+/**
+ * A daylight metric to compute. `"ASE"` (Annual Sunlight Exposure) runs
+ * synchronously; any request including `"sDA"` (Spatial Daylight Autonomy,
+ * sDA300/50% with LM-83 dynamic blind operation) runs asynchronously —
+ * `compute` returns a `runId` to pass to
+ * {@linkcode PluginAnalysisDaylightApi.poll}.
+ */
+export const PluginDaylightMetric = z.enum(["ASE", "sDA"])
+export type PluginDaylightMetric = z.infer<typeof PluginDaylightMetric>
+
+/**
+ * Status of a daylight run. ASE-only runs are synchronous, so their result is
+ * `"complete"`; runs including sDA return `"running"` from `compute` and
+ * progress to `"complete"` (or `"failed"`) via
+ * {@linkcode PluginAnalysisDaylightApi.poll}.
+ */
+export const PluginDaylightRunStatus = z.enum([
+  "running",
+  "complete",
+  "cancelled",
+  "failed",
+])
+export type PluginDaylightRunStatus = z.infer<typeof PluginDaylightRunStatus>
+
+/**
+ * Sensor-grid spec: spacing, workplane height, and boundary inset (all metres).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacingM` | `number` | Sensor spacing |
+ * | `workplaneHeightM` | `number` | Sensor height above the floor |
+ * | `boundaryOffsetM` | `number` | Inset from the space boundary |
+ */
+export const PluginDaylightGrid = z.object({
+  spacingM: z.number(),
+  workplaneHeightM: z.number(),
+  boundaryOffsetM: z.number(),
+})
+export type PluginDaylightGrid = z.infer<typeof PluginDaylightGrid>
+
+/**
+ * Optional occupancy schedule (local hours). Defaults to the LM-83 default
+ * (8am–6pm) when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `startHour` | `number` | Occupied-period start hour, local (`0`..`24`) |
+ * | `endHour` | `number` | Occupied-period end hour, local (`0`..`24`) |
+ */
+export const PluginDaylightSchedule = z.object({
+  startHour: z.number(),
+  endHour: z.number(),
+})
+export type PluginDaylightSchedule = z.infer<typeof PluginDaylightSchedule>
+
+/**
+ * Opaque surface optics: visible reflectance (`0`..`1`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `reflectance` | `number` | Visible reflectance (`0`..`1`) |
+ */
+export const PluginDaylightOpaqueOptics = z.object({
+  reflectance: z.number().min(0).max(1),
+})
+export type PluginDaylightOpaqueOptics = z.infer<
+  typeof PluginDaylightOpaqueOptics
+>
+
+/**
+ * Glazing optics: visible **transmittance** (Tvis, `0`..`1`) exactly as
+ * manufacturers quote it. The backend converts it to Radiance glass
+ * transmissivity internally — never pre-convert.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `transmittance` | `number` | Visible transmittance Tvis (`0`..`1`) |
+ */
+export const PluginDaylightGlazingOptics = z.object({
+  transmittance: z.number().min(0).max(1),
+})
+export type PluginDaylightGlazingOptics = z.infer<
+  typeof PluginDaylightGlazingOptics
+>
+
+/**
+ * Optics for one material: {@linkcode PluginDaylightOpaqueOptics}
+ * (`reflectance`) for opaque surfaces, or
+ * {@linkcode PluginDaylightGlazingOptics} (`transmittance`) for glazing.
+ */
+export const PluginDaylightMaterialOptics = z.union([
+  PluginDaylightOpaqueOptics,
+  PluginDaylightGlazingOptics,
+])
+export type PluginDaylightMaterialOptics = z.infer<
+  typeof PluginDaylightMaterialOptics
+>
+
+/**
+ * Per-category optics overrides. Categories cover every surface in the
+ * model; omitted categories use the LM-83/convention defaults (wall `0.5`,
+ * ceiling `0.7`, floor `0.2`, furniture `0.5`, glazing Tvis `0.65`,
+ * context `0.2`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `wall` | {@linkcode PluginDaylightOpaqueOptics}? | Walls, columns, beams, doors, frames (default `0.5`) |
+ * | `ceiling` | {@linkcode PluginDaylightOpaqueOptics}? | Down-facing slab faces (default `0.7`) |
+ * | `floor` | {@linkcode PluginDaylightOpaqueOptics}? | Up-facing slab faces (default `0.2`) |
+ * | `furniture` | {@linkcode PluginDaylightOpaqueOptics}? | Furniture (default `0.5`) |
+ * | `glazing` | {@linkcode PluginDaylightGlazingOptics}? | Window/door glass (default Tvis `0.65`) |
+ * | `context` | {@linkcode PluginDaylightOpaqueOptics}? | Terrain / context masses (default `0.2`) |
+ */
+export const PluginDaylightCategoryDefaults = z.object({
+  wall: PluginDaylightOpaqueOptics.optional(),
+  ceiling: PluginDaylightOpaqueOptics.optional(),
+  floor: PluginDaylightOpaqueOptics.optional(),
+  furniture: PluginDaylightOpaqueOptics.optional(),
+  glazing: PluginDaylightGlazingOptics.optional(),
+  context: PluginDaylightOpaqueOptics.optional(),
+})
+export type PluginDaylightCategoryDefaults = z.infer<
+  typeof PluginDaylightCategoryDefaults
+>
+
+/**
+ * Closed-blind optics: diffuse transmittance of the closed state. Defaults to
+ * the LM-83 `0.05` (5% diffuse) when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `transmittance` | `number` | Closed-blind diffuse transmittance (`0`..`1`) |
+ */
+export const PluginDaylightBlindsOptics = z.object({
+  transmittance: z.number().min(0).max(1),
+})
+export type PluginDaylightBlindsOptics = z.infer<
+  typeof PluginDaylightBlindsOptics
+>
+
+/**
+ * Surface-optics overrides for a daylight run. Resolution order per surface:
+ * `materials` (by material name) → `categories` → LM-83/convention defaults.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `materials` | `Record<string,` {@linkcode PluginDaylightMaterialOptics}`>`? | Keyed by material **name** as shown in Snaptrude (the same names `design.query.geometry.getTriangulatedMeshes` returns in `materialIds`); applies wherever the material appears and wins over category defaults |
+ * | `categories` | {@linkcode PluginDaylightCategoryDefaults}? | Per-category defaults override |
+ * | `blinds` | {@linkcode PluginDaylightBlindsOptics}? | Closed-blind state (default `0.05` diffuse) |
+ */
+export const PluginDaylightOptics = z.object({
+  materials: z.record(z.string(), PluginDaylightMaterialOptics).optional(),
+  categories: PluginDaylightCategoryDefaults.optional(),
+  blinds: PluginDaylightBlindsOptics.optional(),
+})
+export type PluginDaylightOptics = z.infer<typeof PluginDaylightOptics>
+
+/**
+ * Arguments for {@linkcode PluginAnalysisDaylightApi.compute}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `standard` | `"IES-LM-83-23"` | Daylight standard; only supported value |
+ * | `metrics` | {@linkcode PluginDaylightMetric}`[]` | Metrics to compute (`["ASE"]` synchronous; including `"sDA"` asynchronous) |
+ * | `schedule` | {@linkcode PluginDaylightSchedule}? | Occupancy hours (default 8am–6pm) |
+ * | `grid` | {@linkcode PluginDaylightGrid} | Sensor-grid spec |
+ * | `optics` | {@linkcode PluginDaylightOptics}? | Surface-optics overrides (per-material → per-category → LM-83 defaults) |
+ */
+export const PluginDaylightComputeArgs = z.object({
+  standard: z.literal("IES-LM-83-23"),
+  metrics: z.array(PluginDaylightMetric).min(1),
+  schedule: PluginDaylightSchedule.optional(),
+  grid: PluginDaylightGrid,
+  optics: PluginDaylightOptics.optional(),
+})
+export type PluginDaylightComputeArgs = z.infer<
+  typeof PluginDaylightComputeArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginAnalysisDaylightApi.poll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `runId` | `string` | The run id returned by `compute` |
+ * | `cursor` | `string`? | Sensor-page cursor from a previous page's `nextCursor` |
+ */
+export const PluginDaylightPollArgs = z.object({
+  runId: z.string(),
+  cursor: z.string().optional(),
+})
+export type PluginDaylightPollArgs = z.infer<typeof PluginDaylightPollArgs>
+
+/**
+ * One sensor's record. Positions are world plan-space `[x, y, z]`. Metric
+ * fields are present when the corresponding metric was requested: the ASE
+ * pair for `"ASE"`, `da300Percent`/`sdaPass` for `"sDA"`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sensorId` | `string` | Sensor id |
+ * | `position` | `[number, number, number]` | World plan-space `[x, y, z]` |
+ * | `spaceId` | `string` | `ComponentHandle` id of the containing space |
+ * | `storeyId` | `string` | Storey the sensor is on |
+ * | `areaWeightM2` | `number` | Floor area this sensor represents (m²) |
+ * | `occupiedHours` | `number` | Occupied hours per the schedule |
+ * | `directSunHoursAtOrAbove1000Lux` | `number`? | ASE numerator (shades ignored per LM-83); present when ASE requested |
+ * | `aseFail` | `boolean`? | Direct-sun hours > 250 (fails ASE); present when ASE requested |
+ * | `da300Percent` | `number`? | % of occupied hours at or above 300 lux, blinds operated; present when sDA requested |
+ * | `sdaPass` | `boolean`? | `da300Percent >= 50`; present when sDA requested |
+ */
+export const PluginDaylightSensorRecord = z.object({
+  sensorId: z.string(),
+  position: z.tuple([z.number(), z.number(), z.number()]),
+  spaceId: z.string(),
+  storeyId: z.string(),
+  areaWeightM2: z.number(),
+  occupiedHours: z.number(),
+  directSunHoursAtOrAbove1000Lux: z.number().optional(),
+  aseFail: z.boolean().optional(),
+  da300Percent: z.number().optional(),
+  sdaPass: z.boolean().optional(),
+})
+export type PluginDaylightSensorRecord = z.infer<
+  typeof PluginDaylightSensorRecord
+>
+
+/**
+ * Scope of a rolled-up aggregate.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `"project"` | Whole project (aggregate `id` is `null`) |
+ * | `"storey"` | One storey (`id` = storey id) |
+ * | `"space"` | One space (`id` = space `ComponentHandle` id) |
+ */
+export const PluginDaylightAggregateScope = z.enum([
+  "project",
+  "storey",
+  "space",
+])
+export type PluginDaylightAggregateScope = z.infer<
+  typeof PluginDaylightAggregateScope
+>
+
+/**
+ * An area-weighted rollup for a scope. Metric fields are present when the
+ * corresponding metric was requested.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `scope` | {@linkcode PluginDaylightAggregateScope} | `"project"` \| `"storey"` \| `"space"` |
+ * | `id` | `string \| null` | Scope id; `null` for project scope |
+ * | `analysisAreaM2` | `number` | Analysed floor area (m²) |
+ * | `asePercent` | `number`? | Area-weighted % of the analysis area failing ASE; present when ASE requested |
+ * | `sdaPercent` | `number`? | Area-weighted % of the analysis area passing sDA300/50%; present when sDA requested |
+ */
+export const PluginDaylightAggregate = z.object({
+  scope: PluginDaylightAggregateScope,
+  id: z.string().nullable(),
+  analysisAreaM2: z.number(),
+  asePercent: z.number().optional(),
+  sdaPercent: z.number().optional(),
+})
+export type PluginDaylightAggregate = z.infer<typeof PluginDaylightAggregate>
+
+/**
+ * Full provenance echo of a daylight run — a **loose** record: the known keys
+ * below are typed (all optional), and any additional backend-supplied keys pass
+ * through unmodified. `weather` is the resolved {@linkcode PluginWeatherSourceMeta}
+ * (or `null`); `surfaceReflectances` maps material/family-default key →
+ * reflectance so callers can tell per-material values from defaults.
+ */
+export const PluginDaylightProvenance = z
+  .object({
+    engine: z.string(),
+    engineVersion: z.string(),
+    standardProfile: z.string(),
+    thresholds: z
+      .object({ aseLux: z.number(), aseHours: z.number() })
+      .passthrough(),
+    weather: PluginWeatherSourceMeta.nullable(),
+    occupancySchedule: z
+      .object({ id: z.string(), hoursPerYear: z.number() })
+      .passthrough(),
+    grid: PluginDaylightGrid,
+    location: z
+      .object({
+        latitude: z.number(),
+        longitude: z.number(),
+        timezone: z.string(),
+        trueNorthDeg: z.number(),
+      })
+      .passthrough(),
+    surfaceReflectances: z.record(z.string(), z.number()),
+    modelRevision: z.string(),
+    inputHash: z.string(),
+    warnings: z.array(z.string()),
+    excludedSpaces: z.array(
+      z.object({ spaceId: z.string(), reason: z.string() }),
+    ),
+    failedGeometry: z.array(
+      z.object({ componentId: z.string(), reason: z.string() }),
+    ),
+  })
+  .partial()
+  .passthrough()
+export type PluginDaylightProvenance = z.infer<typeof PluginDaylightProvenance>
+
+/**
+ * Result of {@linkcode PluginAnalysisDaylightApi.compute} and
+ * {@linkcode PluginAnalysisDaylightApi.poll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `status` | {@linkcode PluginDaylightRunStatus} | `"complete"` on synchronous (ASE-only) runs; `"running"` then `"complete"`/`"failed"` on sDA runs |
+ * | `runId` | `string`? | Run id for {@linkcode PluginAnalysisDaylightApi.poll}; present on asynchronous (sDA) runs |
+ * | `sensors` | {@linkcode PluginDaylightSensorRecord}`[]` | Per-sensor records (paged; empty while `"running"`) |
+ * | `aggregates` | {@linkcode PluginDaylightAggregate}`[]` | Scope rollups (all scopes, not paged; empty while `"running"`) |
+ * | `provenance` | {@linkcode PluginDaylightProvenance} | Full run provenance echo |
+ * | `nextCursor` | `string \| null` | Next sensor page cursor; `null` = last page |
+ */
+export const PluginDaylightResults = z.object({
+  status: PluginDaylightRunStatus,
+  runId: z.string().optional(),
+  sensors: z.array(PluginDaylightSensorRecord),
+  aggregates: z.array(PluginDaylightAggregate),
+  provenance: PluginDaylightProvenance,
+  nextCursor: z.string().nullable(),
+})
+export type PluginDaylightResults = z.infer<typeof PluginDaylightResults>