@polycode-projects/the-mechanical-code-talker 1.10.14 → 1.11.5

package/src/memory/core.mjs

@@ -1023,7 +1023,7 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
   const p = normText(predicate);
   const o = normFactTerm(object);
   if (!s || !p || !o) throw new Error("a fact needs subject, predicate and object");
-  const id = `fact:${fnv1aHex(`${s}${p}${o}`)}`;
+  const id = `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
   const text = `${s} ${p} ${o}`;
   const tokens = proseTokensFor({ doc: text });
   const q = normText(quantifier);
@@ -1166,31 +1166,64 @@ export async function appendFacts(dir, facts) {
 export const RULE_KIND_COMPOSE2 = "compose2";
 export const RULE_KIND_FILTER = "filter";
 export const RULE_KIND_RECURSIVE = "recursive";
-export const RULE_KINDS = Object.freeze([RULE_KIND_COMPOSE2, RULE_KIND_FILTER, RULE_KIND_RECURSIVE]);
+// The action family: one taught sentence = one Rule individual, the family
+// sharing one mgx:ruleName. A single flat kind can't hold several
+// preconditions under content addressing (one value per slot), so signature,
+// precondition and effect are sibling kinds collected by name at plan time.
+export const RULE_KIND_ACTION_SIGNATURE = "action-signature";
+export const RULE_KIND_ACTION_PRECOND = "action-precond";
+export const RULE_KIND_ACTION_EFFECT = "action-effect";
+export const RULE_KIND_ACTION_CONSTRAINT = "action-constraint";
+export const RULE_KINDS = Object.freeze([
+  RULE_KIND_COMPOSE2, RULE_KIND_FILTER, RULE_KIND_RECURSIVE,
+  RULE_KIND_ACTION_SIGNATURE, RULE_KIND_ACTION_PRECOND, RULE_KIND_ACTION_EFFECT,
+  RULE_KIND_ACTION_CONSTRAINT,
+]);
 
 export const RULE_NAME_PROP = "mgx:ruleName";
 export const RULE_KIND_PROP = "mgx:ruleKind";
 
 // Per-kind slot contract: JS slot key -> the mgx: attribute it's written under.
-// filter's "base" slot deliberately reuses ruleBase1 (not a fresh "ruleBase")
-// — the same attribute name compose2's first hop already uses, since both
-// play the identical "base relation this rule builds on" role. Order within
-// each array is the (slot1, slot2) order the content-address hash below
-// uses — fixed and load-bearing.
+// filter's "base" slot reuses ruleBase1 — the same attribute name compose2's
+// first hop already uses, since both play the identical "base relation this
+// rule builds on" role. Order within each array is the content-address hash
+// order below — fixed and load-bearing. Predicate slots store BARE values
+// ("rest-on", "smaller-than"): normFactTerm strips a leading CURIE prefix, so
+// an mgx:-prefixed value could never round-trip; readers re-attach mgx:.
 const RULE_SLOT_SPEC = {
   [RULE_KIND_COMPOSE2]: [["base1", "mgx:ruleBase1"], ["base2", "mgx:ruleBase2"]],
   [RULE_KIND_FILTER]: [["base", "mgx:ruleBase1"], ["property", "mgx:ruleFilterProperty"]],
   [RULE_KIND_RECURSIVE]: [["baseCase", "mgx:ruleBaseCase"], ["recStep", "mgx:ruleRecStep"]],
+  [RULE_KIND_ACTION_SIGNATURE]: [
+    ["subjectClass", "mgx:ruleActionSubjectClass"], ["targetClass", "mgx:ruleActionTargetClass"],
+  ],
+  [RULE_KIND_ACTION_PRECOND]: [
+    ["shape", "mgx:ruleActionPrecondShape"], ["predicate", "mgx:ruleActionPrecondPredicate"],
+    ["role", "mgx:ruleActionPrecondRole"], ["scope", "mgx:ruleActionPrecondScope"],
+  ],
+  [RULE_KIND_ACTION_EFFECT]: [
+    ["predicate", "mgx:ruleActionEffectPredicate"], ["subjectRole", "mgx:ruleActionEffectSubject"],
+    ["objectRole", "mgx:ruleActionEffectObject"],
+  ],
+  // "the <left> may not be with the <right> without the <guard>" — each slot
+  // names a class whose sole member src/domain.mjs resolves at compile time.
+  [RULE_KIND_ACTION_CONSTRAINT]: [
+    ["left", "mgx:ruleActionConstraintLeft"], ["right", "mgx:ruleActionConstraintRight"],
+    ["guard", "mgx:ruleActionConstraintGuard"],
+  ],
 };
 
-// Content-addressed over (kind, name, slot1, slot2), mirroring factIdFor's
-// NUL-delimited discipline: identical rules upsert, different ones coexist.
-const ruleIdFor = (kind, name, slot1, slot2) => `rule:${fnv1aHex(`${kind}\0${name}\0${slot1}\0${slot2}`)}`;
-
-/** Append one taught RULE (compose2 | filter | recursive) — a sibling of
- *  appendFact storing a `Rule` individual, same upsert/provenance/trust/SHACL
- *  discipline (neither pipeline ever checks `individual.class`). `slots` is
- *  the matching per-kind object (RULE_SLOT_SPEC above). Returns { id }. */
+// Content-addressed over (kind, name, ...slots in RULE_SLOT_SPEC order),
+// mirroring factIdFor's NUL-delimited discipline: identical rules upsert,
+// different ones coexist. For 2-slot kinds the joined string is byte-identical
+// to the historical (kind, name, slot1, slot2) template, so pre-existing rule
+// ids never change (pinned by test/memory-rules-action.test.mjs).
+const ruleIdFor = (kind, name, slotValues) => `rule:${fnv1aHex([kind, name, ...slotValues].join("\0"))}`;
+
+/** Append one taught RULE — a sibling of appendFact storing a `Rule`
+ *  individual, same upsert/provenance/trust/SHACL discipline (neither
+ *  pipeline ever checks `individual.class`). `slots` is the matching
+ *  per-kind object (RULE_SLOT_SPEC above). Returns { id }. */
 export async function appendRule(dir, { name, kind, slots, provenance = "", createdAt = "" } = {}) {
   const spec = RULE_SLOT_SPEC[kind];
   if (!spec) throw new Error(`a rule kind must be one of ${RULE_KINDS.join(", ")}, got ${JSON.stringify(kind)}`);
@@ -1200,7 +1233,7 @@ export async function appendRule(dir, { name, kind, slots, provenance = "", crea
   if (slotValues.some((v) => !v)) {
     throw new Error(`a ${kind} rule needs ${spec.map(([slotKey]) => slotKey).join(" + ")}`);
   }
-  const id = ruleIdFor(kind, n, slotValues[0], slotValues[1]);
+  const id = ruleIdFor(kind, n, slotValues);
   const label = labelOf(`${n} = ${kind}(${slotValues.join(", ")})`);
   await mutateMemory(dir, async (payload) => {
     const prior = payload.individuals.find((x) => x?.id === id);
@@ -1244,6 +1277,45 @@ export function findRuleByName(memory, name) {
   );
 }
 
+/** Every Rule individual sharing `name` — an action family's members live as
+ *  sibling individuals (one per taught sentence), so consumers collect them
+ *  all. Sorted by kind then id for deterministic iteration. */
+export function findRulesByName(memory, name) {
+  const n = normFactTerm(name);
+  const kindOf = (i) => (i.attributes || []).find((a) => a?.prop === RULE_KIND_PROP)?.value || "";
+  return (memory?.individuals || [])
+    .filter((i) => i?.class === RULE_CLASS
+      && (i.attributes || []).find((a) => a?.prop === RULE_NAME_PROP)?.value === n)
+    .sort((a, b) => kindOf(a).localeCompare(kindOf(b)) || String(a.id).localeCompare(String(b.id)));
+}
+
+/** Every taught Rule as a plain row {id, name, kind, slots, provenance} —
+ *  the sibling of readFactRows, so consumers (src/domain.mjs) never touch
+ *  raw individuals. Rules whose kind has no RULE_SLOT_SPEC entry are
+ *  skipped (unreadable without a slot contract). Sorted by name, kind, id. */
+export function readRuleRows(memory) {
+  const rows = [];
+  for (const ind of memory?.individuals || []) {
+    if (ind?.class !== RULE_CLASS) continue;
+    const attr = (prop) => (ind.attributes || []).find((a) => a?.prop === prop)?.value;
+    const kind = attr(RULE_KIND_PROP);
+    const spec = RULE_SLOT_SPEC[kind];
+    if (!spec) continue;
+    const slots = {};
+    for (const [slotKey, prop] of spec) slots[slotKey] = attr(prop) ?? "";
+    rows.push({
+      id: ind.id,
+      name: attr(RULE_NAME_PROP) || "",
+      kind,
+      slots,
+      provenance: attr("mgx:factProvenance") || "",
+    });
+  }
+  rows.sort((a, b) => a.name.localeCompare(b.name)
+    || a.kind.localeCompare(b.kind) || String(a.id).localeCompare(String(b.id)));
+  return rows;
+}
+
 // ---- Relation chase ---------------------------------------------------------
 //
 // `resolveRelationChase` and `resolveRelationChaseReverse` are standalone,
@@ -1504,13 +1576,24 @@ export async function removeFacts(dir, ids) {
  *  contradiction (below it the fact is too weak to contradict anything). */
 export const CONTRADICTION_TRUST_FLOOR = 0.5;
 
+export const HAS_A_PREDICATE = "mgx:hasA";
+export const CAPABLE_OF_PREDICATE = "mgx:capableOf";
+
+/** Predicates whose real-world semantics allow many objects at once ("a dog
+ *  has legs" AND "a dog has a tail"; "a bird can fly" AND "a bird can sing"),
+ *  so a second object is a second fact, never a disagreement. A closed list:
+ *  every predicate outside it keeps the full contradiction contract. */
+export const MULTI_VALUED_PREDICATES = new Set([HAS_A_PREDICATE, CAPABLE_OF_PREDICATE]);
+
 /** Facts that CONTRADICT: same (subject, predicate), different object, each
  *  above the trust floor. Returns groups (trust-desc) so callers surface both,
- *  never silently pick one. Same (s,p,o) is corroboration, not contradiction. */
+ *  never silently pick one. Same (s,p,o) is corroboration, not contradiction,
+ *  and a MULTI_VALUED_PREDICATES predicate never contradicts on object count. */
 export function findContradictions(memory, { floor = CONTRADICTION_TRUST_FLOOR } = {}) {
   const rows = readFactRows(memory).filter((r) => r.trust >= floor);
   const byKey = new Map();
   for (const r of rows) {
+    if (MULTI_VALUED_PREDICATES.has(r.predicate)) continue;
     const key = `${r.subject} ${r.predicate}`;
     if (!byKey.has(key)) byKey.set(key, []);
     byKey.get(key).push(r);

package/src/memory/shacl.mjs

@@ -6,15 +6,29 @@
 // only fires on genuine malformation, never a sparse-but-valid write.
 
 const MEMORY_CLASSES = new Set(["Utterance", "Fact", "Session", "Source", "Rule"]);
-const RULE_KINDS = new Set(["compose2", "filter", "recursive"]);
+const RULE_KINDS = new Set([
+  "compose2", "filter", "recursive",
+  "action-signature", "action-precond", "action-effect", "action-constraint",
+]);
 
 // Mirrors core.mjs's own (unexported) RULE_SLOT_SPEC exactly — the single
-// source of truth for the closed compose2/filter/recursive shapes; kept in
-// sync by hand (both describe the SAME three rule kinds' slot pairs).
+// source of truth for the closed rule-kind shapes; kept in sync by hand
+// (both describe the same kinds' slots).
 const RULE_SLOT_PROPS = {
   compose2: ["mgx:ruleBase1", "mgx:ruleBase2"],
   filter: ["mgx:ruleBase1", "mgx:ruleFilterProperty"],
   recursive: ["mgx:ruleBaseCase", "mgx:ruleRecStep"],
+  "action-signature": ["mgx:ruleActionSubjectClass", "mgx:ruleActionTargetClass"],
+  "action-precond": [
+    "mgx:ruleActionPrecondShape", "mgx:ruleActionPrecondPredicate",
+    "mgx:ruleActionPrecondRole", "mgx:ruleActionPrecondScope",
+  ],
+  "action-effect": [
+    "mgx:ruleActionEffectPredicate", "mgx:ruleActionEffectSubject", "mgx:ruleActionEffectObject",
+  ],
+  "action-constraint": [
+    "mgx:ruleActionConstraintLeft", "mgx:ruleActionConstraintRight", "mgx:ruleActionConstraintGuard",
+  ],
 };
 
 function attrValue(ind, prop) {
@@ -45,14 +59,13 @@ function checkFact(ind, violations) {
 }
 
 /** RuleShape (mgx:RuleShape): a non-empty name; a kind from the closed
- *  compose2 | filter | recursive vocabulary; and the matching pair of slots
- *  for that declared kind, each present and non-empty (RULE_SLOT_PROPS
- *  above). */
+ *  vocabulary; and the matching slots for that declared kind, each present
+ *  and non-empty (RULE_SLOT_PROPS above). */
 function checkRule(ind, violations) {
   if (!nonEmpty(attrValue(ind, "mgx:ruleName"))) violations.push("a Rule needs a non-empty mgx:ruleName");
   const kind = attrValue(ind, "mgx:ruleKind");
   if (!kind || !RULE_KINDS.has(kind)) {
-    violations.push(`a Rule's mgx:ruleKind must be one of compose2 | filter | recursive (got ${JSON.stringify(kind)})`);
+    violations.push(`a Rule's mgx:ruleKind must be one of ${[...RULE_KINDS].join(" | ")} (got ${JSON.stringify(kind)})`);
     return; // no declared kind to check slots against
   }
   for (const prop of RULE_SLOT_PROPS[kind]) {

package/src/memory-ask-browser-entry.mjs

@@ -1,13 +1,15 @@
-// memory-ask-browser-entry.mjs — the esbuild entry for `tmct viz`'s embedded
-// "Ask the graph" panel's memory-graph engine.
+// memory-ask-browser-entry.mjs — the esbuild entry for the ledger page's
+// chat dock (`tmct viz`, src/ledger-viz.mjs).
 //
 // Re-exports `factAnswer` (src/chat.mjs) and `createInMemoryStore`
-// (src/memory/core.mjs), which lets the panel hand `factAnswer` the page's
+// (src/memory/core.mjs), which lets the dock hand `factAnswer` the page's
 // already-embedded payload with zero fs I/O. Called with `envelope: null,
 // miss: true` to arm factAnswer's bare-question regex fallbacks directly,
-// bypassing the structural-graph parse pipeline this panel has no use for.
-import { factAnswer } from "./chat.mjs";
+// bypassing the structural-graph parse pipeline this dock has no use for.
+import { factAnswer, factReadBack } from "./chat.mjs";
 import { createInMemoryStore, normFactTerm } from "./memory/core.mjs";
 
-// normFactTerm is re-exported too, for viz.mjs's client-side term normalization.
-globalThis.tmctMemoryAsk = { factAnswer, createInMemoryStore, normFactTerm };
+// normFactTerm is re-exported too, for the page's client-side term normalization.
+// factReadBack carries the taught-relation chases (grandfather-style questions)
+// that factAnswer's own lanes don't reach.
+globalThis.tmctMemoryAsk = { factAnswer, factReadBack, createInMemoryStore, normFactTerm };