@lssm/lib.contracts 0.0.0-canary-20251217052941 → 0.0.0-canary-20251217060433

package/dist/server/graphql-pothos.d.ts

@@ -0,0 +1,27 @@
+import { ResourceRegistry } from "../resources.js";
+import { SpecRegistry } from "../registry.js";
+import { SchemaTypes } from "@pothos/core";
+import "@pothos/plugin-relay";
+
+//#region src/server/graphql-pothos.d.ts
+
+/**
+ * Registers all ContractSpecs from a SpecRegistry onto a Pothos SchemaBuilder.
+ *
+ * This adapter:
+ * 1. Discovers output types from specs and registers them as Pothos object types.
+ * 2. Maps `ContractSpec` inputs to Pothos input types.
+ * 3. Mounts `query` specs as `Query` fields and `command` specs as `Mutation` fields.
+ * 4. Wraps the resolver to:
+ *    - Enforce auth policies (basic check).
+ *    - Build a `HandlerCtx`.
+ *    - Execute via `SpecRegistry`.
+ *    - Hydrate resource references if applicable.
+ *
+ * @param builder - The Pothos SchemaBuilder instance.
+ * @param reg - The SpecRegistry containing operations.
+ * @param resources - (Optional) ResourceRegistry for hydrating resource references.
+ */
+declare function registerContractsOnBuilder<T extends SchemaTypes>(builder: PothosSchemaTypes.SchemaBuilder<T>, reg: SpecRegistry, resources?: ResourceRegistry): void;
+//#endregion
+export { registerContractsOnBuilder };

package/dist/server/index.d.ts

@@ -0,0 +1,9 @@
+import { registerContractsOnBuilder } from "./graphql-pothos.js";
+import { createMcpServer } from "./mcp/createMcpServer.js";
+import "./provider-mcp.js";
+import { RestOptions, createFetchHandler } from "./rest-generic.js";
+import { elysiaPlugin } from "./rest-elysia.js";
+import { expressRouter } from "./rest-express.js";
+import { makeNextAppHandler } from "./rest-next-app.js";
+import { makeNextPagesHandler } from "./rest-next-pages.js";
+export { RestOptions, createFetchHandler, createMcpServer, elysiaPlugin, expressRouter, makeNextAppHandler, makeNextPagesHandler, registerContractsOnBuilder };

package/dist/server/mcp/createMcpServer.d.ts

@@ -0,0 +1,15 @@
+import { ResourceRegistry } from "../../resources.js";
+import { SpecRegistry } from "../../registry.js";
+import { PromptRegistry } from "../../promptRegistry.js";
+import { McpCtxFactories } from "./mcpTypes.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/server/mcp/createMcpServer.d.ts
+
+/**
+ * Creates a unified Model Context Protocol (MCP) server exposing operations, resources, prompts,
+ * and (optionally) presentations.\n+ *
+ * ContractSpec exposes:\n+ * - Tools: `command` operations from `SpecRegistry`.\n+ * - Resources: templates from `ResourceRegistry`.\n+ * - Prompts: templates from `PromptRegistry`.\n+ * - Presentations: V1 registry and/or V2 descriptors as read-only resources.\n+ */
+declare function createMcpServer(server: McpServer, ops: SpecRegistry, resources: ResourceRegistry, prompts: PromptRegistry, ctxFactories: McpCtxFactories): McpServer;
+//#endregion
+export { createMcpServer };

package/dist/server/mcp/mcpTypes.d.ts

@@ -0,0 +1,29 @@
+import { PresentationDescriptorV2 } from "../../presentations.v2.js";
+import { PresentationRegistry } from "../../presentations.js";
+import { HandlerCtx } from "../../types.js";
+import { Logger } from "@lssm/lib.logger";
+
+//#region src/server/mcp/mcpTypes.d.ts
+interface McpCtxFactories {
+  logger: Logger;
+  /** Factory for tool execution context (e.g., system actor) */
+  toolCtx: () => HandlerCtx;
+  /** Factory for prompt rendering context */
+  promptCtx: () => {
+    userId?: string | null;
+    orgId?: string | null;
+    locale?: string;
+  };
+  /** Factory for resource resolution context */
+  resourceCtx: () => {
+    userId?: string | null;
+    orgId?: string | null;
+    locale?: string;
+  };
+  /** Optional registry for V1 presentations */
+  presentations?: PresentationRegistry;
+  /** Optional list of V2 presentation descriptors */
+  presentationsV2?: PresentationDescriptorV2[];
+}
+//#endregion
+export { McpCtxFactories };

package/dist/server/mcp/registerPresentations.d.ts

@@ -0,0 +1,7 @@
+import { McpCtxFactories } from "./mcpTypes.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/server/mcp/registerPresentations.d.ts
+declare function registerMcpPresentations(server: McpServer, ctx: Pick<McpCtxFactories, 'logger' | 'presentations' | 'presentationsV2'>): void;
+//#endregion
+export { registerMcpPresentations };

package/dist/server/mcp/registerPrompts.d.ts

@@ -0,0 +1,8 @@
+import { PromptRegistry } from "../../promptRegistry.js";
+import { McpCtxFactories } from "./mcpTypes.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/server/mcp/registerPrompts.d.ts
+declare function registerMcpPrompts(server: McpServer, prompts: PromptRegistry, ctx: Pick<McpCtxFactories, 'promptCtx'>): void;
+//#endregion
+export { registerMcpPrompts };

package/dist/server/mcp/registerResources.d.ts

@@ -0,0 +1,8 @@
+import { ResourceRegistry } from "../../resources.js";
+import { McpCtxFactories } from "./mcpTypes.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/server/mcp/registerResources.d.ts
+declare function registerMcpResources(server: McpServer, resources: ResourceRegistry, ctx: Pick<McpCtxFactories, 'logger' | 'resourceCtx'>): void;
+//#endregion
+export { registerMcpResources };

package/dist/server/mcp/registerTools.d.ts

@@ -0,0 +1,8 @@
+import { SpecRegistry } from "../../registry.js";
+import { McpCtxFactories } from "./mcpTypes.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/server/mcp/registerTools.d.ts
+declare function registerMcpTools(server: McpServer, ops: SpecRegistry, ctx: Pick<McpCtxFactories, 'toolCtx'>): void;
+//#endregion
+export { registerMcpTools };

package/dist/server/provider-mcp.d.ts

@@ -0,0 +1,2 @@
+import { createMcpServer } from "./mcp/createMcpServer.js";
+export { createMcpServer };

package/dist/server/rest-elysia.d.ts

@@ -0,0 +1,40 @@
+import { HandlerCtx } from "../types.js";
+import { SpecRegistry } from "../registry.js";
+import { RestOptions } from "./rest-generic.js";
+import { Elysia } from "elysia";
+
+//#region src/server/rest-elysia.d.ts
+/** Mount routes on an Elysia instance */
+declare function elysiaPlugin(app: Elysia, reg: SpecRegistry, ctxFactory: (c: {
+  request: Request;
+  store: any;
+}) => HandlerCtx, options?: RestOptions): Elysia<"", {
+  decorator: {};
+  store: {};
+  derive: {};
+  resolve: {};
+}, {
+  typebox: {};
+  error: {};
+}, {
+  schema: {};
+  standaloneSchema: {};
+  macro: {};
+  macroFn: {};
+  parser: {};
+  response: {};
+}, {}, {
+  derive: {};
+  resolve: {};
+  schema: {};
+  standaloneSchema: {};
+  response: {};
+}, {
+  derive: {};
+  resolve: {};
+  schema: {};
+  standaloneSchema: {};
+  response: {};
+}>;
+//#endregion
+export { elysiaPlugin };

package/dist/server/rest-express.d.ts

@@ -0,0 +1,16 @@
+import { HandlerCtx } from "../types.js";
+import { SpecRegistry } from "../registry.js";
+import { RestOptions } from "./rest-generic.js";
+import { Request, Router } from "express";
+
+//#region src/server/rest-express.d.ts
+
+/**
+ * Build an Express Router that proxies to the Fetch-style handler.
+ * You can mount it at any base path; pass the same basePath in options.
+ */
+declare function expressRouter(express: {
+  Router: () => Router;
+}, reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): Router;
+//#endregion
+export { expressRouter };

package/dist/server/rest-generic.d.ts

@@ -0,0 +1,32 @@
+import { HandlerCtx } from "../types.js";
+import { SpecRegistry } from "../registry.js";
+
+//#region src/server/rest-generic.d.ts
+interface RestOptions {
+  /** Prefix all routes, e.g. "/api" */
+  basePath?: string;
+  /** If true, handle OPTIONS and set CORS headers */
+  cors?: boolean | {
+    origin?: string | '*';
+    methods?: string[];
+    headers?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+  };
+  /** JSON spacing in responses (dev only ideally) */
+  prettyJson?: number | false;
+  /** Map thrown errors to {status, body} */
+  onError?: (err: unknown) => {
+    status: number;
+    body: any;
+  };
+}
+/**
+ * Build a single Fetch-style handler: (req) => Response
+ * - Discovers routes from SpecRegistry
+ * - Validates with zod via registry.execute()
+ * - Handles CORS (optional)
+ */
+declare function createFetchHandler(reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
+//#endregion
+export { RestOptions, createFetchHandler };

package/dist/server/rest-next-app.d.ts

@@ -0,0 +1,35 @@
+import { HandlerCtx } from "../types.js";
+import { SpecRegistry } from "../registry.js";
+import { RestOptions } from "./rest-generic.js";
+
+//#region src/server/rest-next-app.d.ts
+
+/**
+ * Creates a Next.js App Router route handler for ContractSpec operations.
+ *
+ * This function returns a handler suitable for `export const { GET, POST }` in a `route.ts` file.
+ * It handles:
+ * - Path parsing to determine the operation name and version.
+ * - Body parsing (JSON).
+ * - Context creation via `ctxFactory`.
+ * - Execution via `SpecRegistry`.
+ * - Response formatting (JSON success/error).
+ *
+ * @param reg - The SpecRegistry containing the operations.
+ * @param ctxFactory - A factory function to build the `HandlerCtx` (e.g., auth, tenant) from the request.
+ * @param options - Optional configuration for the REST handler.
+ * @returns A function `(req: Request) => Promise<Response>`.
+ *
+ * @example
+ * ```ts
+ * // app/api/[...route]/route.ts
+ * import { makeNextAppHandler } from '@lssm/lib.contracts/server/rest-next-app';
+ * import { registry } from '@/lib/registry';
+ *
+ * const handler = makeNextAppHandler(registry, (req) => ({ actor: 'anonymous' }));
+ * export { handler as GET, handler as POST };
+ * ```
+ */
+declare function makeNextAppHandler(reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
+//#endregion
+export { makeNextAppHandler };

package/dist/server/rest-next-mcp.d.ts

@@ -0,0 +1,11 @@
+import { HandlerCtx } from "../types.js";
+import { SpecRegistry } from "../registry.js";
+
+//#region src/server/rest-next-mcp.d.ts
+declare function makeNextMcpServerFromRegistry(reg: SpecRegistry, ctxFactory: () => HandlerCtx): {
+  GET: (request: Request) => Promise<Response>;
+  POST: (request: Request) => Promise<Response>;
+  DELETE: (request: Request) => Promise<Response>;
+};
+//#endregion
+export { makeNextMcpServerFromRegistry };

package/dist/server/rest-next-pages.d.ts

@@ -0,0 +1,9 @@
+import { HandlerCtx } from "../types.js";
+import { SpecRegistry } from "../registry.js";
+import { RestOptions } from "./rest-generic.js";
+import { NextApiRequest, NextApiResponse } from "next";
+
+//#region src/server/rest-next-pages.d.ts
+declare function makeNextPagesHandler(reg: SpecRegistry, ctxFactory: (req: NextApiRequest) => HandlerCtx, options?: RestOptions): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
+//#endregion
+export { makeNextPagesHandler };

package/dist/spec.d.ts

@@ -0,0 +1,195 @@
+import { Owner, Stability, Tag } from "./ownership.js";
+import { DocId } from "./docs/registry.js";
+import { EventSpec } from "./events.js";
+import { ResourceRefDescriptor } from "./resources.js";
+import { PolicyRef } from "./policy/spec.js";
+import { TestSpecRef } from "./tests/spec.js";
+import { AnySchemaModel } from "@lssm/lib.schema";
+
+//#region src/spec.d.ts
+
+/**
+ * Distinguishes between state-changing operations (command) and read-only operations (query).
+ */
+type OpKind = 'command' | 'query';
+/**
+ * Type of implementation artifact.
+ */
+type ImplementationType = 'handler' | 'component' | 'form' | 'test' | 'service' | 'hook' | 'other';
+/**
+ * Reference to an implementation file for a spec.
+ * Used for explicit implementation mapping.
+ */
+interface ImplementationRef {
+  /** Path to implementation file (relative to workspace root) */
+  path: string;
+  /** Type of implementation artifact */
+  type: ImplementationType;
+  /** Optional human-readable description */
+  description?: string;
+}
+interface EmitDeclRef {
+  ref: EventSpec<AnySchemaModel>;
+  when: string;
+}
+interface EmitDeclInline {
+  name: string;
+  version: number;
+  when: string;
+  payload: AnySchemaModel;
+}
+/**
+ * Declaration of an event that an operation may emit.
+ * Can be a reference to an `EventSpec` or an inline definition.
+ */
+type EmitDecl = EmitDeclRef | EmitDeclInline;
+declare const isEmitDeclRef: (e: EmitDecl) => e is EmitDeclRef;
+interface TelemetryTrigger {
+  event: {
+    name: string;
+    version?: number;
+  };
+  properties?: (args: {
+    input: unknown;
+    output?: unknown;
+    error?: unknown;
+  }) => Record<string, unknown>;
+}
+/**
+ * The core specification interface for any operation (Command or Query).
+ *
+ * @template Input - The Zod-backed schema model for the input payload.
+ * @template Output - The Zod-backed schema model for the output payload, or a resource reference.
+ * @template Events - Tuple of events that this operation may emit.
+ */
+interface ContractSpec<Input extends AnySchemaModel, Output extends AnySchemaModel | ResourceRefDescriptor<boolean>, Events extends readonly EmitDecl[] | undefined = readonly EmitDecl[] | undefined> {
+  meta: {
+    /** Fully-qualified op name (e.g., "sigil.beginSignup") */
+    name: string;
+    /** Breaking changes => bump version */
+    version: number;
+    /** "command" changes state; "query" is read-only/idempotent */
+    kind: OpKind;
+    /** Lifecycle marker for comms & tooling */
+    stability: Stability;
+    /** Owners for CODEOWNERS / on-call / approvals */
+    owners: Owner[];
+    /** Search tags, grouping, docs navigation */
+    tags: Tag[];
+    /** Short human-friendly summary */
+    description: string;
+    /** Business goal: why this exists */
+    goal: string;
+    /** Background, constraints, scope edges (feeds docs & LLM context) */
+    context: string;
+    /** Optional doc block id for this operation. */
+    docId?: DocId;
+  };
+  io: {
+    /** Zod schema for input payload */
+    input: Input | null;
+    /** Zod schema for output payload */
+    output: Output;
+    /** Named, typed errors this op may throw (optional) */
+    errors?: Record<string, {
+      description: string;
+      http?: number;
+      gqlCode?: string;
+      when: string;
+    }>;
+  };
+  policy: {
+    /** Minimal auth category allowed to call this op */
+    auth: 'anonymous' | 'user' | 'admin';
+    /** Idempotency hint. Queries default true; commands default false. */
+    idempotent?: boolean;
+    /** Soft rate limit suggestion; adapter enforces via limiter */
+    rateLimit?: {
+      rpm: number;
+      key: 'user' | 'org' | 'global';
+    };
+    /** Feature flags that must be ON for this op to run */
+    flags?: string[];
+    /** Whether a human must approve before action (e.g., risky commands) */
+    escalate?: 'human_review' | null;
+    /** JSONPath-like pointers to redact from logs/prompts */
+    pii?: string[];
+    /** Referenced policy specs governing access */
+    policies?: PolicyRef[];
+    /** Field-level overrides referencing policy specs */
+    fieldPolicies?: {
+      field: string;
+      actions: ('read' | 'write')[];
+      policy?: PolicyRef;
+    }[];
+  };
+  sideEffects?: {
+    /** Declared events this op may emit; runtime will guard against others */
+    emits?: Events;
+    /** Analytics intents (names); the service decides the sink */
+    analytics?: string[];
+    /** Audit intents (labels); the service decides storage */
+    audit?: string[];
+  };
+  telemetry?: {
+    success?: TelemetryTrigger;
+    failure?: TelemetryTrigger;
+  };
+  tests?: TestSpecRef[];
+  transport?: {
+    rest?: {
+      /** Override HTTP method (default: POST for commands, GET for queries) */
+      method?: 'GET' | 'POST';
+      /** Override path (default derived from meta.name/version) */
+      path?: string;
+    };
+    gql?: {
+      /** Override field name (default: dots→underscores + _vN) */
+      field?: string;
+      returns?: string;
+    };
+    mcp?: {
+      /** Override tool identifier (default: "<name>.v<version>") */
+      toolName?: string;
+    };
+  };
+  acceptance?: {
+    /** Gherkin-lite scenarios for docs & auto tests */
+    scenarios?: {
+      name: string;
+      given: string[];
+      when: string[];
+      then: string[];
+    }[];
+    /** Request/response examples (used for docs & snapshot tests) */
+    examples?: {
+      name: string;
+      input: unknown;
+      output: unknown;
+    }[];
+  };
+  /**
+   * Explicit implementation file mappings.
+   * Used for tracking and verifying that this spec is correctly implemented.
+   */
+  implementations?: ImplementationRef[];
+}
+type AnyContractSpec = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+/**
+ * Helper to define a Command (write operation).
+ * Sets `kind: 'command'` and defaults `idempotent: false`.
+ */
+declare const defineCommand: <I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>, E extends readonly EmitDecl[] | undefined = undefined>(spec: Omit<ContractSpec<I, O, E>, "meta" | "policy"> & {
+  meta: Omit<ContractSpec<I, O, E>["meta"], "kind">;
+  policy: Omit<ContractSpec<I, O, E>["policy"], "idempotent">;
+}) => ContractSpec<I, O, E>;
+/**
+ * Helper to define a Query (read-only operation).
+ * Sets `kind: 'query'` and forces `idempotent: true`.
+ */
+declare const defineQuery: <I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>, E extends readonly EmitDecl[] | undefined = undefined>(spec: Omit<ContractSpec<I, O, E>, "meta" | "policy"> & {
+  meta: Omit<ContractSpec<I, O, E>["meta"], "kind">;
+  policy: Omit<ContractSpec<I, O, E>["policy"], "idempotent">;
+}) => ContractSpec<I, O, E>;
+//#endregion
+export { AnyContractSpec, ContractSpec, EmitDecl, EmitDeclInline, EmitDeclRef, ImplementationRef, ImplementationType, OpKind, TelemetryTrigger, defineCommand, defineQuery, isEmitDeclRef };

package/dist/telemetry/anomaly.d.ts

@@ -0,0 +1,27 @@
+import { TelemetryAnomalyDetectionConfig } from "./spec.js";
+import { TelemetryDispatch } from "./tracker.js";
+
+//#region src/telemetry/anomaly.d.ts
+interface TelemetryAnomalyEvent {
+  dispatch: TelemetryDispatch;
+  threshold: TelemetryAnomalyDetectionConfig;
+  metric: string;
+  value: number | undefined;
+  type: 'min' | 'max';
+}
+interface TelemetryAnomalyMonitorOptions {
+  onAnomaly?: (event: TelemetryAnomalyEvent) => void;
+  now?: () => Date;
+}
+declare class TelemetryAnomalyMonitor {
+  private readonly onAnomaly?;
+  private readonly now;
+  private readonly samples;
+  constructor(options?: TelemetryAnomalyMonitorOptions);
+  observe(dispatch: TelemetryDispatch): void;
+  private extractMetric;
+  private emit;
+  reset(): void;
+}
+//#endregion
+export { TelemetryAnomalyEvent, TelemetryAnomalyMonitor, TelemetryAnomalyMonitorOptions };

package/dist/telemetry/docs/telemetry.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@lssm/lib.contracts/docs";
+
+//#region src/telemetry/docs/telemetry.docblock.d.ts
+declare const tech_contracts_telemetry_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_telemetry_DocBlocks };

package/dist/telemetry/index.d.ts

@@ -0,0 +1,4 @@
+import { TelemetryAnomalyAction, TelemetryAnomalyDetectionConfig, TelemetryAnomalyThreshold, TelemetryConfig, TelemetryEventDef, TelemetryMeta, TelemetryPrivacyLevel, TelemetryPropertyDef, TelemetryProviderConfig, TelemetryRegistry, TelemetryRetentionConfig, TelemetrySamplingConfig, TelemetrySpec, makeTelemetryKey } from "./spec.js";
+import { TelemetryAnomalyEvent, TelemetryAnomalyMonitor, TelemetryAnomalyMonitorOptions } from "./anomaly.js";
+import { RuntimeTelemetryProvider, TelemetryDispatch, TelemetryEventContext, TelemetryTracker, TelemetryTrackerOptions } from "./tracker.js";
+export { RuntimeTelemetryProvider, TelemetryAnomalyAction, TelemetryAnomalyDetectionConfig, TelemetryAnomalyEvent, TelemetryAnomalyMonitor, TelemetryAnomalyMonitorOptions, TelemetryAnomalyThreshold, TelemetryConfig, TelemetryDispatch, TelemetryEventContext, TelemetryEventDef, TelemetryMeta, TelemetryPrivacyLevel, TelemetryPropertyDef, TelemetryProviderConfig, TelemetryRegistry, TelemetryRetentionConfig, TelemetrySamplingConfig, TelemetrySpec, TelemetryTracker, TelemetryTrackerOptions, makeTelemetryKey };

package/dist/telemetry/spec.d.ts

@@ -0,0 +1,98 @@
+import { OwnerShipMeta } from "../ownership.js";
+
+//#region src/telemetry/spec.d.ts
+type TelemetryPrivacyLevel = 'public' | 'internal' | 'pii' | 'sensitive';
+interface TelemetryMeta extends OwnerShipMeta {
+  /** Fully-qualified telemetry spec name (e.g., "sigil.core"). */
+  name: string;
+  /** Incremented when telemetry definitions change in a breaking way. */
+  version: number;
+  /** Optional domain or bounded-context hint (e.g., "onboarding"). */
+  domain: string;
+}
+interface TelemetryPropertyDef {
+  type: 'string' | 'number' | 'boolean' | 'timestamp' | 'json';
+  required?: boolean;
+  pii?: boolean;
+  redact?: boolean;
+  description?: string;
+}
+interface TelemetryAnomalyThreshold {
+  metric: string;
+  min?: number;
+  max?: number;
+}
+type TelemetryAnomalyAction = 'alert' | 'log' | 'trigger_regen';
+interface TelemetryAnomalyDetectionConfig {
+  enabled: boolean;
+  thresholds?: TelemetryAnomalyThreshold[];
+  actions?: TelemetryAnomalyAction[];
+  /**
+   * Minimum sample size before evaluating thresholds.
+   * Helps avoid false positives on small sample sizes.
+   */
+  minimumSample?: number;
+}
+interface TelemetrySamplingConfig {
+  rate: number;
+  conditions?: string[];
+}
+interface TelemetryRetentionConfig {
+  days: number;
+  policy?: 'archive' | 'delete';
+}
+interface TelemetryEventDef {
+  /** Name of the event (should match EventSpec.name for cross-reference). */
+  name: string;
+  /** Version of the underlying event. */
+  version: number;
+  /** High-level semantics for docs/analyzers. */
+  semantics: {
+    who?: string;
+    what: string;
+    why?: string;
+  };
+  /** Detailed property metadata keyed by property name. */
+  properties: Record<string, TelemetryPropertyDef>;
+  /** Privacy level for the entire event. */
+  privacy: TelemetryPrivacyLevel;
+  /** Retention policy overrides. */
+  retention?: TelemetryRetentionConfig;
+  /** Sampling rules, defaulting to spec.config defaults. */
+  sampling?: TelemetrySamplingConfig;
+  /** Anomaly detection overrides. */
+  anomalyDetection?: TelemetryAnomalyDetectionConfig;
+  /** Optional tags for analytics/AI hints. */
+  tags?: string[];
+}
+interface TelemetryProviderConfig {
+  type: 'posthog' | 'segment' | 'opentelemetry' | 'internal';
+  config: Record<string, unknown>;
+}
+interface TelemetryConfig {
+  defaultRetentionDays?: number;
+  defaultSamplingRate?: number;
+  providers?: TelemetryProviderConfig[];
+  anomalyDetection?: {
+    enabled: boolean;
+    checkIntervalMs?: number;
+  };
+}
+interface TelemetrySpec {
+  meta: TelemetryMeta;
+  events: TelemetryEventDef[];
+  config?: TelemetryConfig;
+}
+declare class TelemetryRegistry {
+  private readonly items;
+  private readonly eventsByKey;
+  private readonly specByEventKey;
+  register(spec: TelemetrySpec): this;
+  list(): TelemetrySpec[];
+  get(name: string, version?: number): TelemetrySpec | undefined;
+  findEventDef(name: string, version?: number): TelemetryEventDef | undefined;
+  getSpecForEvent(name: string, version?: number): TelemetrySpec | undefined;
+}
+declare function makeTelemetryKey(meta: TelemetryMeta): string;
+//#endregion
+export { TelemetryAnomalyAction, TelemetryAnomalyDetectionConfig, TelemetryAnomalyThreshold, TelemetryConfig, TelemetryEventDef, TelemetryMeta, TelemetryPrivacyLevel, TelemetryPropertyDef, TelemetryProviderConfig, TelemetryRegistry, TelemetryRetentionConfig, TelemetrySamplingConfig, TelemetrySpec, makeTelemetryKey };

package/dist/telemetry/tracker.d.ts

@@ -0,0 +1,51 @@
+import { TelemetryEventDef, TelemetryRegistry, TelemetrySpec } from "./spec.js";
+import { TelemetryAnomalyMonitor } from "./anomaly.js";
+
+//#region src/telemetry/tracker.d.ts
+interface TelemetryEventContext {
+  tenantId?: string;
+  organizationId?: string | null;
+  userId?: string | null;
+  sessionId?: string | null;
+  actor?: 'anonymous' | 'user' | 'admin';
+  channel?: 'web' | 'mobile' | 'job' | 'agent';
+  metadata?: Record<string, unknown>;
+}
+interface TelemetryDispatch {
+  id: string;
+  name: string;
+  version: number;
+  occurredAt: string;
+  properties: Record<string, unknown>;
+  privacy: TelemetryEventDef['privacy'];
+  context: TelemetryEventContext;
+  tags?: string[];
+  spec: TelemetrySpec;
+  definition: TelemetryEventDef;
+}
+interface RuntimeTelemetryProvider {
+  id: string;
+  send(event: TelemetryDispatch): Promise<void>;
+}
+interface TelemetryTrackerOptions {
+  registry: TelemetryRegistry;
+  providers?: RuntimeTelemetryProvider[];
+  anomalyMonitor?: TelemetryAnomalyMonitor;
+  random?: () => number;
+  clock?: () => Date;
+}
+declare class TelemetryTracker {
+  private readonly providers;
+  private readonly registry;
+  private readonly anomalyMonitor?;
+  private readonly random;
+  private readonly clock;
+  constructor(options: TelemetryTrackerOptions);
+  registerProvider(provider: RuntimeTelemetryProvider): void;
+  unregisterProvider(providerId: string): void;
+  track(name: string, version: number, properties: Record<string, unknown>, context?: TelemetryEventContext): Promise<boolean>;
+  private shouldSample;
+  private redactProperties;
+}
+//#endregion
+export { RuntimeTelemetryProvider, TelemetryDispatch, TelemetryEventContext, TelemetryTracker, TelemetryTrackerOptions };