@patterkit/ops 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -80,6 +80,10 @@ interface ValidateResult {
     hygiene: HygieneIssue[];
     /** Committed `.patterc` bundles whose hash no longer matches source (spec §11). */
     staleBundles: HygieneIssue[];
+    /** Conditions provably unsatisfiable over monotonic latches (reachability.ts). WARNINGS, and
+     *  deliberately NOT part of `ok`: content is written in pieces, so a gate whose writer has not been
+     *  authored yet is the normal state mid-work and must never fail a build. */
+    reachability: ConditionIssue[];
     /** Lingering `.patterconflict` sidecars - an unresolved merge (patter-merge.md §3.6). */
     unresolvedMerges: HygieneIssue[];
     /** Patter shards on disk that the project does NOT contain - see `orphanShards`. */
@@ -89,6 +93,12 @@ interface ValidateResult {
 /** Run structural + expression + interpolation + hygiene + bundle-staleness + merge validation. */
 declare function runValidate(loaded: LoadedProject): ValidateResult;
 
+/**
+ * Conditions that can never hold, as warnings. Empty for a project with no monotonic latches, which is
+ * most of them: this only speaks when it can prove an ordering.
+ */
+declare function reachabilityIssues(loaded: LoadedProject, compiled?: Bundle): ConditionIssue[];
+
 declare function runExport(loaded: LoadedProject): Bundle;
 /** Compile WITHOUT the localisation-mode transform - the full bundle with every locale inline. Used where
  *  the host needs all strings regardless of build mode (e.g. Patterpad's Play window + Export Localisation). */
@@ -211,6 +221,19 @@ interface CoverageBeat {
     /** Set on a never-reached beat that is gated on a host-scope ref (`@world.x`) nothing writes and no
      *  driver provides, i.e. it may just need an input, not be truly dead. Lists the offending refs. */
     needsInput?: string[];
+    /** Set on a never-reached beat gated on a ref that IS written, but ONLY by content that was itself
+     *  never reached: the beat is dead at one remove, and the gate is not the real question. Names the
+     *  ref and the beats that witness its only writers, so two mysteries collapse into one. Absent
+     *  whenever the chain cannot be refuted (see `writerSites` in the analysis). */
+    blockedBy?: BlockedGate[];
+}
+/** A gate on a never-reached beat whose every writer was itself never reached. */
+interface BlockedGate {
+    /** The gating ref, at the granularity the condition reads it: `@world.alarm`, or `@world.mood:armed`
+     *  for a single flag of a flags property. */
+    ref: string;
+    /** Beat ids witnessing the writers: content that would have to play for this gate to be written. */
+    writers: string[];
 }
 /** A choice that ran DRY during the coverage run: at some point it had no takeable option and no eligible
  *  fallback, so it fell through silently and the flow carried on past it. This is easy to author by
@@ -907,4 +930,4 @@ declare function classesForChannel(classes: DocumentationClass[], channel: strin
  */
 declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
 
-export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, detectMergeType, extractLoc, findProjectFile, isUnsafeEntry, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, poToCatalog, proposeCoverageDrivers, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, xlsxToCatalog };
+export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, detectMergeType, extractLoc, findProjectFile, isUnsafeEntry, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, poToCatalog, proposeCoverageDrivers, reachabilityIssues, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, xlsxToCatalog };

package/dist/index.js

@@ -571,7 +571,205 @@ var arrEq = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
 
 // src/validate.ts
 import { validateProject, parseSource as parseSource2 } from "@patterkit/core";
-import { validateConditions, validateInterpolation, exportBundle, hostScopesToSpec } from "@patterkit/compiler";
+import { validateConditions, validateInterpolation, exportBundle as exportBundle2, hostScopesToSpec } from "@patterkit/compiler";
+
+// src/reachability.ts
+import { exportBundle } from "@patterkit/compiler";
+var normaliseRef = (ref) => ref.includes(".") ? ref : `@patter.${ref.slice(1)}`;
+var SEP = "\0";
+var keyOf = (ref, sceneId) => ref.startsWith("@scene.") ? `${sceneId}${SEP}${ref}` : ref;
+var shown = (key) => {
+  const bare = key.includes(SEP) ? key.slice(key.indexOf(SEP) + 1) : key;
+  const at = bare.indexOf(":");
+  return at < 0 ? bare : `${bare.slice(0, at)} +${bare.slice(at + 1)}`;
+};
+var svRef = (ast) => Array.isArray(ast) && ast[0] === "sv" ? `@${String(ast[1])}.${String(ast[2])}` : void 0;
+function latchOf(ast, sceneId) {
+  const direct = svRef(ast);
+  if (direct !== void 0) return keyOf(direct, sceneId);
+  if (!Array.isArray(ast)) return void 0;
+  if (ast[0] === "bin" && ast[1] === "==") {
+    const [, , l, r] = ast;
+    for (const [a, b] of [[l, r], [r, l]]) {
+      const ref = svRef(a);
+      if (ref !== void 0 && Array.isArray(b) && b[0] === "b" && b[1] === true) return keyOf(ref, sceneId);
+    }
+    return void 0;
+  }
+  if (ast[0] === "call" && ast[1] === "check_flags") {
+    const ref = svRef(ast[2]);
+    const args = ast.slice(3);
+    if (ref === void 0 || args.length !== 1) return void 0;
+    const arg = args[0];
+    if (Array.isArray(arg) && arg[0] === "fd" && arg[1] === "+") return `${keyOf(ref, sceneId)}:${String(arg[2])}`;
+  }
+  return void 0;
+}
+function disjuncts(ast) {
+  if (Array.isArray(ast) && ast[0] === "bin" && ast[1] === "or") {
+    const [, , l, r] = ast;
+    return [...disjuncts(l), ...disjuncts(r)];
+  }
+  return [ast];
+}
+function terms(ast, sceneId, negated = false, into = []) {
+  const latch = latchOf(ast, sceneId);
+  if (latch !== void 0) {
+    into.push({ key: latch, negated });
+    return into;
+  }
+  if (!Array.isArray(ast)) return into;
+  if (ast[0] === "u" && ast[1] === "not") return terms(ast[2], sceneId, !negated, into);
+  if (ast[0] === "bin" && ast[1] === "and" && !negated) {
+    terms(ast[2], sceneId, false, into);
+    terms(ast[3], sceneId, false, into);
+  }
+  return into;
+}
+var requirementsOf = (expr, sceneId) => expr === void 0 ? [] : terms(expr.ast, sceneId);
+var asFlags = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+function reachabilityIssues(loaded, compiled) {
+  const bundle = compiled ?? exportBundle({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
+  const hostTokens = new Set((loaded.project.scopeRegistry?.scopes ?? []).map((s) => s.token));
+  const preset = /* @__PURE__ */ new Set();
+  const notALatch = (decl, key) => {
+    if (decl.temporary) {
+      preset.add(key);
+      for (const v of decl.values ?? []) preset.add(`${key}:${v}`);
+      return;
+    }
+    if (decl.type === "boolean" && decl.default === true) preset.add(key);
+    if (decl.type === "flags") for (const v of asFlags(decl.default)) preset.add(`${key}:${v}`);
+  };
+  for (const decl of loaded.project.properties ?? []) notALatch(decl, `@patter.${decl.name}`);
+  for (const scene of loaded.scenes) {
+    for (const decl of scene.sceneProps ?? []) notALatch(decl, `${scene.id}${SEP}@scene.${decl.name}`);
+  }
+  const latched = /* @__PURE__ */ new Set();
+  const broken = /* @__PURE__ */ new Set();
+  const writers = /* @__PURE__ */ new Map();
+  const noteWrite = (key, requires) => {
+    latched.add(key);
+    (writers.get(key) ?? writers.set(key, []).get(key)).push({ requires });
+  };
+  const breakKey = (key) => {
+    broken.add(key);
+    for (const k of latched) if (k.startsWith(`${key}:`)) broken.add(k);
+  };
+  const scanEffects = (effects, sceneId, need) => {
+    for (const e of effects ?? []) {
+      const ref = normaliseRef(e.target);
+      const key = keyOf(ref, sceneId);
+      const ast = e.value.ast;
+      if (Array.isArray(ast) && ast[0] === "b" && ast[1] === true) {
+        noteWrite(key, need);
+        continue;
+      }
+      if (Array.isArray(ast) && ast[0] === "call" && ast[1] === "set_flags" && svRef(ast[2]) === ref) {
+        let clean = true;
+        for (const arg of ast.slice(3)) {
+          if (Array.isArray(arg) && arg[0] === "fd" && arg[1] === "+") noteWrite(`${key}:${String(arg[2])}`, need);
+          else clean = false;
+        }
+        if (clean) continue;
+      }
+      breakKey(key);
+    }
+  };
+  const walk = (nodes, sceneId, gate) => {
+    for (const node of nodes) {
+      const here = [...gate, ...requirementsOf(node.condition, sceneId)];
+      if (node.type === "group") walk(node.children, sceneId, here);
+      else {
+        scanEffects(node.onEnter, sceneId, here);
+        scanEffects(node.onExit, sceneId, here);
+      }
+    }
+  };
+  for (const scene of Object.values(bundle.scenes)) {
+    scanEffects(scene.onEntry, scene.id, []);
+    for (const block of scene.blocks) walk(block.children, scene.id, []);
+  }
+  for (const key of [...latched]) {
+    const at = key.indexOf(":");
+    if (at > 0 && broken.has(key.slice(0, at))) broken.add(key);
+  }
+  const hostDriven = (key) => hostTokens.has(key.slice(1, key.indexOf(".")));
+  const monotonic = (key) => latched.has(key) && !broken.has(key) && !preset.has(key) && !hostDriven(key);
+  const cache = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Set();
+  const mustHold = (key) => {
+    const done = cache.get(key);
+    if (done !== void 0) return { need: done, cut: false };
+    if (inFlight.has(key)) return { need: /* @__PURE__ */ new Set(), cut: true };
+    const routes = writers.get(key);
+    if (routes === void 0 || routes.length === 0) return { need: /* @__PURE__ */ new Set(), cut: false };
+    inFlight.add(key);
+    let shared;
+    let cut = false;
+    for (const route of routes) {
+      const need = /* @__PURE__ */ new Set();
+      for (const t of route.requires) {
+        if (t.negated || !monotonic(t.key)) continue;
+        need.add(t.key);
+        const deeper = mustHold(t.key);
+        cut ||= deeper.cut;
+        for (const k of deeper.need) need.add(k);
+      }
+      shared = shared === void 0 ? need : new Set([...shared].filter((k) => need.has(k)));
+    }
+    inFlight.delete(key);
+    const result = shared ?? /* @__PURE__ */ new Set();
+    if (!cut) cache.set(key, result);
+    return { need: result, cut };
+  };
+  const refute = (gate) => {
+    for (const no of gate.filter((t) => t.negated)) {
+      if (!monotonic(no.key)) continue;
+      if (gate.some((t) => !t.negated && t.key === no.key)) {
+        return `it asks for ${shown(no.key)} to be both set and not set`;
+      }
+      for (const yes of gate.filter((t) => !t.negated && t.key !== no.key)) {
+        if (!monotonic(yes.key)) continue;
+        const chain = mustHold(yes.key);
+        if (!chain.cut && chain.need.has(no.key)) {
+          return `${shown(yes.key)} can only become true after ${shown(no.key)}, which nothing sets back, so this condition can never hold`;
+        }
+      }
+    }
+    return void 0;
+  };
+  const issues = [];
+  const report = (nodes, sceneId, gate) => {
+    for (const node of nodes) {
+      const own = node.condition;
+      const branches = own ? disjuncts(own.ast) : [void 0];
+      let reason;
+      const refuted = branches.every((b) => {
+        const r = refute([...gate, ...b ? terms(b, sceneId) : []]);
+        reason ??= r;
+        return r !== void 0;
+      });
+      if (refuted && reason !== void 0 && own) {
+        issues.push({
+          nodeId: node.id,
+          field: "condition",
+          src: own.src,
+          severity: "warning",
+          message: `this can never run: ${reason}`
+        });
+        continue;
+      }
+      if (node.type === "group") report(node.children, sceneId, [...gate, ...requirementsOf(own, sceneId)]);
+    }
+  };
+  for (const scene of Object.values(bundle.scenes)) {
+    for (const block of scene.blocks) report(block.children, scene.id, []);
+  }
+  return issues;
+}
+
+// src/validate.ts
 function runValidate(loaded) {
   const { project, scenes, locales } = loaded;
   const structural = validateProject({ project, scenes, authoring: loaded.authoring });
@@ -582,10 +780,12 @@ function runValidate(loaded) {
   const staleBundles = checkBundles(loaded);
   const unresolvedMerges = sidecarIssues(walkFiles(loaded.root, CONFLICT_SIDECAR));
   const orphans = orphanShards(loaded);
+  const reachability = structural.length === 0 && conditions.length === 0 ? reachabilityIssues(loaded) : [];
   return {
     structural,
     conditions,
     interpolation,
+    reachability,
     hygiene,
     staleBundles,
     unresolvedMerges,
@@ -621,7 +821,7 @@ function checkBundles(loaded) {
   if (bundles.length === 0) return issues;
   let fresh;
   try {
-    fresh = exportBundle({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales }).content.hash;
+    fresh = exportBundle2({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales }).content.hash;
   } catch {
     return issues;
   }
@@ -675,7 +875,7 @@ function checkHygiene(files) {
 
 // src/export.ts
 import { basename as basename2, isAbsolute, join as join2 } from "path";
-import { exportBundle as exportBundle2 } from "@patterkit/compiler";
+import { exportBundle as exportBundle3 } from "@patterkit/compiler";
 import { isContentlessBeat } from "@patterkit/model";
 function compileScenes(loaded) {
   const def = loaded.project.locales.default;
@@ -707,7 +907,7 @@ function refuseUnresolvedMerge(loaded) {
 function runExport(loaded) {
   refuseUnresolvedMerge(loaded);
   const { project, locales } = loaded;
-  const full = exportBundle2({ project, scenes: compileScenes(loaded), locales });
+  const full = exportBundle3({ project, scenes: compileScenes(loaded), locales });
   const loc = project.export?.localisation;
   if (!loc || loc.mode === "embedded") return full;
   const strings = loc.sourceDebug ? { [full.locales.default]: full.strings[full.locales.default] ?? {} } : {};
@@ -716,7 +916,7 @@ function runExport(loaded) {
 function runExportFull(loaded) {
   refuseUnresolvedMerge(loaded);
   const { project, locales } = loaded;
-  return exportBundle2({ project, scenes: compileScenes(loaded), locales });
+  return exportBundle3({ project, scenes: compileScenes(loaded), locales });
 }
 function bundleOutputPath(loaded) {
   const override = loaded.project.export?.bundle;
@@ -953,7 +1153,7 @@ function scanAudioStatus(loaded) {
 }
 
 // src/play.ts
-import { exportBundle as exportBundle3 } from "@patterkit/compiler";
+import { exportBundle as exportBundle4 } from "@patterkit/compiler";
 import { Engine } from "@patterkit/runtime";
 
 // src/loaded-helpers.ts
@@ -1007,7 +1207,7 @@ function mergeAuthoring2(loaded) {
 
 // src/play.ts
 function runPlay(loaded, opts = {}) {
-  const bundle = exportBundle3({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
+  const bundle = exportBundle4({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
   const events = [];
   const engine = new Engine(bundle, { seed: opts.seed });
   const start = resolveStart(loaded, opts);
@@ -1062,7 +1262,7 @@ function renderPlay(result) {
 }
 
 // src/coverage.ts
-import { exportBundle as exportBundle4 } from "@patterkit/compiler";
+import { exportBundle as exportBundle5 } from "@patterkit/compiler";
 import { Engine as Engine2 } from "@patterkit/runtime";
 import { walkNodes } from "@patterkit/model";
 
@@ -1142,45 +1342,118 @@ function targetHostRef(target, hostTokens) {
   const m = /^@([A-Za-z_][\w]*)\.(.+)$/.exec(target);
   return m && hostTokens.has(m[1]) ? `@${m[1]}.${m[2]}` : void 0;
 }
+function flagKeys(node, hostTokens, fn) {
+  if (node.kind !== "call" || node.name !== fn) return [];
+  const subject = node.args[0];
+  if (!subject || subject.kind !== "scopedvar" || !hostTokens.has(subject.scope)) return [];
+  const ref = `@${subject.scope}.${subject.name}`;
+  return node.args.slice(1).filter((a) => a.kind === "flagdelta").map((a) => `${ref}:${a.name}`);
+}
+function fineRefsIn(node, hostTokens, out) {
+  for (const k of flagKeys(node, hostTokens, "check_flags")) out.add(k);
+  switch (node.kind) {
+    case "unary":
+      fineRefsIn(node.operand, hostTokens, out);
+      break;
+    case "binary":
+      fineRefsIn(node.left, hostTokens, out);
+      fineRefsIn(node.right, hostTokens, out);
+      break;
+    case "call":
+      for (const a of node.args) fineRefsIn(a, hostTokens, out);
+      break;
+    default:
+      break;
+  }
+}
 function analyzeHostScopes(bundle, hostTokens) {
   const written = /* @__PURE__ */ new Set();
   const gatesByBeat = /* @__PURE__ */ new Map();
+  const fineGatesByBeat = /* @__PURE__ */ new Map();
   const proposals = /* @__PURE__ */ new Map();
-  if (hostTokens.size === 0) return { written, gatesByBeat, proposals };
+  const writerSites = /* @__PURE__ */ new Map();
+  const opaqueWrites = /* @__PURE__ */ new Set();
+  const empty = { written, gatesByBeat, proposals, fineGatesByBeat, writerSites, opaqueWrites };
+  if (hostTokens.size === 0) return empty;
   const refsIn = (expr) => {
     const refs = /* @__PURE__ */ new Set();
     if (expr) scanExpr(deserialiseAst(expr.ast), hostTokens, refs, proposals);
     return refs;
   };
-  const scanEffects = (effects) => {
+  const fineIn = (expr) => {
+    const refs = /* @__PURE__ */ new Set();
+    if (expr) fineRefsIn(deserialiseAst(expr.ast), hostTokens, refs);
+    return refs;
+  };
+  const addSite = (key, witnesses) => {
+    (writerSites.get(key) ?? writerSites.set(key, []).get(key)).push(witnesses);
+  };
+  const scanEffects = (effects, witnesses) => {
     for (const e of effects ?? []) {
-      const t = targetHostRef(e.target, hostTokens);
-      if (t) written.add(t);
+      const target = targetHostRef(e.target, hostTokens);
+      if (target) {
+        written.add(target);
+        addSite(target, witnesses);
+        const flags = e.value ? flagKeys(deserialiseAst(e.value.ast), hostTokens, "set_flags") : [];
+        if (flags.length) for (const k of flags) addSite(k, witnesses);
+        else opaqueWrites.add(target);
+      }
       refsIn(e.value);
     }
   };
-  const walk = (nodes, gate) => {
+  const walk = (nodes, gate, fine) => {
     for (const node of nodes) {
       const here = /* @__PURE__ */ new Set([...gate, ...refsIn(node.condition)]);
+      const hereFine = /* @__PURE__ */ new Set([...fine, ...fineIn(node.condition)]);
       if (node.type === "group") {
-        walk(node.children, here);
+        walk(node.children, here, hereFine);
       } else {
-        scanEffects(node.onEnter);
-        scanEffects(node.onExit);
-        for (const beat of node.beats ?? []) gatesByBeat.set(beat.id, here);
+        const witnesses = (node.beats ?? []).map((b) => b.id);
+        scanEffects(node.onEnter, witnesses);
+        scanEffects(node.onExit, witnesses);
+        for (const beat of node.beats ?? []) {
+          gatesByBeat.set(beat.id, here);
+          fineGatesByBeat.set(beat.id, hereFine);
+        }
       }
     }
   };
   for (const scene of Object.values(bundle.scenes)) {
-    scanEffects(scene.onEntry);
-    for (const block of scene.blocks) walk(block.children, /* @__PURE__ */ new Set());
+    const sceneBeats = [];
+    const collect = (nodes) => {
+      for (const n of nodes) {
+        if (n.type === "group") collect(n.children);
+        else for (const b of n.beats ?? []) sceneBeats.push(b.id);
+      }
+    };
+    for (const block of scene.blocks) collect(block.children);
+    scanEffects(scene.onEntry, sceneBeats);
+    for (const block of scene.blocks) walk(block.children, /* @__PURE__ */ new Set(), /* @__PURE__ */ new Set());
   }
-  return { written, gatesByBeat, proposals };
+  return empty;
+}
+function blockedGates(beatId, analysis, drivenRefs, reachedRuns) {
+  const out = [];
+  const gates = /* @__PURE__ */ new Set([...analysis.gatesByBeat.get(beatId) ?? [], ...analysis.fineGatesByBeat.get(beatId) ?? []]);
+  for (const ref of [...gates].sort()) {
+    const coarse = ref.includes(":") ? ref.slice(0, ref.indexOf(":")) : ref;
+    if (drivenRefs.has(coarse)) continue;
+    if (!analysis.written.has(coarse)) continue;
+    if (ref !== coarse && analysis.opaqueWrites.has(coarse)) continue;
+    if (ref === coarse && [...gates].some((g) => g !== ref && g.startsWith(`${ref}:`))) continue;
+    const sites = analysis.writerSites.get(ref) ?? [];
+    if (!sites.length) continue;
+    if (sites.some((s) => !s.length || s.some((w) => !reachedRuns.has(w)))) continue;
+    if (!sites.every((s) => s.every((w) => reachedRuns.get(w) === 0))) continue;
+    const writers = [...new Set(sites.flat())].sort();
+    out.push({ ref, writers });
+  }
+  return out;
 }
 function proposeCoverageDrivers(loaded) {
   const hostTokens = new Set((loaded.project.scopeRegistry?.scopes ?? []).map((s) => s.token));
   if (hostTokens.size === 0) return [];
-  const bundle = exportBundle4({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
+  const bundle = exportBundle5({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
   const { written, proposals } = analyzeHostScopes(bundle, hostTokens);
   const declByRef = /* @__PURE__ */ new Map();
   for (const s of loaded.project.scopeRegistry?.scopes ?? []) {
@@ -1241,7 +1514,7 @@ function* sweep(loaded, options = {}, hooks = {}) {
   const reachedRuns = new Map(order.map((id) => [id, 0]));
   const dryRuns = /* @__PURE__ */ new Map();
   const termination = { ended: 0, capped: 0, stalled: 0, evalError: 0 };
-  const bundle = exportBundle4({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
+  const bundle = exportBundle5({ project: loaded.project, scenes: loaded.scenes, locales: loaded.locales });
   const rng = mulberry32(seed);
   const hostTokens = new Set((loaded.project.scopeRegistry?.scopes ?? []).map((s) => s.token));
   const analysis = analyzeHostScopes(bundle, hostTokens);
@@ -1308,12 +1581,15 @@ function* sweep(loaded, options = {}, hooks = {}) {
     const m = meta.get(id);
     const reached = reachedRuns.get(id);
     let needsInput;
+    let blockedBy;
     if (reached === 0) {
       const gates = [...analysis.gatesByBeat.get(id) ?? []].filter((r) => !analysis.written.has(r) && !drivenRefs.has(r));
       if (gates.length) {
         needsInput = gates;
         for (const g of gates) unwrittenInputs.add(g);
       }
+      const blocked = blockedGates(id, analysis, drivenRefs, reachedRuns);
+      if (blocked.length) blockedBy = blocked;
     }
     return {
       id,
@@ -1324,7 +1600,8 @@ function* sweep(loaded, options = {}, hooks = {}) {
       hits: hitCount.get(id),
       reachedRuns: reached,
       reachPct: executed ? reached / executed * 100 : 0,
-      ...needsInput ? { needsInput } : {}
+      ...needsInput ? { needsInput } : {},
+      ...blockedBy ? { blockedBy } : {}
     };
   });
   const neverHit = beats.filter((b) => b.reachedRuns === 0).length;
@@ -1387,9 +1664,16 @@ function renderCoverageText(report, sceneName = (id) => id) {
     out.push("");
     out.push(`${sceneName(scene)}${dead ? `  (${dead} never reached)` : ""}`);
     for (const b of beats) {
-      const mark = b.reachedRuns === 0 ? b.needsInput ? "? " : "\u203C " : "  ";
+      const mark = b.reachedRuns === 0 ? b.needsInput || b.blockedBy ? "? " : "\u203C " : "  ";
       const label = b.character ? `${b.character}: ${clip(b.preview)}` : clip(b.preview || `(${b.kind})`);
       out.push(`  ${mark}${b.reachPct.toFixed(0).padStart(3)}%  ${String(b.hits).padStart(6)}  ${label}`);
+      for (const bg of b.blockedBy ?? []) {
+        const names = bg.writers.map((w) => {
+          const target = report.beats.find((x) => x.id === w);
+          return target ? clip(target.preview || target.id, 28) : w;
+        });
+        out.push(`         gated on ${bg.ref}, written only by: ${names.join(", ")} (never played either)`);
+      }
     }
   }
   return out;
@@ -3469,6 +3753,7 @@ export {
   loadProjectLanding,
   poToCatalog,
   proposeCoverageDrivers,
+  reachabilityIssues,
   renderCoverageText,
   renderPlay,
   renderReportText,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/ops",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The shared operations layer: every project operation (load, validate, export, format, play, ...) as a pure function, consumed by the patter CLI and Patterpad alike.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "@patterkit/compiler": "0.2.4",
     "@patterkit/core": "0.2.1",
     "@patterkit/model": "0.4.0",
-    "@patterkit/runtime": "0.7.0",
+    "@patterkit/runtime": "0.7.1",
     "docx": "^9.7.1",
     "exceljs": "^4.4.0",
     "jszip": "^3.10.1",