Interface: LessonStore

Defined in: ports/lesson-store.ts:9

Runtime storage port for querying, admitting, scoring, and retiring empirical lessons.

Always resolves file or database paths against the immutable host process root (Invariant 5).

Methods

admit()

admit(lesson): Promise<string>;

Defined in: ports/lesson-store.ts:33

Persists a newly distilled lesson into the store and returns its assigned lessonId.

Deduplicates identical (partition, directive) entries and records epochAtCreation and createdByRunId.

Parameters

Parameter	Type	Description
lesson	{ createdByRunId?: string; directive: string; epochAtCreation: number; partition?: string; }	Lesson definition to admit.
lesson.createdByRunId?	string	-
lesson.directive	string	-
lesson.epochAtCreation	number	-
lesson.partition?	string	-

Returns

Promise<string>

Newly assigned or content-addressed lessonId.

---

markSignalEmitted()

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

Defined in: ports/lesson-store.ts:79

Records the ISO-8601 timestamp when a promotion signal was emitted for lessonId.

Persists the timestamp in signalLastEmittedAt[signalId] to enforce cooldownHours across restarts.

Parameters

Parameter	Type	Description
lessonId	string	Identifier of the lesson that triggered the signal.
signalId	string	Identifier of the emitted signal.
emittedAt	string	ISO-8601 timestamp string of the emission.

Returns

Promise<void>

Resolves when the cooldown timestamp is persisted.

---

queryCandidates()

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

Defined in: ports/lesson-store.ts:19

Queries non-retired candidate lessons relevant to queryText and partitions.

Computes normalized text similarity relevanceScore in [0, 1] for each candidate lesson.

Parameters

Parameter	Type	Description
req	{ partitions: readonly string[]; queryText: string; }	Search query and active partitions.
req.partitions	readonly string[]	-
req.queryText	string	-

Returns

Promise<readonly LessonRecord[]>

Candidate lesson records with relevanceScore populated.

---

recordOutcomes()

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

Defined in: ports/lesson-store.ts:49

Appends deduplicated step execution outcomes to the specified lessons and returns their updated records.

Increments totalCleanPasses or totalViolated and updates each lesson's recentOutcomes window.

Parameters

Parameter	Type	Description
outcomes	readonly object[]	Batch of (lessonId, outcome) pairs.

Returns

Promise<readonly LessonRecord[]>

Updated lesson records reflecting the recorded outcomes.

---

retire()

retire(lessonIds): Promise<void>;

Defined in: ports/lesson-store.ts:90

Permanently retires lessons that breached violation or low clean-pass-rate thresholds.

Excludes retired lessons from all subsequent queryCandidates() recalls.

Parameters

Parameter	Type	Description
lessonIds	readonly string[]	Identifiers of lessons to retire.

Returns

Promise<void>

Resolves when all specified lessons are retired.

---

syncCreationEpochsForRuns()

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

Defined in: ports/lesson-store.ts:63

Aligns epochAtCreation for lessons created by runIds when their topology overlays commit to the base store.

Prevents lessons authored in a run that also updated a partition's contract from being falsely penalized for epoch drift.

Parameters

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

Returns

Promise<void>

Resolves when creation epochs are synchronized.