@contractspec/lib.metering 1.56.1 → 1.58.0

package/dist/browser/index.js

@@ -0,0 +1,1879 @@
+// src/aggregation/index.ts
+function getPeriodStart(date, periodType) {
+  const d = new Date(date);
+  switch (periodType) {
+    case "HOURLY":
+      d.setMinutes(0, 0, 0);
+      return d;
+    case "DAILY":
+      d.setHours(0, 0, 0, 0);
+      return d;
+    case "WEEKLY": {
+      d.setHours(0, 0, 0, 0);
+      const day = d.getDay();
+      d.setDate(d.getDate() - day);
+      return d;
+    }
+    case "MONTHLY":
+      d.setHours(0, 0, 0, 0);
+      d.setDate(1);
+      return d;
+    case "YEARLY":
+      d.setHours(0, 0, 0, 0);
+      d.setMonth(0, 1);
+      return d;
+  }
+}
+function getPeriodEnd(date, periodType) {
+  const start = getPeriodStart(date, periodType);
+  switch (periodType) {
+    case "HOURLY":
+      return new Date(start.getTime() + 60 * 60 * 1000);
+    case "DAILY":
+      return new Date(start.getTime() + 24 * 60 * 60 * 1000);
+    case "WEEKLY":
+      return new Date(start.getTime() + 7 * 24 * 60 * 60 * 1000);
+    case "MONTHLY": {
+      const end = new Date(start);
+      end.setMonth(end.getMonth() + 1);
+      return end;
+    }
+    case "YEARLY": {
+      const end = new Date(start);
+      end.setFullYear(end.getFullYear() + 1);
+      return end;
+    }
+  }
+}
+function formatPeriodKey(date, periodType) {
+  const start = getPeriodStart(date, periodType);
+  const year = start.getFullYear();
+  const month = String(start.getMonth() + 1).padStart(2, "0");
+  const day = String(start.getDate()).padStart(2, "0");
+  const hour = String(start.getHours()).padStart(2, "0");
+  switch (periodType) {
+    case "HOURLY":
+      return `${year}-${month}-${day}T${hour}`;
+    case "DAILY":
+      return `${year}-${month}-${day}`;
+    case "WEEKLY":
+      return `${year}-W${getWeekNumber(start)}`;
+    case "MONTHLY":
+      return `${year}-${month}`;
+    case "YEARLY":
+      return `${year}`;
+  }
+}
+function getWeekNumber(date) {
+  const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+  const dayNum = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  const weekNum = Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+  return String(weekNum).padStart(2, "0");
+}
+
+class UsageAggregator {
+  storage;
+  batchSize;
+  constructor(options) {
+    this.storage = options.storage;
+    this.batchSize = options.batchSize || 1000;
+  }
+  async aggregate(params) {
+    const { periodType, periodStart, metricKey } = params;
+    const periodEnd = params.periodEnd || getPeriodEnd(periodStart, periodType);
+    const result = {
+      periodType,
+      periodStart,
+      periodEnd,
+      recordsProcessed: 0,
+      summariesCreated: 0,
+      summariesUpdated: 0,
+      errors: []
+    };
+    const records = await this.storage.getUnaggregatedRecords({
+      metricKey,
+      periodStart,
+      periodEnd,
+      limit: this.batchSize
+    });
+    if (records.length === 0) {
+      return result;
+    }
+    const groups = this.groupRecords(records, periodType);
+    for (const [groupKey, groupRecords] of groups.entries()) {
+      try {
+        await this.aggregateGroup(groupKey, groupRecords, periodType, result);
+      } catch (error) {
+        const [metricKey2, subjectType, subjectId] = groupKey.split("::");
+        result.errors.push({
+          metricKey: metricKey2 ?? "unknown",
+          subjectType: subjectType ?? "unknown",
+          subjectId: subjectId ?? "unknown",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    const recordIds = records.map((r) => r.id);
+    await this.storage.markRecordsAggregated(recordIds, new Date);
+    result.recordsProcessed = records.length;
+    return result;
+  }
+  groupRecords(records, periodType) {
+    const groups = new Map;
+    for (const record of records) {
+      const periodKey = formatPeriodKey(record.timestamp, periodType);
+      const groupKey = `${record.metricKey}::${record.subjectType}::${record.subjectId}::${periodKey}`;
+      const existing = groups.get(groupKey) || [];
+      existing.push(record);
+      groups.set(groupKey, existing);
+    }
+    return groups;
+  }
+  async aggregateGroup(groupKey, records, periodType, result) {
+    const [metricKey, subjectType, subjectId] = groupKey.split("::");
+    if (!metricKey || !subjectType || !subjectId || records.length === 0) {
+      return;
+    }
+    const firstRecord = records[0];
+    if (!firstRecord)
+      return;
+    const periodStart = getPeriodStart(firstRecord.timestamp, periodType);
+    const periodEnd = getPeriodEnd(firstRecord.timestamp, periodType);
+    const metric = await this.storage.getMetric(metricKey);
+    const aggregationType = metric?.aggregationType || "SUM";
+    const quantities = records.map((r) => r.quantity);
+    const aggregated = this.calculateAggregation(quantities, aggregationType);
+    await this.storage.upsertSummary({
+      metricKey,
+      subjectType,
+      subjectId,
+      periodType,
+      periodStart,
+      periodEnd,
+      totalQuantity: aggregated.total,
+      recordCount: records.length,
+      minQuantity: aggregated.min,
+      maxQuantity: aggregated.max,
+      avgQuantity: aggregated.avg
+    });
+    result.summariesCreated++;
+  }
+  calculateAggregation(quantities, aggregationType) {
+    if (quantities.length === 0) {
+      return { total: 0, min: 0, max: 0, avg: 0 };
+    }
+    const min = Math.min(...quantities);
+    const max = Math.max(...quantities);
+    const sum = quantities.reduce((a, b) => a + b, 0);
+    const avg = sum / quantities.length;
+    const count = quantities.length;
+    let total;
+    switch (aggregationType) {
+      case "COUNT":
+        total = count;
+        break;
+      case "SUM":
+        total = sum;
+        break;
+      case "AVG":
+        total = avg;
+        break;
+      case "MAX":
+        total = max;
+        break;
+      case "MIN":
+        total = min;
+        break;
+      case "LAST":
+        total = quantities[quantities.length - 1] ?? 0;
+        break;
+      default:
+        total = sum;
+    }
+    return { total, min, max, avg };
+  }
+}
+
+class InMemoryUsageStorage {
+  records = [];
+  summaries = new Map;
+  metrics = new Map;
+  addRecord(record) {
+    this.records.push(record);
+  }
+  addMetric(metric) {
+    this.metrics.set(metric.key, metric);
+  }
+  async getUnaggregatedRecords(options) {
+    let records = this.records.filter((r) => {
+      const inPeriod = r.timestamp >= options.periodStart && r.timestamp < options.periodEnd;
+      const matchesMetric = !options.metricKey || r.metricKey === options.metricKey;
+      return inPeriod && matchesMetric;
+    });
+    if (options.limit) {
+      records = records.slice(0, options.limit);
+    }
+    return records;
+  }
+  async markRecordsAggregated(recordIds) {
+    this.records = this.records.filter((r) => !recordIds.includes(r.id));
+  }
+  async upsertSummary(summary) {
+    const key = `${summary.metricKey}::${summary.subjectType}::${summary.subjectId}::${summary.periodType}::${summary.periodStart.toISOString()}`;
+    const existing = this.summaries.get(key);
+    if (existing) {
+      existing.totalQuantity += summary.totalQuantity;
+      existing.recordCount += summary.recordCount;
+      if (summary.minQuantity !== undefined) {
+        existing.minQuantity = Math.min(existing.minQuantity ?? Infinity, summary.minQuantity);
+      }
+      if (summary.maxQuantity !== undefined) {
+        existing.maxQuantity = Math.max(existing.maxQuantity ?? -Infinity, summary.maxQuantity);
+      }
+      return existing;
+    }
+    const newSummary = {
+      id: `summary-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      ...summary
+    };
+    this.summaries.set(key, newSummary);
+    return newSummary;
+  }
+  async getMetric(key) {
+    return this.metrics.get(key) || null;
+  }
+  async listMetrics() {
+    return Array.from(this.metrics.values());
+  }
+  getSummaries() {
+    return Array.from(this.summaries.values());
+  }
+  clear() {
+    this.records = [];
+    this.summaries.clear();
+    this.metrics.clear();
+  }
+}
+
+// src/analytics/posthog-metering-reader.ts
+class PosthogMeteringReader {
+  reader;
+  eventPrefix;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.eventPrefix = options.eventPrefix ?? "metering";
+  }
+  async getUsageByMetric(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.recordId as recordId,",
+        "  properties.metricKey as metricKey,",
+        "  properties.subjectType as subjectType,",
+        "  distinct_id as subjectId,",
+        "  properties.quantity as quantity,",
+        "  properties.source as source,",
+        "  timestamp as timestamp",
+        "from events",
+        `where ${buildUsageWhereClause(this.eventPrefix, input)}`,
+        "order by timestamp desc",
+        `limit ${input.limit ?? 200}`
+      ].join(`
+`),
+      values: buildUsageValues(input)
+    });
+    return mapUsageRecords(result);
+  }
+  async getUsageSummary(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.summaryId as summaryId,",
+        "  properties.metricKey as metricKey,",
+        "  properties.subjectType as subjectType,",
+        "  distinct_id as subjectId,",
+        "  properties.periodType as periodType,",
+        "  properties.periodStart as periodStart,",
+        "  properties.periodEnd as periodEnd,",
+        "  properties.totalQuantity as totalQuantity,",
+        "  properties.recordCount as recordCount,",
+        "  timestamp as aggregatedAt",
+        "from events",
+        `where ${buildSummaryWhereClause(this.eventPrefix, input)}`,
+        "order by timestamp desc",
+        `limit ${input.limit ?? 200}`
+      ].join(`
+`),
+      values: buildSummaryValues(input)
+    });
+    return mapUsageSummaries(result);
+  }
+  async getUsageTrend(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        `  ${bucketExpression(input.bucket)} as bucketStart,`,
+        "  sum(properties.quantity) as totalQuantity,",
+        "  count() as recordCount",
+        "from events",
+        `where ${buildUsageWhereClause(this.eventPrefix, input)}`,
+        "group by bucketStart",
+        "order by bucketStart asc"
+      ].join(`
+`),
+      values: buildUsageValues(input)
+    });
+    return mapUsageTrend(result);
+  }
+  async queryHogQL(input) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    return this.reader.queryHogQL(input);
+  }
+}
+function buildUsageWhereClause(eventPrefix, input) {
+  const clauses = [
+    `event = '${eventPrefix}.usage_recorded'`,
+    `properties.metricKey = {metricKey}`
+  ];
+  if (input.subjectId) {
+    clauses.push("distinct_id = {subjectId}");
+  }
+  if (input.dateRange?.from) {
+    clauses.push("timestamp >= {dateFrom}");
+  }
+  if (input.dateRange?.to) {
+    clauses.push("timestamp < {dateTo}");
+  }
+  return clauses.join(" and ");
+}
+function buildSummaryWhereClause(eventPrefix, input) {
+  const clauses = [
+    `event = '${eventPrefix}.usage_aggregated'`,
+    `properties.metricKey = {metricKey}`
+  ];
+  if (input.subjectId) {
+    clauses.push("distinct_id = {subjectId}");
+  }
+  if (input.periodType) {
+    clauses.push("properties.periodType = {periodType}");
+  }
+  if (input.dateRange?.from) {
+    clauses.push("timestamp >= {dateFrom}");
+  }
+  if (input.dateRange?.to) {
+    clauses.push("timestamp < {dateTo}");
+  }
+  return clauses.join(" and ");
+}
+function buildUsageValues(input) {
+  return {
+    metricKey: input.metricKey,
+    subjectId: input.subjectId,
+    dateFrom: toIsoString(input.dateRange?.from),
+    dateTo: toIsoString(input.dateRange?.to)
+  };
+}
+function buildSummaryValues(input) {
+  return {
+    metricKey: input.metricKey,
+    subjectId: input.subjectId,
+    periodType: input.periodType,
+    dateFrom: toIsoString(input.dateRange?.from),
+    dateTo: toIsoString(input.dateRange?.to)
+  };
+}
+function bucketExpression(bucket) {
+  switch (bucket) {
+    case "hour":
+      return "toStartOfHour(timestamp)";
+    case "week":
+      return "toStartOfWeek(timestamp)";
+    case "month":
+      return "toStartOfMonth(timestamp)";
+    case "day":
+    default:
+      return "toStartOfDay(timestamp)";
+  }
+}
+function mapUsageRecords(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const metricKey = asString(row.metricKey);
+    const subjectType = asString(row.subjectType);
+    const subjectId = asString(row.subjectId);
+    const timestamp = asDate(row.timestamp);
+    if (!metricKey || !subjectType || !subjectId || !timestamp) {
+      return [];
+    }
+    return [
+      {
+        recordId: asOptionalString(row.recordId),
+        metricKey,
+        subjectType,
+        subjectId,
+        quantity: asNumber(row.quantity),
+        source: asOptionalString(row.source),
+        timestamp
+      }
+    ];
+  });
+}
+function mapUsageSummaries(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const metricKey = asString(row.metricKey);
+    const subjectType = asString(row.subjectType);
+    const subjectId = asString(row.subjectId);
+    const periodType = asString(row.periodType);
+    const periodStart = asDate(row.periodStart);
+    const periodEnd = asDate(row.periodEnd);
+    const aggregatedAt = asDate(row.aggregatedAt);
+    if (!metricKey || !subjectType || !subjectId || !periodType || !periodStart || !periodEnd || !aggregatedAt) {
+      return [];
+    }
+    return [
+      {
+        summaryId: asOptionalString(row.summaryId),
+        metricKey,
+        subjectType,
+        subjectId,
+        periodType,
+        periodStart,
+        periodEnd,
+        totalQuantity: asNumber(row.totalQuantity),
+        recordCount: asNumber(row.recordCount),
+        aggregatedAt
+      }
+    ];
+  });
+}
+function mapUsageTrend(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const bucketStart = asString(row.bucketStart);
+    if (!bucketStart)
+      return [];
+    return [
+      {
+        bucketStart,
+        totalQuantity: asNumber(row.totalQuantity),
+        recordCount: asNumber(row.recordCount)
+      }
+    ];
+  });
+}
+function mapRows(result) {
+  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
+    return [];
+  }
+  const columns = result.columns;
+  return result.results.flatMap((row) => {
+    if (!Array.isArray(row))
+      return [];
+    const record = {};
+    columns.forEach((column, index) => {
+      record[column] = row[index];
+    });
+    return [record];
+  });
+}
+function asString(value) {
+  if (typeof value === "string" && value.trim())
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asOptionalString(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed))
+      return parsed;
+  }
+  return 0;
+}
+function asDate(value) {
+  if (value instanceof Date)
+    return value;
+  if (typeof value === "string" || typeof value === "number") {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime()))
+      return date;
+  }
+  return null;
+}
+function toIsoString(value) {
+  if (!value)
+    return;
+  return typeof value === "string" ? value : value.toISOString();
+}
+
+// src/analytics/posthog-metering.ts
+class PosthogMeteringReporter {
+  provider;
+  eventPrefix;
+  includeSource;
+  constructor(provider, options = {}) {
+    this.provider = provider;
+    this.eventPrefix = options.eventPrefix ?? "metering";
+    this.includeSource = options.includeSource ?? true;
+  }
+  async captureUsageRecorded(record) {
+    await this.provider.capture({
+      distinctId: record.subjectId,
+      event: `${this.eventPrefix}.usage_recorded`,
+      timestamp: record.timestamp,
+      properties: {
+        recordId: record.recordId ?? null,
+        metricKey: record.metricKey,
+        subjectType: record.subjectType,
+        quantity: record.quantity,
+        ...this.includeSource && record.source ? { source: record.source } : {}
+      }
+    });
+  }
+  async captureUsageAggregated(summary) {
+    await this.provider.capture({
+      distinctId: summary.subjectId,
+      event: `${this.eventPrefix}.usage_aggregated`,
+      timestamp: summary.aggregatedAt,
+      properties: {
+        summaryId: summary.summaryId ?? null,
+        metricKey: summary.metricKey,
+        subjectType: summary.subjectType,
+        periodType: summary.periodType,
+        periodStart: summary.periodStart.toISOString(),
+        periodEnd: summary.periodEnd.toISOString(),
+        totalQuantity: summary.totalQuantity,
+        recordCount: summary.recordCount
+      }
+    });
+  }
+}
+
+// src/contracts/index.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var OWNERS = ["platform.metering"];
+var MetricDefinitionModel = defineSchemaModel({
+  name: "MetricDefinition",
+  description: "Represents a metric definition",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    unit: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    aggregationType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    resetPeriod: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    category: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isActive: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var UsageRecordModel = defineSchemaModel({
+  name: "UsageRecord",
+  description: "Represents a usage record",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    source: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    resourceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    resourceType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var UsageSummaryModel = defineSchemaModel({
+  name: "UsageSummary",
+  description: "Represents aggregated usage",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    periodType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    periodStart: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    periodEnd: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    totalQuantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    recordCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    minQuantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    maxQuantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    avgQuantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true }
+  }
+});
+var UsageThresholdModel = defineSchemaModel({
+  name: "UsageThreshold",
+  description: "Represents a usage threshold",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    threshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    warnThreshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    periodType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    action: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    currentValue: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    isActive: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var DefineMetricInput = defineSchemaModel({
+  name: "DefineMetricInput",
+  description: "Input for defining a metric",
+  fields: {
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    unit: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    aggregationType: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    resetPeriod: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    category: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+var UpdateMetricInput = defineSchemaModel({
+  name: "UpdateMetricInput",
+  description: "Input for updating a metric",
+  fields: {
+    metricId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    category: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isActive: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    metadata: { type: ScalarTypeEnum.JSON(), isOptional: true }
+  }
+});
+var DeleteMetricInput = defineSchemaModel({
+  name: "DeleteMetricInput",
+  description: "Input for deleting a metric",
+  fields: {
+    metricId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var GetMetricInput = defineSchemaModel({
+  name: "GetMetricInput",
+  description: "Input for getting a metric",
+  fields: {
+    key: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var ListMetricsInput = defineSchemaModel({
+  name: "ListMetricsInput",
+  description: "Input for listing metrics",
+  fields: {
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    category: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isActive: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    offset: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var ListMetricsOutput = defineSchemaModel({
+  name: "ListMetricsOutput",
+  description: "Output for listing metrics",
+  fields: {
+    metrics: { type: MetricDefinitionModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var RecordUsageInput = defineSchemaModel({
+  name: "RecordUsageInput",
+  description: "Input for recording usage",
+  fields: {
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    timestamp: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    source: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    resourceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    resourceType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    idempotencyKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    }
+  }
+});
+var RecordBatchUsageInput = defineSchemaModel({
+  name: "RecordBatchUsageInput",
+  description: "Input for recording batch usage",
+  fields: {
+    records: { type: RecordUsageInput, isArray: true, isOptional: false }
+  }
+});
+var RecordBatchUsageOutput = defineSchemaModel({
+  name: "RecordBatchUsageOutput",
+  description: "Output for recording batch usage",
+  fields: {
+    recordedCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    skippedCount: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    recordIds: { type: ScalarTypeEnum.JSON(), isOptional: false }
+  }
+});
+var GetUsageInput = defineSchemaModel({
+  name: "GetUsageInput",
+  description: "Input for getting usage",
+  fields: {
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    startDate: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    endDate: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    limit: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    offset: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var GetUsageOutput = defineSchemaModel({
+  name: "GetUsageOutput",
+  description: "Output for getting usage",
+  fields: {
+    records: { type: UsageRecordModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    totalQuantity: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false }
+  }
+});
+var GetUsageSummaryInput = defineSchemaModel({
+  name: "GetUsageSummaryInput",
+  description: "Input for getting usage summary",
+  fields: {
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    periodType: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    startDate: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    endDate: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var GetUsageSummaryOutput = defineSchemaModel({
+  name: "GetUsageSummaryOutput",
+  description: "Output for getting usage summary",
+  fields: {
+    summaries: { type: UsageSummaryModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var CreateThresholdInput = defineSchemaModel({
+  name: "CreateThresholdInput",
+  description: "Input for creating a threshold",
+  fields: {
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    threshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    warnThreshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    periodType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    action: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    notifyEmails: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    notifyWebhook: { type: ScalarTypeEnum.String_unsecure(), isOptional: true }
+  }
+});
+var UpdateThresholdInput = defineSchemaModel({
+  name: "UpdateThresholdInput",
+  description: "Input for updating a threshold",
+  fields: {
+    thresholdId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    threshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    warnThreshold: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    action: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    notifyEmails: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    notifyWebhook: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isActive: { type: ScalarTypeEnum.Boolean(), isOptional: true }
+  }
+});
+var DeleteThresholdInput = defineSchemaModel({
+  name: "DeleteThresholdInput",
+  description: "Input for deleting a threshold",
+  fields: {
+    thresholdId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+  }
+});
+var ListThresholdsInput = defineSchemaModel({
+  name: "ListThresholdsInput",
+  description: "Input for listing thresholds",
+  fields: {
+    metricKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    subjectType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    isActive: { type: ScalarTypeEnum.Boolean(), isOptional: true }
+  }
+});
+var ListThresholdsOutput = defineSchemaModel({
+  name: "ListThresholdsOutput",
+  description: "Output for listing thresholds",
+  fields: {
+    thresholds: { type: UsageThresholdModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false }
+  }
+});
+var SuccessOutput = defineSchemaModel({
+  name: "SuccessOutput",
+  description: "Generic success output",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var DefineMetricContract = defineCommand({
+  meta: {
+    key: "metric.define",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "metric", "define"],
+    description: "Define a new usage metric.",
+    goal: "Create a new metric for tracking usage.",
+    context: "Called when setting up metering."
+  },
+  io: {
+    input: DefineMetricInput,
+    output: MetricDefinitionModel,
+    errors: {
+      METRIC_KEY_EXISTS: {
+        description: "Metric key already exists",
+        http: 409,
+        gqlCode: "METRIC_KEY_EXISTS",
+        when: "A metric with this key already exists"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var UpdateMetricContract = defineCommand({
+  meta: {
+    key: "metric.update",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "metric", "update"],
+    description: "Update a metric definition.",
+    goal: "Modify metric configuration.",
+    context: "Called when updating metric settings."
+  },
+  io: {
+    input: UpdateMetricInput,
+    output: MetricDefinitionModel,
+    errors: {
+      METRIC_NOT_FOUND: {
+        description: "Metric does not exist",
+        http: 404,
+        gqlCode: "METRIC_NOT_FOUND",
+        when: "Metric ID is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var DeleteMetricContract = defineCommand({
+  meta: {
+    key: "metric.delete",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "metric", "delete"],
+    description: "Delete a metric definition.",
+    goal: "Remove a metric and its data.",
+    context: "Called when removing a metric."
+  },
+  io: {
+    input: DeleteMetricInput,
+    output: SuccessOutput,
+    errors: {
+      METRIC_NOT_FOUND: {
+        description: "Metric does not exist",
+        http: 404,
+        gqlCode: "METRIC_NOT_FOUND",
+        when: "Metric ID is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var GetMetricContract = defineQuery({
+  meta: {
+    key: "metric.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "metric", "get"],
+    description: "Get a metric by key.",
+    goal: "Retrieve metric definition.",
+    context: "Called to inspect metric details."
+  },
+  io: {
+    input: GetMetricInput,
+    output: MetricDefinitionModel,
+    errors: {
+      METRIC_NOT_FOUND: {
+        description: "Metric does not exist",
+        http: 404,
+        gqlCode: "METRIC_NOT_FOUND",
+        when: "Metric key is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var ListMetricsContract = defineQuery({
+  meta: {
+    key: "metric.list",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "metric", "list"],
+    description: "List all metrics.",
+    goal: "View configured metrics.",
+    context: "Called to browse metrics."
+  },
+  io: {
+    input: ListMetricsInput,
+    output: ListMetricsOutput
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var RecordUsageContract = defineCommand({
+  meta: {
+    key: "usage.record",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "usage", "record"],
+    description: "Record a usage event.",
+    goal: "Track usage for billing and monitoring.",
+    context: "Called when usage occurs."
+  },
+  io: {
+    input: RecordUsageInput,
+    output: UsageRecordModel,
+    errors: {
+      METRIC_NOT_FOUND: {
+        description: "Metric does not exist",
+        http: 404,
+        gqlCode: "METRIC_NOT_FOUND",
+        when: "Metric key is invalid"
+      },
+      DUPLICATE_RECORD: {
+        description: "Record already exists",
+        http: 409,
+        gqlCode: "DUPLICATE_RECORD",
+        when: "Idempotency key already used"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var RecordBatchUsageContract = defineCommand({
+  meta: {
+    key: "usage.recordBatch",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "usage", "batch"],
+    description: "Record multiple usage events.",
+    goal: "Efficiently track bulk usage.",
+    context: "Called for batch processing."
+  },
+  io: {
+    input: RecordBatchUsageInput,
+    output: RecordBatchUsageOutput
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var GetUsageContract = defineQuery({
+  meta: {
+    key: "usage.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "usage", "get"],
+    description: "Get usage records for a subject.",
+    goal: "View detailed usage history.",
+    context: "Called to analyze usage."
+  },
+  io: {
+    input: GetUsageInput,
+    output: GetUsageOutput
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var GetUsageSummaryContract = defineQuery({
+  meta: {
+    key: "usage.getSummary",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "usage", "summary"],
+    description: "Get aggregated usage summary.",
+    goal: "View usage totals for billing.",
+    context: "Called for billing and reporting."
+  },
+  io: {
+    input: GetUsageSummaryInput,
+    output: GetUsageSummaryOutput
+  },
+  policy: {
+    auth: "user"
+  }
+});
+var CreateThresholdContract = defineCommand({
+  meta: {
+    key: "threshold.create",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "threshold", "create"],
+    description: "Create a usage threshold.",
+    goal: "Set up usage limits and alerts.",
+    context: "Called when configuring limits."
+  },
+  io: {
+    input: CreateThresholdInput,
+    output: UsageThresholdModel,
+    errors: {
+      METRIC_NOT_FOUND: {
+        description: "Metric does not exist",
+        http: 404,
+        gqlCode: "METRIC_NOT_FOUND",
+        when: "Metric key is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var UpdateThresholdContract = defineCommand({
+  meta: {
+    key: "threshold.update",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "threshold", "update"],
+    description: "Update a threshold.",
+    goal: "Modify threshold configuration.",
+    context: "Called when adjusting limits."
+  },
+  io: {
+    input: UpdateThresholdInput,
+    output: UsageThresholdModel,
+    errors: {
+      THRESHOLD_NOT_FOUND: {
+        description: "Threshold does not exist",
+        http: 404,
+        gqlCode: "THRESHOLD_NOT_FOUND",
+        when: "Threshold ID is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var DeleteThresholdContract = defineCommand({
+  meta: {
+    key: "threshold.delete",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "threshold", "delete"],
+    description: "Delete a threshold.",
+    goal: "Remove a usage threshold.",
+    context: "Called when removing limits."
+  },
+  io: {
+    input: DeleteThresholdInput,
+    output: SuccessOutput,
+    errors: {
+      THRESHOLD_NOT_FOUND: {
+        description: "Threshold does not exist",
+        http: 404,
+        gqlCode: "THRESHOLD_NOT_FOUND",
+        when: "Threshold ID is invalid"
+      }
+    }
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var ListThresholdsContract = defineQuery({
+  meta: {
+    key: "threshold.list",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["metering", "threshold", "list"],
+    description: "List usage thresholds.",
+    goal: "View configured limits.",
+    context: "Called to browse thresholds."
+  },
+  io: {
+    input: ListThresholdsInput,
+    output: ListThresholdsOutput
+  },
+  policy: {
+    auth: "user"
+  }
+});
+
+// src/docs/metering.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var meteringDocBlocks = [
+  {
+    id: "docs.metering.usage",
+    title: "Usage Metering & Billing Core",
+    summary: "Reusable usage/metering layer with metric definitions, usage ingestion, aggregation, thresholds, and alerts for billing or quotas.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/metering/usage",
+    tags: ["metering", "usage", "billing", "quotas"],
+    body: `## Capabilities
+
+- **Entities**: MetricDefinition, UsageRecord, UsageSummary, UsageThreshold, UsageAlert.
+- **Contracts**: define/list metrics; record usage (batch + idempotent); retrieve usage by subject; manage thresholds and alerts.
+- **Aggregation**: hourly/daily/weekly/monthly rollups with SUM/COUNT/AVG/MIN/MAX/LAST strategies.
+- **Events**: usage.recorded, usage.aggregated, threshold.exceeded (see events export).
+
+## Usage
+
+1) Compose schema
+- Add \`meteringSchemaContribution\` to your schema composition.
+
+2) Register contracts/events
+- Import from \`@contractspec/lib.metering\` into your spec registry.
+
+3) Ingest usage
+- Use \`recordUsage\` contract (see contracts export) from application services whenever a billable/important action happens (e.g., agent run, API call).
+
+4) Aggregate + thresholds
+- Run scheduled jobs using \`aggregateUsage\` helper to roll up summaries.
+- Configure \`UsageThreshold\` to emit alerts or blocking actions; pipe alerts into Notifications/Audit.
+- Use \`PosthogMeteringReader\` to backfill or validate usage from PostHog events.
+
+## Example
+
+${"```"}ts
+import { meteringSchemaContribution } from '@contractspec/lib.metering';
+import { aggregateUsage } from '@contractspec/lib.metering/aggregation';
+
+// schema composition
+const schema = {
+  modules: [meteringSchemaContribution],
+};
+
+// aggregation job
+await aggregateUsage({
+  metrics: metricRepository,
+  usage: usageRepository,
+  period: 'DAILY',
+});
+${"```"},
+
+## Guardrails
+
+- Keep metric keys stable; store quantities as decimals for currency/units.
+- Use idempotency keys for external ingestion; avoid PII in metric metadata.
+- Scope by org/user for multi-tenant isolation; emit audit + analytics events on changes.
+`
+  }
+];
+registerDocBlocks(meteringDocBlocks);
+// src/entities/index.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var AggregationTypeEnum = defineEntityEnum({
+  name: "AggregationType",
+  values: ["COUNT", "SUM", "AVG", "MAX", "MIN", "LAST"],
+  schema: "lssm_metering",
+  description: "How to aggregate metric values."
+});
+var ResetPeriodEnum = defineEntityEnum({
+  name: "ResetPeriod",
+  values: ["NEVER", "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY"],
+  schema: "lssm_metering",
+  description: "When to reset metric counters."
+});
+var PeriodTypeEnum = defineEntityEnum({
+  name: "PeriodType",
+  values: ["HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY"],
+  schema: "lssm_metering",
+  description: "Time period for aggregation."
+});
+var ThresholdActionEnum = defineEntityEnum({
+  name: "ThresholdAction",
+  values: ["NONE", "ALERT", "WARN", "BLOCK", "DOWNGRADE"],
+  schema: "lssm_metering",
+  description: "Action to take when threshold is exceeded."
+});
+var MetricDefinitionEntity = defineEntity({
+  name: "MetricDefinition",
+  description: "Definition of a usage metric.",
+  schema: "lssm_metering",
+  map: "metric_definition",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    key: field.string({
+      isUnique: true,
+      description: "Metric key (e.g., api_calls, storage_gb)"
+    }),
+    name: field.string({ description: "Human-readable name" }),
+    description: field.string({
+      isOptional: true,
+      description: "Metric description"
+    }),
+    unit: field.string({
+      description: "Unit of measurement (calls, bytes, etc.)"
+    }),
+    aggregationType: field.enum("AggregationType", {
+      default: "SUM",
+      description: "How to aggregate values"
+    }),
+    resetPeriod: field.enum("ResetPeriod", {
+      default: "MONTHLY",
+      description: "When to reset counters"
+    }),
+    precision: field.int({ default: 2, description: "Decimal precision" }),
+    orgId: field.string({
+      isOptional: true,
+      description: "Organization scope (null = global metric)"
+    }),
+    category: field.string({
+      isOptional: true,
+      description: "Category for grouping"
+    }),
+    displayOrder: field.int({ default: 0, description: "Order for display" }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    isActive: field.boolean({
+      default: true,
+      description: "Whether metric is active"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    usageRecords: field.hasMany("UsageRecord"),
+    usageSummaries: field.hasMany("UsageSummary"),
+    thresholds: field.hasMany("UsageThreshold")
+  },
+  indexes: [
+    index.on(["orgId", "key"]),
+    index.on(["category"]),
+    index.on(["isActive"])
+  ],
+  enums: [AggregationTypeEnum, ResetPeriodEnum]
+});
+var UsageRecordEntity = defineEntity({
+  name: "UsageRecord",
+  description: "A single usage event.",
+  schema: "lssm_metering",
+  map: "usage_record",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    metricKey: field.string({ description: "Metric being recorded" }),
+    metricId: field.string({
+      isOptional: true,
+      description: "Metric ID (for FK)"
+    }),
+    subjectType: field.string({
+      description: "Subject type (org, user, project)"
+    }),
+    subjectId: field.string({ description: "Subject identifier" }),
+    quantity: field.decimal({ description: "Usage quantity" }),
+    source: field.string({
+      isOptional: true,
+      description: "Source of usage (endpoint, feature, etc.)"
+    }),
+    resourceId: field.string({
+      isOptional: true,
+      description: "Related resource ID"
+    }),
+    resourceType: field.string({
+      isOptional: true,
+      description: "Related resource type"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional context"
+    }),
+    idempotencyKey: field.string({
+      isOptional: true,
+      description: "Idempotency key for deduplication"
+    }),
+    timestamp: field.dateTime({ description: "When usage occurred" }),
+    createdAt: field.createdAt(),
+    aggregated: field.boolean({
+      default: false,
+      description: "Whether included in summary"
+    }),
+    aggregatedAt: field.dateTime({
+      isOptional: true,
+      description: "When aggregated"
+    })
+  },
+  indexes: [
+    index.on(["metricKey", "subjectType", "subjectId", "timestamp"]),
+    index.on(["subjectType", "subjectId", "timestamp"]),
+    index.on(["timestamp"]),
+    index.on(["aggregated", "timestamp"]),
+    index.unique(["idempotencyKey"], { name: "usage_record_idempotency" })
+  ]
+});
+var UsageSummaryEntity = defineEntity({
+  name: "UsageSummary",
+  description: "Pre-aggregated usage summary.",
+  schema: "lssm_metering",
+  map: "usage_summary",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    metricKey: field.string({ description: "Metric key" }),
+    metricId: field.string({
+      isOptional: true,
+      description: "Metric ID (for FK)"
+    }),
+    subjectType: field.string({ description: "Subject type" }),
+    subjectId: field.string({ description: "Subject identifier" }),
+    periodType: field.enum("PeriodType", { description: "Period type" }),
+    periodStart: field.dateTime({ description: "Period start time" }),
+    periodEnd: field.dateTime({ description: "Period end time" }),
+    totalQuantity: field.decimal({ description: "Total/aggregated quantity" }),
+    recordCount: field.int({
+      default: 0,
+      description: "Number of records aggregated"
+    }),
+    minQuantity: field.decimal({
+      isOptional: true,
+      description: "Minimum value"
+    }),
+    maxQuantity: field.decimal({
+      isOptional: true,
+      description: "Maximum value"
+    }),
+    avgQuantity: field.decimal({
+      isOptional: true,
+      description: "Average value"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt()
+  },
+  indexes: [
+    index.unique(["metricKey", "subjectType", "subjectId", "periodType", "periodStart"], { name: "usage_summary_unique" }),
+    index.on(["subjectType", "subjectId", "periodType", "periodStart"]),
+    index.on(["metricKey", "periodType", "periodStart"])
+  ],
+  enums: [PeriodTypeEnum]
+});
+var UsageThresholdEntity = defineEntity({
+  name: "UsageThreshold",
+  description: "Usage threshold configuration.",
+  schema: "lssm_metering",
+  map: "usage_threshold",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    metricKey: field.string({ description: "Metric to monitor" }),
+    metricId: field.string({
+      isOptional: true,
+      description: "Metric ID (for FK)"
+    }),
+    subjectType: field.string({
+      isOptional: true,
+      description: "Subject type"
+    }),
+    subjectId: field.string({
+      isOptional: true,
+      description: "Subject identifier"
+    }),
+    name: field.string({ description: "Threshold name" }),
+    threshold: field.decimal({ description: "Threshold value" }),
+    warnThreshold: field.decimal({
+      isOptional: true,
+      description: "Warning threshold (e.g., 80%)"
+    }),
+    periodType: field.enum("PeriodType", {
+      default: "MONTHLY",
+      description: "Period to evaluate"
+    }),
+    action: field.enum("ThresholdAction", {
+      default: "ALERT",
+      description: "Action when exceeded"
+    }),
+    notifyEmails: field.json({
+      isOptional: true,
+      description: "Email addresses to notify"
+    }),
+    notifyWebhook: field.string({
+      isOptional: true,
+      description: "Webhook URL to call"
+    }),
+    currentValue: field.decimal({
+      default: 0,
+      description: "Current usage value"
+    }),
+    lastCheckedAt: field.dateTime({
+      isOptional: true,
+      description: "Last threshold check"
+    }),
+    lastExceededAt: field.dateTime({
+      isOptional: true,
+      description: "Last time threshold was exceeded"
+    }),
+    isActive: field.boolean({
+      default: true,
+      description: "Whether threshold is active"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt()
+  },
+  indexes: [
+    index.on(["metricKey"]),
+    index.on(["subjectType", "subjectId"]),
+    index.on(["isActive", "metricKey"])
+  ],
+  enums: [ThresholdActionEnum]
+});
+var UsageAlertEntity = defineEntity({
+  name: "UsageAlert",
+  description: "Alert generated when threshold is exceeded.",
+  schema: "lssm_metering",
+  map: "usage_alert",
+  fields: {
+    id: field.id({ description: "Unique identifier" }),
+    thresholdId: field.foreignKey({
+      description: "Threshold that triggered alert"
+    }),
+    metricKey: field.string({ description: "Metric key" }),
+    subjectType: field.string({
+      isOptional: true,
+      description: "Subject type"
+    }),
+    subjectId: field.string({
+      isOptional: true,
+      description: "Subject identifier"
+    }),
+    alertType: field.string({ description: "Alert type (warn, exceed, etc.)" }),
+    threshold: field.decimal({ description: "Threshold value" }),
+    actualValue: field.decimal({ description: "Actual usage value" }),
+    percentageUsed: field.decimal({
+      description: "Percentage of threshold used"
+    }),
+    status: field.string({
+      default: '"pending"',
+      description: "Alert status (pending, acknowledged, resolved)"
+    }),
+    acknowledgedBy: field.string({
+      isOptional: true,
+      description: "User who acknowledged"
+    }),
+    acknowledgedAt: field.dateTime({
+      isOptional: true,
+      description: "When acknowledged"
+    }),
+    resolvedAt: field.dateTime({
+      isOptional: true,
+      description: "When resolved"
+    }),
+    notificationsSent: field.json({
+      isOptional: true,
+      description: "Notifications sent"
+    }),
+    triggeredAt: field.dateTime({ description: "When alert was triggered" }),
+    createdAt: field.createdAt(),
+    thresholdRelation: field.belongsTo("UsageThreshold", ["thresholdId"], ["id"], { onDelete: "Cascade" })
+  },
+  indexes: [
+    index.on(["thresholdId", "status"]),
+    index.on(["metricKey", "triggeredAt"]),
+    index.on(["status", "triggeredAt"])
+  ]
+});
+var meteringEntities = [
+  MetricDefinitionEntity,
+  UsageRecordEntity,
+  UsageSummaryEntity,
+  UsageThresholdEntity,
+  UsageAlertEntity
+];
+var meteringSchemaContribution = {
+  moduleId: "@contractspec/lib.metering",
+  entities: meteringEntities,
+  enums: [
+    AggregationTypeEnum,
+    ResetPeriodEnum,
+    PeriodTypeEnum,
+    ThresholdActionEnum
+  ]
+};
+
+// src/events.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, defineSchemaModel as defineSchemaModel2 } from "@contractspec/lib.schema";
+import { defineEvent } from "@contractspec/lib.contracts";
+var MetricDefinedPayload = defineSchemaModel2({
+  name: "MetricDefinedEventPayload",
+  description: "Payload when a metric is defined",
+  fields: {
+    metricId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    unit: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    aggregationType: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: false
+    },
+    orgId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    createdBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var MetricUpdatedPayload = defineSchemaModel2({
+  name: "MetricUpdatedEventPayload",
+  description: "Payload when a metric is updated",
+  fields: {
+    metricId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    key: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    changes: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+    updatedBy: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    updatedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var UsageRecordedPayload = defineSchemaModel2({
+  name: "UsageRecordedEventPayload",
+  description: "Payload when usage is recorded",
+  fields: {
+    recordId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    quantity: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    source: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    timestamp: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var UsageBatchRecordedPayload = defineSchemaModel2({
+  name: "UsageBatchRecordedEventPayload",
+  description: "Payload when a batch of usage is recorded",
+  fields: {
+    recordCount: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    metricKeys: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+    totalQuantity: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    timestamp: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var UsageAggregatedPayload = defineSchemaModel2({
+  name: "UsageAggregatedEventPayload",
+  description: "Payload when usage is aggregated",
+  fields: {
+    summaryId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    periodType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    periodStart: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    periodEnd: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    totalQuantity: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    recordCount: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    aggregatedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ThresholdCreatedPayload = defineSchemaModel2({
+  name: "ThresholdCreatedEventPayload",
+  description: "Payload when a threshold is created",
+  fields: {
+    thresholdId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    threshold: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    action: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ThresholdExceededPayload = defineSchemaModel2({
+  name: "ThresholdExceededEventPayload",
+  description: "Payload when a threshold is exceeded",
+  fields: {
+    alertId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    thresholdId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    threshold: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    actualValue: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    percentageUsed: {
+      type: ScalarTypeEnum2.Float_unsecure(),
+      isOptional: false
+    },
+    action: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    triggeredAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var ThresholdApproachingPayload = defineSchemaModel2({
+  name: "ThresholdApproachingEventPayload",
+  description: "Payload when usage is approaching a threshold",
+  fields: {
+    thresholdId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    metricKey: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+    subjectType: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    subjectId: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    threshold: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    currentValue: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: false },
+    percentageUsed: {
+      type: ScalarTypeEnum2.Float_unsecure(),
+      isOptional: false
+    },
+    triggeredAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false }
+  }
+});
+var MetricDefinedEvent = defineEvent({
+  meta: {
+    key: "metric.defined",
+    version: "1.0.0",
+    description: "A metric has been defined.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "metric"]
+  },
+  payload: MetricDefinedPayload
+});
+var MetricUpdatedEvent = defineEvent({
+  meta: {
+    key: "metric.updated",
+    version: "1.0.0",
+    description: "A metric has been updated.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "metric"]
+  },
+  payload: MetricUpdatedPayload
+});
+var UsageRecordedEvent = defineEvent({
+  meta: {
+    key: "usage.recorded",
+    version: "1.0.0",
+    description: "Usage has been recorded.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage"]
+  },
+  payload: UsageRecordedPayload
+});
+var UsageBatchRecordedEvent = defineEvent({
+  meta: {
+    key: "usage.batch_recorded",
+    version: "1.0.0",
+    description: "A batch of usage has been recorded.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage"]
+  },
+  payload: UsageBatchRecordedPayload
+});
+var UsageAggregatedEvent = defineEvent({
+  meta: {
+    key: "usage.aggregated",
+    version: "1.0.0",
+    description: "Usage has been aggregated into a summary.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage"]
+  },
+  payload: UsageAggregatedPayload
+});
+var ThresholdCreatedEvent = defineEvent({
+  meta: {
+    key: "threshold.created",
+    version: "1.0.0",
+    description: "A usage threshold has been created.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "threshold"]
+  },
+  payload: ThresholdCreatedPayload
+});
+var ThresholdExceededEvent = defineEvent({
+  meta: {
+    key: "threshold.exceeded",
+    version: "1.0.0",
+    description: "Usage has exceeded a threshold.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "threshold"]
+  },
+  payload: ThresholdExceededPayload
+});
+var ThresholdApproachingEvent = defineEvent({
+  meta: {
+    key: "threshold.approaching",
+    version: "1.0.0",
+    description: "Usage is approaching a threshold.",
+    stability: "stable",
+    owners: ["@platform.metering"],
+    tags: ["metering", "threshold"]
+  },
+  payload: ThresholdApproachingPayload
+});
+var MeteringEvents = {
+  MetricDefinedEvent,
+  MetricUpdatedEvent,
+  UsageRecordedEvent,
+  UsageBatchRecordedEvent,
+  UsageAggregatedEvent,
+  ThresholdCreatedEvent,
+  ThresholdExceededEvent,
+  ThresholdApproachingEvent
+};
+
+// src/metering.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var MeteringFeature = defineFeature({
+  meta: {
+    key: "metrics",
+    version: "1.0.0",
+    title: "Usage Metering",
+    description: "Usage metering, metric definitions, and threshold alerting",
+    domain: "platform",
+    owners: ["@platform.metering"],
+    tags: ["metering", "usage", "billing", "thresholds"],
+    stability: "stable"
+  },
+  operations: [
+    { key: "metric.define", version: "1.0.0" },
+    { key: "metric.update", version: "1.0.0" },
+    { key: "metric.delete", version: "1.0.0" },
+    { key: "metric.get", version: "1.0.0" },
+    { key: "metric.list", version: "1.0.0" },
+    { key: "usage.record", version: "1.0.0" },
+    { key: "usage.recordBatch", version: "1.0.0" },
+    { key: "usage.get", version: "1.0.0" },
+    { key: "usage.getSummary", version: "1.0.0" },
+    { key: "threshold.create", version: "1.0.0" },
+    { key: "threshold.update", version: "1.0.0" },
+    { key: "threshold.delete", version: "1.0.0" },
+    { key: "threshold.list", version: "1.0.0" }
+  ],
+  events: [
+    { key: "metric.defined", version: "1.0.0" },
+    { key: "metric.updated", version: "1.0.0" },
+    { key: "usage.recorded", version: "1.0.0" },
+    { key: "usage.batch_recorded", version: "1.0.0" },
+    { key: "usage.aggregated", version: "1.0.0" },
+    { key: "threshold.created", version: "1.0.0" },
+    { key: "threshold.exceeded", version: "1.0.0" },
+    { key: "threshold.approaching", version: "1.0.0" }
+  ],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    provides: [
+      { key: "metering", version: "1.0.0" },
+      { key: "thresholds", version: "1.0.0" }
+    ],
+    requires: []
+  }
+});
+export {
+  meteringSchemaContribution,
+  meteringEntities,
+  getPeriodStart,
+  getPeriodEnd,
+  formatPeriodKey,
+  UsageThresholdModel,
+  UsageThresholdEntity,
+  UsageSummaryModel,
+  UsageSummaryEntity,
+  UsageRecordedEvent,
+  UsageRecordModel,
+  UsageRecordEntity,
+  UsageBatchRecordedEvent,
+  UsageAlertEntity,
+  UsageAggregator,
+  UsageAggregatedEvent,
+  UpdateThresholdContract,
+  UpdateMetricContract,
+  ThresholdExceededEvent,
+  ThresholdCreatedEvent,
+  ThresholdApproachingEvent,
+  ThresholdActionEnum,
+  ResetPeriodEnum,
+  RecordUsageContract,
+  RecordBatchUsageContract,
+  PosthogMeteringReporter,
+  PosthogMeteringReader,
+  PeriodTypeEnum,
+  MetricUpdatedEvent,
+  MetricDefinitionModel,
+  MetricDefinitionEntity,
+  MetricDefinedEvent,
+  MeteringFeature,
+  MeteringEvents,
+  ListThresholdsContract,
+  ListMetricsContract,
+  InMemoryUsageStorage,
+  GetUsageSummaryContract,
+  GetUsageContract,
+  GetMetricContract,
+  DeleteThresholdContract,
+  DeleteMetricContract,
+  DefineMetricContract,
+  CreateThresholdContract,
+  AggregationTypeEnum
+};