@coggit/core 0.2.0

package/dist/layout.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem } from './interfaces';
+import type { CoggitWorkspaceRoot, MisplacedCognitionEntry, PathKeyRecord } from './types';
+export declare function detectMisplacedCognitionEntries(root: CoggitWorkspaceRoot, fs: FileSystem, entries: Record<string, PathKeyRecord>): Promise<MisplacedCognitionEntry[]>;

package/dist/locks.d.ts

@@ -0,0 +1,44 @@
+import type { UriComponents } from './interfaces';
+export interface ProjectLockContext {
+    readonly owner: 'vscode' | 'mcp' | 'cli' | 'daemon' | string;
+    readonly operation: string;
+    readonly projectLabel?: string;
+}
+/**
+ * Host-neutral coordinator for serializing protected project write sessions.
+ *
+ * Implementations are NOT reentrant: calling `withWriteLock` from within `fn`
+ * on the same project root will block until the outer lock is released, causing
+ * a deadlock or bounded-timeout error. Callers must not nest lock acquisitions.
+ */
+export interface ProjectLockManager {
+    withWriteLock<T>(projectRoot: UriComponents, context: ProjectLockContext, fn: () => Promise<T>): Promise<T>;
+}
+export declare class ProjectLockError extends Error {
+    readonly code: string;
+    readonly context?: ProjectLockContext | undefined;
+    constructor(message: string, code: string, context?: ProjectLockContext | undefined);
+}
+export declare const noOpProjectLockManager: ProjectLockManager;
+/** A held watch lease. Renew keeps the lease from going stale; release ends it. */
+export interface WatchLeaseHandle {
+    renew(): Promise<void>;
+    release(): Promise<void>;
+}
+/**
+ * Host-neutral coordinator for single-writer watcher leases.
+ *
+ * Unlike `ProjectLockManager`, acquisition never blocks: a caller either
+ * becomes the sole holder immediately or backs off to reconcile-on-read.
+ */
+export interface WatchLeaseManager {
+    /**
+     * Non-blocking try-acquire. Returns null when a live holder exists (the
+     * caller declines watching and falls back to reconcile-on-read). Never waits.
+     */
+    tryAcquireWatchLease(projectRoot: UriComponents, context: ProjectLockContext): Promise<WatchLeaseHandle | null>;
+}
+export declare class WatchLeaseError extends ProjectLockError {
+    constructor(message: string, code: string, context?: ProjectLockContext);
+}
+export declare const noOpWatchLeaseManager: WatchLeaseManager;

package/dist/logger.d.ts

@@ -0,0 +1,17 @@
+export type CoggitLogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface CoggitLogEvent {
+    level: CoggitLogLevel;
+    category: string;
+    message: string;
+    data?: Record<string, unknown>;
+}
+export interface CoggitLogger {
+    log(event: CoggitLogEvent): void;
+}
+export declare const nullCoggitLogger: CoggitLogger;
+export declare function logEvent(logger: CoggitLogger | undefined, level: CoggitLogLevel, category: string, message: string, data?: Record<string, unknown>): void;
+export declare function debugLog(logger: CoggitLogger | undefined, category: string, message: string, data?: Record<string, unknown>): void;
+export declare function infoLog(logger: CoggitLogger | undefined, category: string, message: string, data?: Record<string, unknown>): void;
+export declare function warnLog(logger: CoggitLogger | undefined, category: string, message: string, data?: Record<string, unknown>): void;
+export declare function errorLog(logger: CoggitLogger | undefined, category: string, message: string, data?: Record<string, unknown>): void;
+export declare function createEnvCoggitLogger(prefix?: string): CoggitLogger;

package/dist/maintenance.d.ts

@@ -0,0 +1,7 @@
+import type { FileSystem } from './interfaces';
+import { type CognitionDiscovery } from './cognitionDiscovery';
+import type { CoggitWorkspaceRoot, OrphanedCognitionEntry, PathKeyRecord, StrayCognitionEntry, UnboundCognitionEntry } from './types';
+export { detectMisplacedCognitionEntries } from './layout';
+export declare function detectOrphanedCognitionEntries(root: CoggitWorkspaceRoot, fs: FileSystem, entries: Record<string, PathKeyRecord>): Promise<OrphanedCognitionEntry[]>;
+export declare function detectStrayCognitionEntries(root: CoggitWorkspaceRoot, fs: FileSystem, entries: Record<string, PathKeyRecord>, discovery?: CognitionDiscovery): Promise<StrayCognitionEntry[]>;
+export declare function detectUnboundCognitionEntries(root: CoggitWorkspaceRoot, fs: FileSystem, entries: Record<string, PathKeyRecord>, discovery?: CognitionDiscovery): Promise<UnboundCognitionEntry[]>;

package/dist/maintenancePresentation.d.ts

@@ -0,0 +1,16 @@
+import type { MaintenanceDiagnostic } from './types';
+export type MaintenancePresentationFormat = 'text' | 'markdown';
+export type MaintenanceIssueCode = 'tracked-source-missing' | 'cognition-path-out-of-sync' | 'unregistered-cognition' | 'unbound-cognition' | 'missing-source-candidate';
+export interface MaintenancePresentationItem {
+    kind: MaintenanceDiagnostic['kind'];
+    issueCode: MaintenanceIssueCode;
+    severity: 'warning';
+    path: string;
+    message: string;
+    hint: string;
+}
+export interface MaintenancePresentationView {
+    items: MaintenancePresentationItem[];
+}
+export declare function projectMaintenancePresentation(diagnostics: readonly MaintenanceDiagnostic[]): MaintenancePresentationView;
+export declare function renderMaintenancePresentation(view: MaintenancePresentationView, format?: MaintenancePresentationFormat): string;

package/dist/mapping.d.ts

@@ -0,0 +1,98 @@
+import type { UriComponents } from './interfaces';
+import type { CoggitConfig, CoggitWorkspaceRoot } from './types';
+/**
+ * Path and URI mapping helpers.
+ *
+ * String helpers are kept for pure path tests and file-scheme callers. URI helpers
+ * are the production API for workspace roots and cognition targets so remote, WSL,
+ * and dev-container schemes are preserved end-to-end.
+ */
+/**
+ * Derive the project root path from a config.yaml path.
+ * Convention: .coggit/config.yaml → project root is the parent of .coggit/.
+ */
+export declare function getProjectRootPath(configPath: string): string;
+/**
+ * Resolve sourceRoot / cognitionRoot from a config URI without converting through
+ * fsPath → path.resolve → Uri.file. This preserves the original URI scheme.
+ */
+export declare function resolveConfigRoots(configUri: UriComponents, config: CoggitConfig): {
+    projectRootUri: UriComponents;
+    sourceRootUri: UriComponents;
+    cognitionRootUri: UriComponents;
+};
+/**
+ * Resolve sourceRoot / cognitionRoot as file-system paths.
+ * Prefer resolveConfigRoots() in VS Code-facing code.
+ */
+export declare function resolveConfigRootPaths(configPath: string, config: CoggitConfig): {
+    projectRoot: string;
+    sourceRoot: string;
+    cognitionRoot: string;
+};
+export declare function resolvePath(basePath: string, targetPath: string): string;
+/**
+ * sourcePath relative to sourceRoot, normalized to / separators.
+ */
+export declare function toRelativePath(sourceRootPath: string, sourcePath: string): string;
+export declare function toRelativeUriPath(rootUri: UriComponents, uri: UriComponents): string;
+/**
+ * Normalize an operation `sourcePath` input to a source identity.
+ *
+ * The operation-DTO input surface is project-root-relative; this is the single
+ * place that strips the configured `sourceRoot` prefix back to the
+ * source-root-relative identity used for tree matching. Non-prefixed paths pass
+ * through unchanged as the legacy source-root-relative fallback.
+ */
+export declare function normalizeSourcePathInput(sourcePath: string, context?: {
+    sourceRoot?: string;
+    projectRootUri?: UriComponents;
+    sourceRootUri?: UriComponents;
+}): string;
+/**
+ * The single source↔cognition pairing convention. Written once here and reused
+ * by key derivation (`identity.ts`), URI mapping (below), and reverse inference.
+ *
+ * - Leaf:      `sourceIdentity + ".md"`
+ * - Skeleton:  `sourceIdentity + "/README.md"` (root `.` → `README.md`)
+ */
+export type CognitionIdentityKind = 'leaf' | 'folder';
+export declare function sourceIdentityToCognitionIdentity(sourceIdentity: string, kind: CognitionIdentityKind): string;
+/**
+ * Reverse of {@link sourceIdentityToCognitionIdentity}. Returns `undefined` for
+ * free-form cognition documents (e.g. `CODE_MAP.md`) that have no source-pairing
+ * convention.
+ */
+export declare function cognitionIdentityToSourceIdentity(cognitionIdentity: string): {
+    sourceIdentity: string;
+    kind: CognitionIdentityKind;
+} | undefined;
+/**
+ * source file → cognition markdown file path.
+ * Example: src/foo/bar.ts → src_cognition/foo/bar.ts.md
+ */
+export declare function toCognitionFilePath(sourceRootPath: string, cognitionRootPath: string, sourceFilePath: string): string;
+export declare function toCognitionFileUri(sourceRootUri: UriComponents, cognitionRootUri: UriComponents, sourceFileUri: UriComponents): UriComponents;
+/**
+ * source folder → cognition README path.
+ * Example: src/foo → src_cognition/foo/README.md
+ */
+export declare function toCognitionFolderReadmePath(sourceRootPath: string, cognitionRootPath: string, folderPath: string): string;
+export declare function toCognitionFolderReadmeUri(sourceRootUri: UriComponents, cognitionRootUri: UriComponents, folderUri: UriComponents): UriComponents;
+export declare function inferSourceUriFromCognitionUri(cognitionUri: UriComponents, sourceRootUri: UriComponents, cognitionRootUri: UriComponents): UriComponents | undefined;
+export declare function inferSourceUriCandidatesFromCognitionUri(cognitionUri: UriComponents, sourceRootUri: UriComponents, cognitionRootUri: UriComponents): UriComponents[];
+/**
+ * Convert a source-root-relative identity to a project-root-relative path by
+ * prepending the configured `sourceRoot` name (skipped when the root is `.`).
+ */
+export declare function sourceIdentityToProjectRelative(root: CoggitWorkspaceRoot, sourceIdentity: string): string;
+export declare function cognitionIdentityToProjectRelative(root: CoggitWorkspaceRoot, cognitionIdentity: string): string;
+/**
+ * Convert a project-root-relative path back to a source identity by stripping
+ * the configured `sourceRoot` name. Non-prefixed paths pass through unchanged
+ * (the legacy source-root-relative fallback).
+ */
+export declare function projectRelativeToSourceIdentity(root: CoggitWorkspaceRoot, projectRelative: string): string;
+export declare function getParentDir(filePath: string): string;
+export declare function isWithin(parentPath: string, childPath: string): boolean;
+export declare function basename(filePath: string): string;

package/dist/operationTypes.d.ts

@@ -0,0 +1,45 @@
+export type SnapshotOperationScope = 'tracked' | 'untracked' | 'issues' | 'all';
+export interface CoggitProjectContext {
+    label: string;
+    configUri: string;
+    /**
+     * The consumer anchor: every project-root-relative path on the operation-DTO
+     * surface resolves against this URI. `sourceRootUri` / `cognitionRootUri`
+     * are internal and intentionally absent.
+     */
+    projectRootUri: string;
+    /** Project-root-relative source root path, e.g. "codebase" - mirrors config.yaml source_root. */
+    sourceRoot: string;
+    /** Project-root-relative cognition root path, e.g. "codebase_cognition" - mirrors config.yaml cognition_root. */
+    cognitionRoot: string;
+    sourcePathRule: string;
+}
+/**
+ * Surface-neutral operation vocabulary.
+ *
+ * Boundary rule for core hints: `suggestedActions` and any other next-step
+ * guidance emitted by core may only reference these operation ids and opaque
+ * asset ids (e.g. `handbookId`) — never adapter tool names, CLI command
+ * names, or resource URIs. Each adapter owns the mapping from an operation id
+ * to its own surface addressing (MCP maps to its `coggit_*` tools, the CLI
+ * maps to subcommands, and so on).
+ */
+export declare const CORE_OPERATION_IDS: readonly ["snapshot", "status", "add", "resolve", "routes"];
+export type CoreOperationId = typeof CORE_OPERATION_IDS[number];
+export interface CoggitOperationAction {
+    code: string;
+    label: string;
+    operation?: CoreOperationId;
+    /**
+     * Read-before-edit asset reference for authoring steps (e.g. the stale
+     * sync step). Same opaque id as the top-level `StatusOperationResult
+     * .handbookId`; adapters map it to their skill/resource address exactly as
+     * they map the top-level field. An action carrying `handbookId` is
+     * structured (adapter-mappable) even without an `operation`.
+     */
+    handbookId?: 'leaf' | 'skeleton';
+    /** Project-root-relative source path (the same coordinate as operation `sourcePath` inputs). */
+    sourcePath?: string;
+    scope?: SnapshotOperationScope;
+    maxDepth?: number;
+}

package/dist/operations.d.ts

@@ -0,0 +1,228 @@
+import type { AddCognitionKind, CognitionKind } from './cognition';
+import type { CoggitProject } from './interfaces';
+import type { CoggitSnapshot, CoggitTreeNode, CoggitNodeKind, CoggitOperationAction, CoggitProjectContext, LocatedStatusIssue, NodeStatusInspection, ObservedStatus, SnapshotOperationScope, StaleAction, StatusIssue, StatusIssueVisibility, CognitionRoutes, CognitionRoutesEntry, CognitionDocumentDiagnostic } from './types';
+export type { CoggitOperationAction, CoggitProjectContext, CoreOperationId, SnapshotOperationScope, } from './types';
+export { CORE_OPERATION_IDS } from './operationTypes';
+export interface CoggitHandbookCatalogEntry {
+    id: 'all' | CognitionKind;
+    nodeKind: CoggitNodeKind | null;
+    title: string;
+    kind: 'all' | CognitionKind;
+}
+export interface CoggitOperationIssue {
+    relativePath: string;
+    severity: 'info' | 'warning' | 'error';
+    code: StatusIssue['diagnostic']['code'] | 'path-not-found' | 'add-failed' | 'invalid-kind';
+    message: string;
+    actions: CoggitOperationAction[];
+}
+export interface SnapshotOperationResult {
+    scope: SnapshotOperationScope;
+    projectCount: number;
+    trackedCount: number;
+    untrackedCount: number;
+    issueCount: number;
+    nextScopes: SnapshotOperationScope[];
+    maxDepth: number | null;
+    truncated: boolean;
+    omittedChildrenCount: number;
+    suggestedActions: CoggitOperationAction[];
+    projects: CoggitProjectContext[];
+    sourcePath: string | null;
+    found: boolean;
+    snapshot: CoggitSnapshot | null;
+    node: CoggitTreeNode | null;
+    /** Fuzzy source-path hints when the source path matched no node. Empty when found. */
+    pathHints: string[];
+    /** Present only when the source path matched no node. */
+    pathMissMessage?: string;
+    /** Present only when a miss produced fuzzy hints. */
+    pathHintMessage?: string;
+}
+export interface StatusOperationResult {
+    found: boolean;
+    /** Project-root-relative source path: the matched node's relative path on a
+     *  hit, or the requested input on a miss. */
+    sourcePath: string;
+    /** Absolute source URI key string; `null` on a miss. */
+    sourceUri: string | null;
+    nodeKind: CoggitNodeKind | null;
+    /** `null` on a miss. */
+    project: CoggitProjectContext | null;
+    /**
+     * Expected paired cognition path, project-root-relative. `null` on a miss
+     * or when the node has no expected cognition URI. This is the *expected*
+     * target path, not an existence check — same semantics and null encoding as
+     * `LocatedStatusIssue.cognitionPath`.
+     */
+    cognitionPath: string | null;
+    /** Absolute cognition URI key string; `null` on a miss or when the node has
+     *  no expected cognition URI. */
+    cognitionUri: string | null;
+    /**
+     * Whole-node observed status: the worst of `ownStatus` and `descendantStatus`
+     * by `fresh` < `stale` < `conflict`. `null` means "no cognition" (neither the
+     * node nor any tracked descendant has an observed status).
+     */
+    status: ObservedStatus | null;
+    /**
+     * This node's own observed status, before descendant aggregation; `null`
+     * means "no own cognition".
+     */
+    ownStatus: ObservedStatus | null;
+    /**
+     * Worst observed status over descendants with an observed status (the
+     * tracked node-status subset) by `fresh` < `stale` < `conflict`. `null` means
+     * no descendant in that subset has an observed status (untracked descendants
+     * are skipped) — not "no cognition".
+     */
+    descendantStatus: ObservedStatus | null;
+    staleAction: StaleAction | null;
+    issueCount: number;
+    ownIssueCount: number;
+    descendantIssueCount: number;
+    issues: CoggitOperationIssue[];
+    suggestedActions: CoggitOperationAction[];
+    handbookId: 'leaf' | 'skeleton' | null;
+    /** `null` on a miss; the matched tree node on a hit. */
+    node: CoggitTreeNode | null;
+    /** Fuzzy source-path hints when the source path matched no node. Empty when found. */
+    pathHints: string[];
+    /** Present only when the source path matched no node. */
+    pathMissMessage?: string;
+    /** Present only when a miss produced fuzzy hints. */
+    pathHintMessage?: string;
+    /** Canonical status inspection when the node was found.
+     *  undefined when found is false. */
+    inspection?: NodeStatusInspection | undefined;
+}
+export declare const ADD_OPERATION_ERROR_CODES: readonly ["no-projects", "path-not-found", "invalid-kind", "mapping-conflict", "filesystem-failure", "unknown"];
+export type AddOperationErrorCode = typeof ADD_OPERATION_ERROR_CODES[number];
+export interface AddOperationError {
+    code: AddOperationErrorCode;
+    message: string;
+}
+export interface AddOperationResult {
+    success: boolean;
+    /** Whether the add materialized a new cognition file; `null` on failure. */
+    created: boolean | null;
+    /** Created cognition kind on success; `null` on failure. */
+    kind: CognitionKind | null;
+    /** Project-root-relative source path. */
+    sourcePath: string;
+    /** Absolute source URI key string; `null` on failure. */
+    sourceUri: string | null;
+    /** Expected paired cognition path, project-root-relative; `null` on
+     *  failure (no path materialized). */
+    cognitionPath: string | null;
+    /** Absolute cognition URI key string; `null` on failure. */
+    cognitionUri: string | null;
+    /** `null` on a miss or `no-projects`. */
+    project: CoggitProjectContext | null;
+    handbookId: 'leaf' | 'skeleton' | null;
+    suggestedActions: CoggitOperationAction[];
+    /** `null` on success; typed failure details on failure. */
+    error: AddOperationError | null;
+    /** Fuzzy source-path hints when the source path matched no node. Empty when found. */
+    pathHints: string[];
+    /** Present only when the source path matched no node. */
+    pathMissMessage?: string;
+    /** Present only when a miss produced fuzzy hints. */
+    pathHintMessage?: string;
+}
+/**
+ * Resolve failure codes.
+ *
+ * - `content-changed`: the source/cognition pair changed during the resolve
+ *   acceptance window. The guard compares the accepted-pair identity captured
+ *   before and after the accept write — the registry `sourceKey` plus the
+ *   `source` and `cognition` content identities (SHA-256 content hashes, not
+ *   mtimes) — covering both the source and cognition sides.
+ * - `registry-changed`: the registry revision changed during the accept write;
+ *   the acceptance was not committed.
+ * - `registry-unavailable`: no registry could be loaded.
+ * - `path-not-found`: the source path matched no node.
+ * - `no-projects`: no CogGit project is open.
+ * - `unknown`: any other failure.
+ */
+export declare const RESOLVE_ERROR_CODES: readonly ["no-projects", "path-not-found", "registry-unavailable", "registry-changed", "content-changed", "unknown"];
+export type ResolveErrorCode = typeof RESOLVE_ERROR_CODES[number];
+export interface ResolveOperationError {
+    code: ResolveErrorCode;
+    message: string;
+}
+export interface ResolveOperationResult {
+    success: boolean;
+    /** Project-root-relative source path. */
+    sourcePath: string;
+    /** Absolute source URI key string; `null` when the node could not be re-read. */
+    sourceUri: string | null;
+    /** Expected paired cognition path, project-root-relative; `null` when the
+     *  node could not be re-read after acceptance. */
+    cognitionPath: string | null;
+    /** Absolute cognition URI key string; `null` when the node could not be re-read. */
+    cognitionUri: string | null;
+    /** `null` on a miss or `no-projects`. */
+    project: CoggitProjectContext | null;
+    /** Registry key written on success; `null` on failure. */
+    sourceKey: string | null;
+    /** Acceptance timestamp written on success; `null` on failure. */
+    verificationTimeMs: number | null;
+    suggestedActions: CoggitOperationAction[];
+    /** `null` on success; typed failure details on failure. */
+    error: ResolveOperationError | null;
+    /** Fuzzy source-path hints when the source path matched no node. Empty when found. */
+    pathHints: string[];
+    /** Present only when the source path matched no node. */
+    pathMissMessage?: string;
+    /** Present only when a miss produced fuzzy hints. */
+    pathHintMessage?: string;
+}
+export interface RoutesOperationResult {
+    project: CoggitProjectContext;
+    generatedAt: number;
+    entryCount: number;
+    entries: CognitionRoutesEntry[];
+    diagnostics: CognitionDocumentDiagnostic[];
+    routes: CognitionRoutes;
+}
+export declare function projectContext(project: CoggitProject): CoggitProjectContext;
+export declare function handbookCatalog(): CoggitHandbookCatalogEntry[];
+export declare function handbookIdForNodeKind(kind: CoggitNodeKind): 'leaf' | 'skeleton';
+export declare function handbookIdForCognitionKind(kind: CognitionKind): 'leaf' | 'skeleton';
+export declare function findProjectNode(projects: readonly CoggitProject[], sourcePath: string): Promise<{
+    project: CoggitProject;
+    node: CoggitTreeNode;
+} | undefined>;
+/** Expand a raw input path into candidate source-root-relative paths to try, per project. */
+export type SourcePathCandidatesExpander = (project: CoggitProject, sourcePath: string) => readonly string[];
+export interface SnapshotOperationOptions {
+    sourcePath?: string;
+    scope?: SnapshotOperationScope;
+    maxDepth?: number;
+    sourcePathCandidates?: SourcePathCandidatesExpander;
+}
+export declare function snapshotOperation(projects: readonly CoggitProject[], options?: SnapshotOperationOptions): Promise<SnapshotOperationResult>;
+export interface StatusOperationOptions {
+    sourcePathCandidates?: SourcePathCandidatesExpander;
+    issueVisibility?: StatusIssueVisibility;
+    /**
+     * Optional pre-built combined snapshot (from `buildSnapshotFromProjects`).
+     * When provided, `statusOperation` resolves `sourcePath` against it instead
+     * of rebuilding the tree per project. The caller owns snapshot freshness:
+     * pass a snapshot built in the same turn as the mutation that precedes it;
+     * do not reuse a snapshot across writes (reconcile-on-read semantics).
+     */
+    snapshot?: CoggitSnapshot;
+}
+export declare function statusOperation(projects: readonly CoggitProject[], sourcePath: string, options?: StatusOperationOptions): Promise<StatusOperationResult>;
+export declare function addOperation(projects: readonly CoggitProject[], sourcePath: string, options?: {
+    kind?: AddCognitionKind;
+    overwrite?: boolean;
+    sourcePathCandidates?: SourcePathCandidatesExpander;
+}): Promise<AddOperationResult>;
+export declare function resolveOperation(projects: readonly CoggitProject[], sourcePath: string, options?: {
+    sourcePathCandidates?: SourcePathCandidatesExpander;
+}): Promise<ResolveOperationResult>;
+export declare function routesOperation(project: CoggitProject, options?: Parameters<CoggitProject['buildCognitionRoutes']>[0]): Promise<RoutesOperationResult>;
+export declare function operationIssue(located: LocatedStatusIssue): CoggitOperationIssue;

package/dist/path-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pure-JS path utilities — no Node.js dependency.
+ * Replaces `node:path` in core for cross-platform compatibility.
+ *
+ * Implements only the subset of `node:path` used by core/mapping.ts.
+ */
+export declare function isAbsolute(p: string): boolean;
+export declare function dirname(p: string): string;
+export declare function basename(p: string): string;
+export declare function normalize(p: string): string;
+export declare function resolve(...segments: string[]): string;
+export declare function relative(from: string, to: string): string;
+export declare function join(...segments: string[]): string;
+export declare const posix: {
+    isAbsolute(p: string): boolean;
+    parse(p: string): {
+        dir: string;
+        name: string;
+        ext: string;
+    };
+    join(...segments: string[]): string;
+    normalize(p: string): string;
+};
+export declare const win32: {
+    isAbsolute(p: string): boolean;
+};

package/dist/pathHints.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Fuzzy source-path hint suggestions, shared by routes, status, and snapshot.
+ *
+ * When a source path matches nothing, segment-suffix matching suggests the
+ * closest existing source paths. A miss like `src/core/watchPipeline.ts` can
+ * suggest the source-root-relative path `coggit/src/core/watchPipeline.ts`
+ * because their trailing segments match.
+ *
+ * Hints are suggestions for caller re-decision, never automatic rewrites:
+ * the caller chooses whether to re-run against a suggested path.
+ */
+/**
+ * Collect up to five candidate paths whose trailing segments match the
+ * source path. Returns an empty array when nothing matches.
+ */
+export declare function suggestPathHints(candidatePaths: Iterable<string>, sourcePath: string): string[];
+/** Canonical bare sentence (no path) for a source path that matched no node. */
+export declare const PATH_MISS_MESSAGE = "Path not found in any CogGit project.";
+/** Canonical lead-in for the fuzzy-hint suggestion line. */
+export declare const PATH_HINT_MESSAGE = "You may mean one of these source-root-relative source paths.";
+/** Full miss line including the source path, e.g. `Path not found in any CogGit project: src/main.ts`. */
+export declare function pathMissMessage(sourcePath: string): string;
+/** Render the backtick-wrapped hint list: `` `a`, `b` ``. */
+export declare function pathHintsTryText(pathHints: readonly string[]): string;
+/** Render the full miss line plus optional hint suggestion lines. */
+export declare function renderPathMissText(result: {
+    sourcePath: string | null;
+    pathMissMessage?: string;
+    pathHintMessage?: string;
+    pathHints: readonly string[];
+}): string;

package/dist/project/buildSnapshot.d.ts

@@ -0,0 +1,10 @@
+import type { CoggitSnapshot } from '../types';
+import type { ConfigProvider, FileSystem } from '../interfaces';
+/**
+ * One-shot reconcile-on-read snapshot for a bare fs+config consumer.
+ *
+ * This is the minimal public entry point for a runtime that owns its own
+ * `FileSystem` and `ConfigProvider` adapters but does not need the full
+ * `CoggitProject` facade lifecycle.
+ */
+export declare function buildSnapshot(fs: FileSystem, config: ConfigProvider): Promise<CoggitSnapshot>;

package/dist/project/discover.d.ts

@@ -0,0 +1,32 @@
+import type { FileSystem, UriComponents } from '../interfaces';
+/**
+ * Result of a successful `findProjectRoot` call.
+ *
+ * `configUri` points to the `.coggit/config.yaml` that was found.
+ * `projectRootUri` is the directory containing the `.coggit/` folder
+ * (i.e. `dirname(dirname(configUri.path))`).
+ *
+ * Callers that need `sourceRootUri`/`cognitionRootUri` should parse
+ * the YAML at `configUri` and resolve relative paths from `projectRootUri`.
+ */
+export interface ProjectRoot {
+    configUri: UriComponents;
+    projectRootUri: UriComponents;
+}
+/**
+ * Walk up from `startUri` to find the nearest enclosing `.coggit/config.yaml`.
+ *
+ * Analogous to Git's `rev-parse --git-dir` — a lightweight path-anchoring
+ * primitive that discovers which coggit project a file or directory belongs to.
+ *
+ * Core-layer function: depends only on `FileSystem` and `UriComponents`.
+ * No host runtime (VS Code / Node) dependency.
+ *
+ * @param startUri  The URI to start from (file or directory).
+ * @param fs        The FileSystem abstraction for existence checks.
+ * @param options   Optional `{ maxWalkDepth }` to limit the upward walk.
+ * @returns The `ProjectRoot` if found, or `undefined` if the walk exhausted.
+ */
+export declare function findProjectRoot(startUri: UriComponents, fs: FileSystem, options?: {
+    maxWalkDepth?: number;
+}): Promise<ProjectRoot | undefined>;

package/dist/project/index.d.ts

@@ -0,0 +1,8 @@
+export { ResolveAcceptanceError, RuntimeAcceptanceEvidence, createCoggitServices, discoverCoggitProjects, openCoggitProject, buildSnapshotFromProjects, parentUri, resolveNodeInSnapshot, } from './project';
+export type { CoggitProjectDiscoveryOptions, RegistryInitFailurePolicy, } from './project';
+export { projectContextFromRoot, projectContext } from './projectContext';
+export { findProjectRoot } from './discover';
+export type { ProjectRoot } from './discover';
+export { discoverWorkspaceRoots, readWorkspaceRoot } from './workspace';
+export { initProject } from './init';
+export { buildSnapshot } from './buildSnapshot';

package/dist/project/init.d.ts

@@ -0,0 +1,22 @@
+import type { FileSystem, UriComponents } from '../interfaces';
+/**
+ * Initialize a coggit project at the given project root.
+ *
+ * Creates `.coggit/config.yaml`, the cognition root directory, and ensures
+ * `.gitignore` has the right coggit entries so cache files don't leak in
+ * and users are reminded not to gitignore `.coggit/` itself.
+ *
+ * Core-layer function: takes a `FileSystem` abstraction and `UriComponents`,
+ * making it portable across VS Code, CLI, and tests.  Callers are responsible
+ * for converting string paths to `UriComponents` before calling this function.
+ *
+ * @param fs           The filesystem abstraction to use for all I/O.
+ * @param projectRoot  URI of the project root (the directory that will contain
+ *                     the `.coggit/` folder).
+ * @param overrides    Optional `{ sourceRoot, cognitionRoot }` to override the
+ *                     defaults (`"src"` / `"src_cognition"`).
+ */
+export declare function initProject(fs: FileSystem, projectRoot: UriComponents, overrides?: {
+    sourceRoot?: string;
+    cognitionRoot?: string;
+}): Promise<void>;

package/dist/project/project.d.ts

@@ -0,0 +1,44 @@
+import type { CoggitProject, CoggitServices, SourcePathResolution, UriComponents } from '../interfaces';
+import type { CoggitLogger } from '../logger';
+import type { AcceptedPair, CoggitSnapshot, CoggitWorkspaceRoot } from '../types';
+/**
+ * Raised by `markResolved` when the acceptance operation fails after the source
+ * path has already resolved to a node. Carries the canonical source-root-relative
+ * node path (`node.relativePath`) so callers can echo a canonical path on
+ * post-resolution failures instead of the raw caller input.
+ */
+export declare class ResolveAcceptanceError extends Error {
+    readonly canonicalSourcePath: string;
+    constructor(message: string, canonicalSourcePath: string, cause?: unknown);
+}
+export type RegistryInitFailurePolicy = 'degrade' | 'throw';
+export interface CoggitProjectDiscoveryOptions {
+    /** How project-open registry reconciliation failures are surfaced. */
+    readonly registryInitFailure?: RegistryInitFailurePolicy;
+    /** Host-local ordering evidence reused across project runtime rebuilds. */
+    readonly runtimeEvidence?: (root: CoggitWorkspaceRoot) => RuntimeAcceptanceEvidence;
+}
+export declare class RuntimeAcceptanceEvidence {
+    private readonly records;
+    private fallbackGeneration;
+    normalizeGeneration(generation: number | undefined): number;
+    beginSource(key: string, generation: number): void;
+    completeSource(key: string, generation: number, identity: AcceptedPair['source']): boolean;
+    recordCognition(key: string, generation: number): void;
+    hasSourceBeforeCognition(key: string, pair: AcceptedPair): boolean;
+    clear(key: string): void;
+}
+export declare function createCoggitServices(services: CoggitServices): CoggitServices;
+export declare function createCoggitServices(fs: CoggitServices['fs'], config: CoggitServices['config'], registry?: CoggitServices['registry'], logger?: CoggitLogger, locks?: CoggitServices['locks']): CoggitServices;
+export declare function discoverCoggitProjects(services: CoggitServices, options?: CoggitProjectDiscoveryOptions): Promise<CoggitProject[]>;
+export declare function openCoggitProject(services: CoggitServices, root: CoggitWorkspaceRoot, options?: CoggitProjectDiscoveryOptions): Promise<CoggitProject>;
+export declare function buildSnapshotFromProjects(projects: readonly CoggitProject[]): Promise<CoggitSnapshot>;
+/**
+ * Resolve a source path against an already-built snapshot, scoped to one
+ * project root. Shared by `resolveProjectNode` (which builds the snapshot
+ * first) and `statusOperation`'s snapshot-reuse path (which receives a
+ * pre-built combined snapshot from `buildSnapshotFromProjects`).
+ */
+export declare function resolveNodeInSnapshot(snapshot: CoggitSnapshot, root: CoggitWorkspaceRoot, sourcePath: string): SourcePathResolution;
+/** Return the parent URI (directory) of a given URI. */
+export declare function parentUri(uri: UriComponents): UriComponents;

package/dist/project/projectContext.d.ts

@@ -0,0 +1,4 @@
+import type { CoggitProject } from '../interfaces';
+import type { CoggitProjectContext, CoggitWorkspaceRoot } from '../types';
+export declare function projectContextFromRoot(root: CoggitWorkspaceRoot): CoggitProjectContext;
+export declare function projectContext(project: CoggitProject): CoggitProjectContext;