Class: FsJsonlLessonStore

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:66

Crash-safe hybrid filesystem LessonStore implementation (fs.jsonlLessonStore, SPEC.md §4.3).

Resolves definitionsDir, statsPath, and lockFile against the immutable host repository root (Invariant 5), writes immutable <definitionsDir>/<lessonId>.json definition files on admit(), and updates mutable telemetry counters in statsPath under a PQueue({ concurrency: 1 }) queue combined with @paraharness/lockfile and write-file-atomic.

Implements

• LessonStore

Constructors

Constructor

new FsJsonlLessonStore(node, hostRoot?): FsJsonlLessonStore;

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:84

Initializes an FsJsonlLessonStore bound to the host repository root (SPEC.md Invariant 5).

Resolves all configured store paths relative to hostRoot (defaulting to process.cwd()).

Parameters

Parameter	Type	Description
node	FsJsonlLessonStoreNode	Passive lesson store AST node.
hostRoot?	string	Optional explicit host repository root directory.

Returns

FsJsonlLessonStore

Methods

admit()

admit(lesson): Promise<string>;

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:135

Admits a distilled lesson by writing an immutable <definitionsDir>/<lessonId>.json file.

Deduplicates identical (partition, directive) pairs and initializes telemetry counters in statsPath.

Parameters

Parameter	Type	Description
lesson	FsAdmitLessonParams	Lesson definition to admit.

Returns

Promise<string>

Assigned content-addressed lessonId.

Implementation of

LessonStore.admit

---

markSignalEmitted()

markSignalEmitted(
   lessonId, 
   signalId, 
   emittedAt
): Promise<void>;

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:202

Persists the ISO-8601 emission timestamp for signalId on lessonId in statsPath.

Enforces .emitSignalWhen() cooldowns across process restarts (SPEC.md §3.4.3).

Parameters

Parameter	Type	Description
lessonId	string	Lesson identifier.
signalId	string	Signal identifier.
emittedAt	string	ISO-8601 emission timestamp.

Returns

Promise<void>

Resolves when statsPath is atomically updated.

Implementation of

LessonStore.markSignalEmitted

---

queryCandidates()

queryCandidates(req): Promise<readonly LessonRecord[]>;

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:115

Queries non-retired candidate lessons and populates relevanceScore in [0, 1] via MiniSearch.

Orders returned candidate lessons deterministically by descending relevanceScore and id.

Parameters

Parameter	Type	Description
req	FsQueryCandidatesParams	Query text and active partitions.

Returns

Promise<readonly LessonRecord[]>

Frozen array of candidate lesson records.

Implementation of

LessonStore.queryCandidates

---

recordOutcomes()

recordOutcomes(outcomes): Promise<readonly LessonRecord[]>;

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:157

Appends deduplicated step execution outcomes to statsPath and returns the updated lesson records.

Increments totalCleanPasses and totalViolated counters without touching <definitionsDir>/<lessonId>.json.

Parameters

Parameter	Type	Description
outcomes	readonly FsRecordOutcomeParams[]	Batch of lesson outcomes.

Returns

Promise<readonly LessonRecord[]>

Updated lesson records for the affected lessons.

Implementation of

LessonStore.recordOutcomes

---

retire()

retire(lessonIds): Promise<void>;

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:222

Permanently retires lessonIds in statsPath so subsequent queryCandidates() calls exclude them.

Preserves historical <definitionsDir>/<lessonId>.json audit files while marking retired: true.

Parameters

Parameter	Type	Description
lessonIds	readonly string[]	Lesson identifiers to retire.

Returns

Promise<void>

Resolves when statsPath is atomically updated.

Implementation of

LessonStore.retire

---

syncCreationEpochsForRuns()

syncCreationEpochsForRuns(runIds, updatedEpochs): Promise<void>;

Defined in: fs/src/stores/fs-jsonl-lesson-store.ts:177

Aligns epochAtCreation overrides in statsPath for lessons created by runIds.

Keeps <definitionsDir>/<lessonId>.json 100% immutable while updating statsPath (SPEC.md §4.3).

Parameters

Parameter	Type	Description
runIds	readonly string[]	Run IDs whose topology overlays committed.
updatedEpochs	ReadonlyMap<string, number>	Map of partitionId to committed base epoch.

Returns

Promise<void>

Resolves when statsPath is atomically updated.

Implementation of

LessonStore.syncCreationEpochsForRuns