@trigger.dev/core 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/dist/esm/v3/schemas/queues.js

@@ -0,0 +1,245 @@
+import { z } from "zod/v4";
+import { discriminatedUnion, preprocess } from "../utils/zod.js";
+const queueTypes = ["task", "custom"];
+/**
+ * The type of queue, either "task" or "custom"
+ * "task" are created automatically for each task.
+ * "custom" are created by you explicitly in your code.
+ * */
+export const QueueType = z.enum(queueTypes);
+export const RetrieveQueueType = z.enum([...queueTypes, "id"]);
+const QueueItemCommon = {
+    /** The queue id, e.g. queue_12345 */
+    id: z.string(),
+    /** The queue name */
+    name: z.string(),
+    /**
+     * The queue type, either "task" or "custom"
+     * "task" are created automatically for each task.
+     * "custom" are created by you explicitly in your code.
+     * */
+    type: QueueType,
+    /** The number of runs currently running */
+    running: z.number(),
+    /** The number of runs currently queued */
+    queued: z.number(),
+    /** Whether the queue is paused. If it's paused, no new runs will be started. */
+    paused: z.boolean(),
+    /**
+     * The queue's own concurrency limit. Meaningful on V1 queues only; always
+     * null on V2 queues (kept on both so existing clients keep parsing).
+     */
+    concurrencyLimit: z.number().nullable(),
+};
+/**
+ * The queue's `version` discriminates its shape. V1 queues carry their own
+ * concurrency limit (applied per key when runs pass a `concurrencyKey`, to the
+ * whole queue when they don't) and its override state. V2 queues are only the
+ * line runs wait in: concurrency is declared with the task `concurrency`
+ * option and read or overridden through `concurrencyLimits`. A response from a
+ * server that predates the discriminator has V1 semantics by definition, so a
+ * missing `version` defaults to "V1" rather than failing the parse.
+ */
+const QueueItemUnion = discriminatedUnion("version", [
+    z.object({
+        ...QueueItemCommon,
+        version: z.literal("V1"),
+        /** The queue's concurrency limit override state */
+        concurrency: z
+            .object({
+            /** The effective/current concurrency limit */
+            current: z.number().nullable(),
+            /** The base concurrency limit (default) */
+            base: z.number().nullable(),
+            /** The overridden concurrency limit, when an override is active */
+            override: z.number().nullable(),
+            /** When the override was applied */
+            overriddenAt: z.coerce.date().nullable(),
+            /** Who overrode the concurrency limit (will be null if overridden via the API) */
+            overriddenBy: z.string().nullable(),
+        })
+            .optional(),
+    }),
+    z.object({
+        ...QueueItemCommon,
+        version: z.literal("V2"),
+        /** Never present on V2 queues; declared so existing `queue.concurrency?.…`
+         * reads keep compiling across the union and see undefined. */
+        concurrency: z.undefined().optional(),
+    }),
+]);
+export const QueueItem = preprocess((value) => value && typeof value === "object" && !("version" in value)
+    ? { ...value, version: "V1" }
+    : value, QueueItemUnion);
+export const ListQueueOptions = z.object({
+    /** The page number */
+    page: z.number().optional(),
+    /** The number of queues per page */
+    perPage: z.number().optional(),
+});
+export const QueueTypeName = z.object({
+    /** "task" or "custom" */
+    type: QueueType,
+    /** The name of your queue.
+     * For "task" type it will be the task id, for "custom" it will be the name you specified.
+     * */
+    name: z.string(),
+});
+/**
+ * When retrieving a queue you can either use the queue id,
+ * or the type and name.
+ *
+ * @example
+ *
+ * ```ts
+ * // Use a queue id (they start with queue_
+ * const q1 = await queues.retrieve("queue_12345");
+ *
+ * // Or use the type and name
+ * // The default queue for your "my-task-id"
+ * const q2 = await queues.retrieve({ type: "task", name: "my-task-id"});
+ *
+ * // The custom queue you defined in your code
+ * const q3 = await queues.retrieve({ type: "custom", name: "my-custom-queue" });
+ * ```
+ */
+export const RetrieveQueueParam = z.union([z.string(), QueueTypeName]);
+/** One bound of a concurrency limit: the enforced value, the declared base, and
+ * any active override. `current` is the cap this bound enforces right now (the
+ * stored value clamped to the environment concurrency limit). Pausing an
+ * environment or queue stops dequeues without changing its configured bounds,
+ * so pause state is reported separately, never as a `current` of 0. */
+export const ConcurrencyLimitBound = z.object({
+    current: z.number().nullable(),
+    base: z.number().nullable(),
+    override: z.number().nullable(),
+    overriddenAt: z.coerce.date().nullable(),
+});
+export const ConcurrencyLimitItem = z.object({
+    /** The limit's id, starting with `climit_`. */
+    id: z.string(),
+    /** The limit's name, as declared with `concurrencyLimit()` (anonymous inline
+     * limits use the derived name `task/<taskId>`). */
+    name: z.string(),
+    /** Caps each concurrencyKey pool; runs without a key share one pool. */
+    perKey: ConcurrencyLimitBound,
+    /** Caps every run holding this limit, keys or not. */
+    total: ConcurrencyLimitBound,
+    /** Runs executing that hold this limit. */
+    running: z.number(),
+    /** Runs that are queued and must clear this limit to execute. */
+    queued: z.number(),
+    /** Whether the limit is paused. A paused limit admits no runs until resumed;
+     * its configured bounds are kept. Older servers omit the field. */
+    paused: z.boolean().default(false),
+});
+export const ListConcurrencyLimitOptions = z.object({
+    page: z.number().optional(),
+    perPage: z.number().optional(),
+});
+/** A concurrency-key value as callers write it: numbers are accepted and stored as strings,
+ * matching how a trigger's `concurrencyKey` is coerced. */
+const OverrideConcurrencyKeySchema = z
+    .union([z.string(), z.number()])
+    .transform((value) => String(value))
+    .pipe(z.string().min(1).max(128));
+const ConcurrencyBoundSchema = z.number().int().min(0).max(100000);
+const OverrideTtlSchema = z.string().or(z.number().int().positive());
+/** Changes only the given bounds of the limit itself. Zero blocks every run holding
+ * the limit, which is how a limit is paused; `reset` restores the declared values. */
+export const OverrideConcurrencyLimitBoundsBody = z
+    .object({
+    perKey: ConcurrencyBoundSchema.optional(),
+    total: ConcurrencyBoundSchema.optional(),
+    concurrencyKey: z.never().optional(),
+    ttl: z.never().optional(),
+})
+    .refine((body) => body.perKey !== undefined || body.total !== undefined, {
+    message: "Provide at least one of `perKey` or `total`",
+});
+/** A temporary per-key cap on this limit's `perKey` for one concurrencyKey: `0`
+ * blocks the key, and the override expires after `ttl` (a duration such as `"7d"`
+ * or a number of seconds; default 7 days, at most 30 days). `total` is not per key,
+ * so it cannot be given here. `reset` with the same `concurrencyKey` clears it. */
+export const OverrideConcurrencyLimitKeyBody = z.object({
+    concurrencyKey: OverrideConcurrencyKeySchema,
+    perKey: ConcurrencyBoundSchema,
+    ttl: OverrideTtlSchema.optional(),
+    total: z.never().optional(),
+});
+/** Either the limit's own bounds or a per-key cap, told apart by `concurrencyKey`.
+ * The output type is the union of the two shapes above, so `total` with a key, a key
+ * without `perKey`, and `ttl` without a key are type errors for SDK callers. Parsing
+ * goes through one flat object with cross-field checks rather than a `z.union`, so an
+ * HTTP caller gets a single message naming the field at fault instead of the failures
+ * of both branches. */
+export const OverrideConcurrencyLimitRequestBody = z
+    .object({
+    perKey: ConcurrencyBoundSchema.optional(),
+    total: ConcurrencyBoundSchema.optional(),
+    concurrencyKey: OverrideConcurrencyKeySchema.optional(),
+    ttl: OverrideTtlSchema.optional(),
+})
+    .superRefine((body, ctx) => {
+    if (body.concurrencyKey !== undefined) {
+        if (body.perKey === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["perKey"],
+                message: "A per-key override needs `perKey`",
+            });
+        }
+        if (body.total !== undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["total"],
+                message: "`total` is not per key; omit it when overriding one concurrencyKey",
+            });
+        }
+        return;
+    }
+    if (body.ttl !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["ttl"],
+            message: "`ttl` only applies to a per-key override; pass `concurrencyKey` with it",
+        });
+    }
+    if (body.perKey === undefined && body.total === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            message: "Provide at least one of `perKey` or `total`",
+        });
+    }
+})
+    .transform((body) => body);
+/** `reset` with a `concurrencyKey` clears that key's override and leaves the limit
+ * itself alone; without one it resets the limit's own override. */
+export const ResetConcurrencyLimitRequestBody = z.object({
+    concurrencyKey: OverrideConcurrencyKeySchema.optional(),
+});
+export const RetrieveConcurrencyLimitOptions = z.object({
+    /** Return the view of this limit for one concurrencyKey instead of the limit itself. */
+    concurrencyKey: OverrideConcurrencyKeySchema.optional(),
+});
+/** The per-key bound of a limit for one concurrencyKey: `base` is the limit's own
+ * `perKey` as enforced, `override` the key's temporary cap, `current` whichever
+ * applies right now (env-clamped). A paused limit still reports its bounds. */
+export const ConcurrencyLimitKeyBound = z.object({
+    current: z.number().nullable(),
+    base: z.number().nullable(),
+    override: z.number().nullable(),
+    /** When the key's override lapses; null when there is none. */
+    expiresAt: z.coerce.date().nullable(),
+});
+export const ConcurrencyLimitKeyItem = z.object({
+    /** The limit's name. */
+    name: z.string(),
+    concurrencyKey: z.string(),
+    perKey: ConcurrencyLimitKeyBound,
+    /** Runs executing for this key that hold this limit. */
+    running: z.number(),
+    /** Whether the limit is paused. A paused limit admits no runs, override or not. */
+    paused: z.boolean(),
+});
+//# sourceMappingURL=queues.js.map

package/dist/esm/v3/schemas/queues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queues.js","sourceRoot":"","sources":["../../../../src/v3/schemas/queues.ts"],"names":[],"mappings":"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"}

package/dist/esm/v3/schemas/reports.d.ts

@@ -0,0 +1,291 @@
+import { z } from "zod/v4";
+/** A positive integer plus `m`, `h`, `d` or `w`, capped at 90d. Reports bucket by whole minutes. */
+export declare const ReportPeriodSchema: z.ZodString;
+export type ReportPeriod = z.infer<typeof ReportPeriodSchema>;
+/** The response encodings the endpoint can render. `json` returns a `ReportViewModel`. */
+export declare const ReportFormatSchema: z.ZodEnum<{
+    ansi: "ansi";
+    json: "json";
+    markdown: "markdown";
+}>;
+export type ReportFormat = z.infer<typeof ReportFormatSchema>;
+export declare const ReportSeveritySchema: z.ZodEnum<{
+    crit: "crit";
+    ok: "ok";
+    warn: "warn";
+}>;
+export type ReportSeverity = z.infer<typeof ReportSeveritySchema>;
+export declare const ReportUnitSchema: z.ZodEnum<{
+    count: "count";
+    ms: "ms";
+    perMin: "perMin";
+    ratio: "ratio";
+}>;
+export type ReportUnit = z.infer<typeof ReportUnitSchema>;
+/** A code resolved to a human string by the renderer's message table. */
+export declare const ReportReasonCodeSchema: z.ZodString;
+export type ReportReasonCode = z.infer<typeof ReportReasonCodeSchema>;
+/** A key into `ReportViewModel.links`, so a recommendation can point at a URL. */
+export declare const ReportLinkKeySchema: z.ZodString;
+export type ReportLinkKey = z.infer<typeof ReportLinkKeySchema>;
+export declare const ReportDeltaSchema: z.ZodObject<{
+    dir: z.ZodEnum<{
+        down: "down";
+        flat: "flat";
+        up: "up";
+    }>;
+    mult: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ReportDelta = z.infer<typeof ReportDeltaSchema>;
+export declare const ReportMetricSeriesSchema: z.ZodObject<{
+    points: z.ZodArray<z.ZodNumber>;
+    kind: z.ZodEnum<{
+        estimated: "estimated";
+        measured: "measured";
+    }>;
+}, z.core.$strip>;
+export type ReportMetricSeries = z.infer<typeof ReportMetricSeriesSchema>;
+export declare const ReportMetricSchema: z.ZodObject<{
+    id: z.ZodString;
+    value: z.ZodNumber;
+    unit: z.ZodEnum<{
+        count: "count";
+        ms: "ms";
+        perMin: "perMin";
+        ratio: "ratio";
+    }>;
+    aggregation: z.ZodOptional<z.ZodEnum<{
+        count: "count";
+        p95: "p95";
+        rate: "rate";
+        ratio: "ratio";
+    }>>;
+    normal: z.ZodOptional<z.ZodNumber>;
+    delta: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodEnum<{
+            down: "down";
+            flat: "flat";
+            up: "up";
+        }>;
+        mult: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    series: z.ZodOptional<z.ZodObject<{
+        points: z.ZodArray<z.ZodNumber>;
+        kind: z.ZodEnum<{
+            estimated: "estimated";
+            measured: "measured";
+        }>;
+    }, z.core.$strip>>;
+    breakdown: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    annotation: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        value: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    availability: z.ZodOptional<z.ZodEnum<{
+        measured: "measured";
+        unknown: "unknown";
+    }>>;
+    severity: z.ZodEnum<{
+        crit: "crit";
+        ok: "ok";
+        warn: "warn";
+    }>;
+}, z.core.$strip>;
+export type ReportMetric = z.infer<typeof ReportMetricSchema>;
+export declare const ReportRecommendationSchema: z.ZodObject<{
+    code: z.ZodString;
+    link: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReportRecommendation = z.infer<typeof ReportRecommendationSchema>;
+/** A footer line: an action, or the "do nothing" option (carries value). */
+export declare const ReportFooterEntrySchema: z.ZodObject<{
+    code: z.ZodString;
+    link: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ReportFooterEntry = z.infer<typeof ReportFooterEntrySchema>;
+/** A ruled-out cause + its evidence, e.g. "not your code" (never emitted without evidence). */
+export declare const ReportExclusionSchema: z.ZodObject<{
+    code: z.ZodString;
+    evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type ReportExclusion = z.infer<typeof ReportExclusionSchema>;
+/** A measured fact backing the verdict. `ReportExclusion` states what the problem isn't. */
+export declare const ReportObservationSchema: z.ZodObject<{
+    code: z.ZodString;
+    evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type ReportObservation = z.infer<typeof ReportObservationSchema>;
+export declare const ReportFindingSchema: z.ZodObject<{
+    type: z.ZodString;
+    severity: z.ZodEnum<{
+        crit: "crit";
+        ok: "ok";
+        warn: "warn";
+    }>;
+    reason: z.ZodString;
+    read: z.ZodOptional<z.ZodString>;
+    metricIds: z.ZodArray<z.ZodString>;
+    recommendation: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        link: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    hedge: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        link: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    anomalyWindow: z.ZodOptional<z.ZodObject<{
+        minutes: z.ZodNumber;
+        touchesEnd: z.ZodBoolean;
+    }, z.core.$strip>>;
+    attribution: z.ZodOptional<z.ZodObject<{
+        dim: z.ZodString;
+        key: z.ZodString;
+        share: z.ZodNumber;
+        of: z.ZodString;
+    }, z.core.$strip>>;
+    exclusions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>>>;
+    observations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ReportFinding = z.infer<typeof ReportFindingSchema>;
+export declare const ReportSummaryStatementSchema: z.ZodObject<{
+    findingType: z.ZodString;
+    severity: z.ZodEnum<{
+        crit: "crit";
+        ok: "ok";
+        warn: "warn";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReportSummaryStatement = z.infer<typeof ReportSummaryStatementSchema>;
+export declare const ReportLinkSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+export type ReportLink = z.infer<typeof ReportLinkSchema>;
+export declare const ReportViewModelSchema: z.ZodObject<{
+    title: z.ZodString;
+    scope: z.ZodString;
+    period: z.ZodString;
+    baselineLabel: z.ZodOptional<z.ZodString>;
+    generatedAt: z.ZodString;
+    windowMinutes: z.ZodNumber;
+    summary: z.ZodObject<{
+        severity: z.ZodEnum<{
+            crit: "crit";
+            ok: "ok";
+            warn: "warn";
+        }>;
+        statements: z.ZodArray<z.ZodObject<{
+            findingType: z.ZodString;
+            severity: z.ZodEnum<{
+                crit: "crit";
+                ok: "ok";
+                warn: "warn";
+            }>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    findings: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        severity: z.ZodEnum<{
+            crit: "crit";
+            ok: "ok";
+            warn: "warn";
+        }>;
+        reason: z.ZodString;
+        read: z.ZodOptional<z.ZodString>;
+        metricIds: z.ZodArray<z.ZodString>;
+        recommendation: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            link: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        hedge: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            link: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        anomalyWindow: z.ZodOptional<z.ZodObject<{
+            minutes: z.ZodNumber;
+            touchesEnd: z.ZodBoolean;
+        }, z.core.$strip>>;
+        attribution: z.ZodOptional<z.ZodObject<{
+            dim: z.ZodString;
+            key: z.ZodString;
+            share: z.ZodNumber;
+            of: z.ZodString;
+        }, z.core.$strip>>;
+        exclusions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>>>;
+        observations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            evidence: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    metrics: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        value: z.ZodNumber;
+        unit: z.ZodEnum<{
+            count: "count";
+            ms: "ms";
+            perMin: "perMin";
+            ratio: "ratio";
+        }>;
+        aggregation: z.ZodOptional<z.ZodEnum<{
+            count: "count";
+            p95: "p95";
+            rate: "rate";
+            ratio: "ratio";
+        }>>;
+        normal: z.ZodOptional<z.ZodNumber>;
+        delta: z.ZodOptional<z.ZodObject<{
+            dir: z.ZodEnum<{
+                down: "down";
+                flat: "flat";
+                up: "up";
+            }>;
+            mult: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        series: z.ZodOptional<z.ZodObject<{
+            points: z.ZodArray<z.ZodNumber>;
+            kind: z.ZodEnum<{
+                estimated: "estimated";
+                measured: "measured";
+            }>;
+        }, z.core.$strip>>;
+        breakdown: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        annotation: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            value: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        availability: z.ZodOptional<z.ZodEnum<{
+            measured: "measured";
+            unknown: "unknown";
+        }>>;
+        severity: z.ZodEnum<{
+            crit: "crit";
+            ok: "ok";
+            warn: "warn";
+        }>;
+    }, z.core.$strip>>;
+    facts: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    links: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    footer: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        link: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReportViewModel = z.infer<typeof ReportViewModelSchema>;

package/dist/esm/v3/schemas/reports.js

@@ -0,0 +1,131 @@
+import { z } from "zod/v4";
+// Shared contract for `GET /api/v1/reports/:key`: the period grammar and the `format=json` body.
+// The view model is semantic, not a UI tree: reasons are codes the renderer resolves to prose.
+const PERIOD_UNIT_MS = { m: 6e4, h: 36e5, d: 864e5, w: 6048e5 };
+const MAX_PERIOD_MS = 90 * 864e5; // 90d
+/** A positive integer plus `m`, `h`, `d` or `w`, capped at 90d. Reports bucket by whole minutes. */
+export const ReportPeriodSchema = z
+    .string()
+    .regex(/^[1-9]\d*[mhdw]$/, "period must be a shorthand like '30m', '1h' or '7d' — minutes (m), hours (h), days (d) or weeks (w); seconds are not supported")
+    .refine(
+// The regex guarantees the last char is a known unit; `?? 0` just satisfies the type checker.
+(p) => Number(p.slice(0, -1)) * (PERIOD_UNIT_MS[p.slice(-1)] ?? 0) <= MAX_PERIOD_MS, "period is too large (max 90d)");
+/** The response encodings the endpoint can render. `json` returns a `ReportViewModel`. */
+export const ReportFormatSchema = z.enum(["markdown", "json", "ansi"]);
+export const ReportSeveritySchema = z.enum(["ok", "warn", "crit"]);
+export const ReportUnitSchema = z.enum(["ms", "count", "ratio", "perMin"]);
+/** A code resolved to a human string by the renderer's message table. */
+export const ReportReasonCodeSchema = z.string();
+/** A key into `ReportViewModel.links`, so a recommendation can point at a URL. */
+export const ReportLinkKeySchema = z.string();
+export const ReportDeltaSchema = z.object({
+    dir: z.enum(["up", "down", "flat"]),
+    /** rounded value/normal multiplier; renderer decides whether to print "6×". */
+    mult: z.number().optional(),
+});
+export const ReportMetricSeriesSchema = z.object({
+    points: z.array(z.number()),
+    /** "estimated" = a proxy (e.g. pending backlog), shown informational-only. */
+    kind: z.enum(["measured", "estimated"]),
+});
+export const ReportMetricSchema = z.object({
+    /** A code, e.g. "start_latency_p95"; the messages map turns it into the label. */
+    id: z.string(),
+    value: z.number(),
+    unit: ReportUnitSchema,
+    aggregation: z.enum(["p95", "rate", "ratio", "count"]).optional(),
+    /** baseline; renderer formats "(normal ~7s)". */
+    normal: z.number().optional(),
+    delta: ReportDeltaSchema.optional(),
+    series: ReportMetricSeriesSchema.optional(),
+    /** named sub-values for composite metrics (e.g. throughput { done, triggered }). */
+    breakdown: z.record(z.string(), z.number()).optional(),
+    /** shown on a cause line INSTEAD of "(normal ~x)", e.g. "pinned 40 of last 60 min". */
+    annotation: z.object({ code: ReportReasonCodeSchema, value: z.number().optional() }).optional(),
+    /** "unknown" means `value` is a placeholder a consumer must not read as real. Absent = measured. */
+    availability: z.enum(["measured", "unknown"]).optional(),
+    severity: ReportSeveritySchema,
+});
+export const ReportRecommendationSchema = z.object({
+    code: ReportReasonCodeSchema,
+    link: ReportLinkKeySchema.optional(),
+});
+/** A footer line: an action, or the "do nothing" option (carries value). */
+export const ReportFooterEntrySchema = z.object({
+    code: ReportReasonCodeSchema,
+    link: ReportLinkKeySchema.optional(),
+    /** a computed fact (e.g. drainMinutes), never invented. */
+    value: z.number().optional(),
+});
+/** A ruled-out cause + its evidence, e.g. "not your code" (never emitted without evidence). */
+export const ReportExclusionSchema = z.object({
+    code: ReportReasonCodeSchema,
+    evidence: z.record(z.string(), z.number()).optional(),
+});
+/** A measured fact backing the verdict. `ReportExclusion` states what the problem isn't. */
+export const ReportObservationSchema = z.object({
+    code: ReportReasonCodeSchema,
+    evidence: z.record(z.string(), z.number()).optional(),
+});
+export const ReportFindingSchema = z.object({
+    /** "flow" | "execution" | "liveness" | future "infrastructure" | "billing" */
+    type: z.string(),
+    severity: ReportSeveritySchema,
+    /** Code for the state or cause, e.g. "env_limit_saturation" | "healthy". */
+    reason: ReportReasonCodeSchema,
+    /** Code for the "read:" line. Built last, may span findings. */
+    read: ReportReasonCodeSchema.optional(),
+    /** metric ids this finding covers, in causal order when degraded. */
+    metricIds: z.array(z.string()),
+    /** A single primary action. */
+    recommendation: ReportRecommendationSchema.optional(),
+    /** optional parenthetical — same shape as recommendation. */
+    hedge: ReportRecommendationSchema.optional(),
+    /** contiguous breach window of the driving metric -> "(last 40 min)". */
+    anomalyWindow: z.object({ minutes: z.number(), touchesEnd: z.boolean() }).optional(),
+    /** Which dimension and key own the problem. `of` is the denominator label the renderer prints. */
+    attribution: z
+        .object({ dim: z.string(), key: z.string(), share: z.number(), of: z.string() })
+        .optional(),
+    /** Ruled-out causes and evidence, rendered under the `read:` line. */
+    exclusions: z.array(ReportExclusionSchema).optional(),
+    /** Supporting facts, rendered under the `read:` line after the exclusions. */
+    observations: z.array(ReportObservationSchema).optional(),
+});
+export const ReportSummaryStatementSchema = z.object({
+    findingType: z.string(),
+    severity: ReportSeveritySchema,
+    /** Renders from (findingType, severity) unless a reason is present. */
+    reason: ReportReasonCodeSchema.optional(),
+});
+export const ReportLinkSchema = z.object({
+    key: ReportLinkKeySchema,
+    label: z.string(),
+    url: z.string(),
+});
+export const ReportViewModelSchema = z.object({
+    /** "health" | "cost" | … */
+    title: z.string(),
+    /** "prod" */
+    scope: z.string(),
+    /** "last 1h" */
+    period: z.string(),
+    /** "vs your 7d normal" */
+    baselineLabel: z.string().optional(),
+    /** ISO string. Passed in, never read from the clock inside interpret. */
+    generatedAt: z.string(),
+    /** live window length in minutes — lets the renderer say "of last 60 min". */
+    windowMinutes: z.number(),
+    summary: z.object({
+        severity: ReportSeveritySchema,
+        statements: z.array(ReportSummaryStatementSchema),
+    }),
+    findings: z.array(ReportFindingSchema),
+    metrics: z.array(ReportMetricSchema),
+    /** dense structured payload for agents. */
+    facts: z.record(z.string(), z.unknown()),
+    links: z.array(ReportLinkSchema),
+    /** dominant finding's action + optional "do nothing" option. Max two entries. */
+    footer: z.array(ReportFooterEntrySchema),
+});
+//# sourceMappingURL=reports.js.map