@coggit/core 0.2.0

package/dist/status/statusAgentPresentation.d.ts

@@ -0,0 +1,37 @@
+import type { NodeStatusInspection } from './statusTypes';
+export type StatusAgentActionRole = 'recommended' | 'optional-on-demand' | 'diagnostic';
+export type StatusAgentSeverityLevel = 'INFO' | 'WARN' | 'ERROR';
+export interface StatusAgentIssueLegendEntry {
+    level: StatusAgentSeverityLevel;
+    tag: string;
+    description: string;
+    /** Label-only remediation action codes for this issue tag, rendered as `hint=`. */
+    hints: string[];
+}
+export interface StatusAgentActionLegendEntry {
+    tag: string;
+    role: StatusAgentActionRole;
+    description: string;
+}
+export interface StatusAgentIssueRow {
+    level: StatusAgentSeverityLevel;
+    issueTags: string[];
+    sourcePath: string;
+    actionTags: string[];
+    optionalActionTags: string[];
+}
+export interface StatusAgentPresentation {
+    sourcePath: string;
+    cognitionPath: string | null;
+    cognitionPresence: NodeStatusInspection['cognitionPresence'];
+    status: NodeStatusInspection['status'];
+    ownIssueCount: number;
+    descendantIssueCount: number;
+    ownIssues: StatusAgentIssueRow[];
+    descendantIssues: StatusAgentIssueRow[];
+    issueLegend: StatusAgentIssueLegendEntry[];
+    actionLegend: StatusAgentActionLegendEntry[];
+}
+export declare function projectStatusAgentPresentation(inspection: NodeStatusInspection): StatusAgentPresentation;
+export declare function renderStatusAgentPresentation(view: StatusAgentPresentation): string;
+export declare function renderStatusAgentInspectionText(inspection: NodeStatusInspection): string;

package/dist/status/statusPresentation.d.ts

@@ -0,0 +1,43 @@
+import type { CognitionCoveragePresence, LocatedStatusIssue, NodeStatusInspection, ObservedStatus } from './statusTypes';
+export type StatusPresentationFormat = 'text' | 'markdown';
+export interface StatusPresentationIssue {
+    sourcePath: string;
+    cognitionPath: string | null;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    suggestedActions: string[];
+}
+export interface StatusPresentationView {
+    sourcePath: string;
+    cognitionPath: string | null;
+    cognitionPresence: CognitionCoveragePresence;
+    status: ObservedStatus | null;
+    ownStatus: ObservedStatus | null;
+    descendantStatus: ObservedStatus | null;
+    ownIssues: StatusPresentationIssue[];
+    descendantIssues: StatusPresentationIssue[];
+}
+/** Map located issues into the serializable presentation issue shape. Shared
+ *  by the single-node presentation view and the subtree triage projection so
+ *  both keep the same null encoding and field conventions. */
+export declare function mapStatusPresentationIssues(issues: readonly LocatedStatusIssue[]): StatusPresentationIssue[];
+export declare function projectStatusPresentation(inspection: NodeStatusInspection): StatusPresentationView;
+/** Adapter-ready structured view for a status miss: the requested source path
+ *  plus recovery guidance (`pathHints`, miss/hint messages). Complements
+ *  `StatusPresentationView` (the inspection-backed HIT view). */
+export interface StatusMissPresentation {
+    sourcePath: string;
+    pathHints: string[];
+    pathMissMessage?: string;
+    pathHintMessage?: string;
+}
+/** Project a status miss into an adapter-ready structured view. A miss has no
+ *  inspection, so this carries the lookup identity and recovery guidance without
+ *  requiring each adapter to assemble its own fallback shape. */
+export declare function projectStatusMissPresentation(result: {
+    sourcePath: string;
+    pathHints: readonly string[];
+    pathMissMessage?: string;
+    pathHintMessage?: string;
+}): StatusMissPresentation;
+export declare function renderStatusPresentation(view: StatusPresentationView, format?: StatusPresentationFormat): string;

package/dist/status/statusTriage.d.ts

@@ -0,0 +1,50 @@
+import type { CoggitOperationAction } from '../operationTypes';
+import type { CoggitNodeKind } from '../snapshotTypes';
+import type { NodeStatusInspection } from './statusTypes';
+import { type StatusPresentationIssue } from './statusPresentation';
+/**
+ * Adapter-ready subtree triage view for a status hit: one entry per
+ * issue-bearing node in the inspected node's projected issue set, grouping
+ * that node's issues with its node-scoped next-step actions. Lets an adapter
+ * answer "which descendants need attention, with what action and handbook
+ * guidance" from one folder/root status call, without per-descendant
+ * re-inspection.
+ */
+export interface StatusTriageView {
+    /** Project-root-relative path of the inspected node. */
+    sourcePath: string;
+    /** Total projected issue count over the inspected node and its subtree. */
+    issueCount: number;
+    entries: StatusTriageEntry[];
+}
+export interface StatusTriageEntry {
+    sourcePath: string;
+    /** Expected paired cognition path; same expected-path semantics and null
+     *  encoding as `StatusPresentationView.cognitionPath`. */
+    cognitionPath: string | null;
+    nodeKind: CoggitNodeKind;
+    relation: 'own' | 'descendant';
+    issues: StatusPresentationIssue[];
+    /**
+     * Node-scoped workflow actions. Facts-only (`[]`) for the own entry: the
+     * inspected node's next steps remain exclusively in the top-level
+     * `suggestedActions` channel. Handbook guidance rides the action-level
+     * `handbookId` (ISSUE 20260819-2200); no parallel entry-level handbook
+     * representation exists.
+     */
+    suggestedActions: CoggitOperationAction[];
+}
+/**
+ * Project an inspection's synthesized triage facts into the adapter-ready
+ * subtree triage view. Pure projection: the node-signal synthesis of
+ * descendant-scoped actions happens in `status/` during inspection (which is
+ * why this consumes the inspection, whose `triage` entries carry the matched
+ * tree nodes' synthesized actions, rather than re-deriving actions from
+ * `subtreeIssues`).
+ *
+ * This is a workflow/triage contract adjacent to the presentation, not a
+ * `StatusPresentationView` scope variant: the presentation stays the
+ * single-node fact projection, and adapters must not reintroduce `own` or
+ * `subtree` presentation variants through it.
+ */
+export declare function projectStatusTriage(inspection: NodeStatusInspection): StatusTriageView;

package/dist/status/statusTypes.d.ts

@@ -0,0 +1,240 @@
+import type { UriComponents } from '../interfaces';
+import type { CoggitOperationAction } from '../operationTypes';
+import type { CoggitNodeKind } from '../snapshotTypes';
+import type { AcceptedPair } from '../registryTypes';
+export type ObservedStatus = 'fresh' | 'stale' | 'conflict';
+export type SourceFactKind = 'file-content' | 'directory-entry';
+export interface EvidenceDiagnostic {
+    code: 'missing-cognition' | 'template-cognition' | 'outdated-cognition' | 'folder-structure-changed' | 'missing-coverage' | 'broken-links' | 'metadata-broken' | 'source-deleted' | 'conflicting-evidence' | 'folder-structure-outdated';
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    relatedPaths?: string[];
+}
+export interface StatusAction {
+    label: string;
+}
+export interface StatusIssue {
+    diagnostic: EvidenceDiagnostic;
+    actions: StatusAction[];
+}
+export type CognitionCoveragePresence = 'present' | 'missing' | 'not-applicable';
+export interface CoverageSignals {
+    ownCognition: CognitionCoveragePresence;
+    isMaterializable: boolean;
+    missingMaterializableCount: number;
+    coveredCount: number;
+}
+export type MaintenanceRecommendation = 'none' | 'optional' | 'recommended' | 'urgent';
+export type StaleAction = 'align-cognition-first';
+export interface NodeStatusResult {
+    observedStatus?: ObservedStatus;
+    ownObservedStatus?: ObservedStatus;
+    descendantObservedStatus?: ObservedStatus;
+    staleAction?: StaleAction;
+    /** Own-node issues only. Subtree diagnostics are queried with collectSubtreeIssues(). */
+    issues?: StatusIssue[];
+    coverage?: CoverageSignals;
+    computedAt?: number;
+}
+export interface LocatedStatusIssue {
+    nodeId: string;
+    nodeKind: CoggitNodeKind;
+    sourceUri: UriComponents;
+    /** Expected paired cognition URI. Optional: absent for nodes with no
+     *  expected cognition URI (e.g. the `error` node kind built by
+     *  `createErrorNode`); mirrors `CoggitTreeNode.cognitionUri`. */
+    cognitionUri?: UriComponents;
+    /**
+     * Expected paired cognition path, project-root-relative. Non-null for any
+     * real node (derived from the node's `cognitionUri`); `null` only for nodes
+     * with no `cognitionUri`. This is the *expected* target path — it does not
+     * assert that the document exists. Null is encoded as `null` (not
+     * `undefined`) to match `StatusOperationResult.cognitionPath`: the two
+     * fields share one meaning, so they share one null encoding.
+     */
+    cognitionPath: string | null;
+    /** Project-root-relative source path of the issue-bearing node. */
+    relativePath: string;
+    hasPairedCognition?: boolean;
+    issue: StatusIssue;
+}
+export interface SubtreeIssueQueryResult {
+    ownIssues: LocatedStatusIssue[];
+    descendantIssues: LocatedStatusIssue[];
+    totalIssues: number;
+}
+export type StatusIssueVisibility = 'maintained' | 'all';
+export type ReasonKind = 'outdated-mtime' | 'source-changed' | 'unverified' | 'broken-links' | 'missing-coverage' | 'missing-metadata' | 'corrupted-metadata' | 'dep-mismatch' | 'semantic-edge-changed' | 'acceptance-order-unknown' | 'symbol-changed' | 'structural-edge-changed' | 'source-deleted' | 'source-renamed';
+export interface Reason {
+    kind: ReasonKind;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    relatedPaths?: string[];
+}
+export interface SourceFactIdentity {
+    kind: SourceFactKind;
+    currentHash: string;
+}
+export interface TextMetrics {
+    charLength: number;
+    lineCount: number;
+    nonEmptyLineCount: number;
+}
+export interface SourceChangeMetrics {
+    basis: 'unavailable' | 'git-diff' | 'snapshot';
+    changedLines: number | null;
+    changeRatio: number | null;
+}
+export interface StaleDegreeResult {
+    availability: 'available' | 'unavailable' | 'not-applicable';
+    score: number | null;
+    recommendation: MaintenanceRecommendation | null;
+    confidence: 'none' | 'low' | 'medium' | 'high';
+    reason: string;
+}
+export interface Evidence {
+    sourceMtimeMs: number;
+    sourceBlobHash: string;
+    cognitionMtimeMs: number | null;
+    verificationTimeMs?: number | null;
+    sourceFactIdentity: SourceFactIdentity;
+    acceptedPair?: AcceptedPair | null;
+    cognitionBlobHash?: string | null;
+    cognitionChangedSinceAccepted?: boolean;
+    sourceChangedSinceAccepted?: boolean;
+    sourceMetrics: TextMetrics;
+    cognitionMetrics: TextMetrics | null;
+    changeMetrics: SourceChangeMetrics;
+    changedSymbols: string[];
+    brokenLinks: LinkCheckResult[];
+    gitCommitsSinceVerified: number;
+    /** Whether cognition exists but still has only template-like content. */
+    cognitionContentIsTemplate: boolean;
+    /** Orphan detection: cognition exists while source no longer exists. */
+    sourceDeleted: boolean;
+}
+export interface StatusResult {
+    observedStatus?: ObservedStatus;
+    ownObservedStatus?: ObservedStatus;
+    staleAction?: StaleAction;
+    issues: StatusIssue[];
+    coverage: CoverageSignals;
+    reasons: Reason[];
+    evidence: Evidence;
+    computedAt: number;
+}
+/**
+ * Per-node triage fact synthesized during inspection: one entry per
+ * issue-bearing node in the projected issue set, grouping that node's issues
+ * with its node-scoped workflow actions. This is the subtree-maintenance
+ * counterpart to the single-node `suggestedActions` channel; the
+ * [[statusTriage.ts]] projection maps these facts into the adapter-ready
+ * `StatusTriageView`.
+ */
+export interface NodeStatusTriageEntry {
+    /** Project-root-relative path of the issue-bearing node. */
+    sourcePath: string;
+    /**
+     * Expected paired cognition path, project-root-relative; same expected-path
+     * semantics and null encoding as `NodeStatusInspection.cognitionPath`.
+     */
+    cognitionPath: string | null;
+    nodeKind: CoggitNodeKind;
+    /** Whether this entry is the inspected node itself or a descendant. */
+    relation: 'own' | 'descendant';
+    /** This node's issues under the selected issue visibility. */
+    issues: LocatedStatusIssue[];
+    /**
+     * Node-scoped workflow actions synthesized from this node's own
+     * status/coverage signals. Structured-only (carries `operation` or
+     * `handbookId`): label-only issue guidance stays in the entry's
+     * `issues[].issue.actions` and is never echoed here, so consumers never
+     * re-judge which actions are workflow. The own entry is facts-only and
+     * always `[]`: the inspected node's next steps remain exclusively in the
+     * top-level `suggestedActions` channel, so no action appears in two
+     * channels. Error nodes carry no synthesized actions.
+     */
+    actions: CoggitOperationAction[];
+}
+export interface NodeStatusInspection {
+    /** Project-root-relative source path of the inspected node. */
+    sourcePath: string;
+    /**
+     * Expected paired cognition path, project-root-relative; `null` only when
+     * the node has no expected cognition URI. This is the *expected* target
+     * path, not an existence check — pair it with `cognitionPresence`.
+     */
+    cognitionPath: string | null;
+    cognitionPresence: CognitionCoveragePresence;
+    nodeKind: CoggitNodeKind;
+    /**
+     * 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;
+    issueSummary: {
+        total: number;
+        own: number;
+        descendant: number;
+    };
+    /** Always present with `own`/`descendant` arrays; `[]` means "none". */
+    subtreeIssues: {
+        own: LocatedStatusIssue[];
+        descendant: LocatedStatusIssue[];
+    };
+    suggestedActions: CoggitOperationAction[];
+    /**
+     * One entry per issue-bearing node in the projected issue set: the own
+     * entry first (when the inspected node has issues), then descendant entries
+     * in subtree collection order. Descendant entries carry node-scoped actions
+     * synthesized from node signals; adapters render subtree workflow from these
+     * entries, not from `suggestedActions`.
+     */
+    triage: NodeStatusTriageEntry[];
+    handbookId: 'leaf' | 'skeleton' | null;
+}
+export interface SourceFileInfo {
+    uri: string;
+    mtimeMs: number;
+    content: string;
+    blobHash: string;
+    sourceFactKind?: SourceFactKind;
+    publicSymbols: string[];
+    dependencies: string[];
+}
+export interface CognitionFileInfo {
+    uri: string;
+    mtimeMs: number | null;
+    content: string | null;
+    verificationTimeMs?: number | null;
+    acceptedPair?: AcceptedPair | null;
+    links: Array<{
+        text: string;
+        target: string;
+    }>;
+    brokenLinks: LinkCheckResult[];
+}
+export interface LinkCheckResult {
+    text: string;
+    target: string;
+    reason: 'not-found' | 'external' | 'cyclic' | 'invalid-format';
+    sourceLine: number;
+}
+export interface StatusContext {
+    symbolIndex: Map<string, string[]>;
+    linkIndex: Map<string, LinkCheckResult[]>;
+    depGraph: Map<string, string[]>;
+}

package/dist/systemPrompt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Surface-neutral system prompt assets for CogGit hosts.
+ *
+ * A "system prompt" is the short guidance a host injects so an agent knows
+ * CogGit exists and how to approach it. Forms range from a short hint
+ * (minimal) to fuller operational instructions. Every form is surface-neutral:
+ * it names CogGit as the project, references CLI-baseline commands only, and
+ * never hard-codes a specific surface's tool names, resource URIs, or
+ * addressing (`coggit_*`, `coggit://`). Hosts that need surface-specific
+ * wording re-address these forms themselves (see the TODO below).
+ */
+export type CoggitSystemPromptKind = 'minimal';
+export interface CoggitSystemPrompt {
+    kind: CoggitSystemPromptKind;
+    version: 'system-prompt-v1';
+    content: string;
+}
+/**
+ * The minimal form: the essential identity of CogGit — the mirrored cognition
+ * layer and what it records — plus the keep-it-current directive, without
+ * prescribing a workflow.
+ */
+export declare const MINIMAL_SYSTEM_PROMPT: CoggitSystemPrompt;
+export declare function getCoggitSystemPrompt(kind?: CoggitSystemPromptKind): CoggitSystemPrompt;

package/dist/time.d.ts

@@ -0,0 +1,2 @@
+export declare function formatTimestamp(value: number | null, noneLabel: string): string;
+export declare function latestAcceptedTime(cognitionMtimeMs: number | null, verificationTimeMs: number | null): number | null;

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+export type { ObservedStatus, SourceFactKind, EvidenceDiagnostic, StatusAction, StatusIssue, CognitionCoveragePresence, CoverageSignals, MaintenanceRecommendation, StaleAction, NodeStatusResult, LocatedStatusIssue, StatusIssueVisibility, SubtreeIssueQueryResult, ReasonKind, Reason, SourceFactIdentity, TextMetrics, SourceChangeMetrics, StaleDegreeResult, Evidence, StatusResult, NodeStatusInspection, NodeStatusTriageEntry, SourceFileInfo, CognitionFileInfo, LinkCheckResult, StatusContext, } from './status/statusTypes';
+export type { SnapshotOperationScope, CoggitProjectContext, CoggitOperationAction, CoreOperationId, } from './operationTypes';
+export type { CognitionDocumentKind, CognitionFrontmatterMetadata, CognitionFrontmatter, CognitionHeading, CognitionDocumentMetrics, CognitionDocumentDiagnostic, CognitionDocumentFacts, CognitionMetadataQuality, CognitionContextStaleRisk, CognitionRoutes, CognitionRoutesEntry, CognitionContextIdentity, CognitionContextDocumentSummary, CognitionContextQuality, CognitionContextStatus, RoutesProjectionNode, } from './cognitionTypes';
+export type { AcceptedPair, PathKeyRecord, RegistryFile, RegistryProvider, } from './registryTypes';
+export type { MisplacedCognitionEntry, OrphanedCognitionEntry, StrayCognitionEntry, UnboundCognitionEntry, MaintenanceDiagnostic, CognitionDiscoveryEntry, SourceCandidateState, CoggitNodeKind, MappingIndex, AffectedResult, CoggitWorkspaceRoot, CoggitTreeNode, CoggitSnapshot, TreeProjectionNode, CoggitConfig, } from './snapshotTypes';

package/dist/uri-utils.d.ts

@@ -0,0 +1,35 @@
+import type { UriComponents, UriKey } from './interfaces';
+/** Produce a canonical URI key string from UriComponents */
+export declare function uriKey(components: UriComponents): UriKey;
+/** Compute relative path from root to child, comparing scheme/authority/path */
+export declare function uriRelativePath(root: UriComponents, child: UriComponents): string | undefined;
+export declare function isEqualOrChildUri(parent: UriComponents, child: UriComponents): boolean;
+/**
+ * Join path segments onto a base URI, preserving scheme and authority.
+ * This is a path-level operation (unlike vscode.Uri.joinPath which is URI-aware).
+ */
+export declare function joinUriPath(base: UriComponents, ...segments: string[]): UriComponents;
+export declare function uriBasename(uri: UriComponents): string;
+export declare function formatUri(uri: UriComponents): string;
+/**
+ * Extract a clean, runtime-independent path string from UriComponents.
+ *
+ * For `file://` URIs the scheme prefix is stripped so callers get an
+ * absolute path they can use directly or wrap in a runtime-specific URI.
+ * Non-file URIs return the full URI key unchanged so no information is lost.
+ *
+ * This is the boundary transform at the MCP DTO layer — core internals keep
+ * working with UriComponents; MCP-facing projections use this to decouple
+ * the wire format from the `file://` scheme.
+ */
+export declare function uriToExternalPath(uri: UriComponents): string;
+/**
+ * Convert a URI key string (e.g. `"file:///d:/project"`) to a clean external
+ * path suitable for MCP DTOs and CLI output.
+ *
+ * Inverse of `uriKey()` when the input was produced from a `file://` UriComponents.
+ * Non-file URIs are returned as-is (no scheme stripping).
+ */
+export declare function externalPathFromString(uriKeyStr: string): string;
+/** Parse a URI key string back into UriComponents. */
+export declare function parseUriKey(uriKeyStr: string): UriComponents;

package/dist/watchHost.d.ts

@@ -0,0 +1,44 @@
+import type { CoggitProject, UriComponents } from './interfaces';
+import type { AffectedResult, CoggitSnapshot } from './types';
+import { type NormalizedWatchEvent, type WatchBatchRefreshMode, type WatchEventDomain, type WatchFileChangeKind, type WatcherEventApplyResult } from './watchPipeline';
+export interface WatchObservation {
+    readonly domain: WatchEventDomain;
+    readonly uri: UriComponents;
+    readonly kind: WatchFileChangeKind;
+    readonly observedAtMs?: number;
+}
+export type WatchObservationHandler = (observation: WatchObservation) => Promise<WatchHostObservationResult>;
+export interface WatchObserverSubscription {
+    dispose(): void;
+}
+export interface WatchObserver {
+    subscribe(handler: WatchObservationHandler): WatchObserverSubscription;
+}
+export interface WatchHostOptions {
+    readonly projects: readonly CoggitProject[];
+    readonly snapshotProvider: () => CoggitSnapshot | Promise<CoggitSnapshot>;
+    readonly observer?: WatchObserver;
+    readonly now?: () => number;
+}
+export interface WatchHost {
+    start(): void;
+    stop(): void;
+    observe(observation: WatchObservation): Promise<WatchHostObservationResult>;
+}
+export interface WatchHostRefreshIntent {
+    readonly mode: WatchBatchRefreshMode;
+    readonly reason: 'affected-pairs' | 'known-root-unmapped' | 'outside-known-roots' | 'empty-batch' | 'structural-event' | 'config-event';
+    readonly changedPaths: readonly string[];
+    readonly affected?: AffectedResult;
+}
+export interface WatchHostObservationResult {
+    readonly observation: WatchObservation;
+    readonly generation: number;
+    readonly delivered: true;
+    readonly matchedRootIds: readonly string[];
+    readonly matchedProjectCount: number;
+    readonly normalizedEvent?: NormalizedWatchEvent;
+    readonly applyResult?: WatcherEventApplyResult;
+    readonly refresh: WatchHostRefreshIntent;
+}
+export declare function createWatchHost(options: WatchHostOptions): WatchHost;

package/dist/watchPipeline.d.ts

@@ -0,0 +1,31 @@
+import type { CoggitProject, UriComponents } from './interfaces';
+import type { AffectedResult, CoggitSnapshot } from './types';
+export type WatchFileChangeKind = 'change' | 'create' | 'delete';
+export type WatchEventDomain = 'source' | 'cognition' | 'config';
+export type WatchRefreshMode = 'full' | 'partial';
+export type WatchBatchRefreshMode = WatchRefreshMode | 'none';
+export interface NormalizedWatchEvent {
+    readonly domain: WatchEventDomain;
+    readonly uri: UriComponents;
+    readonly kind: WatchFileChangeKind;
+    readonly generation: number;
+    readonly observedAtMs?: number;
+}
+export interface WatcherEventApplyResult {
+    readonly domain: WatchEventDomain;
+    readonly kind: WatchFileChangeKind;
+    readonly generation: number;
+    readonly projectCount: number;
+    readonly sourceObservationCount: number;
+    readonly directoryObservationCount: number;
+    readonly passiveAcceptanceCount: number;
+}
+export interface WatchRefreshRoute {
+    readonly mode: WatchBatchRefreshMode;
+    readonly reason: 'affected-pairs' | 'known-root-unmapped' | 'outside-known-roots' | 'empty-batch';
+    readonly changedPaths: readonly string[];
+    readonly affected: AffectedResult;
+}
+export declare function selectWatchRefreshMode(kind: WatchFileChangeKind, hasMappingIndex: boolean): WatchRefreshMode;
+export declare function planWatchRefresh(snapshot: CoggitSnapshot, changedUris: readonly UriComponents[]): WatchRefreshRoute;
+export declare function applyWatchEventToProjects(projects: readonly CoggitProject[], event: NormalizedWatchEvent): Promise<WatcherEventApplyResult>;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@coggit/core",
+  "version": "0.2.0",
+  "description": "CogGit core kernel: source/cognition freshness semantics, registry, snapshot, status, and operations.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CatheadOwl/coggit.git",
+    "directory": "packages/core"
+  },
+  "main": "./dist/public.js",
+  "types": "./dist/public.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./dist/public.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/mocha": "^10.0.10",
+    "@types/node": "24.x",
+    "esbuild": "^0.28.1",
+    "typescript": "^6.0.3",
+    "yaml": "^2.8.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && node build.js",
+    "check-types": "tsc -b",
+    "watch": "node build.js --watch"
+  }
+}