@contractspec/lib.contracts-spec 2.0.0

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

@@ -0,0 +1,664 @@
+import { ZodSchemaType } from '@contractspec/lib.schema';
+import * as z from 'zod';
+import type { OwnerShipMeta } from '../ownership';
+import type { ContractPatchIntent, ContractSpecPatch, EvidenceFindingExtraction, ImpactReport, InsightExtraction, OpportunityBrief, ProblemGrouping, TaskPack, TicketCollection } from './types';
+declare const ProductIntentSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    meta: z.ZodObject<{
+        key: z.ZodString;
+        version: z.ZodString;
+        description: z.ZodString;
+        stability: z.ZodEnum<{
+            readonly Idea: "idea";
+            readonly InCreation: "in_creation";
+            readonly Experimental: "experimental";
+            readonly Beta: "beta";
+            readonly Stable: "stable";
+            readonly Deprecated: "deprecated";
+        }>;
+        owners: z.ZodArray<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        docId: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        goal: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    question: z.ZodString;
+    runtimeContext: z.ZodOptional<z.ZodUnknown>;
+    findings: z.ZodOptional<z.ZodType<{
+        findings: {
+            findingId: string;
+            summary: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        findings: {
+            findingId: string;
+            summary: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+        }[];
+    }, unknown>>>;
+    insights: z.ZodOptional<z.ZodType<{
+        insights: {
+            insightId: string;
+            claim: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+            segment?: string | undefined;
+            confidence?: number | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        insights: {
+            insightId: string;
+            claim: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+            segment?: string | undefined;
+            confidence?: number | undefined;
+        }[];
+    }, unknown>>>;
+    problems: z.ZodOptional<z.ZodType<{
+        problems: {
+            problemId: string;
+            statement: string;
+            evidenceIds: string[];
+            tags?: string[] | undefined;
+            severity?: "high" | "medium" | "low" | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        problems: {
+            problemId: string;
+            statement: string;
+            evidenceIds: string[];
+            tags?: string[] | undefined;
+            severity?: "high" | "medium" | "low" | undefined;
+        }[];
+    }, unknown>>>;
+    brief: z.ZodOptional<z.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: "high" | "medium" | "low";
+        risks?: {
+            text: string;
+            citations?: {
+                chunkId: string;
+                quote: string;
+            }[] | undefined;
+        }[] | undefined;
+    }, unknown, z.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: "high" | "medium" | "low";
+        risks?: {
+            text: string;
+            citations?: {
+                chunkId: string;
+                quote: string;
+            }[] | undefined;
+        }[] | undefined;
+    }, unknown>>>;
+    tickets: z.ZodOptional<z.ZodType<{
+        tickets: {
+            ticketId: string;
+            title: string;
+            summary: string;
+            evidenceIds: string[];
+            acceptanceCriteria: string[];
+            priority?: "high" | "medium" | "low" | undefined;
+            tags?: string[] | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        tickets: {
+            ticketId: string;
+            title: string;
+            summary: string;
+            evidenceIds: string[];
+            acceptanceCriteria: string[];
+            priority?: "high" | "medium" | "low" | undefined;
+            tags?: string[] | undefined;
+        }[];
+    }, unknown>>>;
+    patchIntent: z.ZodOptional<z.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.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.ZodOptional<z.ZodType<{
+        overlay: {
+            adds?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            updates?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            removes?: {
+                path: string;
+            }[] | undefined;
+        };
+    }, unknown, z.core.$ZodTypeInternals<{
+        overlay: {
+            adds?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            updates?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            removes?: {
+                path: string;
+            }[] | undefined;
+        };
+    }, unknown>>>;
+    impact: z.ZodOptional<z.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.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.ZodOptional<z.ZodType<{
+        packId: string;
+        patchId: string;
+        overview: string;
+        tasks: {
+            id: string;
+            title: string;
+            surface: ("docs" | "api" | "ui" | "other" | "policy" | "tests" | "workflows" | "db")[];
+            why: string;
+            acceptance: string[];
+            agentPrompt: string;
+            dependsOn?: string[] | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        packId: string;
+        patchId: string;
+        overview: string;
+        tasks: {
+            id: string;
+            title: string;
+            surface: ("docs" | "api" | "ui" | "other" | "policy" | "tests" | "workflows" | "db")[];
+            why: string;
+            acceptance: string[];
+            agentPrompt: string;
+            dependsOn?: string[] | undefined;
+        }[];
+    }, unknown>>>;
+}, z.core.$strip>;
+export declare const ProductIntentSpecModel: ZodSchemaType<z.ZodObject<{
+    id: z.ZodString;
+    meta: z.ZodObject<{
+        key: z.ZodString;
+        version: z.ZodString;
+        description: z.ZodString;
+        stability: z.ZodEnum<{
+            readonly Idea: "idea";
+            readonly InCreation: "in_creation";
+            readonly Experimental: "experimental";
+            readonly Beta: "beta";
+            readonly Stable: "stable";
+            readonly Deprecated: "deprecated";
+        }>;
+        owners: z.ZodArray<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        docId: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        goal: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    question: z.ZodString;
+    runtimeContext: z.ZodOptional<z.ZodUnknown>;
+    findings: z.ZodOptional<z.ZodType<{
+        findings: {
+            findingId: string;
+            summary: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        findings: {
+            findingId: string;
+            summary: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+        }[];
+    }, unknown>>>;
+    insights: z.ZodOptional<z.ZodType<{
+        insights: {
+            insightId: string;
+            claim: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+            segment?: string | undefined;
+            confidence?: number | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        insights: {
+            insightId: string;
+            claim: string;
+            citations: {
+                chunkId: string;
+                quote: string;
+            }[];
+            tags?: string[] | undefined;
+            segment?: string | undefined;
+            confidence?: number | undefined;
+        }[];
+    }, unknown>>>;
+    problems: z.ZodOptional<z.ZodType<{
+        problems: {
+            problemId: string;
+            statement: string;
+            evidenceIds: string[];
+            tags?: string[] | undefined;
+            severity?: "high" | "medium" | "low" | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        problems: {
+            problemId: string;
+            statement: string;
+            evidenceIds: string[];
+            tags?: string[] | undefined;
+            severity?: "high" | "medium" | "low" | undefined;
+        }[];
+    }, unknown>>>;
+    brief: z.ZodOptional<z.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: "high" | "medium" | "low";
+        risks?: {
+            text: string;
+            citations?: {
+                chunkId: string;
+                quote: string;
+            }[] | undefined;
+        }[] | undefined;
+    }, unknown, z.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: "high" | "medium" | "low";
+        risks?: {
+            text: string;
+            citations?: {
+                chunkId: string;
+                quote: string;
+            }[] | undefined;
+        }[] | undefined;
+    }, unknown>>>;
+    tickets: z.ZodOptional<z.ZodType<{
+        tickets: {
+            ticketId: string;
+            title: string;
+            summary: string;
+            evidenceIds: string[];
+            acceptanceCriteria: string[];
+            priority?: "high" | "medium" | "low" | undefined;
+            tags?: string[] | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        tickets: {
+            ticketId: string;
+            title: string;
+            summary: string;
+            evidenceIds: string[];
+            acceptanceCriteria: string[];
+            priority?: "high" | "medium" | "low" | undefined;
+            tags?: string[] | undefined;
+        }[];
+    }, unknown>>>;
+    patchIntent: z.ZodOptional<z.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.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.ZodOptional<z.ZodType<{
+        overlay: {
+            adds?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            updates?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            removes?: {
+                path: string;
+            }[] | undefined;
+        };
+    }, unknown, z.core.$ZodTypeInternals<{
+        overlay: {
+            adds?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            updates?: {
+                path: string;
+                value: unknown;
+            }[] | undefined;
+            removes?: {
+                path: string;
+            }[] | undefined;
+        };
+    }, unknown>>>;
+    impact: z.ZodOptional<z.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.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.ZodOptional<z.ZodType<{
+        packId: string;
+        patchId: string;
+        overview: string;
+        tasks: {
+            id: string;
+            title: string;
+            surface: ("docs" | "api" | "ui" | "other" | "policy" | "tests" | "workflows" | "db")[];
+            why: string;
+            acceptance: string[];
+            agentPrompt: string;
+            dependsOn?: string[] | undefined;
+        }[];
+    }, unknown, z.core.$ZodTypeInternals<{
+        packId: string;
+        patchId: string;
+        overview: string;
+        tasks: {
+            id: string;
+            title: string;
+            surface: ("docs" | "api" | "ui" | "other" | "policy" | "tests" | "workflows" | "db")[];
+            why: string;
+            acceptance: string[];
+            agentPrompt: string;
+            dependsOn?: string[] | undefined;
+        }[];
+    }, unknown>>>;
+}, z.core.$strip>>;
+export type ProductIntentSpecData = z.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.
+ */
+export interface ProductIntentMeta extends OwnerShipMeta {
+    goal?: string;
+    context?: string;
+}
+export 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.
+ */
+export declare function defineProductIntentSpec<Context = unknown>(spec: ProductIntentSpec<Context>): ProductIntentSpec<Context>;
+export {};