hadara 0.3.2 → 0.3.3-rc.0

package/dist/context/context-cache-store.js

@@ -0,0 +1,925 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXT_CACHE_WARM_COMMAND = exports.CONTEXT_CACHE_STATUS_COMMAND = exports.CONTEXT_CACHE_RECORD_VERSION = exports.CONTEXT_CACHE_WARM_SCHEMA_ID = exports.CONTEXT_CACHE_STATUS_SCHEMA_ID = exports.CONTEXT_CACHE_RECORD_SCHEMA_ID = void 0;
+exports.buildContextCacheRecord = buildContextCacheRecord;
+exports.readContextCacheRecord = readContextCacheRecord;
+exports.writeContextCacheRecord = writeContextCacheRecord;
+exports.readContextSourceManifestCache = readContextSourceManifestCache;
+exports.writeContextSourceManifestCache = writeContextSourceManifestCache;
+exports.listContextGraphExtractorShardKeys = listContextGraphExtractorShardKeys;
+exports.contextGraphExtractorShardCachePath = contextGraphExtractorShardCachePath;
+exports.contextGraphCoreShardCachePath = contextGraphCoreShardCachePath;
+exports.contextCodeIndexShardCachePath = contextCodeIndexShardCachePath;
+exports.buildContextGraphExtractorShardRecord = buildContextGraphExtractorShardRecord;
+exports.writeContextGraphExtractorShard = writeContextGraphExtractorShard;
+exports.readContextGraphExtractorShard = readContextGraphExtractorShard;
+exports.collectContextGraphExtractorShards = collectContextGraphExtractorShards;
+exports.buildContextGraphCoreExtractionResult = buildContextGraphCoreExtractionResult;
+exports.buildContextGraphCoreShardRecord = buildContextGraphCoreShardRecord;
+exports.writeContextGraphCoreShard = writeContextGraphCoreShard;
+exports.readContextGraphCoreShard = readContextGraphCoreShard;
+exports.buildContextCodeIndexShardRecord = buildContextCodeIndexShardRecord;
+exports.writeContextCodeIndexShard = writeContextCodeIndexShard;
+exports.readContextCodeIndexShard = readContextCodeIndexShard;
+exports.createContextCacheStatusReport = createContextCacheStatusReport;
+exports.createContextCacheWarmReport = createContextCacheWarmReport;
+exports.createSourceManifestCacheAnalysis = createSourceManifestCacheAnalysis;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../core/fs");
+const schema_1 = require("../core/schema");
+const source_manifest_1 = require("./source-manifest");
+const code_index_1 = require("./code-index");
+const extractor_contract_1 = require("./extractor-contract");
+const document_extractors_1 = require("./document-extractors");
+const evidence_extractors_1 = require("./evidence-extractors");
+const registry_extractors_1 = require("./registry-extractors");
+const release_extractors_1 = require("./release-extractors");
+const task_extractors_1 = require("./task-extractors");
+exports.CONTEXT_CACHE_RECORD_SCHEMA_ID = 'hadara.context.cacheRecord.v1';
+exports.CONTEXT_CACHE_STATUS_SCHEMA_ID = 'hadara.context.cacheStatus.v1';
+exports.CONTEXT_CACHE_WARM_SCHEMA_ID = 'hadara.context.cacheWarm.v1';
+exports.CONTEXT_CACHE_RECORD_VERSION = 'c6.2-cache-record-v1';
+exports.CONTEXT_CACHE_STATUS_COMMAND = 'context.cache.status';
+exports.CONTEXT_CACHE_WARM_COMMAND = 'context.cache.warm';
+const CONTEXT_GRAPH_EXTRACTOR_SHARD_PROJECTION_PREFIX = 'context.graph.extractor';
+const CONTEXT_GRAPH_CORE_PROJECTION = 'context.graph.core';
+const CONTEXT_CODE_INDEX_PROJECTION = 'context.codeIndex';
+const CONTEXT_GRAPH_EXTRACTOR_SHARD_SCHEMA_VERSION = 'hadara.contextGraph.v1';
+const CONTEXT_GRAPH_CORE_CACHE_PATH = `${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT}/graph-core.json`;
+const CONTEXT_CODE_INDEX_CACHE_PATH = `${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT}/code-index.json`;
+const CONTEXT_GRAPH_EXTRACTOR_SHARD_KEYS = [
+    'extractTaskBoard',
+    'extractDocsRegistry',
+    'extractCommandRegistry'
+];
+const CONTEXT_GRAPH_EXTRACTOR_SHARD_CACHE_PATHS = {
+    extractTaskBoard: `${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT}/extractors/task-board.json`,
+    extractDocsRegistry: `${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT}/extractors/docs-registry.json`,
+    extractCommandRegistry: `${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT}/extractors/command-registry.json`
+};
+const CONTEXT_GRAPH_EXTRACTOR_SHARD_EXTRACTORS = {
+    extractTaskBoard: task_extractors_1.extractTaskBoard,
+    extractDocsRegistry: registry_extractors_1.extractDocsRegistry,
+    extractCommandRegistry: registry_extractors_1.extractCommandRegistry
+};
+const CONTEXT_GRAPH_CORE_EXTRACTOR_KEYS = [
+    'extractTaskCapsules',
+    'extractTaskBoard',
+    'extractDocsRegistry',
+    'extractCommandRegistry',
+    'extractManagedSections',
+    'extractProjectState',
+    'extractDecisions',
+    'extractAgentHandoff',
+    'extractEvidence',
+    'extractReleaseReadiness'
+];
+function buildContextCacheRecord(options) {
+    const extractorKeys = options.extractorKeys?.length ? [...options.extractorKeys].sort() : undefined;
+    const sourceSubsetHash = extractorKeys
+        ? (0, extractor_contract_1.hashContextGraphJson)(extractorKeys.map((extractorKey) => ({
+            extractorKey,
+            subsetHash: (0, source_manifest_1.createContextSourceSubsetHash)(options.manifest, { extractorKey })
+        })))
+        : (0, source_manifest_1.createContextSourceSubsetHash)(options.manifest);
+    const extractorVersions = {
+        ...Object.fromEntries(Object.entries(options.manifest.extractorVersions)
+            .filter(([key]) => !extractorKeys || extractorKeys.includes(key))),
+        ...(options.extractorVersions ?? {})
+    };
+    const createdAt = options.createdAt ?? new Date().toISOString();
+    const cacheKey = (0, extractor_contract_1.hashContextGraphJson)({
+        projection: options.projection,
+        projectionSchemaVersion: options.projectionSchemaVersion,
+        manifestHash: options.manifest.manifestHash,
+        sourceSubsetHash,
+        extractorVersions
+    });
+    return {
+        schemaVersion: exports.CONTEXT_CACHE_RECORD_SCHEMA_ID,
+        cacheRecordVersion: exports.CONTEXT_CACHE_RECORD_VERSION,
+        cacheKey,
+        projection: options.projection,
+        projectionSchemaVersion: options.projectionSchemaVersion,
+        createdAt,
+        manifestHash: options.manifest.manifestHash,
+        sourceSubsetHash,
+        extractorVersions,
+        degraded: options.degraded ?? false,
+        issues: options.issues ?? [],
+        payload: options.payload
+    };
+}
+function readContextCacheRecord(projectRoot, cachePath) {
+    const relativePath = normalizeContextCachePath(cachePath);
+    const absolutePath = node_path_1.default.join(projectRoot, relativePath);
+    if (!node_fs_1.default.existsSync(absolutePath)) {
+        return {
+            ok: false,
+            status: 'missing',
+            path: relativePath,
+            issues: [contextCacheIssue('info', 'CONTEXT_CACHE_MISS', `Context cache record is missing at ${relativePath}.`, relativePath)]
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(absolutePath, 'utf8'));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 'corrupt',
+            path: relativePath,
+            issues: [contextCacheIssue('warning', 'CONTEXT_CACHE_CORRUPT', `Context cache record at ${relativePath} could not be parsed: ${error instanceof Error ? error.message : String(error)}.`, relativePath)]
+        };
+    }
+    const validation = (0, schema_1.validateSchema)(exports.CONTEXT_CACHE_RECORD_SCHEMA_ID, parsed);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            status: 'schema-mismatch',
+            path: relativePath,
+            issues: [contextCacheIssue('warning', 'CONTEXT_CACHE_SCHEMA_MISMATCH', `Context cache record at ${relativePath} does not match ${exports.CONTEXT_CACHE_RECORD_SCHEMA_ID}.`, relativePath)]
+        };
+    }
+    return {
+        ok: true,
+        status: 'valid',
+        path: relativePath,
+        record: parsed,
+        issues: []
+    };
+}
+function writeContextCacheRecord(projectRoot, cachePath, record) {
+    const relativePath = normalizeContextCachePath(cachePath);
+    const validation = (0, schema_1.validateSchema)(exports.CONTEXT_CACHE_RECORD_SCHEMA_ID, record);
+    if (!validation.ok) {
+        throw new Error(`Context cache record does not match ${exports.CONTEXT_CACHE_RECORD_SCHEMA_ID}: ${validation.issues[0]?.path ?? '$'}`);
+    }
+    (0, fs_1.atomicWriteTextFile)(projectRoot, relativePath, `${JSON.stringify(record, null, 2)}\n`);
+}
+function readContextSourceManifestCache(projectRoot) {
+    const absolutePath = node_path_1.default.join(projectRoot, source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH);
+    if (!node_fs_1.default.existsSync(absolutePath)) {
+        return {
+            ok: false,
+            status: 'missing',
+            path: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH,
+            issues: [contextCacheIssue('info', 'CONTEXT_CACHE_MISS', `Source manifest cache is missing at ${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH}.`, source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH)]
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(absolutePath, 'utf8'));
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 'corrupt',
+            path: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH,
+            issues: [contextCacheIssue('warning', 'CONTEXT_CACHE_CORRUPT', `Source manifest cache could not be parsed: ${error instanceof Error ? error.message : String(error)}.`, source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH)]
+        };
+    }
+    const validation = (0, schema_1.validateSchema)(source_manifest_1.CONTEXT_SOURCE_MANIFEST_SCHEMA_ID, parsed);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            status: 'schema-mismatch',
+            path: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH,
+            issues: [contextCacheIssue('warning', 'CONTEXT_CACHE_SCHEMA_MISMATCH', `Source manifest cache does not match ${source_manifest_1.CONTEXT_SOURCE_MANIFEST_SCHEMA_ID}.`, source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH)]
+        };
+    }
+    return {
+        ok: true,
+        status: 'valid',
+        path: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH,
+        manifest: parsed,
+        issues: []
+    };
+}
+function writeContextSourceManifestCache(projectRoot, manifest) {
+    const validation = (0, schema_1.validateSchema)(source_manifest_1.CONTEXT_SOURCE_MANIFEST_SCHEMA_ID, manifest);
+    if (!validation.ok) {
+        throw new Error(`Context source manifest does not match ${source_manifest_1.CONTEXT_SOURCE_MANIFEST_SCHEMA_ID}: ${validation.issues[0]?.path ?? '$'}`);
+    }
+    (0, fs_1.atomicWriteTextFile)(projectRoot, source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+function listContextGraphExtractorShardKeys() {
+    return [...CONTEXT_GRAPH_EXTRACTOR_SHARD_KEYS];
+}
+function contextGraphExtractorShardCachePath(extractorKey) {
+    return CONTEXT_GRAPH_EXTRACTOR_SHARD_CACHE_PATHS[extractorKey];
+}
+function contextGraphCoreShardCachePath() {
+    return CONTEXT_GRAPH_CORE_CACHE_PATH;
+}
+function contextCodeIndexShardCachePath() {
+    return CONTEXT_CODE_INDEX_CACHE_PATH;
+}
+function buildContextGraphExtractorShardRecord(input) {
+    return buildContextCacheRecord({
+        projection: contextGraphExtractorShardProjection(input.extractorKey),
+        projectionSchemaVersion: CONTEXT_GRAPH_EXTRACTOR_SHARD_SCHEMA_VERSION,
+        manifest: input.manifest,
+        extractorKeys: [input.extractorKey],
+        payload: input.result,
+        createdAt: input.createdAt,
+        degraded: input.result.issues.some((issue) => issue.severity === 'warning' || issue.severity === 'error')
+    });
+}
+function writeContextGraphExtractorShard(input) {
+    const record = buildContextGraphExtractorShardRecord(input);
+    writeContextCacheRecord(input.projectRoot, contextGraphExtractorShardCachePath(input.extractorKey), record);
+    return record;
+}
+function readContextGraphExtractorShard(input) {
+    const cachePath = contextGraphExtractorShardCachePath(input.extractorKey);
+    const read = readContextCacheRecord(input.projectRoot, cachePath);
+    if (!read.ok || !read.record) {
+        return {
+            ok: false,
+            hit: false,
+            status: read.status === 'valid' ? 'schema-mismatch' : read.status,
+            extractorKey: input.extractorKey,
+            path: read.path,
+            issues: read.issues
+        };
+    }
+    const expected = buildContextCacheRecord({
+        projection: contextGraphExtractorShardProjection(input.extractorKey),
+        projectionSchemaVersion: CONTEXT_GRAPH_EXTRACTOR_SHARD_SCHEMA_VERSION,
+        manifest: input.manifest,
+        extractorKeys: [input.extractorKey],
+        payload: read.record.payload,
+        createdAt: read.record.createdAt
+    });
+    const shapeIssue = validateGraphExtractionPayload(read.record.payload, input.extractorKey, read.path);
+    if (shapeIssue) {
+        return {
+            ok: false,
+            hit: false,
+            status: 'schema-mismatch',
+            extractorKey: input.extractorKey,
+            path: read.path,
+            record: read.record,
+            issues: [shapeIssue]
+        };
+    }
+    if (read.record.projection !== expected.projection
+        || read.record.projectionSchemaVersion !== expected.projectionSchemaVersion
+        || read.record.sourceSubsetHash !== expected.sourceSubsetHash
+        || !sameRecord(read.record.extractorVersions, expected.extractorVersions)) {
+        return {
+            ok: false,
+            hit: false,
+            status: 'stale',
+            extractorKey: input.extractorKey,
+            path: read.path,
+            record: read.record,
+            issues: [contextCacheIssue('warning', 'CONTEXT_CACHE_STALE', `Context graph extractor shard ${input.extractorKey} is stale.`, read.path)]
+        };
+    }
+    return {
+        ok: true,
+        hit: true,
+        status: 'fresh',
+        extractorKey: input.extractorKey,
+        path: read.path,
+        record: read.record,
+        result: read.record.payload,
+        issues: []
+    };
+}
+function collectContextGraphExtractorShards(input) {
+    const results = {};
+    const reads = CONTEXT_GRAPH_EXTRACTOR_SHARD_KEYS.map((extractorKey) => readContextGraphExtractorShard({ projectRoot: input.projectRoot, manifest: input.manifest, extractorKey }));
+    for (const read of reads) {
+        if (read.hit && read.result)
+            results[read.extractorKey] = read.result;
+    }
+    const hitReads = reads.filter((read) => read.hit);
+    const staleReads = reads.filter((read) => read.status === 'stale');
+    const cache = {
+        used: hitReads.length > 0,
+        hit: hitReads.length > 0,
+        mode: 'extractor-shards',
+        manifestHash: input.manifest.manifestHash,
+        readShardCount: reads.length,
+        hitShardCount: hitReads.length,
+        missShardCount: reads.filter((read) => read.status === 'missing').length,
+        staleShardCount: staleReads.length,
+        corruptShardCount: reads.filter((read) => read.status === 'corrupt').length,
+        schemaMismatchShardCount: reads.filter((read) => read.status === 'schema-mismatch').length,
+        shardPaths: reads.map((read) => read.path).sort(),
+        staleExtractorKeys: staleReads.map((read) => read.extractorKey).sort(),
+        ...(hitReads[0]?.record ? { createdAt: hitReads[0].record.createdAt, cachePath: hitReads[0].path } : {})
+    };
+    return {
+        results,
+        cache,
+        issues: reads.flatMap((read) => read.issues)
+    };
+}
+function buildContextGraphCoreExtractionResult(projectRoot) {
+    return (0, extractor_contract_1.mergeGraphExtractionResults)([
+        (0, task_extractors_1.extractTaskCapsules)(projectRoot),
+        (0, task_extractors_1.extractTaskBoard)(projectRoot),
+        (0, registry_extractors_1.extractDocsRegistry)(projectRoot),
+        (0, registry_extractors_1.extractCommandRegistry)(projectRoot),
+        (0, document_extractors_1.extractManagedSections)(projectRoot),
+        (0, document_extractors_1.extractProjectState)(projectRoot),
+        (0, document_extractors_1.extractDecisions)(projectRoot),
+        (0, document_extractors_1.extractAgentHandoff)(projectRoot),
+        (0, evidence_extractors_1.extractEvidence)(projectRoot),
+        (0, release_extractors_1.extractReleaseReadiness)(projectRoot)
+    ]);
+}
+function buildContextGraphCoreShardRecord(input) {
+    return buildContextCacheRecord({
+        projection: CONTEXT_GRAPH_CORE_PROJECTION,
+        projectionSchemaVersion: CONTEXT_GRAPH_EXTRACTOR_SHARD_SCHEMA_VERSION,
+        manifest: input.manifest,
+        extractorKeys: [...CONTEXT_GRAPH_CORE_EXTRACTOR_KEYS],
+        payload: input.result,
+        createdAt: input.createdAt,
+        degraded: input.result.issues.some((issue) => issue.severity === 'warning' || issue.severity === 'error')
+    });
+}
+function writeContextGraphCoreShard(input) {
+    const record = buildContextGraphCoreShardRecord(input);
+    writeContextCacheRecord(input.projectRoot, CONTEXT_GRAPH_CORE_CACHE_PATH, record);
+    return record;
+}
+function readContextGraphCoreShard(input) {
+    const read = readContextCacheRecord(input.projectRoot, CONTEXT_GRAPH_CORE_CACHE_PATH);
+    if (!read.ok || !read.record) {
+        return {
+            ok: false,
+            hit: false,
+            status: read.status === 'valid' ? 'schema-mismatch' : read.status,
+            path: read.path,
+            issues: read.issues
+        };
+    }
+    const expected = buildContextCacheRecord({
+        projection: CONTEXT_GRAPH_CORE_PROJECTION,
+        projectionSchemaVersion: CONTEXT_GRAPH_EXTRACTOR_SHARD_SCHEMA_VERSION,
+        manifest: input.manifest,
+        extractorKeys: [...CONTEXT_GRAPH_CORE_EXTRACTOR_KEYS],
+        payload: read.record.payload,
+        createdAt: read.record.createdAt
+    });
+    const shapeIssue = validateGraphCorePayload(read.record.payload, read.path);
+    if (shapeIssue) {
+        return {
+            ok: false,
+            hit: false,
+            status: 'schema-mismatch',
+            path: read.path,
+            record: read.record,
+            issues: [shapeIssue]
+        };
+    }
+    if (read.record.projection !== expected.projection
+        || read.record.projectionSchemaVersion !== expected.projectionSchemaVersion
+        || read.record.sourceSubsetHash !== expected.sourceSubsetHash
+        || !sameRecord(read.record.extractorVersions, expected.extractorVersions)) {
+        return {
+            ok: false,
+            hit: false,
+            status: 'stale',
+            path: read.path,
+            record: read.record,
+            issues: [contextCacheIssue('warning', 'CONTEXT_CACHE_STALE', 'Context graph core shard is stale.', read.path)]
+        };
+    }
+    return {
+        ok: true,
+        hit: true,
+        status: 'fresh',
+        path: read.path,
+        record: read.record,
+        result: read.record.payload,
+        issues: []
+    };
+}
+function buildContextCodeIndexShardRecord(input) {
+    return buildContextCacheRecord({
+        projection: CONTEXT_CODE_INDEX_PROJECTION,
+        projectionSchemaVersion: code_index_1.CODE_INDEX_SCHEMA_ID,
+        manifest: input.manifest,
+        extractorKeys: ['codeIndex'],
+        payload: input.result,
+        createdAt: input.createdAt,
+        degraded: input.result.summary.degraded || input.result.issues.some((issue) => issue.severity === 'warning' || issue.severity === 'error')
+    });
+}
+function writeContextCodeIndexShard(input) {
+    const record = buildContextCodeIndexShardRecord(input);
+    writeContextCacheRecord(input.projectRoot, CONTEXT_CODE_INDEX_CACHE_PATH, record);
+    return record;
+}
+function readContextCodeIndexShard(input) {
+    const read = readContextCacheRecord(input.projectRoot, CONTEXT_CODE_INDEX_CACHE_PATH);
+    if (!read.ok || !read.record) {
+        return {
+            ok: false,
+            hit: false,
+            status: read.status === 'valid' ? 'schema-mismatch' : read.status,
+            path: read.path,
+            issues: read.issues
+        };
+    }
+    const expected = buildContextCacheRecord({
+        projection: CONTEXT_CODE_INDEX_PROJECTION,
+        projectionSchemaVersion: code_index_1.CODE_INDEX_SCHEMA_ID,
+        manifest: input.manifest,
+        extractorKeys: ['codeIndex'],
+        payload: read.record.payload,
+        createdAt: read.record.createdAt
+    });
+    const shapeIssue = validateCodeIndexPayload(read.record.payload, read.path);
+    if (shapeIssue) {
+        return {
+            ok: false,
+            hit: false,
+            status: 'schema-mismatch',
+            path: read.path,
+            record: read.record,
+            issues: [shapeIssue]
+        };
+    }
+    if (read.record.projection !== expected.projection
+        || read.record.projectionSchemaVersion !== expected.projectionSchemaVersion
+        || read.record.sourceSubsetHash !== expected.sourceSubsetHash
+        || !sameRecord(read.record.extractorVersions, expected.extractorVersions)) {
+        return {
+            ok: false,
+            hit: false,
+            status: 'stale',
+            path: read.path,
+            record: read.record,
+            issues: [contextCacheIssue('warning', 'CONTEXT_CACHE_STALE', 'Context code-index shard is stale.', read.path)]
+        };
+    }
+    return {
+        ok: true,
+        hit: true,
+        status: 'fresh',
+        path: read.path,
+        record: read.record,
+        result: withCodeIndexCacheHitMetadata(read.record.payload, read.record, read.path),
+        issues: []
+    };
+}
+function createContextCacheStatusReport(input) {
+    const analysis = createSourceManifestCacheAnalysis({
+        projectRoot: input.projectRoot,
+        generatedAt: input.generatedAt,
+        generatedByCommand: exports.CONTEXT_CACHE_STATUS_COMMAND
+    });
+    const shardItems = createContextGraphExtractorShardWarmItems({
+        projectRoot: input.projectRoot,
+        manifest: analysis.currentManifest,
+        execute: false,
+        generatedAt: analysis.generatedAt
+    });
+    return {
+        schemaVersion: exports.CONTEXT_CACHE_STATUS_SCHEMA_ID,
+        command: exports.CONTEXT_CACHE_STATUS_COMMAND,
+        ok: true,
+        generatedAt: analysis.generatedAt,
+        projectRoot: input.projectRoot,
+        cacheRoot: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT,
+        readOnly: true,
+        summary: {
+            mode: analysis.cacheFresh ? 'hit' : analysis.cached.status === 'missing' ? 'miss' : analysis.cached.status === 'valid' ? 'stale' : 'corrupt',
+            cachePresent: analysis.cached.status !== 'missing',
+            cacheFresh: analysis.cacheFresh,
+            fastPath: analysis.fastPath,
+            degraded: analysis.degraded,
+            staleExtractorKeys: analysis.staleExtractorKeys
+        },
+        manifest: createManifestReportSection(analysis),
+        diagnostics: createContextCacheDiagnostics({
+            projectRoot: input.projectRoot,
+            analysis,
+            shardItems
+        }),
+        issues: analysis.issues
+    };
+}
+function createContextCacheWarmReport(input) {
+    const execute = input.execute ?? false;
+    const analysis = createSourceManifestCacheAnalysis({
+        projectRoot: input.projectRoot,
+        generatedAt: input.generatedAt,
+        generatedByCommand: exports.CONTEXT_CACHE_WARM_COMMAND
+    });
+    const shardItems = createContextGraphExtractorShardWarmItems({
+        projectRoot: input.projectRoot,
+        manifest: analysis.currentManifest,
+        execute,
+        generatedAt: analysis.generatedAt
+    });
+    const shardWritePlanned = shardItems.some((item) => item.planned);
+    const shardWriteExecuted = shardItems.some((item) => item.executed);
+    const writePlanned = !analysis.cacheFresh;
+    let writeExecuted = false;
+    if (execute && writePlanned) {
+        writeContextSourceManifestCache(input.projectRoot, analysis.currentManifest);
+        writeExecuted = true;
+    }
+    return {
+        schemaVersion: exports.CONTEXT_CACHE_WARM_SCHEMA_ID,
+        command: exports.CONTEXT_CACHE_WARM_COMMAND,
+        ok: true,
+        generatedAt: analysis.generatedAt,
+        projectRoot: input.projectRoot,
+        cacheRoot: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT,
+        mode: execute ? 'execute' : 'dry-run',
+        summary: {
+            cacheMode: analysis.cacheFresh ? 'fresh' : analysis.cached.status === 'missing' ? 'miss' : analysis.cached.status === 'valid' ? 'stale' : 'corrupt',
+            cachePresent: analysis.cached.status !== 'missing',
+            cacheFresh: analysis.cacheFresh,
+            fastPath: analysis.fastPath,
+            writePlanned: writePlanned || shardWritePlanned,
+            writeExecuted: writeExecuted || shardWriteExecuted,
+            shardWritePlanned,
+            shardWriteExecuted,
+            shardHitCount: shardItems.filter((item) => item.beforeStatus === 'fresh').length,
+            shardMissCount: shardItems.filter((item) => item.beforeStatus === 'missing').length,
+            shardStaleCount: shardItems.filter((item) => item.beforeStatus === 'stale').length,
+            shardCorruptCount: shardItems.filter((item) => item.beforeStatus === 'corrupt').length,
+            shardSchemaMismatchCount: shardItems.filter((item) => item.beforeStatus === 'schema-mismatch').length,
+            degraded: analysis.degraded,
+            staleExtractorKeys: analysis.staleExtractorKeys
+        },
+        manifest: createManifestReportSection(analysis),
+        write: {
+            policy: execute ? 'execute' : 'dry-run',
+            planned: writePlanned,
+            executed: writeExecuted,
+            cachePath: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH,
+            beforeStatus: analysis.cached.status,
+            ...(analysis.cached.manifest ? { beforeManifestHash: analysis.cached.manifest.manifestHash } : {}),
+            afterManifestHash: analysis.currentManifest.manifestHash,
+            ...(!writePlanned ? { skippedReason: 'cache-fresh' } : {})
+        },
+        shards: {
+            planned: shardWritePlanned,
+            executed: shardWriteExecuted,
+            items: shardItems
+        },
+        diagnostics: createContextCacheDiagnostics({
+            projectRoot: input.projectRoot,
+            analysis,
+            shardItems
+        }),
+        issues: analysis.issues
+    };
+}
+function createContextCacheDiagnostics(input) {
+    const shardSummary = {
+        total: input.shardItems.length,
+        fresh: input.shardItems.filter((item) => item.beforeStatus === 'fresh').length,
+        missing: input.shardItems.filter((item) => item.beforeStatus === 'missing').length,
+        stale: input.shardItems.filter((item) => item.beforeStatus === 'stale').length,
+        corrupt: input.shardItems.filter((item) => item.beforeStatus === 'corrupt').length,
+        schemaMismatch: input.shardItems.filter((item) => item.beforeStatus === 'schema-mismatch').length,
+        planned: input.shardItems.filter((item) => item.planned).length,
+        plannedShardKeys: input.shardItems.filter((item) => item.planned).map((item) => item.extractorKey).sort()
+    };
+    const manifestCorrupt = input.analysis.cached.status === 'corrupt' || input.analysis.cached.status === 'schema-mismatch';
+    const hasPartialShards = input.analysis.cacheFresh && shardSummary.planned > 0;
+    const state = manifestCorrupt
+        ? 'corrupt'
+        : input.analysis.cached.status === 'missing'
+            ? 'missing'
+            : input.analysis.cacheFresh
+                ? hasPartialShards ? 'partial' : 'fresh'
+                : 'stale';
+    const needsWarm = state !== 'fresh';
+    return {
+        state,
+        operatorSummary: contextCacheOperatorSummary(state, shardSummary.planned),
+        ...(needsWarm ? {
+            recommendedCommand: 'hadara context cache warm --execute --json',
+            recommendedCommandArgs: ['context', 'cache', 'warm', '--execute', '--json']
+        } : {}),
+        slowPath: {
+            mountedWorkspace: input.projectRoot.startsWith('/mnt/'),
+            fullManifestBuilt: input.analysis.fastPath !== 'hit',
+            fastPath: input.analysis.fastPath,
+            ...(input.analysis.fastPathReason ? { reason: input.analysis.fastPathReason } : {}),
+            ...(input.analysis.fastPathStrategy ? { strategy: input.analysis.fastPathStrategy } : {})
+        },
+        manifestChanges: {
+            addedPathCount: input.analysis.comparison.addedPaths.length,
+            removedPathCount: input.analysis.comparison.removedPaths.length,
+            changedPathCount: input.analysis.comparison.changedPaths.length,
+            unchangedSourceCount: input.analysis.comparison.unchangedPaths.length,
+            staleExtractorKeys: input.analysis.staleExtractorKeys
+        },
+        shardSummary
+    };
+}
+function contextCacheOperatorSummary(state, plannedShardCount) {
+    if (state === 'fresh')
+        return 'Context cache is fresh and all warm shards are available.';
+    if (state === 'missing')
+        return 'Context cache is missing; run an explicit warm execute to populate source manifest and shards.';
+    if (state === 'corrupt')
+        return 'Context cache has corrupt or schema-mismatched records; run an explicit warm execute to repair it.';
+    if (state === 'partial')
+        return `Source manifest is fresh but ${plannedShardCount} warm shard(s) are missing, stale, corrupt, or schema-mismatched.`;
+    return 'Context cache is stale relative to current project source metadata; run an explicit warm execute to refresh it.';
+}
+function createContextGraphExtractorShardWarmItems(input) {
+    const extractorItems = CONTEXT_GRAPH_EXTRACTOR_SHARD_KEYS.map((extractorKey) => {
+        const read = readContextGraphExtractorShard({
+            projectRoot: input.projectRoot,
+            manifest: input.manifest,
+            extractorKey
+        });
+        const planned = !read.hit;
+        let afterCacheKey;
+        if (input.execute && planned) {
+            const result = CONTEXT_GRAPH_EXTRACTOR_SHARD_EXTRACTORS[extractorKey](input.projectRoot);
+            const record = writeContextGraphExtractorShard({
+                projectRoot: input.projectRoot,
+                manifest: input.manifest,
+                extractorKey,
+                result,
+                createdAt: input.generatedAt
+            });
+            afterCacheKey = record.cacheKey;
+        }
+        return {
+            extractorKey,
+            cachePath: read.path,
+            beforeStatus: read.status,
+            planned,
+            executed: input.execute && planned,
+            ...(read.record ? { beforeCacheKey: read.record.cacheKey } : {}),
+            ...(afterCacheKey ? { afterCacheKey } : {}),
+            ...(!planned ? { skippedReason: 'cache-fresh' } : {})
+        };
+    });
+    const graphCoreRead = readContextGraphCoreShard({
+        projectRoot: input.projectRoot,
+        manifest: input.manifest
+    });
+    const graphCorePlanned = !graphCoreRead.hit;
+    let graphCoreAfterCacheKey;
+    if (input.execute && graphCorePlanned) {
+        const result = buildContextGraphCoreExtractionResult(input.projectRoot);
+        const record = writeContextGraphCoreShard({
+            projectRoot: input.projectRoot,
+            manifest: input.manifest,
+            result,
+            createdAt: input.generatedAt
+        });
+        graphCoreAfterCacheKey = record.cacheKey;
+    }
+    return [
+        ...extractorItems,
+        {
+            extractorKey: 'graphCore',
+            cachePath: graphCoreRead.path,
+            beforeStatus: graphCoreRead.status,
+            planned: graphCorePlanned,
+            executed: input.execute && graphCorePlanned,
+            ...(graphCoreRead.record ? { beforeCacheKey: graphCoreRead.record.cacheKey } : {}),
+            ...(graphCoreAfterCacheKey ? { afterCacheKey: graphCoreAfterCacheKey } : {}),
+            ...(!graphCorePlanned ? { skippedReason: 'cache-fresh' } : {})
+        },
+        createContextCodeIndexShardWarmItem(input)
+    ];
+}
+function createContextCodeIndexShardWarmItem(input) {
+    const read = readContextCodeIndexShard({
+        projectRoot: input.projectRoot,
+        manifest: input.manifest
+    });
+    const planned = !read.hit;
+    let afterCacheKey;
+    let result;
+    if (input.execute && planned) {
+        result = (0, code_index_1.buildCodeIndexReport)({
+            projectRoot: input.projectRoot,
+            generatedAt: input.generatedAt,
+            sourceEntries: codeIndexSourceEntries(input.manifest),
+            fileSummaryCache: {
+                mode: 'read-write',
+                createdAt: input.generatedAt,
+                extractorVersion: input.manifest.extractorVersions.codeIndex
+            }
+        });
+        const record = writeContextCodeIndexShard({
+            projectRoot: input.projectRoot,
+            manifest: input.manifest,
+            result,
+            createdAt: input.generatedAt
+        });
+        afterCacheKey = record.cacheKey;
+    }
+    return {
+        extractorKey: 'codeIndex',
+        cachePath: read.path,
+        beforeStatus: read.status,
+        planned,
+        executed: input.execute && planned,
+        ...(read.record ? { beforeCacheKey: read.record.cacheKey } : {}),
+        ...(afterCacheKey ? { afterCacheKey } : {}),
+        ...(result?.cache?.readFileSummaryCount === undefined ? {} : {
+            readFileSummaryCount: result.cache.readFileSummaryCount,
+            reusedFileSummaryCount: result.cache.reusedFileSummaryCount,
+            recomputedFileSummaryCount: result.cache.recomputedFileSummaryCount,
+            missingFileSummaryCount: result.cache.missingFileSummaryCount,
+            staleFileSummaryCount: result.cache.staleFileSummaryCount,
+            corruptFileSummaryCount: result.cache.corruptFileSummaryCount,
+            schemaMismatchFileSummaryCount: result.cache.schemaMismatchFileSummaryCount
+        }),
+        ...(!planned ? { skippedReason: 'cache-fresh' } : {})
+    };
+}
+function codeIndexSourceEntries(manifest) {
+    return manifest.sources
+        .filter((source) => source.extractorKeys.includes('codeIndex'))
+        .map((source) => ({
+        path: source.path,
+        sizeBytes: source.sizeBytes,
+        ...(source.mtimeMs === undefined ? {} : { mtimeMs: source.mtimeMs }),
+        ...(source.contentHash ? { contentHash: source.contentHash } : {}),
+        metadataHash: source.metadataHash,
+        extractorKeys: source.extractorKeys
+    }));
+}
+function withCodeIndexCacheHitMetadata(report, record, cachePath) {
+    return {
+        ...report,
+        cache: {
+            used: true,
+            hit: true,
+            mode: 'code-index',
+            manifestHash: record.manifestHash,
+            createdAt: record.createdAt,
+            cachePath
+        }
+    };
+}
+function createSourceManifestCacheAnalysis(input) {
+    const generatedAt = input.generatedAt ?? new Date().toISOString();
+    const cached = readContextSourceManifestCache(input.projectRoot);
+    const fastFreshness = cached.status === 'valid' && cached.manifest
+        ? (0, source_manifest_1.checkContextSourceManifestFastFreshness)(input.projectRoot, cached.manifest)
+        : undefined;
+    if (cached.status === 'valid' && cached.manifest) {
+        if (fastFreshness?.ok) {
+            return {
+                generatedAt,
+                cached,
+                currentManifest: cached.manifest,
+                comparison: {
+                    addedPaths: [],
+                    removedPaths: [],
+                    changedPaths: [],
+                    unchangedPaths: cached.manifest.sources.map((source) => source.path).sort(),
+                    staleExtractorKeys: []
+                },
+                staleExtractorKeys: [],
+                cacheFresh: true,
+                fastPath: 'hit',
+                fastPathReason: fastFreshness.reason,
+                fastPathStrategy: fastFreshness.strategy,
+                degraded: cached.manifest.issues.some((issue) => issue.severity === 'warning' || issue.severity === 'error'),
+                issues: [...cached.issues]
+            };
+        }
+    }
+    const currentManifest = (0, source_manifest_1.buildContextSourceManifest)({
+        projectRoot: input.projectRoot,
+        generatedAt,
+        generatedByCommand: input.generatedByCommand,
+        ...(cached.status === 'valid' && cached.manifest ? { previousManifest: cached.manifest } : {})
+    });
+    const comparison = cached.manifest
+        ? (0, source_manifest_1.compareContextSourceManifests)(cached.manifest, currentManifest)
+        : { addedPaths: [], removedPaths: [], changedPaths: [], unchangedPaths: [], staleExtractorKeys: [] };
+    const staleExtractorKeys = comparison.staleExtractorKeys;
+    const cacheFresh = cached.status === 'valid'
+        && cached.manifest?.manifestHash === currentManifest.manifestHash
+        && staleExtractorKeys.length === 0
+        && comparison.addedPaths.length === 0
+        && comparison.removedPaths.length === 0
+        && comparison.changedPaths.length === 0;
+    const degraded = currentManifest.issues.some((issue) => issue.severity === 'warning' || issue.severity === 'error');
+    const issues = [...cached.issues];
+    if (cached.status === 'valid' && !cacheFresh) {
+        issues.push(contextCacheIssue('warning', 'CONTEXT_CACHE_STALE', 'Source manifest cache is stale relative to current project source metadata.', source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH));
+    }
+    return {
+        generatedAt,
+        cached,
+        currentManifest,
+        comparison,
+        staleExtractorKeys,
+        cacheFresh,
+        fastPath: fastFreshness ? 'miss' : 'skipped',
+        ...(fastFreshness ? {
+            fastPathReason: fastFreshness.reason,
+            ...(fastFreshness.strategy ? { fastPathStrategy: fastFreshness.strategy } : {})
+        } : {}),
+        degraded,
+        issues
+    };
+}
+function createManifestReportSection(analysis) {
+    return {
+        cachePath: source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_PATH,
+        status: analysis.cacheFresh ? 'fresh' : analysis.cached.status === 'valid' ? 'stale' : analysis.cached.status,
+        currentManifestHash: analysis.currentManifest.manifestHash,
+        currentSourceCount: analysis.currentManifest.summary.sourceCount,
+        currentSkippedSourceCount: analysis.currentManifest.summary.skippedSourceCount,
+        ...(analysis.cached.manifest ? {
+            cachedManifestHash: analysis.cached.manifest.manifestHash,
+            cachedGeneratedAt: analysis.cached.manifest.generatedAt,
+            cachedSourceCount: analysis.cached.manifest.summary.sourceCount
+        } : {}),
+        addedPaths: analysis.comparison.addedPaths,
+        removedPaths: analysis.comparison.removedPaths,
+        changedPaths: analysis.comparison.changedPaths,
+        unchangedSourceCount: analysis.comparison.unchangedPaths.length,
+        staleExtractorKeys: analysis.staleExtractorKeys,
+        fastPath: analysis.fastPath,
+        ...(analysis.fastPathReason ? { fastPathReason: analysis.fastPathReason } : {}),
+        ...(analysis.fastPathStrategy ? { fastPathStrategy: analysis.fastPathStrategy } : {})
+    };
+}
+function normalizeContextCachePath(inputPath) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(inputPath);
+    if (node_path_1.default.isAbsolute(inputPath) || normalizedPath.startsWith('../') || normalizedPath === '..') {
+        throw new Error(`Context cache path must be project-relative: ${inputPath}`);
+    }
+    if (normalizedPath !== source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT && !normalizedPath.startsWith(`${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT}/`)) {
+        throw new Error(`Context cache path must stay under ${source_manifest_1.CONTEXT_SOURCE_MANIFEST_CACHE_ROOT}: ${inputPath}`);
+    }
+    return normalizedPath;
+}
+function contextGraphExtractorShardProjection(extractorKey) {
+    return `${CONTEXT_GRAPH_EXTRACTOR_SHARD_PROJECTION_PREFIX}.${extractorKey}`;
+}
+function validateGraphExtractionPayload(payload, extractorKey, cachePath) {
+    if (!payload
+        || typeof payload !== 'object'
+        || !payload.source
+        || payload.source.extractor !== extractorKey
+        || !Array.isArray(payload.source.paths)
+        || typeof payload.source.sourceHash !== 'string'
+        || !Array.isArray(payload.nodes)
+        || !Array.isArray(payload.edges)
+        || !Array.isArray(payload.issues)) {
+        return contextCacheIssue('warning', 'CONTEXT_CACHE_SCHEMA_MISMATCH', `Context graph extractor shard ${extractorKey} payload is not a valid extraction result.`, cachePath);
+    }
+    return undefined;
+}
+function validateGraphCorePayload(payload, cachePath) {
+    if (!payload
+        || typeof payload !== 'object'
+        || !payload.source
+        || payload.source.extractor !== 'mergeGraphExtractionResults'
+        || !Array.isArray(payload.source.paths)
+        || typeof payload.source.sourceHash !== 'string'
+        || !Array.isArray(payload.nodes)
+        || !Array.isArray(payload.edges)
+        || !Array.isArray(payload.issues)) {
+        return contextCacheIssue('warning', 'CONTEXT_CACHE_SCHEMA_MISMATCH', 'Context graph core shard payload is not a valid merged extraction result.', cachePath);
+    }
+    return undefined;
+}
+function validateCodeIndexPayload(payload, cachePath) {
+    const validation = (0, schema_1.validateSchema)(code_index_1.CODE_INDEX_SCHEMA_ID, payload);
+    if (!validation.ok) {
+        return contextCacheIssue('warning', 'CONTEXT_CACHE_SCHEMA_MISMATCH', `Context code-index shard payload is not a valid ${code_index_1.CODE_INDEX_SCHEMA_ID} report.`, cachePath);
+    }
+    return undefined;
+}
+function sameRecord(left, right) {
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every((key, index) => key === rightKeys[index] && left[key] === right[key]);
+}
+function contextCacheIssue(severity, code, message, issuePath) {
+    return {
+        severity,
+        code,
+        message,
+        ...(issuePath ? { path: issuePath } : {})
+    };
+}