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

package/dist/lucern/contracts/src/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lucern Platform Contracts
+ *
+ * Machine-readable source of truth for all external API surfaces.
+ * Enforcement hierarchy: MCP/API (co-equal) → SDK (derived) → Schema (internal).
+ *
+ * These contracts are consumed by:
+ *   - MCP tool registration (learning-loop module)
+ *   - API route validation (platform gateway)
+ *   - SDK type generation (@lucern/sdk-* packages)
+ *   - Contract lint gates (CI)
+ */
+export * from "./api-enums.contract";
+export * from "./auth-session.contract";
+export * from "./auth-context.contract";
+export * from "./convex-admin.contract";
+export * from "./gateway.contract";
+export * from "./context-pack.contract";
+export * from "./events.contract";
+export * from "./events-types.contract";
+export * from "./ids.contract";
+export * as mcpToolsContract from "./mcp-tools.contract";
+export * from "./ontology-matching.contract";
+export * from "./prompt.contract";
+export * from "./sdk-methods.contract";
+export * as sdkToolsContract from "./sdk-tools.contract";
+export * from "./text-matching.contract";
+export * from "./topic-scope.contract";
+export * from "./workflow-runtime.contract";

package/dist/lucern/contracts/src/index.js

@@ -0,0 +1,29 @@
+/**
+ * Lucern Platform Contracts
+ *
+ * Machine-readable source of truth for all external API surfaces.
+ * Enforcement hierarchy: MCP/API (co-equal) → SDK (derived) → Schema (internal).
+ *
+ * These contracts are consumed by:
+ *   - MCP tool registration (learning-loop module)
+ *   - API route validation (platform gateway)
+ *   - SDK type generation (@lucern/sdk-* packages)
+ *   - Contract lint gates (CI)
+ */
+export * from "./api-enums.contract.js";
+export * from "./auth-session.contract.js";
+export * from "./auth-context.contract.js";
+export * from "./convex-admin.contract.js";
+export * from "./gateway.contract.js";
+export * from "./context-pack.contract.js";
+export * from "./events.contract.js";
+export * from "./events-types.contract.js";
+export * from "./ids.contract.js";
+export * as mcpToolsContract from "./mcp-tools.contract.js";
+export * from "./ontology-matching.contract.js";
+export * from "./prompt.contract.js";
+export * from "./sdk-methods.contract.js";
+export * as sdkToolsContract from "./sdk-tools.contract.js";
+export * from "./text-matching.contract.js";
+export * from "./topic-scope.contract.js";
+export * from "./workflow-runtime.contract.js";

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 };
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Canonical lens workflow contract shared across schema, SDK, and MCP surfaces.
+ */
+export { validateFilterCriteria, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, } from "./lens-filter.contract.js";
+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";
+    }
+    if (normalized === "axis" || normalized === "dimension") {
+        return "comparison";
+    }
+    if (normalized === "track") {
+        return "investigation";
+    }
+    return "analysis";
+}
+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,
+        },
+    };
+}
+export function buildDeprecatedBranchMetadata(args) {
+    return {
+        deprecated: true,
+        deprecationMessage: BRANCH_DEPRECATION_MESSAGE,
+        lensSuggestion: migrateBranchToLens(args),
+    };
+}