@lucern/sdk 0.2.0-alpha.4 → 0.2.0-alpha.5

package/dist/lib/platform/sdk/workflowClient.js

@@ -0,0 +1,366 @@
+import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
+import { asListItems, createListResult, mapAliasedList, mapGatewayData, normalizeTopicQuery, resolveTopicId, withTopicAlias, } from "./sdkSurface.js";
+export { LucernApiError };
+function normalizeLensQuery(value) {
+    const topicId = resolveTopicId(value);
+    return {
+        ...value,
+        ...(topicId ? { topicId } : {}),
+    };
+}
+/**
+ * Create the workflow client for lenses, legacy branches, worktrees, context,
+ * and tasks.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage branches, lenses, worktrees, topics, and tasks.
+ */
+export function createWorkflowClient(config = {}) {
+    const gateway = createGatewayRequestClient(config);
+    const client = {
+        /**
+         * List workflow branches for a topic scope.
+         */
+        async listBranches(query) {
+            return gateway.request({
+                path: `/api/platform/v1/workflow/branches${toQueryString(normalizeTopicQuery(query))}`,
+            }).then((response) => mapGatewayData(response, (data) => mapAliasedList(data, "branches")));
+        },
+        /**
+         * Create a workflow branch.
+         */
+        async createBranch(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/workflow/branches",
+                method: "POST",
+                body: normalizeTopicQuery(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * List reusable lenses for a workspace or topic scope.
+         */
+        async listLenses(query) {
+            return gateway.request({
+                path: `/api/platform/v1/workflow/lenses${toQueryString(normalizeLensQuery(query))}`,
+            }).then((response) => mapGatewayData(response, (data) => mapAliasedList(data, "lenses")));
+        },
+        /**
+         * Create a reusable workflow lens.
+         */
+        async createLens(input, idempotencyKey) {
+            const payload = normalizeLensQuery(input);
+            return gateway.request({
+                path: "/api/platform/v1/workflow/lenses",
+                method: "POST",
+                body: payload,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * Apply an existing lens to a topic.
+         */
+        async applyLensToTopic(input, idempotencyKey) {
+            const payload = normalizeLensQuery(input);
+            return gateway.request({
+                path: "/api/platform/v1/workflow/lens-bindings",
+                method: "POST",
+                body: payload,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * Remove an applied lens from a topic.
+         */
+        async removeLensFromTopic(input, idempotencyKey) {
+            const topicId = resolveTopicId(input);
+            if (!topicId) {
+                throw new LucernApiError({
+                    code: "INVALID_REQUEST",
+                    message: "topicId is required",
+                    status: 400,
+                });
+            }
+            return gateway.request({
+                path: `/api/platform/v1/workflow/lens-bindings${toQueryString({
+                    lensId: input.lensId,
+                    topicId,
+                })}`,
+                method: "DELETE",
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * List worktrees for a topic scope.
+         */
+        async listWorktrees(query) {
+            const normalized = normalizeTopicQuery(query);
+            return gateway.request({
+                path: `/api/platform/v1/worktrees${toQueryString({
+                    ...normalized,
+                    track: query.track,
+                    executionBand: query.executionBand,
+                })}`,
+            }).then((response) => mapGatewayData(response, (data) => mapAliasedList(data, "worktrees")));
+        },
+        /**
+         * List all worktrees across accessible topics.
+         */
+        async listAllWorktrees(query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/worktrees${toQueryString({
+                    status: query.status,
+                    track: query.track,
+                    executionBand: query.executionBand,
+                    limit: query.limit,
+                })}`,
+            }).then((response) => mapGatewayData(response, (data) => {
+                const record = data && typeof data === "object" && !Array.isArray(data)
+                    ? data
+                    : {};
+                const list = mapAliasedList(data, "worktrees");
+                return {
+                    ...list,
+                    ...(record.tracks &&
+                        typeof record.tracks === "object" &&
+                        !Array.isArray(record.tracks)
+                        ? { tracks: record.tracks }
+                        : {}),
+                    ...(record.bands &&
+                        typeof record.bands === "object" &&
+                        !Array.isArray(record.bands)
+                        ? { bands: record.bands }
+                        : {}),
+                };
+            }));
+        },
+        /**
+         * Create a workflow worktree.
+         */
+        async createWorktree(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/worktrees",
+                method: "POST",
+                body: normalizeTopicQuery(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * @deprecated Use createWorktree.
+         */
+        async addWorktree(input, idempotencyKey) {
+            return client.createWorktree(input, idempotencyKey);
+        },
+        /**
+         * Merge a worktree into the main belief line.
+         */
+        async merge(worktreeId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/merge`,
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Activate a planning worktree.
+         */
+        async activateWorktree(worktreeId, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/activate`,
+                method: "POST",
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * Update targeted beliefs/questions for a worktree.
+         */
+        async updateWorktreeTargets(input, idempotencyKey) {
+            const { worktreeId, ...body } = input;
+            return gateway.request({
+                path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/targets`,
+                method: "POST",
+                body,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * Mark a worktree record complete.
+         */
+        async completeWorktree(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/worktrees/complete",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Advance a worktree to its next lifecycle phase.
+         */
+        async advanceWorktreePhase(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/worktrees/advance-phase",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Force a worktree into a specific lifecycle phase.
+         */
+        async setWorktreePhase(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/worktrees/set-phase",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Patch opaque worktree state for orchestration flows.
+         */
+        async patchWorktreeState(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/worktrees/patch-state",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Batch create worktree records.
+         */
+        async bulkCreateWorktrees(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/worktrees/bulk",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Open a pull request for a worktree.
+         */
+        async openPullRequest(worktreeId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/workflow/worktrees/${encodeURIComponent(worktreeId)}/pull-request`,
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Push scored worktree findings into another context.
+         */
+        async push(worktreeId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/workflow/worktrees/${encodeURIComponent(worktreeId)}/push`,
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * List accessible topic contexts.
+         */
+        async listTopics(query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/workflow/topics${toQueryString({
+                    includeShared: typeof query.includeShared === "boolean"
+                        ? query.includeShared
+                            ? "true"
+                            : "false"
+                        : undefined,
+                    limit: query.limit,
+                })}`,
+            }).then((response) => mapGatewayData(response, (data) => {
+                const items = asListItems(data, "topics").map((item) => withTopicAlias(item));
+                const record = data && typeof data === "object"
+                    ? data
+                    : {};
+                return {
+                    ...record,
+                    ...createListResult(items, "topics"),
+                    total: typeof record.total === "number" ? record.total : items.length,
+                };
+            }));
+        },
+        /**
+         * Switch the active context by topic or project name.
+         */
+        async switchTopicContext(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/workflow/topics/switch",
+                method: "POST",
+                body: {
+                    targetTopicName: input.targetTopicName,
+                },
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
+        },
+        /**
+         * Create a workflow task.
+         */
+        async createTask(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/workflow/tasks",
+                method: "POST",
+                body: normalizeTopicQuery(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Complete a workflow task.
+         */
+        async completeTask(taskId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/workflow/tasks/${encodeURIComponent(taskId)}/complete`,
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update a workflow task.
+         */
+        async updateTask(taskId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/workflow/tasks/${encodeURIComponent(taskId)}`,
+                method: "PATCH",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * @deprecated Use createBranch.
+         */
+        async createPillar(input, idempotencyKey) {
+            return client.createBranch(input, idempotencyKey);
+        },
+        /**
+         * @deprecated Use addWorktree.
+         */
+        async createSprint(input, idempotencyKey) {
+            return client.createWorktree(input, idempotencyKey);
+        },
+        /**
+         * @deprecated Use merge.
+         */
+        async completeSprint(worktreeId, input, idempotencyKey) {
+            return client.merge(worktreeId, input, idempotencyKey);
+        },
+        /**
+         * @deprecated Use openPullRequest.
+         */
+        async requestReview(worktreeId, input, idempotencyKey) {
+            return client.openPullRequest(worktreeId, input, idempotencyKey);
+        },
+        /**
+         * @deprecated Use push.
+         */
+        async publishFindings(worktreeId, input, idempotencyKey) {
+            return client.push(worktreeId, input, idempotencyKey);
+        },
+    };
+    return client;
+}

package/dist/lucern/contracts/src/api-enums.contract.d.ts

@@ -0,0 +1,58 @@
+/**
+ * API Enum Contract Definitions
+ *
+ * Canonical enum values for all API-facing enumerations.
+ * These are co-equal with MCP contracts as external contracts.
+ * SDK types are DERIVED from these — not independently authored.
+ *
+ * CONTRACT SURFACE: Adding a new enum value is additive (non-breaking).
+ * Removing or renaming an existing value is a BREAKING CHANGE.
+ */
+/** Fork reasons — why a scored belief was branched */
+export declare const FORK_REASONS: readonly ["refinement", "contradiction_response", "scope_change", "confidence_collapse", "manual"];
+export type ForkReason = (typeof FORK_REASONS)[number];
+/** Confidence modulation triggers — what caused a confidence change */
+export declare const CONFIDENCE_TRIGGERS: readonly ["evidence_added", "contradiction_detected", "merge_outcome", "manual", "decay"];
+export type ConfidenceTrigger = (typeof CONFIDENCE_TRIGGERS)[number];
+/** Belief status — lifecycle state */
+export declare const BELIEF_STATUSES: readonly ["unscored", "scored", "archived"];
+export type BeliefStatus = (typeof BELIEF_STATUSES)[number];
+/** Reasoning methods — how an edge relationship was determined */
+export declare const REASONING_METHODS: readonly ["deductive", "inductive", "abductive", "analogical", "empirical"];
+export type ReasoningMethod = (typeof REASONING_METHODS)[number];
+/** Defeat types (Pollock taxonomy) — how a contradiction operates */
+export declare const DEFEAT_TYPES: readonly ["rebuts", "undercuts", "undermines"];
+export type DefeatType = (typeof DEFEAT_TYPES)[number];
+/** Contradiction severity levels */
+export declare const CONTRADICTION_SEVERITIES: readonly ["low", "medium", "high", "critical"];
+export type ContradictionSeverity = (typeof CONTRADICTION_SEVERITIES)[number];
+/** Contradiction resolution status */
+export declare const CONTRADICTION_STATUSES: readonly ["unresolved", "resolved", "accepted"];
+export type ContradictionStatus = (typeof CONTRADICTION_STATUSES)[number];
+/** Merge outcome types — how a worktree merge resolved */
+export declare const MERGE_OUTCOMES: readonly ["validated", "invalidated", "forked", "inconclusive"];
+export type MergeOutcome = (typeof MERGE_OUTCOMES)[number];
+/** Worktree phases — investigation lifecycle within a checked-out worktree */
+export declare const WORKTREE_PHASES: readonly ["hypothesis", "investigation", "evaluation", "resolution"];
+export type WorktreePhase = (typeof WORKTREE_PHASES)[number];
+/** Branch status — thematic branch lifecycle */
+export declare const BRANCH_STATUSES: readonly ["dormant", "active", "archived"];
+export type BranchStatus = (typeof BRANCH_STATUSES)[number];
+/** Pull request status — review lifecycle before merge */
+export declare const PULL_REQUEST_STATUSES: readonly ["pending_review", "changes_requested", "approved", "blocked"];
+export type PullRequestStatus = (typeof PULL_REQUEST_STATUSES)[number];
+/** Epistemic layers — the hierarchy of knowledge */
+export declare const EPISTEMIC_LAYERS: readonly ["L1", "L2", "L3", "L4"];
+export type EpistemicLayer = (typeof EPISTEMIC_LAYERS)[number];
+/**
+ * Judgment type — classification of the determination.
+ *
+ * Phase 1: These are new enum values for the Judgment (L4) vocabulary.
+ * The existing code uses "Decision" — these are the forward-looking terms
+ * that will eventually replace the Decision vocabulary (Phase 2-3).
+ */
+export declare const JUDGMENT_TYPES: readonly ["investment_thesis", "thesis_maturity", "contradiction_ruling", "scope_determination", "confidence_ruling"];
+export type JudgmentType = (typeof JUDGMENT_TYPES)[number];
+/** Core edge types used in the Integration Surfaces */
+export declare const INTEGRATION_EDGE_TYPES: readonly ["informs", "grounds", "answers", "contradicts", "supports", "depends_on", "derived_from", "contains", "supersedes", "tests"];
+export type IntegrationEdgeType = (typeof INTEGRATION_EDGE_TYPES)[number];

package/dist/lucern/contracts/src/api-enums.contract.js

@@ -0,0 +1,147 @@
+/**
+ * API Enum Contract Definitions
+ *
+ * Canonical enum values for all API-facing enumerations.
+ * These are co-equal with MCP contracts as external contracts.
+ * SDK types are DERIVED from these — not independently authored.
+ *
+ * CONTRACT SURFACE: Adding a new enum value is additive (non-breaking).
+ * Removing or renaming an existing value is a BREAKING CHANGE.
+ */
+// =============================================================================
+// BELIEF ENUMS
+// =============================================================================
+/** Fork reasons — why a scored belief was branched */
+export const FORK_REASONS = [
+    "refinement", // Belief text evolved based on new understanding
+    "contradiction_response", // Created in response to a detected contradiction
+    "scope_change", // Belief scope narrowed or broadened
+    "confidence_collapse", // Confidence dropped below viability threshold
+    "manual", // User-initiated fork without specific trigger
+];
+/** Confidence modulation triggers — what caused a confidence change */
+export const CONFIDENCE_TRIGGERS = [
+    "evidence_added", // New evidence bore on the belief
+    "contradiction_detected", // A contradiction was flagged involving this belief
+    "merge_outcome", // Merge scoring determined this confidence
+    "manual", // User manually adjusted confidence
+    "decay", // Time-based confidence erosion
+];
+/** Belief status — lifecycle state */
+export const BELIEF_STATUSES = [
+    "unscored", // Draft — editable in worktree (on feature branch, pre-merge)
+    "scored", // Merged — formulation frozen (merged to main)
+    "archived", // Soft-deleted — preserved in history (git rm)
+];
+// =============================================================================
+// EDGE ENUMS
+// =============================================================================
+/** Reasoning methods — how an edge relationship was determined */
+export const REASONING_METHODS = [
+    "deductive", // Logically entailed
+    "inductive", // Generalized from instances
+    "abductive", // Best explanation inference
+    "analogical", // Reasoning by analogy
+    "empirical", // Direct observation/measurement
+];
+/** Defeat types (Pollock taxonomy) — how a contradiction operates */
+export const DEFEAT_TYPES = [
+    "rebuts", // Direct contradiction — reasons for the negation
+    "undercuts", // Breaks the inference link between evidence and belief
+    "undermines", // Attacks a premise the belief depends on
+];
+/** Contradiction severity levels */
+export const CONTRADICTION_SEVERITIES = [
+    "low", // Minor tension, may not require action
+    "medium", // Moderate conflict, should be investigated
+    "high", // Significant contradiction, likely needs resolution
+    "critical", // Blocks progress — must be addressed before judgment
+];
+/** Contradiction resolution status */
+export const CONTRADICTION_STATUSES = [
+    "unresolved", // Open conflict — may persist indefinitely
+    "resolved", // Conflict addressed (one belief forked, archived, or confidence adjusted)
+    "accepted", // Explicitly accepted as irreconcilable — both beliefs maintained
+];
+// =============================================================================
+// WORKTREE ENUMS (git worktree lifecycle)
+// =============================================================================
+/** Merge outcome types — how a worktree merge resolved */
+export const MERGE_OUTCOMES = [
+    "validated", // Beliefs confirmed — clean merge to main
+    "invalidated", // Defeat recorded — confidence collapsed (merge with revert)
+    "forked", // Beliefs split into competing versions (fork from merge point)
+    "inconclusive", // Insufficient evidence — stashed (git stash)
+];
+/** Worktree phases — investigation lifecycle within a checked-out worktree */
+export const WORKTREE_PHASES = [
+    "hypothesis", // Form testable claims (write the code — commits)
+    "investigation", // Collect evidence (run the tests — more commits)
+    "evaluation", // Update credences (review the results — amend as needed)
+    "resolution", // Determine outcome (merge to main, fork, or stash)
+];
+// =============================================================================
+// BRANCH ENUMS (git branch lifecycle)
+// =============================================================================
+/** Branch status — thematic branch lifecycle */
+export const BRANCH_STATUSES = [
+    "dormant", // Branch exists but no active worktree (no one investigating)
+    "active", // At least one worktree is investigating this branch
+    "archived", // Branch retired — no longer a relevant thematic container
+];
+// =============================================================================
+// PULL REQUEST ENUMS (git pull request lifecycle)
+// =============================================================================
+/** Pull request status — review lifecycle before merge */
+export const PULL_REQUEST_STATUSES = [
+    "pending_review", // PR opened — awaiting reviewer feedback
+    "changes_requested", // Reviewer requests changes before merge
+    "approved", // Approved — ready to merge
+    "blocked", // Blocked — cannot merge until contradiction is resolved
+];
+// =============================================================================
+// LAYER ENUMS
+// =============================================================================
+/** Epistemic layers — the hierarchy of knowledge */
+export const EPISTEMIC_LAYERS = [
+    "L1", // Source — the given (vendored deps)
+    "L2", // Evidence — the interpreted (test suite)
+    "L3", // Belief — the structural (source files)
+    "L4", // Judgment — the committed (release tags)
+];
+// =============================================================================
+// JUDGMENT ENUMS (Phase 1: new vocabulary)
+// =============================================================================
+/**
+ * Judgment type — classification of the determination.
+ *
+ * Phase 1: These are new enum values for the Judgment (L4) vocabulary.
+ * The existing code uses "Decision" — these are the forward-looking terms
+ * that will eventually replace the Decision vocabulary (Phase 2-3).
+ */
+export const JUDGMENT_TYPES = [
+    "investment_thesis", // Judgment on an investment opportunity
+    "thesis_maturity", // Judgment that a thesis is ready for IC presentation
+    "contradiction_ruling", // Judgment on how to handle an irreconcilable contradiction
+    "scope_determination", // Judgment that defines or redefines investigation scope
+    "confidence_ruling", // Judgment that overrides automated confidence for policy reasons
+];
+// =============================================================================
+// SUPPORT RELATION ENUMS
+// =============================================================================
+/** Core edge types used in the Integration Surfaces */
+export const INTEGRATION_EDGE_TYPES = [
+    // Support relations
+    "informs", // Evidence bears on a belief (weight = direction/strength)
+    "grounds", // Source provides raw basis for evidence
+    "answers", // Evidence or belief resolves a question
+    // Defeat relations (Pollock) — weight carries direction
+    "contradicts", // Rebuts — direct contradiction
+    "supports", // Weight carries valence (negative = weakens/undercuts)
+    // Structural relations
+    "depends_on", // Belief B requires Belief A
+    "derived_from", // Provenance lineage
+    "contains", // Hierarchical containment
+    "supersedes", // New version replaces old (lineage)
+    "tests", // Question tests a belief
+];

package/dist/lucern/contracts/src/lens-filter.contract.js

@@ -0,0 +1,95 @@
+/**
+ * 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";
+}
+export 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;
+    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 !== 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 };
+}