@contractspec/lib.contracts 1.44.0

package/dist/presentations/presentations.d.ts

@@ -0,0 +1,50 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { AnySchemaModel } from "@contractspec/lib.schema";
+import { BlockConfig } from "@blocknote/core";
+
+//#region src/presentations/presentations.d.ts
+/** Supported render targets for the transform engine and descriptors. */
+type PresentationTarget = 'react' | 'markdown' | 'application/json' | 'application/xml';
+interface PresentationSpecMeta extends OwnerShipMeta {
+  /** Business goal: why this exists */
+  goal: string;
+  /** Background, constraints, scope edges (feeds docs & LLM context) */
+  context: string;
+}
+/** React component presentation source. */
+interface PresentationSourceComponentReact {
+  /** Source marker for React component presentations. */
+  type: 'component';
+  /** Framework for the component source (currently only 'react'). */
+  framework: 'react';
+  /** Component key resolved by host `componentMap`. */
+  componentKey: string;
+  /** Optional props schema to validate against. */
+  props?: AnySchemaModel;
+}
+/** BlockNoteJS document presentation source. */
+interface PresentationSourceBlocknotejs {
+  /** Source marker for BlockNoteJS document presentations. */
+  type: 'blocknotejs';
+  /** BlockNoteJS JSON document. */
+  docJson: unknown;
+  /** Optional BlockNote config to guide rendering. */
+  blockConfig?: BlockConfig;
+}
+type PresentationSource = PresentationSourceComponentReact | PresentationSourceBlocknotejs;
+/**
+ * Normalized presentation spec decoupled from framework/adapters.
+ * Renderers and validators are provided via TransformEngine.
+ */
+interface PresentationSpec {
+  meta: PresentationSpecMeta;
+  policy?: {
+    flags?: string[];
+    pii?: string[];
+  };
+  source: PresentationSource;
+  targets: PresentationTarget[];
+}
+declare const definePresentation: (spec: PresentationSpec) => PresentationSpec;
+//#endregion
+export { PresentationSource, PresentationSourceBlocknotejs, PresentationSourceComponentReact, PresentationSpec, PresentationSpecMeta, PresentationTarget, definePresentation };

package/dist/presentations/presentations.js

@@ -0,0 +1,7 @@
+//#region src/presentations/presentations.ts
+const definePresentation = (spec) => {
+	return spec;
+};
+
+//#endregion
+export { definePresentation };

package/dist/presentations/registry.d.ts

@@ -0,0 +1,10 @@
+import { PresentationSpec } from "./presentations.js";
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/presentations/registry.d.ts
+/** In-memory registry for PresentationSpec. */
+declare class PresentationRegistry extends SpecContractRegistry<'presentation', PresentationSpec> {
+  constructor(items?: PresentationSpec[]);
+}
+//#endregion
+export { PresentationRegistry };

package/dist/presentations/registry.js

@@ -0,0 +1,12 @@
+import { SpecContractRegistry } from "../registry.js";
+
+//#region src/presentations/registry.ts
+/** In-memory registry for PresentationSpec. */
+var PresentationRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("presentation", items);
+	}
+};
+
+//#endregion
+export { PresentationRegistry };

package/dist/presentations/transform-engine.d.ts

@@ -0,0 +1,66 @@
+import { PresentationSpec, PresentationTarget } from "./presentations.js";
+import React from "react";
+import { BlockConfig } from "@blocknote/core";
+
+//#region src/presentations/transform-engine.d.ts
+interface RenderContext {
+  /** Optional locale hint (i18n). */
+  locale?: string;
+  /** Enabled feature flags to drive conditional rendering. */
+  featureFlags?: string[];
+  /** Redaction hook for custom PII handling. */
+  redact?: (path: string, value: unknown) => unknown;
+  /** Optional data for schema-driven rendering (arrays or objects). */
+  data?: unknown;
+  /** Optional async data fetcher for renderers that need to load data on demand. */
+  fetchData?: () => Promise<unknown>;
+}
+interface PresentationRenderer<TOut> {
+  target: PresentationTarget;
+  render: (desc: PresentationSpec, ctx?: RenderContext) => Promise<TOut>;
+}
+interface PresentationValidator {
+  validate: (desc: PresentationSpec, target: PresentationTarget, ctx?: RenderContext) => Promise<void> | void;
+}
+declare class TransformEngine {
+  private renderers;
+  private validators;
+  register<TOut>(renderer: PresentationRenderer<TOut>): this;
+  /**
+   * Register a renderer that will be tried BEFORE existing renderers for the same target.
+   * Useful for custom renderers that should take priority over default ones.
+   */
+  prependRegister<TOut>(renderer: PresentationRenderer<TOut>): this;
+  addValidator(v: PresentationValidator): this;
+  render<TOut = unknown>(target: PresentationTarget, desc: PresentationSpec, ctx?: RenderContext): Promise<TOut>;
+}
+/** Create a TransformEngine instance with default markdown/json/xml renderers. */
+declare function createDefaultTransformEngine(): TransformEngine;
+/** Serializable render descriptor for React hosts. */
+type ReactRenderDescriptor = {
+  kind: 'react_component';
+  componentKey: string;
+  props?: Record<string, unknown>;
+} | {
+  kind: 'blocknotejs';
+  docJson: unknown;
+  blockConfig?: BlockConfig;
+};
+/** Register a default React target renderer that returns a serializable descriptor. */
+declare function registerDefaultReactRenderer(engine: TransformEngine): TransformEngine;
+/**
+ * Add basic validators (e.g., meta.description presence) to the engine.
+ */
+declare function registerBasicValidation(engine: TransformEngine): TransformEngine;
+/**
+ * Component map type for React rendering.
+ */
+type ComponentMap = Record<string, React.ComponentType<any>>;
+/**
+ * Register a React-to-markdown renderer that renders React components to HTML
+ * and converts them to markdown using turndown.
+ * This renderer takes priority over the default metadata-only renderer.
+ */
+declare function registerReactToMarkdownRenderer(engine: TransformEngine, componentMap: ComponentMap): TransformEngine;
+//#endregion
+export { ComponentMap, PresentationRenderer, PresentationValidator, ReactRenderDescriptor, RenderContext, TransformEngine, createDefaultTransformEngine, registerBasicValidation, registerDefaultReactRenderer, registerReactToMarkdownRenderer };

package/dist/presentations/transform-engine.js

@@ -0,0 +1,282 @@
+import { schemaToMarkdown } from "../schema-to-markdown.js";
+import React from "react";
+import TurndownService from "turndown";
+
+//#region src/presentations/transform-engine.ts
+/**
+* Pluggable transform engine that renders descriptors to various targets
+* and runs validators (e.g., basic metadata checks, PII redaction policies).
+*/
+const turndown = new TurndownService();
+function renderTextNode(node) {
+	const text = node.text ?? "";
+	if (!node.marks || node.marks.length === 0) return text;
+	return node.marks.reduce((acc, mark) => {
+		switch (mark.type) {
+			case "bold": return `**${acc}**`;
+			case "italic": return `*${acc}*`;
+			case "underline": return `__${acc}__`;
+			case "strike": return `~~${acc}~~`;
+			case "code": return `\`${acc}\``;
+			case "link": {
+				const href = mark.attrs?.href ?? "";
+				return href ? `[${acc}](${href})` : acc;
+			}
+			default: return acc;
+		}
+	}, text);
+}
+function renderInline(nodes) {
+	if (!nodes?.length) return "";
+	return nodes.map((child) => renderNode(child)).join("");
+}
+function renderList(nodes, ordered = false) {
+	if (!nodes?.length) return "";
+	let counter = 1;
+	return nodes.map((item) => {
+		const body = renderInline(item.content ?? []);
+		if (!body) return "";
+		return `${ordered ? `${counter++}. ` : "- "}${body}`;
+	}).filter(Boolean).join("\n");
+}
+function renderNode(node) {
+	switch (node.type) {
+		case "doc": return renderInline(node.content);
+		case "paragraph": {
+			const text = renderInline(node.content);
+			return text.trim().length ? text : "";
+		}
+		case "heading": {
+			const levelAttr = node.attrs?.level;
+			const levelVal = typeof levelAttr === "number" ? levelAttr : 1;
+			const level = Math.min(Math.max(levelVal, 1), 6);
+			return `${"#".repeat(level)} ${renderInline(node.content)}`.trim();
+		}
+		case "bullet_list": return renderList(node.content, false);
+		case "ordered_list": return renderList(node.content, true);
+		case "list_item": return renderInline(node.content);
+		case "blockquote": return renderInline(node.content).split("\n").map((line) => `> ${line}`).join("\n");
+		case "code_block": {
+			const body = renderInline(node.content);
+			return body ? `\`\`\`\n${body}\n\`\`\`` : "";
+		}
+		case "horizontal_rule": return "---";
+		case "hard_break": return "\n";
+		case "text": return renderTextNode(node);
+		default:
+			if (node.text) return renderTextNode(node);
+			return "";
+	}
+}
+function blockNoteToMarkdown(docJson) {
+	if (typeof docJson === "string") return docJson;
+	if (docJson && typeof docJson === "object" && "html" in docJson) {
+		const html = String(docJson.html);
+		return turndown.turndown(html);
+	}
+	const root = docJson;
+	if (root?.type === "doc" || root?.content) return (root.content ?? []).map((n) => renderNode(n)).filter(Boolean).join("\n\n").trim();
+	try {
+		return JSON.stringify(docJson, null, 2);
+	} catch {
+		return String(docJson);
+	}
+}
+var TransformEngine = class {
+	renderers = /* @__PURE__ */ new Map();
+	validators = [];
+	register(renderer) {
+		const arr = this.renderers.get(renderer.target) ?? [];
+		arr.push(renderer);
+		this.renderers.set(renderer.target, arr);
+		return this;
+	}
+	/**
+	* Register a renderer that will be tried BEFORE existing renderers for the same target.
+	* Useful for custom renderers that should take priority over default ones.
+	*/
+	prependRegister(renderer) {
+		const arr = this.renderers.get(renderer.target) ?? [];
+		arr.unshift(renderer);
+		this.renderers.set(renderer.target, arr);
+		return this;
+	}
+	addValidator(v) {
+		this.validators.push(v);
+		return this;
+	}
+	async render(target, desc, ctx) {
+		if (!desc.targets.includes(target)) throw new Error(`Target ${target} not declared for ${desc.meta.key}.v${desc.meta.version}`);
+		for (const v of this.validators) await v.validate(desc, target, ctx);
+		const arr = this.renderers.get(target) ?? [];
+		for (const r of arr) try {
+			return await r.render(desc, ctx);
+		} catch (_e) {}
+		throw new Error(`No renderer available for ${target}`);
+	}
+};
+/** Create a TransformEngine instance with default markdown/json/xml renderers. */
+function createDefaultTransformEngine() {
+	const engine = new TransformEngine();
+	const applyPii = (desc, obj) => {
+		const clone = JSON.parse(JSON.stringify(obj));
+		const paths = desc.policy?.pii ?? [];
+		const setAtPath = (root, path) => {
+			const segs = path.replace(/^\//, "").replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+			let cur = root;
+			for (let i = 0; i < segs.length - 1; i++) {
+				const k = segs[i];
+				if (!k) continue;
+				if (cur && typeof cur === "object" && k in cur) cur = cur[k];
+				else return;
+			}
+			const last = segs[segs.length - 1];
+			if (cur && typeof cur === "object" && last && last in cur) cur[last] = "[REDACTED]";
+		};
+		for (const p of paths) setAtPath(clone, p);
+		return clone;
+	};
+	engine.register({
+		target: "markdown",
+		async render(desc, ctx) {
+			let data = ctx?.data;
+			if (!data && ctx?.fetchData) data = await ctx.fetchData();
+			if (desc.source.type === "component" && desc.source.props && data !== void 0) {
+				const isArray = Array.isArray(data);
+				const isSimpleObject = !isArray && typeof data === "object" && data !== null && !Object.values(data).some((v) => Array.isArray(v) || typeof v === "object" && v !== null);
+				if (isArray || isSimpleObject) return {
+					mimeType: "text/markdown",
+					body: schemaToMarkdown(desc.source.props, data, {
+						title: desc.meta.description ?? desc.meta.key,
+						description: `${desc.meta.key} v${desc.meta.version}`
+					})
+				};
+				throw new Error(`Complex data structure for ${desc.meta.key} - expecting custom renderer`);
+			}
+			if (desc.source.type === "blocknotejs") {
+				const redacted = applyPii(desc, { text: blockNoteToMarkdown(desc.source.docJson) });
+				return {
+					mimeType: "text/markdown",
+					body: String(redacted.text)
+				};
+			}
+			if (desc.source.type === "component" && data !== void 0) throw new Error(`No schema (source.props) available for ${desc.meta.key} - expecting custom renderer`);
+			if (desc.source.type === "component") return {
+				mimeType: "text/markdown",
+				body: `${`# ${desc.meta.key} v${desc.meta.version}`}${desc.meta.description ? `\n\n${desc.meta.description}` : ""}${desc.meta.tags && desc.meta.tags.length ? `\n\nTags: ${desc.meta.tags.join(", ")}` : ""}${desc.meta.owners && desc.meta.owners.length ? `\n\nOwners: ${desc.meta.owners.join(", ")}` : ""}${`\n\nComponent: \`${desc.source.componentKey}\``}${desc.policy?.pii?.length ? `\n\nRedacted paths: ${desc.policy.pii.map((p) => `\`${p}\``).join(", ")}` : ""}`
+			};
+			throw new Error("unsupported");
+		}
+	});
+	engine.register({
+		target: "application/json",
+		async render(desc) {
+			const payload = applyPii(desc, {
+				meta: desc.meta,
+				source: desc.source
+			});
+			return {
+				mimeType: "application/json",
+				body: JSON.stringify(payload, null, 2)
+			};
+		}
+	});
+	engine.register({
+		target: "application/xml",
+		async render(desc) {
+			const json = applyPii(desc, {
+				meta: desc.meta,
+				source: desc.source
+			});
+			return {
+				mimeType: "application/xml",
+				body: `<presentation name="${desc.meta.key}" version="${desc.meta.version}"><json>${encodeURIComponent(JSON.stringify(json))}</json></presentation>`
+			};
+		}
+	});
+	return engine;
+}
+/** Register a default React target renderer that returns a serializable descriptor. */
+function registerDefaultReactRenderer(engine) {
+	engine.register({
+		target: "react",
+		async render(desc) {
+			if (desc.source.type === "component") {
+				const props = desc.source.props ? desc.source.props.getZod().safeParse({}).success ? {} : void 0 : void 0;
+				return {
+					kind: "react_component",
+					componentKey: desc.source.componentKey,
+					props
+				};
+			}
+			return {
+				kind: "blocknotejs",
+				docJson: desc.source.docJson,
+				blockConfig: desc.source.blockConfig
+			};
+		}
+	});
+	return engine;
+}
+/**
+* Add basic validators (e.g., meta.description presence) to the engine.
+*/
+function registerBasicValidation(engine) {
+	engine.addValidator({ validate(desc) {
+		if (!desc.meta.description || desc.meta.description.length < 3) throw new Error(`Presentation ${desc.meta.key}.v${desc.meta.version} missing meta.description`);
+	} });
+	return engine;
+}
+/**
+* Register a React-to-markdown renderer that renders React components to HTML
+* and converts them to markdown using turndown.
+* This renderer takes priority over the default metadata-only renderer.
+*/
+function registerReactToMarkdownRenderer(engine, componentMap) {
+	const turndownService = new TurndownService({
+		headingStyle: "atx",
+		codeBlockStyle: "fenced",
+		bulletListMarker: "-"
+	});
+	turndownService.addRule("link", {
+		filter: "a",
+		replacement: (content, node) => {
+			const href = node.href;
+			if (href && content) return `[${content}](${href})`;
+			return content || "";
+		}
+	});
+	engine.prependRegister({
+		target: "markdown",
+		async render(desc, _ctx) {
+			if (desc.source.type !== "component") throw new Error("React-to-markdown renderer only handles component presentations");
+			const { renderToStaticMarkup } = await import("react-dom/server");
+			const Component = componentMap[desc.source.componentKey];
+			if (!Component) throw new Error(`Component ${desc.source.componentKey} not found in componentMap`);
+			let html;
+			try {
+				html = renderToStaticMarkup(React.createElement(Component, desc.source.props ? {} : void 0));
+			} catch (error) {
+				throw new Error(`Failed to render component ${desc.source.componentKey}: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
+			let markdown;
+			try {
+				markdown = turndownService.turndown(html);
+			} catch (error) {
+				throw new Error(`Failed to convert HTML to markdown: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
+			if (desc.policy?.pii && desc.policy.pii.length > 0) return {
+				mimeType: "text/markdown",
+				body: markdown.replace(/\[REDACTED\]/g, "[REDACTED]")
+			};
+			return {
+				mimeType: "text/markdown",
+				body: markdown
+			};
+		}
+	});
+	return engine;
+}
+
+//#endregion
+export { TransformEngine, createDefaultTransformEngine, registerBasicValidation, registerDefaultReactRenderer, registerReactToMarkdownRenderer };

package/dist/prompt.d.ts

@@ -0,0 +1,60 @@
+import * as z$1 from "zod";
+
+//#region src/prompt.d.ts
+type PromptStability = 'experimental' | 'beta' | 'stable' | 'deprecated';
+/** Parameter definition for a prompt argument. */
+interface PromptArg {
+  name: string;
+  description?: string;
+  required?: boolean;
+  schema: z$1.ZodType;
+  completeWith?: string;
+}
+/**
+ * Rendered content part for a prompt. Clients (MCP) can fetch referenced resources.
+ */
+type PromptContentPart = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'resource';
+  uri: string;
+  title?: string;
+};
+/** Prompt metadata for discoverability and governance. */
+interface PromptMeta {
+  key: string;
+  version: number;
+  title: string;
+  description: string;
+  tags?: string[];
+  stability?: PromptStability;
+  owners?: string[];
+}
+/** Policy constraints for prompts (flags, PII paths, rate limits). */
+interface PromptPolicy {
+  flags?: string[];
+  pii?: string[];
+  rateLimit?: {
+    rpm: number;
+    key: 'user' | 'org' | 'global';
+  };
+}
+/** Full prompt specification including args schema and render function. */
+interface PromptSpec<I extends z$1.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: {
+    userId?: string | null;
+    orgId?: string | null;
+    locale?: string;
+    link: (template: string, vars: Record<string, string | number>) => string;
+  }) => Promise<PromptContentPart[]>;
+}
+/** Identity helper that preserves generic inference when declaring prompts. */
+declare function definePrompt<I extends z$1.ZodType>(spec: PromptSpec<I>): PromptSpec<I>;
+//#endregion
+export { PromptArg, PromptContentPart, PromptMeta, PromptPolicy, PromptSpec, PromptStability, definePrompt };

package/dist/prompt.js

@@ -0,0 +1,10 @@
+import "zod";
+
+//#region src/prompt.ts
+/** Identity helper that preserves generic inference when declaring prompts. */
+function definePrompt(spec) {
+	return spec;
+}
+
+//#endregion
+export { definePrompt };

package/dist/promptRegistry.d.ts

@@ -0,0 +1,15 @@
+import { PromptSpec } from "./prompt.js";
+import * as z$1 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;
+  /** List all registered prompts. */
+  list(): PromptSpec<z$1.ZodType<unknown, unknown, z$1.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;
+}
+//#endregion
+export { PromptRegistry };

package/dist/promptRegistry.js

@@ -0,0 +1,34 @@
+import "zod";
+
+//#region src/promptRegistry.ts
+var PromptRegistry = class {
+	prompts = /* @__PURE__ */ new Map();
+	/** Register a prompt. Throws on duplicate name+version. */
+	register(p) {
+		const key = `${p.meta.key}-v${p.meta.version}`;
+		if (this.prompts.has(key)) throw new Error(`Duplicate prompt ${key}`);
+		this.prompts.set(key, p);
+		return this;
+	}
+	/** List all registered prompts. */
+	list() {
+		return [...this.prompts.values()];
+	}
+	/** Get prompt by name; when version omitted, returns highest version. */
+	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;
+			}
+		}
+		return candidate;
+	}
+};
+
+//#endregion
+export { PromptRegistry };

package/dist/regenerator/adapters.d.ts

@@ -0,0 +1,19 @@
+import { BehaviorSignal, ErrorSignal, RegenerationContext, TelemetrySignal } from "./types.js";
+
+//#region src/regenerator/adapters.d.ts
+interface TelemetrySignalProvider {
+  pollTelemetry(context: RegenerationContext, since: Date, until: Date): Promise<TelemetrySignal[]>;
+}
+interface ErrorSignalProvider {
+  pollErrors(context: RegenerationContext, since: Date, until: Date): Promise<ErrorSignal[]>;
+}
+interface BehaviorSignalProvider {
+  pollBehavior(context: RegenerationContext, since: Date, until: Date): Promise<BehaviorSignal[]>;
+}
+interface SignalAdapters {
+  telemetry?: TelemetrySignalProvider;
+  errors?: ErrorSignalProvider;
+  behavior?: BehaviorSignalProvider;
+}
+//#endregion
+export { BehaviorSignalProvider, ErrorSignalProvider, SignalAdapters, TelemetrySignalProvider };

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

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

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

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../docs/registry.js";
+
+//#region src/regenerator/docs/regenerator.docblock.ts
+const tech_contracts_regenerator_DocBlocks = [{
+	id: "docs.tech.contracts.regenerator",
+	title: "Regenerator Service",
+	summary: "The 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.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/regenerator",
+	tags: [
+		"tech",
+		"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"
+}];
+registerDocBlocks(tech_contracts_regenerator_DocBlocks);
+
+//#endregion
+export { tech_contracts_regenerator_DocBlocks };