@contractspec/lib.contracts 1.56.1 → 1.57.0

package/dist/product-intent/problems.js

@@ -0,0 +1,22 @@
+import { ZodSchemaType } from "@contractspec/lib.schema";
+import * as z$2 from "zod";
+
+//#region src/product-intent/problems.ts
+const ProblemSeveritySchema = z$2.enum([
+	"low",
+	"medium",
+	"high"
+]);
+const ProblemStatementSchema = z$2.object({
+	problemId: z$2.string().min(1),
+	statement: z$2.string().min(1),
+	evidenceIds: z$2.array(z$2.string().min(1)).min(1),
+	tags: z$2.array(z$2.string().min(1)).optional(),
+	severity: ProblemSeveritySchema.optional()
+});
+const ProblemStatementModel = new ZodSchemaType(ProblemStatementSchema, { name: "ProblemStatement" });
+const ProblemGroupingSchema = z$2.object({ problems: z$2.array(ProblemStatementSchema) });
+const ProblemGroupingModel = new ZodSchemaType(ProblemGroupingSchema, { name: "ProblemGrouping" });
+
+//#endregion
+export { ProblemGroupingModel, ProblemStatementModel };

package/dist/product-intent/registry.d.ts

@@ -0,0 +1,32 @@
+import { SpecContractRegistry } from "../registry.js";
+import { ProductIntentSpec } from "./spec.js";
+
+//#region src/product-intent/registry.d.ts
+/**
+ * Registry for ProductIntentSpec contracts.
+ */
+declare class ProductIntentRegistry extends SpecContractRegistry<'product-intent', ProductIntentSpec> {
+  constructor(items?: ProductIntentSpec[]);
+  /**
+   * Add or replace a spec by meta key and version.
+   */
+  set(spec: ProductIntentSpec): this;
+  /**
+   * Retrieve a product intent spec by runtime id.
+   */
+  getById<Context = unknown>(id: string): ProductIntentSpec<Context> | undefined;
+  /**
+   * Delete a spec by runtime id.
+   */
+  delete(id: string): boolean;
+  /**
+   * Delete a spec by contract key and version.
+   */
+  deleteByKey(key: string, version: string): boolean;
+  /**
+   * Clear all registered specs.
+   */
+  clear(): void;
+}
+//#endregion
+export { ProductIntentRegistry };

package/dist/product-intent/registry.js

@@ -0,0 +1,49 @@
+import { SpecContractRegistry, keyOfSpecContract } from "../registry.js";
+
+//#region src/product-intent/registry.ts
+/**
+* Registry for ProductIntentSpec contracts.
+*/
+var ProductIntentRegistry = class extends SpecContractRegistry {
+	constructor(items) {
+		super("product-intent", items);
+	}
+	/**
+	* Add or replace a spec by meta key and version.
+	*/
+	set(spec) {
+		const key = keyOfSpecContract(spec);
+		this.items.set(key, spec);
+		return this;
+	}
+	/**
+	* Retrieve a product intent spec by runtime id.
+	*/
+	getById(id) {
+		return this.list().find((spec) => spec.id === id);
+	}
+	/**
+	* Delete a spec by runtime id.
+	*/
+	delete(id) {
+		const target = this.list().find((spec) => spec.id === id);
+		if (!target) return false;
+		const key = keyOfSpecContract(target);
+		return this.items.delete(key);
+	}
+	/**
+	* Delete a spec by contract key and version.
+	*/
+	deleteByKey(key, version) {
+		return this.items.delete(`${key}.v${version}`);
+	}
+	/**
+	* Clear all registered specs.
+	*/
+	clear() {
+		this.items.clear();
+	}
+};
+
+//#endregion
+export { ProductIntentRegistry };

package/dist/product-intent/runtime.d.ts

@@ -0,0 +1,103 @@
+import { EvidenceChunk } from "./evidence.js";
+import { InsightExtraction } from "./insights.js";
+import { OpportunityBrief } from "./opportunity-brief.js";
+import { ContractPatchIntent } from "./contract-patch-intent.js";
+import { ContractSpecPatch } from "./contract-spec-patch.js";
+import { ImpactReport } from "./impact-report.js";
+import { TaskPack } from "./task-pack.js";
+import "./types.js";
+import { ProductIntentMeta, ProductIntentSpec } from "./spec.js";
+import { ProductIntentRegistry } from "./registry.js";
+
+//#region src/product-intent/runtime.d.ts
+interface ProductIntentRuntimeOptions<Context = unknown> {
+  /**
+   * Fetch evidence relevant to a discovery question.
+   */
+  fetchEvidence: (params: {
+    query: string;
+    maxChunks?: number;
+    context?: Context;
+  }) => Promise<EvidenceChunk[]>;
+  /**
+   * Default maximum number of evidence chunks to retrieve.
+   */
+  maxEvidenceChunks?: number;
+  /**
+   * Optional callback invoked after insight extraction.
+   */
+  onInsightsGenerated?: (insights: InsightExtraction, ctx?: Context) => Promise<void>;
+  /**
+   * Optional callback invoked after brief synthesis.
+   */
+  onBriefSynthesised?: (brief: OpportunityBrief, ctx?: Context) => Promise<void>;
+  /**
+   * Optional callback invoked after patch intent generation.
+   */
+  onPatchIntentGenerated?: (intent: ContractPatchIntent, ctx?: Context) => Promise<void>;
+  /**
+   * Optional callback invoked after concrete patch generation.
+   */
+  onPatchGenerated?: (patch: ContractSpecPatch, ctx?: Context) => Promise<void>;
+  /**
+   * Optional callback invoked after impact report generation.
+   */
+  onImpactGenerated?: (impact: ImpactReport, ctx?: Context) => Promise<void>;
+  /**
+   * Optional callback invoked after task pack generation.
+   */
+  onTasksGenerated?: (tasks: TaskPack, ctx?: Context) => Promise<void>;
+}
+interface ProductIntentDiscoveryParams<Context = unknown> {
+  id: string;
+  meta: ProductIntentMeta;
+  question: string;
+  context?: Context;
+  maxEvidenceChunks?: number;
+}
+/**
+ * ProductIntentRuntime orchestrates the multi-step pipeline of evidence
+ * retrieval, insight extraction, brief synthesis, patch generation and
+ * task generation. Consumers should extend this class and override
+ * extractInsights, synthesiseBrief, generatePatchIntent, generatePatch,
+ * generateImpactReport, and generateTasks.
+ */
+declare class ProductIntentRuntime<Context = unknown> {
+  private registry;
+  private opts;
+  constructor(opts: ProductIntentRuntimeOptions<Context>, registry?: ProductIntentRegistry);
+  /**
+   * Register an intent spec with this runtime.
+   */
+  registerIntent(spec: ProductIntentSpec<Context>): void;
+  /**
+   * Main entrypoint for running the discovery loop.
+   */
+  runDiscovery(params: ProductIntentDiscoveryParams<Context>): Promise<ProductIntentSpec<Context>>;
+  /**
+   * Extract insights from evidence. Override in subclasses.
+   */
+  protected extractInsights(_question: string, _evidence: EvidenceChunk[], _context?: Context): Promise<InsightExtraction>;
+  /**
+   * Synthesize a brief from extracted insights. Override in subclasses.
+   */
+  protected synthesiseBrief(_question: string, _insights: InsightExtraction, _context?: Context): Promise<OpportunityBrief>;
+  /**
+   * Generate a patch intent from a brief. Override in subclasses.
+   */
+  protected generatePatchIntent(_brief: OpportunityBrief, _context?: Context): Promise<ContractPatchIntent>;
+  /**
+   * Translate a patch intent into a concrete ContractSpec patch.
+   */
+  protected generatePatch(_intent: ContractPatchIntent, _context?: Context): Promise<ContractSpecPatch>;
+  /**
+   * Produce an impact report for a given intent and patch.
+   */
+  protected generateImpactReport(_intent: ContractPatchIntent, _patch: ContractSpecPatch, _context?: Context): Promise<ImpactReport>;
+  /**
+   * Generate a task pack from the brief, intent and impact report.
+   */
+  protected generateTasks(_brief: OpportunityBrief, _intent: ContractPatchIntent, _impact: ImpactReport, _context?: Context): Promise<TaskPack>;
+}
+//#endregion
+export { ProductIntentDiscoveryParams, ProductIntentRuntime, ProductIntentRuntimeOptions };

package/dist/product-intent/runtime.js

@@ -0,0 +1,101 @@
+import { ProductIntentRegistry } from "./registry.js";
+
+//#region src/product-intent/runtime.ts
+/**
+* ProductIntentRuntime orchestrates the multi-step pipeline of evidence
+* retrieval, insight extraction, brief synthesis, patch generation and
+* task generation. Consumers should extend this class and override
+* extractInsights, synthesiseBrief, generatePatchIntent, generatePatch,
+* generateImpactReport, and generateTasks.
+*/
+var ProductIntentRuntime = class {
+	registry;
+	opts;
+	constructor(opts, registry) {
+		this.opts = opts;
+		this.registry = registry ?? new ProductIntentRegistry();
+	}
+	/**
+	* Register an intent spec with this runtime.
+	*/
+	registerIntent(spec) {
+		this.registry.register(spec);
+	}
+	/**
+	* Main entrypoint for running the discovery loop.
+	*/
+	async runDiscovery(params) {
+		const { id, meta, question, context } = params;
+		const maxEvidenceChunks = params.maxEvidenceChunks ?? this.opts.maxEvidenceChunks ?? 20;
+		const spec = {
+			id,
+			meta,
+			question,
+			runtimeContext: context
+		};
+		const evidence = await this.opts.fetchEvidence({
+			query: question,
+			maxChunks: maxEvidenceChunks,
+			context
+		});
+		const insights = await this.extractInsights(question, evidence, context);
+		spec.insights = insights;
+		if (this.opts.onInsightsGenerated) await this.opts.onInsightsGenerated(insights, context);
+		const brief = await this.synthesiseBrief(question, insights, context);
+		spec.brief = brief;
+		if (this.opts.onBriefSynthesised) await this.opts.onBriefSynthesised(brief, context);
+		const intent = await this.generatePatchIntent(brief, context);
+		spec.patchIntent = intent;
+		if (this.opts.onPatchIntentGenerated) await this.opts.onPatchIntentGenerated(intent, context);
+		const patch = await this.generatePatch(intent, context);
+		spec.patch = patch;
+		if (this.opts.onPatchGenerated) await this.opts.onPatchGenerated(patch, context);
+		const impact = await this.generateImpactReport(intent, patch, context);
+		spec.impact = impact;
+		if (this.opts.onImpactGenerated) await this.opts.onImpactGenerated(impact, context);
+		const tasks = await this.generateTasks(brief, intent, impact, context);
+		spec.tasks = tasks;
+		if (this.opts.onTasksGenerated) await this.opts.onTasksGenerated(tasks, context);
+		this.registry.set(spec);
+		return spec;
+	}
+	/**
+	* Extract insights from evidence. Override in subclasses.
+	*/
+	async extractInsights(_question, _evidence, _context) {
+		throw new Error("extractInsights() not implemented. Provide an implementation in a subclass.");
+	}
+	/**
+	* Synthesize a brief from extracted insights. Override in subclasses.
+	*/
+	async synthesiseBrief(_question, _insights, _context) {
+		throw new Error("synthesiseBrief() not implemented. Provide an implementation in a subclass.");
+	}
+	/**
+	* Generate a patch intent from a brief. Override in subclasses.
+	*/
+	async generatePatchIntent(_brief, _context) {
+		throw new Error("generatePatchIntent() not implemented. Provide an implementation in a subclass.");
+	}
+	/**
+	* Translate a patch intent into a concrete ContractSpec patch.
+	*/
+	async generatePatch(_intent, _context) {
+		throw new Error("generatePatch() not implemented. Provide an implementation in a subclass.");
+	}
+	/**
+	* Produce an impact report for a given intent and patch.
+	*/
+	async generateImpactReport(_intent, _patch, _context) {
+		throw new Error("generateImpactReport() not implemented. Provide an implementation in a subclass.");
+	}
+	/**
+	* Generate a task pack from the brief, intent and impact report.
+	*/
+	async generateTasks(_brief, _intent, _impact, _context) {
+		throw new Error("generateTasks() not implemented. Provide an implementation in a subclass.");
+	}
+};
+
+//#endregion
+export { ProductIntentRuntime };