@starci/hfs 4.7.44 → 4.7.45

package/runtime/scripts/hfs/example-secrets.mjs

@@ -6,6 +6,11 @@ import path from 'node:path';
 import { runProgram } from '../api/process/run-program.mjs';
 import { init as initGit } from '../api/git/init.mjs';
 import { add as addGit } from '../api/git/add.mjs';
+import { runGit } from '../api/git/lib.mjs';
+import { mergeBase } from '../api/git/merge-base.mjs';
+import { writeTree } from '../api/git/write-tree.mjs';
+import { commitTree } from '../api/git/commit-tree.mjs';
+import { updateRef } from '../api/git/update-ref.mjs';
 import { stringifyYaml } from '../../engine/yaml.mjs';
 import { isMain } from '../lib/is-main.mjs';
 import { readEnv } from '../lib/env.mjs';
@@ -50,7 +55,42 @@ export async function materializeExample(repoRoot, { createIdentity = generateAp
   }
 }
 
-function trackExample(repoRoot) {
+const COMMITTER = { 'user.name': 'starci', 'user.email': 'l4@starci.invalid' };
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+const ok = (r) => !r.error && r.status === 0 && Boolean(String(r.stdout ?? '').trim());
+
+/**
+ * The lint base the copy's size-growth ratchet measures against: the source app's subtree at the source repository's
+ * lint baseline (STARCI_BASE_REF, then origin/main, then main),
+ * re-committed inside the copy so `merge-base` and `git show` resolve here. The source objects are reached through an
+ * objects alternate, never copied. An app absent at the baseline bases on the empty tree: every file is new.
+ * Returns the synthetic base commit sha, or null when the source sits in no repository. Missing repository baselines fail explicitly.
+ */
+function sealedLintBase(repoRoot, source, env) {
+  const query = { cwd: source, env };
+  const top = runGit(['rev-parse', '--show-toplevel'], query);
+  if (!ok(top)) return null;
+  const common = runGit(['rev-parse', '--git-common-dir'], query);
+  if (!ok(common)) return null;
+  const candidates = [...(env.STARCI_BASE_REF ? [env.STARCI_BASE_REF] : []), 'origin/main', 'main'];
+  let baseSha = null;
+  for (const ref of candidates) {
+    baseSha = mergeBase(source, 'HEAD', ref);
+    if (baseSha) break;
+  }
+  if (!baseSha) throw new Error('sealed lint baseline unavailable: set STARCI_BASE_REF to a source commit sharing history with HEAD, or fetch origin/main or main');
+  const relative = path.relative(top.stdout.trim(), path.resolve(source)).split(path.sep).join('/');
+  const tree = runGit(['rev-parse', '--verify', '--quiet', relative && !relative.startsWith('..') ? `${baseSha}:${relative}` : `${baseSha}^{tree}`], query);
+  const baseTree = ok(tree) ? tree.stdout.trim() : EMPTY_TREE;
+  const info = path.join(repoRoot, '.git', 'objects', 'info');
+  fs.mkdirSync(info, { recursive: true });
+  fs.appendFileSync(path.join(info, 'alternates'), `${path.resolve(source, common.stdout.trim()).split(path.sep).join('/')}/objects\n`);
+  const base = commitTree([baseTree, '-m', 'sealed lint base'], { cwd: repoRoot, env, config: COMMITTER });
+  if (!ok(base)) throw new Error('could not commit the lint base of the isolated example git tree');
+  return base.stdout.trim();
+}
+
+function trackExample(repoRoot, source) {
   const env = withoutGitLocalEnv(process.env);
   if (!initGit(repoRoot, { env }).ok) throw new Error('could not initialize the isolated example git tree');
   // The linked node_modules (linkExampleDependencies: a junction on Windows, a symlink elsewhere) is the install, never a tracked entry: git treats a
@@ -59,6 +99,16 @@ function trackExample(repoRoot) {
   fs.appendFileSync(path.join(repoRoot, '.git', 'info', 'exclude'), ['', '# the linked install of the example (example-secrets.mjs)', 'node_modules', ''].join('\n'));
   const staged = addGit(['-A', '--', '.'], { cwd: repoRoot, env });
   if (staged.error || staged.status !== 0) throw new Error('could not stage the isolated example git tree');
+  // The isolated tree is committed (and based on the source's lint baseline) so the size-growth ratchet reads a real
+  // recorded size instead of failing "baseline unavailable" in every sealed lint, as it did on a historyless tree.
+  const base = sealedLintBase(repoRoot, source, env);
+  const tree = writeTree([], { cwd: repoRoot, env });
+  if (!ok(tree)) throw new Error('could not write the isolated example git tree');
+  const committed = commitTree([tree.stdout.trim(), ...(base ? ['-p', base] : []), '-m', 'sealed snapshot'], { cwd: repoRoot, env, config: COMMITTER });
+  if (!ok(committed)) throw new Error('could not commit the isolated example git tree');
+  const moved = updateRef(repoRoot, 'HEAD', committed.stdout.trim());
+  if (!moved.ok) throw new Error('could not point the isolated example git tree at its snapshot commit');
+  return base;
 }
 
 function safeExampleSource(source, { preserveCoverage = false } = {}) {
@@ -82,7 +132,7 @@ function pruneEmptyDirectories(directory) {
   if (!fs.readdirSync(directory).length) fs.rmdirSync(directory);
 }
 
-/** Await callback(tempExamplePath), return its result, and remove the os.tmpdir-based copy even on failure. */
+/** Await callback(tempExamplePath, lintBaseRef), return its result, and remove the os.tmpdir-based copy even on failure. */
 export async function withMaterializedExample(repoRoot, exampleRelativePath, callback, { materialize = materializeExample, linkDependencies = false, preserveCoverage = false } = {}) {
   const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-example-'));
   const source = path.resolve(repoRoot, exampleRelativePath);
@@ -96,8 +146,8 @@ export async function withMaterializedExample(repoRoot, exampleRelativePath, cal
     pruneEmptyDirectories(app);
     if (linkDependencies) linkExampleDependencies(source, app);
     await materialize(app);
-    trackExample(app);
-    return await callback(app);
+    const lintBaseRef = trackExample(app, source);
+    return await callback(app, lintBaseRef);
   } finally {
     safeRemove(directory, { hold: () => null });
   }
@@ -133,16 +183,19 @@ function commandLaunch(command, args) {
   return { file: process.execPath, args: [cli, ...args] };
 }
 
-function commandEnvironment() {
+// The copy's own lint base replaces any STARCI_BASE_REF of the caller, which names a ref of the source repository, not of the copy.
+function commandEnvironment(lintBaseRef) {
   const env = withoutGitLocalEnv(process.env);
-  return Object.fromEntries(Object.entries(env).filter(([name]) => !/^SOPS_AGE_KEY(?:_FILE)?$/iu.test(name)));
+  const out = Object.fromEntries(Object.entries(env).filter(([name]) => !/^SOPS_AGE_KEY(?:_FILE)?$/iu.test(name)));
+  if (lintBaseRef) out.STARCI_BASE_REF = lintBaseRef;
+  return out;
 }
 
 /** Run an installed app command in a sealed temporary copy, returning its exit code and preserving report artifacts. */
 async function runMaterializedCommand(repoRoot, command, args = [], { run = runProgram } = {}) {
-  return withMaterializedExample(repoRoot, '.', (app) => {
+  return withMaterializedExample(repoRoot, '.', (app, lintBaseRef) => {
     const launch = commandLaunch(command, args);
-    const result = run(launch.file, launch.args, { cwd: app, env: commandEnvironment(), stdio: 'inherit', windowsHide: true });
+    const result = run(launch.file, launch.args, { cwd: app, env: commandEnvironment(lintBaseRef), stdio: 'inherit', windowsHide: true });
     const reports = path.join(app, 'reports');
     if (fs.existsSync(reports)) fs.cpSync(reports, path.join(repoRoot, 'reports'), { recursive: true });
     if (result.error) throw new Error('the example check command could not start');

package/runtime/scripts/hfs/typescript-programs.mjs

@@ -9,6 +9,11 @@ import { byCodeUnit } from '../lib/list.mjs';
 // builds afresh.
 const runs = new AsyncLocalStorage();
 
+/** Share compiler inputs only until this check finishes; nested callers join the same run. */
+export function withTypeScriptProgramRun(run) {
+  return runs.getStore() ? run() : runs.run(new Map(), run);
+}
+
 
 function keyOf(value) {
   if (value === undefined) return 'u';
@@ -48,7 +53,28 @@ export function sharedInProgramRun(kind, ts, input, build) {
 /** ts.createProgram, shared inside a program run. */
 export function createTypeScriptProgram(ts, { rootNames, options, projectReferences }) {
   return sharedInProgramRun('program', ts, { rootNames, options, projectReferences },
-    () => ts.createProgram({ rootNames, options, projectReferences }));
+    () => ts.createProgram({ rootNames, options, projectReferences, host: sharedSourceHost(ts, options) }));
+}
+
+function sharedSourceHost(ts, options) {
+  if (!runs.getStore()) return undefined;
+  const registry = sharedInProgramRun('documents', ts, null,
+    () => ts.createDocumentRegistry(ts.sys.useCaseSensitiveFileNames, ts.sys.getCurrentDirectory()));
+  const host = ts.createCompilerHost(options);
+  const readSource = host.getSourceFile;
+  // TypeScript's registry separates parse-affecting settings and Node module formats. Sharing syntax trees leaves
+  // module resolution and symbol/type caches with each program, including projects with different path aliases.
+  host.getSourceFile = (file, sourceOptions, onError, fresh) => {
+    if (fresh) return readSource(file, sourceOptions, onError, fresh);
+    let text;
+    try { text = host.readFile(file); } catch (error) {
+      onError?.(String(error.message ?? error));
+      text = '';
+    }
+    if (text === undefined) return undefined;
+    return registry.acquireDocument(file, options, ts.ScriptSnapshot.fromString(text), '0', undefined, sourceOptions);
+  };
+  return host;
 }
 
 /** Read and expand a tsconfig with the caller's TypeScript compiler and optional tracked file reader. */
@@ -66,6 +92,7 @@ export function typeScriptProjectReferencePath(ts, reference) {
 }
 
 /** Resolve an import using the selected project's compiler options. */
-export function resolveTypeScriptModule(ts, specifier, from, options, host = ts.sys) {
-  return ts.resolveModuleName(specifier, from, options, host).resolvedModule?.resolvedFileName;
+export function resolveTypeScriptModule(ts, specifier, from, options, host, cache) {
+  const resolverHost = host === undefined ? ts.sys : host;
+  return ts.resolveModuleName(specifier, from, options, resolverHost, cache).resolvedModule?.resolvedFileName;
 }

package/runtime/scripts/lib/release-version.mjs

@@ -1,134 +1,134 @@
-// release-version.mjs - the one reading of a release version (owner ruling release-waves). A prerelease `<label>.N` opens the release
-// line N and `<label>.N.M` is the M-th release after it, a wave or a fix alike, so alpha.31 < alpha.31.1 < alpha.31.2 < alpha.32 in
-// SemVer order. The next release is derived from the highest one already released, never guessed. The legacy `<label>.N-fix.K` still
-// reads as release K after `<label>.N` and is never produced again. Pure: the callers read the tags and the registry.
-
-const NUMERIC = /^(?:0|[1-9]\d*)$/;
-const POSITIVE = /^[1-9]\d*$/;
-const IDENTIFIERS = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
-const LEGACY_FIX = '-fix.';
-
-/** {base, wave, legacy}: the release a version counts its waves from, and its wave M (0 for the release that opens the line). */
-export function waveOf(version) {
-  const text = String(version ?? '').split('+')[0];
-  const fix = text.lastIndexOf(LEGACY_FIX);
-  const legacyWave = fix > 0 ? text.slice(fix + LEGACY_FIX.length) : '';
-  if (POSITIVE.test(legacyWave)) return { base: text.slice(0, fix), wave: Number(legacyWave), legacy: true };
-  const ids = text.split('.');
-  const counted = ids.length > 3 && POSITIVE.test(ids.at(-1)) && (text.includes('-') ? NUMERIC.test(ids.at(-2)) : ids.length === 4);
-  return counted ? { base: ids.slice(0, -1).join('.'), wave: Number(ids.at(-1)), legacy: false } : { base: text, wave: 0, legacy: false };
-}
-
-/** Parsed SemVer identifiers {core, pre} of `version`; an unreadable version throws. */
-export function versionParts(version) {
-  const parts = typeof version === 'string' ? version.split('+') : [];
-  if (!parts.length || parts.length > 2 || (parts.length === 2 && !IDENTIFIERS.test(parts[1]))) throw new Error(`unreadable release version ${version}`);
-  const boundary = parts[0].indexOf('-');
-  const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
-  const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
-  if (core.length !== 3 || core.some((part) => !NUMERIC.test(part)) || (prerelease !== null && !IDENTIFIERS.test(prerelease))) throw new Error(`unreadable release version ${version}`);
-  const pre = prerelease?.split('.') ?? [];
-  if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
-  return { core: core.map(BigInt), pre };
-}
-
-const readable = (version) => {
-  try {
-    versionParts(version);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-/** The SemVer spelling a version is ordered by: a legacy `-fix.K` orders as wave K of its line. */
-const ordered = (version) => {
-  const { base, wave, legacy } = waveOf(version);
-  return legacy ? `${base}.${wave}` : version;
-};
-
-const compareIdentifier = (a, b) => {
-  const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
-  if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
-  if (numericA !== numericB) return numericA ? -1 : 1;
-  return a < b ? -1 : Number(a > b);
-};
-
-/** SemVer precedence, numeric prerelease identifiers included; build metadata has no precedence. */
-export function compareVersions(a, b) {
-  const left = versionParts(ordered(a)), right = versionParts(ordered(b));
-  for (const i of left.core.keys()) {
-    if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
-  }
-  if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
-  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
-    if (left.pre[i] === undefined) return -1;
-    if (right.pre[i] === undefined) return 1;
-    const compared = compareIdentifier(left.pre[i], right.pre[i]);
-    if (compared) return compared;
-  }
-  return 0;
-}
-
-/** The release line of `version`: a prerelease's core and the identifiers before its first number (every alpha.N and alpha.N.M share one), a stable release's major and minor. */
-export function releaseLine(version) {
-  const { core, pre } = versionParts(ordered(version));
-  if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
-  const first = pre.findIndex((id) => /^\d+$/.test(id));
-  return `${core.join('.')}-${(first < 0 ? pre : pre.slice(0, first)).join('.')}`;
-}
-
-/** {family, line} of a release that opens a line (`<x.y.z>-<label>.N`), or null for any other shape. */
-function lineStart(base) {
-  if (!readable(base)) return null;
-  const { core, pre } = versionParts(base);
-  return pre.length === 2 && !/^\d+$/.test(pre[0]) && NUMERIC.test(pre[1]) ? { family: `${core.join('.')}-${pre[0]}`, line: Number(pre[1]) } : null;
-}
-
-/** The next wave after `version`: its base with M one past the highest wave of that base among `version` and `known`. */
-export function nextWave(version, known = []) {
-  const { base } = waveOf(version);
-  const waves = [version, ...known].map(waveOf).filter((entry) => entry.base === base).map((entry) => entry.wave);
-  return `${base}.${Math.max(0, ...waves) + 1}`;
-}
-
-/** The family of a version: its core and label up to `-<label>` (`1.0.0-alpha`), or null for a stable or unlabelled version. */
-export function familyOf(version) {
-  if (!readable(version)) return null;
-  const { core, pre } = versionParts(ordered(version));
-  return pre.length && !/^\d+$/.test(pre[0]) ? `${core.join('.')}-${pre[0]}` : null;
-}
-
-/**
- * What may follow the highest line-shaped release of `versions`: {highest, family, wave, line}, or null when none has that shape.
- * With a `candidate`, a family that already has released tags is judged alone (another family's tags, such as legacy 2.0.1-alpha.N,
- * never outrank the candidate's own line); a family without a tag falls back to the highest release overall.
- */
-export function nextReleases(versions, candidate = null) {
-  const shaped = versions.filter((version) => readable(version) && lineStart(waveOf(version).base));
-  const family = candidate === null ? null : familyOf(candidate);
-  const own = family === null ? [] : shaped.filter((version) => lineStart(waveOf(version).base).family === family);
-  const pool = own.length ? own : shaped;
-  if (!pool.length) return null;
-  const highest = pool.reduce((top, version) => (compareVersions(version, top) > 0 ? version : top));
-  const start = lineStart(waveOf(highest).base);
-  return { highest, family: start.family, wave: nextWave(highest, pool), line: `${start.family}.${start.line + 1}` };
-}
-
-/**
- * Why `version` cannot be released after `released` (the versions already tagged), or null when it can: the next wave of the highest
- * release of its own family, the first release of the next line, or (when its family has no tag) a later release of another label or
- * core than the highest. The legacy `-fix` form is always refused.
- */
-export function releaseVersionRefusal(version, released) {
-  const next = nextReleases(released.filter((entry) => entry !== version), version);
-  const named = next ? `; the next release is ${next.wave} (the next wave or fix after ${next.highest}) or ${next.line} (the next line)` : '';
-  if (waveOf(version).legacy) return `${version} is the legacy -fix form, which is read and never released again${named}`;
-  if (!next || version === next.wave || version === next.line) return null;
-  if (!readable(version)) return `${version} is not a SemVer version${named}`;
-  if (lineStart(waveOf(version).base)?.family !== next.family && compareVersions(version, next.highest) > 0) return null;
-  return `${version} does not follow ${next.highest}${named}`;
-}
-
-/** The versions of the release tags `v<version>` in the output of `git tag --list`. */
-export const taggedVersions = (listing) => String(listing ?? '').split(/\r?\n/).map((name) => name.trim()).filter((name) => /^v\d/.test(name)).map((name) => name.slice(1));
+// release-version.mjs - the one reading of a release version (owner ruling release-waves). A prerelease `<label>.N` opens the release
+// line N and `<label>.N.M` is the M-th release after it, a wave or a fix alike, so alpha.31 < alpha.31.1 < alpha.31.2 < alpha.32 in
+// SemVer order. The next release is derived from the highest one already released, never guessed. The legacy `<label>.N-fix.K` still
+// reads as release K after `<label>.N` and is never produced again. Pure: the callers read the tags and the registry.
+
+const NUMERIC = /^(?:0|[1-9]\d*)$/;
+const POSITIVE = /^[1-9]\d*$/;
+const IDENTIFIERS = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
+const LEGACY_FIX = '-fix.';
+
+/** {base, wave, legacy}: the release a version counts its waves from, and its wave M (0 for the release that opens the line). */
+export function waveOf(version) {
+  const text = String(version ?? '').split('+')[0];
+  const fix = text.lastIndexOf(LEGACY_FIX);
+  const legacyWave = fix > 0 ? text.slice(fix + LEGACY_FIX.length) : '';
+  if (POSITIVE.test(legacyWave)) return { base: text.slice(0, fix), wave: Number(legacyWave), legacy: true };
+  const ids = text.split('.');
+  const counted = ids.length > 3 && POSITIVE.test(ids.at(-1)) && (text.includes('-') ? NUMERIC.test(ids.at(-2)) : ids.length === 4);
+  return counted ? { base: ids.slice(0, -1).join('.'), wave: Number(ids.at(-1)), legacy: false } : { base: text, wave: 0, legacy: false };
+}
+
+/** Parsed SemVer identifiers {core, pre} of `version`; an unreadable version throws. */
+export function versionParts(version) {
+  const parts = typeof version === 'string' ? version.split('+') : [];
+  if (!parts.length || parts.length > 2 || (parts.length === 2 && !IDENTIFIERS.test(parts[1]))) throw new Error(`unreadable release version ${version}`);
+  const boundary = parts[0].indexOf('-');
+  const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
+  const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
+  if (core.length !== 3 || core.some((part) => !NUMERIC.test(part)) || (prerelease !== null && !IDENTIFIERS.test(prerelease))) throw new Error(`unreadable release version ${version}`);
+  const pre = prerelease?.split('.') ?? [];
+  if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
+  return { core: core.map(BigInt), pre };
+}
+
+const readable = (version) => {
+  try {
+    versionParts(version);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The SemVer spelling a version is ordered by: a legacy `-fix.K` orders as wave K of its line. */
+const ordered = (version) => {
+  const { base, wave, legacy } = waveOf(version);
+  return legacy ? `${base}.${wave}` : version;
+};
+
+const compareIdentifier = (a, b) => {
+  const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
+  if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
+  if (numericA !== numericB) return numericA ? -1 : 1;
+  return a < b ? -1 : Number(a > b);
+};
+
+/** SemVer precedence, numeric prerelease identifiers included; build metadata has no precedence. */
+export function compareVersions(a, b) {
+  const left = versionParts(ordered(a)), right = versionParts(ordered(b));
+  for (const i of left.core.keys()) {
+    if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
+  }
+  if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
+    if (left.pre[i] === undefined) return -1;
+    if (right.pre[i] === undefined) return 1;
+    const compared = compareIdentifier(left.pre[i], right.pre[i]);
+    if (compared) return compared;
+  }
+  return 0;
+}
+
+/** The release line of `version`: a prerelease's core and the identifiers before its first number (every alpha.N and alpha.N.M share one), a stable release's major and minor. */
+export function releaseLine(version) {
+  const { core, pre } = versionParts(ordered(version));
+  if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
+  const first = pre.findIndex((id) => /^\d+$/.test(id));
+  return `${core.join('.')}-${(first < 0 ? pre : pre.slice(0, first)).join('.')}`;
+}
+
+/** {family, line} of a release that opens a line (`<x.y.z>-<label>.N`), or null for any other shape. */
+function lineStart(base) {
+  if (!readable(base)) return null;
+  const { core, pre } = versionParts(base);
+  return pre.length === 2 && !/^\d+$/.test(pre[0]) && NUMERIC.test(pre[1]) ? { family: `${core.join('.')}-${pre[0]}`, line: Number(pre[1]) } : null;
+}
+
+/** The next wave after `version`: its base with M one past the highest wave of that base among `version` and `known`. */
+export function nextWave(version, known = []) {
+  const { base } = waveOf(version);
+  const waves = [version, ...known].map(waveOf).filter((entry) => entry.base === base).map((entry) => entry.wave);
+  return `${base}.${Math.max(0, ...waves) + 1}`;
+}
+
+/** The family of a version: its core and label up to `-<label>` (`1.0.0-alpha`), or null for a stable or unlabelled version. */
+export function familyOf(version) {
+  if (!readable(version)) return null;
+  const { core, pre } = versionParts(ordered(version));
+  return pre.length && !/^\d+$/.test(pre[0]) ? `${core.join('.')}-${pre[0]}` : null;
+}
+
+/**
+ * What may follow the highest line-shaped release of `versions`: {highest, family, wave, line}, or null when none has that shape.
+ * With a `candidate`, a family that already has released tags is judged alone (another family's tags, such as legacy 2.0.1-alpha.N,
+ * never outrank the candidate's own line); a family without a tag falls back to the highest release overall.
+ */
+export function nextReleases(versions, candidate = null) {
+  const shaped = versions.filter((version) => readable(version) && lineStart(waveOf(version).base));
+  const family = candidate === null ? null : familyOf(candidate);
+  const own = family === null ? [] : shaped.filter((version) => lineStart(waveOf(version).base).family === family);
+  const pool = own.length ? own : shaped;
+  if (!pool.length) return null;
+  const highest = pool.reduce((top, version) => (compareVersions(version, top) > 0 ? version : top));
+  const start = lineStart(waveOf(highest).base);
+  return { highest, family: start.family, wave: nextWave(highest, pool), line: `${start.family}.${start.line + 1}` };
+}
+
+/**
+ * Why `version` cannot be released after `released` (the versions already tagged), or null when it can: the next wave of the highest
+ * release of its own family, the first release of the next line, or (when its family has no tag) a later release of another label or
+ * core than the highest. The legacy `-fix` form is always refused.
+ */
+export function releaseVersionRefusal(version, released) {
+  const next = nextReleases(released.filter((entry) => entry !== version), version);
+  const named = next ? `; the next release is ${next.wave} (the next wave or fix after ${next.highest}) or ${next.line} (the next line)` : '';
+  if (waveOf(version).legacy) return `${version} is the legacy -fix form, which is read and never released again${named}`;
+  if (!next || version === next.wave || version === next.line) return null;
+  if (!readable(version)) return `${version} is not a SemVer version${named}`;
+  if (lineStart(waveOf(version).base)?.family !== next.family && compareVersions(version, next.highest) > 0) return null;
+  return `${version} does not follow ${next.highest}${named}`;
+}
+
+/** The versions of the release tags `v<version>` in the output of `git tag --list`. */
+export const taggedVersions = (listing) => String(listing ?? '').split(/\r?\n/).map((name) => name.trim()).filter((name) => /^v\d/.test(name)).map((name) => name.slice(1));

package/templates/be/inbox/platform/inbox/inbox.port.ts.tpl

@@ -13,9 +13,7 @@ export interface ClientOperation {
 }
 
 /** The domain work whose JSON result commits with the client receipt. */
-export interface ClientOperationEffect<T> {
-    (): Promise<T>
-}
+export type ClientOperationEffect<T> = () => Promise<T>
 
 /** The signed provider header may omit its delivery identity; the adapter refuses that delivery. */
 export type InboxEventId = string | undefined

package/templates/be/patterns/idempotency/platform/inbox/inbox.port.ts.tpl

@@ -27,9 +27,7 @@ export interface DeliveryClaimBackfill extends DeliveryClaim {
 }
 
 /** The domain work whose JSON result commits with the client receipt. */
-export interface ClientOperationEffect<T> {
-    (): Promise<T>
-}
+export type ClientOperationEffect<T> = () => Promise<T>
 
 /** Deduplicates deliveries by the source and event id of their consumer. */
 export interface Inbox {

package/templates/be/patterns/realtime/realtime-config.mapper.ts.tpl

@@ -0,0 +1,32 @@
+import type { EnvSource } from "@modules/platform/config"
+import { REDIS_DEFAULT_PREFIX } from "./realtime.contracts"
+import type { PostgresRealtimeConfig, RealtimeConfig, RedisRealtimeOptions } from "./realtime.options"
+
+/** The hubs an app can run. */
+const HUBS = ["memory", "postgres", "redis"] as const
+
+/** The Redis hub: its URL (a secret), database and the prefix of its channel and keys. */
+const redisConfigOf = (env: EnvSource): RedisRealtimeOptions => ({
+    hub: "redis",
+    url: env.secret("REALTIME_REDIS_URL"),
+    db: env.int("REALTIME_REDIS_DB", 0),
+    prefix: env.optional("REALTIME_REDIS_PREFIX") ?? REDIS_DEFAULT_PREFIX,
+})
+
+/** The Postgres hub: the dedicated LISTEN URL when `REALTIME_DB_URL` is declared. */
+const postgresConfigOf = (env: EnvSource): PostgresRealtimeConfig => ({
+    hub: "postgres",
+    listenUrl: env.has("REALTIME_DB_URL") ? env.secret("REALTIME_DB_URL") : undefined,
+})
+
+/**
+ * Reads the hub from `REALTIME_HUB`; when it is not declared the full edition defaults to `redis` (the in-process `memory` hub is
+ * never a default, so a scaled deploy cannot fall back to it unseen). For the Redis hub it reads the address and prefix. A Postgres
+ * hub LISTENs on `REALTIME_DB_URL` when it is declared (a direct or session-mode URL, never a transaction pooler), else on the
+ * primary database URL; either way the boot probe refuses a connection that does not deliver notifications.
+ */
+export const parseRealtimeConfig = (env: EnvSource): RealtimeConfig => {
+    const hub = env.has("REALTIME_HUB") ? env.enum("REALTIME_HUB", HUBS) : "redis"
+    if (hub === "redis") return redisConfigOf(env)
+    return hub === "postgres" ? postgresConfigOf(env) : { hub }
+}