@uptimizr/metrics 0.1.0 → 0.2.0

package/dist/envelopes.js

@@ -0,0 +1,289 @@
+/**
+ * Zod mirrors of the three result envelopes (ADR 0051 §2, design sketch §B.1).
+ *
+ * `format=full | table | summary` is the shared querystring of every
+ * registry-served aggregate endpoint, and the same three shapes are what an
+ * agent gets back through MCP. They are described **here**, next to the row
+ * schemas they wrap, because three different packages need them and none of
+ * them may depend on the others:
+ *
+ * - `@uptimizr/db` attaches each route's 200 response schema from the registry,
+ *   so the collector's Zod type provider serialises a formatted response
+ *   *through* one of these — without them a `table` or `summary` response would
+ *   be stripped to nothing on its way out. `@uptimizr/db/summary` re-exports
+ *   every schema below under its established names, so that package's public
+ *   API is unchanged.
+ * - `@uptimizr/agent-core` derives each generated tool's `outputSchema` from
+ *   them, and `@uptimizr/mcp` validates `structuredContent` with them. Neither
+ *   package may depend on `@uptimizr/db` (it carries a ~37 MB DuckDB binding;
+ *   `dependencies.test.ts` in both packages fails if it reappears) — which is
+ *   exactly why the *pure* schemas live in this dependency-free package.
+ *
+ * Only the schemas moved. The summariser that *builds* an envelope
+ * (`summarizeRows`, `tableResult`, `clusterCells`, …) is still
+ * `@uptimizr/db/summary`'s; relocating it is #337.
+ */
+import { z } from "zod";
+import { METRIC_IDS } from "./registry.js";
+/**
+ * `format=full | table | summary`, the shared querystring value every
+ * registry-served aggregate endpoint accepts. Spelled out literally rather than
+ * built from a `RESULT_FORMATS` array so the inferred type is the string union
+ * itself and a route handler keeps its narrowing.
+ */
+export const resultFormatSchema = z.enum(["full", "table", "summary"]);
+/** Any registry metric id. */
+const metricIdSchema = z.enum(METRIC_IDS);
+const rangeSchema = z.object({
+    since: z.number().nullable(),
+    until: z.number().nullable(),
+});
+/** Applied filter values are whatever the route's own schema produced. */
+const filtersSchema = z.record(z.string(), z.unknown());
+const sampleSizeSchema = z.object({
+    sessions: z.number().nullable(),
+    events: z.number().nullable(),
+});
+const limitsSchema = z.object({
+    maxRows: z.number().int(),
+    maxSummaryRows: z.number().int(),
+});
+const measureSchema = z
+    .object({
+    column: z.string(),
+    unit: z.string().nullable(),
+    additive: z.boolean(),
+})
+    .nullable();
+const shareIntervalSchema = z.object({ low: z.number(), high: z.number() });
+const confidenceSchema = z.object({
+    kind: z.literal("wilson"),
+    level: z.number(),
+    note: z.string(),
+});
+const drillSchema = z.record(z.string(), z.string());
+/**
+ * The runnable drill-down query a ranked row can carry (#304): the query that
+ * produced the digest, with one more filter. Loose on purpose — its real shape
+ * is `queryV1Schema` in `@uptimizr/schema`, and restating it here would create
+ * the second definition ADR 0051 §1 exists to prevent.
+ */
+const drillQuerySchema = z.record(z.string(), z.unknown());
+const restSchema = z.object({
+    rows: z.number().int(),
+    value: z.number().nullable(),
+    share: z.number().nullable(),
+});
+const clusterRestSchema = z.object({
+    clusters: z.number().int(),
+    cells: z.number().int(),
+    weight: z.number().nullable(),
+    share: z.number().nullable(),
+});
+const rankedRowSchema = z.object({
+    label: z.string(),
+    value: z.number().nullable(),
+    share: z.number().nullable(),
+    shareInterval: shareIntervalSchema.optional(),
+    drill: drillSchema.optional(),
+    drillQuery: drillQuerySchema.optional(),
+});
+const seriesDigestSchema = z.object({
+    axis: z.string(),
+    points: z.number().int(),
+    first: z.number().nullable(),
+    last: z.number().nullable(),
+    min: z.number().nullable(),
+    max: z.number().nullable(),
+    firstLabel: z.string().nullable(),
+    lastLabel: z.string().nullable(),
+    minLabel: z.string().nullable(),
+    maxLabel: z.string().nullable(),
+    trend: z.enum(["up", "down", "flat"]),
+    slope: z.number().nullable(),
+});
+const spatialClusterSchema = z.object({
+    centroid: z.array(z.number()),
+    extent: z.object({ min: z.array(z.number()), max: z.array(z.number()) }),
+    cells: z.number().int(),
+    weight: z.number(),
+    share: z.number().nullable(),
+    drill: drillSchema.optional(),
+    // Spatial labelling (ADR 0051 §2 / sketch §B.2, #302). Optional as a group: a
+    // labelled cluster carries all four; they are absent entirely when the grid is
+    // not world-space or the request selected no scene. `null` inside the group
+    // means "the scene was checked and nothing contains this hotspot".
+    region: z.string().nullable().optional(),
+    regions: z.array(z.string()).optional(),
+    nearestMesh: z.string().nullable().optional(),
+    distance: z.number().nullable().optional(),
+});
+const recordValueSchema = z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]));
+const ratesSchema = z.record(z.string(), z.object({
+    value: z.number().nullable(),
+    numerator: z.string(),
+    denominator: z.string(),
+}));
+/** Fields every summary carries, whatever its grain. */
+const summaryBase = {
+    metric: metricIdSchema,
+    range: rangeSchema,
+    filters: filtersSchema,
+    sampleSize: sampleSizeSchema,
+    total: z.number().nullable(),
+    measure: measureSchema,
+    confidence: confidenceSchema.optional(),
+    reading: z.string(),
+    caveats: z.array(z.string()),
+};
+const rankedSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("ranked"),
+    top: z.array(rankedRowSchema),
+    rest: restSchema,
+});
+const seriesSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("series"),
+    series: seriesDigestSchema,
+});
+const clusterSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("clusters"),
+    axes: z.array(z.string()),
+    occupiedCells: z.number().int(),
+    densityThreshold: z.number(),
+    clusters: z.array(spatialClusterSchema),
+    rest: clusterRestSchema,
+});
+const recordSummarySchema = z.object({
+    ...summaryBase,
+    kind: z.literal("record"),
+    record: recordValueSchema,
+    rates: ratesSchema,
+});
+/** `format=summary`: one of the four grain-driven shapes. */
+export const summaryEnvelopeSchema = z.discriminatedUnion("kind", [
+    rankedSummarySchema,
+    seriesSummarySchema,
+    clusterSummarySchema,
+    recordSummarySchema,
+]);
+/** The `meta` block `format=table` wraps a metric's rows in. */
+export const tableMetaSchema = z.object({
+    metric: metricIdSchema,
+    range: rangeSchema,
+    filters: filtersSchema,
+    sampleSize: sampleSizeSchema,
+    rows: z.number().int(),
+    truncated: z.boolean(),
+    limits: limitsSchema,
+});
+/** `format=table`: the `meta` envelope around a metric's own row schema. */
+export function tableEnvelopeSchema(row) {
+    return z.object({
+        meta: tableMetaSchema,
+        rows: z.array(row),
+    });
+}
+/**
+ * The result a caller gets from a surface that honours `format`: the union of
+ * the three envelopes.
+ *
+ * Order matters. The `full` shape is first, so a default request is parsed by
+ * precisely the schema it was parsed by before this existed and its bytes
+ * cannot drift. The envelopes are unambiguous against it — `table` is an object
+ * with `meta` and `rows`, `summary` an object with `kind` and `reading`, and
+ * neither can satisfy a row array or a stats row's required numeric columns.
+ *
+ * `full` defaults to a plain array of `row`, which is what an agent-facing
+ * caller wants; the collector passes its own route-level 200 schema instead,
+ * because a single-record route (the spatial `stats` endpoints) answers with a
+ * bare object rather than an array.
+ */
+export function resultEnvelopeSchema(row, full = z.array(row)) {
+    return z.union([full, tableEnvelopeSchema(row), summaryEnvelopeSchema]);
+}
+/**
+ * The **object** form of {@link resultEnvelopeSchema}, for a tool that must
+ * advertise its result as a single JSON Schema object — which is what MCP's
+ * `outputSchema` is: a `type: "object"` schema the SDK validates
+ * `structuredContent` against, on the server with Zod and again on the client
+ * with Ajv.
+ *
+ * A top-level `z.union` cannot be used there. The MCP TypeScript SDK normalises
+ * an output schema to an object schema and **silently drops** anything that is
+ * not one (`normalizeObjectSchema` returns `undefined` for a union), so
+ * `tools/list` would advertise no output schema at all and every call would then
+ * fail validation — worse than the bug this replaces. So the three envelopes are
+ * merged into one loose object whose every key is optional:
+ *
+ * - `rows` — `format=full` (wrapped as `{ rows }` by the MCP server, so a
+ *   single-record read looks like every other) and the rows of `format=table`.
+ *   Its element schema stays the metric's own, so a column that is out of
+ *   contract is still reported by name.
+ * - `meta` — only `format=table` carries it.
+ * - `kind` and the summary fields — only `format=summary` carries them, and
+ *   `kind` says which grain-specific fields (`top`, `series`, `clusters`,
+ *   `record`) came with it.
+ *
+ * The object is deliberately *loose*: an envelope key a newer collector adds is
+ * passed through rather than dropped. Callers that can express a union — a
+ * collector route's response schema, a test — should use
+ * {@link resultEnvelopeSchema}, which discriminates strictly.
+ */
+export function structuredEnvelopeSchema(row, metric) {
+    // A tool answers for exactly one metric, so naming it collapses two copies
+    // of the 69-value registry enum (~2.7 kB per tool in `tools/list`) into a
+    // literal — smaller *and* more precise. Omitted, the enum stands.
+    const id = metric == null ? metricIdSchema : z.literal(metric);
+    return z.looseObject({
+        rows: z
+            .array(row)
+            .optional()
+            .describe("`format=full` and `format=table`: the result rows. Absent from a summary."),
+        meta: (metric == null ? tableMetaSchema : tableMetaSchema.extend({ metric: id }))
+            .optional()
+            .describe("`format=table` only: metric, range, applied filters, row count, caps."),
+        kind: z
+            .enum(["ranked", "series", "clusters", "record"])
+            .optional()
+            .describe("`format=summary` only: which digest this is."),
+        metric: id.optional().describe("`format=summary` only: the metric summarised."),
+        range: rangeSchema.optional(),
+        filters: filtersSchema.optional(),
+        sampleSize: sampleSizeSchema.optional(),
+        total: z.number().nullable().optional(),
+        measure: measureSchema.optional(),
+        confidence: confidenceSchema.optional(),
+        reading: z
+            .string()
+            .optional()
+            .describe("`format=summary` only: one plain-language sentence, templated — never written."),
+        caveats: z.array(z.string()).optional(),
+        top: z.array(rankedRowSchema).optional().describe('`kind: "ranked"`: the leading rows.'),
+        rest: z
+            .looseObject({
+            rows: z.number().int().optional(),
+            clusters: z.number().int().optional(),
+            cells: z.number().int().optional(),
+            value: z.number().nullable().optional(),
+            weight: z.number().nullable().optional(),
+            share: z.number().nullable().optional(),
+        })
+            .optional()
+            .describe("What the digest did not list individually: `rows`/`value` for a ranked digest, " +
+            "`clusters`/`cells`/`weight` for a spatial one."),
+        series: seriesDigestSchema.optional().describe('`kind: "series"`: the per-bucket digest.'),
+        axes: z.array(z.string()).optional(),
+        occupiedCells: z.number().int().optional(),
+        densityThreshold: z.number().optional(),
+        clusters: z
+            .array(spatialClusterSchema)
+            .optional()
+            .describe('`kind: "clusters"`: merged spatial hotspots.'),
+        record: recordValueSchema.optional().describe('`kind: "record"`: the single row itself.'),
+        rates: ratesSchema.optional(),
+    });
+}
+//# sourceMappingURL=envelopes.js.map

package/dist/envelopes.js.map

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

package/dist/index.d.ts

@@ -24,6 +24,13 @@
  * metric?.row; // z.ZodObject — the shape of one row
  * ```
  */
-export { AGGREGATION_BUILDER_NAMES, DIMENSION_COLUMNS, FILTER_TARGETS, METRIC_BY_BUILDER, METRIC_IDS, METRIC_REGISTRY, allMetrics, getMetric, isMetricId, isResourceMetric, metricForBuilder, } from "./registry.js";
-export type { AggregationBuilderName, ColumnSemantics, ColumnUnit, DimensionId, FilterId, FilterOptionInterface, FilterTarget, MetricCategory, MetricComparison, MetricDefinition, MetricEndpoint, MetricGrain, MetricId, MetricRegistry, NoUnregisteredAggregations, UnregisteredAggregation, } from "./registry.js";
+export { AGGREGATION_BUILDER_NAMES, DIMENSION_COLUMNS, DIMENSION_ROW_COLUMNS, FILTER_TARGETS, GENERIC_DIMENSIONS, METRIC_BY_BUILDER, METRIC_IDS, METRIC_REGISTRY, allMetrics, getMetric, isMetricId, isAggregateMetric, isDerivedMetric, isResourceMetric, metricCapability, metricForBuilder, } from "./registry.js";
+export { REQUIRED_FILTERS, dimensionColumn, genericDimensions, nativeDimensions, orderableColumns, queryTier, queryableFilters, requiredFilters, segmentableDimensions, validateQuery, } from "./query.js";
+export type { QueryIssue, QueryIssueCode, QueryTier, QueryValidation } from "./query.js";
+export { PANEL_CHART_RULES, axisColumn, chartSuitsMetric, chartsForMetric, defaultEncoding, labelColumn, measureColumn, resultColumns, suggestChart, validatePanelSpec, } from "./panelSpec.js";
+export type { PanelChartRule, PanelSpecIssue, PanelSpecIssueCode, PanelSpecValidation, } from "./panelSpec.js";
+export type { AggregationBuilderName, ColumnSemantics, ColumnUnit, DimensionId, FilterId, FilterOptionInterface, FilterTarget, GenericGroupBy, GenericMeasure, GenericMeasureKind, GenericScope, MetricCapability, MetricCategory, MetricComparison, MetricDefinition, MetricDerivation, MetricEndpoint, MetricGrain, MetricId, MetricRegistry, NoUnregisteredAggregations, UnregisteredAggregation, } from "./registry.js";
+export { resultEnvelopeSchema, resultFormatSchema, structuredEnvelopeSchema, summaryEnvelopeSchema, tableEnvelopeSchema, tableMetaSchema, } from "./envelopes.js";
+export { NARRATIVE_ENTRY_KINDS, NARRATIVE_LIMITS, narrativeEntryKindSchema, narrativeRefsSchema, sessionNarrativeEntrySchema, sessionNarrativeTotalsSchema, } from "./narrative.js";
+export type { NarrativeEntryKind, NarrativeRefs, SessionNarrativeEntry, SessionNarrativeTotals, } from "./narrative.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,WAAW,EACX,QAAQ,EACR,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,cAAc,EACd,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAKvB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAMzF,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,EACb,YAAY,EACZ,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,WAAW,EACX,QAAQ,EACR,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,cAAc,EACd,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAQvB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -24,5 +24,27 @@
  * metric?.row; // z.ZodObject — the shape of one row
  * ```
  */
-export { AGGREGATION_BUILDER_NAMES, DIMENSION_COLUMNS, FILTER_TARGETS, METRIC_BY_BUILDER, METRIC_IDS, METRIC_REGISTRY, allMetrics, getMetric, isMetricId, isResourceMetric, metricForBuilder, } from "./registry.js";
+export { AGGREGATION_BUILDER_NAMES, DIMENSION_COLUMNS, DIMENSION_ROW_COLUMNS, FILTER_TARGETS, GENERIC_DIMENSIONS, METRIC_BY_BUILDER, METRIC_IDS, METRIC_REGISTRY, allMetrics, getMetric, isMetricId, isAggregateMetric, isDerivedMetric, isResourceMetric, metricCapability, metricForBuilder, } from "./registry.js";
+// --- Query DSL validation (ADR 0051 §3) ---
+// The registry half of validating a `queryV1` document: `@uptimizr/schema`
+// checks the shape, this checks the vocabulary.
+export { REQUIRED_FILTERS, dimensionColumn, genericDimensions, nativeDimensions, orderableColumns, queryTier, queryableFilters, requiredFilters, segmentableDimensions, validateQuery, } from "./query.js";
+// --- Declarative panel specs (ADR 0051 §7 / sketch §G.3) -------------------
+// The registry half of validating a `panelSpecV1`: its query through
+// `validateQuery`, then the two questions only the registry can answer — does
+// this chart suit the metric's grain, and do these encoding columns exist.
+export { PANEL_CHART_RULES, axisColumn, chartSuitsMetric, chartsForMetric, defaultEncoding, labelColumn, measureColumn, resultColumns, suggestChart, validatePanelSpec, } from "./panelSpec.js";
+// --- Result envelopes (ADR 0051 §2) ---
+// The Zod mirrors of `format=full | table | summary`. They live here, next to
+// the row schemas they wrap, so the collector (`@uptimizr/db`), the generated
+// tool catalog (`@uptimizr/agent-core`) and the MCP server can all describe the
+// same three shapes without any of them depending on the others. The summariser
+// that *builds* an envelope stays in `@uptimizr/db/summary` (#337).
+export { resultEnvelopeSchema, resultFormatSchema, structuredEnvelopeSchema, summaryEnvelopeSchema, tableEnvelopeSchema, tableMetaSchema, } from "./envelopes.js";
+// --- Session narrative (ADR 0051 §7, design sketch §G.2) -------------------
+//
+// The shapes and bounds of the `query:raw`-gated session narrative, shared by
+// the compaction in `@uptimizr/db`, the collector route that serves it and the
+// `session_narrative` registry entry above.
+export { NARRATIVE_ENTRY_KINDS, NARRATIVE_LIMITS, narrativeEntryKindSchema, narrativeRefsSchema, sessionNarrativeEntrySchema, sessionNarrativeTotalsSchema, } from "./narrative.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,6CAA6C;AAC7C,2EAA2E;AAC3E,gDAAgD;AAChD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,8EAA8E;AAC9E,qEAAqE;AACrE,8EAA8E;AAC9E,2EAA2E;AAC3E,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,EACb,YAAY,EACZ,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAiCxB,yCAAyC;AACzC,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,oEAAoE;AACpE,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,4CAA4C;AAC5C,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC"}

package/dist/narrative.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The **session narrative** contract (ADR 0051 §7, design sketch §G.2).
+ *
+ * A narrative is an ordered, compacted account of what one session did — scene
+ * changes, mesh dwell, interactions, performance dips, errors and the reason it
+ * ended — with every timestamp relative to the session's first event. It exists
+ * because the two things an agent could otherwise ask for are both useless to
+ * it: the aggregate metrics say nothing about *one* session, and the raw NDJSON
+ * stream is tens of thousands of lines of sampled telemetry.
+ *
+ * Only the **shapes and bounds** live here, in the dependency-free registry
+ * package, because three packages need them and none of them may depend on the
+ * others:
+ *
+ * - `@uptimizr/db` computes a narrative from `AnyEvent[]` (`src/narrative/`);
+ * - the collector serves it on `GET /api/v1/sessions/:id/narrative` and bounds
+ *   its querystring with the same numbers;
+ * - the registry entry below it (`session_narrative`) advertises the row schema
+ *   to OpenAPI, the agent tool catalog and the docs tables.
+ *
+ * **Privacy (ADR 0003).** A narrative is derived from raw per-session events, so
+ * it is reachable only on a collector with `ENABLE_RAW_SESSION_RETENTION` and
+ * only with a key holding `query:raw`. Even then it is a *projection*: an entry
+ * carries a relative timestamp, a templated one-line summary and at most a mesh
+ * name, a scene id and a custom-event name. It never carries the visitor hash,
+ * the page URL, `pageMeta`, positions, rays, or anything from the `device` block
+ * beyond the engine/graphics API. Custom-event **property values** are excluded
+ * unless the caller explicitly asks for them; the property *keys* are always
+ * safe to show because they are developer-chosen field names.
+ */
+import { z } from "zod";
+/**
+ * What one narrative entry is about.
+ *
+ * - `scene` — the session entered a scene (`session_start` or `scene_change`).
+ * - `dwell` — a mesh held the viewer's attention for at least `minDwellMs`,
+ *   aggregated across the session from `mesh_visibility` / `hover_dwell`.
+ * - `interaction` — a discrete act: a mesh interaction, a click that hit a mesh,
+ *   a named input action, or a custom event.
+ * - `perf_dip` — a run of consecutive `frame_perf` samples below `fpsThreshold`,
+ *   collapsed into one entry with the run's duration and sample count.
+ * - `error` — a `runtime_error`, message truncated.
+ * - `diagnostic` — a `graphics_diagnostic`, by category and severity.
+ * - `capability` — a `capability_change` (quality drop, tracking loss, backend
+ *   fallback).
+ * - `xr` — entering/leaving immersive input, and a boundary-proximity summary.
+ * - `end` — how the session finished (`session_end` reason), when it reported.
+ * - `summary` — the single closing entry carrying the session's totals.
+ */
+export declare const NARRATIVE_ENTRY_KINDS: readonly ["scene", "dwell", "interaction", "perf_dip", "error", "diagnostic", "capability", "xr", "end", "summary"];
+/** One narrative entry kind. */
+export type NarrativeEntryKind = (typeof NARRATIVE_ENTRY_KINDS)[number];
+/** {@link NARRATIVE_ENTRY_KINDS} as a Zod enum. */
+export declare const narrativeEntryKindSchema: z.ZodEnum<{
+    scene: "scene";
+    dwell: "dwell";
+    interaction: "interaction";
+    perf_dip: "perf_dip";
+    error: "error";
+    diagnostic: "diagnostic";
+    capability: "capability";
+    xr: "xr";
+    end: "end";
+    summary: "summary";
+}>;
+/**
+ * The named things an entry points at. Deliberately only three, and all three
+ * are developer-assigned identifiers rather than anything about a person: the
+ * mesh/object name, the scene id, and the name of a custom event or input
+ * action.
+ */
+export declare const narrativeRefsSchema: z.ZodObject<{
+    mesh: z.ZodOptional<z.ZodString>;
+    scene: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** What an entry points at — see {@link narrativeRefsSchema}. */
+export type NarrativeRefs = z.infer<typeof narrativeRefsSchema>;
+/**
+ * Session-wide totals, carried on the closing `summary` entry so a reader that
+ * only keeps the last line still knows the shape of what it just read.
+ */
+export declare const sessionNarrativeTotalsSchema: z.ZodObject<{
+    events: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    scenes: z.ZodNumber;
+    meshes: z.ZodNumber;
+    interactions: z.ZodNumber;
+    dips: z.ZodNumber;
+    errors: z.ZodNumber;
+}, z.core.$strip>;
+/** Session-wide totals — see {@link sessionNarrativeTotalsSchema}. */
+export type SessionNarrativeTotals = z.infer<typeof sessionNarrativeTotalsSchema>;
+/**
+ * One line of the narrative.
+ *
+ * `summary` is a **templated** one-line sentence composed from the fields
+ * already on the entry — never free text copied out of an event payload — so
+ * that what an LLM reads cannot contain anything the structured fields do not.
+ */
+export declare const sessionNarrativeEntrySchema: z.ZodObject<{
+    tMs: z.ZodNumber;
+    kind: z.ZodEnum<{
+        scene: "scene";
+        dwell: "dwell";
+        interaction: "interaction";
+        perf_dip: "perf_dip";
+        error: "error";
+        diagnostic: "diagnostic";
+        capability: "capability";
+        xr: "xr";
+        end: "end";
+        summary: "summary";
+    }>;
+    summary: z.ZodString;
+    refs: z.ZodObject<{
+        mesh: z.ZodOptional<z.ZodString>;
+        scene: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    count: z.ZodOptional<z.ZodNumber>;
+    totals: z.ZodOptional<z.ZodObject<{
+        events: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        scenes: z.ZodNumber;
+        meshes: z.ZodNumber;
+        interactions: z.ZodNumber;
+        dips: z.ZodNumber;
+        errors: z.ZodNumber;
+    }, z.core.$strip>>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** One line of the narrative — see {@link sessionNarrativeEntrySchema}. */
+export type SessionNarrativeEntry = z.infer<typeof sessionNarrativeEntrySchema>;
+/**
+ * The bounds and defaults every consumer shares. The collector's querystring
+ * schema, the generated tool's input schema and the compaction function all read
+ * them from here, so "the default dwell floor" is one number rather than three.
+ */
+export declare const NARRATIVE_LIMITS: {
+    /** Default dwell floor: below this a mesh is a glance, not attention. */
+    readonly defaultMinDwellMs: 1000;
+    /** Largest dwell floor a caller may ask for (one hour). */
+    readonly maxMinDwellMs: 3600000;
+    /** Default FPS floor below which a frame sample counts towards a dip. */
+    readonly defaultFpsThreshold: 30;
+    /** Largest FPS floor a caller may ask for. */
+    readonly maxFpsThreshold: 240;
+    /**
+     * Consecutive sub-threshold `frame_perf` samples before a dip is reported.
+     * Two, so a single unlucky sample (a tab switch, a GC pause) is not a story.
+     */
+    readonly dipMinSamples: 2;
+    /** Default entry cap — the "under 200 lines" bound issue #314 asks for. */
+    readonly defaultMaxEntries: 200;
+    /** Hard cap: no caller can ask for an unbounded narrative (ADR 0051 §9). */
+    readonly maxMaxEntries: 1000;
+    /** Error/diagnostic messages are truncated to this many characters. */
+    readonly maxMessageLength: 200;
+    /** At most this many custom-event property **keys** are listed per entry. */
+    readonly maxCustomPropKeys: 12;
+};
+//# sourceMappingURL=narrative.d.ts.map

package/dist/narrative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrative.d.ts","sourceRoot":"","sources":["../src/narrative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,qHAWxB,CAAC;AAEX,gCAAgC;AAChC,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,mDAAmD;AACnD,eAAO,MAAM,wBAAwB;;;;;;;;;;;EAAgC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AAEH,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;iBAevC,CAAC;AAEH,sEAAsE;AACtE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmBtC,CAAC;AAEH,2EAA2E;AAC3E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;IAC3B,yEAAyE;;IAEzE,2DAA2D;;IAE3D,yEAAyE;;IAEzE,8CAA8C;;IAE9C;;;OAGG;;IAEH,2EAA2E;;IAE3E,4EAA4E;;IAE5E,uEAAuE;;IAEvE,6EAA6E;;CAErE,CAAC"}