nlm-memory 0.21.0 → 0.21.13

package/dist/core/jobs/job-supervisor.js

@@ -0,0 +1,335 @@
+/**
+ * JobSupervisor — owns at most one child `reprocess` run at a time.
+ *
+ * Built because a detached `nlm reprocess` died on a V8 OOM and sat dead
+ * ~16h unobserved (twice: 07-27 and 07-27→08-03). Supervision now lives in
+ * the daemon instead of a bolt-on watchdog script: this class tracks a
+ * single child process's progress, restarts it on a non-clean exit while
+ * work remains, and reports stalls when the child is alive but stuck.
+ *
+ * One job type only (reprocess) — no generic job framework (YAGNI). Ports
+ * (`spawnChild`, `clock`) are injected so this stays pure-core: no real
+ * child_process, no real timers, testable with fakes. Same posture as
+ * `ScanScheduler` (src/core/scheduler/scheduler.ts).
+ *
+ * Progress-line format verified directly in src/cli/nlm.ts's `reprocess`
+ * command (the only place reprocess's `onProgress` callback is wired to
+ * output — reprocess.ts itself never prints, it just calls the callback):
+ *
+ *   process.stderr.write(`  [${i}/${n}] ${sid}  ${status}\n`);
+ *
+ * i.e. two leading spaces, `[i/n]` (no zero-padding), a single space, the
+ * session id, TWO spaces, then a status word (`ok`, `empty_body`,
+ * `classify_failed`, or `ingest_failed`). The plan's assumed format
+ * (`[N/total] <id> ok`) was close but understated the leading indent and
+ * the double space before status. `processed` in reprocess.ts increments
+ * on every branch (success or failure), so ANY line matching `[i/n]` is a
+ * genuine advance regardless of the trailing status word — the parser
+ * below only needs the two numbers.
+ *
+ * Restart policy: child exit with work remaining → re-spawn same args, up
+ * to `maxRestartsWithoutProgress` (default 3) consecutive restarts with no
+ * progress observed since the last one. A progress line resets the
+ * counter to 0. Exceeding the cap fires `{kind: "exhausted"}` and stops
+ * respawning. "Work remaining" is `code !== 0` (covers OOM/signal kills
+ * and any non-clean exit, including one where no progress line was ever
+ * seen) OR `processed < total` on an otherwise-clean exit — reprocess only
+ * exits 0 after its `work` loop finishes every item, so a clean exit with
+ * `processed < total` is a defensive fallback, not the expected path.
+ *
+ * Stall: child alive, no progress advance for `stallMinutes` (default 20,
+ * from `NLM_JOB_STALL_MINUTES`) → fires `{kind: "stalled"}` ONCE per stall
+ * episode. A later progress advance ends the episode (state returns to
+ * "running"); a subsequent stall re-arms and can fire again. Checked on a
+ * coarse interval behind the injected `clock` port so tests never need
+ * real timers.
+ *
+ * `restarts` in both the snapshot and event payloads is the
+ * restarts-without-progress counter (reset by any advance), not a
+ * lifetime total — it directly explains "why is this run stalled/
+ * exhausted" the way an operator reading /api/health would want. It counts
+ * only respawns that actually happened: the cap check runs BEFORE the
+ * increment, so an exhausted run's `restarts` equals the number of real
+ * respawns performed (== `maxRestartsWithoutProgress`), never that value
+ * plus the refused final attempt.
+ *
+ * `restartsTotal` is a companion lifetime counter: every successful respawn
+ * increments it, and unlike `restarts` it is never reset by progress —
+ * only a fresh `start()` resets it to 0. It exists because `restarts`
+ * resetting on every advance makes OOM churn invisible on a long run (a job
+ * that OOM-restarts 40 times but keeps making progress between crashes
+ * reports `restarts: 0`); `restartsTotal` is the "how much churn has this
+ * run actually had" number surfaced alongside it.
+ *
+ * State machine: "idle" (never started, or this JobSupervisor instance's
+ * initial state — not one of the plan's five snapshot states, but the
+ * natural "no job block" representation Task 2's health-route mapping
+ * needs) → "running" → ("stalled" ⇄ "running" across stall episodes) →
+ * terminal "completed" | "exhausted" | "stopped". A terminal state is
+ * left only by calling `start()` again, which begins a fresh run.
+ *
+ * Spawn-failure safety: `spawnChild` can throw synchronously (EMFILE,
+ * ENOMEM, a bad binary path) instead of returning a handle — both at
+ * `start()` and at every mid-run respawn inside `handleExit`. Both call
+ * sites wrap `spawnAndWire()` in try/catch: on a thrown spawn, the run
+ * lands in the terminal "exhausted" state (never leaves `state` reading
+ * "running" with no child) and fires a `{kind: "spawn_failed"}` event so
+ * an operator can tell "never got off the ground" apart from "ran out of
+ * restart budget". `start()` still rethrows the original error after
+ * landing that terminal state, preserving its existing contract (the HTTP
+ * route at `POST /api/jobs/reprocess` catches the throw and returns a
+ * clean 500) — the fix is that by the time it throws, `snapshot()` already
+ * reads a terminal state, so a subsequent `start()` call is not refused
+ * with "already active" and a subsequent POST does not 409 forever.
+ * `handleExit` has no caller to rethrow to (it runs off an async `onExit`
+ * callback), so it only logs and stops there.
+ *
+ * Stale-callback safety: `spawnAndWire` captures the child instance it just
+ * spawned and every onLine/onExit callback checks `this.child === child`
+ * before touching any state. A killed child (stop(), or a fast respawn
+ * chain) can still deliver a queued exit or line after this.child has moved
+ * on to a newer child or gone null; without the identity guard that stale
+ * delivery would corrupt the live run's processed/total/restarts, null out
+ * the live child (leaking it — now unmanaged and unkillable), or trigger a
+ * bogus respawn.
+ */
+const DEFAULT_STALL_MINUTES = 20;
+const DEFAULT_MAX_RESTARTS_WITHOUT_PROGRESS = 3;
+const DEFAULT_STALL_CHECK_INTERVAL_MS = 60_000;
+// Matches the two-space-indented `[i/n] <sid>  <status>` verbose line reprocess's
+// CLI wiring writes (src/cli/nlm.ts, reprocess command). Only the counters
+// matter: reprocess increments `processed` on every outcome branch, so any
+// line of this shape is an advance regardless of what follows it.
+const PROGRESS_RE = /^\s*\[(\d+)\/(\d+)\]/;
+function stallMinutesFromEnv() {
+    const raw = process.env["NLM_JOB_STALL_MINUTES"];
+    if (raw === undefined)
+        return DEFAULT_STALL_MINUTES;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_STALL_MINUTES;
+}
+export class JobSupervisor {
+    spawnChildFn;
+    clock;
+    onEventCb;
+    stallMs;
+    maxRestartsWithoutProgress;
+    log;
+    state = "idle";
+    args = [];
+    child = null;
+    processed = 0;
+    total = 0;
+    startedAt = null;
+    lastAdvanceAt = null;
+    restarts = 0;
+    restartsTotal = 0;
+    stallEpisodeFired = false;
+    stopRequested = false;
+    constructor(opts) {
+        this.spawnChildFn = opts.spawnChild;
+        this.clock = opts.clock;
+        this.onEventCb = opts.onEvent ?? (() => { });
+        this.stallMs = (opts.stallMinutes ?? stallMinutesFromEnv()) * 60_000;
+        this.maxRestartsWithoutProgress =
+            opts.maxRestartsWithoutProgress ?? DEFAULT_MAX_RESTARTS_WITHOUT_PROGRESS;
+        this.log = opts.log ?? ((msg) => console.error(msg));
+        const stallCheckIntervalMs = opts.stallCheckIntervalMs ?? DEFAULT_STALL_CHECK_INTERVAL_MS;
+        this.clock.setInterval(() => this.checkStall(), stallCheckIntervalMs);
+    }
+    /** Starts a new run. Refuses (throws) if a run is already active. */
+    start(args) {
+        if (this.state === "running" || this.state === "stalled") {
+            throw new Error("reprocess job already active");
+        }
+        this.args = args;
+        this.processed = 0;
+        this.total = 0;
+        this.restarts = 0;
+        this.restartsTotal = 0;
+        this.stallEpisodeFired = false;
+        this.stopRequested = false;
+        this.startedAt = new Date(this.clock.now()).toISOString();
+        this.lastAdvanceAt = null;
+        this.state = "running";
+        try {
+            this.spawnAndWire();
+        }
+        catch (e) {
+            this.child = null;
+            this.state = "exhausted";
+            this.emitEvent({
+                kind: "spawn_failed",
+                job: "reprocess",
+                processed: this.processed,
+                total: this.total,
+                restarts: this.restarts,
+                restartsTotal: this.restartsTotal,
+                lastAdvanceAt: this.lastAdvanceAt,
+            });
+            throw e;
+        }
+    }
+    /** Kills the active child (if any) and moves to "stopped". No-op if idle/terminal. */
+    stop() {
+        if (this.state !== "running" && this.state !== "stalled")
+            return;
+        this.stopRequested = true;
+        const child = this.child;
+        this.child = null;
+        this.state = "stopped";
+        try {
+            child?.kill();
+        }
+        catch (e) {
+            this.log(`[job-supervisor] kill failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    snapshot() {
+        return {
+            name: "reprocess",
+            state: this.state,
+            processed: this.processed,
+            total: this.total,
+            startedAt: this.startedAt,
+            lastAdvanceAt: this.lastAdvanceAt,
+            restarts: this.restarts,
+            restartsTotal: this.restartsTotal,
+        };
+    }
+    spawnAndWire() {
+        const child = this.spawnChildFn(this.args);
+        this.child = child;
+        // Identity-guard every callback against `this.child`: a killed-but-not-yet-
+        // exited child (stop(), or a respawn racing a slow exit/line delivery) can
+        // still deliver onLine/onExit after this.child has moved on to a newer
+        // child (or null). Without this guard a stale callback from child A would
+        // mutate state for the live run, null out this.child (leaking A's
+        // now-unmanaged, unkillable successor if A had one), or trigger a bogus
+        // restart/respawn.
+        child.onLine((line) => {
+            if (this.child !== child)
+                return;
+            try {
+                this.handleLine(line);
+            }
+            catch (e) {
+                this.log(`[job-supervisor] onLine handler error: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        });
+        child.onExit((code) => {
+            if (this.child !== child)
+                return;
+            try {
+                this.handleExit(code);
+            }
+            catch (e) {
+                this.log(`[job-supervisor] onExit handler error: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        });
+    }
+    handleLine(line) {
+        const match = PROGRESS_RE.exec(line);
+        if (!match)
+            return;
+        const processed = Number(match[1]);
+        const total = Number(match[2]);
+        if (!Number.isFinite(processed) || !Number.isFinite(total))
+            return;
+        this.processed = processed;
+        this.total = total;
+        this.lastAdvanceAt = new Date(this.clock.now()).toISOString();
+        this.restarts = 0;
+        if (this.state === "stalled")
+            this.state = "running";
+        this.stallEpisodeFired = false;
+    }
+    handleExit(code) {
+        this.child = null;
+        if (this.stopRequested)
+            return; // stop() already set state to "stopped"
+        const workRemaining = code !== 0 || (this.total > 0 && this.processed < this.total);
+        if (!workRemaining) {
+            this.state = "completed";
+            return;
+        }
+        // Checked BEFORE incrementing: `restarts` only counts respawns that
+        // actually happened, so exhaustion trips exactly when that many real
+        // respawns have already been spent — the emitted `restarts` on the
+        // "exhausted" event below is never one higher than the real count.
+        if (this.restarts >= this.maxRestartsWithoutProgress) {
+            this.state = "exhausted";
+            this.emitEvent({
+                kind: "exhausted",
+                job: "reprocess",
+                processed: this.processed,
+                total: this.total,
+                restarts: this.restarts,
+                restartsTotal: this.restartsTotal,
+                lastAdvanceAt: this.lastAdvanceAt,
+            });
+            return;
+        }
+        this.state = "running";
+        this.stallEpisodeFired = false;
+        try {
+            this.spawnAndWire();
+        }
+        catch (e) {
+            this.child = null;
+            this.state = "exhausted";
+            this.log(`[job-supervisor] respawn failed: ${e instanceof Error ? e.message : String(e)}`);
+            this.emitEvent({
+                kind: "spawn_failed",
+                job: "reprocess",
+                processed: this.processed,
+                total: this.total,
+                restarts: this.restarts,
+                restartsTotal: this.restartsTotal,
+                lastAdvanceAt: this.lastAdvanceAt,
+            });
+            return;
+        }
+        this.restarts += 1;
+        this.restartsTotal += 1;
+    }
+    checkStall() {
+        try {
+            if (this.state !== "running" && this.state !== "stalled")
+                return;
+            if (!this.child)
+                return;
+            if (this.stallEpisodeFired)
+                return;
+            const referenceIso = this.lastAdvanceAt ?? this.startedAt;
+            if (!referenceIso)
+                return;
+            const elapsed = this.clock.now() - Date.parse(referenceIso);
+            if (elapsed < this.stallMs)
+                return;
+            this.stallEpisodeFired = true;
+            this.state = "stalled";
+            this.emitEvent({
+                kind: "stalled",
+                job: "reprocess",
+                processed: this.processed,
+                total: this.total,
+                restarts: this.restarts,
+                restartsTotal: this.restartsTotal,
+                lastAdvanceAt: this.lastAdvanceAt,
+            });
+        }
+        catch (e) {
+            this.log(`[job-supervisor] stall check error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    emitEvent(event) {
+        try {
+            this.onEventCb(event);
+        }
+        catch (e) {
+            this.log(`[job-supervisor] onEvent handler threw: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+}
+//# sourceMappingURL=job-supervisor.js.map

package/dist/core/jobs/job-supervisor.js.map

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

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>;