heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/split-research.mjs

@@ -42,8 +42,27 @@ import {
   mkdirSync,
   unlinkSync,
 } from 'node:fs';
-import { join } from 'node:path';
-import { deriveSlug } from './promotion-helpers.mjs';
+import { join, isAbsolute, resolve, sep } from 'node:path';
+import {
+  deriveSlug,
+  fetchSpecRecordViaConsole,
+  resolveWriteModeFromDeps,
+  splitRawSpecForConsole,
+  cloudWriteFailureResult,
+} from './promotion-helpers.mjs';
+// Cloud-mode vault WRITES + the cloud-tier read selector
+// ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]], HS-KR16).
+// Split has the same create-first, link-second shape as the other promotion
+// flows: each child's "Split-from" callout names its SIBLINGS, and the
+// original's `split_into:` names every child — basenames the console only
+// mints when the POST lands.
+import {
+  createSpecViaConsole,
+  updateSpecViaConsole,
+  stripServerMintedFields,
+} from './cloud-vault-writes.mjs';
+import { readViaSelector } from './read-path.mjs';
+
 import { yamlScalar } from './yaml-scalar.mjs';
 import {
   allocateFileKey,
@@ -60,6 +79,14 @@ import {
 // caller would only learn that reactively when heyspex_promote_research
 // later refuses a child with RESEARCH_STILL_STUB.
 import { findUnresolvedResearchPlaceholders } from './promote-research.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+// Placeholders the CLOUD path feeds `buildChildResearchContent` in place of a
+// locally-minted id / file key / family key; `stripServerMintedFields` removes
+// them from the POST body (plus an explicit `delete` of an un-inheritable
+// `family:`), so the console never sees them.
+const CLOUD_PENDING_ID = 'HS-PENDING';
+const CLOUD_PENDING_KEY = 'PENDING';
 
 // Id validation/classification is via parseSpecId (dual-read: accepts type-first
 // HS-RES-<key> / HS-MIL-<key> / HS-CAP-<key> and the family-first orderings, plus
@@ -216,7 +243,7 @@ function appendChangeLogRow(body, dateStr, author, message) {
   return body.replace(/\s*$/, '') + `\n${row}\n`;
 }
 
-function commitWrites(writes) {
+function commitWrites(writes, vaultRoot) {
   const snapshots = new Map();
   const performed = [];
   try {
@@ -230,7 +257,10 @@ function commitWrites(writes) {
           0,
           Math.max(w.absPath.lastIndexOf('/'), w.absPath.lastIndexOf('\\')),
         );
-        if (dir) mkdirSync(dir, { recursive: true });
+        if (dir) {
+          if (vaultRoot) assertPathUnderRoot(vaultRoot, dir, 'split-research write');
+          mkdirSync(dir, { recursive: true });
+        }
         writeFileSync(w.absPath, w.content, 'utf8');
         performed.push(w);
       } else if (w.kind === 'update') {
@@ -396,6 +426,49 @@ function findCaptureByIdOrBasename(vaultRoot, ref) {
   return null;
 }
 
+// ── Cloud-tier siblings of the three lookups above (HS-KR16 pattern) ────────
+// `tier` is resolved ONCE per call by `executeSplitResearch` from `deps.tier`
+// and threaded down; absent it is `disk`, so every pre-existing caller reads
+// exactly as before. The neon branch reuses `fetchSpecRecordViaConsole` — the
+// same injected-`consoleFetch` reader promote-capture/promote-research use —
+// so a test drives the whole flow with a recorder and never opens a socket.
+// These exist because a cloud WRITE is pointless if the INPUTS cannot be
+// found: the writes below all derive from the original research doc and the
+// captures it names.
+
+async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findResearchByIdLocal(vaultRoot, researchId),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, researchId),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
+async function findMilestoneViaTier(vaultRoot, ref, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findMilestoneByIdOrBasename(vaultRoot, ref),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, ref),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
+async function findCaptureViaTier(vaultRoot, ref, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findCaptureByIdOrBasename(vaultRoot, ref),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, ref),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
 function collectOccupiedResearchIds(vaultRoot) {
   const occupied = new Set();
   const dir = join(vaultRoot, 'specs', 'research');
@@ -601,7 +674,20 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
   const validationError = validateInputShape(args);
   if (validationError) return validationError;
 
-  const research = findResearchByIdLocal(vaultRoot, args.research_id);
+  // Tier + write mode are resolved ONCE, here, by the caller and threaded down
+  // — never re-resolved inside a helper. Both default to the disk behaviour so
+  // every pre-existing caller/test is byte-identical
+  // ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+  const tierDeps = {
+    tier: deps?.tier ?? 'disk',
+    consoleUrl: deps?.consoleUrl,
+    consoleFetch: deps?.consoleFetch,
+  };
+  const writeMode = resolveWriteModeFromDeps(deps);
+  const cloudDeps = { consoleFetch: deps?.consoleFetch, consoleUrl: deps?.consoleUrl };
+  const cloudCompleted = [];
+
+  const research = await findResearchByIdViaTier(vaultRoot, args.research_id, tierDeps);
   if (!research) {
     return {
       error: 'RESEARCH_NOT_FOUND',
@@ -650,9 +736,16 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
   // Resolve all splits up-front, before any writes.
   // One occupied set across the whole loop (owner ruling 2026-07-10) — children
   // are not on disk yet, so a fresh vault walk per split could repeat a key.
-  const occupiedFileKeys = collectOccupiedKeysEitherKind(vaultRoot); // union: file+family keys (HS-SJOT)
+  //
+  // In CLOUD mode nothing is minted here at all: `collectOccupiedKeysEitherKind`
+  // is a vault SCAN, and in a file-less vault it returns an EMPTY set — a key
+  // drawn against it can collide with one the cloud vault already holds. The
+  // console mints every child's file key, family and filename.
+  const occupiedFileKeys =
+    writeMode === 'cloud' ? new Set() : collectOccupiedKeysEitherKind(vaultRoot); // union: file+family keys (HS-SJOT)
   const childRecords = [];
   const captureChildMap = new Map();
+  const captureRecords = new Map(); // basename -> record (raw reused by the write phase)
 
   for (let i = 0; i < args.splits.length; i++) {
     const split = args.splits[i];
@@ -661,7 +754,7 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
     if (split.target_milestone === 'NEW') {
       targetMilestone = { absent: true, newName: split.new_milestone_name.trim() };
     } else {
-      const ms = findMilestoneByIdOrBasename(vaultRoot, split.target_milestone);
+      const ms = await findMilestoneViaTier(vaultRoot, split.target_milestone, tierDeps);
       if (!ms) {
         return {
           error: 'MILESTONE_NOT_FOUND',
@@ -673,7 +766,8 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
 
     const childCaptureBasenames = [];
     for (const captureRef of split.sources_captures) {
-      const cap = findCaptureByIdOrBasename(vaultRoot, captureRef);
+      const cap = await findCaptureViaTier(vaultRoot, captureRef, tierDeps);
+      if (cap) captureRecords.set(cap.basename, cap);
       if (!cap) {
         return {
           error: 'CAPTURE_NOT_FOUND',
@@ -695,15 +789,18 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
     // original itself has no derivable family (should not occur for a real
     // research doc).
     const childFamilyKey =
-      originalFamilyKey ?? mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit });
+      writeMode === 'cloud'
+        ? (originalFamilyKey ?? null)
+        : (originalFamilyKey ?? mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit }));
     // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
     // and (V3) the anchor for `id:` itself
     // ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]).
-    const childFileKey = allocateFileKey(occupiedFileKeys, { randomUnit: deps?.randomUnit });
-    occupiedFileKeys.add(childFileKey);
-    const childId = `HS-${childFileKey}`;
+    const childFileKey =
+      writeMode === 'cloud' ? null : allocateFileKey(occupiedFileKeys, { randomUnit: deps?.randomUnit });
+    if (childFileKey) occupiedFileKeys.add(childFileKey);
+    const childId = childFileKey ? `HS-${childFileKey}` : null;
     const slug = deriveSlug(split.name);
-    const basename = `${childId}-${childFamilyKey}-RES-${slug}`;
+    const basename = childFileKey ? `${childId}-${childFamilyKey}-RES-${slug}` : null;
 
     childRecords.push({
       id: childId,
@@ -716,9 +813,13 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
       bodySlice: split.body_slice,
     });
 
+    // Hold the child RECORD, not its basename: in cloud mode the basename is
+    // still null here and only lands when that child's POST answers, so the
+    // capture→children map is read lazily at write time in both modes.
+    const childRecord = childRecords[childRecords.length - 1];
     for (const capBasename of childCaptureBasenames) {
       if (!captureChildMap.has(capBasename)) captureChildMap.set(capBasename, []);
-      captureChildMap.get(capBasename).push(basename);
+      captureChildMap.get(capBasename).push(childRecord);
     }
   }
 
@@ -727,17 +828,16 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
   const today = now.slice(0, 10);
   const author = 'split-research (agent)';
   const writes = [];
-  const childBasenames = childRecords.map((c) => c.basename);
-
-  for (const child of childRecords) {
-    const content = buildChildResearchContent({
-      id: child.id,
-      fileKey: child.fileKey,
-      familyKey: child.familyKey,
-      basename: child.basename,
+
+  const buildChildContent = (child, siblingBasenames) =>
+    buildChildResearchContent({
+      id: child.id ?? CLOUD_PENDING_ID,
+      fileKey: child.fileKey ?? CLOUD_PENDING_KEY,
+      familyKey: child.familyKey ?? CLOUD_PENDING_KEY,
+      basename: child.basename ?? '',
       name: child.name,
       originalBasename: research.basename,
-      siblingBasenames: childBasenames,
+      siblingBasenames,
       targetMilestone: child.targetMilestone,
       capturesBasenames: child.capturesBasenames,
       bodySlice: child.bodySlice,
@@ -745,42 +845,186 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
       today,
       author,
     });
-    child.unresolvedPlaceholderCount = findUnresolvedResearchPlaceholders(content);
-    writes.push({
-      kind: 'create',
-      absPath: join(vaultRoot, 'specs', 'research', `${child.basename}.md`),
-      content,
+
+  if (writeMode === 'cloud') {
+    // ── CREATE FIRST ────────────────────────────────────────────────────────
+    // Each child is POSTed with an EMPTY sibling list (a sibling's basename is
+    // minted by the console, so it cannot be known before that sibling's own
+    // POST answers), then re-PUT once every basename is in hand. The sibling
+    // cross-links live only in the "Split-from:" body callout, so the follow-up
+    // PUT replaces the BODY and keeps the frontmatter the console stored.
+    for (const child of childRecords) {
+      const content = buildChildContent(child, []);
+      child.unresolvedPlaceholderCount = findUnresolvedResearchPlaceholders(content);
+      const { frontmatter, body } = splitRawSpecForConsole(content);
+      const cleaned = stripServerMintedFields(frontmatter);
+      if (!child.familyKey) delete cleaned.family;
+      let created;
+      try {
+        created = await createSpecViaConsole({
+          ...cloudDeps,
+          type: 'research',
+          name: child.name,
+          frontmatter: cleaned,
+          body,
+          actingAgent: deps?.actingAgent ?? null,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'create', type: 'research', name: child.name },
+          completed: cloudCompleted,
+        });
+      }
+      child.id = created.specId;
+      child.basename = created.basename;
+      child.relPath = created.relPath;
+      child.cloudFrontmatter = created.spec?.frontmatter ?? cleaned;
+      cloudCompleted.push({
+        kind: 'create',
+        type: 'research',
+        spec_id: created.specId,
+        basename: created.basename,
+        rel_path: created.relPath,
+      });
+    }
+
+    const cloudChildBasenames = childRecords.map((c) => c.basename);
+
+    // ── …LINK SECOND: sibling callouts, then the original, then the captures.
+    if (childRecords.length > 1) {
+      for (const child of childRecords) {
+        const rebuilt = buildChildContent(child, cloudChildBasenames);
+        const { body } = splitRawSpecForConsole(rebuilt);
+        try {
+          const res = await updateSpecViaConsole({
+            ...cloudDeps,
+            specId: child.id,
+            frontmatter: child.cloudFrontmatter,
+            body,
+          });
+          cloudCompleted.push({
+            kind: 'update',
+            type: 'research.siblings',
+            spec_id: res.specId,
+            basename: res.basename ?? child.basename,
+            rel_path: res.relPath,
+          });
+        } catch (err) {
+          return cloudWriteFailureResult(err, {
+            step: { kind: 'update', type: 'research.siblings', basename: child.basename },
+            completed: cloudCompleted,
+          });
+        }
+      }
+    }
+
+    const originalUpdatedCloud = buildUpdatedOriginalContent(research.raw, {
+      childBasenames: cloudChildBasenames,
+      now,
+      today,
+      author,
     });
-  }
+    {
+      const { frontmatter, body } = splitRawSpecForConsole(originalUpdatedCloud);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: originalId,
+          frontmatter,
+          body,
+        });
+        cloudCompleted.push({
+          kind: 'update',
+          type: 'research.original',
+          spec_id: res.specId,
+          basename: res.basename ?? research.basename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: 'research.original', basename: research.basename },
+          completed: cloudCompleted,
+        });
+      }
+    }
 
-  const originalUpdated = buildUpdatedOriginalContent(research.raw, {
-    childBasenames,
-    now,
-    today,
-    author,
-  });
-  writes.push({
-    kind: 'update',
-    absPath: research.absPath,
-    content: originalUpdated,
-  });
+    for (const [capBasename, childList] of captureChildMap.entries()) {
+      const capRecord = captureRecords.get(capBasename);
+      if (!capRecord) continue;
+      const capUpdated = buildUpdatedCaptureContent(
+        capRecord.raw,
+        childList.map((c) => c.basename),
+        now,
+      );
+      if (capUpdated === capRecord.raw) continue;
+      const { frontmatter, body } = splitRawSpecForConsole(capUpdated);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: getScalarField(getFrontmatterBlock(capRecord.raw)?.block ?? '', 'id') ?? capBasename,
+          frontmatter,
+          body,
+        });
+        cloudCompleted.push({
+          kind: 'update',
+          type: 'capture',
+          spec_id: res.specId,
+          basename: res.basename ?? capBasename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: 'capture', basename: capBasename },
+          completed: cloudCompleted,
+        });
+      }
+    }
+  } else {
+    const childBasenames = childRecords.map((c) => c.basename);
+
+    for (const child of childRecords) {
+      const content = buildChildContent(child, childBasenames);
+      child.unresolvedPlaceholderCount = findUnresolvedResearchPlaceholders(content);
+      writes.push({
+        kind: 'create',
+        absPath: join(vaultRoot, 'specs', 'research', `${child.basename}.md`),
+        content,
+      });
+    }
 
-  for (const [capBasename, childList] of captureChildMap.entries()) {
-    const capAbs = join(vaultRoot, 'specs', 'captures', `${capBasename}.md`);
-    const capRaw = readFileSync(capAbs, 'utf8');
-    const capUpdated = buildUpdatedCaptureContent(capRaw, childList, now);
-    if (capUpdated !== capRaw) {
-      writes.push({ kind: 'update', absPath: capAbs, content: capUpdated });
+    const originalUpdated = buildUpdatedOriginalContent(research.raw, {
+      childBasenames,
+      now,
+      today,
+      author,
+    });
+    writes.push({
+      kind: 'update',
+      absPath: research.absPath,
+      content: originalUpdated,
+    });
+
+    for (const [capBasename, childList] of captureChildMap.entries()) {
+      const capAbs = join(vaultRoot, 'specs', 'captures', `${capBasename}.md`);
+      const capRaw = readFileSync(capAbs, 'utf8');
+      const capUpdated = buildUpdatedCaptureContent(
+        capRaw,
+        childList.map((c) => c.basename),
+        now,
+      );
+      if (capUpdated !== capRaw) {
+        writes.push({ kind: 'update', absPath: capAbs, content: capUpdated });
+      }
     }
-  }
 
-  const commitResult = commitWrites(writes);
-  if (!commitResult.ok) {
-    return {
-      error: 'WRITE_FAILED',
-      message: commitResult.error?.message ?? 'unknown write failure',
-      rollback_error: commitResult.error?.rollbackError,
-    };
+    const commitResult = commitWrites(writes, vaultRoot);
+    if (!commitResult.ok) {
+      return {
+        error: 'WRITE_FAILED',
+        message: commitResult.error?.message ?? 'unknown write failure',
+        rollback_error: commitResult.error?.rollbackError,
+      };
+    }
   }
 
   const anyChildStillStub = childRecords.some((c) => c.unresolvedPlaceholderCount > 0);
@@ -790,10 +1034,11 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
     archive_basename: research.basename,
     archive_path: research.relPath,
     archive_status_after: getScalarField(fm.block, 'status') ?? 'open',
+    ...(writeMode === 'cloud' ? { write_mode: 'cloud' } : {}),
     children: childRecords.map((c) => ({
       id: c.id,
       basename: c.basename,
-      path: join('specs', 'research', `${c.basename}.md`),
+      path: c.relPath ?? join('specs', 'research', `${c.basename}.md`),
       target_milestone: c.targetMilestone.absent ? 'NEW' : c.targetMilestone.basename,
       sources_captures: c.capturesBasenames,
       // Same placeholder count RESEARCH_STILL_STUB would later refuse
@@ -802,7 +1047,10 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
       research_still_stub: c.unresolvedPlaceholderCount > 0,
       unresolved_placeholder_count: c.unresolvedPlaceholderCount,
     })),
-    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    writes:
+      writeMode === 'cloud'
+        ? cloudCompleted.map((w) => ({ kind: w.kind, path: w.rel_path ?? null, spec_id: w.spec_id }))
+        : writes.map((w) => ({ kind: w.kind, path: w.absPath })),
     // No fallback warning: every child unconditionally inherits the
     // original's family key (V3 shared-surname model — see the block comment
     // above inheritedFamilyKey).

package/vendor/heyspex-mcp/stdio-rpc.mjs

@@ -0,0 +1,22 @@
+// JSON-RPC writers for the stdio transport — the only place the MCP server
+// writes to stdout. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+export function sendResponse(id, result) {
+  const response = { jsonrpc: '2.0', id, result };
+  process.stdout.write(JSON.stringify(response) + '\n');
+}
+
+export function sendError(id, code, message, data) {
+  const response = {
+    jsonrpc: '2.0',
+    id,
+    error: { code, message, ...(data && { data }) },
+  };
+  process.stdout.write(JSON.stringify(response) + '\n');
+}
+
+export function sendNotification(method, params) {
+  const notification = { jsonrpc: '2.0', method, params };
+  process.stdout.write(JSON.stringify(notification) + '\n');
+}