heyspex 0.1.0 → 0.2.0

package/spexharness/src/profile/proposals.mjs

@@ -0,0 +1,357 @@
+// spexharness/src/profile/proposals.mjs
+//
+// P6 (epic [[HS-HEBV-8CMW-EPIC-spexcode-profile-v0-learn-the-developer]], task
+// [[HS-B0JT-8CMW-TASK-p6-proposal-flow-learned-observations]]) — the accept/decline
+// gate in front of P1's profile file. A learned observation the P1 learner
+// (spexharness/src/profile/learn.mjs) would otherwise fold straight into the profile
+// instead starts life here as a `pending` proposal; only an explicit `accept()` turns
+// it into a real profile entry P4-style injection would ever read. A `decline()` is
+// remembered by a normalized-text fingerprint, so the same note (or a near-duplicate
+// of it) is never re-queued.
+//
+// Reuse, never duplicate: this module writes through to P1's OWN profile file and
+// incremental-state file via learn.mjs's exported `loadProfileState`/`saveProfileState`/
+// `classifySection`/`renderProfileMarkdown` — it never re-implements the section store or
+// the markdown renderer. It also drives the T15 arrow-key select prompt
+// (spexharness/src/chat/tui/select.mjs) rather than a typed y/n prompt, the same UI every
+// other high-stakes ask in this harness already uses.
+//
+// Ledger: `.heyspex/profile-proposals.jsonl` (machine-local, NEVER written to the vault
+// under `specs/` — same rule as the profile file itself). Append-only event log
+// (`queued`/`accepted`/`declined`), one JSON object per line; current state for any given
+// proposal id is the fold of its own events (latest wins), mirroring the shape DR1's
+// corpus.mjs already uses for an append-only, resumable log.
+//
+// Asking happens only at a turn boundary (turn end / session close) — never mid-stream,
+// never blocking the prompt — via `presentPendingProposal`/`createProposalPrompt`, which a
+// front wires into `spexharness/src/chat/chat-loop.mjs`'s optional `proposalPrompt` hook.
+// `listPending()` itself never conditions a seat's context: it only reads the ledger.
+
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { classifySection, loadProfileState, normalizeFingerprint, saveProfileState, renderProfileMarkdown } from './learn.mjs';
+import { select, SELECT_NEEDS_TTY } from '../chat/tui/select.mjs';
+
+// ── paths ─────────────────────────────────────────────────────────────────────────
+
+/** The proposal ledger's canonical, machine-local location. */
+export function defaultProposalsLedgerPath(repoRoot) {
+  return join(repoRoot, '.heyspex', 'profile-proposals.jsonl');
+}
+
+// ── fingerprinting (near-duplicate detection for declined proposals) ────────────────
+
+/**
+ * Normalize `text` into a stable, whitespace/punctuation-insensitive fingerprint — two
+ * observations that only differ by casing, punctuation, or extra whitespace normalize to
+ * the same string, so a decline blocks a near-duplicate re-queue, not just an exact repeat.
+ *
+ * Defined in ./learn.mjs and re-exported here (this module's long-standing public name for
+ * it). learn.mjs's own `dedupeSection` uses the SAME function, so "already in the profile"
+ * and "already proposed" can never drift apart.
+ */
+export { normalizeFingerprint };
+
+function proposalIdForObservation(observation) {
+  if (observation && typeof observation.id === 'string' && observation.id.trim()) return observation.id.trim();
+  return `fp:${normalizeFingerprint(observation?.text)}`;
+}
+
+// ── ledger I/O ────────────────────────────────────────────────────────────────────
+
+/** Read every event from the ledger, oldest first. Missing file -> []. Corrupt lines skipped. */
+export function readLedgerEvents(ledgerPath) {
+  if (!existsSync(ledgerPath)) return [];
+  const text = readFileSync(ledgerPath, 'utf8');
+  const out = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      out.push(JSON.parse(trimmed));
+    } catch {
+      // corrupt/partial line — skip, don't throw
+    }
+  }
+  return out;
+}
+
+function appendLedgerEvent(ledgerPath, event) {
+  mkdirSync(dirname(ledgerPath), { recursive: true });
+  appendFileSync(ledgerPath, `${JSON.stringify(event)}\n`);
+}
+
+/**
+ * Fold the append-only ledger into current per-id state (the latest event for a given id
+ * wins) plus the full set of fingerprints any `declined` event has ever carried — a
+ * near-duplicate is blocked by matching ANY prior decline's fingerprint, not just the one
+ * belonging to the same id.
+ */
+function foldLedger(events) {
+  const byId = new Map();
+  const declinedFingerprints = new Set();
+  for (const ev of events) {
+    if (!ev || typeof ev.id !== 'string') continue;
+    const prior = byId.get(ev.id) ?? {};
+    byId.set(ev.id, { ...prior, ...ev });
+    if (ev.type === 'declined' && typeof ev.fingerprint === 'string') {
+      declinedFingerprints.add(ev.fingerprint);
+    }
+  }
+  return { byId, declinedFingerprints };
+}
+
+// ── queue / list ──────────────────────────────────────────────────────────────────
+
+/**
+ * Every proposal currently `pending`, oldest first. Pure read — never mutates the ledger,
+ * never touches the profile file or state. This is the ONE thing a seat's context
+ * injection must never read (P4-style injection reads only `accepted` profile entries).
+ *
+ * @param {{ ledgerPath: string }} opts
+ * @returns {Array<{ id: string, status: 'pending', fingerprint: string, queuedAt: string, observation: object }>}
+ */
+export function listPending({ ledgerPath }) {
+  const { byId } = foldLedger(readLedgerEvents(ledgerPath));
+  const out = [];
+  for (const proposal of byId.values()) {
+    if (proposal.status === 'pending') out.push(proposal);
+  }
+  out.sort((a, b) => String(a.queuedAt ?? '').localeCompare(String(b.queuedAt ?? '')));
+  return out;
+}
+
+/**
+ * Queue a candidate profile entry from the P1 learner as `pending` — it does NOT touch the
+ * profile file or condition anything until `accept()` is called. A repeat of the same
+ * observation id, or a near-duplicate (by fingerprint) of a previously DECLINED
+ * observation, is silently skipped rather than re-queued.
+ *
+ * @param {{ id?: string, text: string, source?: string, project?: string, session?: string,
+ *   ts?: string|null, kind?: string, supersedes?: object|null }} observation - the same
+ *   shape corpus.mjs's `readObservations` yields; `supersedes`, when present (P7's
+ *   contradiction-detection path), is carried through verbatim and interpreted only by the
+ *   caller — this module never inspects it.
+ * @param {{ ledgerPath: string, now?: () => string }} opts
+ * @returns {{ queued: boolean, id: string, reason?: string, fingerprint?: string, queuedAt?: string, status?: string }}
+ */
+export function queueProposal(observation, { ledgerPath, now = () => new Date().toISOString() } = {}) {
+  if (!ledgerPath) throw new Error('queueProposal: ledgerPath is required');
+  if (!observation || typeof observation.text !== 'string' || !observation.text.trim()) {
+    return { queued: false, id: '', reason: 'empty-observation' };
+  }
+
+  const id = proposalIdForObservation(observation);
+  const fingerprint = normalizeFingerprint(observation.text);
+  const { byId, declinedFingerprints } = foldLedger(readLedgerEvents(ledgerPath));
+
+  const existing = byId.get(id);
+  if (existing && (existing.status === 'pending' || existing.status === 'accepted')) {
+    return { queued: false, id, reason: 'already-queued', status: existing.status };
+  }
+  if (existing && existing.status === 'declined') {
+    return { queued: false, id, reason: 'declined-duplicate' };
+  }
+  if (declinedFingerprints.has(fingerprint)) {
+    return { queued: false, id, reason: 'declined-near-duplicate', fingerprint };
+  }
+
+  const queuedAt = now();
+  appendLedgerEvent(ledgerPath, {
+    type: 'queued',
+    id,
+    status: 'pending',
+    fingerprint,
+    queuedAt,
+    observation: {
+      id: observation.id ?? null,
+      text: observation.text,
+      source: observation.source ?? null,
+      project: observation.project ?? null,
+      session: observation.session ?? null,
+      ts: observation.ts ?? null,
+      kind: observation.kind ?? null,
+      supersedes: observation.supersedes ?? null,
+    },
+  });
+  return { queued: true, id, fingerprint, queuedAt, status: 'pending' };
+}
+
+function requirePendingProposal(ledgerPath, id) {
+  const { byId } = foldLedger(readLedgerEvents(ledgerPath));
+  const proposal = byId.get(id);
+  if (!proposal || proposal.status !== 'pending') return null;
+  return proposal;
+}
+
+// ── decide ────────────────────────────────────────────────────────────────────────
+
+/**
+ * Decline a pending proposal. Its fingerprint is remembered so the same observation, or a
+ * near-duplicate of it, is never re-queued by a later `queueProposal` call.
+ *
+ * @param {string} id
+ * @param {{ ledgerPath: string, now?: () => string }} opts
+ * @returns {{ ok: boolean, id: string, reason?: string, declinedAt?: string }}
+ */
+export function decline(id, { ledgerPath, now = () => new Date().toISOString() } = {}) {
+  if (!ledgerPath) throw new Error('decline: ledgerPath is required');
+  const proposal = requirePendingProposal(ledgerPath, id);
+  if (!proposal) return { ok: false, id, reason: 'not-pending' };
+
+  const declinedAt = now();
+  appendLedgerEvent(ledgerPath, {
+    type: 'declined',
+    id,
+    status: 'declined',
+    fingerprint: proposal.fingerprint,
+    declinedAt,
+  });
+  return { ok: true, id, declinedAt };
+}
+
+/**
+ * Accept a pending proposal — the ONLY path that turns a learned observation into a real
+ * profile entry. Writes through to P1's own profile file/state (`learn.mjs`'s
+ * `loadProfileState`/`saveProfileState`/`renderProfileMarkdown`), classifying the
+ * observation into a section exactly like `buildProfile` does, but with provenance
+ * (`accepted-at`, the source observation id) folded into the rendered line so an accepted
+ * entry is traceable back to the proposal that produced it.
+ *
+ * @param {string} id
+ * @param {{ ledgerPath: string, profilePath: string, profileStatePath: string, now?: () => string }} opts
+ * @returns {{ ok: boolean, id: string, reason?: string, acceptedAt?: string, section?: string, profilePath?: string, markdown?: string }}
+ */
+export function accept(id, { ledgerPath, profilePath, profileStatePath, now = () => new Date().toISOString() } = {}) {
+  if (!ledgerPath) throw new Error('accept: ledgerPath is required');
+  if (!profilePath) throw new Error('accept: profilePath is required');
+  if (!profileStatePath) throw new Error('accept: profileStatePath is required');
+
+  const proposal = requirePendingProposal(ledgerPath, id);
+  if (!proposal) return { ok: false, id, reason: 'not-pending' };
+
+  const acceptedAt = now();
+  const observation = proposal.observation ?? {};
+  const key = classifySection({ kind: observation.kind, text: observation.text });
+
+  const state = loadProfileState(profileStatePath);
+  const sourceObservationId = observation.id ?? id;
+  const provenanceText = `${observation.text} _(accepted: ${acceptedAt}, from proposal: ${id}, source observation: ${sourceObservationId})_`;
+  state.sections[key].push({
+    text: provenanceText,
+    source: observation.source ?? 'unknown',
+    project: observation.project ?? 'unknown',
+    session: observation.session ?? 'unknown',
+    ts: observation.ts ?? null,
+  });
+  state.lastLearnedAt = acceptedAt;
+
+  const markdown = renderProfileMarkdown(state.sections);
+  mkdirSync(dirname(profilePath), { recursive: true });
+  writeFileSync(profilePath, markdown);
+  saveProfileState(profileStatePath, state);
+
+  appendLedgerEvent(ledgerPath, {
+    type: 'accepted',
+    id,
+    status: 'accepted',
+    fingerprint: proposal.fingerprint,
+    acceptedAt,
+    sourceObservationId,
+  });
+
+  return { ok: true, id, acceptedAt, section: key, profilePath, markdown };
+}
+
+// ── turn-boundary prompt (T15 arrow-key select) ─────────────────────────────────────
+
+/**
+ * Present the oldest pending proposal (if any) via the T15 arrow-key select prompt and act
+ * on the developer's choice. Never called mid-stream — a caller wires this into a turn
+ * boundary (turn end / session close) only, same rule as the folder-trust/tool-permission
+ * asks already follow. On a non-TTY `stdin` (a script/headless run), this resolves with
+ * `{ presented: false, reason: 'no-tty' }` instead of throwing — a proposal prompt must
+ * never be the reason a non-interactive run breaks.
+ *
+ * @param {{ ledgerPath: string, profilePath: string, profileStatePath: string,
+ *   stdin?: NodeJS.ReadStream, stdout?: { write: Function }, selectFn?: typeof select,
+ *   now?: () => string }} opts
+ * @returns {Promise<{ presented: boolean, reason?: string, decision?: string, id?: string, result?: object }>}
+ */
+export async function presentPendingProposal({
+  ledgerPath,
+  profilePath,
+  profileStatePath,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  selectFn = select,
+  now,
+} = {}) {
+  const pending = listPending({ ledgerPath });
+  if (pending.length === 0) return { presented: false, reason: 'no-pending' };
+
+  const proposal = pending[0];
+  const obs = proposal.observation ?? {};
+
+  let choice;
+  try {
+    choice = await selectFn({
+      title: 'SpexCode noticed a new habit — add it to your SpexCode Profile?',
+      lines: [
+        obs.text ?? '',
+        `_(source: ${obs.source ?? 'unknown'}, project: ${obs.project ?? 'unknown'}, session: ${obs.session ?? 'unknown'})_`,
+      ],
+      options: [
+        { key: 'accept', label: 'Accept — add to my SpexCode Profile' },
+        { key: 'decline', label: "Decline — don't ask about this again" },
+        { key: 'later', label: 'Ask me later' },
+      ],
+      footer: '↑/↓ to navigate · enter to select · esc to skip for now',
+      stdin,
+      stdout,
+    });
+  } catch (err) {
+    if (err && (err.code === SELECT_NEEDS_TTY || err.message === SELECT_NEEDS_TTY)) {
+      return { presented: false, reason: 'no-tty' };
+    }
+    throw err;
+  }
+
+  if (choice === 'accept') {
+    const result = accept(proposal.id, { ledgerPath, profilePath, profileStatePath, now });
+    return { presented: true, decision: 'accept', id: proposal.id, result };
+  }
+  if (choice === 'decline') {
+    const result = decline(proposal.id, { ledgerPath, now });
+    return { presented: true, decision: 'decline', id: proposal.id, result };
+  }
+  // Escape (null) or 'later' — leave it pending, ask again another turn.
+  return { presented: true, decision: choice ?? 'later', id: proposal.id };
+}
+
+/**
+ * Bind `presentPendingProposal`'s options once and hand back a zero-arg-friendly hook
+ * shaped for `spexharness/src/chat/chat-loop.mjs`'s optional `proposalPrompt` — called
+ * (awaited) at a turn boundary only.
+ *
+ * @param {Parameters<typeof presentPendingProposal>[0]} opts
+ * @returns {() => Promise<ReturnType<typeof presentPendingProposal>>}
+ */
+export function createProposalPrompt(opts = {}) {
+  return function proposalPrompt() {
+    return presentPendingProposal(opts);
+  };
+}
+
+export default {
+  defaultProposalsLedgerPath,
+  normalizeFingerprint,
+  readLedgerEvents,
+  listPending,
+  queueProposal,
+  decline,
+  accept,
+  presentPendingProposal,
+  createProposalPrompt,
+};