@lucern/sdk 0.2.0-alpha.1

package/dist/lucern/contracts/src/lens-workflow.contract.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Canonical lens workflow contract shared across schema, SDK, and MCP surfaces.
+ */
+export type { LensFilterCriteria, TaxonomyFilterCriteriaV1, EntityTypeFilterV1, OntologyScope, FilterValidationResult, } from "./lens-filter.contract";
+export { validateFilterCriteria, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, } from "./lens-filter.contract";
+export declare const LENS_PERSPECTIVE_TYPES: readonly ["investigation", "monitoring", "analysis", "comparison", "taxonomy"];
+export type LensPerspectiveType = (typeof LENS_PERSPECTIVE_TYPES)[number];
+export declare const LENS_STATUSES: readonly ["draft", "active", "archived"];
+export type LensStatus = (typeof LENS_STATUSES)[number];
+export declare const LENS_TASK_TEMPLATE_PRIORITIES: readonly ["critical", "high", "medium", "low"];
+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 declare 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 declare function inferLensPerspectiveTypeFromBranchSchema(schema?: string | null): LensPerspectiveType;
+export declare function migrateBranchToLens(args: {
+    name: string;
+    description?: string;
+    topicId?: string;
+    workspaceId?: string;
+    schema?: string | null;
+}): LensBranchMigrationSuggestion;
+export declare function buildDeprecatedBranchMetadata(args: {
+    name: string;
+    description?: string;
+    topicId?: string;
+    workspaceId?: string;
+    schema?: string | null;
+}): DeprecatedBranchMetadata;

package/dist/lucern/contracts/src/mcp-tools.contract.d.ts

@@ -0,0 +1,151 @@
+/**
+ * MCP Tool Contract Definitions
+ *
+ * Machine-readable source of truth for all Lucern MCP tool names,
+ * descriptions, parameters, and response schemas.
+ *
+ * CONTRACT SURFACE: These definitions are the external API for AI agents.
+ * Renaming a tool or changing its description is a BREAKING CHANGE.
+ *
+ * Git-native naming rules (enforced by lint):
+ *   1. Workflow tools use git verbs directly (add_worktree, merge, push, open_pull_request)
+ *   2. Knowledge tools use epistemic verbs (create_belief, fork_belief, modulate_confidence)
+ *   3. First sentence of description includes the git analog verb
+ *   4. Description includes "Like `git X`" parenthetical
+ *   5. Parameter names use domain terms (canonicalText, nodeId, confidence)
+ */
+export type McpToolContract = {
+    /** Stable tool name — breaking change to rename */
+    name: string;
+    /** Git-semantic description — breaking change to remove git references */
+    description: string;
+    /** Parameter schema (JSON Schema subset) */
+    parameters: Record<string, McpParameterDef>;
+    /** Required parameter names */
+    required: string[];
+    /** Response shape description */
+    response: McpResponseDef;
+    /** Which Lucern module owns the implementation */
+    ownerModule: string;
+    /** Ontology primitive this tool operates on */
+    ontologyPrimitive: "belief" | "evidence" | "source" | "question" | "judgment" | "worktree" | "branch" | "lens" | "edge" | "graph" | "task" | "policy" | "ontology" | "identity";
+    /** MCP surface tier — showcase (front page, every demo) or workhorse (complete CRUD, discovered when building) */
+    tier: "showcase" | "workhorse";
+    /** Hide this tool from public discovery surfaces. */
+    internal?: boolean;
+    /** Deprecation notice shown in contract-driven docs and discovery. */
+    deprecated?: string;
+};
+export type McpParameterDef = {
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description: string;
+    required?: boolean;
+    enum?: string[];
+};
+export type McpResponseDef = {
+    description: string;
+    fields: Record<string, string>;
+};
+export declare const CREATE_BELIEF: McpToolContract;
+export declare const GET_BELIEF: McpToolContract;
+export declare const REFINE_BELIEF: McpToolContract;
+export declare const MODULATE_CONFIDENCE: McpToolContract;
+export declare const FORK_BELIEF: McpToolContract;
+export declare const ARCHIVE_BELIEF: McpToolContract;
+export declare const CREATE_EPISTEMIC_CONTRACT: McpToolContract;
+export declare const ADD_EVIDENCE: McpToolContract;
+export declare const FLAG_CONTRADICTION: McpToolContract;
+export declare const ADD_WORKTREE: McpToolContract;
+export declare const MERGE: McpToolContract;
+export declare const QUERY_LINEAGE: McpToolContract;
+export declare const GET_CONFIDENCE_HISTORY: McpToolContract;
+export declare const GET_AUDIT_TRAIL: McpToolContract;
+export declare const TRAVERSE_GRAPH: McpToolContract;
+export declare const GET_GRAPH_NEIGHBORHOOD: McpToolContract;
+export declare const TRACE_ENTITY_IMPACT: McpToolContract;
+export declare const SEARCH_BELIEFS: McpToolContract;
+export declare const SEARCH_RESOURCES: McpToolContract;
+export declare const FIND_CONTRADICTIONS: McpToolContract;
+export declare const CREATE_EDGE: McpToolContract;
+export declare const RECORD_JUDGMENT: McpToolContract;
+export declare const CREATE_LENS: McpToolContract;
+export declare const LIST_LENSES: McpToolContract;
+export declare const APPLY_LENS_TO_TOPIC: McpToolContract;
+export declare const REMOVE_LENS_FROM_TOPIC: McpToolContract;
+export declare const PUSH: McpToolContract;
+export declare const OPEN_PULL_REQUEST: McpToolContract;
+export declare const BISECT_CONFIDENCE: McpToolContract;
+export declare const DETECT_CONFIRMATION_BIAS: McpToolContract;
+export declare const GET_GRAPH_STRUCTURE_ANALYSIS: McpToolContract;
+export declare const GET_FALSIFICATION_QUESTIONS: McpToolContract;
+export declare const SEARCH_SOURCES: McpToolContract;
+export declare const EXECUTE_DEEP_RESEARCH: McpToolContract;
+export declare const SEARCH_EVIDENCE: McpToolContract;
+export declare const CREATE_EVIDENCE: McpToolContract;
+export declare const GET_EVIDENCE: McpToolContract;
+export declare const LIST_EVIDENCE: McpToolContract;
+export declare const LINK_EVIDENCE: McpToolContract;
+export declare const LINK_EVIDENCE_TO_BELIEF: McpToolContract;
+export declare const CREATE_QUESTION: McpToolContract;
+export declare const GET_QUESTION: McpToolContract;
+export declare const REFINE_QUESTION: McpToolContract;
+export declare const LIST_QUESTIONS: McpToolContract;
+export declare const ANSWER_QUESTION: McpToolContract;
+export declare const UPDATE_QUESTION_STATUS: McpToolContract;
+export declare const ARCHIVE_QUESTION: McpToolContract;
+export declare const LINK_EVIDENCE_TO_QUESTION: McpToolContract;
+export declare const CREATE_ANSWER: McpToolContract;
+export declare const GET_ANSWER: McpToolContract;
+export declare const GET_HIGH_PRIORITY_QUESTIONS: McpToolContract;
+export declare const FIND_MISSING_QUESTIONS: McpToolContract;
+export declare const LIST_BELIEFS: McpToolContract;
+export declare const LIST_WORKTREES: McpToolContract;
+export declare const LIST_ALL_WORKTREES: McpToolContract;
+export declare const ACTIVATE_WORKTREE: McpToolContract;
+export declare const UPDATE_WORKTREE_TARGETS: McpToolContract;
+export declare const UPDATE_WORKTREE_METADATA: McpToolContract;
+export declare const IDENTITY_WHOAMI: McpToolContract;
+export declare const COMPILE_CONTEXT: McpToolContract;
+export declare const CHECK_PERMISSION: McpToolContract;
+export declare const FILTER_BY_PERMISSION: McpToolContract;
+export declare const INGEST_OBSERVATION: McpToolContract;
+export declare const GET_OBSERVATION_CONTEXT: McpToolContract;
+export declare const CREATE_TASK: McpToolContract;
+export declare const COMPLETE_TASK: McpToolContract;
+export declare const UPDATE_TASK: McpToolContract;
+export declare const LIST_TASKS: McpToolContract;
+export declare const CREATE_TOPIC: McpToolContract;
+export declare const LIST_TOPICS: McpToolContract;
+export declare const GET_TOPIC: McpToolContract;
+export declare const UPDATE_TOPIC: McpToolContract;
+export declare const GET_TOPIC_TREE: McpToolContract;
+export declare const GET_CODE_CONTEXT: McpToolContract;
+export declare const GET_CHANGE_HISTORY: McpToolContract;
+export declare const RECORD_ATTEMPT: McpToolContract;
+export declare const GET_FAILURE_LOG: McpToolContract;
+export declare const GET_TOPIC_COVERAGE: McpToolContract;
+export declare const GET_GRAPH_GAPS: McpToolContract;
+export declare const MANAGE_WRITE_POLICY: McpToolContract;
+export declare const LIST_ONTOLOGIES: McpToolContract;
+export declare const GET_ONTOLOGY: McpToolContract;
+export declare const APPLY_ONTOLOGY: McpToolContract;
+export declare const MATCH_ENTITY_TYPE: McpToolContract;
+export declare const CREATE_ONTOLOGY: McpToolContract;
+export declare const UPDATE_ONTOLOGY: McpToolContract;
+export declare const ARCHIVE_ONTOLOGY: McpToolContract;
+export declare const CREATE_ONTOLOGY_VERSION: McpToolContract;
+export declare const PUBLISH_ONTOLOGY_VERSION: McpToolContract;
+export declare const DEPRECATE_ONTOLOGY_VERSION: McpToolContract;
+export declare const RESOLVE_EFFECTIVE_ONTOLOGY: McpToolContract;
+/** All MCP tool contracts, indexed by name */
+export declare const MCP_TOOL_CONTRACTS: Record<string, McpToolContract>;
+/** Tool names that MUST include git-semantic language in descriptions */
+export declare const GIT_SEMANTIC_REQUIRED_TOOLS: string[];
+/**
+ * Lint validation: every tool description must contain "Like `git" or "Like a `git"
+ * or reference a git operation in the first sentence.
+ */
+export declare function validateGitSemantics(tool: McpToolContract): {
+    valid: boolean;
+    reason?: string;
+};

package/dist/lucern/contracts/src/workflow-runtime.contract.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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[];

package/dist/lucern/mcp-server/src/context-pack-policy.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Context-Pack Ranking and Injection Policy
+ *
+ * Implements the ranking algorithm and token-budget injection planner
+ * for context pack assembly. All tunable constants are imported from
+ * the canonical contract at lucern/contracts/src/context-pack.contract.ts.
+ */
+import { type ContextPackSectionKey, type ContextRankingProfile, type PackWeightOverride, type RankingWeightVector } from "../../contracts/src/context-pack.contract.js";
+export type SectionKey = ContextPackSectionKey;
+export type RankCandidate = {
+    id: string;
+    text: string;
+    updatedAt?: number | null;
+    createdAt?: number | null;
+    confidence?: number | null;
+    beliefType?: string | null;
+    priority?: string | null;
+    severity?: string | null;
+};
+export type RankedCandidate<T extends RankCandidate> = T & {
+    score: number;
+    /** Human-readable justification for the ranking (RS-2). */
+    justification?: string;
+};
+/** An item excluded from the injection plan (RS-2). */
+export type ExcludedItem = {
+    id: string;
+    section: SectionKey;
+    reason: "budget_exceeded" | "anti_repetition" | "below_threshold";
+    score: number;
+};
+export type InjectionPlan = {
+    tokenBudget: number;
+    estimatedTokens: number;
+    sectionBudgets: Record<SectionKey, number>;
+    sectionUsage: Record<SectionKey, number>;
+    selected: Record<SectionKey, string[]>;
+    /** Items excluded from injection with reasons (RS-2). */
+    excludedItems?: ExcludedItem[];
+};
+/**
+ * Resolve effective ranking weights by merging overrides onto defaults.
+ * Overrides are partial — only specified fields replace defaults.
+ */
+export declare function resolveEffectiveWeights(overrides?: PackWeightOverride[]): Readonly<Record<ContextPackSectionKey, RankingWeightVector>>;
+/**
+ * Filter out candidates whose IDs appear in the suppression set.
+ * Returns the filtered list and the IDs that were suppressed.
+ */
+export declare function applySuppression<T extends RankCandidate>(candidates: T[], suppressedIds: ReadonlySet<string>): {
+    filtered: T[];
+    suppressed: string[];
+};
+/** Options for RS-2 enhanced ranking. */
+export type RankContextOptions = {
+    /** Pack weight overrides from domain pack binding. */
+    effectiveWeights?: Readonly<Record<ContextPackSectionKey, RankingWeightVector>>;
+    /** Generate human-readable justifications for each ranked item. */
+    includeJustifications?: boolean;
+    /** Stable timestamp anchor for recency scoring when compilation must be deterministic. */
+    referenceTimeMs?: number;
+};
+export declare function rankContextSection<T extends RankCandidate>(section: SectionKey, rows: T[], queryTokens: string[], limit: number, profile: ContextRankingProfile, options?: RankContextOptions): RankedCandidate<T>[];
+export declare function parseTokenBudget(value: unknown, fallback?: number): number;
+export declare function buildInjectionPlan(args: {
+    tokenBudget: number;
+    invariants: Array<{
+        nodeId: string;
+        canonicalText: string;
+        score?: number;
+    }>;
+    activeBeliefs: Array<{
+        nodeId: string;
+        canonicalText: string;
+        score?: number;
+    }>;
+    openQuestions: Array<{
+        questionId: string;
+        text: string;
+        score?: number;
+    }>;
+    recentEvidence: Array<{
+        nodeId: string;
+        canonicalText: string;
+        score?: number;
+    }>;
+    contradictions: Array<{
+        contradictionId: string;
+        description: string;
+        score?: number;
+    }>;
+    /** Track excluded items with reasons (RS-2). */
+    trackExclusions?: boolean;
+}): InjectionPlan;
+/**
+ * Candidate for entity ranking in the context pack.
+ * Entities are ranked separately from the token-budgeted sections.
+ */
+export type EntityCandidate = {
+    nodeId: string;
+    entityType: string;
+    title: string;
+    canonicalText: string;
+    connectedBeliefCount: number;
+    connectedEvidenceCount: number;
+    metadata: Record<string, unknown>;
+    updatedAt?: number | null;
+};
+export type RankedEntity = EntityCandidate & {
+    score: number;
+};
+/**
+ * Rank entities by query relevance + connectivity.
+ *
+ * Uses ENTITY_RANKING_WEIGHTS: { query: 0.4, connectivity: 0.6 }
+ * - query: Token-hit scoring against the focus query
+ * - connectivity: Normalized count of connected beliefs + evidence
+ */
+export declare function rankEntities(candidates: EntityCandidate[], queryTokens: string[], limit?: number): RankedEntity[];

package/dist/lucern/mcp-server/src/context-pack-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Context-Pack Schema Validation
+ *
+ * Runtime validator for ContextPackV1 output. Types and constants are
+ * imported from the canonical contract at lucern/contracts/src/context-pack.contract.ts.
+ *
+ * This module is intentionally thin: it re-exports the contract types and provides
+ * runtime validation that the contract cannot enforce (since TypeScript types
+ * are erased at runtime).
+ */
+import { CONTEXT_PACK_SCHEMA_VERSION, type ContextRankingProfile } from "../../contracts/src/context-pack.contract.js";
+export { CONTEXT_PACK_SCHEMA_VERSION, type ContextRankingProfile };
+type ValidationResult = {
+    valid: boolean;
+    errors: string[];
+};
+export declare function validateContextPackSchema(payload: unknown): ValidationResult;
+export declare function assertContextPackSchema(payload: unknown): void;

package/dist/lucern/modules/graph-primitives/src/ontology-matching.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Ontology Matching Engine — L0 entity type classification and similarity scoring.
+ *
+ * Provides bigram-based text similarity for matching free text against
+ * ontology entity types. Domain-agnostic: works identically for companies,
+ * molecules, code modules, or any tenant-defined entity vocabulary.
+ *
+ * Used by:
+ *   - match_entity_type MCP handler (classify new entities)
+ *   - discover_entity_connections MCP handler (suggest missing bridge edges)
+ *
+ * @module graph-primitives/ontology-matching
+ */
+/** An entity type definition from a resolved ontology version. */
+export type OntologyEntityType = {
+    value: string;
+    label: string;
+    description?: string;
+    subtypes?: Array<{
+        value: string;
+        label: string;
+        description?: string;
+    }>;
+};
+/** A scored match between input text and an entity type. */
+export type EntityTypeMatch = {
+    entityType: string;
+    label: string;
+    score: number;
+    reason: string;
+};
+/** A candidate entity node that can be matched against a target node. */
+export type EntityMatchCandidate = {
+    nodeId: string;
+    entityType: string;
+    title: string;
+    canonicalText: string;
+    connectedBeliefCount: number;
+    connectedEvidenceCount: number;
+};
+/** A scored entity match with suggested bridge edge type. */
+export type EntityConnectionMatch = {
+    entityNodeId: string;
+    entityType: string;
+    title: string;
+    score: number;
+    suggestedEdgeType: string;
+    reason: string;
+};
+/**
+ * Score how well input text matches a single entity type definition.
+ * Combines bigram Jaccard similarity, word overlap, and description matching.
+ */
+export declare function scoreEntityTypeMatch(inputText: string, entityType: OntologyEntityType): EntityTypeMatch;
+/**
+ * Rank all entity types in an ontology against input text.
+ * Returns matches sorted by score (descending), filtered to score > minScore.
+ */
+export declare function rankEntityTypeMatches(inputText: string, entityTypes: OntologyEntityType[], options?: {
+    minScore?: number;
+    limit?: number;
+}): EntityTypeMatch[];
+/**
+ * Score how well a node's text matches an entity candidate.
+ * Used by discover_entity_connections to suggest missing bridge edges.
+ */
+export declare function scoreEntityConnection(nodeText: string, candidate: EntityMatchCandidate, options?: {
+    connectivityWeight?: number;
+}): EntityConnectionMatch;
+/**
+ * Rank entity candidates against a node's text.
+ * Returns sorted matches above the minimum score threshold.
+ */
+export declare function rankEntityConnections(nodeText: string, candidates: EntityMatchCandidate[], options?: {
+    minScore?: number;
+    limit?: number;
+    connectivityWeight?: number;
+}): EntityConnectionMatch[];

package/dist/lucern/modules/graph-primitives/src/text-matching.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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[];