Class: PostgresLessonStore

Defined in: postgres/src/stores/postgres-lesson-store.ts:28

PostgreSQL implementation of the @paraharness/core LessonStore runtime port.

Persists distilled empirical lessons, computes normalized BM25/fuzzy relevance scores $R(L, Q) \in [0, 1]$, tracks 4-state execution outcome windows, aligns creation epochs on overlay commit, and retires lessons.

Implements

• LessonStore

Constructors

Constructor

new PostgresLessonStore(client): PostgresLessonStore;

Defined in: postgres/src/stores/postgres-lesson-store.ts:43

Initializes a PostgresLessonStore backed by a PostgresQueryClient, pg.Pool, or connection URI string.

Defers DDL execution until the first store operation so constructing the store performs zero I/O.

Parameters

Parameter	Type	Description
client	| string | PostgresQueryClient | Pool	PostgreSQL query client, pg.Pool, or connection URI.

Returns

PostgresLessonStore

Methods

admit()

admit(lesson): Promise<string>;

Defined in: postgres/src/stores/postgres-lesson-store.ts:86

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	AdmitLessonParams	Lesson definition to admit.

Returns

Promise<string>

Newly assigned or content-addressed lessonId.

Implementation of

LessonStore.admit

---

markSignalEmitted()

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

Defined in: postgres/src/stores/postgres-lesson-store.ts:143

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.

Implementation of

LessonStore.markSignalEmitted

---

queryCandidates()

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

Defined in: postgres/src/stores/postgres-lesson-store.ts:73

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

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

Parameters

Parameter	Type	Description
req	QueryPgLessonCandidatesParams	Search query and active partitions.

Returns

Promise<readonly LessonRecord[]>

Candidate lesson records with relevanceScore populated.

Implementation of

LessonStore.queryCandidates

---

recordOutcomes()

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

Defined in: postgres/src/stores/postgres-lesson-store.ts:101

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 PgLessonOutcomeEntryParams[]	Batch of (lessonId, outcome) pairs.

Returns

Promise<readonly LessonRecord[]>

Updated lesson records reflecting the recorded outcomes.

Implementation of

LessonStore.recordOutcomes

---

retire()

retire(lessonIds): Promise<void>;

Defined in: postgres/src/stores/postgres-lesson-store.ts:160

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.

Implementation of

LessonStore.retire

---

syncCreationEpochsForRuns()

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

Defined in: postgres/src/stores/postgres-lesson-store.ts:121

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.

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.

Implementation of

LessonStore.syncCreationEpochsForRuns