@afokapu/atdd-flow 0.3.57 → 0.3.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.57",
+  "version": "0.3.59",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/core.ts

@@ -1,8 +1,9 @@
-import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { isDeepStrictEqual } from "node:util";
+import { Document, Scalar, parse as parseYaml, stringify as stringifyYaml, visit } from "yaml";
 
 export type Role = { address: string; branch: string; agent?: string; purpose?: string; worktree?: string; base?: string };
 export type Group = { role?: string; members?: string[] };
@@ -24,6 +25,8 @@ export type Desk = {
   /** Named commands that model portfolio entries may resolve through. */
   executables?: Record<string, string>;
   aliases?: Record<string, string>;
+  /** Model id used for a role when launch model selection falls back; unlisted roles use the strongest candidate. */
+  fallback_model?: Record<string, string>;
 };
 export type ModelCandidate = {
   id: string;
@@ -133,9 +136,48 @@ export const required = <T>(value: T | undefined, label: string) => {
   if (value === undefined || value === "") throw new Error(`Missing ${label}.`);
   return value;
 };
+const printOptions = { collectionStyle: "flow", flowCollectionPadding: false } as const;
+
+// What a faithful YAML round trip must return: JSON semantics, but never silently lossy.
+function expectedRoundTrip(value: unknown) {
+  return JSON.parse(JSON.stringify(value, (_key, entry) => {
+    if (typeof entry === "function" || typeof entry === "symbol" || typeof entry === "bigint") throw new Error("Value is not representable in YAML.");
+    if (typeof entry === "number" && !Number.isFinite(entry)) throw new Error("Value is not representable in YAML.");
+    return entry;
+  }));
+}
+
+// Tier 2 keeps multi-line text readable as block literals; tier 3 quotes every string.
+const printTiers: Array<(expected: unknown) => string> = [
+  (expected) => stringifyYaml(expected, printOptions),
+  (expected) => {
+    const document = new Document(expected, { ...printOptions, lineWidth: 0 });
+    visit(document, { Scalar: (_key, node) => { if (typeof node.value === "string" && node.value.includes("\n")) node.type = Scalar.BLOCK_LITERAL; } });
+    return document.toString();
+  },
+  (expected) => stringifyYaml(expected, { ...printOptions, lineWidth: 0, defaultStringType: "QUOTE_DOUBLE", defaultKeyType: "PLAIN" }),
+];
+
+// A parse error and a value mismatch are equally unsafe to publish, so both count as "does not round-trip".
+// Strict deep equality also catches silent coercions such as the string "null" becoming null.
+function roundTrips(text: string, expected: unknown) {
+  try { return isDeepStrictEqual(parseYaml(text), expected); }
+  catch { return false; }
+}
+
+/** Serializes and proves the text parses back to the same value; the first tier that does wins, otherwise fail closed. */
+function printVerified(value: unknown) {
+  const expected = expectedRoundTrip(value);
+  for (const tier of printTiers) {
+    const text = tier(expected);
+    if (roundTrips(text, expected)) return text;
+  }
+  throw new Error("Refusing to write YAML that does not parse back to the original value.");
+}
+
 export const yaml = {
   parse: <T>(text: string) => parseYaml(text) as T,
-  print: (value: unknown) => stringifyYaml(value, { collectionStyle: "flow", flowCollectionPadding: false }),
+  print: (value: unknown) => printVerified(value),
 };
 
 export function addressParts(address: string) {
@@ -176,7 +218,13 @@ export const paths = (root: string) => ({
 export async function atomicYaml(file: string, value: unknown) {
   await mkdir(dirname(file), { recursive: true });
   const temp = join(dirname(file), `.${basename(file)}.${randomUUID()}.tmp`);
-  await writeFile(temp, yaml.print(value), "utf8");
+  const text = yaml.print(value);
+  await writeFile(temp, text, "utf8");
+  // yaml.print already proved this text round-trips; compare the bytes on disk to it before the rename publishes them.
+  if ((await readFile(temp, "utf8")) !== text) {
+    await rm(temp, { force: true });
+    throw new Error(`Refusing to publish ${file}: written YAML does not round-trip.`);
+  }
   await rename(temp, file);
 }
 

package/src/pi-runtime-launch.ts

@@ -108,6 +108,15 @@ async function launchEligibleTasks(root: string, record: Seat, address: string)
   return eligible.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
 }
 
+/** Fallback is the role's configured model when set (failing closed if unavailable), else the strongest candidate. */
+function fallbackCandidate(config: Desk, role: string, candidates: ModelCandidate[], reason: string) {
+  const configured = config.fallback_model?.[role];
+  if (configured === undefined) return { candidate: candidates[0]! };
+  const candidate = candidates.find((entry) => entry.id === configured);
+  if (!candidate) throw new Error(`fallback_model.${role} names "${configured}", which is not an enabled model with an available executable in models.yaml; refusing launch.`);
+  return { candidate, appliedFallback: { role, model: candidate.id, reason } };
+}
+
 async function chooseLaunchModel(root: string, config: Desk, record: Seat, portfolio: ModelPortfolio, select: (input: ModelSelectionInput) => Promise<ModelSelectionResponse> = selectModel) {
   const candidates = availableModelCandidates(config, portfolio);
   if (!candidates.length) throw new Error("No enabled model in models.yaml has an available executable.");
@@ -128,7 +137,7 @@ async function chooseLaunchModel(root: string, config: Desk, record: Seat, portf
     const reason = !selection.available ? selection.reason : selection.confidence < 0.75
       ? `Jev model selection confidence is low (${selection.confidence}).`
       : `Jev selected a model outside the available portfolio: ${selection.selected_model}.`;
-    return { candidate: candidates[0]!, selection, fallback: reason };
+    return { selection, fallback: reason, ...fallbackCandidate(config, record.role, candidates, reason) };
   }
   return { candidate: required(candidates.find((entry) => entry.id === selection.selected_model), `selected model ${selection.selected_model}`), selection };
 }
@@ -390,7 +399,7 @@ async function verifyRuntime(launch: PreparedLaunch, pane: string, priorPath?: s
 
 function receiptSelection(launch: PreparedLaunch) {
   const { selection } = launch;
-  if (selection.fallback) return { result: "fallback", reason: selection.fallback };
+  if (selection.fallback) return { result: "fallback", reason: selection.fallback, ...(selection.appliedFallback ? { applied_fallback: selection.appliedFallback } : {}) };
   return { result: "selected", confidence: selection.selection.confidence,
     ...(selection.selection.available && selection.selection.model ? { model: selection.selection.model } : {}) };
 }