@lorekit/cli 1.68.0 → 1.70.0

package/src/commands/show.mjs

@@ -14,6 +14,12 @@
 //                            split (the shorthand already carries a namespaced
 //                            key, since the split lands at the first valid-scope
 //                            prefix — see `resolveScopeArg`)
+//   show <s1::k1> <s2::k2> [...]
+//                          — multi-ref form: two or more positionals that EACH
+//                            parse as a complete `<scope>::<key>` reference (see
+//                            `isMultiRefForm` below). Batches through each
+//                            store's `readMany`, one round-trip to the remote
+//                            store rather than one request per ref.
 //
 // Uses each store's real `read({scope, key})` method (both stores expose it),
 // not a filtered `list` — a single-record lookup is what `read` is for, and it
@@ -29,9 +35,12 @@ import {
   shortDate,
   describeError,
   recordsDiverge,
+  resolveScopeArg,
   resolveScopeKeyArgs,
+  isScopeString,
   scopeIssue,
 } from '../shared/lessons-view.mjs';
+import { SCOPE_PRECEDENCE } from '../shared/scope-precedence.mjs';
 import { resolveAppBase } from '../shared/deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
 import { log, err, heading, status, c } from '../shared/util.mjs';
@@ -55,6 +64,193 @@ async function readOne(store, scope, key) {
   return { available: true, found: Boolean(record), record, error: null };
 }
 
+// Is this a multi-ref invocation? Two or more positionals, no `--scope`/`--key`
+// override (a flag is an explicit single-ref assertion — see
+// `resolveScopeKeyArgs`), and EVERY positional parses as a complete
+// `<scope>::<key>` reference via `resolveScopeArg`.
+//
+// This is what keeps the existing `show <scope> <key>` two-positional form
+// unambiguous: its first positional is a BARE scope with no `::`, so
+// `resolveScopeArg` reports it with a null key and the predicate below is
+// false — the single-ref path runs unchanged, exactly as `show <scope::key>`
+// (one positional) always has.
+function isMultiRefForm(positionals, args) {
+  if (positionals.length < 2 || args.scope || args.key) return false;
+  return positionals.every((p) => resolveScopeArg(p, isScopeString).key !== null);
+}
+
+// Batch-read `refs` ({scope,key}[]) from one store via its `readMany`, and
+// project the result back into ONE `{available, found, record, error}` slot
+// per ref, in the SAME order the refs were given — mirroring what `readOne`
+// answers for a single ref, so the per-ref renderer and `--json` builder don't
+// need to know whether they are looking at a single read or a batch one.
+//
+// A transport-level failure (throw, or `{ ok:false }`) degrades EVERY ref in
+// the batch to the same error note, exactly as a per-store outage would if
+// each ref were read one at a time — a batch call doesn't get to fail more
+// silently than the single-ref path it replaces.
+async function readManyFrom(store, refs) {
+  let res;
+  try {
+    res = await store.readMany(refs);
+  } catch (e) {
+    const msg = (e && e.message) || 'error';
+    return refs.map(() => ({ available: true, found: false, record: null, error: msg }));
+  }
+  if (!res || res.ok === false) {
+    const msg = describeError(res);
+    return refs.map(() => ({ available: true, found: false, record: null, error: msg }));
+  }
+  return projectBatchResult(refs, res);
+}
+
+/**
+ * The line printed under a ref no store returned a record for — `null` when the
+ * ref WAS found, since the caller only asks about unresolved ones. Pure and
+ * exported so the three answers below are unit-testable.
+ *
+ * Three answers, not two. A slot carrying an `error` NEVER LOOKED — either the
+ * store dropped the ref (`REF_DROPPED_ERROR`) or the read itself failed — so
+ * its silence is not a "not found", and lumping it in with a store that did
+ * look states as absent something nobody checked. The mixed case is the whole
+ * reason this is not a boolean: the local store answers every ref it is given
+ * and never truncates, so past the remote's 32-ref cap the offline store says
+ * "no" while the remote never looked, and only naming both halves is accurate.
+ */
+export function unresolvedReason(ref, slots) {
+  const readable = slots.filter((s) => s.available);
+  const dropped = readable.filter((s) => Boolean(s.error));
+  const answered = readable.length - dropped.length;
+  if (answered === 0) return `no store looked up ${ref} — it may exist`;
+  if (dropped.length > 0) {
+    return `${ref} not found in the store(s) that looked; ${dropped.length} did not look — it may exist there`;
+  }
+  return `no memory found for ${ref} in the readable store(s)`;
+}
+
+/** The message a ref the store never looked up carries. Exported for the spec. */
+export const REF_DROPPED_ERROR =
+  'not looked up — the store dropped this reference (past the 32-reference cap, or a scope it does not accept)';
+
+/**
+ * Project a `readMany` result back onto the requested refs, in request order.
+ * Pure — no store, no IO — so the three outcomes below are unit-testable
+ * without a mock REST server (see CLAUDE.md on the loopback-HTTP flakiness).
+ *
+ * A ref the store ANSWERED is in exactly one of `entries` or `missing`. One in
+ * NEITHER was never looked up: the remote store drops refs past the 32-reference
+ * cap and refs whose scope its stricter grammar rejects, and neither loss
+ * reaches `missing`, which is a not-found list by design. Reporting those as
+ * `found: false` would print "no such key in this store" for a lesson that may
+ * well be there, so they carry an explicit error instead. The local store
+ * answers every ref it is given, so that branch is unreachable for it by
+ * construction rather than by a transport check.
+ */
+export function projectBatchResult(refs, res) {
+  const byRef = new Map();
+  for (const entry of res.entries || []) {
+    const record = normalizeEntry(entry);
+    byRef.set(`${record.scope}::${record.key}`, record);
+  }
+  const answered = new Set(res.missing || []);
+  return refs.map(({ scope, key }) => {
+    const ref = `${scope}::${key}`;
+    const record = byRef.get(ref) || null;
+    if (!record && !answered.has(ref)) {
+      return { available: true, found: false, record: null, error: REF_DROPPED_ERROR };
+    }
+    return { available: true, found: Boolean(record), record, error: null };
+  });
+}
+
+// The multi-ref path: resolve every ref against both stores (one `readMany`
+// round-trip per store, not one per ref) and report each in request order.
+async function showRefs(refs, args, root, env) {
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  const offlineList = localDenied
+    ? refs.map(() => ({ available: false, reason: `disabled by deny constraint (${localDenied.source})` }))
+    : await readManyFrom(local, refs);
+
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteList = remoteDenied
+    ? refs.map(() => ({ available: false, reason: `disabled by deny constraint (${remoteDenied.source})` }))
+    : remoteAvailable
+      ? await readManyFrom(remote, refs)
+      : refs.map(() => ({ available: false, reason: remoteUnavailableReason(connection) }));
+
+  const results = refs.map(({ scope, key }, i) => {
+    const offline = offlineList[i];
+    const remote_ = remoteList[i];
+    const foundOffline = Boolean(offline.available && offline.found);
+    const foundRemote = Boolean(remote_.available && remote_.found);
+    const diverged = foundOffline && foundRemote && recordsDiverge(offline.record, remote_.record);
+    const found = foundOffline || foundRemote;
+    // Which stores actually looked decides what a "not found" may claim.
+    const unresolved = found ? null : unresolvedReason(`${scope}::${key}`, [offline, remote_]);
+    const dropped = [offline, remote_].some((s) => s.available && Boolean(s.error));
+    return { scope, key, offline, remote_, foundOffline, foundRemote, diverged, found, unresolved, dropped };
+  });
+
+  if (args.json) {
+    log(JSON.stringify({
+      results: results.map((r) => buildJson({
+        scope: r.scope, key: r.key, offline: r.offline, remote_: r.remote_, diverged: r.diverged,
+      })),
+    }, null, 2));
+  } else {
+    heading('LoreKit memory');
+    log(`  ${c.dim(`${results.length} references`)}`);
+    for (const r of results) {
+      log('');
+      log(`  ${c.cyan(`${r.scope}::${r.key}`)}`);
+      renderRecordSection('Offline', r.offline);
+      renderRecordSection('Remote', r.remote_, remoteAvailable ? connection.endpoint : undefined);
+      if (r.diverged) status('warn', 'divergence', 'the offline and remote values differ');
+      // "not found" and "nobody looked" are different answers: say which.
+      if (r.unresolved) log(`    ${c.dim(r.unresolved)}`);
+    }
+    log('');
+  }
+
+  const foundCount = results.filter((r) => r.found).length;
+  // Bounded, non-PII telemetry — counts only, never a scope or key string.
+  return {
+    exitCode: foundCount === results.length ? 0 : 1,
+    'lorekit.cli.show.ref_count': results.length,
+    'lorekit.cli.show.found_count': foundCount,
+    'lorekit.cli.show.diverged_count': results.filter((r) => r.diverged).length,
+    // Refs at least one readable store never looked up — the batch hit the
+    // 32-ref cap, met a scope that store's grammar rejects, or the store
+    // errored. Without it a truncated batch is indistinguishable from a
+    // genuinely empty one: both report `found_count` below `ref_count`.
+    'lorekit.cli.show.dropped_count': results.filter((r) => r.dropped).length,
+  };
+}
+
+/**
+ * Was this argument MEANT as a scope, even though it is not a valid one?
+ *
+ * The discriminator is the segment before the first `:` — if it is one of the
+ * four scope types, the caller was reaching for scope syntax and got it wrong
+ * (`global::`, `repo:noslash`, `branch::o/r`), and naming the scope is more
+ * useful than silently looking up a lesson keyed on that exact string.
+ *
+ * The case this must NOT catch is the reason the unscoped read exists:
+ * `pre-exec-lessons::automation-network-no-cli-blocks-everything` is a KEY that
+ * happens to contain `::`. Its first segment is not a scope type, so it reads
+ * as the key it is. A test for "does it contain `::`" would get that backwards.
+ */
+function looksLikeScopeAttempt(token) {
+  const head = String(token).split(':')[0].toLowerCase();
+  return SCOPE_PRECEDENCE.includes(head);
+}
+
 export async function show(args) {
   const root = resolveProjectRoot(args.dir);
   const env = { ...process.env };
@@ -67,10 +263,42 @@ export async function show(args) {
   //                                  the `::` split (the shorthand handles a
   //                                  namespaced key on its own now)
   const positionals = args._.slice(1);
-  const { scope, key, consumed } = resolveScopeKeyArgs(positionals, {
+
+  if (isMultiRefForm(positionals, args)) {
+    const refs = positionals.map((p) => resolveScopeArg(p, isScopeString));
+    return showRefs(refs, args, root, env);
+  }
+
+  let { scope, key, consumed } = resolveScopeKeyArgs(positionals, {
     scope: args.scope,
     key: args.key,
   });
+  // A LONE positional that is neither a valid scope nor an ATTEMPT at one is a
+  // KEY, not a malformed scope.
+  //
+  // `resolveScopeKeyArgs` reports an unparseable first positional as the scope
+  // (with a null key) so its callers can name it as the malformed scope it is —
+  // right for `write`, which cannot proceed without knowing where to put the
+  // lesson. `show` can: a key alone resolves across every scope. So
+  // `lorekit show my-key` is a key-only lookup rather than "invalid scope
+  // my-key", which is what it used to say.
+  //
+  // Reinterpreted HERE rather than inside the shared parser: `write` and `link`
+  // must keep the strict reading, and the difference is about what each command
+  // can DO without a scope, not about how the arguments are spelled.
+  //
+  // Three things switch it off, each because the argument was plainly meant as
+  // a scope and a silent re-read would bury the user's actual mistake:
+  //   - an explicit `--scope` (a flag is an assertion, so a bad one is an error)
+  //   - MORE THAN ONE positional (`show foo bar` is the `<scope> <key>` form —
+  //     `foo` is a scope that failed to parse, not a key with a stray argument)
+  //   - a token that LOOKS like a scope attempt (`global::`, `repo:noslash`) —
+  //     see `looksLikeScopeAttempt`.
+  if (!key && scope && !args.scope && positionals.length === 1
+      && !isScopeString(scope) && !looksLikeScopeAttempt(scope)) {
+    key = scope;
+    scope = '';
+  }
   // Scope validity is checked FIRST, for the same reason as in `write`: a bad
   // scope is the root cause, and "a key is required" is downstream noise.
   const badScope = scope ? scopeIssue(scope) : null;
@@ -80,10 +308,11 @@ export async function show(args) {
     err(`Run ${c.cyan('lorekit show --help')} for options.`);
     return 1;
   }
-  if (!scope || !key) {
+  if (!key) {
     err(`${c.red('Usage:')} lorekit show <scope::key> [--json]`);
     err(`       lorekit show <scope> <key> [--json]`);
-    err(`Both a scope and a key are required. Run ${c.cyan('lorekit show --help')} for options.`);
+    err(`       lorekit show <key> [--json]        (searches every scope)`);
+    err(`A key is required. Run ${c.cyan('lorekit show --help')} for options.`);
     return 1;
   }
   // `show` consumes every positional it is given — unlike `write`, it has no
@@ -96,6 +325,18 @@ export async function show(args) {
     return 1;
   }
 
+  // `--link` is the one form that still needs a scope up front. It deliberately
+  // touches no store, and the deep link it prints is `?scope=…&lesson=…` — so
+  // without a scope there is nothing to resolve the key against and the URL
+  // would open the dashboard on an empty scope. Say so rather than emitting a
+  // link that goes nowhere.
+  if (args.link && !scope) {
+    err(`${c.red('Error:')} --link needs a scope — it builds a URL without reading any store.`);
+    err(`Pass ${c.cyan('lorekit show <scope>::' + key + ' --link')} or add ${c.cyan('--scope <s>')}.`);
+    err(`Run ${c.cyan('lorekit show ' + key)} to find which scope holds it.`);
+    return 1;
+  }
+
   // `--link` short-circuits: print the deep link that opens THIS lesson's detail
   // sheet (`?scope=…&lesson=…`) for the current args, without touching a store.
   if (args.link) {

package/src/shared/candidates-pure.mjs

@@ -44,6 +44,89 @@ export function parseMetaComment(value) {
   return out;
 }
 
+const STATUS_TAG_PREFIX = 'status::';
+
+/**
+ * A member's declared status. The canonical home is a `status::<value>` tag —
+ * first-class, filterable, and visible to a human reading the lesson — which is
+ * what the lorekit-setup skill now prescribes. A legacy `<!-- meta: status=… -->`
+ * comment in the body is still honoured so lessons written under the older
+ * convention keep their signal; the tag wins when both are present. Returns `''`
+ * when neither declares one.
+ */
+export function statusOf(member) {
+  const tags = Array.isArray(member?.tags) ? member.tags : [];
+  for (const t of tags) {
+    if (typeof t === 'string' && t.startsWith(STATUS_TAG_PREFIX)) {
+      const v = t.slice(STATUS_TAG_PREFIX.length).trim();
+      if (v) return v;
+    }
+  }
+  const fromMeta = parseMetaComment(member?.value).status;
+  return typeof fromMeta === 'string' ? fromMeta.trim() : '';
+}
+
+// Is this line a bold LABEL, and which one? Returns `{ name, rest }` or null.
+//
+// Deliberately a line test rather than another alternative in a lookahead. Four
+// separate defects in this function were one paragraph-terminating lookahead
+// failing a different way each time — truncating at the first newline, then at
+// any bold token, then failing to stop at a label whose colon sits OUTSIDE the
+// bold (`**Why**:` rather than `**Why:**`). Each fix narrowed the failure
+// without ending the class, because "where does this paragraph stop" is a
+// line-level question and a single pattern answering it has to encode every
+// spelling at once. Asked per line it is four lines of obvious code, and a new
+// spelling is a new case here rather than a new branch inside a lookahead.
+//
+// A label carries a colon; bold alone does not. `**foo()** in the parser.` is
+// prose continuing the paragraph, `**Why:**` and `**Why**:` both end it.
+const BOLD_LEAD_RE = /^[ \t]*\*\*([^\n*]+?)\*\*[ \t]*(:?)[ \t]*/;
+
+function boldLabel(line) {
+  const m = BOLD_LEAD_RE.exec(line);
+  if (!m) return null;
+  const [matched, inner, trailingColon] = m;
+  const innerColon = inner.endsWith(':');
+  if (trailingColon !== ':' && !innerColon) return null;
+  return {
+    name: (innerColon ? inner.slice(0, -1) : inner).trim().toLowerCase(),
+    rest: line.slice(matched.length),
+  };
+}
+
+/**
+ * A member's applicability signal, printed verbatim and never interpreted. The
+ * canonical home is the visible `**Applies when:**` paragraph the lorekit-setup
+ * skill prescribes; a legacy `trigger-context` meta field is the fallback.
+ * Returns `''` when the lesson declares neither.
+ *
+ * Internal newlines are collapsed to single spaces — the only transformation,
+ * and a presentational one: the caller prints this as one field on one line, so
+ * a wrapped source paragraph must re-flow rather than break the record. No word
+ * is added, removed, or reordered, which is the sense in which it stays verbatim.
+ */
+export function appliesWhenOf(member) {
+  const value = member?.value;
+  if (typeof value === 'string') {
+    const lines = value.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const label = boldLabel(lines[i]);
+      if (!label || label.name !== 'applies when') continue;
+      // The paragraph runs until a blank line, the next label, or the end.
+      const paragraph = [label.rest];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === '' || boldLabel(lines[j])) break;
+        paragraph.push(lines[j]);
+      }
+      const text = paragraph.join(' ').replace(/\s+/g, ' ').trim();
+      if (text) return text;
+      break; // declared but empty — fall through to the legacy field
+    }
+  }
+  const fromMeta = parseMetaComment(value)['trigger-context'];
+  return typeof fromMeta === 'string' ? fromMeta.trim() : '';
+}
+
 function totalSeen(members) {
   return (members || []).reduce((n, m) => n + (Number.isFinite(m.seenCount) ? m.seenCount : 0), 0);
 }
@@ -57,14 +140,15 @@ function distinctScopeCount(members) {
  * summed `seenCount` across members crosses `minSeenCount` (default 3 — the
  * kickoff's "seen_count >= 3" criterion, applied to the SUM across the
  * cluster's members rather than any single one, since the whole pitch of a
- * candidate is "these N sightings are really one entry"), or a member's own
- * meta comment already declares a non-"active" status.
+ * candidate is "these N sightings are really one entry"), or a member already
+ * declares a non-"active" status (a `status::<value>` tag, or a legacy meta
+ * comment — see `statusOf`).
  */
 export function isCandidate(members, { minSeenCount = 3 } = {}) {
   if (totalSeen(members) >= minSeenCount) return true;
   return (members || []).some((m) => {
-    const status = parseMetaComment(m.value).status;
-    return typeof status === 'string' && status.length > 0 && status !== 'active';
+    const status = statusOf(m);
+    return status.length > 0 && status !== 'active';
   });
 }
 
@@ -90,7 +174,12 @@ export function rankCandidates(clusters, { minSeenCount = 3, resolveClass } = {}
   return (clusters || [])
     .filter((cl) => isCandidate(cl.members, { minSeenCount }))
     .map((cl) => {
-      const members = (cl.members || []).map((m) => ({ ...m, meta: parseMetaComment(m.value) }));
+      const members = (cl.members || []).map((m) => ({
+        ...m,
+        meta: parseMetaComment(m.value),
+        status: statusOf(m),
+        appliesWhen: appliesWhenOf(m),
+      }));
       return {
         members,
         size: cl.size ?? members.length,

package/src/shared/lessons-view.mjs

@@ -253,6 +253,36 @@ export function diffGroups(offline = {}, remote = {}) {
 // too terse to carry a durable observation (e.g. "yes", "fixed", "todo").
 export const MIN_VALUE_LEN = 12;
 
+// Blank the INTERIOR of fenced code blocks (``` or ~~~ fences) so example content
+// — a lesson documenting an `<!-- MARKER -->` or pasting a ```yaml front-matter
+// sample — is never mistaken for hidden metadata. Such content renders as VISIBLE
+// fenced text, the opposite of the digest-hidden block `hidden-metadata` targets,
+// and `lint` is a CI gate, so a false positive there fails a legitimate lesson.
+// Line positions are preserved (interiors and fence lines become empty) so the
+// heading-anchored checks still see the real document structure. A closing fence
+// is ≥3 of the SAME character as the opener with no trailing info string
+// (CommonMark); an opener may carry an info string (```yaml). Pure.
+function stripFencedCode(value) {
+  let fence = null; // the active fence character (` or ~), or null when outside a block
+  return String(value)
+    .split('\n')
+    .map((line) => {
+      const m = line.match(/^\s*(`{3,}|~{3,})/);
+      if (fence === null) {
+        if (m) {
+          fence = m[1][0];
+          return '';
+        }
+        return line;
+      }
+      if (m && m[1][0] === fence && line.trim().replace(/[`~\s]/g, '') === '') {
+        fence = null;
+      }
+      return '';
+    })
+    .join('\n');
+}
+
 // The lint rule set: each a pure predicate over a normalized entry returning a
 // short reason string when it FIRES, or null when the entry is clean. Kept as
 // discrete named functions so each rule is independently unit-testable and the
@@ -335,6 +365,47 @@ export const LINT_RULES = {
     if (parsed === null || typeof parsed !== 'object') return null; // a bare scalar — short-value's to catch when short, otherwise unjudged.
     return 'value is a JSON object/array with no kind set — it renders as a raw JSON blob in every SessionStart digest; set --kind bus or --kind signal';
   },
+  // A lesson body is markdown for humans — no HTML comment, no front-matter, no
+  // `key=value` header. The `<!-- meta: seen_count=… status=… trigger-context=… -->`
+  // block is a REPUDIATED legacy convention this repo's lorekit-setup skill once
+  // prescribed (still parsed as a read-fallback in `candidates-pure.mjs` /
+  // `commands/invariants.mjs`, and skipped by the digest preview in `core/lessons.mjs`).
+  // It is wrong on the merits: an HTML comment renders to nothing, so a human sees a
+  // lesson starting mid-sentence, while a baked-in `seen_count`/`status`/`trigger`
+  // silently disagrees with the store's own column/tag/field. Conservative like the
+  // other rules — three concrete shapes only, never a fuzzy "looks like metadata":
+  //   1. any HTML comment (`<!--`), the strongest and most common offender;
+  //   2. a body that OPENS with a YAML front-matter block (`---` as the first line);
+  //   3. a machine-metadata header (`meta:`, `seen_count`, `status=`, `expires`,
+  //      `ttl(_days)`, `trigger-context`) appearing BEFORE the first `#` title, so a
+  //      legitimate prose line mid-body never trips it.
+  // All three run against a fence-stripped copy (`stripFencedCode`) so a lesson that
+  // DOCUMENTS one of these shapes inside a code block is never flagged.
+  'hidden-metadata': (e) => {
+    const raw = String(e.value ?? '');
+    if (!raw.trim()) return null; // an empty value is `empty-value`'s to report.
+    const v = stripFencedCode(raw);
+    if (!v.trim()) return null; // nothing outside code fences — no prose metadata to flag.
+    if (v.includes('<!--')) {
+      return "value contains an HTML comment — lesson bodies are pure markdown; move seen_count → the column, status → a status:: tag, trigger → the trigger field";
+    }
+    const lines = v.split('\n');
+    const firstNonEmpty = lines.find((l) => l.trim() !== '');
+    if (firstNonEmpty !== undefined && firstNonEmpty.trim() === '---') {
+      return 'value opens with a front-matter block — lesson bodies carry no front-matter; every stored fact belongs in its own write field';
+    }
+    const headingIdx = lines.findIndex((l) => /^\s*#/.test(l));
+    if (headingIdx > 0) {
+      const metaHeader = lines
+        .slice(0, headingIdx)
+        .filter((l) => l.trim() !== '')
+        .find((l) => /^\s*(meta\b|seen_count\b|status\s*=|expires\b|ttl(?:_days)?\b|trigger[-_]context\b)/i.test(l));
+      if (metaHeader) {
+        return `value has a machine-metadata header before the title ('${metaHeader.trim().slice(0, 40)}') — move it to the store's own fields`;
+      }
+    }
+    return null;
+  },
 };
 
 // Run every lint rule against one normalized entry, returning the findings it

package/src/shared/mirror-pairs.mjs

@@ -75,6 +75,11 @@ export const mirrorPairs = [
   { core: 'packages/mcp-core/src/limits/expiring-window.ts', edge: 'supabase/functions/_shared/limits/expiring-window.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/rest/cors-origins.ts', edge: 'supabase/functions/_shared/api/cors-origins.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/scope/scope-type-attribute.ts', edge: 'supabase/functions/_shared/scope/scope-type-attribute.ts', driftChecked: true },
+  // Which row an UNSCOPED read resolves to. Import-free on both sides (it only
+  // parses the scope prefix and compares strings), so the byte comparison
+  // applies — which is the point: a precedence that drifted between MCP and
+  // REST would hand the same key-only read two different lessons.
+  { core: 'packages/mcp-core/src/scope/scope-precedence.ts', edge: 'supabase/functions/_shared/scope/scope-precedence.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/auth/account-wide-tools.ts', edge: 'supabase/functions/_shared/auth/account-wide-tools.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/telemetry/io-ledger.ts', edge: 'supabase/functions/_shared/telemetry/io-ledger.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/telemetry/db-query-metrics.ts', edge: 'supabase/functions/_shared/telemetry/db-query-metrics.ts', driftChecked: true },
@@ -91,6 +96,10 @@ export const mirrorPairs = [
   // `lessons-view.mjs` clustering, which is what `lorekit dedupe` runs — guarded
   // behaviourally by `duplicate-clusters-parity.spec.ts` instead.
   { core: 'packages/mcp-core/src/clusters/duplicate-clusters.ts', edge: 'supabase/functions/_shared/clusters/duplicate-clusters.ts', driftChecked: true },
+  // Batch `memory.read` (`refs`) core — grouping-by-scope, the key charset
+  // guard, and the found/missing set difference shared by MCP's `toolRead`
+  // and REST's `handleRead`. Import-free, so the byte comparison applies.
+  { core: 'packages/mcp-core/src/memory/read-refs.ts', edge: 'supabase/functions/_shared/memory/read-refs.ts', driftChecked: true },
   // Excluded from the byte-comparison drift check: the edge copy types the
   // client as `ReturnType<typeof createClient>` off an `npm:` specifier where
   // mcp-core imports a typed `SupabaseClient`, and additionally carries

package/src/shared/scope-precedence.mjs

@@ -0,0 +1,82 @@
+// Which entry wins when a read named NO scope — the CLI's twin of
+// `packages/mcp-core/src/scope/scope-precedence.ts` (and its edge mirror,
+// `supabase/functions/_shared/scope/scope-precedence.ts`).
+//
+// Kept as a separate zero-dep module rather than imported: this package has no
+// dependency on `@lorekit/core`, and the pair is a CROSS-LANGUAGE one (this
+// `.mjs` vs that `.ts`), so it is guarded for BEHAVIOURAL parity by
+// `scope-precedence-parity.spec.ts` rather than the byte comparison
+// `mirror-pairs.mjs` runs over the two TypeScript copies — the same
+// arrangement `session-kind-parity.spec.ts` uses.
+//
+// Distinct from `resolvePrecedence` in `lessons-pure.mjs`, which resolves a
+// key across the CALLER'S OWN scope list (`deriveScope().readOrder`,
+// narrow-to-broad). That one answers "the agent is standing in this repo, on
+// this branch — whose lesson wins?". This one answers the question that only
+// arises once NO scope was named at all, where the caller's own scopes are not
+// the candidate set: every scope the account can see is. The server has no
+// working directory to derive `readOrder` from, so this is the only definition
+// MCP, REST and the CLI can all compute — which is why `show <key>` uses it
+// too, instead of quietly resolving differently from the hosted surfaces.
+
+/**
+ * Scope types in resolution order, most-specific first. The SAME order as
+ * `readOrder` — see the TS twin for why it is a list rather than a segment
+ * count.
+ */
+export const SCOPE_PRECEDENCE = ['project', 'branch', 'repo', 'global'];
+
+/**
+ * Rank a scope by type: 0 for the most specific, higher for broader. An
+ * unrecognised scope ranks LAST rather than throwing.
+ */
+export function scopePrecedenceRank(scope) {
+  const raw = typeof scope === 'string' ? scope.trim().toLowerCase() : '';
+  const sep = raw.indexOf('::');
+  const prefix = sep === -1 ? raw : raw.slice(0, sep);
+  const at = SCOPE_PRECEDENCE.indexOf(prefix);
+  return at === -1 ? SCOPE_PRECEDENCE.length : at;
+}
+
+/**
+ * Order two candidates: precedence band, then most-recently-updated, then
+ * scope ascending. Total and deterministic — see the TS twin for why the last
+ * two tie-breaks are load-bearing rather than decoration.
+ */
+export function compareScopePrecedence(a, b) {
+  const byRank = scopePrecedenceRank(a?.scope) - scopePrecedenceRank(b?.scope);
+  if (byRank !== 0) return byRank;
+  const at = typeof a?.updated_at === 'string' ? a.updated_at : '';
+  const bt = typeof b?.updated_at === 'string' ? b.updated_at : '';
+  if (at !== bt) return at < bt ? 1 : -1;
+  const as = typeof a?.scope === 'string' ? a.scope : '';
+  const bs = typeof b?.scope === 'string' ? b.scope : '';
+  return as < bs ? -1 : as > bs ? 1 : 0;
+}
+
+/** The entry an unscoped read resolves to, or `null` when there were none. */
+export function pickScopeWinner(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  let winner = rows[0];
+  for (let i = 1; i < rows.length; i += 1) {
+    if (compareScopePrecedence(rows[i], winner) < 0) winner = rows[i];
+  }
+  return winner;
+}
+
+/**
+ * Every scope the candidates cover EXCEPT the winner's, in precedence order,
+ * de-duplicated — what an unscoped read reports so the caller can see its key
+ * was ambiguous and pass an explicit scope next time.
+ */
+export function shadowedScopes(rows, winner) {
+  if (!Array.isArray(rows) || !winner) return [];
+  const seen = new Set([winner.scope]);
+  const out = [];
+  for (const row of [...rows].sort(compareScopePrecedence)) {
+    if (seen.has(row.scope)) continue;
+    seen.add(row.scope);
+    out.push(row.scope);
+  }
+  return out;
+}