@lssm/lib.contracts 0.0.0-canary-20251220041653 → 0.0.0-canary-20251221132705

package/dist/registry.d.ts

@@ -1,31 +1,31 @@
+import { GroupKeyFn, RegistryFilter } from "./registry-utils.js";
 import { defaultDocRegistry, docId, registerDocBlocks } from "./docs/registry.js";
 import { ResourceRefDescriptor } from "./resources.js";
-import { ContractSpec } from "./spec.js";
+import { AnyOperationSpec, OperationSpec } from "./operation.js";
 import { HandlerCtx } from "./types.js";
-import { HandlerFor } from "./install.js";
+import { HandlerForOperationSpec } from "./install.js";
 import { AnySchemaModel } from "@lssm/lib.schema";
 
 //#region src/registry.d.ts
 
 type OperationKey = `${string}.v${number}`;
 declare function opKey(name: string, version: number): OperationKey;
-type AnySpec = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
-type AnyHandler = (args: unknown, ctx: HandlerCtx) => Promise<unknown>;
+type AnyOperationHandler = (args: unknown, ctx: HandlerCtx) => Promise<unknown>;
 /**
  * In-memory registry for ContractSpecs and their bound handlers.
  * Provides validation, policy enforcement, and guarded event emission at execute time.
  */
-declare class SpecRegistry {
+declare class OperationSpecRegistry {
   private specs;
   private handlers;
   /**
-   * Registers a ContractSpec definition.
+   * Registers a OperationSpec definition.
    *
    * @param spec - The contract specification to register.
    * @returns The registry instance for chaining.
    * @throws If a spec with the same name and version is already registered.
    */
-  register<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: ContractSpec<I, O>): this;
+  register<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: OperationSpec<I, O>): this;
   /**
    * Binds a runtime handler implementation to a previously registered spec.
    *
@@ -34,7 +34,7 @@ declare class SpecRegistry {
    * @returns The registry instance for chaining.
    * @throws If the spec is not found or a handler is already bound.
    */
-  bind<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: ContractSpec<I, O>, handler: HandlerFor<ContractSpec<I, O>>): this;
+  bind<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: OperationSpec<I, O>, handler: HandlerForOperationSpec<OperationSpec<I, O>>): this;
   /**
    * Retrieves a registered spec by name and version.
    * If version is omitted, returns the highest version found.
@@ -42,18 +42,50 @@ declare class SpecRegistry {
    * @param name - Operation name.
    * @param version - (Optional) Specific version.
    */
-  getSpec(name: string, version?: number): AnySpec | undefined;
+  getSpec(name: string, version?: number): AnyOperationSpec | undefined;
   /**
    * Retrieves the bound handler for a spec.
    */
-  getHandler(name: string, version?: number): AnyHandler | undefined;
+  getHandler(name: string, version?: number): AnyOperationHandler | undefined;
   /** Iterate all registered specs. */
-  listSpecs(): AnySpec[];
+  listSpecs(): AnyOperationSpec[];
   /** Iterate all bound operations (spec+handler). */
   listBound(): {
-    spec: AnySpec;
-    handler: AnyHandler;
+    spec: AnyOperationSpec;
+    handler: AnyOperationHandler;
   }[];
+  /**
+   * Filter specs by criteria.
+   */
+  filter(criteria: RegistryFilter): AnyOperationSpec[];
+  /**
+   * List specs with specific tag.
+   */
+  listByTag(tag: string): AnyOperationSpec[];
+  /**
+   * List specs by owner.
+   */
+  listByOwner(owner: string): AnyOperationSpec[];
+  /**
+   * Group specs by key function.
+   */
+  groupBy(keyFn: GroupKeyFn<AnyOperationSpec>): Map<string, AnyOperationSpec[]>;
+  /**
+   * Group by domain (first segment of name).
+   */
+  groupByDomain(): Map<string, AnyOperationSpec[]>;
+  /**
+   * Group by tag.
+   */
+  groupByTag(): Map<string, AnyOperationSpec[]>;
+  /**
+   * Get unique tags from all specs.
+   */
+  getUniqueTags(): string[];
+  /**
+   * Get unique owners from all specs.
+   */
+  getUniqueOwners(): string[];
   /**
    * Execute an operation by name/version with full runtime protections:
    * 1. Validates input against Zod schema.
@@ -70,4 +102,4 @@ declare class SpecRegistry {
   execute(name: string, version: number | undefined, rawInput: unknown, ctx: HandlerCtx): Promise<unknown>;
 }
 //#endregion
-export { OperationKey, SpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };
+export { OperationKey, OperationSpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };

package/dist/registry.js

@@ -1,10 +1,12 @@
+import { __toCommonJS } from "./_virtual/rolldown_runtime.js";
+import { init_registry_utils, registry_utils_exports } from "./registry-utils.js";
 import { eventKey } from "./events.js";
-import { isEmitDeclRef } from "./spec.js";
+import { isEmitDeclRef } from "./operation.js";
 import { defaultDocRegistry, docId, registerDocBlocks } from "./docs/registry.js";
 
 //#region src/registry.ts
 /**
-* SpecRegistry:
+* OperationSpecRegistry:
 * - Registers ContractSpecs (unique by name+version)
 * - Binds runtime handlers to specs
 * - Provides lookup, iteration, and a safe execute() with validation/policy/enforcement
@@ -18,11 +20,11 @@ function opKey(name, version) {
 * In-memory registry for ContractSpecs and their bound handlers.
 * Provides validation, policy enforcement, and guarded event emission at execute time.
 */
-var SpecRegistry = class {
+var OperationSpecRegistry = class {
 	specs = /* @__PURE__ */ new Map();
 	handlers = /* @__PURE__ */ new Map();
 	/**
-	* Registers a ContractSpec definition.
+	* Registers a OperationSpec definition.
 	*
 	* @param spec - The contract specification to register.
 	* @returns The registry instance for chaining.
@@ -94,6 +96,60 @@ var SpecRegistry = class {
 		return out;
 	}
 	/**
+	* Filter specs by criteria.
+	*/
+	filter(criteria) {
+		const { filterBy } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return filterBy(this.listSpecs(), criteria);
+	}
+	/**
+	* List specs with specific tag.
+	*/
+	listByTag(tag) {
+		return this.listSpecs().filter((s) => s.meta.tags?.includes(tag));
+	}
+	/**
+	* List specs by owner.
+	*/
+	listByOwner(owner) {
+		return this.listSpecs().filter((s) => s.meta.owners?.includes(owner));
+	}
+	/**
+	* Group specs by key function.
+	*/
+	groupBy(keyFn) {
+		const { groupBy } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return groupBy(this.listSpecs(), keyFn);
+	}
+	/**
+	* Group by domain (first segment of name).
+	*/
+	groupByDomain() {
+		const { GroupingStrategies } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return this.groupBy(GroupingStrategies.byDomain);
+	}
+	/**
+	* Group by tag.
+	*/
+	groupByTag() {
+		const { GroupingStrategies } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return this.groupBy(GroupingStrategies.byTag);
+	}
+	/**
+	* Get unique tags from all specs.
+	*/
+	getUniqueTags() {
+		const { getUniqueTags } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return getUniqueTags(this.listSpecs());
+	}
+	/**
+	* Get unique owners from all specs.
+	*/
+	getUniqueOwners() {
+		const { getUniqueOwners } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return getUniqueOwners(this.listSpecs());
+	}
+	/**
 	* Execute an operation by name/version with full runtime protections:
 	* 1. Validates input against Zod schema.
 	* 2. Enforces policy (Auth, RBAC, Rate Limits) via PDP.
@@ -206,4 +262,4 @@ var SpecRegistry = class {
 };
 
 //#endregion
-export { SpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };
+export { OperationSpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };

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

@@ -1,5 +1,5 @@
 import { ResourceRegistry } from "../resources.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import "@pothos/plugin-prisma";
 import "@pothos/plugin-complexity";
 import "@pothos/plugin-relay";
@@ -10,22 +10,22 @@ import { SchemaTypes } from "@pothos/core";
 //#region src/server/graphql-pothos.d.ts
 
 /**
- * Registers all ContractSpecs from a SpecRegistry onto a Pothos SchemaBuilder.
+ * Registers all ContractSpecs from a OperationSpecRegistry 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.
+ * 2. Maps `ContractSpec` (OperationSpec) 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`.
+ *    - Execute via `OperationSpecRegistry`.
  *    - Hydrate resource references if applicable.
  *
  * @param builder - The Pothos SchemaBuilder instance.
- * @param reg - The SpecRegistry containing operations.
+ * @param reg - The OperationSpecRegistry 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;
+declare function registerContractsOnBuilder<T extends SchemaTypes>(builder: PothosSchemaTypes.SchemaBuilder<T>, reg: OperationSpecRegistry, resources?: ResourceRegistry): void;
 //#endregion
 export { registerContractsOnBuilder };

package/dist/server/graphql-pothos.js

@@ -9,20 +9,20 @@ import "@pothos/plugin-tracing";
 
 //#region src/server/graphql-pothos.ts
 /**
-* Registers all ContractSpecs from a SpecRegistry onto a Pothos SchemaBuilder.
+* Registers all ContractSpecs from a OperationSpecRegistry 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.
+* 2. Maps `ContractSpec` (OperationSpec) 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`.
+*    - Execute via `OperationSpecRegistry`.
 *    - Hydrate resource references if applicable.
 *
 * @param builder - The Pothos SchemaBuilder instance.
-* @param reg - The SpecRegistry containing operations.
+* @param reg - The OperationSpecRegistry containing operations.
 * @param resources - (Optional) ResourceRegistry for hydrating resource references.
 */
 function registerContractsOnBuilder(builder, reg, resources) {

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

@@ -1,5 +1,5 @@
 import { ResourceRegistry } from "../../resources.js";
-import { SpecRegistry } from "../../registry.js";
+import { OperationSpecRegistry } from "../../registry.js";
 import { PromptRegistry } from "../../promptRegistry.js";
 import { McpCtxFactories } from "./mcpTypes.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -9,7 +9,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 /**
  * 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;
+ * ContractSpec exposes:\n+ * - Tools: `command` operations from `OperationSpecRegistry`.\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: OperationSpecRegistry, resources: ResourceRegistry, prompts: PromptRegistry, ctxFactories: McpCtxFactories): McpServer;
 //#endregion
 export { createMcpServer };

package/dist/server/mcp/createMcpServer.js

@@ -7,7 +7,7 @@ import { registerMcpPresentations } from "./registerPresentations.js";
 /**
 * 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+ */
+* ContractSpec exposes:\n+ * - Tools: `command` operations from `OperationSpecRegistry`.\n+ * - Resources: templates from `ResourceRegistry`.\n+ * - Prompts: templates from `PromptRegistry`.\n+ * - Presentations: V1 registry and/or V2 descriptors as read-only resources.\n+ */
 function createMcpServer(server, ops, resources, prompts, ctxFactories) {
 	ctxFactories.logger.info("Creating MCP server");
 	registerMcpTools(server, ops, { toolCtx: ctxFactories.toolCtx });

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

@@ -1,8 +1,8 @@
-import { SpecRegistry } from "../../registry.js";
+import { OperationSpecRegistry } 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;
+declare function registerMcpTools(server: McpServer, ops: OperationSpecRegistry, ctx: Pick<McpCtxFactories, 'toolCtx'>): void;
 //#endregion
 export { registerMcpTools };

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

@@ -1,11 +1,11 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } 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: {
+declare function elysiaPlugin(app: Elysia, reg: OperationSpecRegistry, ctxFactory: (c: {
   request: Request;
   store: unknown;
 }) => HandlerCtx, options?: RestOptions): Elysia<"", {

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

@@ -1,5 +1,5 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import { RestOptions } from "./rest-generic.js";
 import { Request, Router } from "express";
 
@@ -11,6 +11,6 @@ import { Request, Router } from "express";
  */
 declare function expressRouter(express: {
   Router: () => Router;
-}, reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): Router;
+}, reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): Router;
 //#endregion
 export { expressRouter };

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

@@ -1,5 +1,5 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 
 //#region src/server/rest-generic.d.ts
 interface RestOptions {
@@ -23,10 +23,10 @@ interface RestOptions {
 }
 /**
  * Build a single Fetch-style handler: (req) => Response
- * - Discovers routes from SpecRegistry
+ * - Discovers routes from OperationSpecRegistry
  * - Validates with zod via registry.execute()
  * - Handles CORS (optional)
  */
-declare function createFetchHandler(reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
+declare function createFetchHandler(reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
 //#endregion
 export { RestOptions, createFetchHandler };

package/dist/server/rest-generic.js

@@ -22,7 +22,7 @@ function joinPath(a, b) {
 }
 /**
 * Build a single Fetch-style handler: (req) => Response
-* - Discovers routes from SpecRegistry
+* - Discovers routes from OperationSpecRegistry
 * - Validates with zod via registry.execute()
 * - Handles CORS (optional)
 */

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

@@ -1,5 +1,5 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import { RestOptions } from "./rest-generic.js";
 
 //#region src/server/rest-next-app.d.ts
@@ -12,10 +12,10 @@ import { RestOptions } from "./rest-generic.js";
  * - Path parsing to determine the operation name and version.
  * - Body parsing (JSON).
  * - Context creation via `ctxFactory`.
- * - Execution via `SpecRegistry`.
+ * - Execution via `OperationSpecRegistry`.
  * - Response formatting (JSON success/error).
  *
- * @param reg - The SpecRegistry containing the operations.
+ * @param reg - The OperationSpecRegistry 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>`.
@@ -30,6 +30,6 @@ import { RestOptions } from "./rest-generic.js";
  * export { handler as GET, handler as POST };
  * ```
  */
-declare function makeNextAppHandler(reg: SpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
+declare function makeNextAppHandler(reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;
 //#endregion
 export { makeNextAppHandler };

package/dist/server/rest-next-app.js

@@ -9,10 +9,10 @@ import { createFetchHandler } from "./rest-generic.js";
 * - Path parsing to determine the operation name and version.
 * - Body parsing (JSON).
 * - Context creation via `ctxFactory`.
-* - Execution via `SpecRegistry`.
+* - Execution via `OperationSpecRegistry`.
 * - Response formatting (JSON success/error).
 *
-* @param reg - The SpecRegistry containing the operations.
+* @param reg - The OperationSpecRegistry 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>`.

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

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

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

@@ -1,9 +1,9 @@
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } 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>;
+declare function makeNextPagesHandler(reg: OperationSpecRegistry, ctxFactory: (req: NextApiRequest) => HandlerCtx, options?: RestOptions): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;
 //#endregion
 export { makeNextPagesHandler };

package/dist/telemetry/docs/telemetry.docblock.js

@@ -14,7 +14,7 @@ const tech_contracts_telemetry_DocBlocks = [{
 		"contracts",
 		"telemetry"
 	],
-	body: "## TelemetrySpec\n\nTelemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.\n\n- **File location**: `packages/libs/contracts/src/telemetry/spec.ts`\n- **Runtime tracker**: `packages/libs/contracts/src/telemetry/tracker.ts`\n- **Anomaly monitor**: `packages/libs/contracts/src/telemetry/anomaly.ts`\n\n### Core concepts\n\n```ts\nexport interface TelemetrySpec {\n  meta: TelemetryMeta;\n  events: TelemetryEventDef[];\n  config?: TelemetryConfig;\n}\n```\n\n- `meta`: ownership + identifiers (`name`, `version`, `domain`)\n- `events`: per-event semantics, property definitions, privacy level, retention, sampling, anomaly rules\n- `config`: defaults and provider configuration\n- `TelemetryRegistry`: registers specs, resolves latest version, finds event definitions by name/version\n\n### An example\n\n```ts\nexport const SigilTelemetry: TelemetrySpec = {\n  meta: {\n    name: 'sigil.telemetry',\n    version: 1,\n    title: 'Sigil telemetry',\n    description: 'Core Sigil product telemetry',\n    domain: 'sigil',\n    owners: ['@team.analytics'],\n    tags: ['telemetry'],\n    stability: StabilityEnum.Experimental,\n  },\n  config: {\n    defaultRetentionDays: 30,\n    defaultSamplingRate: 1,\n    providers: [\n      { type: 'posthog', config: { projectApiKey: process.env.POSTHOG_KEY } },\n    ],\n  },\n  events: [\n    {\n      name: 'sigil.telemetry.workflow_step',\n      version: 1,\n      semantics: {\n        what: 'Workflow step executed',\n        who: 'Actor executing the workflow',\n      },\n      privacy: 'internal',\n      properties: {\n        workflow: { type: 'string', required: true },\n        step: { type: 'string', required: true },\n        durationMs: { type: 'number' },\n        userId: { type: 'string', pii: true, redact: true },\n      },\n      anomalyDetection: {\n        enabled: true,\n        minimumSample: 10,\n        thresholds: [\n          { metric: 'durationMs', max: 1500 },\n        ],\n        actions: ['alert', 'trigger_regen'],\n      },\n    },\n  ],\n};\n```\n\n### Tracking events at runtime\n\n`TelemetryTracker` performs sampling, PII redaction, provider dispatch, and anomaly detection.\n\n```ts\nconst tracker = new TelemetryTracker({\n  registry: telemetryRegistry,\n  providers: [\n    {\n      id: 'posthog',\n      async send(dispatch) {\n        posthog.capture({\n          event: dispatch.name,\n          properties: dispatch.properties,\n          distinctId: dispatch.context.userId ?? dispatch.context.sessionId,\n        });\n      },\n    },\n  ],\n  anomalyMonitor: new TelemetryAnomalyMonitor({\n    onAnomaly(event) {\n      console.warn('Telemetry anomaly detected', event);\n    },\n  }),\n});\n\nawait tracker.track('sigil.telemetry.workflow_step', 1, {\n  workflow: 'onboarding',\n  step: 'verify_email',\n  durationMs: 2100,\n  userId: 'user-123',\n});\n```\n\n- Sampling obeys the event-specific rate (fallback to spec defaults)\n- Properties flagged with `pii` or `redact` are masked before dispatch\n- Anomaly monitor evaluates thresholds and triggers actions (e.g., log, alert, regeneration)\n\n### Spec integration\n\n- `ContractSpec.telemetry` allows operations to emit success/failure events automatically\n- `SpecRegistry.execute()` uses the tracker when `ctx.telemetry` is provided\n- `WorkflowRunner` (Phase 4 follow-up) will emit telemetry during step transitions\n- `TelemetrySpec` events should reuse `EventSpec` names/versions to keep analytics/contract parity\n\n### CLI workflow\n\n```\ncontracts-cli create telemetry\n```\n\n- Interactive wizard prompts for meta, providers, events, properties, retention, anomaly rules\n- Output: `*.telemetry.ts` file using `TelemetrySpec`\n\n### Best practices\n\n- Prefer `internal` privacy for non-PII; mark PII properties explicitly with `pii` + `redact`\n- Keep sampling ≥0.05 except for high-volume events\n- Configure anomaly detection on key metrics (duration, error count, conversion)\n- Check telemetry into source control alongside contracts; regenerate via CLI when specs change\n\n### Next steps\n\n- Phase 5: Regenerator monitors telemetry anomalies to propose spec improvements\n- Phase 6: Studio surfaces telemetry controls per tenant via `TenantAppConfig`\n\n"
+	body: "## TelemetrySpec\n\nTelemetry specs describe product analytics in a durable, type-safe way. They reference existing `EventSpec`s (same name/version) but layer on privacy classification, retention, sampling, and anomaly detection so instrumentation stays compliant and observable.\n\n- **File location**: `packages/libs/contracts/src/telemetry/spec.ts`\n- **Runtime tracker**: `packages/libs/contracts/src/telemetry/tracker.ts`\n- **Anomaly monitor**: `packages/libs/contracts/src/telemetry/anomaly.ts`\n\n### Core concepts\n\n```ts\nexport interface TelemetrySpec {\n  meta: TelemetryMeta;\n  events: TelemetryEventDef[];\n  config?: TelemetryConfig;\n}\n```\n\n- `meta`: ownership + identifiers (`name`, `version`, `domain`)\n- `events`: per-event semantics, property definitions, privacy level, retention, sampling, anomaly rules\n- `config`: defaults and provider configuration\n- `TelemetryRegistry`: registers specs, resolves latest version, finds event definitions by name/version\n\n### An example\n\n```ts\nexport const SigilTelemetry: TelemetrySpec = {\n  meta: {\n    name: 'sigil.telemetry',\n    version: 1,\n    title: 'Sigil telemetry',\n    description: 'Core Sigil product telemetry',\n    domain: 'sigil',\n    owners: ['@team.analytics'],\n    tags: ['telemetry'],\n    stability: StabilityEnum.Experimental,\n  },\n  config: {\n    defaultRetentionDays: 30,\n    defaultSamplingRate: 1,\n    providers: [\n      { type: 'posthog', config: { projectApiKey: process.env.POSTHOG_KEY } },\n    ],\n  },\n  events: [\n    {\n      name: 'sigil.telemetry.workflow_step',\n      version: 1,\n      semantics: {\n        what: 'Workflow step executed',\n        who: 'Actor executing the workflow',\n      },\n      privacy: 'internal',\n      properties: {\n        workflow: { type: 'string', required: true },\n        step: { type: 'string', required: true },\n        durationMs: { type: 'number' },\n        userId: { type: 'string', pii: true, redact: true },\n      },\n      anomalyDetection: {\n        enabled: true,\n        minimumSample: 10,\n        thresholds: [\n          { metric: 'durationMs', max: 1500 },\n        ],\n        actions: ['alert', 'trigger_regen'],\n      },\n    },\n  ],\n};\n```\n\n### Tracking events at runtime\n\n`TelemetryTracker` performs sampling, PII redaction, provider dispatch, and anomaly detection.\n\n```ts\nconst tracker = new TelemetryTracker({\n  registry: telemetryRegistry,\n  providers: [\n    {\n      id: 'posthog',\n      async send(dispatch) {\n        posthog.capture({\n          event: dispatch.name,\n          properties: dispatch.properties,\n          distinctId: dispatch.context.userId ?? dispatch.context.sessionId,\n        });\n      },\n    },\n  ],\n  anomalyMonitor: new TelemetryAnomalyMonitor({\n    onAnomaly(event) {\n      console.warn('Telemetry anomaly detected', event);\n    },\n  }),\n});\n\nawait tracker.track('sigil.telemetry.workflow_step', 1, {\n  workflow: 'onboarding',\n  step: 'verify_email',\n  durationMs: 2100,\n  userId: 'user-123',\n});\n```\n\n- Sampling obeys the event-specific rate (fallback to spec defaults)\n- Properties flagged with `pii` or `redact` are masked before dispatch\n- Anomaly monitor evaluates thresholds and triggers actions (e.g., log, alert, regeneration)\n\n### Spec integration\n\n- `ContractSpec.telemetry` allows operations to emit success/failure events automatically\n- `OperationSpecRegistry.execute()` uses the tracker when `ctx.telemetry` is provided\n- `WorkflowRunner` (Phase 4 follow-up) will emit telemetry during step transitions\n- `TelemetrySpec` events should reuse `EventSpec` names/versions to keep analytics/contract parity\n\n### CLI workflow\n\n```\ncontracts-cli create telemetry\n```\n\n- Interactive wizard prompts for meta, providers, events, properties, retention, anomaly rules\n- Output: `*.telemetry.ts` file using `TelemetrySpec`\n\n### Best practices\n\n- Prefer `internal` privacy for non-PII; mark PII properties explicitly with `pii` + `redact`\n- Keep sampling ≥0.05 except for high-volume events\n- Configure anomaly detection on key metrics (duration, error count, conversion)\n- Check telemetry into source control alongside contracts; regenerate via CLI when specs change\n\n### Next steps\n\n- Phase 5: Regenerator monitors telemetry anomalies to propose spec improvements\n- Phase 6: Studio surfaces telemetry controls per tenant via `TenantAppConfig`\n\n"
 }];
 registerDocBlocks(tech_contracts_telemetry_DocBlocks);
 

package/dist/tests/runner.d.ts

@@ -1,6 +1,6 @@
 import { Assertion, TestScenario, TestSpec } from "./spec.js";
 import { HandlerCtx } from "../types.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import "../index.js";
 
 //#region src/tests/runner.d.ts
@@ -22,7 +22,7 @@ interface TestRunResult {
   failed: number;
 }
 interface TestRunnerConfig {
-  registry: SpecRegistry;
+  registry: OperationSpecRegistry;
   createContext?: () => HandlerCtx | Promise<HandlerCtx>;
   beforeEach?: (scenario: TestScenario) => void | Promise<void>;
   afterEach?: (scenario: TestScenario, result: ScenarioRunResult) => void | Promise<void>;

package/dist/tests/spec.d.ts

@@ -10,7 +10,7 @@ interface WorkflowTargetRef {
   version?: number;
 }
 type TestTarget = {
-  type: 'contract';
+  type: 'operation';
   operation: OperationTargetRef;
 } | {
   type: 'workflow';

package/dist/workflow/spec.d.ts

@@ -1,10 +1,10 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
 import { CapabilityRef } from "../capabilities.js";
 import { ExperimentRef } from "../experiments/spec.js";
 import { OpRef } from "../features.js";
 
 //#region src/workflow/spec.d.ts
-
 /**
  * Reference to a form spec declared in {@link FormRegistry}.
  */
@@ -94,6 +94,16 @@ declare class WorkflowRegistry {
   register(spec: WorkflowSpec): this;
   list(): WorkflowSpec[];
   get(name: string, version?: number): WorkflowSpec | undefined;
+  /** Filter workflows by criteria. */
+  filter(criteria: RegistryFilter): WorkflowSpec[];
+  /** List workflows with specific tag. */
+  listByTag(tag: string): WorkflowSpec[];
+  /** List workflows by owner. */
+  listByOwner(owner: string): WorkflowSpec[];
+  /** Group workflows by key function. */
+  groupBy(keyFn: GroupKeyFn<WorkflowSpec>): Map<string, WorkflowSpec[]>;
+  /** Get unique tags from all workflows. */
+  getUniqueTags(): string[];
 }
 //#endregion
 export { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus };

package/dist/workflow/spec.js

@@ -1,3 +1,6 @@
+import { __toCommonJS } from "../_virtual/rolldown_runtime.js";
+import { init_registry_utils, registry_utils_exports } from "../registry-utils.js";
+
 //#region src/workflow/spec.ts
 function workflowKey(meta) {
 	return `${meta.name}.v${meta.version}`;
@@ -26,6 +29,29 @@ var WorkflowRegistry = class {
 		}
 		return candidate;
 	}
+	/** Filter workflows by criteria. */
+	filter(criteria) {
+		const { filterBy } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return filterBy(this.list(), criteria);
+	}
+	/** List workflows with specific tag. */
+	listByTag(tag) {
+		return this.list().filter((w) => w.meta.tags?.includes(tag));
+	}
+	/** List workflows by owner. */
+	listByOwner(owner) {
+		return this.list().filter((w) => w.meta.owners?.includes(owner));
+	}
+	/** Group workflows by key function. */
+	groupBy(keyFn) {
+		const { groupBy } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return groupBy(this.list(), keyFn);
+	}
+	/** Get unique tags from all workflows. */
+	getUniqueTags() {
+		const { getUniqueTags } = (init_registry_utils(), __toCommonJS(registry_utils_exports));
+		return getUniqueTags(this.list());
+	}
 };
 
 //#endregion

package/dist/workflow/validation.d.ts

@@ -1,5 +1,5 @@
 import { WorkflowSpec } from "./spec.js";
-import { SpecRegistry } from "../registry.js";
+import { OperationSpecRegistry } from "../registry.js";
 import { FormRegistry } from "../forms.js";
 
 //#region src/workflow/validation.d.ts
@@ -10,7 +10,7 @@ interface WorkflowValidationIssue {
   context?: Record<string, unknown>;
 }
 interface ValidateWorkflowSpecOptions {
-  operations?: SpecRegistry;
+  operations?: OperationSpecRegistry;
   forms?: FormRegistry;
 }
 declare class WorkflowValidationError extends Error {