@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/research/store/index.mjs

@@ -0,0 +1,312 @@
+// Session store — the WRITE CHOKEPOINT (tooling standard §7).
+//
+// Every filesystem mutation for session state (mkdir, writeFile, rm) lives in
+// this module and nowhere else. Validators are pure; commands read via the
+// helpers here but never call fs.writeFile directly. There is deliberately no
+// "write arbitrary path" API — callers write whole, validated session artifacts.
+//
+// Reads MAY fan out (tooling standard §7: "Reads may be scattered; writes may
+// not"), but for convenience the common reads live here too since path
+// resolution does.
+//
+// Error → exit-code mapping (translated to process.exit only in cli.mjs):
+//   session/file not found         → 2 (operational)
+//   malformed JSON / failed schema → 2 (from the validators)
+//   disk read/write/mkdir/rm error → 3 (transport/IO)
+
+import { mkdir, writeFile, readFile, readdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { getRepoRoot } from '../../pa/repo-root.mjs';
+import { validateManifest, loadManifest } from './manifest.mjs';
+import { validatePlan, loadPlan } from './plan.mjs';
+import { validateSources, loadSources } from './sources.mjs';
+import { validateGates, loadGates } from './gates.mjs';
+import { validateFinding, loadFinding } from './findings.mjs';
+
+// Where session directories live inside the operator repo. Historical shape:
+// when the tool sat at `operator/extensions/tools/research/`, sessions were
+// `<that dir>/sessions/`. After promotion into `@stravica-ai/digital-operator-pa`, the
+// package can no longer host runtime state — sessions must land in the
+// operator repo. `.cache/research/sessions/` matches the operational-artefact
+// convention (`.cache/distill/`, `.cache/estate-sync/`); already gitignore-friendly.
+export const SESSIONS_SUBPATH = '.cache/research/sessions';
+
+// Resolve the default sessions dir from the operator repo root. Async because
+// getRepoRoot walks upward for `.git` (or reads $DAVE_REPO_ROOT / $PA_REPO_ROOT).
+// Callers that already know the sessions dir (tests, alternative operators)
+// pass it into `makeStore(dir)` directly and never hit this.
+export async function defaultSessionsDir() {
+  return join(await getRepoRoot(), SESSIONS_SUBPATH);
+}
+
+// Statuses a session cannot leave — `done`/`aborted` are one-way ends.
+const TERMINAL_STATUSES = new Set(['done', 'aborted']);
+
+// ── id generation ─────────────────────────────────────────────────────────────
+// ULID-like: 26-char Crockford base32 = 10-char millisecond timestamp (48 bits,
+// lexicographically sortable by creation time) + 16-char entropy (80 bits from
+// crypto.randomBytes → collision-safe). Uppercase, excludes I L O U to stay
+// unambiguous. node:crypto is stdlib, so this stays zero-dependency.
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const SESSION_ID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+
+function encodeTime(ms) {
+  let n = ms;
+  let out = '';
+  for (let i = 0; i < 10; i++) {
+    const mod = n % 32;
+    out = CROCKFORD[mod] + out;
+    n = (n - mod) / 32;
+  }
+  return out;
+}
+
+function encodeEntropy() {
+  const bytes = randomBytes(16); // 256 is a multiple of 32 → low 5 bits are unbiased
+  let out = '';
+  for (let i = 0; i < 16; i++) out += CROCKFORD[bytes[i] & 0x1f];
+  return out;
+}
+
+export function newSessionId(now = Date.now()) {
+  return encodeTime(now) + encodeEntropy();
+}
+
+export function isValidSessionId(id) {
+  return typeof id === 'string' && SESSION_ID_RE.test(id);
+}
+
+// ── error helpers ─────────────────────────────────────────────────────────────
+function notFound(msg) {
+  return Object.assign(new Error(msg), { exitCode: 2 });
+}
+function ioFail(msg, cause) {
+  return Object.assign(new Error(`${msg}: ${cause && cause.message ? cause.message : cause}`), { exitCode: 3 });
+}
+
+// ── store factory ─────────────────────────────────────────────────────────────
+// makeStore(dir) binds all paths + IO to `dir`. Tests pass a temp dir. Commands
+// that don't know the dir up-front go through `getDefaultStore()` (below), which
+// resolves via getRepoRoot() and caches — same lazy pattern `pa knowledge` uses.
+export function makeStore(sessionsDir) {
+  if (!sessionsDir) {
+    throw new Error('makeStore(sessionsDir) requires an explicit sessions dir; use getDefaultStore() for the operator-repo default');
+  }
+  function sessionDir(id) { return join(sessionsDir, id); }
+  function paths(id) {
+    const dir = sessionDir(id);
+    return {
+      dir,
+      manifest: join(dir, 'manifest.json'),
+      plan: join(dir, 'plan.json'),
+      sources: join(dir, 'sources.json'),
+      gates: join(dir, 'gates.json'),
+      answer: join(dir, 'answer.md'),
+      findingsDir: join(dir, 'findings'),
+      gatedDir: join(dir, 'gated'),
+    };
+  }
+
+  function exists(id) { return existsSync(join(sessionsDir, id, 'manifest.json')); }
+
+  // Sole low-level write. Serialises pretty JSON with a trailing newline.
+  async function writeJson(path, obj) {
+    try {
+      await writeFile(path, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    } catch (e) {
+      throw ioFail(`failed to write ${path}`, e);
+    }
+  }
+
+  async function ensureDir(dir) {
+    try {
+      await mkdir(dir, { recursive: true });
+    } catch (e) {
+      throw ioFail(`failed to create ${dir}`, e);
+    }
+  }
+
+  async function readText(path, whatMissing) {
+    try {
+      return await readFile(path, 'utf8');
+    } catch (e) {
+      if (e.code === 'ENOENT') throw notFound(whatMissing);
+      throw ioFail(`failed to read ${path}`, e);
+    }
+  }
+
+  // Create a fresh session directory with its four store files. `plan`,
+  // `sources`, `gates` are optional; manifest is mandatory. Validates every
+  // artifact before it touches disk.
+  async function createSession({ manifest, plan, sources, gates }) {
+    validateManifest(manifest);
+    const p = paths(manifest.sessionId);
+    await ensureDir(p.dir);
+    await writeJson(p.manifest, manifest);
+    if (plan !== undefined) { validatePlan(plan); await writeJson(p.plan, plan); }
+    if (sources !== undefined) { validateSources(sources); await writeJson(p.sources, sources); }
+    if (gates !== undefined) { validateGates(gates); await writeJson(p.gates, gates); }
+    return manifest.sessionId;
+  }
+
+  async function writeManifest(id, manifest) {
+    validateManifest(manifest);
+    await writeJson(paths(id).manifest, manifest);
+  }
+
+  // Atomic status transition through the chokepoint: read → guard → validate →
+  // write. Refuses to move a session out of a TERMINAL status (done/aborted) —
+  // finalising is one-way, so this is an operational failure (exit 2), matching
+  // the "explicit filter matched nothing" posture in prune. `nowIso` is injected
+  // (the store stays clock-agnostic; the command binds the clock).
+  async function updateManifestStatus(id, nextStatus, nowIso) {
+    const manifest = await readManifest(id); // exit 2 if missing / malformed
+    if (TERMINAL_STATUSES.has(manifest.status)) {
+      throw notFound(`session ${id} is already ${manifest.status}; cannot mark ${nextStatus}`);
+    }
+    const updated = { ...manifest, status: nextStatus, updatedAt: nowIso };
+    await writeManifest(id, updated); // validates before persist
+    return updated;
+  }
+  async function writePlan(id, plan) {
+    validatePlan(plan);
+    await writeJson(paths(id).plan, plan);
+  }
+  async function writeSources(id, sources) {
+    validateSources(sources);
+    await writeJson(paths(id).sources, sources);
+  }
+  async function writeGates(id, gates) {
+    validateGates(gates);
+    await writeJson(paths(id).gates, gates);
+  }
+
+  async function deleteSession(id) {
+    try {
+      await rm(sessionDir(id), { recursive: true, force: true });
+    } catch (e) {
+      throw ioFail(`failed to delete session ${id}`, e);
+    }
+  }
+
+  // ── reads ───────────────────────────────────────────────────────────────────
+  async function readManifest(id) {
+    const text = await readText(paths(id).manifest, `session ${id} not found`);
+    return loadManifest(text, `session ${id} manifest`);
+  }
+  async function readPlan(id) {
+    const text = await readText(paths(id).plan, `session ${id} has no plan.json`);
+    return loadPlan(text, `session ${id} plan`);
+  }
+  async function readSources(id) {
+    if (!existsSync(paths(id).sources)) return { items: [] };
+    const text = await readText(paths(id).sources, `session ${id} has no sources.json`);
+    return loadSources(text, `session ${id} sources`);
+  }
+  async function readGates(id) {
+    if (!existsSync(paths(id).gates)) return { queue: [] };
+    const text = await readText(paths(id).gates, `session ${id} has no gates.json`);
+    return loadGates(text, `session ${id} gates`);
+  }
+
+  // The session answer is worker-written (Finalise phase), free-form Markdown —
+  // no schema. Returns the raw text, or null when the session was never
+  // finalised (answer.md absent). Promotion reads it verbatim; a missing answer
+  // is a soft skip, not an error, so we don't throw here.
+  async function readAnswer(id) {
+    const p = paths(id).answer;
+    if (!existsSync(p)) return null;
+    try {
+      return await readFile(p, 'utf8');
+    } catch (e) {
+      throw ioFail(`failed to read answer for ${id}`, e);
+    }
+  }
+
+  // Findings are worker-written at findings/sq-<id>.json. Read + validate all.
+  async function listFindings(id) {
+    const dir = paths(id).findingsDir;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (e) {
+      if (e.code === 'ENOENT') return [];
+      throw ioFail(`failed to read findings for ${id}`, e);
+    }
+    const files = entries
+      .filter((e) => e.isFile() && e.name.endsWith('.json'))
+      .map((e) => e.name)
+      .sort();
+    const out = [];
+    for (const name of files) {
+      const text = await readText(join(dir, name), `finding ${name} vanished`);
+      out.push(loadFinding(text, `session ${id} finding ${name}`));
+    }
+    return out;
+  }
+
+  // List every session, newest first (sessionId sorts by creation time).
+  // Malformed sessions are surfaced with an error marker rather than silently
+  // dropped — `show` can then diagnose them.
+  async function listSessions() {
+    let entries;
+    try {
+      entries = await readdir(sessionsDir, { withFileTypes: true });
+    } catch (e) {
+      if (e.code === 'ENOENT') return [];
+      throw ioFail(`failed to read sessions dir`, e);
+    }
+    const ids = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort().reverse();
+    const out = [];
+    for (const id of ids) {
+      try {
+        const manifest = await readManifest(id);
+        out.push({ id, manifest, error: null });
+      } catch (e) {
+        out.push({ id, manifest: null, error: e.message });
+      }
+    }
+    return out;
+  }
+
+  return {
+    sessionsDir,
+    newSessionId,
+    isValidSessionId,
+    sessionDir,
+    paths,
+    exists,
+    createSession,
+    writeManifest,
+    updateManifestStatus,
+    writePlan,
+    writeSources,
+    writeGates,
+    deleteSession,
+    readManifest,
+    readPlan,
+    readSources,
+    readGates,
+    readAnswer,
+    listFindings,
+    listSessions,
+  };
+}
+
+// Cached default store, resolved lazily via getRepoRoot(). Commands call this
+// when the caller didn't inject a store; tests inject via makeStore(tmpDir).
+let _defaultStore = null;
+export async function getDefaultStore() {
+  if (_defaultStore) return _defaultStore;
+  const dir = await defaultSessionsDir();
+  _defaultStore = makeStore(dir);
+  return _defaultStore;
+}
+
+// Test seam: drop the cached default so a fresh env/cwd is picked up.
+export function _resetDefaultStore() {
+  _defaultStore = null;
+}

package/dist/engineering-pa-cli/src/research/store/manifest.mjs

@@ -0,0 +1,56 @@
+// manifest.json schema + validator (build-spec §3–§6). Zero-dep, hand-rolled.
+// Schema doc: src/schema/manifest.schema.json.
+import {
+  parseJson, requireObject, requireFields, noExtraFields,
+  requireString, optionalString, requireEnum, requireArray, requireInteger, fail,
+} from './validate.mjs';
+
+export const MODES = ['light', 'normal', 'deep'];
+export const GATE_POLICIES = ['operatorPresent', 'background', 'worker'];
+export const STATUSES = ['draft', 'in-progress', 'done', 'aborted'];
+export const OUTPUT_MODES = ['shortAnswer', 'article', 'structured'];
+
+const TOP = [
+  'sessionId', 'mode', 'question', 'intent', 'gatePolicy', 'status',
+  'outputMode', 'budget', 'assumptions', 'createdAt', 'updatedAt',
+];
+const REQUIRED = [
+  'sessionId', 'mode', 'question', 'gatePolicy', 'status',
+  'outputMode', 'budget', 'assumptions', 'createdAt', 'updatedAt',
+];
+const SESSION_ID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+const BUDGET_FIELDS = ['maxSubQuestions', 'maxDeepeningRounds', 'wallClockMinutes'];
+
+export function loadManifest(text, where = 'manifest') {
+  return validateManifest(parseJson(text, where), where);
+}
+
+export function validateManifest(m, where = 'manifest') {
+  requireObject(m, where);
+  requireFields(m, REQUIRED, where);
+  noExtraFields(m, TOP, where);
+
+  const sessionId = requireString(m, 'sessionId', where);
+  if (!SESSION_ID_RE.test(sessionId)) fail('sessionId is not a valid ULID-like id', where);
+
+  requireEnum(m, 'mode', MODES, where);
+  requireString(m, 'question', where);
+  optionalString(m, 'intent', where);
+  requireEnum(m, 'gatePolicy', GATE_POLICIES, where);
+  requireEnum(m, 'status', STATUSES, where);
+  requireEnum(m, 'outputMode', OUTPUT_MODES, where);
+
+  requireObject(m.budget, `${where}.budget`);
+  requireFields(m.budget, BUDGET_FIELDS, `${where}.budget`);
+  noExtraFields(m.budget, BUDGET_FIELDS, `${where}.budget`);
+  for (const f of BUDGET_FIELDS) requireInteger(m.budget, f, `${where}.budget`, { min: 0 });
+
+  const assumptions = requireArray(m, 'assumptions', where);
+  assumptions.forEach((a, i) => {
+    if (typeof a !== 'string') fail(`assumptions[${i}] must be a string`, where);
+  });
+
+  requireString(m, 'createdAt', where);
+  requireString(m, 'updatedAt', where);
+  return m;
+}

package/dist/engineering-pa-cli/src/research/store/plan.mjs

@@ -0,0 +1,59 @@
+// plan.json schema + validator (build-spec §4/§5). Zero-dep, hand-rolled.
+// Schema doc: src/schema/plan.schema.json.
+import {
+  parseJson, requireObject, requireFields, noExtraFields,
+  requireString, requireEnum, requireArray, requireInteger, fail,
+} from './validate.mjs';
+
+export const SQ_KINDS = ['independent', 'dependent'];
+export const VERIFICATION_TIERS = ['none', 'central-3vote', 'diverse-lens-3vote'];
+
+const TOP = ['subQuestions', 'deepeningRounds', 'verificationTier'];
+const SQ_FIELDS = ['id', 'text', 'kind', 'dependsOn'];
+
+// Mode-derived plan defaults. `run` writes the skeleton; the workflow (w-017)
+// fills subQuestions. Single source of truth for the light/normal/deep mapping.
+export const PLAN_DEFAULTS = {
+  light: { deepeningRounds: 0, verificationTier: 'none' },
+  normal: { deepeningRounds: 1, verificationTier: 'central-3vote' },
+  deep: { deepeningRounds: 3, verificationTier: 'diverse-lens-3vote' },
+};
+
+// Build the skeleton plan for a mode (used by `run`).
+export function skeletonPlan(mode) {
+  const d = PLAN_DEFAULTS[mode];
+  if (!d) throw Object.assign(new Error(`unknown mode "${mode}"`), { exitCode: 1 });
+  return { subQuestions: [], deepeningRounds: d.deepeningRounds, verificationTier: d.verificationTier };
+}
+
+export function loadPlan(text, where = 'plan') {
+  return validatePlan(parseJson(text, where), where);
+}
+
+export function validatePlan(p, where = 'plan') {
+  requireObject(p, where);
+  requireFields(p, TOP, where);
+  noExtraFields(p, TOP, where);
+
+  const sqs = requireArray(p, 'subQuestions', where);
+  const seen = new Set();
+  sqs.forEach((sq, i) => {
+    const w = `${where}.subQuestions[${i}]`;
+    requireObject(sq, w);
+    requireFields(sq, SQ_FIELDS, w);
+    noExtraFields(sq, SQ_FIELDS, w);
+    const id = requireString(sq, 'id', w);
+    if (seen.has(id)) fail(`duplicate sub-question id "${id}"`, w);
+    seen.add(id);
+    requireString(sq, 'text', w);
+    requireEnum(sq, 'kind', SQ_KINDS, w);
+    const deps = requireArray(sq, 'dependsOn', w);
+    deps.forEach((d, j) => {
+      if (typeof d !== 'string') fail(`dependsOn[${j}] must be a string`, w);
+    });
+  });
+
+  requireInteger(p, 'deepeningRounds', where, { min: 0, max: 3 });
+  requireEnum(p, 'verificationTier', VERIFICATION_TIERS, where);
+  return p;
+}

package/dist/engineering-pa-cli/src/research/store/sources.mjs

@@ -0,0 +1,44 @@
+// sources.json schema + validator (build-spec §2/§3). Zero-dep, hand-rolled.
+// Schema doc: src/schema/sources.schema.json.
+import {
+  parseJson, requireObject, requireFields, noExtraFields,
+  requireString, optionalString, requireEnum, requireArray, fail,
+} from './validate.mjs';
+
+export const SOURCE_KINDS = ['web', 'playwright', 'kb', 'codebase', 'prior-session'];
+
+const TOP = ['items'];
+const ITEM_FIELDS = ['id', 'kind', 'url', 'title', 'fetchedAt', 'checksum'];
+const ITEM_REQUIRED = ['id', 'kind'];
+
+export function emptySources() {
+  return { items: [] };
+}
+
+export function loadSources(text, where = 'sources') {
+  return validateSources(parseJson(text, where), where);
+}
+
+export function validateSources(s, where = 'sources') {
+  requireObject(s, where);
+  requireFields(s, TOP, where);
+  noExtraFields(s, TOP, where);
+
+  const items = requireArray(s, 'items', where);
+  const seen = new Set();
+  items.forEach((it, i) => {
+    const w = `${where}.items[${i}]`;
+    requireObject(it, w);
+    requireFields(it, ITEM_REQUIRED, w);
+    noExtraFields(it, ITEM_FIELDS, w);
+    const id = requireString(it, 'id', w);
+    if (seen.has(id)) fail(`duplicate source id "${id}"`, w);
+    seen.add(id);
+    requireEnum(it, 'kind', SOURCE_KINDS, w);
+    optionalString(it, 'url', w);
+    optionalString(it, 'title', w);
+    optionalString(it, 'fetchedAt', w);
+    optionalString(it, 'checksum', w);
+  });
+  return s;
+}

package/dist/engineering-pa-cli/src/research/store/validate.mjs

@@ -0,0 +1,92 @@
+// Shared hand-rolled validation helpers for the research session schemas.
+//
+// Zero-dep. No schema library (tooling standard §3). These are the primitives
+// the per-schema validators in this directory are built from.
+//
+// A validation failure means "a session file on disk is malformed" — that is an
+// operational failure, exit code 2 (tooling standard §6). Callers that validate
+// *user input* (e.g. run's CLI flags) do that in cli.mjs and map to exit 1 there;
+// by the time a manifest object reaches these validators it is expected to be valid,
+// so a failure here is a genuine data-integrity problem.
+
+// Throw a validation error carrying exit code 2 and a located message.
+export function fail(msg, where) {
+  const err = new Error(`${where ? where + ': ' : ''}${msg}`);
+  err.exitCode = 2;
+  err.validation = true;
+  throw err;
+}
+
+export function isObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+export function requireObject(v, where) {
+  if (!isObject(v)) fail('must be a JSON object', where);
+  return v;
+}
+
+export function requireFields(obj, fields, where) {
+  for (const f of fields) {
+    if (!(f in obj)) fail(`missing required field "${f}"`, where);
+  }
+}
+
+export function noExtraFields(obj, allowed, where) {
+  const set = new Set(allowed);
+  for (const k of Object.keys(obj)) {
+    if (!set.has(k)) fail(`unexpected field "${k}"`, where);
+  }
+}
+
+export function requireString(obj, key, where, { nonEmpty = true } = {}) {
+  const v = obj[key];
+  if (typeof v !== 'string') fail(`"${key}" must be a string`, where);
+  if (nonEmpty && v.length === 0) fail(`"${key}" must be non-empty`, where);
+  return v;
+}
+
+export function optionalString(obj, key, where) {
+  if (!(key in obj) || obj[key] == null) return undefined;
+  if (typeof obj[key] !== 'string') fail(`"${key}" must be a string if present`, where);
+  return obj[key];
+}
+
+export function requireEnum(obj, key, allowed, where) {
+  const v = obj[key];
+  if (!allowed.includes(v)) fail(`"${key}" must be one of ${allowed.join(' | ')} (got ${JSON.stringify(v)})`, where);
+  return v;
+}
+
+export function optionalEnum(obj, key, allowed, where) {
+  if (!(key in obj) || obj[key] == null) return undefined;
+  return requireEnum(obj, key, allowed, where);
+}
+
+export function requireArray(obj, key, where) {
+  const v = obj[key];
+  if (!Array.isArray(v)) fail(`"${key}" must be an array`, where);
+  return v;
+}
+
+export function requireBoolean(obj, key, where) {
+  if (typeof obj[key] !== 'boolean') fail(`"${key}" must be a boolean`, where);
+  return obj[key];
+}
+
+export function requireInteger(obj, key, where, { min, max } = {}) {
+  const v = obj[key];
+  if (typeof v !== 'number' || !Number.isInteger(v)) fail(`"${key}" must be an integer`, where);
+  if (min != null && v < min) fail(`"${key}" must be >= ${min}`, where);
+  if (max != null && v > max) fail(`"${key}" must be <= ${max}`, where);
+  return v;
+}
+
+// Parse JSON text, failing with exit code 2 on malformed JSON.
+export function parseJson(text, where) {
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    fail(`not valid JSON: ${e.message}`, where);
+  }
+}