@dzhechkov/harness-core 0.8.10 → 0.8.20

package/src/codex-hooks-assets.ts

@@ -29,18 +29,26 @@
  */
 
 import { DZ_HOOK_HELPER_VERSION } from './codex-hooks.js';
+import { harnessCoreDistDir } from './harness-core-location.js';
 
 /** Shared prologue: payload read, project-root walk, never-throw error note. */
-function preamble(): string {
+function preamble(installedDistDir: string | null): string {
   return `#!/usr/bin/env node
 // GENERATED by @dzhechkov/harness-core — dz-hook-helper-version: ${DZ_HOOK_HELPER_VERSION}
 // Do not edit: dz rewrites this file, and any edit disarms the hook until it is re-trusted.
 'use strict';
 const fs = require('node:fs');
 const path = require('node:path');
+const { pathToFileURL } = require('node:url');
 
 const HELPER_VERSION = ${DZ_HOOK_HELPER_VERSION};
 const CODEX_HOME = process.env.CODEX_HOME || path.join(require('node:os').homedir(), '.codex');
+// The harness-core installation that EMITTED this helper, baked in at emission time.
+// MEASURED 2026-09-05: with only the two project-relative candidates below, the documented
+// global install ('npm i -g @dzhechkov/harness-cli') left every target repository without a
+// resolvable module — every shell call reached 'guard not loaded' and was ALLOWED. It is null
+// when the emitter could not name its own location; the project candidates still apply.
+const INSTALLED_CORE_DIST = ${installedDistDir === null ? 'null' : JSON.stringify(installedDistDir)};
 const ERROR_LOG = path.join(CODEX_HOME, 'dz-hooks', 'helper-errors.jsonl');
 
 /**
@@ -141,35 +149,77 @@ function readProjectConfig(root) {
   }
 }
 
-/** Load a built module from the project's own harness-core, or null. Never throws. */
-function loadCore(root, fileName, predicate) {
+/**
+ * Load a built module from the project's own harness-core. Never throws.
+ *
+ * \`import()\`, NEVER \`require()\`. \`@dzhechkov/harness-core\` is \`"type": "module"\`, so every file in
+ * its \`dist/\` is an ES module, while this package supports \`node >= 20\`. \`require()\` of an ES
+ * module was only unflagged in Node 20.19 / 22.12 — below that it throws ERR_REQUIRE_ESM, this
+ * loader turned that into \`null\`, and a \`null\` policy is a SILENT allow. MEASURED 2026-09-05 on
+ * this machine, reproducing the old loader with the flag that turns the unflagging back off:
+ *   node --no-experimental-require-module <veto helper>  on  \`rm -rf .agentic-qe\`
+ *   ⇒ exit 0 and an EMPTY stderr — the guard was not weak there, it was absent and mute.
+ * \`import()\` loads BOTH module kinds on every supported Node, so there is one loader instead of one
+ * that happens to work on the runtime that ran the tests.
+ *
+ * Returns \`{ mod, reason }\`. \`reason\` is the cause that was OBSERVED — the module id plus the code
+ * Node reported for it — never a cause we assumed: a warning that says "no build" about an
+ * ERR_REQUIRE_ESM sends the reader to fix something that is not broken.
+ */
+async function loadCoreDetailed(root, fileName, predicate) {
   const candidates = [
     path.join(root, 'node_modules', '@dzhechkov', 'harness-core', 'dist', fileName),
     path.join(root, 'packages', '@dzhechkov', 'harness-core', 'dist', fileName),
   ];
+  // The emitting installation is the LAST resort, never the first: a project that ships its own
+  // harness-core must keep using its own copy rather than being pinned to whatever emitted the hook.
+  if (INSTALLED_CORE_DIST !== null) candidates.push(path.join(INSTALLED_CORE_DIST, fileName));
+  const failures = [];
   for (const candidate of candidates) {
     try {
-      if (!fs.existsSync(candidate)) continue;
-      const mod = require(candidate);
-      if (predicate(mod)) return mod;
+      const mod = await import(pathToFileURL(candidate).href);
+      if (predicate(mod)) return { mod: mod, reason: null };
+      if (mod.default && predicate(mod.default)) return { mod: mod.default, reason: null };
+      failures.push(candidate + ': загружен, но нужный экспорт отсутствует');
     } catch (err) {
-      note('load-core:' + fileName, err);
+      const code = (err && err.code) || 'ERR_UNKNOWN';
+      failures.push(candidate + ': ' + code + ' ' + String((err && err.message) || err));
+      // An absent optional module is the ORDINARY case (a project may not ship every policy), so it
+      // does not earn a durable note; anything else is a real load failure and does.
+      if (code !== 'ERR_MODULE_NOT_FOUND') note('load-core:' + fileName, err);
     }
   }
-  return null;
+  return { mod: null, reason: failures.join(' | ').replace(/\\s*\\n\\s*/g, ' ') };
+}
+
+/** The module only, for callers that have nothing to say about WHY it is missing. */
+async function loadCore(root, fileName, predicate) {
+  return (await loadCoreDetailed(root, fileName, predicate)).mod;
 }
 `;
 }
 
 /**
- * The PreToolUse veto helper.
+ * The PreToolUse veto helper — TWO checks behind one registry entry.
+ *
+ * 1. The destructive-command guard (feature `destructive-command-guard`, ADR-001): a deletion by a
+ *    LITERAL path into a protected store (`.dz/`, `.agentic-qe/`, a database file). It blocks
+ *    UNCONDITIONALLY, with no config mode, and that asymmetry with the shell veto below is
+ *    deliberate: the shell veto's default is `warn` because its class is broad and its false-hit
+ *    rate is unmeasured, while this guard's scope was cut by measurement over 20 938 real commands
+ *    down to one refusal per ~510 commands (0,196 %) — narrow enough that a refusal is a fact about
+ *    the command's FORM, not a judgement about its intent. The verdict, the text and the limits all
+ *    come from `destructive-guard-hook.js`, the SAME module the Claude host's hook consumes, so
+ *    both runtimes refuse the same commands in the same words.
+ * 2. The shell veto policy: fail-OPEN on OUR failure, mode-driven on a POLICY hit. Exit 2 only when
+ *    the project explicitly opted in — the shipped default warns and returns 0 (AM-24 / G-J).
  *
- * Fail-OPEN on OUR failure, mode-driven on a POLICY hit. Exit 2 only when the project explicitly
- * opted in — the shipped default warns and returns 0 (AM-24 / G-J).
+ * The destructive check runs FIRST and is loaded SEPARATELY, so a project whose build lacks the
+ * shell-veto policy still gets it, and vice versa.
  */
-export function generateCodexVetoHelper(): string {
-  return `${preamble().replace('const HELPER_VERSION', "const HELPER = 'dz-codex-veto';\nconst HELPER_VERSION")}
-function main() {
+export function generateCodexVetoHelper(installedDistDir: string | null = harnessCoreDistDir()): string {
+  return `${preamble(installedDistDir).replace('const HELPER_VERSION', "const HELPER = 'dz-codex-veto';\nconst HELPER_VERSION")}
+async function main() {
   const payload = readPayload();
   if (payload === null) return 0;
 
@@ -183,7 +233,58 @@ function main() {
   const root = findProjectRoot(cwd);
   if (root === null) return 0; // inert outside an opted-in dz project: no decision, no output, no write
 
-  const policy = loadCore(root, 'shell-veto-policy.js', (m) => typeof m.vetoShellCommand === 'function');
+  // (1) The destructive-command guard. Never blocks on our own failure: an absent module, a throw,
+  // or an \`undecidable\` verdict all fall through to the shell veto below (AC-10).
+  const destructiveLoad = await loadCoreDetailed(root, 'destructive-guard-hook.js', (m) => typeof m.decideDestructiveHook === 'function');
+  if (destructiveLoad.mod === null) {
+    // NEVER silence. A guard that could not load is indistinguishable from a guard that decided
+    // "allow" unless it SAYS so, and the measurement that produced this branch is exactly that:
+    // exit 0 with an empty stderr on \`rm -rf .agentic-qe\`. The exit code stays 0 — our failure is
+    // not the user's violation — but it is announced on ONE line in BOTH places a human can read
+    // it: the transcript, and the durable notes log (codex swallows an exit-0 stderr, M9).
+    const line = 'DZ-DESTRUCTIVE-WARN: guard not loaded — ' + destructiveLoad.reason;
+    process.stderr.write(line + '\\n');
+    note('destructive-not-loaded', null, Object.assign(
+      { marker: 'DZ-DESTRUCTIVE-WARN', reason: destructiveLoad.reason },
+      commandFacts(command),
+    ));
+  } else {
+    const destructive = destructiveLoad.mod;
+    let decision = null;
+    try {
+      decision = destructive.decideDestructiveHook(payload, 'codex');
+      // CHECKED, not assumed: a decision the helper cannot read must reach the loud path with a
+      // NAME. Both \`null\` and \`{}\` are falsy at \`decision.stderr\` further down, so an unreadable
+      // shape used to make the verdict simply vanish — a second door into the same silence.
+      if (!decision || typeof decision.stderr !== 'string') {
+        throw new TypeError('решение стража нечитаемо: ' + JSON.stringify(decision));
+      }
+    } catch (err) {
+      // ONE line, always (round 9). The Claude hook already failed open LOUDLY here; this helper
+      // only wrote a note, so in the transcript a thrown decider was indistinguishable from a clean
+      // allow — the round-2 defect class (absent AND mute) reached through another door. Exit stays
+      // 0, because our failure is not the user's violation, and the record lands in BOTH places a
+      // human can read: the transcript, and the notes log (codex swallows an exit-0 stderr, M9).
+      const why = String((err && err.message) || err).replace(/\\s*\\n\\s*/g, ' ');
+      process.stderr.write('DZ-DESTRUCTIVE-WARN: classifier threw — ' + why + '\\n');
+      note('destructive-threw', err, Object.assign({ marker: 'DZ-DESTRUCTIVE-WARN' }, commandFacts(command)));
+      decision = null;
+    }
+    if (decision && decision.stderr) process.stderr.write(decision.stderr);
+    if (decision && decision.exitCode === 2) {
+      // The note carries the RULE and the command's hash, never the command line itself (R2-8).
+      note('destructive-block', null, Object.assign({ marker: 'DZ-DESTRUCTIVE', rule: decision.rule }, commandFacts(command)));
+      return 2;
+    }
+    if (decision && decision.stderr) {
+      // MEASURED (M9): codex swallows an exit-0 hook's stderr, so a non-blocking word from this
+      // guard is unobservable unless it is ALSO written where it can be read back.
+      note('destructive-' + decision.outcome, null, Object.assign({ marker: 'DZ-DESTRUCTIVE-WARN' }, commandFacts(command)));
+    }
+  }
+
+  // (2) The shell veto policy.
+  const policy = await loadCore(root, 'shell-veto-policy.js', (m) => typeof m.vetoShellCommand === 'function');
   if (policy === null) return 0; // no logic available => allow (never block on OUR failure)
 
   let hit = null;
@@ -210,14 +311,12 @@ function main() {
   return 0;
 }
 
-let code = 0;
-try {
-  code = main();
-} catch (err) {
-  note('main', err);
-  code = 0;
-}
-process.exit(code === 2 ? 2 : 0);
+// \`main\` is async because the policy loader is (\`import()\`, not \`require()\` — see loadCoreDetailed).
+// The exit code still comes from exactly one place, and a rejected promise is the same fail-open as
+// a thrown error was: note it, exit 0.
+main()
+  .catch((err) => { note('main', err); return 0; })
+  .then((code) => process.exit(code === 2 ? 2 : 0));
 `;
 }
 
@@ -228,8 +327,8 @@ process.exit(code === 2 ? 2 : 0);
  * relevant, which is exactly why the acceptance canary is a FORCED HIT plus a removed-hook twin
  * (AM-4) — a dead hook and a correctly-silent one are indistinguishable from the outside.
  */
-export function generateCodexRecallHelper(): string {
-  return `${preamble().replace('const HELPER_VERSION', "const HELPER = 'dz-codex-recall';\nconst HELPER_VERSION")}
+export function generateCodexRecallHelper(installedDistDir: string | null = harnessCoreDistDir()): string {
+  return `${preamble(installedDistDir).replace('const HELPER_VERSION', "const HELPER = 'dz-codex-recall';\nconst HELPER_VERSION")}
 const net = require('node:net');
 const DAEMON_TIMEOUT_MS = 2000;
 
@@ -275,7 +374,7 @@ async function main() {
   const root = findProjectRoot(cwd);
   if (root === null) return; // inert outside an opted-in dz project
 
-  const policy = loadCore(root, 'recall-hook-policy.js', (m) => typeof m.selectHookHits === 'function');
+  const policy = await loadCore(root, 'recall-hook-policy.js', (m) => typeof m.selectHookHits === 'function');
   if (policy === null) return;
 
   const candidates = await askDaemon(root, prompt);
@@ -301,7 +400,7 @@ async function main() {
   // The usage row carries runtime: 'codex' (ADR-003 §3) through the SHARED chained appender in
   // harness-core — ONE writer implementation, two callers (AM-6/AM-7). Written AFTER stdout so a
   // logging failure can never cost the user their injection.
-  const usage = loadCore(root, 'recall-usage.js', (m) => typeof m.appendRecallUsage === 'function');
+  const usage = await loadCore(root, 'recall-usage.js', (m) => typeof m.appendRecallUsage === 'function');
   if (usage === null) return;
   try {
     usage.appendRecallUsage({
@@ -322,7 +421,18 @@ main()
 `;
 }
 
-/** Both helper bodies, keyed by the file they are written to. */
-export function generateCodexHelpers(): Readonly<Record<'veto' | 'recall', string>> {
-  return { veto: generateCodexVetoHelper(), recall: generateCodexRecallHelper() };
+/**
+ * Both helper bodies, keyed by the file they are written to.
+ *
+ * `installedDistDir` defaults to the harness-core doing the emitting; pass `null` for a body with
+ * no absolute fallback (the pre-fix behaviour, kept so a test can prove the fallback is what makes
+ * a global install work rather than asserting it).
+ */
+export function generateCodexHelpers(
+  installedDistDir: string | null = harnessCoreDistDir(),
+): Readonly<Record<'veto' | 'recall', string>> {
+  return {
+    veto: generateCodexVetoHelper(installedDistDir),
+    recall: generateCodexRecallHelper(installedDistDir),
+  };
 }

package/src/codex-hooks.ts

@@ -36,8 +36,28 @@ import { mergeManagedHookEntries } from './managed-hooks.js';
  * 3 — fix round 2: the note's `commandSynopsis` is a binary NAME or `(redacted)` — an
  * env-assignment first token (`SECRET=xyz ssh …`) carried the credential the redaction removed
  * everywhere else (R2-8).
+ * 4 — the destructive-command guard (feature `destructive-command-guard`, ADR-001, task T8): the
+ * veto helper consults `destructive-guard-hook.js` BEFORE the shell veto and blocks
+ * unconditionally on a literal path into a protected store. A changed body changes codex's
+ * `currentHash`, so the entry must be re-trusted — re-run `dz setup --target codex`.
+ * 5 — round 2 of the cross-family review, MEASURED: the helper's module loader was `require()`, and
+ * every file in this package's `dist/` is an ES module, so on Node below 20.19 / 22.12 the load
+ * threw ERR_REQUIRE_ESM, the catch returned `null`, and the helper exited 0 with an EMPTY stderr on
+ * `rm -rf .agentic-qe` — absent AND mute on a Node the package claims to support. The loader is now
+ * `import()`, `main` is async, and a decider that still cannot load says so on one line instead of
+ * staying silent. A changed body ⇒ a changed `currentHash` ⇒ re-trust.
+ * 6 — round 3, MEASURED: the body's module candidates were both PROJECT-relative, so in the
+ * documented global install (`npm i -g @dzhechkov/harness-cli`) an ordinary target repository
+ * resolved neither — every shell call reached `guard not loaded` and was ALLOWED, while the tests
+ * hid it by symlinking the package into the temp project. The emitting installation's absolute
+ * dist path is now baked in as the LAST candidate. A changed body ⇒ re-trust.
+ * 7 — round 9, MEASURED: when the decider THREW (or returned a shape the helper could not read),
+ * the helper wrote a note and printed NOTHING — stderr came back empty, so in the transcript the
+ * run was indistinguishable from a clean allow. The Claude hook already failed open loudly here.
+ * Now it prints ONE line, `DZ-DESTRUCTIVE-WARN: classifier threw — <message>`, and still exits 0.
+ * A changed body ⇒ re-trust.
  */
-export const DZ_HOOK_HELPER_VERSION = 3;
+export const DZ_HOOK_HELPER_VERSION = 7;
 
 /** Seconds. Probe-proven (spike S2): `timeout` is honored, the unset default is 600 s. */
 export const DZ_HOOK_TIMEOUT_SECONDS = 5;

package/src/codex-invoke.ts

@@ -0,0 +1,138 @@
+/**
+ * The one supported way to invoke Codex from a Claude Code session.
+ *
+ * Three failure modes were measured on 2026-08-31, each violating knowledge we had already
+ * written down and could not enforce: the fire-and-forget wrapper returning a dispatch stub for a
+ * stage whose deliverable is its return value; a prompt passed as a shell ARGUMENT whose backticks
+ * the shell read as command substitution, leaving codex to read an empty stdin and hang for 26
+ * minutes; and an unscoped run spending its whole budget exploring the tree and returning no
+ * verdict at all.
+ *
+ * The cure is structural, not advisory: this module has no parameter that accepts a prompt STRING
+ * (so a shell can never mangle it), a timeout is always present, and the outcome set is CLOSED —
+ * either the model's text, or one of five named refusals. There is no third state, which is the
+ * property the tests pin.
+ */
+
+/** Every way this can fail, enumerated. A refusal outside this set is a bug, not a new case. */
+export type CodexRefusal =
+  | 'timeout'
+  | 'no-output'
+  | 'model-unavailable'
+  | 'tool-error'
+  | 'bad-usage';
+
+export interface CodexOk {
+  readonly ok: true;
+  readonly text: string;
+  readonly model: string;
+  readonly elapsedMs: number;
+}
+
+export interface CodexRefused {
+  readonly ok: false;
+  readonly refusal: CodexRefusal;
+  /** Human-readable, names WHAT was observed — never a guess at the cause. */
+  readonly detail: string;
+  readonly model?: string;
+  readonly elapsedMs?: number;
+}
+
+export type CodexOutcome = CodexOk | CodexRefused;
+
+export const CODEX_DEFAULT_TIMEOUT_MS = 600_000;
+export const CODEX_PROBE_TIMEOUT_MS = 90_000;
+
+/** Model ids this account has been seen to answer on. A name here is spellable, never available. */
+export const CODEX_KNOWN_MODELS = ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5'] as const;
+
+export interface CodexRunInput {
+  /** Absolute path to a file holding the prompt. There is deliberately no string variant. */
+  readonly promptFile: string;
+  readonly model: string;
+  readonly timeoutMs?: number;
+  /**
+   * Files the model may read. REQUIRED for review-shaped work: an unscoped run was measured at
+   * 280s / exit 124 / 416KB of exploration and no verdict, while the same question scoped to two
+   * named files answered in 41s. Empty means "no scope declared" and is allowed only for a
+   * self-contained question that needs no repository access.
+   */
+  readonly scope?: readonly string[];
+  readonly effort?: 'low' | 'medium' | 'high' | 'xhigh';
+}
+
+/** What a runner must provide. Kept tiny so tests can substitute it without spawning anything. */
+export interface CodexRunner {
+  (argv: readonly string[], timeoutMs: number): {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+  };
+}
+
+/** Build the argv. Exported so a test can assert the prompt never rides on the command line. */
+export function codexArgv(input: CodexRunInput): string[] {
+  const argv = ['exec', '-m', input.model, '--skip-git-repo-check'];
+  if (input.effort !== undefined) argv.push('-c', `model_reasoning_effort=${input.effort}`);
+  return argv;
+}
+
+/** Turn a raw runner result into the closed outcome set. */
+export function classifyCodexResult(
+  raw: { status: number | null; stdout: string; stderr: string; timedOut: boolean },
+  model: string,
+  elapsedMs: number,
+): CodexOutcome {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      refusal: 'timeout',
+      detail: `no answer within the deadline (${elapsedMs}ms); narrow the scope rather than raising the ceiling — an unscoped run spends the budget exploring`,
+      model,
+      elapsedMs,
+    };
+  }
+  if (raw.status !== 0) {
+    return {
+      ok: false,
+      refusal: 'tool-error',
+      detail: `codex exited ${raw.status === null ? 'by signal' : String(raw.status)}: ${raw.stderr.trim().slice(0, 300) || '(no stderr)'}`,
+      model,
+      elapsedMs,
+    };
+  }
+  const text = raw.stdout.trim();
+  if (text === '') {
+    // Silence is the failure this module exists to make impossible. A clean exit with nothing
+    // written is what a mangled prompt looks like from the outside, and it must never read as ok.
+    return {
+      ok: false,
+      refusal: 'no-output',
+      detail: 'codex exited 0 but wrote nothing — an empty answer is a refusal, never a clean result',
+      model,
+      elapsedMs,
+    };
+  }
+  return { ok: true, text, model, elapsedMs };
+}
+
+/** Compose the prompt file's content: the task, plus the scope fence when one is declared. */
+export function codexPromptBody(task: string, scope?: readonly string[]): string {
+  const trimmed = String(task ?? '').trim();
+  if (scope === undefined || scope.length === 0) return trimmed;
+  const list = scope.map((p) => `- ${p}`).join('\n');
+  return [
+    trimmed,
+    '',
+    'SCOPE — read ONLY these files and do not open others. This bound is what makes an answer',
+    'possible at all: an unscoped run was measured spending its entire budget exploring the tree',
+    'and returning no verdict.',
+    list,
+  ].join('\n');
+}
+
+/** True when the outcome may be consumed as an answer. Exists so callers cannot forget the check. */
+export function codexAnswered(outcome: CodexOutcome): outcome is CodexOk {
+  return outcome.ok === true;
+}

package/src/course-staleness.ts

@@ -0,0 +1,125 @@
+import { compareVersions } from './publish.js';
+
+export type CourseStalenessState =
+  | 'S0_SHIPPED'
+  | 'S3_TUTORIAL_STALE'
+  | 'S4_PACKAGE_BEHIND'
+  | 'E2_UNSTAMPED'
+  | 'E3_INVALID_VERSION'
+  | 'E4_PACKAGE_MISMATCH'
+  | 'E5_REGISTRY_UNKNOWN';
+
+export interface CourseStalenessInput {
+  readonly source: unknown;
+  readonly expectedPackage?: string | null;
+  readonly registryVersion?: string | null;
+}
+
+export interface CourseStalenessResult {
+  readonly state: CourseStalenessState;
+  readonly reason: string;
+  readonly courseVersion?: string;
+  readonly registryVersion?: string;
+  readonly package?: string;
+}
+
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Classify only the version evidence supplied by the caller. Obtaining a registry version is a
+ * caller responsibility; this function performs no filesystem, network, clock, or environment I/O.
+ */
+export function classifyCourseStaleness(input: CourseStalenessInput): CourseStalenessResult {
+  const candidate = isRecord(input) ? input : undefined;
+  const source = candidate?.source;
+
+  // Presence and shape come first. Unknown values must never reach an equality comparison where
+  // two absences could be mistaken for parity.
+  if (!isRecord(source)
+    || typeof source.package !== 'string'
+    || source.package.trim() === ''
+    || typeof source.version !== 'string'
+    || source.version.trim() === '') {
+    return {
+      state: 'E2_UNSTAMPED',
+      reason: 'course.source.package and course.source.version must both be non-empty strings',
+    };
+  }
+
+  const packageName = source.package.trim();
+  const courseVersion = source.version.trim();
+  if (!SEMVER.test(courseVersion)) {
+    return {
+      state: 'E3_INVALID_VERSION',
+      reason: `course.source.version is not valid semver: ${courseVersion}`,
+      courseVersion,
+      package: packageName,
+    };
+  }
+
+  const expectedPackage = typeof candidate?.expectedPackage === 'string'
+    ? candidate.expectedPackage.trim()
+    : candidate?.expectedPackage;
+  if (!PACKAGE_NAME.test(packageName)
+    || (expectedPackage !== null && expectedPackage !== undefined
+      && (!PACKAGE_NAME.test(expectedPackage) || packageName !== expectedPackage))) {
+    return {
+      state: 'E4_PACKAGE_MISMATCH',
+      reason: expectedPackage
+        ? `course.source.package ${packageName} does not match expectedPackage ${expectedPackage}`
+        : `course.source.package is not a valid npm package name: ${packageName}`,
+      courseVersion,
+      package: packageName,
+    };
+  }
+
+  const registryVersion = candidate?.registryVersion;
+  if (registryVersion === null || registryVersion === undefined) {
+    return {
+      state: 'E5_REGISTRY_UNKNOWN',
+      reason: 'registryVersion is absent, so package parity is unknown',
+      courseVersion,
+      package: packageName,
+    };
+  }
+  if (typeof registryVersion !== 'string' || !SEMVER.test(registryVersion.trim())) {
+    return {
+      state: 'E3_INVALID_VERSION',
+      reason: `registryVersion is not valid semver: ${String(registryVersion)}`,
+      courseVersion,
+      package: packageName,
+    };
+  }
+
+  const normalizedRegistryVersion = registryVersion.trim();
+  const ordering = compareVersions(courseVersion, normalizedRegistryVersion);
+  const common = {
+    courseVersion,
+    registryVersion: normalizedRegistryVersion,
+    package: packageName,
+  };
+  if (ordering === 0) {
+    return {
+      state: 'S0_SHIPPED',
+      reason: 'course.source.version equals registryVersion',
+      ...common,
+    };
+  }
+  if (ordering < 0) {
+    return {
+      state: 'S3_TUTORIAL_STALE',
+      reason: 'course.source.version is below registryVersion',
+      ...common,
+    };
+  }
+  return {
+    state: 'S4_PACKAGE_BEHIND',
+    reason: 'course.source.version is above registryVersion',
+    ...common,
+  };
+}