@lucern/sdk 0.2.0-alpha.12 → 0.2.0-alpha.2

package/dist/{contracts → lucern/contracts/src}/auth-session.contract.d.ts

@@ -4,13 +4,13 @@
  * Canonical session lifecycle vocabulary shared by platform gateway auth,
  * hosted MCP auth, Master Control persistence, and SDK session tokens.
  */
-declare const SESSION_AUTH_MODES: readonly ["interactive_user", "service_principal", "tenant_api_key", "session_token"];
-type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
-declare const SESSION_PRINCIPAL_TYPES: readonly ["human", "service", "agent"];
-type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];
-declare const SESSION_LIFECYCLE_STATUSES: readonly ["active", "expired", "revoked"];
-type SessionLifecycleStatus = (typeof SESSION_LIFECYCLE_STATUSES)[number];
-type SessionDelegationHop = {
+export declare const SESSION_AUTH_MODES: readonly ["interactive_user", "service_principal", "tenant_api_key", "session_token"];
+export type SessionAuthMode = (typeof SESSION_AUTH_MODES)[number];
+export declare const SESSION_PRINCIPAL_TYPES: readonly ["human", "service", "agent"];
+export type SessionPrincipalType = (typeof SESSION_PRINCIPAL_TYPES)[number];
+export declare const SESSION_LIFECYCLE_STATUSES: readonly ["active", "expired", "revoked"];
+export type SessionLifecycleStatus = (typeof SESSION_LIFECYCLE_STATUSES)[number];
+export type SessionDelegationHop = {
     principalId: string;
     principalType: SessionPrincipalType;
     authMode?: SessionAuthMode;
@@ -18,8 +18,8 @@ type SessionDelegationHop = {
     delegatedAt?: number;
     reason?: string;
 };
-type SessionAuditOutcome = "accepted" | "rejected" | "revoked" | "expired";
-type SessionAuditEnvelope = {
+export type SessionAuditOutcome = "accepted" | "rejected" | "revoked" | "expired";
+export type SessionAuditEnvelope = {
     sessionId: string;
     authMode: SessionAuthMode;
     principalId: string;
@@ -42,14 +42,12 @@ type SessionAuditEnvelope = {
         reason?: string;
     };
 };
-declare function inferSessionPrincipalType(principalId: string): SessionPrincipalType;
-declare function normalizeDelegationChain(args: {
+export declare function inferSessionPrincipalType(principalId: string): SessionPrincipalType;
+export declare function normalizeDelegationChain(args: {
     delegationChain?: readonly SessionDelegationHop[];
     delegatedBy?: string;
     delegatedByType?: SessionPrincipalType;
     delegatedAt?: number;
     reason?: string;
 }): SessionDelegationHop[] | undefined;
-declare function lastDelegator(delegationChain?: readonly SessionDelegationHop[]): string | undefined;
-
-export { SESSION_AUTH_MODES, SESSION_LIFECYCLE_STATUSES, SESSION_PRINCIPAL_TYPES, type SessionAuditEnvelope, type SessionAuditOutcome, type SessionAuthMode, type SessionDelegationHop, type SessionLifecycleStatus, type SessionPrincipalType, inferSessionPrincipalType, lastDelegator, normalizeDelegationChain };
+export declare function lastDelegator(delegationChain?: readonly SessionDelegationHop[]): string | undefined;

package/dist/{contracts → lucern/contracts/src}/context-pack.contract.d.ts

@@ -14,7 +14,7 @@
  *   - Changing the version string is BREAKING (consumers check it)
  */
 /** Canonical version string. Consumers MUST check this field for compatibility. */
-declare const CONTEXT_PACK_SCHEMA_VERSION: "1.0.0";
+export declare const CONTEXT_PACK_SCHEMA_VERSION: "1.0.0";
 /**
  * Available ranking profiles for context-pack assembly.
  *
@@ -22,9 +22,9 @@ declare const CONTEXT_PACK_SCHEMA_VERSION: "1.0.0";
  * - `weighted_v1`: Multi-signal scoring combining query relevance, recency, confidence,
  *    belief type, priority, and severity with section-specific weight vectors.
  */
-type ContextRankingProfile = "baseline_v1" | "weighted_v1";
-declare const CONTEXT_RANKING_PROFILES: readonly ContextRankingProfile[];
-declare const DEFAULT_RANKING_PROFILE: ContextRankingProfile;
+export type ContextRankingProfile = "baseline_v1" | "weighted_v1";
+export declare const CONTEXT_RANKING_PROFILES: readonly ContextRankingProfile[];
+export declare const DEFAULT_RANKING_PROFILE: ContextRankingProfile;
 /**
  * Context compilation mode.
  *
@@ -32,14 +32,14 @@ declare const DEFAULT_RANKING_PROFILE: ContextRankingProfile;
  * - `delta`: Diff-aware — adds failure context, verification obligations,
  *    and worktree ledger analysis to the standard context pack.
  */
-type ContextCompilationMode = "standard" | "delta";
-declare const DEFAULT_COMPILATION_MODE: ContextCompilationMode;
+export type ContextCompilationMode = "standard" | "delta";
+export declare const DEFAULT_COMPILATION_MODE: ContextCompilationMode;
 /**
  * The five canonical sections of a context pack.
  * Order matters: invariants are injected first, contradictions last.
  */
-type ContextPackSectionKey = "invariants" | "activeBeliefs" | "openQuestions" | "recentEvidence" | "contradictions";
-declare const CONTEXT_PACK_SECTION_KEYS: readonly ContextPackSectionKey[];
+export type ContextPackSectionKey = "invariants" | "activeBeliefs" | "openQuestions" | "recentEvidence" | "contradictions";
+export declare const CONTEXT_PACK_SECTION_KEYS: readonly ContextPackSectionKey[];
 /**
  * Token budget allocation ratios per section.
  * These sum to 1.0 and determine how the total tokenBudget is divided.
@@ -51,19 +51,19 @@ declare const CONTEXT_PACK_SECTION_KEYS: readonly ContextPackSectionKey[];
  * - recentEvidence (0.17): Implementation context for grounding
  * - contradictions (0.08): Tension signals, smallest section
  */
-declare const SECTION_BUDGET_RATIOS: Readonly<Record<ContextPackSectionKey, number>>;
+export declare const SECTION_BUDGET_RATIOS: Readonly<Record<ContextPackSectionKey, number>>;
 /** Minimum allowed token budget. Below this, context packs lose utility. */
-declare const MIN_TOKEN_BUDGET = 400;
+export declare const MIN_TOKEN_BUDGET = 400;
 /** Maximum allowed token budget. Above this, context packs bloat prompts. */
-declare const MAX_TOKEN_BUDGET = 8000;
+export declare const MAX_TOKEN_BUDGET = 8000;
 /** Default token budget when caller does not specify. */
-declare const DEFAULT_TOKEN_BUDGET = 1800;
+export declare const DEFAULT_TOKEN_BUDGET = 1800;
 /** Default max items per section. */
-declare const DEFAULT_SECTION_LIMIT = 8;
+export declare const DEFAULT_SECTION_LIMIT = 8;
 /** Hard ceiling on items per section. */
-declare const MAX_SECTION_LIMIT = 25;
+export declare const MAX_SECTION_LIMIT = 25;
 /** Minimum contradiction section budget floor (tokens). */
-declare const MIN_CONTRADICTION_BUDGET = 40;
+export declare const MIN_CONTRADICTION_BUDGET = 40;
 /**
  * Weight vectors for the weighted_v1 ranking profile.
  * Each section has a different signal mix:
@@ -75,7 +75,7 @@ declare const MIN_CONTRADICTION_BUDGET = 40;
  * - priority: Question priority (critical > high > medium > low)
  * - severity: Contradiction severity (critical > high > medium > low)
  */
-type RankingWeightVector = {
+export type RankingWeightVector = {
     query: number;
     recency: number;
     confidence?: number;
@@ -83,35 +83,35 @@ type RankingWeightVector = {
     priority?: number;
     severity?: number;
 };
-declare const RANKING_WEIGHTS: Readonly<Record<ContextPackSectionKey, RankingWeightVector>>;
+export declare const RANKING_WEIGHTS: Readonly<Record<ContextPackSectionKey, RankingWeightVector>>;
 /** Recency decay half-life in days. After 30 days, recency score = 0.5. */
-declare const RECENCY_HALF_LIFE_DAYS = 30;
+export declare const RECENCY_HALF_LIFE_DAYS = 30;
 /**
  * Ranking weight vector for the relatedEntities section.
  * Entities are ranked by query relevance and connectivity (bridge edge count).
  * Separate from RANKING_WEIGHTS because entities are not part of the
  * token-budgeted injection plan.
  */
-declare const ENTITY_RANKING_WEIGHTS: {
+export declare const ENTITY_RANKING_WEIGHTS: {
     readonly query: 0.4;
     readonly connectivity: 0.6;
 };
 /** Default max entities to include in the context pack. */
-declare const DEFAULT_ENTITY_LIMIT = 10;
+export declare const DEFAULT_ENTITY_LIMIT = 10;
 /** Hard ceiling on entities per context pack. */
-declare const MAX_ENTITY_LIMIT = 50;
+export declare const MAX_ENTITY_LIMIT = 50;
 /**
  * Bonus multiplier for belief types in ranking.
  * Invariants get 1.0, unknown types get 0.4.
  */
-declare const BELIEF_TYPE_BONUS: Readonly<Record<string, number>>;
-declare const DEFAULT_BELIEF_TYPE_BONUS = 0.4;
-declare const PRIORITY_SCORES: Readonly<Record<string, number>>;
-declare const DEFAULT_PRIORITY_SCORE = 0.5;
-declare const SEVERITY_SCORES: Readonly<Record<string, number>>;
-declare const DEFAULT_SEVERITY_SCORE = 0.5;
+export declare const BELIEF_TYPE_BONUS: Readonly<Record<string, number>>;
+export declare const DEFAULT_BELIEF_TYPE_BONUS = 0.4;
+export declare const PRIORITY_SCORES: Readonly<Record<string, number>>;
+export declare const DEFAULT_PRIORITY_SCORE = 0.5;
+export declare const SEVERITY_SCORES: Readonly<Record<string, number>>;
+export declare const DEFAULT_SEVERITY_SCORE = 0.5;
 /** A ranked belief in the invariants or activeBeliefs section. */
-type ContextPackBelief = {
+export type ContextPackBelief = {
     nodeId: string;
     canonicalText: string;
     confidence: number | null;
@@ -124,7 +124,7 @@ type ContextPackBelief = {
     justification?: string;
 };
 /** A ranked question in the openQuestions section. */
-type ContextPackQuestion = {
+export type ContextPackQuestion = {
     questionId: string;
     text: string;
     status: string;
@@ -135,7 +135,7 @@ type ContextPackQuestion = {
     justification?: string;
 };
 /** A ranked evidence item in the recentEvidence section. */
-type ContextPackEvidence = {
+export type ContextPackEvidence = {
     nodeId: string;
     canonicalText: string;
     sourceUrl: string | null;
@@ -146,7 +146,7 @@ type ContextPackEvidence = {
     justification?: string;
 };
 /** A ranked contradiction in the contradictions section. */
-type ContextPackContradiction = {
+export type ContextPackContradiction = {
     contradictionId: string;
     severity: string;
     status: string;
@@ -161,7 +161,7 @@ type ContextPackContradiction = {
  * to beliefs via bridge edges. They provide the "reality anchor" that makes
  * the reasoning graph domain-aware.
  */
-type ContextPackEntity = {
+export type ContextPackEntity = {
     /** Convex document ID of the entity node. */
     nodeId: string;
     /** Entity type (e.g., "company", "person", "function"). */
@@ -181,7 +181,7 @@ type ContextPackEntity = {
  * A lattice seed entry representing a belief that was auto-generated
  * to cover an ontology entity type within a topic scope.
  */
-type BeliefLatticeSeed = {
+export type BeliefLatticeSeed = {
     /** The belief node ID that was created or already existed. */
     beliefNodeId: string;
     /** The entity type this seed belief covers. */
@@ -192,7 +192,7 @@ type BeliefLatticeSeed = {
     canonicalText: string;
 };
 /** Counts and scoped health signals for the context pack. */
-type ContextPackSummary = {
+export type ContextPackSummary = {
     totalBeliefs: number;
     invariants: number;
     openQuestions: number;
@@ -205,7 +205,7 @@ type ContextPackSummary = {
     query: string | null;
 };
 /** A failed approach surfaced from the failure log for anti-repetition. */
-type ContextPackFailure = {
+export type ContextPackFailure = {
     /** Lucern attempt/evidence node ID. */
     attemptId: string;
     /** What was tried. */
@@ -218,14 +218,14 @@ type ContextPackFailure = {
     score: number;
 };
 /** Failure context section appended to context packs in delta mode. */
-type ContextPackFailureContext = {
+export type ContextPackFailureContext = {
     /** Ranked failed approaches relevant to the current query. */
     failures: ContextPackFailure[];
     /** IDs of items suppressed from other sections due to anti-repetition. */
     suppressedIds: string[];
 };
 /** A verification obligation surfaced by delta compilation. */
-type VerificationObligation = {
+export type VerificationObligation = {
     /** What must be verified. */
     description: string;
     /** Source of the obligation (e.g., "belief:xyz confidence drop"). */
@@ -234,7 +234,7 @@ type VerificationObligation = {
     severity: "critical" | "high" | "medium" | "low";
 };
 /** Delta report appended to context packs when mode = "delta". */
-type ContextPackDeltaReport = {
+export type ContextPackDeltaReport = {
     /** Items that changed since the reference point (new, updated, removed). */
     changedItems: Array<{
         id: string;
@@ -251,14 +251,14 @@ type ContextPackDeltaReport = {
  * Per-section weight overrides that domain packs can apply.
  * Overrides merge with RANKING_WEIGHTS — only specified fields replace defaults.
  */
-type PackWeightOverride = {
+export type PackWeightOverride = {
     /** Which section to override weights for. */
     section: ContextPackSectionKey;
     /** Partial weight vector — only specified fields replace defaults. */
     weights: Partial<RankingWeightVector>;
 };
 /** Token-budgeted section selections for prompt injection. */
-type ContextPackInjectionPolicy = {
+export type ContextPackInjectionPolicy = {
     /** Total token budget for the entire context pack. */
     tokenBudget: number;
     /** Estimated tokens consumed across all sections. */
@@ -278,7 +278,7 @@ type ContextPackInjectionPolicy = {
     }>;
 };
 /** Telemetry for context pack assembly. */
-type ContextPackDiagnostics = {
+export type ContextPackDiagnostics = {
     /** Total candidates scored across all sections. */
     itemsScored: number;
     /** Ratio of estimatedTokens / tokenBudget. Range [0, 1+]. */
@@ -290,7 +290,7 @@ type ContextPackDiagnostics = {
  * This preserves the existing external shape while the canonical compiler
  * contract evolves in parallel as ContextPackV1.
  */
-type PublicContextBelief = {
+export type PublicContextBelief = {
     beliefId: string;
     text: string;
     confidence: number | null;
@@ -300,7 +300,7 @@ type PublicContextBelief = {
     score: number;
     justification?: string;
 };
-type PublicContextQuestion = {
+export type PublicContextQuestion = {
     questionId: string;
     text: string;
     status: string;
@@ -309,7 +309,7 @@ type PublicContextQuestion = {
     score: number;
     justification?: string;
 };
-type PublicContextEvidence = {
+export type PublicContextEvidence = {
     evidenceId: string;
     text: string;
     sourceUrl?: string | null;
@@ -318,7 +318,7 @@ type PublicContextEvidence = {
     score: number;
     justification?: string;
 };
-type PublicContextContradiction = {
+export type PublicContextContradiction = {
     contradictionId: string;
     severity: string;
     status: string;
@@ -326,7 +326,7 @@ type PublicContextContradiction = {
     score: number;
     justification?: string;
 };
-type PublicContextEntity = {
+export type PublicContextEntity = {
     entityId: string;
     entityType: string;
     title: string;
@@ -336,7 +336,7 @@ type PublicContextEntity = {
     score: number;
     metadata?: Record<string, unknown>;
 };
-type PublicContextInjectionPolicy = {
+export type PublicContextInjectionPolicy = {
     tokenBudget: number;
     estimatedTokens: number;
     sectionBudgets: Record<string, number>;
@@ -349,7 +349,7 @@ type PublicContextInjectionPolicy = {
         score: number;
     }>;
 };
-type PublicCompiledContext = {
+export type PublicCompiledContext = {
     schemaVersion: string;
     topicId: string;
     topicName: string;
@@ -400,9 +400,11 @@ type PublicCompiledContext = {
  * in the output. Adding optional fields is non-breaking; removing or
  * changing types is breaking (requires version bump).
  */
-type ContextPackV1 = {
+export type ContextPackV1 = {
     /** Schema version for compatibility checking. */
     schemaVersion: typeof CONTEXT_PACK_SCHEMA_VERSION;
+    /** Deprecated compatibility alias for the requested scope ID. */
+    projectId?: string;
     /** Resolved topic ID after scope resolution. */
     topicId: string;
     /** Human-readable topic name. */
@@ -448,11 +450,13 @@ type ContextPackV1 = {
 };
 /**
  * The canonical input schema for `compile_context`.
- * `topicId` is the only scope identifier.
+ * `topicId` is canonical. `projectId` remains an optional compatibility alias.
  */
-type ContextPackRequestV1 = {
+export type ContextPackRequestV1 = {
     /** Topic scope ID (required). */
     topicId: string;
+    /** Deprecated compatibility alias for older callers. */
+    projectId?: string;
     /** Focus query for relevance ranking. */
     query?: string;
     /** Max items per section. Default: DEFAULT_SECTION_LIMIT. */
@@ -480,13 +484,11 @@ type ContextPackRequestV1 = {
  * Question statuses that are considered "resolved" (not open).
  * Used to filter which questions appear in the openQuestions section.
  */
-declare const RESOLVED_QUESTION_STATUSES: readonly string[];
+export declare const RESOLVED_QUESTION_STATUSES: readonly string[];
 /**
  * Tokens-per-word multiplier for rough token estimation.
  * Conservative estimate: ~1.35 tokens per whitespace-delimited word.
  */
-declare const TOKENS_PER_WORD = 1.35;
+export declare const TOKENS_PER_WORD = 1.35;
 /** Minimum token estimate for any non-empty string. */
-declare const MIN_TOKEN_ESTIMATE = 8;
-
-export { BELIEF_TYPE_BONUS, type BeliefLatticeSeed, CONTEXT_PACK_SCHEMA_VERSION, CONTEXT_PACK_SECTION_KEYS, CONTEXT_RANKING_PROFILES, type ContextCompilationMode, type ContextPackBelief, type ContextPackContradiction, type ContextPackDeltaReport, type ContextPackDiagnostics, type ContextPackEntity, type ContextPackEvidence, type ContextPackFailure, type ContextPackFailureContext, type ContextPackInjectionPolicy, type ContextPackQuestion, type ContextPackRequestV1, type ContextPackSectionKey, type ContextPackSummary, type ContextPackV1, type ContextRankingProfile, DEFAULT_BELIEF_TYPE_BONUS, DEFAULT_COMPILATION_MODE, DEFAULT_ENTITY_LIMIT, DEFAULT_PRIORITY_SCORE, DEFAULT_RANKING_PROFILE, DEFAULT_SECTION_LIMIT, DEFAULT_SEVERITY_SCORE, DEFAULT_TOKEN_BUDGET, ENTITY_RANKING_WEIGHTS, MAX_ENTITY_LIMIT, MAX_SECTION_LIMIT, MAX_TOKEN_BUDGET, MIN_CONTRADICTION_BUDGET, MIN_TOKEN_BUDGET, MIN_TOKEN_ESTIMATE, PRIORITY_SCORES, type PackWeightOverride, type PublicCompiledContext, type PublicContextBelief, type PublicContextContradiction, type PublicContextEntity, type PublicContextEvidence, type PublicContextInjectionPolicy, type PublicContextQuestion, RANKING_WEIGHTS, RECENCY_HALF_LIFE_DAYS, RESOLVED_QUESTION_STATUSES, type RankingWeightVector, SECTION_BUDGET_RATIOS, SEVERITY_SCORES, TOKENS_PER_WORD, type VerificationObligation };
+export declare const MIN_TOKEN_ESTIMATE = 8;

package/dist/{contracts → lucern/contracts/src}/lens-filter.contract.d.ts

@@ -21,7 +21,7 @@
  *
  * V2 will add `propertyMatchers` here for arbitrary JSON Schema facet queries.
  */
-type EntityTypeFilterV1 = {
+export type EntityTypeFilterV1 = {
     /** References ontologyVersion.entityTypes[].value, e.g. "company" */
     entityTypeValue: string;
     /** Optional subtype narrowing. If omitted or empty, all subtypes match. */
@@ -31,14 +31,14 @@ type EntityTypeFilterV1 = {
  * Optional scope to restrict which ontology the filter resolves against.
  * If omitted, resolution uses whatever ontology is active in the workspace.
  */
-type OntologyScope = {
+export type OntologyScope = {
     /** Restrict to a specific ontology by key, e.g. "vc-investment" */
     ontologyKey?: string;
 };
 /**
  * Taxonomy filter criteria v1: entity type + subtype matching over ontology.
  */
-type TaxonomyFilterCriteriaV1 = {
+export type TaxonomyFilterCriteriaV1 = {
     version: 1;
     kind: "taxonomy";
     entityTypeFilters: EntityTypeFilterV1[];
@@ -54,10 +54,10 @@ type TaxonomyFilterCriteriaV1 = {
  *   3. Add a resolver in taxonomy-filter.ts
  *   4. No schema migration needed — filterCriteria is v.any()
  */
-type LensFilterCriteria = TaxonomyFilterCriteriaV1;
-declare function isLensFilterCriteria(value: unknown): value is LensFilterCriteria;
-declare function isTaxonomyFilterCriteriaV1(value: unknown): value is TaxonomyFilterCriteriaV1;
-type FilterValidationResult = {
+export type LensFilterCriteria = TaxonomyFilterCriteriaV1;
+export declare function isLensFilterCriteria(value: unknown): value is LensFilterCriteria;
+export declare function isTaxonomyFilterCriteriaV1(value: unknown): value is TaxonomyFilterCriteriaV1;
+export type FilterValidationResult = {
     valid: true;
 } | {
     valid: false;
@@ -67,6 +67,4 @@ type FilterValidationResult = {
  * Validate a filter criteria document at the contract layer.
  * This runs before persisting to Convex.
  */
-declare function validateFilterCriteria(value: unknown): FilterValidationResult;
-
-export { type EntityTypeFilterV1, type FilterValidationResult, type LensFilterCriteria, type OntologyScope, type TaxonomyFilterCriteriaV1, isLensFilterCriteria, isTaxonomyFilterCriteriaV1, validateFilterCriteria };
+export declare function validateFilterCriteria(value: unknown): FilterValidationResult;

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