@lucern/contracts 0.1.0-alpha.3 → 0.1.1-alpha.1

package/src/lens-filter.contract.ts

@@ -0,0 +1,183 @@
+/**
+ * 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
+ */
+
+// ---------------------------------------------------------------------------
+// V1: Taxonomy Filter — entity type + subtype matching
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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 = {
+  version: 1;
+  kind: "taxonomy";
+  entityTypeFilters: EntityTypeFilterV1[];
+  ontologyScope?: OntologyScope;
+};
+
+// ---------------------------------------------------------------------------
+// Union: All filter criteria versions and kinds
+// ---------------------------------------------------------------------------
+
+/**
+ * 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()
+ */
+export type LensFilterCriteria = TaxonomyFilterCriteriaV1;
+// Future: | TemporalFilterCriteriaV1 | ConfidenceRangeFilterCriteriaV1 | ...
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+export function isLensFilterCriteria(
+  value: unknown
+): value is LensFilterCriteria {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return typeof obj.version === "number" && typeof obj.kind === "string";
+}
+
+export function isTaxonomyFilterCriteriaV1(
+  value: unknown
+): value is TaxonomyFilterCriteriaV1 {
+  if (!isLensFilterCriteria(value)) return false;
+  return value.version === 1 && value.kind === "taxonomy";
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+export type FilterValidationResult =
+  | { valid: true }
+  | { valid: false; errors: string[] };
+
+/**
+ * Validate a filter criteria document at the contract layer.
+ * This runs before persisting to Convex.
+ */
+export function validateFilterCriteria(
+  value: unknown
+): FilterValidationResult {
+  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 as { version: number; kind: string };
+  return {
+    valid: false,
+    errors: [
+      `Unsupported filter criteria: version=${raw.version}, kind=${raw.kind}`,
+    ],
+  };
+}
+
+function validateTaxonomyFilterV1(
+  criteria: TaxonomyFilterCriteriaV1
+): FilterValidationResult {
+  const errors: string[] = [];
+
+  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 !== undefined &&
+      !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");
+    }
+  }
+
+  return errors.length === 0
+    ? { valid: true }
+    : { valid: false, errors };
+}

package/src/lens-workflow.contract.ts

@@ -0,0 +1,162 @@
+/**
+ * Canonical lens workflow contract shared across schema, SDK, and MCP surfaces.
+ */
+
+// Re-export filter criteria types for consumers who import from lens-workflow
+export type {
+  LensFilterCriteria,
+  TaxonomyFilterCriteriaV1,
+  EntityTypeFilterV1,
+  OntologyScope,
+  FilterValidationResult,
+} from "./lens-filter.contract";
+export {
+  validateFilterCriteria,
+  isLensFilterCriteria,
+  isTaxonomyFilterCriteriaV1,
+} from "./lens-filter.contract";
+
+export const LENS_PERSPECTIVE_TYPES = [
+  "investigation",
+  "monitoring",
+  "analysis",
+  "comparison",
+  "taxonomy",
+] as const;
+
+export type LensPerspectiveType = (typeof LENS_PERSPECTIVE_TYPES)[number];
+
+export const LENS_STATUSES = ["draft", "active", "archived"] as const;
+
+export type LensStatus = (typeof LENS_STATUSES)[number];
+
+export const LENS_TASK_TEMPLATE_PRIORITIES = [
+  "critical",
+  "high",
+  "medium",
+  "low",
+] as const;
+
+export type LensTaskTemplatePriority =
+  (typeof LENS_TASK_TEMPLATE_PRIORITIES)[number];
+
+export type LensLooseMetadata = Record<string, unknown>;
+
+export type LensPromptTemplateReference = {
+  key: string;
+  promptRef: string;
+  phase?: string;
+  role?: string;
+  version?: string;
+  required?: boolean;
+  metadata?: LensLooseMetadata;
+};
+
+export type LensWorkflowStepTemplate = {
+  key: string;
+  title: string;
+  description?: string;
+  promptTemplateKey?: string;
+  taskTemplateKeys?: string[];
+  metadata?: LensLooseMetadata;
+};
+
+export type LensWorkflowTemplate = {
+  key: string;
+  name: string;
+  description?: string;
+  steps: LensWorkflowStepTemplate[];
+  metadata?: LensLooseMetadata;
+};
+
+export type LensTaskTemplate = {
+  key: string;
+  title: string;
+  description?: string;
+  priority?: LensTaskTemplatePriority;
+  phase?: string;
+  metadata?: LensLooseMetadata;
+};
+
+export type LensQuestionTemplate = {
+  key: string;
+  text: string;
+  priority?: LensTaskTemplatePriority;
+  linkedBeliefKey?: string;
+  metadata?: LensLooseMetadata;
+};
+
+export type LensBranchMigrationSuggestion = {
+  recommendedTool: "create_lens";
+  perspectiveType: LensPerspectiveType;
+  message: string;
+  suggestedPayload: {
+    name: string;
+    description?: string;
+    topicId?: string;
+    workspaceId?: string;
+    perspectiveType: LensPerspectiveType;
+  };
+};
+
+export const BRANCH_DEPRECATION_MESSAGE =
+  "Branches are deprecated for operational framing. Create a workspace-scoped lens instead.";
+
+export type DeprecatedBranchMetadata = {
+  deprecated: true;
+  deprecationMessage: string;
+  lensSuggestion: LensBranchMigrationSuggestion;
+};
+
+export function inferLensPerspectiveTypeFromBranchSchema(
+  schema?: string | null
+): LensPerspectiveType {
+  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 migrateBranchToLens(args: {
+  name: string;
+  description?: string;
+  topicId?: string;
+  workspaceId?: string;
+  schema?: string | null;
+}): LensBranchMigrationSuggestion {
+  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,
+    },
+  };
+}
+
+export function buildDeprecatedBranchMetadata(args: {
+  name: string;
+  description?: string;
+  topicId?: string;
+  workspaceId?: string;
+  schema?: string | null;
+}): DeprecatedBranchMetadata {
+  return {
+    deprecated: true,
+    deprecationMessage: BRANCH_DEPRECATION_MESSAGE,
+    lensSuggestion: migrateBranchToLens(args),
+  };
+}