@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/metrics/compute.ts

@@ -0,0 +1,243 @@
+import type { WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  AggregateDimension,
+  AggregateKey,
+  AggregateRow,
+} from "@cosmicdrift/kumiko-types/aggregate-types";
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { Temporal } from "temporal-polyfill";
+import { MAX_GROUP_ROWS, type MetricRange } from "./constants.js";
+import type {
+  MetricDefinition,
+  MetricDeltaDirection,
+  MetricPoint,
+  MetricResult,
+  MetricRow,
+  MetricSegment,
+  MetricSeries,
+} from "./types.js";
+import { bucketStartsMs, computeWindow, resolveBucket } from "./window.js";
+
+export type MetricRunParams = {
+  readonly range: MetricRange;
+  readonly timeZone: string;
+  readonly now: Temporal.Instant;
+  /** Extra filter that narrows the source to the caller's scope. */
+  readonly scopeWhere: WhereObject;
+};
+
+const NULL_KEY_TEXT = "—";
+
+function keyText(key: AggregateKey | undefined): string {
+  return key === null || key === undefined ? NULL_KEY_TEXT : String(key);
+}
+
+function formatDelta(
+  value: number | null,
+  previousValue: number | null,
+): { delta: string | null; deltaDirection: MetricDeltaDirection | null } {
+  if (value === null || previousValue === null || previousValue === 0 || value === previousValue) {
+    return { delta: null, deltaDirection: null };
+  }
+  const percent = Math.round((Math.abs(value - previousValue) / Math.abs(previousValue)) * 100);
+  if (percent === 0) return { delta: null, deltaDirection: null };
+  return { delta: `${percent} %`, deltaDirection: value > previousValue ? "up" : "down" };
+}
+
+function fractionOf(value: number, total: number | null): number {
+  if (total === null || total <= 0) return 0;
+  return Math.min(1, Math.max(0, value / total));
+}
+
+type MetricWindow = ReturnType<typeof computeWindow>;
+
+type MetricWheres = {
+  readonly current: WhereObject;
+  readonly previous: WhereObject | undefined;
+};
+
+type MetricAggregates = {
+  readonly total: readonly AggregateRow[];
+  readonly previous: readonly AggregateRow[] | undefined;
+  readonly points: readonly AggregateRow[];
+  readonly groups: readonly AggregateRow[];
+  readonly stacks: readonly AggregateRow[];
+  readonly series: readonly AggregateRow[];
+};
+
+function buildWheres(
+  metric: MetricDefinition,
+  window: MetricWindow | undefined,
+  scopeWhere: WhereObject,
+): MetricWheres {
+  const baseWhere: WhereObject = { ...metric.where, ...scopeWhere };
+  const { timeField } = metric;
+  if (timeField === undefined || window === undefined) {
+    return { current: baseWhere, previous: undefined };
+  }
+  return {
+    current: { ...baseWhere, [timeField]: { gte: window.start, lte: window.end } },
+    previous:
+      metric.comparePrevious === false
+        ? undefined
+        : { ...baseWhere, [timeField]: { gte: window.previousStart, lt: window.start } },
+  };
+}
+
+async function fetchAggregates(
+  db: TenantDb,
+  metric: MetricDefinition,
+  wheres: MetricWheres,
+  bucketDimension: AggregateDimension | undefined,
+): Promise<MetricAggregates> {
+  const aggregate = (
+    groupBy: readonly AggregateDimension[],
+    where: WhereObject,
+    extra: { readonly orderByValue?: "desc"; readonly limit?: number } = {},
+  ): Promise<readonly AggregateRow[]> =>
+    db.aggregate(metric.source, { measure: metric.measure, groupBy, ...extra }, where);
+  const { groupBy, stackBy } = metric;
+  const { current } = wheres;
+
+  const groupsPromise =
+    groupBy === undefined
+      ? Promise.resolve([])
+      : aggregate([{ field: groupBy }], current, { orderByValue: "desc", limit: MAX_GROUP_ROWS });
+  // Stacks/series are only rendered for the top groups. A NULL group key can't be
+  // matched by IN, so a null among the top groups falls back to the unrestricted scan.
+  const groupedWhere = async (): Promise<WhereObject> => {
+    if (groupBy === undefined) return current;
+    const keys = (await groupsPromise).map((row) => row.keys[0]);
+    return keys.length === 0 || keys.includes(null) || keys.includes(undefined)
+      ? current
+      : { ...current, [groupBy]: keys };
+  };
+
+  const [total, previous, points, groups, stacks, series] = await Promise.all([
+    aggregate([], current),
+    wheres.previous === undefined ? Promise.resolve(undefined) : aggregate([], wheres.previous),
+    bucketDimension !== undefined && groupBy === undefined
+      ? aggregate([bucketDimension], current)
+      : Promise.resolve([]),
+    groupsPromise,
+    groupBy !== undefined && stackBy !== undefined
+      ? groupedWhere().then((where) => aggregate([{ field: groupBy }, { field: stackBy }], where))
+      : Promise.resolve([]),
+    bucketDimension !== undefined && groupBy !== undefined
+      ? groupedWhere().then((where) => aggregate([{ field: groupBy }, bucketDimension], where))
+      : Promise.resolve([]),
+  ]);
+  return { total, previous, points, groups, stacks, series };
+}
+
+function groupSegments(
+  stackRows: readonly AggregateRow[],
+  labelOf: (key: string) => string,
+): ReadonlyMap<string, readonly MetricSegment[]> {
+  const segmentsByGroup = new Map<string, MetricSegment[]>();
+  for (const row of stackRows) {
+    const groupKey = keyText(row.keys[0]);
+    const stackKey = keyText(row.keys[1]);
+    const segments = segmentsByGroup.get(groupKey) ?? [];
+    segments.push({ key: stackKey, label: labelOf(stackKey), value: row.value ?? 0 });
+    segmentsByGroup.set(groupKey, segments);
+  }
+  return segmentsByGroup;
+}
+
+function buildRows(
+  metric: MetricDefinition,
+  aggregates: MetricAggregates,
+  total: number | null,
+  labelOf: (key: string) => string,
+): readonly MetricRow[] {
+  const segmentsByGroup = groupSegments(aggregates.stacks, labelOf);
+  return aggregates.groups.map((row) => {
+    const key = keyText(row.keys[0]);
+    const rowValue = row.value ?? 0;
+    return {
+      id: key,
+      key,
+      label: labelOf(key),
+      value: rowValue,
+      fraction: fractionOf(rowValue, total),
+      ...(metric.stackBy !== undefined && { segments: segmentsByGroup.get(key) ?? [] }),
+    };
+  });
+}
+
+function buildSeries(
+  rows: readonly MetricRow[],
+  seriesRows: readonly AggregateRow[],
+  fillBuckets: (byBucketMs: ReadonlyMap<number, number | null>) => readonly MetricPoint[],
+): readonly MetricSeries[] {
+  const bucketsByGroup = new Map<string, Map<number, number | null>>();
+  for (const row of seriesRows) {
+    const groupKey = keyText(row.keys[0]);
+    const buckets = bucketsByGroup.get(groupKey) ?? new Map<number, number | null>();
+    buckets.set(Number(row.keys[1]), row.value);
+    bucketsByGroup.set(groupKey, buckets);
+  }
+  return rows.map((row) => ({
+    key: row.key,
+    label: row.label,
+    points: fillBuckets(bucketsByGroup.get(row.key) ?? new Map()),
+  }));
+}
+
+export async function runMetric(
+  db: TenantDb,
+  metric: MetricDefinition,
+  params: MetricRunParams,
+): Promise<MetricResult> {
+  const range = metric.window ?? params.range;
+  const bucket = resolveBucket(metric, range);
+  const { timeField } = metric;
+  const window =
+    timeField === undefined ? undefined : computeWindow(range, bucket, params.timeZone, params.now);
+  const bucketDimension: AggregateDimension | undefined =
+    timeField !== undefined && bucket !== undefined
+      ? { field: timeField, bucket, timeZone: params.timeZone }
+      : undefined;
+
+  const wheres = buildWheres(metric, window, params.scopeWhere);
+  const aggregates = await fetchAggregates(db, metric, wheres, bucketDimension);
+
+  const value = aggregates.total[0]?.value ?? null;
+  const previousValue = aggregates.previous?.[0]?.value ?? null;
+  const labelOf = (key: string): string => metric.groupLabels?.[key] ?? key;
+  const gapValue = metric.measure.fn === "avg" ? null : 0;
+
+  const bucketStarts =
+    window !== undefined && bucket !== undefined
+      ? bucketStartsMs(window, bucket, params.timeZone)
+      : [];
+  const fillBuckets = (byBucketMs: ReadonlyMap<number, number | null>): readonly MetricPoint[] =>
+    bucketStarts.map((atMs) => ({ atMs, value: byBucketMs.get(atMs) ?? gapValue }));
+
+  // Grouped metrics carry their time series in `series`; fetchAggregates skips the total series, so filling gaps here would fake a flat zero line.
+  const points =
+    metric.groupBy === undefined
+      ? fillBuckets(
+          new Map(
+            aggregates.points.map((row): [number, number | null] => [
+              Number(row.keys[0]),
+              row.value,
+            ]),
+          ),
+        )
+      : [];
+  const rows = buildRows(metric, aggregates, value, labelOf);
+
+  return {
+    value,
+    previousValue,
+    ...formatDelta(value, previousValue),
+    windowStartMs: window?.start.epochMilliseconds ?? null,
+    windowEndMs: window?.end.epochMilliseconds ?? null,
+    points,
+    series: buildSeries(rows, aggregates.series, fillBuckets),
+    rows,
+    nextCursor: null,
+  };
+}

package/packages/bundled-features/src/metrics/constants.ts

@@ -0,0 +1,22 @@
+// @runtime client
+// Pure constants — imported by server (feature.ts) and by panel declarations,
+// so no runtime import from the engine barrel here.
+
+export const METRICS_FEATURE = "metrics" as const;
+export const METRICS_SYSTEM_FEATURE = "metrics-system" as const;
+
+export type MetricScope = "system" | "tenant";
+
+const FEATURE_BY_SCOPE: Readonly<Record<MetricScope, string>> = {
+  tenant: METRICS_FEATURE,
+  system: METRICS_SYSTEM_FEATURE,
+};
+
+export function metricQueryName(scope: MetricScope, id: string): string {
+  return `${FEATURE_BY_SCOPE[scope]}:query:${id}`;
+}
+
+export const METRIC_RANGES = ["24h", "7d", "14d", "30d"] as const;
+export type MetricRange = (typeof METRIC_RANGES)[number];
+
+export const MAX_GROUP_ROWS = 50;

package/packages/bundled-features/src/metrics/default-metrics.ts

@@ -0,0 +1,133 @@
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { DELIVERY_FEATURE, DeliveryStatus, deliveryAttemptsTable } from "../delivery/index.js";
+import {
+  JOBS_FEATURE,
+  type JobRunStatus,
+  jobRunsTable,
+  tenantJobFailuresTable,
+} from "../jobs/index.js";
+import { SESSIONS_FEATURE, userSessionTable } from "../sessions/index.js";
+import { TENANT_FEATURE, tenantTable } from "../tenant/index.js";
+import { defineMetric } from "./types.js";
+
+const JOB_STATUSES: readonly JobRunStatus[] = ["queued", "running", "completed", "failed"];
+
+function labelKeys(prefix: string, keys: readonly string[]): Readonly<Record<string, string>> {
+  return Object.fromEntries(keys.map((key) => [key, `${prefix}.${key}`]));
+}
+
+const JOB_STATUS_LABELS = labelKeys("metrics:jobStatus", JOB_STATUSES);
+const DELIVERY_STATUS_LABELS = labelKeys("metrics:deliveryStatus", Object.values(DeliveryStatus));
+// Channel ids are open (extension point), so only the bundled ones are mapped;
+// unknown channels fall back to their raw id. Shared map: labelOf serves groupBy and stackBy.
+const DELIVERY_CHANNEL_LABELS = labelKeys("metrics:deliveryChannel", ["inApp", "email", "push"]);
+
+export const jobRunsByStatusMetric = defineMetric({
+  id: "job-runs-by-status",
+  description: "Counts job runs started in the window, split by status over time.",
+  source: jobRunsTable,
+  requires: JOBS_FEATURE,
+  measure: { fn: "count" },
+  timeField: "startedAt",
+  bucket: "auto",
+  groupBy: "status",
+  groupLabels: JOB_STATUS_LABELS,
+  scopes: ["system"],
+});
+
+export const failedJobRunsMetric = defineMetric({
+  id: "failed-job-runs",
+  description: "Counts failed job runs over the last 24 hours, per hour.",
+  source: jobRunsTable,
+  requires: JOBS_FEATURE,
+  measure: { fn: "count" },
+  where: { status: "failed" satisfies JobRunStatus },
+  timeField: "startedAt",
+  window: "24h",
+  bucket: "hour",
+  scopes: ["system"],
+});
+
+export const tenantJobFailuresMetric = defineMetric({
+  id: "tenant-job-failures",
+  description: "Counts tenant-attributed job failures over the last 24 hours, per hour.",
+  source: tenantJobFailuresTable,
+  requires: JOBS_FEATURE,
+  measure: { fn: "count" },
+  timeField: "failedAt",
+  window: "24h",
+  bucket: "hour",
+  scopes: ["tenant", "system"],
+});
+
+export const deliveriesByChannelMetric = defineMetric({
+  id: "deliveries-by-channel",
+  description:
+    "Counts notification delivery attempts in the window per channel, stacked by status.",
+  source: deliveryAttemptsTable,
+  requires: DELIVERY_FEATURE,
+  measure: { fn: "count" },
+  timeField: "createdAt",
+  groupBy: "channel",
+  stackBy: "status",
+  groupLabels: { ...DELIVERY_CHANNEL_LABELS, ...DELIVERY_STATUS_LABELS },
+  scopes: ["tenant", "system"],
+});
+
+export const failedDeliveriesMetric = defineMetric({
+  id: "failed-deliveries",
+  description: "Counts failed notification delivery attempts over the last 24 hours, per hour.",
+  source: deliveryAttemptsTable,
+  requires: DELIVERY_FEATURE,
+  measure: { fn: "count" },
+  where: { status: DeliveryStatus.failed },
+  timeField: "createdAt",
+  window: "24h",
+  bucket: "hour",
+  scopes: ["tenant", "system"],
+});
+
+export const activeUsersMetric = defineMetric({
+  id: "active-users",
+  description: "Counts distinct users with session activity over the last 7 days, per day.",
+  source: userSessionTable,
+  requires: SESSIONS_FEATURE,
+  measure: { fn: "countDistinct", field: "userId" },
+  timeField: "lastSeenAt",
+  window: "7d",
+  bucket: "day",
+  comparePrevious: false,
+  scopes: ["tenant", "system"],
+});
+
+export const activeTenantsMetric = defineMetric({
+  id: "active-tenants",
+  description: "Counts tenants that are enabled and in the active lifecycle state.",
+  source: tenantTable,
+  requires: TENANT_FEATURE,
+  measure: { fn: "count" },
+  where: { isEnabled: true, status: "active" },
+  scopes: ["system"],
+});
+
+export const auditWritesMetric = defineMetric({
+  id: "audit-writes",
+  description: "Counts event-store writes over the last 14 days, per day.",
+  source: eventsTable,
+  measure: { fn: "count" },
+  timeField: "createdAt",
+  window: "14d",
+  bucket: "day",
+  scopes: ["tenant", "system"],
+});
+
+export const DEFAULT_METRICS = [
+  jobRunsByStatusMetric,
+  failedJobRunsMetric,
+  tenantJobFailuresMetric,
+  deliveriesByChannelMetric,
+  failedDeliveriesMetric,
+  activeUsersMetric,
+  activeTenantsMetric,
+  auditWritesMetric,
+] as const;

package/packages/bundled-features/src/metrics/feature.ts

@@ -0,0 +1,159 @@
+import {
+  access,
+  defineFeature,
+  defineQueryHandler,
+  type FeatureDefinition,
+  type QueryHandlerDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "temporal-polyfill";
+import * as z from "zod";
+import { runMetric } from "./compute.js";
+import {
+  METRIC_RANGES,
+  METRICS_FEATURE,
+  METRICS_SYSTEM_FEATURE,
+  type MetricScope,
+} from "./constants.js";
+import { METRICS_I18N } from "./i18n.js";
+import type { MetricDefinition, MetricsFeatureOptions } from "./types.js";
+import { metricHasTenantColumn, validateMetrics } from "./validate.js";
+import { isValidTimeZone } from "./window.js";
+
+const DEFAULT_RANGE = "7d";
+const DEFAULT_TIME_ZONE = "UTC";
+
+const windowFields = {
+  range: z.enum(METRIC_RANGES).default(DEFAULT_RANGE),
+  timeZone: z.string().default(DEFAULT_TIME_ZONE),
+};
+
+const invalidTimeZone = {
+  path: ["timeZone"],
+  message: "Unknown IANA time zone",
+};
+
+const tenantPayloadSchema = z
+  .object(windowFields)
+  .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+
+const systemPayloadSchema = z
+  .object({ ...windowFields, tenantId: z.uuid().optional() })
+  .refine((payload) => isValidTimeZone(payload.timeZone), invalidTimeZone);
+
+const defaultClock = (): Temporal.Instant => Temporal.Now.instant();
+
+function metricsForScope(
+  metrics: readonly MetricDefinition[],
+  scope: MetricScope,
+): readonly MetricDefinition[] {
+  return metrics.filter((metric) => metric.scopes.includes(scope));
+}
+
+function requiredFeatures(metrics: readonly MetricDefinition[]): readonly string[] {
+  const features = metrics.flatMap((metric) =>
+    metric.requires === undefined ? [] : [metric.requires],
+  );
+  return [...new Set(features)];
+}
+
+function createTenantMetricQuery(
+  metric: MetricDefinition,
+  now: () => Temporal.Instant,
+): QueryHandlerDefinition {
+  return defineQueryHandler({
+    name: metric.id,
+    description: metric.description,
+    schema: tenantPayloadSchema,
+    access: { roles: access.admin },
+    handler: (query, ctx) =>
+      runMetric(ctx.db, metric, {
+        range: query.payload.range,
+        timeZone: query.payload.timeZone,
+        now: now(),
+        // ctx.db already reads own-tenant + SYSTEM reference rows; this narrows to own-tenant only.
+        scopeWhere: { tenantId: query.user.tenantId },
+      }),
+  });
+}
+
+function createSystemMetricQuery(
+  metric: MetricDefinition,
+  now: () => Temporal.Instant,
+): QueryHandlerDefinition {
+  return defineQueryHandler({
+    name: metric.id,
+    description: metric.description,
+    schema: systemPayloadSchema,
+    access: { roles: access.systemAdmin },
+    handler: (query, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message: `${METRICS_SYSTEM_FEATURE}:query:${metric.id} requires ctx.systemDb — is r.systemScope() set?`,
+        });
+      }
+      const { tenantId } = query.payload;
+      if (tenantId !== undefined && !metricHasTenantColumn(metric)) {
+        throw new ValidationError({
+          fields: [
+            {
+              path: "tenantId",
+              code: "unsupported",
+              i18nKey: "metrics.errors.tenantFilterUnsupported",
+            },
+          ],
+        });
+      }
+      const db = ctx.systemDb.acknowledgeCrossTenant(
+        `${METRICS_SYSTEM_FEATURE}:${metric.id} — SystemAdmin platform-wide aggregate`,
+      );
+      return runMetric(db, metric, {
+        range: query.payload.range,
+        timeZone: query.payload.timeZone,
+        now: now(),
+        scopeWhere: tenantId === undefined ? {} : { tenantId },
+      });
+    },
+  });
+}
+
+export function createMetricsFeature(options: MetricsFeatureOptions): FeatureDefinition {
+  validateMetrics(options.metrics);
+  const metrics = metricsForScope(options.metrics, "tenant");
+  const now = options.now ?? defaultClock;
+
+  return defineFeature(METRICS_FEATURE, (r) => {
+    r.describe(
+      "Declarative tenant-scoped metrics: each metric declaration becomes an admin-only query that aggregates a read-model table for the caller's own tenant and returns the shape dashboard panels consume (stat value with period delta, time series, ranked rows).",
+    );
+    r.uiHints({
+      displayLabel: "Metrics · Tenant Dashboard Data",
+      category: "operations",
+      recommended: false,
+    });
+    for (const feature of requiredFeatures(metrics)) r.requires(feature);
+    for (const metric of metrics) r.queryHandler(createTenantMetricQuery(metric, now));
+    r.translations({ keys: METRICS_I18N });
+  });
+}
+
+export function createSystemMetricsFeature(options: MetricsFeatureOptions): FeatureDefinition {
+  validateMetrics(options.metrics);
+  const metrics = metricsForScope(options.metrics, "system");
+  const now = options.now ?? defaultClock;
+
+  return defineFeature(METRICS_SYSTEM_FEATURE, (r) => {
+    r.describe(
+      "Declarative platform-wide metrics for SystemAdmin: each metric declaration becomes a query that aggregates a read-model table across all tenants (optionally narrowed to one tenant) and returns the shape dashboard panels consume.",
+    );
+    r.uiHints({
+      displayLabel: "Metrics · Platform Dashboard Data",
+      category: "operations",
+      recommended: false,
+    });
+    r.systemScope();
+    for (const feature of requiredFeatures(metrics)) r.requires(feature);
+    for (const metric of metrics) r.queryHandler(createSystemMetricQuery(metric, now));
+    r.translations({ keys: METRICS_I18N });
+  });
+}

package/packages/bundled-features/src/metrics/i18n.ts

@@ -0,0 +1,18 @@
+type LocalizedString = { readonly en: string };
+
+export const METRICS_I18N: Readonly<Record<string, LocalizedString>> = {
+  "metrics:jobStatus.queued": { en: "Queued" },
+  "metrics:jobStatus.running": { en: "Running" },
+  "metrics:jobStatus.completed": { en: "Completed" },
+  "metrics:jobStatus.failed": { en: "Failed" },
+  "metrics:deliveryStatus.queued": { en: "Queued" },
+  "metrics:deliveryStatus.sent": { en: "Sent" },
+  "metrics:deliveryStatus.failed": { en: "Failed" },
+  "metrics:deliveryStatus.skipped": { en: "Skipped" },
+  "metrics:deliveryChannel.inApp": { en: "In-app" },
+  "metrics:deliveryChannel.email": { en: "Email" },
+  "metrics:deliveryChannel.push": { en: "Push" },
+  "metrics.errors.tenantFilterUnsupported": {
+    en: "This metric's source has no tenant column, so it cannot be narrowed to one tenant.",
+  },
+};

package/packages/bundled-features/src/metrics/index.ts

@@ -0,0 +1,33 @@
+// Public API of the metrics bundled-feature.
+
+export {
+  METRIC_RANGES,
+  METRICS_FEATURE,
+  METRICS_SYSTEM_FEATURE,
+  type MetricRange,
+  type MetricScope,
+  metricQueryName,
+} from "./constants.js";
+export {
+  activeTenantsMetric,
+  activeUsersMetric,
+  auditWritesMetric,
+  DEFAULT_METRICS,
+  deliveriesByChannelMetric,
+  failedDeliveriesMetric,
+  failedJobRunsMetric,
+  jobRunsByStatusMetric,
+  tenantJobFailuresMetric,
+} from "./default-metrics.js";
+export { createMetricsFeature, createSystemMetricsFeature } from "./feature.js";
+export { METRICS_I18N } from "./i18n.js";
+export {
+  defineMetric,
+  type MetricDefinition,
+  type MetricPoint,
+  type MetricResult,
+  type MetricRow,
+  type MetricSegment,
+  type MetricSeries,
+  type MetricsFeatureOptions,
+} from "./types.js";

package/packages/bundled-features/src/metrics/types.ts

@@ -0,0 +1,81 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  AggregateMeasure,
+  AggregateTimeBucket,
+} from "@cosmicdrift/kumiko-types/aggregate-types";
+import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
+import type { Temporal } from "temporal-polyfill";
+import type { MetricRange, MetricScope } from "./constants.js";
+
+export type MetricDefinition = {
+  readonly id: string;
+  readonly description: string;
+  readonly source: SchemaTable | EntityTableMeta;
+  /** Feature that owns the source table; becomes `r.requires(...)`. */
+  readonly requires?: string;
+  readonly measure: AggregateMeasure;
+  readonly where?: WhereObject;
+  /** timestamptz column; without it the metric is a snapshot with no window. */
+  readonly timeField?: string;
+  /** Fixed window, ignores the payload range. */
+  readonly window?: MetricRange;
+  /** "auto": 24h → hour, otherwise day. */
+  readonly bucket?: AggregateTimeBucket | "auto";
+  /** Default true; false skips the previous-period query (no delta), for measures the previous window cannot answer, e.g. overwritten lastSeenAt. */
+  readonly comparePrevious?: boolean;
+  readonly groupBy?: string;
+  /** Second dimension, becomes `rows[].segments`; only without bucket. */
+  readonly stackBy?: string;
+  /** Key value → i18n key, applied to groupBy and stackBy keys. */
+  readonly groupLabels?: Readonly<Record<string, string>>;
+  readonly scopes: readonly MetricScope[];
+};
+
+export function defineMetric(definition: MetricDefinition): MetricDefinition {
+  return definition;
+}
+
+export type MetricPoint = { readonly atMs: number; readonly value: number | null };
+
+export type MetricSeries = {
+  readonly key: string;
+  readonly label: string;
+  readonly points: readonly MetricPoint[];
+};
+
+export type MetricSegment = {
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+};
+
+export type MetricRow = {
+  readonly id: string;
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+  readonly fraction: number;
+  readonly segments?: readonly MetricSegment[];
+};
+
+export type MetricDeltaDirection = "up" | "down";
+
+export type MetricResult = {
+  readonly value: number | null;
+  readonly previousValue: number | null;
+  readonly delta: string | null;
+  readonly deltaDirection: MetricDeltaDirection | null;
+  readonly windowStartMs: number | null;
+  readonly windowEndMs: number | null;
+  readonly points: readonly MetricPoint[];
+  readonly series: readonly MetricSeries[];
+  readonly rows: readonly MetricRow[];
+  readonly nextCursor: null;
+};
+
+export type MetricsFeatureOptions = {
+  readonly metrics: readonly MetricDefinition[];
+  /** Fixed clock for deterministic tests. */
+  readonly now?: () => Temporal.Instant;
+};