@contractspec/lib.contracts 1.44.0 → 1.45.0

package/dist/policy/docs/policy.docblock.js

@@ -13,7 +13,7 @@ const tech_contracts_policy_DocBlocks = [{
 		"contracts",
 		"policy"
 	],
-	body: "# PolicySpec & PolicyEngine\n\n## Purpose\n\n`PolicySpec` gives a declarative, typed home for access-control logic covering:\n- **Who** can perform an action (ABAC/ReBAC style rules)\n- **What** they can access (resources + optional field-level overrides)\n- **When** special conditions apply (contextual expressions)\n- **How** PII should be handled (consent/retention hints)\n\n`PolicyEngine` evaluates one or more policies and returns an `allow`/`deny` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (`OperationSpecRegistry` → `ctx.decide`).\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/policy/spec.ts`\n- Runtime evaluation: `packages/libs/contracts/src/policy/engine.ts`\n- Tests: `packages/.../policy/engine.test.ts`\n\n## `PolicySpec`\n\n```ts\nexport interface PolicySpec {\n  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }\n  rules: PolicyRule[];       // allow/deny rules for actions\n  fieldPolicies?: FieldPolicyRule[];\n  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };\n  relationships?: RelationshipDefinition[];\n  consents?: ConsentDefinition[];\n  rateLimits?: RateLimitDefinition[];\n  opa?: { package: string; decision?: string };\n}\n```\n\n- `PolicyRule`\n  - `effect`: `'allow' | 'deny'`\n  - `actions`: e.g., `['read', 'write', 'delete']` (string namespace is flexible)\n  - `subject`: `{ roles?: string[]; attributes?: { attr: matcher } }`\n  - `resource`: `{ type: string; fields?: string[]; attributes?: {...} }`\n  - `relationships`: `{ relation, objectId?, objectType? }[]` → ReBAC checks (use `objectId: '$resource'` to target the current resource)\n  - `requiresConsent`: `['consent_id']` → references spec-level consent definitions\n  - `flags`: feature flags that must be enabled (`DecisionContext.flags`)\n  - `rateLimit`: string reference to `rateLimits` entry or inline object `{ rpm, key?, windowSeconds?, burst? }`\n  - `escalate`: `'human_review' | null` to indicate manual approval\n  - `conditions`: optional expression snippets evaluated against `{ subject, resource, context }`\n- `FieldPolicyRule`\n  - `field`: dot-path string (e.g., `contact.email`)\n  - `actions`: subset of `['read', 'write']`\n  - Same `subject` / `resource` / `conditions` shape\n  - Useful for redacting specific fields, even when the global action is allowed\n- `RelationshipDefinition`\n  - Canonical tuples for relationship graph (`subjectType`, `relation`, `objectType`, `transitive?`)\n- `ConsentDefinition`\n  - `{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }`\n- `RateLimitDefinition`\n  - `{ id, rpm, key?, windowSeconds?, burst? }`\n- `PolicyRef`\n  - `{ name: string; version: number }` → attach to contract specs / workflows\n\n## Registry\n\n```ts\nconst registry = new PolicyRegistry();\nregistry.register(CorePolicySpec);\nconst spec = registry.get('core.default', 1);\n```\n\nGuarantees uniqueness per `(name, version)` and exposes helpers to resolve highest versions.\n\n## Engine\n\n```ts\nconst engine = new PolicyEngine(policyRegistry);\n\nconst decision = engine.decide({\n  action: 'read',\n  subject: { roles: ['admin'] },\n  resource: { type: 'resident', fields: ['contact.email'] },\n  policies: [{ name: 'core.default', version: 1 }],\n});\n/*\n{\n  effect: 'allow',\n  reason: 'core.default',\n  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],\n  pii: { fields: ['contact.email'], consentRequired: true }\n}\n*/\n```\n\n- First matching **deny** wins; otherwise the first **allow** is returned.\n- Field policies are aggregated across referenced policies:\n  - Later denies override earlier allows for a given field.\n  - Returned as `fieldDecisions` to simplify downstream masking.\n- PII metadata is surfaced when defined to help adapt logging/telemetry.\n\n### Expression Support\n\nConditions accept small JS snippets (e.g., `subject.attributes.orgId === context.orgId`). The engine runs them in a constrained scope (`subject`, `resource`, `context`) without access to global state.\n\n### ReBAC & Relationships\n\n- Provide relationship tuples via `PolicySpec.relationships` for documentation/validation.\n- Reference them inside rules with `relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]`.\n- The execution context must populate `subject.relationships` (`[{ relation, object, objectType }]`) for the engine to evaluate ReBAC guards.\n\n### Consent & Rate Limits\n\n- Declare reusable consent definitions under `consents`. Rules list the IDs they require; if a user session lacks the consent (`DecisionContext.consents`), the engine returns `effect: 'deny'` with `reason: 'consent_required'` and enumerates missing consents.\n- Attach rate limits either inline or via `rateLimits` references. When a rule matches, the engine surfaces `{ rpm, key, windowSeconds?, burst? }` so callers can feed it to shared limiters.\n\n### OPA Adapter\n\n- `OPAPolicyAdapter` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (`effect`, `reason`, `fieldDecisions`, `requiredConsents`).\n- Use when migrating to OPA policies or running defense-in-depth: call `engine.decide()`, then pass the preliminary decision to `adapter.evaluate(...)`. The adapter marks merged decisions with `evaluatedBy: 'opa'`.\n- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.\n\n## Contract Integration\n\n`ContractSpec.policy` now supports:\n\n```ts\npolicy: {\n  auth: 'anonymous' | 'user' | 'admin';\n  ...\n  policies?: PolicyRef[];                // policies evaluated before execution\n  fieldPolicies?: {                      // field hints (read/write) per policy\n    field: string;\n    actions: ('read' | 'write')[];\n    policy?: PolicyRef;\n  }[];\n}\n```\n\nAdapters can resolve refs through a shared `PolicyEngine` and populate `ctx.decide` so `OperationSpecRegistry.execute` benefits from centralized enforcement.\n\n## Authoring Guidelines\n\n1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).\n2. Keep rule scopes narrow (per feature/operation) and compose multiple `PolicyRef`s when necessary.\n3. Store PII field lists here to avoid duplication across logs/telemetry.\n4. Use explicit rule reasons for auditability and better developer feedback.\n5. Treat versioning seriously; bump `meta.version` whenever behavior changes.\n\n## Future Enhancements\n\n- Richer expression language (composable predicates, time-based conditions).\n- Multi-tenant relationship graph services (store/resolve relationships at scale).\n- Tooling that auto-generates docs/tests for policies referenced in specs.\n\n"
+	body: "# PolicySpec & PolicyEngine\n\n## Purpose\n\n`PolicySpec` gives a declarative, typed home for access-control logic covering:\n- **Who** can perform an action (ABAC/ReBAC style rules)\n- **What** they can access (resources + optional field-level overrides)\n- **When** special conditions apply (contextual expressions)\n- **How** PII should be handled (consent/retention hints)\n\n`PolicyEngine` evaluates one or more policies and returns an `allow`/`deny` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (`OperationSpecRegistry` → `ctx.decide`).\n\n## Location\n\n- Types & registry: `packages/libs/contracts/src/policy/spec.ts`\n- Runtime evaluation: `packages/libs/contracts/src/policy/engine.ts`\n- Tests: `packages/.../policy/engine.test.ts`\n\n## `PolicySpec`\n\n```ts\nexport interface PolicySpec {\n  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }\n  rules: PolicyRule[];       // allow/deny rules for actions\n  fieldPolicies?: FieldPolicyRule[];\n  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };\n  relationships?: RelationshipDefinition[];\n  consents?: ConsentDefinition[];\n  rateLimits?: RateLimitDefinition[];\n  opa?: { package: string; decision?: string };\n}\n```\n\n- `PolicyRule`\n  - `effect`: `'allow' | 'deny'`\n  - `actions`: e.g., `['read', 'write', 'delete']` (string namespace is flexible)\n  - `subject`: `{ roles?: string[]; attributes?: { attr: matcher } }`\n  - `resource`: `{ type: string; fields?: string[]; attributes?: {...} }`\n  - `relationships`: `{ relation, objectId?, objectType? }[]` → ReBAC checks (use `objectId: '$resource'` to target the current resource)\n  - `requiresConsent`: `['consent_id']` → references spec-level consent definitions\n  - `flags`: feature flags that must be enabled (`DecisionContext.flags`)\n  - `rateLimit`: string reference to `rateLimits` entry or inline object `{ rpm, key?, windowSeconds?, burst? }`\n  - `escalate`: `'human_review' | null` to indicate manual approval\n  - `conditions`: optional expression snippets evaluated against `{ subject, resource, context }`\n- `FieldPolicyRule`\n  - `field`: dot-path string (e.g., `contact.email`)\n  - `actions`: subset of `['read', 'write']`\n  - Same `subject` / `resource` / `conditions` shape\n  - Useful for redacting specific fields, even when the global action is allowed\n- `RelationshipDefinition`\n  - Canonical tuples for relationship graph (`subjectType`, `relation`, `objectType`, `transitive?`)\n- `ConsentDefinition`\n  - `{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }`\n- `RateLimitDefinition`\n  - `{ id, rpm, key?, windowSeconds?, burst? }`\n- `PolicyRef`\n  - `{ name: string; version: string }` → attach to contract specs / workflows\n\n## Registry\n\n```ts\nconst registry = new PolicyRegistry();\nregistry.register(CorePolicySpec);\nconst spec = registry.get('core.default', 1);\n```\n\nGuarantees uniqueness per `(name, version)` and exposes helpers to resolve highest versions.\n\n## Engine\n\n```ts\nconst engine = new PolicyEngine(policyRegistry);\n\nconst decision = engine.decide({\n  action: 'read',\n  subject: { roles: ['admin'] },\n  resource: { type: 'resident', fields: ['contact.email'] },\n  policies: [{ name: 'core.default', version: '1.0.0' }],\n});\n/*\n{\n  effect: 'allow',\n  reason: 'core.default',\n  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],\n  pii: { fields: ['contact.email'], consentRequired: true }\n}\n*/\n```\n\n- First matching **deny** wins; otherwise the first **allow** is returned.\n- Field policies are aggregated across referenced policies:\n  - Later denies override earlier allows for a given field.\n  - Returned as `fieldDecisions` to simplify downstream masking.\n- PII metadata is surfaced when defined to help adapt logging/telemetry.\n\n### Expression Support\n\nConditions accept small JS snippets (e.g., `subject.attributes.orgId === context.orgId`). The engine runs them in a constrained scope (`subject`, `resource`, `context`) without access to global state.\n\n### ReBAC & Relationships\n\n- Provide relationship tuples via `PolicySpec.relationships` for documentation/validation.\n- Reference them inside rules with `relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]`.\n- The execution context must populate `subject.relationships` (`[{ relation, object, objectType }]`) for the engine to evaluate ReBAC guards.\n\n### Consent & Rate Limits\n\n- Declare reusable consent definitions under `consents`. Rules list the IDs they require; if a user session lacks the consent (`DecisionContext.consents`), the engine returns `effect: 'deny'` with `reason: 'consent_required'` and enumerates missing consents.\n- Attach rate limits either inline or via `rateLimits` references. When a rule matches, the engine surfaces `{ rpm, key, windowSeconds?, burst? }` so callers can feed it to shared limiters.\n\n### OPA Adapter\n\n- `OPAPolicyAdapter` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (`effect`, `reason`, `fieldDecisions`, `requiredConsents`).\n- Use when migrating to OPA policies or running defense-in-depth: call `engine.decide()`, then pass the preliminary decision to `adapter.evaluate(...)`. The adapter marks merged decisions with `evaluatedBy: 'opa'`.\n- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.\n\n## Contract Integration\n\n`ContractSpec.policy` now supports:\n\n```ts\npolicy: {\n  auth: 'anonymous' | 'user' | 'admin';\n  ...\n  policies?: PolicyRef[];                // policies evaluated before execution\n  fieldPolicies?: {                      // field hints (read/write) per policy\n    field: string;\n    actions: ('read' | 'write')[];\n    policy?: PolicyRef;\n  }[];\n}\n```\n\nAdapters can resolve refs through a shared `PolicyEngine` and populate `ctx.decide` so `OperationSpecRegistry.execute` benefits from centralized enforcement.\n\n## Authoring Guidelines\n\n1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).\n2. Keep rule scopes narrow (per feature/operation) and compose multiple `PolicyRef`s when necessary.\n3. Store PII field lists here to avoid duplication across logs/telemetry.\n4. Use explicit rule reasons for auditability and better developer feedback.\n5. Treat versioning seriously; bump `meta.version` whenever behavior changes.\n\n## Future Enhancements\n\n- Richer expression language (composable predicates, time-based conditions).\n- Multi-tenant relationship graph services (store/resolve relationships at scale).\n- Tooling that auto-generates docs/tests for policies referenced in specs.\n\n"
 }];
 registerDocBlocks(tech_contracts_policy_DocBlocks);
 

package/dist/policy/engine.js

@@ -1,3 +1,5 @@
+import "./registry.js";
+
 //#region src/policy/engine.ts
 var PolicyEngine = class {
 	constructor(registry) {

package/dist/policy/spec.d.ts

@@ -97,7 +97,7 @@ interface PolicySpec {
 }
 interface PolicyRef {
   key: string;
-  version: number;
+  version: string;
 }
 //#endregion
 export { AttributeMatcher, ConsentDefinition, FieldPolicyRule, PIIPolicy, PolicyCondition, PolicyEffect, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRule, PolicySpec, RateLimitDefinition, RelationshipDefinition, RelationshipMatcher, ResourceMatcher, SubjectMatcher };

package/dist/prompt.d.ts

@@ -1,4 +1,4 @@
-import * as z$1 from "zod";
+import * as z$2 from "zod";
 
 //#region src/prompt.d.ts
 type PromptStability = 'experimental' | 'beta' | 'stable' | 'deprecated';
@@ -7,7 +7,7 @@ interface PromptArg {
   name: string;
   description?: string;
   required?: boolean;
-  schema: z$1.ZodType;
+  schema: z$2.ZodType;
   completeWith?: string;
 }
 /**
@@ -24,7 +24,7 @@ type PromptContentPart = {
 /** Prompt metadata for discoverability and governance. */
 interface PromptMeta {
   key: string;
-  version: number;
+  version: string;
   title: string;
   description: string;
   tags?: string[];
@@ -41,13 +41,13 @@ interface PromptPolicy {
   };
 }
 /** Full prompt specification including args schema and render function. */
-interface PromptSpec<I extends z$1.ZodType> {
+interface PromptSpec<I extends z$2.ZodType> {
   meta: PromptMeta;
   args: PromptArg[];
   input: I;
   policy?: PromptPolicy;
   /** Render MCP-friendly content parts. DO NOT perform side effects here. */
-  render: (args: z$1.infer<I>, ctx: {
+  render: (args: z$2.infer<I>, ctx: {
     userId?: string | null;
     orgId?: string | null;
     locale?: string;
@@ -55,6 +55,6 @@ interface PromptSpec<I extends z$1.ZodType> {
   }) => Promise<PromptContentPart[]>;
 }
 /** Identity helper that preserves generic inference when declaring prompts. */
-declare function definePrompt<I extends z$1.ZodType>(spec: PromptSpec<I>): PromptSpec<I>;
+declare function definePrompt<I extends z$2.ZodType>(spec: PromptSpec<I>): PromptSpec<I>;
 //#endregion
 export { PromptArg, PromptContentPart, PromptMeta, PromptPolicy, PromptSpec, PromptStability, definePrompt };

package/dist/promptRegistry.d.ts

@@ -1,15 +1,15 @@
 import { PromptSpec } from "./prompt.js";
-import * as z$1 from "zod";
+import * as z$2 from "zod";
 
 //#region src/promptRegistry.d.ts
 declare class PromptRegistry {
   private prompts;
   /** Register a prompt. Throws on duplicate name+version. */
-  register<I extends z$1.ZodType>(p: PromptSpec<I>): this;
+  register<I extends z$2.ZodType>(p: PromptSpec<I>): this;
   /** List all registered prompts. */
-  list(): PromptSpec<z$1.ZodType<unknown, unknown, z$1.core.$ZodTypeInternals<unknown, unknown>>>[];
+  list(): PromptSpec<z$2.ZodType<unknown, unknown, z$2.core.$ZodTypeInternals<unknown, unknown>>>[];
   /** Get prompt by name; when version omitted, returns highest version. */
-  get(name: string, version?: number): PromptSpec<z$1.ZodType<unknown, unknown, z$1.core.$ZodTypeInternals<unknown, unknown>>> | undefined;
+  get(name: string, version?: string): PromptSpec<z$2.ZodType<unknown, unknown, z$2.core.$ZodTypeInternals<unknown, unknown>>> | undefined;
 }
 //#endregion
 export { PromptRegistry };

package/dist/promptRegistry.js

@@ -1,3 +1,4 @@
+import { compareVersions } from "compare-versions";
 import "zod";
 
 //#region src/promptRegistry.ts
@@ -18,13 +19,9 @@ var PromptRegistry = class {
 	get(name, version) {
 		if (version != null) return this.prompts.get(`${name}-v${version}`);
 		let candidate;
-		let max = -Infinity;
 		for (const [k, p] of this.prompts.entries()) {
 			if (!k.startsWith(`${name}.v`)) continue;
-			if (p.meta.version > max) {
-				max = p.meta.version;
-				candidate = p;
-			}
+			if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) candidate = p;
 		}
 		return candidate;
 	}

package/dist/regenerator/docs/regenerator.docblock.js

@@ -13,7 +13,7 @@ const tech_contracts_regenerator_DocBlocks = [{
 		"contracts",
 		"regenerator"
 	],
-	body: "## Regenerator Service\n\nThe Regenerator daemon observes telemetry, error, and behavior streams, then suggests spec-level changes (not code patches) that can be reviewed and applied through the App Studio.\n\n- Runtime entrypoint: `packages/libs/contracts/src/regenerator/service.ts`\n- Types/interfaces: `packages/libs/contracts/src/regenerator/types.ts`\n- Signal adapters: `packages/libs/contracts/src/regenerator/adapters.ts`\n\n### Architecture\n\n```text\nSignal Adapters ──► RegeneratorService ──► Rules ──► ProposalSink\n          ▲                                       │\n          │                                       ▼\n     Telemetry / Errors / Behavior         Spec change proposals\n```\n\n1. **Signal adapters** pull batches of telemetry, error logs, or behavior metrics for each `RegenerationContext`.\n2. `RegeneratorService` schedules polling (`resolveAppConfig` + `composeAppConfig` provide context).\n3. **Rules** implement domain heuristics and emit `SpecChangeProposal` objects.\n4. **Proposal sinks** persist or forward proposals for human review.\n\n### Key types\n\n```ts\nexport interface RegenerationContext {\n  id: string;\n  blueprint: AppBlueprintSpec;\n  tenantConfig: TenantAppConfig;\n  resolved: ResolvedAppConfig;\n}\n\nexport interface RegeneratorRule {\n  id: string;\n  description: string;\n  evaluate(\n    context: RegenerationContext,\n    signals: RegeneratorSignal[]\n  ): Promise<SpecChangeProposal[]>;\n}\n\nexport interface SpecChangeProposal {\n  id: string;\n  title: string;\n  summary: string;\n  confidence: 'low' | 'medium' | 'high';\n  target: ProposalTarget;\n  actions: ProposalAction[];\n  blockers?: ProposalBlocker[];\n  signalIds: string[];\n  createdAt: Date;\n}\n```\n\n- Signals are normalized envelopes: telemetry (`count`, anomaly score), errors, and behavior trends.\n- Proposals reference blueprint or tenant specs via `ProposalTarget`.\n- Actions encode what the automation should perform (update blueprint, run tests/migrations, trigger regeneration).\n\n### Providing signals\n\nImplement `TelemetrySignalProvider`, `ErrorSignalProvider`, or `BehaviorSignalProvider`:\n\n```ts\nconst service = new RegeneratorService({\n  contexts,\n  adapters: {\n    telemetry: new PosthogTelemetryAdapter(),\n    errors: new SentryErrorAdapter(),\n  },\n  rules: [new WorkflowFailureRule(), new DataViewUsageRule()],\n  sink: new ProposalQueueSink(),\n  pollIntervalMs: 60_000,\n});\n```\n\nAdapters receive the full `RegenerationContext`, making it easy to scope queries per tenant/app.\n\n### Authoring rules\n\nRules focus on signals → proposals:\n\n```ts\nclass WorkflowFailureRule implements RegeneratorRule {\n  id = 'workflow-failure';\n  description = 'Suggest splitting workflows that exceed failure thresholds';\n\n  async evaluate(context, signals) {\n    const failures = signals.filter(\n      (signal) =>\n        signal.type === 'telemetry' &&\n        signal.signal.eventName === 'workflow.failure' &&\n        signal.signal.count >= 10\n    );\n\n    if (failures.length === 0) return [];\n\n    return [\n      {\n        id: `${this.id}-${context.id}`,\n        title: 'Split onboarding workflow',\n        summary: 'Step 3 fails consistently; propose dedicated remediation branch.',\n        confidence: 'medium',\n        rationale: ['Failure count ≥ 10 within last window'],\n        target: {\n          specType: 'workflow',\n          reference: { name: 'onboarding.workflow', version: 1 },\n          tenantScoped: true,\n        },\n        actions: [\n          { kind: 'update_tenant_config', summary: 'Add alternate fallback path' },\n          { kind: 'run_tests', tests: ['workflows/onboarding.spec.ts'] },\n        ],\n        signalIds: failures.map((f) => f.signal.eventName),\n        createdAt: new Date(),\n      },\n    ];\n  }\n}\n```\n\n### Reviewing proposals\n\nProposals flow to a `ProposalSink` (queue, DB, messaging bus). The Studio will surface:\n\n1. Signal evidence (telemetry counts, error metadata)\n2. Proposed spec diffs and required actions (tests/migrations)\n3. Approval workflow (approve → write spec diff → run automation)\n\n### CLI driver\n\nRun the regenerator daemon from the CLI:\n\n```bash\nbunx contracts regenerator ./app.blueprint.ts ./tenant.config.ts ./regenerator.rules.ts auto \\\n  --executor ./regenerator.executor.ts \\\n  --poll-interval 60000 \\\n  --batch-duration 300000 \\\n  --dry-run\n```\n\n- Expects modules exporting default `AppBlueprintSpec`, `TenantAppConfig`, and one or more `RegenerationRule`s.\n- Pass a sink module path, or use the special `auto` value with `--executor <module>` to instantiate an `ExecutorProposalSink`.\n- Executor modules can export a `ProposalExecutor` instance, a factory, or a plain dependency object for the executor constructor. Optional exports: `sinkOptions`, `logger`, `onResult`, `dryRun`.\n- Optionally provide `--contexts ./contexts.ts` to load custom context arrays (advanced multi-tenant scenarios).\n- Use `--dry-run` to preview actions without mutating specs/configs, and `--once` for CI smoke tests.\n\n### Proposal executor\n\n`ProposalExecutor` + `ExecutorProposalSink` orchestrate follow-up actions once a proposal is approved:\n\n- Interfaces for applying blueprint or tenant-config updates (`BlueprintUpdater`, `TenantConfigUpdater`).\n- Hooks for running contract tests and migrations (`TestExecutor`, `MigrationExecutor`).\n- Optional trigger to recompose the runtime (`RegenerationTrigger`).\n- Built-in `dryRun` mode to preview outcomes.\n- Pluggable result logging/forwarding via `ExecutorSinkOptions`.\n\n```ts\nimport {\n  ProposalExecutor,\n  ExecutorProposalSink,\n} from '@contractspec/lib.contracts/regenerator';\n\nconst executor = new ProposalExecutor({\n  tenantConfigUpdater,\n  testExecutor,\n  migrationExecutor,\n  regenerationTrigger,\n});\n\nconst sink = new ExecutorProposalSink(executor, {\n  dryRun: false,\n  onResult: ({ result }) => console.log(result.status),\n});\n```\n\nExecution results include per-action status (`success`, `skipped`, `failed`) plus aggregated proposal status (`success`, `partial`, `failed`). Missing dependencies mark actions as `skipped`, making it easy to plug into partial automation flows today and extend later.\n\n### Next steps\n\n- Build adapters for existing telemetry/error providers.\n- Encode canonical rules (workflow failure, feature under-use, high latency).\n- Integrate with App Studio proposal inbox and automate acceptance (write spec diff, run tests, queue migrations).\n\n"
+	body: "## Regenerator Service\n\nThe Regenerator daemon observes telemetry, error, and behavior streams, then suggests spec-level changes (not code patches) that can be reviewed and applied through the App Studio.\n\n- Runtime entrypoint: `packages/libs/contracts/src/regenerator/service.ts`\n- Types/interfaces: `packages/libs/contracts/src/regenerator/types.ts`\n- Signal adapters: `packages/libs/contracts/src/regenerator/adapters.ts`\n\n### Architecture\n\n```text\nSignal Adapters ──► RegeneratorService ──► Rules ──► ProposalSink\n          ▲                                       │\n          │                                       ▼\n     Telemetry / Errors / Behavior         Spec change proposals\n```\n\n1. **Signal adapters** pull batches of telemetry, error logs, or behavior metrics for each `RegenerationContext`.\n2. `RegeneratorService` schedules polling (`resolveAppConfig` + `composeAppConfig` provide context).\n3. **Rules** implement domain heuristics and emit `SpecChangeProposal` objects.\n4. **Proposal sinks** persist or forward proposals for human review.\n\n### Key types\n\n```ts\nexport interface RegenerationContext {\n  id: string;\n  blueprint: AppBlueprintSpec;\n  tenantConfig: TenantAppConfig;\n  resolved: ResolvedAppConfig;\n}\n\nexport interface RegeneratorRule {\n  id: string;\n  description: string;\n  evaluate(\n    context: RegenerationContext,\n    signals: RegeneratorSignal[]\n  ): Promise<SpecChangeProposal[]>;\n}\n\nexport interface SpecChangeProposal {\n  id: string;\n  title: string;\n  summary: string;\n  confidence: 'low' | 'medium' | 'high';\n  target: ProposalTarget;\n  actions: ProposalAction[];\n  blockers?: ProposalBlocker[];\n  signalIds: string[];\n  createdAt: Date;\n}\n```\n\n- Signals are normalized envelopes: telemetry (`count`, anomaly score), errors, and behavior trends.\n- Proposals reference blueprint or tenant specs via `ProposalTarget`.\n- Actions encode what the automation should perform (update blueprint, run tests/migrations, trigger regeneration).\n\n### Providing signals\n\nImplement `TelemetrySignalProvider`, `ErrorSignalProvider`, or `BehaviorSignalProvider`:\n\n```ts\nconst service = new RegeneratorService({\n  contexts,\n  adapters: {\n    telemetry: new PosthogTelemetryAdapter(),\n    errors: new SentryErrorAdapter(),\n  },\n  rules: [new WorkflowFailureRule(), new DataViewUsageRule()],\n  sink: new ProposalQueueSink(),\n  pollIntervalMs: 60_000,\n});\n```\n\nAdapters receive the full `RegenerationContext`, making it easy to scope queries per tenant/app.\n\n### Authoring rules\n\nRules focus on signals → proposals:\n\n```ts\nclass WorkflowFailureRule implements RegeneratorRule {\n  id = 'workflow-failure';\n  description = 'Suggest splitting workflows that exceed failure thresholds';\n\n  async evaluate(context, signals) {\n    const failures = signals.filter(\n      (signal) =>\n        signal.type === 'telemetry' &&\n        signal.signal.eventName === 'workflow.failure' &&\n        signal.signal.count >= 10\n    );\n\n    if (failures.length === 0) return [];\n\n    return [\n      {\n        id: `${this.id}-${context.id}`,\n        title: 'Split onboarding workflow',\n        summary: 'Step 3 fails consistently; propose dedicated remediation branch.',\n        confidence: 'medium',\n        rationale: ['Failure count ≥ 10 within last window'],\n        target: {\n          specType: 'workflow',\n          reference: { name: 'onboarding.workflow', version: '1.0.0' },\n          tenantScoped: true,\n        },\n        actions: [\n          { kind: 'update_tenant_config', summary: 'Add alternate fallback path' },\n          { kind: 'run_tests', tests: ['workflows/onboarding.spec.ts'] },\n        ],\n        signalIds: failures.map((f) => f.signal.eventName),\n        createdAt: new Date(),\n      },\n    ];\n  }\n}\n```\n\n### Reviewing proposals\n\nProposals flow to a `ProposalSink` (queue, DB, messaging bus). The Studio will surface:\n\n1. Signal evidence (telemetry counts, error metadata)\n2. Proposed spec diffs and required actions (tests/migrations)\n3. Approval workflow (approve → write spec diff → run automation)\n\n### CLI driver\n\nRun the regenerator daemon from the CLI:\n\n```bash\nbunx contracts regenerator ./app.blueprint.ts ./tenant.config.ts ./regenerator.rules.ts auto \\\n  --executor ./regenerator.executor.ts \\\n  --poll-interval 60000 \\\n  --batch-duration 300000 \\\n  --dry-run\n```\n\n- Expects modules exporting default `AppBlueprintSpec`, `TenantAppConfig`, and one or more `RegenerationRule`s.\n- Pass a sink module path, or use the special `auto` value with `--executor <module>` to instantiate an `ExecutorProposalSink`.\n- Executor modules can export a `ProposalExecutor` instance, a factory, or a plain dependency object for the executor constructor. Optional exports: `sinkOptions`, `logger`, `onResult`, `dryRun`.\n- Optionally provide `--contexts ./contexts.ts` to load custom context arrays (advanced multi-tenant scenarios).\n- Use `--dry-run` to preview actions without mutating specs/configs, and `--once` for CI smoke tests.\n\n### Proposal executor\n\n`ProposalExecutor` + `ExecutorProposalSink` orchestrate follow-up actions once a proposal is approved:\n\n- Interfaces for applying blueprint or tenant-config updates (`BlueprintUpdater`, `TenantConfigUpdater`).\n- Hooks for running contract tests and migrations (`TestExecutor`, `MigrationExecutor`).\n- Optional trigger to recompose the runtime (`RegenerationTrigger`).\n- Built-in `dryRun` mode to preview outcomes.\n- Pluggable result logging/forwarding via `ExecutorSinkOptions`.\n\n```ts\nimport {\n  ProposalExecutor,\n  ExecutorProposalSink,\n} from '@contractspec/lib.contracts/regenerator';\n\nconst executor = new ProposalExecutor({\n  tenantConfigUpdater,\n  testExecutor,\n  migrationExecutor,\n  regenerationTrigger,\n});\n\nconst sink = new ExecutorProposalSink(executor, {\n  dryRun: false,\n  onResult: ({ result }) => console.log(result.status),\n});\n```\n\nExecution results include per-action status (`success`, `skipped`, `failed`) plus aggregated proposal status (`success`, `partial`, `failed`). Missing dependencies mark actions as `skipped`, making it easy to plug into partial automation flows today and extend later.\n\n### Next steps\n\n- Build adapters for existing telemetry/error providers.\n- Encode canonical rules (workflow failure, feature under-use, high latency).\n- Integrate with App Studio proposal inbox and automate acceptance (write spec diff, run tests, queue migrations).\n\n"
 }];
 registerDocBlocks(tech_contracts_regenerator_DocBlocks);
 

package/dist/regenerator/types.d.ts

@@ -65,7 +65,7 @@ interface ProposalTarget {
   specType: 'workflow' | 'capability' | 'policy' | 'dataView' | 'telemetry' | 'experiment' | 'theme' | 'unknown';
   reference: {
     key: string;
-    version?: number;
+    version?: string;
   };
   tenantScoped?: boolean;
 }

package/dist/registry.d.ts

@@ -10,12 +10,13 @@ declare const keyOfSpecContract: (spec: AnySpecContract) => string;
 /** In-memory registry for PresentationSpec. */
 declare abstract class SpecContractRegistry<ContractType extends ContractSpecType, SpecContract extends AnySpecContract> {
   protected readonly contractType: ContractType;
-  private items;
+  protected items: Map<string, SpecContract>;
   protected constructor(contractType: ContractType, items?: SpecContract[]);
   register(p: SpecContract): this;
   count(): number;
   list(): SpecContract[];
-  get(key: string, version?: number): SpecContract | undefined;
+  get(key: string, version?: string): SpecContract | undefined;
+  has(key: string, version?: string): boolean;
   /** Filter presentations by criteria. */
   filter(criteria: RegistryFilter): SpecContract[];
   /** List presentations with specific tag. */

package/dist/registry.js

@@ -1,4 +1,5 @@
 import { filterBy, getUniqueTags, groupBy, init_registry_utils } from "./registry-utils.js";
+import { compareVersions } from "compare-versions";
 
 //#region src/registry.ts
 init_registry_utils();
@@ -25,16 +26,15 @@ var SpecContractRegistry = class {
 	get(key, version) {
 		if (version != null) return this.items.get(`${key}.v${version}`);
 		let candidate;
-		let max = -Infinity;
 		for (const [k, p] of this.items.entries()) {
 			if (!k.startsWith(`${key}.v`)) continue;
-			if (p.meta.version > max) {
-				max = p.meta.version;
-				candidate = p;
-			}
+			if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) candidate = p;
 		}
 		return candidate;
 	}
+	has(key, version) {
+		return !!this.get(key, version);
+	}
 	/** Filter presentations by criteria. */
 	filter(criteria) {
 		return filterBy(this.list(), criteria);

package/dist/resources.d.ts

@@ -1,5 +1,5 @@
 import { Tag } from "./ownership.js";
-import * as z$1 from "zod";
+import * as z$2 from "zod";
 
 //#region src/resources.d.ts
 interface ResourceMeta {
@@ -14,7 +14,7 @@ interface ResourceMeta {
   /** Tags for filtering/grouping */
   tags?: Tag[];
 }
-interface ResourceTemplateSpec<I extends z$1.ZodType> {
+interface ResourceTemplateSpec<I extends z$2.ZodType> {
   meta: ResourceMeta;
   /** Arguments to materialize the URI (zod validates input) */
   input: I;
@@ -22,7 +22,7 @@ interface ResourceTemplateSpec<I extends z$1.ZodType> {
    * Resolve returns the resource body and a resolved URI.
    * It MUST be read-only (no side effects).
    */
-  resolve: (args: z$1.infer<I>, ctx: {
+  resolve: (args: z$2.infer<I>, ctx: {
     userId?: string | null;
     orgId?: string | null;
     locale?: string;
@@ -32,10 +32,10 @@ interface ResourceTemplateSpec<I extends z$1.ZodType> {
     data: Uint8Array | string;
   }>;
 }
-declare function defineResourceTemplate<I extends z$1.ZodType>(spec: ResourceTemplateSpec<I>): ResourceTemplateSpec<I>;
+declare function defineResourceTemplate<I extends z$2.ZodType>(spec: ResourceTemplateSpec<I>): ResourceTemplateSpec<I>;
 declare class ResourceRegistry {
   private templates;
-  register<I extends z$1.ZodType>(tmpl: ResourceTemplateSpec<I>): this;
+  register<I extends z$2.ZodType>(tmpl: ResourceTemplateSpec<I>): this;
   listTemplates(): ResourceTemplateSpec<any>[];
   /** Try to match a concrete URI to a template by naive pattern substitution */
   match(uri: string): {

package/dist/server/graphql-pothos.js

@@ -29,7 +29,7 @@ import "@pothos/plugin-tracing";
 function registerContractsOnBuilder(builder, reg, resources) {
 	const { buildInputFieldArgs } = createInputTypeBuilder(builder);
 	const outputTypeCache = /* @__PURE__ */ new Map();
-	for (const spec of reg.listSpecs()) {
+	for (const spec of reg.list()) {
 		const out = spec.io.output;
 		if (out && "getZod" in out && typeof out.getZod === "function") {
 			const model = out;
@@ -77,7 +77,7 @@ function registerContractsOnBuilder(builder, reg, resources) {
 		}
 		return "JSON";
 	}
-	for (const spec of reg.listSpecs()) {
+	for (const spec of reg.list()) {
 		const fieldName = spec.transport?.gql?.field ?? defaultGqlField(spec.meta.key, spec.meta.version);
 		const byIdField = spec.transport?.gql?.byIdField ?? "id";
 		const returnsResource = spec.transport?.gql?.resource;

package/dist/server/mcp/registerTools.js

@@ -2,7 +2,7 @@ import { defaultMcpTool } from "../../jsonschema.js";
 
 //#region src/server/mcp/registerTools.ts
 function registerMcpTools(server, ops, ctx) {
-	for (const spec of ops.listSpecs()) {
+	for (const spec of ops.list()) {
 		if (spec.meta.kind !== "command") continue;
 		const toolName = spec.transport?.mcp?.toolName ?? defaultMcpTool(spec.meta.key, spec.meta.version);
 		server.registerTool(toolName, {

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

@@ -1,5 +1,5 @@
-import { HandlerCtx } from "../types.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
 import { RestOptions } from "./rest-generic.js";
 import { Elysia } from "elysia";
 

package/dist/server/rest-elysia.js

@@ -7,7 +7,7 @@ function elysiaPlugin(app, reg, ctxFactory, options) {
 		request: req,
 		store: app.store
 	}), options);
-	for (const spec of reg.listSpecs()) {
+	for (const spec of reg.list()) {
 		const method = spec.transport?.rest?.method ?? (spec.meta.kind === "query" ? "GET" : "POST");
 		const path = (options?.basePath ?? "") + (spec.transport?.rest?.path ?? `/${spec.meta.key.replace(/\./g, "/")}/v${spec.meta.version}`);
 		app[method.toLowerCase()](path, ({ request }) => handler(request));

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

@@ -1,5 +1,5 @@
-import { HandlerCtx } from "../types.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
 import { RestOptions } from "./rest-generic.js";
 import { Request, Router } from "express";
 

package/dist/server/rest-express.js

@@ -7,7 +7,7 @@ import { createFetchHandler } from "./rest-generic.js";
 */
 function expressRouter(express, reg, ctxFactory, options) {
 	const router = express.Router();
-	for (const spec of reg.listSpecs()) {
+	for (const spec of reg.list()) {
 		const method = spec.transport?.rest?.method ?? (spec.meta.kind === "query" ? "GET" : "POST");
 		const path = (options?.basePath ?? "") + (spec.transport?.rest?.path ?? `/${spec.meta.key.replace(/\./g, "/")}/v${spec.meta.version}`);
 		router[method.toLowerCase()](path, async (req, res) => {

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

@@ -1,5 +1,5 @@
-import { HandlerCtx } from "../types.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
 
 //#region src/server/rest-generic.d.ts
 interface RestOptions {

package/dist/server/rest-generic.js

@@ -33,7 +33,7 @@ function createFetchHandler(reg, ctxFactory, options) {
 		prettyJson: options?.prettyJson ?? false,
 		onError: options?.onError
 	};
-	const routes = reg.listSpecs().map((spec) => ({
+	const routes = reg.list().map((spec) => ({
 		method: spec.transport?.rest?.method ?? (spec.meta.kind === "query" ? "GET" : "POST"),
 		path: joinPath(opts.basePath, spec.transport?.rest?.path ?? defaultRestPath(spec.meta.key, spec.meta.version)),
 		name: spec.meta.key,

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

@@ -1,5 +1,5 @@
-import { HandlerCtx } from "../types.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
 import { RestOptions } from "./rest-generic.js";
 
 //#region src/server/rest-next-app.d.ts

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

@@ -1,5 +1,5 @@
-import { HandlerCtx } from "../types.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
 
 //#region src/server/rest-next-mcp.d.ts
 declare function makeNextMcpServerFromRegistry(reg: OperationSpecRegistry, ctxFactory: () => HandlerCtx): {

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

@@ -5,7 +5,7 @@ import { createMcpHandler } from "mcp-handler";
 //#region src/server/rest-next-mcp.ts
 function makeNextMcpServerFromRegistry(reg, ctxFactory) {
 	const handler = createMcpHandler((server) => {
-		for (const spec of reg.listSpecs()) {
+		for (const spec of reg.list()) {
 			const { input, meta } = jsonSchemaForSpec(spec);
 			if (meta.kind === "query") {
 				const resourceName = spec.transport?.mcp?.toolName ?? defaultMcpTool(spec.meta.key, spec.meta.version);

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

@@ -1,5 +1,5 @@
-import { HandlerCtx } from "../types.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
 import { RestOptions } from "./rest-generic.js";
 import { NextApiRequest, NextApiResponse } from "next";
 

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

@@ -13,7 +13,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- `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"
+	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);
 

package/dist/telemetry/spec.d.ts

@@ -1,4 +1,5 @@
 import { OwnerShipMeta } from "../ownership.js";
+import { SpecContractRegistry } from "../registry.js";
 
 //#region src/telemetry/spec.d.ts
 type TelemetryPrivacyLevel = 'public' | 'internal' | 'pii' | 'sensitive';
@@ -38,7 +39,7 @@ interface TelemetryEventDef {
   /** Name of the event (should match EventSpec.key for cross-reference). */
   key: string;
   /** Version of the underlying event. */
-  version: number;
+  version: string;
   /** High-level semantics for docs/analyzers. */
   semantics: {
     who?: string;
@@ -76,15 +77,14 @@ interface TelemetrySpec {
   events: TelemetryEventDef[];
   config?: TelemetryConfig;
 }
-declare class TelemetryRegistry {
-  private readonly items;
+declare class TelemetryRegistry extends SpecContractRegistry<'telemetry', TelemetrySpec> {
   private readonly eventsByKey;
   private readonly specByEventKey;
+  constructor(items?: TelemetrySpec[]);
   register(spec: TelemetrySpec): this;
-  list(): TelemetrySpec[];
-  get(key: string, version?: number): TelemetrySpec | undefined;
-  findEventDef(name: string, version?: number): TelemetryEventDef | undefined;
-  getSpecForEvent(name: string, version?: number): TelemetrySpec | undefined;
+  private indexEvents;
+  findEventDef(name: string, version?: string): TelemetryEventDef | undefined;
+  getSpecForEvent(name: string, version: string): TelemetrySpec | undefined;
 }
 declare function makeTelemetryKey(meta: TelemetryMeta): string;
 //#endregion

package/dist/telemetry/spec.js

@@ -1,64 +1,37 @@
+import { SpecContractRegistry } from "../registry.js";
+import { compareVersions } from "compare-versions";
+
 //#region src/telemetry/spec.ts
 const telemetryKey = (meta) => `${meta.key}.v${meta.version}`;
-var TelemetryRegistry = class {
-	items = /* @__PURE__ */ new Map();
+var TelemetryRegistry = class extends SpecContractRegistry {
 	eventsByKey = /* @__PURE__ */ new Map();
 	specByEventKey = /* @__PURE__ */ new Map();
+	constructor(items) {
+		super("telemetry", items);
+		if (items) items.forEach((spec) => this.indexEvents(spec));
+	}
 	register(spec) {
-		const key = telemetryKey(spec.meta);
-		if (this.items.has(key)) throw new Error(`Duplicate TelemetrySpec registration for ${key}`);
-		this.items.set(key, 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);
 		}
-		return this;
-	}
-	list() {
-		return [...this.items.values()];
-	}
-	get(key, version) {
-		if (version != null) return this.items.get(`${key}.v${version}`);
-		let latest;
-		let maxVersion = -Infinity;
-		for (const item of this.items.values()) {
-			if (item.meta.key !== key) continue;
-			if (item.meta.version > maxVersion) {
-				maxVersion = item.meta.version;
-				latest = item;
-			}
-		}
-		return latest;
 	}
 	findEventDef(name, version) {
 		if (version != null) return this.eventsByKey.get(`${name}.v${version}`);
 		let latest;
-		let maxVersion = -Infinity;
-		for (const [key, event] of this.eventsByKey.entries()) {
-			const [eventName, versionPart] = key.split(".v");
-			if (eventName !== name) continue;
-			const ver = Number(versionPart);
-			if (Number.isFinite(ver) && ver > maxVersion) {
-				maxVersion = ver;
-				latest = event;
-			}
+		for (const event of this.eventsByKey.values()) {
+			if (event.key !== name) continue;
+			if (!latest || compareVersions(event.version, latest.version) > 0) latest = event;
 		}
 		return latest;
 	}
 	getSpecForEvent(name, version) {
-		if (version != null) return this.specByEventKey.get(`${name}.v${version}`);
-		let latest;
-		let maxVersion = -Infinity;
-		for (const [key, spec] of this.specByEventKey.entries()) {
-			const [eventName, versionPart] = key.split(".v");
-			if (eventName !== name) continue;
-			const ver = Number(versionPart);
-			if (Number.isFinite(ver) && ver > maxVersion) {
-				maxVersion = ver;
-				latest = spec;
-			}
-		}
-		return latest;
+		return this.specByEventKey.get(`${name}.v${version}`);
 	}
 };
 function makeTelemetryKey(meta) {

package/dist/telemetry/tracker.d.ts

@@ -14,7 +14,7 @@ interface TelemetryEventContext {
 interface TelemetryDispatch {
   id: string;
   name: string;
-  version: number;
+  version: string;
   occurredAt: string;
   properties: Record<string, unknown>;
   privacy: TelemetryEventDef['privacy'];
@@ -43,7 +43,7 @@ declare class TelemetryTracker {
   constructor(options: TelemetryTrackerOptions);
   registerProvider(provider: RuntimeTelemetryProvider): void;
   unregisterProvider(providerId: string): void;
-  track(name: string, version: number, properties: Record<string, unknown>, context?: TelemetryEventContext): Promise<boolean>;
+  track(name: string, version: string, properties: Record<string, unknown>, context?: TelemetryEventContext): Promise<boolean>;
   private shouldSample;
   private redactProperties;
 }

package/dist/tests/runner.d.ts

@@ -1,6 +1,6 @@
-import { HandlerCtx } from "../types.js";
 import { Assertion, TestScenario, TestSpec } from "./spec.js";
 import { OperationSpecRegistry } from "../operations/registry.js";
+import { HandlerCtx } from "../types.js";
 import "../index.js";
 
 //#region src/tests/runner.d.ts

package/dist/tests/spec.d.ts

@@ -3,11 +3,11 @@ import { OwnerShipMeta } from "../ownership.js";
 //#region src/tests/spec.d.ts
 interface OperationTargetRef {
   key: string;
-  version?: number;
+  version?: string;
 }
 interface WorkflowTargetRef {
   key: string;
-  version?: number;
+  version?: string;
 }
 type TestTarget = {
   type: 'operation';
@@ -35,7 +35,7 @@ interface ExpectErrorAssertion {
 }
 interface ExpectedEvent {
   key: string;
-  version: number;
+  version: string;
   min?: number;
   max?: number;
 }
@@ -68,13 +68,13 @@ interface TestSpec {
 }
 interface TestSpecRef {
   key: string;
-  version?: number;
+  version?: string;
 }
 declare class TestRegistry {
   private readonly items;
   register(spec: TestSpec): this;
   list(): TestSpec[];
-  get(name: string, version?: number): TestSpec | undefined;
+  get(name: string, version?: string): TestSpec | undefined;
 }
 declare function makeTestKey(meta: TestSpecMeta): string;
 //#endregion

package/dist/tests/spec.js

@@ -1,3 +1,5 @@
+import { compareVersions } from "compare-versions";
+
 //#region src/tests/spec.ts
 const testKey = (meta) => `${meta.key}.v${meta.version}`;
 var TestRegistry = class {
@@ -14,13 +16,9 @@ var TestRegistry = class {
 	get(name, version) {
 		if (version != null) return this.items.get(`${name}.v${version}`);
 		let latest;
-		let maxVersion = -Infinity;
 		for (const spec of this.items.values()) {
 			if (spec.meta.key !== name) continue;
-			if (spec.meta.version > maxVersion) {
-				maxVersion = spec.meta.version;
-				latest = spec;
-			}
+			if (!latest || compareVersions(spec.meta.version, latest.meta.version) > 0) latest = spec;
 		}
 		return latest;
 	}