@tech-leads-club/harness-toolkit 0.2.1

package/src/core/lesson/lesson.service.ts

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import type { FailureCategory } from "../gate/gate.types.ts";
+import { readProjectLessons, upsertProjectLesson } from "./lesson.store.ts";
+import type { HarnessLesson } from "./lesson.types.ts";
+
+function lessonId(gate: string, fingerprint: string): string {
+  const digest = createHash("sha256").update(`${gate}|${fingerprint}`).digest("hex").slice(0, 12);
+  return `project:${gate}:${digest}`;
+}
+
+function tokensFrom(gate: string, output: string, category: string): string[] {
+  const tokens = new Set<string>([gate, category]);
+  for (const line of output.split("\n").slice(0, 20)) {
+    for (const word of line.toLowerCase().match(/[a-z][a-z0-9_./-]{2,}/g) ?? []) {
+      if (word.length <= 40) {
+        tokens.add(word);
+      }
+      if (tokens.size >= 16) {
+        break;
+      }
+    }
+    if (tokens.size >= 16) {
+      break;
+    }
+  }
+  return [...tokens];
+}
+
+// hazard: `suggestion` used to be a parameter here and was prefixed onto `instruction`. The consumer prints
+// next_action from the same suggestionFor(category, gate) call, so every lesson opened by restating the line
+// the gate had already emitted — duplicated by construction, spending the lessons budget on an echo. What a
+// lesson uniquely knows is the recurring signature and the retry guidance, so that is all it carries.
+const MAX_SESSION_KEYS = 12;
+
+// why: a bounded set, because the count only has to reach `promoteHitCount` and an unbounded list would grow a
+// stored record without limit.
+function withSessionKey(existing: readonly string[], sessionKey: string): string[] {
+  if (!sessionKey || existing.includes(sessionKey)) {
+    return [...existing];
+  }
+  return [...existing, sessionKey].slice(-MAX_SESSION_KEYS);
+}
+
+export async function recordLessonFromFailure(args: {
+  projectDir: string;
+  gate: string;
+  category: FailureCategory;
+  fingerprint: string;
+  output: string;
+  sessionKey: string;
+}): Promise<HarnessLesson> {
+  const now = new Date().toISOString();
+  const id = lessonId(args.gate, args.fingerprint);
+  const existing = readProjectLessons(args.projectDir).find((item) => item.id === id);
+  const snippet = args.output
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .slice(0, 3)
+    .join(" | ")
+    .slice(0, 220);
+
+  if (existing) {
+    const updated: HarnessLesson = {
+      ...existing,
+      hitCount: existing.hitCount + 1,
+      sessionKeys: withSessionKey(existing.sessionKeys, args.sessionKey),
+      lastSeenAt: now,
+      lastAccessedAt: now,
+      updatedAt: now,
+      confidence: Math.min(1, existing.confidence + 0.08),
+      triggerTokens: snippet
+        ? [
+            ...new Set([...existing.triggerTokens, ...tokensFrom(args.gate, args.output, args.category)]),
+          ].slice(0, 16)
+        : existing.triggerTokens,
+    };
+    return upsertProjectLesson(args.projectDir, updated);
+  }
+
+  const lesson: HarnessLesson = {
+    id,
+    scope: "gate-execution",
+    failedGate: args.gate,
+    category: args.category,
+    triggerTokens: tokensFrom(args.gate, args.output, args.category),
+    instruction: `Recurrent failure signature on gate "${args.gate}".${snippet ? ` Signal: ${snippet}` : ""}`,
+    avoid: "Do not repeat the same failing edit, suppression, or command that produced this fingerprint.",
+    prefer: "Change approach using the gate output; verify with the same gate before claiming done.",
+    preRetryCheck: `Re-read the ${args.gate} output and confirm the next edit targets a different root cause.`,
+    source: "project",
+    tier: "project",
+    status: "candidate",
+    confidence: 0.55,
+    hitCount: 1,
+    priority: 70,
+    pinned: false,
+    refs: [],
+    sessionKeys: withSessionKey([], args.sessionKey),
+    injectedCount: 0,
+    gradeableCount: 0,
+    helpedCount: 0,
+    neutralCount: 0,
+    firstSeenAt: now,
+    lastSeenAt: now,
+    lastAccessedAt: now,
+    updatedAt: now,
+  };
+  return upsertProjectLesson(args.projectDir, lesson);
+}

package/src/core/lesson/lesson.store.ts

@@ -0,0 +1,317 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { updateJsonAtomic } from "../../platform/fs-atomic.ts";
+import { projectStateDir, runtimeStateDir } from "../../platform/paths.ts";
+import { divergedMessage, seal, shouldInject, verifySeal } from "../integrity/state-seal.ts";
+import { creditLesson, type LessonVerdict } from "./lesson.credit.ts";
+import type { HarnessLesson, LessonStoreFile, LessonTier } from "./lesson.types.ts";
+
+const EPOCH = "1970-01-01T00:00:00.000Z";
+
+type CoreLessonInput = Pick<
+  HarnessLesson,
+  | "id"
+  | "failedGate"
+  | "category"
+  | "triggerTokens"
+  | "instruction"
+  | "avoid"
+  | "prefer"
+  | "preRetryCheck"
+  | "priority"
+>;
+
+function coreLesson(input: CoreLessonInput): HarnessLesson {
+  return {
+    ...input,
+    scope: "gate-execution",
+    source: "core",
+    tier: "core",
+    status: "active",
+    confidence: 1,
+    hitCount: 1,
+    pinned: false,
+    refs: [],
+    sessionKeys: [],
+    injectedCount: 0,
+    gradeableCount: 0,
+    helpedCount: 0,
+    neutralCount: 0,
+    firstSeenAt: EPOCH,
+    lastSeenAt: EPOCH,
+    lastAccessedAt: EPOCH,
+    updatedAt: EPOCH,
+  };
+}
+
+export const CORE_LESSONS: readonly HarnessLesson[] = [
+  coreLesson({
+    id: "core:gate:lint",
+    failedGate: "lint",
+    category: "verification",
+    triggerTokens: ["lint", "biome", "eslint", "ruff", "format"],
+    instruction:
+      "A lint gate failure means changed files still violate the project lint command. Fix the reported findings without suppressions.",
+    avoid: "Do not add lint suppressions, disable comments, or delete failing files to silence the gate.",
+    prefer: "Apply the smallest fix that clears each finding, then let the stop hook re-check.",
+    preRetryCheck:
+      "Confirm the lint command targets only the intended changed files and still fails for the same codes.",
+    priority: 90,
+  }),
+  coreLesson({
+    id: "core:gate:test",
+    failedGate: "test",
+    category: "verification",
+    triggerTokens: ["test", "vitest", "jest", "pytest", "failing"],
+    instruction:
+      "A test gate failure means assertions still fail. Fix the behavior or the test under the real contract — do not delete or skip tests.",
+    avoid: "Do not delete failing tests, mark them skipped, or weaken assertions to force green.",
+    prefer: "Reproduce the failure, fix root cause, re-run the same test target.",
+    preRetryCheck: "Identify the failing test name/file from the gate output before editing.",
+    priority: 90,
+  }),
+  coreLesson({
+    id: "core:gate:comments",
+    failedGate: "comments",
+    category: "verification",
+    triggerTokens: ["junk comment", "TODO", "FIXME", "banner"],
+    instruction:
+      "Junk-comment policy failed. Delete narrating comments, banners, TODO/FIXME, and commented-out code.",
+    avoid: "Do not keep TODO markers or section banners 'for clarity'.",
+    prefer: "Keep only comments that explain a non-obvious why (invariant, hazard, external constraint).",
+    preRetryCheck: "Scan the listed file:line hits and remove each one.",
+    priority: 80,
+  }),
+  coreLesson({
+    id: "core:gate:ship",
+    failedGate: "ship",
+    category: "ship-evidence",
+    triggerTokens: ["ship", "evidence", "90-verdict", "PASS"],
+    instruction:
+      "Ship claim without recent production PASS evidence. Produce real evidence before claiming done.",
+    avoid: "Do not claim shipped based on unit tests alone when runtime paths changed.",
+    prefer: "Run production E2E, write 90-verdict.txt PASS, cite the evidence path.",
+    preRetryCheck: "Confirm evidenceDir and a recent PASS verdict exist for this change.",
+    priority: 95,
+  }),
+  coreLesson({
+    id: "core:gate:empty-diff",
+    failedGate: "empty-diff",
+    category: "ship-evidence",
+    triggerTokens: ["empty", "diff", "no changes", "shipped"],
+    instruction:
+      "Done/shipped was claimed with zero file changes. Either implement the work or explain why zero-diff is correct — do not claim shipped on an empty tree.",
+    avoid: "Do not restate 'done' without a real diff or an explicit zero-change justification.",
+    prefer: "Make the missing change, or clearly document why no files should change.",
+    preRetryCheck: "Inspect git status / changed files before the next stop.",
+    priority: 92,
+  }),
+  coreLesson({
+    id: "core:gate:stagnation",
+    failedGate: "stagnation",
+    category: "stagnation",
+    triggerTokens: ["stagnation", "identical", "fingerprint", "same fail"],
+    instruction:
+      "Identical validation fingerprint repeated. Change approach — do not re-apply the same failing edit.",
+    avoid: "Do not retry the exact same patch, command, or suppression.",
+    prefer: "Diagnose root cause with a different path, or escalate with BLOCKED / TRIED / NEED.",
+    preRetryCheck: "Diff your last edit against the gate output; ensure the next action is different.",
+    priority: 100,
+  }),
+];
+
+export function lessonsStorePath(root: string): string {
+  return join(projectStateDir(root), "lessons.json");
+}
+
+// why: one store for every repository on the machine. The per-repo store stays authoritative for this
+// repository; this is the tier that follows the operator across products ([/decisions/ad-040.md](/decisions/ad-040.md)).
+export function globalLessonsStorePath(): string {
+  return join(runtimeStateDir(), "lessons.json");
+}
+
+function storePathFor(root: string, tier: Exclude<LessonTier, "core">): string {
+  return tier === "global" ? globalLessonsStorePath() : lessonsStorePath(root);
+}
+
+// hazard: a record written before a field existed reads as `undefined`, and `undefined` propagated into
+// `hitCount + 1` or `refs.length` throws or poisons a comparator. Every read normalizes, so no consumer has to.
+function normalizeLesson(raw: HarnessLesson, tier: LessonTier): HarnessLesson {
+  return {
+    ...raw,
+    tier,
+    pinned: raw.pinned === true,
+    refs: Array.isArray(raw.refs) ? raw.refs : [],
+    sessionKeys: Array.isArray(raw.sessionKeys) ? raw.sessionKeys : [],
+    injectedCount: Number.isFinite(raw.injectedCount) ? raw.injectedCount : 0,
+    gradeableCount: Number.isFinite(raw.gradeableCount) ? raw.gradeableCount : 0,
+    helpedCount: Number.isFinite(raw.helpedCount) ? raw.helpedCount : 0,
+    neutralCount: Number.isFinite(raw.neutralCount) ? raw.neutralCount : 0,
+  };
+}
+
+function readStore(path: string, tier: LessonTier): HarnessLesson[] {
+  if (!existsSync(path)) {
+    return [];
+  }
+  try {
+    const file = JSON.parse(readFileSync(path, "utf8")) as LessonStoreFile;
+    return Array.isArray(file.lessons) ? file.lessons.map((lesson) => normalizeLesson(lesson, tier)) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * why: the project store only. The global store is written by sessions in other repositories, so a per-project
+ * seal would diverge on every legitimate cross-project write ([/decisions/ad-078.md](/decisions/ad-078.md)).
+ */
+export function projectLessonsInjectable(root: string): { ok: boolean; note: string | null } {
+  const target = lessonsStorePath(root);
+  const verdict = verifySeal(target);
+  return shouldInject(verdict)
+    ? { ok: true, note: null }
+    : { ok: false, note: divergedMessage(target, "The project lesson store") };
+}
+
+export function readProjectLessons(root: string): HarnessLesson[] {
+  return readStore(lessonsStorePath(root), "project");
+}
+
+export function readGlobalLessons(): HarnessLesson[] {
+  return readStore(globalLessonsStorePath(), "global");
+}
+
+// invariant: the nearer tier wins on a duplicate id. A project that has taken a global lesson and rewritten it
+// reads its own version, and the same lesson is never injected twice.
+export function allLessons(root: string): HarnessLesson[] {
+  const byId = new Map<string, HarnessLesson>();
+  for (const lesson of [...CORE_LESSONS, ...readGlobalLessons(), ...readProjectLessons(root)]) {
+    byId.set(lesson.id, lesson);
+  }
+  return [...byId.values()];
+}
+
+async function mutateStore(
+  path: string,
+  tier: LessonTier,
+  mutate: (current: HarnessLesson[]) => HarnessLesson[],
+): Promise<HarnessLesson[]> {
+  const file = await updateJsonAtomic<LessonStoreFile>(
+    path,
+    (current) => {
+      const lessons = current && Array.isArray(current.lessons) ? current.lessons : [];
+      return { version: 1, lessons: mutate(lessons.map((lesson) => normalizeLesson(lesson, tier))) };
+    },
+    { lockPath: `${path}.lock`, afterWrite: seal },
+  );
+  return file.lessons;
+}
+
+export async function writeProjectLessons(root: string, lessons: HarnessLesson[]): Promise<void> {
+  await mutateStore(lessonsStorePath(root), "project", () => lessons);
+}
+
+function upsert(lessons: HarnessLesson[], lesson: HarnessLesson): HarnessLesson[] {
+  const index = lessons.findIndex((item) => item.id === lesson.id);
+  if (index < 0) {
+    return [...lessons, lesson];
+  }
+  const next = [...lessons];
+  next[index] = lesson;
+  return next;
+}
+
+export async function upsertProjectLesson(root: string, lesson: HarnessLesson): Promise<HarnessLesson> {
+  const saved = { ...lesson, tier: "project" as const };
+  await mutateStore(lessonsStorePath(root), "project", (current) => upsert(current, saved));
+  return saved;
+}
+
+export async function upsertGlobalLesson(lesson: HarnessLesson): Promise<HarnessLesson> {
+  const saved = { ...lesson, tier: "global" as const };
+  await mutateStore(globalLessonsStorePath(), "global", (current) => upsert(current, saved));
+  return saved;
+}
+
+export async function upsertLesson(
+  root: string,
+  lesson: HarnessLesson,
+  tier: Exclude<LessonTier, "core">,
+): Promise<HarnessLesson> {
+  return tier === "global" ? upsertGlobalLesson(lesson) : upsertProjectLesson(root, lesson);
+}
+
+async function mutateWritableTiers(
+  root: string,
+  ids: readonly string[],
+  patch: (lesson: HarnessLesson) => HarnessLesson,
+): Promise<void> {
+  if (ids.length === 0) {
+    return;
+  }
+  const idSet = new Set(ids);
+  // why: an injected set can span both writable tiers, so both are visited. Core is skipped because it is
+  // shipped and identical everywhere — a counter on it would be a per-machine edit to a constant.
+  for (const tier of ["project", "global"] as const) {
+    const path = storePathFor(root, tier);
+    if (!existsSync(path)) {
+      continue;
+    }
+    await mutateStore(path, tier, (current) =>
+      current.map((lesson) => (idSet.has(lesson.id) ? patch(lesson) : lesson)),
+    );
+  }
+}
+
+export async function touchAccessed(root: string, ids: string[], now = new Date()): Promise<void> {
+  const iso = now.toISOString();
+  await mutateWritableTiers(root, ids, (lesson) => ({
+    ...lesson,
+    lastAccessedAt: iso,
+    updatedAt: iso,
+    injectedCount: lesson.injectedCount + 1,
+  }));
+}
+
+/**
+ * Marks an injection as one a later gate run can grade.
+ *
+ * why: called where the pending credit is written, so the counter and the credit cannot disagree. Counting it at
+ * injection time instead would include session-start injections, which nothing ever grades
+ * ([/decisions/ad-044.md](/decisions/ad-044.md)).
+ */
+export async function markGradeable(root: string, ids: readonly string[], now = new Date()): Promise<void> {
+  const iso = now.toISOString();
+  await mutateWritableTiers(root, ids, (lesson) => ({
+    ...lesson,
+    gradeableCount: lesson.gradeableCount + 1,
+    updatedAt: iso,
+  }));
+}
+
+export async function creditLessons(
+  root: string,
+  ids: readonly string[],
+  verdict: LessonVerdict,
+  now = new Date(),
+): Promise<void> {
+  const iso = now.toISOString();
+  await mutateWritableTiers(root, ids, (lesson) => creditLesson(lesson, verdict, iso));
+}
+
+export async function gardenProjectLessons(
+  root: string,
+  mutate: (current: HarnessLesson[]) => HarnessLesson[],
+): Promise<HarnessLesson[]> {
+  return mutateStore(lessonsStorePath(root), "project", mutate);
+}
+
+export async function gardenGlobalLessons(
+  mutate: (current: HarnessLesson[]) => HarnessLesson[],
+): Promise<HarnessLesson[]> {
+  if (!existsSync(globalLessonsStorePath())) {
+    return [];
+  }
+  return mutateStore(globalLessonsStorePath(), "global", mutate);
+}

package/src/core/lesson/lesson.sync.ts

@@ -0,0 +1,70 @@
+/**
+ * How the durable provider view is decided. `auto` asks the host: a provider that does not deliver context from
+ * its session-start hook has no other route, so the view is written there and not where the hook works
+ * ([/decisions/ad-050.md](/decisions/ad-050.md)).
+ */
+export type LessonsSyncMode = "auto" | "always" | "never";
+
+export type SyncModeResolution = {
+  mode: LessonsSyncMode;
+  /** The boolean this mode was read from, when a config predating the mode is still in place. */
+  coercedFrom?: boolean;
+  /**
+   * hazard: the file the coerced value is actually in. The migration line named the project config unconditionally
+   * and the value can come from the runtime home, so it sent an operator to edit a file that did not have it.
+   */
+  coercedIn?: string;
+};
+
+/**
+ * hazard: `.tlc/harness/config.json` is merged structurally and never validated, so the field arrives as whatever
+ * the operator wrote. A config carrying the old boolean would have compared unequal to every mode and silently
+ * read as `auto`, turning an explicit `false` into a file the operator had switched off.
+ */
+export function resolveSyncMode(raw: unknown): SyncModeResolution {
+  if (raw === true) {
+    return { mode: "always", coercedFrom: true };
+  }
+  if (raw === false) {
+    return { mode: "never", coercedFrom: false };
+  }
+  if (raw === "always" || raw === "never" || raw === "auto") {
+    return { mode: raw };
+  }
+  return { mode: "auto" };
+}
+
+export function lessonsSyncMode(raw: unknown): LessonsSyncMode {
+  return resolveSyncMode(raw).mode;
+}
+
+export type DurableViewVerdict = {
+  writes: boolean;
+  /** Why, in the operator's terms. `lessons status` prints this, so a view that is not written says so. */
+  reason: string;
+};
+
+/**
+ * why: the verdict carries a reason, following `appendFilesVerdict`. A capability that silently does nothing is the
+ * defect this project keeps finding; one that says why is a configuration choice.
+ */
+export function durableViewVerdict(mode: LessonsSyncMode, hookContextReliable: boolean): DurableViewVerdict {
+  if (mode === "never") {
+    return { writes: false, reason: "syncRulesFile is set to never" };
+  }
+  if (mode === "always") {
+    return { writes: true, reason: "syncRulesFile is set to always" };
+  }
+  if (hookContextReliable) {
+    return {
+      writes: false,
+      reason:
+        "this provider delivers context from its session-start hook, so lessons arrive without a rules file",
+    };
+  }
+  return {
+    writes: true,
+    reason:
+      "this provider does not deliver context from its session-start hook, so the durable view is the route",
+  };
+}

package/src/core/lesson/lesson.types.ts

@@ -0,0 +1,92 @@
+export type LessonStatus = "candidate" | "active" | "quarantine";
+
+/** How the lesson was learned. Provenance, not location — see {@link LessonTier}. */
+export type LessonSource = "core" | "project" | "manual";
+
+/**
+ * Where the lesson lives, which decides who sees it: `core` ships in the runtime, `global` is this machine and
+ * every product on it, `project` is this repository alone.
+ *
+ * invariant: nothing moves between tiers on its own ([/decisions/ad-040.md](/decisions/ad-040.md)).
+ */
+export type LessonTier = "core" | "global" | "project";
+
+/** A repository-relative reference to the thing that makes a lesson true. */
+export type LessonLink = {
+  path: string;
+  symbol?: string;
+};
+
+export type LessonLinkStatus = "present" | "path-missing" | "symbol-missing" | "unreadable";
+
+/**
+ * hazard: `unproven` is not a passing reading — it means the lesson was injected and no gate run has graded it.
+ * `not-injected` is the separate, uninteresting case, kept apart so a store of brand-new lessons does not read as
+ * a store of unjustified ones ([/decisions/ad-039.md](/decisions/ad-039.md)).
+ */
+export type LessonEffectiveness = "helped" | "neutral" | "unproven" | "not-injected";
+
+export type HarnessLesson = {
+  id: string;
+  scope: "gate-execution";
+  failedGate: string;
+  category: string;
+  triggerTokens: string[];
+  instruction: string;
+  avoid: string;
+  prefer: string;
+  preRetryCheck: string;
+  source: LessonSource;
+  // invariant: derived on read from the store the lesson came out of, never trusted from the file.
+  tier: LessonTier;
+  status: LessonStatus;
+  confidence: number;
+  hitCount: number;
+  priority: number;
+  /**
+   * A standing rule the operator does not want ranked. Pinned lessons are placed before every scored lesson,
+   * still subject to staleness, validity and the char budget.
+   *
+   * why: ranking is built for lessons the harness inferred from failures. An instruction the operator wrote
+   * deliberately competes with those on confidence and priority and loses to a shipped seed, so it is written,
+   * stored, correct, and never delivered ([/decisions/ad-043.md](/decisions/ad-043.md)).
+   */
+  pinned: boolean;
+  /** What makes this lesson true. Empty means it is about conduct and cannot go stale. */
+  refs: LessonLink[];
+  staleReason?: LessonLinkStatus;
+  staleCheckedAt?: string;
+  validFrom?: string;
+  validTo?: string;
+  // why: promotion counts these, not `hitCount` — one stuck session repeating a failure is one observation of
+  // the world, not several ([/decisions/ad-038.md](/decisions/ad-038.md)).
+  sessionKeys: string[];
+  /** Times selected for injection, in any mode. */
+  injectedCount: number;
+  /**
+   * Times injected **for a gate**, which is the only injection a later gate run can grade.
+   *
+   * hazard: `injectedCount` counts session-start injections too, and those are never graded — a lesson whose gate
+   * is `any` is not eligible on a retry at all, so judging it by `injectedCount` warned "unproven" forever on a
+   * perfectly healthy store ([/decisions/ad-044.md](/decisions/ad-044.md)).
+   */
+  gradeableCount: number;
+  helpedCount: number;
+  neutralCount: number;
+  firstSeenAt: string;
+  lastSeenAt: string;
+  lastAccessedAt: string;
+  updatedAt: string;
+};
+
+export type LessonStoreFile = {
+  version: 1;
+  lessons: HarnessLesson[];
+};
+
+/** A gate's injected lessons awaiting a verdict, carried on the handoff between one stop and the next. */
+export type PendingLessonCredit = {
+  gate: string;
+  ids: string[];
+  at: string;
+};

package/src/core/lesson/lesson.validity.ts

@@ -0,0 +1,44 @@
+import type { HarnessLesson } from "./lesson.types.ts";
+
+type Boundary = "absent" | "invalid" | number;
+
+function boundary(iso: string | undefined): Boundary {
+  if (iso === undefined || iso.trim() === "") {
+    return "absent";
+  }
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : "invalid";
+}
+
+// invariant: an unparseable bound fails the window. A lesson whose validity cannot be evaluated is withheld,
+// never injected.
+export function isWithinValidity(lesson: HarnessLesson, now: Date): boolean {
+  const nowMs = now.getTime();
+  const from = boundary(lesson.validFrom);
+  if (from === "invalid" || (typeof from === "number" && from > nowMs)) {
+    return false;
+  }
+  const to = boundary(lesson.validTo);
+  if (to === "invalid" || (typeof to === "number" && to <= nowMs)) {
+    return false;
+  }
+  return true;
+}
+
+export function validityReason(
+  lesson: HarnessLesson,
+  now: Date,
+): "active" | "pending" | "expired" | "invalid" {
+  const from = boundary(lesson.validFrom);
+  const to = boundary(lesson.validTo);
+  if (from === "invalid" || to === "invalid") {
+    return "invalid";
+  }
+  if (typeof from === "number" && from > now.getTime()) {
+    return "pending";
+  }
+  if (typeof to === "number" && to <= now.getTime()) {
+    return "expired";
+  }
+  return "active";
+}