@starci/hfs 4.0.7 → 4.0.9

package/bin/hfs.mjs

@@ -1,233 +0,0 @@
-#!/usr/bin/env node
-// hfs - the HFS command line of a StarCi app: one repository, `<app>/`, with one package.json, lockfile and node_modules at its root
-// and two sides, be/ and fe/, declared by the one hfs.json of kind app. Every verb runs at the app root.
-//   hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>]
-//                                            every tracked path has a slot; required files exist; nothing forbidden or
-//                                            tracked-that-must-be-ignored; pins match; every managed file equals its render
-//                                            (sync/managed.mjs, the .gitignore block and sonar-project.properties included); no empty or ghost
-//                                            directory, no untracked entry outside an ignored slot; plaintext secrets, the .starcistacks shape, CI
-//                                            and pre-push canon steps, dependency version skew, the contract snapshot and the test, wire and i18n
-//                                            trees; prettier over every tracked file through the repository's own install (sync/format.mjs; not under
-//                                            --fast, and a repository without prettier is a refusal); soft-size backlog (report only); then the whole
-//                                            architecture machine (tiers, owners, clones, dead exports, module registration, the
-//                                            front-end and back-end source rules), each violation a finding with its why.
-//                                            --fast: only what changed since the merge-base with origin/main (else main; --base
-//                                            overrides it); the machine
-//                                            runs on those owners without clones and dead exports. No merge-base is a refusal
-//                                            (exit 2), never a silent full pass. Exit 1 on any error-level finding. The root checks run once and
-//                                            the side checks and the machine once per side, the side folder as their root; every path is app-relative.
-//   hfs lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>]
-//                                            the ONE lint entry (npm run lint): ESLint per side with that side's canon config (per-file rules and
-//                                            the project-graph rules), this check's findings, and stylelint over the fe side, as one starci/lint@1
-//                                            report; --sonar writes the one Sonar import file. Exit 0 clean, 1 findings, 2 a tool could not run (lint/run.mjs).
-//   hfs scaffold app <name> [--into <dir>]  a new app <dir>/<name>/: the root (hfs.json, package.json, managed files, .starciwork) and the
-//                                            be/ and fe/ skeletons (scaffold/app.mjs). Refuses an existing directory.
-//   hfs explain <path> [--repo <dir>] [--json]   which slot owns the path, its tier, allowed imports, required tests.
-//   hfs emit-contracts [--repo <dir>]      write be/contracts/<app>/schema.graphql of every api app that serves GraphQL (emit/contracts.mjs):
-//                                            printSchema(lexicographicSortSchema) of the resolvers the app root composes; no env, no database, no network.
-//   hfs sync (--check | --write) [--root <dir>]  the managed files of the root (scripts, husky, CI, .gitignore block, sonar, prettier) and
-//                                            of each side (tsconfig, eslint, jest, stylelint); sync/cli.mjs
-//   hfs work-hygiene                              the pre-commit guard: staged .starciwork and .starcistacks paths, and the secrets guard over every staged file (read from the index); sync/cli.mjs
-//   hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]
-//                                            a back-end `<name>.service.ts` and its `<name>.service.spec.ts` skeleton (scaffold/service.mjs; <dir> is
-//                                            relative to be/): the spec is built
-//                                            with Test.createTestingModule, one provider per constructor dependency (kit doubles from @starci/jest-preset),
-//                                            one placeholder it per public method. Never overwrites a file.
-//   hfs new spec <file>.service.ts [--repo <dir>]  the spec skeleton of an existing service, read from its constructor with the repository's TypeScript
-// Every finding names a why code and carries its Vietnamese text. check, lint and explain read the app, never write to it. Exit codes:
-// 0 clean, 1 error findings, 2 a refusal or bad usage.
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { isMain } from '../runtime/scripts/checks/common.mjs';
-import { checkRepository, explainPath, trackedFiles } from '../runtime/scripts/lib/hfs-check.mjs';
-import { HfsSlotsError, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
-import { formatFindings } from '../sync/format.mjs';
-import { main as syncMain } from '../sync/cli.mjs';
-import { SyncError, loadPresets } from '../sync/index.mjs';
-import { managedFindings } from '../sync/managed.mjs';
-import { emitContracts } from '../emit/contracts.mjs';
-import { ScaffoldError, newService, newSpec } from '../scaffold/service.mjs';
-import { scaffoldApp } from '../scaffold/app.mjs';
-import { contractEmitFindings } from '../runtime/scripts/lib/hfs-rules/contract.mjs';
-import { lintRepository, parseLintArgs, printLintText } from '../lint/run.mjs';
-import { writeReport } from '../report/sonar.mjs';
-
-const USAGE = `hfs check [--repo <dir>] [--json] [--fast] [--base <ref>]
-hfs lint [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>]
-hfs scaffold app <name> [--into <dir>]
-hfs emit-contracts [--repo <dir>]
-hfs explain <path> [--repo <dir>] [--json]
-hfs sync (--check | --write) [--root <dir>]
-hfs work-hygiene
-hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]
-hfs new spec <file>.service.ts [--repo <dir>]
-`;
-const PER_CODE_LIMIT = 25;
-const VALUE_FLAGS = new Set(['--repo', '--base', '--inject', '--into']);
-/** Flags that may repeat: their values are collected in order. */
-const LIST_FLAGS = new Set(['--inject']);
-const BOOL_FLAGS = new Set(['--json', '--fast']);
-
-function parse(argv) {
-  const opts = { positional: [] };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (VALUE_FLAGS.has(arg)) {
-      if (argv[i + 1] === undefined) throw new Error(`${arg} needs a value`);
-      opts[arg.slice(2)] = LIST_FLAGS.has(arg) ? [...(opts[arg.slice(2)] ?? []), argv[i + 1]] : argv[i + 1];
-      i += 1;
-    }
-    else if (BOOL_FLAGS.has(arg)) opts[arg.slice(2)] = true;
-    else if (arg.startsWith('--')) throw new Error(`unknown flag ${arg}`);
-    else opts.positional.push(arg);
-  }
-  return opts;
-}
-
-function printCheck(result, out) {
-  const { counts } = result;
-  out(`hfs check${result.fast ? ' --fast' : ''} ${result.repoRoot} (profile ${result.profile ?? 'unknown'}, manifest ${result.manifest}, ${result.tracked} tracked paths)\n`);
-  if (result.fast) out(`  ${result.fast.changed} path${result.fast.changed === 1 ? '' : 's'} changed since ${result.fast.base.slice(0, 12)}\n`);
-  out(`  architecture machine: ${result.machine.status === 'ran' ? `ran over ${result.machine.files} source files${result.machine.paths ? ` (owners ${result.machine.paths.join(', ')})` : ''}` : `skipped, ${result.machine.reason}`}\n`);
-  if (result.contracts) out(`  contract snapshots: ${result.contracts.status === 'checked' ? `emitted and compared, ${result.contracts.apps.map((a) => `${a.app}/${a.artifact} ${a.status}`).join(', ') || 'no api app'}` : `skipped, ${result.contracts.reason}`}
-`);
-  const byCode = new Map();
-  for (const f of result.findings) byCode.set(f.code, [...(byCode.get(f.code) ?? []), f]);
-  for (const [code, list] of byCode) {
-    const first = list[0];
-    out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
-    for (const f of list.slice(0, PER_CODE_LIMIT)) out(`  - ${f.message}\n`);
-    if (list.length > PER_CODE_LIMIT) out(`  ... and ${list.length - PER_CODE_LIMIT} more (use --json for all)\n`);
-  }
-  out(`\n${counts.error} error finding${counts.error === 1 ? '' : 's'}, ${counts.info} report-only\n`);
-}
-
-function printExplain(e, out) {
-  out(`${e.path}\n`);
-  if (e.status === 'no-slot') {
-    out(`  no slot owns this path (${e.code}): ${e.titleVi}\n  ${e.whyVi}\n`);
-    if (e.nearest) out(`  nearest slot ${e.nearest.slot}, pattern ${e.nearest.pattern}; matched ${e.nearest.matchedPrefix || '.'}, then expected ${e.nearest.expectedNext ?? 'nothing'}\n`);
-    return;
-  }
-  if (e.status === 'ambiguous') { out(`  owned equally by ${e.candidates.join(', ')} (${e.code}): ${e.titleVi}\n`); return; }
-  out(`  slot       ${e.slot}  (${e.pattern})\n  presence   ${e.presence}, ${e.tracking}\n  tier       ${e.tier}${e.owner ? `  owner ${e.owner.root} (${e.owner.slot})` : ''}\n`);
-  out(`  imports    ${e.allowedImports ? `may import ${e.allowedImports.join(', ')}; ${e.importRule}` : (e.importRule ?? 'not applicable')}\n`);
-  out(`  tests      ${e.tests}: ${e.testsMeaning}\n`);
-  if (e.requiredFiles.length) out(`  requires   ${e.requiredFiles.join(', ')}\n`);
-  if (e.goesTo) out(`  belongs at ${e.goesTo}\n`);
-  if (e.rules) out(`  rules      ${e.rules.join(', ')}\n`);
-  if (e.code) out(`  ${e.code}: ${e.titleVi}\n  ${e.whyVi}\n`);
-}
-
-/**
- * The app pass: slots, managed files, formatter, contract snapshots and the architecture machine's check surface, root and sides.
- * `only` limits the formatter to those (app-relative) files.
- */
-async function runCheck({ repoRoot, fast = false, base, only, presets, prettier }) {
-  const tracked = trackedFiles(repoRoot);
-  // Managed files of the root and both sides, the .gitignore block and sonar against their render (R04, R05, R11, ...), and prettier
-  // through the app's own install (R19, never under --fast).
-  const extraFindings = [...await managedFindings({ repoRoot, tracked, presets }), ...(fast ? [] : await formatFindings({ repoRoot, files: only ?? tracked, prettier }))];
-  // R23 against the be side itself (full pass only): the committed snapshots equal what `emit-contracts` writes now.
-  let contracts = null;
-  let be = null;
-  try { be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be ?? null; } catch { /* checkRepository reports the unreadable declaration */ }
-  if (be) {
-    if (fast) contracts = { status: 'skipped', reason: '--fast does not emit the apps' };
-    else {
-      const files = tracked.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
-      const emitted = contractEmitFindings({ repoRoot: path.join(repoRoot, 'be'), files, repo: be, emit: emitContracts });
-      extraFindings.push(...emitted.findings.map((finding) => ({ ...finding, side: 'be', path: `be/${finding.path}` })));
-      contracts = { status: 'checked', apps: emitted.apps };
-    }
-  }
-  const result = checkRepository({ repoRoot, fast, base, extraFindings });
-  if (contracts) result.contracts = contracts;
-  return result;
-}
-
-/** `hfs lint`: ESLint per side, the app checks and stylelint over the fe side as one report; see lint/run.mjs. */
-async function lintMain(argv, { stdout, presets, prettier }) {
-  const opts = parseLintArgs(argv);
-  const repoRoot = path.resolve(opts.repo ?? process.cwd());
-  const { report, sonar, exit } = await lintRepository({
-    repoRoot, opts, trackedFiles,
-    hfsCheck: (root) => runCheck({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
-  });
-  if (opts.sonar !== undefined) writeReport(path.resolve(opts.sonar), sonar);
-  if (opts.format === 'json') stdout(`${JSON.stringify(report, null, 2)}
-`); else printLintText(report, stdout);
-  return exit;
-}
-
-/**
- * The jest preset a new app renders its Sonar exclusions from: the one installed beside this @starci/hfs (`npx -p @starci/hfs -p
- * @starci/jest-preset hfs scaffold app <name>`, or an install that holds both). None is a refusal, never a render without it.
- */
-async function scaffoldPresets() {
-  try { return await loadPresets(path.dirname(fileURLToPath(import.meta.url))); } catch (error) {
-    throw new SyncError('HFS_SYNC_PRESET_MISSING', `${error.message.replace(/^[A-Z_]+: /, '')}; run hfs scaffold with @starci/jest-preset installed beside @starci/hfs (npx -p @starci/hfs -p @starci/jest-preset hfs scaffold app <name>)`);
-  }
-}
-
-/** `presets` and `prettier` are test seams: the Sonar exclusions sync would load from the repository's installed preset, and the repository's own prettier. */
-export async function main(argv, { stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier } = {}) {
-  const [verb, ...rest] = argv;
-  if (!['check', 'lint', 'scaffold', 'explain', 'sync', 'work-hygiene', 'emit-contracts', 'new'].includes(verb)) { stderr(USAGE); return 2; }
-  try {
-    if (verb === 'sync' || verb === 'work-hygiene') return await syncMain(argv);
-    if (verb === 'lint') return await lintMain(rest, { stdout, presets, prettier });
-    const opts = parse(rest);
-    const repoRoot = path.resolve(opts.repo ?? process.cwd());
-    if (verb === 'check') {
-      if (opts.positional.length) throw new Error('hfs check takes no path');
-      if (opts.base !== undefined && opts.fast !== true) throw new Error('--base names the ref --fast compares with; it needs --fast');
-      const result = await runCheck({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier });
-      if (opts.json) stdout(`${JSON.stringify(result, null, 2)}\n`); else printCheck(result, stdout);
-      return result.ok ? 0 : 1;
-    }
-    if (verb === 'emit-contracts') {
-      if (opts.positional.length) throw new Error('hfs emit-contracts takes no path');
-      const be = readRepoDeclaration(loadSlotManifest(), repoRoot).sides?.be;
-      if (!be) throw new Error('hfs emit-contracts runs at the app root (the folder of hfs.json)');
-      const { written, skipped, standIns } = emitContracts({ repoRoot: path.join(repoRoot, 'be'), declaration: be });
-      for (const file of written) stdout(`wrote be/${file}
-`);
-      stdout(`hfs emit-contracts: ${written.length} written${skipped.length ? `, ${skipped.join(', ')} serve no GraphQL` : ''}
-`);
-      for (const [app, lines] of Object.entries(standIns)) {
-        stdout(`${app}: ${lines.length} dependenc${lines.length === 1 ? 'y' : 'ies'} of the resolvers could not load here and stood in (no GraphQL type is affected):\n`);
-        for (const line of lines) stdout(`  ${line}\n`);
-      }
-      return 0;
-    }
-    if (verb === 'new') {
-      const [kind, ...args] = opts.positional;
-      let written;
-      if (kind === 'service' && args.length === 2) written = newService({ repoRoot, dir: args[0], name: args[1], inject: opts.inject ?? [] });
-      else if (kind === 'spec' && args.length === 1 && opts.inject === undefined) written = newSpec({ repoRoot, file: args[0] });
-      else throw new Error('hfs new takes `service <dir> <name> [--inject ...]` or `spec <file>.service.ts`');
-      for (const file of written) stdout(`created ${file}
-`);
-      return 0;
-    }
-    if (verb === 'scaffold') {
-      const [kind, name, ...extra] = opts.positional;
-      if (kind !== 'app' || !name || extra.length || opts.repo !== undefined) throw new Error('hfs scaffold takes `app <name> [--into <dir>]`');
-      const { root: created, files } = scaffoldApp({ name, into: path.resolve(opts.into ?? process.cwd()), presets: presets ?? await scaffoldPresets() });
-      stdout(`hfs scaffold app: created ${created} (${files.length} files); next: npm ci, then npm run lint\n`);
-      return 0;
-    }
-    if (opts.positional.length !== 1) throw new Error('hfs explain takes exactly one path');
-    const explained = explainPath({ repoRoot, input: opts.positional[0] });
-    if (opts.json) stdout(`${JSON.stringify(explained, null, 2)}\n`); else printExplain(explained, stdout);
-    return explained.status === 'no-slot' || explained.status === 'ambiguous' ? 1 : 0;
-  } catch (error) {
-    stderr(error instanceof HfsSlotsError || error instanceof SyncError ? `${error.message}\n` : error instanceof ScaffoldError ? `${error.code}: ${error.message}\n` : `hfs: ${error.message}\n${USAGE}`);
-    return 2;
-  }
-}
-
-// Run when this file is the entry point, compared by real path: through a node_modules junction or an npx shim argv[1] is
-// the junction path while import.meta.url is the resolved one, and a plain comparison silently skipped main (hfs printed nothing).
-if (isMain(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/runtime/engine/admission.mjs

@@ -1,284 +0,0 @@
-import { createHash } from 'node:crypto';
-
-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 `nivo-fe/`).
- * 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 (nivo wf-nivo-fe-debt-mug06w7h inc-52a4a5ee5b12: `apps/app/src/messages/vi.json` bare for
- * the fe repository vs `nivo-fe/apps/app/src/messages` repository-prefixed never overlapped). `canonicalOf`
- * (scripts/kernel/lease-canon.mjs) resolves a path to its 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;
-}
-
-/**
- * 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 (fleet-wide). A null, absent or non-positive value is unbounded, so
- * a workflow with no owner budget still meets the fleet ceiling. A parallelism gear raises what
- * `api 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),fleet=positive(maxParallelOps);
-  if(owner===null&&fleet===null)return {ceiling:null,source:null};
-  if(owner===null)return {ceiling:fleet,source:'maxParallelOps'};
-  if(fleet===null)return {ceiling:owner,source:'budgets.maxOps'};
-  return owner<=fleet?{ceiling:owner,source:'budgets.maxOps'}:{ceiling:fleet,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'};
-}
-
-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/ledger-db.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/api.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`
- * (api 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 - `api 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'];
-const refuseUnit=(message,code,extra={})=>Object.assign(new Error(message),{code,...extra});
-/** 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 refuseUnit(`--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 refuseUnit(`unit ${unit.unit_id} already has an open try ${open.map(j=>`${j.job_id} (${j.status})`).join(', ')}: edit that try (api 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 refuseUnit(`--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 refuseUnit(`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 refuseUnit(`--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 refuseUnit(`unit ${unit.unit_id} spent ${spentTries(ordered)} of its ${unit.try_budget} tries: the owner or the Supervisor decides (api 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/digest.mjs

@@ -1,10 +0,0 @@
-// 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 const sha256File = (file) => sha256(fs.readFileSync(file));