taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/application/context/context-loader.js

@@ -0,0 +1,223 @@
+import { resolve } from "node:path";
+import { ProjectContextModuleSchema, ProjectContextSchema, ResolvedProjectContextSchema } from "../../domain/project-context.js";
+import { projectRelativePath } from "../../shared/paths.js";
+import { assertProjectPathUnder, CONTEXT_DIR } from "../../domain/workspace.js";
+import { compareStrings } from "../../shared/strings.js";
+import { assertShardIdentity } from "./shard-identity.js";
+export const MAX_CONTEXT_SHARD_BYTES = 4 * 1024 * 1024;
+export class ContextLoadError extends Error {
+    code;
+    name = "ContextLoadError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function inspectionMessage(label, path, inspection) {
+    switch (inspection.status) {
+        case "rootNotFound":
+        case "rootUnreadable":
+            return "Project root does not exist or cannot be read";
+        case "rootNotDirectory":
+            return "Project root is not a directory";
+        case "notFound":
+            return `${label} does not exist: ${path}`;
+        case "unreadable":
+            return `${label} cannot be read: ${path}`;
+        case "escape":
+            return `${label} resolves outside the project: ${path}`;
+        case "changedIdentity":
+            return `${label} changed during inspection: ${path}`;
+        case "notFile":
+            return `${label} path is not a file: ${path}`;
+        case "tooLarge":
+            return `${label} exceeds ${String(MAX_CONTEXT_SHARD_BYTES)} bytes: ${path}`;
+    }
+}
+function selectedReferences(bundle, requestedIds) {
+    const byId = new Map(bundle.modules.map((module) => [module.id, module]));
+    const selected = new Set(requestedIds === undefined || requestedIds.length === 0
+        ? bundle.modules.map((module) => module.id)
+        : [
+            ...bundle.modules
+                .filter((module) => module.kind === "application")
+                .map((module) => module.id),
+            ...requestedIds
+        ]);
+    const pending = [...selected];
+    while (pending.length > 0) {
+        const id = pending.pop();
+        if (id === undefined) {
+            continue;
+        }
+        const module = byId.get(id);
+        if (module === undefined) {
+            throw new ContextLoadError("CONTEXT_MODULE_NOT_FOUND", `Project Context module does not exist: ${id}`);
+        }
+        for (const dependency of module.dependsOn) {
+            if (!selected.has(dependency)) {
+                selected.add(dependency);
+                pending.push(dependency);
+            }
+        }
+    }
+    return bundle.modules.filter((module) => selected.has(module.id));
+}
+function effectiveContext(bundle, modules, indexHash) {
+    const evidence = [
+        ...bundle.manifest.files,
+        ...modules.flatMap((module) => module.manifest.files)
+    ];
+    const byPath = new Map();
+    for (const file of evidence) {
+        const existing = byPath.get(file.path);
+        if (existing !== undefined && existing.sha256 !== file.sha256) {
+            throw new ContextLoadError("CONTEXT_INVALID", `Conflicting Context evidence hash for ${file.path}`);
+        }
+        byPath.set(file.path, file);
+    }
+    return ResolvedProjectContextSchema.parse({
+        version: 2,
+        packageName: bundle.packageName,
+        launchActivity: bundle.launchActivity,
+        manifest: {
+            version: 1,
+            files: [...byPath.values()].sort((left, right) => (compareStrings(left.path, right.path)))
+        },
+        interactionPolicy: bundle.interactionPolicy,
+        selection: {
+            bundleVersion: 2,
+            indexHash,
+            modules: modules.map((module) => {
+                const reference = bundle.modules.find((candidate) => candidate.id === module.moduleId);
+                if (reference === undefined) {
+                    throw new ContextLoadError("CONTEXT_INVALID", `Context shard is missing from its index: ${module.moduleId}`);
+                }
+                return {
+                    id: reference.id,
+                    sha256: reference.sha256,
+                    projectDir: module.projectDir,
+                    inventory: {
+                        pathSetSha256: module.inventory.pathSetSha256,
+                        categories: module.inventory.categories
+                    }
+                };
+            })
+        }
+    });
+}
+function sameStrings(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    const sortedLeft = [...left].sort(compareStrings);
+    const sortedRight = [...right].sort(compareStrings);
+    return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
+export class ContextLoader {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    readStableDocument = async (input) => {
+        const before = await this.dependencies.files.inspectProjectFile({
+            projectRoot: input.root,
+            relativePath: input.relativePath,
+            maximumBytes: MAX_CONTEXT_SHARD_BYTES
+        });
+        if (before.status !== "inspected") {
+            throw new ContextLoadError("CONTEXT_INVALID", inspectionMessage(input.label, input.relativePath, before));
+        }
+        let document;
+        try {
+            document = await this.dependencies.readJson(resolve(input.root, input.relativePath));
+        }
+        catch (error) {
+            throw new ContextLoadError("CONTEXT_INVALID", error instanceof Error
+                ? error.message
+                : `Unable to read ${input.label}: ${input.relativePath}`);
+        }
+        const after = await this.dependencies.files.inspectProjectFile({
+            projectRoot: input.root,
+            relativePath: input.relativePath,
+            maximumBytes: MAX_CONTEXT_SHARD_BYTES
+        });
+        if (after.status !== "inspected"
+            || after.sha256 !== before.sha256) {
+            throw new ContextLoadError("CONTEXT_INVALID", `${input.label} changed while loading: ${input.relativePath}`);
+        }
+        return { document, sha256: before.sha256 };
+    };
+    readIndex = async (input) => {
+        const contextRoot = input.projectRoot;
+        const relativeContextPath = projectRelativePath(contextRoot, input.contextPath, (message) => new ContextLoadError("CONTEXT_INVALID", message));
+        try {
+            assertProjectPathUnder(contextRoot, relativeContextPath, CONTEXT_DIR, "Project Context");
+        }
+        catch (error) {
+            throw new ContextLoadError("CONTEXT_INVALID", error instanceof Error ? error.message : String(error));
+        }
+        const loaded = await this.readStableDocument({
+            root: contextRoot,
+            relativePath: relativeContextPath,
+            label: "Project Context index"
+        });
+        const parsedBundle = ProjectContextSchema.safeParse(loaded.document);
+        if (!parsedBundle.success) {
+            throw new ContextLoadError("CONTEXT_INVALID", "Project Context does not match the version 2 index schema");
+        }
+        return {
+            bundle: parsedBundle.data,
+            indexHash: loaded.sha256
+        };
+    };
+    load = async (input) => {
+        const { bundle, indexHash } = await this.readIndex(input);
+        const references = selectedReferences(bundle, input.moduleIds);
+        if (input.allowIncomplete !== true) {
+            const incomplete = references.find((module) => module.status === "partial"
+                || module.status === "notAnalyzed");
+            if (incomplete !== undefined) {
+                throw new ContextLoadError("CONTEXT_MODULE_INCOMPLETE", `Project Context module is ${incomplete.status}: ${incomplete.id}`);
+            }
+        }
+        const modules = [];
+        for (const reference of references) {
+            const loaded = await this.readStableDocument({
+                root: input.projectRoot,
+                relativePath: reference.contextPath,
+                label: "Context shard"
+            });
+            if (loaded.sha256 !== reference.sha256) {
+                throw new ContextLoadError("CONTEXT_STALE", `Context shard changed: ${reference.contextPath}`);
+            }
+            const module = ProjectContextModuleSchema.safeParse(loaded.document);
+            if (!module.success) {
+                throw new ContextLoadError("CONTEXT_INVALID", `Context shard does not match the module schema: ${reference.contextPath}`);
+            }
+            assertShardIdentity(reference, module.data, (message) => new ContextLoadError("CONTEXT_INVALID", message));
+            if (!sameStrings(reference.features, module.data.summary.features)
+                || !sameStrings(reference.activities, module.data.summary.activities.map((activity) => activity.name))) {
+                throw new ContextLoadError("CONTEXT_INVALID", `Context shard routing summary does not match its index: ${reference.id}`);
+            }
+            const inventory = await this.dependencies.inventory.inspectProjectInventory({
+                projectRoot: input.projectRoot,
+                projectDir: module.data.projectDir,
+                categories: module.data.inventory.categories
+            });
+            if (inventory.status !== "inspected") {
+                throw new ContextLoadError("CONTEXT_INVALID", `Unable to inspect module inventory: ${reference.id}`);
+            }
+            if (inventory.pathSetSha256 !== module.data.inventory.pathSetSha256) {
+                throw new ContextLoadError("CONTEXT_STALE", `Module file inventory changed: ${reference.id}`);
+            }
+            modules.push(module.data);
+        }
+        const context = effectiveContext(bundle, modules, indexHash);
+        return {
+            context,
+            bundle,
+            modules
+        };
+    };
+}

package/dist/application/context/context-refresher.d.ts

@@ -0,0 +1,59 @@
+import type { ContextDocumentWriter } from "../../ports/context-document-writer.js";
+import type { ProjectFileInspector } from "../../ports/project-file-inspector.js";
+import type { ProjectInventoryInspector } from "../../ports/project-inventory-inspector.js";
+import { type ContextLoader } from "./context-loader.js";
+export type ContextRefreshErrorCode = "CONTEXT_INVALID" | "CONTEXT_MODULE_NOT_FOUND" | "CONTEXT_WRITE_FAILED";
+export declare class ContextRefreshError extends Error {
+    readonly code: ContextRefreshErrorCode;
+    readonly name = "ContextRefreshError";
+    constructor(code: ContextRefreshErrorCode, message: string);
+}
+export type ContextRefreshBlockCode = "EVIDENCE_UNRESOLVED" | "EVIDENCE_SEMANTIC_CHANGED" | "MODULE_INVENTORY_CHANGED";
+export type ContextRefreshResolution = "pruneDeleted" | "acceptSourceChanges" | "reanalyze";
+export interface ContextRefreshBlock {
+    code: ContextRefreshBlockCode;
+    resolution: ContextRefreshResolution;
+    message: string;
+}
+export interface ContextRefreshScopeReport {
+    scope: "index" | "module";
+    id: string;
+    contextPath: string;
+    written: boolean;
+    semanticBackfilled: number;
+    formattingRehashed: number;
+    semanticChanged: string[];
+    unresolved: string[];
+    pruned: number;
+    droppedIneligible: number;
+    inventoryChanged: boolean;
+}
+export interface ContextRefreshResult {
+    status: "refreshed" | "unchanged" | "blocked";
+    indexHash: string;
+    acceptedSourceChanges: boolean;
+    scopes: ContextRefreshScopeReport[];
+    blocked: ContextRefreshBlock[];
+}
+export interface ContextRefreshInput {
+    projectRoot: string;
+    contextPath: string;
+    moduleIds?: string[] | undefined;
+    acceptSourceChanges?: boolean | undefined;
+    pruneDeleted?: boolean | undefined;
+}
+export interface ContextRefresherDependencies {
+    files: ProjectFileInspector;
+    inventory: ProjectInventoryInspector;
+    loader: Pick<ContextLoader, "readIndex">;
+    writer: ContextDocumentWriter;
+}
+export declare class ContextRefresher {
+    private readonly dependencies;
+    constructor(dependencies: ContextRefresherDependencies);
+    readonly refresh: (input: ContextRefreshInput) => Promise<ContextRefreshResult>;
+    private readonly refreshModule;
+    private readonly refreshManifest;
+    private readonly readShard;
+    private readonly writeDocument;
+}

package/dist/application/context/context-refresher.js

@@ -0,0 +1,349 @@
+import { ProjectContextModuleSchema, ProjectContextSchema } from "../../domain/project-context.js";
+import { projectRelativePath } from "../../shared/paths.js";
+import { MAX_CONTEXT_SHARD_BYTES } from "./context-loader.js";
+import { MAX_CONTEXT_EVIDENCE_BYTES } from "./context-validator.js";
+import { semanticSha256 } from "./evidence-hash.js";
+import { assertShardIdentity } from "./shard-identity.js";
+import { assertProjectPathUnder, CONTEXT_DIR } from "../../domain/workspace.js";
+export class ContextRefreshError extends Error {
+    code;
+    name = "ContextRefreshError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function selectedReferences(bundle, moduleIds) {
+    if (moduleIds === undefined || moduleIds.length === 0) {
+        return bundle.modules;
+    }
+    const requested = new Set(moduleIds);
+    for (const id of requested) {
+        if (!bundle.modules.some((module) => module.id === id)) {
+            throw new ContextRefreshError("CONTEXT_MODULE_NOT_FOUND", `Project Context module does not exist: ${id}`);
+        }
+    }
+    return bundle.modules.filter((module) => requested.has(module.id));
+}
+function scopeBlocks(report, acceptSourceChanges) {
+    const blocks = [];
+    if (report.unresolved.length > 0) {
+        const allNotFound = report.unresolved.every((entry) => entry.endsWith(": notFound"));
+        blocks.push({
+            code: "EVIDENCE_UNRESOLVED",
+            resolution: allNotFound ? "pruneDeleted" : "reanalyze",
+            message: `${report.id}: evidence cannot be hashed (${report.unresolved.join(", ")})`
+        });
+    }
+    if (acceptSourceChanges) {
+        return blocks;
+    }
+    if (report.semanticChanged.length > 0) {
+        blocks.push({
+            code: "EVIDENCE_SEMANTIC_CHANGED",
+            resolution: "acceptSourceChanges",
+            message: `${report.id}: ${String(report.semanticChanged.length)} evidence files changed semantically (${report.semanticChanged.join(", ")})`
+        });
+    }
+    if (report.inventoryChanged) {
+        blocks.push({
+            code: "MODULE_INVENTORY_CHANGED",
+            resolution: "acceptSourceChanges",
+            message: `${report.id}: module file inventory changed`
+        });
+    }
+    return blocks;
+}
+export class ContextRefresher {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    refresh = async (input) => {
+        const indexPath = projectRelativePath(input.projectRoot, input.contextPath, (message) => new ContextRefreshError("CONTEXT_INVALID", message));
+        try {
+            assertProjectPathUnder(input.projectRoot, indexPath, CONTEXT_DIR, "Project Context output");
+        }
+        catch (error) {
+            throw new ContextRefreshError("CONTEXT_INVALID", error instanceof Error ? error.message : String(error));
+        }
+        const { bundle, indexHash } = await this.dependencies.loader.readIndex({
+            projectRoot: input.projectRoot,
+            contextPath: input.contextPath
+        });
+        const acceptSourceChanges = input.acceptSourceChanges === true;
+        const pruneDeleted = input.pruneDeleted === true;
+        const references = selectedReferences(bundle, input.moduleIds);
+        const root = await this.refreshManifest(input.projectRoot, bundle.manifest, acceptSourceChanges, pruneDeleted);
+        const rootReport = {
+            scope: "index",
+            id: "index",
+            contextPath: indexPath,
+            written: false,
+            semanticBackfilled: root.semanticBackfilled,
+            formattingRehashed: root.formattingRehashed,
+            semanticChanged: root.semanticChanged,
+            unresolved: root.unresolved,
+            pruned: root.pruned,
+            droppedIneligible: root.droppedIneligible,
+            inventoryChanged: false
+        };
+        const modules = [];
+        for (const reference of references) {
+            modules.push(await this.refreshModule(input.projectRoot, reference, acceptSourceChanges, pruneDeleted));
+        }
+        const blocked = [
+            ...scopeBlocks(rootReport, acceptSourceChanges),
+            ...modules.flatMap((module) => scopeBlocks(module.report, acceptSourceChanges))
+        ];
+        const scopes = [rootReport, ...modules.map((module) => module.report)];
+        if (blocked.length > 0) {
+            return {
+                status: "blocked",
+                indexHash,
+                acceptedSourceChanges: acceptSourceChanges,
+                scopes,
+                blocked
+            };
+        }
+        const moduleHashes = new Map();
+        for (const module of modules) {
+            if (!module.modified) {
+                moduleHashes.set(module.reference.id, module.currentSha256);
+            }
+        }
+        const modifiedModules = modules.filter((module) => module.modified);
+        if (modifiedModules.length > 0) {
+            const batchWriter = this.dependencies.writer.writeContextDocumentBatch;
+            if (batchWriter !== undefined) {
+                const results = await batchWriter({
+                    projectRoot: input.projectRoot,
+                    documents: modifiedModules.map((module) => ({
+                        relativePath: module.reference.contextPath,
+                        document: module.document
+                    }))
+                });
+                for (let i = 0; i < modifiedModules.length; i++) {
+                    const module = modifiedModules[i];
+                    if (module === undefined) {
+                        continue;
+                    }
+                    const result = results[i];
+                    if (result === undefined || result.status !== "written") {
+                        let message;
+                        if (result === undefined) {
+                            message = `Context document cannot be written: ${module.reference.contextPath}`;
+                        }
+                        else if (result.status === "escape") {
+                            message = `Context document resolves outside the project: ${module.reference.contextPath}`;
+                        }
+                        else {
+                            message = `Context document cannot be written: ${module.reference.contextPath} (${result.message})`;
+                        }
+                        throw new ContextRefreshError("CONTEXT_WRITE_FAILED", message);
+                    }
+                    moduleHashes.set(module.reference.id, result.sha256);
+                    module.report.written = true;
+                }
+            }
+            else {
+                for (const module of modifiedModules) {
+                    moduleHashes.set(module.reference.id, await this.writeDocument(input.projectRoot, module.reference.contextPath, module.document));
+                    module.report.written = true;
+                }
+            }
+        }
+        const nextModules = bundle.modules.map((module) => {
+            const sha256 = moduleHashes.get(module.id);
+            return sha256 === undefined || sha256 === module.sha256
+                ? module
+                : { ...module, sha256 };
+        });
+        const indexModified = root.modified
+            || nextModules.some((module, index) => module !== bundle.modules[index]);
+        if (!indexModified) {
+            return {
+                status: modules.some((module) => module.report.written)
+                    ? "refreshed"
+                    : "unchanged",
+                indexHash,
+                acceptedSourceChanges: acceptSourceChanges,
+                scopes,
+                blocked
+            };
+        }
+        const nextBundle = ProjectContextSchema.safeParse({
+            ...bundle,
+            manifest: { ...bundle.manifest, files: root.files },
+            modules: nextModules
+        });
+        if (!nextBundle.success) {
+            throw new ContextRefreshError("CONTEXT_INVALID", "Refreshed Project Context index does not match the version 2 schema");
+        }
+        const nextIndexHash = await this.writeDocument(input.projectRoot, indexPath, nextBundle.data);
+        rootReport.written = true;
+        return {
+            status: "refreshed",
+            indexHash: nextIndexHash,
+            acceptedSourceChanges: acceptSourceChanges,
+            scopes,
+            blocked
+        };
+    };
+    refreshModule = async (projectRoot, reference, acceptSourceChanges, pruneDeleted) => {
+        const shard = await this.readShard(projectRoot, reference);
+        const inventory = await this.dependencies.inventory.inspectProjectInventory({
+            projectRoot,
+            projectDir: shard.document.projectDir,
+            categories: shard.document.inventory.categories
+        });
+        if (inventory.status !== "inspected") {
+            throw new ContextRefreshError("CONTEXT_INVALID", `Unable to inspect module inventory: ${reference.id}`);
+        }
+        const inventoryChanged = (inventory.pathSetSha256 !== shard.document.inventory.pathSetSha256);
+        const acceptedInventory = inventoryChanged && acceptSourceChanges;
+        const manifest = await this.refreshManifest(projectRoot, shard.document.manifest, acceptSourceChanges, pruneDeleted, acceptedInventory ? new Set(inventory.paths) : undefined);
+        const document = ProjectContextModuleSchema.safeParse({
+            ...shard.document,
+            inventory: acceptedInventory
+                ? {
+                    ...shard.document.inventory,
+                    pathSetSha256: inventory.pathSetSha256
+                }
+                : shard.document.inventory,
+            manifest: { ...shard.document.manifest, files: manifest.files }
+        });
+        if (!document.success) {
+            throw new ContextRefreshError("CONTEXT_INVALID", `Refreshed Context shard does not match the module schema: ${reference.contextPath}`);
+        }
+        return {
+            reference,
+            document: document.data,
+            currentSha256: shard.sha256,
+            modified: manifest.modified || acceptedInventory,
+            report: {
+                scope: "module",
+                id: reference.id,
+                contextPath: reference.contextPath,
+                written: false,
+                semanticBackfilled: manifest.semanticBackfilled,
+                formattingRehashed: manifest.formattingRehashed,
+                semanticChanged: manifest.semanticChanged,
+                unresolved: manifest.unresolved,
+                pruned: manifest.pruned,
+                droppedIneligible: manifest.droppedIneligible,
+                inventoryChanged
+            }
+        };
+    };
+    refreshManifest = async (projectRoot, manifest, acceptSourceChanges, pruneDeleted, eligiblePaths) => {
+        const files = [];
+        const semanticChanged = [];
+        const unresolved = [];
+        let modified = false;
+        let semanticBackfilled = 0;
+        let formattingRehashed = 0;
+        let pruned = 0;
+        let droppedIneligible = 0;
+        for (const evidence of manifest.files) {
+            const inspection = await this.dependencies.files.inspectProjectFile({
+                projectRoot,
+                relativePath: evidence.path,
+                maximumBytes: MAX_CONTEXT_EVIDENCE_BYTES
+            });
+            if (inspection.status !== "inspected" || inspection.bytes === undefined) {
+                if (pruneDeleted && inspection.status === "notFound") {
+                    pruned += 1;
+                    modified = true;
+                    continue;
+                }
+                unresolved.push(`${evidence.path}: ${inspection.status}`);
+                files.push(evidence);
+                continue;
+            }
+            if (eligiblePaths !== undefined && !eligiblePaths.has(evidence.path)) {
+                droppedIneligible += 1;
+                modified = true;
+                continue;
+            }
+            const semantic = semanticSha256(inspection.bytes);
+            if (inspection.sha256 === evidence.sha256) {
+                if (evidence.semanticSha256 === semantic) {
+                    files.push(evidence);
+                    continue;
+                }
+                files.push({ ...evidence, semanticSha256: semantic });
+                semanticBackfilled += 1;
+                modified = true;
+                continue;
+            }
+            if (evidence.semanticSha256 === semantic) {
+                files.push({
+                    ...evidence,
+                    sha256: inspection.sha256,
+                    semanticSha256: semantic
+                });
+                formattingRehashed += 1;
+                modified = true;
+                continue;
+            }
+            semanticChanged.push(evidence.path);
+            if (!acceptSourceChanges) {
+                files.push(evidence);
+                continue;
+            }
+            files.push({
+                ...evidence,
+                sha256: inspection.sha256,
+                semanticSha256: semantic
+            });
+            modified = true;
+        }
+        return {
+            files,
+            modified,
+            semanticBackfilled,
+            formattingRehashed,
+            semanticChanged,
+            unresolved,
+            pruned,
+            droppedIneligible
+        };
+    };
+    readShard = async (projectRoot, reference) => {
+        const inspection = await this.dependencies.files.inspectProjectFile({
+            projectRoot,
+            relativePath: reference.contextPath,
+            maximumBytes: MAX_CONTEXT_SHARD_BYTES
+        });
+        if (inspection.status !== "inspected" || inspection.bytes === undefined) {
+            throw new ContextRefreshError("CONTEXT_INVALID", `Context shard cannot be read: ${reference.contextPath}`);
+        }
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(inspection.bytes.toString("utf8"));
+        }
+        catch {
+            throw new ContextRefreshError("CONTEXT_INVALID", `Context shard is not valid JSON: ${reference.contextPath}`);
+        }
+        const document = ProjectContextModuleSchema.safeParse(parsedJson);
+        if (!document.success) {
+            throw new ContextRefreshError("CONTEXT_INVALID", `Context shard does not match the module schema: ${reference.contextPath}`);
+        }
+        assertShardIdentity(reference, document.data, (message) => new ContextRefreshError("CONTEXT_INVALID", message));
+        return { document: document.data, sha256: inspection.sha256 };
+    };
+    writeDocument = async (projectRoot, relativePath, document) => {
+        const written = await this.dependencies.writer.writeContextDocument({
+            projectRoot,
+            relativePath,
+            document
+        });
+        if (written.status !== "written") {
+            throw new ContextRefreshError("CONTEXT_WRITE_FAILED", written.status === "escape"
+                ? `Context document resolves outside the project: ${relativePath}`
+                : `Context document cannot be written: ${relativePath} (${written.message})`);
+        }
+        return written.sha256;
+    };
+}

package/dist/application/context/context-rehasher.d.ts

@@ -0,0 +1,36 @@
+import type { ContextDocumentWriter } from "../../ports/context-document-writer.js";
+import type { ProjectFileInspector } from "../../ports/project-file-inspector.js";
+import { type ContextLoader } from "./context-loader.js";
+export type ContextRehashErrorCode = "CONTEXT_INVALID" | "CONTEXT_MODULE_NOT_FOUND" | "CONTEXT_WRITE_FAILED";
+export declare class ContextRehashError extends Error {
+    readonly code: ContextRehashErrorCode;
+    readonly name = "ContextRehashError";
+    constructor(code: ContextRehashErrorCode, message: string);
+}
+export interface ContextRehashInput {
+    readonly projectRoot: string;
+    readonly contextPath: string;
+    readonly moduleIds?: readonly string[] | undefined;
+}
+export interface ContextRehashModuleResult {
+    readonly id: string;
+    readonly previousSha256: string;
+    readonly currentSha256: string;
+    readonly changed: boolean;
+}
+export interface ContextRehashResult {
+    readonly status: "rehashed" | "unchanged";
+    readonly modules: readonly ContextRehashModuleResult[];
+    readonly previousIndexHash: string;
+    readonly indexHash: string;
+}
+export interface ContextRehasherDependencies {
+    readonly files: ProjectFileInspector;
+    readonly loader: Pick<ContextLoader, "readIndex">;
+    readonly writer: ContextDocumentWriter;
+}
+export declare class ContextRehasher {
+    private readonly dependencies;
+    constructor(dependencies: ContextRehasherDependencies);
+    readonly rehash: (input: ContextRehashInput) => Promise<ContextRehashResult>;
+}