@starci/hfs 4.0.9 → 4.0.10

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/lint/run.mjs

@@ -19,10 +19,11 @@ 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 { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
 
 export const LINT_SCHEMA = 'starci/lint@1';
 /** The side whose stylesheets stylelint judges. */
@@ -75,12 +76,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 +101,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();
+}
+
+/** 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 +196,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 +221,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;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@starci/hfs",
-  "version": "4.0.9",
+  "version": "4.0.10",
   "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/runtime/engine/admission.mjs

@@ -0,0 +1,308 @@
+import { createHash } from 'node:crypto';
+import { refuse } from './refuse.mjs';
+
+const PATH_LEASE_PREFIX='path:';
+const GLOB_META=/[*?[\]{}]/;
+// Next.js App Router spells route segments as literal directory names: dynamic `[lang]`, catch-all
+// `[...slug]` and optional catch-all `[[...opt]]`, optionally behind an intercept prefix `(.)`, `(..)`,
+// `(...)` or `(..)(..)`. Route groups `(group)`, parallel slots `@slot` and intercepts on a static name
+// carry no glob meta at all. A segment of exactly this shape is a concrete name, never a character class;
+// every consumer that hands an owned path to a glob engine escapes it (git: ownedPathspec below).
+const APP_ROUTER_SEGMENT=/^(?:\(\.{1,3}\))*(?:\[\[\.\.\.[A-Za-z0-9_$-]+\]\]|\[(?:\.\.\.)?[A-Za-z0-9_$-]+\])$/;
+
+/** A Next.js App Router bracket segment (`[id]`, `[...slug]`, `[[...opt]]`, `(.)[id]`) — a literal directory name. */
+export const isAppRouterSegment=part=>APP_ROUTER_SEGMENT.test(String(part??''));
+
+/** A path segment that is a real glob (`*`, `?`, `{a,b}`, a bare character class), not an App Router name. */
+export const isGlobSegment=part=>GLOB_META.test(String(part??''))&&!isAppRouterSegment(part);
+
+/**
+ * The git pathspec for one concrete owned path. Git reads a plain pathspec as a glob, so `src/app/[id]`
+ * would also match a sibling `src/app/i`; `:(literal)` pins it to the named directory. Admission
+ * refuses a glob, so every owned path is literal.
+ */
+export const ownedPathspec=spec=>`:(literal)${String(spec??'').replace(/\\/g,'/')||'.'}`;
+
+const plainPath=value=>typeof value==='string'?value:value?.path;
+
+/**
+ * Canonical workspace-relative path prefix used by planning, leases and report boundaries. In a
+ * multi-repository project the caller includes the repository binding prefix (for example `my-app/`).
+ * A directory prefix is spelled either bare (`docs/`) or with a trailing `/**`, which normalizes to
+ * the same prefix; every other glob, absolute path and parent traversal is refused because it is not
+ * a concrete ownership boundary. A Next.js App Router segment (`[lang]`, `[...slug]`, `[[...opt]]`,
+ * `(group)`, `@slot`, `(.)photo`) is a literal directory name and is admitted as one.
+ */
+export function normalizeOwnedPath(value){
+  let input=String(plainPath(value)??'').trim().replace(/\\/g,'/');
+  input=input.replace(/\/\*\*\/$/,'').replace(/\/\*\*$/,'');
+  if(!input||input.startsWith('/')||/^[A-Za-z]:\//.test(input))throw Error(`owned path must be repository-relative: ${JSON.stringify(plainPath(value)??value)}`);
+  const parts=[];
+  for(const part of input.split('/')){
+    if(!part||part==='.')continue;
+    if(part==='..')throw Error(`owned path must not traverse its repository: ${JSON.stringify(plainPath(value)??value)}`);
+    if(isGlobSegment(part))throw Error(`owned path must be a concrete prefix, not a glob: ${JSON.stringify(plainPath(value)??value)}`);
+    parts.push(part);
+  }
+  if(!parts.length)throw Error(`owned path must name a concrete repository-relative prefix: ${JSON.stringify(plainPath(value)??value)}`);
+  return parts.join('/');
+}
+
+/** Normalize, de-duplicate and collapse descendants already covered by an owned ancestor. */
+export function normalizeOwnedPaths(values=[]){
+  const paths=[...new Set(values.map(normalizeOwnedPath))].sort((a,b)=>a.length-b.length||a.localeCompare(b));
+  return paths.filter((candidate,index)=>!paths.slice(0,index).some(parent=>ownedPathsIntersect(parent,candidate)));
+}
+
+/** Path-prefix overlap: equality or either concrete path being below the other. */
+export function ownedPathsIntersect(left,right){
+  const a=normalizeOwnedPath(left),b=normalizeOwnedPath(right);
+  return a===b||a.startsWith(`${b}/`)||b.startsWith(`${a}/`);
+}
+
+/** The durable resource identity for one normalized concrete owned path. */
+export const ownedPathLeaseKey=value=>`${PATH_LEASE_PREFIX}${normalizeOwnedPath(value)}`;
+
+/** One capacity-one request per minimal owned prefix. */
+export const ownedPathLeaseRequests=values=>normalizeOwnedPaths(values).map(path=>({resourceKey:ownedPathLeaseKey(path),units:1}));
+
+const leasePath=resourceKey=>String(resourceKey??'').startsWith(PATH_LEASE_PREFIX)
+  ?String(resourceKey).slice(PATH_LEASE_PREFIX.length):null;
+
+/**
+ * The spelling two lease paths are compared in. The same file must compare equal however a workflow
+ * spelled it (a past incident had `apps/app/src/messages/vi.json` spelled bare for
+ * the fe repository while the repository-prefixed spelling of the same file never overlapped it). `canonicalOf`
+ * (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}={})=>{
+  let value=normalizeOwnedPath(leasePathValue);
+  if(canonicalOf){try{value=normalizeOwnedPath(canonicalOf(value,row)??value);}catch{/* an unresolvable spelling compares as written */}}
+  return platform==='win32'?value.toLowerCase():value;
+};
+
+/**
+ * Find durable path leases that overlap a requested parent/child prefix. Lease-row existence is the
+ * fence; expiry is only a recovery signal and does not by itself prove the prior worker has no effect.
+ * Both sides are compared in leaseCompareForm, so a bare and a repository-prefixed spelling of one
+ * file overlap and the same relative path in two repositories does not.
+ */
+export function findOwnedPathLeaseConflicts(db,requests,{excludeJobId=null,canonicalOf=null,platform=process.platform}={}){
+  const requested=[...new Set(requests.map(item=>item?.resourceKey??item).filter(key=>leasePath(key)!==null))];
+  if(!requested.length)return [];
+  const held=db.prepare("SELECT resource_key,job_id,workflow_id,op_id,try_no AS attempt,generation,expires_at FROM leases WHERE resource_key LIKE 'path:%' ORDER BY resource_key,job_id").all();
+  const formOf=new Map();
+  const compare=(key,row)=>{
+    const id=`${row?.job_id??''}\0${key}`;
+    if(!formOf.has(id))formOf.set(id,leaseCompareForm(leasePath(key),{canonicalOf,row,platform}));
+    return formOf.get(id);
+  };
+  const conflicts=[];
+  for(const requestKey of requested){
+    const requestPath=compare(requestKey,null);
+    for(const row of held){
+      if(excludeJobId&&row.job_id===excludeJobId)continue;
+      if(ownedPathsIntersect(requestPath,compare(row.resource_key,row)))conflicts.push({requested:requestKey,held:row.resource_key,...row});
+    }
+  }
+  return conflicts;
+}
+
+/** Existing durable path and resource checks, read inside the caller's reservation transaction. */
+export function resourceAdmission(db,repoNeeds,{at,canonicalOf=null}={}){
+  const reasons=[];
+  const pathConflicts=findOwnedPathLeaseConflicts(db,repoNeeds,{canonicalOf});
+  for(const conflict of pathConflicts)reasons.push(`resource ${conflict.requested} overlaps durable lease ${conflict.held} held by ${conflict.job_id}`);
+  for(const item of repoNeeds){
+    const row=db.prepare('SELECT capacity FROM resources WHERE resource_key=?').get(item.resourceKey);
+    const capacity=row?.capacity??1;
+    const used=db.prepare('SELECT COALESCE(SUM(units),0) u FROM leases WHERE resource_key=? AND expires_at>?').get(item.resourceKey,at).u;
+    if(used+item.units>capacity)reasons.push(`resource ${item.resourceKey} capacity ${capacity} has ${used} used and needs ${item.units}`);
+  }
+  if(reasons.length)return {ok:false,reason:reasons.join('; '),reasons,pathConflicts:pathConflicts.map(({requested,held,job_id,workflow_id,op_id,expires_at})=>({requested,held,jobId:job_id,workflowId:workflow_id,opId:op_id,expiresAt:expires_at}))};
+  return {ok:true};
+}
+
+/**
+ * The concurrent-operation ceiling one workflow is admitted at. Two declared numbers meet here and
+ * the LOWER of them admits: the owner's `budgets.maxOps` (per workflow) and `maxParallelOps` from
+ * modules/models/runtimes.yaml (worker-wide). A null, absent or non-positive value is unbounded, so
+ * a workflow with no owner budget still meets the worker ceiling. A parallelism gear raises what
+ * `starci kernel estimate` requests and never raises either of these.
+ */
+export function opSlotCeiling({maxOps=null,maxParallelOps=null}={}){
+  const positive=value=>{const n=Number(value);return Number.isInteger(n)&&n>0?n:null;};
+  const owner=positive(maxOps),workers=positive(maxParallelOps);
+  if(owner===null&&workers===null)return {ceiling:null,source:null};
+  if(owner===null)return {ceiling:workers,source:'maxParallelOps'};
+  if(workers===null)return {ceiling:owner,source:'budgets.maxOps'};
+  return owner<=workers?{ceiling:owner,source:'budgets.maxOps'}:{ceiling:workers,source:'maxParallelOps'};
+}
+
+/**
+ * Admission against that ceiling. `running` is how many operations of the one workflow already hold
+ * a slot; a job at or above the ceiling is refused `max-ops` rather than launched and left to
+ * discover the cap from a provider.
+ */
+export function admitOpSlot({running=0,maxOps=null,maxParallelOps=null}={}){
+  const {ceiling,source}=opSlotCeiling({maxOps,maxParallelOps});
+  const held=Math.max(0,Number(running)||0);
+  if(ceiling===null)return {ok:true,running:held,ceiling:null,ceilingSource:null,reason:null};
+  return held<ceiling
+    ?{ok:true,running:held,ceiling,ceilingSource:source,reason:null}
+    :{ok:false,running:held,ceiling,ceilingSource:source,reason:'max-ops'};
+}
+
+/** Count this workflow's durable held slots and judge the same declared ceiling at preflight and reservation. */
+export function workflowOpSlots(db,workflowId,{excludeJobId=null,holdingStatuses,maxOps=null,maxParallelOps=null}={}){
+  if(!Array.isArray(holdingStatuses)||!holdingStatuses.length)throw Error('workflowOpSlots requires canonical held statuses');
+  const running=db.prepare(`SELECT count(*) n FROM jobs WHERE workflow_id=? AND kind<>'kernel' AND job_id<>?
+    AND status IN (${holdingStatuses.map(()=>'?').join(',')})`).get(workflowId,excludeJobId??'',...holdingStatuses).n;
+  return admitOpSlot({running,maxOps,maxParallelOps});
+}
+
+const rowObject=value=>{
+  if(value&&typeof value==='object')return value;
+  if(typeof value!=='string'||!value.trim())return {};
+  try{const parsed=JSON.parse(value);return parsed&&typeof parsed==='object'?parsed:{};}catch{return {};}
+};
+
+/**
+ * The durable payload/result of a job-shaped row: the parsed object when the row carries the decoded
+ * field (a mapped ledger row), else the tolerant parse of its `*_json` text — a missing, blank or
+ * unparsable field reads as {}. Several scripts spell this by hand; these are the one pair to cite.
+ */
+export const payloadOf=job=>rowObject(job?.payload??job?.payload_json);
+export const resultOf=job=>rowObject(job?.result??job?.result_json);
+
+/** The settled verdict of an attempt that asked the owner and waits for the answer. */
+export const AWAITING_OWNER='awaiting-owner';
+/**
+ * jobs.status of a try that ended asking the owner (report outcome ask): settled, but neither a failure nor a spent try
+ * (its unit's try budget and business retries ignore it). A retry or resume may follow it exactly as it follows `failed`.
+ */
+export const AWAITING_OWNER_STATUS='awaiting_owner';
+export const RETRYABLE_JOB_STATUSES=Object.freeze(['failed',AWAITING_OWNER_STATUS]);
+/** Every jobs.status that holds nothing the runtime still needs (mirrors engine/db/ledger.mjs JOB_STATUSES.settled). */
+export const SETTLED_JOB_LIST=Object.freeze(['succeeded','failed',AWAITING_OWNER_STATUS,'cancelled']);
+/** The tries of a unit that spent budget: every try but the ones that only waited on the owner. */
+export const spentTries=tries=>tries.filter(job=>job.status!==AWAITING_OWNER_STATUS).length;
+// An attempt the environment killed with effects on the tree (a host terminal wipe: every Orca terminal
+// gone at once, scripts/kernel/cli.mjs hostTerminalWipeOf) settles failed with this retryClass: its retry
+// is a new durable attempt that continues the partial tree and spends no business retry.
+export const RETRY_CLASS_ENVIRONMENT='environment';
+
+/**
+ * Classify a settled attempt for retry accounting. Infrastructure is free only when the durable result
+ * explicitly proves `effectState: none`; unknown or partial effects consume the ordinary business budget.
+ * An attempt settled `awaiting-owner` asked a question and did not fail: its successor is a new durable
+ * attempt (the ask attempt ran) that spends no business retry. Nor does one settled `peerBlocked`
+ * (starci kernel settle: every red check was a peer's change, scripts/kernel/gate-attribution.mjs), nor one settled
+ * with retryClass environment (RETRY_CLASS_ENVIRONMENT).
+ */
+export function retryDisposition(job){
+  const result=resultOf(job),reason=String(result.reason??'');
+  const infrastructure=result.retryClass==='infrastructure'||reason==='dispatch-rejected'||reason==='provider-unavailable';
+  const explicitlyReusable=(result.retryable===true&&result.attemptConsumed===false)||result.retryClass==='infrastructure';
+  const noEffect=infrastructure&&result.effectState==='none'&&explicitlyReusable;
+  const ownerAnswer=!noEffect&&result.verdict===AWAITING_OWNER;
+  const peerBlocked=!noEffect&&!ownerAnswer&&result.verdict!=='pass'&&Boolean(result.peerBlocked&&typeof result.peerBlocked==='object');
+  const environment=!noEffect&&!ownerAnswer&&!peerBlocked&&result.retryClass===RETRY_CLASS_ENVIRONMENT&&result.attemptConsumed===false;
+  return {
+    retryClass:noEffect?'infrastructure':ownerAnswer?'owner-answer':peerBlocked?'peer-blocked':environment?RETRY_CLASS_ENVIRONMENT:'business',
+    effectState:result.effectState??'unknown',
+    resumable:noEffect,
+    consumesBusinessRetry:!noEffect&&!ownerAnswer&&!peerBlocked&&!environment,
+  };
+}
+
+/**
+ * A row retired while still queued - `starci kernel reconcile --drop` (result.verdict `dropped`) or a goal revision
+ * that superseded it (result.reason `goal-revision-superseded`) - with no dispatch binding in its payload.
+ * It ran nothing, so it is no attempt: never a retry predecessor, never a cut seam, never the latest job
+ * of its ordinal (inc-5005d003825a: a retry chained to a dropped ordinal-1 row as business attempt 2 and
+ * lost the owner-answer lineage; inc-b428eb47fde3: ordinal 2 read a dropped seam as dependency-failed).
+ */
+export function retiredBeforeDispatch(job){
+  if(job?.status!=='cancelled')return false;
+  const result=resultOf(job),payload=payloadOf(job);
+  if(result.verdict!=='dropped'&&result.reason!=='goal-revision-superseded')return false;
+  const runtime=payload.hierarchy?.runtime??{};
+  const bound=Boolean(job.worker_id||payload.managed||payload.orca||runtime.dispatchId||runtime.terminalHandle
+    ||(Array.isArray(payload.rejectedDispatches)&&payload.rejectedDispatches.length));
+  return !bound;
+}
+
+
+/** The cut slice a job row carries, or null: {id, ordinal} identify one bounded SAME-op slice. */
+export function cutOf(job){
+  const cut=payloadOf(job).cut;
+  return cut&&cut.id!=null&&cut.ordinal!=null?{id:String(cut.id),ordinal:Number(cut.ordinal),total:Number(cut.total)}:null;
+}
+
+
+/* ------------------------------------------------------------ work units (H3, H4, H5) */
+
+/** The default try budget of a unit (Q13; DBTREE work_units.try_budget). Only the owner or the Supervisor raises one. */
+export const UNIT_TRY_BUDGET=5;
+const shortDigest=value=>createHash('sha256').update(value).digest('hex').slice(0,16);
+const lineagePaths=list=>(Array.isArray(list)?list:[]).map(item=>typeof item==='string'?item:item?.path).filter(p=>typeof p==='string'&&p.trim());
+const normList=list=>[...new Set(lineagePaths(list).map(p=>p.replace(/\\/g,'/').replace(/\/\*\*$/,'').replace(/\/+$/,'')))].sort();
+
+/**
+ * The work identity of a job (DBTREE work_units.subject_key): a cut slice is `cut:<id>#<ordinal>`, an op about one
+ * named subject `subject:<s>`, else the digest of its records, else of its owned paths. One op, one subject key and
+ * one goal revision are ONE unit (UNIQUE(workflow_id, op_id, subject_key, goal_revision)): a try of the same work can
+ * never start a fresh budget.
+ */
+export function unitSubjectKey({cut=null,params=null,records=[],ownedPaths=[]}={}){
+  if(cut?.id!=null&&cut?.ordinal!=null)return `cut:${cut.id}#${Number(cut.ordinal)}`;
+  const subject=typeof params?.subject==='string'&&params.subject.trim()?params.subject.trim():null;
+  if(subject)return `subject:${subject}`;
+  const recs=normList(records);
+  if(recs.length)return `records:${shortDigest(recs.join('|'))}`;
+  return `paths:${shortDigest(normList(ownedPaths).join('|'))}`;
+}
+
+/** Two jobs are tries of one work unit (jobs.unit_id). */
+export const sameUnit=(a,b)=>Boolean(a?.unit_id&&a.unit_id===b?.unit_id);
+
+const OPEN_TRY=['queued','ready','leased','running','answering','reported','deciding','effect_unknown'];
+
+/** The jobs.retry_class of a successor of `last` (DBTREE: business | infra | resume | follow-up). */
+const retryClassOf=(last,disposition)=>last.status==='cancelled'?'resume'
+  :disposition?.retryClass==='business'?'business'
+    :disposition?.retryClass==='infrastructure'||disposition?.retryClass===RETRY_CLASS_ENVIRONMENT?'infra':'follow-up';
+/**
+ * Admit one more try of a unit (the code side of DBTREE jobs_enqueue_guard + work_units_done_guard), pure over the
+ * unit's row and its tries. `tries` are the unit's jobs with {job_id, status, try_no, result_json?} (result_json the
+ * settle result retryDisposition reads); `unit` is the work_units row. Returns {tryNo, retryOf, resumeOf, retryClass,
+ * reopen} or throws a typed refusal:
+ *   unit-in-flight             a try of the unit is still open (edit it, or let it settle first)
+ *   unit-already-passed        the unit is done; a re-run needs an explicit reopen with a reason (H5)
+ *   retry-lineage-invalid      retryOf is not the unit's latest try, or that try did not fail (H4)
+ *   unit-try-budget-exhausted  try_no would pass work_units.try_budget; only the owner or the Supervisor raises it (H3)
+ */
+export function admitUnitTry({unit=null,tries=[],retryOf=null,reopen=null}={}){
+  const ordered=[...tries].sort((a,b)=>Number(a.try_no)-Number(b.try_no));
+  const last=ordered.at(-1)??null;
+  if(!unit||!last){
+    if(retryOf)throw refuse(`--retry-of ${retryOf} names no earlier try of this unit`,'retry-lineage-invalid');
+    return {tryNo:1,retryOf:null,resumeOf:null,retryClass:null,reopen:null};
+  }
+  const open=ordered.filter(job=>OPEN_TRY.includes(job.status));
+  if(open.length)throw refuse(`unit ${unit.unit_id} already has an open try ${open.map(j=>`${j.job_id} (${j.status})`).join(', ')}: edit that try (starci kernel graph-edit widen|params) or let it settle`,'unit-in-flight',{open:open.map(j=>j.job_id)});
+  if(retryOf&&retryOf!==last.job_id)throw refuse(`--retry-of ${retryOf} is not the latest try of unit ${unit.unit_id} (${last.job_id} is): a retry follows the unit's latest failed try`,'retry-lineage-invalid',{latest:last.job_id});
+  const done=unit.state==='done'||last.status==='succeeded';
+  if(done&&!(reopen?.reason&&reopen?.by))throw refuse(`unit ${unit.unit_id} already passed (${last.job_id}); running it again needs an explicit reopen with a reason (--reopen <reason>)`,'unit-already-passed',{passed:last.job_id});
+  if(retryOf&&!done&&!RETRYABLE_JOB_STATUSES.includes(last.status))throw refuse(`--retry-of ${retryOf} is ${last.status}: a retry follows a FAILED or awaiting_owner try of the same unit`,'retry-lineage-invalid');
+  const tryNo=Number(last.try_no)+1;
+  if(tryNo-(ordered.length-spentTries(ordered))>Number(unit.try_budget))throw refuse(`unit ${unit.unit_id} spent ${spentTries(ordered)} of its ${unit.try_budget} tries: the owner or the Supervisor decides (starci kernel unit --raise-budget), never another try`,'unit-try-budget-exhausted',{tries:Number(last.try_no),budget:Number(unit.try_budget)});
+  if(done)return {tryNo,retryOf:null,resumeOf:null,retryClass:'follow-up',reopen:{reason:String(reopen.reason),by:String(reopen.by)}};
+  const disposition=RETRYABLE_JOB_STATUSES.includes(last.status)?retryDisposition(last):null;
+  const resume=last.status==='cancelled';
+  return {tryNo,retryOf:resume?null:last.job_id,resumeOf:resume?last.job_id:null,retryClass:retryClassOf(last,disposition),reopen:null};
+}

package/runtime/engine/canonical-json.mjs

@@ -0,0 +1,10 @@
+// canonical-json.mjs — the one canonical JSON the runtime digests structured values with: object keys
+// sorted, arrays in order, so two equal values always serialize to the same bytes. A leaf beside digest.mjs.
+import {isPlainObject} from './plain-object.mjs';
+
+/** The canonical JSON text of `value`: keys sorted at every depth. */
+export function canonicalJSON(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJSON).join(',')}]`;
+  if (isPlainObject(value)) return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonicalJSON(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}