@paraharness/fs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lesson-definition-record.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/fs-lesson-definition-record.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,8FAA8F;IAC9F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC"}

package/dist/stores/internal/fs-lesson-definition-record.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fs-lesson-definition-record.js.map

package/dist/stores/internal/fs-lesson-definition-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lesson-definition-record.js","sourceRoot":"","sources":["../../../src/stores/internal/fs-lesson-definition-record.ts"],"names":[],"mappings":""}

package/dist/stores/internal/fs-lesson-lock-and-atomic-io.d.ts

@@ -0,0 +1,51 @@
+import { type FileLockOptions } from '@paraharness/lockfile';
+import type { FsLessonDefinitionRecord } from './fs-lesson-definition-record.js';
+import type { FsLessonStatsEntry } from './fs-lesson-stats-entry.js';
+/**
+ * Acquires an exclusive advisory lockfile via `@paraharness/lockfile` and executes `work`.
+ *
+ * Ensures cross-process and in-process serialization on `lockFilePath` with heartbeat
+ * and stale-lock reclamation (`SPEC.md` §4.3).
+ *
+ * @template TResult Return type of the critical section callback.
+ *
+ * @param {string}                  lockFilePath - Absolute host-root path to the lockfile.
+ * @param {() => Promise<TResult>}  work         - Async operation executed while holding the lock.
+ * @param {FileLockOptions}         [options]    - Optional lockfile timing overrides.
+ *
+ * @returns {Promise<TResult>} Result resolved by `work`.
+ */
+export declare function withLessonFileLock<TResult>(lockFilePath: string, work: () => Promise<TResult>, options?: FileLockOptions): Promise<TResult>;
+/**
+ * Writes `payload` as formatted JSON to `targetPath` atomically via `write-file-atomic`.
+ *
+ * Guarantees crash-safe atomic updates (`fsync: true` + atomic `rename`) for both
+ * `<definitionsDir>/<lessonId>.json` and `statsPath` (`SPEC.md` §4.3).
+ *
+ * @param {string}  targetPath - Destination file path.
+ * @param {unknown} payload    - JSON-serializable value to write.
+ *
+ * @returns {Promise<void>} Resolves once `fsync` and atomic `rename` complete.
+ */
+export declare function atomicWriteJsonFile(targetPath: string, payload: unknown): Promise<void>;
+/**
+ * Reads and parses the mutable lesson telemetry map from `statsPath`.
+ *
+ * Returns a mutable shallow clone of the `lessonId -> FsLessonStatsEntry` dictionary, or an empty object if `statsPath` does not yet exist.
+ *
+ * @param {string} statsPath - Absolute host-root path to `statsPath`.
+ *
+ * @returns {Promise<Record<string, FsLessonStatsEntry>>} Parsed per-lesson telemetry counter map.
+ */
+export declare function readLessonStatsFile(statsPath: string): Promise<Record<string, FsLessonStatsEntry>>;
+/**
+ * Reads all immutable `<lessonId>.json` definition files from `definitionsDir` in lexicographical filename order.
+ *
+ * Skips temporary `.tmp.` files and returns an empty array if `definitionsDir` does not yet exist.
+ *
+ * @param {string} definitionsDir - Absolute host-root path to `definitionsDir`.
+ *
+ * @returns {Promise<readonly FsLessonDefinitionRecord[]>} Frozen array of parsed lesson definitions.
+ */
+export declare function readAllLessonDefinitions(definitionsDir: string): Promise<readonly FsLessonDefinitionRecord[]>;
+//# sourceMappingURL=fs-lesson-lock-and-atomic-io.d.ts.map

package/dist/stores/internal/fs-lesson-lock-and-atomic-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lesson-lock-and-atomic-io.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/fs-lesson-lock-and-atomic-io.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAgB,MAAM,uBAAuB,CAAC;AAE3E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EACxC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC5B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAU7C;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,SAAS,wBAAwB,EAAE,CAAC,CAkB9C"}

package/dist/stores/internal/fs-lesson-lock-and-atomic-io.js

@@ -0,0 +1,89 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { withFileLock } from '@paraharness/lockfile';
+import writeFileAtomic from 'write-file-atomic';
+/**
+ * Acquires an exclusive advisory lockfile via `@paraharness/lockfile` and executes `work`.
+ *
+ * Ensures cross-process and in-process serialization on `lockFilePath` with heartbeat
+ * and stale-lock reclamation (`SPEC.md` §4.3).
+ *
+ * @template TResult Return type of the critical section callback.
+ *
+ * @param {string}                  lockFilePath - Absolute host-root path to the lockfile.
+ * @param {() => Promise<TResult>}  work         - Async operation executed while holding the lock.
+ * @param {FileLockOptions}         [options]    - Optional lockfile timing overrides.
+ *
+ * @returns {Promise<TResult>} Result resolved by `work`.
+ */
+export function withLessonFileLock(lockFilePath, work, options) {
+    return withFileLock(lockFilePath, work, options);
+}
+/**
+ * Writes `payload` as formatted JSON to `targetPath` atomically via `write-file-atomic`.
+ *
+ * Guarantees crash-safe atomic updates (`fsync: true` + atomic `rename`) for both
+ * `<definitionsDir>/<lessonId>.json` and `statsPath` (`SPEC.md` §4.3).
+ *
+ * @param {string}  targetPath - Destination file path.
+ * @param {unknown} payload    - JSON-serializable value to write.
+ *
+ * @returns {Promise<void>} Resolves once `fsync` and atomic `rename` complete.
+ */
+export async function atomicWriteJsonFile(targetPath, payload) {
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFileAtomic(targetPath, `${JSON.stringify(payload, null, 2)}\n`, {
+        encoding: 'utf8',
+        fsync: true,
+    });
+}
+/**
+ * Reads and parses the mutable lesson telemetry map from `statsPath`.
+ *
+ * Returns a mutable shallow clone of the `lessonId -> FsLessonStatsEntry` dictionary, or an empty object if `statsPath` does not yet exist.
+ *
+ * @param {string} statsPath - Absolute host-root path to `statsPath`.
+ *
+ * @returns {Promise<Record<string, FsLessonStatsEntry>>} Parsed per-lesson telemetry counter map.
+ */
+export async function readLessonStatsFile(statsPath) {
+    if (!existsSync(statsPath)) {
+        return {};
+    }
+    const raw = await readFile(statsPath, 'utf8');
+    if (raw.trim().length === 0) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    return { ...parsed };
+}
+/**
+ * Reads all immutable `<lessonId>.json` definition files from `definitionsDir` in lexicographical filename order.
+ *
+ * Skips temporary `.tmp.` files and returns an empty array if `definitionsDir` does not yet exist.
+ *
+ * @param {string} definitionsDir - Absolute host-root path to `definitionsDir`.
+ *
+ * @returns {Promise<readonly FsLessonDefinitionRecord[]>} Frozen array of parsed lesson definitions.
+ */
+export async function readAllLessonDefinitions(definitionsDir) {
+    if (!existsSync(definitionsDir)) {
+        return Object.freeze([]);
+    }
+    const entries = await readdir(definitionsDir);
+    const jsonFiles = [];
+    for (const fileName of entries) {
+        if (fileName.endsWith('.json') && !fileName.includes('.tmp.')) {
+            jsonFiles.push(fileName);
+        }
+    }
+    jsonFiles.sort((a, b) => a.localeCompare(b));
+    const definitions = [];
+    for (const fileName of jsonFiles) {
+        const raw = await readFile(path.join(definitionsDir, fileName), 'utf8');
+        definitions.push(JSON.parse(raw));
+    }
+    return Object.freeze(definitions);
+}
+//# sourceMappingURL=fs-lesson-lock-and-atomic-io.js.map

package/dist/stores/internal/fs-lesson-lock-and-atomic-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lesson-lock-and-atomic-io.js","sourceRoot":"","sources":["../../../src/stores/internal/fs-lesson-lock-and-atomic-io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAwB,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,eAAe,MAAM,mBAAmB,CAAC;AAIhD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAAoB,EACpB,IAA4B,EAC5B,OAAyB;IAEzB,OAAO,YAAY,CAAC,YAAY,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAkB,EAClB,OAAgB;IAEhB,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3D,MAAM,eAAe,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACzE,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAiB;IAEjB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiD,CAAC;IAC/E,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,cAAsB;IAEtB,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9D,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,MAAM,WAAW,GAA+B,EAAE,CAAC;IACnD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;QACxE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAA6B,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACpC,CAAC"}

package/dist/stores/internal/fs-lesson-relevance.d.ts

@@ -0,0 +1,49 @@
+import type { LessonRecord } from '@paraharness/core';
+import type { FsLessonDefinitionRecord } from './fs-lesson-definition-record.js';
+import type { FsLessonStatsEntry } from './fs-lesson-stats-entry.js';
+/**
+ * Computes a deterministic content-addressed `lessonId` from `partition` and `directive`.
+ *
+ * Deduplicates identical `(partition, directive)` admissions across runs (`SPEC.md` §4.3).
+ *
+ * @param {string | undefined} partition - Optional partition identifier.
+ * @param {string}             directive - Lesson directive text.
+ *
+ * @returns {string} Content-addressed lesson identifier (`lesson-<16-hex>`).
+ */
+export declare function computeLessonId(partition: string | undefined, directive: string): string;
+/**
+ * Computes normalized BM25 text similarity $R(L, Q) \in [0, 1]$ across `definitions` using `MiniSearch`.
+ *
+ * Indexes `directive` and `partition` fields with `{ prefix: true, fuzzy: 0.2 }` and normalizes
+ * BM25 scores against the top-scoring candidate (`SPEC.md` §2.7 & §3.4.3).
+ *
+ * @param {string}                                   queryText   - Search query extracted from actor input.
+ * @param {readonly FsLessonDefinitionRecord[]}      definitions - Active non-retired lesson definitions.
+ * @param {ReadonlySet<string> | readonly string[]}  partitions  - Active task partitions.
+ *
+ * @returns {ReadonlyMap<string, number>} Map of `lessonId` to normalized relevance score in `[0, 1]`.
+ */
+export declare function scoreLessonsWithMiniSearch(queryText: string, definitions: readonly FsLessonDefinitionRecord[], partitions: ReadonlySet<string> | readonly string[]): ReadonlyMap<string, number>;
+/**
+ * Merges an immutable `FsLessonDefinitionRecord` with its mutable `FsLessonStatsEntry` into a `LessonRecord`.
+ *
+ * Applies any `epochAtCreation` override from `stats` while preserving monomorphic `LessonRecord` property order (`Rule 4.3`).
+ *
+ * @param {FsLessonDefinitionRecord}       definition       - Immutable lesson definition record.
+ * @param {FsLessonStatsEntry | undefined} stats            - Mutable telemetry counters for the lesson.
+ * @param {number | undefined}             [relevanceScore] - Optional query relevance score in `[0, 1]`.
+ *
+ * @returns {LessonRecord} Frozen `LessonRecord`.
+ */
+export declare function mergeDefinitionAndStats(definition: FsLessonDefinitionRecord, stats: FsLessonStatsEntry | undefined, relevanceScore?: number): LessonRecord;
+/**
+ * Compares two `LessonRecord` entries by descending `relevanceScore` with lexicographical `id` tie-breaking.
+ *
+ * @param {LessonRecord} left  - First lesson record.
+ * @param {LessonRecord} right - Second lesson record.
+ *
+ * @returns {number} Negative when `left` ranks ahead of `right`, positive when behind, or `0`.
+ */
+export declare function compareLessonRecordsByRelevance(left: LessonRecord, right: LessonRecord): number;
+//# sourceMappingURL=fs-lesson-relevance.d.ts.map

package/dist/stores/internal/fs-lesson-relevance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lesson-relevance.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/fs-lesson-relevance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,SAAS,wBAAwB,EAAE,EAChD,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,GAClD,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAoC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,wBAAwB,EACpC,KAAK,EAAE,kBAAkB,GAAG,SAAS,EACrC,cAAc,CAAC,EAAE,MAAM,GACtB,YAAY,CAgBd;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,YAAY,GAClB,MAAM,CAOR"}

package/dist/stores/internal/fs-lesson-relevance.js

@@ -0,0 +1,113 @@
+import { createHash } from 'node:crypto';
+import MiniSearch from 'minisearch';
+/**
+ * Computes a deterministic content-addressed `lessonId` from `partition` and `directive`.
+ *
+ * Deduplicates identical `(partition, directive)` admissions across runs (`SPEC.md` §4.3).
+ *
+ * @param {string | undefined} partition - Optional partition identifier.
+ * @param {string}             directive - Lesson directive text.
+ *
+ * @returns {string} Content-addressed lesson identifier (`lesson-<16-hex>`).
+ */
+export function computeLessonId(partition, directive) {
+    const hash = createHash('sha256')
+        .update(`${partition ?? ''}::${directive.trim()}`, 'utf8')
+        .digest('hex')
+        .slice(0, 16);
+    return `lesson-${hash}`;
+}
+/**
+ * Computes normalized BM25 text similarity $R(L, Q) \in [0, 1]$ across `definitions` using `MiniSearch`.
+ *
+ * Indexes `directive` and `partition` fields with `{ prefix: true, fuzzy: 0.2 }` and normalizes
+ * BM25 scores against the top-scoring candidate (`SPEC.md` §2.7 & §3.4.3).
+ *
+ * @param {string}                                   queryText   - Search query extracted from actor input.
+ * @param {readonly FsLessonDefinitionRecord[]}      definitions - Active non-retired lesson definitions.
+ * @param {ReadonlySet<string> | readonly string[]}  partitions  - Active task partitions.
+ *
+ * @returns {ReadonlyMap<string, number>} Map of `lessonId` to normalized relevance score in `[0, 1]`.
+ */
+export function scoreLessonsWithMiniSearch(queryText, definitions, partitions) {
+    const scoresById = new Map();
+    if (definitions.length === 0)
+        return scoresById;
+    const trimmedQuery = queryText.trim();
+    if (trimmedQuery.length === 0) {
+        for (const def of definitions)
+            scoresById.set(def.id, 1);
+        return scoresById;
+    }
+    const miniSearch = new MiniSearch({
+        fields: ['directive', 'partition'],
+        storeFields: ['id'],
+        searchOptions: { prefix: true, fuzzy: 0.2 },
+    });
+    for (const def of definitions) {
+        miniSearch.add({ id: def.id, directive: def.directive, partition: def.partition ?? '' });
+    }
+    const hits = miniSearch.search(trimmedQuery, { prefix: true, fuzzy: 0.2 });
+    const maxScore = hits[0]?.score ?? 0;
+    const rawScoreById = new Map();
+    for (const hit of hits)
+        rawScoreById.set(String(hit.id), hit.score);
+    const partitionSet = partitions instanceof Set ? partitions : new Set(partitions);
+    for (const def of definitions) {
+        const rawScore = rawScoreById.get(def.id);
+        if (rawScore !== undefined && maxScore > 0) {
+            scoresById.set(def.id, Math.min(1, Math.max(0.1, rawScore / maxScore)));
+        }
+        else if (def.partition !== undefined && partitionSet.has(def.partition)) {
+            scoresById.set(def.id, 0.05);
+        }
+        else {
+            scoresById.set(def.id, 0);
+        }
+    }
+    return scoresById;
+}
+/**
+ * Merges an immutable `FsLessonDefinitionRecord` with its mutable `FsLessonStatsEntry` into a `LessonRecord`.
+ *
+ * Applies any `epochAtCreation` override from `stats` while preserving monomorphic `LessonRecord` property order (`Rule 4.3`).
+ *
+ * @param {FsLessonDefinitionRecord}       definition       - Immutable lesson definition record.
+ * @param {FsLessonStatsEntry | undefined} stats            - Mutable telemetry counters for the lesson.
+ * @param {number | undefined}             [relevanceScore] - Optional query relevance score in `[0, 1]`.
+ *
+ * @returns {LessonRecord} Frozen `LessonRecord`.
+ */
+export function mergeDefinitionAndStats(definition, stats, relevanceScore) {
+    return Object.freeze({
+        id: definition.id,
+        partition: definition.partition,
+        directive: definition.directive,
+        epochAtCreation: stats?.epochAtCreation ?? definition.epochAtCreation,
+        createdByRunId: definition.createdByRunId,
+        recentOutcomes: Object.freeze([...(stats?.recentOutcomes ?? [])]),
+        totalCleanPasses: stats?.totalCleanPasses ?? 0,
+        totalViolated: stats?.totalViolated ?? 0,
+        relevanceScore,
+        signalLastEmittedAt: stats?.signalLastEmittedAt !== undefined
+            ? Object.freeze({ ...stats.signalLastEmittedAt })
+            : undefined,
+    });
+}
+/**
+ * Compares two `LessonRecord` entries by descending `relevanceScore` with lexicographical `id` tie-breaking.
+ *
+ * @param {LessonRecord} left  - First lesson record.
+ * @param {LessonRecord} right - Second lesson record.
+ *
+ * @returns {number} Negative when `left` ranks ahead of `right`, positive when behind, or `0`.
+ */
+export function compareLessonRecordsByRelevance(left, right) {
+    const leftScore = left.relevanceScore ?? 0;
+    const rightScore = right.relevanceScore ?? 0;
+    if (rightScore !== leftScore) {
+        return rightScore - leftScore;
+    }
+    return left.id.localeCompare(right.id);
+}
+//# sourceMappingURL=fs-lesson-relevance.js.map

package/dist/stores/internal/fs-lesson-relevance.js.map

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

package/dist/stores/internal/fs-lesson-stats-entry.d.ts

@@ -0,0 +1,22 @@
+import type { LessonOutcome } from '@paraharness/core';
+/**
+ * Mutable per-lesson telemetry counter record persisted in `statsPath` (`SPEC.md` §4.3).
+ *
+ * Tracks sliding-window outcomes, cumulative pass/violation counters, post-commit
+ * `epochAtCreation` overrides, signal emission timestamps, and retirement status.
+ */
+export interface FsLessonStatsEntry {
+    /** Ordered list of recorded 4-state step outcomes for this lesson. */
+    readonly recentOutcomes: readonly LessonOutcome[];
+    /** Cumulative number of `'clean_pass'` outcomes recorded. */
+    readonly totalCleanPasses: number;
+    /** Cumulative number of `'violated'` outcomes recorded. */
+    readonly totalViolated: number;
+    /** Optional synchronized creation epoch override written by `syncCreationEpochsForRuns`. */
+    readonly epochAtCreation?: number;
+    /** Optional map of `signalId` to ISO-8601 emission timestamp from `markSignalEmitted`. */
+    readonly signalLastEmittedAt?: Readonly<Record<string, string>>;
+    /** True when the lesson has been permanently retired via `retire()`. */
+    readonly retired?: boolean;
+}
+//# sourceMappingURL=fs-lesson-stats-entry.d.ts.map

package/dist/stores/internal/fs-lesson-stats-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lesson-stats-entry.d.ts","sourceRoot":"","sources":["../../../src/stores/internal/fs-lesson-stats-entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD,6DAA6D;IAC7D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,0FAA0F;IAC1F,QAAQ,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B"}

package/dist/stores/internal/fs-lesson-stats-entry.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fs-lesson-stats-entry.js.map

package/dist/stores/internal/fs-lesson-stats-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-lesson-stats-entry.js","sourceRoot":"","sources":["../../../src/stores/internal/fs-lesson-stats-entry.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@paraharness/fs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Workspace-jailed filesystem tools, glob effect matchers, pre/post-flight write policy guards, quota tripwires, and atomic JSONL lesson store for Paraharness.",
+  "keywords": [
+    "paraharness",
+    "filesystem",
+    "sandbox",
+    "policy-guards",
+    "globs",
+    "tools",
+    "ai-agents"
+  ],
+  "author": "Tornike Tsomaia",
+  "license": "MIT",
+  "homepage": "https://paraharness.github.io/paraharness/modules/_paraharness_fs.html",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paraharness/paraharness.git",
+    "directory": "packages/fs"
+  },
+  "bugs": {
+    "url": "https://github.com/paraharness/paraharness/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "minisearch": "^7.2.0",
+    "p-queue": "^9.1.0",
+    "picomatch": "^4.0.3",
+    "tinyglobby": "^0.2.17",
+    "write-file-atomic": "^8.0.0",
+    "zod": "^4.6.7",
+    "@paraharness/core": "0.1.0",
+    "@paraharness/lockfile": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "@types/picomatch": "^4.0.3",
+    "@types/write-file-atomic": "^4.0.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.0"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "src/index.ts"
+    ],
+    "tsconfig": "tsconfig.build.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint \"{src,test}/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config ../../vitest.config.ts --dir . --passWithNoTests"
+  }
 }