@lucern/contracts 0.1.1-alpha.1 → 0.1.2-alpha.1

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

@@ -0,0 +1,72 @@
+/**
+ * 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
+ */
+/**
+ * A single entity type filter entry. Matches nodes whose `nodeType` equals
+ * `entityTypeValue`, optionally further narrowed by subtype membership.
+ *
+ * V2 will add `propertyMatchers` here for arbitrary JSON Schema facet queries.
+ */
+type EntityTypeFilterV1 = {
+    /** References ontologyVersion.entityTypes[].value, e.g. "company" */
+    entityTypeValue: string;
+    /** Optional subtype narrowing. If omitted or empty, all subtypes match. */
+    subtypeValues?: string[];
+};
+/**
+ * Optional scope to restrict which ontology the filter resolves against.
+ * If omitted, resolution uses whatever ontology is active in the workspace.
+ */
+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.
+ */
+type TaxonomyFilterCriteriaV1 = {
+    version: 1;
+    kind: "taxonomy";
+    entityTypeFilters: EntityTypeFilterV1[];
+    ontologyScope?: OntologyScope;
+};
+/**
+ * Discriminated union of all supported filter criteria.
+ * Resolution logic switches on `version` + `kind`.
+ *
+ * To add a new filter kind:
+ *   1. Define a new type (e.g., TemporalFilterCriteriaV1)
+ *   2. Add it to this union
+ *   3. Add a resolver in taxonomy-filter.ts
+ *   4. No schema migration needed — filterCriteria is v.any()
+ */
+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;
+    errors: string[];
+};
+/**
+ * Validate a filter criteria document at the contract layer.
+ * This runs before persisting to Convex.
+ */
+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

@@ -0,0 +1,71 @@
+// 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 (filter.subtypeValues !== void 0 && !Array.isArray(filter.subtypeValues)) {
+      errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);
+    }
+  }
+  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 };
+}
+
+export { isLensFilterCriteria, isTaxonomyFilterCriteriaV1, validateFilterCriteria };
+//# sourceMappingURL=lens-filter.contract.js.map
+//# sourceMappingURL=lens-filter.contract.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,87 @@
+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.
+ */
+
+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;
+    role?: string;
+    version?: string;
+    required?: boolean;
+    metadata?: LensLooseMetadata;
+};
+type LensWorkflowStepTemplate = {
+    key: string;
+    title: string;
+    description?: string;
+    promptTemplateKey?: string;
+    taskTemplateKeys?: string[];
+    metadata?: LensLooseMetadata;
+};
+type LensWorkflowTemplate = {
+    key: string;
+    name: string;
+    description?: string;
+    steps: LensWorkflowStepTemplate[];
+    metadata?: LensLooseMetadata;
+};
+type LensTaskTemplate = {
+    key: string;
+    title: string;
+    description?: string;
+    priority?: LensTaskTemplatePriority;
+    phase?: string;
+    metadata?: LensLooseMetadata;
+};
+type LensQuestionTemplate = {
+    key: string;
+    text: string;
+    priority?: LensTaskTemplatePriority;
+    linkedBeliefKey?: string;
+    metadata?: LensLooseMetadata;
+};
+type LensBranchMigrationSuggestion = {
+    recommendedTool: "create_lens";
+    perspectiveType: LensPerspectiveType;
+    message: string;
+    suggestedPayload: {
+        name: string;
+        description?: string;
+        topicId?: string;
+        workspaceId?: string;
+        perspectiveType: LensPerspectiveType;
+    };
+};
+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;
+};
+declare function inferLensPerspectiveTypeFromBranchSchema(schema?: string | null): LensPerspectiveType;
+declare function migrateBranchToLens(args: {
+    name: string;
+    description?: string;
+    topicId?: string;
+    workspaceId?: string;
+    schema?: string | null;
+}): LensBranchMigrationSuggestion;
+declare function buildDeprecatedBranchMetadata(args: {
+    name: string;
+    description?: string;
+    topicId?: string;
+    workspaceId?: string;
+    schema?: string | null;
+}): DeprecatedBranchMetadata;
+
+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

@@ -0,0 +1,123 @@
+// 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 (filter.subtypeValues !== void 0 && !Array.isArray(filter.subtypeValues)) {
+      errors.push(`entityTypeFilters[${i}].subtypeValues must be an array`);
+    }
+  }
+  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 };
+}
+
+// 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";
+}
+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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lens-filter.contract.ts","../src/lens-workflow.contract.ts"],"names":[],"mappings":";AA4EO,SAAS,qBACd,KAAA,EAC6B;AAC7B,EAAA,IAAI,CAAC,KAAA,IAAS,OAAO,KAAA,KAAU,UAAU,OAAO,KAAA;AAChD,EAAA,MAAM,GAAA,GAAM,KAAA;AACZ,EAAA,OAAO,OAAO,GAAA,CAAI,OAAA,KAAY,QAAA,IAAY,OAAO,IAAI,IAAA,KAAS,QAAA;AAChE;AAEO,SAAS,2BACd,KAAA,EACmC;AACnC,EAAA,IAAI,CAAC,oBAAA,CAAqB,KAAK,CAAA,EAAG,OAAO,KAAA;AACzC,EAAA,OAAO,KAAA,CAAM,OAAA,KAAY,CAAA,IAAK,KAAA,CAAM,IAAA,KAAS,UAAA;AAC/C;AAcO,SAAS,uBACd,KAAA,EACwB;AACxB,EAAA,IAAI,KAAA,KAAU,MAAA,IAAa,KAAA,KAAU,IAAA,EAAM;AACzC,IAAA,OAAO,EAAE,OAAO,IAAA,EAAK;AAAA,EACvB;AAEA,EAAA,IAAI,CAAC,oBAAA,CAAqB,KAAK,CAAA,EAAG;AAChC,IAAA,OAAO;AAAA,MACL,KAAA,EAAO,KAAA;AAAA,MACP,MAAA,EAAQ;AAAA,QACN;AAAA;AACF,KACF;AAAA,EACF;AAEA,EAAA,IAAI,0BAAA,CAA2B,KAAK,CAAA,EAAG;AACrC,IAAA,OAAO,yBAAyB,KAAK,CAAA;AAAA,EACvC;AAIA,EAAA,MAAM,GAAA,GAAM,KAAA;AACZ,EAAA,OAAO;AAAA,IACL,KAAA,EAAO,KAAA;AAAA,IACP,MAAA,EAAQ;AAAA,MACN,CAAA,qCAAA,EAAwC,GAAA,CAAI,OAAO,CAAA,OAAA,EAAU,IAAI,IAAI,CAAA;AAAA;AACvE,GACF;AACF;AAEA,SAAS,yBACP,QAAA,EACwB;AACxB,EAAA,MAAM,SAAmB,EAAC;AAE1B,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,QAAA,CAAS,iBAAiB,CAAA,EAAG;AAC9C,IAAA,MAAA,CAAO,KAAK,oCAAoC,CAAA;AAChD,IAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAO;AAAA,EAChC;AAEA,EAAA,IAAI,QAAA,CAAS,iBAAA,CAAkB,MAAA,KAAW,CAAA,EAAG;AAC3C,IAAA,MAAA,CAAO,KAAK,mDAAmD,CAAA;AAC/D,IAAA,OAAO,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAO;AAAA,EAChC;AAEA,EAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,QAAA,CAAS,iBAAA,CAAkB,QAAQ,CAAA,EAAA,EAAK;AAC1D,IAAA,MAAM,MAAA,GAAS,QAAA,CAAS,iBAAA,CAAkB,CAAC,CAAA;AAC3C,IAAA,IAAI,CAAC,MAAA,IAAU,OAAO,MAAA,CAAO,oBAAoB,QAAA,EAAU;AACzD,MAAA,MAAA,CAAO,IAAA;AAAA,QACL,qBAAqB,CAAC,CAAA,4CAAA;AAAA,OACxB;AACA,MAAA;AAAA,IACF;AACA,IAAA,IAAI,MAAA,CAAO,eAAA,CAAgB,IAAA,EAAK,CAAE,WAAW,CAAA,EAAG;AAC9C,MAAA,MAAA,CAAO,IAAA;AAAA,QACL,qBAAqB,CAAC,CAAA,4CAAA;AAAA,OACxB;AAAA,IACF;AACA,IAAA,IACE,MAAA,CAAO,kBAAkB,MAAA,IACzB,CAAC,MAAM,OAAA,CAAQ,MAAA,CAAO,aAAa,CAAA,EACnC;AACA,MAAA,MAAA,CAAO,IAAA,CAAK,CAAA,kBAAA,EAAqB,CAAC,CAAA,gCAAA,CAAkC,CAAA;AAAA,IACtE;AAAA,EACF;AAEA,EAAA,IAAI,QAAA,CAAS,kBAAkB,MAAA,EAAW;AACxC,IAAA,IACE,OAAO,QAAA,CAAS,aAAA,KAAkB,QAAA,IAClC,QAAA,CAAS,kBAAkB,IAAA,EAC3B;AACA,MAAA,MAAA,CAAO,KAAK,iCAAiC,CAAA;AAAA,IAC/C;AAAA,EACF;AAEA,EAAA,OAAO,MAAA,CAAO,MAAA,KAAW,CAAA,GACrB,EAAE,KAAA,EAAO,MAAK,GACd,EAAE,KAAA,EAAO,KAAA,EAAO,MAAA,EAAO;AAC7B;;;ACpKO,IAAM,sBAAA,GAAyB;AAAA,EACpC,eAAA;AAAA,EACA,YAAA;AAAA,EACA,UAAA;AAAA,EACA,YAAA;AAAA,EACA;AACF;AAIO,IAAM,aAAA,GAAgB,CAAC,OAAA,EAAS,QAAA,EAAU,UAAU;AAIpD,IAAM,6BAAA,GAAgC;AAAA,EAC3C,UAAA;AAAA,EACA,MAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF;AAgEO,IAAM,0BAAA,GACX;AAQK,SAAS,yCACd,MAAA,EACqB;AACrB,EAAA,MAAM,UAAA,GAAa,MAAA,EAAQ,IAAA,EAAK,CAAE,WAAA,EAAY;AAC9C,EAAA,IAAI,eAAe,OAAA,EAAS;AAC1B,IAAA,OAAO,YAAA;AAAA,EACT;AACA,EAAA,IAAI,UAAA,KAAe,MAAA,IAAU,UAAA,KAAe,WAAA,EAAa;AACvD,IAAA,OAAO,YAAA;AAAA,EACT;AACA,EAAA,IAAI,eAAe,OAAA,EAAS;AAC1B,IAAA,OAAO,eAAA;AAAA,EACT;AACA,EAAA,OAAO,UAAA;AACT;AAEO,SAAS,oBAAoB,IAAA,EAMF;AAChC,EAAA,MAAM,eAAA,GAAkB,wCAAA,CAAyC,IAAA,CAAK,MAAM,CAAA;AAC5E,EAAA,OAAO;AAAA,IACL,eAAA,EAAiB,aAAA;AAAA,IACjB,eAAA;AAAA,IACA,OAAA,EACE,qHAAA;AAAA,IACF,gBAAA,EAAkB;AAAA,MAChB,MAAM,IAAA,CAAK,IAAA;AAAA,MACX,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,SAAS,IAAA,CAAK,OAAA;AAAA,MACd,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB;AAAA;AACF,GACF;AACF;AAEO,SAAS,8BAA8B,IAAA,EAMjB;AAC3B,EAAA,OAAO;AAAA,IACL,UAAA,EAAY,IAAA;AAAA,IACZ,kBAAA,EAAoB,0BAAA;AAAA,IACpB,cAAA,EAAgB,oBAAoB,IAAI;AAAA,GAC1C;AACF","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"]}