@lucern/sdk 1.0.29 → 1.0.31

package/dist/contextPackCompiler.js

@@ -1,6 +1,8 @@
-import { CONTEXT_PACK_SCHEMA_VERSION, DEFAULT_COMPILATION_MODE, DEFAULT_ENTITY_LIMIT, MAX_ENTITY_LIMIT, } from "./contracts/context-pack.contract.js";
+// biome-ignore-all lint/style/useFilenamingConvention: This file is an @lucern/sdk public import ABI / package subpath compatibility surface; the camelCase filename is intentional.
 import { buildInjectionPlan, parseTokenBudget, rankContextSection, rankEntities, resolveEffectiveWeights, } from "./contextPackPolicy.js";
 import { validateContextPackSchema } from "./contextPackSchema.js";
+import { CONTEXT_PACK_SCHEMA_VERSION, DEFAULT_COMPILATION_MODE, DEFAULT_ENTITY_LIMIT, MAX_ENTITY_LIMIT, } from "./contracts/context-pack.contract.js";
+const QUERY_TOKEN_SPLIT_PATTERN = /[^a-z0-9]+/;
 function assertContextPackSchema(payload) {
     const result = validateContextPackSchema(payload);
     if (!result.valid) {
@@ -28,7 +30,7 @@ function normalizeQueryTokens(query) {
     }
     return query
         .toLowerCase()
-        .split(/[^a-z0-9]+/)
+        .split(QUERY_TOKEN_SPLIT_PATTERN)
         .map((token) => token.trim())
         .filter((token) => token.length >= 2);
 }
@@ -129,7 +131,11 @@ function candidateTimestamp(candidate) {
     if (!isRecord(candidate)) {
         return 0;
     }
-    const timestamps = [candidate.updatedAt, candidate.createdAt, candidate.generatedAt].filter((value) => typeof value === "number" && Number.isFinite(value));
+    const timestamps = [
+        candidate.updatedAt,
+        candidate.createdAt,
+        candidate.generatedAt,
+    ].filter((value) => typeof value === "number" && Number.isFinite(value));
     return timestamps.length > 0 ? Math.max(...timestamps) : 0;
 }
 function resolveReferenceTimeMs(...collections) {
@@ -144,45 +150,73 @@ function resolveReferenceTimeMs(...collections) {
     }
     return maxTimestamp;
 }
+function contradictionSeverity(weight) {
+    if (weight <= -0.9) {
+        return "critical";
+    }
+    if (weight <= -0.7) {
+        return "high";
+    }
+    if (weight <= -0.5) {
+        return "medium";
+    }
+    return "low";
+}
+function optionalArgString(args, key) {
+    const value = args[key];
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function rankingProfileFromArgs(args) {
+    return parseRankingProfile(typeof args.ranking === "string" ? args.ranking : args.rankingProfile);
+}
+function tokenBudgetFromArgs(args) {
+    return parseTokenBudget(typeof args.budget === "number" ? args.budget : args.tokenBudget, 1800);
+}
+function descendantDepthFromArgs(args, topic) {
+    const topicDepth = typeof topic.depth === "number" && Number.isFinite(topic.depth)
+        ? topic.depth
+        : 0;
+    if (typeof args.maxDepth === "number" && Number.isFinite(args.maxDepth)) {
+        return Math.max(1, Math.min(Math.floor(args.maxDepth), 6));
+    }
+    return topicDepth <= 1 ? 4 : 2;
+}
+function packWeightOverridesFromArgs(args) {
+    return Array.isArray(args.packWeightOverrides)
+        ? args.packWeightOverrides
+        : undefined;
+}
+function scopedTopicIdsForPlan(input, topicId, descendantDepth, args) {
+    const scopedTopicIds = collectTopicNeighborhood(input.allTopics, topicId, descendantDepth);
+    const allowedTopicIds = asStringArray(args.allowedTopicIds);
+    if (allowedTopicIds.length === 0) {
+        return scopedTopicIds;
+    }
+    const allowedSet = new Set(allowedTopicIds);
+    if (!allowedSet.has(topicId)) {
+        throw new Error(`Access denied to compile context for topic ${topicId}.`);
+    }
+    return scopedTopicIds.filter((id) => allowedSet.has(id));
+}
 export function planContextPackCompilation(input) {
     const args = input.args ?? {};
     const topicId = String(input.topic._id);
-    const queryText = typeof args.query === "string" && args.query.trim().length > 0
-        ? args.query.trim()
-        : undefined;
+    const queryText = optionalArgString(args, "query");
     const tokens = normalizeQueryTokens(queryText);
     const limit = toPositiveInt(args.limit, 8, 25);
-    const rankingProfile = parseRankingProfile(typeof args.ranking === "string" ? args.ranking : args.rankingProfile);
-    const tokenBudget = parseTokenBudget(typeof args.budget === "number" ? args.budget : args.tokenBudget, 1800);
-    const topicDepth = typeof input.topic.depth === "number" && Number.isFinite(input.topic.depth)
-        ? input.topic.depth
-        : 0;
-    const requestedMaxDepth = typeof args.maxDepth === "number" && Number.isFinite(args.maxDepth)
-        ? Math.max(1, Math.min(Math.floor(args.maxDepth), 6))
-        : undefined;
-    const descendantDepth = requestedMaxDepth ?? (topicDepth <= 1 ? 4 : 2);
+    const rankingProfile = rankingProfileFromArgs(args);
+    const tokenBudget = tokenBudgetFromArgs(args);
+    const descendantDepth = descendantDepthFromArgs(args, input.topic);
     const includeEntities = args.includeEntities !== false;
     const compilationMode = args.mode === "delta" ? "delta" : DEFAULT_COMPILATION_MODE;
     const includeFailures = compilationMode === "delta" || args.includeFailures === true;
-    const worktreeId = typeof args.worktreeId === "string" && args.worktreeId.trim().length > 0
-        ? args.worktreeId.trim()
-        : undefined;
-    const sessionId = typeof args.sessionId === "string" && args.sessionId.trim().length > 0
-        ? args.sessionId.trim()
-        : undefined;
-    const packWeightOverrides = Array.isArray(args.packWeightOverrides)
-        ? args.packWeightOverrides
-        : undefined;
+    const worktreeId = optionalArgString(args, "worktreeId");
+    const sessionId = optionalArgString(args, "sessionId");
+    const packWeightOverrides = packWeightOverridesFromArgs(args);
     const effectiveWeights = resolveEffectiveWeights(packWeightOverrides);
-    let scopedTopicIds = collectTopicNeighborhood(input.allTopics, topicId, descendantDepth);
-    const allowedTopicIds = asStringArray(args.allowedTopicIds);
-    if (allowedTopicIds.length > 0) {
-        const allowedSet = new Set(allowedTopicIds);
-        if (!allowedSet.has(topicId)) {
-            throw new Error(`Access denied to compile context for topic ${topicId}.`);
-        }
-        scopedTopicIds = scopedTopicIds.filter((id) => allowedSet.has(id));
-    }
+    const scopedTopicIds = scopedTopicIdsForPlan(input, topicId, descendantDepth, args);
     return {
         topicId,
         ...(queryText ? { queryText } : {}),
@@ -201,17 +235,7 @@ export function planContextPackCompilation(input) {
         scopedTopicIds,
     };
 }
-export function compileContextPackFromSnapshot(snapshot) {
-    const uniqueBeliefs = dedupeById(snapshot.beliefs);
-    const uniqueQuestions = dedupeById(snapshot.questions);
-    const uniqueEvidence = dedupeById(snapshot.evidence);
-    const uniqueContradictions = dedupeById(snapshot.contradictions);
-    const referenceTimeMs = resolveReferenceTimeMs([snapshot.topic], uniqueBeliefs, uniqueQuestions, uniqueEvidence, uniqueContradictions, snapshot.entities) || 0;
-    const rankOptions = {
-        effectiveWeights: snapshot.plan.effectiveWeights,
-        includeJustifications: snapshot.plan.compilationMode === "delta",
-        referenceTimeMs,
-    };
+function compileBeliefSections(uniqueBeliefs, plan, rankOptions) {
     const invariantCandidates = uniqueBeliefs
         .filter((belief) => beliefTypeOf(belief).toLowerCase() === "invariant")
         .map((belief) => ({
@@ -225,7 +249,7 @@ export function compileContextPackFromSnapshot(snapshot) {
         ...candidate,
         id: candidate.nodeId,
         text: `${candidate.canonicalText} ${candidate.beliefType}`,
-    })), snapshot.plan.tokens, snapshot.plan.limit, snapshot.plan.rankingProfile, rankOptions).map((row) => ({
+    })), plan.tokens, plan.limit, plan.rankingProfile, rankOptions).map((row) => ({
         nodeId: row.nodeId,
         canonicalText: row.canonicalText,
         confidence: row.confidence,
@@ -250,7 +274,7 @@ export function compileContextPackFromSnapshot(snapshot) {
         ...candidate,
         id: candidate.nodeId,
         text: `${candidate.canonicalText} ${candidate.metadataText}`,
-    })), snapshot.plan.tokens, snapshot.plan.limit, snapshot.plan.rankingProfile, rankOptions).map((row) => ({
+    })), plan.tokens, plan.limit, plan.rankingProfile, rankOptions).map((row) => ({
         nodeId: row.nodeId,
         canonicalText: row.canonicalText,
         confidence: row.confidence,
@@ -260,6 +284,14 @@ export function compileContextPackFromSnapshot(snapshot) {
         score: row.score,
         ...(row.justification ? { justification: row.justification } : {}),
     }));
+    return {
+        activeBeliefCandidates,
+        activeBeliefs,
+        invariantCandidates,
+        invariants,
+    };
+}
+function compileOpenQuestions(uniqueQuestions, plan, rankOptions) {
     const openQuestionCandidates = uniqueQuestions
         .map((question) => {
         const status = questionStatusOf(question);
@@ -280,7 +312,7 @@ export function compileContextPackFromSnapshot(snapshot) {
         ...candidate,
         id: candidate.questionId,
         text: `${candidate.text} ${candidate.metadataText}`,
-    })), snapshot.plan.tokens, snapshot.plan.limit, snapshot.plan.rankingProfile, rankOptions).map((row) => ({
+    })), plan.tokens, plan.limit, plan.rankingProfile, rankOptions).map((row) => ({
         questionId: row.questionId,
         text: row.text,
         status: row.status,
@@ -289,6 +321,9 @@ export function compileContextPackFromSnapshot(snapshot) {
         score: row.score,
         ...(row.justification ? { justification: row.justification } : {}),
     }));
+    return { openQuestionCandidates, openQuestions };
+}
+function compileRecentEvidence(uniqueEvidence, plan, rankOptions) {
     const evidenceCandidates = uniqueEvidence.map((item) => {
         const metadata = item.metadata && typeof item.metadata === "object" ? item.metadata : {};
         return {
@@ -307,7 +342,7 @@ export function compileContextPackFromSnapshot(snapshot) {
         ...candidate,
         id: candidate.nodeId,
         text: `${candidate.canonicalText} ${candidate.metadataText}`,
-    })), snapshot.plan.tokens, snapshot.plan.limit, snapshot.plan.rankingProfile, rankOptions).map((row) => ({
+    })), plan.tokens, plan.limit, plan.rankingProfile, rankOptions).map((row) => ({
         nodeId: row.nodeId,
         canonicalText: row.canonicalText,
         sourceUrl: row.sourceUrl,
@@ -316,18 +351,14 @@ export function compileContextPackFromSnapshot(snapshot) {
         score: row.score,
         ...(row.justification ? { justification: row.justification } : {}),
     }));
+    return { evidenceCandidates, recentEvidence };
+}
+function compileContradictions(uniqueContradictions, plan, rankOptions) {
     const contradictionCandidates = uniqueContradictions.map((row) => {
         const weight = typeof row.weight === "number" ? row.weight : 0;
-        const severity = weight <= -0.9
-            ? "critical"
-            : weight <= -0.7
-                ? "high"
-                : weight <= -0.5
-                    ? "medium"
-                    : "low";
         return {
             contradictionId: String(row._id || row.globalId || ""),
-            severity,
+            severity: contradictionSeverity(weight),
             status: "active",
             description: row.context || row.description || row.summary || "",
             updatedAt: row.updatedAt || row.createdAt || null,
@@ -337,7 +368,7 @@ export function compileContextPackFromSnapshot(snapshot) {
         ...candidate,
         id: candidate.contradictionId,
         text: `${candidate.description} ${candidate.severity}`,
-    })), snapshot.plan.tokens, snapshot.plan.limit, snapshot.plan.rankingProfile, rankOptions).map((row) => ({
+    })), plan.tokens, plan.limit, plan.rankingProfile, rankOptions).map((row) => ({
         contradictionId: row.contradictionId,
         severity: row.severity,
         status: row.status,
@@ -345,85 +376,123 @@ export function compileContextPackFromSnapshot(snapshot) {
         score: row.score,
         ...(row.justification ? { justification: row.justification } : {}),
     }));
-    const entityCandidates = snapshot.entities.map((row) => ({
+    return { contradictionCandidates, contradictions };
+}
+function compileEntities(entities, plan) {
+    const entityCandidates = entities.map((row) => ({
         nodeId: String(row._id),
         entityType: String(row.nodeType || ""),
         title: String(row.title || ""),
         canonicalText: String(row.canonicalText || ""),
-        connectedBeliefCount: typeof row.connectedBeliefCount === "number" ? row.connectedBeliefCount : 0,
+        connectedBeliefCount: typeof row.connectedBeliefCount === "number"
+            ? row.connectedBeliefCount
+            : 0,
         connectedEvidenceCount: typeof row.connectedEvidenceCount === "number"
             ? row.connectedEvidenceCount
             : 0,
         metadata: row.metadata && typeof row.metadata === "object" ? row.metadata : {},
         updatedAt: row.updatedAt || null,
     }));
-    const entityLimit = toPositiveInt(snapshot.plan.limit, DEFAULT_ENTITY_LIMIT, MAX_ENTITY_LIMIT);
-    const rankedEntities = snapshot.plan.includeEntities
-        ? rankEntities(entityCandidates, snapshot.plan.tokens, entityLimit).map((row) => ({
-            nodeId: row.nodeId,
-            entityType: row.entityType,
-            title: row.title,
-            connectedBeliefCount: row.connectedBeliefCount,
-            connectedEvidenceCount: row.connectedEvidenceCount,
+    if (!plan.includeEntities) {
+        return { entityCandidates };
+    }
+    const entityLimit = toPositiveInt(plan.limit, DEFAULT_ENTITY_LIMIT, MAX_ENTITY_LIMIT);
+    const rankedEntities = rankEntities(entityCandidates, plan.tokens, entityLimit).map((row) => ({
+        nodeId: row.nodeId,
+        entityType: row.entityType,
+        title: row.title,
+        connectedBeliefCount: row.connectedBeliefCount,
+        connectedEvidenceCount: row.connectedEvidenceCount,
+        score: row.score,
+        ...(Object.keys(row.metadata).length > 0 ? { metadata: row.metadata } : {}),
+    }));
+    return { entityCandidates, rankedEntities };
+}
+function compileFailureContext(args) {
+    if (!(args.plan.includeFailures && args.failures)) {
+        return;
+    }
+    const allFailures = args.failures.filter((node) => {
+        const metadata = isRecord(node.metadata) ? node.metadata : {};
+        return (metadata.failedApproach === true || metadata.isFailedAttempt === true);
+    });
+    const rankedFailures = rankContextSection("recentEvidence", allFailures.map((node) => ({
+        id: String(node._id),
+        text: String(node.canonicalText || ""),
+        createdAt: node.createdAt || null,
+        updatedAt: node.updatedAt || node.createdAt || null,
+    })), args.plan.tokens, 10, args.plan.rankingProfile, args.rankOptions);
+    const failures = rankedFailures.map((row) => {
+        const original = allFailures.find((node) => String(node._id) === row.id);
+        const metadata = isRecord(original?.metadata) ? original?.metadata : {};
+        return {
+            attemptId: row.id,
+            approach: String(row.text || ""),
+            outcome: String(metadata.errorMessage || "Failed"),
+            recordedAt: row.createdAt || args.referenceTimeMs || 0,
             score: row.score,
-            ...(Object.keys(row.metadata).length > 0
-                ? { metadata: row.metadata }
-                : {}),
-        }))
-        : undefined;
-    let failureContext;
-    if (snapshot.plan.includeFailures && snapshot.failures) {
-        const allFailures = snapshot.failures.filter((node) => {
-            const metadata = isRecord(node.metadata) ? node.metadata : {};
-            return metadata.failedApproach === true || metadata.isFailedAttempt === true;
-        });
-        const rankedFailures = rankContextSection("recentEvidence", allFailures.map((node) => ({
-            id: String(node._id),
-            text: String(node.canonicalText || ""),
-            createdAt: node.createdAt || null,
-            updatedAt: node.updatedAt || node.createdAt || null,
-        })), snapshot.plan.tokens, 10, snapshot.plan.rankingProfile, rankOptions);
-        const failures = rankedFailures.map((row) => {
-            const original = allFailures.find((node) => String(node._id) === row.id);
-            const metadata = isRecord(original?.metadata) ? original?.metadata : {};
-            return {
-                attemptId: row.id,
-                approach: String(row.text || ""),
-                outcome: String(metadata.errorMessage || "Failed"),
-                recordedAt: row.createdAt || referenceTimeMs || 0,
-                score: row.score,
-            };
-        });
-        const failureTexts = new Set(failures.map((failure) => failure.approach.toLowerCase().slice(0, 100)));
-        const suppressionIds = new Set();
-        if (snapshot.plan.sessionId && failureTexts.size > 0) {
-            for (const evidenceRow of recentEvidence) {
-                const evidenceText = evidenceRow.canonicalText.toLowerCase().slice(0, 100);
-                for (const failureText of failureTexts) {
-                    if (evidenceText.includes(failureText) ||
-                        failureText.includes(evidenceText)) {
-                        suppressionIds.add(evidenceRow.nodeId);
-                        break;
-                    }
+        };
+    });
+    if (failures.length === 0) {
+        return;
+    }
+    const failureTexts = new Set(failures.map((failure) => failure.approach.toLowerCase().slice(0, 100)));
+    const suppressionIds = new Set();
+    if (args.plan.sessionId && failureTexts.size > 0) {
+        for (const evidenceRow of args.recentEvidence) {
+            const evidenceText = evidenceRow.canonicalText
+                .toLowerCase()
+                .slice(0, 100);
+            for (const failureText of failureTexts) {
+                if (evidenceText.includes(failureText) ||
+                    failureText.includes(evidenceText)) {
+                    suppressionIds.add(evidenceRow.nodeId);
+                    break;
                 }
             }
         }
-        if (failures.length > 0) {
-            failureContext = {
-                failures,
-                suppressedIds: Array.from(suppressionIds),
-            };
-        }
     }
+    return {
+        failures,
+        suppressedIds: Array.from(suppressionIds),
+    };
+}
+function applyFailureSuppression(recentEvidence, failureContext) {
     const suppressionSet = new Set(failureContext?.suppressedIds || []);
-    const effectiveEvidence = suppressionSet.size > 0
-        ? recentEvidence.filter((row) => !suppressionSet.has(row.nodeId))
-        : recentEvidence;
-    const suppressedEvidenceIds = suppressionSet.size > 0
-        ? recentEvidence
+    if (suppressionSet.size === 0) {
+        return { effectiveEvidence: recentEvidence, suppressedEvidenceIds: [] };
+    }
+    return {
+        effectiveEvidence: recentEvidence.filter((row) => !suppressionSet.has(row.nodeId)),
+        suppressedEvidenceIds: recentEvidence
             .filter((row) => suppressionSet.has(row.nodeId))
-            .map((row) => row.nodeId)
-        : [];
+            .map((row) => row.nodeId),
+    };
+}
+export function compileContextPackFromSnapshot(snapshot) {
+    const uniqueBeliefs = dedupeById(snapshot.beliefs);
+    const uniqueQuestions = dedupeById(snapshot.questions);
+    const uniqueEvidence = dedupeById(snapshot.evidence);
+    const uniqueContradictions = dedupeById(snapshot.contradictions);
+    const referenceTimeMs = resolveReferenceTimeMs([snapshot.topic], uniqueBeliefs, uniqueQuestions, uniqueEvidence, uniqueContradictions, snapshot.entities) || 0;
+    const rankOptions = {
+        effectiveWeights: snapshot.plan.effectiveWeights,
+        includeJustifications: snapshot.plan.compilationMode === "delta",
+        referenceTimeMs,
+    };
+    const { activeBeliefCandidates, activeBeliefs, invariantCandidates, invariants, } = compileBeliefSections(uniqueBeliefs, snapshot.plan, rankOptions);
+    const { openQuestionCandidates, openQuestions } = compileOpenQuestions(uniqueQuestions, snapshot.plan, rankOptions);
+    const { evidenceCandidates, recentEvidence } = compileRecentEvidence(uniqueEvidence, snapshot.plan, rankOptions);
+    const { contradictionCandidates, contradictions } = compileContradictions(uniqueContradictions, snapshot.plan, rankOptions);
+    const { entityCandidates, rankedEntities } = compileEntities(snapshot.entities, snapshot.plan);
+    const failureContext = compileFailureContext({
+        failures: snapshot.failures,
+        plan: snapshot.plan,
+        rankOptions,
+        recentEvidence,
+        referenceTimeMs,
+    });
+    const { effectiveEvidence, suppressedEvidenceIds } = applyFailureSuppression(recentEvidence, failureContext);
     const summary = {
         totalBeliefs: uniqueBeliefs.length,
         invariants: invariants.length,
@@ -493,6 +562,7 @@ export function compileContextPackFromSnapshot(snapshot) {
         topicName: snapshot.topic.name || "Untitled Topic",
         scopedTopicIds: snapshot.plan.scopedTopicIds,
         generatedAt: referenceTimeMs,
+        ranking: snapshot.plan.rankingProfile,
         rankingProfile: snapshot.plan.rankingProfile,
         summary,
         invariants,
@@ -518,9 +588,9 @@ export function compileContextPackFromSnapshot(snapshot) {
                 : Number((injectionPolicy.estimatedTokens / injectionPolicy.tokenBudget).toFixed(4)),
             referenceTimeMs,
         },
-        ...(snapshot.plan.compilationMode !== "standard"
-            ? { compilationMode: snapshot.plan.compilationMode }
-            : {}),
+        ...(snapshot.plan.compilationMode === "standard"
+            ? {}
+            : { compilationMode: snapshot.plan.compilationMode }),
         ...(failureContext ? { failureContext } : {}),
         ...(deltaReport ? { deltaReport } : {}),
         ...(snapshot.plan.packWeightOverrides &&

package/dist/contextPackPolicy.d.ts

@@ -1,38 +1,38 @@
-import { type PackWeightOverride, type RankingWeightVector, type ContextPackSectionKey, type ContextRankingProfile } from "./contracts/context-pack.contract";
+import { type ContextPackSectionKey, type ContextRankingProfile, type PackWeightOverride, type RankingWeightVector } from "./contracts/context-pack.contract";
 export type SectionKey = ContextPackSectionKey;
-export type RankCandidate = {
-    id: string;
-    text: string;
-    updatedAt?: number | null;
-    createdAt?: number | null;
-    confidence?: number | null;
+export interface RankCandidate {
     beliefType?: string | null;
+    confidence?: number | null;
+    createdAt?: number | null;
+    id: string;
     priority?: string | null;
     severity?: string | null;
-};
+    text: string;
+    updatedAt?: number | null;
+}
 export type RankedCandidate<T extends RankCandidate> = T & {
     score: number;
     justification?: string;
 };
-type LexicalExclusion = {
+interface LexicalExclusion {
     id: string;
-    section: SectionKey;
     reason: "budget_exceeded" | "anti_repetition" | "below_threshold";
     score: number;
-};
-export type InjectionPlan = {
-    tokenBudget: number;
+    section: SectionKey;
+}
+export interface InjectionPlan {
     estimatedTokens: number;
+    excludedItems?: LexicalExclusion[];
     sectionBudgets: Record<SectionKey, number>;
     sectionUsage: Record<SectionKey, number>;
     selected: Record<SectionKey, string[]>;
-    excludedItems?: LexicalExclusion[];
-};
-type RankContextOptions = {
+    tokenBudget: number;
+}
+interface RankContextOptions {
     effectiveWeights?: Readonly<Record<ContextPackSectionKey, RankingWeightVector>>;
     includeJustifications?: boolean;
     referenceTimeMs?: number;
-};
+}
 export declare function resolveEffectiveWeights(overrides?: PackWeightOverride[]): Readonly<Record<ContextPackSectionKey, RankingWeightVector>>;
 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;
@@ -65,16 +65,16 @@ export declare function buildInjectionPlan(args: {
     }>;
     trackExclusions?: boolean;
 }): InjectionPlan;
-export type EntityCandidate = {
-    nodeId: string;
-    entityType: string;
-    title: string;
+export interface EntityCandidate {
     canonicalText: string;
     connectedBeliefCount: number;
     connectedEvidenceCount: number;
+    entityType: string;
     metadata: Record<string, unknown>;
+    nodeId: string;
+    title: string;
     updatedAt?: number | null;
-};
+}
 export type RankedEntity = EntityCandidate & {
     score: number;
 };

package/dist/contextPackPolicy.js

@@ -1,4 +1,6 @@
-import { BELIEF_TYPE_BONUS, DEFAULT_ENTITY_LIMIT, DEFAULT_BELIEF_TYPE_BONUS, DEFAULT_PRIORITY_SCORE, DEFAULT_SEVERITY_SCORE, DEFAULT_TOKEN_BUDGET, ENTITY_RANKING_WEIGHTS, MAX_TOKEN_BUDGET, MAX_ENTITY_LIMIT, MIN_CONTRADICTION_BUDGET, MIN_TOKEN_BUDGET, MIN_TOKEN_ESTIMATE, PRIORITY_SCORES, RANKING_WEIGHTS, RECENCY_HALF_LIFE_DAYS, SECTION_BUDGET_RATIOS, SEVERITY_SCORES, TOKENS_PER_WORD, } from "./contracts/context-pack.contract.js";
+// biome-ignore-all lint/style/useFilenamingConvention: This file is an @lucern/sdk public import ABI / package subpath compatibility surface; the camelCase filename is intentional.
+import { BELIEF_TYPE_BONUS, DEFAULT_BELIEF_TYPE_BONUS, DEFAULT_ENTITY_LIMIT, DEFAULT_PRIORITY_SCORE, DEFAULT_SEVERITY_SCORE, DEFAULT_TOKEN_BUDGET, ENTITY_RANKING_WEIGHTS, MAX_ENTITY_LIMIT, MAX_TOKEN_BUDGET, MIN_CONTRADICTION_BUDGET, MIN_TOKEN_BUDGET, MIN_TOKEN_ESTIMATE, PRIORITY_SCORES, RANKING_WEIGHTS, RECENCY_HALF_LIFE_DAYS, SECTION_BUDGET_RATIOS, SEVERITY_SCORES, TOKENS_PER_WORD, } from "./contracts/context-pack.contract.js";
+const TOKEN_SPLIT_PATTERN = /\s+/;
 function tokenHits(text, tokens) {
     if (tokens.length === 0) {
         return 1;
@@ -19,7 +21,7 @@ function clamp01(value) {
     return Math.max(0, Math.min(1, value));
 }
 function recencyScore(updatedAt, referenceTimeMs = Date.now()) {
-    if (!updatedAt || !Number.isFinite(updatedAt)) {
+    if (!(updatedAt && Number.isFinite(updatedAt))) {
         return 0.25;
     }
     const ageMs = Math.max(0, referenceTimeMs - updatedAt);
@@ -58,15 +60,16 @@ export function resolveEffectiveWeights(overrides) {
     }
     return result;
 }
-function generateJustification(_section, candidate, queryTokens, weights) {
-    const parts = [];
-    const hits = tokenHits(candidate.text, queryTokens);
+function appendQueryJustification(parts, text, queryTokens) {
+    const hits = tokenHits(text, queryTokens);
     if (queryTokens.length > 0 && hits > 0) {
         parts.push(`${hits}/${queryTokens.length} query terms matched`);
     }
     else if (queryTokens.length === 0) {
         parts.push("no query filter");
     }
+}
+function appendFreshnessJustification(parts, candidate) {
     const ts = candidate.updatedAt || candidate.createdAt || null;
     if (ts && Number.isFinite(ts)) {
         const ageDays = Math.max(0, Date.now() - ts) / (1000 * 60 * 60 * 24);
@@ -83,6 +86,8 @@ function generateJustification(_section, candidate, queryTokens, weights) {
             parts.push(`updated ${Math.floor(ageDays)}d ago (decayed)`);
         }
     }
+}
+function appendWeightedFieldJustifications(parts, candidate, weights) {
     if (weights.confidence !== undefined &&
         candidate.confidence !== null &&
         candidate.confidence !== undefined) {
@@ -97,8 +102,17 @@ function generateJustification(_section, candidate, queryTokens, weights) {
     if (weights.severity !== undefined && candidate.severity) {
         parts.push(`severity=${candidate.severity}`);
     }
+}
+function generateJustification(_section, candidate, queryTokens, weights) {
+    const parts = [];
+    appendQueryJustification(parts, candidate.text, queryTokens);
+    appendFreshnessJustification(parts, candidate);
+    appendWeightedFieldJustifications(parts, candidate, weights);
     return parts.join(", ");
 }
+function computeBaselineScore(candidate, queryTokens) {
+    return queryTokens.length === 0 ? 1 : tokenHits(candidate.text, queryTokens);
+}
 function computeWeightedScore(section, candidate, queryTokens, effectiveWeights, referenceTimeMs) {
     const weights = (effectiveWeights ?? RANKING_WEIGHTS)[section];
     const queryComponent = queryTokens.length === 0
@@ -127,9 +141,7 @@ export function rankContextSection(section, rows, queryTokens, limit, profile, o
     const scored = rows.map((row) => {
         const score = profile === "weighted_v1"
             ? computeWeightedScore(section, row, queryTokens, effectiveWeights, referenceTimeMs)
-            : queryTokens.length === 0
-                ? 1
-                : tokenHits(row.text, queryTokens);
+            : computeBaselineScore(row, queryTokens);
         const result = { ...row, score };
         if (includeJustifications && profile === "weighted_v1") {
             const weights = (effectiveWeights ?? RANKING_WEIGHTS)[section];
@@ -155,7 +167,7 @@ export function parseTokenBudget(value, fallback = DEFAULT_TOKEN_BUDGET) {
     return Math.max(MIN_TOKEN_BUDGET, Math.min(MAX_TOKEN_BUDGET, parsed));
 }
 function estimateTokens(text) {
-    const words = text.trim().split(/\s+/).filter(Boolean).length;
+    const words = text.trim().split(TOKEN_SPLIT_PATTERN).filter(Boolean).length;
     return Math.max(MIN_TOKEN_ESTIMATE, Math.ceil(words * TOKENS_PER_WORD));
 }
 export function buildInjectionPlan(args) {

package/dist/contextPackSchema.d.ts

@@ -1,7 +1,7 @@
-type ValidationResult = {
-    valid: boolean;
+interface ValidationResult {
     errors: string[];
-};
+    valid: boolean;
+}
 export declare function validateContextPackSchema(payload: unknown): ValidationResult;
 export {};
 //# sourceMappingURL=contextPackSchema.d.ts.map

package/dist/contextPackSchema.js

@@ -1,3 +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.
 const CONTEXT_PACK_SCHEMA_VERSION = "1.0.0";
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);