@starci/hfs 4.7.44 → 4.7.46

package/runtime/scripts/hfs/architecture/type-context.mjs

@@ -103,36 +103,35 @@ function createProjects(config, paths, state, selection, ts, helpers) {
   return projects;
 }
 
+function ownershipRank(config, project, file, helpers) {
+  return helpers.isInside(path.dirname(path.join(config.root, ...project.relative.split('/'))), file)
+    ? project.relative.split('/').length : -1;
+}
+
 function collectProjectFiles(config, projects, helpers) {
-  const occurrences = new Map();
-  const sourceIn = new Map();
+  const fileMap = new Map();
+  const ownerByFile = new Map();
+  // Retain only the winning source occurrence while visiting each project. Equal ranks keep the first project,
+  // as does a file outside every project directory; the deepest enclosing tsconfig otherwise owns its checker.
+  // Within that project the last realpath alias supplies the source, matching the compiler's occurrence order.
   for (const project of projects) {
-    for (const sourceFile of project.program.getSourceFiles().filter(file => helpers.isProductionSource(config.root, file))) {
+    for (const sourceFile of project.program.getSourceFiles()) {
+      if (!helpers.isProductionSource(config.root, sourceFile)) continue;
       const name = helpers.canonical(sourceFile.fileName);
-      if (!occurrences.has(name)) occurrences.set(name, []);
-      occurrences.get(name).push(project);
-      sourceIn.set(`${project.relative}|${name}`, sourceFile);
+      const owner = ownerByFile.get(name);
+      if (owner === project) { fileMap.set(name, sourceFile); continue; }
+      if (owner && ownershipRank(config, owner, name, helpers) >= ownershipRank(config, project, name, helpers)) continue;
+      ownerByFile.set(name, project);
+      fileMap.set(name, sourceFile);
     }
   }
-  return { occurrences, sourceIn };
-}
-
-function owningProject(config, candidates, file, helpers) {
-  return candidates.filter(item => helpers.isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), file))
-    .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+  return { fileMap, ownerByFile };
 }
 
 function makeFileGraph(config, projects, helpers) {
-  const { occurrences, sourceIn } = collectProjectFiles(config, projects, helpers);
-  const fileMap = new Map();
+  const { fileMap, ownerByFile } = collectProjectFiles(config, projects, helpers);
   const checkerByFile = new Map();
-  const ownerByFile = new Map();
-  for (const [name, candidates] of occurrences) {
-    const owner = owningProject(config, candidates, name, helpers);
-    ownerByFile.set(name, owner);
-    fileMap.set(name, sourceIn.get(`${owner.relative}|${name}`));
-    checkerByFile.set(name, owner.program.getTypeChecker());
-  }
+  for (const [name, owner] of ownerByFile) checkerByFile.set(name, owner.program.getTypeChecker());
   const files = [...fileMap.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, file]) => file);
   const edges = new Map([...fileMap.keys()].map(file => [file, []]));
   for (const [file, sourceFile] of fileMap) {
@@ -142,6 +141,21 @@ function makeFileGraph(config, projects, helpers) {
   return { fileMap, checkerByFile, ownerByFile, files, edges };
 }
 
+// Resolution entries contain failed lookup paths as well as hits. Keep only one bounded batch for the current project;
+// graph edges retain the resolved targets, so rotating this scratch cache changes neither coverage nor findings.
+const RESOLUTION_BATCH_SIZE = 1024;
+
+function resolutionCache(state, project) {
+  if (state.resolutionProject !== project || state.resolutionCount === RESOLUTION_BATCH_SIZE) {
+    state.resolutionProject = project;
+    state.resolutionCount = 0;
+    state.resolutionCache = state.ts.createModuleResolutionCache(state.config.root,
+      file => state.ts.sys.useCaseSensitiveFileNames ? file : file.toLowerCase(), project.options);
+  }
+  state.resolutionCount += 1;
+  return state.resolutionCache;
+}
+
 function addUnprovenFindings(sourceFile, project, references, errors, config, helpers) {
   for (const item of references.unproven) errors.push({
     ruleId: 'ARCH_DYNAMIC_DEPENDENCY_UNPROVEN',
@@ -229,7 +243,7 @@ function processReference(from, sourceFile, project, owningWorkspace, reference,
   const { config, ts, workspaceNames, workspaces, host, errors, helpers } = state;
   // A workspace package is read at its source, never at its build: the same import resolves whether or not dist exists.
   const workspaceTarget = workspaces.filter(item => item.root !== helpers.canonical(config.root)).map(item => helpers.workspaceSourceEntry(ts, item, reference.specifier)).find(Boolean);
-  const resolvedName = workspaceTarget ?? helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host);
+  const resolvedName = workspaceTarget ?? helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));
   if (!resolvedName) {
     unresolvedReferenceFinding(reference, sourceFile, project, config, workspaceNames, errors, helpers);
     return;
@@ -279,7 +293,8 @@ export function contextFromProjects(config, loaded, paths, helpers) {
   const fileGraph = makeFileGraph(config, projects, helpers);
   const { edges, workspaces } = dependencyGraph(config, loaded, fileGraph, fileGraph.ownerByFile, errors, helpers);
   if (projects.length && fileGraph.files.length === 0) errors.push({ ruleId: 'ARCH_NO_SOURCE', message: 'The configured TypeScript projects contain no production TypeScript or JavaScript source.' });
+  const { checkerByFile } = fileGraph;
   return { loaded, errors, files: fileGraph.files, edges, programs: projects.map(item => item.program), program: projects[0]?.program ?? null, projects, ts, workspaces,
-    checkerFor: file => fileGraph.checkerByFile.get(helpers.canonical(file)) ?? null,
+    checkerFor: file => checkerByFile.get(helpers.canonical(file)) ?? null,
     workspaceOf: file => helpers.workspaceOf(workspaces, helpers.canonical(file)) };
 }

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 { revParseQuery } from '../api/git/rev-parse-query.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 = revParseQuery(['--show-toplevel'], query);
+  if (!ok(top)) return null;
+  const common = revParseQuery(['--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 = revParseQuery(['--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/rules/deploy-workflow.mjs

@@ -80,9 +80,9 @@ function hasAgeIdentity(job, doc) {
 
 /** The release candidate branches (OWNER RULING candidate-ci, 2026-10-18): `starci app release push` waits for the ci.yml run of the release sha there. */
 const CANDIDATE_BRANCHES = 'release/candidate-*';
-const pushFilterValid = (options) => record(options) && Object.keys(options).length > 0 && Object.keys(options).every((key) => key === 'tags' || key === 'branches')
+const pushFilterValid = (options, ci) => record(options) && Object.keys(options).length > 0 && Object.keys(options).every((key) => key === 'tags' || key === 'branches')
   && (options.tags === undefined || (Array.isArray(options.tags) && options.tags.length === 1 && options.tags[0] === 'v*'))
-  && (options.branches === undefined || (Array.isArray(options.branches) && options.branches.length === 1 && options.branches[0] === CANDIDATE_BRANCHES));
+  && (options.branches === undefined || (Array.isArray(options.branches) && options.branches.length > 0 && new Set(options.branches).size === options.branches.length && options.branches.every((branch) => branch === CANDIDATE_BRANCHES || (ci && branch === 'main'))));
 
 function triggerFindings(doc, refuse, file = '') {
   const on = workflowEventOptions(doc.on);
@@ -94,11 +94,11 @@ function triggerFindings(doc, refuse, file = '') {
   for (const [event, options] of Object.entries(on)) {
     if (event === 'workflow_dispatch') continue;
     if (event !== 'push') {
-      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches or workflow_dispatch`));
+      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches, main in ci.yml, or workflow_dispatch`));
       continue;
     }
-    if (!pushFilterValid(options)) {
-      findings.push(refuse(TRIGGER, `push may contain only tags: [v*] and branches: ['${CANDIDATE_BRANCHES}']; other branch and path filters are forbidden`));
+    if (!pushFilterValid(options, /(^|\/)ci\.ya?ml$/.test(file))) {
+      findings.push(refuse(TRIGGER, `push may contain only tags: [v*] and branches: ['${CANDIDATE_BRANCHES}']; ci.yml may also name main; other branch and path filters are forbidden`));
     }
   }
   return findings;

package/runtime/scripts/hfs/runtime-rules/git-triggers.mjs

@@ -0,0 +1,61 @@
+// CI_TRIGGERS_RELEASE_ONLY: runtime workflows and app ci.yml may judge main; release candidates, v* tags and manual dispatch retain their scope.
+import { parseWorkflow, workflowFindings } from './workflow-source.mjs';
+import { workflowEventOptions } from '../../lib/workflow-events.mjs';
+
+export const CODE = 'CI_TRIGGERS_RELEASE_ONLY';
+const RELEASE_TAGS = 'v*';
+const RUNTIME_BRANCH = 'main';
+/** The branch pattern of the release candidate refs (refs/heads/release/candidate-<version>), shared with the release flows. */
+export const CANDIDATE_BRANCHES = 'release/candidate-*';
+/** The workflows that judge an app release (every app ci.yml): they must run on the candidate refs. The runtime's own workflows judge each push to main instead. */
+const RELEASE_WORKFLOW = /(^|\/)ci\.ya?ml$/;
+
+const isReleaseTagFilter = (tags) => Array.isArray(tags) && tags.length === 1 && String(tags[0]) === RELEASE_TAGS;
+/** The branches a filter may name: main (runtime workflows and app ci.yml) and the candidate pattern. */
+const allowedBranches = (ownBranch) => (ownBranch ? [RUNTIME_BRANCH, CANDIDATE_BRANCHES] : [CANDIDATE_BRANCHES]);
+const isBranchFilter = (ownBranch, branches) => Array.isArray(branches) && branches.length > 0 && new Set(branches.map(String)).size === branches.length
+  && branches.every((branch) => allowedBranches(ownBranch).includes(String(branch)));
+const namesCandidate = (branches) => Array.isArray(branches) && branches.map(String).includes(CANDIDATE_BRANCHES);
+
+const missingFilterMessage = (ownBranch) => (ownBranch
+  ? `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches\` of [${RUNTIME_BRANCH}, '${CANDIDATE_BRANCHES}'] (no other branch starts CI)`
+  : `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches: ['${CANDIDATE_BRANCHES}']\` (no other branch starts an app's CI)`);
+
+const branchFilterMessage = (ownBranch) => (ownBranch
+  ? `\`push.branches\` may name only ${RUNTIME_BRANCH} and '${CANDIDATE_BRANCHES}', each once`
+  : `\`push.branches\` may name only '${CANDIDATE_BRANCHES}' in an example or an app template: its CI runs on the release candidate and the release tag`);
+
+function pushFindings({ ownBranch, config, refuse, release }) {
+  const filters = config && typeof config === 'object' && !Array.isArray(config) ? config : {};
+  const { tags, branches } = filters;
+  const found = [];
+  if (tags === undefined && branches === undefined) found.push(refuse(missingFilterMessage(ownBranch)));
+  if (tags !== undefined && !isReleaseTagFilter(tags)) found.push(refuse(`\`push.tags\` must be exactly ['${RELEASE_TAGS}']`));
+  if (branches !== undefined && !isBranchFilter(ownBranch, branches)) found.push(refuse(branchFilterMessage(ownBranch)));
+  if (release && !namesCandidate(branches)) found.push(refuse(`\`push.branches\` must name '${CANDIDATE_BRANCHES}': starci app release push waits for the CI run of the release sha on its candidate ref`));
+  for (const other of Object.keys(filters).filter((key) => key !== 'tags' && key !== 'branches')) found.push(refuse(`\`push.${other}\` is not allowed beside the trigger filters`));
+  return found;
+}
+
+function eventFindings({ event, config, ownBranch, refuse, release }) {
+  if (event === 'workflow_dispatch') return [];
+  if (event !== 'push') return [refuse(`the trigger \`${event}\` is not allowed: only a push of release tags [${RELEASE_TAGS}], of '${CANDIDATE_BRANCHES}' (and, in runtime workflows or app ci.yml, of branch ${RUNTIME_BRANCH}) and workflow_dispatch may start CI`)];
+  return pushFindings({ ownBranch, config, refuse, release });
+}
+
+/** The CI_TRIGGERS_RELEASE_ONLY findings of one workflow text; a text that is not YAML yields none (the other checks name it). Runtime workflows and app ci.yml may also push on main. */
+function workflowTriggerFindings({ path: file, text }) {
+  const doc = parseWorkflow(text);
+  if (!doc || typeof doc !== 'object') return [];
+  const ownBranch = file.startsWith('.github/workflows/') || RELEASE_WORKFLOW.test(file);
+  const refuse = (why) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${why}` });
+  const on = doc.on;
+  if (on === undefined || on === null) return [refuse('the workflow has no `on` trigger block: it must declare push of tags [v*] and/or workflow_dispatch')];
+  const events = workflowEventOptions(on, String);
+  const release = !file.startsWith('.github/workflows/') && RELEASE_WORKFLOW.test(file);
+  const missingPush = release && !Object.hasOwn(events, 'push') ? [refuse(`the app release workflow must run on a push of '${CANDIDATE_BRANCHES}' and of tags [${RELEASE_TAGS}]`)] : [];
+  return [...missingPush, ...Object.entries(events).flatMap(([event, config]) => eventFindings({ event, config, ownBranch, refuse, release }))];
+}
+
+/** CI_TRIGGERS_RELEASE_ONLY over every tracked workflow (ctx of scripts/hfs/runtime-check.mjs). */
+export const gitTriggerFindings = (ctx) => workflowFindings(ctx, workflowTriggerFindings);

package/runtime/scripts/hfs/runtime-rules/hook-shape.mjs

@@ -1,9 +1,7 @@
 // hook-shape.mjs - RT_HOOK_SHAPE (knowledge/hfs/rules.yaml, gate runtime): the app hook templates keep the gate model.
 //   pre-commit  L0 only: no typecheck and no test run (`test:` scripts, npm test, jest, vitest, a spec). Types and the targeted specs
 //               belong to the op gate.
-//   pre-push    a release gate check, never a build or test run: no npm test, jest, vitest, typecheck or lint, and it carries the
-//               release gate markers: `starci-release` (the L4 record directory), `refs/backup/` (the backup namespace) and `v[0-9]`
-//               (the release tag pattern). A push of anything but the release cut and refs/backup/* is refused there.
+//   pre-push    the bundled push gate owns fast-forward main, annotated tags and the secret scan; no build, test or lint run.
 // Guard hooks keep their host timeout above the runtime's own input, verdict, cleanup and output budgets.
 // Comments are not judged (the templates explain what they do not run). Pure apart from ctx.read.
 import { shellCommandSource } from '../../lib/shell-source.mjs';
@@ -25,7 +23,7 @@ const PRE_PUSH_FORBIDDEN = [
   [/\btypecheck\b/, 'a typecheck'],
   [/\blint\b/, 'a lint run'],
 ];
-const PRE_PUSH_MARKERS = ['starci-release', 'refs/backup/', 'v[0-9]', 'RIGHTS_PUSH_NOT_RELEASE'];
+const PRE_PUSH_MARKERS = ["node --input-type=module -e", "import { main } from '@starci/hfs/runtime/scripts/guards/release-push-gate.mjs'", 'process.exit(await main())'];
 
 const finding = (file, message) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${message}` });
 
@@ -35,13 +33,13 @@ function fileHookShapeFindings({ path: file, name, text }) {
   const found = [];
   const forbidden = name === 'pre-commit' ? PRE_COMMIT_FORBIDDEN : PRE_PUSH_FORBIDDEN;
   for (const [pattern, what] of forbidden) {
-    if (pattern.test(body)) found.push(finding(file, name === 'pre-commit' ? `the commit gate is L0 only and runs ${what}; types and targeted specs belong to the op gate` : `the push gate checks the release gate and runs ${what}; only the release cut tests`));
+    if (pattern.test(body)) found.push(finding(file, name === 'pre-commit' ? `the commit gate is L0 only and runs ${what}; types and targeted specs belong to the op gate` : `the push gate runs ${what}; it must use the bundled push policy alone`));
   }
   if (name === 'pre-push') {
     const missing = PRE_PUSH_MARKERS.filter((marker) => !body.includes(marker));
     if (missing.length) {
       const markers = missing.map((m) => `\`${m}\``).join(', ');
-      found.push(finding(file, `the push gate lacks the release gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must check the L4 record of HEAD and allow only the release cut and refs/backup/*`));
+      found.push(finding(file, `the push gate lacks the bundled gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must invoke the shared fast-forward, annotation and secret-scan policy`));
     }
   }
   return found;

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/machine/home.mjs

@@ -49,7 +49,7 @@ export const STARTUP_RESERVATION_MS = 180_000;
 
 export const DEFAULTS = Object.freeze({
   workers: Object.freeze({ base: 0, max: 0, hardMax: 10 }),
-  landGate: Object.freeze({ mode: 'shared' }),
+  landGate: Object.freeze({ mode: 'shared', push: true }),
   frozenMinutes: 10,
   pollIntervalMs: 600_000,
 });
@@ -194,7 +194,7 @@ export function supervisorSettings({ config = undefined } = {}) {
     pollIntervalMs: Number.isInteger(sup.pollIntervalMs) ? sup.pollIntervalMs : DEFAULTS.pollIntervalMs,
     workers: { base: Number.isInteger(sup.workers?.base) ? sup.workers.base : DEFAULTS.workers.base,
       max: Math.min(DEFAULTS.workers.hardMax, Number.isInteger(sup.workers?.max) ? sup.workers.max : DEFAULTS.workers.max) },
-    landGate: { mode: sup.landGate?.mode === 'exclusive' ? 'exclusive' : DEFAULTS.landGate.mode },
+    landGate: { mode: sup.landGate?.mode === 'exclusive' ? 'exclusive' : DEFAULTS.landGate.mode, push: typeof sup.landGate?.push === 'boolean' ? sup.landGate.push : DEFAULTS.landGate.push },
     // supervisor-watchdog.mjs: a busy seat frame with no turn progress for this long is frozen, not busy.
     frozenMinutes: Number.isInteger(sup.frozenMinutes) && sup.frozenMinutes > 0 ? sup.frozenMinutes : DEFAULTS.frozenMinutes,
     language: typeof cfg?.language === 'string' ? cfg.language : DEFAULT_OWNER_LANGUAGE,

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -1,10 +1,10 @@
 {{header}}
 name: ci
 
-# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
+# CI judges main, release candidates and release tags.
 on:
   push:
-    branches: ["release/candidate-*"]
+    branches: ["main", "release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -1,10 +1,10 @@
 {{header}}
 name: ci
 
-# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
+# CI judges main, release candidates and release tags.
 on:
   push:
-    branches: ["release/candidate-*"]
+    branches: ["main", "release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 

package/templates/app/hooks/husky/pre-push

@@ -1,57 +1,4 @@
 {{header}}
-# Push gate: a release gate check, never a test run. Nothing but the release cut pushes main or a release tag, and the coordinator
-# backs work up under refs/backup/*. Git hands this hook one line per ref: <local ref> <local sha> <remote ref> <remote sha>.
-#   refs/backup/*                  allowed: the coordinator backup namespace
-#   refs/heads/main, refs/tags/v*  allowed only when HEAD carries an annotated tag v[0-9]* and the release cut recorded the
-#                                  full suite of HEAD: <git common dir>/starci-release/<HEAD sha>.l4.json names that head and tag;
-#                                  a pushed tag must be that tag and must point at HEAD
-#   refs/heads/release/candidate-* the release candidate (starci app release push sends the release sha there first and moves main
-#                                  and the tag only when its ci.yml run is green): allowed under the same release gate, never deleted
-#   any other ref, a delete        refused
-common=$(git rev-parse --git-common-dir)
-case "$common" in /* | [A-Za-z]:*) ;; *) common="$(pwd)/$common" ;; esac
-head=$(git rev-parse HEAD)
-record="$common/starci-release/$head.l4.json"
-status=0
-gate=""
-gate_tag=""
-refuse() {
-  echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main, v* tags and the release/candidate-* ref) or refs/backup/* (backups)" >&2
-  status=1
-}
-# gate: the verdict of the release gate for HEAD, computed once: "ok" or the reason it is closed.
-release_gate() {
-  if [ -n "$gate" ]; then return 0; fi
-  gate="no annotated tag v[0-9]* on HEAD $head"
-  tags=$(git tag --points-at HEAD --list 'v[0-9]*' 2>/dev/null) || { gate="cannot list the tags of HEAD $head"; return 0; }
-  for tag in $tags; do
-    kind=$(git cat-file -t "refs/tags/$tag" 2>/dev/null) || continue
-    if [ "$kind" != "tag" ]; then continue; fi
-    if [ ! -f "$record" ]; then gate="no L4 record $record"; continue; fi
-    flat=$(tr -d ' \t\r\n' < "$record")
-    case "$flat" in
-      *'"head":"'"$head"'"'*'"tag":"'"$tag"'"'* | *'"tag":"'"$tag"'"'*'"head":"'"$head"'"'*) gate="ok"; gate_tag="$tag"; return 0 ;;
-    esac
-    gate="the L4 record $record does not name head $head and tag $tag"
-  done
-  return 0
-}
-while read -r local_ref local_sha remote_ref remote_sha; do
-  case "$remote_ref" in
-    refs/backup/*) ;;
-    refs/heads/main | refs/tags/v* | refs/heads/release/candidate-*)
-      case "$local_sha" in
-        *[!0]*) ;;
-        *) refuse "refusing to delete $remote_ref"; continue ;;
-      esac
-      release_gate
-      if [ "$gate" != "ok" ]; then refuse "$remote_ref is closed: $gate"; continue; fi
-      case "$remote_ref" in
-        refs/tags/*)
-          if [ "$remote_ref" != "refs/tags/$gate_tag" ]; then refuse "$remote_ref is not the release tag $gate_tag of HEAD $head"
-          elif [ "$(git rev-parse "$local_sha^{commit}" 2>/dev/null)" != "$head" ]; then refuse "$remote_ref does not point at HEAD $head"; fi ;;
-      esac ;;
-    *) refuse "refusing to push $remote_ref" ;;
-  esac
-done
-exit "$status"
+# Push gate: fast-forward main with a clean secret scan, annotated v* tags, and bounded ref input.
+# The bundled gate owns the policy; backups and lane refs use the same policy as the runtime.
+node --input-type=module -e "import { main } from '@starci/hfs/runtime/scripts/guards/release-push-gate.mjs'; process.exit(await main());"

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 }
+}

package/runtime/scripts/api/fs/write-json-file.mjs

@@ -1,10 +0,0 @@
-// write-json-file.mjs - one JSON document written to a file (the runtime's pretty-printed state files).
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** `value` written to `file` as two-space JSON plus a trailing newline (parent directories created). */
-export function writeJsonFile(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}
-`);
-}

package/runtime/scripts/api/git/merge-base-query.mjs

@@ -1,5 +0,0 @@
-// merge-base-query.mjs — `git merge-base <args>`: one merge-base query (the best common ancestor, or --is-ancestor's exit status).
-import { runGit } from './lib.mjs';
-
-/** The spawn result {status, stdout, stderr, error} of `git merge-base ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
-export const mergeBaseQuery = (args = [], options = {}) => runGit(['merge-base', ...args], options);