Data Model and Types

Relevant Source Files

• src/cli/adopt.ts
• src/index.ts
• src/types.ts
• test/types-difficulty.test.ts

This section serves as a technical reference for the TypeScript interfaces and type definitions that form the backbone of the PALEE system. All core types are defined in src/types.ts.

The data model is designed to be serialized into Markdown frontmatter or JSON files, providing a bridge between the "Natural Language Space" (Markdown notes) and the "Code Entity Space" (the Engine Core).

System Data Mapping

The following diagram illustrates how high-level system concepts map to specific code entities within the src/types.ts file.

Conceptual to Code Entity Mapping

Sources: src/types.ts

---

Core Learning Schema

The learning model is centered around the Topic interface, which represents the state of a single note within the Obsidian vault.

• Topic: The primary unit of learning, containing metadata, mastery status, and scheduling data src/types.ts.
• Assessment: A four-pillar model (Conceptual, Practical, Debug, Feynman) used to track mastery levels src/types.ts.
• Review: Contains the Spaced Repetition System (SRS) state, including ease factor, repetition count, lapses, and next due date src/types.ts.
• Difficulty: Union type 'beginner' | 'intermediate' | 'advanced' src/types.ts.

For details on how these fields are used in the SRS algorithm and frontmatter, see Topic and Assessment Schema.

Sources: src/types.ts

---

Difficulty Normalization

PALEE uses a strict Difficulty union type: 'beginner' | 'intermediate' | 'advanced' src/types.ts. To handle varied user input from the CLI or Markdown frontmatter, the system provides a normalizeDifficulty utility.

Input Type	Value	Result
String	"beginner", "BEGINNER", " beginner "	'beginner'
Numeric	1 or "1"	'beginner'
Numeric	2, 3 or "2", "3"	'intermediate'
Numeric	4, 5 or "4", "5"	'advanced'
Fallback	null, undefined, "expert"	'intermediate'

Sources: src/types.tstest/types-difficulty.test.ts

---

Session and Memory Types

Session management tracks active learning periods, maintains crash-resilient session draft checkpoints, and persists hot working memory to bridge study sessions.

Discriminated Union Session Types

In PALEE, learning sessions exist in two distinct lifecycle states represented as TypeScript discriminated unions in src/types.ts:

1. Runtime Snapshot (Session = CompletedSession | DraftSession):
   • CompletedSession: Represents a concluded study session with recorded duration and timestamps.
   • DraftSession: Represents an active, in-progress checkpoint before the user finishes or saves their study session.
2. Persistent Storage Record (SessionRecord = CompletedSessionRecord | DraftSessionRecord):
   • CompletedSessionRecord: Frontmatter schema serialized into permanent session notes (.palee/sessions/S-*.md).
   • DraftSessionRecord: Frontmatter schema serialized into temporary session draft files (.palee/sessions/DRAFT-*.md).

// Base shared metadata
export interface BaseSession {
  palee_schema: number;
  session_id: string;   // e.g. 'S-20260830T012000-A1B2' or 'DRAFT-S-*'
  topic_id: string;     // target topic palee_id
  started_at: string;   // ISO 8601 timestamp
}

// Completed session: ended_at is a non-null ISO 8601 string
export interface CompletedSession extends BaseSession {
  status: 'completed';
  ended_at: string;
}

// Draft session: ended_at is strictly null
export interface DraftSession extends BaseSession {
  status: 'draft';
  ended_at: null;
}

export type Session = CompletedSession | DraftSession;

Discriminator & Typing Contract

Type Interface	Discriminator (status)	ended_at Contract	session_id Pattern	Purpose
CompletedSession / CompletedSessionRecord	'completed'	string (ISO 8601 timestamp)	S-YYYYMMDDTHHMMSS-XXXXXXXX	Persisted, finalized learning session record
DraftSession / DraftSessionRecord	'draft'	null (strictly null)	DRAFT-S-XXXXXXXX	Live checkpoint for recovery during interrupted CLI sessions

Type Narrowing Invariant

Because status acts as the discriminant field, TypeScript automatically narrows the type of ended_at and associated properties:

function formatSessionSummary(session: Session): string {
  if (session.status === 'completed') {
    // TypeScript knows session is CompletedSession: ended_at is string
    return `Session ${session.session_id} finished at ${session.ended_at}`;
  }
  // TypeScript knows session is DraftSession: ended_at is null
  return `Draft ${session.session_id} in progress (started ${session.started_at})`;
}

Memory and Synchronization Types

• DraftRecoveryAction: Union of user choices when resuming or processing an unfinished draft session ('resume' | 'save' | 'discard' | 'ignore') src/types.ts.
• HotMemoryData: Represents the runtime state stored in .palee/hot.md, caching memory_id, active_topic, last_session, and updated_at src/types.ts.
• LockData: Payload written into .palee/locks/<hash>.lockdir/<lock_id>.json containing lock_id, target, pid, hostname, and created_at src/types.ts.

Sources: src/types.tssrc/storage/memory.ts

---

Infrastructure and CLI Types

These types support the internal workings of the storage layer and the command-line interface.

• PaleeConfig: Defines user environment settings in config.json, including vaultPath, aiProvider, and model. The file is read from $PALEE_CONFIG_DIR when set — otherwise the per-user %LOCALAPPDATA%\palee on Windows, the per-user ~/.config/palee elsewhere — so each user account keeps its own default vault path, provider and model src/types.tssrc/cli/config.ts.
• CacheEntry<T>: Generic schema for in-memory file cache entries tracking mtime, size, fingerprint, data, and lastVerified src/types.ts.
• FrontmatterResult: Result object from CST parsing holding frontmatter, body, raw, doc, and optional error src/types.ts.
• ValidationError & ValidationResult: Vault integrity error representations (duplicate_id, missing_dependency, cycle) and aggregated validation status src/types.ts.
• CLI Options: Specific argument interfaces including AdoptOptions, NextOptions, PlanOptions, DashboardOptions, ProgressOptions, ValidateOptions, SessionOptions, and RoadmapOptions src/types.ts.

For details on configuration paths and CLI flags, see Configuration and CLI Option Types.

Sources: src/types.ts

---

Dependency Graph Model

The dependency engine uses the TopicNode interface to build a Directed Acyclic Graph (DAG) of the vault's topics.

Graph Data Flow

Sources: src/types.ts

Gating semantics (ADR cross-references). How a depends_on list is interpreted is not a plain graph walk: the additive depends_on_source field makes toc/tie edges advisory (never gating) while an absent or unrecognized label gates fail-closed — the binding rule is ADR-0009. Identity of a node across renames (palee_id, the value a rename preserves) is ADR-0015, and the storage-normalization of depends_on/dependencies with byte-fidelity on any frontmatter rewrite is ADR-0016.