@dreamforgestudiollc/emet 0.0.0-stage → 0.2.4

package/src/metadata.js

@@ -0,0 +1,61 @@
+/**
+ * EMET - Enduring Memory & Epistemic Tiers
+ * Copyright (c) 2026 Dreamforge Studio LLC
+ *
+ * Licensed under the MIT License - see LICENSE
+ *
+ * metadata: ONE place that knows the field has had two shapes.
+ *
+ * Until 2026-09-05 every layer entry stored `metadata` as a JSON STRING. Mongo
+ * cannot see inside a string, so nothing in it was queryable or indexable -
+ * `metadata.superseded_by` matched zero documents (probe, 2026-08-24). Two
+ * fields that bit in practice, superseded_by and valid_until, were promoted to
+ * top-level columns as a targeted fix; the provenance pointer was written
+ * top-level from the start for the same reason. That fixed instances. This
+ * fixes the class: metadata is now stored as a real subdocument, and the
+ * corpus was migrated (scripts/migrate_metadata_to_subdocument.mjs).
+ *
+ * Readers still go through parseMetadata() rather than trusting the shape,
+ * because a store that was never migrated - or one document a migration
+ * skipped - must read correctly rather than throw. Tolerance on read is what
+ * makes the write-side change safe to ship ahead of the migration.
+ */
+
+/**
+ * Return metadata as an object whatever shape it was stored in.
+ * - object  -> returned as-is
+ * - string  -> JSON.parse; an unparseable string yields {} (the read must not
+ *              throw over one bad row, and nothing is lost - the row is untouched)
+ * - null / undefined / anything else -> {}
+ */
+export function parseMetadata(value) {
+  if (value === null || value === undefined) return {};
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  if (typeof value === 'object' && !Array.isArray(value)) return value;
+  return {};
+}
+
+/** True when a stored metadata value is the pre-2026-09-05 JSON-string shape. */
+export function isLegacyMetadataString(value) {
+  return typeof value === 'string';
+}
+
+/**
+ * Is this a column the SQL dialect may translate? Top-level columns come from
+ * the caller's whitelist; metadata sub-paths are allowed because the field is a
+ * subdocument now, provided the path is plain identifier segments - no operators,
+ * no `$`, nothing that could be read by Mongo as anything but a field path.
+ */
+const METADATA_PATH = /^metadata(\.[A-Za-z_][A-Za-z0-9_]*)+$/;
+export function isMetadataPath(col) {
+  return typeof col === 'string' && METADATA_PATH.test(col);
+}
+
+export default { parseMetadata, isLegacyMetadataString, isMetadataPath };

package/src/module-path.js

@@ -0,0 +1,32 @@
+/**
+ * EMET - Enduring Memory & Epistemic Tiers
+ * Copyright (c) 2026 Dreamforge Studio LLC
+ *
+ * Licensed under the MIT License - see LICENSE
+ *
+ * A module URL is not a filesystem path. On Windows, `new URL(href).pathname`
+ * is `/C:/...`. `path.resolve` against a working directory on `C:` then joins
+ * that into `C:\C:\...`, and opening the file fails. `fileURLToPath` decodes
+ * the URL first; `path.resolve` walks from that path's directory.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Absolute path of a file URL, then any relative segments. A leading `..`
+ * leaves the module's own directory.
+ *
+ * `opts.path` and `opts.toPath` exist so a test can pass `path.win32` and a
+ * Windows `fileURLToPath` without running on Windows. Production callers omit
+ * them and get the host path module.
+ *
+ * @param {string|URL} fileUrl
+ * @param {string[]} [segments]
+ * @param {{ path?: typeof path, toPath?: (url: string|URL) => string }} [opts]
+ */
+export function resolveModulePath(fileUrl, segments = [], opts = {}) {
+  const pathImpl = opts.path || path;
+  const toPath = opts.toPath || fileURLToPath;
+  return pathImpl.resolve(pathImpl.dirname(toPath(fileUrl)), ...segments);
+}

package/src/mongo-connect.js

@@ -0,0 +1,48 @@
+/**
+ * EMET - the one way to open a MongoDB connection (2026-09-29).
+ *
+ * Some local resolvers (home routers, VPN DNS) refuse
+ * the SRV queries a mongodb+srv:// URI needs, and the driver fails with
+ * "querySrv ECONNREFUSED". Until today the public-DNS fallback lived only in
+ * EmetDatabase.ensureClient; nine other connections in src/ and
+ * scripts/chain-verify.mjs opened their own client without it, so every tool
+ * behind them failed on a machine with such a resolver while the layer tools
+ * worked. One helper, used everywhere, so the fallback cannot be forgotten in
+ * a tenth place.
+ *
+ * On a querySrv failure: switch this process to public DNS (8.8.8.8, 1.1.1.1)
+ * and retry once. dns.setServers is process-wide, so every later connection
+ * in the same process resolves first time. Any other failure is rethrown as
+ * it came.
+ */
+
+import dns from 'dns';
+import { MongoClient } from 'mongodb';
+
+export const PUBLIC_DNS = Object.freeze(['8.8.8.8', '1.1.1.1']);
+
+export function isSrvRefusal(error) {
+  return /querySrv/i.test(String(error && error.message));
+}
+
+/**
+ * Test seam (2026-10-01): the suites install an in-memory client so a tool
+ * that connects for itself (emet_transcript_append) can be run end to end
+ * with no database. Never set outside tests; null means the real driver.
+ */
+let testClient = null;
+export function useTestClient(Client) { testClient = Client || null; }
+export function testClientActive() { return testClient != null; }
+
+/** Connect and return the client. `onFallback(message)` is told when the retry happens. */
+export async function connectMongo(uri, options = {}, { onFallback = null, _Client = testClient || MongoClient, _dns = dns } = {}) {
+  const attempt = async () => { const c = new _Client(uri, options); await c.connect(); return c; };
+  try {
+    return await attempt();
+  } catch (error) {
+    if (!isSrvRefusal(error)) throw error;
+    if (onFallback) onFallback(`SRV DNS lookup refused by the local resolver - retrying with public DNS (${PUBLIC_DNS.join(', ')})`);
+    _dns.setServers([...PUBLIC_DNS]);
+    return await attempt();
+  }
+}

package/src/named-items.js

@@ -0,0 +1,208 @@
+/**
+ * Names the board and handoff already hold, so a session start can say them.
+ *
+ * The board template keeps half-finished work in §1, dates in §2, and open,
+ * waiting, and parked rows in §3. The handoff keeps what was left undecided.
+ * A section that is not a table is marked unread. An empty list is not a
+ * claim that the document has nothing in it.
+ */
+
+function isPlaceholder(s) {
+  const t = String(s || '').trim();
+  if (!t || t === '__' || /^_+$/.test(t)) return true;
+  if (/^none\b/i.test(t)) return true;
+  return false;
+}
+
+function tableCells(line) {
+  return String(line).trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+}
+
+function isSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((c) => /^:?-{3,}:?$/.test(c));
+}
+
+function sectionBodies(text) {
+  const sections = new Map();
+  let key = null;
+  const buf = [];
+  const flush = () => {
+    if (key) sections.set(key, buf.join('\n'));
+    buf.length = 0;
+  };
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const m = line.match(/^##\s+§(\d+)\b/);
+    if (m) { flush(); key = m[1]; }
+    else if (key) buf.push(line);
+  }
+  flush();
+  return sections;
+}
+
+function firstTable(sectionText) {
+  const lines = String(sectionText || '').split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim().startsWith('|'));
+  if (start < 0) return null;
+  const raw = [];
+  for (let i = start; i < lines.length; i++) {
+    if (!lines[i].trim().startsWith('|')) break;
+    raw.push(lines[i]);
+  }
+  if (!raw.length) return null;
+  const header = tableCells(raw[0]).map((h) => h.toLowerCase());
+  const data = [];
+  for (const line of raw.slice(1)) {
+    const cells = tableCells(line);
+    if (isSeparatorRow(cells)) continue;
+    data.push(cells);
+  }
+  return { header, data };
+}
+
+function colIndex(header, names) {
+  return header.findIndex((h) => names.some((n) => h === n || h.startsWith(n)));
+}
+
+function cell(row, header, names) {
+  const i = colIndex(header, names);
+  return i >= 0 ? (row[i] || '').trim() : '';
+}
+
+function nameOf(header, row) {
+  const named = cell(row, header, ['what', 'item']);
+  if (named) return named;
+  const i = header.findIndex((h, idx) => h !== 'id' && !isPlaceholder(row[idx]));
+  return i >= 0 ? (row[i] || '').trim() : '';
+}
+
+function addDaysIso(iso, n) {
+  const [y, m, d] = String(iso).split('-').map(Number);
+  if (!y || !m || !d) return null;
+  const dt = new Date(Date.UTC(y, m - 1, d));
+  dt.setUTCDate(dt.getUTCDate() + n);
+  return dt.toISOString().slice(0, 10);
+}
+
+function isoDateIn(text) {
+  const m = String(text || '').match(/\d{4}-\d{2}-\d{2}/);
+  return m ? m[0] : null;
+}
+
+function resumesWhen(statusRaw) {
+  const m = String(statusRaw || '').match(/resumes when:\s*(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+
+function takeSection(board, sections, num, label, out) {
+  if (typeof board !== 'string') {
+    out.sections[label] = 'unread';
+    return null;
+  }
+  if (!sections.has(num)) {
+    out.sections[label] = 'unread';
+    return null;
+  }
+  const table = firstTable(sections.get(num));
+  // Prose is not a table the server could read. unread is not an empty list:
+  // the session still has to read the document.
+  out.sections[label] = table ? 'read' : 'unread';
+  return table;
+}
+
+export function undecidedFrom(text) {
+  if (typeof text !== 'string') return { section: 'unread', lines: [] };
+  const m = text.match(/\*\*Left undecided this session:\*\*([^\n]*)((?:\n(?!-\s+\*\*|##\s).*)*)/i);
+  if (!m) return { section: 'unread', lines: [] };
+  const lines = [];
+  const push = (s) => {
+    const t = String(s || '').trim().replace(/^[-*]\s+/, '').replace(/^:\s*/, '').trim();
+    if (!t || isPlaceholder(t)) return;
+    if (/one line each/i.test(t) || /^drafts, proposals/i.test(t)) return;
+    lines.push(t);
+  };
+  push(m[1]);
+  for (const line of m[2].split('\n')) push(line);
+  return { section: 'read', lines };
+}
+
+/**
+ * @param {string|null|undefined} board
+ * @param {string|null|undefined} handoff
+ * @param {string} today  YYYY-MM-DD
+ * @param {{ board_doc?: string, handoff_doc?: string }} [ids]
+ */
+export function namedItemsFrom(board, handoff, today, ids = {}) {
+  const day = typeof today === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(today)
+    ? today
+    : new Date().toISOString().slice(0, 10);
+  const end = addDaysIso(day, 7);
+  const out = {
+    board_doc: ids.board_doc || 'STATE.md',
+    handoff_doc: ids.handoff_doc || 'HANDOFF.md',
+    board_read: typeof board === 'string',
+    handoff_read: typeof handoff === 'string',
+    as_of: day,
+    half_finished: [],
+    dated: [],
+    open: [],
+    waiting: [],
+    parked: [],
+    undecided: [],
+    sections: {},
+    note: 'Say every name in this list. Parked names are their own list: say what brings each one back, and ask nothing of it. A section marked unread was not a table the server could read, so read that document and name what it holds. An empty list is not a reason to skip the document. Then name lessons_pending. A count never replaces the names.'
+  };
+  const sections = sectionBodies(board);
+  const half = takeSection(board, sections, '1', 'half_finished', out);
+  if (half) {
+    for (const row of half.data) {
+      const name = nameOf(half.header, row);
+      if (isPlaceholder(name)) continue;
+      out.half_finished.push({
+        name,
+        state: cell(row, half.header, ['state']) || null,
+        next_action: cell(row, half.header, ['next action']) || null,
+        id: cell(row, half.header, ['id']) || null
+      });
+    }
+  }
+  const dated = takeSection(board, sections, '2', 'dated', out);
+  if (dated) {
+    for (const row of dated.data) {
+      const item = nameOf(dated.header, row);
+      const dateRaw = cell(row, dated.header, ['date']);
+      if (isPlaceholder(item) && isPlaceholder(dateRaw)) continue;
+      const date = isoDateIn(dateRaw);
+      out.dated.push({
+        date: date || (isPlaceholder(dateRaw) ? null : dateRaw) || null,
+        name: isPlaceholder(item) ? null : item,
+        owner: cell(row, dated.header, ['owner']) || null,
+        id: cell(row, dated.header, ['id']) || null,
+        within_seven_days: date && end ? date >= day && date <= end : null
+      });
+    }
+  }
+  const open = takeSection(board, sections, '3', 'open', out);
+  if (open) {
+    for (const row of open.data) {
+      const name = nameOf(open.header, row);
+      if (isPlaceholder(name)) continue;
+      const statusRaw = cell(row, open.header, ['status']);
+      const status = (statusRaw || 'OPEN').toUpperCase();
+      const entry = {
+        name,
+        status: status.split(/\s+/)[0],
+        next_action: cell(row, open.header, ['next action']) || null,
+        owner: cell(row, open.header, ['owner']) || null,
+        id: cell(row, open.header, ['id']) || null,
+        resumes_when: cell(row, open.header, ['resumes when']) || resumesWhen(statusRaw) || null
+      };
+      if (status.startsWith('PARKED')) out.parked.push(entry);
+      else if (status.startsWith('WAITING')) out.waiting.push(entry);
+      else out.open.push(entry);
+    }
+  }
+  const und = undecidedFrom(handoff);
+  out.sections.undecided = und.section;
+  out.undecided = und.lines;
+  return out;
+}