@starci/hfs 4.0.8 → 4.0.10

package/runtime/engine/db/provider-reservations.mjs

@@ -0,0 +1,101 @@
+// Provider receipt SQL participates in the machine writer's existing fenced transactions.
+
+export function providerReservationMethods({ need, parse, toJson, hex }) {
+  // Provider/account slots are shared by all five agent roles. A clock timeout is not exit evidence.
+  const providerReservationRow = (row) => row ? { id: row.id, fence: row.fence, attemptId: row.attempt_id,
+    provider: row.provider, account: row.account, model: row.model, role: row.role, state: row.state,
+    slots: row.slots, amountUnit: 'concurrent-launch', maxParallel: row.max_parallel,
+    handle: row.handle, pid: row.pid, launchIdentity: row.launch_identity, hostRequestId: row.host_request_id, createdAt: row.created_at, updatedAt: row.updated_at,
+    scope: parse(row.scope_json), estimate: parse(row.estimate_json), quota: parse(row.quota_json),
+    override: parse(row.override_json), releasedAt: row.released_at, proof: parse(row.proof_json) } : null;
+  function providerReservations(m, { provider = null, account = null, activeOnly = false } = {}) {
+    const where = [], args = [];
+    if (provider !== null) { where.push('provider=?'); args.push(provider); }
+    if (account !== null) { where.push('account=?'); args.push(account); }
+    if (activeOnly) where.push("state<>'released'");
+    return m.db.prepare(`SELECT * FROM provider_reservations${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY fence`).all(...args).map(providerReservationRow);
+  }
+  function providerReservationUsage(m, { provider, account = 'default' } = {}) {
+    const reservations = providerReservations(m, { provider, account, activeOnly: true });
+    return { running: reservations.length, reservations, observed: true };
+  }
+  /** Atomic last-slot admission. Replays preserve the original receipt; changed attempt meaning refuses. */
+  function reserveProvider(m, { provider, account = 'default', attemptId, role, model, maxParallel, scope = null, quota = null, estimate = null, override = null } = {}) {
+    need([provider, account, attemptId, model].every((value) => typeof value === 'string' && value.trim()), 'provider reservation needs provider, account, attemptId and concrete model');
+    need(typeof role === 'string' && role.trim(), 'provider reservation needs one agent role'); // The DDL owns the allowed role domain.
+    need(Number.isInteger(maxParallel) && maxParallel >= 0, 'provider reservation needs nonnegative integer maxParallel');
+    return m.transaction((db) => {
+      const existing = db.prepare('SELECT * FROM provider_reservations WHERE attempt_id=?').get(attemptId);
+      if (existing) {
+        if (existing.provider !== provider || existing.account !== account || existing.model !== model || existing.role !== role || existing.scope_json !== toJson(scope))
+          return { ok: false, reason: 'attempt-conflict', reservation: providerReservationRow(existing) };
+        return { ok: existing.state !== 'released', reason: existing.state === 'released' ? 'attempt-released' : 'reserved', reused: true, reservation: providerReservationRow(existing) };
+      }
+      const running = Number(db.prepare("SELECT count(*) n FROM provider_reservations WHERE provider=? AND account=? AND state<>'released'").get(provider, account).n);
+      if (running >= maxParallel) return { ok: false, reason: 'capacity', running, maxParallel };
+      const id = hex(16), at = m.now();
+      const result = db.prepare("INSERT INTO provider_reservations(id,attempt_id,provider,account,model,role,scope_json,state,max_parallel,quota_json,estimate_json,override_json,created_at,updated_at) VALUES(?,?,?,?,?,?,?,'reserved',?,?,?,?,?,?)")
+        .run(id, attemptId, provider, account, model, role, toJson(scope), maxParallel, toJson(quota), toJson(estimate), toJson(override), at, at);
+      db.prepare("INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state) VALUES(?,?,NULL,'reserved')").run(id, at);
+      return { ok: true, reason: 'reserved', reused: false, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE fence=?').get(result.lastInsertRowid)) };
+    });
+  }
+  const fencedProviderRow = (db, { id, fence, attemptId } = {}) => {
+    const row = db.prepare('SELECT * FROM provider_reservations WHERE id=? AND fence=?').get(id ?? '', fence ?? -1);
+    return row && (attemptId === undefined || row.attempt_id === attemptId) ? row : null;
+  };
+  /** Observe launch progress under its original fence; unknown still occupies its slot. */
+  function markProviderReservation(m, { id, fence, attemptId, provider, account, model, role, state, launchIdentity = null, hostRequestId = null, handle = null, pid = null } = {}) {
+    need(['launching', 'live', 'unknown'].includes(state), 'provider reservation observation needs launching, live or unknown');
+    return m.transaction((db) => {
+      const row = fencedProviderRow(db, { id, fence, attemptId });
+      if (!row) return { ok: false, reason: 'fenced' };
+      if (Object.entries({ provider, account, model, role }).some(([key, value]) => value !== undefined && row[key] !== value)) return { ok: false, reason: 'identity-conflict' };
+      if (row.state === 'released') return { ok: false, reason: 'released' };
+      if (state === 'launching' && (typeof launchIdentity !== 'string' || !launchIdentity.trim())) return { ok: false, reason: 'launch-identity-required' };
+      if (launchIdentity !== null && row.launch_identity && row.launch_identity !== launchIdentity) return { ok: false, reason: 'launch-identity-conflict', reservation: providerReservationRow(row) };
+      if (hostRequestId !== null && row.host_request_id && row.host_request_id !== hostRequestId) return { ok: false, reason: 'host-request-conflict', reservation: providerReservationRow(row) };
+      if (state === 'launching' && row.state !== 'reserved' && row.state !== 'launching') return { ok: false, reason: 'state-regression' };
+      if ((row.handle && handle && row.handle !== handle) || (row.pid && pid && row.pid !== pid)) return { ok: false, reason: 'identity-conflict' };
+      const at = m.now();
+      db.prepare('UPDATE provider_reservations SET state=?,launch_identity=coalesce(launch_identity,?),host_request_id=coalesce(host_request_id,?),handle=coalesce(handle,?),pid=coalesce(pid,?),updated_at=? WHERE id=? AND fence=?')
+        .run(state, launchIdentity, hostRequestId, handle, pid, at, id, fence);
+      if (row.state !== state) db.prepare('INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state) VALUES(?,?,?,?)').run(id, at, row.state, state);
+      return { ok: true, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE id=?').get(id)) };
+    });
+  }
+  /** Only the launcher/reconciler's definitive matching exit/no-effect receipt releases capacity. */
+  function releaseProviderReservation(m, { id, fence, attemptId, proof } = {}) {
+    return m.transaction((db) => {
+      const row = fencedProviderRow(db, { id, fence, attemptId });
+      if (!row) return { ok: false, reason: 'fenced' };
+      if (row.state === 'released') return { ok: true, reused: true, reservation: providerReservationRow(row) };
+      const affirmation = proof?.hostAffirmation;
+      const reply = affirmation?.receipt, result = reply?.result;
+      const residual = result?.residualResources ?? result?.worker?.residualResources;
+      const identities = [result, result?.worker, result?.terminal].filter((value) => value && typeof value === 'object');
+      const hostNoEffect = reply && typeof reply === 'object' && !['unknown', 'outcome_unknown'].includes(result?.state)
+        && !['unknown', 'outcome_unknown'].includes(result?.worker?.state)
+        && !(residual && typeof residual === 'object' && Object.keys(residual).length > 0)
+        && !identities.some((value) => ['agentTerminalHandle', 'terminalHandle', 'handle', 'pid', 'processId', 'dispatchId'].some((key) => value[key] !== undefined && value[key] !== null && value[key] !== ''))
+        && (result?.failedStage !== undefined || result?.stage !== undefined || typeof reply.error?.code === 'string' && reply.error.code.trim());
+      const resolvedUnknown = row.state === 'unknown' && row.launch_identity && proof?.launchIdentity === row.launch_identity
+        && row.host_request_id && affirmation?.requestId === row.host_request_id && affirmation.kind === 'worker-start-replay'
+        && affirmation.replayed === true && affirmation.outcome === 'failed' && affirmation.effectState === 'none'
+        && hostNoEffect;
+      const noEffect = proof?.kind === 'failed-before-launch' && proof.confirmed === true && !row.handle && !row.pid
+        && (['reserved', 'launching'].includes(row.state) || resolvedUnknown);
+      const terminalEnded = row.handle && proof?.kind === 'closed' && proof.handle === row.handle
+        && ['gone', 'disconnected'].includes(proof.terminalProof) && ['none', 'stopped'].includes(proof.processVerdict);
+      const processEnded = !row.handle && row.pid && proof?.kind === 'process-exited' && proof.pid === row.pid;
+      const ended = proof?.confirmed === true && (terminalEnded || processEnded)
+        && (!row.pid || proof.pid == null || proof.pid === row.pid);
+      if (!noEffect && !ended) return { ok: false, reason: 'exit-unproven', reservation: providerReservationRow(row) };
+      const at = m.now();
+      db.prepare("UPDATE provider_reservations SET state='released',released_at=?,updated_at=?,proof_json=? WHERE id=? AND fence=?").run(at, at, toJson(proof), id, fence);
+      db.prepare("INSERT INTO provider_reservation_events(reservation_id,at,from_state,to_state,proof_json) VALUES(?,?,?,'released',?)").run(id, at, row.state, toJson(proof));
+      return { ok: true, reused: false, reservation: providerReservationRow(db.prepare('SELECT * FROM provider_reservations WHERE id=?').get(id)) };
+    });
+  }
+  return { reserveProvider, providerReservations, providerReservationUsage, markProviderReservation, releaseProviderReservation };
+}

package/runtime/engine/digest.mjs

@@ -0,0 +1,16 @@
+// digest.mjs — the one SHA-256 the runtime hashes with. A leaf: every file's integrity digest,
+// every ledger input ref and every stamped asset is this function, so a byte stream and a file
+// never disagree about what their digest is.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+
+/** The lowercase hex SHA-256 of `value` (string, Buffer or TypedArray). */
+export const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/** The SHA-256 of the file's exact bytes; throws when the file cannot be read. */
+export function sha256File(file){
+  // A numeric descriptor belongs to the caller; positional reads preserve its offset.
+  const owned=typeof file!=='number',fd=owned?fs.openSync(file,'r'):file;
+  const hash=createHash('sha256'),buffer=Buffer.alloc(1024*1024);
+  try{let at=0,n;while((n=fs.readSync(fd,buffer,0,buffer.length,at))>0){hash.update(buffer.subarray(0,n));at+=n;}return hash.digest('hex');}
+  finally{if(owned)fs.closeSync(fd);}
+}

package/runtime/engine/invalid-config.mjs

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import {isPlainObject as plain} from './plain-object.mjs';
+/** The one `Invalid config.yaml:` raiser every section validator shares: bad('<rest>') throws it. */
+export const invalid=section=>message=>{throw Error(`Invalid config.yaml: ${section}${message}`);};
+
+/** The host roots the owner may relocate (config.yaml `roots`): the archive root and the lanes root. */
+const ROOT_KEYS=Object.freeze(['archive','lanes']);
+/** config.yaml `roots` - {archive?, lanes?}: absolute directories, or null; an absent key means <starciLocalRoot>/archive and <starciLocalRoot>/lanes. */
+export function validateRoots(roots){
+  if(roots===null)return;
+  const bad=invalid('roots');
+  if(!plain(roots))bad(` must be {archive?: <absolute directory>, lanes?: <absolute directory>} or null.`);
+  for(const key of Object.keys(roots))if(!ROOT_KEYS.includes(key))bad(` has unknown key ${key} (allowed: ${ROOT_KEYS.join(', ')}).`);
+  for(const key of ROOT_KEYS)if(roots[key]!==undefined&&roots[key]!==null&&!(typeof roots[key]==='string'&&roots[key].trim()&&path.isAbsolute(roots[key])))bad(`.${key} must be an absolute directory path or null.`);
+}

package/runtime/engine/orca-config.mjs

@@ -0,0 +1,27 @@
+import {isPlainObject as plain} from './plain-object.mjs';
+import {invalid} from './invalid-config.mjs';
+
+/**
+ * config.yaml `orca` — the owner's Orca app settings the runtime must know. maxWorkerDepth is the deepest worker Orca
+ * lets start under the owner's chat (chat = depth 0, a Kernel or the [Supervisor] 1, an op or a [Worker] 2, the draw
+ * critic 3); a deeper worker-start is refused by Orca with nested_worker_depth_exceeded. Orca exposes no read of that
+ * setting, so it is declared here and MUST equal the Orca app setting: scripts/agent/lib.mjs spawnAgent refuses a launch
+ * deeper than it before worker-start (worker-depth-exceeded), and `start --check` with STARCI_ORCA_LIVE=1 compares it with
+ * a measured probe (scripts/agent/depth-probe.mjs).
+ */
+export const ORCA_DEFAULTS=Object.freeze({maxWorkerDepth:4});
+export const MAX_WORKER_DEPTH_CEILING=16;
+export function validateOrca(orca){
+  if(orca===null)return;
+  const bad=invalid('orca');
+  if(!plain(orca))bad(' must be {maxWorkerDepth?} or null.');
+  for(const key of Object.keys(orca))if(key!=='maxWorkerDepth')bad(` has unknown key ${key} (allowed: maxWorkerDepth).`);
+  const v=orca.maxWorkerDepth;
+  if(v!==undefined&&v!==null&&!(Number.isInteger(v)&&v>=1&&v<=MAX_WORKER_DEPTH_CEILING))bad(`.maxWorkerDepth must be an integer from 1 to ${MAX_WORKER_DEPTH_CEILING} equal to the Orca app's worker depth setting (default ${ORCA_DEFAULTS.maxWorkerDepth}), or null.`);
+}
+/** The owner's Orca settings: {maxWorkerDepth, source: 'orca'|'default'}. An absent or null block or key is the default. */
+export function orcaSettings(config){
+  if(config?.orca!==undefined)validateOrca(config.orca);
+  const value=plain(config?.orca)?config.orca.maxWorkerDepth:null;
+  return Number.isInteger(value)?{maxWorkerDepth:value,source:'orca'}:{maxWorkerDepth:ORCA_DEFAULTS.maxWorkerDepth,source:'default'};
+}

package/runtime/engine/refuse.mjs

@@ -0,0 +1,11 @@
+// refuse.mjs — the refusal Error every verb raises: a message plus a stable `code` (and any extra fields the
+// caller attaches). `refuse` builds it, `fail` throws it, `need` throws it when a required condition is false.
+
+/** An Error carrying `code` and `extra` fields; callers `throw` it or hand it to a result row. */
+export const refuse = (message, code, extra = {}) => Object.assign(new Error(message), { code, ...extra });
+
+/** Throws the refusal `refuse` builds — the spelling used where refusing is the whole statement. */
+export const fail = (message, code, extra = {}) => { throw refuse(message, code, extra); };
+
+/** Throws `refuse(message, code)` when `ok` is falsy — the assertion spelling of a refusal. */
+export const need = (ok, message, code) => { if (!ok) throw refuse(message, code); };

package/runtime/engine/secrets.mjs

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The host-local credential filename, resolved only against a verified runtime main root. */
+export const SECRET_ENV_FILE='secret.env';
+/** The configured credential variable grammar shared by validation and secret resolution. */
+export const ENV_NAME=/^[A-Z_][A-Z0-9_]{0,63}$/;
+export const CREDENTIAL_FILE_MAX_BYTES=1024*1024;
+const resolvedValues = new Set();
+const remember = value => {
+  if (typeof value === 'string' && value.length >= 6) resolvedValues.add(value);
+  return value;
+};
+
+/** Filter credentials resolved by this process; the values never leave their resolution owner. */
+export function redactResolvedSecrets(text) {
+  let clean = text;
+  for (const value of resolvedValues) if (clean.includes(value)) clean = clean.split(value).join('[redacted:resolved-secret]');
+  return clean;
+}
+
+/** Check lexical availability only; blank and conventional template markers never prove provider validity. */
+export function credentialPresent(value){
+  if(typeof value!=='string'||!value.trim())return false;
+  return !/^(?:CHANGE_ME|REPLACE_ME|PLACEHOLDER|TODO|<[^>]*>|YOUR_[A-Z0-9_]+)$/i.test(value.trim());
+}
+
+/** Read one configured credential file with a finite byte budget; no effects beyond the read. */
+export function readSecretBytes(file){
+  const before=fs.lstatSync(file);
+  if(!before.isFile()||before.isSymbolicLink())throw new Error('credential file must be a regular file');
+  if(before.size>CREDENTIAL_FILE_MAX_BYTES)throw new Error('credential file exceeds the byte budget');
+  const fd=fs.openSync(file,fs.constants.O_RDONLY|(fs.constants.O_NOFOLLOW??0));
+  let bytes;
+  try{
+    const stat=fs.fstatSync(fd);
+    if(!stat.isFile()||stat.dev!==before.dev||stat.ino!==before.ino)throw new Error('credential file changed during resolution');
+    bytes=Buffer.alloc(CREDENTIAL_FILE_MAX_BYTES+1);
+    let count=0;
+    while(count<bytes.length){const n=fs.readSync(fd,bytes,count,bytes.length-count,null);if(n===0)break;count+=n;}
+    if(count>CREDENTIAL_FILE_MAX_BYTES)throw new Error('credential file exceeds the byte budget');
+    return bytes.subarray(0,count);
+  }catch(error){bytes?.fill(0);throw error;}finally{fs.closeSync(fd);}
+}
+
+const readCredentialFile = file => { const bytes=readSecretBytes(file); try{return bytes.toString('utf8');}finally{bytes.fill(0);} };
+
+/** Parse a dotenv file (KEY=VALUE lines, # comments, optional export/quotes). An absent file is {}. */
+export function readDotenv(file){
+  let text='';try{text=readCredentialFile(file);}catch(error){if(error?.code==='ENOENT')return {};throw error;}
+  const out={};
+  for(const line of text.split(/\r?\n/)){
+    const m=line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if(!m)continue;
+    let value=m[2];
+    if(value.length>=2&&(value[0]==='"'||value[0]==="'")&&value.at(-1)===value[0])value=value.slice(1,-1);
+    out[m[1]]=value;
+  }
+  return out;
+}
+
+/**
+ * Resolve a configured variable or its supported NAME_FILE custody pointer. An explicitly supplied
+ * blank variable disables the value; it must not resurrect a file value. Never print the result.
+ */
+export function connectorSecret(name,env=process.env){
+  if(typeof name!=='string'||!ENV_NAME.test(name))return null;
+  if(Object.hasOwn(env,name))return typeof env[name]==='string'?remember(env[name].trim()||null):null;
+  const pointer=typeof env[`${name}_FILE`]==='string'?env[`${name}_FILE`].trim():'';
+  if(!pointer)return null;
+  try{const value=readCredentialFile(pointer).trim();return remember(value||null);}catch{return null;}
+}
+
+/**
+ * Load the verified runtime main's local credentials below the actual environment without mutating
+ * either input. The caller owns repository identity; this base-tier reader never infers a root from cwd.
+ * Absence is allowed so the action-specific gate can name only the credentials that action requires.
+ */
+export function secretEnv(verifiedRuntimeRoot,env=process.env){
+  if(typeof verifiedRuntimeRoot!=='string'||!path.isAbsolute(verifiedRuntimeRoot))
+    throw new TypeError('secretEnv requires an absolute verified runtime root');
+  if(env===null||typeof env!=='object'||Array.isArray(env))throw new TypeError('secretEnv requires an environment mapping');
+  const root=fs.lstatSync(verifiedRuntimeRoot);
+  if(!root.isDirectory()||root.isSymbolicLink())throw new Error('secretEnv runtime root must be a regular directory');
+  const file=path.join(verifiedRuntimeRoot,SECRET_ENV_FILE);
+  let stat;
+  try{stat=fs.lstatSync(file);}catch(error){if(error?.code==='ENOENT')return {...env};throw error;}
+  if(!stat.isFile()||stat.isSymbolicLink())throw new Error('secret.env must be a regular file');
+  const local = readDotenv(file);
+  const resolved = {...local,...env};
+  for (const name of Object.keys(local)) if (typeof resolved[name] === 'string') remember(resolved[name]);
+  return resolved;
+}
+
+/** Select a supplied age identity without inventing custody or running a key tool. Inline execution awaits its owned isolation capability. */
+export function sopsIdentityEnv(env,{identity=null,required=false,platform=process.platform}={}){
+  const refuse=(reason,message)=>{
+    const error=new Error(`SOPS identity [${reason}]: ${message}`);
+    error.name='SopsIdentityRefusal';error.identityRefusal=reason;
+    return {mode:'refused',env:null,error};
+  };
+  if(!env||typeof env!=='object'||Array.isArray(env))return refuse('invalid-environment','an environment mapping is required');
+  const names=name=>Object.keys(env).filter(key=>platform==='win32'?key.toUpperCase()===name:key===name);
+  const inline=names('SOPS_AGE_KEY'),files=names('SOPS_AGE_KEY_FILE');
+  if(inline.length>1||files.length>1)return refuse('ambiguous-environment','multiple Windows aliases select an age identity');
+  if(inline.length){
+    const name=inline[0];
+    if(!credentialPresent(env[name]))return refuse('disabled-inline','SOPS_AGE_KEY is explicitly empty or invalid');
+    remember(env[name].trim());
+    return {...refuse('inline-context-unqualified','the supplied SOPS_AGE_KEY awaits an owned selected-identity isolation capability; no SOPS process was launched'),inlineName:name};
+  }
+  let file=identity;
+  if(files.length){
+    const value=env[files[0]];
+    if(!credentialPresent(value))return refuse('disabled-file','SOPS_AGE_KEY_FILE is explicitly empty or invalid');
+    if(identity!==null&&identity!==undefined&&identity!==value)return refuse('conflicting-files','two different original identity files were explicitly selected');
+    file=value;
+  }
+  if(file!==null&&file!==undefined){
+    if(!credentialPresent(file))return refuse('invalid-file','the original identity file selection is empty or invalid');
+    if(!path.isAbsolute(file))return refuse('identity-file-location-unqualified','select the original identity by its absolute path; caller and SOPS working directories may differ');
+    try{
+      const stat=fs.lstatSync(file);
+      if(!stat.isFile()||stat.isSymbolicLink())return refuse('identity-file-unavailable','the explicitly selected original identity must be a regular non-symlink file');
+    }catch{return refuse('identity-file-unavailable','the explicitly selected original identity file is unavailable');}
+    return {mode:'file',env:{...env,SOPS_AGE_KEY_FILE:file},error:null};
+  }
+  if(required)return refuse('identity-not-supplied','supply SOPS_AGE_KEY locally or select the original SOPS_AGE_KEY_FILE; no home default was inferred');
+  return {mode:'public-recipient',env:{...env},error:null};
+}

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

@@ -3,14 +3,12 @@ purpose: >-
   The exact version of every dependency a StarCi product repository pins. One version per dependency for the whole
   family. Raising a version is a change to this file first (with the package bump when it is a @starci package),
   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. An app (hfs 4) has ONE package.json for both sides, so a
+  .claude/packages and from the installed node_modules of the six product repositories; where they disagreed the
+  newest version installed in more than one repository 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
+  two, pinned here with a why (2026-10-01: every such conflict but graphql was already pinned). The runtime's example apps
+  merged the same way on 2026-10-01: 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:
@@ -24,77 +22,89 @@ pins:
     source: packages/heroicons/package.json
     why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
-    version: 0.8.2
+    version: 0.8.3
     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.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).
+    why: the product front ends pinned older versions (0.4.11, 0.5.0, 0.5.1); the runtime source is 0.8.0 and wins for a @starci package (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: 3.0.8
+    version: 3.0.10
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: '3.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 3.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 3.0.1: its bundled canon-pins copy pins hfs 4.0.1. 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: 8.0.8
+    version: 8.0.10
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: '8.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 8.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 8.0.1: its bundled canon-pins copy pins hfs 4.0.1. 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.3
+    version: 2.0.5
     group: starci
     install: registry
     side: fe
     source: packages/stylelint/package.json
     why: '2.0.2: no-class-selector refuses a compound class selector (`div.card`), which the 2.0.1 pattern let through. 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.2
+    version: 2.0.3
     group: starci
     install: registry
     side: both
     source: packages/tsconfig/package.json
   '@starci/prettier-config':
-    version: 1.0.1
+    version: 1.0.3
     group: starci
     install: registry
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.2.3
+    version: 2.2.5
     group: starci
     install: registry
     side: be
     source: packages/jest-preset/package.json
-    why: '2.2.2: the unit run writes the lcov Sonar and Codecov import (services only); 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.'
+    why: '2.2.4: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: pinned together with @starci/test-world 1.1.0, any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. 2.2.3: republished after the move (no preset change). 2.2.2: the unit run writes the lcov Sonar and Codecov import (services only); 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.6
+    version: 1.2.1
     group: starci
     install: registry
     side: be
     source: packages/test-world/package.json
-    why: '1.0.5: a modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, and w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client. 1.0.4: world.resolve and scope.resolve take any Nest token (class, string or symbol). 1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. 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. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
+    why: '1.2.0: Kafka as real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and schema-per-context Postgres (a schema and a login role per context in a shared database); its CLI main is exported at ./cli for starci app stack, and the former starci app stack bin is removed. 1.1.0: per-worker data slots: a run provisions min(jest workers, workers cap, default 2) slots, each its own namespace (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock, so world files run in parallel; state file protocol 2, paired exactly with @starci/jest-preset 2.2.4 (TEST_WORLD_PAIR_MISMATCH otherwise). 1.0.6: republished after the move (no library change). 1.0.5: a modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, and w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client. 1.0.4: world.resolve and scope.resolve take any Nest token (class, string or symbol). 1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. 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 and the outage lock; a devDependency of every back end. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
+  '@starci/cli':
+    version: 1.0.1
+    group: starci
+    install: registry
+    side: both
+    source: packages/cli/package.json
+    why: '1.0.0: the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.0.8
+    version: 4.0.10
     group: starci
     install: registry
     side: both
     source: packages/hfs/package.json
-    why: '4.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2, eslint-canon-be 3.0.3 and eslint-canon-fe 8.0.3 (what `hfs scaffold app` writes); the package gains its own clean-install test. 4.0.2: .starcistacks and .sops.yaml live at the app root (slots app.starcistacks, app.sops; a side holding either is refused, HFS_STACKS_IN_SIDE), the managed .gitignore block carries the custody rules, the scaffold writes them at the root. 4.0.1: `hfs scaffold app` resolves the real lockfile with npm (`npm install --package-lock-only`) instead of writing a root-only stub that `npm ci` refuses. 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.'
+    why: '4.0.9: the transitive app implementation used by @starci/cli; it carries the generated runtime slice read by starci app commands.'
   # --- tooling
   typescript:
     version: 5.9.3
     group: tooling
     side: both
-    why: all six repositories resolve 5.9.3 already; the declared ranges (^5, ^5.7.3) become exact.
+    why: all six product repositories resolve 5.9.3 already; the declared ranges (^5, ^5.7.3) become exact.
+  turbo:
+    version: 2.11.6
+    group: tooling
+    side: fe
+    why: 'every app is a monorepo (R143): turbo runs build, dev, lint and typecheck over the fe workspaces fe/apps/* and fe/packages/* from the app root turbo.json, as nivo-fe does; 2.11.6 is the newest 2.x on 2026-10-02.'
   prettier:
     version: 3.9.6
     group: tooling
     side: both
-    why: only nivo-backend has it installed (3.9.6); the other five adopt it with the formatter change.
+    why: only one product repository had it installed (3.9.6); the other five adopt it with the formatter change.
   stylelint:
     version: 17.15.0
     group: tooling
@@ -109,7 +119,7 @@ pins:
     version: 9.39.5
     group: tooling
     side: both
-    why: five repositories resolve 9.39.5, nivo-backend 9.39.4.
+    why: five product repositories resolve 9.39.5, the sixth 9.39.4.
   eslint-plugin-react-hooks:
     version: 7.1.1
     group: tooling
@@ -119,7 +129,42 @@ pins:
     version: 22.20.4
     group: tooling
     side: both
-    why: nivo-fe resolves 20.19.43 and nivo-backend 22.20.0; the package engines are node >=22.
+    why: one front end resolves 20.19.43 and one back end 22.20.0; the package engines are node >=22.
+  '@types/express':
+    version: 4.17.25
+    group: tooling
+    side: be
+    why: the Express types of a back end; the reference app declares ^4.17.21 and resolves 4.17.25.
+  '@types/react':
+    version: 19.3.0
+    group: tooling
+    side: fe
+    why: the React types of a front end; the reference app declares ^19.0.0 and resolves 19.3.0.
+  '@types/react-dom':
+    version: 19.3.0
+    group: tooling
+    side: fe
+    why: the React DOM types of a front end; the reference app declares ^19.0.0 and resolves 19.3.0.
+  husky:
+    version: 9.1.7
+    group: tooling
+    side: both
+    why: the managed git hooks of the app root (pre-commit, pre-push); the reference app declares ^9.1.7 and resolves 9.1.7.
+  ts-node-dev:
+    version: 2.0.0
+    group: tooling
+    side: be
+    why: 'the watch runner of the managed dev:be:<app> script (ts-node-dev --respawn -r tsconfig-paths/register); 2.0.0 is its latest release.'
+  tsc-alias:
+    version: 1.9.7
+    group: tooling
+    side: be
+    why: 'rewrites the path aliases in the compiled output (build:be); the reference app declares ^1.8.10 and resolves 1.9.7.'
+  tsconfig-paths:
+    version: 4.2.0
+    group: tooling
+    side: be
+    why: 'loads the path aliases for the dev runner (dev:be:<app>); the reference app declares ^4.2.0 and resolves 4.2.0.'
   # --- test
   jest:
     version: 29.7.0
@@ -146,11 +191,16 @@ pins:
     version: 19.2.3
     group: framework
     side: fe
+  nest-commander:
+    version: 3.21.0
+    group: framework
+    side: be
+    why: 'the one command-line framework of a back end (R148-R150): apps/cli boots with CommandFactory.run and every one-off action is a nest-commander command of src/features/cli; 3.21.0 is the newest on 2026-10-02 and takes @nestjs 11 as its peer.'
   '@nestjs/core':
     version: 11.2.5
     group: framework
     side: be
-    why: nivo-backend resolves 11.1.27, starci-next and mia-mia-backend 11.2.5.
+    why: one product back end resolves 11.1.27, the others 11.2.5.
   '@nestjs/common':
     version: 11.2.5
     group: framework
@@ -167,30 +217,111 @@ pins:
     version: 11.1.1
     group: framework
     side: be
-    why: readiness probes with dependency indicators use Terminus (the liveness route of the hfs sync --init skeleton does not, being a thin door over the liveness service); nivo-backend, starci-next and mia-mia-backend all resolve 11.1.1.
+    why: readiness probes with dependency indicators use Terminus (the liveness route of the scaffolded skeleton does not, being a thin door over the liveness service); every measured product back end resolves 11.1.1.
+  '@nestjs/cqrs':
+    version: 11.0.3
+    group: framework
+    side: be
+    why: 'the CQRS module of the application layer (commands, queries, handlers); the reference app declares ^11.0.3 and resolves 11.0.3.'
+  '@nestjs/typeorm':
+    version: 11.0.3
+    group: framework
+    side: be
+    why: 'the Nest bridge of TypeORM; the reference app declares ^11.0.3 and resolves 11.0.3.'
+  typeorm:
+    version: 0.3.31
+    group: framework
+    side: be
+    why: 'the one ORM of a back end; the reference app declares ^0.3.20 and resolves 0.3.31.'
+  pg:
+    version: 8.23.1
+    group: framework
+    side: be
+    why: 'the Postgres driver behind TypeORM; the reference app declares ^8.12.0 and resolves 8.23.1.'
+  reflect-metadata:
+    version: 0.2.2
+    group: framework
+    side: be
+    why: 'the decorator-metadata runtime Nest reads; the reference app declares ^0.2.2 and resolves 0.2.2.'
+  rxjs:
+    version: 7.8.2
+    group: framework
+    side: be
+    why: 'the observable runtime Nest is built on; the reference app declares ^7.8.1 and resolves 7.8.2.'
+  tslib:
+    version: 2.8.1
+    group: framework
+    side: be
+    why: 'the helper runtime the TypeScript emit references (importHelpers); the reference app declares ^2.8.1 and resolves 2.8.1.'
+  server-only:
+    version: 0.0.1
+    group: framework
+    side: fe
+    why: 'the Next.js marker that fails a client bundle that imports it; the i18n workspace of the reference app declares ^0.0.1.'
   next-intl:
     version: 4.13.6
     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.
+    why: every HFS front end uses next-intl with the [locale] segment (starci app scaffold writes it); the measured front end 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.'
+    why: 'one app package.json for both sides (hfs 4): where the two sides declared different ranges (^16.14.1 on a back end, ^16.14.2 on a front end), the higher wins; the measured product installs resolve 16.14.2. The example apps declared ^16.14.2 as well; each app root now has one dependencies entry at the pin.'
   supertest:
     version: 7.3.0
     group: tooling
     side: be
-    why: the e2e world of a back end calls the app over HTTP (/health/live in the skeleton); starci-next and mia-mia-backend resolve 7.3.0, nivo-backend 7.2.2.
+    why: the e2e world of a back end calls the app over HTTP (/health/live in the skeleton); two product back ends resolve 7.3.0, one 7.2.2.
   # --- ui
   '@heroui/react':
     version: 3.2.6
     group: ui
     side: fe
-    why: nivo-fe resolves 3.2.4, starci-next-fe and miamia-fe 3.2.6.
+    why: one product front end resolves 3.2.4, the others 3.2.6.
   '@heroui/styles':
     version: 3.2.6
     group: ui
     side: fe
-    why: nivo-fe resolves 3.2.4, starci-next-fe and miamia-fe 3.2.6.
+    why: one product front end resolves 3.2.4, the others 3.2.6.
+  tailwindcss:
+    version: 4.3.3
+    group: ui
+    side: fe
+    why: 'the styling engine of a front end; the reference app declares ^4 and resolves 4.3.3.'
+  '@tailwindcss/postcss':
+    version: 4.3.3
+    group: ui
+    side: fe
+    why: 'the PostCSS plugin tailwindcss 4 runs through; the reference app declares ^4 and resolves 4.3.3.'
+  # --- Supabase lite
+  '@supabase/ssr':
+    version: 0.12.7
+    group: framework
+    side: fe
+    why: the one server/browser client factory for a lite Next app; exact version registry-checked for the lite scaffold.
+  '@supabase/supabase-js':
+    version: 2.117.2
+    group: framework
+    side: both
+    why: the generated Database-typed client used by the FE data owner and the BE Auth/Storage integration.
+  jose:
+    version: 6.2.12
+    group: framework
+    side: be
+    why: verifies Supabase access tokens against the project JWKS with issuer, audience, expiry and algorithm checks.
+  supabase:
+    version: 2.119.0
+    group: tooling
+    side: both
+    why: the root CLI wrapper owns local schema lifecycle and generates the committed database types.
+  class-transformer:
+    version: 0.5.1
+    group: framework
+    side: be
+    why: Nest request transformation in the API runtime, pinned with the validation library.
+  class-validator:
+    version: 0.15.1
+    group: framework
+    side: be
+    why: Nest boundary validation in the API runtime, pinned with the transformation library.