@polycode-projects/the-mechanical-code-talker 0.2.0 → 0.3.0

package/src/corpus/conceptnet.mjs

@@ -0,0 +1,155 @@
+// corpus/conceptnet.mjs — the ConceptNet slice loader + memory seeder
+// (ROADMAP Phase 2, "ConceptNet corpus slice").
+//
+//   loadSlice(path?)        stream corpus/conceptnet/slice.jsonl → assertions
+//   loadMap(path?)          src/corpus/conceptnet-map.toml → Map(rel → row)
+//   toFacts(assertions,map) assertions → appendFact-shaped triples
+//   seedMemory(dir, opts)   write them into <dir>/.tmct/memory via appendFact
+//
+// The slice is committed data (one JSON object per line: {start, rel, end,
+// surfaceText?, weight}; en→en only; CC-BY-SA 4.0 for ConceptNet-derived rows
+// — see corpus/conceptnet/LICENSE-NOTICE). The mapping table decides which
+// relations become memory facts and under which predicate URI; rows marked
+// ace = "none" are deliberate non-emissions. A slice relation MISSING from
+// the table is a drift error — loud, never guessed around.
+//
+// Seeding goes through src/memory/core.mjs appendFact() ONLY (memory is
+// import-only here): fact ids are content-hashed from (s,p,o), so re-seeding
+// is idempotent by construction. seedMemory additionally pre-loads the store
+// once and skips triples already present, so a re-seed is read-mostly instead
+// of N rewrites.
+
+import { createReadStream } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { appendFact, loadMemory, normFactTerm } from "../memory/core.mjs";
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const SLICE_FILE = join(PKG_ROOT, "corpus", "conceptnet", "slice.jsonl");
+export const MAP_FILE = join(PKG_ROOT, "src", "corpus", "conceptnet-map.toml");
+
+const ACE_PATTERNS = new Set(["subClassOf", "type", "ObjectProperty", "someValuesFrom", "disjointWith", "property", "none"]);
+
+/** Load the slice JSONL as a stream (never the whole file as one string) and
+ *  return the parsed assertions. Every line must carry start/rel/end; bad
+ *  lines fail loudly with file:line. */
+export async function loadSlice(path = SLICE_FILE) {
+  const rl = createInterface({ input: createReadStream(path, "utf8"), crlfDelay: Infinity });
+  const assertions = [];
+  let n = 0;
+  for await (const raw of rl) {
+    n += 1;
+    const line = raw.trim();
+    if (!line) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (e) {
+      throw new Error(`${path}:${n}: not valid JSON: ${e.message}`);
+    }
+    for (const field of ["start", "rel", "end"]) {
+      if (typeof row[field] !== "string" || !row[field]) {
+        throw new Error(`${path}:${n}: assertion missing "${field}"`);
+      }
+    }
+    assertions.push(row);
+  }
+  return assertions;
+}
+
+/** Load the relation → ACE-OWL mapping table. Returns Map(rel → row); every
+ *  row must have a known `ace` pattern, and a mapped (non-"none") row must
+ *  name the predicate URI it emits. */
+export async function loadMap(path = MAP_FILE) {
+  const table = parseToml(await readFile(path, "utf8"));
+  const rows = table.relation || [];
+  const map = new Map();
+  for (const row of rows) {
+    if (!row.rel) throw new Error(`${path}: a [[relation]] row is missing "rel"`);
+    if (map.has(row.rel)) throw new Error(`${path}: duplicate mapping for ${row.rel}`);
+    if (!ACE_PATTERNS.has(row.ace)) {
+      throw new Error(`${path}: ${row.rel} has unknown ace pattern ${JSON.stringify(row.ace)}`);
+    }
+    if (row.ace !== "none" && !row.predicate) {
+      throw new Error(`${path}: ${row.rel} maps to ${row.ace} but names no predicate URI`);
+    }
+    map.set(row.rel, row);
+  }
+  return map;
+}
+
+/** /c/en/source_code → "source code" — the human term text a memory fact stores. */
+export const termText = (uri) => {
+  const m = /^\/c\/en\/([^/]+)/.exec(String(uri || ""));
+  return m ? m[1].replace(/_/g, " ") : null;
+};
+
+/** Map slice assertions → appendFact-shaped triples:
+ *    { subject, predicate, object, provenance }
+ *  (provenance is a STRING — exactly what src/memory/core.mjs appendFact
+ *  takes; it names the corpus and the originating ConceptNet relation).
+ *  Rows whose relation maps ace="none" are skipped — deliberate non-emission.
+ *  A relation with NO row in the map throws: that is table drift, not data. */
+export function toFacts(assertions, map) {
+  const facts = [];
+  for (const a of assertions) {
+    const row = map.get(a.rel);
+    if (!row) {
+      throw new Error(`slice/map drift: relation ${a.rel} has no row in conceptnet-map.toml`);
+    }
+    if (row.ace === "none") continue;
+    const subject = termText(a.start);
+    const object = termText(a.end);
+    if (!subject || !object) continue; // non-en endpoint slipped in — filtered, not fatal
+    facts.push({
+      subject,
+      predicate: row.predicate,
+      object,
+      provenance: `corpus:conceptnet ${a.rel}`,
+    });
+  }
+  return facts;
+}
+
+/** Seed a repo's memory graph (<dir>/.tmct/memory/graph.json) from the
+ *  committed slice. Options: limit (cap the facts written — handy for tests
+ *  and fast bootstraps), slicePath/mapPath overrides.
+ *
+ *  Idempotent twice over: appendFact's content-hashed ids make a blind
+ *  re-append an upsert, and we pre-read the store once to skip triples that
+ *  are already there (so re-seeding costs one read, not N rewrites).
+ *  Returns { appended, skipped, total }. */
+export async function seedMemory(dir, { limit, slicePath = SLICE_FILE, mapPath = MAP_FILE } = {}) {
+  const [assertions, map] = await Promise.all([loadSlice(slicePath), loadMap(mapPath)]);
+  let facts = toFacts(assertions, map);
+  if (limit !== undefined) facts = facts.slice(0, limit);
+
+  // One read up front: what does the store already reify? Keys are built with
+  // memory's own normFactTerm so they match the normalized read-back exactly
+  // (appendFact converges /c/en/foo_bar, tmct:Foo and "Foo bar" to one term).
+  const factKey = (s, p, o) => `${normFactTerm(s)} ${p} ${normFactTerm(o)}`;
+  const existing = new Set();
+  const memory = await loadMemory(dir);
+  for (const ind of memory.individuals || []) {
+    if (ind?.class !== "Fact") continue;
+    const get = (key) => (ind.attributes || []).find((x) => x.key === key)?.value;
+    existing.add(factKey(get("subject"), get("predicate"), get("object")));
+  }
+
+  let appended = 0;
+  let skipped = 0;
+  for (const fact of facts) {
+    const key = factKey(fact.subject, fact.predicate, fact.object);
+    if (existing.has(key)) {
+      skipped += 1;
+      continue;
+    }
+    await appendFact(dir, fact);
+    existing.add(key);
+    appended += 1;
+  }
+  return { appended, skipped, total: facts.length };
+}

package/src/corpus/templates.mjs

@@ -0,0 +1,104 @@
+// corpus/templates.mjs — the response-template library + SE phrase book loaders
+// (ROADMAP Phase 2, items 4+7). Plain diffable data in, strict renderers out:
+//
+//   data/templates/responses.jsonl   {id, class, template, register} rows
+//   data/phrasebook/software-phrases.txt  one phrase pattern per line
+//                                         (`#` comments, `~` synonym families)
+//
+// loadTemplates() validates the whole file (parse, required fields, unique
+// ids) and caches; render(id, slots) is then synchronous and STRICT — an
+// unknown id or a missing slot throws, it never emits a half-filled sentence.
+// The response surface (Phase 1 pipeline) fills templates from grounded data
+// only, so a thrown slot is a programming error, not a user-facing miss.
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export const TEMPLATES_FILE = join(PKG_ROOT, "data", "templates", "responses.jsonl");
+export const PHRASEBOOK_FILE = join(PKG_ROOT, "data", "phrasebook", "software-phrases.txt");
+
+const REGISTERS = new Set(["terse", "friendly"]);
+const SLOT_RE = /\{([A-Za-z][A-Za-z0-9]*)\}/g;
+
+/** The slot names a template string requires, in first-appearance order. */
+export function slotsOf(template) {
+  const out = [];
+  for (const m of String(template).matchAll(SLOT_RE)) {
+    if (!out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
+}
+
+let cache = null; // Map<id, row> from the last loadTemplates() — render()'s source
+
+/** Load + validate the response templates. Every line must parse as JSON with
+ *  a unique `id`, a `class`, a known `register`, and a non-empty `template`
+ *  (bad data fails loudly at load, never at render time). Returns Map<id,row>
+ *  (each row gains `slots`, its required slot names) and primes render(). */
+export async function loadTemplates(path = TEMPLATES_FILE) {
+  const text = await readFile(path, "utf8");
+  const byId = new Map();
+  const lines = text.split("\n");
+  for (let n = 0; n < lines.length; n += 1) {
+    const line = lines[n].trim();
+    if (!line) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (e) {
+      throw new Error(`${path}:${n + 1}: not valid JSON: ${e.message}`);
+    }
+    for (const field of ["id", "class", "template", "register"]) {
+      if (typeof row[field] !== "string" || !row[field]) {
+        throw new Error(`${path}:${n + 1}: missing/empty "${field}"`);
+      }
+    }
+    if (!REGISTERS.has(row.register)) {
+      throw new Error(`${path}:${n + 1}: register must be terse|friendly, got "${row.register}"`);
+    }
+    if (byId.has(row.id)) throw new Error(`${path}:${n + 1}: duplicate template id "${row.id}"`);
+    byId.set(row.id, { ...row, slots: slotsOf(row.template) });
+  }
+  cache = byId;
+  return byId;
+}
+
+/** Fill template `id` with `slots` — strict: unknown id throws; ANY missing
+ *  slot throws (named), so a response is complete or not emitted at all.
+ *  Extra slots are ignored. Uses the map from loadTemplates() (pass
+ *  `templates` explicitly to bypass the module cache, e.g. in tests). */
+export function render(id, slots = {}, templates = cache) {
+  if (!templates) throw new Error("render() before loadTemplates() — load the template library first");
+  const row = templates.get(id);
+  if (!row) throw new Error(`unknown template id "${id}"`);
+  const missing = row.slots.filter((s) => slots[s] === undefined || slots[s] === null);
+  if (missing.length) {
+    throw new Error(`template "${id}" missing slot${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}`);
+  }
+  return row.template.replace(SLOT_RE, (_, name) => String(slots[name]));
+}
+
+/** Load + parse the SE phrase book. Returns:
+ *    patterns  [{pattern, slots}]  one per phrase line ("what calls {x}")
+ *    synonyms  [[word, …], …]      one per `~` family line (≥2 entries each)
+ *  `#`-prefixed lines and blank lines are skipped. */
+export async function loadPhrasebook(path = PHRASEBOOK_FILE) {
+  const text = await readFile(path, "utf8");
+  const patterns = [];
+  const synonyms = [];
+  const lines = text.split("\n");
+  for (let n = 0; n < lines.length; n += 1) {
+    const line = lines[n].trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("~")) {
+      const family = line.slice(1).split(",").map((w) => w.trim().toLowerCase()).filter(Boolean);
+      if (family.length < 2) throw new Error(`${path}:${n + 1}: a synonym family needs at least 2 entries`);
+      synonyms.push(family);
+      continue;
+    }
+    patterns.push({ pattern: line, slots: slotsOf(line) });
+  }
+  return { patterns, synonyms };
+}

package/src/grammar/ace.mjs

@@ -0,0 +1,341 @@
+// grammar/ace.mjs — tmct's deterministic ACE-OWL sub-fragment parser (ROADMAP
+// Phase 2, item 2). Implements the 8 controlled-English sentence patterns of
+// docs/references/schemas/ace-owl-fragment.md and nothing more: fitting the
+// grammar is a strong signal, missing it is a FEATURE — parseAce returns null
+// (or an empty-triples result carrying the unknown words as `residue`) and the
+// interpretation pipeline (src/interpret/) falls through to the tolerant
+// strategies. No NLP dependency: tokenization is whitespace + trailing
+// punctuation, morphology is the lexicon's suffix fold.
+//
+// parseAce(sentence, lexicon) → { pattern, triples, residue } | null
+//   pattern  one of: subClassOf | typeAssertion | relation | someValuesFrom |
+//            cardinality | disjointWith | possessive | adjective
+//   triples  [{ subject, predicate, object, kind, n? }] — OWL-labelled string
+//            triples shaped for src/memory/core.mjs's appendFact (which
+//            normalizes subject/object via normFactTerm: "tmct:module" is
+//            stored as "module"; the predicate keeps its vocabulary casing).
+//   residue  [] on a clean parse; the unknown tokens when the sentence FITS a
+//            pattern structurally but uses undeclared words (triples is then
+//            empty — feeds the pipeline's "if you mean X…" surround).
+//   null     the sentence does not fit the fragment at all.
+//
+// Term style: classes/individuals are `tmct:<lexeme>` CURIEs (lexicon lemma
+// for nouns, canonical spelling for proper names, the literal token for
+// code-shaped references like chat.mjs); predicates are the OWL/RDF(S)
+// vocabulary terms or the lexicon verb's tmct:<3sg> predicate. Restriction
+// and intersection class expressions get READABLE deterministic node names
+// (tmct:some-imports-test, tmct:module-that-imports-test) instead of blank
+// nodes, so the same sentence always re-emits the same triples and appendFact
+// stays idempotent. An intersection is flattened to repeated
+// owl:intersectionOf triples (one per member) — the flat-JSON stand-in for an
+// RDF list, documented in ontology/tmct-core.ttl.
+
+import {
+  loadLexicon, lookupNoun, lookupVerb, lookupAdjective, lookupProperName,
+  predicateOf, numberOf, classify,
+} from "./lexicon.mjs";
+
+const DET = new Set(["a", "an", "the"]);
+// A token SHAPED like a code reference (a path, file, symbol or CURIE) is an
+// individual by form — a deterministic tokenizer rule, not a guess: declared
+// proper names cover words; this covers chat.mjs, src/ask.mjs, Foo#bar.
+const CODE_REF = /[./\\#:@]/;
+
+/** Whitespace tokenizer: curly quotes normalized, commas/semicolons dropped,
+ *  ONE trailing punctuation run stripped (so "chat.mjs." keeps its dots). */
+export function tokenize(sentence) {
+  return String(sentence ?? "")
+    .replace(/[‘’]/g, "'")
+    .replace(/[,;]/g, " ")
+    .replace(/[?!.]+\s*$/, "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+const local = (term) => String(term).replace(/^tmct:/, "");
+
+const stripDet = (tokens) =>
+  tokens.length > 1 && DET.has(tokens[0].toLowerCase()) ? tokens.slice(1) : tokens;
+
+/** Resolve a 1–2 word noun phrase: PROPERNAME | code-ref | NOUN | ADJ NOUN.
+ *  Returns { term, individual, extras, unknown } — `term` null on a miss with
+ *  the undeclared tokens in `unknown` (empty `unknown` = structurally
+ *  unparseable phrase → the caller returns a hard null). `extras` carries the
+ *  pattern-8 adjective triples (subclass axioms / hasValue restriction). */
+function resolveNP(lexicon, tokensIn) {
+  const tokens = stripDet(tokensIn);
+  if (tokens.length === 1) {
+    const t = tokens[0];
+    const proper = lookupProperName(lexicon, t);
+    if (proper) return { term: `tmct:${proper}`, individual: true, extras: [], unknown: [] };
+    if (CODE_REF.test(t)) return { term: `tmct:${t}`, individual: true, extras: [], unknown: [] };
+    const noun = lookupNoun(lexicon, t);
+    if (noun) return { term: `tmct:${noun.lemma}`, individual: false, noun, extras: [], unknown: [] };
+    return { term: null, individual: false, extras: [], unknown: [t] };
+  }
+  if (tokens.length === 2) {
+    const adj = lookupAdjective(lexicon, tokens[0]);
+    const noun = lookupNoun(lexicon, tokens[1]);
+    if (adj && noun) {
+      const term = `tmct:${adj.lemma}-${noun.lemma}`;
+      const extras = [
+        { subject: term, predicate: "rdfs:subClassOf", object: `tmct:${noun.lemma}`, kind: "rdfs:subClassOf" },
+      ];
+      if (adj.type === "subclass") {
+        // the adjective itself denotes a class: legacy-module ⊑ module, ⊑ legacy
+        extras.push({ subject: term, predicate: "rdfs:subClassOf", object: `tmct:${adj.lemma}`, kind: "rdfs:subClassOf" });
+      } else {
+        // data adjective: subclass-with-restriction on the boolean-ish property
+        const r = `tmct:has-${adj.lemma}`;
+        extras.push(
+          { subject: r, predicate: "rdf:type", object: "owl:Restriction", kind: "owl:hasValue" },
+          { subject: r, predicate: "owl:onProperty", object: adj.property || `tmct:${adj.lemma}`, kind: "owl:hasValue" },
+          { subject: r, predicate: "owl:hasValue", object: adj.value ?? "true", kind: "owl:hasValue" },
+          { subject: term, predicate: "rdfs:subClassOf", object: r, kind: "owl:hasValue" },
+        );
+      }
+      return { term, individual: false, noun, extras, unknown: [] };
+    }
+    // only genuinely undeclared words are residue — a declared word in the
+    // wrong slot ("GitLab pipeline") is a structural miss, not an unknown
+    const unknown = tokens.filter((t) => !classify(t, lexicon));
+    return { term: null, individual: false, extras: [], unknown };
+  }
+  // 0 or 3+ tokens: not a fragment NP. Name the undeclared words if any.
+  return { term: null, individual: false, extras: [], unknown: tokens.filter((t) => !classify(t, lexicon)) };
+}
+
+/** The shared miss result: a structural fit with undeclared words returns the
+ *  pattern + residue (triples empty); a fit with only declared-but-unusable
+ *  phrasing returns null — the honest fall-through either way. */
+function missOrNull(pattern, nps, extraUnknown = []) {
+  const residue = [...extraUnknown, ...nps.flatMap((np) => np.unknown)];
+  return residue.length ? { pattern, triples: [], residue } : null;
+}
+
+const hit = (pattern, nps, triples, more = {}) => ({
+  pattern,
+  triples: [...nps.flatMap((np) => np.extras), ...triples],
+  residue: [],
+  ...more,
+});
+
+/** Pattern 3 — "N1 VERB N2" / "PROPERNAME VERBs PROPERNAME" → object-property
+ *  assertion. Also the no-declared-verb 3-token shape: both ends resolvable →
+ *  residue names the middle token (the future "if you mean X…" hook). */
+function parseRelation(lexicon, toks, lower) {
+  for (let i = 1; i < toks.length - 1; i += 1) {
+    const verb = lookupVerb(lexicon, lower[i]);
+    if (!verb) continue;
+    let objStart = i + 1;
+    if (verb.prep) {
+      if (lower[objStart] !== verb.prep) continue;
+      objStart += 1;
+      if (objStart >= toks.length) continue;
+    }
+    const np1 = resolveNP(lexicon, toks.slice(0, i));
+    const np2 = resolveNP(lexicon, toks.slice(objStart));
+    if (np1.term == null || np2.term == null) return missOrNull("relation", [np1, np2]);
+    return hit("relation", [np1, np2], [
+      { subject: np1.term, predicate: predicateOf(verb), object: np2.term, kind: "owl:ObjectProperty" },
+    ]);
+  }
+  const content = toks.filter((t) => !DET.has(t.toLowerCase()));
+  if (content.length === 3 && !classify(content[1], lexicon)) {
+    const np1 = resolveNP(lexicon, [content[0]]);
+    const np2 = resolveNP(lexicon, [content[2]]);
+    if (np1.term != null && np2.term != null) return { pattern: "relation", triples: [], residue: [content[1]] };
+  }
+  return null;
+}
+
+/** Pattern 8 (copula arm) — "X is ADJ": data adjective → datatype-property
+ *  assertion; subclass adjective → rdf:type (individual) / rdfs:subClassOf. */
+function adjectiveCopula(pattern, np1, adj) {
+  if (np1.term == null) return missOrNull(pattern, [np1]);
+  if (adj.type === "data") {
+    return hit(pattern, [np1], [
+      { subject: np1.term, predicate: adj.property || `tmct:${adj.lemma}`, object: adj.value ?? "true", kind: "owl:DatatypeProperty" },
+    ]);
+  }
+  const predicate = np1.individual ? "rdf:type" : "rdfs:subClassOf";
+  return hit(pattern, [np1], [
+    { subject: np1.term, predicate, object: `tmct:${adj.lemma}`, kind: predicate },
+  ]);
+}
+
+/** Pattern 4 — "every N1 that VERBs a N2 is a N3" → someValuesFrom restriction:
+ *  (N1 ⊓ ∃VERB.N2) ⊑ N3, flattened onto readable deterministic node names. */
+function parseRestriction(lexicon, toks, lower, thatIdx) {
+  const isIdx = lower.indexOf("is", thatIdx + 2);
+  if (isIdx < 0 || thatIdx + 1 >= isIdx) return null;
+  const verb = lookupVerb(lexicon, lower[thatIdx + 1]);
+  const np1 = resolveNP(lexicon, toks.slice(1, thatIdx));
+  let objStart = thatIdx + 2;
+  if (verb?.prep) {
+    if (lower[objStart] !== verb.prep) return null;
+    objStart += 1;
+  }
+  const np2 = resolveNP(lexicon, toks.slice(objStart, isIdx));
+  const np3 = resolveNP(lexicon, toks.slice(isIdx + 1));
+  if (!verb) return missOrNull("someValuesFrom", [np1, np2, np3], [toks[thatIdx + 1]]);
+  if (np1.term == null || np2.term == null || np3.term == null) {
+    return missOrNull("someValuesFrom", [np1, np2, np3]);
+  }
+  if (np1.individual || np2.individual || np3.individual) return null; // class-level pattern only
+  const pred = predicateOf(verb);
+  const k = "owl:someValuesFrom";
+  const r = `tmct:some-${local(pred)}-${local(np2.term)}`;
+  const inter = `tmct:${local(np1.term)}-that-${local(pred)}-${local(np2.term)}`;
+  return hit("someValuesFrom", [np1, np2, np3], [
+    { subject: r, predicate: "rdf:type", object: "owl:Restriction", kind: k },
+    { subject: r, predicate: "owl:onProperty", object: pred, kind: k },
+    { subject: r, predicate: "owl:someValuesFrom", object: np2.term, kind: k },
+    { subject: inter, predicate: "owl:intersectionOf", object: np1.term, kind: k },
+    { subject: inter, predicate: "owl:intersectionOf", object: r, kind: k },
+    { subject: inter, predicate: "rdfs:subClassOf", object: np3.term, kind: k },
+  ]);
+}
+
+/** Pattern 5 — "every N has at least|at most|exactly n N2" → cardinality
+ *  restriction on tmct:has (owl:onClass records the counted class — the
+ *  qualified-form question is noted in docs/references/schemas/owl2-vocabulary.md). */
+function parseCardinality(lexicon, toks, lower, hasIdx) {
+  let kind = null;
+  let nIdx = -1;
+  if (lower[hasIdx + 1] === "at" && lower[hasIdx + 2] === "least") { kind = "owl:minCardinality"; nIdx = hasIdx + 3; }
+  else if (lower[hasIdx + 1] === "at" && lower[hasIdx + 2] === "most") { kind = "owl:maxCardinality"; nIdx = hasIdx + 3; }
+  else if (lower[hasIdx + 1] === "exactly") { kind = "owl:cardinality"; nIdx = hasIdx + 2; }
+  else return null;
+  const n = numberOf(lower[nIdx]);
+  if (n == null || nIdx + 1 >= toks.length) return null;
+  const np1 = resolveNP(lexicon, toks.slice(1, hasIdx));
+  const np2 = resolveNP(lexicon, toks.slice(nIdx + 1));
+  if (np1.term == null || np2.term == null) return missOrNull("cardinality", [np1, np2]);
+  if (np1.individual || np2.individual) return null;
+  const tag = { "owl:minCardinality": "min", "owl:maxCardinality": "max", "owl:cardinality": "exactly" }[kind];
+  const r = `tmct:${tag}-${n}-${local(np2.term)}`;
+  return hit("cardinality", [np1, np2], [
+    { subject: r, predicate: "rdf:type", object: "owl:Restriction", kind },
+    { subject: r, predicate: "owl:onProperty", object: "tmct:has", kind },
+    { subject: r, predicate: kind, object: String(n), kind, n },
+    { subject: r, predicate: "owl:onClass", object: np2.term, kind },
+    { subject: np1.term, predicate: "rdfs:subClassOf", object: r, kind },
+  ], { n });
+}
+
+/** Patterns 1, 4, 5 and 8's "every …" arm. */
+function parseEvery(lexicon, toks, lower) {
+  const thatIdx = lower.indexOf("that");
+  if (thatIdx > 1) return parseRestriction(lexicon, toks, lower, thatIdx);
+  const hasIdx = lower.indexOf("has");
+  if (hasIdx > 1 && (lower[hasIdx + 1] === "at" || lower[hasIdx + 1] === "exactly")) {
+    return parseCardinality(lexicon, toks, lower, hasIdx);
+  }
+  const isIdx = lower.indexOf("is");
+  if (isIdx <= 1 || isIdx === toks.length - 1) return null;
+  const np1 = resolveNP(lexicon, toks.slice(1, isIdx));
+  const rest = toks.slice(isIdx + 1);
+  if (rest.length === 1) {
+    const adj = lookupAdjective(lexicon, rest[0]);
+    if (adj) return adjectiveCopula("adjective", np1, adj);
+  }
+  const np2 = resolveNP(lexicon, rest);
+  if (np1.term == null || np2.term == null) return missOrNull("subClassOf", [np1, np2]);
+  if (np1.individual || np2.individual) return null; // "every X is chat.mjs" — not the fragment
+  return hit("subClassOf", [np1, np2], [
+    { subject: np1.term, predicate: "rdfs:subClassOf", object: np2.term, kind: "rdfs:subClassOf" },
+  ]);
+}
+
+/** Pattern 6 — "no N1 is a N2" → owl:disjointWith. */
+function parseDisjoint(lexicon, toks, lower) {
+  const isIdx = lower.indexOf("is");
+  if (isIdx <= 1 || isIdx === toks.length - 1) return null;
+  const np1 = resolveNP(lexicon, toks.slice(1, isIdx));
+  const np2 = resolveNP(lexicon, toks.slice(isIdx + 1));
+  if (np1.term == null || np2.term == null) return missOrNull("disjointWith", [np1, np2]);
+  if (np1.individual || np2.individual) return null;
+  return hit("disjointWith", [np1, np2], [
+    { subject: np1.term, predicate: "owl:disjointWith", object: np2.term, kind: "owl:disjointWith" },
+  ]);
+}
+
+/** Pattern 7 — "N1's N2 is VALUE" / "the N2 of N1 is VALUE": data or object
+ *  property assertion per the possessive noun's DECLARED typing (undeclared
+ *  typing defaults to data — a literal value is the honest floor). */
+function buildPossessive(lexicon, ownerToks, headToks, valueToks) {
+  const owner = resolveNP(lexicon, ownerToks);
+  if (headToks.length !== 1) return null;
+  const head = lookupNoun(lexicon, headToks[0]);
+  if (!head) return missOrNull("possessive", [owner], [headToks[0]]);
+  if (owner.term == null) return missOrNull("possessive", [owner]);
+  if (!valueToks.length) return null;
+  const predicate = `tmct:${head.lemma}`;
+  if ((head.property || "data") === "object") {
+    const value = resolveNP(lexicon, valueToks);
+    if (value.term == null) return missOrNull("possessive", [owner, value]);
+    return hit("possessive", [owner, value], [
+      { subject: owner.term, predicate, object: value.term, kind: "owl:ObjectProperty" },
+    ]);
+  }
+  return hit("possessive", [owner], [
+    { subject: owner.term, predicate, object: valueToks.join(" "), kind: "owl:DatatypeProperty" },
+  ]);
+}
+
+function parsePossessive(lexicon, toks, lower) {
+  const ownerRaw = toks[0].replace(/'s$/i, "");
+  const isIdx = lower.indexOf("is");
+  if (isIdx < 2 || !ownerRaw) return null;
+  return buildPossessive(lexicon, [ownerRaw], toks.slice(1, isIdx), toks.slice(isIdx + 1));
+}
+
+function parseOfForm(lexicon, toks, lower) {
+  const ofIdx = lower.indexOf("of");
+  const isIdx = lower.indexOf("is", ofIdx + 1);
+  if (ofIdx < 2 || isIdx < ofIdx + 2) return null;
+  return buildPossessive(lexicon, toks.slice(ofIdx + 1, isIdx), toks.slice(1, ofIdx), toks.slice(isIdx + 1));
+}
+
+/** Patterns 2 (class assertion), 1's bare-copula variant, and 8's copula arm. */
+function parseCopula(lexicon, toks, lower, isIdx) {
+  const np1 = resolveNP(lexicon, toks.slice(0, isIdx));
+  const rest = toks.slice(isIdx + 1);
+  if (!rest.length) return null;
+  if (rest.length === 1) {
+    const adj = lookupAdjective(lexicon, rest[0]);
+    if (adj) return adjectiveCopula("adjective", np1, adj);
+  }
+  const np2 = resolveNP(lexicon, rest);
+  if (np1.term == null || np2.term == null) {
+    return missOrNull(np1.individual ? "typeAssertion" : "subClassOf", [np1, np2]);
+  }
+  if (np2.individual) return null; // "chat.mjs is sessions.mjs" — identity is not in the fragment
+  if (np1.individual) {
+    return hit("typeAssertion", [np1, np2], [
+      { subject: np1.term, predicate: "rdf:type", object: np2.term, kind: "rdf:type" },
+    ]);
+  }
+  return hit("subClassOf", [np1, np2], [
+    { subject: np1.term, predicate: "rdfs:subClassOf", object: np2.term, kind: "rdfs:subClassOf" },
+  ]);
+}
+
+/** Parse one sentence against the 8-pattern ACE-OWL sub-fragment. See the file
+ *  header for the result contract; `lexicon` defaults to the committed core. */
+export function parseAce(sentence, lexicon = loadLexicon()) {
+  const toks = tokenize(sentence);
+  if (toks.length < 3) return null;
+  const lower = toks.map((t) => t.toLowerCase());
+  if (lower[0] === "every") return parseEvery(lexicon, toks, lower);
+  if (lower[0] === "no") return parseDisjoint(lexicon, toks, lower);
+  if (/'s$/.test(lower[0]) && lower[0].length > 2) return parsePossessive(lexicon, toks, lower);
+  if (lower[0] === "the" && lower.includes("of") && lower.includes("is")) {
+    return parseOfForm(lexicon, toks, lower);
+  }
+  const isIdx = lower.indexOf("is");
+  if (isIdx > 0) return parseCopula(lexicon, toks, lower, isIdx);
+  return parseRelation(lexicon, toks, lower);
+}

package/src/grammar/assert.mjs

@@ -0,0 +1,40 @@
+// grammar/assert.mjs — the grammar→memory bridge: parseAce a sentence and land
+// every emitted triple in tmct's OWN memory graph via memory/core.mjs's
+// appendFact (ROADMAP Phase 2 item 2 meeting Phase 1 item 9).
+//
+// appendFact normalizes each triple's subject/object through normFactTerm
+// (tmct:Legacy-module → "legacy-module"; the predicate keeps its vocabulary
+// casing) and content-addresses the fact id — so re-asserting the same
+// sentence upserts, never duplicates, and different writers (chat, corpus)
+// converge on the same stored term spelling. Provenance is a compact tag
+// ("ace:chat:<sessionId>@<ts>"); core.mjs unions tags "|"-joined when several
+// writers assert the same fact.
+
+import { appendFact } from "../memory/core.mjs";
+import { parseAce } from "./ace.mjs";
+import { loadLexicon } from "./lexicon.mjs";
+
+/** Render a provenance descriptor {source, sessionId?, ts?} as the stored tag.
+ *  Deterministic, compact, greppable: ace:chat:0189…abcd@2026-07-04T10:00:00Z */
+export function provenanceTag({ source = "chat", sessionId = "", ts = "" } = {}) {
+  return `ace:${source}${sessionId ? `:${sessionId}` : ""}${ts ? `@${ts}` : ""}`;
+}
+
+/** Parse `sentence` against the ACE-OWL sub-fragment and append every emitted
+ *  triple to the memory graph under `dir`. Returns the parse result extended
+ *  with `ids` (one fact id per triple, same order) and the provenance tag —
+ *  or null (grammar miss, nothing written), or the residue parse (unknown
+ *  words: triples empty, ids empty, nothing written). */
+export async function assertSentence(dir, sentence, { lexicon, provenance } = {}) {
+  const parse = parseAce(sentence, lexicon ?? loadLexicon());
+  if (!parse) return null;
+  const tag = provenanceTag(provenance);
+  const ids = [];
+  for (const t of parse.triples) {
+    const { id } = await appendFact(dir, {
+      subject: t.subject, predicate: t.predicate, object: t.object, provenance: tag,
+    });
+    ids.push(id);
+  }
+  return { ...parse, ids, provenance: tag };
+}