@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/hfs/rules/edition.mjs

@@ -7,16 +7,22 @@
 //   - inside a package.json: an e2e, stack or browser script (`test:e2e`, `test:stack`, `test:browser`,
 //     with a pre/post prefix too) or a dependency of the infrastructure lite does not run - a test-world container or proxy
 //     (testcontainers, toxiproxy) or a browser runner (playwright, cypress), and every library the lite infraOwners own nowhere
-//     while full owns them (BullMQ, Kafka, Redis: lite runs pgmq and Postgres locks instead);
+//     while full owns them (Kafka: the lite event bus runs pgmq);
 //   - a declaration of what lite does not have: an app kind, pattern or trigger kind every slot of which is forbidden under
 //     lite. The forbidden names are DERIVED from the manifest, so adding or restoring a kind is a manifest edit, not an edit here
-//     (under the 2026-10-13 ruling no pattern, trigger or app kind is gone).
+//     (under the 2026-10-13 ruling no pattern, trigger or app kind is gone);
+//   - a backing service that is not declared or not used (ruling:R212/case-10): a client library of a service of
+//     ruleParams.be.backing (bullmq for redis) or a declared pattern that needs one (queue) while hfs.json sides.be.backing does
+//     not declare it is HFS_BACKING_UNDECLARED, as is a service the catalog's editions excludes (owner:lite-vector-is-pgvector),
+//     and a declared service no dependency of the app consumes is HFS_BACKING_UNUSED.
 // A full app answers []: the rule tests the edition once and a full view forbids none of these names.
 import { found, readJson } from './read.mjs';
 import { DEPENDENCY_SECTIONS } from './fe-no-tests.mjs';
-import { editionRuleParams } from '../edition-slots.mjs';
+import { editionRuleParams, judgedInEdition } from '../edition-slots.mjs';
 
 export const HFS_EDITION_FORBIDDEN_PRESENT = 'HFS_EDITION_FORBIDDEN_PRESENT';
+export const HFS_BACKING_UNDECLARED = 'HFS_BACKING_UNDECLARED';
+export const HFS_BACKING_UNUSED = 'HFS_BACKING_UNUSED';
 
 const PACKAGE_JSON = /(?:^|\/)package\.json$/;
 /** The scripts of a world lite does not have: the e2e layer, the self-hosted stack and the browser journey. */
@@ -54,8 +60,8 @@ function editionGone(resolver) {
 const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 
 /**
- * The specifiers a lite back end may import nowhere although full gives them an owner: the self-hosted infrastructure libraries
- * the lite infraOwners override removes (bullmq, kafkajs, ioredis, ...). Read from the two rule-parameter views, never listed here.
+ * The specifiers a lite back end may import nowhere although full gives them an owner: the infrastructure libraries the lite
+ * infraOwners override removes (kafkajs). Read from the two rule-parameter views, never listed here.
  */
 function liteRemovedLibraries(manifest) {
   const be = manifest?.ruleParams?.be;
@@ -72,24 +78,60 @@ function scriptFindings(rel, pkg) {
     .map((name) => found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} has script ${JSON.stringify(name)}: a lite app has unit specs, optional integration specs on the local Supabase stack and optional contract specs, never an e2e, stack or browser run`, { name }));
 }
 
-function dependencyFindings(rel, pkg, removed) {
+/** The backing services of the manifest (ruleParams.be.backing): name -> {clients, patterns, images, editions?}. */
+const backingCatalog = (manifest) => manifest?.ruleParams?.be?.backing ?? {};
+
+/** The backing service `name` is a client library of, or null. */
+const serviceOfClient = (catalog, name) => Object.keys(catalog).find((service) => catalog[service].clients.includes(name)) ?? null;
+
+/** The dependency names of a package.json, every section. */
+const dependencyNames = (pkg) => DEPENDENCY_SECTIONS.flatMap((section) => (isPlainObject(pkg?.[section]) ? Object.keys(pkg[section]) : []));
+
+function dependencyFindings(rel, pkg, { removed, catalog, declared }) {
   const findings = [];
   for (const section of DEPENDENCY_SECTIONS) {
     const deps = pkg[section];
     if (!isPlainObject(deps)) continue;
     for (const name of Object.keys(deps)) {
+      const service = serviceOfClient(catalog, name);
       if (LITE_FORBIDDEN_TEST_INFRA.test(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: a lite app runs no test containers, fault proxy or browser journey - its integration specs run against \`supabase start\``, { section, name }));
-      else if (removed.has(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: lite replaces backing infrastructure with Supabase - the pattern's port is implemented on Supabase (pgmq, Postgres locks)`, { section, name }));
+      else if (removed.has(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: lite runs no self-hosted Kafka - the event bus port is implemented on Supabase (pgmq) or in process`, { section, name }));
+      else if (service !== null && !judgedInEdition(catalog[service], 'lite')) findings.push(found(HFS_BACKING_UNDECLARED, rel, `${rel} ${section} has ${name}, a client of ${service}, which the lite edition does not admit: remove the dependency`, { section, name, service }));
+      else if (service !== null && !declared.has(service)) findings.push(found(HFS_BACKING_UNDECLARED, rel, `${rel} ${section} has ${name}, a client of ${service}, which hfs.json sides.be.backing does not declare: declare ${service} for the capability that needs it, or remove the dependency`, { section, name, service }));
     }
   }
   return findings;
 }
 
 /** The findings one package.json's scripts and dependencies produce under lite. */
-function packageFindings(repoRoot, rel, removed) {
+function packageFindings(repoRoot, rel, context) {
   const pkg = readJson(repoRoot, rel);
   if (!isPlainObject(pkg)) return [];
-  return [...scriptFindings(rel, pkg), ...dependencyFindings(rel, pkg, removed)];
+  return [...scriptFindings(rel, pkg), ...dependencyFindings(rel, pkg, context)];
+}
+
+/**
+ * The backing findings of the be declaration: a declared pattern whose service is undeclared, and (at the app root or a
+ * standalone back end, whose package.json carries the back end's dependencies) a declared service no dependency consumes.
+ */
+function backingFindings({ repoRoot, beView, catalog, ownsPackage }) {
+  const declared = new Set(beView.backing ?? []);
+  const findings = [];
+  for (const service of declared) {
+    if (catalog[service] && !judgedInEdition(catalog[service], 'lite')) findings.push(found(HFS_BACKING_UNDECLARED, 'hfs.json', `hfs.json sides.be.backing declares ${service}, which the lite edition does not admit: remove the declaration`, { service }));
+  }
+  for (const [service, entry] of Object.entries(catalog)) {
+    const needing = (beView.patterns ?? []).filter((pattern) => entry.patterns.includes(pattern));
+    if (needing.length && !declared.has(service)) findings.push(found(HFS_BACKING_UNDECLARED, 'hfs.json', `hfs.json declares the ${needing.join(', ')} pattern, which runs on ${service}: declare ${service} in sides.be.backing`, { service, patterns: needing }));
+  }
+  if (!ownsPackage) return findings;
+  const dependencies = new Set(dependencyNames(readJson(repoRoot, 'package.json')));
+  for (const service of declared) {
+    if (!judgedInEdition(catalog[service], 'lite')) continue;
+    const clients = catalog[service]?.clients ?? [];
+    if (!clients.some((name) => dependencies.has(name))) findings.push(found(HFS_BACKING_UNUSED, 'hfs.json', `hfs.json sides.be.backing declares ${service}, but no dependency consumes it (${clients.join(', ')}): remove the declaration, or add the capability that needs it`, { service }));
+  }
+  return findings;
 }
 
 const goneAppFindings = (repo, gone) => (repo.apps ?? [])
@@ -121,11 +163,13 @@ export function editionFindings({ repoRoot, files, repo, resolver, manifest, wit
   let beView = null;
   if (withDeclaration && repo.profile === 'app') beView = repo.sides?.be;
   else if (withDeclaration && repo.profile === 'be') beView = repo;
-  const findings = beView ? declarationFindings(beView, gone) : [];
-  const removed = liteRemovedLibraries(manifest);
+  const catalog = backingCatalog(manifest);
+  const findings = beView ? [...declarationFindings(beView, gone), ...backingFindings({ repoRoot, beView, catalog, ownsPackage: true })] : [];
+  const declared = new Set((repo.profile === 'app' ? repo.sides?.be?.backing : repo.backing) ?? []);
+  const context = { removed: liteRemovedLibraries(manifest), catalog, declared };
   for (const file of files) {
     if (file.includes('node_modules/') || !PACKAGE_JSON.test(file)) continue;
-    findings.push(...packageFindings(repoRoot, file, removed));
+    findings.push(...packageFindings(repoRoot, file, context));
   }
   return findings;
 }

package/runtime/scripts/hfs/rules/fe-contract-documents.mjs

@@ -11,6 +11,7 @@ import { byCodeUnit } from '../../lib/list.mjs';
 import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { isConstVariable, sourceLocation } from '../../lib/ts-ast.mjs';
+import { lexicalChecker } from '../../lib/ts-analysis.mjs';
 
 export const FE_GRAPHQL_CONTRACT = 'FE_GRAPHQL_CONTRACT';
 
@@ -61,16 +62,6 @@ function templateText(ts, node, checker, names, visiting = new Set()) {
   return text;
 }
 
-/** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
-function lexicalChecker(ts, source) {
-  const options = { noLib: true, noResolve: true, allowJs: true };
-  const host = ts.createCompilerHost(options);
-  host.getSourceFile = (file) => file === source.fileName ? source : undefined;
-  host.fileExists = () => false;
-  host.readFile = () => undefined;
-  return ts.createProgram([source.fileName], options, host).getTypeChecker();
-}
-
 /** Actual tagged-template AST nodes: comments, quoted examples and other template tags are not operations. */
 function gqlDocuments(ts, file, text) {
   const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);

package/runtime/scripts/hfs/rules/fe-stack.mjs

@@ -11,6 +11,7 @@ import { parseYaml } from '../../../engine/yaml.mjs';
 import { found, readJson } from './read.mjs';
 import { DEPENDENCY_SECTIONS } from './fe-no-tests.mjs';
 import { editionRuleParams } from '../edition-slots.mjs';
+import { globExpression } from '../../lib/glob.mjs';
 
 export const FE_STACK_FORBIDDEN = 'FE_STACK_FORBIDDEN';
 export const FE_STACK_UNLISTED = 'FE_STACK_UNLISTED';
@@ -21,18 +22,23 @@ const APP_ROOT_MANIFEST = 'package.json';
 
 let forbidden = null;
 
-/** name -> {concern, canonical} for every package a concern of the catalog forbids, read once. */
+/** Package-name patterns and their concern, canonical packages and guidance, read once. */
 function forbiddenPackages() {
   if (forbidden) return forbidden;
   const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
   if (catalog?.schema !== 'starci/fe-stack@1' || !Array.isArray(catalog.concerns)) throw new Error('knowledge/hfs/fe-stack.yaml is not a starci/fe-stack@1 catalog');
-  forbidden = new Map();
+  forbidden = [];
   for (const concern of catalog.concerns) {
-    for (const name of concern.forbids ?? []) forbidden.set(name, { concern: concern.id, canonical: concern.packages ?? [] });
+    for (const name of concern.forbids ?? []) forbidden.push({ matches: globExpression(name), concern: concern.id, canonical: concern.packages ?? [], why: concern.why });
   }
   return forbidden;
 }
 
+/** A forbidden package or npm scope is judged before the closed dependency catalog. */
+function forbiddingPackage(name) {
+  return forbiddenPackages().find(entry => entry.matches.test(name));
+}
+
 /**
  * The packages the back end owns (be infraOwners with at least one owner, full's view: a library lite removes is the edition rule's
  * finding, not a front-end one): a root dependency of the back end.
@@ -47,14 +53,13 @@ function backendOwned(manifest) {
 function manifestFindings(repoRoot, rel, skip) {
   const pkg = readJson(repoRoot, rel);
   if (!pkg || typeof pkg !== 'object') return [];
-  const catalog = forbiddenPackages();
   const findings = [];
   for (const section of DEPENDENCY_SECTIONS) {
     for (const name of Object.keys(pkg[section] ?? {})) {
-      const entry = catalog.get(name);
+      const entry = forbiddingPackage(name);
       if (!entry || skip.has(name)) continue;
       const canonical = entry.canonical.length ? entry.canonical.join(', ') : 'the canonical library of the concern';
-      findings.push(found(FE_STACK_FORBIDDEN, rel, `${rel} ${section} declares ${name}, which the front-end stack forbids for the ${entry.concern} concern (knowledge/hfs/fe-stack.yaml); use ${canonical} and delete ${name}`, { section, dependency: name, concern: entry.concern }));
+      findings.push(found(FE_STACK_FORBIDDEN, rel, `${rel} ${section} declares ${name}, which the front-end stack forbids for the ${entry.concern} concern (knowledge/hfs/fe-stack.yaml); use ${canonical} and delete ${name}. ${entry.why}`, { section, dependency: name, concern: entry.concern }));
     }
   }
   return findings;
@@ -98,7 +103,7 @@ function extraPackages(declaration) {
 function unlistedFindings(rel, pkg, allowed, extras, workspaces) {
   const findings = [];
   for (const section of DEPENDENCY_SECTIONS) for (const name of Object.keys(pkg?.[section] ?? {})) {
-    if (allowed.has(name) || extras.has(name) || workspaces.has(name) || forbiddenPackages().has(name)) continue;
+    if (allowed.has(name) || extras.has(name) || workspaces.has(name) || forbiddingPackage(name)) continue;
     findings.push(found(FE_STACK_UNLISTED, rel, `${rel} ${section} declares ${name}, absent from knowledge/hfs/fe-stack.yaml; add a canonical concern or declare sides.fe.extraPackages with its name and a nonempty reason in hfs.json`, { section, dependency: name }));
   }
   return findings;

package/runtime/scripts/hfs/rules/lite-proof-lane.mjs

@@ -11,7 +11,7 @@ const LITE_PROOF_LANE_MISSING = 'BE_LITE_PROOF_LANE_MISSING';
 const PATTERN_SPEC_MISSING = 'BE_PATTERN_SPEC_MISSING';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const INTEGRATION_SPEC = /^be\/src\/tests\/integration\/.+\.integration-spec\.ts$/;
-const PATTERNS = new Set(['event-bus', 'queue', 'webhooks', 'realtime', 'fenced-job', 'projection', 'saga']);
+const PATTERNS = new Set(['logging', 'event-bus', 'queue', 'webhooks', 'realtime', 'fenced-job', 'projection', 'saga', 'idempotency']);
 // Fallback saga scenarios until the shared manifest provides its scenario table.
 const SAGA_SCENARIOS = ['compensation-on-failure', 'step-order', 'state-version-fences', 'consumer-dedupes'];
 

package/runtime/scripts/hfs/rules/stacks-lite-backing.mjs

@@ -1,10 +1,20 @@
-// R276: lite uses managed Supabase backing; sidecar SQLite persists on declared named volumes.
+// R276: lite keeps Postgres and pgvector on managed Supabase, admits only the backing services available to its edition,
+// and runs a declared Redis as one service with AOF fsynced at least every second on a named volume and no eviction
+// (ruling:R212/case-10, owner:lite-vector-is-pgvector); sidecar SQLite persists on declared named volumes.
 import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
 import { composeEntries } from '../../lib/compose-values.mjs';
 import { repositoryOf } from '../../lib/stack-services.mjs';
+import { loadSlotManifest } from '../slots.mjs';
+import { judgedInEdition } from '../edition-slots.mjs';
+import { readJson } from './read.mjs';
 import { stacksDeploymentFindings } from './stacks-runtime.mjs';
 
-const BACKING_IMAGE = /^(?:postgres(?:ql)?|postgresql-repmgr|redis(?:-stack(?:-server)?)?|mongo(?:db)?|mongodb-community-server)$/i;
+const DATABASE_IMAGE = /^(?:postgres(?:ql)?|postgresql-repmgr|mongo(?:db)?|mongodb-community-server)$/i;
+const APPEND_ONLY = /(?:^|\s)--appendonly\s+yes(?:\s|$)/;
+const EVICTION_POLICY = /(?:^|\s)--maxmemory-policy\s+(\S+)/;
+const FSYNC_POLICY = /(?:^|\s)--appendfsync\s+(\S+)/;
+const BOUNDED_FSYNC = new Set(['everysec', 'always']);
+const REDIS_DATA_DIR = '/data';
 const DATABASE_ADAPTER_KEYS = new Set(['db_type', 'database_type', 'db_provider', 'database_provider', 'db_client', 'database_client', 'db_adapter', 'database_adapter']);
 const SQLITE_ADAPTERS = new Set(['sqlite', 'sqlite3', 'better-sqlite3', 'sql.js']);
 const DATABASE_URL_KEY = /DB|DATABASE|POSTGRES|REDIS|MONGO/i;
@@ -14,18 +24,72 @@ const NAMED_VOLUME = /^[a-z0-9][a-z0-9_.-]*$/i;
 const mapping = value => plain(value) ? value : {};
 const present = value => typeof value === 'string' && Boolean(value.trim());
 
-function imageIssues(components, services) {
+/** The backing service (a key of ruleParams.be.backing) whose image repository `image` names, or null. */
+function serviceOfImage(catalog, image) {
+  if (!present(image)) return null;
+  const repository = repositoryOf(image).toLowerCase();
+  return Object.keys(catalog).find(service => catalog[service].images.includes(repository)) ?? null;
+}
+
+/** The services hfs.json sides.be.backing declares: from the resolved declaration, else from hfs.json at the app root. */
+function declaredBacking(repo, repoRoot) {
+  const declared = repo?.sides?.be?.backing ?? repo?.backing ?? (present(repoRoot) ? readJson(repoRoot, 'hfs.json')?.sides?.be?.backing : undefined);
+  return new Set(Array.isArray(declared) ? declared : []);
+}
+
+function imageIssues(components, services, { catalog, declared }) {
   const errors = [];
   for (const [prefix, inventory] of [['components', components], ['services', services]]) {
     for (const [id, entry] of Object.entries(inventory)) {
-      if (present(entry?.image) && BACKING_IMAGE.test(repositoryOf(entry.image)))
+      if (!present(entry?.image)) continue;
+      const service = serviceOfImage(catalog, entry.image);
+      if (DATABASE_IMAGE.test(repositoryOf(entry.image)))
         errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
-          message: 'lite must not run a self-hosted Postgres, Redis or Mongo database image; use managed Supabase backing' });
+          message: 'lite must not run a self-hosted Postgres or Mongo database image; use managed Supabase backing' });
+      else if (service !== null && !judgedInEdition(catalog[service], 'lite'))
+        errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
+          message: `lite must not run ${service}; vector search uses Supabase pgvector (owner:lite-vector-is-pgvector)` });
+      else if (service !== null && !declared.has(service))
+        errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
+          message: `lite runs ${service} only when hfs.json sides.be.backing declares it for the capability that needs it (ruling:R212/case-10)` });
     }
   }
   return errors;
 }
 
+const commandText = service => (Array.isArray(service?.command) ? service.command.map(String).join(' ') : String(service?.command ?? ''));
+
+function persistentDataMount(entry, volumes) {
+  if (typeof entry === 'string') {
+    const [name, target, options = ''] = entry.split(':');
+    return NAMED_VOLUME.test(name) && Object.hasOwn(volumes, name) && target === REDIS_DATA_DIR && !options.split(',').includes('ro');
+  }
+  return plain(entry) && entry.type === 'volume' && Object.hasOwn(volumes, entry.source) && entry.target === REDIS_DATA_DIR && entry.read_only !== true;
+}
+
+/**
+ * AOF on a writable named volume at the data directory, fsynced at least every second (everysec, the Redis default, or always),
+ * and no eviction policy but noeviction (the Redis default).
+ */
+function persisted(service, volumes) {
+  const command = commandText(service);
+  const policy = EVICTION_POLICY.exec(command)?.[1].replaceAll(/["']/g, '');
+  const fsync = FSYNC_POLICY.exec(command)?.[1].replaceAll(/["']/g, '');
+  return APPEND_ONLY.test(command) && (policy === undefined || policy === 'noeviction') && (fsync === undefined || BOUNDED_FSYNC.has(fsync))
+    && (Array.isArray(service.volumes) ? service.volumes : []).some(entry => persistentDataMount(entry, volumes));
+}
+
+/** Queue jobs live in Redis, so a declared Redis runs as exactly one stack service that persists every job and evicts none. */
+function redisPersistenceIssues(services, volumes, { catalog, declared }) {
+  if (!declared.has('redis')) return [];
+  const redis = Object.entries(services).filter(([, service]) => serviceOfImage(catalog, service?.image) === 'redis');
+  if (redis.length !== 1) return [{ code: 'STACKS_LITE_REDIS_PERSISTENCE', at: 'services',
+    message: `hfs.json sides.be.backing declares redis, so the lite stack runs exactly one Redis service; it runs ${redis.length}` }];
+  return redis.filter(([, service]) => !persisted(service, volumes))
+    .map(([id]) => ({ code: 'STACKS_LITE_REDIS_PERSISTENCE', at: `services.${id}`,
+      message: `the lite Redis runs redis-server --appendonly yes with appendfsync everysec (the default) or always, a writable named volume mounted at ${REDIS_DATA_DIR} and maxmemory-policy noeviction (the default), so queue jobs survive a restart and are never evicted` }));
+}
+
 function unsupportedAdapter(service) {
   for (const [key, value] of composeEntries(service?.environment, { stringsOnly: true })) {
     const adapterKey = DATABASE_ADAPTER_KEYS.has(key.toLowerCase());
@@ -94,13 +158,15 @@ function sidecarIssues({ components, services, bindings, volumes }) {
 }
 
 /** The lite backing contract; full keeps its existing backing choices. */
-export function liteBackingIssues({ doc, environment, spec = doc?.environments?.[environment], model, repo, edition = repo?.edition }) {
+export function liteBackingIssues({ doc, environment, spec = doc?.environments?.[environment], model, repo, repoRoot, edition = repo?.edition }) {
   if (edition !== 'lite' || spec?.runtime !== 'docker-swarm') return [];
-  const components = mapping(doc?.components), services = mapping(model?.services);
+  const components = mapping(doc?.components), services = mapping(model?.services), volumes = mapping(model?.volumes);
+  const backing = { catalog: mapping(loadSlotManifest().ruleParams?.be?.backing), declared: declaredBacking(repo, repoRoot) };
   return [
-    ...imageIssues(components, services),
+    ...imageIssues(components, services, backing),
+    ...redisPersistenceIssues(services, volumes, backing),
     ...renderedAdapterIssues(components, services),
-    ...sidecarIssues({ components, services, bindings: mapping(spec.components), volumes: mapping(model?.volumes) }),
+    ...sidecarIssues({ components, services, bindings: mapping(spec.components), volumes }),
   ];
 }
 

package/runtime/scripts/hfs/rules/stacks-runtime.mjs

@@ -23,7 +23,7 @@ export function hostCrontabFindings({ repoRoot, files }) {
     if (text === null) continue;
     for (const [index, line] of text.split(/\r?\n/).entries()) {
       if (HOST_CRON.test(line)) findings.push(found(CODE, file,
-        `${file}:${index + 1}: host crontab installation is forbidden; recurring work must use an app scheduler, pgmq/pg_cron, or a declared Swarm scheduler and replicated-job`, { line: index + 1 }));
+        `${file}:${index + 1}: host crontab installation is forbidden; recurring work must use an app queue scheduler, a pg_cron tick enqueueing through the queue outbox, or a declared Swarm scheduler and replicated-job`, { line: index + 1 }));
     }
   }
   return findings;

package/runtime/scripts/hfs/rules/stacks-swarm.mjs

@@ -381,14 +381,25 @@ function appComposesRealtime(repoRoot, app, files) {
   return false;
 }
 
+const SHARED_HUBS = new Set(['postgres', 'redis']);
+
+/** The hub a service selects with REALTIME_HUB, or null when it declares none. */
+function realtimeHub(service) {
+  const entry = composeEntries(service.environment, { missingValue: null }).find(([key]) => key === 'REALTIME_HUB');
+  return entry && present(entry[1]) ? String(entry[1]).trim() : null;
+}
+
+/** A service runs on several nodes: more than one replica, or the global mode (one task per node). */
+const scaledOut = service => service.deploy?.mode === 'global' || Number(service.deploy?.replicas ?? 1) > 1;
+
+/** Realtime scale (knowledge/patterns/be/realtime.yaml BE-REALTIME-7): an API with several replicas selects a shared hub. */
 function realtimeIssues(input, add) {
-  if (input.repo?.edition !== 'lite') return;
   const apis = new Set(list(input.repo?.sides?.be?.apps).filter(app => app.kind === 'api').map(app => app.name));
   for (const [id, service] of Object.entries(mapping(input.model.services))) {
     const component = mapping(input.doc.components)[id], app = component?.app ?? id;
-    if (!apis.has(app) || service.deploy?.replicas === 1) continue;
-    if (appComposesRealtime(input.repoRoot, app, list(input.files)))
-      add('STACKS_REALTIME_SCALED', `services.${id}.deploy.replicas`, 'A lite API composing realtime must pin deploy.replicas: 1 because its realtime hub and gateway live in one API process');
+    if (!apis.has(app) || !scaledOut(service) || !appComposesRealtime(input.repoRoot, app, list(input.files))) continue;
+    if (!SHARED_HUBS.has(realtimeHub(service) ?? ''))
+      add('STACKS_REALTIME_SCALED', `services.${id}.environment.REALTIME_HUB`, 'A realtime API with more than one replica must select a shared hub (REALTIME_HUB postgres or redis): the memory hub serves one process only');
   }
 }
 

package/runtime/scripts/hfs/rules/text-integrity.mjs

@@ -0,0 +1,73 @@
+// R311: the Vietnamese copy of an app reaches users as written. A message catalog (`<owner>.messages.ts` or a `vi.json` locale file)
+// is valid UTF-8, and no `vi` string carries the mark of a lossy re-encode: a diacritic letter replaced by a literal `?`
+// (so a word reads as letters around a question mark) or by the U+FFFD replacement character.
+import { found, readText } from './read.mjs';
+
+export const HFS_TEXT_CORRUPT = 'HFS_TEXT_CORRUPT';
+const CATALOG_TS_SUFFIX = '.messages.ts';
+const CATALOG_JSON = /(?:^|\/)vi\.json$/;
+const OUTSIDE = /(?:^|\/)(?:node_modules|\.git|dist|build)\//;
+const REPLACEMENT = '\uFFFD';
+// A `?` between letters, doubled, or closing a word before punctuation is a lost diacritic; a sentence-final "?" and a lone "?" are not.
+const LOST_LETTER = /\p{L}\?(?=[\p{L}?])|\?\?|\p{L}\?(?=[.,;:)])|(?:^|[\s("])\?\p{L}/u;
+const STRING_LITERAL = /"((?:[^"\\\n]|\\.)*)"/g;
+
+function lineOf(text, index) {
+  return text.slice(0, index).split('\n').length;
+}
+
+// The text of the `vi:` map of a catalog bundle: from `vi:` to the first closing brace at the bundle's own indent.
+function viBlocks(text) {
+  const blocks = [];
+  for (const start of text.matchAll(/\bvi:\s*\{/g)) {
+    const from = start.index + start[0].length;
+    const end = text.indexOf('\n    }', from);
+    blocks.push({ from, to: end < 0 ? text.length : end });
+  }
+  return blocks;
+}
+
+function jsonStrings(node, out) {
+  if (typeof node === 'string') out.push(node);
+  else if (node && typeof node === 'object') for (const value of Object.values(node)) jsonStrings(value, out);
+}
+
+function corruptLine(file, line, value) {
+  return found(HFS_TEXT_CORRUPT, file, `${file}:${line} Vietnamese text ${JSON.stringify(value)} lost its diacritics (a "?" or U+FFFD stands for a letter); rewrite the file as UTF-8 with an editor or Node, never a shell pipe`, { line });
+}
+
+function tsFindings(file, text) {
+  const findings = [];
+  for (const { from, to } of viBlocks(text)) {
+    for (const literal of text.slice(from, to).matchAll(STRING_LITERAL)) {
+      if (LOST_LETTER.test(literal[1])) findings.push(corruptLine(file, lineOf(text, from + literal.index), literal[1]));
+    }
+  }
+  return findings;
+}
+
+function jsonFindings(file, text) {
+  let doc;
+  try { doc = JSON.parse(text); } catch { return []; }
+  const strings = [];
+  jsonStrings(doc, strings);
+  return strings.filter((value) => LOST_LETTER.test(value)).map((value) => corruptLine(file, lineOf(text, text.indexOf(value)), value));
+}
+
+/** Corrupted Vietnamese copy in the message catalogs of this root/side scope. */
+export function textIntegrityFindings({ repoRoot, files, repo, inScope = () => true }) {
+  if (repo.kind === 'runtime' || !['lite', 'full'].includes(repo.edition ?? 'full')) return [];
+  const findings = [];
+  for (const file of files) {
+    const ts = file.endsWith(CATALOG_TS_SUFFIX);
+    if (!inScope(file) || OUTSIDE.test(file) || !(ts || CATALOG_JSON.test(file))) continue;
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    if (text.includes(REPLACEMENT)) {
+      findings.push(found(HFS_TEXT_CORRUPT, file, `${file}:${lineOf(text, text.indexOf(REPLACEMENT))} is not valid UTF-8 (it holds U+FFFD); rewrite the file as UTF-8 with an editor or Node`, { line: lineOf(text, text.indexOf(REPLACEMENT)) }));
+      continue;
+    }
+    findings.push(...(ts ? tsFindings(file, text) : jsonFindings(file, text)));
+  }
+  return findings;
+}

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

@@ -0,0 +1,74 @@
+// 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.
+// 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';
+import { HOOK_INPUT_LIMITS } from '../../lib/hook-limits.mjs';
+
+export const CODE = 'RT_HOOK_SHAPE';
+export const TEMPLATE_DIR = 'packages/hfs/templates/app/hooks/husky';
+const PRE_COMMIT = `${TEMPLATE_DIR}/pre-commit`;
+const PRE_PUSH = `${TEMPLATE_DIR}/pre-push`;
+const HOST_SETTINGS = '.claude/settings.json';
+const GUARD_LIMITS = 'modules/kernel/hook-input.yaml';
+
+const PRE_COMMIT_FORBIDDEN = [
+  [/\btypecheck\b/, 'a typecheck'],
+  [/\btest:|\bnpm\s+(?:run\s+)?test\b|\bjest\b|\bvitest\b|\bspecs?\b/, 'a test run'],
+];
+const PRE_PUSH_FORBIDDEN = [
+  [/\bnpm\s+(?:run\s+)?test\b|\btest:|\bjest\b|\bvitest\b/, 'a test run'],
+  [/\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 finding = (file, message) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${message}` });
+
+/** The RT_HOOK_SHAPE findings of one hook template: `name` is 'pre-commit' or 'pre-push', `text` its content. */
+function fileHookShapeFindings({ path: file, name, text }) {
+  const body = shellCommandSource(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 (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/*`));
+    }
+  }
+  return found;
+}
+
+/** Guard hooks finish inside the host timeout even when input, verdict, tree cleanup and both writes exhaust their budgets. */
+function guardTimeoutFindings(ctx) {
+  if (!ctx.fileSet.has(HOST_SETTINGS)) return [];
+  const limits = HOOK_INPUT_LIMITS;
+  const budget = limits.minInputWindowMs + limits.verdictTimeoutMs + limits.teardownTimeoutMs + 2 * limits.outputTimeoutMs;
+  const found = budget < limits.hookTimeoutSeconds * 1000 ? [] : [finding(GUARD_LIMITS, 'the complete guard lifetime must be shorter than the host hook timeout')];
+  let settings;
+  try { settings = JSON.parse(ctx.read(HOST_SETTINGS)); }
+  catch { return [...found, finding(HOST_SETTINGS, 'the guard hook settings must be readable JSON')]; }
+  const hooks = (settings?.hooks?.PreToolUse ?? []).flatMap((entry) => entry.hooks ?? []);
+  for (const hook of hooks) {
+    if (!/\bguard\s+(?:command|seat-tools)\b/.test(String(hook.command ?? ''))) continue;
+    if (hook.timeout !== limits.hookTimeoutSeconds) found.push(finding(HOST_SETTINGS, `the guard hook timeout must match ${GUARD_LIMITS} hookTimeoutSeconds`));
+  }
+  return found;
+}
+
+/** RT_HOOK_SHAPE over the app hook templates and tracked host guard settings (ctx of scripts/hfs/runtime-check.mjs). */
+export function hookShapeFindings(ctx) {
+  return [...guardTimeoutFindings(ctx), ...[['pre-commit', PRE_COMMIT], ['pre-push', PRE_PUSH]].flatMap(([name, file]) => {
+    if (!ctx.fileSet.has(file)) return [];
+    const text = ctx.read(file);
+    return text === null || text === undefined ? [] : fileHookShapeFindings({ path: file, name, text });
+  })];
+}

package/runtime/scripts/hfs/runtime-rules/release-notes.mjs

@@ -0,0 +1,44 @@
+// release-notes.mjs - RELEASE_NOTES (knowledge/hfs/rules.yaml, gate runtime): a release tag `v<version>` on HEAD has its CHANGELOG.md section
+// `## [<version>]` with no unfinished markers left in it and no `in preparation` mark. The tag message and the GitHub Release are that section
+// (docs/git-governance.md), so a tag cut over an unfinished section would publish a half-written release. Only the tags that point at HEAD are
+// judged: the release being cut. Pure apart from ctx.read and the git read (ctx.tagsAtHead overrides it).
+import { tag } from '../../api/git/tag.mjs';
+
+export const CODE = 'RELEASE_NOTES';
+const RELEASE_TAG = /^v\d[\w.+-]*$/;
+const UNFINISHED = /\b(?:TODO|PENDING|TBD)\b|in preparation/i;
+
+/** The CHANGELOG section of `version`: {found, body}. Pure. */
+export function changelogSection(changelog, version) {
+  const lines = String(changelog ?? '').split(/\r?\n/);
+  const start = lines.findIndex((line) => { const m = /^## \[([^\]]+)\]/.exec(line); return m && m[1] === version; });
+  if (start < 0) return { found: false, body: '' };
+  const end = lines.findIndex((line, i) => i > start && line.startsWith('## ['));
+  return { found: true, body: lines.slice(start, end < 0 ? undefined : end).join('\n') };
+}
+
+/** The RELEASE_NOTES findings of the release tags `tags` against `changelog` text. Pure. */
+export function releaseNotesFindings({ tags, changelog, file = 'CHANGELOG.md' }) {
+  const found = [];
+  for (const name of tags.filter((t) => RELEASE_TAG.test(t))) {
+    const section = changelogSection(changelog, name.slice(1));
+    if (!section.found) { found.push({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: the release tag ${name} has no \`## [${name.slice(1)}]\` section: write the release notes before the tag` }); continue; }
+    const unfinished = new RegExp(UNFINISHED.source, 'gi');
+    const marks = [...new Set([...section.body.matchAll(unfinished)].map(([mark]) => mark))];
+    if (marks.length) {
+      const listedMarks = marks.map((m) => `\`${m}\``).join(', ');
+      found.push({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: the section of ${name} still holds ${listedMarks}: finish it before the tag` });
+    }
+  }
+  return found;
+}
+
+/** RELEASE_NOTES over the checkout (ctx of scripts/hfs/runtime-check.mjs): the release tags at HEAD against the CHANGELOG at HEAD. */
+export function releaseNotesRepoFindings(ctx) {
+  let tags = ctx.tagsAtHead;
+  if (!tags) {
+    try { const r = tag(['--points-at', 'HEAD'], { dir: ctx.repoRoot }); tags = r.status === 0 ? String(r.stdout).split(/\r?\n/).map((t) => t.trim()).filter(Boolean) : []; } catch { tags = []; }
+  }
+  const changelog = ctx.read('CHANGELOG.md');
+  return tags.some((t) => RELEASE_TAG.test(t)) ? releaseNotesFindings({ tags, changelog }) : [];
+}

package/runtime/scripts/hfs/sealed-members.mjs

@@ -80,10 +80,10 @@ function placeholderValue(key) {
   return generated;
 }
 
-/** Create missing members for this app's recipient, preserving owner-provisioned members. */
-export function materializeDeclaredPlaceholders(repoRoot, { recipient, recipientsForFile, processEnv = process.env, sops, write } = {}) {
+/** Create missing members (those `only` selects) for this app's recipient, preserving owner-provisioned members. */
+export function materializeDeclaredPlaceholders(repoRoot, { recipient, recipientsForFile, processEnv = process.env, sops, write, only = () => true } = {}) {
   const members = [];
-  for (const member of declaredSealedMembers(repoRoot)) {
+  for (const member of declaredSealedMembers(repoRoot).filter((declared) => only(declared))) {
     const relative = `.starcistacks/${member.env}/secrets/${member.slug}.enc`;
     if (fs.existsSync(path.join(repoRoot, relative))) continue;
     const age = recipientsForFile?.(path.join(repoRoot, relative)) ?? [recipient];

package/runtime/scripts/hfs/slot-side-problems.mjs

@@ -1,5 +1,5 @@
 // slot-side-problems.mjs - declaration checks for one app side against the HFS manifest.
-import { optionalSlotProblems } from './declaration-slots.mjs';
+import { backingProblems, optionalSlotProblems } from './declaration-slots.mjs';
 
 function sideAppKindProblems(manifest, side, apps) {
   const bad = [];
@@ -19,9 +19,9 @@ function requiredAppKindProblems(manifest, side, declaration) {
 }
 
 /** Problems for one side declaration, preserving the manifest's checks and their order. */
-export function sideProblems(manifest, side, declaration) {
+export function sideProblems(manifest, side, declaration, edition = 'full') {
   const bad = sideAppKindProblems(manifest, side, declaration.apps);
-  bad.push(...optionalSlotProblems(manifest, side, declaration));
+  bad.push(...optionalSlotProblems(manifest, side, declaration), ...backingProblems(manifest, side, declaration, edition));
   for (const read of declaration.reads ?? []) if (!manifest.sides[side].reads.includes(read)) bad.push(`sides.${side}.reads names ${read}; ${side} may read only ${manifest.sides[side].reads.join(', ') || 'nothing of the other side'}`);
   bad.push(...requiredAppKindProblems(manifest, side, declaration));
   return bad;

package/runtime/scripts/hfs/slots.mjs

@@ -116,6 +116,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
     apps: Object.freeze(s.apps.map((a) => Object.freeze({ name: a.name, kind: a.kind }))),
     optionalSlots: Object.freeze([...(s.optionalSlots ?? [])]),
     patterns: Object.freeze([...(s.patterns ?? [])]), kinds: Object.freeze([...(s.kinds ?? [])]),
+    backing: Object.freeze([...(s.backing ?? [])]),
     connections: Object.freeze((s.connections ?? []).map(connectionView)),
     providers,
     reads: Object.freeze([...(s.reads ?? [])]),
@@ -139,7 +140,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
   if (declaration.kind === RUNTIME_KIND) return runtimeDeclaration(manifest, declaration, file, side);
   const { edition, known, valid } = declarationEdition(manifest, declaration);
   if (!valid) fail('HFS_EDITION_INVALID', `hfs.json edition is ${JSON.stringify(declaration.edition)}; the editions this manifest knows are ${known.join(', ')} (absent means full)`, { file, edition: declaration.edition });
-  const bad = PROFILES.flatMap((name) => sideProblems(manifest, name, declaration.sides[name]));
+  const bad = PROFILES.flatMap((name) => sideProblems(manifest, name, declaration.sides[name], edition));
   if (bad.length) declarationInvalid(bad, file);
   if (side !== null && !PROFILES.includes(side)) fail('HFS_DECLARATION_INVALID', `${side} is not a side of an app (be, fe)`, { file, side });
   // A provider declared on any connection enables the provider slots of every profile (a fe side declares none): each view carries the union.