@coggit/core 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `@coggit/core` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); versioning is semver.
+
+## [0.2.0] - 2026-09-05
+
+Initial npm publish. `0.2.0` matches the monorepo split source (see ADR 0017 /
+ADR 0019); there is no npm release for `0.1.0`.
+
+### Added
+
+- Public `.` export surface: source/cognition freshness semantics, registry,
+  snapshot, status, and operations, assembled via `createCoggitServices` port
+  contracts.
+- `./internal` subpath for trusted monorepo consumers (the published `coggit`
+  CLI); ships in the tarball with no third-party stability promise.
+- Zero runtime dependencies (`yaml` is bundled at build time).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CatheadOwl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @coggit/core
+
+CogGit core kernel: source/cognition freshness semantics, registry, snapshot,
+status, and operations. Runtime-agnostic — filesystem, config, and registry
+access come in through port contracts you implement.
+
+## Install
+
+```sh
+npm install @coggit/core
+```
+
+## Minimal usage
+
+```ts
+import { createCoggitServices, statusOperation } from '@coggit/core';
+
+// Assemble the kernel against your runtime's port implementations.
+const services = createCoggitServices({
+  fs: myFileSystem,        // implements the FileSystem port
+  config: myConfig,        // implements the ConfigProvider port
+  registry: myRegistry,    // RegistryProviderFactory
+  logger: myLogger,        // optional
+  locks: myLocks,          // optional
+});
+
+const result = await statusOperation(services, { sourcePath: 'src/main.ts' });
+```
+
+Node host? Use [`@coggit/runtime-node`](../runtime-node/README.md), which
+ships ready-made local-filesystem adapters and
+`createNodeCoggitServices`.
+
+## Surface notes
+
+- The `.` export is the public contract (see `src/public.ts`).
+- `@coggit/core/internal` is a trusted-consumer face used by the published
+  `coggit` CLI; it ships in the tarball but carries **no stability promise**
+  for third parties.
+
+Architecture, concepts, and workflow docs live in the
+[repository root](https://github.com/CatheadOwl/coggit#readme).

package/dist/acceptance.d.ts

@@ -0,0 +1,7 @@
+import type { AcceptanceStore } from './interfaces';
+import type { AcceptedPair } from './registryTypes';
+export interface AcceptCurrentPairResult {
+    accepted: AcceptedPair | null;
+    changed: boolean;
+}
+export declare function acceptCurrentPair(store: AcceptanceStore, rootId: string, sourceKey: string, sourceIdentity: AcceptedPair['source'], cognitionContent: string | null): AcceptCurrentPairResult;

package/dist/affected.d.ts

@@ -0,0 +1,7 @@
+import type { AffectedResult, MappingIndex } from './types';
+/**
+ * Given changed source or cognition paths, calculate affected source-cognition pairs.
+ * Phase 2 incremental refresh uses this to avoid full rebuilds when existing mapped
+ * files change. Unknown create/delete paths are handled by the caller as full rebuilds.
+ */
+export declare function calculateAffected(changedPaths: string[], mapping: MappingIndex): AffectedResult;

package/dist/cognition/handbooks.d.ts

@@ -0,0 +1,3 @@
+export declare const SYSTEM_HANDBOOK: string;
+export declare const SKELETON_HANDBOOK: string;
+export declare const LEAF_HANDBOOK: string;

package/dist/cognition/index.d.ts

@@ -0,0 +1,34 @@
+import type { FileSystem, UriComponents } from '../interfaces';
+import type { CoggitWorkspaceRoot } from '../types';
+import type { Registry } from '../registry/index';
+export type CognitionKind = 'leaf' | 'skeleton';
+export type AddCognitionKind = CognitionKind | 'auto';
+export interface AddCognitionOptions {
+    kind?: AddCognitionKind;
+    overwrite?: boolean;
+}
+export interface AddCognitionResult {
+    kind: CognitionKind;
+    sourcePath: string;
+    cognitionPath: string;
+    cognitionUri: UriComponents;
+    created: boolean;
+}
+export interface CognitionTemplate {
+    kind: CognitionKind;
+    version: 'skeleton-leaf-v3';
+    content: string;
+}
+export interface CognitionHandbook {
+    kind: CognitionKind | 'all';
+    version: 'skeleton-leaf-v3';
+    content: string;
+}
+export declare function addCognition(root: CoggitWorkspaceRoot, fs: FileSystem, registry: Registry | null, sourcePath: string, options?: AddCognitionOptions): Promise<AddCognitionResult>;
+export declare function getCognitionTemplate(kind: CognitionKind): CognitionTemplate;
+export declare function getCognitionHandbook(kind: CognitionKind): CognitionHandbook;
+/**
+ * @deprecated The aggregate handbook is retained only for CLI compatibility.
+ * Use the node-kind handbooks ('leaf' or 'skeleton') for maintained guidance.
+ */
+export declare function getCognitionHandbook(kind?: 'all'): CognitionHandbook;

package/dist/cognition/templates.d.ts

@@ -0,0 +1,3 @@
+export declare const BOOTSTRAP_README_FOR_EMPTY_COGNITION_LAYER: string;
+export declare const SKELETON_TEMPLATE: string;
+export declare const LEAF_TEMPLATE: string;

package/dist/cognitionDiscovery.d.ts

@@ -0,0 +1,9 @@
+import type { FileSystem, UriComponents } from './interfaces';
+import type { CognitionDiscoveryEntry } from './types';
+export interface CognitionDiscoveryOptions {
+    sourceRootUri?: UriComponents;
+    checkSourceCandidates?: boolean;
+    shouldSkipDirectory?: (name: string) => boolean;
+}
+export type CognitionDiscovery = Map<string, CognitionDiscoveryEntry>;
+export declare function discoverCognitionEntries(fs: FileSystem, cognitionRootUri: UriComponents, options?: CognitionDiscoveryOptions): Promise<CognitionDiscovery>;

package/dist/cognitionDocumentFacts.d.ts

@@ -0,0 +1,6 @@
+import type { CognitionDocumentFacts, CognitionHeading } from './types';
+export interface ParseCognitionDocumentFactsOptions {
+    mtimeMs?: number;
+}
+export declare function parseCognitionDocumentFacts(cognitionPath: string, content: string, options?: ParseCognitionDocumentFactsOptions): CognitionDocumentFacts;
+export declare function extractCognitionHeadings(content: string): CognitionHeading[];

package/dist/cognitionRoutes.d.ts

@@ -0,0 +1,10 @@
+import type { FileSystem } from './interfaces';
+import type { CoggitProjectContext, CoggitWorkspaceRoot, CognitionRoutes, PathKeyRecord } from './types';
+export interface BuildCognitionRoutesOptions {
+    includeHeadings?: boolean;
+    maxHeadingDepth?: number;
+}
+export interface CognitionRoutesRegistryLookup {
+    getEntry(key: string): PathKeyRecord | undefined;
+}
+export declare function buildCognitionRoutes(root: CoggitWorkspaceRoot, fs: FileSystem, registryLookup: CognitionRoutesRegistryLookup | null, project: CoggitProjectContext, options?: BuildCognitionRoutesOptions): Promise<CognitionRoutes>;

package/dist/cognitionTypes.d.ts

@@ -0,0 +1,100 @@
+import type { CoggitOperationAction, CoggitProjectContext } from './operationTypes';
+import type { ObservedStatus } from './status/statusTypes';
+export type CognitionDocumentKind = 'leaf' | 'folder';
+export interface CognitionFrontmatterMetadata {
+    type?: string;
+    layer?: string;
+    module?: string;
+    kind?: string;
+    tags?: string[];
+    apiSurface?: string[];
+    retrieval?: {
+        summary?: string;
+        intents?: string[];
+    };
+    [key: string]: unknown;
+}
+export interface CognitionFrontmatter {
+    name: string | null;
+    description: string | null;
+    metadata: CognitionFrontmatterMetadata;
+    raw: Record<string, unknown>;
+}
+export interface CognitionHeading {
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+    line: number;
+    slug: string;
+}
+export interface CognitionDocumentMetrics {
+    charLength: number;
+    lineCount: number;
+    nonEmptyLineCount: number;
+    contentHash: string;
+    mtimeMs: number;
+}
+export interface CognitionDocumentDiagnostic {
+    code: 'missing-frontmatter' | 'malformed-frontmatter' | 'missing-name' | 'missing-description' | 'weak-description' | 'missing-metadata-type' | 'invalid-metadata-tags' | 'invalid-metadata-api-surface' | 'invalid-metadata-retrieval-intents' | 'duplicate-cognition-key' | 'source-path-outside-source-root' | 'unreadable-cognition-file';
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+}
+export interface CognitionDocumentFacts {
+    cognitionPath: string;
+    key: string;
+    kind: CognitionDocumentKind;
+    frontmatter: CognitionFrontmatter;
+    headings: CognitionHeading[];
+    metrics: CognitionDocumentMetrics;
+    diagnostics: CognitionDocumentDiagnostic[];
+}
+export type CognitionMetadataQuality = 'good' | 'usable' | 'poor';
+export type CognitionContextStaleRisk = 'low' | 'medium' | 'high' | 'unknown';
+export interface CognitionRoutes {
+    project: CoggitProjectContext;
+    generatedAt: number;
+    entries: CognitionRoutesEntry[];
+    diagnostics: CognitionDocumentDiagnostic[];
+}
+export interface CognitionRoutesEntry {
+    key: string;
+    /** Bound source path, project-root-relative (from the registry binding). */
+    projectRelativeSourcePath: string | null;
+    /** Cognition document path, project-root-relative. */
+    cognitionPath: string;
+    documentKind: CognitionDocumentKind;
+    metadataType: string | null;
+    identity: CognitionContextIdentity;
+    document: CognitionContextDocumentSummary;
+    quality: CognitionContextQuality;
+    status: CognitionContextStatus;
+    diagnostics: CognitionDocumentDiagnostic[];
+    suggestedActions: CoggitOperationAction[];
+}
+export interface CognitionContextIdentity {
+    name: string | null;
+    description: string | null;
+    retrievalSummary: string | null;
+    retrievalIntents: string[];
+    tags: string[];
+}
+export interface CognitionContextDocumentSummary {
+    metrics: CognitionDocumentMetrics;
+    headings: CognitionHeading[];
+    headingCount: number;
+}
+export interface CognitionContextQuality {
+    metadataQuality: CognitionMetadataQuality;
+    staleRisk: CognitionContextStaleRisk;
+}
+export interface CognitionContextStatus {
+    observedStatus: ObservedStatus | null;
+    staleRisk: CognitionContextStaleRisk;
+}
+export interface RoutesProjectionNode {
+    path: string;
+    cognition?: string;
+    description?: string;
+    truncated?: boolean;
+    omittedChildrenCount?: number;
+    children?: RoutesProjectionNode[];
+}

package/dist/directoryEntrySourceFact.d.ts

@@ -0,0 +1,8 @@
+import type { FileSystem, UriComponents } from './interfaces';
+export interface DirectoryEntrySourceFactItem {
+    readonly name: string;
+    readonly kind: 'file' | 'folder';
+}
+export declare function directoryEntryFingerprint(items: readonly DirectoryEntrySourceFactItem[]): string;
+export declare function directoryEntryItemsFromReadDirectory(entries: readonly (readonly [string, number])[]): DirectoryEntrySourceFactItem[];
+export declare function readDirectoryEntryFingerprint(fs: FileSystem, directoryUri: UriComponents): Promise<string | undefined>;

package/dist/gitignore.d.ts

@@ -0,0 +1,28 @@
+import type { UriComponents } from './interfaces';
+export interface CoggitIgnoreRuleSet {
+    rules: IgnoreRule[];
+}
+interface IgnoreRule {
+    basePath: string;
+    pattern: string;
+    negated: boolean;
+    directoryOnly: boolean;
+    anchored: boolean;
+    hasSlash: boolean;
+    segmentRegExp: RegExp;
+    pathRegExp: RegExp;
+}
+export interface FileReader {
+    readFile(uri: UriComponents): Promise<string>;
+    exists(uri: UriComponents): Promise<boolean>;
+}
+export declare function loadGitignoreRules(projectRootUri: UriComponents, directoryUri: UriComponents, inheritedRules: CoggitIgnoreRuleSet, fileReader: FileReader): Promise<CoggitIgnoreRuleSet>;
+export declare function isIgnoredByGitignoreRules(projectRootUri: UriComponents, ruleSet: CoggitIgnoreRuleSet, uri: UriComponents, isDirectory: boolean): boolean;
+declare function parseGitignoreRules(contents: string, basePath?: string): IgnoreRule[];
+declare function matchesRule(rule: IgnoreRule, relativePath: string, isDirectory: boolean): boolean;
+export declare const __testing__: {
+    parseGitignoreRules: typeof parseGitignoreRules;
+    matchesRule: typeof matchesRule;
+    isIgnoredByGitignoreRules: typeof isIgnoredByGitignoreRules;
+};
+export {};

package/dist/hash.d.ts

@@ -0,0 +1,13 @@
+import type { SourceFactKind } from './status/statusTypes';
+export type ContentIdentity = `sha256:v1:${string}`;
+/** Compute the legacy unprefixed SHA-256 used by reconcile rename caches. */
+export declare function computeBlobHash(content: string): string;
+/**
+ * Compute the versioned CogGit identity used by freshness acceptance.
+ * Domain separation prevents the same bytes in different fact kinds from
+ * accidentally sharing an identity.
+ */
+export declare function computeContentIdentity(kind: 'leaf' | 'cognition' | 'folder', content: string): ContentIdentity;
+export declare function computeSourceFactIdentity(kind: SourceFactKind, content: string): ContentIdentity;
+export declare function computeCognitionIdentity(content: string): ContentIdentity;
+export declare function isContentIdentity(value: unknown): value is ContentIdentity;

package/dist/identity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure path/URI-to-key conversion functions for the CogGit registry.
+ *
+ * Registry keys are cognition-root-derived identities used in
+ * .coggit/registry.json. They are path-shaped keys, not general source paths.
+ * Path anchors are specified in the registry path contract spec.
+ * No IO, no state -- just string transformations.
+ *
+ * The `.md`/`README` source↔cognition pairing convention lives in `mapping.ts`
+ * (`sourceIdentityToCognitionIdentity` / `cognitionIdentityToSourceIdentity`);
+ * this module reuses it for key derivation rather than re-deriving it.
+ */
+/** Minimum content length (in chars) for rename pairing to avoid false positives on empty template skeletons. */
+export declare const MIN_RENAME_PAIRING_LENGTH = 100;
+/**
+ * Transform a source-relative path (with extension) to a registry key.
+ *
+ * Rules:
+ * - Strip the file extension (last `.` onwards)
+ * - Normalize separators to `/`
+ * - Keep dotfiles' dot in the name (`.eslintrc.js` -> `.eslintrc`)
+ *
+ * @example sourcePathToKey("src/model/types.ts")       // -> "src/model/types"
+ * @example sourcePathToKey("src/utils/helpers.js")     // -> "src/utils/helpers"
+ * @example sourcePathToKey("src/index.ts")             // -> "src/index"
+ * @example sourcePathToKey("foo.ts.md")                // -> "foo.ts"
+ * @example sourcePathToKey(".eslintrc.js")             // -> ".eslintrc"
+ * @example sourcePathToKey("noext")                    // -> "noext"
+ * @example sourcePathToKey(".hidden")                  // -> ".hidden"
+ */
+export declare function sourcePathToKey(relativePath: string): string;
+/**
+ * Transform a cognition-relative path (`.md` file) to a registry key.
+ *
+ * Rules:
+ * - Strip trailing `.md`
+ * - If remaining path is `"README"` (leaf name is README) -> return `"<parent-dir>/"`
+ *   (trailing slash = folder key)
+ * - If remaining path is `""` -> return `"/"` (root key)
+ *
+ * @example cognitionPathToKey("src/model/types.ts.md") // -> "src/model/types.ts"
+ * @example cognitionPathToKey("src/README.md")          // -> "src/"
+ * @example cognitionPathToKey("README.md")              // -> "/"
+ */
+export declare function cognitionPathToKey(relativePath: string): string;
+/**
+ * Determine whether a cognition file participates in registry tracking.
+ *
+ * Tracked cognition files have a source-pairing convention:
+ * - `README.md` at any depth maps to a folder → tracked
+ * - `<name>.<ext>.md` (basename contains a source-like extension before `.md`) → tracked
+ *
+ * Free-form cognition documents (CODE_MAP.md, MODULES.md, INDEX.md, etc.) do NOT
+ * map to a specific source node and are excluded from registry tracking.
+ *
+ * @param relativePath Cognition-root-relative path (e.g. "src/CODE_MAP.md")
+ *
+ * @example isTrackedCognitionFile("README.md")              // true
+ * @example isTrackedCognitionFile("src/README.md")          // true
+ * @example isTrackedCognitionFile("src/types.ts.md")        // true
+ * @example isTrackedCognitionFile("src/CODE_MAP.md")        // false
+ * @example isTrackedCognitionFile("src/core/MODULES.md")    // false
+ */
+export declare function isTrackedCognitionFile(relativePath: string): boolean;
+/**
+ * Build the cognition-relative path from a registry key.
+ *
+ * @param key  - Registry key (e.g. "src/model/types", "src/", "/")
+ * @param kind - "leaf" for individual file cognition, "folder" for folder README cognition
+ *
+ * @example keyToCognitionPath("src/model/types", "leaf")   // -> "src/model/types.md"
+ * @example keyToCognitionPath("src/model/types", "folder") // -> "src/model/types/README.md"
+ * @example keyToCognitionPath("src/", "folder")            // -> "src/README.md"
+ * @example keyToCognitionPath("/", "folder")               // -> "README.md"
+ */
+export declare function keyToCognitionPath(key: string, kind: 'leaf' | 'folder'): string;

package/dist/interfaces.d.ts

@@ -0,0 +1,174 @@
+import type { AddCognitionOptions, AddCognitionResult, CognitionHandbook, CognitionKind, CognitionTemplate } from './cognition';
+import type { CoggitSnapshot, CoggitTreeNode, CoggitWorkspaceRoot, CognitionRoutes, AcceptedPair, MaintenanceDiagnostic, MisplacedCognitionEntry, OrphanedCognitionEntry, StrayCognitionEntry, UnboundCognitionEntry, RegistryProvider } from './types';
+import type { BuildCognitionRoutesOptions } from './cognitionRoutes';
+import type { CoggitLogger } from './logger';
+import type { ProjectLockManager } from './locks';
+export interface UriComponents {
+    scheme: string;
+    authority: string;
+    path: string;
+    query: string;
+    fragment: string;
+}
+export type UriKey = string;
+export interface FileSystem {
+    readFile(uri: UriComponents): Promise<string>;
+    writeFile(uri: UriComponents, content: string): Promise<void>;
+    stat(uri: UriComponents): Promise<FileStat | undefined>;
+    readDirectory(uri: UriComponents): Promise<Array<[string, number]>>;
+    exists(uri: UriComponents): Promise<boolean>;
+    createDirectory(uri: UriComponents): Promise<void>;
+    /** Delete a file at the given URI. No-op if the file does not exist. */
+    delete(uri: UriComponents): Promise<void>;
+}
+export interface FileStat {
+    isDirectory: boolean;
+    mtimeMs: number;
+}
+export interface WorkspaceFolderInfo {
+    uri: UriComponents;
+    name: string;
+    index: number;
+}
+export interface ConfigProvider {
+    getWorkspaceFolders(): WorkspaceFolderInfo[];
+    findFiles(pattern: string): Promise<UriComponents[]>;
+}
+export interface RegistryProviderFactory {
+    create(projectRoot: UriComponents): RegistryProvider;
+}
+export interface AcceptanceStore {
+    /** Read the complete accepted source/cognition relationship. */
+    getAcceptedPair(rootId: string, sourceKey: string): AcceptedPair | null;
+    /** Replace the complete accepted relationship atomically in memory. */
+    acceptPair(rootId: string, sourceKey: string, pair: AcceptedPair): void;
+    /**
+     * Return whether runtime-only ordering evidence proves that the current
+     * source identity was observed before the current cognition change.
+     */
+    hasSourceBeforeCognitionEvidence(rootId: string, sourceKey: string, pair: AcceptedPair): boolean;
+}
+/** @deprecated Compatibility surface for pre-v5 test adapters. */
+export interface FreshnessEvidenceStore {
+    getFreshnessTimes(rootId: string, sourceKey: string): {
+        sourceFactMtimeMs: number | null;
+        cognitionMtimeMs: number | null;
+        verificationTimeMs: number | null;
+        sourceFactHash: string | null;
+    };
+    recordSourceFactTime(rootId: string, sourceKey: string, mtimeMs: number, sourceFactHash?: string | null): void;
+    recordCognitionTime(rootId: string, sourceKey: string, mtimeMs: number): void;
+    recordExplicitVerification(rootId: string, sourceKey: string): void;
+}
+export interface ResolveResult {
+    sourceKey: string;
+    accepted?: AcceptedPair;
+    /** @deprecated v4 output field; no longer persisted or used for freshness. */
+    verificationTimeMs?: number;
+}
+export interface CoggitServices {
+    readonly fs: FileSystem;
+    readonly config: ConfigProvider;
+    readonly registry?: RegistryProviderFactory;
+    readonly logger?: CoggitLogger;
+    readonly locks?: ProjectLockManager;
+}
+/**
+ * Result of resolving a source path against a project's source tree.
+ * A shared resolution contract so status, snapshot, and routes can surface
+ * consistent "you may mean" hints instead of a bare not-found miss.
+ */
+export interface SourcePathResolution {
+    /** The matched node, or undefined when the path matched nothing. */
+    node: CoggitTreeNode | undefined;
+    /** Source-root-relative path used for matching, after normalization. */
+    normalizedPath: string;
+    /**
+     * Source-root-relative candidate paths available for fuzzy hinting.
+     * Present only when node is undefined.
+     */
+    candidatePaths?: string[];
+}
+export interface CoggitProject {
+    readonly root: CoggitWorkspaceRoot;
+    /**
+     * Re-validate project registry freshness by scanning cognition state and
+     * reconciling under the project write coordination boundary.
+     *
+     * Idempotent: if nothing changed since the last reconcile, the scan produces
+     * no diff and the registry content remains unchanged. Safe to call from
+     * multiple concurrent MCP processes — the write lock serializes mutations
+     * and the second caller sees an already-fresh registry.
+     *
+     * Fail-closed: if the lock cannot be acquired, the registry cannot be loaded,
+     * or the flush fails, the error propagates to the caller. Callers must handle
+     * the failure explicitly rather than silently serving stale state.
+     *
+     * Callers: MCP read tools before returning authoritative results, CLI reads,
+     * VS Code project-open, future watcher triggers.
+     */
+    ensureFresh(): Promise<void>;
+    buildSnapshot(): Promise<CoggitSnapshot>;
+    buildCognitionRoutes(options?: BuildCognitionRoutesOptions): Promise<CognitionRoutes>;
+    addCognition(sourcePath: string, options?: AddCognitionOptions): Promise<AddCognitionResult>;
+    getCognitionHandbook(kind: CognitionKind): CognitionHandbook;
+    /**
+     * @deprecated Aggregate handbook access is retained only for CLI compatibility.
+     * Use 'leaf' or 'skeleton' for maintained guidance.
+     */
+    getCognitionHandbook(kind?: 'all'): CognitionHandbook;
+    getCognitionTemplate(kind: CognitionKind): CognitionTemplate;
+    getNode(sourcePath: string): Promise<CoggitTreeNode | undefined>;
+    /**
+     * Resolve a source path to a snapshot node, reusing one snapshot build.
+     * When the path matches nothing, also expose the normalized path and the
+     * source tree candidate paths so callers can offer fuzzy path hints.
+     */
+    resolveSourcePath(sourcePath: string): Promise<SourcePathResolution>;
+    listUntracked(): Promise<CoggitTreeNode[]>;
+    listOrphanedCognition(): Promise<OrphanedCognitionEntry[]>;
+    listMisplacedCognition(): Promise<MisplacedCognitionEntry[]>;
+    listStrayCognition(): Promise<StrayCognitionEntry[]>;
+    listUnboundCognition(): Promise<UnboundCognitionEntry[]>;
+    /**
+     * Aggregate maintenance diagnostics from a single core-owned entry point.
+     * Runs after project freshness, so registry-backed and scan-backed slices
+     * share one reconciled view. The stray slice is a raw/pre-reconcile
+     * compatibility view and is expected to be empty in ordinary freshened
+     * flows, because reconcile auto-registers source-paired cognition.
+     * CI and adapters must consume this surface instead of reinterpreting
+     * registry JSON.
+     */
+    listMaintenanceDiagnostics(): Promise<MaintenanceDiagnostic[]>;
+    /**
+     * Move a misplaced cognition file to its expected location.
+     * Updates both the file system and registry.
+     * Returns undefined on success, or an error message string on failure.
+     */
+    moveCognitionToExpected(entry: MisplacedCognitionEntry): Promise<string | undefined>;
+    /**
+     * Apply a source file/folder rename to registry sourcePath metadata.
+     * Returns true when at least one registry record was updated.
+     */
+    applySourceRename(oldUri: UriComponents, newUri: UriComponents): Promise<boolean>;
+    /**
+     * Observe a source-content watcher event without changing durable
+     * acceptance. The generation must share the caller's watcher event order.
+     * Returns true when runtime ordering evidence was recorded.
+     */
+    recordSourceChange(uri: UriComponents, generation?: number): Promise<boolean>;
+    /**
+     * Observe a directory-entry watcher event for the parent folder/root of a
+     * changed source URI without changing durable acceptance. Returns true when
+     * runtime ordering evidence was recorded.
+     */
+    recordDirectoryEntryChange(uri: UriComponents, generation?: number): Promise<boolean>;
+    /**
+     * Observe a cognition watcher event. Returns true when the observation
+     * passively accepts the current source/cognition pair.
+     */
+    recordCognitionChange(uri: UriComponents, generation?: number): Promise<boolean>;
+    markResolved(sourcePath: string): Promise<ResolveResult>;
+    refreshNode(sourcePath: string): Promise<CoggitTreeNode | undefined>;
+    flush(): Promise<void>;
+}

package/dist/internal.d.ts

@@ -0,0 +1,57 @@
+export { initProject } from './project';
+export { findProjectRoot } from './project';
+export { RuntimeAcceptanceEvidence, createCoggitServices, discoverCoggitProjects, openCoggitProject, buildSnapshotFromProjects, } from './project';
+export { projectContextFromRoot } from './project';
+export { noOpProjectLockManager, ProjectLockError, } from './locks';
+export { calculateAffected } from './affected';
+export { applyWatchEventToProjects, planWatchRefresh, selectWatchRefreshMode, } from './watchPipeline';
+export { createWatchHost, } from './watchHost';
+export type { NormalizedWatchEvent, WatchBatchRefreshMode, WatchRefreshRoute, WatcherEventApplyResult, WatchEventDomain, WatchFileChangeKind, WatchRefreshMode, } from './watchPipeline';
+export type { WatchHost, WatchHostObservationResult, WatchHostOptions, WatchHostRefreshIntent, WatchObservation, WatchObservationHandler, WatchObserver, WatchObserverSubscription, } from './watchHost';
+export { ADD_OPERATION_ERROR_CODES, CORE_OPERATION_IDS, addOperation, resolveOperation, routesOperation, findProjectNode, handbookCatalog, handbookIdForCognitionKind, handbookIdForNodeKind, operationIssue, projectContext, snapshotOperation, statusOperation, } from './operations';
+export type { AddOperationError, AddOperationErrorCode, AddOperationResult, ResolveErrorCode, ResolveOperationError, ResolveOperationResult, CoggitHandbookCatalogEntry, CoggitOperationAction, CoggitOperationIssue, CoggitProjectContext, CoreOperationId, RoutesOperationResult, SnapshotOperationResult, SnapshotOperationOptions, SnapshotOperationScope, SourcePathCandidatesExpander, StatusOperationOptions, StatusOperationResult, } from './operations';
+export type { CoggitProjectDiscoveryOptions, RegistryInitFailurePolicy, } from './project';
+export { getCognitionHandbook, getCognitionTemplate } from './cognition';
+export { getCoggitSystemPrompt, MINIMAL_SYSTEM_PROMPT } from './systemPrompt';
+export type { CoggitSystemPrompt, CoggitSystemPromptKind } from './systemPrompt';
+export { applyTreeDepth, projectSnapshotTree, projectTreeFromSnapshot, } from './projection';
+export { DEFAULT_ROUTES_DEPTH, assembleRoutesContent, countRouteNodes, flattenRoutesProjection, projectRoutesEntries, routeProjectionLineText, selectRoutesBySourcePath, toRoutesStructuredOutput, } from './routesProjection';
+export type { AssembleRoutesContentOptions, RoutesPresentationContent, RoutesPresentationFormat, RoutesStructuredOutput, } from './routesProjection';
+export { buildMappingIndex, } from './snapshot';
+export { detectMisplacedCognitionEntries, detectOrphanedCognitionEntries, detectStrayCognitionEntries, detectUnboundCognitionEntries, } from './maintenance';
+export { describeObservedStatus, aggregateNodeStatus, collectSubtreeIssues, computeRuntimeStatus, countSubtreeIssues, inspectNodeStatus, projectStatusIssues, projectStatusResultToNodeStatus, querySubtreeIssues, summarizeRepresentativeMtime, } from './status';
+export { projectStatusAgentPresentation, renderStatusAgentInspectionText, renderStatusAgentPresentation, } from './status/statusAgentPresentation';
+export type { StatusAgentActionLegendEntry, StatusAgentActionRole, StatusAgentIssueLegendEntry, StatusAgentIssueRow, StatusAgentPresentation, StatusAgentSeverityLevel, } from './status/statusAgentPresentation';
+export { projectStatusMissPresentation, projectStatusPresentation, renderStatusPresentation, } from './status/statusPresentation';
+export type { StatusMissPresentation, StatusPresentationFormat, StatusPresentationIssue, StatusPresentationView, } from './status/statusPresentation';
+export { tryGetCognitionPath } from './status/lookupCognition';
+export type { CognitionLookupHit } from './status/lookupCognition';
+export { projectMaintenancePresentation, renderMaintenancePresentation, } from './maintenancePresentation';
+export type { MaintenanceIssueCode, MaintenancePresentationFormat, MaintenancePresentationItem, MaintenancePresentationView, } from './maintenancePresentation';
+export { projectStatusTriage } from './status/statusTriage';
+export type { StatusTriageEntry, StatusTriageView, } from './status/statusTriage';
+export { normalizeSourcePathInput, toCognitionFileUri, toCognitionFolderReadmeUri, toRelativeUriPath, } from './mapping';
+export { PATH_HINT_MESSAGE, PATH_MISS_MESSAGE, pathHintsTryText, pathMissMessage, renderPathMissText, suggestPathHints, } from './pathHints';
+export type { SourcePathResolution, } from './interfaces';
+export { externalPathFromString, uriRelativePath, } from './uri-utils';
+export { createEnvCoggitLogger, debugLog, errorLog, infoLog, logEvent, nullCoggitLogger, warnLog, } from './logger';
+export type { CoggitLogEvent, CoggitLogLevel, CoggitLogger, } from './logger';
+export type { AddCognitionKind, AddCognitionOptions, AddCognitionResult, CognitionHandbook, CognitionKind, CognitionTemplate, } from './cognition';
+export type { ProjectLockContext, ProjectLockManager, } from './locks';
+export type { CoggitSnapshot, CoggitTreeNode, CoggitWorkspaceRoot, CognitionDiscoveryEntry, LocatedStatusIssue, MaintenanceDiagnostic, MisplacedCognitionEntry, NodeStatusResult, NodeStatusTriageEntry, ObservedStatus, OrphanedCognitionEntry, SourceCandidateState, StatusIssueVisibility, StrayCognitionEntry, UnboundCognitionEntry, } from './types';
+export { discoverWorkspaceRoots, readWorkspaceRoot } from './project';
+export { buildSnapshot } from './project';
+export { formatTimestamp, latestAcceptedTime } from './time';
+export { REGISTRY_MAINTENANCE_NOTICE, REGISTRY_SCHEMA_VERSION, Registry, RegistryRevisionMismatchError, computeRegistryRevision, type RegistryCreateOptions, type RegistryRevision, } from './registry/index';
+export { InMemoryRegistryProvider } from './registry/inMemoryRegistryProvider';
+export { GENERATED_SOURCE_STRUCTURE_DIRECTORY_NAMES, generatedSourceStructureGlobExclude, generatedSourceStructureGlobExcludePatterns, isIgnoredSourceStructureEntry, } from './sourceStructureIgnore';
+export { isIgnoredByGitignoreRules, loadGitignoreRules, type CoggitIgnoreRuleSet, type FileReader, __testing__ as gitignoreTesting, } from './gitignore';
+export { __testing__ as statusTesting } from './status';
+export { RESOLVE_ERROR_CODES } from './operations';
+export { applyRoutesFilters, suggestRoutePathHints, } from './routesProjection';
+export { joinUriPath } from './uri-utils';
+export { WatchLeaseError, noOpWatchLeaseManager, type WatchLeaseHandle, type WatchLeaseManager, } from './locks';
+export type { MappingIndex, RoutesProjectionNode, TreeProjectionNode, } from './types';
+export { getParentDir, getProjectRootPath, inferSourceUriCandidatesFromCognitionUri, resolveConfigRoots, toCognitionFilePath, toCognitionFolderReadmePath, } from './mapping';
+export type { EvidenceDiagnostic, StatusContext, StatusIssue, } from './status/statusTypes';
+export type { CoggitConfig, CoggitNodeKind, } from './snapshotTypes';