@starci/hfs 4.0.9 → 4.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## 4.1.0 - 2026-10-08
 
 - Breaking (runtime alpha.4 CLI unification): remove the `hfs` bin and expose `main(argv, io)` for the sole `starci app ...` grammar; the app flags `--repo` and `--root` are replaced by the global `--cwd` flag.
 - Changed (contract change `coverage-modules-logic`): the coverage scope is derived once from the slot manifest (`coverage: required|none` on every tracked be slot, `ruleParams.be.logicRoles`; `scripts/hfs/coverage-scope.mjs`). `hfs sync` renders it into `be/jest.config.js` (`starciJestConfig({ coverage })`), `sonar.coverage.exclusions` and `codecov.yml` (the measured roots, plus one Codecov component per service app and one `platform`, each at 100); `coverageScope`, `coverageExclusions` and `HFS_SYNC_COVERAGE_SCOPE` are gone. New R204 `HFS_COVERAGE_SCOPE_DRIFT`: a hand edit of any of the three coverage statements is drift. `hfs scaffold app` renders with the source it just wrote.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) StarCi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/emit/operations.mjs

@@ -70,7 +70,7 @@ export function readOperations({ ts, program, file }) {
     const output = guard('output', member('output'));
     const refusalType = member('refusal');
     let refusal = [];
-    if (!(refusalType.flags & ts.TypeFlags.Never)) {
+    if ((refusalType.flags & ts.TypeFlags.Never) === 0) {
       const members = refusalType.isUnion() ? refusalType.types : [refusalType];
       if (!members.every((each) => each.isStringLiteral())) fail(`refusal must be a closed union of string literals, found ${checker.typeToString(refusalType)}`);
       refusal = members.map((each) => each.value).sort();

package/emit/type-schema.mjs

@@ -7,11 +7,12 @@
  * object type with no members and no index signature, and a union with `undefined` where a member could not simply be absent.
  * Pure: takes the TypeScript module and a checker.
  */
+import { byCodeUnit } from '../report/order.mjs';
 
 /** Sorts object keys at every depth, so equal schemas print equal text. */
 export function stable(value) {
   if (Array.isArray(value)) return value.map(stable);
-  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, stable(value[key])]));
   return value;
 }
 

package/lint/run.mjs

@@ -19,10 +19,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { linterReport, mergeReports, sonarReport, sourceRootsOf } from '../report/sonar.mjs';
 import { SIDES, appRelativeMessages, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 import { STYLE_GLOB } from '../sync/index.mjs';
+import { byCodeUnit } from '../report/order.mjs';
+import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
 
 export const LINT_SCHEMA = 'starci/lint@1';
 /** The side whose stylesheets stylelint judges. */
@@ -75,12 +77,14 @@ function runLinter({ cwd, pkg, bin, args, bound = null }) {
     return { error: `${pkg} is not installed for ${cwd}` };
   }
   const run = spawnSync(process.execPath, [...(bound ? linterBoundArgs() : []), entry, ...args], { cwd, encoding: 'utf8', maxBuffer: 512 * 1024 * 1024, ...(bound ? { env: { ...process.env, [BOUND_ENV]: bound } } : {}) });
-  // The linters exit 1 when they found something; no json at all means they could not run. ESLint prints its report on stdout,
-  // stylelint (16 and later) its formatter output on stderr.
+  // ESLint prints its report on stdout; stylelint uses stderr. JSON does not prove a completed child: only exits 0/1
+  // without a spawn error or signal are measurable, and exit 1 must carry findings.
   let results;
   try { results = JSON.parse(run.stdout.trim() || run.stderr); } catch { return { error: `${pkg} produced no json report in ${path.basename(cwd)}/ (exit ${run.status}): ${String(run.stderr || run.stdout).trim().split('\n')[0]}` }; }
   if (!Array.isArray(results)) return { error: `${pkg} produced a report that is not a result list` };
-  return { results };
+  const completed = !run.error && !run.signal && [0, 1].includes(run.status)
+    && (run.status === 0 || results.some((result) => result?.messages?.length || result?.warnings?.length));
+  return { results, ...(completed ? {} : { error: `${pkg} could not complete in ${path.basename(cwd)}/ (exit ${run.status}, signal ${run.signal ?? 'none'}): ${String(run.error?.message || run.stderr || run.stdout || '').trim().split('\n')[0]}` }) };
 }
 
 const eslintFindings = (results, appRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
@@ -98,6 +102,69 @@ const byLocation = (a, b) => `${a.path ?? ''}:${String(a.line ?? 0).padStart(7,
 /** The files of `changed` (app-relative) below `side`/, relative to the side folder. */
 const onSide = (changed, side) => changed.filter((file) => file.startsWith(`${side}/`)).map((file) => file.slice(side.length + 1));
 
+const fileKey = (file) => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
+const inside = (root, file) => { const rel = path.relative(root, file); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); };
+
+/** Read the installed canon's source selectors, then enumerate that scope; unavailable or unsupported selectors cannot prove coverage. */
+async function sourceFiles({ repoRoot, cwd, side, scope }) {
+  const entry = createRequire(path.join(cwd, 'package.json')).resolve(`@starci/eslint-canon-${side}`);
+  if (!inside(fs.realpathSync(repoRoot), fs.realpathSync(entry))) throw new Error('the installed canon is outside the app root');
+  const canon = await import(pathToFileURL(entry).href);
+  const factory = side === 'be' ? canon.starciBeConfig : canon.starciFeConfig;
+  if (typeof factory !== 'function' || typeof canon.loadHfs !== 'function') throw new Error('the installed canon has no supported config factory');
+  const config = await factory({ hfs: canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href) });
+  if (!Array.isArray(config)) throw new Error('the installed canon did not return a flat config');
+  const selectors = [], ignored = [];
+  for (const block of config) {
+    if (!block || typeof block !== 'object') throw new Error('the installed canon returned an invalid config block');
+    for (const [field, target] of [['files', selectors], ['ignores', ignored]]) {
+      if (block[field] === undefined) continue;
+      if (!Array.isArray(block[field]) || block[field].some((glob) => typeof glob !== 'string' || glob.startsWith('!'))) throw new Error(`unsupported canon ${field} selectors`);
+      if (field === 'ignores' && Object.keys(block).some((key) => !['ignores', 'name'].includes(key))) throw new Error('unsupported non-global canon ignores');
+      target.push(...block[field].flatMap((glob) => braceVariants(glob).map(globExpression)));
+    }
+  }
+  if (!selectors.length) throw new Error('the installed canon has no source selectors');
+  const matches = (patterns, file) => patterns.some((pattern) => pattern.test(file));
+  const files = [];
+  const visit = (folder) => {
+    for (const child of fs.readdirSync(path.join(cwd, folder), { withFileTypes: true })) {
+      const file = posix(path.join(folder, child.name));
+      // Ask the canon's global ignore patterns before entering output or installed-package trees.
+      if (matches(ignored, file) || matches(ignored, `${file}/__starci_scope_probe__`)) continue;
+      if (child.isSymbolicLink()) throw new Error(`cannot enumerate symlink ${file}`);
+      if (child.isDirectory()) visit(file);
+      else if (child.isFile() && matches(selectors, file)) files.push(file);
+    }
+  };
+  visit(scope ?? '');
+  return files.sort(byCodeUnit);
+}
+
+/** Every requested source needs an explicit, well-formed result; suppressed findings and foreign paths cannot witness a completed lint. */
+function checkedEslintResults({ results, expected, cwd, scope, changed }) {
+  const required = new Set(expected.map((file) => fileKey(path.join(cwd, file))));
+  const seen = new Set(), valid = [], errors = [];
+  for (const result of results) {
+    if (!result || typeof result.filePath !== 'string' || !path.isAbsolute(result.filePath) || !Array.isArray(result.messages)
+      || result.messages.some((message) => !message || typeof message.message !== 'string')
+      || (result.suppressedMessages !== undefined && !Array.isArray(result.suppressedMessages))) {
+      errors.push('eslint produced a malformed file result'); continue;
+    }
+    const key = fileKey(result.filePath);
+    if (!inside(cwd, result.filePath) || (scope && !inside(path.join(cwd, scope), result.filePath)) || (changed && !required.has(key))) {
+      errors.push(`eslint produced a result outside the requested scope: ${result.filePath}`); continue;
+    }
+    if (seen.has(key)) errors.push(`eslint produced duplicate results for ${result.filePath}`);
+    seen.add(key);
+    if (result.suppressedMessages?.length) errors.push(`eslint suppressed findings for ${result.filePath}`);
+    valid.push(result);
+  }
+  const missing = expected.filter((file) => !seen.has(fileKey(path.join(cwd, file))));
+  if (missing.length) errors.push(`eslint produced no result for requested source files: ${missing.join(', ')}`);
+  return { results: valid, errors };
+}
+
 /**
  * Run the whole lint of the app at `repoRoot`. `hfsCheck(repoRoot)` returns the `starci app check` result (`{ findings, tracked }`); the CLI
  * injects it. Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
@@ -130,9 +197,16 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
     if (workspace !== null && side !== STYLE_SIDE) { engines.eslint.sides[side] = { files: 0, skipped: `outside --workspace ${workspace}` }; continue; }
     const sources = onSide(existing, side).filter((file) => /\.(?:[cm]?[jt]sx?)$/.test(file));
     if (changed !== null && !sources.length) { engines.eslint.sides[side] = { files: 0, skipped: 'no changed source file' }; continue; }
-    const linted = runLinter({ cwd: path.join(repoRoot, side), pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : [onFe ?? '.'])], bound: repoRoot });
+    const cwd = path.join(repoRoot, side);
+    let expected;
+    try { expected = changed ? sources : await sourceFiles({ repoRoot, cwd, side, scope: onFe }); }
+    catch (error) { errors.push(`eslint source scope is unavailable in ${side}/: ${String(error?.message ?? error)}`); engines.eslint.sides[side] = { files: 0 }; continue; }
+    const linted = runLinter({ cwd, pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : [onFe ?? '.'])], bound: repoRoot });
     if (linted.error) errors.push(linted.error);
-    else {
+    if (linted.results) {
+      const checked = checkedEslintResults({ results: linted.results, expected, cwd, scope: onFe, changed: changed !== null });
+      errors.push(...checked.errors);
+      linted.results = checked.results;
       // The side canon names side-relative paths in its messages; the report names every path from the app root.
       const appRelative = appRelativeMessages(side, path.join(repoRoot, side));
       for (const result of linted.results) for (const message of result.messages ?? []) message.message = appRelative(message.message);
@@ -148,7 +222,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
     if (changed === null || styles.length) {
       const linted = runLinter({ cwd: path.join(repoRoot, STYLE_SIDE), pkg: 'stylelint', bin: 'stylelint', args: [...(changed ? styles : [onFe ? `${onFe}/src/**/*.css` : STYLE_GLOB]), '--formatter', 'json', ...(opts.fix ? ['--fix'] : [])] });
       if (linted.error) errors.push(linted.error);
-      else {
+      if (linted.results) {
         const appRelative = appRelativeMessages(STYLE_SIDE, path.join(repoRoot, STYLE_SIDE));
         for (const result of linted.results) for (const warning of result.warnings ?? []) warning.text = appRelative(warning.text);
         raw.stylelint = linted.results;
@@ -183,7 +257,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
     linterReport('eslint', raw.eslint, { root: repoRoot, sourceRoots, tracked }),
     linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked }),
   ]);
-  const report = { schema: LINT_SCHEMA, ok: findings.length === 0 && errors.length === 0, repoRoot, changed: changed ? [...changed].sort() : null, workspace, counts: { error: findings.length }, engines, errors, findings };
+  const report = { schema: LINT_SCHEMA, ok: findings.length === 0 && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, counts: { error: findings.length }, engines, errors, findings };
   return { report, sonar, exit: errors.length ? 2 : findings.length ? 1 : 0 };
 }
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@starci/hfs",
-  "version": "4.0.9",
+  "version": "4.1.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "private": false,
   "exports": {
     ".": "./src/main.mjs",
@@ -15,6 +15,7 @@
     "smol-toml": "1.9.0"
   },
   "files": [
+    "LICENSE",
     "src/main.mjs",
     "emit/**",
     "lint/**",

package/report/order.mjs

@@ -0,0 +1,2 @@
+// order.mjs - the one code-unit comparator of @starci/hfs: the order Array.prototype.sort gives without a compare function (UTF-16 code units), named so the digests, emitted files and reports that depend on it stay byte-identical.
+export const byCodeUnit = (a, b) => { const l = String(a), r = String(b); return l < r ? -1 : l > r ? 1 : 0; };

package/runtime/config.example.yaml

@@ -0,0 +1,187 @@
+# config.example.yaml — seed for the per-project owner config.
+# The installer copies this file to the gitignored `config.yaml` next to it;
+# owners edit that copy. Everything below is read at runtime — no key here is
+# decorative. Kernel route precedence: explicit `--agent` flag >
+# `kernel` below > the tier chain (modules/models/tiers.yaml).
+language: vi
+model: null
+effort: medium
+# Explicit current owner adoption is required; shipped defaults grant no trust or purge authority.
+# launchTrust: {profile: automatic, approvedBy: owner, approvalRef: '<current approval>', roots: ['<exact absolute repository root>']}
+# profile: declined preserves an explicit decision; provider-side declines also remain authoritative.
+launchTrust: null
+# retention: {workflowPurge: {approvedBy: owner, approvalRef: '<current approval>', repos: ['<exact absolute ledger-owner repo>']}}
+retention: null
+# kernel — the long-lived [Kernel] seat. It takes the `high` tier of modules/models/tiers.yaml (an ordered chain of
+# members; the picker takes the first member with tokens after your bias and the balance step; docs/config-format.md).
+# {agent?, model?, effort?}: agent and/or model PIN the seat — the bias `only`, keeping the tier's model of that agent
+# (an explicit `--agent` flag is the same bias and wins). effort: the seat's effort; null takes the tier member's effort.
+kernel: {effort: high}
+# parallel — the one knob for how wide the workers run. `gear` indexes the agent
+# table in modules/models/runtimes.yaml allocation.slicing.size: a long (`l`)
+# operation asks for the `l.agents[gear]` agents, an extra-long (`xl`) one for
+# `xl.agents[gear]`; `s` and `m` operations are always one agent. Declared gears
+# are allocation.slicing.gears — an undeclared value fails closed. Absent means
+# the first declared gear. A gear raises only what `starci kernel estimate` requests; it
+# never raises a pool's maxParallel, maxParallelOps or budgets.maxOps below.
+parallel: {gear: 1}
+# supervisor — the optional chat digest cadence. pollIntervalMs controls
+# scripts/supervisor/poll.mjs when run continuously (its floor is the config
+# validation of engine/config.mjs); null uses scripts/machine/home.mjs
+# DEFAULTS, and --interval-ms overrides this key.
+# The reconciler engine owns host runtime cadence and restores seats after reboot.
+# repos: managed product ledger-owner repositories for the reconciler and Supervisor tools,
+# relative to the source root (the directory holding this skill) or absolute.
+# --repo on the poll command line can add another. stallMinutes (optional,
+# integer >= 5) marks a running workflow STALLED in scripts/supervisor/stall.mjs;
+# the Workflow controller turns actionable findings into Decision Items. The [Supervisor]
+# kernel (docs/supervisor.md) also takes, optional, defaults in home.mjs DEFAULTS:
+#   kernel: {agent, model, effort}   its agent pin (default: the kernel pin below)
+#   workers: {base, max}             the adaptive [Worker] cap, 0 to 10 (0 = the Supervisor runs no fix worker)
+#   landGate: {mode: shared}         shared lets running lanes commit directly; exclusive = gate only. A land
+#                                    fast-forwards LOCAL main only: the remote main moves with a release (starci release cut)
+supervisor:
+  # mode: chat (default) - the owner's desktop chat session is the Supervisor: it owns channel 'main'
+  #   and reads Decision Items; nothing starts a [Supervisor] kernel. kernel - the optional [Supervisor]
+  #   Orca kernel (scripts/supervisor/start-supervisor.mjs), kept alive by the reconciler Host controller.
+  #   See docs/supervisor.md.
+  # mode: chat
+  pollIntervalMs: null
+  repos: []
+  # frozenMinutes: <n>   # Host seat check: a busy frame unchanged this long is frozen, not busy
+  # landGate: {mode: shared|exclusive}
+# delegation — while the owner is away, a named delegate (e.g. the supervisor chat) may
+# answer owner asks until the given time; excluded classes stay owner-only. null = none.
+#   delegation: {asks: supervisor, until: 2026-09-23T09:00:00+07:00,
+#     excludes: [credentials, oauth-consent, payments, legal, payment-provider]}
+delegation: null
+# budgets — the owner's ceiling, surfaced by every plan before `ok`. Null = unbounded.
+budgets:
+  maxOps: null       # max concurrent dispatched ops one workflow may hold open;
+                     # route/dispatch refuse `max-ops` at min(this, maxParallelOps)
+# allocation — the owner's default grant for a pool whose capacity is an explicit grant (Devin).
+#   grants: '<pool>=<slots>@<role>+<role>' — the default grant every workflow gets. Once a grants list is
+#     declared it is the whole set: a pool whose registry.yaml capacityAuthority is explicit-workflow-quota
+#     (Devin) routes only for the roles and up to the running slots a grant names ([] closes it).
+allocation:
+  grants: [devin-agent=10@implement+verify+write]
+# models — optional overrides of the shipped model tiers (modules/models/tiers.yaml owns the defaults). Every key is optional:
+#   tiers:   {<tier>: [{agent, model, effort?}, ...]}  replaces or adds one tier's ordered member chain
+#   seats:   {<seat>: <tier>}                          remaps a seat (supervisor, kernel, worker, planner, validator, kernelManager)
+#   balance: {maxStreak, maxSharePercent}              a head member picked maxStreak times in a row, or holding more than
+#                                                      maxSharePercent of the tier's running seats, yields to the next member
+#   usage:   {reservePercent, biasPercent}             a member at reservePercent of its tokens is skipped; an owner bias
+#                                                      naming it keeps it usable up to biasPercent; never above it
+models: {}
+# connectors — the owner's public ask channel (docs/connectors.md). Everything is off by default.
+# One local gateway (scripts/connectors/ask-gateway.mjs) fronts every serve-ask form; a Cloudflare
+# tunnel (scripts/connectors/tunnel.mjs) publishes the gateway; when serve-ask binds a form, the
+# kernel's ask path sends the owner one Telegram message (scripts/connectors/telegram.mjs) with the
+# question, its options and the public link. Telegram carries owner asks only.
+# SECRETS NEVER GO IN THIS FILE: tokenEnv/botTokenEnv NAME an environment variable holding the token
+# (or <NAME>_FILE pointing at a custody file); a value that is not an UPPER_SNAKE env var name is refused.
+#   Host credentials use the canonical runtime root secret.env; docs/host-secrets.md owns setup.
+#     Supplied environment values win, including blank values. Missing local file adds no values.
+#   repos: ledger-owner repository roots whose asks go public, relative to the source root (the
+#     directory holding this skill) or absolute. [] = the source root plus every .workspaces project owner.
+#   gateway.port: the one fixed local port the tunnel points at (outside the 6969..7069 form band).
+#   cloudflare.mode: off | quick | named.
+#     quick — `cloudflared tunnel --url`, a random https://*.trycloudflare.com host, no account, no auth,
+#       a new host on every restart. Good for decisions only.
+#     named — a fixed `hostname`, authenticated one of two ways: `tunnel` (UUID) + `credentialsFile`
+#       (the JSON `cloudflared tunnel create` wrote; the manager writes its own ingress config mapping
+#       hostname -> the gateway and never reads ~/.cloudflared/config.yml), or a remotely managed tunnel
+#       token in `tokenEnv` (its public hostname is routed to http://127.0.0.1:<gateway.port> in the
+#       Cloudflare dashboard).
+#   cloudflare.access: whether a Cloudflare Access application guards `hostname` (informational; false
+#     prints a warning). Recommended for anything beyond yes/no decisions.
+#   telegram.enabled / chatId: the owner's chat with the bot (BotFather token in botTokenEnv). Send the
+#     bot /start, then `starci connect telegram discover-chat` prints the chat id.
+#   telegram.exposeCredentialAsks: false keeps a credential/secret ask off the public link — the message
+#     says to answer it on this machine and carries only the localhost link, and the gateway refuses it.
+connectors:
+  repos: []
+  gateway: {port: 7070}
+  cloudflare: {mode: off, tunnel: null, credentialsFile: null, tokenEnv: CLOUDFLARE_TUNNEL_TOKEN, hostname: null, access: false}
+  telegram:
+    enabled: false
+    botTokenEnv: TELEGRAM_BOT_TOKEN
+    chatId: null
+    exposeCredentialAsks: false
+# asks — owner asks that carry a recommended option (question.recommended, or exactly one option
+# marked "(recommended)" or its Vietnamese equivalents). autoAcceptRecommended: true answers such an
+# ask with its recommendation instead of serving the form: the ledger records ask-answered with
+# answeredBy auto-recommended, the kernel is woken, and Telegram gets one plain message naming the
+# pick. A later owner answer supersedes it. excludes lists the ask classes that always reach the owner:
+#   credential — any ask with secret fields, or of kind credential, account, access or consent;
+#   handover — every handover.review ask (always excluded, even when removed from this list);
+#   draw-review — the opt-out for drawings (interface.draw, scripts/work/draw-review.mjs): unlisted, a
+#     drawing the owner did not ask to review is accepted without the owner (its accept option is the
+#     recommendation); a drawing the owner asked for (a prior owner redraw of the record, the owner
+#     opened its form, or question.ownerRequested) always reaches the owner;
+#   or any ask kind: information, authority, business-decision, irreversible-confirmation, ...
+asks:
+  autoAcceptRecommended: false
+  excludes: [credential, irreversible-confirmation, handover]
+# uat — the machine-wide UAT ceiling. At most maxConcurrent UAT runs (a browser session, a player, the
+# app it drives) execute at once on this host, across every workflow; the rest wait queued for a slot
+# (scripts/uat/uat-slots.mjs, lock files under <runtime>/uat-slots). A slot whose holder died is
+# reclaimed. STARCI_UAT_MAX_CONCURRENT overrides it for one process tree.
+uat:
+  maxConcurrent: 10
+# orca — the owner's Orca app settings the runtime must know (engine/orca-config.mjs orcaSettings). maxWorkerDepth MUST equal
+# the worker depth set in the Orca app: the deepest worker Orca starts under the owner's chat (chat 0, Kernel or
+# Supervisor 1, op or [Worker] 2, draw critic 3). Orca exposes no read of it, so the runtime trusts this value and refuses
+# a deeper launch before worker-start (worker-depth-exceeded). `start --check` with STARCI_ORCA_LIVE=1 measures Orca's
+# real limit and turns red when the two differ.
+orca:
+  maxWorkerDepth: 4
+# debugLoop — the debug watcher. Workflow DEBUG is a /loop of the chat that started the workflow (the /starci skill sets it up in
+# Claude Code and Codex; no seat, no background agent, nothing in the runtime schedules it). Each tick runs the read-only
+# `starci debug digest`. interval is the loop cadence (<n>s | <n>m | <n>h, default `10m` = `debugLoop.interval`); worktreeLimit is the
+# per-repository core-watch alert threshold (default `40` = `debugLoop.worktreeLimit`). Both keys are optional (engine/config.mjs DEBUG_LOOP_DEFAULTS).
+debugLoop:
+  interval: 10m
+  worktreeLimit: 40
+# reconciler — the host's one reconciler engine (scripts/reconciler/engine.mjs; contract
+# modules/reconciler/reconciler.yaml). Each controller runs off | shadow (reads, records what it would do as
+# reconciler.would rows, runs nothing) | active (acts; the old loop yields that duty via scripts/reconciler/owns.mjs).
+# profile — the operational default of every controller, so a host is never left all-shadow by accident:
+#   operational  job, host, workflow, resource active (they settle jobs, start services and seats, wake stalled
+#                workflows, throttle); gc, workers, learning shadow. The `start` skill applies and checks it.
+#   observe      every controller shadow (read-only; a debugging or audit host).
+#   (absent)     only the explicit controllers.<name>.mode entries count; an unnamed controller is off.
+# controllers.<name>.mode overrides the profile for that one controller (e.g. gc: {mode: active}).
+# Rollback of a controller: set its mode to off (the old loops take the duty back within
+# allocation.reconciler.heartbeatStaleMs). Numbers: modules/models/runtimes.yaml allocation.reconciler.
+reconciler:
+  enabled: true
+  profile: operational
+  controllers: {}
+# specs.unit / specs.e2e in workflows (the `specs` map near the top; owner 2026-09-28 "speed up development;
+# test later when asked"; scripts/route/spec-deferral.mjs). Each op brief's policy.specsToggle says what it does:
+#   unit: false - backend.implement, interface.implement and code.refactor run no jest/vitest/test:ci/coverage
+#     and demand no changed-line coverage (Sonar still runs: bugs, smells, security gate);
+#     test.author legs are never dispatched; review/handover gates do not count unit tests or coverage.
+#   e2e: false - e2e.verify legs and e2e test authoring are never dispatched; uat.verify is not e2e.
+#   A leg that is not dispatched settles `deferred: specs.<class>=false` with no attempt spent and the workflow
+#   proceeds past it; starci kernel status lists testsDeferred and `starci kernel run-deferred-tests --workflow <id> [--kind unit|e2e]`
+#   runs them later. Read on every wake: flipping a switch needs no restart.
+# roots — where this host keeps the archive, the lane worktrees and its temporary files, when the owner moves them off the defaults.
+# All keys are optional absolute directories; env STARCI_ARCHIVE_ROOT / STARCI_LANES_ROOT / STARCI_TEMP_ROOT win over them, and an
+# absent key means <starciLocalRoot>/archive (<runtime root>/.runtime/archive), the per-user profile lanes directory, kept out of the checkout (scripts/machine/home.mjs lanesRoot),
+# and the OS temp directory (engine/temp-root.mjs tempRoot; the processes the runtime starts get it as TEMP/TMP/TMPDIR). No host location lives in
+# a tracked file: set the real directories only in the gitignored config.yaml copy, e.g.
+#   roots: {archive: <absolute directory>, lanes: <absolute directory>, temp: <absolute directory>}
+# sonar — the SonarCloud organization the release's Sonar proof of the example apps analyses in (scripts/supervisor/release-sonarcloud.mjs). It is configuration, not a secret,
+# so it lives here and not in secret.env; the project keys are <organization>_starci-example-<app>. The environment variable SONAR_ORGANIZATION wins over it (CI reads the
+# repository variable of the same name). Empty until the owner sets it in the gitignored config.yaml copy, e.g.
+#   sonar: {organization: <the organization key shown on sonarcloud.io>}
+sonar: {organization: null}
+# resources — the host capacity floors the dispatch gate enforces, over the shipped numbers of modules/models/runtimes.yaml allocation.resources
+# (scripts/machine/host-resources.mjs; docs/config-format.md "Host resource floors"). Every key is optional (a number above 0, or null):
+#   minFreeDiskGb  free GB a drive holding the temp root or the repository must keep
+#   minFreeDiskPct the same floor as a percentage of the drive's size; with minFreeDiskGb the larger requirement applies
+#   minFreeRamPct  free-RAM percentage below which no new heavy op starts
+# set them only in the gitignored config.yaml copy, e.g.
+#   resources: {minFreeDiskGb: 5, minFreeDiskPct: 1, minFreeRamPct: 10}

package/runtime/engine/by-code-unit.mjs

@@ -0,0 +1,12 @@
+// by-code-unit.mjs - the comparator of a bare `Array.prototype.sort()`, owned beside the engine files that digest and canonicalize (scripts/lib/list.mjs re-exports it).
+
+/**
+ * The comparator of a bare `Array.prototype.sort()`: values compared as strings by UTF-16 code unit. Pass it to `sort` and
+ * `toSorted` so the order is stated, and stays byte-identical to the default order that digests and canonical output depend on.
+ */
+export const byCodeUnit = (a, b) => {
+  const left = String(a);
+  const right = String(b);
+  if (left < right) return -1;
+  return left > right ? 1 : 0;
+};