@starci/hfs 1.0.0 → 2.0.0

package/emit/type-schema.mjs

@@ -0,0 +1,145 @@
+/**
+ * JSON Schema (2020-12, the dialect of OpenAPI 3.1) of a TypeScript type, read from the type checker.
+ *
+ * Deterministic: properties, enum members and union members are sorted; object types with a name become components (`$ref`) once,
+ * in the order they are met. Undecidable types are errors naming the path inside the type, never `{}`: `any`, `unknown`, `never`,
+ * `object`, an unbound generic, a function, a class of the standard library (Date, Map, Set, Promise), a bigint, a symbol, an
+ * 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.
+ */
+
+/** 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])]));
+  return value;
+}
+
+const canonical = (value) => JSON.stringify(stable(value));
+
+/** A builder over one checker; `components` fills as named object types are met. */
+export function createSchemaBuilder({ ts, checker }) {
+  const F = ts.TypeFlags;
+  const components = new Map();
+  const nameOf = new Map();
+  const taken = new Set();
+  const fail = (path, why) => {
+    throw new Error(`${path}: ${why}`);
+  };
+
+  const isLibrary = (symbol) => (symbol?.getDeclarations?.() ?? []).some((declaration) => /[\\/]typescript[\\/]lib[\\/]lib\./.test(declaration.getSourceFile().fileName));
+
+  const componentName = (type) => {
+    const symbol = type.aliasSymbol ?? type.getSymbol();
+    const written = checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope);
+    const base = (symbol && !/^__/.test(symbol.getName()) && !isLibrary(symbol) ? written : null);
+    if (!base) return null;
+    const clean = base.replace(/[^A-Za-z0-9._-]+/g, '.').replace(/^\.+|\.+$/g, '');
+    let name = clean;
+    for (let n = 2; taken.has(name); n += 1) name = `${clean}_${n}`;
+    taken.add(name);
+    return name;
+  };
+
+  const withoutUndefined = (type) => (type.isUnion() ? type.types.filter((member) => !(member.flags & (F.Undefined | F.Void))) : [type]);
+
+  /** The schema of a set of union members (no `undefined` among them). */
+  function membersSchema(members, path) {
+    const hasTrue = members.some((member) => member.flags & F.BooleanLiteral && checker.typeToString(member) === 'true');
+    const hasFalse = members.some((member) => member.flags & F.BooleanLiteral && checker.typeToString(member) === 'false');
+    const parts = [];
+    let rest = members;
+    if (hasTrue && hasFalse) {
+      rest = members.filter((member) => !(member.flags & F.BooleanLiteral));
+      parts.push({ type: 'boolean' });
+    }
+    const consts = [];
+    for (const member of rest) {
+      if (member.flags & (F.StringLiteral | F.NumberLiteral)) consts.push(member.value);
+      else if (member.flags & F.BooleanLiteral) consts.push(checker.typeToString(member) === 'true');
+      else parts.push(schemaOf(member, path));
+    }
+    if (consts.length) {
+      const sorted = [...consts].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0));
+      const kinds = new Set(sorted.map((item) => typeof item));
+      parts.push(kinds.size === 1 && !kinds.has('boolean') ? { enum: sorted, type: kinds.has('string') ? 'string' : 'number' } : { enum: sorted });
+    }
+    const unique = [...new Map(parts.map((part) => [canonical(part), part])).values()].sort((a, b) => (canonical(a) < canonical(b) ? -1 : 1));
+    return unique.length === 1 ? unique[0] : { anyOf: unique };
+  }
+
+  function unionSchema(type, path) {
+    if (type.types.some((member) => member.flags & (F.Undefined | F.Void))) fail(path, 'undefined is not a wire value here (declare the member optional instead)');
+    return membersSchema(type.types, path);
+  }
+
+  function objectSchema(type, path) {
+    if (checker.isArrayType(type) || checker.isTupleType(type)) {
+      if (checker.isTupleType(type)) {
+        const items = checker.getTypeArguments(type).map((item, index) => schemaOf(item, `${path}[${index}]`));
+        return { type: 'array', prefixItems: items, minItems: items.length, maxItems: items.length };
+      }
+      return { type: 'array', items: schemaOf(checker.getTypeArguments(type)[0], `${path}[]`) };
+    }
+    if (type.getCallSignatures().length || type.getConstructSignatures().length) fail(path, 'a function is not a wire value');
+    const own = type.getSymbol();
+    if (own && !own.getName().startsWith('__') && isLibrary(own) && !/^(Readonly)?Array$/.test(own.getName())) fail(path, `${own.getName()} is not a JSON value (send a string or a plain object type)`);
+    const existing = nameOf.get(type);
+    if (existing) return { $ref: `#/components/schemas/${existing}` };
+    const name = componentName(type);
+    if (name) {
+      nameOf.set(type, name);
+      components.set(name, null);
+    }
+    const built = plainObject(type, path);
+    if (!name) return built;
+    components.set(name, built);
+    return { $ref: `#/components/schemas/${name}` };
+  }
+
+  function plainObject(type, path) {
+    const properties = {};
+    const required = [];
+    const props = [...checker.getPropertiesOfType(type)].sort((a, b) => (a.getName() < b.getName() ? -1 : 1));
+    for (const prop of props) {
+      const propType = checker.getTypeOfSymbol(prop);
+      const optional = (prop.flags & ts.SymbolFlags.Optional) !== 0;
+      const members = propType.isUnion() ? propType.types : [propType];
+      const kept = withoutUndefined(propType);
+      if (kept.length === 0) fail(`${path}.${prop.getName()}`, 'undefined is not a wire value');
+      const hadUndefined = kept.length < members.length;
+      properties[prop.getName()] = !hadUndefined ? schemaOf(propType, `${path}.${prop.getName()}`) : kept.length === 1 ? schemaOf(kept[0], `${path}.${prop.getName()}`) : membersSchema(kept, `${path}.${prop.getName()}`);
+      if (!optional && !hadUndefined) required.push(prop.getName());
+    }
+    const index = checker.getIndexInfosOfType(type).find((info) => info.keyType.flags & F.String);
+    if (props.length === 0 && !index) fail(path, 'an object type with no members and no index signature says nothing');
+    const result = { type: 'object' };
+    if (props.length) result.properties = properties;
+    if (required.length) result.required = required;
+    if (index) result.additionalProperties = schemaOf(index.type, `${path}[key]`);
+    return result;
+  }
+
+  function schemaOf(type, path) {
+    const f = type.flags;
+    if (f & F.Any) fail(path, 'any');
+    if (f & F.Unknown) fail(path, 'unknown');
+    if (f & F.Never) fail(path, 'never');
+    if (f & (F.Undefined | F.Void)) fail(path, 'undefined is not a wire value');
+    if (f & F.TypeParameter) fail(path, 'an unbound generic');
+    if (f & F.NonPrimitive) fail(path, 'object with no declared members');
+    if (f & (F.BigInt | F.BigIntLiteral | F.ESSymbol | F.UniqueESSymbol)) fail(path, 'bigint and symbol are not JSON values');
+    if (f & F.StringLiteral) return { const: type.value };
+    if (f & F.NumberLiteral) return { const: type.value };
+    if (f & F.BooleanLiteral) return { const: checker.typeToString(type) === 'true' };
+    if (f & F.String) return { type: 'string' };
+    if (f & F.Number) return { type: 'number' };
+    if (f & F.Boolean) return { type: 'boolean' };
+    if (f & F.Null) return { type: 'null' };
+    if (type.isUnion()) return unionSchema(type, path);
+    if (f & F.Object || f & F.Intersection) return objectSchema(type, path);
+    return fail(path, `a type this reader cannot express (${checker.typeToString(type)})`);
+  }
+
+  return { schemaOf, components: () => Object.fromEntries([...components.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "The HFS command line of a StarCi product repository: hfs check, init, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
   "type": "module",
   "license": "UNLICENSED",
@@ -8,12 +8,20 @@
   "bin": {
     "hfs": "./bin/hfs.mjs"
   },
+  "exports": {
+    "./package.json": "./package.json",
+    "./runtime/*": "./runtime/*"
+  },
   "files": [
     "bin/hfs.mjs",
+    "emit/**",
+    "scaffold/**",
+    "report/**",
     "runtime/**",
     "sync/**",
     "templates/**",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=22.13.0"

package/report/sonar.mjs

@@ -0,0 +1,180 @@
+// hfs report: the ONE way the findings of the StarCi canon reach Sonar (contract change hfs-sonar-import).
+//
+//   hfs check --sonar <file>               writes every error-level finding of the check (repository, managed files and the whole
+//                                          architecture machine) as a Sonar Generic Issue Import document (SonarQube 10.3+ format:
+//                                          `{ rules, issues }`), engineId `starci-hfs`, rule id = the finding code
+//   hfs report <eslint|stylelint> <in> <out>
+//                                          converts the linter's own json output (`eslint -f json`, `stylelint --formatter json`)
+//                                          into the same document format, engineId `eslint` / `stylelint`, rule id = the linter's
+//                                          rule. Sonar's own ESLint import (sonar.eslint.reportPaths) is not used: it drops an issue
+//                                          on a file outside sonar.sources, and a stylelint result has no native import at all.
+// One placement rule for every engine: Sonar imports an issue only on a file it indexes (a tracked source or stylesheet under
+// sonar.sources). A finding on any other path (hfs.json, a workflow, a package under an unindexed root, e2e/, a directory) is filed
+// on the first source file of sonar.sources and its message names the real path, so no finding is dropped.
+// The output is deterministic: rules sorted by id, issues by file, line, rule and message, so two runs over one tree are
+// byte-identical. A finding of level `info` (report-only) is not exported: the gate fails on any imported issue.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const HFS_ENGINE = 'starci-hfs';
+export const ESLINT_ENGINE = 'eslint';
+export const STYLELINT_ENGINE = 'stylelint';
+/** Every imported issue is a maintainability defect of the highest impact: the gate holds the count at zero. */
+const IMPACT = Object.freeze([Object.freeze({ softwareQuality: 'MAINTAINABILITY', severity: 'HIGH' })]);
+const CLEAN_CODE_ATTRIBUTE = 'CONVENTIONAL';
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
+/** The files Sonar indexes under sonar.sources: the source files above and the stylesheets its CSS analyzer reads. */
+const INDEXED_FILE = /\.(?:[cm]?[jt]sx?|css)$/;
+
+const posix = (file) => file.split(path.sep).join('/').replace(/^\.\//, '');
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+const ruleOf = (id, engineId, name, description) => ({ id, name, description, engineId, cleanCodeAttribute: CLEAN_CODE_ATTRIBUTE, impacts: IMPACT.map((impact) => ({ ...impact })) });
+
+const rangeOf = (line, endLine) => (Number.isInteger(line) && line >= 1 ? { textRange: { startLine: line, endLine: Number.isInteger(endLine) && endLine >= line ? endLine : line } } : {});
+
+function document(rules, issues) {
+  const sorted = [...issues].sort((a, b) => cmp(a.primaryLocation.filePath, b.primaryLocation.filePath)
+    || (a.primaryLocation.textRange?.startLine ?? 0) - (b.primaryLocation.textRange?.startLine ?? 0)
+    || cmp(a.ruleId, b.ruleId)
+    || cmp(a.primaryLocation.message, b.primaryLocation.message));
+  const used = new Set(sorted.map((issue) => issue.ruleId));
+  return { rules: [...rules.values()].filter((rule) => used.has(rule.id)).sort((a, b) => cmp(a.id, b.id)), issues: sorted };
+}
+
+/**
+ * The first source file of the repository (sorted) under one of `sourceRoots`: Sonar imports an issue only on a file it
+ * indexes, and a finding about hfs.json, a workflow, a config file or a directory is not on one, so it is filed on this
+ * file and its message names the real path. Null when the tracked tree has no source file.
+ */
+export function anchorOf(tracked, sourceRoots) {
+  const roots = sourceRoots.map((root) => `${posix(root).replace(/\/$/, '')}/`);
+  return [...tracked].map(posix).filter((file) => SOURCE_FILE.test(file) && roots.some((root) => file.startsWith(root))).sort(cmp)[0] ?? null;
+}
+
+/**
+ * The one placement rule of every engine. `sourceRoots` and `tracked` say which files Sonar indexes; without them every
+ * finding keeps its own path. Returns `place(own, message, line, endLine)`: the `primaryLocation` of the finding (its own file,
+ * or the anchor with the real path named in the message), or null when there is nowhere to file it.
+ */
+function placement({ sourceRoots = [], tracked = [] }) {
+  const anchor = sourceRoots.length ? anchorOf(tracked, sourceRoots) : null;
+  const roots = sourceRoots.map((root) => `${posix(root).replace(/\/$/, '')}/`);
+  const trackedSet = new Set(tracked.map(posix));
+  // Sonar imports an issue only on a file it indexes: a tracked source file or stylesheet under sonar.sources (a directory, a config file or a JSON file is not one).
+  const indexed = (file) => roots.some((root) => file.startsWith(root)) && INDEXED_FILE.test(file) && (trackedSet.size === 0 || trackedSet.has(file));
+  return (own, message, line, endLine) => {
+    const moved = anchor !== null && (own === null || !indexed(own));
+    const filePath = moved ? anchor : own ?? anchor;
+    if (filePath === null) return null;
+    return { message: moved ? `${own ?? 'repository'}: ${message}` : message, filePath, ...(moved ? {} : rangeOf(line, endLine)) };
+  };
+}
+
+/**
+ * The Generic Issue Import document of a check's findings (the `findings` of checkRepository, each with the catalog's
+ * `title`, `titleVi`, `whyVi` and `nextStepVi`). `sourceRoots` and `tracked` place a finding that lies outside the indexed
+ * sources (see placement); without them every finding keeps its own path.
+ */
+export function sonarReport(findings, { sourceRoots = [], tracked = [] } = {}) {
+  const place = placement({ sourceRoots, tracked });
+  const rules = new Map();
+  const issues = [];
+  for (const finding of findings) {
+    if (finding.level !== 'error') continue;
+    if (!rules.has(finding.code)) {
+      rules.set(finding.code, ruleOf(finding.code, HFS_ENGINE, finding.title ?? finding.code, `${finding.title ?? finding.code}. ${finding.titleVi}: ${finding.whyVi} Cách sửa: ${finding.nextStepVi}`));
+    }
+    const primaryLocation = place(finding.path ? posix(finding.path) : null, finding.message, finding.line);
+    if (primaryLocation === null) continue;
+    issues.push({ ruleId: finding.code, effortMinutes: 5, primaryLocation });
+  }
+  return document(rules, issues);
+}
+
+/** Text of a stylelint warning without the trailing " (rule-name)" its formatter appends. */
+const stylelintText = (warning) => String(warning.text ?? '').replace(new RegExp(`\\s*\\(${String(warning.rule ?? '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\)$`), '');
+
+// What differs between the two linters' json output: where the file, the findings, the rule and the text are.
+const LINTERS = Object.freeze({
+  eslint: {
+    engine: ESLINT_ENGINE,
+    errorRule: 'eslint-error',
+    file: (result) => result.filePath,
+    findings: (result) => result.messages,
+    rule: (message) => message.ruleId,
+    text: (message) => message.message,
+    describe: (id) => `ESLint rule ${id} of the StarCi canon (@starci/eslint-canon-be and @starci/eslint-canon-fe) or of a plugin it composes.`,
+    describeError: 'ESLint could not lint a file: a parse error or an invalid configuration.',
+    shape: 'an array of results with a filePath and messages',
+  },
+  stylelint: {
+    engine: STYLELINT_ENGINE,
+    errorRule: 'stylelint-error',
+    file: (result) => result.source,
+    findings: (result) => result.warnings,
+    rule: (warning) => warning.rule,
+    text: stylelintText,
+    describe: (id) => `Stylelint rule ${id} of the StarCi CSS canon (@starci/stylelint-canon, HFS R61).`,
+    describeError: 'Stylelint could not read a stylesheet: a parse error or an invalid option.',
+    shape: 'an array of results with a source and warnings',
+  },
+});
+
+export const LINTER_KINDS = Object.freeze(Object.keys(LINTERS));
+
+/**
+ * A linter's json results (`eslint -f json`: [{ filePath, messages: [{ ruleId, line, endLine, message }] }]; `stylelint
+ * --formatter json`: [{ source, warnings: [{ line, endLine, rule, text }] }]) as a Generic Issue Import document. `root` is
+ * the directory paths are made relative to (the repository root, where the scan runs); a file outside it is skipped.
+ * `sourceRoots` and `tracked` place a finding on a file Sonar does not index (see placement). A parse error or an invalid
+ * option is a finding the linter reports without a rule name; it is imported under the rule `eslint-error` / `stylelint-error`.
+ */
+export function linterReport(kind, results, { root, sourceRoots = [], tracked = [] }) {
+  const linter = LINTERS[kind];
+  if (linter === undefined) throw new Error(`unknown linter ${kind}; expected ${LINTER_KINDS.join(' or ')}`);
+  const place = placement({ sourceRoots, tracked });
+  const rules = new Map();
+  const issues = [];
+  for (const result of results) {
+    const source = String(linter.file(result) ?? '');
+    if (!source) continue;
+    const relative = posix(path.isAbsolute(source) ? path.relative(root, source) : source);
+    if (relative.startsWith('..')) continue;
+    for (const finding of linter.findings(result) ?? []) {
+      const id = linter.rule(finding) || linter.errorRule;
+      if (!rules.has(id)) rules.set(id, ruleOf(id, linter.engine, id, id === linter.errorRule ? linter.describeError : linter.describe(id)));
+      const primaryLocation = place(relative, linter.text(finding) || id, finding.line, finding.endLine);
+      if (primaryLocation !== null) issues.push({ ruleId: id, effortMinutes: 5, primaryLocation });
+    }
+  }
+  return document(rules, issues);
+}
+
+/** The `sonar.sources` roots of a sonar-project.properties text (empty when the file does not name them). */
+export function sourceRootsOf(propertiesText) {
+  const line = String(propertiesText).split(/\r?\n/).map((raw) => raw.trim()).find((raw) => raw.startsWith('sonar.sources='));
+  return line ? line.slice('sonar.sources='.length).split(',').map((root) => root.trim()).filter(Boolean) : [];
+}
+
+/** Write a report as JSON (2-space, LF, trailing newline), creating the directory. */
+export function writeReport(file, report) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(report, null, 2)}\n`);
+}
+
+/** `hfs report <eslint|stylelint> <in> <out> [--repo <dir>]`: convert a linter's json report; returns the number of issues written. */
+export function convertReportFile({ kind, input, output, root, sourceRoots = [], tracked = [] }) {
+  const linter = LINTERS[kind];
+  if (linter === undefined) throw new Error(`unknown linter ${kind}; expected ${LINTER_KINDS.join(' or ')}`);
+  let results;
+  try {
+    results = JSON.parse(fs.readFileSync(input, 'utf8'));
+  } catch (error) {
+    throw new Error(`${input} is not a readable ${kind} json report (${error.message})`);
+  }
+  if (!Array.isArray(results)) throw new Error(`${input} is not a ${kind} json report: expected ${linter.shape}`);
+  const report = linterReport(kind, results, { root, sourceRoots, tracked });
+  writeReport(output, report);
+  return report.issues.length;
+}

package/runtime/engine/admission.mjs

@@ -0,0 +1,284 @@
+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 repository-qualified form
+ * `repository:<role>/<path>` — for a held row through its holder job, so a lease taken before
+ * canonical keys existed still conflicts; paths on Windows compare case-insensitively, as its file
+ * 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

@@ -0,0 +1,10 @@
+// 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));