@lucern/sdk 1.0.28 → 1.0.30

package/dist/contracts/context-pack.contract.d.ts

@@ -76,14 +76,14 @@ export declare const MIN_CONTRADICTION_BUDGET = 40;
  * - priority: Question priority (critical > high > medium > low)
  * - severity: Contradiction severity (critical > high > medium > low)
  */
-export type RankingWeightVector = {
-    query: number;
-    recency: number;
-    confidence?: number;
+export interface RankingWeightVector {
     beliefType?: number;
+    confidence?: number;
     priority?: number;
+    query: number;
+    recency: number;
     severity?: number;
-};
+}
 export declare const RANKING_WEIGHTS: Readonly<Record<ContextPackSectionKey, RankingWeightVector>>;
 /** Recency decay half-life in days. After 30 days, recency score = 0.5. */
 export declare const RECENCY_HALF_LIFE_DAYS = 30;
@@ -112,130 +112,130 @@ 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. */
-export type ContextPackBelief = {
-    nodeId: string;
+export interface ContextPackBelief {
+    beliefType: string | null;
     canonicalText: string;
     confidence: number | null;
-    beliefType: string | null;
+    /** Human-readable explanation of why this item was ranked here (RS-2). */
+    justification?: string;
+    nodeId: string;
     score: number;
     /** Present in activeBeliefs, absent in invariants */
     status?: string;
     updatedAt?: number | null;
+}
+/** A ranked question in the openQuestions section. */
+export interface ContextPackQuestion {
     /** Human-readable explanation of why this item was ranked here (RS-2). */
     justification?: string;
-};
-/** A ranked question in the openQuestions section. */
-export type ContextPackQuestion = {
+    priority: string;
     questionId: string;
-    text: string;
+    score: number;
     status: string;
-    priority: string;
+    text: string;
     updatedAt?: number | null;
-    score: number;
-    /** Human-readable explanation of why this item was ranked here (RS-2). */
-    justification?: string;
-};
+}
 /** A ranked evidence item in the recentEvidence section. */
-export type ContextPackEvidence = {
-    nodeId: string;
+export interface ContextPackEvidence {
     canonicalText: string;
-    sourceUrl: string | null;
-    kind: string;
     createdAt: number | null;
-    score: number;
     /** Human-readable explanation of why this item was ranked here (RS-2). */
     justification?: string;
-};
+    kind: string;
+    nodeId: string;
+    score: number;
+    sourceUrl: string | null;
+}
 /** A ranked contradiction in the contradictions section. */
-export type ContextPackContradiction = {
+export interface ContextPackContradiction {
     contradictionId: string;
-    severity: string;
-    status: string;
     description: string;
-    score: number;
     /** Human-readable explanation of why this item was ranked here (RS-2). */
     justification?: string;
-};
+    score: number;
+    severity: string;
+    status: string;
+}
 /**
  * An entity from the ontological layer surfaced in the context pack.
  * Entities are domain objects (companies, people, functions, etc.) connected
  * to beliefs via bridge edges. They provide the "reality anchor" that makes
  * the reasoning graph domain-aware.
  */
-export type ContextPackEntity = {
-    /** Convex document ID of the entity node. */
-    nodeId: string;
-    /** Entity type (e.g., "company", "person", "function"). */
-    entityType: string;
-    /** Human-readable title/name of the entity. */
-    title: string;
+export interface ContextPackEntity {
     /** Number of beliefs connected to this entity via bridge edges. */
     connectedBeliefCount: number;
     /** Number of evidence items referencing this entity. */
     connectedEvidenceCount: number;
-    /** Relevance score from ranking algorithm. */
-    score: number;
+    /** Entity type (e.g., "company", "person", "function"). */
+    entityType: string;
     /** Entity metadata (structured per ontology schema). */
     metadata?: Record<string, unknown>;
-};
+    /** Convex document ID of the entity node. */
+    nodeId: string;
+    /** Relevance score from ranking algorithm. */
+    score: number;
+    /** Human-readable title/name of the entity. */
+    title: string;
+}
 /**
  * A lattice seed entry representing a belief that was auto-generated
  * to cover an ontology entity type within a topic scope.
  */
-export type BeliefLatticeSeed = {
+export interface BeliefLatticeSeed {
     /** The belief node ID that was created or already existed. */
     beliefNodeId: string;
-    /** The entity type this seed belief covers. */
-    entityType: string;
-    /** Whether this seed was newly created or already existed. */
-    created: boolean;
     /** The canonical text of the seed belief. */
     canonicalText: string;
-};
+    /** Whether this seed was newly created or already existed. */
+    created: boolean;
+    /** The entity type this seed belief covers. */
+    entityType: string;
+}
 /** Counts and scoped health signals for the context pack. */
-export type ContextPackSummary = {
-    totalBeliefs: number;
+export interface ContextPackSummary {
+    contradictions: number;
+    descendantDepth: number;
+    evidenceItems: number;
     invariants: number;
     openQuestions: number;
-    evidenceItems: number;
-    contradictions: number;
+    query: string | null;
     /** Number of ontological entities in scope (optional, present when entity graph is active). */
     relatedEntities?: number;
     scopedTopics: number;
-    descendantDepth: number;
-    query: string | null;
-};
+    totalBeliefs: number;
+}
 /** A failed approach surfaced from the failure log for anti-repetition. */
-export type ContextPackFailure = {
-    /** Lucern attempt/evidence node ID. */
-    attemptId: string;
+export interface ContextPackFailure {
     /** What was tried. */
     approach: string;
+    /** Lucern attempt/evidence node ID. */
+    attemptId: string;
     /** Why it failed. */
     outcome: string;
     /** When the attempt was recorded (ms since epoch). */
     recordedAt: number;
     /** Relevance score from ranking algorithm. */
     score: number;
-};
+}
 /** Failure context section appended to context packs in delta mode. */
-export type ContextPackFailureContext = {
+export interface 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. */
-export type VerificationObligation = {
+export interface VerificationObligation {
     /** What must be verified. */
     description: string;
-    /** Source of the obligation (e.g., "belief:xyz confidence drop"). */
-    source: string;
     /** Severity: how important it is to verify. */
     severity: "critical" | "high" | "medium" | "low";
-};
+    /** Source of the obligation (e.g., "belief:xyz confidence drop"). */
+    source: string;
+}
 /** Delta report appended to context packs when mode = "delta". */
-export type ContextPackDeltaReport = {
+export interface ContextPackDeltaReport {
     /** Items that changed since the reference point (new, updated, removed). */
     changedItems: Array<{
         id: string;
@@ -243,33 +243,25 @@ export type ContextPackDeltaReport = {
         changeType: "added" | "updated" | "removed" | "confidence_changed";
         summary: string;
     }>;
-    /** Obligations the consuming session must verify. */
-    verificationObligations: VerificationObligation[];
     /** Reference point for the delta (worktree ID, timestamp, or commit SHA). */
     referencePoint: string;
-};
+    /** Obligations the consuming session must verify. */
+    verificationObligations: VerificationObligation[];
+}
 /**
  * Per-section weight overrides that domain packs can apply.
  * Overrides merge with RANKING_WEIGHTS — only specified fields replace defaults.
  */
-export type PackWeightOverride = {
+export interface 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. */
-export type ContextPackInjectionPolicy = {
-    /** Total token budget for the entire context pack. */
-    tokenBudget: number;
+export interface ContextPackInjectionPolicy {
     /** Estimated tokens consumed across all sections. */
     estimatedTokens: number;
-    /** Per-section token budgets derived from SECTION_BUDGET_RATIOS. */
-    sectionBudgets: Record<ContextPackSectionKey, number>;
-    /** Actual token usage per section after greedy fill. */
-    sectionUsage: Record<ContextPackSectionKey, number>;
-    /** Node/question IDs selected for injection, per section. */
-    selected: Record<ContextPackSectionKey, string[]>;
     /** Items that were scored but excluded from injection, with reason (RS-2). */
     excludedItems?: Array<{
         id: string;
@@ -277,86 +269,88 @@ export type ContextPackInjectionPolicy = {
         reason: "budget_exceeded" | "anti_repetition" | "below_threshold";
         score: number;
     }>;
-};
+    /** Per-section token budgets derived from SECTION_BUDGET_RATIOS. */
+    sectionBudgets: Record<ContextPackSectionKey, number>;
+    /** Actual token usage per section after greedy fill. */
+    sectionUsage: Record<ContextPackSectionKey, number>;
+    /** Node/question IDs selected for injection, per section. */
+    selected: Record<ContextPackSectionKey, string[]>;
+    /** Total token budget for the entire context pack. */
+    tokenBudget: number;
+}
 /** Telemetry for context pack assembly. */
-export type ContextPackDiagnostics = {
+export interface ContextPackDiagnostics {
     /** Total candidates scored across all sections. */
     itemsScored: number;
     /** Ratio of estimatedTokens / tokenBudget. Range [0, 1+]. */
     tokenBudgetUtilization: number;
-};
+}
 /**
  * Public context surface returned by the SDK-facing context client.
  *
  * This preserves the existing external shape while the canonical compiler
  * contract evolves in parallel as ContextPackV1.
  */
-export type PublicContextBelief = {
+export interface PublicContextBelief {
     beliefId: string;
-    text: string;
-    confidence: number | null;
     beliefType?: string | null;
+    confidence: number | null;
+    justification?: string;
+    score: number;
     status?: string;
+    text: string;
     updatedAt?: number | null;
-    score: number;
+}
+export interface PublicContextQuestion {
     justification?: string;
-};
-export type PublicContextQuestion = {
+    priority: string;
     questionId: string;
-    text: string;
+    score: number;
     status: string;
-    priority: string;
+    text: string;
     updatedAt?: number | null;
-    score: number;
-    justification?: string;
-};
-export type PublicContextEvidence = {
+}
+export interface PublicContextEvidence {
+    createdAt?: number | null;
     evidenceId: string;
-    text: string;
-    sourceUrl?: string | null;
+    justification?: string;
     kind: string;
-    createdAt?: number | null;
     score: number;
-    justification?: string;
-};
-export type PublicContextContradiction = {
+    sourceUrl?: string | null;
+    text: string;
+}
+export interface PublicContextContradiction {
     contradictionId: string;
-    severity: string;
-    status: string;
     description: string;
-    score: number;
     justification?: string;
-};
-export type PublicContextEntity = {
-    entityId: string;
-    entityType: string;
-    title: string;
-    text?: string;
+    score: number;
+    severity: string;
+    status: string;
+}
+export interface PublicContextEntity {
     connectedBeliefCount: number;
     connectedEvidenceCount: number;
-    score: number;
+    entityId: string;
+    entityType: string;
     metadata?: Record<string, unknown>;
-};
-export type PublicContextInjectionPolicy = {
-    tokenBudget: number;
+    score: number;
+    text?: string;
+    title: string;
+}
+export interface PublicContextInjectionPolicy {
     estimatedTokens: number;
-    sectionBudgets: Record<string, number>;
-    sectionUsage: Record<string, number>;
-    selected: Record<string, string[]>;
     excludedItems?: Array<{
         id: string;
         section: string;
         reason: "budget_exceeded" | "anti_repetition" | "below_threshold";
         score: number;
     }>;
-};
-export type PublicContextNarrativeBlock = {
-    kind: string;
-    text: string;
-    recordsNamed?: number;
-    narrativeId?: string;
-    narrative_id?: string;
-    scope?: Record<string, unknown>;
+    sectionBudgets: Record<string, number>;
+    sectionUsage: Record<string, number>;
+    selected: Record<string, string[]>;
+    tokenBudget: number;
+}
+export interface PublicContextNarrativeBlock {
     childNarratives?: Array<{
         narrativeId: string;
         narrative_id?: string;
@@ -365,51 +359,31 @@ export type PublicContextNarrativeBlock = {
         summary: string;
         recordsNamed?: number;
     }>;
-};
-export type PublicContextSupportingObjects = {
-    invariants?: PublicContextBelief[];
+    kind: string;
+    narrative_id?: string;
+    narrativeId?: string;
+    recordsNamed?: number;
+    scope?: Record<string, unknown>;
+    text: string;
+}
+export interface PublicContextSupportingObjects {
     activeBeliefs?: PublicContextBelief[];
-    openQuestions?: PublicContextQuestion[];
-    recentEvidence?: PublicContextEvidence[];
     contradictions?: PublicContextContradiction[];
-    relatedEntities?: PublicContextEntity[];
-    worktrees?: unknown[];
-    lanes?: string[];
     entities?: unknown[];
-};
-export type PublicCompiledContext = {
-    contextNarrative: Array<string | PublicContextNarrativeBlock>;
-    narrativeCoverage?: Record<string, unknown>;
-    synthesisLints?: SynthesisQualityLint[];
-    retrievalReceipt?: Record<string, unknown>;
-    assemblyReceipt?: Record<string, unknown>;
-    supportingObjects?: PublicContextSupportingObjects;
-    schemaVersion: string;
-    topicId: string;
-    topicName: string;
-    scopedTopicIds: string[];
-    generatedAt: number;
-    ranking: ContextRankingProfile;
-    summary: Record<string, unknown>;
     invariants?: PublicContextBelief[];
-    activeBeliefs?: PublicContextBelief[];
+    lanes?: string[];
     openQuestions?: PublicContextQuestion[];
     recentEvidence?: PublicContextEvidence[];
-    contradictions?: PublicContextContradiction[];
     relatedEntities?: PublicContextEntity[];
-    injectionPolicy: PublicContextInjectionPolicy;
-    diagnostics: Record<string, unknown>;
+    worktrees?: unknown[];
+}
+export interface PublicCompiledContext {
+    activeBeliefs?: PublicContextBelief[];
+    appliedWeightOverrides?: unknown[];
+    assemblyReceipt?: Record<string, unknown>;
     compilationMode?: string;
-    failureContext?: {
-        failures: Array<{
-            attemptId: string;
-            approach: string;
-            outcome: string;
-            recordedAt: number;
-            score: number;
-        }>;
-        suppressedIds: string[];
-    };
+    contextNarrative: Array<string | PublicContextNarrativeBlock>;
+    contradictions?: PublicContextContradiction[];
     deltaReport?: {
         changedItems: Array<{
             id: string;
@@ -424,8 +398,34 @@ export type PublicCompiledContext = {
         }>;
         referencePoint: string;
     };
-    appliedWeightOverrides?: unknown[];
-};
+    diagnostics: Record<string, unknown>;
+    failureContext?: {
+        failures: Array<{
+            attemptId: string;
+            approach: string;
+            outcome: string;
+            recordedAt: number;
+            score: number;
+        }>;
+        suppressedIds: string[];
+    };
+    generatedAt: number;
+    injectionPolicy: PublicContextInjectionPolicy;
+    invariants?: PublicContextBelief[];
+    narrativeCoverage?: Record<string, unknown>;
+    openQuestions?: PublicContextQuestion[];
+    ranking: ContextRankingProfile;
+    recentEvidence?: PublicContextEvidence[];
+    relatedEntities?: PublicContextEntity[];
+    retrievalReceipt?: Record<string, unknown>;
+    schemaVersion: string;
+    scopedTopicIds: string[];
+    summary: Record<string, unknown>;
+    supportingObjects?: PublicContextSupportingObjects;
+    synthesisLints?: SynthesisQualityLint[];
+    topicId: string;
+    topicName: string;
+}
 /**
  * The canonical output schema for context compilation responses.
  *
@@ -433,88 +433,88 @@ export type PublicCompiledContext = {
  * in the output. Adding optional fields is non-breaking; removing or
  * changing types is breaking (requires version bump).
  */
-export type ContextPackV1 = {
-    /** Schema version for compatibility checking. */
-    schemaVersion: typeof CONTEXT_PACK_SCHEMA_VERSION;
-    /** Resolved topic ID after scope resolution. */
-    topicId: string;
-    /** Human-readable topic name. */
-    topicName: string;
-    /** All topic IDs included in the neighborhood expansion. */
-    scopedTopicIds: string[];
+export interface ContextPackV1 {
+    /** Active beliefs ranked by query relevance. */
+    activeBeliefs: ContextPackBelief[];
+    /** Pack weight overrides applied during ranking (RS-2). */
+    appliedWeightOverrides?: PackWeightOverride[];
+    /** Compilation mode used to generate this pack (RS-2). Default: "standard". */
+    compilationMode?: ContextCompilationMode;
+    /** Concise instructions for agent context injection. */
+    contextNarrative: Array<string | PublicContextNarrativeBlock>;
+    /** Active contradictions ranked by severity. */
+    contradictions: ContextPackContradiction[];
+    /** Delta report (RS-2). Present only when compilationMode = "delta". */
+    deltaReport?: ContextPackDeltaReport;
+    /** Assembly telemetry. */
+    diagnostics: ContextPackDiagnostics;
+    /** Failure context for anti-repetition (RS-2). Present when failures are relevant. */
+    failureContext?: ContextPackFailureContext;
     /** Deterministic freshness watermark for this pack (ms since epoch). */
     generatedAt: number;
-    /** Which ranking profile was used. */
-    rankingProfile: ContextRankingProfile;
-    /** Aggregate counts and health signals. */
-    summary: ContextPackSummary;
+    /** Token-budgeted injection selections. */
+    injectionPolicy: ContextPackInjectionPolicy;
     /** High-confidence invariant beliefs (beliefType = "invariant"). */
     invariants: ContextPackBelief[];
-    /** Active beliefs ranked by query relevance. */
-    activeBeliefs: ContextPackBelief[];
     /** Open questions ranked by relevance and priority. */
     openQuestions: ContextPackQuestion[];
+    /** Which ranking profile was used. */
+    rankingProfile: ContextRankingProfile;
     /** Recent evidence ranked by relevance and recency. */
     recentEvidence: ContextPackEvidence[];
-    /** Active contradictions ranked by severity. */
-    contradictions: ContextPackContradiction[];
     /**
      * Ontological entities connected to beliefs in scope, ranked by connectivity.
      * Optional — present when entity graph substrate is active for this topic.
      * NON-BREAKING addition per contract rules.
      */
     relatedEntities?: ContextPackEntity[];
-    /** Concise instructions for agent context injection. */
-    contextNarrative: Array<string | PublicContextNarrativeBlock>;
-    /** Token-budgeted injection selections. */
-    injectionPolicy: ContextPackInjectionPolicy;
-    /** Assembly telemetry. */
-    diagnostics: ContextPackDiagnostics;
-    /** Compilation mode used to generate this pack (RS-2). Default: "standard". */
-    compilationMode?: ContextCompilationMode;
-    /** Failure context for anti-repetition (RS-2). Present when failures are relevant. */
-    failureContext?: ContextPackFailureContext;
-    /** Delta report (RS-2). Present only when compilationMode = "delta". */
-    deltaReport?: ContextPackDeltaReport;
-    /** Pack weight overrides applied during ranking (RS-2). */
-    appliedWeightOverrides?: PackWeightOverride[];
-};
+    /** Schema version for compatibility checking. */
+    schemaVersion: typeof CONTEXT_PACK_SCHEMA_VERSION;
+    /** All topic IDs included in the neighborhood expansion. */
+    scopedTopicIds: string[];
+    /** Aggregate counts and health signals. */
+    summary: ContextPackSummary;
+    /** Resolved topic ID after scope resolution. */
+    topicId: string;
+    /** Human-readable topic name. */
+    topicName: string;
+}
 /**
  * The canonical input schema for `compile_context`.
  * `topicId` is the only scope identifier.
  */
-export type ContextPackRequestV1 = {
-    /** Topic scope ID (required). */
-    topicId: string;
-    /** Focus query for relevance ranking. */
-    query?: string;
+export interface ContextPackRequestV1 {
+    /**
+     * Maximum carrier topics to enrich with raw belief/question/evidence rows for
+     * explicit dimension-seeded compiles. The full dimension is still synthesized
+     * through worktrees and receipts; this only bounds raw content fan-out.
+     */
+    contentTopicLimit?: number;
+    /** Include ontological entities connected to beliefs in scope. Default: true. */
+    includeEntities?: boolean;
+    /** Include failure log context for anti-repetition (RS-2). Default: false. */
+    includeFailures?: boolean;
     /** Max items per section. Default: DEFAULT_SECTION_LIMIT. */
     limit?: number;
-    /** Ranking profile. Default: DEFAULT_RANKING_PROFILE. */
-    rankingProfile?: ContextRankingProfile;
-    /** Total token budget. Default: DEFAULT_TOKEN_BUDGET. */
-    tokenBudget?: number;
     /** Descendant topic depth for neighborhood expansion. */
     maxDepth?: number;
-    /** Include ontological entities connected to beliefs in scope. Default: true. */
-    includeEntities?: boolean;
     /** Compilation mode (RS-2). Default: "standard". */
     mode?: ContextCompilationMode;
-    /** Include failure log context for anti-repetition (RS-2). Default: false. */
-    includeFailures?: boolean;
-    /** Active worktree ID for delta mode reference point (RS-2). */
-    worktreeId?: string;
-    /** Session ID for anti-repetition dedup (RS-2). */
-    sessionId?: string;
     /** Pack weight overrides from domain pack binding (RS-2). */
     packWeightOverrides?: PackWeightOverride[];
-    /**
-     * Maximum carrier topics to enrich with raw belief/question/evidence rows for
-     * explicit dimension-seeded compiles. The full dimension is still synthesized
-     * through worktrees and receipts; this only bounds raw content fan-out.
-     */
-    contentTopicLimit?: number;
-};
+    /** Focus query for relevance ranking. */
+    query?: string;
+    /** Ranking profile. Default: DEFAULT_RANKING_PROFILE. */
+    rankingProfile?: ContextRankingProfile;
+    /** Session ID for anti-repetition dedup (RS-2). */
+    sessionId?: string;
+    /** Total token budget. Default: DEFAULT_TOKEN_BUDGET. */
+    tokenBudget?: number;
+    /** Topic scope ID (required). */
+    topicId: string;
+    /** Active worktree ID for delta mode reference point (RS-2). */
+    worktreeId?: string;
+}
 /**
  * Question statuses that are considered "resolved" (not open).
  * Used to filter which questions appear in the openQuestions section.

package/dist/contracts/contextPack.js

@@ -1,2 +1,4 @@
+// biome-ignore-all lint/style/useFilenamingConvention: This file is an @lucern/sdk public import ABI / package subpath compatibility surface; the camelCase filename is intentional.
+// biome-ignore-all lint/performance/noBarrelFile: This file is an @lucern/sdk public import ABI / package subpath compatibility surface; the facade/barrel export is intentional.
 export * from "./context-pack.contract.js";
 //# sourceMappingURL=contextPack.js.map

package/dist/contracts/index.d.ts

@@ -4,8 +4,8 @@ export * from "./contextPack";
 export * from "./lensFilter";
 export * from "./lensWorkflow";
 export * from "./mcpTools";
-export * as mcpToolsContract from "./tool-contracts";
 export * from "./prompt";
 export * as sdkToolsContract from "./sdk-tools.contract";
+export * as mcpToolsContract from "./tool-contracts";
 export * from "./workflowRuntime";
 //# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.js

@@ -1,11 +1,12 @@
+// biome-ignore-all lint/performance/noBarrelFile: This file is an @lucern/sdk public import ABI / package subpath compatibility surface; the facade/barrel export is intentional.
 export * from "./api-enums.contract.js";
 export * from "./auth-session.contract.js";
 export * from "./contextPack.js";
 export * from "./lensFilter.js";
 export * from "./lensWorkflow.js";
 export * from "./mcpTools.js";
-export * as mcpToolsContract from "./tool-contracts.js";
 export * from "./prompt.js";
 export * as sdkToolsContract from "./sdk-tools.contract.js";
+export * as mcpToolsContract from "./tool-contracts.js";
 export * from "./workflowRuntime.js";
 //# sourceMappingURL=index.js.map