@starci/hfs 2.0.2 → 4.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starci/hfs",
-  "version": "2.0.2",
-  "description": "The HFS command line of a StarCi product repository: hfs check, init, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
+  "version": "4.0.0",
+  "description": "The HFS command line of a StarCi app (one repository: the root, be/ and fe/): hfs lint, check, scaffold app, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
   "type": "module",
   "license": "UNLICENSED",
   "private": false,
@@ -15,6 +15,7 @@
   "files": [
     "bin/hfs.mjs",
     "emit/**",
+    "lint/**",
     "scaffold/**",
     "report/**",
     "runtime/**",

package/report/sonar.mjs

@@ -1,13 +1,10 @@
-// hfs report: the ONE way the findings of the StarCi canon reach Sonar (contract change hfs-sonar-import).
-//
-//   hfs check --sonar <file>               writes every error-level finding of the check (repository, managed files and the whole
-//                                          architecture machine) as a Sonar Generic Issue Import document (SonarQube 10.3+ format:
-//                                          `{ rules, issues }`), engineId `starci-hfs`, rule id = the finding code
-//   hfs report <eslint|stylelint> <in> <out>
-//                                          converts the linter's own json output (`eslint -f json`, `stylelint --formatter json`)
-//                                          into the same document format, engineId `eslint` / `stylelint`, rule id = the linter's
-//                                          rule. Sonar's own ESLint import (sonar.eslint.reportPaths) is not used: it drops an issue
-//                                          on a file outside sonar.sources, and a stylelint result has no native import at all.
+// Sonar documents of the ONE lint entry `hfs lint` (contract changes hfs-sonar-import, hfs-lint-entry): the building blocks that turn the
+// findings of the StarCi canon into a Sonar Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`).
+//   sonarReport(findings)        the repository findings of `hfs check`, engineId `starci-hfs`, rule id = the finding code
+//   linterReport(kind, results)  a linter's own json output (`eslint -f json`, `stylelint --formatter json`), engineId `eslint` / `stylelint`,
+//                                rule id = the linter's rule. Sonar's own ESLint import (sonar.eslint.reportPaths) is not used: it drops an
+//                                issue on a file outside sonar.sources, and a stylelint result has no native import at all.
+//   mergeReports(reports)        the documents of one `hfs lint` run as ONE file (reports/lint.sonar.json, sonar.externalIssuesReportPaths)
 // One placement rule for every engine: Sonar imports an issue only on a file it indexes (a tracked source or stylesheet under
 // sonar.sources). A finding on any other path (hfs.json, a workflow, a package under an unindexed root, e2e/, a directory) is filed
 // on the first source file of sonar.sources and its message names the real path, so no finding is dropped.
@@ -42,6 +39,12 @@ function document(rules, issues) {
   return { rules: [...rules.values()].filter((rule) => used.has(rule.id)).sort((a, b) => cmp(a.id, b.id)), issues: sorted };
 }
 
+/** One document of several (the starci-hfs, eslint and stylelint documents of one `hfs lint` run): rules by id, issues in the one sort order. */
+export function mergeReports(reports) {
+  const rules = new Map(reports.flatMap((report) => report.rules).map((rule) => [rule.id, rule]));
+  return document(rules, reports.flatMap((report) => report.issues));
+}
+
 /**
  * The first source file of the repository (sorted) under one of `sourceRoots`: Sonar imports an issue only on a file it
  * indexes, and a finding about hfs.json, a workflow, a config file or a directory is not on one, so it is filed on this
@@ -106,7 +109,6 @@ const LINTERS = Object.freeze({
     text: (message) => message.message,
     describe: (id) => `ESLint rule ${id} of the StarCi canon (@starci/eslint-canon-be and @starci/eslint-canon-fe) or of a plugin it composes.`,
     describeError: 'ESLint could not lint a file: a parse error or an invalid configuration.',
-    shape: 'an array of results with a filePath and messages',
   },
   stylelint: {
     engine: STYLELINT_ENGINE,
@@ -117,11 +119,10 @@ const LINTERS = Object.freeze({
     text: stylelintText,
     describe: (id) => `Stylelint rule ${id} of the StarCi CSS canon (@starci/stylelint-canon, HFS R61).`,
     describeError: 'Stylelint could not read a stylesheet: a parse error or an invalid option.',
-    shape: 'an array of results with a source and warnings',
   },
 });
 
-export const LINTER_KINDS = Object.freeze(Object.keys(LINTERS));
+const LINTER_KINDS = Object.freeze(Object.keys(LINTERS));
 
 /**
  * A linter's json results (`eslint -f json`: [{ filePath, messages: [{ ruleId, line, endLine, message }] }]; `stylelint
@@ -162,19 +163,3 @@ export function writeReport(file, report) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, `${JSON.stringify(report, null, 2)}\n`);
 }
-
-/** `hfs report <eslint|stylelint> <in> <out> [--repo <dir>]`: convert a linter's json report; returns the number of issues written. */
-export function convertReportFile({ kind, input, output, root, sourceRoots = [], tracked = [] }) {
-  const linter = LINTERS[kind];
-  if (linter === undefined) throw new Error(`unknown linter ${kind}; expected ${LINTER_KINDS.join(' or ')}`);
-  let results;
-  try {
-    results = JSON.parse(fs.readFileSync(input, 'utf8'));
-  } catch (error) {
-    throw new Error(`${input} is not a readable ${kind} json report (${error.message})`);
-  }
-  if (!Array.isArray(results)) throw new Error(`${input} is not a ${kind} json report: expected ${linter.shape}`);
-  const report = linterReport(kind, results, { root, sourceRoots, tracked });
-  writeReport(output, report);
-  return report.issues.length;
-}

package/runtime/engine/admission.mjs

@@ -72,9 +72,9 @@ const leasePath=resourceKey=>String(resourceKey??'').startsWith(PATH_LEASE_PREFI
  * The spelling two lease paths are compared in. The same file must compare equal however a workflow
  * spelled it (nivo wf-nivo-fe-debt-mug06w7h inc-52a4a5ee5b12: `apps/app/src/messages/vi.json` bare for
  * the fe repository vs `nivo-fe/apps/app/src/messages` repository-prefixed never overlapped). `canonicalOf`
- * (scripts/kernel/lease-canon.mjs) resolves a path to its repository-qualified form
- * `repository:<role>/<path>` — for a held row through its holder job, so a lease taken before
- * canonical keys existed still conflicts; paths on Windows compare case-insensitively, as its file
+ * (scripts/kernel/lease-canon.mjs) resolves a path to its app-relative form in a bound app
+ * (be/<path>, fe/<path>) — for a held row through its holder job, so every spelling of one file
+ * compares as one key; paths on Windows compare case-insensitively, as its file
  * systems do.
  */
 export const leaseCompareForm=(leasePathValue,{canonicalOf=null,row=null,platform=process.platform}={})=>{

package/runtime/engine/ledger-db.mjs

@@ -54,7 +54,7 @@ export const JOB_ARTIFACT_ROLES=Object.freeze(['check-output','check-stdout','ch
   'direction','prompt','render','redline','critique','capture','dom','screenshot','video','trace','uat-run','metrics','salvage','scan','other']);
 
 export const LEDGER_SCHEMA='starci/runtime@1';
-export const LEDGER_VERSION=4;
+export const LEDGER_VERSION=5;
 
 const need=(ok,message,code)=>{if(!ok)throw Object.assign(Error(message),code?{code}:{});};
 const json=value=>value===undefined||value===null?null:JSON.stringify(value);
@@ -127,7 +127,7 @@ const INIT_SQL_FILE=new URL('./migrations/runtime/0001-init.sql',import.meta.url
 const INIT_SQL=fs.readFileSync(INIT_SQL_FILE,'utf8');
 const INIT_SQL_SHA=sha256(INIT_SQL);
 /** Forward migrations after 0001-init, in order; each bumps user_version to its `version` (migrateLedger). */
-const FORWARD_MIGRATIONS=Object.freeze([{version:3,name:'0003-usage-unavailable'},{version:4,name:'0004-attempt-why'}]);
+const FORWARD_MIGRATIONS=Object.freeze([{version:3,name:'0003-usage-unavailable'},{version:4,name:'0004-attempt-why'},{version:5,name:'0005-ended-workflow-views'}]);
 export const LEDGER_BUSY_TIMEOUT_MS=15000;
 /**
  * Writer pragmas. wal_autocheckpoint=0 on EVERY connection except the one checkpointer (openLedger({checkpointer:true}),

package/runtime/engine/machine-db.mjs

@@ -1,4 +1,4 @@
-// engine/machine-db.mjs — the ONE writer of machine.sqlite (DBTREE.sql Part B, schema 'starci/machine@1', user_version 1).
+// engine/machine-db.mjs — the ONE writer of machine.sqlite (DBTREE.sql Part B, schema 'starci/machine@1', user_version MACHINE_VERSION).
 //
 // machine.sqlite is the host's single operational store: the ledger registry, the Supervisor (sup_*), the engine
 // reconciler (process_runs, engine_leader, leader_history, schedules, engine_actions, controller_modes, sla_episodes),
@@ -24,8 +24,9 @@
 //              and the next flushOutbox (the land gate) applies it. Only idempotent writers are deferrable (DEFERRABLE).
 //   reader   : readOnly, query_only=ON, busy_timeout=15000
 //   startup  : sqlite_version, node_version, journal_mode and user_version are recorded in machine_meta; an old-schema file
-//              (anything that is not 'starci/machine@1') is refused, never migrated — a fresh machine.sqlite is
-//              created by openMachine on first use.
+//              (anything that is not 'starci/machine@1') is refused — a fresh machine.sqlite is created by openMachine on
+//              first use. A starci/machine@1 file at an older user_version is brought forward by migrateMachine
+//              (engine/migrations/machine/000N-*.sql after 0001-init) on the first writer open.
 // Nothing outside engine/ opens machine.sqlite with `new DatabaseSync`: callers use openMachine / openMachineReader /
 // withMachine / readMachine and the typed functions on the handle.
 import fs from 'node:fs';
@@ -42,7 +43,9 @@ import { redactBytes, redactData, redactText } from '../scripts/lib/redact.mjs';
 const require = createRequire(import.meta.url);
 const ENGINE_DIR = path.dirname(fileURLToPath(import.meta.url));
 export const MACHINE_SCHEMA = 'starci/machine@1';
-export const MACHINE_VERSION = 1;
+export const MACHINE_VERSION = 2;
+/** Forward migrations after 0001-init, in order; each bumps user_version to its `version` (migrateMachine). */
+export const MACHINE_MIGRATIONS = Object.freeze([{ version: 2, name: '0002-worktrees-no-workflow-kind' }]);
 export const MACHINE_BUSY_TIMEOUT_MS = 15000;
 /** Test seam: STARCI_MACHINE_BUSY_TIMEOUT_MS (a positive integer) replaces the writer's busy_timeout; unset in production. */
 export const busyTimeoutOf = (env = process.env) => { const n = Number(env?.STARCI_MACHINE_BUSY_TIMEOUT_MS); return Number.isInteger(n) && n > 0 ? n : MACHINE_BUSY_TIMEOUT_MS; };
@@ -256,7 +259,7 @@ export const compareRevs = (a, b) => { const t = (r) => (/^\d{13}:/.test(String(
 
 /** An old or foreign store: refuse it; a fresh store is created by openMachine on first use. */
 function refuseOld(file, why) {
-  throw Object.assign(Error(`machine-schema-old: ${path.resolve(file)} ${why}; this runtime opens only '${MACHINE_SCHEMA}' (user_version ${MACHINE_VERSION}) — move the refused file aside and openMachine creates a fresh machine.sqlite on first use`),
+  throw Object.assign(Error(`machine-schema-old: ${path.resolve(file)} ${why}; this runtime opens only '${MACHINE_SCHEMA}' (user_version 1..${MACHINE_VERSION}) — move the refused file aside and openMachine creates a fresh machine.sqlite on first use`),
     { code: 'STARCI_MACHINE_SCHEMA_OLD' });
 }
 
@@ -267,7 +270,51 @@ function checkSchema(db, file) {
   const schema = db.prepare("SELECT value FROM machine_meta WHERE key='schema'").get()?.value;
   if (schema !== MACHINE_SCHEMA) refuseOld(file, `is schema '${schema ?? 'none'}'`);
   if (version > MACHINE_VERSION) throw Object.assign(Error(`machine-schema-newer: ${file} user_version ${version} > ${MACHINE_VERSION}; upgrade the runtime`), { code: 'STARCI_MACHINE_SCHEMA_NEWER' });
-  if (version !== MACHINE_VERSION) refuseOld(file, `is user_version ${version}`);
+  // 1..MACHINE_VERSION: an older version is brought forward on the first writer open (migrateMachine); a reader reads it as is.
+  if (!(version >= 1)) refuseOld(file, `is user_version ${version}`);
+}
+
+/**
+ * Bring an older machine.sqlite forward: for each MACHINE_MIGRATIONS entry above user_version and not yet in schema_migrations -
+ * integrity_check and a VACUUM INTO backup (`<file>.pre-<name>.bak`, skipped for a store created by this open) first, then in one
+ * transaction the migration SQL, schema_version+1, user_version, its schema_migrations row, foreign_key_check and quick_check
+ * before COMMIT. Idempotent and safe across processes (re-checked under the lock). Returns the names applied.
+ */
+export function migrateMachine(db, { file, now = Date.now, backup: wantBackup = true } = {}) {
+  const version = () => Number(pragma(db, 'user_version'));
+  const pending = () => MACHINE_MIGRATIONS.filter((m) => version() < m.version && !db.prepare('SELECT 1 FROM schema_migrations WHERE version=?').get(m.version));
+  if (!pending().length) return [];
+  const check = db.prepare('PRAGMA integrity_check').all();
+  need(check.length === 1 && check[0].integrity_check === 'ok', `machine-migrate-refused: ${file} fails integrity_check`, 'STARCI_MACHINE_MIGRATE_REFUSED');
+  const applied = [];
+  for (const m of pending()) {
+    const sql = fs.readFileSync(path.join(ENGINE_DIR, 'migrations', 'machine', `${m.name}.sql`), 'utf8');
+    const backup = wantBackup && file ? `${path.resolve(file)}.pre-${m.name}.bak` : null;
+    if (backup && !fs.existsSync(backup)) db.exec(`VACUUM INTO '${backup.replace(/'/g, "''")}'`);
+    db.exec('BEGIN IMMEDIATE');
+    let relaxed = false;
+    try {
+      if (version() >= m.version) { db.exec('ROLLBACK'); continue; }
+      if (typeof db.enableDefensive === 'function') { db.enableDefensive(false); relaxed = true; }   // writable_schema is refused while defensive
+      const started = now();
+      db.exec(sql);
+      db.exec(`PRAGMA schema_version=${Number(pragma(db, 'schema_version')) + 1}`);
+      db.exec('PRAGMA writable_schema=OFF');
+      db.exec(`PRAGMA user_version=${m.version}`);
+      db.prepare("INSERT INTO schema_migrations(version,name,runtime_rev,sql_sha256,backup_path,started_at,finished_at,status) VALUES(?,?,?,?,?,?,?,'done')")
+        .run(m.version, m.name, runtimeRev(), sha256(sql), backup, started, now());
+      need(db.prepare('PRAGMA foreign_key_check').all().length === 0, `machine-migrate-failed: ${m.name} left a foreign key violation`, 'STARCI_MACHINE_MIGRATE_FAILED');
+      const quick = db.prepare('PRAGMA quick_check').all();
+      need(quick.length === 1 && quick[0].quick_check === 'ok', `machine-migrate-failed: ${m.name} fails quick_check`, 'STARCI_MACHINE_MIGRATE_FAILED');
+      db.exec('COMMIT');
+      applied.push(m.name);
+    } catch (error) {
+      try { db.exec('ROLLBACK'); } catch { /* none */ }
+      try { db.exec('PRAGMA writable_schema=OFF'); } catch { /* none */ }
+      throw error;
+    } finally { if (relaxed) db.enableDefensive(true); }
+  }
+  return applied;
 }
 
 function createSchema(db, { file, env, now }) {
@@ -288,7 +335,7 @@ function createSchema(db, { file, env, now }) {
         db.prepare("INSERT INTO mode_changes(controller,from_mode,to_mode,by,reason,at) VALUES(?,NULL,'shadow','machine-db:init','0001-init',?)").run(controller, at);
         db.prepare("INSERT INTO controller_modes(controller,mode,set_at,set_by) VALUES(?,'shadow',?,'machine-db:init')").run(controller, at);
       }
-      db.exec(`PRAGMA user_version=${MACHINE_VERSION}`);
+      db.exec('PRAGMA user_version=1');   // 0001; the forward files follow in migrateMachine
     }
     db.exec('COMMIT');
   } catch (error) { try { db.exec('ROLLBACK'); } catch { /* none */ } throw error; }
@@ -327,6 +374,7 @@ function openConnection(file, { readOnly = false, env = process.env, now = Date.
         createSchema(db, { file, env, now });
       }
       checkSchema(db, file);
+      migrateMachine(db, { file, now, backup: !fresh });
       recordFacts(db);
       return db;
     } catch (error) {
@@ -1254,6 +1302,39 @@ const pushes = (m, { repoRoot = null, limit = 50 } = {}) => m.db.prepare(`SELECT
 const upsertWorktree = (m, wt) => upsertRow(m.db, 'worktrees', { created_at: m.now(), ...snake(wt), path: path.resolve(wt.path) }, ['path']);
 const removedWorktree = (m, wtPath, { error = null, archivedRef = null } = {}) => m.db.prepare('UPDATE worktrees SET removed_at=CASE WHEN ? IS NULL THEN ? ELSE removed_at END, remove_error=?, archived_ref=COALESCE(?,archived_ref) WHERE path=?')
   .run(error, m.now(), error, archivedRef, path.resolve(wtPath)).changes > 0;
+/**
+ * The worktree registry (scripts/lib/worktrees.mjs is its one caller): reserve a row for a worktree about to be created,
+ * atomically against the per-repo cap. BEGIN IMMEDIATE: two dispatches never both take the last slot. `cap` null: no cap.
+ * {ok, live} | {ok:false, reason:'worktree-cap', live, cap}
+ */
+function reserveWorktree(m, wt, { cap = null } = {}) {
+  return m.transaction((db) => {
+    const repoRoot = repoKey(wt.repoRoot);
+    const target = path.resolve(wt.path);
+    const live = db.prepare('SELECT path FROM worktrees WHERE repo_root=? AND removed_at IS NULL').all(repoRoot).filter((r) => r.path !== target).length;
+    if (cap != null && live >= cap) return { ok: false, reason: 'worktree-cap', live, cap };
+    upsertRow(db, 'worktrees', { ...snake(wt), path: target, repo_root: repoRoot, created_at: m.now(), removed_at: null, remove_error: null }, ['path']);
+    return { ok: true, live: live + 1 };
+  });
+}
+/** Live (not removed) registry rows, optionally of one repo. */
+const liveWorktrees = (m, { repoRoot = null } = {}) => m.db.prepare(`SELECT * FROM worktrees WHERE removed_at IS NULL ${repoRoot ? 'AND repo_root=?' : ''} ORDER BY created_at`)
+  .all(...(repoRoot ? [repoKey(repoRoot)] : []));
+const worktreeRow = (m, wtPath) => m.db.prepare('SELECT * FROM worktrees WHERE path=?').get(path.resolve(wtPath)) ?? null;
+/** Every repo the registry ever held a worktree of. */
+const worktreeRepos = (m) => m.db.prepare('SELECT DISTINCT repo_root FROM worktrees ORDER BY repo_root').all().map((r) => r.repo_root);
+/** A reservation whose `git worktree add` failed: the row goes, nothing was created. */
+/** A GC collector's resume point (machine_meta gc_cursor:<name>): where its last bounded pass stopped, or null. */
+const gcCursor = (m, name) => m.db.prepare('SELECT value FROM machine_meta WHERE key=?').get(`gc_cursor:${name}`)?.value ?? null;
+const setGcCursor = (m, name, value) => (value == null
+  ? m.db.prepare('DELETE FROM machine_meta WHERE key=?').run(`gc_cursor:${name}`)
+  : m.db.prepare('INSERT INTO machine_meta(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run(`gc_cursor:${name}`, String(value))).changes > 0;
+/** The worktree GC's stop mark (a removal changed the main checkout): {at, damage, path} or null. set(null) clears it. */
+const worktreeGcStop = (m) => parse(m.db.prepare("SELECT value FROM machine_meta WHERE key='worktree_gc_stopped'").get()?.value ?? null);
+const setWorktreeGcStop = (m, stop) => (stop
+  ? m.db.prepare("INSERT INTO machine_meta(key,value) VALUES('worktree_gc_stopped',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(JSON.stringify(stop))
+  : m.db.prepare("DELETE FROM machine_meta WHERE key='worktree_gc_stopped'").run()).changes > 0;
+const dropWorktree = (m, wtPath) => m.db.prepare('DELETE FROM worktrees WHERE path=? AND removed_at IS NULL').run(path.resolve(wtPath)).changes > 0;
 const upsertEnvServer = (m, server) => upsertRow(m.db, 'env_servers', snake(server), ['server_id']);
 const envServer = (m, serverId) => m.db.prepare('SELECT * FROM env_servers WHERE server_id=?').get(serverId) ?? null;
 const envServers = (m, { live = false } = {}) => m.db.prepare(`SELECT * FROM env_servers ${live ? "WHERE state IN ('starting','ready')" : ''} ORDER BY server_id`).all();
@@ -1443,13 +1524,13 @@ const API = {
   upsertGuardJob, guardJob, releaseGuardJob, recordGuardRefusal, releaseHostLeases, release: releaseHostLeases, hostLeases, setBudget, reserveBudget, settleBudget, budgets,
   startGcRun, finishGcRun, recordGcItem, addGcItem: recordGcItem, updateGcItem, gcItems, gcMark, addGcMarks: gcMark, gcRuns, markMachineBlobArchived, pruneSeatSnapshots,
   upsertLane, setLaneState, laneOf, lanes, enqueueLand, claimLandGate, finishLandTicket, landQueue, recordLandRun, recordLandOutcome, landRuns, recordPush, pushes, flushOutbox,
-  upsertWorktree, removedWorktree, upsertEnvServer, envServer, envServers, upsertUatSlot, uatSlots, releaseUatSlot, upsertConnector, connectorOf, upsertAsk,
+  upsertWorktree, removedWorktree, reserveWorktree, liveWorktrees, worktreeRow, worktreeRepos, dropWorktree, worktreeGcStop, setWorktreeGcStop, gcCursor, setGcCursor, upsertEnvServer, envServer, envServers, upsertUatSlot, uatSlots, releaseUatSlot, upsertConnector, connectorOf, upsertAsk,
   log, logs, pruneLogs, recordMetrics, latestMetrics, recordNotification, notificationSent, markNotificationSent, recordArchive, projectCatalog,
 };
 
 /** Every typed function at module level too: fn(handle, ...args) — blob-gc and callers holding a handle. */
 export {
-  putMachineBlob, jsonOrBlob, meta, checkpoint, registerLedger, resolveLedger, listLedgers, touchLedger, setLedgerState, upsertRepository, forEachLedger, attachFleet, supEvent, supEvents, newestSupEvent, upsertSupJob, setSupJobStatus, supJob, listSupJobs, acquireSupLeases, releaseSupLeases, supLeases, startSupAttempt, updateSupAttempt, latestSupAttempt, recordSupReport, supReports, consumeSupReport, openSupDecision, setSupDecision, markSupDecisionDelivered, listSupDecisions, openOwed, ackOwed, closeOwed, listOwed, upsertLearning, listLearning, recordOwnerRuling, upsertBridge, recordSupMessage, supMessages, markSupMessagesRead, setSupSignal, supSignal, clearSupSignal, recordMachineLlmUsage, startProcessRun, heartbeatProcessRun, endProcessRun, openProcessRuns, processRuns, leaderOf, acquireLeader, renewLeader, releaseLeader, leaderHistory, cursorOf, setCursor, cursors, enqueue, dueQueue, queueRows, dequeue, requeue, ensureSchedule, claimSchedule, finishSchedule, schedules, actionIntent, actionRunning, actionFinish, markStaleActionsUnknown, actionOf, actions, actionStep, controllerModes, setControllerMode, modeChanges, openSlaEpisode, markSlaViolated, markSlaReported, clearSla, openSla, recordViolation, clearViolation, setService, recordProbe, services, serviceEvents, upsertSeat, seatOf, seats, recordDelivery, recordSeatInput, startSeatTurn, endSeatTurn, seatTranscriptSnapshot, upsertTerminal, closeTerminal, openTerminals, acquireHostLock, renewHostLock, releaseHostLock, hostLock, hostLocks, claimResource, releaseClaim, sweptClaim, liveClaims, upsertAgentSession, inventorySnapshot, throttleState, setThrottle, throttleEvents, recordThrottleDecision, releaseThrottleDecision, recordHostSample, hostSamples, setProviderHealth, providerHealth, poolBackoff, setPoolBackoff, clearPoolBackoff, setQuota, quotas, upsertGuardJob, guardJob, releaseGuardJob, recordGuardRefusal, releaseHostLeases, hostLeases, setBudget, reserveBudget, settleBudget, budgets, startGcRun, finishGcRun, recordGcItem, updateGcItem, gcItems, gcMark, gcRuns, markMachineBlobArchived, pruneSeatSnapshots, upsertLane, setLaneState, laneOf, lanes, enqueueLand, claimLandGate, finishLandTicket, landQueue, recordLandRun, recordLandOutcome, landRuns, recordPush, pushes, flushOutbox, upsertWorktree, removedWorktree, upsertEnvServer, envServer, envServers, upsertUatSlot, uatSlots, releaseUatSlot, upsertConnector, connectorOf, upsertAsk, log, logs, pruneLogs, recordMetrics, latestMetrics, recordNotification, notificationSent, markNotificationSent, recordArchive, projectCatalog,
+  putMachineBlob, jsonOrBlob, meta, checkpoint, registerLedger, resolveLedger, listLedgers, touchLedger, setLedgerState, upsertRepository, forEachLedger, attachFleet, supEvent, supEvents, newestSupEvent, upsertSupJob, setSupJobStatus, supJob, listSupJobs, acquireSupLeases, releaseSupLeases, supLeases, startSupAttempt, updateSupAttempt, latestSupAttempt, recordSupReport, supReports, consumeSupReport, openSupDecision, setSupDecision, markSupDecisionDelivered, listSupDecisions, openOwed, ackOwed, closeOwed, listOwed, upsertLearning, listLearning, recordOwnerRuling, upsertBridge, recordSupMessage, supMessages, markSupMessagesRead, setSupSignal, supSignal, clearSupSignal, recordMachineLlmUsage, startProcessRun, heartbeatProcessRun, endProcessRun, openProcessRuns, processRuns, leaderOf, acquireLeader, renewLeader, releaseLeader, leaderHistory, cursorOf, setCursor, cursors, enqueue, dueQueue, queueRows, dequeue, requeue, ensureSchedule, claimSchedule, finishSchedule, schedules, actionIntent, actionRunning, actionFinish, markStaleActionsUnknown, actionOf, actions, actionStep, controllerModes, setControllerMode, modeChanges, openSlaEpisode, markSlaViolated, markSlaReported, clearSla, openSla, recordViolation, clearViolation, setService, recordProbe, services, serviceEvents, upsertSeat, seatOf, seats, recordDelivery, recordSeatInput, startSeatTurn, endSeatTurn, seatTranscriptSnapshot, upsertTerminal, closeTerminal, openTerminals, acquireHostLock, renewHostLock, releaseHostLock, hostLock, hostLocks, claimResource, releaseClaim, sweptClaim, liveClaims, upsertAgentSession, inventorySnapshot, throttleState, setThrottle, throttleEvents, recordThrottleDecision, releaseThrottleDecision, recordHostSample, hostSamples, setProviderHealth, providerHealth, poolBackoff, setPoolBackoff, clearPoolBackoff, setQuota, quotas, upsertGuardJob, guardJob, releaseGuardJob, recordGuardRefusal, releaseHostLeases, hostLeases, setBudget, reserveBudget, settleBudget, budgets, startGcRun, finishGcRun, recordGcItem, updateGcItem, gcItems, gcMark, gcRuns, markMachineBlobArchived, pruneSeatSnapshots, upsertLane, setLaneState, laneOf, lanes, enqueueLand, claimLandGate, finishLandTicket, landQueue, recordLandRun, recordLandOutcome, landRuns, recordPush, pushes, flushOutbox, upsertWorktree, removedWorktree, reserveWorktree, liveWorktrees, worktreeRow, worktreeRepos, dropWorktree, worktreeGcStop, setWorktreeGcStop, gcCursor, setGcCursor, upsertEnvServer, envServer, envServers, upsertUatSlot, uatSlots, releaseUatSlot, upsertConnector, connectorOf, upsertAsk, log, logs, pruneLogs, recordMetrics, latestMetrics, recordNotification, notificationSent, markNotificationSent, recordArchive, projectCatalog,
 };
 export const addGcItem = recordGcItem;
 export const addGcMarks = gcMark;

package/runtime/engine/migrations/machine/0002-worktrees-no-workflow-kind.sql

@@ -0,0 +1,13 @@
+-- 0002-worktrees-no-workflow-kind (starci/machine@1, user_version 1 -> 2). Applied by engine/machine-db.mjs migrateMachine on
+-- the first writer open of an older machine.sqlite (after an integrity_check and a VACUUM INTO backup, with foreign_key_check
+-- + quick_check before COMMIT); a fresh machine.sqlite runs 0001 then the forward files.
+--
+-- The per-workflow worktree is removed: a workflow owns no checkout of its own, an op works in its job worktree and a land
+-- in its scratch. worktrees.kind no longer accepts 'workflow'. A row of that kind describes the removed mechanism and is
+-- deleted (a directory it named, if any is left, is an unregistered worktree the worktree GC and the footprint scan report);
+-- then the table's CHECK is rewritten in place (writable_schema: the views over worktrees stay as they are).
+DELETE FROM worktrees WHERE kind='workflow';
+PRAGMA writable_schema=ON;
+UPDATE sqlite_master
+   SET sql=replace(sql, 'CHECK(kind IN (''op'',''workflow'',''land-scratch'',', 'CHECK(kind IN (''op'',''land-scratch'',')
+ WHERE type='table' AND name='worktrees';

package/runtime/engine/migrations/runtime/0005-ended-workflow-views.sql

@@ -0,0 +1,93 @@
+-- 0005-ended-workflow-views (starci/runtime@1, user_version 4 -> 5). Applied by engine/ledger-db.mjs migrateLedger on the first
+-- writer open of an older ledger (after a VACUUM INTO backup and an integrity_check, with foreign_key_check + quick_check
+-- before COMMIT); a fresh ledger runs 0001 then the forward files.
+--
+-- The runtime views stop surfacing the live leftovers of an ENDED workflow (phase archived|finished): archive/finish close
+-- the workflow's live Decision Items inside their own transaction before the phase flips, and events_refuse_archived refuses
+-- every later write, so a leftover live DI (2026-09-30 nivo-backend di-876124d7) can never be resolved and only ever reads
+-- 'bad' in the UI — a permanent attention item and blocker on work that no longer runs. Every leg carries the ENDED
+-- predicate of scripts/reconciler/decisions.mjs listDecisions: LEFT JOIN workflows w; the row survives when its workflow is
+-- missing or not ended (w.phase IS NULL OR w.phase NOT IN ('archived','finished')).
+--   v_decision_rows  keeps an ended workflow's resolved rows (decision history) and drops only its live-status leftovers;
+--   v_blocking       applies the join per UNION leg — an ended workflow owes no unit, decision, condition, incident,
+--                    worker-question, settle-tail, product-land or settle-overdue row;
+--   v_open_work      the same per leg (decision + job).
+DROP VIEW IF EXISTS v_decision_rows;
+DROP VIEW IF EXISTS v_blocking;
+DROP VIEW IF EXISTS v_open_work;
+CREATE VIEW v_decision_rows AS
+SELECT d.*,
+       (d.due_at IS NOT NULL AND d.status IN ('open','claimed','escalated') AND d.due_at < CAST(unixepoch('subsec')*1000 AS INTEGER)) AS overdue,
+       CASE WHEN d.status IN ('open','claimed','escalated')
+                 AND ((d.due_at IS NOT NULL AND d.due_at < CAST(unixepoch('subsec')*1000 AS INTEGER)) OR d.escalations>=2) THEN 'bad'
+            WHEN d.status='open' AND d.due_at IS NOT NULL
+                 AND (d.due_at - CAST(unixepoch('subsec')*1000 AS INTEGER)) < 0.2*(d.due_at - d.opened_at) THEN 'warn'
+            ELSE COALESCE(m.ui,'unknown') END AS ui
+FROM decision_items d LEFT JOIN ui_state_map m ON m.entity='decision' AND m.native=d.status
+                      LEFT JOIN workflows w ON w.workflow_id=d.workflow_id
+WHERE d.status NOT IN ('open','claimed','escalated') OR w.phase IS NULL OR w.phase NOT IN ('archived','finished');
+
+CREATE VIEW v_blocking AS
+SELECT e.workflow_id, 'unit' AS entity_type, e.to_unit AS entity_id, 'unit' AS blocker_type, e.from_unit AS blocker_id,
+       'UpstreamNotDone' AS reason_code, p.state AS detail, p.updated_at AS since, 'kernel' AS who
+  FROM unit_edges e JOIN work_units t ON t.workflow_id=e.workflow_id AND t.unit_id=e.to_unit
+                    JOIN work_units p ON p.workflow_id=e.workflow_id AND p.unit_id=e.from_unit
+                    LEFT JOIN workflows w ON w.workflow_id=e.workflow_id
+ WHERE t.state IN ('planned','queued') AND p.state NOT IN ('done','dropped')
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+SELECT d.workflow_id, COALESCE(d.entity_type,'workflow'), COALESCE(d.entity_id,d.workflow_id), 'decision', d.di_id,
+       'DecisionOpen:'||d.kind, d.summary, d.opened_at, d.decider
+  FROM decision_items d LEFT JOIN workflows w ON w.workflow_id=d.workflow_id
+ WHERE d.status IN ('open','claimed','escalated')
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+SELECT c.workflow_id, c.entity_type, c.entity_id, 'condition', c.type, c.reason, c.message, c.last_transition_at, COALESCE(c.owner,'controller')
+  FROM conditions c LEFT JOIN workflows w ON w.workflow_id=c.workflow_id
+ WHERE c.status<>'True'
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+SELECT i.workflow_id, 'job', COALESCE(i.job_id,i.workflow_id), 'incident', i.incident_id, 'IncidentOpen:'||i.kind,
+       COALESCE(i.detail,i.last_progress), i.created_at, i.owner
+  FROM incidents i LEFT JOIN workflows w ON w.workflow_id=i.workflow_id
+ WHERE i.status='open'
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+SELECT x.workflow_id, 'attempt', CAST(x.attempt_id AS TEXT), 'question', CAST(x.inbox_id AS TEXT), 'WorkerQuestionPending',
+       json_extract(x.payload_json,'$.question'), x.created_at, 'kernel'
+  FROM inbox x LEFT JOIN workflows w ON w.workflow_id=x.workflow_id
+ WHERE x.kind='worker-question' AND x.status IN ('pending','claimed')
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+SELECT s.workflow_id, 'attempt', CAST(s.attempt_id AS TEXT), 'settle-tail', CAST(s.attempt_id AS TEXT), 'SettleTailFailed', s.last_error,
+       COALESCE(s.started_at,s.queued_at), 'controller'
+  FROM settle_tails s LEFT JOIN workflows w ON w.workflow_id=s.workflow_id
+ WHERE s.state='failed'
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+SELECT l.workflow_id, 'workflow', l.workflow_id, 'product-land', CAST(l.land_id AS TEXT), 'ProductLand:'||l.result, l.reason,
+       l.started_at, 'kernel'
+  FROM product_lands l LEFT JOIN workflows w ON w.workflow_id=l.workflow_id
+ WHERE l.result IN ('failed','conflict','red')
+   AND NOT EXISTS(SELECT 1 FROM product_lands k WHERE k.workflow_id=l.workflow_id AND k.land_id>l.land_id AND k.result='landed')
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+-- H1: a filed report nobody settled within its SLA (the same rows as v_settle_overdue) blocks its job.
+SELECT a.workflow_id, 'attempt', CAST(a.attempt_id AS TEXT), 'settle', CAST(a.attempt_id AS TEXT),
+       'SettleOverdue:'||COALESCE(a.report_outcome,'?'), a.job_id, a.reported_at,
+       CASE WHEN a.report_outcome='done' THEN 'settler' ELSE 'kernel' END
+  FROM op_attempts a LEFT JOIN workflows w ON w.workflow_id=a.workflow_id
+ WHERE a.reported_at IS NOT NULL AND a.settled_at IS NULL AND a.end_state IS NULL
+   AND (CAST(unixepoch('subsec')*1000 AS INTEGER) - a.reported_at) > CASE WHEN a.report_outcome='done' THEN 180000 ELSE 900000 END
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'));
+
+CREATE VIEW v_open_work AS
+SELECT 'decision' AS kind, d.workflow_id, d.di_id AS ref, d.summary AS what, d.opened_at AS since, d.due_at
+  FROM decision_items d LEFT JOIN workflows w ON w.workflow_id=d.workflow_id
+ WHERE d.status IN ('open','claimed','escalated')
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'))
+UNION ALL
+SELECT 'job-'||j.status, j.workflow_id, j.job_id, j.op_id, j.updated_at, j.deadline
+  FROM jobs j LEFT JOIN workflows w ON w.workflow_id=j.workflow_id
+ WHERE j.status IN ('leased','running','answering','effect_unknown')
+   AND (w.phase IS NULL OR w.phase NOT IN ('archived','finished'));

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -5,38 +5,45 @@ purpose: >-
   then the repositories' own upgrade lane (each sets the exact version and reinstalls; nothing else installs a @starci package). Read on 2026-09-29 from the packages under
   .claude/packages and from the installed node_modules of nivo-backend, nivo-fe, starci-next, starci-next-fe,
   mia-mia-backend and miamia-fe; where they disagreed the newest version installed in more than one repository
-  won, and the runtime's own version won for @starci packages.
+  won, and the runtime's own version won for @starci packages. An app (hfs 4) has ONE package.json for both sides, so a
+  dependency both sides declared at different versions takes one: its pin where it has one, otherwise the higher of the
+  two, pinned here with a why (2026-10-01, from nivo-backend/nivo-fe, starci-next/starci-next-fe and
+  mia-mia-backend/miamia-fe: every such conflict but graphql was already pinned). The runtime's example apps merged the
+  same way on 2026-10-01 (examples/todo-app from todo-app-backend/todo-app-frontend, examples/ecommerce-app from
+  ecommerce-app-be/ecommerce-app-fe): no dependency outside this file was declared at two versions across their sides, so
+  every choice is a pin (each side's older @starci pins and graphql moved to the version here). `side` names the side whose code uses
+  the dependency; the app root package.json carries the pins of both.
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
   '@starci/grammar':
-    version: 0.7.2
+    version: 0.8.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
-    why: nivo-fe pins 0.4.11 and 0.5.0 in one workspace, starci-next-fe 0.5.1, miamia-fe 0.5.0; the runtime source is 0.7.2 (Input tel kind and IconButton disclosure props).
+    why: nivo-fe pins 0.4.11 and 0.5.0 in one workspace, starci-next-fe 0.5.1, miamia-fe 0.5.0; the runtime source is 0.8.0 (the brand layer sets `--font-sans` and `--font-mono`; the grammar reads them; 0.7.2 added the Input tel kind and IconButton disclosure props).
   '@starci/eslint-canon-be':
-    version: 2.0.1
+    version: 3.0.0
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
-    why: '2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws (R36 sql-text-only, R83 no-repository-class, R85/R87/R89 service-deps, R43 config-parsed-in-main, R47/R48 test world, R95 operations, R98-R101 builders).'
+    why: '3.0.0: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side; the project graph is built per side. 2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws.'
   '@starci/eslint-canon-fe':
-    version: 7.0.0
+    version: 8.0.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
-    why: '7.0.0: the front end has no tests (test rules removed, FE_NO_TESTS R97 in hfs); no-vietnamese-in-source (R91).'
+    why: '8.0.0: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side; the project graph is built per side. 7.0.0: the front end has no tests (FE_NO_TESTS R97 in hfs); no-vietnamese-in-source (R91).'
   '@starci/stylelint-canon':
-    version: 2.0.0
+    version: 2.0.1
     group: starci
     install: registry
     side: fe
     source: packages/stylelint/package.json
-    why: '2.0.0 adds status-contrast (HeroUI soft pairs measured per theme), fixes brand-layer-shape on the shared :root,.light,.dark block and the info soft pair, and derives appTokens with loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
+    why: '2.0.1 accepts `--font-sans` and `--font-mono` in the brand layer (the vocabulary follows the grammar 0.8.0). 2.0.0 adds status-contrast (HeroUI soft pairs measured per theme), fixes brand-layer-shape on the shared :root,.light,.dark block and the info soft pair, and derives appTokens with loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
   '@starci/tsconfig':
     version: 2.0.0
     group: starci
@@ -50,19 +57,26 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.1.0
+    version: 2.2.0
     group: starci
     install: registry
     side: be
     source: packages/jest-preset/package.json
-    why: '2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
+    why: '2.2.0: the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; 2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
+  '@starci/test-world':
+    version: 1.0.0
+    group: starci
+    install: registry
+    side: be
+    source: packages/test-world/package.json
+    why: 'the shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs, the outage lock and the starci-test-stack bin behind the managed test:stack script; a devDependency of every back end.'
   '@starci/hfs':
-    version: 2.0.2
+    version: 4.0.0
     group: starci
     install: registry
     side: both
     source: packages/hfs/package.json
-    why: '2.0.0 (C0 release): the BE-CONVENTION machine, emit-contracts (GraphQL SDL and OpenAPI from the typed operation table), the four-project test layout, FE has no tests, repo.scripts slot, secrets guard in work-hygiene, rule ids R<2-3 digits>.'
+    why: '4.0.0: the app monorepo standard: one app repository with the root package.json, lockfile and hfs.json of kind app, and the be/ and fe/ sides; `hfs scaffold app <name>` makes it, `hfs lint` at the root lints be/** with the BE canon and fe/** with the FE canon; the standalone be/fe repository kinds and `hfs init` are deleted.'
   # --- tooling
   typescript:
     version: 5.9.3
@@ -152,6 +166,11 @@ pins:
     group: framework
     side: fe
     why: every HFS front end uses next-intl with the [locale] segment (hfs sync --init writes it); nivo-fe resolves 4.13.6.
+  graphql:
+    version: 16.14.2
+    group: framework
+    side: both
+    why: 'one app package.json for both sides (hfs 4): nivo-backend declares ^16.14.1 and nivo-fe ^16.14.2, the higher wins; all four product installs resolve 16.14.2. The example apps: todo-app-backend declared ^16.14.2 (devDependencies) and ecommerce-app-be ^16.14.2 (dependencies and devDependencies); each app root now has one dependencies entry at the pin.'
   supertest:
     version: 7.3.0
     group: tooling

package/runtime/knowledge/hfs/peer-integrations.yaml

@@ -0,0 +1,18 @@
+schema: starci/hfs-peer-integrations@1
+purpose: >-
+  The runtime peers a driver integration needs and npm does not install for it: "if the app depends on every package of
+  `when` (at the named major, when one is named), it must declare `requires` in its dependencies". A missing peer is
+  invisible to the type checker and the unit specs and only fails when the api boots (todo-app and ecommerce-app,
+  2026-10-01: neither old backend declared @as-integrations/express5, so the Apollo GraphQL api could not boot under
+  Express 5 and nothing noticed before e2e). R111 HFS_PEER_INTEGRATION_MISSING judges the app root package.json, the one
+  manifest of both sides, with this catalog; an entry is added the day a boot failure of the same kind is found.
+pairs:
+  - id: nestjs-apollo-express5
+    when:
+      - {package: "@nestjs/apollo"}
+      - {package: "@nestjs/platform-express", major: 11}
+    requires: "@as-integrations/express5"
+    why: >-
+      @nestjs/platform-express 11 runs Express 5, and Apollo Server 5 serves an Express 5 app only through
+      @as-integrations/express5, which @nestjs/apollo loads at boot and does not depend on; without it the GraphQL api
+      does not start.