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

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/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/memory/trust.mjs

@@ -30,6 +30,11 @@ 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)
  *   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 +59,9 @@ 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" };
   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}`;
+}