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

package/dist/lucern/contracts/src/text-matching.contract.d.ts

@@ -1,53 +0,0 @@
-/**
- * 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.
- */
-export type LexicalStrategy = "tokenOverlap" | "bigramJaccard" | "wordOverlap";
-export type PreparedLexicalQuery = {
-    raw: string;
-    tokens: string[];
-    words: string[];
-    bigrams: Set<string>;
-};
-export type LexicalSignal = {
-    strategy?: LexicalStrategy;
-    text: string | null | undefined;
-    weight: number;
-};
-export type LexicalRerankOptions = {
-    lexicalWeight?: number;
-    rankWeight?: number;
-};
-/** Tokenize a string into lowercase words, removing stop words. */
-export declare function tokenizeSearchText(text: string): string[];
-/** Simple stemmer: strip common English suffixes for fuzzy matching. */
-export declare function stemToken(word: string): string;
-/** Compute token overlap score between query tokens and text tokens. */
-export declare function tokenOverlapScore(queryTokens: string[], textTokens: string[]): number;
-/**
- * Extract character bigrams from text. Normalizes to lowercase, removes
- * non-alphanumeric characters, and generates overlapping pairs.
- */
-export declare function bigramTokenize(text: string): Set<string>;
-/**
- * Extract word-level tokens from text (for coarser matching).
- * Normalizes to lowercase, splits on non-alphanumeric.
- */
-export declare function wordTokenize(text: string): string[];
-/** Jaccard similarity between two sets: |A ∩ B| / |A ∪ B|. */
-export declare function jaccardSimilarity(setA: Set<string>, setB: Set<string>): number;
-/** Exact word overlap score: fraction of type words found in input text. */
-export declare function wordOverlapScore(inputWords: string[], typeWords: string[]): number;
-/** Pre-compute reusable lexical structures for a query. */
-export declare function prepareLexicalQuery(query: string): PreparedLexicalQuery;
-/** Score a single lexical signal against a prepared query. */
-export declare function scoreLexicalSignal(query: PreparedLexicalQuery, signal: LexicalSignal): number;
-/** Weighted lexical score across multiple textual signals. */
-export declare function scoreLexicalSignals(query: PreparedLexicalQuery, signals: LexicalSignal[]): number;
-/** Map a candidate's original rank position into a 0..1 prior. */
-export declare function rankWindowScore(index: number, total: number): number;
-/** Rerank a candidate window by lexical overlap while preserving original-rank prior. */
-export declare function rerankLexicalWindow<T>(query: string, items: T[], getText: (item: T) => string | null | undefined, options?: LexicalRerankOptions): T[];

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

@@ -1,277 +0,0 @@
-/**
- * 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

@@ -1,8 +0,0 @@
-/**
- * @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

@@ -1,8 +0,0 @@
-/**
- * @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.d.ts

@@ -1,161 +0,0 @@
-/**
- * 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 declare const WORKFLOW_RUNTIME_SCHEMA_VERSION: "1.0.0";
-export declare const WORKFLOW_MUTATION_TIERS: readonly ["read_only", "low_risk_write", "high_risk_write"];
-export type WorkflowMutationTier = (typeof WORKFLOW_MUTATION_TIERS)[number];
-export declare const WORKFLOW_APPROVAL_MODES: readonly ["none", "audit_only", "human_required", "auto_approve"];
-export type WorkflowApprovalMode = (typeof WORKFLOW_APPROVAL_MODES)[number];
-export declare const DEFAULT_TIER_APPROVAL_MODE: Readonly<Record<WorkflowMutationTier, WorkflowApprovalMode>>;
-export declare const WORKFLOW_ACTION_KINDS: readonly ["context_pack", "integrity_check", "lucern_tool", "report_compile", "brief_publish", "notification", "custom"];
-export type WorkflowActionKind = (typeof WORKFLOW_ACTION_KINDS)[number];
-export declare const WORKFLOW_HOOK_EVENTS: readonly ["schedule.tick", "worktree.activated", "worktree.completed", "question.created", "question.answered", "evidence.appended", "inbox.item_created"];
-export type WorkflowHookEvent = (typeof WORKFLOW_HOOK_EVENTS)[number];
-export declare const WORKFLOW_OUTPUT_KINDS: readonly ["engineering_brief", "research_memo", "strategy_artifact", "inbox_summary", "pipeline_brief", "structured_payload"];
-export type WorkflowOutputKind = (typeof WORKFLOW_OUTPUT_KINDS)[number];
-export declare const WORKFLOW_RUN_STATUSES: readonly ["queued", "running", "awaiting_approval", "completed", "failed", "cancelled"];
-export type WorkflowRunStatus = (typeof WORKFLOW_RUN_STATUSES)[number];
-export declare const WORKFLOW_TRIGGER_KINDS: readonly ["manual", "schedule", "hook"];
-export type WorkflowTriggerKind = (typeof WORKFLOW_TRIGGER_KINDS)[number];
-export declare const WORKFLOW_PROOF_ARTIFACT_KINDS: readonly ["report", "brief", "artifact", "dashboard", "test_evidence"];
-export type WorkflowProofArtifactKind = (typeof WORKFLOW_PROOF_ARTIFACT_KINDS)[number];
-export declare const WORKFLOW_STAFFING_HINTS: readonly ["solo", "backend+tests", "fullstack", "mcp+tests"];
-export type WorkflowStaffingHint = (typeof WORKFLOW_STAFFING_HINTS)[number];
-export declare const WORKFLOW_AUTO_FIX_MODES: readonly ["disabled", "dry_run", "safe", "aggressive"];
-export type WorkflowAutoFixMode = (typeof WORKFLOW_AUTO_FIX_MODES)[number];
-export declare const WORKFLOW_INTEGRITY_CHECKS: readonly ["null_dependency_refs", "superseded_blockers", "band_order_inconsistency", "sparse_shaping", "failed_completed_gate"];
-export type WorkflowIntegrityCheckId = (typeof WORKFLOW_INTEGRITY_CHECKS)[number];
-export type WorkflowProofArtifact = {
-    kind: WorkflowProofArtifactKind;
-    label: string;
-    required?: boolean;
-    sourceRef?: string;
-};
-export type WorkflowAutoFixPolicy = {
-    mode: WorkflowAutoFixMode;
-    maxActionsPerRun?: number;
-    permittedMutationTiers?: WorkflowMutationTier[];
-    requireAuditTrail?: boolean;
-    escalationGate?: string;
-};
-export declare const DEFAULT_WORKFLOW_AUTO_FIX_POLICY: WorkflowAutoFixPolicy;
-export type WorkflowApprovalPolicy = {
-    mode: WorkflowApprovalMode;
-    approvalGate?: string;
-    autoApprovePolicyKey?: string;
-    rationaleRequired?: boolean;
-};
-export type WorkflowOutputBase = {
-    outputId: string;
-    kind: WorkflowOutputKind;
-    title: string;
-    summary: string;
-    generatedAt?: number;
-};
-export type EngineeringBriefOutput = WorkflowOutputBase & {
-    kind: "engineering_brief";
-    sections: Array<{
-        heading: string;
-        body: string;
-    }>;
-    touchedPaths?: string[];
-};
-export type ResearchMemoOutput = WorkflowOutputBase & {
-    kind: "research_memo";
-    claims: string[];
-    evidenceRefs?: string[];
-};
-export type StrategyArtifactOutput = WorkflowOutputBase & {
-    kind: "strategy_artifact";
-    recommendations: string[];
-    decisionWindow?: string;
-};
-export type InboxSummaryOutput = WorkflowOutputBase & {
-    kind: "inbox_summary";
-    channel: "developer_portal" | "chat" | "ops";
-    inboxTitle: string;
-    inboxBody: string;
-};
-export type PipelineBriefOutput = WorkflowOutputBase & {
-    kind: "pipeline_brief";
-    hingeWorktreeId?: string;
-    groupedBlockers: Array<{
-        blocker: string;
-        blockedWorktreeIds: string[];
-    }>;
-};
-export type StructuredPayloadOutput = WorkflowOutputBase & {
-    kind: "structured_payload";
-    payload: Record<string, unknown>;
-};
-export type WorkflowOutputContract = EngineeringBriefOutput | ResearchMemoOutput | StrategyArtifactOutput | InboxSummaryOutput | PipelineBriefOutput | StructuredPayloadOutput;
-export type WorkflowActionContract = {
-    actionId: string;
-    kind: WorkflowActionKind;
-    title: string;
-    description: string;
-    mutationTier: WorkflowMutationTier;
-    toolName?: string;
-    produces?: WorkflowOutputKind[];
-    idempotent?: boolean;
-    approval: WorkflowApprovalPolicy;
-};
-export type WorkflowHookContract = {
-    hookId: string;
-    event: WorkflowHookEvent;
-    description: string;
-    condition?: string;
-    actionIds: string[];
-};
-export type WorkflowTriggerContract = {
-    kind: "manual";
-    description?: string;
-} | {
-    kind: "schedule";
-    cadence: "hourly" | "daily" | "weekly";
-    timezone?: string;
-} | {
-    kind: "hook";
-    event: WorkflowHookEvent;
-};
-export type WorkflowDefinitionV1 = {
-    workflowId: string;
-    version: typeof WORKFLOW_RUNTIME_SCHEMA_VERSION;
-    title: string;
-    description: string;
-    trigger: WorkflowTriggerContract;
-    staffingHint?: WorkflowStaffingHint;
-    proofArtifacts?: WorkflowProofArtifact[];
-    autoFixPolicy?: WorkflowAutoFixPolicy;
-    actions: readonly WorkflowActionContract[];
-    hooks?: readonly WorkflowHookContract[];
-    outputs: readonly WorkflowOutputKind[];
-    integrityChecks?: readonly WorkflowIntegrityCheckId[];
-};
-export type WorkflowRunReceiptV1 = {
-    runId: string;
-    workflowId: string;
-    status: WorkflowRunStatus;
-    triggeredBy: WorkflowTriggerKind;
-    startedAt: number;
-    completedAt?: number;
-    outputKinds: WorkflowOutputKind[];
-    approvalsRequired?: number;
-};
-export declare const NIGHTLY_RECONCILIATION_WORKFLOW_ID: "workflow.pipeline_reconciliation.v1";
-export declare const MORNING_BRIEF_WORKFLOW_ID: "workflow.morning_brief.v1";
-export declare const CANONICAL_WORKFLOW_DEFINITIONS: readonly WorkflowDefinitionV1[];