@polycode-projects/the-mechanical-code-talker 2.6.1 → 2.7.1

package/src/adapters/corpus/worlds-pack.mjs

@@ -0,0 +1,122 @@
+// corpus/worlds-pack.mjs — lazy, failure-tolerated loader for the shipped
+// worlds pack (corpus/worlds/): a gzipped world index consulted first, then
+// exactly one gzipped JSONL shard per world. Nothing here ever throws at a
+// caller — an absent, truncated or corrupt pack reads as null, and a null is
+// the ordinary honest decline ("no worlds pack here").
+//
+// The provider seam mirrors reference-pack.mjs's exactly:
+// registerWorldsPackProvider swaps the whole lookup behind one async
+// `{ list(), load(worldName) }` contract. It exists because a browser surface
+// cannot read this filesystem layout — a web provider can fetch worlds
+// instead, and chat code never knows which one it is talking to. No provider
+// registered = the fs loader below.
+
+import { readFileSync } from "node:fs";
+import { gunzipSync } from "node:zlib";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { isWorldsIndexEntry, isWorldRow, isWorldFactRow, isWorldRuleRow, isWorldMetaRow } from "../../domain/worlds-pack.mjs";
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+
+/** The pack directory: TMCT_WORLDS_PACK_DIR when set, else the package's own
+ *  corpus/worlds/. */
+export function worldsPackDir(env = process.env) {
+  return env?.TMCT_WORLDS_PACK_DIR || join(PKG_ROOT, "corpus", "worlds");
+}
+
+const indexCacheByDir = new Map();   // dir -> { worldName: {s} } | null
+const worldCacheByKey = new Map();   // `${dir}\0${world}` -> payload | null
+
+/** Drop every cached index/world — for tests that mutate a pack dir. */
+export function clearWorldsPackCache() {
+  indexCacheByDir.clear();
+  worldCacheByKey.clear();
+}
+
+function readGunzipped(file) {
+  try {
+    return gunzipSync(readFileSync(file));
+  } catch {
+    return null;
+  }
+}
+
+/** The pack's world index, lazily read and cached per dir; null (cached)
+ *  when the pack is absent or unreadable. Never throws. */
+export function loadWorldsIndex(dir) {
+  if (indexCacheByDir.has(dir)) return indexCacheByDir.get(dir);
+  let index = null;
+  const body = readGunzipped(join(dir, "index.json.gz"));
+  if (body) {
+    try {
+      const parsed = JSON.parse(body.toString("utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) index = parsed;
+    } catch { /* tolerated: a corrupt index is an absent pack */ }
+  }
+  indexCacheByDir.set(dir, index);
+  return index;
+}
+
+/** One world by name: index hit -> the one shard the index names (cached) ->
+ *  { facts, rules, meta }. Null on an index miss or an unreadable shard, so
+ *  an unknown world never costs a shard read. Never throws. */
+export function loadWorld(dir, worldName) {
+  const index = loadWorldsIndex(dir);
+  if (!index) return null;
+  const entry = index[String(worldName ?? "")];
+  if (!isWorldsIndexEntry(entry)) return null;
+  const key = `${dir}\0${worldName}`;
+  if (worldCacheByKey.has(key)) return worldCacheByKey.get(key);
+  let payload = null;
+  const body = readGunzipped(join(dir, "shards", `${entry.s}.jsonl.gz`));
+  if (body) {
+    const facts = [];
+    const rules = [];
+    let meta = null;
+    for (const line of body.toString("utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const row = JSON.parse(line);
+        if (!isWorldRow(row) || row.world !== worldName) continue;
+        if (isWorldFactRow(row)) facts.push(row);
+        else if (isWorldRuleRow(row)) rules.push(row);
+        else if (isWorldMetaRow(row) && !meta) meta = row;
+      } catch { /* tolerated: a bad line loses one row, not the world */ }
+    }
+    if (facts.length || rules.length || meta) payload = { name: worldName, facts, rules, meta };
+  }
+  worldCacheByKey.set(key, payload);
+  return payload;
+}
+
+const fsProviderFor = (dirOf) => ({
+  list: async () => {
+    const index = loadWorldsIndex(dirOf());
+    return index ? Object.keys(index).sort() : null;
+  },
+  load: async (worldName) => loadWorld(dirOf(), worldName),
+});
+
+const fsProvider = fsProviderFor(() => worldsPackDir());
+
+let registeredProvider = null;
+
+/** Swap the pack lookup: provider = { list: async () => string[]|null,
+ *  load: async (worldName) => payload|null }. Pass null to restore the
+ *  default fs loader. */
+export function registerWorldsPackProvider(provider) {
+  registeredProvider = provider
+    && typeof provider.load === "function" && typeof provider.list === "function"
+    ? provider : null;
+}
+
+/** The active provider — the registered one, else the lazy fs loader. An
+ *  explicit `env` bag (a chat turn's own env, which may carry
+ *  TMCT_WORLDS_PACK_DIR) makes the fs loader resolve the pack dir from that
+ *  bag instead of process.env; with no argument the behavior is unchanged. */
+export function getWorldsPackProvider(env) {
+  if (registeredProvider) return registeredProvider;
+  if (env === undefined) return fsProvider;
+  return fsProviderFor(() => worldsPackDir(env));
+}

package/src/domain/ask-vocab.mjs

@@ -466,12 +466,20 @@ export const PLACEHOLDER_NOUNS = Object.freeze([
 
 /** Boolean connectives over same-subject clauses -> a set operation on result ids.
  *  "and" = intersection, "or" = union, "but not"/"and not"/"without"/"except" =
- *  difference. Multi-word keys are matched longest-first by ask.mjs so "but not"
- *  wins over a bare "not". Left-associative in ask.mjs's fold. */
+ *  difference. The do-support negations ("but do not import Y", the expanded
+ *  form every "don't" reaches after the contraction pass) are difference too —
+ *  the auxiliary is part of the connective, never of the branch. A bare "but"
+ *  is contrastive coordination, which still intersects ("inheriting from X but
+ *  untested" = both at once). Multi-word keys are matched longest-first by
+ *  ask.mjs so "but do not" wins over "but not" wins over a bare "but".
+ *  Left-associative in ask.mjs's fold. */
 export const BOOLEAN_CONNECTIVES = Object.freeze({
+  "but do not": "difference", "but does not": "difference",
+  "and do not": "difference", "and does not": "difference",
   "but not": "difference", "and not": "difference", "except": "difference",
   "without": "difference",
   "and": "intersection", "plus": "intersection",
+  "but": "intersection",
   "or": "union",
 });
 

package/src/domain/ask.mjs

@@ -437,6 +437,12 @@ function parseNested(w, lc, nlp, depth) {
     if (!noun) continue;                            // marker not preceded by a noun
     const head = w.slice(0, r - 1);                 // outer clause words, minus the placeholder noun
     if (!head.length) continue;                     // noun is the leading subject → subject-relative, not this shape
+    // A head made ENTIRELY of qualifier adjectives ("tested modules importing
+    // X") is an adjective stack over the subject, not an outer clause —
+    // "tested" doubles as a relation verb, so parseSimpleClause would read it
+    // as reverse(tests) over the inner set and answer the test module itself.
+    // parseRelationalOrQualified owns the adjective reading.
+    if (head.every((x) => QUALIFIERS[x.toLowerCase()])) continue;
     const outer = parseSimpleClause([...head, NEST_SENTINEL].join(" "), nlp);
     if (!outer || (outer.shape !== "reverse" && outer.shape !== "forward")) continue;
     if (outer.modifier && outer.modifier !== "direct") continue; // no transitive-over-set closure primitive

package/src/domain/child-pack.mjs

@@ -0,0 +1,79 @@
+// child-pack.mjs — the pure half of the shipped CHILD triples pack
+// (corpus/child/): the shard naming contract, the index/row shape validators
+// every writer and reader share, and the provenance tag a fact learned from the
+// pack carries. The pack itself is gzipped JSONL shards plus a gzipped term
+// index; loading them is I/O and lives in src/adapters/corpus/child-pack.mjs.
+//
+// The pack is a lazy learn-on-miss reference the clean-miss cascade consults:
+// on a miss for term T the loader returns T's ConceptNet triples, and the chat
+// hook appends them to memory (see childProvenanceTag). It mirrors the reference
+// pack's on-disk shape (index -> one shard per hit) but carries TRIPLES, not
+// article prose — so its row is a list of {subject, predicate, object} facts,
+// already mapped through conceptnet-map.toml into tmct's predicate vocabulary.
+
+import { fnv1aHex, normFactTerm } from "./hash.mjs";
+
+export const CHILD_PACK_NAME = "conceptnet";
+export const CHILD_SHARD_COUNT = 32;
+
+/** The shard a term's triples row lives in: FNV-1a first byte mod 32, as the
+ *  file basename "child-00" … "child-1f". Part of the pack's on-disk contract —
+ *  the build script shards with THIS function, so the reader never scans. The
+ *  term is normFactTerm-folded first, so the key the index stores and the key a
+ *  clean-miss lookup computes are the same spelling. */
+export function shardNameFor(term) {
+  const byte = parseInt(fnv1aHex(normFactTerm(term)).slice(0, 2), 16);
+  return `child-${(byte % CHILD_SHARD_COUNT).toString(16).padStart(2, "0")}`;
+}
+
+const SHARD_NAME_RE = /^child-[0-1][0-9a-f]$/;
+
+/** An index entry {s, t, n}: the shard holding the row, the row's canonical
+ *  term key (a normFactTerm fixed point), and the fact count (a positive
+ *  integer, so a zero-fact row can never be indexed). */
+export function isChildIndexEntry(e) {
+  return !!e && typeof e === "object"
+    && typeof e.s === "string" && SHARD_NAME_RE.test(e.s)
+    && typeof e.t === "string" && e.t.length > 0
+    && Number.isInteger(e.n) && e.n > 0;
+}
+
+/** One triple in a row: {subject, predicate, object, weight?}. subject/object
+ *  are human terms ("penguin", "bird"); predicate is a tmct vocabulary URI
+ *  ("rdfs:subClassOf", "mgx:capableOf", "mgxneg:capableOf"). weight, when
+ *  present, is the ConceptNet edge weight (a positive number). */
+export function isChildFact(f) {
+  if (!f || typeof f !== "object") return false;
+  for (const field of ["subject", "predicate", "object"]) {
+    if (typeof f[field] !== "string" || !f[field]) return false;
+  }
+  if (f.weight !== undefined && !(typeof f.weight === "number" && Number.isFinite(f.weight) && f.weight > 0)) return false;
+  return true;
+}
+
+/** A shard row: {term, facts: [ChildFact, …]} — the term's edges, at least one,
+ *  every one a valid ChildFact that actually touches the term (as subject or
+ *  object, once normalised). */
+export function isChildFactsRow(row) {
+  if (!row || typeof row !== "object") return false;
+  if (typeof row.term !== "string" || !row.term) return false;
+  if (!Array.isArray(row.facts) || row.facts.length === 0) return false;
+  for (const f of row.facts) {
+    if (!isChildFact(f)) return false;
+    if (normFactTerm(f.subject) !== row.term && normFactTerm(f.object) !== row.term) return false;
+  }
+  return true;
+}
+
+/** The provenance tag a fact stored from a child-pack lookup carries. The chat
+ *  hook stamps every fact it appends from term T's row with THIS tag;
+ *  memory/trust.mjs parses it back to a corpus-tier Source ({kind:"corpus",
+ *  name:"conceptnet"}) — the child slice is curated ConceptNet, scored at the
+ *  0.7 corpus prior. The term segment records which miss pulled the fact in, so
+ *  a fact's origin shard stays auditable on its factProvenance string even
+ *  though the Source it corroborates is the shared ConceptNet corpus. */
+export function childProvenanceTag(term) {
+  return `${CHILD_PROVENANCE_PREFIX}${CHILD_PACK_NAME}:${normFactTerm(term)}`;
+}
+
+export const CHILD_PROVENANCE_PREFIX = "child:";

package/src/domain/grammar/ace.mjs

@@ -457,6 +457,83 @@ export function parseAce(sentence, lexicon = loadLexicon()) {
   return parseRelation(lexicon, toks, lower);
 }
 
+// ---- the imperative command pattern -----------------------------------------
+// A subjectless action command ("go north", "take the key", "unlock the
+// cabinet with the key"). Unlike the nine assertion/question patterns above,
+// this one produces no OWL triple — an imperative has no truth value to
+// assert, it has an ACTION NAME to resolve against the taught action
+// families — so parseImperative returns a structured command instead
+// (precedent: parseCardinality's own non-triple `n`). It is a separate
+// export, never folded into parseAce: every triple pattern requires an
+// explicit subject noun phrase, and parseAce's callers expect triples.
+//
+// The verb set is CLOSED (an unlisted verb is a hard null, never a guess),
+// and object phrases resolve through the same lexicon-noun gate as every
+// other pattern: a structural fit over an undeclared word rides out as
+// `residue` so the caller can name it; a declared word in an unusable shape
+// is a hard null.
+
+const IMPERATIVE_VERBS = new Set(["go", "take", "drop", "open", "unlock", "close", "give", "look"]);
+const IMPERATIVE_DIRECTIONS = new Set(["north", "south", "east", "west", "up", "down"]);
+
+/** Resolve one imperative object phrase to its bare lexicon term. */
+function imperativeNP(lexicon, tokens) {
+  const np = resolveNP(lexicon, tokens);
+  if (np.term == null) return { term: null, unknown: np.unknown };
+  return { term: local(lexicon, np.term), unknown: [] };
+}
+
+/**
+ * Parse one imperative command against the closed verb set. Returns
+ * `{ pattern: "imperative", verb, residue, object?, indirectObject?,
+ * instrument?, direction? }`, a residue-carrying miss for a structural fit
+ * over undeclared words (`residue` non-empty, no slots), or null when the
+ * sentence is not an imperative of this fragment at all.
+ */
+export function parseImperative(sentence, lexicon = loadLexicon()) {
+  const toks = tokenize(sentence);
+  if (!toks.length) return null;
+  const verb = toks[0].toLowerCase();
+  if (!IMPERATIVE_VERBS.has(verb)) return null;
+  const rest = toks.slice(1);
+  const lower = rest.map((t) => t.toLowerCase());
+  const command = (fields) => ({ pattern: "imperative", verb, residue: [], ...fields });
+  const miss = (unknown) => (unknown.length ? { pattern: "imperative", verb, residue: unknown } : null);
+
+  if (verb === "look") {
+    if (!rest.length || (rest.length === 1 && lower[0] === "around")) return command({});
+    return null;
+  }
+  if (verb === "go") {
+    if (rest.length === 1 && IMPERATIVE_DIRECTIONS.has(lower[0])) return command({ direction: lower[0] });
+    return null;
+  }
+  if (verb === "give") {
+    const toIdx = lower.indexOf("to");
+    if (toIdx < 1 || toIdx === rest.length - 1) return null;
+    const object = imperativeNP(lexicon, rest.slice(0, toIdx));
+    const indirect = imperativeNP(lexicon, rest.slice(toIdx + 1));
+    if (object.term == null || indirect.term == null) return miss([...object.unknown, ...indirect.unknown]);
+    return command({ object: object.term, indirectObject: indirect.term });
+  }
+  if (verb === "unlock") {
+    const withIdx = lower.indexOf("with");
+    if (withIdx !== -1) {
+      if (withIdx < 1 || withIdx === rest.length - 1) return null;
+      const object = imperativeNP(lexicon, rest.slice(0, withIdx));
+      const instrument = imperativeNP(lexicon, rest.slice(withIdx + 1));
+      if (object.term == null || instrument.term == null) return miss([...object.unknown, ...instrument.unknown]);
+      return command({ object: object.term, instrument: instrument.term });
+    }
+    // fall through to the plain-object arm: "unlock the cabinet" is a valid
+    // command whose missing instrument is the CALLER's precondition to name.
+  }
+  if (!rest.length) return null;
+  const object = imperativeNP(lexicon, rest);
+  if (object.term == null) return miss(object.unknown);
+  return command({ object: object.term });
+}
+
 /** Pattern 9 — "N can VERB" → mgx:capableOf. The modal is not a relation
  *  verb: without this, parseRelation reads "can" through lookupVerb and
  *  asserts a generic object property ("dog cans swim") that no capability

package/src/domain/grammar/lexicon-core.json

@@ -274,6 +274,9 @@
     "judge": {},
     "priest": {},
     "servant": {},
+    "butler": {},
+    "housekeeper": {},
+    "gardener": {},
     "employee": {},
     "boss": {},
     "husband": {},
@@ -328,6 +331,9 @@
     "dress": {},
     "clothing": {},
     "chair": {},
+    "desk": {},
+    "lamp": {},
+    "portrait": {},
     "bed": {},
     "door": {},
     "window": {},

package/src/domain/interpret/normalize.mjs

@@ -8,7 +8,7 @@
 import {
   CONTRACTIONS, MISSPELLINGS, WRONG_WORDS, G_DROP, FILLER_WORDS,
   NEGATION_FRAMES, COMMIT_CONTENT_FRAMES, VERB_TO_KIND, ENTITY_TO_TYPE,
-  TRAILING_SCOPE_FILLER, TRAILING_TEMPORAL_ADVERBS,
+  TRAILING_SCOPE_FILLER, TRAILING_TEMPORAL_ADVERBS, stripTrailingDiscourseTag,
 } from "../ask-vocab.mjs";
 
 export function escapeRegex(s) {
@@ -251,18 +251,29 @@ export function applyPreambleFrames(text) {
   return q;
 }
 
-/** Strippable leading framing clause: "since/although/though/while/because/
- *  whereas/given that/now that <clause>, <Q>" -> "<Q>". Comma-anchored and
- *  non-empty-remainder-required, same discipline as GREETING_PREAMBLE_RE. */
+/** Strippable leading framing clause: "since/[even] though/although/while/
+ *  because/[even] if/whereas/given that/now that <clause>, <Q>" -> "<Q>".
+ *  Comma-anchored and non-empty-remainder-required, same discipline as
+ *  GREETING_PREAMBLE_RE. */
 const SUBORDINATION_FRAMES_RE =
-  /^(?:since|although|though|while|because|whereas|given\s+that|now\s+that)\s+.+?,\s*(.+)$/i;
+  /^(?:since|although|(?:even\s+)?though|while|because|whereas|given\s+that|now\s+that)\s+.+?,\s*(.+)$/i;
+
+/** The same framing clause TRAILING the question ("<Q>, because the sprint
+ *  just kicked off") — comma-anchored on the same subordinator set, so the
+ *  clause never reads as part of the object term. A bare "while"/"since"
+ *  mid-question without the comma is untouched (those can be content). */
+const TRAILING_SUBORDINATION_RE =
+  /^(.+?),\s*(?:since|although|(?:even\s+)?though|while|because|whereas|given\s+that|now\s+that)\s+.+$/i;
 
 export function applySubordinationFrames(text) {
   let q = String(text || "");
   for (let pass = 0; pass < 3; pass++) {
-    const m = q.match(SUBORDINATION_FRAMES_RE);
-    if (!m) break;
-    q = m[1].trim();
+    const before = q;
+    let m = q.match(SUBORDINATION_FRAMES_RE);
+    if (m) q = m[1].trim();
+    m = q.match(TRAILING_SUBORDINATION_RE);
+    if (m) q = m[1].trim();
+    if (q === before) break;
   }
   return q;
 }
@@ -390,6 +401,14 @@ export function normalizeQuery(text) {
   q = applySubordinationFrames(q);
   q = applyConditionalFrames(q);
   q = stripFillerWords(q);
+  // A trailing bare discourse tag ("which modules import a.mjs THEN") is
+  // conversational glue, not part of the object term — the same curated call
+  // ask-vocab's stripTrailingDiscourseTag already makes for the meta-whatis
+  // object. Stripped here, in the shared pre-pass and AFTER the filler strip
+  // (the noise wrappers that leave the tag behind sit at the other end), so
+  // both parse strategies see one string and the residue guard never has to
+  // refuse over a word that carried no content.
+  q = stripTrailingDiscourseTag(q);
   // emphatic trailing punctuation (item 10): a run of terminal "?" collapses to
   // one — the anchored templates consume exactly one optional trailing "?", so
   // "…walk.mjs??" otherwise leaks a stray "?" into the captured object term (the
@@ -485,6 +504,11 @@ const PHRASING_FRAMES = Object.freeze([
   { re: /^what\s+does\s+(.+?)\s+changes?\s+together\s+with\??$/i, to: (m) => `what co-changes with ${m[1]}` },
   { re: /^what\s+changes?\s+together\s+with\s+(.+?)\??$/i, to: (m) => `what co-changes with ${m[1]}` },
 
+  // COMMIT-COUNT PASSIVE ("how many commits are recorded for X") → the touch
+  // phrasing the count restrictor already compiles. "recorded" is no relation
+  // verb, so the passive otherwise dies in the restrictor parse.
+  { re: /^how\s+many\s+commits\s+(?:are|were)\s+(?:recorded|logged)\s+(?:for|against)\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `how many commits touched ${m[1]}` },
+
   // AUTHORSHIP → "who touched X" (tmct's touch edge IS the authorship signal).
   // A commit sha object is excluded — that dumps the commit's touch-set, not its author.
   { re: /^who\s+(?:wrote|authored)\s+(?:the\s+)?(?!(?:commit\s+)?[0-9a-f]{7,40}\??$)(.+?)\??$/i, to: (m) => `who touched ${m[1]}` },

package/src/domain/memory/trust.mjs

@@ -30,6 +30,16 @@ function parseChatTagRest(rest) {
  * kind set (the kinds SOURCE_PRIOR scores):
  *   corpus:conceptnet /r/IsA   -> { kind:"corpus",   name:"conceptnet" }
  *   corpus-weak:conceptnet /r/RelatedTo -> { kind:"corpusWeak", name:"conceptnet" }
+ *   child:conceptnet:<term>    -> { kind:"corpus",   name:"conceptnet" }
+ *     (the lazy child triples pack is curated ConceptNet — same corpus tier,
+ *      same 0.7 prior, same shared Source as the bulk conceptnet import; the
+ *      <term> segment records which miss pulled the fact in and is not part of
+ *      the Source identity)
+ *   world:<name>[:turnN]       -> { kind:"corpus",   name:<name> }
+ *     (a loaded world's facts are first-party authored shipped content — the
+ *      same tier the hand-written tier2 corpus already scores at; the :turnN
+ *      segment a snapshot write carries records when, not who, and is not
+ *      part of the Source identity)
  *   ace:chat:<session>@<ts>    -> { kind:"operator",  createdAt:<ts>, sessionId:<session> }
  *   teach:chat:<session>@<ts>  -> { kind:"teach",     createdAt:<ts>, sessionId:<session> }
  *   web:<url> | url:<url>      -> { kind:"web",       url:<url> }
@@ -54,6 +64,13 @@ export function provenanceTagToSource(tag) {
   const head = t.split(/\s+/)[0]; // drop trailing " /r/IsA" etc.
   if (head.startsWith("corpus-weak:")) return { kind: "corpusWeak", name: head.slice("corpus-weak:".length) || "unknown" };
   if (head.startsWith("corpus:")) return { kind: "corpus", name: head.slice("corpus:".length) || "unknown" };
+  // child:<pack>:<term> — the lazy child triples pack, scored at the corpus tier
+  // under the pack's shared Source; the per-term tail is dropped from the id.
+  if (head.startsWith("child:")) return { kind: "corpus", name: head.slice("child:".length).split(":")[0] || "unknown" };
+  // world:<name>[:turnN] — a loaded world's facts and snapshots, first-party
+  // authored shipped content scored at the corpus tier; the per-turn tail is
+  // dropped from the id so every write of one world corroborates one Source.
+  if (head.startsWith("world:")) return { kind: "corpus", name: head.slice("world:".length).split(":")[0] || "unknown" };
   if (head.startsWith("ace:")) return { kind: "operator", ...parseChatTagRest(head.slice("ace:".length)) };
   if (head.startsWith("teach:")) {
     // the chat teach lane's natural frames — chat.mjs's teachProvenanceTag

package/src/domain/worlds-pack.mjs

@@ -0,0 +1,71 @@
+// worlds-pack.mjs — the pure half of the shipped worlds pack: the row-shape
+// validators every writer and reader share, the provenance tag a loaded
+// world's facts carry, and the closed rule-kind set a world may instate. The
+// pack itself is one gzipped JSONL shard per world plus a gzipped world
+// index; loading them is I/O and lives in src/adapters/corpus/worlds-pack.mjs.
+//
+// A world row is one of three kinds:
+//   fact — an ordinary graph triple the loader appends into the session's
+//          memory store (rooms, exits, placements, NPC cast);
+//   rule — a pre-built action-Rule row (the same four action kinds the live
+//          teach frames store) the loader instates via appendRule;
+//   meta — the world's one announcement row (the opening line).
+
+const WORLD_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/** The action-rule kinds a world shard may carry — the same closed set
+ *  src/adapters/memory/core.mjs stores for live-taught actions. */
+export const WORLD_RULE_KINDS = Object.freeze([
+  "action-signature", "action-precond", "action-effect", "action-constraint",
+]);
+
+const RULE_KIND_SET = new Set(WORLD_RULE_KINDS);
+
+const isNonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
+
+/** A pack world name: lowercase, hyphen-joined ("ashcombe-hall"). */
+export function isWorldName(name) {
+  return typeof name === "string" && WORLD_NAME_RE.test(name);
+}
+
+/** An index entry { s }: the shard (basename, no extension) holding the
+ *  world's rows. */
+export function isWorldsIndexEntry(e) {
+  return !!e && typeof e === "object" && isNonEmptyString(e.s);
+}
+
+/** A fact row: { world, kind:"fact", subject, predicate, object }. */
+export function isWorldFactRow(row) {
+  return !!row && typeof row === "object" && row.kind === "fact"
+    && isWorldName(row.world)
+    && isNonEmptyString(row.subject) && isNonEmptyString(row.predicate) && isNonEmptyString(row.object);
+}
+
+/** A rule row: { world, kind:"rule", name, ruleKind, slots } — ruleKind one
+ *  of WORLD_RULE_KINDS, slots a flat object of non-empty strings (the exact
+ *  per-kind slot contract is appendRule's to enforce at instate time). */
+export function isWorldRuleRow(row) {
+  if (!row || typeof row !== "object" || row.kind !== "rule") return false;
+  if (!isWorldName(row.world) || !isNonEmptyString(row.name)) return false;
+  if (!RULE_KIND_SET.has(row.ruleKind)) return false;
+  if (!row.slots || typeof row.slots !== "object" || Array.isArray(row.slots)) return false;
+  const values = Object.values(row.slots);
+  return values.length > 0 && values.every(isNonEmptyString);
+}
+
+/** A meta row: { world, kind:"meta", opening } — the world's opening line. */
+export function isWorldMetaRow(row) {
+  return !!row && typeof row === "object" && row.kind === "meta"
+    && isWorldName(row.world) && isNonEmptyString(row.opening);
+}
+
+/** Any valid world row. */
+export function isWorldRow(row) {
+  return isWorldFactRow(row) || isWorldRuleRow(row) || isWorldMetaRow(row);
+}
+
+/** The provenance tag every fact/rule loaded from a world carries —
+ *  "world:<name>", so a loaded world is auditable apart from taught facts. */
+export function worldProvenanceTag(worldName) {
+  return `world:${worldName}`;
+}