@animalabs/connectome-host 0.7.4 → 0.8.1

package/scripts/release-changelog.ts

@@ -1,32 +1,221 @@
 // Runs as npm's `version` lifecycle hook (see package.json): at that point
 // package.json already carries the new version, and files staged here are
 // included in the release commit that `npm version` then creates and tags.
-import { readFileSync, writeFileSync } from "node:fs";
+//
+// Folds the pending fragments in changelog.d/ (one file per change,
+// `<slug>.<breaking|added|changed|fixed>.md`) together with anything filed
+// directly under the standing `## Unreleased` section into a new
+// `## X.Y.Z — YYYY-MM-DD` section, deletes the consumed fragments, and
+// leaves a fresh empty `## Unreleased` above it. Refuses to release when
+// there is nothing to release, or when the input's shape is ambiguous.
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
 
-const { version } = JSON.parse(readFileSync("package.json", "utf8"));
-const path = "CHANGELOG.md";
-const text = readFileSync(path, "utf8");
+const CHANGELOG = "CHANGELOG.md";
+const FRAGMENT_DIR = "changelog.d";
+// Canonical subsection order; a fragment's category must be one of these.
+const CATEGORIES = ["breaking", "added", "changed", "fixed"] as const;
+type Category = (typeof CATEGORIES)[number];
+const HEADINGS: Record<Category, string> = {
+  breaking: "Breaking",
+  added: "Added",
+  changed: "Changed",
+  fixed: "Fixed",
+};
 
-const header = text.match(/^## Unreleased[ \t]*$/m);
-if (!header || header.index === undefined) {
-  console.error("CHANGELOG.md: no '## Unreleased' section — add one before releasing.");
-  process.exit(1);
+// Refusals throw and are reported at the entry point, which then lets the
+// process end on its own with exitCode 1. process.exit() would race the
+// stderr write when stderr is a pipe (asynchronous on macOS), leaving the
+// caller a bare failure status with no reason attached.
+class ReleaseError extends Error {}
+const fail = (msg: string): never => {
+  throw new ReleaseError(msg);
+};
+
+interface Fragment {
+  name: string;
+  category: Category;
+  body: string;
 }
 
-const escaped = version.replace(/[.]/g, "\\.");
-if (new RegExp(`^## ${escaped}([^0-9]|$)`, "m").test(text)) {
-  console.error(`CHANGELOG.md: a '## ${version}' section already exists.`);
-  process.exit(1);
+// Fragment grammar: every non-blank line starts a bullet or continues one
+// (indented two or more spaces; nested bullets included). Headings and
+// thematic breaks are refused wherever they appear — at top level a '## '
+// line would splice a fake section boundary into the released changelog,
+// and as item content ('- ## x', '  ## x') they still render as headings.
+const isBulletStart = (l: string): boolean => /^[-*] /.test(l);
+const isContinuation = (l: string): boolean => /^ {2,}\S/.test(l);
+const itemContent = (l: string): string => l.replace(/^\s*(?:[-*]\s+)?/, "");
+const isHeading = (s: string): boolean => /^#{1,6}(\s|$)/.test(s);
+// Thematic breaks may carry interior whitespace ('- - -', '* * *').
+const isRule = (s: string): boolean => /^([-*_=])(\s*\1){2,}\s*$/.test(s);
+const isBlockConstruct = (l: string): boolean =>
+  isRule(l.trim()) || isHeading(itemContent(l));
+
+// The directory is scanned fail-closed: anything that is not README.md or
+// a well-formed fragment file aborts the release, so an entry can never be
+// silently left out (e.g. a fragment created under a 'fix/' subdirectory
+// because the slug was taken verbatim from a branch name).
+function collectFragments(): Fragment[] {
+  const fragments: Fragment[] = [];
+  if (!existsSync(FRAGMENT_DIR)) return fragments;
+  const entries = readdirSync(FRAGMENT_DIR, { withFileTypes: true }).sort(
+    (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+  );
+  for (const entry of entries) {
+    const { name } = entry;
+    if (name === "README.md") continue;
+    if (!entry.isFile()) {
+      fail(
+        `${FRAGMENT_DIR}/${name}: not a file. Fragments are flat files directly ` +
+          `in ${FRAGMENT_DIR}/ — a slug cannot contain '/'; use the PR number, ` +
+          "or the branch name with '/' replaced by '-'.",
+      );
+    }
+    const m = name.match(/\.(breaking|added|changed|fixed)\.md$/);
+    if (!m) {
+      fail(
+        `${FRAGMENT_DIR}/${name}: unrecognized file — name fragments ` +
+          `'<slug>.<${CATEGORIES.join("|")}>.md' so the entry is not silently stranded.`,
+      );
+    }
+    const body = readFileSync(join(FRAGMENT_DIR, name), "utf8").trim();
+    if (!body) fail(`${FRAGMENT_DIR}/${name}: empty fragment.`);
+    const offending = body
+      .split("\n")
+      .find(
+        (l) =>
+          l.trim() !== "" &&
+          (!(isBulletStart(l) || isContinuation(l)) || isBlockConstruct(l)),
+      );
+    if (offending !== undefined) {
+      fail(
+        `${FRAGMENT_DIR}/${name}: a fragment is one or more markdown bullets ` +
+          "('- …'; continuation lines indented two spaces; no headings or " +
+          `rules) — offending line: '${offending}'.`,
+      );
+    }
+    fragments.push({ name, category: m[1] as Category, body });
+  }
+  return fragments;
 }
 
-const afterHeader = text.slice(header.index + header[0].length);
-const nextSection = afterHeader.search(/^## /m);
-const unreleasedBody = nextSection === -1 ? afterHeader : afterHeader.slice(0, nextSection);
-if (!/^\s*[-*] /m.test(unreleasedBody)) {
-  console.error(`CHANGELOG.md: '## Unreleased' has no entries — nothing to release as ${version}.`);
-  process.exit(1);
+// Merge fragment bullets into the Unreleased body's subsection structure.
+// Directly-filed entries are kept; a fragment joins the first subsection
+// whose title starts with its category (so audience-qualified headings like
+// '### Breaking (recipe authors only)' still attract 'breaking' fragments),
+// or a new canonical subsection. Output is emitted in canonical order.
+function mergeFragments(body: string, frags: Fragment[]): string {
+  interface Part {
+    title: string;
+    lines: string[];
+  }
+  const preamble: string[] = [];
+  const parts: Part[] = [];
+  let current: Part | null = null;
+  for (const line of body.split("\n")) {
+    const h = line.match(/^###\s+(.*)$/);
+    if (h) {
+      current = { title: (h[1] ?? "").trim(), lines: [] };
+      parts.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    } else {
+      preamble.push(line);
+    }
+  }
+  for (const f of frags) {
+    let part = parts.find((p) => p.title.toLowerCase().startsWith(f.category));
+    if (!part) {
+      part = { title: HEADINGS[f.category], lines: [] };
+      parts.push(part);
+    }
+    part.lines.push("", ...f.body.split("\n"));
+  }
+  const rank = (t: string): number => {
+    const i = CATEGORIES.findIndex((c) => t.toLowerCase().startsWith(c));
+    return i === -1 ? CATEGORIES.length : i;
+  };
+  const chunks: string[] = [];
+  const pre = preamble.join("\n").trim();
+  if (pre) chunks.push(pre);
+  for (const p of [...parts].sort((a, b) => rank(a.title) - rank(b.title))) {
+    const content = p.lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    chunks.push(content ? `### ${p.title}\n\n${content}` : `### ${p.title}`);
+  }
+  return chunks.join("\n\n");
+}
+
+function main(): void {
+  const { version } = JSON.parse(readFileSync("package.json", "utf8")) as {
+    version: string;
+  };
+  const text = readFileSync(CHANGELOG, "utf8");
+  const fragments = collectFragments();
+
+  // Exactly one Unreleased heading. A second one silently strands entries:
+  // only the first is ever cut, so anything filed under a later heading is
+  // never released and never reaches the GitHub release notes.
+  const headings = [...text.matchAll(/^## Unreleased[ \t]*$/gm)];
+  if (headings.length === 0) {
+    fail(`no '## Unreleased' section in ${CHANGELOG} — add one before releasing.`);
+  }
+  if (headings.length > 1) {
+    const lines = headings.map((m) => text.slice(0, m.index ?? 0).split("\n").length);
+    fail(
+      `${headings.length} '## Unreleased' headings (lines ${lines.join(", ")}). ` +
+        "Only the first is released; fold them into one before releasing.",
+    );
+  }
+  const header = headings[0]!;
+  const headerIndex = header.index ?? 0;
+
+  const escaped = version.replace(/[.]/g, "\\.");
+  if (new RegExp(`^## ${escaped}([^0-9]|$)`, "m").test(text)) {
+    fail(`a '## ${version}' section already exists.`);
+  }
+
+  const afterHeader = text.slice(headerIndex + header[0].length);
+  const nextSection = afterHeader.search(/^## /m);
+  const oldBody = nextSection === -1 ? afterHeader : afterHeader.slice(0, nextSection);
+  const rest = nextSection === -1 ? "" : afterHeader.slice(nextSection);
+
+  const merged = mergeFragments(oldBody, fragments);
+  if (!/^[ \t]*[-*] /m.test(merged)) {
+    fail(
+      `nothing to release as ${version} — no fragments in ${FRAGMENT_DIR}/ ` +
+        "and no entries under '## Unreleased'.",
+    );
+  }
+
+  // Spliced by index rather than string-replaced: `text.replace("## Unreleased", …)`
+  // would hit the first *substring* occurrence, which is not necessarily the
+  // heading the regex matched (an inline mention of `## Unreleased` in prose
+  // comes first) and would inject the version heading into the wrong place.
+  const date = new Date().toISOString().slice(0, 10);
+  writeFileSync(
+    CHANGELOG,
+    text.slice(0, headerIndex) +
+      `## Unreleased\n\n## ${version} — ${date}\n\n${merged}\n\n` +
+      rest,
+  );
+  for (const f of fragments) unlinkSync(join(FRAGMENT_DIR, f.name));
+  console.log(
+    `${CHANGELOG}: released '## ${version} — ${date}' from ${fragments.length} ` +
+      "fragment(s) plus the Unreleased section.",
+  );
 }
 
-const date = new Date().toISOString().slice(0, 10);
-writeFileSync(path, text.replace(header[0], `## Unreleased\n\n## ${version} — ${date}`));
-console.log(`CHANGELOG.md: cut Unreleased into '## ${version} — ${date}'.`);
+try {
+  main();
+} catch (e) {
+  if (!(e instanceof ReleaseError)) throw e;
+  console.error(`release-changelog: ${e.message}`);
+  process.exitCode = 1;
+}

package/src/cache-keepalive-log.ts

@@ -0,0 +1,41 @@
+// Where prompt-cache keepalive events get written.
+//
+// Every event goes to STDERR, deliberately and without exception.
+//
+// The host's systemd unit routes `StandardError` to
+// `<data>/service-stderr.log` and leaves stdout on the journal. That file is
+// where an operator actually looks — it is where `[inference-refusal]` and the
+// `[autobiographical]` lines live. Splitting keepalive events across two sinks
+// by severity means the routine ones land somewhere nobody greps.
+//
+// This is not hypothetical. On 2026-08-23 the keepalive ran correctly on
+// fable-cm for three hours — three clean refreshes, 523,102 tokens read each,
+// zero writes — while a monitor tailing service-stderr.log reported
+// `keepalive=0` the entire time, because `refreshed` was going to stdout. An
+// operator would have concluded the feature was dead. A background spender
+// that cannot be found in the log an operator reads is indistinguishable from
+// one that never ran.
+//
+// Volume does not justify splitting them: one refresh per lineage per ~50
+// minutes is nothing next to the compression chatter already in that file.
+
+import type { KeepaliveEvent } from '@animalabs/membrane';
+
+export const KEEPALIVE_LOG_PREFIX = '[cache-keepalive]';
+
+/** Render one event as a single log line. */
+export function formatKeepaliveEvent(event: KeepaliveEvent): string {
+  return `${KEEPALIVE_LOG_PREFIX} ${JSON.stringify(event)}`;
+}
+
+/**
+ * Write one keepalive event to the operator-visible log.
+ *
+ * `sink` exists for tests; production always uses stderr via the default.
+ */
+export function logKeepaliveEvent(
+  event: KeepaliveEvent,
+  sink: (line: string) => void = (line) => console.error(line),
+): void {
+  sink(formatKeepaliveEvent(event));
+}