@adrata/adrata-mcp 1.0.49 → 1.0.51

package/tools/threads/shared.js

@@ -0,0 +1,390 @@
+/**
+ * Shared vocabulary and pure helpers for the Starfield THREADS tools — Goals,
+ * Propositions, Indicators, Decisions, Ideas, the Discussion that runs under
+ * all five, the Galaxy documents each can file, and the one graph read.
+ *
+ * The contract: `spoq/epics/backlog/starfield-ideas/CONTRACT.md`. Every closed
+ * vocabulary below mirrors a `CHECK` constraint in the `work_threads`
+ * migration byte-for-byte; the Rust side has the same arrays and a test that
+ * the migration and the code agree. If a value here is not in the contract,
+ * the API will 400 it, so add it to the contract first.
+ *
+ * Nothing in this module talks to a server. The helpers are exported so the
+ * one thing a thread tool can silently get wrong — deriving "is this goal on
+ * track" from a reading, or tallying positions — is testable without one.
+ */
+
+export const GOVERNED_NOTE =
+  ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey (reuse the SAME key on retry so a flaky connection cannot write twice).';
+
+/** Who the noun is for. A lens, never a hiding rule: the API returns every audience unless asked to filter. */
+export const AUDIENCES = ['seller', 'manager', 'leader', 'builder', 'company'];
+
+/** Where an idea arrived from. Required on capture, together with `source`. */
+export const VECTORS = [
+  'owner',
+  'customer',
+  'buyer_demand',
+  'competitor',
+  'keynote',
+  'internal_audit',
+  'technology',
+  'regulation',
+];
+
+export const GOAL_LEVELS = ['goal', 'strategy'];
+export const GOAL_STATUSES = ['proposed', 'committed', 'achieved', 'abandoned'];
+export const IDEA_STATES = ['captured', 'explored', 'parked', 'committed', 'realized', 'dropped'];
+export const DECISION_STATUSES = ['proposed', 'discussing', 'decided', 'superseded', 'reversed'];
+export const POSITIONS = ['support', 'concern', 'object'];
+/** The reviewer's verdict on a decided decision's own prediction; stored as the outcome's first token and scored by calibration. */
+export const OUTCOME_VERDICTS = ['held', 'partly', 'did_not_hold'];
+export const INDICATOR_KINDS = ['leading', 'lagging'];
+export const INDICATOR_DIRECTIONS = ['up', 'down'];
+export const DOORS = ['one_way', 'two_way'];
+/** What a decision may point at. Polymorphic by design; the route checks the target exists in the right table. */
+export const DECISION_LINK_TARGET_TYPES = ['goal', 'idea', 'scope', 'work_item', 'indicator'];
+/** How one decision relates to another — the edges of the decision graph. refines = sub-decision. */
+export const DECISION_RELATIONS = ['supersedes', 'amends', 'refines', 'depends_on', 'conflicts_with', 'relates_to'];
+/** What a discussion post, or a field-change row, hangs off. */
+export const THREAD_TARGET_TYPES = ['goal', 'idea', 'decision', 'indicator'];
+/** Derived, never stored (see indicatorStatus). */
+export const INDICATOR_STATUSES = ['no_reading', 'achieved', 'on_track', 'off_track', 'unknown_pace'];
+
+// ---------------------------------------------------------------------------
+// Propositions — the fifth noun (CONTRACT.md "Propositions: the fifth noun").
+// A claim about the world we act on, with the observation that would show it
+// false. `confidence` on the row is the latest reading's value and is never
+// edited directly; moving to contested or falsified needs a reading with
+// evidence. Each array mirrors a CHECK in `work_propositions` /
+// `work_proposition_links` byte-for-byte.
+// ---------------------------------------------------------------------------
+
+export const PROPOSITION_STATUSES = ['proposed', 'supported', 'contested', 'falsified', 'superseded'];
+/** What rests on a proposition — the `assumes` edge. */
+export const PROPOSITION_LINK_TARGET_TYPES = ['goal', 'decision', 'idea', 'indicator'];
+/** Statuses the API refuses without a reading that carries evidence; the tool says so before the 400. */
+export const PROPOSITION_EVIDENCE_STATUSES = new Set(['contested', 'falsified']);
+
+// ---------------------------------------------------------------------------
+// Galaxy documents on every noun (CONTRACT.md "Galaxy, and the ontology as the
+// core of the system"). `work_thread_documents` keyed by (target_type,
+// target_id, document_id), each with a role and a reason.
+// ---------------------------------------------------------------------------
+
+export const DOCUMENT_TARGET_TYPES = ['goal', 'proposition', 'decision', 'indicator', 'idea'];
+export const DOCUMENT_ROLES = ['memo', 'outcome', 'evidence', 'source', 'artifact'];
+/** The route family each noun files its documents under: `POST/DELETE /{family}/{id}/documents[/{documentId}]`. */
+export const DOCUMENT_FAMILY_PATHS = {
+  goal: '/api/v1/work-goals',
+  proposition: '/api/v1/work-propositions',
+  decision: '/api/v1/work-decisions',
+  indicator: '/api/v1/work-indicators',
+  idea: '/api/v1/work-ideas',
+};
+
+// ---------------------------------------------------------------------------
+// The one graph read, any root (CONTRACT.md "Thread graphs you can generate").
+// `GET /work-threads/graph?root=<kind>:<id>&depth=<n>&format=json|mermaid`.
+// The contract's graph section names six root kinds; the propositions section
+// adds the proposition as a node with `assumes` edges, so it is a root too.
+// ---------------------------------------------------------------------------
+
+export const THREAD_GRAPH_ROOT_KINDS = ['goal', 'strategy', 'decision', 'idea', 'indicator', 'scope', 'proposition'];
+export const THREAD_GRAPH_RELATIONS = [
+  'serves', 'measured_by', 'decided_by', 'realizes', 'relates',
+  'supersedes', 'amends', 'refines', 'depends_on', 'conflicts_with', 'assumes',
+];
+export const THREAD_GRAPH_FORMATS = ['json', 'mermaid'];
+export const THREAD_GRAPH_DEFAULT_DEPTH = 3;
+export const THREAD_GRAPH_MAX_NODES = 200;
+
+/** Transitions the route refuses without a non-empty reason (400 naming the field). */
+export const REASON_REQUIRED_STATES = new Set(['parked', 'dropped', 'superseded', 'reversed', 'abandoned']);
+
+/** Mirrors the per-family constants in the Rust modules. */
+export const MAX_TITLE_CHARS = 160;
+export const MAX_REASON_CHARS = 1000;
+export const MAX_BODY_CHARS = 50_000;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+// ---------------------------------------------------------------------------
+// Argument validators. Each throws a plain Error naming the field, so a bad
+// call fails HERE with a sentence rather than at the API with a 400 the agent
+// has to decode. They validate exactly what the route validates and nothing
+// more: they are a mirror, not a second policy.
+// ---------------------------------------------------------------------------
+
+export function validateTitle(title, field = 'title') {
+  const text = String(title ?? '').trim();
+  if (!text) throw new Error(`${field} is required and cannot be blank`);
+  if (text.length > MAX_TITLE_CHARS) {
+    throw new Error(`${field} is ${text.length} characters; the limit is ${MAX_TITLE_CHARS}`);
+  }
+  return text;
+}
+
+export function validateBody(body, field = 'body') {
+  const text = String(body ?? '');
+  if (text.length > MAX_BODY_CHARS) {
+    throw new Error(`${field} is ${text.length} characters; the limit is ${MAX_BODY_CHARS}`);
+  }
+  return text;
+}
+
+/** A reason recorded ON a row (a link, a transition). Distinct from the audit header, though a tool may pass one string as both. */
+export function validateReason(reason, field = 'reason') {
+  const text = String(reason ?? '').trim();
+  if (!text) throw new Error(`${field} is required and cannot be blank`);
+  if (text.length > MAX_REASON_CHARS) {
+    throw new Error(`${field} is ${text.length} characters; the limit is ${MAX_REASON_CHARS}`);
+  }
+  return text;
+}
+
+export function validateConfidence(confidence, field = 'confidence') {
+  if (confidence === undefined || confidence === null) return undefined;
+  const n = Number(confidence);
+  if (!Number.isFinite(n) || n < 0 || n > 1) throw new Error(`${field} must be a number from 0 to 1`);
+  return n;
+}
+
+export function validateDate(value, field) {
+  if (value === undefined || value === null || value === '') return value;
+  if (!DATE_RE.test(String(value))) throw new Error(`${field} must be a date, YYYY-MM-DD`);
+  return value;
+}
+
+export function validateEnum(value, allowed, field) {
+  if (!allowed.includes(value)) {
+    throw new Error(`${field} must be one of ${allowed.join(' | ')}; got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+/**
+ * A goal has no parent; a strategy has exactly one. This is the migration's
+ * `strategy_has_parent` CHECK, mirrored so the agent learns it from a sentence
+ * rather than a constraint-violation string.
+ */
+export function validateGoalLevel(level, parentGoalId) {
+  validateEnum(level, GOAL_LEVELS, 'level');
+  const hasParent = Boolean(parentGoalId);
+  if (level === 'strategy' && !hasParent) {
+    throw new Error('a strategy needs parentGoalId: the goal it is one of the ways to reach');
+  }
+  if (level === 'goal' && hasParent) {
+    throw new Error('a goal has no parentGoalId; to nest under a goal, create a strategy');
+  }
+  return level;
+}
+
+/**
+ * A link call names exactly one target. `choices` is `{ argName: value }`;
+ * the one that is set wins, and zero or two is an error naming the options.
+ */
+export function pickExactlyOne(choices) {
+  const set = Object.entries(choices).filter(([, v]) => v !== undefined && v !== null && v !== '');
+  const names = Object.keys(choices).join(' | ');
+  if (set.length === 0) throw new Error(`pass exactly one of ${names}`);
+  if (set.length > 1) {
+    throw new Error(`pass exactly one of ${names}, not ${set.map(([k]) => k).join(' and ')}`);
+  }
+  const [key, value] = set[0];
+  return { key, value };
+}
+
+/** A transition into a terminal or parked state needs a stated reason; every transition here gets one anyway. */
+export function validateStateReason(state, reason) {
+  if (REASON_REQUIRED_STATES.has(state) && !String(reason ?? '').trim()) {
+    throw new Error(`moving to ${state} requires a reason`);
+  }
+  return validateReason(reason);
+}
+
+/** Audience filter for a list: array or comma string in, `a,b` out (or undefined). */
+export function audienceQuery(audience) {
+  if (audience === undefined || audience === null) return undefined;
+  const list = Array.isArray(audience) ? audience : String(audience).split(',');
+  const clean = list.map((a) => String(a).trim()).filter(Boolean);
+  for (const a of clean) validateEnum(a, AUDIENCES, 'audience');
+  return clean.length ? clean.join(',') : undefined;
+}
+
+/**
+ * A graph root is `<kind>:<id>`, kind from THREAD_GRAPH_ROOT_KINDS. Returns
+ * `{ kind, id, root }` with `root` re-joined, so a stray space is trimmed
+ * before it reaches the query string.
+ */
+export function parseGraphRoot(root) {
+  const text = String(root ?? '').trim();
+  const at = text.indexOf(':');
+  if (!text || at <= 0 || at === text.length - 1) {
+    throw new Error(`root must be <kind>:<id>, kind one of ${THREAD_GRAPH_ROOT_KINDS.join(' | ')}; got ${JSON.stringify(root)}`);
+  }
+  const kind = text.slice(0, at).trim();
+  const id = text.slice(at + 1).trim();
+  validateEnum(kind, THREAD_GRAPH_ROOT_KINDS, 'root kind');
+  if (!id) throw new Error('root must be <kind>:<id>; the id is blank');
+  return { kind, id, root: `${kind}:${id}` };
+}
+
+/** A graph depth is a positive integer; undefined means the API default (3). */
+export function validateDepth(depth, field = 'depth') {
+  if (depth === undefined || depth === null || depth === '') return undefined;
+  const n = Number(depth);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`${field} must be a whole number of 1 or more`);
+  return n;
+}
+
+/**
+ * The mermaid text out of whatever shape the API hands back for
+ * `format=mermaid`: a bare string, `{ mermaid }`, or `{ data: <either> }`.
+ * Returns null when there is none, so the caller can say so rather than
+ * pass an object where a document was promised.
+ */
+export function mermaidText(payload) {
+  if (typeof payload === 'string') return payload;
+  if (!payload || typeof payload !== 'object') return null;
+  if (typeof payload.mermaid === 'string') return payload.mermaid;
+  if (payload.data !== undefined) return mermaidText(payload.data);
+  return null;
+}
+
+/** Build `?k=v&k2=v2`, skipping undefined/null/empty so a bare list has a bare path. */
+export function buildQuery(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (value === undefined || value === null || value === '') continue;
+    search.set(key, String(value));
+  }
+  const s = search.toString();
+  return s ? `?${s}` : '';
+}
+
+/** Drop undefined keys so a body says only what the caller said. */
+export function compactBody(body) {
+  return Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined));
+}
+
+// ---------------------------------------------------------------------------
+// Derivations. These mirror `derive.rs`; the API is the source of truth and
+// returns `status` itself. They exist so a tool can recompute from readings it
+// was handed (get_goal_thread returns the last 12) and so the rule is pinned.
+// ---------------------------------------------------------------------------
+
+function meets(value, target, direction) {
+  if (target === undefined || target === null) return false;
+  return direction === 'down' ? value <= target : value >= target;
+}
+
+/**
+ * no readings → no_reading; latest meets target in direction → achieved;
+ * else latest has `expected`: meets expected → on_track, else off_track;
+ * else unknown_pace (a reading with no plan line says nothing about pace).
+ */
+export function indicatorStatus(latest, target, direction = 'up') {
+  if (!latest || latest.value === undefined || latest.value === null) return 'no_reading';
+  const value = Number(latest.value);
+  if (meets(value, target === undefined || target === null ? null : Number(target), direction)) {
+    return 'achieved';
+  }
+  if (latest.expected !== undefined && latest.expected !== null) {
+    return meets(value, Number(latest.expected), direction) ? 'on_track' : 'off_track';
+  }
+  return 'unknown_pace';
+}
+
+/** `{ support, concern, object }` from a list of positions (rows or bare strings). Unknown values are ignored, never counted. */
+export function positionsTally(positions) {
+  const tally = { support: 0, concern: 0, object: 0 };
+  for (const p of Array.isArray(positions) ? positions : []) {
+    const value = typeof p === 'string' ? p : p?.position;
+    if (value in tally) tally[value] += 1;
+  }
+  return tally;
+}
+
+/**
+ * The API's decision `positions` field IS the tally object `{support, concern,
+ * object}` (Rust `PositionTally`; the who-list is `positionHolders`). Pass it
+ * through as-is; only tally a list, which is what an older payload or a test
+ * fixture may hand over. Anything else counts as no positions.
+ */
+export function tallyFrom(positions) {
+  if (Array.isArray(positions)) return positionsTally(positions);
+  if (positions && typeof positions === 'object') return positions;
+  return positionsTally([]);
+}
+
+/**
+ * The compact form of a goal thread — what an agent should read before the
+ * whole thread. Progress is passed through as the COUNTS the API derived,
+ * never turned into a percentage (hierarchy Decision 4).
+ */
+export function summarizeThread(thread) {
+  if (!thread) return null;
+  const goal = thread.goal ?? thread;
+  const strategies = Array.isArray(thread.strategies) ? thread.strategies : [];
+  const indicators = Array.isArray(thread.indicators) ? thread.indicators : [];
+  const decisions = Array.isArray(thread.decisions) ? thread.decisions : [];
+  const scopes = Array.isArray(thread.scopes) ? thread.scopes : [];
+  const ideas = Array.isArray(thread.ideas) ? thread.ideas : [];
+  const indicatorLine = (ind) => {
+    const readings = Array.isArray(ind.readings) ? ind.readings : [];
+    const latest = ind.latest ?? readings[0] ?? null;
+    return {
+      id: ind.id,
+      name: ind.name,
+      kind: ind.kind,
+      latest: latest ? { value: latest.value, expected: latest.expected ?? null, observedAt: latest.observedAt } : null,
+      target: ind.targetValue ?? null,
+      status: ind.status ?? indicatorStatus(latest, ind.targetValue, ind.direction),
+    };
+  };
+  return {
+    goal: {
+      id: goal.id,
+      title: goal.title,
+      level: goal.level,
+      status: goal.status,
+      audience: goal.audience,
+      targetOn: goal.targetOn ?? null,
+    },
+    strategies: strategies.map((s) => ({
+      id: s.id,
+      title: s.title,
+      status: s.status,
+      confidence: s.confidence ?? null,
+      indicators: (Array.isArray(s.indicators) ? s.indicators : []).map(indicatorLine),
+      progress: s.progress ?? null,
+    })),
+    indicators: indicators.map(indicatorLine),
+    decisions: decisions.map((d) => ({
+      id: d.id,
+      title: d.title,
+      status: d.status,
+      tally: d.tally ?? d.positionsTally ?? tallyFrom(d.positions),
+    })),
+    progress: thread.progress ?? goal.progress ?? null,
+    counts: {
+      strategies: strategies.length,
+      scopes: scopes.length,
+      ideas: ideas.length,
+      decisions: decisions.length,
+      indicators: indicators.length,
+      posts: thread.discussionCount ?? thread.postCount ?? 0,
+    },
+  };
+}
+
+/** The four governed-envelope args every write tool declares, in one place. */
+export function governedArgs(z) {
+  return {
+    dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live write.'),
+    approved: z.boolean().optional().describe('Required true for a live write.'),
+    reason: z.string().optional().describe('Required for a live write: the audit reason.'),
+    idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+  };
+}