sneakoscope 7.3.0 → 7.6.0

package/dist/core/triwiki/context-graph/projections/anchors.js

@@ -0,0 +1,91 @@
+import { CONTEXT_GRAPH_RANKING_CONFIG, groundContextGraphNode } from '../query/index.js';
+export const ATTENTION_FACT_TRUST_FLOOR = 0.6;
+const MAX_HINT_LENGTH = 240;
+const MAX_HINT_CITATIONS = 4;
+export function isFactGradeAnchor(trust, freshness) {
+    return freshness === 'fresh' && trust >= ATTENTION_FACT_TRUST_FLOOR;
+}
+export function attentionHydrateHint(provenance, trust, freshness, risk, factGrade) {
+    const reasons = [];
+    if (!factGrade)
+        reasons.push('trust_action:hydrate_first');
+    if (freshness !== 'fresh')
+        reasons.push(`freshness:${freshness}`);
+    if (risk === 'protected' || risk === 'high')
+        reasons.push(`risk:${risk}`);
+    if (trust < ATTENTION_FACT_TRUST_FLOOR)
+        reasons.push(`trust:${trust.toFixed(2)}`);
+    const paths = [...new Set(provenance.map((ref) => ref.path).filter(Boolean))].slice(0, MAX_HINT_CITATIONS);
+    if (paths.length > 0)
+        reasons.push(`code_citations:${paths.join(',')}`);
+    const hint = reasons.join(';');
+    return hint ? hint.slice(0, MAX_HINT_LENGTH) : null;
+}
+function anchorOf(id, node, trust, freshness, risk, tokenCost, reasonPath, provenance) {
+    const factGrade = isFactGradeAnchor(trust, freshness);
+    const firstHash = provenance[0]?.hash ?? null;
+    return {
+        id,
+        claim_hash: factGrade ? node?.contentHash ?? firstHash : null,
+        source_hash: factGrade ? firstHash : null,
+        hydrate_hint: attentionHydrateHint(provenance, trust, freshness, risk, factGrade),
+        reason_path: reasonPath,
+        trust_score: Number(trust.toFixed(2)),
+        freshness,
+        token_cost: Math.max(0, Math.trunc(tokenCost)),
+        provenance
+    };
+}
+export function projectContextGraphAnchors(index, selected, limit) {
+    const anchors = [];
+    const seen = new Set();
+    for (const node of selected) {
+        if (anchors.length >= limit)
+            break;
+        if (seen.has(node.nodeId) || node.provenance.length === 0)
+            continue;
+        seen.add(node.nodeId);
+        anchors.push(anchorOf(node.nodeId, index.nodesById.get(node.nodeId), node.trust, node.freshness, node.risk, node.tokenCost, [...node.reasonPath], [...node.provenance]));
+    }
+    return anchors;
+}
+export function resolveContextGraphAnchorNode(index, anchorId) {
+    const direct = index.nodesById.get(anchorId);
+    if (direct)
+        return direct;
+    if (!anchorId.startsWith('code:'))
+        return null;
+    const rest = anchorId.slice('code:'.length);
+    const byId = index.nodesById.get(rest);
+    if (byId)
+        return byId;
+    for (const candidate of index.nodesByLabel.get(rest.toLowerCase()) ?? []) {
+        const node = index.nodesById.get(candidate);
+        if (node?.kind === 'module')
+            return node;
+    }
+    return null;
+}
+export function projectContextPackAnchors(index, anchors) {
+    const out = [];
+    for (const anchor of anchors) {
+        const node = resolveContextGraphAnchorNode(index, anchor.id);
+        if (!node) {
+            out.push({
+                id: anchor.id,
+                claim_hash: null,
+                source_hash: null,
+                hydrate_hint: anchor.hydrate_hint ?? 'trust_action:hydrate_first;graph:unresolved_anchor',
+                reason_path: [],
+                trust_score: 0,
+                freshness: 'unknown',
+                token_cost: 0,
+                provenance: []
+            });
+            continue;
+        }
+        const provenance = groundContextGraphNode(index, node, [], CONTEXT_GRAPH_RANKING_CONFIG);
+        out.push(anchorOf(anchor.id, node, node.trust, node.freshness, node.risk, node.tokenCost, [node.id], provenance));
+    }
+    return out;
+}

package/dist/core/triwiki/context-graph/projections/attention.js

@@ -0,0 +1,58 @@
+import { CONTEXT_GRAPH_REPAIR_COMMAND } from '../contracts.js';
+import { contextGraphQueryProfile } from '../profiles.js';
+import { queryContextGraphSnapshot } from '../query/index.js';
+import { loadContextGraphIndex } from '../query/load.js';
+import { projectContextGraphAnchors } from './anchors.js';
+export const CONTEXT_GRAPH_ATTENTION_TOKEN_BUDGET = 2000;
+function unavailable(reason, profile, tokenBudget, warnings, snapshotHash) {
+    return {
+        available: false,
+        reason,
+        anchors: [],
+        profile,
+        snapshotHash,
+        snapshotFreshness: null,
+        tokenCost: 0,
+        tokenBudget,
+        provenanceCoverage: 0,
+        warnings: [...warnings],
+        repairCommand: CONTEXT_GRAPH_REPAIR_COMMAND
+    };
+}
+export async function readContextGraphAttention(request, options = {}) {
+    const profile = contextGraphQueryProfile(request.profile).name;
+    const tokenBudget = Math.max(0, request.tokenBudget ?? CONTEXT_GRAPH_ATTENTION_TOKEN_BUDGET);
+    const limit = Math.max(0, Math.trunc(request.limit));
+    const question = String(request.query ?? '').trim();
+    if (!question || limit === 0)
+        return unavailable('empty_query', profile, tokenBudget, [], null);
+    const load = await loadContextGraphIndex(request.root, options);
+    if (!load.ok || !load.index) {
+        return unavailable(load.errorCode ?? 'context_graph_missing', profile, tokenBudget, load.errors, load.snapshotHash || null);
+    }
+    const result = queryContextGraphSnapshot(load.index, {
+        root: request.root,
+        query: question,
+        profile,
+        tokenBudget,
+        maxSelected: limit,
+        ...(request.risk === undefined ? {} : { risk: request.risk })
+    }, { snapshotFreshness: load.freshness, warnings: load.warnings });
+    const anchors = projectContextGraphAnchors(load.index, result.selected, limit);
+    if (anchors.length === 0) {
+        return unavailable('context_graph_no_match', profile, tokenBudget, result.warnings, result.snapshotHash);
+    }
+    return {
+        available: true,
+        reason: null,
+        anchors,
+        profile: result.profile,
+        snapshotHash: result.snapshotHash,
+        snapshotFreshness: result.snapshotFreshness,
+        tokenCost: anchors.reduce((sum, anchor) => sum + anchor.token_cost, 0),
+        tokenBudget,
+        provenanceCoverage: result.provenanceCoverage,
+        warnings: result.warnings,
+        repairCommand: CONTEXT_GRAPH_REPAIR_COMMAND
+    };
+}

package/dist/core/triwiki/context-graph/projections/code-pack-workspace.js

@@ -0,0 +1,62 @@
+import { CONTEXT_GRAPH_REPAIR_COMMAND } from '../contracts.js';
+import { readSourceHashes } from '../compiler/freshness.js';
+import { readContextGraphMeta } from '../store/snapshot-store.js';
+import { loadContextGraphIndex } from '../query/load.js';
+import { projectCodePackFromGraph } from './code-pack.js';
+const MAX_FRESHNESS_SOURCES = 512;
+function citedPaths(pack) {
+    const paths = new Set();
+    for (const entry of pack.entries) {
+        for (const citation of entry.citations) {
+            if (citation.path)
+                paths.add(citation.path);
+            if (paths.size >= MAX_FRESHNESS_SOURCES)
+                return [...paths];
+        }
+    }
+    return [...paths];
+}
+export async function buildWorkspaceCodePack(root, options = {}) {
+    const load = await loadContextGraphIndex(root, options);
+    if (!load.ok || !load.index) {
+        return {
+            ok: false,
+            pack: null,
+            errorCode: load.errorCode,
+            errors: load.errors,
+            warnings: load.warnings,
+            snapshotHash: load.snapshotHash,
+            snapshotFreshness: 'stale',
+            candidateCount: 0,
+            omittedForBudget: 0,
+            repairCommand: CONTEXT_GRAPH_REPAIR_COMMAND
+        };
+    }
+    const metaLoad = await readContextGraphMeta(root);
+    const gitHeadSha = metaLoad.status === 'ok' && metaLoad.meta ? metaLoad.meta.cacheKeyParts.head : null;
+    const base = {
+        tokenBudget: options.tokenBudget,
+        query: options.query,
+        profile: options.profile,
+        risk: options.risk,
+        maxEntries: options.maxEntries,
+        generatedAt: options.generatedAt,
+        gitHeadSha,
+        snapshotFreshness: load.freshness
+    };
+    const firstPass = projectCodePackFromGraph(root, load.index, base);
+    const observedSourceHashes = await readSourceHashes(root, citedPaths(firstPass.pack));
+    const projection = projectCodePackFromGraph(root, load.index, { ...base, observedSourceHashes });
+    return {
+        ok: true,
+        pack: projection.pack,
+        errorCode: null,
+        errors: [],
+        warnings: load.warnings,
+        snapshotHash: load.snapshotHash,
+        snapshotFreshness: load.freshness,
+        candidateCount: projection.candidateCount,
+        omittedForBudget: projection.omittedForBudget,
+        repairCommand: CONTEXT_GRAPH_REPAIR_COMMAND
+    };
+}

package/dist/core/triwiki/context-graph/projections/code-pack.js

@@ -0,0 +1,144 @@
+import { sha256 } from '../../../fsx.js';
+import { buildContextGraphIndex } from '../graph-index.js';
+import { contextGraphQueryProfile } from '../profiles.js';
+import { queryContextGraphSnapshot } from '../query/index.js';
+import { DEFAULT_CODE_PACK_TOKEN_BUDGET, normalizeCodePackTokenBudget, CODE_PACK_SCHEMA } from './pack-contract.js';
+import { codePackEntryId, describeContextGraphNode, estimateEntryTokenCost, projectedFreshness, projectedTrustScore } from './node-summary.js';
+import { rankModuleCandidates, sortCandidates } from './module-view.js';
+const MAX_PACK_ENTRIES = 64;
+function isIndex(value) {
+    return typeof value.nodesById?.get === 'function';
+}
+function citationsFromProvenance(selected) {
+    const citations = [];
+    const seen = new Set();
+    for (const ref of selected.provenance) {
+        if (!ref.path || seen.has(ref.path))
+            continue;
+        seen.add(ref.path);
+        citations.push(ref.line === undefined ? { path: ref.path } : { path: ref.path, line: ref.line });
+    }
+    return citations;
+}
+function candidatesFromQuery(index, result) {
+    const candidates = [];
+    for (const selected of result.selected) {
+        const node = index.nodesById.get(selected.nodeId);
+        if (!node)
+            continue;
+        const citations = citationsFromProvenance(selected);
+        if (citations.length === 0)
+            continue;
+        candidates.push({
+            node,
+            text: describeContextGraphNode(index, node),
+            citations,
+            members: [node],
+            reasonPath: selected.reasonPath,
+            score: selected.score
+        });
+    }
+    return sortCandidates(candidates);
+}
+function combineFreshness(members, snapshotFreshness, observed) {
+    let verdict = null;
+    for (const member of members) {
+        if (!member.contentHash)
+            continue;
+        const memberVerdict = projectedFreshness(member, 'fresh', observed);
+        if (memberVerdict === 'stale') {
+            verdict = 'stale';
+            break;
+        }
+        if (memberVerdict === 'unknown')
+            verdict = 'unknown';
+        else if (verdict === null)
+            verdict = 'fresh';
+    }
+    const resolved = verdict ?? members[0]?.freshness ?? 'unknown';
+    return snapshotFreshness === 'stale' && resolved === 'fresh' ? 'stale' : resolved;
+}
+function entryOf(candidate, taken, snapshotFreshness, observed) {
+    if (candidate.citations.length === 0)
+        return null;
+    const freshness = combineFreshness(candidate.members, snapshotFreshness, observed);
+    return {
+        id: codePackEntryId(candidate.node, taken),
+        text: candidate.text,
+        citations: candidate.citations,
+        trust_score: projectedTrustScore(candidate.node, candidate.citations.length, freshness),
+        freshness,
+        token_cost: estimateEntryTokenCost(candidate.text)
+    };
+}
+export function computeCodePackIndexDigest(snapshotHash, entries) {
+    const stable = entries.map((entry) => [
+        entry.id,
+        entry.text,
+        entry.citations.map((citation) => `${citation.path}${citation.line === undefined ? '' : `:${citation.line}`}`),
+        entry.trust_score,
+        entry.freshness,
+        entry.token_cost
+    ]);
+    return sha256(JSON.stringify({ snapshotHash, entries: stable }));
+}
+export function isCodePackProjectionBoundToSnapshot(snapshotHash, pack) {
+    return pack.index_digest === computeCodePackIndexDigest(snapshotHash, pack.entries);
+}
+function countFileNodes(snapshot) {
+    let count = 0;
+    for (const node of snapshot.nodes)
+        if (node.kind === 'file')
+            count += 1;
+    return count;
+}
+export function projectCodePackFromGraph(root, source, options = {}) {
+    const index = isIndex(source) ? source : buildContextGraphIndex(source);
+    const tokenBudget = normalizeCodePackTokenBudget(options.tokenBudget ?? DEFAULT_CODE_PACK_TOKEN_BUDGET);
+    const profile = contextGraphQueryProfile(options.profile);
+    const risk = options.risk === 'high' ? 'high' : 'normal';
+    const snapshotFreshness = options.snapshotFreshness ?? 'fresh';
+    const maxEntries = Math.max(1, Math.min(options.maxEntries ?? MAX_PACK_ENTRIES, MAX_PACK_ENTRIES));
+    const question = String(options.query ?? '').trim();
+    let queryResult = null;
+    let candidates;
+    if (question) {
+        queryResult = queryContextGraphSnapshot(index, { root, query: question, profile: profile.name, tokenBudget, maxSelected: maxEntries, risk }, { snapshotFreshness });
+        candidates = candidatesFromQuery(index, queryResult);
+    }
+    else {
+        candidates = rankModuleCandidates(index, profile, risk);
+    }
+    const entries = [];
+    const taken = new Set();
+    let totalTokenCost = 0;
+    let omittedForBudget = 0;
+    for (const candidate of candidates) {
+        if (entries.length >= maxEntries)
+            break;
+        const entry = entryOf(candidate, taken, snapshotFreshness, options.observedSourceHashes);
+        if (!entry)
+            continue;
+        if (totalTokenCost + entry.token_cost > tokenBudget) {
+            omittedForBudget += 1;
+            continue;
+        }
+        taken.add(entry.id);
+        entries.push(entry);
+        totalTokenCost += entry.token_cost;
+    }
+    const pack = {
+        schema: CODE_PACK_SCHEMA,
+        generated_at: options.generatedAt ?? new Date().toISOString(),
+        git_head_sha: options.gitHeadSha ?? null,
+        source_file_count: countFileNodes(index.snapshot),
+        index_digest: computeCodePackIndexDigest(index.snapshot.snapshotHash, entries),
+        entries,
+        token_budget: tokenBudget,
+        total_token_cost: totalTokenCost
+    };
+    return { pack, query: queryResult, candidateCount: candidates.length, omittedForBudget };
+}
+export function buildCodePackFromGraph(root, source, options = {}) {
+    return projectCodePackFromGraph(root, source, options).pack;
+}

package/dist/core/triwiki/context-graph/projections/index.js

@@ -0,0 +1,7 @@
+export { CODE_PACK_SCHEMA, DEFAULT_CODE_PACK_TOKEN_BUDGET, normalizeCodePackTokenBudget } from './pack-contract.js';
+export { buildCodePackFromGraph, computeCodePackIndexDigest, projectCodePackFromGraph } from './code-pack.js';
+export { buildWorkspaceCodePack } from './code-pack-workspace.js';
+export { rankModuleCandidates, sortCandidates } from './module-view.js';
+export { codePackEntryId, describeContextGraphNode, estimateEntryTokenCost, projectedFreshness, projectedTrustScore } from './node-summary.js';
+export { ATTENTION_FACT_TRUST_FLOOR, attentionHydrateHint, isFactGradeAnchor, projectContextGraphAnchors, projectContextPackAnchors, resolveContextGraphAnchorNode } from './anchors.js';
+export { CONTEXT_GRAPH_ATTENTION_TOKEN_BUDGET, readContextGraphAttention } from './attention.js';

package/dist/core/triwiki/context-graph/projections/module-view.js

@@ -0,0 +1,140 @@
+import { compareContextGraphIds } from '../ids.js';
+import { outgoingEdges } from '../graph-index.js';
+import { profileEdgeWeight } from '../profiles.js';
+import { describeContextGraphNode } from './node-summary.js';
+const RISK_RANK = { low: 0, medium: 1, high: 2, protected: 3 };
+const MAX_CITATIONS = 8;
+function riskBonus(node, risk) {
+    const rank = RISK_RANK[node.risk] ?? 0;
+    return risk === 'high' ? rank * 2 : rank * 0.75;
+}
+function metaNumber(node, key) {
+    const value = node.metadata[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function isExportedSymbol(node) {
+    return node.kind === 'symbol' && node.metadata.exported === true;
+}
+function pushCitation(into, seen, node) {
+    if (into.length >= MAX_CITATIONS)
+        return;
+    if (!node.path || seen.has(node.path))
+        return;
+    seen.add(node.path);
+    into.push(node.locator?.line === undefined ? { path: node.path } : { path: node.path, line: node.locator.line });
+}
+function ownerIndex(index, modules) {
+    const owner = new Map();
+    for (const module of modules) {
+        for (const edge of outgoingEdges(index, module.id)) {
+            if (edge.type !== 'contains')
+                continue;
+            if (!owner.has(edge.to))
+                owner.set(edge.to, module.id);
+        }
+    }
+    return owner;
+}
+function accumulateFile(index, accumulator, file, owner, profile) {
+    accumulator.members.push(file);
+    accumulator.fanIn += metaNumber(file, 'fanIn');
+    for (const edge of outgoingEdges(index, file.id)) {
+        const weight = profileEdgeWeight(profile, edge.type);
+        if (weight > 0)
+            accumulator.relationScore += weight;
+        const target = index.nodesById.get(edge.to);
+        if (!target)
+            continue;
+        if (isExportedSymbol(target))
+            accumulator.exports.push(target.label);
+        if (edge.type !== 'imports' && edge.type !== 'depends_on')
+            continue;
+        const ownerId = owner.get(target.id);
+        if (!ownerId || ownerId === accumulator.module.id)
+            continue;
+        const ownerNode = index.nodesById.get(ownerId);
+        if (ownerNode)
+            accumulator.dependsOn.push(ownerNode.label);
+    }
+}
+function candidateOf(index, accumulator, risk) {
+    const files = accumulator.members.filter((member) => member.id !== accumulator.module.id);
+    const citations = [];
+    const seen = new Set();
+    for (const file of files)
+        pushCitation(citations, seen, file);
+    if (citations.length === 0)
+        pushCitation(citations, seen, accumulator.module);
+    const text = describeContextGraphNode(index, accumulator.module, {
+        exports: accumulator.exports,
+        dependsOn: accumulator.dependsOn,
+        fileCount: files.length
+    });
+    const score = accumulator.relationScore
+        + 3 * Math.log2(1 + accumulator.fanIn)
+        + Math.log2(1 + accumulator.exports.length)
+        + riskBonus(accumulator.module, risk);
+    return {
+        node: accumulator.module,
+        text,
+        citations,
+        members: accumulator.members,
+        reasonPath: [accumulator.module.id, 'contains', `${files.length} file(s)`],
+        score: Number(score.toFixed(4))
+    };
+}
+export function rankModuleCandidates(index, profile, risk) {
+    const modules = [];
+    for (const node of index.snapshot.nodes)
+        if (node.kind === 'module')
+            modules.push(node);
+    if (modules.length === 0)
+        return rankFileCandidates(index, profile, risk);
+    const owner = ownerIndex(index, modules);
+    const candidates = [];
+    for (const module of modules) {
+        const accumulator = {
+            module,
+            members: [module],
+            exports: [],
+            dependsOn: [],
+            relationScore: 0,
+            fanIn: 0
+        };
+        for (const edge of outgoingEdges(index, module.id)) {
+            if (edge.type !== 'contains')
+                continue;
+            const file = index.nodesById.get(edge.to);
+            if (file)
+                accumulateFile(index, accumulator, file, owner, profile);
+        }
+        candidates.push(candidateOf(index, accumulator, risk));
+    }
+    return sortCandidates(candidates);
+}
+function rankFileCandidates(index, profile, risk) {
+    const candidates = [];
+    for (const node of index.snapshot.nodes) {
+        if (node.kind !== 'file' || !node.path)
+            continue;
+        let relationScore = 0;
+        for (const edge of outgoingEdges(index, node.id))
+            relationScore += profileEdgeWeight(profile, edge.type);
+        const citations = [];
+        pushCitation(citations, new Set(), node);
+        if (citations.length === 0)
+            continue;
+        candidates.push({
+            node,
+            text: describeContextGraphNode(index, node),
+            citations,
+            members: [node],
+            reasonPath: [node.id],
+            score: Number((relationScore + 3 * Math.log2(1 + metaNumber(node, 'fanIn')) + riskBonus(node, risk)).toFixed(4))
+        });
+    }
+    return sortCandidates(candidates);
+}
+export function sortCandidates(candidates) {
+    return candidates.sort((left, right) => right.score - left.score || compareContextGraphIds(left.node.id, right.node.id));
+}

package/dist/core/triwiki/context-graph/projections/node-summary.js

@@ -0,0 +1,118 @@
+import { CONTEXT_GRAPH_MISSING_SOURCE_HASH } from '../compiler/freshness.js';
+import { outgoingEdges } from '../graph-index.js';
+const EXPORT_EDGE_TYPES = new Set(['defines', 'reexports']);
+const DEPENDENCY_EDGE_TYPES = new Set(['imports', 'depends_on', 'routes_to']);
+const MAX_LISTED = 5;
+function metaString(metadata, key) {
+    const value = metadata[key];
+    return typeof value === 'string' && value ? value : null;
+}
+function metaNumber(metadata, key) {
+    const value = metadata[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function metaBoolean(metadata, key) {
+    return metadata[key] === true;
+}
+function compact(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function listOf(values) {
+    const unique = [...new Set(values.filter((value) => Boolean(value)))].sort();
+    if (unique.length === 0)
+        return '';
+    const shown = unique.slice(0, MAX_LISTED);
+    const rest = unique.length - shown.length;
+    return `${shown.join(', ')}${rest > 0 ? `, and ${rest} more` : ''}`;
+}
+function relatedLabels(index, nodeId, types, exportedOnly) {
+    const labels = [];
+    for (const edge of outgoingEdges(index, nodeId)) {
+        if (!types.has(edge.type))
+            continue;
+        const target = index.nodesById.get(edge.to);
+        if (!target)
+            continue;
+        if (exportedOnly && target.kind === 'symbol' && !metaBoolean(target.metadata, 'exported'))
+            continue;
+        labels.push(target.label);
+    }
+    return labels;
+}
+function headline(node, extras) {
+    const where = node.path ? ` at ${node.path}` : '';
+    const line = node.locator?.line !== undefined ? `:${node.locator.line}` : '';
+    switch (node.kind) {
+        case 'file': {
+            const language = metaString(node.metadata, 'language') ?? 'source';
+            const lines = metaNumber(node.metadata, 'lines');
+            const fanIn = metaNumber(node.metadata, 'fanIn') ?? 0;
+            const size = lines === null ? '' : `${lines} lines, `;
+            return `${node.label} is a ${language} file${where} (${size}fan-in ${fanIn}, ${node.risk} risk).`;
+        }
+        case 'symbol': {
+            const symbolKind = metaString(node.metadata, 'symbolKind') ?? 'symbol';
+            const exported = metaBoolean(node.metadata, 'exported') ? 'exported ' : 'internal ';
+            return `${node.label} is an ${exported}${symbolKind}${where}${line}.`;
+        }
+        case 'module': {
+            const dir = metaString(node.metadata, 'dir') ?? node.path ?? node.label;
+            const fileCount = extras.fileCount ?? metaNumber(node.metadata, 'fileCount') ?? 0;
+            return `${node.label} is a module at ${dir} (${fileCount} file${fileCount === 1 ? '' : 's'}, ${node.risk} risk).`;
+        }
+        case 'test':
+            return `${node.label} is a test${where}.`;
+        case 'gate':
+            return `${node.label} is a ${node.risk} gate${where}.`;
+        case 'command':
+            return `${node.label} is a CLI command declared${where}.`;
+        default:
+            return `${node.label} is a ${node.kind} node${where}${line}.`;
+    }
+}
+export function describeContextGraphNode(index, node, extras = {}) {
+    const exports = extras.exports ?? relatedLabels(index, node.id, EXPORT_EDGE_TYPES, true);
+    const dependsOn = extras.dependsOn ?? relatedLabels(index, node.id, DEPENDENCY_EDGE_TYPES, false);
+    const exportsPart = exports.length > 0 ? `Key exports: ${listOf(exports)}.` : 'It has no exported surface in the graph.';
+    const dependsPart = dependsOn.length > 0 ? `Depends on: ${listOf(dependsOn)}.` : 'It has no recorded outbound dependency.';
+    return compact(`${headline(node, extras)} ${exportsPart} ${dependsPart}`);
+}
+export function estimateEntryTokenCost(text) {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+export function codePackEntryId(node, taken) {
+    const preferred = node.kind === 'module' ? `code:${node.label}` : `code:${node.id}`;
+    if (!taken.has(preferred))
+        return preferred;
+    const fallback = `code:${node.id}`;
+    return taken.has(fallback) ? `${fallback}#${node.kind}` : fallback;
+}
+export function projectedFreshness(node, snapshotFreshness, observedHashes) {
+    let verdict = node.freshness;
+    const observed = node.path === undefined ? undefined : observedHashes?.[node.path];
+    if (observed !== undefined) {
+        if (observed === CONTEXT_GRAPH_MISSING_SOURCE_HASH)
+            verdict = 'stale';
+        else if (node.contentHash)
+            verdict = observed === node.contentHash ? 'fresh' : 'stale';
+        else
+            verdict = 'unknown';
+    }
+    if (snapshotFreshness === 'stale' && verdict === 'fresh')
+        return 'stale';
+    return verdict;
+}
+export function projectedTrustScore(node, provenanceCount, freshness) {
+    let score = Math.max(0, Math.min(1, node.trust));
+    if (provenanceCount === 0)
+        return 0;
+    if (provenanceCount === 1)
+        score -= 0.05;
+    if (freshness === 'stale')
+        score -= 0.3;
+    else if (freshness === 'unknown')
+        score -= 0.15;
+    if (node.risk === 'high')
+        score -= 0.1;
+    return Math.max(0, Math.min(1, Number(score.toFixed(2))));
+}

package/dist/core/triwiki/context-graph/projections/pack-contract.js

@@ -0,0 +1,6 @@
+export const CODE_PACK_SCHEMA = 'sks.code-pack.v1';
+export const DEFAULT_CODE_PACK_TOKEN_BUDGET = 8000;
+export function normalizeCodePackTokenBudget(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : DEFAULT_CODE_PACK_TOKEN_BUDGET;
+}