@contractspec/lib.contracts 1.61.0 → 1.63.0

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

@@ -1,164 +0,0 @@
-import { createRequire } from "node:module";
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/docs/presentations.ts
-var DEFAULT_TARGETS = [
-  "markdown",
-  "react"
-];
-function normalizeRoute(route) {
-  if (!route.length)
-    return "/";
-  const withLeading = route.startsWith("/") ? route : `/${route}`;
-  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-  if (block.route)
-    return normalizeRoute(block.route);
-  const prefix = routePrefix ?? "/docs";
-  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
-  return normalizeRoute(path);
-}
-function buildName(block, namespace) {
-  return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationSpec(block, options) {
-  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
-  const stability = block.stability ?? options?.defaultStability ?? "stable";
-  return {
-    meta: {
-      key: buildName(block, options?.namespace),
-      title: block.title,
-      version,
-      description: block.summary ?? block.title,
-      tags: block.tags || [],
-      owners: block.owners || [],
-      domain: block.domain || "",
-      stability,
-      goal: `Documentation of: ${block.summary}`,
-      context: `Auto-generated`
-    },
-    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
-    source: {
-      type: "blocknotejs",
-      docJson: block.body
-    },
-    targets
-  };
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-  return blocks.map((block) => ({
-    block,
-    route: deriveRoute(block, options?.routePrefix),
-    descriptor: docBlockToPresentationSpec(block, options)
-  }));
-}
-function docBlocksToPresentationSpecs(blocks, options) {
-  return blocks.map((block) => docBlockToPresentationSpec(block, options));
-}
-function mapDocRoutes(routes) {
-  return routes.map(({ route, descriptor }) => [route, descriptor]);
-}
-
-// src/docs/registry.ts
-class DocRegistry {
-  routes = new Map;
-  constructor(blocks = [], options) {
-    blocks.forEach((block) => this.register(block, options));
-  }
-  register(block, options) {
-    const [route] = docBlocksToPresentationRoutes([block], options);
-    if (route) {
-      this.routes.set(block.id, route);
-    }
-    return this;
-  }
-  list() {
-    return [...this.routes.values()];
-  }
-  get(id) {
-    return this.routes.get(id);
-  }
-  toRouteTuples() {
-    return this.list().map(({ route, descriptor }) => [route, descriptor]);
-  }
-  toPresentationSpecs(options) {
-    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-  }
-}
-var requiredFields = [
-  "id",
-  "title",
-  "body",
-  "kind",
-  "visibility",
-  "route"
-];
-var defaultDocRegistry = new DocRegistry;
-function registerDocBlocks(blocks) {
-  for (const block of blocks) {
-    for (const field of requiredFields) {
-      if (!block[field]) {
-        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-      }
-    }
-    defaultDocRegistry.register(block);
-  }
-}
-function listRegisteredDocBlocks() {
-  return defaultDocRegistry.list().map((r) => r.block);
-}
-function docId(id) {
-  const found = defaultDocRegistry.get(id);
-  if (!found)
-    throw new Error(`DocBlock not registered: ${id}`);
-  return id;
-}
-
-// src/telemetry/docs/telemetry.docblock.ts
-var tech_contracts_telemetry_DocBlocks = [
-  {
-    id: "docs.tech.contracts.telemetry",
-    title: "TelemetrySpec",
-    summary: "Telemetry 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.",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/contracts/telemetry",
-    tags: ["tech", "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.0.0',\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.0.0',\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);
-export {
-  tech_contracts_telemetry_DocBlocks
-};

package/dist/node/telemetry/index.js

@@ -1,417 +0,0 @@
-import { createRequire } from "node:module";
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/registry-utils.ts
-var exports_registry_utils = {};
-__export(exports_registry_utils, {
-  groupByToArray: () => groupByToArray,
-  groupByMultiple: () => groupByMultiple,
-  groupBy: () => groupBy,
-  getUniqueTags: () => getUniqueTags,
-  getUniqueOwners: () => getUniqueOwners,
-  getUniqueDomains: () => getUniqueDomains,
-  filterBy: () => filterBy,
-  GroupingStrategies: () => GroupingStrategies
-});
-function filterBy(items, filter) {
-  return items.filter((item) => {
-    if (filter.tags?.length) {
-      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
-      if (!hasMatchingTag)
-        return false;
-    }
-    if (filter.owners?.length) {
-      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
-      if (!hasMatchingOwner)
-        return false;
-    }
-    if (filter.stability?.length) {
-      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
-        return false;
-      }
-    }
-    if (filter.domain) {
-      const itemDomain = GroupingStrategies.byDomain(item);
-      if (itemDomain !== filter.domain)
-        return false;
-    }
-    if (filter.keyPattern) {
-      const name = item.meta.key ?? item.meta.key ?? "";
-      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
-      const regex = new RegExp(`^${pattern}$`, "i");
-      if (!regex.test(name))
-        return false;
-    }
-    return true;
-  });
-}
-function groupBy(items, keyFn) {
-  const groups = new Map;
-  for (const item of items) {
-    const key = keyFn(item);
-    const existing = groups.get(key);
-    if (existing) {
-      existing.push(item);
-    } else {
-      groups.set(key, [item]);
-    }
-  }
-  return groups;
-}
-function groupByToArray(items, keyFn) {
-  const map = groupBy(items, keyFn);
-  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
-}
-function groupByMultiple(items, keysFn) {
-  const groups = new Map;
-  for (const item of items) {
-    const keys = keysFn(item);
-    for (const key of keys) {
-      const existing = groups.get(key);
-      if (existing) {
-        existing.push(item);
-      } else {
-        groups.set(key, [item]);
-      }
-    }
-  }
-  return groups;
-}
-function getUniqueTags(items) {
-  const tags = new Set;
-  for (const item of items) {
-    for (const tag of item.meta.tags ?? []) {
-      tags.add(tag);
-    }
-  }
-  return Array.from(tags).sort();
-}
-function getUniqueOwners(items) {
-  const owners = new Set;
-  for (const item of items) {
-    for (const owner of item.meta.owners ?? []) {
-      owners.add(owner);
-    }
-  }
-  return Array.from(owners).sort();
-}
-function getUniqueDomains(items) {
-  const domains = new Set;
-  for (const item of items) {
-    domains.add(GroupingStrategies.byDomain(item));
-  }
-  return Array.from(domains).sort();
-}
-var GroupingStrategies;
-var init_registry_utils = __esm(() => {
-  GroupingStrategies = {
-    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
-    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
-    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
-    byDomain: (item) => {
-      const name = item.meta.key ?? item.meta.key ?? "";
-      return name.split(".")[0] ?? "default";
-    },
-    byStability: (item) => item.meta.stability ?? "stable",
-    byUrlPath: (level) => (item) => {
-      if (!item.path)
-        return "root";
-      const segments = item.path.split("/").filter(Boolean);
-      return segments.slice(0, level).join("/") || "root";
-    }
-  };
-});
-
-// src/registry.ts
-init_registry_utils();
-import { compareVersions } from "compare-versions";
-var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
-
-class SpecContractRegistry {
-  contractType;
-  items = new Map;
-  constructor(contractType, items) {
-    this.contractType = contractType;
-    if (items) {
-      items.forEach((p) => this.register(p));
-    }
-  }
-  register(p) {
-    const key = keyOfSpecContract(p);
-    if (this.items.has(key))
-      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
-    this.items.set(key, p);
-    return this;
-  }
-  count() {
-    return this.items.size;
-  }
-  list() {
-    return [...this.items.values()];
-  }
-  get(key, version) {
-    if (version != null)
-      return this.items.get(`${key}.v${version}`);
-    let candidate;
-    for (const [k, p] of this.items.entries()) {
-      if (!k.startsWith(`${key}.v`))
-        continue;
-      if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) {
-        candidate = p;
-      }
-    }
-    return candidate;
-  }
-  has(key, version) {
-    return !!this.get(key, version);
-  }
-  filter(criteria) {
-    return filterBy(this.list(), criteria);
-  }
-  listByTag(tag) {
-    return this.list().filter((p) => p.meta.tags?.includes(tag));
-  }
-  listByOwner(owner) {
-    return this.list().filter((p) => p.meta.owners?.includes(owner));
-  }
-  groupBy(keyFn) {
-    return groupBy(this.list(), keyFn);
-  }
-  getUniqueTags() {
-    return getUniqueTags(this.list());
-  }
-}
-
-// src/telemetry/spec.ts
-import { compareVersions as compareVersions2 } from "compare-versions";
-var telemetryKey = (meta) => `${meta.key}.v${meta.version}`;
-
-class TelemetryRegistry extends SpecContractRegistry {
-  eventsByKey = new Map;
-  specByEventKey = new Map;
-  constructor(items) {
-    super("telemetry", items);
-    if (items) {
-      items.forEach((spec) => this.indexEvents(spec));
-    }
-  }
-  register(spec) {
-    super.register(spec);
-    this.indexEvents(spec);
-    return this;
-  }
-  indexEvents(spec) {
-    for (const event of spec.events) {
-      this.eventsByKey.set(`${event.key}.v${event.version}`, event);
-      this.specByEventKey.set(`${event.key}.v${event.version}`, spec);
-    }
-  }
-  findEventDef(name, version) {
-    if (version != null) {
-      return this.eventsByKey.get(`${name}.v${version}`);
-    }
-    let latest;
-    for (const event of this.eventsByKey.values()) {
-      if (event.key !== name)
-        continue;
-      if (!latest || compareVersions2(event.version, latest.version) > 0) {
-        latest = event;
-      }
-    }
-    return latest;
-  }
-  getSpecForEvent(name, version) {
-    return this.specByEventKey.get(`${name}.v${version}`);
-  }
-}
-function makeTelemetryKey(meta) {
-  return telemetryKey(meta);
-}
-
-// src/telemetry/tracker.ts
-import { randomUUID } from "crypto";
-var maskValue = (value) => {
-  if (value == null)
-    return value;
-  if (typeof value === "string")
-    return "REDACTED";
-  if (typeof value === "number")
-    return 0;
-  if (typeof value === "boolean")
-    return false;
-  if (Array.isArray(value))
-    return value.map(() => "REDACTED");
-  if (typeof value === "object") {
-    return Object.fromEntries(Object.keys(value).map((key) => [
-      key,
-      "REDACTED"
-    ]));
-  }
-  return "REDACTED";
-};
-
-class TelemetryTracker {
-  providers = new Map;
-  registry;
-  anomalyMonitor;
-  random;
-  clock;
-  constructor(options) {
-    this.registry = options.registry;
-    this.anomalyMonitor = options.anomalyMonitor;
-    this.random = options.random ?? Math.random;
-    this.clock = options.clock ?? (() => new Date);
-    for (const provider of options.providers ?? []) {
-      this.providers.set(provider.id, provider);
-    }
-  }
-  registerProvider(provider) {
-    this.providers.set(provider.id, provider);
-  }
-  unregisterProvider(providerId) {
-    this.providers.delete(providerId);
-  }
-  async track(name, version, properties, context = {}) {
-    const definition = this.registry.findEventDef(name, version);
-    if (!definition)
-      return false;
-    const spec = this.registry.getSpecForEvent(definition.key, definition.version);
-    if (!spec)
-      return false;
-    if (!this.shouldSample(definition.sampling ?? spec.config?.defaultSamplingRate)) {
-      return false;
-    }
-    const redactedProperties = this.redactProperties(definition, properties);
-    const dispatch = {
-      id: randomUUID(),
-      name: definition.key,
-      version: definition.version,
-      occurredAt: this.clock().toISOString(),
-      properties: redactedProperties,
-      privacy: definition.privacy,
-      context,
-      tags: definition.tags,
-      spec,
-      definition
-    };
-    await Promise.all([...this.providers.values()].map((provider) => provider.send(dispatch)));
-    this.anomalyMonitor?.observe(dispatch);
-    return true;
-  }
-  shouldSample(sampling) {
-    if (typeof sampling === "number") {
-      return this.random() < sampling;
-    }
-    if (!sampling)
-      return true;
-    return this.random() < sampling.rate;
-  }
-  redactProperties(definition, properties) {
-    const result = {};
-    for (const [key, value] of Object.entries(properties)) {
-      const def = definition.properties[key];
-      if (!def) {
-        result[key] = value;
-        continue;
-      }
-      if (def.redact || def.pii || definition.privacy === "sensitive") {
-        result[key] = maskValue(value);
-      } else {
-        result[key] = value;
-      }
-    }
-    return result;
-  }
-}
-
-// src/telemetry/anomaly.ts
-class TelemetryAnomalyMonitor {
-  onAnomaly;
-  now;
-  samples = new Map;
-  constructor(options = {}) {
-    this.onAnomaly = options.onAnomaly;
-    this.now = options.now ?? (() => new Date);
-  }
-  observe(dispatch) {
-    const anomalyConfig = dispatch.definition.anomalyDetection;
-    if (!anomalyConfig?.enabled)
-      return;
-    if (!anomalyConfig.thresholds?.length)
-      return;
-    const eventKey = `${dispatch.name}.v${dispatch.version}`;
-    const count = this.samples.get(eventKey) ?? 0;
-    const newCount = count + 1;
-    this.samples.set(eventKey, newCount);
-    if (typeof anomalyConfig.minimumSample === "number" && newCount < anomalyConfig.minimumSample) {
-      return;
-    }
-    for (const threshold of anomalyConfig.thresholds) {
-      const value = this.extractMetric(dispatch, threshold.metric);
-      if (typeof value !== "number")
-        continue;
-      if (typeof threshold.min === "number" && value < threshold.min) {
-        this.emit(dispatch, anomalyConfig, threshold.metric, value, "min");
-      }
-      if (typeof threshold.max === "number" && value > threshold.max) {
-        this.emit(dispatch, anomalyConfig, threshold.metric, value, "max");
-      }
-    }
-  }
-  extractMetric(dispatch, metric) {
-    const value = dispatch.properties[metric];
-    if (typeof value === "number")
-      return value;
-    if (typeof value === "object" && value !== null && "value" in value) {
-      const maybeNumber = value.value;
-      return typeof maybeNumber === "number" ? maybeNumber : undefined;
-    }
-    return;
-  }
-  emit(dispatch, threshold, metric, value, type) {
-    this.onAnomaly?.({
-      dispatch,
-      threshold,
-      metric,
-      value,
-      type
-    });
-  }
-  reset() {
-    this.samples.clear();
-  }
-}
-export {
-  makeTelemetryKey,
-  TelemetryTracker,
-  TelemetryRegistry,
-  TelemetryAnomalyMonitor
-};