@polycode-projects/the-mechanical-code-talker 4.1.1 → 4.1.3

package/src/domain/hanoi-board.mjs

@@ -0,0 +1,232 @@
+// hanoi-board.mjs — the one pure walk from a solved towers-of-hanoi plan to
+// board-shaped fact rows, and from those rows to the `{individuals,
+// objectProperties}` payload parseEntities consumes. The plan page's
+// counterpart to sprite-facts.mjs, and to ask.mjs's own
+// worldRelationGraphPayload.
+//
+// The plan lane already hands the page everything a board question needs:
+// `plan.states[step]` is the position after `step` moves, one `mgx:rest-on`
+// row per disk; `plan.actions` is the move list; `plan.domain` carries the
+// taught taxonomy (`classMembers`), the taught size order (`ordering`) and
+// the taught render hints. None of that is a graph, so `tmct.ask` over a plan
+// session had nothing to traverse. These two functions close that.
+//
+// A row set is taken AT A STEP, because that is the question a visitor asks
+// on that page: the transport bar scrubs the board, and "where are the disks"
+// means where they are on the board in front of them.
+//
+// What travels, and why each row earns its place:
+//   - `<piece> rdf:type <class>`     — the taught board taxonomy (disk, peg),
+//     so ask()'s dynamic class lane answers "how many disks are there" and
+//     "list the pegs" straight off `individual.class`, with no vocabulary
+//     table to edit.
+//   - `<disk> mgx:rest-on <support>` — the position itself, copied from the
+//     state's own rows. The support is a disk or a peg.
+//   - `<disk> mgx:currently-in <peg>`— the same position chased down the
+//     support chain to the peg the disk is standing on. This is
+//     ask-vocab.mjs's WORLD_RELATIONS.placement predicate, so "where are the
+//     disks" and "list the locations of disks" answer over the live board the
+//     way spider-fly's own board answers them.
+//   - `<peg> mgx:top-disk <disk>`    — the topmost disk on a peg, the only one
+//     a legal move can lift. Derived, not restated: a peg holding nothing
+//     emits no row.
+//   - `<disk> mgx:smaller-than <disk>` — the taught size order, straight from
+//     `plan.domain.ordering`.
+//   - `move-N rdf:type move`, `move-N mgx:moves-disk <disk>`,
+//     `move-N mgx:moves-onto <target>` — the solution's own move list, so
+//     "how many moves are there" and "list the moves" answer about the
+//     puzzle the page is showing.
+//
+// The move rows cover the WHOLE solution rather than only the moves played so
+// far, because that is what the movelist beside the board shows and what "how
+// many moves does this take" means. The step is what the position rows read;
+// the move list is the plan, and the plan does not change as you scrub it.
+//
+// Which classes count as board furniture follows computeBlocksLayout's own
+// rule, for the same reason: `plan.domain.classMembers` is the whole memory's
+// taxonomy, not just this puzzle's, so a session that has been taught a
+// vocabulary carries hundreds of individuals with nothing to do with the game.
+// A class DECLARED in the render hints contributes every member, empty or not
+// (an unused peg is still a peg); an undeclared class contributes only the
+// members the plan itself names.
+
+/** The board relations a projected hanoi graph carries. `placement` is
+ *  ask-vocab.mjs's own WORLD_RELATIONS.placement predicate, restated here
+ *  rather than imported so this module stays a leaf with no imports — the
+ *  spelling is checked against that table by test. */
+export const HANOI_BOARD_RELATIONS = Object.freeze({
+  placement: Object.freeze({
+    predicate: "mgx:currently-in",
+    comment: "disk -> peg: the peg this disk is standing on, chased down its own support chain.",
+  }),
+  support: Object.freeze({
+    predicate: "mgx:rest-on",
+    comment: "disk -> disk or peg: what this disk is resting directly on.",
+  }),
+  topDisk: Object.freeze({
+    predicate: "mgx:top-disk",
+    comment: "peg -> disk: the topmost disk on that peg, the only one a legal move can lift.",
+  }),
+  size: Object.freeze({
+    predicate: "mgx:smaller-than",
+    comment: "disk -> disk: the taught size order between two disks.",
+  }),
+  movesDisk: Object.freeze({
+    predicate: "mgx:moves-disk",
+    comment: "move -> disk: the disk that move lifts.",
+  }),
+  movesOnto: Object.freeze({
+    predicate: "mgx:moves-onto",
+    comment: "move -> disk or peg: what that move sets the disk down on.",
+  }),
+});
+
+/** The class every solution move is filed under, so a count/list question
+ *  reaches the move list by the word a visitor would use. */
+export const HANOI_MOVE_CLASS = "move";
+
+/** `move-1` … `move-N`, numbered the way the movelist beside the board
+ *  numbers them. */
+export const hanoiMoveId = (index) => `move-${index + 1}`;
+
+const isThanPredicate = (predicate) => /-than$/.test(String(predicate || ""));
+
+/** Every label the plan itself names, across its states and its actions —
+ *  the same set computeBlocksLayout draws its undeclared anchors from. */
+function namesInPlan(plan) {
+  const named = new Set();
+  for (const rows of plan?.states || []) {
+    for (const r of rows || []) {
+      if (r?.subject != null) named.add(r.subject);
+      if (r?.object != null) named.add(r.object);
+    }
+  }
+  for (const a of plan?.actions || []) {
+    if (a?.subject != null) named.add(a.subject);
+    if (a?.target != null) named.add(a.target);
+  }
+  return named;
+}
+
+/** class -> the members of it this board carries, applying the declared/
+ *  undeclared rule from this module's header. */
+function boardMembersByClass(plan) {
+  const classMembers = plan?.domain?.classMembers || {};
+  const renderHints = plan?.domain?.renderHints || {};
+  const named = namesInPlan(plan);
+  const out = new Map();
+  for (const cls of Object.keys(classMembers).sort()) {
+    const declared = Object.prototype.hasOwnProperty.call(renderHints, cls);
+    const members = [...(classMembers[cls] || [])]
+      .filter((m) => declared || named.has(m))
+      .sort();
+    if (members.length) out.set(cls, members);
+  }
+  return out;
+}
+
+/** Follow `rest-on` from a piece down to whatever it finally stands on. Returns
+ *  null when the piece rests on nothing, and when the chain loops back on
+ *  itself — a cycle is a position no board can be in, and inventing a peg for
+ *  it would be a guess. */
+function groundUnder(piece, supportOf) {
+  let here = piece;
+  const seen = new Set([piece]);
+  while (supportOf.has(here)) {
+    const next = supportOf.get(here);
+    if (seen.has(next)) return null;
+    seen.add(next);
+    here = next;
+  }
+  return here === piece ? null : here;
+}
+
+/**
+ * The board rows for one position of a solved plan, as plain
+ * `{ subject, predicate, object }` triples — deterministic for identical
+ * inputs, deduplicated, and drawn only from the plan handed in. Pure.
+ *
+ * `step` is the number of moves played, so `0` is the starting position and
+ * `plan.actions.length` is the solved one. Out-of-range steps clamp.
+ */
+export function hanoiBoardRows({ plan, step = 0 } = {}) {
+  const states = plan?.states || [];
+  const actions = plan?.actions || [];
+  const rows = [];
+  const seen = new Set();
+  const add = (subject, predicate, object) => {
+    if (subject == null || object == null || !predicate) return;
+    const key = `${subject} ${predicate} ${object}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    rows.push({ subject: String(subject), predicate, object: String(object) });
+  };
+
+  for (const [cls, members] of boardMembersByClass(plan)) {
+    for (const m of members) add(m, "rdf:type", cls);
+  }
+
+  const at = states.length
+    ? states[Math.max(0, Math.min(states.length - 1, Math.floor(Number(step) || 0)))]
+    : [];
+  const supportOf = new Map();
+  const supporting = new Set();
+  for (const r of at || []) {
+    if (r?.subject == null || r.object == null) continue;
+    add(r.subject, r.predicate || HANOI_BOARD_RELATIONS.support.predicate, r.object);
+    supportOf.set(String(r.subject), String(r.object));
+    supporting.add(String(r.object));
+  }
+
+  const topOf = new Map();
+  for (const piece of [...supportOf.keys()].sort()) {
+    const ground = groundUnder(piece, supportOf);
+    if (!ground) continue;
+    add(piece, HANOI_BOARD_RELATIONS.placement.predicate, ground);
+    if (!supporting.has(piece)) topOf.set(ground, piece);
+  }
+  for (const [ground, top] of [...topOf.entries()].sort()) {
+    add(ground, HANOI_BOARD_RELATIONS.topDisk.predicate, top);
+  }
+
+  for (const row of plan?.domain?.ordering || []) {
+    if (!isThanPredicate(row?.predicate)) continue;
+    add(row.subject, HANOI_BOARD_RELATIONS.size.predicate, row.object);
+  }
+
+  actions.forEach((action, i) => {
+    const id = hanoiMoveId(i);
+    add(id, "rdf:type", HANOI_MOVE_CLASS);
+    add(id, HANOI_BOARD_RELATIONS.movesDisk.predicate, action?.subject);
+    add(id, HANOI_BOARD_RELATIONS.movesOnto.predicate, action?.target);
+  });
+
+  return rows;
+}
+
+/** Project hanoiBoardRows' own rows into the `{individuals, objectProperties}`
+ *  payload parseEntities consumes, so a page holding a live puzzle can hand
+ *  `ask()` a real graph of the position instead of an empty one.
+ *
+ *  Every `rdf:type` row makes its subject an individual of that class, and
+ *  that is the whole individuals set — a term the board only ever mentions as
+ *  the object of an edge is not a board piece and gets no class invented for
+ *  it. Every other row travels as an edge under its own predicate. Pure. */
+export function hanoiBoardGraphPayload(rows) {
+  const individuals = new Map();
+  for (const row of rows || []) {
+    if (row?.predicate !== "rdf:type" || !row.subject || !row.object) continue;
+    if (!individuals.has(row.subject)) {
+      individuals.set(row.subject, { id: row.subject, label: row.subject, class: row.object });
+    }
+  }
+  const groups = new Map();
+  for (const row of rows || []) {
+    if (!row?.subject || !row.predicate || row.predicate === "rdf:type") continue;
+    if (!groups.has(row.predicate)) {
+      groups.set(row.predicate, { prop: row.predicate, predicate: row.predicate, examples: [] });
+    }
+    groups.get(row.predicate).examples.push({ subject: row.subject, object: row.object });
+  }
+  return { individuals: [...individuals.values()], objectProperties: [...groups.values()] };
+}

package/src/domain/ingest-facts.mjs

@@ -0,0 +1,120 @@
+// ingest-facts.mjs — the projection from an ingest session's stored fact rows
+// to the `{individuals, objectProperties}` payload parseEntities consumes, so
+// the ingest page can hand `ask()` a real graph of what a visitor just pasted
+// instead of an empty one. The ingest counterpart to ask.mjs's
+// worldRelationGraphPayload and sprite-facts.mjs's spriteFactGraphPayload.
+//
+// It is shaped differently from both, because the domain is different.
+//
+// A world knows its own predicates ahead of time (ask-vocab.mjs's
+// WORLD_PREDICATES) and a sprite catalog knows its own subjects ahead of time
+// (one per template class), so each of those projections carries a curated
+// predicate or class table. Ingest knows neither: the vocabulary is whatever
+// the visitor's own prose grounded. So nothing here is curated by predicate
+// name at all — every row travels as an edge under its own predicate, and the
+// only rule with a table behind it is which predicates carry a CLASS.
+//
+// The class rule is what makes the graph answerable. `ask()`'s own
+// dynamicClassQuery ("how many dogs are there", "list dogs") resolves a class
+// noun straight against `individual.class`, with no vocabulary-table entry
+// needed, and that is the one lane an open-vocabulary graph can reach. So a
+// term's class is the object of its own taxonomy row: "a beagle is a kind of
+// dog" stores `beagle rdfs:subClassOf dog`, which classes the individual
+// `beagle` as a `dog`, which is what makes "list dogs" answer with the real
+// beagles on record. A term with no taxonomy row of its own still becomes an
+// individual (so a relation edge has both its ends) but carries no class, and
+// no class is ever minted for it — a listing it cannot ground lands on the
+// honest miss wall, the same standard every other projection holds.
+//
+// The class is the DIRECT taxonomy parent, not a closure over it: with
+// `fido -> beagle` and `beagle -> dog` on record, "list dogs" answers `beagle`
+// and "list beagles" answers `fido`. That is what the store actually says.
+//
+// Which rows to project is a separate decision from how to project them, and
+// the session makes it: `ingestedFactRows` keeps the facts a session brought
+// in itself (taught, operator-asserted, extracted, or the low-trust optimistic
+// tier) and drops the seeded corpus bands, which run to tens of thousands of
+// rows the visitor never typed. Both functions are pure.
+import { provenanceTagToSource } from "./memory/trust.mjs";
+
+/** The Source kinds that mean "this session brought this fact in", as opposed
+ *  to the corpus bands it booted with. Read off the same
+ *  `provenanceTagToSource` tags memory-stats.mjs's own taught/band split uses,
+ *  so the ask route and the stats panel can never disagree about which facts
+ *  are the visitor's own. */
+export const INGESTED_SOURCE_KINDS = Object.freeze(["teach", "operator", "extracted", "optimisticExtract"]);
+
+const INGESTED_KINDS = new Set(INGESTED_SOURCE_KINDS);
+
+/** True where this row's provenance names a source kind the visitor's own
+ *  session produced. A row whose provenance parses to nothing is not claimed. */
+export function isIngestedFactRow(row) {
+  for (const tag of String(row?.provenance || "").split(" | ")) {
+    if (!tag) continue;
+    const source = provenanceTagToSource(tag);
+    if (source && INGESTED_KINDS.has(source.kind)) return true;
+  }
+  return false;
+}
+
+/** The subset of `rows` (readFactRows' shape) this session grounded itself. */
+export function ingestedFactRows(rows) {
+  return (rows || []).filter(isIngestedFactRow);
+}
+
+/** The predicates whose object names the subject's CLASS. `rdfs:subClassOf` is
+ *  what the teach lane canonicalizes both "a beagle is a kind of dog" and
+ *  "Fido is a beagle" to; `rdf:type` is what a loaded world and an imported
+ *  pack write instead, and either can reach this store. */
+export const CLASSING_PREDICATES = Object.freeze(["rdfs:subClassOf", "rdf:type"]);
+
+const CLASSING = new Set(CLASSING_PREDICATES);
+
+/**
+ * Project plain ingest fact rows (`{subject, predicate, object}`, the shape
+ * memory/core.mjs's readFactRows returns) into the `{individuals,
+ * objectProperties}` payload parseEntities consumes.
+ *
+ * Every term that appears as a subject or an object becomes an individual, so
+ * an edge always has both its ends in `byId`. A term with a taxonomy row of
+ * its own is classed by that row's object — the FIRST such row in reading
+ * order, so a term taught two parents keeps the one the visitor stated first
+ * rather than a silently reordered pick. Every row, taxonomy rows included,
+ * also travels as an edge under its own predicate, deduplicated.
+ *
+ * Deterministic for identical input: individuals come out in first-seen order,
+ * predicate groups in first-seen predicate order. Pure.
+ */
+export function ingestFactGraphPayload(rows) {
+  const classByTerm = new Map();
+  for (const row of rows || []) {
+    if (!row?.subject || !row.object || !CLASSING.has(row.predicate)) continue;
+    const subject = String(row.subject);
+    if (!classByTerm.has(subject)) classByTerm.set(subject, String(row.object));
+  }
+
+  const individuals = new Map();
+  const noteTerm = (id) => {
+    if (individuals.has(id)) return;
+    const cls = classByTerm.get(id);
+    individuals.set(id, cls ? { id, label: id, class: cls } : { id, label: id });
+  };
+
+  const groups = new Map();
+  const seenEdges = new Set();
+  for (const row of rows || []) {
+    if (!row?.subject || !row.predicate || !row.object) continue;
+    const subject = String(row.subject);
+    const predicate = String(row.predicate);
+    const object = String(row.object);
+    noteTerm(subject);
+    noteTerm(object);
+    const edgeKey = `${predicate} ${subject} ${object}`;
+    if (seenEdges.has(edgeKey)) continue;
+    seenEdges.add(edgeKey);
+    if (!groups.has(predicate)) groups.set(predicate, { prop: predicate, predicate, examples: [] });
+    groups.get(predicate).examples.push({ subject, object });
+  }
+
+  return { individuals: [...individuals.values()], objectProperties: [...groups.values()] };
+}

package/src/domain/interpret/normalize.mjs

@@ -62,6 +62,55 @@ export function kindNounAnaphoraHint(text) {
   return m ? (ENTITY_TO_TYPE[m[2].toLowerCase()] || null) : null;
 }
 
+// ---- the dated teach frame: "<sentence> as of <date>" ----
+
+const MONTH_NAMES = [
+  "january", "february", "march", "april", "may", "june",
+  "july", "august", "september", "october", "november", "december",
+];
+
+/** A closed trailing suffix, not a grammar change: three accepted date forms
+ *  ("as of 2019", "as of 2019-03-01", "as of march 2019"), anchored to the
+ *  end of input with trailing punctuation tolerated. "as of" only — "as at",
+ *  "back in", and bare "in 2019" stay out (the last is ambiguous with
+ *  locatives: "the dog is in 2019" vs "the meeting is in room 4"). */
+const DATED_TEACH_SUFFIX_RE =
+  /\s+as\s+of\s+((?:19|20)\d{2}(?:-(?:0[1-9]|1[0-2])(?:-(?:0[1-9]|[12]\d|3[01]))?)?|(?:january|february|march|april|may|june|july|august|september|october|november|december)\s+(?:19|20)\d{2})\s*[.!?]*$/i;
+
+/** Read-only probe: does `text` carry a trailing "as of <date>" suffix? A hit
+ *  returns `{ stripped, observedAt, dateText }` — `stripped` is the sentence
+ *  with the suffix removed (exactly the shape the teach lanes already parse),
+ *  `dateText` the matched date phrase verbatim (for the acknowledgment echo),
+ *  and `observedAt` the ISO instant the date names, always Date.parse-able.
+ *  No hit, or a suffix with nothing left to teach, returns null. Same
+ *  read-only-probe shape as kindNounAnaphoraHint above — a helper a teach
+ *  lane consults, never a mutation of normalizeQuery's own text->text path.
+ *
+ *  The stored instant is the START of the named period (a bare year ->
+ *  <yyyy>-01-01T00:00:00.000Z; month+year -> the 1st of that month; a full
+ *  date -> that day, all at midnight UTC) — the CONSERVATIVE reading for
+ *  latest-observation-wins: it can under-claim how recent the observation
+ *  was, never over-claim it. */
+export function datedTeachSuffix(text) {
+  const s = String(text || "");
+  const m = DATED_TEACH_SUFFIX_RE.exec(s);
+  if (!m) return null;
+  const stripped = s.slice(0, m.index).trim();
+  if (!stripped) return null;
+  const dateText = m[1];
+  const isoForm = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(dateText);
+  let observedAt;
+  if (isoForm) {
+    const [, year, month, day] = isoForm;
+    observedAt = `${year}-${month || "01"}-${day || "01"}T00:00:00.000Z`;
+  } else {
+    const [, monthName, year] = /^([a-z]+)\s+(\d{4})$/i.exec(dateText);
+    const monthNum = String(MONTH_NAMES.indexOf(monthName.toLowerCase()) + 1).padStart(2, "0");
+    observedAt = `${year}-${monthNum}-01T00:00:00.000Z`;
+  }
+  return { stripped, observedAt, dateText };
+}
+
 // Every relation verb phrase, as one longest-first alternation — feeds the
 // DOES-X-VERB-ANYTHING-ELSE frame below without hardcoding a parallel list.
 const VERB_ALTERNATION = Object.keys(VERB_TO_KIND).sort((a, b) => b.length - a.length).map(escapeRegex).join("|");