@starci/hfs 4.0.7 → 4.0.8

package/sync/index.mjs

@@ -8,8 +8,8 @@
 // side (be, fe) for a side slot, whose files land under that side's folder. Two targets are not whole files of a managedBy slot
 // and are listed in this module: the marked block of the root .gitignore, and .starciwork/.gitignore, which lives inside the
 // .starciwork directory slot. Every file is rendered with the app's hfs.json (both sides and their apps) and, for the Sonar
-// exclusions and the one coverage scope (sonar.coverage.inclusions and codecov.yml alike), the jest preset the app installs for
-// its be side. `--check` compares the sha256 of the rendered content with the
+// exclusions and the one coverage scope (sonar.coverage.exclusions, its complement, and the codecov.yml paths alike), the jest
+// preset the app installs for its be side. `--check` compares the sha256 of the rendered content with the
 // file on disk and fails on any drift; `--write` rewrites the drifted files. `.gitignore` is the one shared file: only the marked
 // block is managed and the app's own lines around it are left alone. The root package.json is managed by its `scripts` block
 // only (mode scripts, compared as parsed JSON): the rest of the file (dependencies, npm workspaces of fe/packages/*) is the app's.
@@ -18,7 +18,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import { braceVariants } from '../runtime/scripts/lib/glob.mjs';
-import { APP_SCOPE, SIDES, loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { APP_SCOPE, SIDES, loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
@@ -121,8 +121,8 @@ export const LCOV_REPORT = 'be/coverage/lcov.info';
 
 /**
  * THE coverage scope of an app, from the app root: the preset's coverage sources on the be side (`be/src/**` + `/*.service.ts`).
- * It is the one source of sonar.coverage.inclusions and of the codecov.yml status paths, so the two can never drift; fe/ is
- * outside it (a front end has no tests).
+ * It is the one source of the codecov.yml status paths and, through coverageExclusions, of Sonar's coverage scope, so the two
+ * can never drift; fe/ is outside it (a front end has no tests).
  */
 export function coverageScope(presets) {
   const sources = presets?.coverageSources;
@@ -130,6 +130,43 @@ export function coverageScope(presets) {
   return sources.map(glob => `be/${glob}`);
 }
 
+const COVERED_SUFFIX = /\*\.([a-z][a-z0-9-]*)\.ts$/;
+const asGlob = (text) => String(text).replace(/<[^>]+>/g, '*');
+
+/**
+ * Sonar's coverage scope of an app as `sonar.coverage.exclusions` globs: the COMPLEMENT of coverageScope. SonarQube has no
+ * coverage inclusions and its globs have no negation, so every executable file that is not a coverage source is excluded:
+ *   - every be source role of the slot manifest's closed suffix vocabulary (ruleParams.be.suffixes, R89) other than the
+ *     roles the coverage sources name (`service`), as `be/**` + `/*.<role>.ts`;
+ *   - every be file name outside that vocabulary a be slot declares (`main.ts`, `index.ts`, `connection.ts`, the migrations,
+ *     the test world's files, dto/ and kit/ files), as `be/<slot path>/<name>` with each `<placeholder>` a `*`;
+ *   - all of fe/ (a front end has no tests).
+ * The result is sorted and has no duplicate. A coverage source that is not `<dir>/**` + `/*.<role>.ts` is refused: its
+ * complement cannot be written in Sonar's globs.
+ */
+export function coverageExclusions(presets, manifest = loadSlotManifest()) {
+  const covered = new Set(coverageScope(presets).map(glob => {
+    const role = COVERED_SUFFIX.exec(glob)?.[1];
+    if (!role) throw new SyncError('HFS_SYNC_COVERAGE_SCOPE', `coverage source ${glob} is not <dir>/**/*.<role>.ts: Sonar's coverage exclusions cannot express its complement`);
+    return role;
+  }));
+  const suffixes = manifest.ruleParams?.be?.suffixes ?? [];
+  const isRole = new RegExp(`\\.(?:${suffixes.map(s => s.replace(/[-]/g, '\\-')).join('|')})\\.ts$`);
+  const globs = new Set(suffixes.filter(role => !covered.has(role)).map(role => `be/**/*.${role}.ts`));
+  for (const slot of manifest.slots) {
+    if (!slot.profiles.includes('be') || slot.presence === 'forbidden') continue;
+    for (const entry of [...(slot.requires ?? []), ...(slot.allows ?? [])]) {
+      if (!/\.ts$/.test(entry) || entry.includes('<role>')) continue;
+      for (const name of braceVariants(entry)) {
+        if (isRole.test(asGlob(name).replace(/\*/g, 'x'))) continue;
+        for (const dir of braceVariants(slot.path)) globs.add(`be/${asGlob(dir)}${asGlob(name)}`.replace(/\/\/+/g, '/'));
+      }
+    }
+  }
+  globs.add('fe/**');
+  return [...globs].sort();
+}
+
 /**
  * The script lines the apps add to the root package.json, each ending with a comma (the template puts them mid-object). Every
  * script runs a side from the app root: a be script from be/ (`cd be && ...`, the folder its tsconfig and jest configuration
@@ -146,9 +183,9 @@ export function appScripts(app) {
   const watch = entry => `cd be && ts-node-dev --respawn -r tsconfig-paths/register apps/${entry.name}/src/main.ts`;
   return [
     ...(apis.length === 1 ? [line('dev:be', watch(apis[0]))] : apis.map(entry => line(`dev:be:${entry.name}`, watch(entry)))),
-    ...(fe.length === 1 ? [line('dev:fe', `npm run codegen --silent && cd fe && next dev apps/${fe[0].name}`)] : fe.map(entry => line(`dev:fe:${entry.name}`, `npm run codegen --silent && cd fe && next dev apps/${entry.name}`))),
+    ...(fe.length === 1 ? [line('dev:fe', `npm run codegen --silent && cd fe/apps/${fe[0].name} && next dev`)] : fe.map(entry => line(`dev:fe:${entry.name}`, `npm run codegen --silent && cd fe/apps/${entry.name} && next dev`))),
     ...be.map(entry => line(entry.kind === 'migrate' ? (migrates.length === 1 ? 'migrate' : `migrate:${entry.name}`) : `start:${entry.name}`, `node be/dist/apps/${entry.name}/src/main.js`)),
-    ...fe.map(entry => line(`start:${entry.name}`, `cd fe && next start apps/${entry.name}`)),
+    ...fe.map(entry => line(`start:${entry.name}`, `cd fe/apps/${entry.name} && next start`)),
   ].join('\n    ');
 }
 
@@ -159,7 +196,7 @@ export const opensPackages = side => (side.optionalSlots ?? []).some(id => id ==
 export const STYLE_GLOB = '{apps,packages}/*/src/**/*.css';
 
 /** Every value a template of `scope` can name, derived from hfs.json and the presets. */
-export function variables(app, scope, presets, sonarKey) {
+export function variables(app, scope, presets, sonarKey, manifest = loadSlotManifest()) {
   const fe = app.sides.fe;
   const packages = opensPackages(fe);
   const feApps = fe.apps.map(entry => `fe/apps/${entry.name}`);
@@ -167,7 +204,7 @@ export function variables(app, scope, presets, sonarKey) {
   return {
     header: HEADER(scope),
     appScripts: appScripts(app),
-    buildFe: ['npm run codegen --silent', ...(packages ? ['npm run build --workspaces --if-present'] : []), `cd fe && ${fe.apps.map(entry => `next build apps/${entry.name}`).join(' && ')}`].join(' && '),
+    buildFe: ['npm run codegen --silent', ...(packages ? ['npm run build --workspaces --if-present'] : []), fe.apps.map(entry => `(cd fe/apps/${entry.name} && next build)`).join(' && ')].join(' && '),
     // The fe apps import the workspace packages from their dist/, so the packages are built before the apps are type-checked.
     typecheck: ['npm run codegen --silent', 'tsc -p be/tsconfig.json', ...(packages ? ['npm run build --workspaces --if-present'] : []), ...feTsconfigs.filter(file => !file.includes('*')).map(file => `tsc -p ${file} --noEmit`), ...(packages ? ['npm run typecheck --workspaces --if-present'] : [])].join(' && '),
     nodeMajor: String(NODE_MAJOR),
@@ -175,7 +212,7 @@ export function variables(app, scope, presets, sonarKey) {
     sonarExclusions: [presets?.sonarExclusions, '**/.next/**', '**/node_modules/**', '**/src/messages/**'].filter(Boolean).join(','),
     sonarSources: ['be/apps', 'be/src', 'fe/apps', ...(packages ? ['fe/packages'] : [])].join(','),
     lcovReport: LCOV_REPORT,
-    coverageInclusions: scope === APP_SCOPE ? coverageScope(presets).join(',') : '',
+    coverageExclusions: scope === APP_SCOPE ? coverageExclusions(presets, manifest).join(',') : '',
     codecovPaths: scope === APP_SCOPE ? coverageScope(presets).map(glob => `          - ${JSON.stringify(glob)}`).join('\n') : '',
     tsconfigPaths: ['be/tsconfig.json', ...feTsconfigs].join(','),
     styleGlob: STYLE_GLOB,
@@ -203,7 +240,7 @@ export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundl
   const app = validateHfs(hfs, manifest);
   const hasTemplate = name => { try { return readTemplate(name) !== undefined; } catch { return false; } };
   return SCOPES.flatMap(scope => {
-    const vars = variables(app, scope, presets, sonarKey);
+    const vars = variables(app, scope, presets, sonarKey, manifest);
     return targetsOf(scope, { manifest, hasTemplate }).map(target => {
       const body = render(readTemplate(target.template), vars, readTemplate);
       const where = onSide(scope, target.path);

package/templates/app/quality-config/codecov.yml

@@ -1,6 +1,6 @@
 {{header}}
 # The be unit run's lcov ({{lcovReport}}), uploaded by the managed CI workflow. Coverage is the services' alone: the status
-# paths are the one coverage scope hfs sync renders into sonar.coverage.inclusions too, held at 100 on the project and on
+# paths are the one coverage scope whose complement hfs sync renders into sonar.coverage.exclusions, held at 100 on the project and on
 # the patch. fe/ is outside coverage (a front end has no tests).
 codecov:
   require_ci_to_pass: true

package/templates/app/quality-config/sonar-project.properties

@@ -8,5 +8,5 @@ sonar.test.inclusions=**/*.spec.ts
 sonar.typescript.tsconfigPaths={{tsconfigPaths}}
 sonar.externalIssuesReportPaths=reports/lint.sonar.json
 sonar.javascript.lcov.reportPaths={{lcovReport}}
-sonar.coverage.inclusions={{coverageInclusions}}
+sonar.coverage.exclusions={{coverageExclusions}}
 sonar.nodejs.maxspace=8192

package/templates/be/skeleton/src/modules/platform/http-security/origin.guard.ts

@@ -5,7 +5,7 @@ import { requestOf } from "./execution-request.mapper"
 import { InjectHttpSecurityOptions } from "./http-security.decorators"
 import type { HttpSecurityOptions } from "./http-security.options"
 
-const SAFE_METHODS: ReadonlyArray<string> = ["GET", "HEAD", "OPTIONS"]
+const SAFE_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD", "OPTIONS"])
 
 const originOf = (origin: string | undefined, referer: string | undefined): string | undefined => {
     if (origin) return origin
@@ -23,7 +23,7 @@ export class OriginGuard implements CanActivate {
     /** Refuses a state-changing request from an origin outside the allowlist. */
     canActivate(context: ExecutionContext): boolean {
         const request = requestOf(context)
-        if (SAFE_METHODS.includes(request.method)) return true
+        if (SAFE_METHODS.has(request.method)) return true
         const origin = originOf(request.headers.origin, request.headers.referer)
         if (origin === undefined || this.options.allowedOrigins.includes(origin)) return true
         throw new HttpSecurityError({ code: HttpSecurityErrorCode.OriginRejected })

package/templates/fe/skeleton/apps/__app__/next.config.ts

@@ -1,11 +1,19 @@
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
 import type { NextConfig } from "next"
 import createNextIntlPlugin from "next-intl/plugin"
 
+/** The request config lives in this app's i18n module; next-intl resolves it from the directory the build runs in. */
 const withNextIntl = createNextIntlPlugin("./src/modules/i18n/request.ts")
 
-/** Next config of the {{app}} app: next-intl wired to the request config, Turbopack rooted at the repository. */
+/** The npm workspace root (three levels above this app): Turbopack resolves the workspace packages from it, and output tracing is pinned to it. */
+const WORKSPACE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..")
+
+/** Next config of the {{app}} app: next-intl wired to the request config, root params on (the locale is read from the route). */
 const nextConfig: NextConfig = {
-    turbopack: { root: process.cwd() },
+    experimental: { rootParams: true },
+    outputFileTracingRoot: WORKSPACE_ROOT,
+    turbopack: { root: WORKSPACE_ROOT },
 }
 
 export default withNextIntl(nextConfig)

package/templates/fe/skeleton/apps/__app__/src/app/[locale]/error.tsx

@@ -5,6 +5,6 @@ import { ErrorPage } from "@/features/pages/ErrorPage"
 type ErrorProps = { readonly reset: () => void }
 
 /** The locale segment's error boundary slot: it mounts the error page and hands it the segment's retry. */
-const Error = (props: ErrorProps) => <ErrorPage onRetry={props.reset} />
+const ErrorBoundary = (props: ErrorProps) => <ErrorPage onRetry={props.reset} />
 
-export default Error
+export default ErrorBoundary

package/templates/fe/skeleton/apps/__app__/src/features/pages/ErrorPage/component.tsx

@@ -2,8 +2,6 @@ import { FailureScreen } from "@/components/composites/FailureScreen"
 
 /** Props for {@link ErrorPageBase}. */
 export type ErrorPageBaseProps = {
-    /** Whole-screen situations this surface settles; the error page only ever shows the failure. */
-    readonly state: "failed"
     /** The words the failure shows. */
     readonly props: {
         readonly title: string

package/templates/fe/skeleton/apps/__app__/src/features/pages/ErrorPage/index.tsx

@@ -7,11 +7,5 @@ type ErrorPageProps = { readonly onRetry: () => void }
 /** A render failure of the locale segment shows this instead of a blank page; retry re-renders the segment. */
 export const ErrorPage = (props: ErrorPageProps) => {
     const t = useTranslations("errors.page")
-    return (
-        <ErrorPageBase
-            state="failed"
-            props={{ title: t("title"), retryLabel: t("retry") }}
-            on={{ retry: props.onRetry }}
-        />
-    )
+    return <ErrorPageBase props={{ title: t("title"), retryLabel: t("retry") }} on={{ retry: props.onRetry }} />
 }

package/templates/fe/skeleton/apps/__app__/src/features/pages/GlobalErrorPage/component.tsx

@@ -2,8 +2,6 @@ import { FailureScreen } from "@/components/composites/FailureScreen"
 
 /** Props for {@link GlobalErrorPageBase}. */
 export type GlobalErrorPageBaseProps = {
-    /** Whole-screen situations this surface settles; the global error page only ever shows the failure. */
-    readonly state: "failed"
     /** The language of the document and the words the failure shows. */
     readonly props: {
         readonly lang: string

package/templates/fe/skeleton/apps/__app__/src/features/pages/GlobalErrorPage/index.tsx

@@ -8,7 +8,6 @@ type GlobalErrorPageProps = { readonly onRetry: () => void }
 /** The last-resort boundary above the locale layout: it has no provider, so it reads the default catalog directly. */
 export const GlobalErrorPage = (props: GlobalErrorPageProps) => (
     <GlobalErrorPageBase
-        state="failed"
         props={{ lang: DEFAULT_LOCALE, title: messages.errors.global.title, retryLabel: messages.errors.global.retry }}
         on={{ retry: props.onRetry }}
     />

package/templates/fe/skeleton/apps/__app__/src/features/pages/HomePage/component.tsx

@@ -2,12 +2,8 @@ import { GrammarRoot, Heading, PageContainer, WorkspaceShell } from "@starci/gra
 
 /** Props for {@link HomePageBase}. */
 export type HomePageBaseProps = {
-    /** Whole-screen situations this surface settles; the home page only ever shows its title. */
-    readonly state: "ready"
     /** The words the page shows. */
     readonly props: { readonly title: string }
-    /** What the surface reports upward; the page reports nothing. */
-    readonly on: Record<never, never>
 }
 
 /** Draw the front door of the app. */

package/templates/fe/skeleton/apps/__app__/src/features/pages/HomePage/index.tsx

@@ -11,5 +11,5 @@ export const homeMetadata = async (): Promise<Metadata> => {
 /** The first page of the app: a server component, so no catalog is shipped for it. */
 export const HomePage = async () => {
     const t = await getTranslations("home")
-    return <HomePageBase state="ready" props={{ title: t("title") }} on={{}} />
+    return <HomePageBase props={{ title: t("title") }} />
 }

package/templates/fe/skeleton/apps/__app__/src/features/pages/LoadingPage/component.tsx

@@ -2,12 +2,8 @@ import { GrammarRoot, PageContainer, Text, WorkspaceShell } from "@starci/gramma
 
 /** Props for {@link LoadingPageBase}. */
 export type LoadingPageBaseProps = {
-    /** Whole-screen situations this surface settles; the loading page only ever waits. */
-    readonly state: "loading"
     /** The words the wait announces. */
     readonly props: { readonly message: string }
-    /** What the surface reports upward; a wait reports nothing. */
-    readonly on: Record<never, never>
 }
 
 /** Draw the wait as one politely announced line. */

package/templates/fe/skeleton/apps/__app__/src/features/pages/LoadingPage/index.tsx

@@ -4,5 +4,5 @@ import { LoadingPageBase } from "./component"
 /** Shown while a route of the locale segment resolves. */
 export const LoadingPage = async () => {
     const t = await getTranslations("loading")
-    return <LoadingPageBase state="loading" props={{ message: t("message") }} on={{}} />
+    return <LoadingPageBase props={{ message: t("message") }} />
 }

package/templates/fe/skeleton/apps/__app__/src/features/pages/NotFoundPage/component.tsx

@@ -3,15 +3,11 @@ import { ROUTES } from "@/modules/routes"
 
 /** Props for {@link NotFoundPageBase}. */
 export type NotFoundPageBaseProps = {
-    /** Whole-screen situations this surface settles; the not-found page only ever says the page is missing. */
-    readonly state: "missing"
     /** The words the page shows. */
     readonly props: {
         readonly title: string
         readonly homeLabel: string
     }
-    /** What the surface reports upward; the page reports nothing. */
-    readonly on: Record<never, never>
 }
 
 /** Draw the missing-page message and the way back to the front door. */

package/templates/fe/skeleton/apps/__app__/src/features/pages/NotFoundPage/index.tsx

@@ -4,5 +4,5 @@ import { NotFoundPageBase } from "./component"
 /** Shown when a route calls `notFound()`. */
 export const NotFoundPage = async () => {
     const t = await getTranslations("notFound")
-    return <NotFoundPageBase state="missing" props={{ title: t("title"), homeLabel: t("home") }} on={{}} />
+    return <NotFoundPageBase props={{ title: t("title"), homeLabel: t("home") }} />
 }

package/templates/fe/skeleton/apps/__app__/src/modules/i18n/request.ts

@@ -1,11 +1,16 @@
 import "server-only"
 import { hasLocale } from "next-intl"
 import { getRequestConfig } from "next-intl/server"
+import { locale as routeLocale } from "next/root-params"
 import { routing } from "./routing"
 
-/** Resolves the locale of a request and loads its catalog; an unknown locale falls back to the default. */
-export default getRequestConfig(async ({ requestLocale }) => {
-    const requested = await requestLocale
+/**
+ * Resolves the locale of a request and loads its catalog; an unknown locale falls back to the default. The locale is the
+ * `[locale]` route param read through `next/root-params` (`experimental.rootParams` in next.config.ts), not the deprecated
+ * `requestLocale`.
+ */
+export default getRequestConfig(async () => {
+    const requested: unknown = await routeLocale()
     const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale
     return {
         locale,

package/templates/fe/skeleton/apps/__app__/src/proxy.ts

@@ -6,5 +6,5 @@ export default createMiddleware(routing)
 
 /** Everything except the API, the health probe, framework files and files with an extension. */
 export const config = {
-    matcher: ["/((?!api|health|_next|_vercel|.*\\..*).*)"],
+    matcher: ["/((?!api|health|_next|_vercel|.*[.].*).*)"],
 }

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));