@lssm/lib.contracts 0.0.0-canary-20251217062943 → 0.0.0-canary-20251217072406

package/dist/presentations.v2.js

@@ -1,7 +1,279 @@
-import{schemaToMarkdown as e}from"./schema-to-markdown.js";import t from"react";import n from"turndown";const r=new n;function i(e){let t=e.text??``;return!e.marks||e.marks.length===0?t:e.marks.reduce((e,t)=>{switch(t.type){case`bold`:return`**${e}**`;case`italic`:return`*${e}*`;case`underline`:return`__${e}__`;case`strike`:return`~~${e}~~`;case`code`:return`\`${e}\``;case`link`:{let n=t.attrs?.href??``;return n?`[${e}](${n})`:e}default:return e}},t)}function a(e){return e?.length?e.map(e=>s(e)).join(``):``}function o(e,t=!1){if(!e?.length)return``;let n=1;return e.map(e=>{let r=a(e.content??[]);return r?`${t?`${n++}. `:`- `}${r}`:``}).filter(Boolean).join(`
-`)}function s(e){switch(e.type){case`doc`:return a(e.content);case`paragraph`:{let t=a(e.content);return t.trim().length?t:``}case`heading`:{let t=Math.min(Math.max(e.attrs?.level??1,1),6);return`${`#`.repeat(t)} ${a(e.content)}`.trim()}case`bullet_list`:return o(e.content,!1);case`ordered_list`:return o(e.content,!0);case`list_item`:return a(e.content);case`blockquote`:return a(e.content).split(`
-`).map(e=>`> ${e}`).join(`
-`);case`code_block`:{let t=a(e.content);return t?`\`\`\`\n${t}\n\`\`\``:``}case`horizontal_rule`:return`---`;case`hard_break`:return`
-`;case`text`:return i(e);default:return e.text?i(e):``}}function c(e){if(typeof e==`string`)return e;if(e&&typeof e==`object`&&`html`in e){let t=String(e.html);return r.turndown(t)}let t=e;if(t?.type===`doc`||t?.content)return(t.content??[]).map(e=>s(e)).filter(Boolean).join(`
+import { schemaToMarkdown } from "./schema-to-markdown.js";
+import React from "react";
+import TurndownService from "turndown";
 
-`).trim();try{return JSON.stringify(e,null,2)}catch{return String(e)}}var l=class{renderers=new Map;validators=[];register(e){let t=this.renderers.get(e.target)??[];return t.push(e),this.renderers.set(e.target,t),this}prependRegister(e){let t=this.renderers.get(e.target)??[];return t.unshift(e),this.renderers.set(e.target,t),this}addValidator(e){return this.validators.push(e),this}async render(e,t,n){if(!t.targets.includes(e))throw Error(`Target ${e} not declared for ${t.meta.name}.v${t.meta.version}`);for(let r of this.validators)await r.validate(t,e,n);let r=this.renderers.get(e)??[];for(let e of r)try{return await e.render(t,n)}catch{}throw Error(`No renderer available for ${e}`)}};function u(){let t=new l,n=(e,t)=>{let n=JSON.parse(JSON.stringify(t)),r=e.policy?.pii??[],i=(e,t)=>{let n=t.replace(/^\//,``).replace(/\[(\d+)\]/g,`.$1`).split(`.`).filter(Boolean),r=e;for(let e=0;e<n.length-1;e++){let t=n[e];if(r&&typeof r==`object`&&t in r)r=r[t];else return}let i=n[n.length-1];r&&typeof r==`object`&&i&&i in r&&(r[i]=`[REDACTED]`)};for(let e of r)i(n,e);return n};return t.register({target:`markdown`,async render(t,r){let i=r?.data;if(!i&&r?.fetchData&&(i=await r.fetchData()),t.source.type===`component`&&t.source.props&&i!==void 0){let n=Array.isArray(i),r=!n&&typeof i==`object`&&!!i&&!Object.values(i).some(e=>Array.isArray(e)||typeof e==`object`&&!!e);if(n||r)return{mimeType:`text/markdown`,body:e(t.source.props,i,{title:t.meta.description??t.meta.name,description:`${t.meta.name} v${t.meta.version}`})};throw Error(`Complex data structure for ${t.meta.name} - expecting custom renderer`)}if(t.source.type===`blocknotejs`){let e=n(t,{text:c(t.source.docJson)});return{mimeType:`text/markdown`,body:String(e.text)}}if(t.source.type===`component`&&i!==void 0)throw Error(`No schema (source.props) available for ${t.meta.name} - expecting custom renderer`);if(t.source.type===`component`)return{mimeType:`text/markdown`,body:`${`# ${t.meta.name} v${t.meta.version}`}${t.meta.description?`\n\n${t.meta.description}`:``}${t.meta.tags&&t.meta.tags.length?`\n\nTags: ${t.meta.tags.join(`, `)}`:``}${t.meta.owners&&t.meta.owners.length?`\n\nOwners: ${t.meta.owners.join(`, `)}`:``}${`\n\nComponent: \`${t.source.componentKey}\``}${t.policy?.pii?.length?`\n\nRedacted paths: ${t.policy.pii.map(e=>`\`${e}\``).join(`, `)}`:``}`};throw Error(`unsupported`)}}),t.register({target:`application/json`,async render(e){let t=n(e,{meta:e.meta,source:e.source});return{mimeType:`application/json`,body:JSON.stringify(t,null,2)}}}),t.register({target:`application/xml`,async render(e){let t=n(e,{meta:e.meta,source:e.source});return{mimeType:`application/xml`,body:`<presentation name="${e.meta.name}" version="${e.meta.version}"><json>${encodeURIComponent(JSON.stringify(t))}</json></presentation>`}}}),t}function d(e){return e.register({target:`react`,async render(e){if(e.source.type===`component`){let t=e.source.props&&e.source.props.getZod().safeParse({}).success?{}:void 0;return{kind:`react_component`,componentKey:e.source.componentKey,props:t}}return{kind:`blocknotejs`,docJson:e.source.docJson,blockConfig:e.source.blockConfig}}}),e}function f(e){return e.addValidator({validate(e){if(!e.meta.description||e.meta.description.length<3)throw Error(`Presentation ${e.meta.name}.v${e.meta.version} missing meta.description`)}}),e}function p(e,r){let i=new n({headingStyle:`atx`,codeBlockStyle:`fenced`,bulletListMarker:`-`});return i.addRule(`link`,{filter:`a`,replacement:(e,t)=>{let n=t.href;return n&&e?`[${e}](${n})`:e||``}}),e.prependRegister({target:`markdown`,async render(e,n){if(e.source.type!==`component`)throw Error(`React-to-markdown renderer only handles component presentations`);let{renderToStaticMarkup:a}=await import(`react-dom/server`),o=r[e.source.componentKey];if(!o)throw Error(`Component ${e.source.componentKey} not found in componentMap`);let s;try{s=a(t.createElement(o,e.source.props?{}:void 0))}catch(t){throw Error(`Failed to render component ${e.source.componentKey}: ${t instanceof Error?t.message:`Unknown error`}`)}let c;try{c=i.turndown(s)}catch(e){throw Error(`Failed to convert HTML to markdown: ${e instanceof Error?e.message:`Unknown error`}`)}return e.policy?.pii&&e.policy.pii.length>0?{mimeType:`text/markdown`,body:c.replace(/\[REDACTED\]/g,`[REDACTED]`)}:{mimeType:`text/markdown`,body:c}}}),e}export{l as TransformEngine,u as createDefaultTransformEngine,f as registerBasicValidation,d as registerDefaultReactRenderer,p as registerReactToMarkdownRenderer};
+//#region src/presentations.v2.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 level = Math.min(Math.max(node.attrs?.level ?? 1, 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.name}.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 (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.name,
+						description: `${desc.meta.name} v${desc.meta.version}`
+					})
+				};
+				throw new Error(`Complex data structure for ${desc.meta.name} - 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.name} - expecting custom renderer`);
+			if (desc.source.type === "component") return {
+				mimeType: "text/markdown",
+				body: `${`# ${desc.meta.name} 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.name}" 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.name}.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.js

@@ -1 +1,10 @@
-import"zod";function e(e){return e}export{e as definePrompt};
+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.js

@@ -1 +1,34 @@
-import"zod";var e=class{prompts=new Map;register(e){let t=`${e.meta.name}.v${e.meta.version}`;if(this.prompts.has(t))throw Error(`Duplicate prompt ${t}`);return this.prompts.set(t,e),this}list(){return[...this.prompts.values()]}get(e,t){if(t!=null)return this.prompts.get(`${e}.v${t}`);let n,r=-1/0;for(let[t,i]of this.prompts.entries())t.startsWith(`${e}.v`)&&i.meta.version>r&&(r=i.meta.version,n=i);return n}};export{e as PromptRegistry};
+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.name}.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/docs/regenerator.docblock.js

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

package/dist/regenerator/executor.js

@@ -1 +1,86 @@
-var e=class{constructor(e={}){this.deps=e}async execute(e,n,r={}){let i=new Date,a=[];for(let[t,i]of n.actions.entries()){let o=await this.executeAction({index:t,action:i,context:e,proposal:n,options:r});a.push(o)}let o=new Date,s=t(a);return{proposalId:n.id,contextId:e.id,startedAt:i,finishedAt:o,status:s,actions:a}}async executeAction({index:e,action:t,context:n,proposal:r,options:i}){let a=new Date,o=i.dryRun??!1,s=(n,r={})=>({index:e,action:t,status:n,startedAt:a,finishedAt:new Date,reason:r.reason,output:r.output,error:r.error});if(o)return s(`skipped`,{reason:`dry_run`});try{switch(t.kind){case`update_blueprint`:{let e=this.deps.blueprintUpdater;return e?s(`success`,{output:await e.applyBlueprintUpdate(n,r,t)}):s(`skipped`,{reason:`missing_blueprint_updater`})}case`update_tenant_config`:{let e=this.deps.tenantConfigUpdater;return e?s(`success`,{output:await e.applyTenantConfigUpdate(n,r,t)}):s(`skipped`,{reason:`missing_tenant_config_updater`})}case`run_tests`:{let e=this.deps.testExecutor;return e?s(`success`,{output:await e.runTests(n,r,t)}):s(`skipped`,{reason:`missing_test_executor`})}case`run_migrations`:{let e=this.deps.migrationExecutor;return e?s(`success`,{output:await e.runMigrations(n,r,t)}):s(`skipped`,{reason:`missing_migration_executor`})}case`trigger_regeneration`:{let e=this.deps.regenerationTrigger;return e?s(`success`,{output:await e.triggerRegeneration(n,r,t)}):s(`skipped`,{reason:`missing_regeneration_trigger`})}default:return s(`skipped`,{reason:`unknown_action`})}}catch(e){return s(`failed`,{error:e instanceof Error?e:Error(String(e))})}}};function t(e){return e.some(e=>e.status===`failed`)?`failed`:e.some(e=>e.status===`success`)&&e.some(e=>e.status===`skipped`)||e.every(e=>e.status===`skipped`)?`partial`:`success`}export{e as ProposalExecutor};
+//#region src/regenerator/executor.ts
+var ProposalExecutor = class {
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
+	async execute(context, proposal, options = {}) {
+		const startedAt = /* @__PURE__ */ new Date();
+		const actionResults = [];
+		for (const [index, action] of proposal.actions.entries()) {
+			const result = await this.executeAction({
+				index,
+				action,
+				context,
+				proposal,
+				options
+			});
+			actionResults.push(result);
+		}
+		const finishedAt = /* @__PURE__ */ new Date();
+		const summaryStatus = summarizeStatus(actionResults);
+		return {
+			proposalId: proposal.id,
+			contextId: context.id,
+			startedAt,
+			finishedAt,
+			status: summaryStatus,
+			actions: actionResults
+		};
+	}
+	async executeAction({ index, action, context, proposal, options }) {
+		const startedAt = /* @__PURE__ */ new Date();
+		const dryRun = options.dryRun ?? false;
+		const complete = (status, params = {}) => ({
+			index,
+			action,
+			status,
+			startedAt,
+			finishedAt: /* @__PURE__ */ new Date(),
+			reason: params.reason,
+			output: params.output,
+			error: params.error
+		});
+		if (dryRun) return complete("skipped", { reason: "dry_run" });
+		try {
+			switch (action.kind) {
+				case "update_blueprint": {
+					const updater = this.deps.blueprintUpdater;
+					if (!updater) return complete("skipped", { reason: "missing_blueprint_updater" });
+					return complete("success", { output: await updater.applyBlueprintUpdate(context, proposal, action) });
+				}
+				case "update_tenant_config": {
+					const updater = this.deps.tenantConfigUpdater;
+					if (!updater) return complete("skipped", { reason: "missing_tenant_config_updater" });
+					return complete("success", { output: await updater.applyTenantConfigUpdate(context, proposal, action) });
+				}
+				case "run_tests": {
+					const executor = this.deps.testExecutor;
+					if (!executor) return complete("skipped", { reason: "missing_test_executor" });
+					return complete("success", { output: await executor.runTests(context, proposal, action) });
+				}
+				case "run_migrations": {
+					const executor = this.deps.migrationExecutor;
+					if (!executor) return complete("skipped", { reason: "missing_migration_executor" });
+					return complete("success", { output: await executor.runMigrations(context, proposal, action) });
+				}
+				case "trigger_regeneration": {
+					const trigger = this.deps.regenerationTrigger;
+					if (!trigger) return complete("skipped", { reason: "missing_regeneration_trigger" });
+					return complete("success", { output: await trigger.triggerRegeneration(context, proposal, action) });
+				}
+				default: return complete("skipped", { reason: "unknown_action" });
+			}
+		} catch (error) {
+			return complete("failed", { error: error instanceof Error ? error : new Error(String(error)) });
+		}
+	}
+};
+function summarizeStatus(actionResults) {
+	if (actionResults.some((result) => result.status === "failed")) return "failed";
+	if (actionResults.some((result) => result.status === "success") && actionResults.some((result) => result.status === "skipped")) return "partial";
+	if (actionResults.every((result) => result.status === "skipped")) return "partial";
+	return "success";
+}
+
+//#endregion
+export { ProposalExecutor };

package/dist/regenerator/index.js

@@ -1 +1,6 @@
-import{behaviorToEnvelope as e,errorToEnvelope as t,telemetryToEnvelope as n}from"./utils.js";import{RegeneratorService as r}from"./service.js";import{ProposalExecutor as i}from"./executor.js";import{ExecutorProposalSink as a}from"./sinks.js";export{a as ExecutorProposalSink,i as ProposalExecutor,r as RegeneratorService,e as behaviorToEnvelope,t as errorToEnvelope,n as telemetryToEnvelope};
+import { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope } from "./utils.js";
+import { RegeneratorService } from "./service.js";
+import { ProposalExecutor } from "./executor.js";
+import { ExecutorProposalSink } from "./sinks.js";
+
+export { ExecutorProposalSink, ProposalExecutor, RegeneratorService, behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope };