@coggit/core 0.2.0

package/dist/registry/inMemoryRegistryProvider.d.ts

@@ -0,0 +1,18 @@
+import type { RegistryProvider, RegistryFile } from '../types';
+/**
+ * In-memory registry provider for testing.
+ *
+ * Stores data as a deep-cloned JSON object so each load/save round-trip
+ * produces independent copies (no shared references).
+ *
+ * This is a pure core test double (no host runtime dependency), so it lives in
+ * the core package next to the `RegistryProvider` port it implements rather than
+ * in a runtime adapter.
+ */
+export declare class InMemoryRegistryProvider implements RegistryProvider {
+    private data;
+    load(): Promise<RegistryFile | null>;
+    save(file: RegistryFile): Promise<void>;
+    /** Test helper: simulate corrupt data to exercise recovery paths. */
+    corrupt(): void;
+}

package/dist/registry/index.d.ts

@@ -0,0 +1,104 @@
+import type { AcceptedPair, PathKeyRecord, RegistryFile, RegistryProvider } from '../types';
+import { type CoggitLogger } from '../logger';
+export declare const REGISTRY_SCHEMA_VERSION = 6;
+export declare const REGISTRY_MAINTENANCE_NOTICE = "This file is auto-maintained CogGit metadata. Ignore routine changes; it is committed so metadata can be located across hosts. Direct reads may be stale; use CogGit commands or MCP tools for authoritative freshness.";
+export interface RegistryCreateOptions {
+    logger?: CoggitLogger;
+}
+/** Opaque revision of the complete registry file loaded by a Registry instance. */
+export type RegistryRevision = string;
+/**
+ * Raised when a Registry instance tries to flush a file based on an obsolete
+ * loaded revision. Callers must discard the instance, reload, and recompute.
+ */
+export declare class RegistryRevisionMismatchError extends Error {
+    readonly expectedRevision: RegistryRevision;
+    readonly actualRevision: RegistryRevision;
+    constructor(expectedRevision: RegistryRevision, actualRevision: RegistryRevision);
+}
+/**
+ * In-memory metadata store backed by a provider (VSCode filesystem or in-memory).
+ *
+ * Manages CRUD over registry entries, dirty tracking, and atomic flush.
+ * Core modules must NOT import this class directly -- only reference the
+ * `RegistryProvider` interface from types.ts.
+ */
+export declare class Registry {
+    private file;
+    private dirty;
+    private provider;
+    private logger;
+    private revision;
+    private constructor();
+    /**
+     * Create a Registry instance backed by the given provider.
+     *
+     * - If the provider has stored data, it is loaded and validated.
+     * - Schema version mismatch triggers a clean rebuild (not a crash).
+     * - If no stored data exists, an empty registry is created.
+     */
+    static create(provider: RegistryProvider, options?: RegistryCreateOptions): Promise<Registry>;
+    /** Get a single entry by key, or undefined if not found. */
+    getEntry(key: string): PathKeyRecord | undefined;
+    /** Check whether an entry exists for the given key. */
+    hasEntry(key: string): boolean;
+    /** Get a shallow clone of all entries (prevents external mutation of the internal map). */
+    getAllEntries(): Record<string, PathKeyRecord>;
+    /** Find all entries that reference the given source path. */
+    getEntriesBySourcePath(sourcePath: string): PathKeyRecord[];
+    /** Find all path-keyed records that reference the given source path. */
+    getRecordsBySourcePath(sourcePath: string): Array<{
+        key: string;
+        record: PathKeyRecord;
+    }>;
+    /** Find all registry keys that reference the given source path. */
+    getKeysBySourcePath(sourcePath: string): string[];
+    /** Get all registry keys. */
+    getKeys(): string[];
+    /** Read the complete accepted source/cognition relationship. */
+    getAcceptedPair(key: string): AcceptedPair | null;
+    /** @deprecated Legacy in-memory accessor; v5 freshness uses getAcceptedPair. */
+    getFreshnessTimes(key: string): {
+        sourceFactMtimeMs: number | null;
+        cognitionMtimeMs: number | null;
+        verificationTimeMs: number | null;
+        sourceFactHash: string | null;
+    };
+    /** Add or overwrite an entry at the given key. Marks the registry dirty. */
+    setEntry(key: string, entry: PathKeyRecord, source?: string): void;
+    /** Remove an entry by key. Marks the registry dirty. No-op if the key does not exist. */
+    deleteEntry(key: string, source?: string): void;
+    /**
+     * Move an entry from oldKey to newKey, preserving all entry fields.
+     *
+     * Sets dirty once (not delete+set as two separate operations).
+     *
+     * @returns true if the rename succeeded, false if oldKey did not exist.
+     */
+    renameKey(oldKey: string, newKey: string, source?: string): boolean;
+    /** Replace the complete accepted relationship atomically in memory. */
+    recordAcceptance(key: string, pair: AcceptedPair): void;
+    /** @deprecated Legacy observation API; not used by v5 runtime. */
+    recordSourceFactTime(key: string, mtimeMs: number, sourceFactHash?: string | null): void;
+    /** @deprecated Legacy observation API; not used by v5 runtime. */
+    recordCognitionTime(key: string, mtimeMs: number, contentHash?: string | null, contentLength?: number | null): void;
+    /** @deprecated Legacy verification API; use recordAcceptance. */
+    recordExplicitVerification(key: string, verificationTimeMs?: number): void;
+    /**
+     * Flush in-memory state to the provider.
+     *
+     * No-op if the registry has not been modified since the last flush.
+     */
+    flush(): Promise<void>;
+    /** Convenience: record an acceptance and flush immediately. */
+    flushAcceptance(key: string, pair: AcceptedPair): Promise<void>;
+    private traceSetEntry;
+    private traceRegistryMutation;
+}
+/**
+ * Compute a deterministic witness for the complete loaded file.
+ *
+ * This is intentionally not persisted and is not a freshness identity. It is
+ * only used to reject stale full-file writes within the local commit boundary.
+ */
+export declare function computeRegistryRevision(file: RegistryFile | null): RegistryRevision;

package/dist/registry/reconcile.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Phase 3: Reconcile engine.
+ *
+ * Compares the on-disk cognition directory tree against the registry to produce
+ * a diff of operations (add, delete). Called at startup and after any
+ * major structural change.
+ *
+ * ## Algorithm
+ *
+ * ```
+ * Input:
+ *   A = walk cognition dir → {key → {path, mtimeMs, contentHash, contentLength}}
+ *   B = registry entries   → {key → entry}
+ *
+ * 1.  deleted  = keys(B) - keys(A)
+ * 2.  added    = keys(A) - keys(B)
+ * ```
+ */
+import type { FileSystem, UriComponents } from '../interfaces';
+import { Registry } from './index';
+/**
+ * Scan-specific info for a cognition file found on disk.
+ *
+ * NOT the same as `CognitionFileInfo` from types.ts — this type is purpose-built
+ * for directory scanning and carries content-hash data for scan diagnostics.
+ */
+export interface CognitionFileScanInfo {
+    /** Relative path from cognition root to the `.md` file */
+    path: string;
+    /** Last modification time in milliseconds */
+    mtimeMs: number;
+    /** SHA256 hex hash of file content */
+    contentHash: string;
+    /** Content length in characters */
+    contentLength: number;
+}
+/** Result of scanning the cognition directory: registry key → scan info. */
+export type CognitionDirScan = Map<string, CognitionFileScanInfo>;
+/**
+ * Result of a reconcile run.
+ *
+ * Describes every registry key's disposition after comparing on-disk cognition
+ * files against the stored registry.
+ */
+export interface ReconcileDiff {
+    /** Keys added to the registry (new cognition files with no prior entry). */
+    added: string[];
+    /** Keys removed from the registry (cognition file deleted). */
+    deleted: string[];
+    /** Summary counters. */
+    stats: {
+        totalScanned: number;
+        totalRegistryEntries: number;
+    };
+}
+/**
+ * Walk the cognition directory tree recursively and collect structured info for
+ * every source-paired cognition file.
+ *
+ * - Computes registry keys via `cognitionPathToKey`
+ * - Skips free-form markdown, non-`.md` files, and unreadable entries
+ * - Reads file content and computes a SHA256 content hash via `computeBlobHash`
+ *
+ * @param fs               Platform filesystem abstraction
+ * @param cognitionRootUri URI of the cognition root directory
+ * @returns Map of registry key → cognition file scan info
+ */
+export declare function scanCognitionDirectory(fs: FileSystem, cognitionRootUri: UriComponents): Promise<CognitionDirScan>;
+/**
+ * Full reconcile algorithm — the main entry point for Phase 3.
+ *
+ * 1. Compute `deleted` and `added` key sets
+ * 2. Apply operations to the registry:
+ *    - `delete(key)` — cognition file no longer exists
+ *    - `add(key, info)` — new cognition file discovered
+ * 3. Return a `ReconcileDiff` summarising the structural outcome
+ *
+ * @param registry   The in-memory registry (will be mutated and marked dirty)
+ * @param scanResult On-disk cognition file scan from `scanCognitionDirectory`
+ * @returns Diff describing what changed
+ */
+export declare function reconcileRegistry(registry: Registry, scanResult: CognitionDirScan): Promise<ReconcileDiff>;

package/dist/registry/sourceRelocation.d.ts

@@ -0,0 +1,11 @@
+import { Registry } from './index';
+export type RegistrySourceRelocation = {
+    kind: 'exact';
+    fromSourcePath: string;
+    toSourcePath: string;
+} | {
+    kind: 'prefix';
+    fromSourcePath: string;
+    toSourcePath: string;
+};
+export declare function applyRegistrySourceRelocations(registry: Registry, relocations: readonly RegistrySourceRelocation[], source?: string): boolean;

package/dist/registryTypes.d.ts

@@ -0,0 +1,52 @@
+import type { ContentIdentity } from './hash';
+export interface AcceptedPair {
+    source: ContentIdentity;
+    cognition: ContentIdentity;
+}
+/**
+ * A single cognition-keyed record in .coggit/registry.json.
+ *
+ * Path anchors are specified in the registry path contract spec.
+ */
+export interface PathKeyRecord {
+    /**
+     * Bound source file or folder path, relative to the CogGit project root
+     * (the directory containing .coggit/). This is registry storage, aligned
+     * with the project-root-relative coordinate used by tool-facing operation
+     * DTOs.
+     */
+    sourcePath: string | null;
+    /** Cognition type, matching config template definition. */
+    type: 'leaf' | 'folder';
+    /** ISO datetime of entry creation. @deprecated Removed from schema v6; retained only for old in-memory callers. */
+    createdAt?: string | null;
+    /** Accepted source/cognition provenance relationship. */
+    accepted?: AcceptedPair | null;
+    /** @deprecated Removed from schema v5; retained only for old in-memory callers. */
+    sourceFactMtimeMs?: number | null;
+    /** @deprecated Removed from schema v5; retained only for old in-memory callers. */
+    cognitionMtimeMs?: number | null;
+    /** @deprecated Removed from schema v5; retained only for old in-memory callers. */
+    verificationTimeMs?: number | null;
+    /** @deprecated Removed from schema v5; retained only for old in-memory callers. */
+    sourceFactHash?: string | null;
+    /** @deprecated Removed from schema v6; retained only for legacy in-memory compatibility. */
+    cognitionBlobHash?: string | null;
+    /** @deprecated Removed from schema v6; retained only for legacy in-memory compatibility. */
+    cognitionLength?: number | null;
+}
+/** The on-disk registry file shape. */
+export interface RegistryFile {
+    schemaVersion: number;
+    /** Human-facing note for agents and contributors inspecting this generated metadata. */
+    maintenanceNotice?: string;
+    /** Map from cognition registry key to persisted source/cognition metadata. */
+    entries: Record<string, PathKeyRecord>;
+}
+/** Optional provider that core can use to read/write registry data. */
+export interface RegistryProvider {
+    /** Load the full registry file. Returns null if no file exists or recovery failed. */
+    load(): Promise<RegistryFile | null>;
+    /** Atomically save the full registry file. */
+    save(file: RegistryFile): Promise<void>;
+}

package/dist/routesProjection.d.ts

@@ -0,0 +1,65 @@
+import type { CognitionRoutesEntry, RoutesProjectionNode } from './types.js';
+import type { UriComponents } from './interfaces.js';
+export declare const DEFAULT_ROUTES_DEPTH = 2;
+export interface RouteProjectionLine {
+    path: string;
+    cognition?: string;
+    description?: string;
+    truncated?: boolean;
+    omittedChildrenCount?: number;
+}
+export interface RoutesSourcePathContext {
+    sourceRoot?: string;
+    projectRootUri?: UriComponents;
+    sourceRootUri?: UriComponents;
+}
+export interface RoutesSourcePathSelection {
+    normalizedSourcePath?: string;
+    nodes: RoutesProjectionNode[];
+    missed: boolean;
+    pathHints: string[];
+}
+export declare function projectRoutesEntries(entries: readonly CognitionRoutesEntry[]): RoutesProjectionNode[];
+export declare function flattenRoutesProjection(nodes: readonly RoutesProjectionNode[]): RouteProjectionLine[];
+export declare function routeProjectionLineText(route: RouteProjectionLine): string;
+export declare function selectRoutesBySourcePath(tree: readonly RoutesProjectionNode[], sourcePath?: string, _context?: RoutesSourcePathContext): RoutesSourcePathSelection;
+export declare function suggestRoutePathHints(tree: readonly RoutesProjectionNode[], sourcePath: string, _sourceRoot?: string): string[];
+export declare function applyRoutesFilters(tree: readonly RoutesProjectionNode[], sourcePath?: string, _sourceRoot?: string): RoutesProjectionNode[];
+export type RoutesPresentationFormat = 'flat' | 'tree';
+export interface RoutesPresentationContent {
+    project: {
+        sourceRoot: string;
+        cognitionRoot: string;
+    };
+    depth: number;
+    format: RoutesPresentationFormat;
+    sourcePath?: string;
+    pathMissMessage?: string;
+    pathHintMessage?: string;
+    pathHints?: string[];
+    routes?: string[];
+    tree?: RoutesProjectionNode[];
+}
+export interface AssembleRoutesContentOptions {
+    sourcePath?: string;
+    depth?: number;
+    format?: RoutesPresentationFormat;
+    projectRootUri?: UriComponents;
+    sourceRootUri?: UriComponents;
+}
+/**
+ * Consumer-agnostic routes presentation pipeline:
+ * entries → tree → sourcePath selection → depth truncation → content assembly.
+ */
+export declare function assembleRoutesContent(input: {
+    entries: readonly CognitionRoutesEntry[];
+    project: {
+        sourceRoot: string;
+        cognitionRoot: string;
+    };
+}, options?: AssembleRoutesContentOptions): RoutesPresentationContent;
+/** Structured output shape: RoutesPresentationContent minus the presentation-only `format` field. */
+export type RoutesStructuredOutput = Omit<RoutesPresentationContent, 'format'>;
+/** Strip presentation-only fields, yielding the consumer-facing structured payload. */
+export declare function toRoutesStructuredOutput(content: RoutesPresentationContent): RoutesStructuredOutput;
+export declare function countRouteNodes(nodes: readonly RoutesProjectionNode[]): number;

package/dist/snapshot/index.d.ts

@@ -0,0 +1,3 @@
+export type { BuildProjectSnapshotOptions } from './tree';
+export { buildProjectSnapshot, buildRootNode, buildDirectoryChildren, buildFolderNode, buildFileNode, computeFolderFingerprint, folderSourceKey, } from './tree';
+export { buildMappingIndex } from './mappingIndex';

package/dist/snapshot/mappingIndex.d.ts

@@ -0,0 +1,2 @@
+import type { CoggitTreeNode, MappingIndex } from '../types';
+export declare function buildMappingIndex(nodes: CoggitTreeNode[]): MappingIndex;

package/dist/snapshot/tree.d.ts

@@ -0,0 +1,15 @@
+import type { CoggitSnapshot, CoggitTreeNode, CoggitWorkspaceRoot } from '../types';
+import type { AcceptanceStore, FileSystem, FreshnessEvidenceStore, UriComponents } from '../interfaces';
+import { loadGitignoreRules } from '../gitignore';
+export interface BuildProjectSnapshotOptions {
+    acceptance?: AcceptanceStore | null;
+    /** @deprecated v3 test adapter; ignored by the v5 acceptance model. */
+    freshnessEvidence?: FreshnessEvidenceStore | null;
+}
+export declare function computeFolderFingerprint(children: CoggitTreeNode[]): string;
+export declare function folderSourceKey(relativePath: string): string;
+export declare function buildProjectSnapshot(root: CoggitWorkspaceRoot, fs: FileSystem, options?: BuildProjectSnapshotOptions): Promise<CoggitSnapshot>;
+export declare function buildRootNode(root: CoggitWorkspaceRoot, fs: FileSystem, options?: BuildProjectSnapshotOptions): Promise<CoggitTreeNode>;
+export declare function buildDirectoryChildren(parent: CoggitTreeNode, directoryUri: UriComponents, sourceRootUri: UriComponents, inheritedIgnoreRules: Parameters<typeof loadGitignoreRules>[2], fs: FileSystem, options?: BuildProjectSnapshotOptions): Promise<CoggitTreeNode[]>;
+export declare function buildFolderNode(parent: CoggitTreeNode, folderUri: UriComponents, sourceRootUri: UriComponents, inheritedIgnoreRules: Parameters<typeof loadGitignoreRules>[2], fs: FileSystem, options?: BuildProjectSnapshotOptions): Promise<CoggitTreeNode>;
+export declare function buildFileNode(parent: CoggitTreeNode, fileUri: UriComponents, sourceRootUri: UriComponents, fs: FileSystem, options?: BuildProjectSnapshotOptions): Promise<CoggitTreeNode>;

package/dist/snapshotTypes.d.ts

@@ -0,0 +1,133 @@
+import type { UriComponents, UriKey, WorkspaceFolderInfo } from './interfaces';
+import type { NodeStatusResult, ObservedStatus } from './status/statusTypes';
+export type SourceCandidateState = 'some-exist' | 'all-missing' | 'ambiguous' | 'unchecked';
+export interface CognitionDiscoveryEntry {
+    registryKey: string;
+    type: 'leaf' | 'folder';
+    cognitionPath: string;
+    cognitionUri: UriComponents;
+    sourceCandidateUris: UriComponents[];
+    sourceCandidateState?: SourceCandidateState;
+}
+export interface MisplacedCognitionEntry {
+    registryKey: string;
+    type: 'leaf' | 'folder';
+    sourcePath: string;
+    sourceUri: UriComponents;
+    actualCognitionPath: string;
+    actualCognitionUri: UriComponents;
+    expectedCognitionPath: string;
+    expectedCognitionUri: UriComponents;
+}
+export interface OrphanedCognitionEntry {
+    registryKey: string;
+    type: 'leaf' | 'folder';
+    sourcePath: string;
+    sourceUri: UriComponents;
+    cognitionPath: string;
+    cognitionUri: UriComponents;
+}
+export interface StrayCognitionEntry extends CognitionDiscoveryEntry {
+}
+export interface UnboundCognitionEntry extends CognitionDiscoveryEntry {
+}
+export type MaintenanceDiagnostic = {
+    kind: 'orphaned';
+    entry: OrphanedCognitionEntry;
+} | {
+    kind: 'misplaced';
+    entry: MisplacedCognitionEntry;
+} | {
+    kind: 'stray';
+    entry: StrayCognitionEntry;
+} | {
+    kind: 'unbound';
+    entry: UnboundCognitionEntry;
+};
+export type CoggitNodeKind = 'root' | 'folder' | 'file' | 'error';
+export interface MappingIndex {
+    /** Canonical URI identity key. */
+    sourceToCognition: Map<UriKey, UriKey[]>;
+    /** Canonical URI identity key. */
+    cognitionToSource: Map<UriKey, UriKey>;
+    structuralEdges: Array<{
+        from: string;
+        to: string;
+        kind: 'parent' | 'child' | 'sibling';
+    }>;
+    semanticEdges: Array<{
+        from: string;
+        to: string;
+        kind: 'link' | 'backlink';
+    }>;
+}
+export interface AffectedResult {
+    pairs: Array<{
+        sourcePath: string;
+        cognitionPath: string;
+        reason: 'direct' | 'structural' | 'semantic';
+    }>;
+    stats: {
+        direct: number;
+        structural: number;
+        semantic: number;
+        total: number;
+    };
+}
+export interface CoggitWorkspaceRoot {
+    id: string;
+    label: string;
+    workspaceFolder: WorkspaceFolderInfo;
+    configUri: UriComponents;
+    projectRootUri: UriComponents;
+    sourceRootUri: UriComponents;
+    cognitionRootUri: UriComponents;
+    error?: string;
+}
+export interface CoggitTreeNode {
+    id: string;
+    kind: CoggitNodeKind;
+    label: string;
+    resourceUri: UriComponents;
+    sourceUri: UriComponents;
+    cognitionUri?: UriComponents;
+    relativePath: string;
+    /** Own cognition/projection status for this node only, before descendant aggregation. */
+    ownStatus?: NodeStatusResult;
+    /** Aggregated status for this node plus descendants. */
+    status?: NodeStatusResult;
+    contextValue: string;
+    parent?: CoggitTreeNode;
+    children?: CoggitTreeNode[];
+    description?: string;
+    tooltip?: string;
+    root: CoggitWorkspaceRoot;
+    representativeMtimeMs?: number;
+}
+export interface CoggitSnapshot {
+    roots: CoggitTreeNode[];
+    allNodes: CoggitTreeNode[];
+    nodeById: Map<string, CoggitTreeNode>;
+    nodeBySourceUri: Map<string, CoggitTreeNode>;
+    /** Mapping index used for incremental affected-path calculation. */
+    mappingIndex?: MappingIndex;
+}
+/**
+ * Plain-data projection node. Absent optional fields are omitted keys,
+ * never own properties with `undefined` values.
+ */
+export interface TreeProjectionNode {
+    path: string;
+    label: string;
+    kind: CoggitNodeKind;
+    cognition?: string;
+    description?: string;
+    observedStatus?: ObservedStatus | null;
+    ownObservedStatus?: ObservedStatus | null;
+    tracked?: boolean;
+    children?: TreeProjectionNode[];
+}
+export interface CoggitConfig {
+    sourceRoot: string;
+    cognitionRoot: string;
+}

package/dist/sourceStructureIgnore.d.ts

@@ -0,0 +1,4 @@
+export declare const GENERATED_SOURCE_STRUCTURE_DIRECTORY_NAMES: readonly [".cache", ".git", ".mypy_cache", ".next", ".nox", ".nuxt", ".parcel-cache", ".pytest_cache", ".ruff_cache", ".svelte-kit", ".tox", ".turbo", ".vite", ".vscode-test", "__pycache__", "build", "coverage", "dist", "lib", "node_modules", "out", "vendor"];
+export declare function isIgnoredSourceStructureEntry(name: string, isDirectory: boolean): boolean;
+export declare function generatedSourceStructureGlobExcludePatterns(): string[];
+export declare function generatedSourceStructureGlobExclude(): string;

package/dist/status/evidence.d.ts

@@ -0,0 +1,44 @@
+import type { CognitionFileInfo, CoverageSignals, Evidence, ObservedStatus, Reason, SourceFileInfo, StaleDegreeResult, StatusContext, StatusIssue } from '../types';
+/**
+ * Collects structured evidence between source and cognition.
+ * All check functions are pure for easy unit testing.
+ */
+export declare function collectEvidence(source: SourceFileInfo, cognition: CognitionFileInfo | null): Evidence;
+export declare function deriveStaleDegree(evidence: Evidence): StaleDegreeResult;
+/**
+ * Determines whether cognition content is only a skeleton template (no substantive analysis).
+ * Rule: pure headings, heading + empty lines only, or fewer than 3 effective content lines are treated as template.
+ */
+export declare function isTemplateContent(content: string | null): boolean;
+export declare function checkMtime(source: SourceFileInfo, cognition: CognitionFileInfo | null): Reason[];
+export declare function checkAcceptedPair(source: SourceFileInfo, cognition: CognitionFileInfo | null): Reason[];
+export declare function checkSymbols(source: SourceFileInfo, cognition: CognitionFileInfo | null, symbolIndex: StatusContext['symbolIndex']): Reason[];
+export declare function checkLinks(cognition: CognitionFileInfo | null, linkIndex: StatusContext['linkIndex']): Reason[];
+export declare function checkDeps(source: SourceFileInfo, depGraph: StatusContext['depGraph']): Reason[];
+export declare function checkSourceExistence(source: SourceFileInfo, cognition: CognitionFileInfo | null): Reason[];
+/**
+ * Single-source edit-work labels for stale pairs. The status inspection
+ * reuses these exact labels on its synthesized handbook-bearing sync action,
+ * so the issue action and the next-step action always dedup by label match.
+ */
+export declare const SYNC_COGNITION_ACTION_LABEL = "Sync cognition with source changes";
+export declare const SYNC_FOLDER_README_ACTION_LABEL = "Sync folder README with child structure changes";
+export declare function actionLabelsFromIssues(issues: Iterable<StatusIssue> | undefined): string[];
+/**
+ * Synthesizes the final 8-state from reasons.
+ * Uses a deterministic decision tree (not a weighted model) — see DECISIONS documentation.
+ */
+export declare function synthesizeStatus(reasons: Reason[], evidence: Evidence): {
+    observedStatus: ObservedStatus | undefined;
+    ownObservedStatus: ObservedStatus | undefined;
+    issues: StatusIssue[];
+    coverage: CoverageSignals;
+};
+/**
+ * Derives recommended actions based on status and reasons.
+ */
+export declare function deriveActions(synthesized: {
+    observedStatus: ObservedStatus | undefined;
+    issues: StatusIssue[];
+    coverage: CoverageSignals;
+}, _reasons: Reason[]): string[];

package/dist/status/index.d.ts

@@ -0,0 +1,89 @@
+import type { CoggitTreeNode, CognitionFileInfo, LocatedStatusIssue, NodeStatusInspection, NodeStatusResult, ObservedStatus, SourceFileInfo, StatusContext, StatusResult, SubtreeIssueQueryResult, SourceFactKind, StatusIssueVisibility } from '../types';
+import type { AcceptedPair } from '../registryTypes';
+export { isTemplateContent } from './evidence';
+export declare function projectStatusResultToNodeStatus(status: StatusResult): NodeStatusResult;
+/**
+ * Quick mtime-based observed status check.
+ * Returns undefined (no observation possible) when cognition doesn't exist.
+ */
+export declare function computeMtimeObservedStatus(sourceMtimeMs: number | undefined, cognitionMtimeMs: number | undefined): ObservedStatus | undefined;
+/**
+ * Combine observed statuses by severity: `conflict` > `stale` > `fresh`. Returns
+ * the worst (highest-priority) observed status, or `undefined` when none are
+ * observed. This is the single place that defines the aggregation ordering used
+ * by `NodeStatusInspection.status` / `StatusOperationResult.status`.
+ */
+export declare function combineObservedStatus(statuses: Iterable<ObservedStatus | undefined>): ObservedStatus | undefined;
+export interface AggregateNodeStatusInput {
+    ownStatus?: NodeStatusResult;
+    descendantStatuses?: Iterable<NodeStatusResult | undefined>;
+}
+/**
+ * Aggregate own and descendant status for a node.
+ *
+ * - `observedStatus` (whole-node): worst of own + descendant by `fresh` <
+ *   `stale` < `conflict`.
+ * - `descendantObservedStatus`: same worst-of over descendants with an observed
+ *   status (the tracked node-status subset; untracked descendants are skipped).
+ * - `ownObservedStatus`: the node's own status, before descendant aggregation.
+ */
+export declare function aggregateNodeStatus(input: AggregateNodeStatusInput): NodeStatusResult;
+export declare function collectSubtreeIssues(node: CoggitTreeNode): LocatedStatusIssue[];
+export declare function querySubtreeIssues(node: CoggitTreeNode): SubtreeIssueQueryResult;
+export declare function countSubtreeIssues(node: CoggitTreeNode): number;
+export declare function projectStatusIssues(issues: SubtreeIssueQueryResult, visibility?: StatusIssueVisibility): SubtreeIssueQueryResult;
+export interface InspectNodeStatusInput {
+    node: CoggitTreeNode;
+    sourcePath: string;
+    cognitionPath: string | null;
+    handbookId: 'leaf' | 'skeleton' | null;
+    issueVisibility?: StatusIssueVisibility;
+}
+export declare function inspectNodeStatus(input: InspectNodeStatusInput): NodeStatusInspection;
+/**
+ * Full 8-state status determination — synthesized from the evidence chain.
+ * Replaces the Python prototype's 4-state StatusValue (ok/risk/unknown/blocked).
+ */
+export declare function computeStatus(source: SourceFileInfo, cognition: CognitionFileInfo | null, context: StatusContext): StatusResult;
+/**
+ * Summarizes the most recent representativeMtime among child nodes.
+ */
+export declare function summarizeRepresentativeMtime(children: CoggitTreeNode[]): number | undefined;
+export interface RuntimeStatusInput {
+    sourceUri: string;
+    sourceContent: string;
+    sourceFactKind?: SourceFactKind;
+    sourceMtimeMs: number;
+    cognitionUri: string | null;
+    cognitionContent: string | null;
+    cognitionMtimeMs: number | null;
+    verificationTimeMs?: number | null;
+    acceptedPair?: AcceptedPair | null;
+    context?: Partial<StatusContext>;
+}
+export declare function computeRuntimeStatus(input: RuntimeStatusInput): StatusResult;
+/**
+ * Lightweight helper for callers that only have raw text and mtimes.
+ *
+ * This is not the full evidence pipeline: URI, verification metadata,
+ * symbols, links, and dependency context are intentionally unavailable here.
+ * Runtime code should prefer computeStatus() whenever those facts are known.
+ */
+export declare function computeStatusFromContent(sourceContent: string, cognitionContent: string | null, sourceMtimeMs: number, cognitionMtimeMs: number | null, context?: Partial<StatusContext>): ObservedStatus | undefined;
+/**
+ * Map an ObservedStatus to a human-readable label.
+ */
+export declare function describeObservedStatus(status: ObservedStatus | undefined): string | undefined;
+export declare const __testing__: {
+    computeRuntimeStatus: typeof computeRuntimeStatus;
+    computeMtimeObservedStatus: typeof computeMtimeObservedStatus;
+    computeStatusFromContent: typeof computeStatusFromContent;
+    combineObservedStatus: typeof combineObservedStatus;
+    aggregateNodeStatus: typeof aggregateNodeStatus;
+    collectSubtreeIssues: typeof collectSubtreeIssues;
+    querySubtreeIssues: typeof querySubtreeIssues;
+    countSubtreeIssues: typeof countSubtreeIssues;
+    projectStatusIssues: typeof projectStatusIssues;
+    summarizeRepresentativeMtime: typeof summarizeRepresentativeMtime;
+    inspectNodeStatus: typeof inspectNodeStatus;
+};

package/dist/status/lookupCognition.d.ts

@@ -0,0 +1,23 @@
+import type { StatusOperationResult } from '../operations';
+/**
+ * Hit payload for `tryGetCognitionPath`: the existing paired cognition path and
+ * whether that cognition is stale.
+ */
+export interface CognitionLookupHit {
+    cognitionPath: string;
+    stale: boolean;
+}
+/**
+ * Project a `statusOperation` result down to the lookup question: does this
+ * source path have an existing paired cognition file, and where is it?
+ *
+ * Returns `null` when there is no existing paired cognition — a source miss, a
+ * matched node with no cognition yet, and a not-applicable node all collapse to
+ * `null`. On a hit, `stale` is `true` only when the node's own cognition is
+ * stale; `conflict` and descendant status do not set it.
+ *
+ * This is a pure projection over `StatusOperationResult`: it re-encodes fields
+ * `statusOperation` already computed and performs no path resolution, path
+ * mapping, or presence detection of its own.
+ */
+export declare function tryGetCognitionPath(statusResult: StatusOperationResult): CognitionLookupHit | null;