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

package/dist/lucern/contracts/src/text-matching.contract.js

@@ -0,0 +1,277 @@
+/**
+ * Shared lexical matching primitives used across MCP handlers and graph utilities.
+ *
+ * The goal is not to replace downstream LLM scoring. It provides a fast,
+ * deterministic substrate for candidate generation, reranking, and light
+ * classification across belief/question/evidence/entity surfaces.
+ */
+const TOKEN_SPLIT_REGEX = /[^a-z0-9]+/;
+const NON_ALPHANUMERIC_REGEX = /[^a-z0-9]/g;
+/** Stop words that add noise to scoring. */
+const STOP_WORDS = new Set([
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "but",
+    "in",
+    "on",
+    "at",
+    "to",
+    "for",
+    "of",
+    "with",
+    "by",
+    "from",
+    "is",
+    "it",
+    "as",
+    "be",
+    "was",
+    "are",
+    "this",
+    "that",
+    "has",
+    "had",
+    "have",
+    "not",
+    "all",
+    "can",
+    "do",
+    "its",
+    "may",
+    "will",
+    "how",
+    "what",
+    "which",
+    "who",
+    "when",
+    "where",
+    "than",
+    "then",
+    "each",
+    "into",
+    "such",
+    "any",
+    "been",
+    "if",
+    "would",
+    "about",
+    "should",
+    "these",
+    "those",
+    "their",
+    "we",
+    "our",
+    "so",
+]);
+/** Tokenize a string into lowercase words, removing stop words. */
+export function tokenizeSearchText(text) {
+    return text
+        .toLowerCase()
+        .split(TOKEN_SPLIT_REGEX)
+        .filter((token) => token.length >= 2 && !STOP_WORDS.has(token));
+}
+/** Simple stemmer: strip common English suffixes for fuzzy matching. */
+export function stemToken(word) {
+    if (word.length <= 4) {
+        return word;
+    }
+    if (word.endsWith("ation")) {
+        return word.slice(0, -5);
+    }
+    if (word.endsWith("ment")) {
+        return word.slice(0, -4);
+    }
+    if (word.endsWith("ness")) {
+        return word.slice(0, -4);
+    }
+    if (word.endsWith("ical")) {
+        return word.slice(0, -4);
+    }
+    if (word.endsWith("tion")) {
+        return word.slice(0, -4);
+    }
+    if (word.endsWith("sion")) {
+        return word.slice(0, -4);
+    }
+    if (word.endsWith("ing")) {
+        return word.slice(0, -3);
+    }
+    if (word.endsWith("ous")) {
+        return word.slice(0, -3);
+    }
+    if (word.endsWith("ive")) {
+        return word.slice(0, -3);
+    }
+    if (word.endsWith("ity")) {
+        return word.slice(0, -3);
+    }
+    if (word.endsWith("ics")) {
+        return word.slice(0, -3);
+    }
+    if (word.endsWith("ly")) {
+        return word.slice(0, -2);
+    }
+    if (word.endsWith("ed")) {
+        return word.slice(0, -2);
+    }
+    if (word.endsWith("er")) {
+        return word.slice(0, -2);
+    }
+    if (word.endsWith("es")) {
+        return word.slice(0, -2);
+    }
+    if (word.endsWith("al")) {
+        return word.slice(0, -2);
+    }
+    if (word.endsWith("ic")) {
+        return word.slice(0, -2);
+    }
+    if (word.endsWith("s") && !word.endsWith("ss")) {
+        return word.slice(0, -1);
+    }
+    return word;
+}
+/** Compute token overlap score between query tokens and text tokens. */
+export function tokenOverlapScore(queryTokens, textTokens) {
+    if (queryTokens.length === 0 || textTokens.length === 0) {
+        return 0;
+    }
+    const stemmedText = new Set(textTokens.map(stemToken));
+    let matchCount = 0;
+    for (const queryToken of queryTokens) {
+        const stemmedQuery = stemToken(queryToken);
+        if (stemmedText.has(stemmedQuery)) {
+            matchCount += 1;
+            continue;
+        }
+        for (const textToken of stemmedText) {
+            if (textToken.startsWith(stemmedQuery) ||
+                stemmedQuery.startsWith(textToken)) {
+                matchCount += 0.5;
+                break;
+            }
+        }
+    }
+    return matchCount / queryTokens.length;
+}
+/**
+ * Extract character bigrams from text. Normalizes to lowercase, removes
+ * non-alphanumeric characters, and generates overlapping pairs.
+ */
+export function bigramTokenize(text) {
+    const normalized = text.toLowerCase().replace(NON_ALPHANUMERIC_REGEX, "");
+    const bigrams = new Set();
+    for (let i = 0; i < normalized.length - 1; i++) {
+        bigrams.add(normalized.slice(i, i + 2));
+    }
+    return bigrams;
+}
+/**
+ * Extract word-level tokens from text (for coarser matching).
+ * Normalizes to lowercase, splits on non-alphanumeric.
+ */
+export function wordTokenize(text) {
+    return text
+        .toLowerCase()
+        .split(TOKEN_SPLIT_REGEX)
+        .filter((token) => token.length > 1);
+}
+/** Jaccard similarity between two sets: |A ∩ B| / |A ∪ B|. */
+export function jaccardSimilarity(setA, setB) {
+    if (setA.size === 0 && setB.size === 0) {
+        return 0;
+    }
+    let intersectionSize = 0;
+    const smaller = setA.size <= setB.size ? setA : setB;
+    const larger = setA.size <= setB.size ? setB : setA;
+    for (const item of smaller) {
+        if (larger.has(item)) {
+            intersectionSize++;
+        }
+    }
+    const unionSize = setA.size + setB.size - intersectionSize;
+    return unionSize === 0 ? 0 : intersectionSize / unionSize;
+}
+/** Exact word overlap score: fraction of type words found in input text. */
+export function wordOverlapScore(inputWords, typeWords) {
+    if (typeWords.length === 0) {
+        return 0;
+    }
+    let matches = 0;
+    for (const word of typeWords) {
+        if (inputWords.includes(word)) {
+            matches++;
+        }
+    }
+    return matches / typeWords.length;
+}
+/** Pre-compute reusable lexical structures for a query. */
+export function prepareLexicalQuery(query) {
+    return {
+        raw: query,
+        tokens: tokenizeSearchText(query),
+        words: wordTokenize(query),
+        bigrams: bigramTokenize(query),
+    };
+}
+/** Score a single lexical signal against a prepared query. */
+export function scoreLexicalSignal(query, signal) {
+    const text = signal.text?.trim();
+    if (!text) {
+        return 0;
+    }
+    switch (signal.strategy ?? "tokenOverlap") {
+        case "bigramJaccard":
+            return jaccardSimilarity(query.bigrams, bigramTokenize(text));
+        case "wordOverlap":
+            return wordOverlapScore(query.words, wordTokenize(text));
+        default:
+            return tokenOverlapScore(query.tokens, tokenizeSearchText(text));
+    }
+}
+/** Weighted lexical score across multiple textual signals. */
+export function scoreLexicalSignals(query, signals) {
+    let weightedScore = 0;
+    let totalWeight = 0;
+    for (const signal of signals) {
+        if (!signal.text?.trim() || signal.weight <= 0) {
+            continue;
+        }
+        weightedScore += scoreLexicalSignal(query, signal) * signal.weight;
+        totalWeight += signal.weight;
+    }
+    return totalWeight === 0 ? 0 : weightedScore / totalWeight;
+}
+/** Map a candidate's original rank position into a 0..1 prior. */
+export function rankWindowScore(index, total) {
+    if (total <= 1) {
+        return 1;
+    }
+    const clampedIndex = Math.max(0, Math.min(index, total - 1));
+    return 1 - clampedIndex / (total - 1);
+}
+/** Rerank a candidate window by lexical overlap while preserving original-rank prior. */
+export function rerankLexicalWindow(query, items, getText, options) {
+    const preparedQuery = prepareLexicalQuery(query);
+    if (preparedQuery.tokens.length === 0 || items.length <= 1) {
+        return items;
+    }
+    const lexicalWeight = options?.lexicalWeight ?? 0.65;
+    const rankWeight = options?.rankWeight ?? 0.35;
+    return items
+        .map((item, index) => {
+        const lexicalScore = scoreLexicalSignals(preparedQuery, [
+            { text: getText(item) ?? "", weight: 1, strategy: "tokenOverlap" },
+        ]);
+        const rankScore = rankWindowScore(index, items.length);
+        return {
+            item,
+            combinedScore: lexicalScore * lexicalWeight + rankScore * rankWeight,
+        };
+    })
+        .sort((left, right) => right.combinedScore - left.combinedScore)
+        .map(({ item }) => item);
+}

package/dist/lucern/contracts/src/topic-scope.contract.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @lucern/contracts — topic-scope compat shim
+ *
+ * This file moved to ./v1/topics/v1.ts during EK-16 T1 PR 2.
+ * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
+ * New code should import from "@lucern/contracts/v1/topics" directly.
+ */
+export * from "./v1/topics/v1";

package/dist/lucern/contracts/src/topic-scope.contract.js

@@ -0,0 +1,8 @@
+/**
+ * @lucern/contracts — topic-scope compat shim
+ *
+ * This file moved to ./v1/topics/v1.ts during EK-16 T1 PR 2.
+ * Retained here until the Lucern 1.0.0 barrel-sunset cut (D12).
+ * New code should import from "@lucern/contracts/v1/topics" directly.
+ */
+export * from "./v1/topics/v1.js";

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

@@ -0,0 +1,257 @@
+/**
+ * Workflow Runtime Contract v1
+ *
+ * Canonical TypeScript contract for Lucern's graph-local workflow runtime.
+ * WF-1 defines the typed substrate for:
+ *   - workflow definitions and run receipts
+ *   - action mutation tiering and approval expectations
+ *   - hooks over worktree/question/evidence/inbox events
+ *   - output unions for domain-specific artifacts
+ *   - deterministic integrity checks and operational metadata
+ *
+ * BREAKING CHANGE RULES:
+ *   - Adding optional fields is NON-breaking
+ *   - Removing fields or renaming enum values is BREAKING
+ *   - Reclassifying a mutation tier is BREAKING
+ *   - Changing canonical workflow IDs is BREAKING
+ */
+export const WORKFLOW_RUNTIME_SCHEMA_VERSION = "1.0.0";
+export const WORKFLOW_MUTATION_TIERS = [
+    "read_only",
+    "low_risk_write",
+    "high_risk_write",
+];
+export const WORKFLOW_APPROVAL_MODES = [
+    "none",
+    "audit_only",
+    "human_required",
+    "auto_approve",
+];
+export const DEFAULT_TIER_APPROVAL_MODE = {
+    read_only: "none",
+    low_risk_write: "audit_only",
+    high_risk_write: "human_required",
+};
+export const WORKFLOW_ACTION_KINDS = [
+    "context_pack",
+    "integrity_check",
+    "lucern_tool",
+    "report_compile",
+    "brief_publish",
+    "notification",
+    "custom",
+];
+export const WORKFLOW_HOOK_EVENTS = [
+    "schedule.tick",
+    "worktree.activated",
+    "worktree.completed",
+    "question.created",
+    "question.answered",
+    "evidence.appended",
+    "inbox.item_created",
+];
+export const WORKFLOW_OUTPUT_KINDS = [
+    "engineering_brief",
+    "research_memo",
+    "strategy_artifact",
+    "inbox_summary",
+    "pipeline_brief",
+    "structured_payload",
+];
+export const WORKFLOW_RUN_STATUSES = [
+    "queued",
+    "running",
+    "awaiting_approval",
+    "completed",
+    "failed",
+    "cancelled",
+];
+export const WORKFLOW_TRIGGER_KINDS = [
+    "manual",
+    "schedule",
+    "hook",
+];
+export const WORKFLOW_PROOF_ARTIFACT_KINDS = [
+    "report",
+    "brief",
+    "artifact",
+    "dashboard",
+    "test_evidence",
+];
+export const WORKFLOW_STAFFING_HINTS = [
+    "solo",
+    "backend+tests",
+    "fullstack",
+    "mcp+tests",
+];
+export const WORKFLOW_AUTO_FIX_MODES = [
+    "disabled",
+    "dry_run",
+    "safe",
+    "aggressive",
+];
+export const WORKFLOW_INTEGRITY_CHECKS = [
+    "null_dependency_refs",
+    "superseded_blockers",
+    "band_order_inconsistency",
+    "sparse_shaping",
+    "failed_completed_gate",
+];
+export const DEFAULT_WORKFLOW_AUTO_FIX_POLICY = {
+    mode: "disabled",
+    permittedMutationTiers: ["read_only"],
+    requireAuditTrail: true,
+};
+export const NIGHTLY_RECONCILIATION_WORKFLOW_ID = "workflow.pipeline_reconciliation.v1";
+export const MORNING_BRIEF_WORKFLOW_ID = "workflow.morning_brief.v1";
+export const CANONICAL_WORKFLOW_DEFINITIONS = [
+    {
+        workflowId: NIGHTLY_RECONCILIATION_WORKFLOW_ID,
+        version: WORKFLOW_RUNTIME_SCHEMA_VERSION,
+        title: "Nightly Pipeline Reconciliation",
+        description: "Runs deterministic integrity checks, compiles pipeline state, and emits an operator-facing reconciliation brief.",
+        trigger: {
+            kind: "schedule",
+            cadence: "daily",
+            timezone: "America/New_York",
+        },
+        staffingHint: "backend+tests",
+        proofArtifacts: [
+            {
+                kind: "report",
+                label: "Pipeline reconciliation report",
+                required: true,
+            },
+            {
+                kind: "test_evidence",
+                label: "Integrity check receipt",
+                required: true,
+            },
+        ],
+        autoFixPolicy: {
+            mode: "safe",
+            maxActionsPerRun: 5,
+            permittedMutationTiers: ["read_only", "low_risk_write"],
+            requireAuditTrail: true,
+            escalationGate: "gate:workflow-runtime-contract-live",
+        },
+        actions: [
+            {
+                actionId: "compile_context_pack",
+                kind: "context_pack",
+                title: "Compile pipeline context",
+                description: "Build the ranked context needed for deterministic checks.",
+                mutationTier: "read_only",
+                produces: ["structured_payload"],
+                idempotent: true,
+                approval: { mode: "none" },
+            },
+            {
+                actionId: "run_integrity_checks",
+                kind: "integrity_check",
+                title: "Run integrity checks",
+                description: "Evaluate dependency references, blockers, execution bands, shaping coverage, and completed gates.",
+                mutationTier: "read_only",
+                produces: ["structured_payload"],
+                idempotent: true,
+                approval: { mode: "none" },
+            },
+            {
+                actionId: "record_followup_questions",
+                kind: "lucern_tool",
+                title: "Record follow-up questions",
+                description: "Create or reopen operator-facing questions for integrity failures that require human review.",
+                mutationTier: "low_risk_write",
+                toolName: "create_question",
+                produces: ["pipeline_brief"],
+                approval: { mode: "audit_only", rationaleRequired: true },
+            },
+            {
+                actionId: "publish_reconciliation_brief",
+                kind: "brief_publish",
+                title: "Publish reconciliation brief",
+                description: "Emit an inbox-routed brief summarizing the nightly pipeline state and grouped blockers.",
+                mutationTier: "low_risk_write",
+                produces: ["pipeline_brief", "inbox_summary"],
+                approval: { mode: "audit_only" },
+            },
+        ],
+        hooks: [
+            {
+                hookId: "nightly-schedule",
+                event: "schedule.tick",
+                description: "Run once per nightly cadence.",
+                actionIds: [
+                    "compile_context_pack",
+                    "run_integrity_checks",
+                    "record_followup_questions",
+                    "publish_reconciliation_brief",
+                ],
+            },
+        ],
+        outputs: ["pipeline_brief", "inbox_summary", "structured_payload"],
+        integrityChecks: WORKFLOW_INTEGRITY_CHECKS,
+    },
+    {
+        workflowId: MORNING_BRIEF_WORKFLOW_ID,
+        version: WORKFLOW_RUNTIME_SCHEMA_VERSION,
+        title: "Morning Brief",
+        description: "Compiles a developer-facing morning brief from graph state, overnight workflow outputs, and inbox routing preferences.",
+        trigger: {
+            kind: "schedule",
+            cadence: "daily",
+            timezone: "America/New_York",
+        },
+        staffingHint: "solo",
+        proofArtifacts: [
+            {
+                kind: "brief",
+                label: "Morning brief",
+                required: true,
+            },
+        ],
+        autoFixPolicy: {
+            mode: "dry_run",
+            maxActionsPerRun: 1,
+            permittedMutationTiers: ["read_only", "low_risk_write"],
+            requireAuditTrail: true,
+        },
+        actions: [
+            {
+                actionId: "compile_brief_inputs",
+                kind: "context_pack",
+                title: "Compile brief inputs",
+                description: "Read graph state, worktree state, and overnight workflow receipts.",
+                mutationTier: "read_only",
+                produces: ["structured_payload"],
+                idempotent: true,
+                approval: { mode: "none" },
+            },
+            {
+                actionId: "publish_morning_brief",
+                kind: "brief_publish",
+                title: "Publish morning brief",
+                description: "Publish a typed inbox summary with prioritized worktree and question context.",
+                mutationTier: "low_risk_write",
+                produces: ["engineering_brief", "inbox_summary"],
+                approval: { mode: "audit_only" },
+            },
+        ],
+        hooks: [
+            {
+                hookId: "morning-schedule",
+                event: "schedule.tick",
+                description: "Run once per morning cadence.",
+                actionIds: ["compile_brief_inputs", "publish_morning_brief"],
+            },
+            {
+                hookId: "worktree-complete-refresh",
+                event: "worktree.completed",
+                description: "Refresh the queued morning brief inputs when worktree outcomes land overnight.",
+                actionIds: ["compile_brief_inputs"],
+            },
+        ],
+        outputs: ["engineering_brief", "inbox_summary", "structured_payload"],
+        integrityChecks: ["sparse_shaping"],
+    },
+];

package/dist/realtime-refs.d.ts

@@ -0,0 +1 @@
+export * from "./lib/platform/sdk/realtime/refs";

package/dist/realtime-refs.js

@@ -0,0 +1 @@
+export * from "./lib/platform/sdk/realtime/refs.js";

package/dist/realtime.d.ts

@@ -0,0 +1 @@
+export * from "./lib/platform/sdk/realtime/index";

package/dist/realtime.js

@@ -0,0 +1 @@
+export * from "./lib/platform/sdk/realtime/index.js";

package/package.json

@@ -1,20 +1,28 @@
 {
   "name": "@lucern/sdk",
-  "version": "0.2.0-alpha.4",
+  "version": "0.2.0-alpha.6",
   "description": "Lucern reasoning platform SDK. Install this one package, provide your API key, and start building in 10 minutes.",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
-  "types": "./dist/packages/sdk/src/index.d.ts",
+  "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "README.md"
   ],
   "exports": {
     ".": {
-      "types": "./dist/packages/sdk/src/index.d.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./realtime": {
+      "types": "./dist/realtime.d.ts",
+      "import": "./dist/realtime.js"
+    },
+    "./realtime/refs": {
+      "types": "./dist/realtime-refs.d.ts",
+      "import": "./dist/realtime-refs.js"
     }
   },
   "sideEffects": false,
@@ -22,18 +30,23 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsup && tsc --project tsconfig.bundle.json --declaration --emitDeclarationOnly --outDir dist",
+    "build": "bash -lc 'cd ../../.. && npx tsx scripts/build-sdk-package.ts'",
     "build:js": "tsup",
     "build:dts": "tsc --project tsconfig.bundle.json --declaration --emitDeclarationOnly --outDir dist",
     "pack:dry-run": "npm pack --dry-run",
+    "prepack": "npm run build",
     "typecheck": "tsc --project tsconfig.json --noEmit"
   },
   "peerDependencies": {
-    "convex": ">=1.0.0"
+    "convex": ">=1.0.0",
+    "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
     "convex": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "devDependencies": {