@contractspec/lib.contracts 1.56.1 → 1.57.0

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

@@ -0,0 +1,676 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { EvidenceFindingExtraction } from "./findings.js";
+import { InsightExtraction } from "./insights.js";
+import { ProblemGrouping } from "./problems.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 { TicketCollection } from "./tickets.js";
+import "./types.js";
+import { ZodSchemaType } from "@contractspec/lib.schema";
+import * as z$2 from "zod";
+
+//#region src/product-intent/spec.d.ts
+declare const ProductIntentSpecSchema: z$2.ZodObject<{
+  id: z$2.ZodString;
+  meta: z$2.ZodObject<{
+    key: z$2.ZodString;
+    version: z$2.ZodString;
+    description: z$2.ZodString;
+    stability: z$2.ZodEnum<{
+      readonly Idea: "idea";
+      readonly InCreation: "in_creation";
+      readonly Experimental: "experimental";
+      readonly Beta: "beta";
+      readonly Stable: "stable";
+      readonly Deprecated: "deprecated";
+    }>;
+    owners: z$2.ZodArray<z$2.ZodString>;
+    tags: z$2.ZodArray<z$2.ZodString>;
+    title: z$2.ZodOptional<z$2.ZodString>;
+    domain: z$2.ZodOptional<z$2.ZodString>;
+    docId: z$2.ZodOptional<z$2.ZodArray<z$2.ZodString>>;
+    goal: z$2.ZodOptional<z$2.ZodString>;
+    context: z$2.ZodOptional<z$2.ZodString>;
+  }, z$2.core.$strip>;
+  question: z$2.ZodString;
+  runtimeContext: z$2.ZodOptional<z$2.ZodUnknown>;
+  findings: z$2.ZodOptional<z$2.ZodType<{
+    findings: {
+      findingId: string;
+      summary: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    findings: {
+      findingId: string;
+      summary: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+    }[];
+  }, unknown>>>;
+  insights: z$2.ZodOptional<z$2.ZodType<{
+    insights: {
+      insightId: string;
+      claim: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+      segment?: string | undefined;
+      confidence?: number | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    insights: {
+      insightId: string;
+      claim: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+      segment?: string | undefined;
+      confidence?: number | undefined;
+    }[];
+  }, unknown>>>;
+  problems: z$2.ZodOptional<z$2.ZodType<{
+    problems: {
+      problemId: string;
+      statement: string;
+      evidenceIds: string[];
+      tags?: string[] | undefined;
+      severity?: "low" | "medium" | "high" | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    problems: {
+      problemId: string;
+      statement: string;
+      evidenceIds: string[];
+      tags?: string[] | undefined;
+      severity?: "low" | "medium" | "high" | undefined;
+    }[];
+  }, unknown>>>;
+  brief: z$2.ZodOptional<z$2.ZodType<{
+    opportunityId: string;
+    title: string;
+    problem: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    who: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    proposedChange: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    expectedImpact: {
+      metric: string;
+      direction: "up" | "down";
+      magnitudeHint?: string | undefined;
+      timeframeHint?: string | undefined;
+    };
+    confidence: "low" | "medium" | "high";
+    risks?: {
+      text: string;
+      citations?: {
+        chunkId: string;
+        quote: string;
+      }[] | undefined;
+    }[] | undefined;
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    opportunityId: string;
+    title: string;
+    problem: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    who: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    proposedChange: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    expectedImpact: {
+      metric: string;
+      direction: "up" | "down";
+      magnitudeHint?: string | undefined;
+      timeframeHint?: string | undefined;
+    };
+    confidence: "low" | "medium" | "high";
+    risks?: {
+      text: string;
+      citations?: {
+        chunkId: string;
+        quote: string;
+      }[] | undefined;
+    }[] | undefined;
+  }, unknown>>>;
+  tickets: z$2.ZodOptional<z$2.ZodType<{
+    tickets: {
+      ticketId: string;
+      title: string;
+      summary: string;
+      evidenceIds: string[];
+      acceptanceCriteria: string[];
+      priority?: "low" | "medium" | "high" | undefined;
+      tags?: string[] | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    tickets: {
+      ticketId: string;
+      title: string;
+      summary: string;
+      evidenceIds: string[];
+      acceptanceCriteria: string[];
+      priority?: "low" | "medium" | "high" | undefined;
+      tags?: string[] | undefined;
+    }[];
+  }, unknown>>>;
+  patchIntent: z$2.ZodOptional<z$2.ZodType<{
+    featureKey: string;
+    changes: {
+      type: "other" | "add_field" | "remove_field" | "rename_field" | "add_event" | "update_event" | "add_operation" | "update_operation" | "update_form" | "update_policy" | "add_enum_value" | "remove_enum_value";
+      target: string;
+      detail: string;
+    }[];
+    acceptanceCriteria: string[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    featureKey: string;
+    changes: {
+      type: "other" | "add_field" | "remove_field" | "rename_field" | "add_event" | "update_event" | "add_operation" | "update_operation" | "update_form" | "update_policy" | "add_enum_value" | "remove_enum_value";
+      target: string;
+      detail: string;
+    }[];
+    acceptanceCriteria: string[];
+  }, unknown>>>;
+  patch: z$2.ZodOptional<z$2.ZodType<{
+    overlay: {
+      adds?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      updates?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      removes?: {
+        path: string;
+      }[] | undefined;
+    };
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    overlay: {
+      adds?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      updates?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      removes?: {
+        path: string;
+      }[] | undefined;
+    };
+  }, unknown>>>;
+  impact: z$2.ZodOptional<z$2.ZodType<{
+    reportId: string;
+    patchId: string;
+    summary: string;
+    surfaces: {
+      api?: string[] | undefined;
+      db?: string[] | undefined;
+      ui?: string[] | undefined;
+      workflows?: string[] | undefined;
+      policy?: string[] | undefined;
+      docs?: string[] | undefined;
+      tests?: string[] | undefined;
+    };
+    breaks?: string[] | undefined;
+    mustChange?: string[] | undefined;
+    risky?: string[] | undefined;
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    reportId: string;
+    patchId: string;
+    summary: string;
+    surfaces: {
+      api?: string[] | undefined;
+      db?: string[] | undefined;
+      ui?: string[] | undefined;
+      workflows?: string[] | undefined;
+      policy?: string[] | undefined;
+      docs?: string[] | undefined;
+      tests?: string[] | undefined;
+    };
+    breaks?: string[] | undefined;
+    mustChange?: string[] | undefined;
+    risky?: string[] | undefined;
+  }, unknown>>>;
+  tasks: z$2.ZodOptional<z$2.ZodType<{
+    packId: string;
+    patchId: string;
+    overview: string;
+    tasks: {
+      id: string;
+      title: string;
+      surface: ("policy" | "tests" | "docs" | "api" | "db" | "ui" | "workflows" | "other")[];
+      why: string;
+      acceptance: string[];
+      agentPrompt: string;
+      dependsOn?: string[] | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    packId: string;
+    patchId: string;
+    overview: string;
+    tasks: {
+      id: string;
+      title: string;
+      surface: ("policy" | "tests" | "docs" | "api" | "db" | "ui" | "workflows" | "other")[];
+      why: string;
+      acceptance: string[];
+      agentPrompt: string;
+      dependsOn?: string[] | undefined;
+    }[];
+  }, unknown>>>;
+}, z$2.core.$strip>;
+declare const ProductIntentSpecModel: ZodSchemaType<z$2.ZodObject<{
+  id: z$2.ZodString;
+  meta: z$2.ZodObject<{
+    key: z$2.ZodString;
+    version: z$2.ZodString;
+    description: z$2.ZodString;
+    stability: z$2.ZodEnum<{
+      readonly Idea: "idea";
+      readonly InCreation: "in_creation";
+      readonly Experimental: "experimental";
+      readonly Beta: "beta";
+      readonly Stable: "stable";
+      readonly Deprecated: "deprecated";
+    }>;
+    owners: z$2.ZodArray<z$2.ZodString>;
+    tags: z$2.ZodArray<z$2.ZodString>;
+    title: z$2.ZodOptional<z$2.ZodString>;
+    domain: z$2.ZodOptional<z$2.ZodString>;
+    docId: z$2.ZodOptional<z$2.ZodArray<z$2.ZodString>>;
+    goal: z$2.ZodOptional<z$2.ZodString>;
+    context: z$2.ZodOptional<z$2.ZodString>;
+  }, z$2.core.$strip>;
+  question: z$2.ZodString;
+  runtimeContext: z$2.ZodOptional<z$2.ZodUnknown>;
+  findings: z$2.ZodOptional<z$2.ZodType<{
+    findings: {
+      findingId: string;
+      summary: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    findings: {
+      findingId: string;
+      summary: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+    }[];
+  }, unknown>>>;
+  insights: z$2.ZodOptional<z$2.ZodType<{
+    insights: {
+      insightId: string;
+      claim: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+      segment?: string | undefined;
+      confidence?: number | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    insights: {
+      insightId: string;
+      claim: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+      tags?: string[] | undefined;
+      segment?: string | undefined;
+      confidence?: number | undefined;
+    }[];
+  }, unknown>>>;
+  problems: z$2.ZodOptional<z$2.ZodType<{
+    problems: {
+      problemId: string;
+      statement: string;
+      evidenceIds: string[];
+      tags?: string[] | undefined;
+      severity?: "low" | "medium" | "high" | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    problems: {
+      problemId: string;
+      statement: string;
+      evidenceIds: string[];
+      tags?: string[] | undefined;
+      severity?: "low" | "medium" | "high" | undefined;
+    }[];
+  }, unknown>>>;
+  brief: z$2.ZodOptional<z$2.ZodType<{
+    opportunityId: string;
+    title: string;
+    problem: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    who: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    proposedChange: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    expectedImpact: {
+      metric: string;
+      direction: "up" | "down";
+      magnitudeHint?: string | undefined;
+      timeframeHint?: string | undefined;
+    };
+    confidence: "low" | "medium" | "high";
+    risks?: {
+      text: string;
+      citations?: {
+        chunkId: string;
+        quote: string;
+      }[] | undefined;
+    }[] | undefined;
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    opportunityId: string;
+    title: string;
+    problem: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    who: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    proposedChange: {
+      text: string;
+      citations: {
+        chunkId: string;
+        quote: string;
+      }[];
+    };
+    expectedImpact: {
+      metric: string;
+      direction: "up" | "down";
+      magnitudeHint?: string | undefined;
+      timeframeHint?: string | undefined;
+    };
+    confidence: "low" | "medium" | "high";
+    risks?: {
+      text: string;
+      citations?: {
+        chunkId: string;
+        quote: string;
+      }[] | undefined;
+    }[] | undefined;
+  }, unknown>>>;
+  tickets: z$2.ZodOptional<z$2.ZodType<{
+    tickets: {
+      ticketId: string;
+      title: string;
+      summary: string;
+      evidenceIds: string[];
+      acceptanceCriteria: string[];
+      priority?: "low" | "medium" | "high" | undefined;
+      tags?: string[] | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    tickets: {
+      ticketId: string;
+      title: string;
+      summary: string;
+      evidenceIds: string[];
+      acceptanceCriteria: string[];
+      priority?: "low" | "medium" | "high" | undefined;
+      tags?: string[] | undefined;
+    }[];
+  }, unknown>>>;
+  patchIntent: z$2.ZodOptional<z$2.ZodType<{
+    featureKey: string;
+    changes: {
+      type: "other" | "add_field" | "remove_field" | "rename_field" | "add_event" | "update_event" | "add_operation" | "update_operation" | "update_form" | "update_policy" | "add_enum_value" | "remove_enum_value";
+      target: string;
+      detail: string;
+    }[];
+    acceptanceCriteria: string[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    featureKey: string;
+    changes: {
+      type: "other" | "add_field" | "remove_field" | "rename_field" | "add_event" | "update_event" | "add_operation" | "update_operation" | "update_form" | "update_policy" | "add_enum_value" | "remove_enum_value";
+      target: string;
+      detail: string;
+    }[];
+    acceptanceCriteria: string[];
+  }, unknown>>>;
+  patch: z$2.ZodOptional<z$2.ZodType<{
+    overlay: {
+      adds?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      updates?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      removes?: {
+        path: string;
+      }[] | undefined;
+    };
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    overlay: {
+      adds?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      updates?: {
+        path: string;
+        value: unknown;
+      }[] | undefined;
+      removes?: {
+        path: string;
+      }[] | undefined;
+    };
+  }, unknown>>>;
+  impact: z$2.ZodOptional<z$2.ZodType<{
+    reportId: string;
+    patchId: string;
+    summary: string;
+    surfaces: {
+      api?: string[] | undefined;
+      db?: string[] | undefined;
+      ui?: string[] | undefined;
+      workflows?: string[] | undefined;
+      policy?: string[] | undefined;
+      docs?: string[] | undefined;
+      tests?: string[] | undefined;
+    };
+    breaks?: string[] | undefined;
+    mustChange?: string[] | undefined;
+    risky?: string[] | undefined;
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    reportId: string;
+    patchId: string;
+    summary: string;
+    surfaces: {
+      api?: string[] | undefined;
+      db?: string[] | undefined;
+      ui?: string[] | undefined;
+      workflows?: string[] | undefined;
+      policy?: string[] | undefined;
+      docs?: string[] | undefined;
+      tests?: string[] | undefined;
+    };
+    breaks?: string[] | undefined;
+    mustChange?: string[] | undefined;
+    risky?: string[] | undefined;
+  }, unknown>>>;
+  tasks: z$2.ZodOptional<z$2.ZodType<{
+    packId: string;
+    patchId: string;
+    overview: string;
+    tasks: {
+      id: string;
+      title: string;
+      surface: ("policy" | "tests" | "docs" | "api" | "db" | "ui" | "workflows" | "other")[];
+      why: string;
+      acceptance: string[];
+      agentPrompt: string;
+      dependsOn?: string[] | undefined;
+    }[];
+  }, unknown, z$2.core.$ZodTypeInternals<{
+    packId: string;
+    patchId: string;
+    overview: string;
+    tasks: {
+      id: string;
+      title: string;
+      surface: ("policy" | "tests" | "docs" | "api" | "db" | "ui" | "workflows" | "other")[];
+      why: string;
+      acceptance: string[];
+      agentPrompt: string;
+      dependsOn?: string[] | undefined;
+    }[];
+  }, unknown>>>;
+}, z$2.core.$strip>>;
+type ProductIntentSpecData = z$2.infer<typeof ProductIntentSpecSchema>;
+/**
+ * A ProductIntentSpec describes the contract for a single product
+ * opportunity. It ties together the question being asked, the
+ * resulting brief, the proposed patch intent, the concrete patch, the
+ * impact report and the tasks required to implement it. This interface
+ * is intentionally flexible so that different implementations can fill
+ * in the pieces as they become available.
+ */
+interface ProductIntentMeta extends OwnerShipMeta {
+  goal?: string;
+  context?: string;
+}
+interface ProductIntentSpec<Context = unknown> {
+  /**
+   * A unique identifier for this product intent. This is used when
+   * storing and retrieving specs from a registry or database.
+   */
+  id: string;
+  /**
+   * Contract metadata for registry and ownership tracking.
+   */
+  meta: ProductIntentMeta;
+  /**
+   * The question or goal that triggered the discovery process. For
+   * example: "What should we build next to improve activation?".
+   */
+  question: string;
+  /**
+   * Optional runtime context defined by the caller.
+   */
+  runtimeContext?: Context;
+  /**
+   * The extracted insights grounded in evidence.
+   */
+  insights?: InsightExtraction;
+  /**
+   * The evidence findings extracted from transcripts.
+   */
+  findings?: EvidenceFindingExtraction;
+  /**
+   * Grouped problem statements linked to evidence findings.
+   */
+  problems?: ProblemGrouping;
+  /**
+   * The synthesized opportunity brief explaining what to build and why.
+   */
+  brief?: OpportunityBrief;
+  /**
+   * Tickets derived from the problems and evidence findings.
+   */
+  tickets?: TicketCollection;
+  /**
+   * The intermediate patch intent derived from the brief. This is
+   * converted into an actual ContractSpec patch by the runtime.
+   */
+  patchIntent?: ContractPatchIntent;
+  /**
+   * The concrete patch to apply to the ContractSpec. Produced by
+   * translating the patch intent into your spec format.
+   */
+  patch?: ContractSpecPatch;
+  /**
+   * The impact report describing consequences of applying the patch.
+   */
+  impact?: ImpactReport;
+  /**
+   * The task pack enumerating discrete work items to implement the patch.
+   */
+  tasks?: TaskPack;
+}
+/**
+ * Helper to define a ProductIntentSpec with proper type inference.
+ */
+declare function defineProductIntentSpec<Context = unknown>(spec: ProductIntentSpec<Context>): ProductIntentSpec<Context>;
+//#endregion
+export { ProductIntentMeta, ProductIntentSpec, ProductIntentSpecData, ProductIntentSpecModel, defineProductIntentSpec };