session-orchestrator 3.16.0

package/scripts/lib/vault-mirror/pseudonym-map.mjs

@@ -0,0 +1,164 @@
+/**
+ * pseudonym-map.mjs — Host-local repo-namespace pseudonym map (Epic #725 D5).
+ *
+ * vault-mirror namespaces every write under a per-repo subdirectory (#660). For
+ * owner-leaky repo identifiers (personal home path / private project slug /
+ * personal name), `resolveRepoNamespace()` used to collapse ALL of them to a
+ * single `redacted-repo/` subdir — which breaks the #660 write-isolation (N
+ * private repos share one dir → id/slug collisions) and destroys cross-repo
+ * attribution.
+ *
+ * This module loads a HOST-LOCAL map that assigns each real repo slug a stable
+ * pseudonym. The real names live in a file referenced by owner.yaml
+ * (`paths.namespace-map-path`, env `SO_NAMESPACE_MAP`) OUTSIDE any repo, so they
+ * are never committed; only the stable, non-leaky pseudonyms reach the vault.
+ *
+ * Contract:
+ *   loadPseudonymMap({ mapPath, deps? }) → Map<string,string> | null
+ *
+ *   - `mapPath` empty/whitespace/non-string → null (no map configured; SILENT —
+ *     this is the default for the ~99% of hosts without a map).
+ *   - file missing / unreadable / malformed-JSON / non-object → null + one stderr WARN.
+ *   - Each entry's PSEUDONYM value is validated: it must be a filesystem-safe
+ *     kebab slug (isValidSlug) AND must NOT itself be owner-leaky
+ *     (isOwnerLeakySegment). Entries failing either check are dropped with an
+ *     aggregate WARN (real keys / rejected values are NOT logged — logging them
+ *     would defeat the privacy guarantee).
+ *   - Result is CACHED per process, keyed by mapPath (the mirror loop calls this
+ *     once per record — the file is read+parsed at most once per path).
+ *
+ * Privacy: this module never writes the map anywhere; it only reads the operator's
+ * host-local file. WARN messages carry the map PATH (the operator's own config
+ * path, shown transiently on their terminal) but never the real slugs or rejected
+ * pseudonym values.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { isValidSlug } from './utils.mjs';
+import { isOwnerLeakySegment } from '../validate/check-owner-leakage.mjs';
+
+/** Per-process cache: mapPath → (Map<string,string> | null). */
+const _cache = new Map();
+
+/**
+ * Clear the per-process pseudonym-map cache. Test-only seam — production code
+ * never needs to reset (the map file does not change mid-process).
+ */
+export function _resetPseudonymMapCache() {
+  _cache.clear();
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** Default (production) dependency bindings — overridable per call for tests. */
+const DEFAULT_DEPS = {
+  readFileSync,
+  existsSync,
+  isLeaky: isOwnerLeakySegment,
+  warn: (msg) => process.stderr.write(msg),
+};
+
+/**
+ * Parse + validate the raw JSON map body into a Map of real-slug → pseudonym.
+ * Returns null when the body is malformed or yields zero usable entries.
+ *
+ * @param {string} raw
+ * @param {string} mapPath
+ * @param {{ isLeaky: (v: string) => (string|null), warn: (msg: string) => void }} d
+ * @returns {Map<string,string>|null}
+ */
+function parseMap(raw, mapPath, d) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    d.warn(
+      `WARN vault-mirror/pseudonym-map: malformed JSON in namespace map ${mapPath}: ${err.message}; ignoring the map (owner-leaky repos fall back to 'redacted-repo')\n`,
+    );
+    return null;
+  }
+
+  if (!isPlainObject(parsed)) {
+    d.warn(
+      `WARN vault-mirror/pseudonym-map: namespace map ${mapPath} must be a JSON object of {"real-slug":"pseudonym-slug"}; ignoring the map\n`,
+    );
+    return null;
+  }
+
+  const map = new Map();
+  let ignoredInvalid = 0;
+  let ignoredLeaky = 0;
+
+  for (const [real, pseudo] of Object.entries(parsed)) {
+    // JSON object keys are always strings; guard against an empty key anyway.
+    if (typeof real !== 'string' || real.trim() === '') {
+      ignoredInvalid += 1;
+      continue;
+    }
+    if (typeof pseudo !== 'string' || !isValidSlug(pseudo)) {
+      ignoredInvalid += 1;
+      continue;
+    }
+    // A pseudonym that is ITSELF owner-leaky would re-introduce the very leak the
+    // map exists to prevent. Drop it — the repo falls back to 'redacted-repo'.
+    if (d.isLeaky(pseudo) !== null) {
+      ignoredLeaky += 1;
+      continue;
+    }
+    map.set(real, pseudo);
+  }
+
+  if (ignoredInvalid > 0 || ignoredLeaky > 0) {
+    // Deliberately omit the offending keys/values — logging them would leak the
+    // private slugs the map is meant to keep host-local.
+    d.warn(
+      `WARN vault-mirror/pseudonym-map: ignored ${ignoredInvalid} invalid-slug and ${ignoredLeaky} owner-leaky pseudonym mapping(s) in ${mapPath}\n`,
+    );
+  }
+
+  return map.size > 0 ? map : null;
+}
+
+/**
+ * Load and validate the host-local pseudonym map. Defensive — never throws.
+ *
+ * @param {object} opts
+ * @param {string|null|undefined} opts.mapPath - absolute path to the map JSON, or
+ *   empty/absent when no map is configured.
+ * @param {Partial<typeof DEFAULT_DEPS>} [opts.deps] - injected fs / leak-check / warn (tests).
+ * @returns {Map<string,string>|null} the validated map, or null when unconfigured/unusable.
+ */
+export function loadPseudonymMap({ mapPath, deps = {} } = {}) {
+  const d = { ...DEFAULT_DEPS, ...deps };
+
+  // Unconfigured → no map, no noise. This is the normal case for public repos and
+  // for any host that has not opted into pseudonym mapping.
+  if (typeof mapPath !== 'string' || mapPath.trim() === '') {
+    return null;
+  }
+
+  if (_cache.has(mapPath)) {
+    return _cache.get(mapPath);
+  }
+
+  let result = null; // default when the file is missing/unreadable/unusable
+  try {
+    if (!d.existsSync(mapPath)) {
+      d.warn(
+        `WARN vault-mirror/pseudonym-map: namespace-map-path is set but the file does not exist: ${mapPath}; owner-leaky repos fall back to 'redacted-repo'\n`,
+      );
+    } else {
+      const raw = d.readFileSync(mapPath, 'utf8');
+      result = parseMap(raw, mapPath, d);
+    }
+  } catch (err) {
+    d.warn(
+      `WARN vault-mirror/pseudonym-map: failed to read namespace map at ${mapPath}: ${err.message}; ignoring the map\n`,
+    );
+  }
+
+  _cache.set(mapPath, result);
+  return result;
+}

package/scripts/lib/vault-mirror/render-learnings.mjs

@@ -0,0 +1,201 @@
+/**
+ * render-learnings.mjs — Learning markdown generators for vault-mirror (Issue #283 split).
+ *
+ * Exports: detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2
+ */
+
+import { toDate, truncateAtWord, yamlQuoteIfNeeded, subjectToSlug, isValidSlug, buildTag, resolveSourceSessionLink } from './utils.mjs';
+
+const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
+
+/**
+ * Learning JSONL has two producer schemas in production:
+ *   v1 (legacy): id, type, subject, insight, evidence, confidence, source_session, created_at, expires_at?
+ *   v2 (S69+):   id, type, text, scope, confidence, first_seen, decay?
+ * Detect by presence of the v2-only field 'text'.
+ */
+export function detectLearningSchema(entry) {
+  return entry && typeof entry.text === 'string' ? 'v2' : 'v1';
+}
+
+const firstString = (...vals) => vals.find((v) => typeof v === 'string' && v.length > 0);
+
+const joinList = (v) =>
+  Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string') ? v.join(', ') : undefined;
+
+/**
+ * Map known producer alias fields onto the canonical v1 shape (#635).
+ *
+ * Newer producers (evolve consolidation, memory-propose, dialectic) emit
+ * field families the v1 validator rejects — summary/detail, description/rationale,
+ * title/body/how_to_apply, content, narrative, name — causing up to 44% of
+ * learnings to be skipped-invalid at mirror time. Rather than one generator per
+ * producer family, this pure function fills MISSING canonical fields from their
+ * aliases and leaves canonical v1/v2 entries byte-identical (pass-through).
+ *
+ * Returns a new object; never mutates the input. Entries that lack any insight
+ * source remain incomplete and still fail validation (intentional — content-free
+ * records should stay skipped-invalid).
+ */
+export function normalizeLearningEntry(entry) {
+  if (!entry || typeof entry !== 'object') return entry;
+  if (typeof entry.text === 'string') return entry; // v2 — canonical, untouched
+  const e = { ...entry };
+
+  if (!firstString(e.insight)) {
+    e.insight = firstString(e.detail, e.rationale, e.body, e.narrative, e.content, e.how_to_apply);
+  }
+  if (!firstString(e.subject)) {
+    e.subject = firstString(e.summary, e.title, e.name);
+  }
+  // `description` is ambiguous: insight-like next to name/title, subject-like
+  // next to rationale/detail. Assign it to whichever slot is still empty.
+  if (!firstString(e.insight)) e.insight = firstString(e.description);
+  else if (!firstString(e.subject)) e.subject = firstString(e.description);
+  if (!firstString(e.subject) && firstString(e.insight)) {
+    e.subject = truncateAtWord(e.insight, 80);
+  }
+
+  if (e.evidence === null || e.evidence === undefined || e.evidence === '') {
+    e.evidence = joinList(e.evidence_sessions) ?? joinList(e.files) ?? joinList(e.sessions) ?? '(none recorded)';
+  }
+  if (e.id === null || e.id === undefined) {
+    // subjectToSlug strips whitespace without hyphenating (designed for
+    // kebab-ish inputs) — pre-map whitespace to hyphens for prose subjects.
+    const derived = firstString(e.subject) ? subjectToSlug(e.subject.trim().replace(/\s+/g, '-')) : '';
+    if (isValidSlug(derived)) e.id = derived;
+  }
+  if (e.source_session === null || e.source_session === undefined) {
+    e.source_session =
+      firstString(e.session_id, Array.isArray(e.sessions) ? e.sessions[0] : undefined, e._provenance) ?? 'unknown';
+  }
+  if (e.created_at === null || e.created_at === undefined) {
+    e.created_at = firstString(e.first_seen, e.last_seen, e.updated_at);
+  }
+  if (e.type === null || e.type === undefined) e.type = 'general';
+
+  return e;
+}
+
+export function generateLearningNote(entry, slug, opts = {}) {
+  const REQUIRED_LEARNING_FIELDS = ['id', 'type', 'subject', 'insight', 'evidence', 'confidence', 'source_session', 'created_at'];
+  for (const field of REQUIRED_LEARNING_FIELDS) {
+    if (entry[field] === null || entry[field] === undefined) {
+      throw new Error(`vault-mirror: learning entry missing required field '${field}' (id=${entry.id ?? '<no id>'})`);
+    }
+  }
+
+  const { id: _id, type, subject: _subject, insight, evidence, confidence, source_session, created_at, expires_at } = entry;
+
+  const status = confidence > 0.8 ? 'verified' : 'draft';
+  const created = toDate(created_at);
+  const updated = toDate(created_at);
+  const expires = toDate(expires_at);
+
+  const titleRaw = truncateAtWord(insight, 80);
+  const title = yamlQuoteIfNeeded(titleRaw);
+
+  // #602: type/status are interpolated raw upstream; route every tag segment
+  // through buildTag so each is kebab-slugified and capped at 64 chars. The
+  // existing source/<session> slug is preserved (buildTag is idempotent for an
+  // already-kebab value and adds the length cap).
+  const sourceTag = subjectToSlug(String(source_session)) || 'unknown';
+  const tags = `[${buildTag(['learning', type])}, ${buildTag(['status', status])}, ${buildTag(['source', sourceTag])}]`;
+
+  // Check if expires has a value; it's optional in schema
+  const expiresLine = expires ? `expires: ${expires}\n` : '';
+
+  // #725 D2: emit `source-repo` for cross-repo attribution when the caller
+  // (process.mjs) threads the resolved repo namespace through opts.repoNs. The
+  // value is already sanitised + leak-guarded by resolveRepoNamespace. Absent for
+  // older callers / unit tests → the line is omitted (backward-compatible; the
+  // vault-sync schema declares source-repo OPTIONAL).
+  const sourceRepoLine =
+    typeof opts.repoNs === 'string' && opts.repoNs.length > 0 ? `source-repo: ${opts.repoNs}\n` : '';
+
+  // source_session is emitted as an Obsidian wikilink ONLY when source_session
+  // resolves to a real, mirror-able session id (semantic or UUID-v4). Anything
+  // else — 'unknown', legacy timestamp ids without a trailing counter, provenance
+  // tags, etc. — is emitted as plain text to prevent dangling [[unknown]] /
+  // [[malformed]] links in the vault (Issue #704 bugs A + B). Tags are fed by
+  // sourceTag (L102 above) which is independent of this link decision.
+  const { isLink: _srcIsLink, target: _srcTarget } = resolveSourceSessionLink(source_session, { noteExists: opts.noteExists });
+  const sourceSessionLink = _srcIsLink ? `"[[${_srcTarget}]]"` : yamlQuoteIfNeeded(_srcTarget);
+  const sourceSessionBodyLink = _srcIsLink ? `[[${_srcTarget}]]` : _srcTarget;
+
+  return `---
+id: ${slug}
+type: learning
+title: ${title}
+status: ${status}
+created: ${created}
+updated: ${updated}
+tags: ${tags}
+source_session: ${sourceSessionLink}
+${expiresLine}${sourceRepoLine}_generator: ${GENERATOR_MARKER}
+---
+
+# ${titleRaw}
+
+- **Type:** ${type}
+- **Confidence:** ${confidence}
+- **Source session:** ${sourceSessionBodyLink}
+
+## Insight
+
+${insight}
+
+## Evidence
+
+${evidence}
+`;
+}
+
+export function generateLearningNoteV2(entry, slug, opts = {}) {
+  const REQUIRED_LEARNING_V2_FIELDS = ['id', 'type', 'text', 'scope', 'confidence', 'first_seen'];
+  for (const field of REQUIRED_LEARNING_V2_FIELDS) {
+    if (entry[field] === null || entry[field] === undefined) {
+      throw new Error(`vault-mirror: learning entry missing required field '${field}' (id=${entry.id ?? '<no id>'})`);
+    }
+  }
+
+  const { type, text, scope, confidence, first_seen } = entry;
+
+  const status = confidence > 0.8 ? 'verified' : 'draft';
+  const created = toDate(first_seen);
+  const updated = created;
+
+  const titleRaw = truncateAtWord(text, 80);
+  const title = yamlQuoteIfNeeded(titleRaw);
+
+  // #602: type/status interpolated raw upstream — slugify + cap each segment.
+  const scopeTag = subjectToSlug(scope) || 'unscoped';
+  const tags = `[${buildTag(['learning', type])}, ${buildTag(['status', status])}, ${buildTag(['scope', scopeTag])}]`;
+
+  // #725 D2: emit `source-repo` for cross-repo attribution when the caller threads
+  // opts.repoNs (see generateLearningNote for the full contract). Backward-compatible.
+  const sourceRepoLine =
+    typeof opts.repoNs === 'string' && opts.repoNs.length > 0 ? `source-repo: ${opts.repoNs}\n` : '';
+
+  return `---
+id: ${slug}
+type: learning
+title: ${title}
+status: ${status}
+created: ${created}
+updated: ${updated}
+tags: ${tags}
+${sourceRepoLine}_generator: ${GENERATOR_MARKER}
+---
+
+# ${titleRaw}
+
+- **Type:** ${type}
+- **Confidence:** ${confidence}
+- **Scope:** ${scope}
+
+## Insight
+
+${text}
+`;
+}