@paraharness/fs 0.0.0-stage → 0.1.0

package/dist/stores/fs-jsonl-lesson-store.d.ts

@@ -0,0 +1,135 @@
+import type { FsJsonlLessonStoreNode, LessonOutcome, LessonRecord, LessonStore } from '@paraharness/core';
+/**
+ * Query parameters for {@link FsJsonlLessonStore.queryCandidates}.
+ */
+export interface FsQueryCandidatesParams {
+    /** Search query text extracted from actor input. */
+    readonly queryText: string;
+    /** Active task partitions. */
+    readonly partitions: readonly string[];
+}
+/**
+ * Admission parameters for {@link FsJsonlLessonStore.admit}.
+ */
+export interface FsAdmitLessonParams {
+    /** Optional topology partition identifier. */
+    readonly partition?: string;
+    /** Preventative or prescriptive directive text. */
+    readonly directive: string;
+    /** Partition contract epoch at creation. */
+    readonly epochAtCreation: number;
+    /** Optional run identifier that admitted the lesson. */
+    readonly createdByRunId?: string;
+}
+/**
+ * Single lesson outcome entry for {@link FsJsonlLessonStore.recordOutcomes}.
+ */
+export interface FsRecordOutcomeParams {
+    /** Target lesson identifier. */
+    readonly lessonId: string;
+    /** Recorded execution outcome (`'clean_pass'` or `'violated'`). */
+    readonly outcome: LessonOutcome;
+}
+/**
+ * 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`.
+ */
+export declare class FsJsonlLessonStore implements LessonStore {
+    /** Absolute host-root directory path storing immutable `<lessonId>.json` definitions. */
+    private readonly definitionsDirPath;
+    /** Absolute host-root file path storing mutable lesson telemetry counters. */
+    private readonly statsFilePath;
+    /** Absolute host-root advisory lockfile path. */
+    private readonly lockFilePath;
+    /** Serialized in-process async mutex queue (`concurrency: 1`). */
+    private readonly mutexQueue;
+    /**
+     * 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()`).
+     *
+     * @param {FsJsonlLessonStoreNode} node                     - Passive lesson store AST node.
+     * @param {string}                 [hostRoot=process.cwd()] - Optional explicit host repository root directory.
+     */
+    constructor(node: FsJsonlLessonStoreNode, hostRoot?: string);
+    /**
+     * Enqueues `operation` onto the in-process `PQueue` (`concurrency: 1`) and acquires the advisory file lock.
+     *
+     * Guarantees strict serialization across concurrent calls within the process and across processes.
+     *
+     * @template TResult Result type of the locked operation.
+     *
+     * @param {() => Promise<TResult>} operation - Critical section callback.
+     *
+     * @returns {Promise<TResult>} Result returned by `operation`.
+     */
+    private enqueueLocked;
+    /**
+     * Queries non-retired candidate lessons and populates `relevanceScore` in `[0, 1]` via `MiniSearch`.
+     *
+     * Orders returned candidate lessons deterministically by descending `relevanceScore` and `id`.
+     *
+     * @param {FsQueryCandidatesParams} req - Query text and active partitions.
+     *
+     * @returns {Promise<readonly LessonRecord[]>} Frozen array of candidate lesson records.
+     */
+    queryCandidates(req: FsQueryCandidatesParams): Promise<readonly LessonRecord[]>;
+    /**
+     * Admits a distilled lesson by writing an immutable `<definitionsDir>/<lessonId>.json` file.
+     *
+     * Deduplicates identical `(partition, directive)` pairs and initializes telemetry counters in `statsPath`.
+     *
+     * @param {FsAdmitLessonParams} lesson - Lesson definition to admit.
+     *
+     * @returns {Promise<string>} Assigned content-addressed `lessonId`.
+     */
+    admit(lesson: FsAdmitLessonParams): Promise<string>;
+    /**
+     * Appends deduplicated step execution outcomes to `statsPath` and returns the updated lesson records.
+     *
+     * Increments `totalCleanPasses` and `totalViolated` counters without touching `<definitionsDir>/<lessonId>.json`.
+     *
+     * @param {readonly FsRecordOutcomeParams[]} outcomes - Batch of lesson outcomes.
+     *
+     * @returns {Promise<readonly LessonRecord[]>} Updated lesson records for the affected lessons.
+     */
+    recordOutcomes(outcomes: readonly FsRecordOutcomeParams[]): Promise<readonly LessonRecord[]>;
+    /**
+     * Aligns `epochAtCreation` overrides in `statsPath` for lessons created by `runIds`.
+     *
+     * Keeps `<definitionsDir>/<lessonId>.json` 100% immutable while updating `statsPath` (`SPEC.md` §4.3).
+     *
+     * @param {readonly string[]}           runIds        - Run IDs whose topology overlays committed.
+     * @param {ReadonlyMap<string, number>} updatedEpochs - Map of `partitionId` to committed base epoch.
+     *
+     * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+     */
+    syncCreationEpochsForRuns(runIds: readonly string[], updatedEpochs: ReadonlyMap<string, number>): Promise<void>;
+    /**
+     * Persists the ISO-8601 emission timestamp for `signalId` on `lessonId` in `statsPath`.
+     *
+     * Enforces `.emitSignalWhen()` cooldowns across process restarts (`SPEC.md` §3.4.3).
+     *
+     * @param {string} lessonId  - Lesson identifier.
+     * @param {string} signalId  - Signal identifier.
+     * @param {string} emittedAt - ISO-8601 emission timestamp.
+     *
+     * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+     */
+    markSignalEmitted(lessonId: string, signalId: string, emittedAt: string): Promise<void>;
+    /**
+     * Permanently retires `lessonIds` in `statsPath` so subsequent `queryCandidates()` calls exclude them.
+     *
+     * Preserves historical `<definitionsDir>/<lessonId>.json` audit files while marking `retired: true`.
+     *
+     * @param {readonly string[]} lessonIds - Lesson identifiers to retire.
+     *
+     * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+     */
+    retire(lessonIds: readonly string[]): Promise<void>;
+}
+//# sourceMappingURL=fs-jsonl-lesson-store.d.ts.map

package/dist/stores/fs-jsonl-lesson-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-jsonl-lesson-store.d.ts","sourceRoot":"","sources":["../../src/stores/fs-jsonl-lesson-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAY3B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,wDAAwD;IACxD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACpD,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAE7D;;;;;;;OAOG;gBACS,IAAI,EAAE,sBAAsB,EAAE,QAAQ,GAAE,MAAsB;IAO1E;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;;;OAQG;IACH,eAAe,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;IAW/E;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAanD;;;;;;;;OAQG;IACH,cAAc,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;IAU5F;;;;;;;;;OASG;IACH,yBAAyB,CACvB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvF;;;;;;;;OAQG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQpD"}

package/dist/stores/fs-jsonl-lesson-store.js

@@ -0,0 +1,155 @@
+import path from 'node:path';
+import PQueue from 'p-queue';
+import { admitLessonToStore, markLessonSignalEmittedInStore, queryActiveLessonCandidates, recordLessonOutcomesInStore, retireLessonsInStore, syncLessonCreationEpochsInStore, } from './internal/fs-jsonl-lesson-file-io.js';
+import { withLessonFileLock } from './internal/fs-lesson-lock-and-atomic-io.js';
+/**
+ * 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`.
+ */
+export class FsJsonlLessonStore {
+    /** Absolute host-root directory path storing immutable `<lessonId>.json` definitions. */
+    definitionsDirPath;
+    /** Absolute host-root file path storing mutable lesson telemetry counters. */
+    statsFilePath;
+    /** Absolute host-root advisory lockfile path. */
+    lockFilePath;
+    /** Serialized in-process async mutex queue (`concurrency: 1`). */
+    mutexQueue = new PQueue({ concurrency: 1 });
+    /**
+     * 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()`).
+     *
+     * @param {FsJsonlLessonStoreNode} node                     - Passive lesson store AST node.
+     * @param {string}                 [hostRoot=process.cwd()] - Optional explicit host repository root directory.
+     */
+    constructor(node, hostRoot = process.cwd()) {
+        const resolvedRoot = path.resolve(hostRoot);
+        this.definitionsDirPath = path.resolve(resolvedRoot, node.definitionsDir);
+        this.statsFilePath = path.resolve(resolvedRoot, node.statsPath);
+        this.lockFilePath = path.resolve(resolvedRoot, node.lockFile);
+    }
+    /**
+     * Enqueues `operation` onto the in-process `PQueue` (`concurrency: 1`) and acquires the advisory file lock.
+     *
+     * Guarantees strict serialization across concurrent calls within the process and across processes.
+     *
+     * @template TResult Result type of the locked operation.
+     *
+     * @param {() => Promise<TResult>} operation - Critical section callback.
+     *
+     * @returns {Promise<TResult>} Result returned by `operation`.
+     */
+    enqueueLocked(operation) {
+        return this.mutexQueue.add(() => withLessonFileLock(this.lockFilePath, operation));
+    }
+    /**
+     * Queries non-retired candidate lessons and populates `relevanceScore` in `[0, 1]` via `MiniSearch`.
+     *
+     * Orders returned candidate lessons deterministically by descending `relevanceScore` and `id`.
+     *
+     * @param {FsQueryCandidatesParams} req - Query text and active partitions.
+     *
+     * @returns {Promise<readonly LessonRecord[]>} Frozen array of candidate lesson records.
+     */
+    queryCandidates(req) {
+        return this.enqueueLocked(() => queryActiveLessonCandidates({
+            definitionsDirPath: this.definitionsDirPath,
+            statsFilePath: this.statsFilePath,
+            queryText: req.queryText,
+            partitions: req.partitions,
+        }));
+    }
+    /**
+     * Admits a distilled lesson by writing an immutable `<definitionsDir>/<lessonId>.json` file.
+     *
+     * Deduplicates identical `(partition, directive)` pairs and initializes telemetry counters in `statsPath`.
+     *
+     * @param {FsAdmitLessonParams} lesson - Lesson definition to admit.
+     *
+     * @returns {Promise<string>} Assigned content-addressed `lessonId`.
+     */
+    admit(lesson) {
+        return this.enqueueLocked(() => admitLessonToStore({
+            definitionsDirPath: this.definitionsDirPath,
+            statsFilePath: this.statsFilePath,
+            partition: lesson.partition,
+            directive: lesson.directive,
+            epochAtCreation: lesson.epochAtCreation,
+            createdByRunId: lesson.createdByRunId,
+        }));
+    }
+    /**
+     * Appends deduplicated step execution outcomes to `statsPath` and returns the updated lesson records.
+     *
+     * Increments `totalCleanPasses` and `totalViolated` counters without touching `<definitionsDir>/<lessonId>.json`.
+     *
+     * @param {readonly FsRecordOutcomeParams[]} outcomes - Batch of lesson outcomes.
+     *
+     * @returns {Promise<readonly LessonRecord[]>} Updated lesson records for the affected lessons.
+     */
+    recordOutcomes(outcomes) {
+        return this.enqueueLocked(() => recordLessonOutcomesInStore({
+            definitionsDirPath: this.definitionsDirPath,
+            statsFilePath: this.statsFilePath,
+            outcomes,
+        }));
+    }
+    /**
+     * Aligns `epochAtCreation` overrides in `statsPath` for lessons created by `runIds`.
+     *
+     * Keeps `<definitionsDir>/<lessonId>.json` 100% immutable while updating `statsPath` (`SPEC.md` §4.3).
+     *
+     * @param {readonly string[]}           runIds        - Run IDs whose topology overlays committed.
+     * @param {ReadonlyMap<string, number>} updatedEpochs - Map of `partitionId` to committed base epoch.
+     *
+     * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+     */
+    syncCreationEpochsForRuns(runIds, updatedEpochs) {
+        return this.enqueueLocked(() => syncLessonCreationEpochsInStore({
+            definitionsDirPath: this.definitionsDirPath,
+            statsFilePath: this.statsFilePath,
+            runIds,
+            updatedEpochs,
+        }));
+    }
+    /**
+     * Persists the ISO-8601 emission timestamp for `signalId` on `lessonId` in `statsPath`.
+     *
+     * Enforces `.emitSignalWhen()` cooldowns across process restarts (`SPEC.md` §3.4.3).
+     *
+     * @param {string} lessonId  - Lesson identifier.
+     * @param {string} signalId  - Signal identifier.
+     * @param {string} emittedAt - ISO-8601 emission timestamp.
+     *
+     * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+     */
+    markSignalEmitted(lessonId, signalId, emittedAt) {
+        return this.enqueueLocked(() => markLessonSignalEmittedInStore({
+            statsFilePath: this.statsFilePath,
+            lessonId,
+            signalId,
+            emittedAt,
+        }));
+    }
+    /**
+     * Permanently retires `lessonIds` in `statsPath` so subsequent `queryCandidates()` calls exclude them.
+     *
+     * Preserves historical `<definitionsDir>/<lessonId>.json` audit files while marking `retired: true`.
+     *
+     * @param {readonly string[]} lessonIds - Lesson identifiers to retire.
+     *
+     * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+     */
+    retire(lessonIds) {
+        return this.enqueueLocked(() => retireLessonsInStore({
+            statsFilePath: this.statsFilePath,
+            lessonIds,
+        }));
+    }
+}
+//# sourceMappingURL=fs-jsonl-lesson-store.js.map

package/dist/stores/fs-jsonl-lesson-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-jsonl-lesson-store.js","sourceRoot":"","sources":["../../src/stores/fs-jsonl-lesson-store.ts"],"names":[],"mappings":"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"}

package/dist/stores/internal/fs-jsonl-lesson-file-io.d.ts

@@ -0,0 +1,129 @@
+import type { LessonOutcome, LessonRecord } from '@paraharness/core';
+/**
+ * Parameters for {@link queryActiveLessonCandidates}.
+ */
+export interface QueryActiveLessonCandidatesParams {
+    /** Absolute path to the definitions directory. */
+    readonly definitionsDirPath: string;
+    /** Absolute path to the telemetry stats file. */
+    readonly statsFilePath: string;
+    /** Search query text. */
+    readonly queryText: string;
+    /** Active task partitions. */
+    readonly partitions: readonly string[];
+}
+/**
+ * Parameters for {@link admitLessonToStore}.
+ */
+export interface AdmitLessonToStoreParams {
+    /** Absolute path to the definitions directory. */
+    readonly definitionsDirPath: string;
+    /** Absolute path to the telemetry stats file. */
+    readonly statsFilePath: string;
+    /** Optional partition identifier. */
+    readonly partition?: string;
+    /** Preventative or prescriptive directive text. */
+    readonly directive: string;
+    /** Partition contract epoch at creation. */
+    readonly epochAtCreation: number;
+    /** Optional run identifier that admitted the lesson. */
+    readonly createdByRunId?: string;
+}
+/**
+ * Parameters for {@link recordLessonOutcomesInStore}.
+ */
+export interface RecordLessonOutcomesInStoreParams {
+    /** Absolute path to the definitions directory. */
+    readonly definitionsDirPath: string;
+    /** Absolute path to the telemetry stats file. */
+    readonly statsFilePath: string;
+    /** Batch of lesson outcomes to record. */
+    readonly outcomes: ReadonlyArray<{
+        readonly lessonId: string;
+        readonly outcome: LessonOutcome;
+    }>;
+}
+/**
+ * Parameters for {@link syncLessonCreationEpochsInStore}.
+ */
+export interface SyncLessonCreationEpochsInStoreParams {
+    /** Absolute path to the definitions directory. */
+    readonly definitionsDirPath: string;
+    /** Absolute path to the telemetry stats file. */
+    readonly statsFilePath: string;
+    /** Run IDs whose topology overlays committed. */
+    readonly runIds: readonly string[];
+    /** Map of `partitionId` to committed base epoch. */
+    readonly updatedEpochs: ReadonlyMap<string, number>;
+}
+/**
+ * Parameters for {@link markLessonSignalEmittedInStore}.
+ */
+export interface MarkLessonSignalEmittedInStoreParams {
+    /** Absolute path to the telemetry stats file. */
+    readonly statsFilePath: string;
+    /** Lesson identifier. */
+    readonly lessonId: string;
+    /** Signal identifier. */
+    readonly signalId: string;
+    /** ISO-8601 emission timestamp. */
+    readonly emittedAt: string;
+}
+/**
+ * Parameters for {@link retireLessonsInStore}.
+ */
+export interface RetireLessonsInStoreParams {
+    /** Absolute path to the telemetry stats file. */
+    readonly statsFilePath: string;
+    /** Lesson identifiers to mark retired. */
+    readonly lessonIds: readonly string[];
+}
+/**
+ * Queries non-retired lesson definitions, scores them via `MiniSearch`, and returns sorted `LessonRecord` candidates.
+ *
+ * @param {QueryActiveLessonCandidatesParams} params - Store paths, query text, and active partitions.
+ *
+ * @returns {Promise<readonly LessonRecord[]>} Frozen sorted array of active candidate lesson records.
+ */
+export declare function queryActiveLessonCandidates(params: QueryActiveLessonCandidatesParams): Promise<readonly LessonRecord[]>;
+/**
+ * Writes an immutable `<definitionsDir>/<lessonId>.json` file (if absent) and initializes telemetry counters in `statsPath`.
+ *
+ * @param {AdmitLessonToStoreParams} params - Store paths and lesson admission metadata.
+ *
+ * @returns {Promise<string>} Content-addressed `lessonId`.
+ */
+export declare function admitLessonToStore(params: AdmitLessonToStoreParams): Promise<string>;
+/**
+ * Appends deduplicated step execution outcomes to `statsPath` and returns updated `LessonRecord` items.
+ *
+ * @param {RecordLessonOutcomesInStoreParams} params - Store paths and outcome batch.
+ *
+ * @returns {Promise<readonly LessonRecord[]>} Frozen array of updated lesson records.
+ */
+export declare function recordLessonOutcomesInStore(params: RecordLessonOutcomesInStoreParams): Promise<readonly LessonRecord[]>;
+/**
+ * Aligns `epochAtCreation` overrides in `statsPath` for lessons created by `params.runIds`.
+ *
+ * @param {SyncLessonCreationEpochsInStoreParams} params - Store paths, committed run IDs, and updated partition epochs.
+ *
+ * @returns {Promise<void>} Resolves when `statsPath` is updated.
+ */
+export declare function syncLessonCreationEpochsInStore(params: SyncLessonCreationEpochsInStoreParams): Promise<void>;
+/**
+ * Persists the ISO-8601 emission timestamp for `params.signalId` on `params.lessonId` in `statsPath`.
+ *
+ * @param {MarkLessonSignalEmittedInStoreParams} params - Stats file path, lesson ID, signal ID, and timestamp.
+ *
+ * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+ */
+export declare function markLessonSignalEmittedInStore(params: MarkLessonSignalEmittedInStoreParams): Promise<void>;
+/**
+ * Marks `params.lessonIds` as `retired: true` in `statsPath` while preserving immutable definition files.
+ *
+ * @param {RetireLessonsInStoreParams} params - Stats file path and lesson IDs to retire.
+ *
+ * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+ */
+export declare function retireLessonsInStore(params: RetireLessonsInStoreParams): Promise<void>;
+//# sourceMappingURL=fs-jsonl-lesson-file-io.d.ts.map

package/dist/stores/internal/fs-jsonl-lesson-file-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-jsonl-lesson-file-io.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/fs-jsonl-lesson-file-io.ts"],"names":[],"mappings":"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"}

package/dist/stores/internal/fs-jsonl-lesson-file-io.js

@@ -0,0 +1,197 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { atomicWriteJsonFile, readAllLessonDefinitions, readLessonStatsFile, } from './fs-lesson-lock-and-atomic-io.js';
+import { compareLessonRecordsByRelevance, computeLessonId, mergeDefinitionAndStats, scoreLessonsWithMiniSearch, } from './fs-lesson-relevance.js';
+/**
+ * Queries non-retired lesson definitions, scores them via `MiniSearch`, and returns sorted `LessonRecord` candidates.
+ *
+ * @param {QueryActiveLessonCandidatesParams} params - Store paths, query text, and active partitions.
+ *
+ * @returns {Promise<readonly LessonRecord[]>} Frozen sorted array of active candidate lesson records.
+ */
+export async function queryActiveLessonCandidates(params) {
+    const definitions = await readAllLessonDefinitions(params.definitionsDirPath);
+    const statsMap = await readLessonStatsFile(params.statsFilePath);
+    const activeDefinitions = [];
+    for (const def of definitions) {
+        if (statsMap[def.id]?.retired !== true)
+            activeDefinitions.push(def);
+    }
+    const scoresById = scoreLessonsWithMiniSearch(params.queryText, activeDefinitions, new Set(params.partitions));
+    const records = [];
+    for (const def of activeDefinitions) {
+        records.push(mergeDefinitionAndStats(def, statsMap[def.id], scoresById.get(def.id) ?? 0));
+    }
+    records.sort(compareLessonRecordsByRelevance);
+    return Object.freeze(records);
+}
+/**
+ * Writes an immutable `<definitionsDir>/<lessonId>.json` file (if absent) and initializes telemetry counters in `statsPath`.
+ *
+ * @param {AdmitLessonToStoreParams} params - Store paths and lesson admission metadata.
+ *
+ * @returns {Promise<string>} Content-addressed `lessonId`.
+ */
+export async function admitLessonToStore(params) {
+    const lessonId = computeLessonId(params.partition, params.directive);
+    const defPath = path.join(params.definitionsDirPath, `${lessonId}.json`);
+    if (!existsSync(defPath)) {
+        const defRecord = Object.freeze({
+            id: lessonId,
+            partition: params.partition,
+            directive: params.directive,
+            epochAtCreation: params.epochAtCreation,
+            createdByRunId: params.createdByRunId,
+        });
+        await atomicWriteJsonFile(defPath, defRecord);
+    }
+    const statsMap = await readLessonStatsFile(params.statsFilePath);
+    if (statsMap[lessonId] === undefined) {
+        statsMap[lessonId] = {
+            recentOutcomes: [],
+            totalCleanPasses: 0,
+            totalViolated: 0,
+            epochAtCreation: undefined,
+            signalLastEmittedAt: undefined,
+            retired: false,
+        };
+        await atomicWriteJsonFile(params.statsFilePath, statsMap);
+    }
+    return lessonId;
+}
+/**
+ * Appends deduplicated step execution outcomes to `statsPath` and returns updated `LessonRecord` items.
+ *
+ * @param {RecordLessonOutcomesInStoreParams} params - Store paths and outcome batch.
+ *
+ * @returns {Promise<readonly LessonRecord[]>} Frozen array of updated lesson records.
+ */
+export async function recordLessonOutcomesInStore(params) {
+    const definitions = await readAllLessonDefinitions(params.definitionsDirPath);
+    const defById = new Map();
+    for (const def of definitions)
+        defById.set(def.id, def);
+    const statsMap = await readLessonStatsFile(params.statsFilePath);
+    const touchedIds = new Set();
+    const mutableOutcomesById = new Map();
+    for (const outcomeEntry of params.outcomes) {
+        const prev = statsMap[outcomeEntry.lessonId] ?? {
+            recentOutcomes: [],
+            totalCleanPasses: 0,
+            totalViolated: 0,
+        };
+        let outcomeList = mutableOutcomesById.get(outcomeEntry.lessonId);
+        if (outcomeList === undefined) {
+            outcomeList = Array.from(prev.recentOutcomes);
+            mutableOutcomesById.set(outcomeEntry.lessonId, outcomeList);
+        }
+        outcomeList.push(outcomeEntry.outcome);
+        statsMap[outcomeEntry.lessonId] = {
+            recentOutcomes: outcomeList,
+            totalCleanPasses: prev.totalCleanPasses + (outcomeEntry.outcome === 'clean_pass' ? 1 : 0),
+            totalViolated: prev.totalViolated + (outcomeEntry.outcome === 'violated' ? 1 : 0),
+            epochAtCreation: prev.epochAtCreation,
+            signalLastEmittedAt: prev.signalLastEmittedAt,
+            retired: prev.retired,
+        };
+        touchedIds.add(outcomeEntry.lessonId);
+    }
+    await atomicWriteJsonFile(params.statsFilePath, statsMap);
+    const updated = [];
+    for (const id of touchedIds) {
+        const def = defById.get(id);
+        if (def !== undefined)
+            updated.push(mergeDefinitionAndStats(def, statsMap[id]));
+    }
+    return Object.freeze(updated);
+}
+/**
+ * Aligns `epochAtCreation` overrides in `statsPath` for lessons created by `params.runIds`.
+ *
+ * @param {SyncLessonCreationEpochsInStoreParams} params - Store paths, committed run IDs, and updated partition epochs.
+ *
+ * @returns {Promise<void>} Resolves when `statsPath` is updated.
+ */
+export async function syncLessonCreationEpochsInStore(params) {
+    if (params.runIds.length === 0 || params.updatedEpochs.size === 0)
+        return;
+    const runIdSet = new Set(params.runIds);
+    const definitions = await readAllLessonDefinitions(params.definitionsDirPath);
+    const statsMap = await readLessonStatsFile(params.statsFilePath);
+    let mutated = false;
+    for (const def of definitions) {
+        if (def.createdByRunId === undefined ||
+            !runIdSet.has(def.createdByRunId) ||
+            def.partition === undefined) {
+            continue;
+        }
+        const newEpoch = params.updatedEpochs.get(def.partition);
+        if (newEpoch === undefined)
+            continue;
+        const prev = statsMap[def.id] ?? { recentOutcomes: [], totalCleanPasses: 0, totalViolated: 0 };
+        statsMap[def.id] = {
+            recentOutcomes: prev.recentOutcomes,
+            totalCleanPasses: prev.totalCleanPasses,
+            totalViolated: prev.totalViolated,
+            epochAtCreation: newEpoch,
+            signalLastEmittedAt: prev.signalLastEmittedAt,
+            retired: prev.retired,
+        };
+        mutated = true;
+    }
+    if (mutated) {
+        await atomicWriteJsonFile(params.statsFilePath, statsMap);
+    }
+}
+/**
+ * Persists the ISO-8601 emission timestamp for `params.signalId` on `params.lessonId` in `statsPath`.
+ *
+ * @param {MarkLessonSignalEmittedInStoreParams} params - Stats file path, lesson ID, signal ID, and timestamp.
+ *
+ * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+ */
+export async function markLessonSignalEmittedInStore(params) {
+    const statsMap = await readLessonStatsFile(params.statsFilePath);
+    const prev = statsMap[params.lessonId] ?? {
+        recentOutcomes: [],
+        totalCleanPasses: 0,
+        totalViolated: 0,
+    };
+    statsMap[params.lessonId] = {
+        recentOutcomes: prev.recentOutcomes,
+        totalCleanPasses: prev.totalCleanPasses,
+        totalViolated: prev.totalViolated,
+        epochAtCreation: prev.epochAtCreation,
+        signalLastEmittedAt: {
+            ...(prev.signalLastEmittedAt ?? {}),
+            [params.signalId]: params.emittedAt,
+        },
+        retired: prev.retired,
+    };
+    await atomicWriteJsonFile(params.statsFilePath, statsMap);
+}
+/**
+ * Marks `params.lessonIds` as `retired: true` in `statsPath` while preserving immutable definition files.
+ *
+ * @param {RetireLessonsInStoreParams} params - Stats file path and lesson IDs to retire.
+ *
+ * @returns {Promise<void>} Resolves when `statsPath` is atomically updated.
+ */
+export async function retireLessonsInStore(params) {
+    if (params.lessonIds.length === 0)
+        return;
+    const statsMap = await readLessonStatsFile(params.statsFilePath);
+    for (const id of params.lessonIds) {
+        const prev = statsMap[id] ?? { recentOutcomes: [], totalCleanPasses: 0, totalViolated: 0 };
+        statsMap[id] = {
+            recentOutcomes: prev.recentOutcomes,
+            totalCleanPasses: prev.totalCleanPasses,
+            totalViolated: prev.totalViolated,
+            epochAtCreation: prev.epochAtCreation,
+            signalLastEmittedAt: prev.signalLastEmittedAt,
+            retired: true,
+        };
+    }
+    await atomicWriteJsonFile(params.statsFilePath, statsMap);
+}
+//# sourceMappingURL=fs-jsonl-lesson-file-io.js.map

package/dist/stores/internal/fs-jsonl-lesson-file-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-jsonl-lesson-file-io.js","sourceRoot":"","sources":["../../../src/stores/internal/fs-jsonl-lesson-file-io.ts"],"names":[],"mappings":"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"}

package/dist/stores/internal/fs-lesson-definition-record.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Immutable JSON record persisted in `<definitionsDir>/<lessonId>.json` (`SPEC.md` §4.3).
+ *
+ * Written once during `FsJsonlLessonStore.admit()` and never mutated on subsequent
+ * outcome recordings or epoch synchronizations.
+ */
+export interface FsLessonDefinitionRecord {
+    /** Content-addressed lesson identifier. */
+    readonly id: string;
+    /** Optional topology partition associated with the lesson. */
+    readonly partition?: string;
+    /** Preventative or prescriptive directive text. */
+    readonly directive: string;
+    /** Initial partition contract epoch when the lesson was admitted. */
+    readonly epochAtCreation: number;
+    /** Optional run identifier that created the lesson or last mutated its partition contract. */
+    readonly createdByRunId?: string;
+}
+//# sourceMappingURL=fs-lesson-definition-record.d.ts.map