nlm-memory 0.21.0 → 0.21.12

package/dist/core/learner/model.d.ts

@@ -0,0 +1,63 @@
+export type EnrollmentStatus = "active" | "completed";
+export type AttemptResult = "correct" | "partial" | "incorrect";
+export type AttemptHelp = "none" | "hint" | "worked-example";
+export type AttemptKind = "application" | "retrieval" | "transfer";
+export interface Learner {
+    readonly id: string;
+    readonly label: string;
+    readonly profile: Record<string, unknown>;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface Attempt {
+    readonly concept: string;
+    readonly task: string;
+    readonly response: string;
+    readonly result: AttemptResult;
+    readonly help: AttemptHelp;
+    readonly kind: AttemptKind;
+}
+export interface LearningEvent {
+    readonly id: string;
+    readonly date: string;
+    readonly covered: ReadonlyArray<string>;
+    readonly attempts: ReadonlyArray<Attempt>;
+    readonly interpretation: string;
+    readonly nextStep: string;
+    readonly createdAt: string;
+}
+export interface Enrollment {
+    readonly id: string;
+    readonly learnerId: string;
+    readonly courseId: string;
+    readonly workstreamId: string | null;
+    readonly planRef: string;
+    readonly planRevision: number;
+    readonly planFingerprint: string;
+    readonly status: EnrollmentStatus;
+    readonly completionHistory: ReadonlyArray<unknown>;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export declare function makeEnrollmentId(): string;
+/**
+ * Canonical JSON: object keys sorted recursively, arrays preserved. pg JSONB
+ * reorders object keys on write, so byte comparison of round-tripped JSON
+ * false-conflicts; canonical form is the only backend-agnostic equality.
+ */
+export declare function canonicalJson(value: unknown): string;
+export interface StoredEventContent {
+    readonly date: string;
+    readonly covered: ReadonlyArray<string>;
+    readonly attempts: ReadonlyArray<Attempt>;
+    readonly interpretation: string;
+    readonly nextStep: string;
+}
+/** Idempotent-record comparison: same event if all content fields match. */
+export declare function learningEventContentEqual(input: {
+    date: string;
+    covered: ReadonlyArray<string>;
+    attempts: ReadonlyArray<Attempt>;
+    interpretation: string;
+    nextStep: string;
+}, stored: StoredEventContent): boolean;

package/dist/core/learner/model.js

@@ -0,0 +1,30 @@
+// src/core/learner/model.ts
+import { randomUUID } from "node:crypto";
+export function makeEnrollmentId() {
+    return `enr_${randomUUID()}`;
+}
+/**
+ * Canonical JSON: object keys sorted recursively, arrays preserved. pg JSONB
+ * reorders object keys on write, so byte comparison of round-tripped JSON
+ * false-conflicts; canonical form is the only backend-agnostic equality.
+ */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+        return `{${entries.join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/** Idempotent-record comparison: same event if all content fields match. */
+export function learningEventContentEqual(input, stored) {
+    return (input.date === stored.date &&
+        canonicalJson(input.covered) === canonicalJson(stored.covered) &&
+        canonicalJson(input.attempts) === canonicalJson(stored.attempts) &&
+        input.interpretation === stored.interpretation &&
+        input.nextStep === stored.nextStep);
+}
+//# sourceMappingURL=model.js.map

package/dist/core/learner/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/core/learner/model.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiDzC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,UAAU,EAAE,EAAE,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3E,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClC,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;AACzC,CAAC;AAUD,4EAA4E;AAC5E,MAAM,UAAU,yBAAyB,CACvC,KAAmI,EACnI,MAA0B;IAE1B,OAAO,CACL,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QAC1B,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;QAC9D,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC;QAChE,KAAK,CAAC,cAAc,KAAK,MAAM,CAAC,cAAc;QAC9C,KAAK,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ,CACnC,CAAC;AACJ,CAAC"}

package/dist/core/learner/service.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Learner service — orchestration over LearnerStore + WorkstreamStore.
+ *
+ * Owns validation (validate.ts), learner auto-init, workstream id-or-label
+ * resolution, and summary assembly. Idempotency, fingerprint matching, and
+ * tenant isolation stay in the store. The MCP layer (M3) calls these
+ * operations; unrecorded-session listing needs SessionStore and lands in M3.
+ */
+import type { LearnerStore, LearningEventInput, RecordResult } from "../../ports/learner-store.js";
+import type { WorkstreamStore } from "../../ports/workstream-store.js";
+import type { Enrollment, EnrollmentStatus } from "./model.js";
+import { type ConceptSummary } from "./summary.js";
+export interface LearnerServiceDeps {
+    readonly learners: LearnerStore;
+    readonly workstreams: Pick<WorkstreamStore, "getById" | "findByNormalizedLabel">;
+}
+export interface EnrollRequest {
+    readonly learnerId: string;
+    readonly learnerLabel?: string;
+    readonly courseId: string;
+    /** Workstream id or label; resolved like recall_workstream. */
+    readonly workstream: string;
+    readonly planRef: string;
+    readonly planRevision: number;
+    readonly planFingerprint: string;
+}
+export interface CourseSummary {
+    readonly learnerId: string;
+    readonly courseId: string;
+    readonly status: EnrollmentStatus;
+    readonly workstreamId: string | null;
+    readonly planRevision: number;
+    readonly concepts: ReadonlyArray<ConceptSummary>;
+    /** Latest event's next step, or null when nothing is recorded yet. */
+    readonly nextStep: string | null;
+    readonly eventCount: number;
+    readonly lastEventDate: string | null;
+}
+export declare function enrollCourse(deps: LearnerServiceDeps, tenantId: string, req: EnrollRequest): Promise<Enrollment>;
+export declare function recordLearningEvent(deps: LearnerServiceDeps, tenantId: string, learnerId: string, courseId: string, event: LearningEventInput): Promise<RecordResult>;
+export declare function completeLearnerCourse(deps: LearnerServiceDeps, tenantId: string, learnerId: string, courseId: string): Promise<void>;
+export declare function getCourseSummary(deps: LearnerServiceDeps, tenantId: string, learnerId: string, courseId: string): Promise<CourseSummary | null>;

package/dist/core/learner/service.js

@@ -0,0 +1,74 @@
+/**
+ * Learner service — orchestration over LearnerStore + WorkstreamStore.
+ *
+ * Owns validation (validate.ts), learner auto-init, workstream id-or-label
+ * resolution, and summary assembly. Idempotency, fingerprint matching, and
+ * tenant isolation stay in the store. The MCP layer (M3) calls these
+ * operations; unrecorded-session listing needs SessionStore and lands in M3.
+ */
+import { normalizeLabel } from "../workstream/model.js";
+import { assertValidEnrollmentInput, assertValidEventInput, assertValidLearnerInit, assertValidSlug, } from "./validate.js";
+import { summarizeConcepts } from "./summary.js";
+async function resolveWorkstreamId(deps, tenantId, idOrLabel) {
+    const trimmed = idOrLabel.trim();
+    if (!trimmed)
+        throw new Error("learner service: workstream id or label is required");
+    const found = (await deps.workstreams.getById(tenantId, trimmed)) ??
+        (await deps.workstreams.findByNormalizedLabel(tenantId, normalizeLabel(trimmed)));
+    if (!found)
+        throw new Error(`learner service: no workstream matches "${trimmed}"`);
+    return found.id;
+}
+export async function enrollCourse(deps, tenantId, req) {
+    assertValidSlug(req.learnerId, "enrollment.learnerId");
+    assertValidSlug(req.courseId, "enrollment.courseId");
+    const workstreamId = await resolveWorkstreamId(deps, tenantId, req.workstream);
+    const existing = await deps.learners.getLearner(tenantId, req.learnerId);
+    if (!existing) {
+        const init = { id: req.learnerId, label: req.learnerLabel ?? req.learnerId };
+        assertValidLearnerInit(init);
+        await deps.learners.initLearner(tenantId, init);
+    }
+    const input = {
+        learnerId: req.learnerId,
+        courseId: req.courseId,
+        workstreamId,
+        planRef: req.planRef,
+        planRevision: req.planRevision,
+        planFingerprint: req.planFingerprint,
+    };
+    assertValidEnrollmentInput(input);
+    return deps.learners.enroll(tenantId, input);
+}
+export async function recordLearningEvent(deps, tenantId, learnerId, courseId, event) {
+    assertValidSlug(learnerId, "enrollment.learnerId");
+    assertValidSlug(courseId, "enrollment.courseId");
+    assertValidEventInput(event);
+    return deps.learners.recordEvent(tenantId, learnerId, courseId, event);
+}
+export async function completeLearnerCourse(deps, tenantId, learnerId, courseId) {
+    assertValidSlug(learnerId, "enrollment.learnerId");
+    assertValidSlug(courseId, "enrollment.courseId");
+    return deps.learners.completeCourse(tenantId, learnerId, courseId);
+}
+export async function getCourseSummary(deps, tenantId, learnerId, courseId) {
+    assertValidSlug(learnerId, "enrollment.learnerId");
+    assertValidSlug(courseId, "enrollment.courseId");
+    const enrollment = await deps.learners.getEnrollment(tenantId, learnerId, courseId);
+    if (!enrollment)
+        return null;
+    const events = await deps.learners.listEvents(tenantId, learnerId, courseId);
+    const last = events.length > 0 ? events[events.length - 1] : null;
+    return {
+        learnerId,
+        courseId,
+        status: enrollment.status,
+        workstreamId: enrollment.workstreamId,
+        planRevision: enrollment.planRevision,
+        concepts: summarizeConcepts(events),
+        nextStep: last ? last.nextStep : null,
+        eventCount: events.length,
+        lastEventDate: last ? last.date : null,
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/core/learner/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/core/learner/service.ts"],"names":[],"mappings":"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"}

package/dist/core/learner/summary.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Learner summary derivation — port of the Gnos deterministic summary rule
+ * (`skills/learner-tracking/references/evidence.md`, MIT, attribution kept).
+ *
+ * Per concept, from events in `listEvents` order ((date, id) ascending):
+ *
+ * - covered, never attempted: **exposed**
+ * - latest attempt assisted, partial, or incorrect: **practicing**
+ * - latest attempt correct + unassisted: **demonstrated**
+ * - latest success is retrieval/transfer on a strictly later date than an
+ *   earlier unassisted success: **retained**
+ *
+ * Latest failure demotes back to practicing; earlier evidence is preserved in
+ * the events, not in the label. These are workflow labels, not calibrated
+ * scores — the summary never issues "mastered".
+ */
+import type { LearningEvent } from "./model.js";
+export type ConceptStatus = "exposed" | "practicing" | "demonstrated" | "retained";
+export interface ConceptSummary {
+    readonly concept: string;
+    readonly status: ConceptStatus;
+    readonly attemptCount: number;
+    /** Latest attempt date, else the date the concept was last covered. */
+    readonly latestDate: string | null;
+    /** Latest attempt's task, or null when never attempted. */
+    readonly latestTask: string | null;
+}
+export declare function summarizeConcepts(events: ReadonlyArray<LearningEvent>): ReadonlyArray<ConceptSummary>;

package/dist/core/learner/summary.js

@@ -0,0 +1,70 @@
+/**
+ * Learner summary derivation — port of the Gnos deterministic summary rule
+ * (`skills/learner-tracking/references/evidence.md`, MIT, attribution kept).
+ *
+ * Per concept, from events in `listEvents` order ((date, id) ascending):
+ *
+ * - covered, never attempted: **exposed**
+ * - latest attempt assisted, partial, or incorrect: **practicing**
+ * - latest attempt correct + unassisted: **demonstrated**
+ * - latest success is retrieval/transfer on a strictly later date than an
+ *   earlier unassisted success: **retained**
+ *
+ * Latest failure demotes back to practicing; earlier evidence is preserved in
+ * the events, not in the label. These are workflow labels, not calibrated
+ * scores — the summary never issues "mastered".
+ */
+function isUnassistedSuccess(a) {
+    return a.result === "correct" && a.help === "none";
+}
+export function summarizeConcepts(events) {
+    const coveredOn = new Map();
+    const attemptsByConcept = new Map();
+    for (const event of events) {
+        for (const concept of event.covered)
+            coveredOn.set(concept, event.date);
+        for (const attempt of event.attempts) {
+            let list = attemptsByConcept.get(attempt.concept);
+            if (!list) {
+                list = [];
+                attemptsByConcept.set(attempt.concept, list);
+            }
+            list.push({ attempt, date: event.date });
+            if (!coveredOn.has(attempt.concept))
+                coveredOn.set(attempt.concept, event.date);
+        }
+    }
+    const concepts = [...new Set([...coveredOn.keys(), ...attemptsByConcept.keys()])].sort();
+    return concepts.map((concept) => {
+        const attempts = attemptsByConcept.get(concept) ?? [];
+        if (attempts.length === 0) {
+            return {
+                concept,
+                status: "exposed",
+                attemptCount: 0,
+                latestDate: coveredOn.get(concept) ?? null,
+                latestTask: null,
+            };
+        }
+        const latest = attempts[attempts.length - 1];
+        let status;
+        if (!isUnassistedSuccess(latest.attempt)) {
+            status = "practicing";
+        }
+        else if ((latest.attempt.kind === "retrieval" || latest.attempt.kind === "transfer") &&
+            attempts.some((a) => a.date < latest.date && isUnassistedSuccess(a.attempt))) {
+            status = "retained";
+        }
+        else {
+            status = "demonstrated";
+        }
+        return {
+            concept,
+            status,
+            attemptCount: attempts.length,
+            latestDate: latest.date,
+            latestTask: latest.attempt.task,
+        };
+    });
+}
+//# sourceMappingURL=summary.js.map

package/dist/core/learner/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../../src/core/learner/summary.ts"],"names":[],"mappings":"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"}

package/dist/core/learner/validate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Learner evidence validation — port of the Gnos evidence contract
+ * (`skills/learner-tracking/scripts/learner_state.py`, MIT, attribution kept).
+ *
+ * Shape rules only: slug/concept formats, required fields, enum membership,
+ * real calendar dates that are never in the future. Cross-row rules
+ * (fingerprint match, idempotent retry) live in the store; orchestration in
+ * service.ts. All failures throw `Error`; the MCP layer (M3) maps them to
+ * tool errors.
+ */
+import type { EnrollmentInput, LearnerInit, LearningEventInput } from "../../ports/learner-store.js";
+export declare function assertValidSlug(value: unknown, label: string): asserts value is string;
+export declare function assertValidConceptId(value: unknown): asserts value is string;
+export declare function assertNonempty(value: unknown, label: string): asserts value is string;
+export declare function assertValidDate(value: unknown, label?: string): asserts value is string;
+export declare function assertValidLearnerInit(input: LearnerInit): void;
+export declare function assertValidEnrollmentInput(input: EnrollmentInput): void;
+export declare function assertValidEventInput(event: LearningEventInput): void;

package/dist/core/learner/validate.js

@@ -0,0 +1,95 @@
+/**
+ * Learner evidence validation — port of the Gnos evidence contract
+ * (`skills/learner-tracking/scripts/learner_state.py`, MIT, attribution kept).
+ *
+ * Shape rules only: slug/concept formats, required fields, enum membership,
+ * real calendar dates that are never in the future. Cross-row rules
+ * (fingerprint match, idempotent retry) live in the store; orchestration in
+ * service.ts. All failures throw `Error`; the MCP layer (M3) maps them to
+ * tool errors.
+ */
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CONCEPT_PATTERN = /^[a-z][a-z0-9-]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ATTEMPT_RESULTS = ["correct", "partial", "incorrect"];
+const ATTEMPT_HELPS = ["none", "hint", "worked-example"];
+const ATTEMPT_KINDS = ["application", "retrieval", "transfer"];
+export function assertValidSlug(value, label) {
+    if (typeof value !== "string" || value.length > 80 || !SLUG_PATTERN.test(value)) {
+        throw new Error(`learner validation: ${label} must be a lowercase slug of at most 80 characters`);
+    }
+}
+export function assertValidConceptId(value) {
+    if (typeof value !== "string" || !CONCEPT_PATTERN.test(value)) {
+        throw new Error(`learner validation: invalid concept ID: ${JSON.stringify(value)}`);
+    }
+}
+export function assertNonempty(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`learner validation: ${label} must be nonempty text`);
+    }
+}
+export function assertValidDate(value, label = "event.date") {
+    if (typeof value !== "string") {
+        throw new Error(`learner validation: ${label} must be YYYY-MM-DD`);
+    }
+    const match = DATE_PATTERN.exec(value);
+    if (!match)
+        throw new Error(`learner validation: ${label} must be YYYY-MM-DD`);
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const dt = new Date(Date.UTC(year, month - 1, day));
+    if (dt.getUTCFullYear() !== year || dt.getUTCMonth() !== month - 1 || dt.getUTCDate() !== day) {
+        throw new Error(`learner validation: ${label} is not a real calendar date: ${value}`);
+    }
+    const today = new Date().toISOString().slice(0, 10);
+    if (value > today) {
+        throw new Error(`learner validation: ${label} cannot be in the future: ${value}`);
+    }
+}
+export function assertValidLearnerInit(input) {
+    assertValidSlug(input.id, "learner.id");
+    assertNonempty(input.label, "learner.label");
+}
+export function assertValidEnrollmentInput(input) {
+    assertValidSlug(input.learnerId, "enrollment.learnerId");
+    assertValidSlug(input.courseId, "enrollment.courseId");
+    assertNonempty(input.workstreamId, "enrollment.workstreamId");
+    assertNonempty(input.planRef, "enrollment.planRef");
+    assertNonempty(input.planFingerprint, "enrollment.planFingerprint");
+    if (!Number.isInteger(input.planRevision) || input.planRevision < 1) {
+        throw new Error("learner validation: enrollment.planRevision must be a positive integer");
+    }
+}
+export function assertValidEventInput(event) {
+    assertValidSlug(event.id, "event.id");
+    assertValidDate(event.date);
+    if (!Array.isArray(event.covered)) {
+        throw new Error("learner validation: event.covered must be a list");
+    }
+    for (const concept of event.covered)
+        assertValidConceptId(concept);
+    assertNonempty(event.nextStep, "event.nextStep");
+    if (typeof event.interpretation !== "string") {
+        throw new Error("learner validation: event.interpretation must be text (may be empty)");
+    }
+    if (!Array.isArray(event.attempts)) {
+        throw new Error("learner validation: event.attempts must be a list");
+    }
+    for (const attempt of event.attempts) {
+        assertValidConceptId(attempt.concept);
+        assertNonempty(attempt.task, "attempt.task");
+        assertNonempty(attempt.response, "attempt.response");
+        if (!ATTEMPT_RESULTS.includes(attempt.result)) {
+            throw new Error(`learner validation: attempt.result must be one of ${ATTEMPT_RESULTS.join(", ")}`);
+        }
+        if (!ATTEMPT_HELPS.includes(attempt.help)) {
+            throw new Error(`learner validation: attempt.help must be one of ${ATTEMPT_HELPS.join(", ")}`);
+        }
+        if (!ATTEMPT_KINDS.includes(attempt.kind)) {
+            throw new Error(`learner validation: attempt.kind must be one of ${ATTEMPT_KINDS.join(", ")}`);
+        }
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/core/learner/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/core/learner/validate.ts"],"names":[],"mappings":"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"}

package/dist/core/metrics/re-derivation.d.ts

@@ -31,8 +31,25 @@ export interface ReDerivationPair {
 export interface ReDerivationReport {
     readonly rate: number;
     readonly pairs: ReadonlyArray<ReDerivationPair>;
-    /** Denominator: entity-sharing session pairs eligible for the rate. */
+    /**
+     * Denominator of the legacy pair-space rate: entity-sharing session pairs
+     * where BOTH sides carry at least one decision. A pair with a decisionless
+     * side cannot be a re-derivation by construction, and counting it inflated
+     * this figure roughly 3x - measured 2026-08-04 on the live 90-day window,
+     * 1,266,809 of 1,905,497 eligible pairs (66.5%) had a decisionless side.
+     */
     readonly eligible: number;
+    /** Sessions in the window carrying at least one decision. Linear in corpus size. */
+    readonly decisionBearingSessions: number;
+    /** Distinct later-side sessions appearing in `pairs`. Counted once each. */
+    readonly reDerivingSessions: number;
+    /**
+     * reDerivingSessions / decisionBearingSessions. This is the trendable metric:
+     * the pair-space `rate` divides by a denominator that grows quadratically with
+     * the corpus, so it mechanically falls the more the product is used, which is
+     * backwards for a number whose job is to show improvement.
+     */
+    readonly sessionRate: number;
 }
 interface SqliteLike {
     prepare(sql: string): {
@@ -42,7 +59,19 @@ interface SqliteLike {
 /**
  * SQLite-backed deps for the CLI readout. Reads sessions started within the
  * window along with their entity links and decision markers, plus all edges.
+ * `tenantId` scopes the sessions SELECT via tenantClause — the pairs this
+ * produces get persisted to a tenant-derived cache file (see
+ * `@core/storage/sqlite-outcome-store.js`), so an un-tenanted scan here would
+ * leak every tenant's sessions into whichever tenant's file reads it back.
  */
-export declare function sqliteReDerivationDeps(db: SqliteLike): ReDerivationDeps;
+export declare function sqliteReDerivationDeps(db: SqliteLike, tenantId: string): ReDerivationDeps;
+/**
+ * Parses the on-disk cache the 24h corpus-monitor job writes to
+ * (`~/.nlm/re-derivation-pairs.json`, see `src/cli/nlm.ts`) and the SQLite
+ * outcome adapters read back (`@core/storage/sqlite-outcome-store.js`).
+ * The file is a plain `ReDerivationPair[]` - anything else (corrupt JSON,
+ * a non-array shape) is treated as no pairs rather than thrown.
+ */
+export declare function parseReDerivationPairsFile(raw: string): ReadonlyArray<ReDerivationPair>;
 export declare function computeReDerivationRate(deps: ReDerivationDeps, windowDays: number): Promise<ReDerivationReport>;
 export {};

package/dist/core/metrics/re-derivation.js

@@ -7,6 +7,7 @@
  * entity, sit more than GAP_DAYS apart, have decision text overlapping at or
  * above JACCARD_FLOOR, and have no `continues`/`supersedes` edge linking them.
  */
+import { tenantClause } from "../tenancy/tenant-clause.js";
 const JACCARD_FLOOR = 0.5;
 const GAP_DAYS = 7;
 const MS_PER_DAY = 86_400_000;
@@ -28,16 +29,21 @@ function jaccard(a, b) {
 /**
  * SQLite-backed deps for the CLI readout. Reads sessions started within the
  * window along with their entity links and decision markers, plus all edges.
+ * `tenantId` scopes the sessions SELECT via tenantClause — the pairs this
+ * produces get persisted to a tenant-derived cache file (see
+ * `@core/storage/sqlite-outcome-store.js`), so an un-tenanted scan here would
+ * leak every tenant's sessions into whichever tenant's file reads it back.
  */
-export function sqliteReDerivationDeps(db) {
+export function sqliteReDerivationDeps(db, tenantId) {
+    const tc = tenantClause(tenantId);
     return {
         async listSessionsWithin(windowDays) {
             const rows = db
                 .prepare(`SELECT id, started_at AS startedAt
              FROM sessions
-            WHERE started_at >= datetime('now', ?)
+            WHERE started_at >= datetime('now', ?) AND ${tc.sql}
             ORDER BY started_at ASC`)
-                .all(`-${windowDays} days`);
+                .all(`-${windowDays} days`, tc.param);
             const entStmt = db.prepare("SELECT entity_canonical AS e FROM session_entities WHERE session_id = ?");
             const decStmt = db.prepare("SELECT text AS t FROM markers WHERE session_id = ? AND kind = 'decision' ORDER BY position ASC");
             return rows.map((r) => ({
@@ -54,6 +60,17 @@ export function sqliteReDerivationDeps(db) {
         },
     };
 }
+/**
+ * Parses the on-disk cache the 24h corpus-monitor job writes to
+ * (`~/.nlm/re-derivation-pairs.json`, see `src/cli/nlm.ts`) and the SQLite
+ * outcome adapters read back (`@core/storage/sqlite-outcome-store.js`).
+ * The file is a plain `ReDerivationPair[]` - anything else (corrupt JSON,
+ * a non-array shape) is treated as no pairs rather than thrown.
+ */
+export function parseReDerivationPairsFile(raw) {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+}
 export async function computeReDerivationRate(deps, windowDays) {
     const sessions = await deps.listSessionsWithin(windowDays);
     const edges = await deps.listEdges();
@@ -61,11 +78,16 @@ export async function computeReDerivationRate(deps, windowDays) {
         .filter((e) => e.kind === "continues" || e.kind === "supersedes")
         .map((e) => [e.from_session, e.to_session].sort().join("|")));
     const pairs = [];
+    const reDeriving = new Set();
     let eligible = 0;
     for (let i = 0; i < sessions.length; i++) {
         for (let j = i + 1; j < sessions.length; j++) {
             const s = sessions[i];
             const t = sessions[j];
+            // A decisionless side can never be a re-derivation, so such a pair does
+            // not belong in the denominator at all.
+            if (s.decisions.length === 0 || t.decisions.length === 0)
+                continue;
             const shared = s.entities.filter((e) => t.entities.includes(e));
             if (shared.length === 0)
                 continue;
@@ -79,9 +101,19 @@ export async function computeReDerivationRate(deps, windowDays) {
             const jac = jaccard(s.decisions, t.decisions);
             if (jac >= JACCARD_FLOOR) {
                 pairs.push({ a: s.id, b: t.id, sharedEntities: shared, jaccard: round2(jac) });
+                const later = new Date(t.startedAt).getTime() >= new Date(s.startedAt).getTime() ? t.id : s.id;
+                reDeriving.add(later);
             }
         }
     }
-    return { rate: eligible ? pairs.length / eligible : 0, pairs, eligible };
+    const decisionBearingSessions = sessions.filter((s) => s.decisions.length > 0).length;
+    return {
+        rate: eligible ? pairs.length / eligible : 0,
+        pairs,
+        eligible,
+        decisionBearingSessions,
+        reDerivingSessions: reDeriving.size,
+        sessionRate: decisionBearingSessions ? reDeriving.size / decisionBearingSessions : 0,
+    };
 }
 //# sourceMappingURL=re-derivation.js.map

package/dist/core/metrics/re-derivation.js.map

@@ -1 +1 @@
-{"version":3,"file":"re-derivation.js","sourceRoot":"","sources":["../../../src/core/metrics/re-derivation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"re-derivation.js","sourceRoot":"","sources":["../../../src/core/metrics/re-derivation.ts"],"names":[],"mappings":"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"}

package/dist/core/outcome/coverage.d.ts

@@ -30,4 +30,4 @@ export interface OutcomeCoverage {
     readonly reDerivedLater: number;
     readonly unobserved: number;
 }
-export declare function computeOutcomeCoverage(input: OutcomeCoverageInput): Promise<OutcomeCoverage>;
+export declare function computeOutcomeCoverage(tenantId: string, input: OutcomeCoverageInput): Promise<OutcomeCoverage>;

package/dist/core/outcome/coverage.js

@@ -11,10 +11,10 @@
  * the precedence logic itself is never duplicated, only its I/O is batched.
  */
 import { deriveOutcome } from "./rollup.js";
-export async function computeOutcomeCoverage(input) {
+export async function computeOutcomeCoverage(tenantId, input) {
     const counts = { held: 0, overturned: 0, builtUpon: 0, reDerivedLater: 0, unobserved: 0 };
     for (const session of input.sessions) {
-        const verdict = await deriveOutcome(session.id, {
+        const verdict = await deriveOutcome(tenantId, session.id, {
             sessions: { getById: async () => session },
             signals: { listForSession: async () => input.signalsBySession.get(session.id) ?? [] },
             edges: { listForSession: async () => input.edgesBySession.get(session.id) ?? [] },