@lucern/contracts 0.1.0 → 0.1.2-alpha.1

package/dist/lens-filter.contract.d.ts

@@ -21,7 +21,7 @@
  *
  * V2 will add `propertyMatchers` here for arbitrary JSON Schema facet queries.
  */
-export type EntityTypeFilterV1 = {
+type EntityTypeFilterV1 = {
     /** References ontologyVersion.entityTypes[].value, e.g. "company" */
     entityTypeValue: string;
     /** Optional subtype narrowing. If omitted or empty, all subtypes match. */
@@ -31,14 +31,14 @@ export type EntityTypeFilterV1 = {
  * Optional scope to restrict which ontology the filter resolves against.
  * If omitted, resolution uses whatever ontology is active in the workspace.
  */
-export type OntologyScope = {
+type OntologyScope = {
     /** Restrict to a specific ontology by key, e.g. "vc-investment" */
     ontologyKey?: string;
 };
 /**
  * Taxonomy filter criteria v1: entity type + subtype matching over ontology.
  */
-export type TaxonomyFilterCriteriaV1 = {
+type TaxonomyFilterCriteriaV1 = {
     version: 1;
     kind: "taxonomy";
     entityTypeFilters: EntityTypeFilterV1[];
@@ -54,10 +54,10 @@ export type TaxonomyFilterCriteriaV1 = {
  *   3. Add a resolver in taxonomy-filter.ts
  *   4. No schema migration needed — filterCriteria is v.any()
  */
-export type LensFilterCriteria = TaxonomyFilterCriteriaV1;
-export declare function isLensFilterCriteria(value: unknown): value is LensFilterCriteria;
-export declare function isTaxonomyFilterCriteriaV1(value: unknown): value is TaxonomyFilterCriteriaV1;
-export type FilterValidationResult = {
+type LensFilterCriteria = TaxonomyFilterCriteriaV1;
+declare function isLensFilterCriteria(value: unknown): value is LensFilterCriteria;
+declare function isTaxonomyFilterCriteriaV1(value: unknown): value is TaxonomyFilterCriteriaV1;
+type FilterValidationResult = {
     valid: true;
 } | {
     valid: false;
@@ -67,5 +67,6 @@ export type FilterValidationResult = {
  * Validate a filter criteria document at the contract layer.
  * This runs before persisting to Convex.
  */
-export declare function validateFilterCriteria(value: unknown): FilterValidationResult;
-//# sourceMappingURL=lens-filter.contract.d.ts.map
+declare function validateFilterCriteria(value: unknown): FilterValidationResult;
+
+export { type EntityTypeFilterV1, type FilterValidationResult, type LensFilterCriteria, type OntologyScope, type TaxonomyFilterCriteriaV1, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, validateFilterCriteria };

package/dist/lens-filter.contract.js

@@ -1,96 +1,71 @@
-/**
- * Lens Filter Criteria Contract
- *
- * Version-discriminated filter DSL for lenses. Each filter criteria document
- * carries a `version` and `kind` discriminator so future shapes can coexist
- * without schema migrations. The Convex `filterCriteria` field remains v.any()
- * — all type enforcement happens here at the TypeScript contract layer.
- *
- * Forward-compatibility guarantees:
- * - `version` field: new versions add fields, never remove or rename existing ones
- * - `kind` field: new filter kinds (temporal, confidence-range) can be added
- *   without touching taxonomy code paths
- * - `entityTypeFilters` array items are open to extension in future versions
- * - Resolution logic switches on `version` + `kind` to select the right resolver
- *
- * @module lucern/contracts/src/lens-filter
- */
-// Future: | TemporalFilterCriteriaV1 | ConfidenceRangeFilterCriteriaV1 | ...
-// ---------------------------------------------------------------------------
-// Type guards
-// ---------------------------------------------------------------------------
-export function isLensFilterCriteria(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const obj = value;
-    return typeof obj.version === "number" && typeof obj.kind === "string";
+// src/lens-filter.contract.ts
+function isLensFilterCriteria(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return typeof obj.version === "number" && typeof obj.kind === "string";
 }
-export function isTaxonomyFilterCriteriaV1(value) {
-    if (!isLensFilterCriteria(value))
-        return false;
-    return value.version === 1 && value.kind === "taxonomy";
+function isTaxonomyFilterCriteriaV1(value) {
+  if (!isLensFilterCriteria(value)) return false;
+  return value.version === 1 && value.kind === "taxonomy";
 }
-/**
- * Validate a filter criteria document at the contract layer.
- * This runs before persisting to Convex.
- */
-export function validateFilterCriteria(value) {
-    if (value === undefined || value === null) {
-        return { valid: true }; // filterCriteria is optional
-    }
-    if (!isLensFilterCriteria(value)) {
-        return {
-            valid: false,
-            errors: [
-                'filterCriteria must have numeric "version" and string "kind" fields',
-            ],
-        };
-    }
-    if (isTaxonomyFilterCriteriaV1(value)) {
-        return validateTaxonomyFilterV1(value);
-    }
-    // Cast to access properties — TypeScript narrows to `never` when all union
-    // members are exhausted, but at runtime unknown version/kind combos are possible.
-    const raw = value;
+function validateFilterCriteria(value) {
+  if (value === void 0 || value === null) {
+    return { valid: true };
+  }
+  if (!isLensFilterCriteria(value)) {
     return {
-        valid: false,
-        errors: [
-            `Unsupported filter criteria: version=${raw.version}, kind=${raw.kind}`,
-        ],
+      valid: false,
+      errors: [
+        'filterCriteria must have numeric "version" and string "kind" fields'
+      ]
     };
+  }
+  if (isTaxonomyFilterCriteriaV1(value)) {
+    return validateTaxonomyFilterV1(value);
+  }
+  const raw = value;
+  return {
+    valid: false,
+    errors: [
+      `Unsupported filter criteria: version=${raw.version}, kind=${raw.kind}`
+    ]
+  };
 }
 function validateTaxonomyFilterV1(criteria) {
-    const errors = [];
-    if (!Array.isArray(criteria.entityTypeFilters)) {
-        errors.push("entityTypeFilters must be an array");
-        return { valid: false, errors };
+  const errors = [];
+  if (!Array.isArray(criteria.entityTypeFilters)) {
+    errors.push("entityTypeFilters must be an array");
+    return { valid: false, errors };
+  }
+  if (criteria.entityTypeFilters.length === 0) {
+    errors.push("entityTypeFilters must contain at least one entry");
+    return { valid: false, errors };
+  }
+  for (let i = 0; i < criteria.entityTypeFilters.length; i++) {
+    const filter = criteria.entityTypeFilters[i];
+    if (!filter || typeof filter.entityTypeValue !== "string") {
+      errors.push(
+        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`
+      );
+      continue;
     }
-    if (criteria.entityTypeFilters.length === 0) {
-        errors.push("entityTypeFilters must contain at least one entry");
-        return { valid: false, errors };
+    if (filter.entityTypeValue.trim().length === 0) {
+      errors.push(
+        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`
+      );
     }
-    for (let i = 0; i < criteria.entityTypeFilters.length; i++) {
-        const filter = criteria.entityTypeFilters[i];
-        if (!filter || typeof filter.entityTypeValue !== "string") {
-            errors.push(`entityTypeFilters[${i}].entityTypeValue must be a non-empty string`);
-            continue;
-        }
-        if (filter.entityTypeValue.trim().length === 0) {
-            errors.push(`entityTypeFilters[${i}].entityTypeValue must be a non-empty string`);
-        }
-        if (filter.subtypeValues !== undefined &&
-            !Array.isArray(filter.subtypeValues)) {
-            errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);
-        }
+    if (filter.subtypeValues !== void 0 && !Array.isArray(filter.subtypeValues)) {
+      errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);
     }
-    if (criteria.ontologyScope !== undefined) {
-        if (typeof criteria.ontologyScope !== "object" ||
-            criteria.ontologyScope === null) {
-            errors.push("ontologyScope must be an object");
-        }
+  }
+  if (criteria.ontologyScope !== void 0) {
+    if (typeof criteria.ontologyScope !== "object" || criteria.ontologyScope === null) {
+      errors.push("ontologyScope must be an object");
     }
-    return errors.length === 0
-        ? { valid: true }
-        : { valid: false, errors };
+  }
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
 }
+
+export { isLensFilterCriteria, isTaxonomyFilterCriteriaV1, validateFilterCriteria };
+//# sourceMappingURL=lens-filter.contract.js.map
 //# sourceMappingURL=lens-filter.contract.js.map

package/dist/lens-filter.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"lens-filter.contract.js","sourceRoot":"","sources":["../src/lens-filter.contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"sources":["../src/lens-filter.contract.ts"],"names":[],"mappings":"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","file":"lens-filter.contract.js","sourcesContent":["/**\n * Lens Filter Criteria Contract\n *\n * Version-discriminated filter DSL for lenses. Each filter criteria document\n * carries a `version` and `kind` discriminator so future shapes can coexist\n * without schema migrations. The Convex `filterCriteria` field remains v.any()\n * — all type enforcement happens here at the TypeScript contract layer.\n *\n * Forward-compatibility guarantees:\n * - `version` field: new versions add fields, never remove or rename existing ones\n * - `kind` field: new filter kinds (temporal, confidence-range) can be added\n *   without touching taxonomy code paths\n * - `entityTypeFilters` array items are open to extension in future versions\n * - Resolution logic switches on `version` + `kind` to select the right resolver\n *\n * @module lucern/contracts/src/lens-filter\n */\n\n// ---------------------------------------------------------------------------\n// V1: Taxonomy Filter — entity type + subtype matching\n// ---------------------------------------------------------------------------\n\n/**\n * A single entity type filter entry. Matches nodes whose `nodeType` equals\n * `entityTypeValue`, optionally further narrowed by subtype membership.\n *\n * V2 will add `propertyMatchers` here for arbitrary JSON Schema facet queries.\n */\nexport type EntityTypeFilterV1 = {\n  /** References ontologyVersion.entityTypes[].value, e.g. \"company\" */\n  entityTypeValue: string;\n\n  /** Optional subtype narrowing. If omitted or empty, all subtypes match. */\n  subtypeValues?: string[];\n};\n\n/**\n * Optional scope to restrict which ontology the filter resolves against.\n * If omitted, resolution uses whatever ontology is active in the workspace.\n */\nexport type OntologyScope = {\n  /** Restrict to a specific ontology by key, e.g. \"vc-investment\" */\n  ontologyKey?: string;\n};\n\n/**\n * Taxonomy filter criteria v1: entity type + subtype matching over ontology.\n */\nexport type TaxonomyFilterCriteriaV1 = {\n  version: 1;\n  kind: \"taxonomy\";\n  entityTypeFilters: EntityTypeFilterV1[];\n  ontologyScope?: OntologyScope;\n};\n\n// ---------------------------------------------------------------------------\n// Union: All filter criteria versions and kinds\n// ---------------------------------------------------------------------------\n\n/**\n * Discriminated union of all supported filter criteria.\n * Resolution logic switches on `version` + `kind`.\n *\n * To add a new filter kind:\n *   1. Define a new type (e.g., TemporalFilterCriteriaV1)\n *   2. Add it to this union\n *   3. Add a resolver in taxonomy-filter.ts\n *   4. No schema migration needed — filterCriteria is v.any()\n */\nexport type LensFilterCriteria = TaxonomyFilterCriteriaV1;\n// Future: | TemporalFilterCriteriaV1 | ConfidenceRangeFilterCriteriaV1 | ...\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\nexport function isLensFilterCriteria(\n  value: unknown\n): value is LensFilterCriteria {\n  if (!value || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  return typeof obj.version === \"number\" && typeof obj.kind === \"string\";\n}\n\nexport function isTaxonomyFilterCriteriaV1(\n  value: unknown\n): value is TaxonomyFilterCriteriaV1 {\n  if (!isLensFilterCriteria(value)) return false;\n  return value.version === 1 && value.kind === \"taxonomy\";\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nexport type FilterValidationResult =\n  | { valid: true }\n  | { valid: false; errors: string[] };\n\n/**\n * Validate a filter criteria document at the contract layer.\n * This runs before persisting to Convex.\n */\nexport function validateFilterCriteria(\n  value: unknown\n): FilterValidationResult {\n  if (value === undefined || value === null) {\n    return { valid: true }; // filterCriteria is optional\n  }\n\n  if (!isLensFilterCriteria(value)) {\n    return {\n      valid: false,\n      errors: [\n        'filterCriteria must have numeric \"version\" and string \"kind\" fields',\n      ],\n    };\n  }\n\n  if (isTaxonomyFilterCriteriaV1(value)) {\n    return validateTaxonomyFilterV1(value);\n  }\n\n  // Cast to access properties — TypeScript narrows to `never` when all union\n  // members are exhausted, but at runtime unknown version/kind combos are possible.\n  const raw = value as { version: number; kind: string };\n  return {\n    valid: false,\n    errors: [\n      `Unsupported filter criteria: version=${raw.version}, kind=${raw.kind}`,\n    ],\n  };\n}\n\nfunction validateTaxonomyFilterV1(\n  criteria: TaxonomyFilterCriteriaV1\n): FilterValidationResult {\n  const errors: string[] = [];\n\n  if (!Array.isArray(criteria.entityTypeFilters)) {\n    errors.push(\"entityTypeFilters must be an array\");\n    return { valid: false, errors };\n  }\n\n  if (criteria.entityTypeFilters.length === 0) {\n    errors.push(\"entityTypeFilters must contain at least one entry\");\n    return { valid: false, errors };\n  }\n\n  for (let i = 0; i < criteria.entityTypeFilters.length; i++) {\n    const filter = criteria.entityTypeFilters[i];\n    if (!filter || typeof filter.entityTypeValue !== \"string\") {\n      errors.push(\n        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`\n      );\n      continue;\n    }\n    if (filter.entityTypeValue.trim().length === 0) {\n      errors.push(\n        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`\n      );\n    }\n    if (\n      filter.subtypeValues !== undefined &&\n      !Array.isArray(filter.subtypeValues)\n    ) {\n      errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);\n    }\n  }\n\n  if (criteria.ontologyScope !== undefined) {\n    if (\n      typeof criteria.ontologyScope !== \"object\" ||\n      criteria.ontologyScope === null\n    ) {\n      errors.push(\"ontologyScope must be an object\");\n    }\n  }\n\n  return errors.length === 0\n    ? { valid: true }\n    : { valid: false, errors };\n}\n"]}

package/dist/lens-workflow.contract.d.ts

@@ -1,16 +1,17 @@
+export { EntityTypeFilterV1, FilterValidationResult, LensFilterCriteria, OntologyScope, TaxonomyFilterCriteriaV1, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, validateFilterCriteria } from './lens-filter.contract.js';
+
 /**
  * Canonical lens workflow contract shared across schema, SDK, and MCP surfaces.
  */
-export type { LensFilterCriteria, TaxonomyFilterCriteriaV1, EntityTypeFilterV1, OntologyScope, FilterValidationResult, } from "./lens-filter.contract";
-export { validateFilterCriteria, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, } from "./lens-filter.contract";
-export declare const LENS_PERSPECTIVE_TYPES: readonly ["investigation", "monitoring", "analysis", "comparison", "taxonomy"];
-export type LensPerspectiveType = (typeof LENS_PERSPECTIVE_TYPES)[number];
-export declare const LENS_STATUSES: readonly ["draft", "active", "archived"];
-export type LensStatus = (typeof LENS_STATUSES)[number];
-export declare const LENS_TASK_TEMPLATE_PRIORITIES: readonly ["critical", "high", "medium", "low"];
-export type LensTaskTemplatePriority = (typeof LENS_TASK_TEMPLATE_PRIORITIES)[number];
-export type LensLooseMetadata = Record<string, unknown>;
-export type LensPromptTemplateReference = {
+
+declare const LENS_PERSPECTIVE_TYPES: readonly ["investigation", "monitoring", "analysis", "comparison", "taxonomy"];
+type LensPerspectiveType = (typeof LENS_PERSPECTIVE_TYPES)[number];
+declare const LENS_STATUSES: readonly ["draft", "active", "archived"];
+type LensStatus = (typeof LENS_STATUSES)[number];
+declare const LENS_TASK_TEMPLATE_PRIORITIES: readonly ["critical", "high", "medium", "low"];
+type LensTaskTemplatePriority = (typeof LENS_TASK_TEMPLATE_PRIORITIES)[number];
+type LensLooseMetadata = Record<string, unknown>;
+type LensPromptTemplateReference = {
     key: string;
     promptRef: string;
     phase?: string;
@@ -19,7 +20,7 @@ export type LensPromptTemplateReference = {
     required?: boolean;
     metadata?: LensLooseMetadata;
 };
-export type LensWorkflowStepTemplate = {
+type LensWorkflowStepTemplate = {
     key: string;
     title: string;
     description?: string;
@@ -27,14 +28,14 @@ export type LensWorkflowStepTemplate = {
     taskTemplateKeys?: string[];
     metadata?: LensLooseMetadata;
 };
-export type LensWorkflowTemplate = {
+type LensWorkflowTemplate = {
     key: string;
     name: string;
     description?: string;
     steps: LensWorkflowStepTemplate[];
     metadata?: LensLooseMetadata;
 };
-export type LensTaskTemplate = {
+type LensTaskTemplate = {
     key: string;
     title: string;
     description?: string;
@@ -42,14 +43,14 @@ export type LensTaskTemplate = {
     phase?: string;
     metadata?: LensLooseMetadata;
 };
-export type LensQuestionTemplate = {
+type LensQuestionTemplate = {
     key: string;
     text: string;
     priority?: LensTaskTemplatePriority;
     linkedBeliefKey?: string;
     metadata?: LensLooseMetadata;
 };
-export type LensBranchMigrationSuggestion = {
+type LensBranchMigrationSuggestion = {
     recommendedTool: "create_lens";
     perspectiveType: LensPerspectiveType;
     message: string;
@@ -61,25 +62,26 @@ export type LensBranchMigrationSuggestion = {
         perspectiveType: LensPerspectiveType;
     };
 };
-export declare const BRANCH_DEPRECATION_MESSAGE = "Branches are deprecated for operational framing. Create a workspace-scoped lens instead.";
-export type DeprecatedBranchMetadata = {
+declare const BRANCH_DEPRECATION_MESSAGE = "Branches are deprecated for operational framing. Create a workspace-scoped lens instead.";
+type DeprecatedBranchMetadata = {
     deprecated: true;
     deprecationMessage: string;
     lensSuggestion: LensBranchMigrationSuggestion;
 };
-export declare function inferLensPerspectiveTypeFromBranchSchema(schema?: string | null): LensPerspectiveType;
-export declare function migrateBranchToLens(args: {
+declare function inferLensPerspectiveTypeFromBranchSchema(schema?: string | null): LensPerspectiveType;
+declare function migrateBranchToLens(args: {
     name: string;
     description?: string;
     topicId?: string;
     workspaceId?: string;
     schema?: string | null;
 }): LensBranchMigrationSuggestion;
-export declare function buildDeprecatedBranchMetadata(args: {
+declare function buildDeprecatedBranchMetadata(args: {
     name: string;
     description?: string;
     topicId?: string;
     workspaceId?: string;
     schema?: string | null;
 }): DeprecatedBranchMetadata;
-//# sourceMappingURL=lens-workflow.contract.d.ts.map
+
+export { BRANCH_DEPRECATION_MESSAGE, type DeprecatedBranchMetadata, LENS_PERSPECTIVE_TYPES, LENS_STATUSES, LENS_TASK_TEMPLATE_PRIORITIES, type LensBranchMigrationSuggestion, type LensLooseMetadata, type LensPerspectiveType, type LensPromptTemplateReference, type LensQuestionTemplate, type LensStatus, type LensTaskTemplate, type LensTaskTemplatePriority, type LensWorkflowStepTemplate, type LensWorkflowTemplate, buildDeprecatedBranchMetadata, inferLensPerspectiveTypeFromBranchSchema, migrateBranchToLens };

package/dist/lens-workflow.contract.js

@@ -1,55 +1,123 @@
-/**
- * Canonical lens workflow contract shared across schema, SDK, and MCP surfaces.
- */
-export { validateFilterCriteria, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, } from "./lens-filter.contract";
-export const LENS_PERSPECTIVE_TYPES = [
-    "investigation",
-    "monitoring",
-    "analysis",
-    "comparison",
-    "taxonomy",
-];
-export const LENS_STATUSES = ["draft", "active", "archived"];
-export const LENS_TASK_TEMPLATE_PRIORITIES = [
-    "critical",
-    "high",
-    "medium",
-    "low",
-];
-export const BRANCH_DEPRECATION_MESSAGE = "Branches are deprecated for operational framing. Create a workspace-scoped lens instead.";
-export function inferLensPerspectiveTypeFromBranchSchema(schema) {
-    const normalized = schema?.trim().toLowerCase();
-    if (normalized === "phase") {
-        return "monitoring";
+// src/lens-filter.contract.ts
+function isLensFilterCriteria(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return typeof obj.version === "number" && typeof obj.kind === "string";
+}
+function isTaxonomyFilterCriteriaV1(value) {
+  if (!isLensFilterCriteria(value)) return false;
+  return value.version === 1 && value.kind === "taxonomy";
+}
+function validateFilterCriteria(value) {
+  if (value === void 0 || value === null) {
+    return { valid: true };
+  }
+  if (!isLensFilterCriteria(value)) {
+    return {
+      valid: false,
+      errors: [
+        'filterCriteria must have numeric "version" and string "kind" fields'
+      ]
+    };
+  }
+  if (isTaxonomyFilterCriteriaV1(value)) {
+    return validateTaxonomyFilterV1(value);
+  }
+  const raw = value;
+  return {
+    valid: false,
+    errors: [
+      `Unsupported filter criteria: version=${raw.version}, kind=${raw.kind}`
+    ]
+  };
+}
+function validateTaxonomyFilterV1(criteria) {
+  const errors = [];
+  if (!Array.isArray(criteria.entityTypeFilters)) {
+    errors.push("entityTypeFilters must be an array");
+    return { valid: false, errors };
+  }
+  if (criteria.entityTypeFilters.length === 0) {
+    errors.push("entityTypeFilters must contain at least one entry");
+    return { valid: false, errors };
+  }
+  for (let i = 0; i < criteria.entityTypeFilters.length; i++) {
+    const filter = criteria.entityTypeFilters[i];
+    if (!filter || typeof filter.entityTypeValue !== "string") {
+      errors.push(
+        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`
+      );
+      continue;
+    }
+    if (filter.entityTypeValue.trim().length === 0) {
+      errors.push(
+        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`
+      );
     }
-    if (normalized === "axis" || normalized === "dimension") {
-        return "comparison";
+    if (filter.subtypeValues !== void 0 && !Array.isArray(filter.subtypeValues)) {
+      errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);
     }
-    if (normalized === "track") {
-        return "investigation";
+  }
+  if (criteria.ontologyScope !== void 0) {
+    if (typeof criteria.ontologyScope !== "object" || criteria.ontologyScope === null) {
+      errors.push("ontologyScope must be an object");
     }
-    return "analysis";
+  }
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
 }
-export function migrateBranchToLens(args) {
-    const perspectiveType = inferLensPerspectiveTypeFromBranchSchema(args.schema);
-    return {
-        recommendedTool: "create_lens",
-        perspectiveType,
-        message: "Branches are deprecated for operational framing. Create a workspace-scoped lens with the suggested payload instead.",
-        suggestedPayload: {
-            name: args.name,
-            description: args.description,
-            topicId: args.topicId,
-            workspaceId: args.workspaceId,
-            perspectiveType,
-        },
-    };
+
+// src/lens-workflow.contract.ts
+var LENS_PERSPECTIVE_TYPES = [
+  "investigation",
+  "monitoring",
+  "analysis",
+  "comparison",
+  "taxonomy"
+];
+var LENS_STATUSES = ["draft", "active", "archived"];
+var LENS_TASK_TEMPLATE_PRIORITIES = [
+  "critical",
+  "high",
+  "medium",
+  "low"
+];
+var BRANCH_DEPRECATION_MESSAGE = "Branches are deprecated for operational framing. Create a workspace-scoped lens instead.";
+function inferLensPerspectiveTypeFromBranchSchema(schema) {
+  const normalized = schema?.trim().toLowerCase();
+  if (normalized === "phase") {
+    return "monitoring";
+  }
+  if (normalized === "axis" || normalized === "dimension") {
+    return "comparison";
+  }
+  if (normalized === "track") {
+    return "investigation";
+  }
+  return "analysis";
 }
-export function buildDeprecatedBranchMetadata(args) {
-    return {
-        deprecated: true,
-        deprecationMessage: BRANCH_DEPRECATION_MESSAGE,
-        lensSuggestion: migrateBranchToLens(args),
-    };
+function migrateBranchToLens(args) {
+  const perspectiveType = inferLensPerspectiveTypeFromBranchSchema(args.schema);
+  return {
+    recommendedTool: "create_lens",
+    perspectiveType,
+    message: "Branches are deprecated for operational framing. Create a workspace-scoped lens with the suggested payload instead.",
+    suggestedPayload: {
+      name: args.name,
+      description: args.description,
+      topicId: args.topicId,
+      workspaceId: args.workspaceId,
+      perspectiveType
+    }
+  };
+}
+function buildDeprecatedBranchMetadata(args) {
+  return {
+    deprecated: true,
+    deprecationMessage: BRANCH_DEPRECATION_MESSAGE,
+    lensSuggestion: migrateBranchToLens(args)
+  };
 }
+
+export { BRANCH_DEPRECATION_MESSAGE, LENS_PERSPECTIVE_TYPES, LENS_STATUSES, LENS_TASK_TEMPLATE_PRIORITIES, buildDeprecatedBranchMetadata, inferLensPerspectiveTypeFromBranchSchema, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, migrateBranchToLens, validateFilterCriteria };
+//# sourceMappingURL=lens-workflow.contract.js.map
 //# sourceMappingURL=lens-workflow.contract.js.map

package/dist/lens-workflow.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"lens-workflow.contract.js","sourceRoot":"","sources":["../src/lens-workflow.contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,wBAAwB,CAAC;AAEhC,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,eAAe;IACf,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,UAAU;CACF,CAAC;AAIX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC;AAItE,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,UAAU;IACV,MAAM;IACN,QAAQ;IACR,KAAK;CACG,CAAC;AAgEX,MAAM,CAAC,MAAM,0BAA0B,GACrC,0FAA0F,CAAC;AAQ7F,MAAM,UAAU,wCAAwC,CACtD,MAAsB;IAEtB,MAAM,UAAU,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAChD,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;QACxD,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,IAAI,UAAU,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAMnC;IACC,MAAM,eAAe,GAAG,wCAAwC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9E,OAAO;QACL,eAAe,EAAE,aAAa;QAC9B,eAAe;QACf,OAAO,EACL,qHAAqH;QACvH,gBAAgB,EAAE;YAChB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,eAAe;SAChB;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,IAM7C;IACC,OAAO;QACL,UAAU,EAAE,IAAI;QAChB,kBAAkB,EAAE,0BAA0B;QAC9C,cAAc,EAAE,mBAAmB,CAAC,IAAI,CAAC;KAC1C,CAAC;AACJ,CAAC"}
+{"version":3,"sources":["../src/lens-filter.contract.ts","../src/lens-workflow.contract.ts"],"names":[],"mappings":"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","file":"lens-workflow.contract.js","sourcesContent":["/**\n * Lens Filter Criteria Contract\n *\n * Version-discriminated filter DSL for lenses. Each filter criteria document\n * carries a `version` and `kind` discriminator so future shapes can coexist\n * without schema migrations. The Convex `filterCriteria` field remains v.any()\n * — all type enforcement happens here at the TypeScript contract layer.\n *\n * Forward-compatibility guarantees:\n * - `version` field: new versions add fields, never remove or rename existing ones\n * - `kind` field: new filter kinds (temporal, confidence-range) can be added\n *   without touching taxonomy code paths\n * - `entityTypeFilters` array items are open to extension in future versions\n * - Resolution logic switches on `version` + `kind` to select the right resolver\n *\n * @module lucern/contracts/src/lens-filter\n */\n\n// ---------------------------------------------------------------------------\n// V1: Taxonomy Filter — entity type + subtype matching\n// ---------------------------------------------------------------------------\n\n/**\n * A single entity type filter entry. Matches nodes whose `nodeType` equals\n * `entityTypeValue`, optionally further narrowed by subtype membership.\n *\n * V2 will add `propertyMatchers` here for arbitrary JSON Schema facet queries.\n */\nexport type EntityTypeFilterV1 = {\n  /** References ontologyVersion.entityTypes[].value, e.g. \"company\" */\n  entityTypeValue: string;\n\n  /** Optional subtype narrowing. If omitted or empty, all subtypes match. */\n  subtypeValues?: string[];\n};\n\n/**\n * Optional scope to restrict which ontology the filter resolves against.\n * If omitted, resolution uses whatever ontology is active in the workspace.\n */\nexport type OntologyScope = {\n  /** Restrict to a specific ontology by key, e.g. \"vc-investment\" */\n  ontologyKey?: string;\n};\n\n/**\n * Taxonomy filter criteria v1: entity type + subtype matching over ontology.\n */\nexport type TaxonomyFilterCriteriaV1 = {\n  version: 1;\n  kind: \"taxonomy\";\n  entityTypeFilters: EntityTypeFilterV1[];\n  ontologyScope?: OntologyScope;\n};\n\n// ---------------------------------------------------------------------------\n// Union: All filter criteria versions and kinds\n// ---------------------------------------------------------------------------\n\n/**\n * Discriminated union of all supported filter criteria.\n * Resolution logic switches on `version` + `kind`.\n *\n * To add a new filter kind:\n *   1. Define a new type (e.g., TemporalFilterCriteriaV1)\n *   2. Add it to this union\n *   3. Add a resolver in taxonomy-filter.ts\n *   4. No schema migration needed — filterCriteria is v.any()\n */\nexport type LensFilterCriteria = TaxonomyFilterCriteriaV1;\n// Future: | TemporalFilterCriteriaV1 | ConfidenceRangeFilterCriteriaV1 | ...\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\nexport function isLensFilterCriteria(\n  value: unknown\n): value is LensFilterCriteria {\n  if (!value || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  return typeof obj.version === \"number\" && typeof obj.kind === \"string\";\n}\n\nexport function isTaxonomyFilterCriteriaV1(\n  value: unknown\n): value is TaxonomyFilterCriteriaV1 {\n  if (!isLensFilterCriteria(value)) return false;\n  return value.version === 1 && value.kind === \"taxonomy\";\n}\n\n// ---------------------------------------------------------------------------\n// Validation\n// ---------------------------------------------------------------------------\n\nexport type FilterValidationResult =\n  | { valid: true }\n  | { valid: false; errors: string[] };\n\n/**\n * Validate a filter criteria document at the contract layer.\n * This runs before persisting to Convex.\n */\nexport function validateFilterCriteria(\n  value: unknown\n): FilterValidationResult {\n  if (value === undefined || value === null) {\n    return { valid: true }; // filterCriteria is optional\n  }\n\n  if (!isLensFilterCriteria(value)) {\n    return {\n      valid: false,\n      errors: [\n        'filterCriteria must have numeric \"version\" and string \"kind\" fields',\n      ],\n    };\n  }\n\n  if (isTaxonomyFilterCriteriaV1(value)) {\n    return validateTaxonomyFilterV1(value);\n  }\n\n  // Cast to access properties — TypeScript narrows to `never` when all union\n  // members are exhausted, but at runtime unknown version/kind combos are possible.\n  const raw = value as { version: number; kind: string };\n  return {\n    valid: false,\n    errors: [\n      `Unsupported filter criteria: version=${raw.version}, kind=${raw.kind}`,\n    ],\n  };\n}\n\nfunction validateTaxonomyFilterV1(\n  criteria: TaxonomyFilterCriteriaV1\n): FilterValidationResult {\n  const errors: string[] = [];\n\n  if (!Array.isArray(criteria.entityTypeFilters)) {\n    errors.push(\"entityTypeFilters must be an array\");\n    return { valid: false, errors };\n  }\n\n  if (criteria.entityTypeFilters.length === 0) {\n    errors.push(\"entityTypeFilters must contain at least one entry\");\n    return { valid: false, errors };\n  }\n\n  for (let i = 0; i < criteria.entityTypeFilters.length; i++) {\n    const filter = criteria.entityTypeFilters[i];\n    if (!filter || typeof filter.entityTypeValue !== \"string\") {\n      errors.push(\n        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`\n      );\n      continue;\n    }\n    if (filter.entityTypeValue.trim().length === 0) {\n      errors.push(\n        `entityTypeFilters[${i}].entityTypeValue must be a non-empty string`\n      );\n    }\n    if (\n      filter.subtypeValues !== undefined &&\n      !Array.isArray(filter.subtypeValues)\n    ) {\n      errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);\n    }\n  }\n\n  if (criteria.ontologyScope !== undefined) {\n    if (\n      typeof criteria.ontologyScope !== \"object\" ||\n      criteria.ontologyScope === null\n    ) {\n      errors.push(\"ontologyScope must be an object\");\n    }\n  }\n\n  return errors.length === 0\n    ? { valid: true }\n    : { valid: false, errors };\n}\n","/**\n * Canonical lens workflow contract shared across schema, SDK, and MCP surfaces.\n */\n\n// Re-export filter criteria types for consumers who import from lens-workflow\nexport type {\n  LensFilterCriteria,\n  TaxonomyFilterCriteriaV1,\n  EntityTypeFilterV1,\n  OntologyScope,\n  FilterValidationResult,\n} from \"./lens-filter.contract\";\nexport {\n  validateFilterCriteria,\n  isLensFilterCriteria,\n  isTaxonomyFilterCriteriaV1,\n} from \"./lens-filter.contract\";\n\nexport const LENS_PERSPECTIVE_TYPES = [\n  \"investigation\",\n  \"monitoring\",\n  \"analysis\",\n  \"comparison\",\n  \"taxonomy\",\n] as const;\n\nexport type LensPerspectiveType = (typeof LENS_PERSPECTIVE_TYPES)[number];\n\nexport const LENS_STATUSES = [\"draft\", \"active\", \"archived\"] as const;\n\nexport type LensStatus = (typeof LENS_STATUSES)[number];\n\nexport const LENS_TASK_TEMPLATE_PRIORITIES = [\n  \"critical\",\n  \"high\",\n  \"medium\",\n  \"low\",\n] as const;\n\nexport type LensTaskTemplatePriority =\n  (typeof LENS_TASK_TEMPLATE_PRIORITIES)[number];\n\nexport type LensLooseMetadata = Record<string, unknown>;\n\nexport type LensPromptTemplateReference = {\n  key: string;\n  promptRef: string;\n  phase?: string;\n  role?: string;\n  version?: string;\n  required?: boolean;\n  metadata?: LensLooseMetadata;\n};\n\nexport type LensWorkflowStepTemplate = {\n  key: string;\n  title: string;\n  description?: string;\n  promptTemplateKey?: string;\n  taskTemplateKeys?: string[];\n  metadata?: LensLooseMetadata;\n};\n\nexport type LensWorkflowTemplate = {\n  key: string;\n  name: string;\n  description?: string;\n  steps: LensWorkflowStepTemplate[];\n  metadata?: LensLooseMetadata;\n};\n\nexport type LensTaskTemplate = {\n  key: string;\n  title: string;\n  description?: string;\n  priority?: LensTaskTemplatePriority;\n  phase?: string;\n  metadata?: LensLooseMetadata;\n};\n\nexport type LensQuestionTemplate = {\n  key: string;\n  text: string;\n  priority?: LensTaskTemplatePriority;\n  linkedBeliefKey?: string;\n  metadata?: LensLooseMetadata;\n};\n\nexport type LensBranchMigrationSuggestion = {\n  recommendedTool: \"create_lens\";\n  perspectiveType: LensPerspectiveType;\n  message: string;\n  suggestedPayload: {\n    name: string;\n    description?: string;\n    topicId?: string;\n    workspaceId?: string;\n    perspectiveType: LensPerspectiveType;\n  };\n};\n\nexport const BRANCH_DEPRECATION_MESSAGE =\n  \"Branches are deprecated for operational framing. Create a workspace-scoped lens instead.\";\n\nexport type DeprecatedBranchMetadata = {\n  deprecated: true;\n  deprecationMessage: string;\n  lensSuggestion: LensBranchMigrationSuggestion;\n};\n\nexport function inferLensPerspectiveTypeFromBranchSchema(\n  schema?: string | null\n): LensPerspectiveType {\n  const normalized = schema?.trim().toLowerCase();\n  if (normalized === \"phase\") {\n    return \"monitoring\";\n  }\n  if (normalized === \"axis\" || normalized === \"dimension\") {\n    return \"comparison\";\n  }\n  if (normalized === \"track\") {\n    return \"investigation\";\n  }\n  return \"analysis\";\n}\n\nexport function migrateBranchToLens(args: {\n  name: string;\n  description?: string;\n  topicId?: string;\n  workspaceId?: string;\n  schema?: string | null;\n}): LensBranchMigrationSuggestion {\n  const perspectiveType = inferLensPerspectiveTypeFromBranchSchema(args.schema);\n  return {\n    recommendedTool: \"create_lens\",\n    perspectiveType,\n    message:\n      \"Branches are deprecated for operational framing. Create a workspace-scoped lens with the suggested payload instead.\",\n    suggestedPayload: {\n      name: args.name,\n      description: args.description,\n      topicId: args.topicId,\n      workspaceId: args.workspaceId,\n      perspectiveType,\n    },\n  };\n}\n\nexport function buildDeprecatedBranchMetadata(args: {\n  name: string;\n  description?: string;\n  topicId?: string;\n  workspaceId?: string;\n  schema?: string | null;\n}): DeprecatedBranchMetadata {\n  return {\n    deprecated: true,\n    deprecationMessage: BRANCH_DEPRECATION_MESSAGE,\n    lensSuggestion: migrateBranchToLens(args),\n  };\n}\n"]}