@starci/hfs 4.9.9 → 4.9.11

package/runtime/knowledge/hfs/rules.yaml

@@ -1820,7 +1820,7 @@ rules:
       - {path: packages/eslint/be/be-r89-source-form-coverage.spec.mjs, edition: full, codes: [BE_SOURCE_FORM, BE_PUBLIC_CONTRACT_FORM]}
   - id: R90
     code: "BE_INFRA_OWNER"
-    law: "Each raw infrastructure library (HTTP, cache, queue, scheduler, logger, date, config, events) is imported or referenced only by its one owning platform or integration capability, and the `HttpClient` port of `platform/http` is called only by an `integrations` capability."
+    law: "Each raw infrastructure library (HTTP, cache, queue, scheduler, logger, date, config, events, model SDKs) is imported or referenced only by its one owning platform or integration capability, and the `HttpClient` port of `platform/http` is called only by an `integrations` capability."
     kinds: [lint, codemod]
     failureCodes: ["BE_INFRA_OWNER"]
     enforcers:
@@ -4716,10 +4716,10 @@ rules:
       - {path: packages/hfs/src/hfs-release-provenance.spec.mjs, edition: full}
   - id: R272
     code: "BE_APP_BOOT_PROOF_MISSING"
-    law: "Every lite back-end app proves its real Nest AppModule composition by compiling the dependency graph with explicit fixture options and infrastructure doubles; unresolved providers, circular dependencies and a missing or failed proof are refused. The app check wiring verb uses the same proof. Full retains its existing e2e boot proof."
+    law: "Every lite back-end app proves its real Nest AppModule composition by compiling the dependency graph with explicit fixture options and infrastructure doubles; unresolved providers, circular dependencies and a missing or failed proof are refused. The proof worker runs within its own budget from its spawn and is retried once when it runs out; a second timeout reaches no verdict and is reported as BOOT_PROOF_TIMEOUT, a warning, never as a failed proof. The app check wiring verb uses the same proof. Full retains its existing e2e boot proof."
     kinds: [check]
     gates: ["settle","land","ci"]
-    failureCodes: ["BE_APP_BOOT_PROOF_MISSING"]
+    failureCodes: ["BE_APP_BOOT_PROOF_MISSING", "BOOT_PROOF_TIMEOUT"]
     enforcers:
       - {kind: hfs, id: boot-proof, at: scripts/hfs/rules/boot-proof.mjs}
     editions: ["lite"]
@@ -5756,3 +5756,74 @@ rules:
         source: owner
         quote: "ok trò"
         ruling: "A route page is one Grammar Page (owner ruling page-frame): the single owner of the page inset and rhythm; the lint refuses a sibling beside the Page and a bare PageHeader or PageContainer in a page owner."
+  - id: R326
+    code: "BE_AI_KEY_CUSTODY"
+    law: "An upstream model provider key variable (OPENROUTER_API_KEY, OPENAI_API_KEY and the rest of the canon's one list) is named only inside the ai-router gateway's custody owner integrations/ai-gateway, in a literal, a member or a destructured property; every other file reaches a model through the gateway with a virtual key."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["BE_AI_KEY_CUSTODY"]
+    enforcers:
+      - {kind: eslint-be, id: provider-key-custody}
+    editions: [lite, full]
+    docs: [contexts/code/be/ai.md]
+    templateNa: "The skeleton scaffolds no model call; an app adds the ai and ai-gateway integrations when it calls a model."
+    proves:
+      - packages/eslint-canon-be/src/ai-gateway.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_KEY_CUSTODY]}
+    witness:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_KEY_CUSTODY]}
+    cases:
+      - id: case-1
+        date: "2026-10-29"
+        source: owner
+        quote: "nhớ làm langchain nhé update .claude lun là call thẳng từ code phải dùng langchain với embeded context"
+        ruling: "A model call made straight from code uses LangChain with retrieved context, through the ai-router gateway (owner ruling be-ai-langchain-gateway): only the gateway's custody owner reads a provider key."
+  - id: R327
+    code: "BE_AI_GATEWAY_CLIENT"
+    law: "Code builds only the ChatOpenAI and OpenAIEmbeddings clients of @langchain/openai, each from an inline options object with no spread, its configuration.baseURL read from a <c>.options.ts type and its apiKey the reveal() of a platform/config Secret, so every model call goes through the ai-router gateway with a virtual key."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["BE_AI_GATEWAY_CLIENT"]
+    enforcers:
+      - {kind: eslint-be, id: ai-client-through-gateway}
+    editions: [lite, full]
+    docs: [contexts/code/be/ai.md]
+    templateNa: "The skeleton scaffolds no model call; an app adds the ai and ai-gateway integrations when it calls a model."
+    proves:
+      - packages/eslint-canon-be/src/ai-gateway.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_GATEWAY_CLIENT]}
+    witness:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_GATEWAY_CLIENT]}
+    cases:
+      - id: case-1
+        date: "2026-10-29"
+        source: owner
+        quote: "nhớ làm langchain nhé update .claude lun là call thẳng từ code phải dùng langchain với embeded context"
+        ruling: "A model call made straight from code uses LangChain with retrieved context, through the ai-router gateway (owner ruling be-ai-langchain-gateway): the LangChain clients point at the gateway's base URL with its virtual key."
+  - id: R333
+    code: "BE_ENTITY_SCHEMA_DRIFT"
+    law: "Every TypeORM entity column of an app's entity list (be/src/platform/database/entities.ts) matches the schema its SQL migrations build: `starci app db drift` applies db/bootstrap.sql and every active db/migrations/*.sql to a scratch database (a container of the app's db image, or the empty database --url-env names), reads information_schema.columns and pg_catalog, and refuses a missing table, a missing column, a type that differs once both are normalised to PostgreSQL's format_type names (an enum by its type name), and a nullability that differs. A database column no entity maps is fine. A host that cannot provide the scratch database gets no verdict (exit 2, needs a database), never a green."
+    kinds: [check]
+    gates: [ci]
+    failureCodes: ["BE_ENTITY_SCHEMA_DRIFT"]
+    enforcers:
+      - {kind: hfs, id: db-drift, at: packages/hfs/db/drift.mjs}
+    editions: [lite]
+    editionWhy: "The owner ruling of 2026-10-29 maps lite tables with TypeORM entities while db/migrations/*.sql stays the only DDL and synchronize is false, so only lite entities can drift from a schema they do not create; full entities ship with their own TypeORM migrations."
+    docs: [contexts/code/be/persistence.md]
+    templateNa: "The entities and the migrations are the product's tables; the check judges whichever an app writes, and a template scaffolds no table."
+    proves:
+      - {path: packages/hfs/src/db-drift.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
+      - {path: packages/hfs/src/db-drift-docker.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
+    exemplifiedBy:
+      - {path: packages/hfs/src/db-drift.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
+    witness:
+      - {path: packages/hfs/src/db-drift.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
+    cases:
+      - id: case-1
+        date: "2026-10-29"
+        source: owner
+        quote: "lite persistence moves to TypeORM entities while db/migrations/*.sql stays the only DDL and synchronize is false"
+        ruling: "Lite entities only map tables the migrations create, so each entity column is checked against the migrated schema by starci app db drift, which CI runs in the build job and the release gate runs as its db-drift row."

package/runtime/knowledge/hfs/slots.yaml

@@ -7,7 +7,7 @@
 # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
 # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
 schema: starci/hfs-slots@3
-version: 3.7.0
+version: 3.8.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -45,6 +45,8 @@ versioning:
 # 2026-10-24: lite may serve SSE, and SSE is the default door for one-way push), and lets fe.modules.api hold the SSE stream operations (sse/).
 # 3.7.0 is a minor (alpha.31): it ADDS the optional app.scripts.integration slot (scripts/integration/*.mjs, the product test-support scripts that only the integration harness runs) and the optional fe.transport.stream slot, the fetch reader of server-sent-events streams (the stream half of the
 # transport client layer), and lets fe.hooks.swr hold the SWR subscription hooks (api/sse/subscriptions/useSubscribe<X>Swr.ts, one useSWRSubscription per stream operation).
+# 3.8.0 is a minor (urgent release, 2026-10-29): it ADDS the optional fe.dev-server-generated slot (apps/*/AGENTS.md, which `next dev` rewrites) and the
+# slot field rewrittenBy, so the release gate's clean-tree check passes over an untracked file a declared dev server writes, and over nothing else.
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.
@@ -56,6 +58,8 @@ versioning:
 #               A slot is optional in the sense of the requirements list when its presence is not required.
 #   tracked     tracked (committed) | ignored (may exist, must be gitignored) | external (must not exist in the tree;
 #               goesTo says where it lives).
+#   rewrittenBy on an ignored file slot: the dev server that writes the file into the working tree while it runs (`next dev`). The
+#               release gate's clean-tree check (release/gate.mjs dirtyPaths) passes over an untracked file such a slot owns, and only it.
 #   tier        node of the import direction matrix (tiers below); none = takes no part in import checks;
 #               inherit = the tier of the enclosing owner.
 #   owner       true when every directory matching the slot is an owner: the unit cross-owner imports and cycles use.
@@ -254,6 +258,25 @@ ruleParams:
       "@socket.io/postgres-adapter": [platform/realtime]   # the stateless socket.io adapter of a scaled lite back end without Redis
       "@socket.io/redis-adapter": [platform/realtime]      # the sharded socket.io adapter of a scaled back end on the declared Redis
       pg: [platform/realtime]                              # the LISTEN connection of the Postgres hub; every other query goes through TypeORM
+      # BE-AI-1, BE-AI-3: every model call goes through the ai-router gateway. Its custody owner registers @starci/ai-router with the
+      # provider keys; the one LangChain integration owns @langchain/*; no provider SDK, openai client or agent framework is imported.
+      "@starci/ai-router": [integrations/ai-gateway]
+      "@starci/ai-router/testing": [integrations/ai-gateway, integrations/ai]   # the fake provider a spec of either side boots the gateway with
+      "@langchain": [integrations/ai]       # a scope key: every @langchain/* package
+      "@langchain/langgraph": []            # an agent loop runs in the agent runtime, never in code
+      "@langchain/community": []            # retrieval reads the app's own persistence through its owner
+      langchain: []                          # createAgent is an agent loop
+      openai: []                             # code calls models through @langchain/openai
+      "@anthropic-ai/sdk": []
+      "@google/genai": []
+      "@google/generative-ai": []
+      "@mistralai/mistralai": []
+      "@openrouter/ai-sdk-provider": []
+      "@ai-sdk": []
+      ai: []
+      cohere-ai: []
+      groq-sdk: []
+      ollama: []
     # R87 BE_CQRS_SHAPE no-event-bus: the in-process event vocabulary the rule refuses. `imports` maps a module
     # specifier to the member names that are an in-process event; `[]` flags the package itself (its emitter packages
     # are the `[]` owners of infraOwners above). `classes` maps a module specifier to the class names that are an
@@ -1136,6 +1159,16 @@ slots:
     tier: none
     tests: none
     why: produced by `npm run codegen` (prebuild and pretypecheck); never committed
+  - id: fe.dev-server-generated
+    since: 3.8.0
+    profiles: [fe]
+    path: "apps/*/AGENTS.md"
+    presence: optional
+    tracked: ignored
+    rewrittenBy: next dev
+    tier: none
+    tests: none
+    why: the agent notes `next dev` writes at a Next app's root each time it starts; never committed, and never a dirty tree for the release gate
 
   # ----- never in the working tree: caches, scratch, agent output ----------------------------------------
   - id: repo.tool-cache
@@ -1892,7 +1925,7 @@ slots:
     tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
     coverage: required
     budget: {indexExports: 80}   # a provider's port surface includes clients, config, options, tokens and errors
-    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING]
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT]
   - id: be.integrations.model
     since: 3.1.0
     profiles: [be]
@@ -1902,7 +1935,7 @@ slots:
     tier: integrations
     tests: none
     coverage: required
-    why: an ML or LLM model client is an integration; weights and datasets are never in git
+    why: a self-hosted ML model client is an integration; weights and datasets are never in git, and a language model is called through the ai-router gateway by the integrations/ai LangChain client (BE-AI-1, BE-AI-3)
     rules: [BE_TIER_DIRECTION, BE_INFRA_OWNER, BE_INTEGRATION_SPEC_MISSING]
 
   - id: be.integrations.supabase

package/runtime/modules/kernel/failure-codes.yaml

@@ -1739,6 +1739,16 @@ BE_WEBHOOK_UNVERIFIED:
   owner: op-retry
   kind: check-finding
 
+BOOT_PROOF_TIMEOUT:
+  title: "The lite boot proof's worker ran out of its budget twice and reached no verdict"
+  title_vi: "Bằng chứng khởi động lite hết thời gian hai lần, chưa có kết luận"
+  meaning_vi: "Tiến trình chứng minh ghép nối Nest chạy quá ngân sách thời gian riêng của nó (STARCI_BOOT_PROOF_TIMEOUT_MS, lấy từ heavy.bootProofTimeoutSeconds của ops/liveness.yaml) cả lần đầu lẫn lần thử lại. Đây không phải lỗi ghép nối: máy đang quá tải nên chưa phán được."
+  causes_vi:
+    - "Máy chủ đang chạy nhiều lệnh nặng cùng lúc nên trình biên dịch TypeScript của bằng chứng chạy quá chậm"
+  nextStep_vi: "Chạy lại starci app check --wiring khi máy rảnh hơn; nếu vẫn hết thời gian khi máy rảnh, nâng heavy.bootProofTimeoutSeconds trong ops/liveness.yaml."
+  owner: op-retry
+  kind: check-finding
+
 CI_DECLARATION_DRIFT:
   title: "Workflow references drift from CI declarations"
   title_vi: "Workflow lệch khai báo CI"
@@ -5629,3 +5639,14 @@ STACK_TOOLING_REIMPLEMENTED:
   nextStep_vi: "Xóa tệp hoặc lệnh đó và gọi động từ được nêu trong thông báo (starci app stack render, deploy, converge, verify, prune, rollback, prepare, doctor), đặt hằng số của ứng dụng vào khối deploy của application-stacks.yaml."
   owner: op-retry
   kind: check-finding
+
+BE_ENTITY_SCHEMA_DRIFT:
+  title: "A TypeORM entity column differs from the schema the migrations build"
+  title_vi: "Cột entity TypeORM lệch với schema mà migration tạo ra"
+  meaning_vi: "starci app db drift áp db/bootstrap.sql và mọi migration vào một cơ sở dữ liệu tạm, rồi so từng cột entity với schema đó: bảng hoặc cột không tồn tại, kiểu khác nhau sau khi chuẩn hóa theo tên của PostgreSQL, hoặc khả năng nhận NULL khác nhau."
+  causes_vi:
+    - "Vi phạm R333: entity được sửa mà không có migration tương ứng, hoặc migration đổi bảng mà entity chưa theo kịp."
+    - "Entity khai báo sai kiểu (ví dụ timestamp thay vì timestamptz) hoặc quên nullable cho một cột cho phép NULL."
+  nextStep_vi: "Viết migration mới trong db/migrations để schema có đúng cột đó, hoặc sửa entity cho khớp schema hiện tại, rồi chạy lại starci app db drift cho đến khi xanh."
+  owner: op-retry
+  kind: check-finding

package/runtime/scripts/hfs/app-wiring.mjs

@@ -2,6 +2,9 @@
 // Dynamic roots need public fixture options: src/tests/fixtures/builders/<app>.builder.ts may export
 // buildWiringProof(AppModule) => { options, overrides: [{ token, value }], request? }. The runner always chooses
 // the real root; a fixture cannot substitute an empty module. No environment parser or main.ts runs.
+// The proof worker has its own budget, counted from its spawn: STARCI_BOOT_PROOF_TIMEOUT_MS, which the starci CLI sets from ops/liveness.yaml
+// (heavy.bootProofTimeoutSeconds). A worker that runs out of it reached no verdict: it is retried once, and a second timeout is reported as
+// BOOT_PROOF_TIMEOUT (a warning: the host was too loaded to judge), never as the proof failing (BE_APP_BOOT_PROOF_MISSING).
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
@@ -12,6 +15,8 @@ import { isMain } from '../lib/is-main.mjs';
 import { readJson } from './rules/read.mjs';
 
 export const BOOT_PROOF_CODE = 'BE_APP_BOOT_PROOF_MISSING';
+export const BOOT_PROOF_TIMEOUT = 'BOOT_PROOF_TIMEOUT';
+export const BOOT_PROOF_TIMEOUT_ENV = 'STARCI_BOOT_PROOF_TIMEOUT_MS';
 const WORKER = fileURLToPath(import.meta.url);
 const DEFAULT_TIMEOUT = 15000;
 const DI_FAILURES = new Map([
@@ -29,6 +34,18 @@ export const wiringFixturePath = app => `src/tests/fixtures/builders/${app}.buil
 const refusal = (file, reason) => ({ code: BOOT_PROOF_CODE, level: 'error', path: file,
   message: `${file}: lite boot proof failed (${reason}); compile the real AppModule with explicit fixture options and infrastructure doubles using starci app check --wiring`, reason });
 
+const timedOut = (file, budget) => ({ code: BOOT_PROOF_TIMEOUT, level: 'warning', path: file, reason: 'proof worker timed out',
+  message: `${file}: the lite boot proof reached no verdict: its worker ran out of its ${Math.round(budget / 1000)} s budget twice (the host is loaded); this is no failure of the proof, rerun starci app check --wiring when the host is quieter` });
+
+/** The worker's budget in ms, from its spawn: the CLI's STARCI_BOOT_PROOF_TIMEOUT_MS, else four compile deadlines (at least a minute). */
+export function workerBudget(timeout, env = process.env) {
+  const configured = Number(env[BOOT_PROOF_TIMEOUT_ENV]);
+  return Number.isInteger(configured) && configured > 0 ? configured : Math.max(60000, timeout * 4) + 2000;
+}
+
+/** True when the worker was stopped by its budget (spawnSync's ETIMEDOUT, or the kill signal it sends), not when it ended by itself. */
+const isTimeout = (result) => result?.error?.code === 'ETIMEDOUT' || (result?.status === null && result?.signal != null);
+
 /** Stable diagnostics never forward exception text, source values or child output. */
 function failureReason(error) {
   // Nest exceptions inherit Error.name; their constructor identifies the refusal.
@@ -153,8 +170,12 @@ function appWiringFinding({ repoRoot, beRoot, prefix, app, files, fixtures, time
   const fixture = fixtures[app] ?? wiringFixturePath(app);
   const fixtureExists = fs.existsSync(path.join(beRoot, fixture)) && (!files || files.includes(`${prefix}${fixture}`));
   const args = [WORKER, '--worker', JSON.stringify({ repoRoot: beRoot, app, fixture: fixtureExists ? fixture : null, timeout })];
-  const options = { cwd: beRoot, encoding: 'utf8', env: {}, windowsHide: true, timeout: Math.max(60000, timeout * 4) + 2000, maxBuffer: 1024 * 1024 };
-  const result = run ? run(process.execPath, args, options) : runNode(args, options);
+  const budget = workerBudget(timeout);
+  const options = { cwd: beRoot, encoding: 'utf8', env: {}, windowsHide: true, timeout: budget, maxBuffer: 1024 * 1024 };
+  const spawnWorker = () => (run ? run(process.execPath, args, options) : runNode(args, options));
+  let result = spawnWorker();
+  if (isTimeout(result)) result = spawnWorker();
+  if (isTimeout(result)) return timedOut(file, budget);
   let proof;
   try { proof = JSON.parse(result.stdout ?? ''); } catch { /* Output from app source cannot serve as a proof. */ }
   if (result.status !== 0 || proof?.ok !== true) return refusal(file, SAFE_REASONS.has(proof?.reason) ? proof.reason : WORKER_FAILURE);

package/runtime/scripts/hfs/check.mjs

@@ -61,7 +61,7 @@
 // findings fail the check.
 import fs from 'node:fs';
 import path from 'node:path';
-import { appWiring, BOOT_PROOF_CODE } from './app-wiring.mjs';
+import { appWiring, BOOT_PROOF_CODE, BOOT_PROOF_TIMEOUT } from './app-wiring.mjs';
 import { coverageFrom as coverageFromReport } from './coverage-from.mjs';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { ARCHITECTURE_RULE_IDS, checkArchitecture } from './architecture/index.mjs';
@@ -410,7 +410,7 @@ export function withCheckProofs(result, { repoRoot, root = skillRoot, manifest =
   const proofFindings = Object.values(reports).flatMap(report => report.findings);
   const why = readWhy(root, [...new Set(proofFindings.map(finding => finding.code))]);
   // The explicit whole-tree wiring proof supersedes the ordinary finder's scoped result.
-  const previous = result.findings.filter(finding => !wiring || finding.code !== BOOT_PROOF_CODE);
+  const previous = result.findings.filter(finding => !wiring || (finding.code !== BOOT_PROOF_CODE && finding.code !== BOOT_PROOF_TIMEOUT));
   const findings = [...previous, ...withWhy(judgedFindings(proofFindings, repo.edition ?? 'full', root), why)];
   const counts = summarize(findings);
   return { ...result, ...reports, findings, counts, ok: counts.error === 0 };

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -87,7 +87,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
 
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'rewrittenBy'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
 const LITE_OVERLAY_KEYS = ['path', 'requires', 'allows', 'forbids', 'minInstances', 'requiredInstances', 'why'];
 /** A runtime slot has no app kind, side composition, layer or managed template; it may name the generator of a generated copy. */
@@ -114,6 +114,7 @@ function appIdentityProblems(slot, at, appScope, scopes) {
   if (!SLOT_ID.test(String(slot.id))) bad.push(`${at}: id must look like be.transport.http`);
   if (profilesInvalid(slot.profiles, appScope, scopes)) bad.push(`${at}: profiles must be [app] or a unique non-empty subset of be, fe`);
   else if ((slot.profiles[0] === appScope) !== String(slot.id).startsWith(`${appScope}.`)) bad.push(`${at}: an app-root slot has profiles [app] and an id app.<name>, and only it`);
+  if (slot.rewrittenBy !== undefined && (typeof slot.rewrittenBy !== 'string' || !slot.rewrittenBy.trim() || slot.tracked !== 'ignored' || String(slot.path).endsWith('/'))) bad.push(`${at}: rewrittenBy names the dev server that writes the files of an ignored file slot`);
   return bad;
 }
 

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -48,7 +48,7 @@ export const A15_CODES = [
   'HFS_WORKFLOW_CONTEXT',
   'CI_STANDARD',
   'CI_SECRET_SEALED', 'APP_SECRET_IN_CI', 'CI_DECLARATION_DRIFT',
-  'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_API_EXPOSED', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_CRON_OWNED', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_SERVICE_ROLE_SCOPE', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_REDIS_PERSISTENCE', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
+  'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BOOT_PROOF_TIMEOUT', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_API_EXPOSED', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_CRON_OWNED', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_SERVICE_ROLE_SCOPE', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_REDIS_PERSISTENCE', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
   // codes-end
 ];
 

package/src/main.mjs

@@ -96,10 +96,11 @@ import { dbMigrateMain } from '../db/migrate.mjs';
 import { dbPostCutoverMain } from '../db/post-cutover.mjs';
 import { dbDumpMain } from '../db/dump.mjs';
 import { dbResetMain } from '../db/reset.mjs';
+import { dbDriftMain } from '../db/drift.mjs';
 import { codemodMain } from '../codemod/button-intent.mjs';
 
 export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene', 'coverage', 'codemod']);
-const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
+const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain], ['drift', dbDriftMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
 starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app|block|composite|branch|leaf|page|overlay|layout> <name> [options] [--cwd <dir>]
@@ -114,11 +115,13 @@ starci app db dump (--linked | --local | --url-env <NAME>) --out <dir> [--schema
 starci app db reset --linked --auth keep|drop --storage keep|drop --backup <receipt.json> [--execute] [--json] [--cwd <dir>]
 starci app db migrate [--execute] [--local | --linked | --url-env <NAME>] [--json] [--cwd <dir>]
 starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--linked | --url-env <NAME>] [--json] [--cwd <dir>]
-starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--json] [--cwd <dir>]
-starci app release push [--execute] [--remote <name>] [--json] [--cwd <dir>]
+starci app db drift [--url-env <NAME>] [--json] [--cwd <dir>]
+starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--backfill <tag>] [--json] [--cwd <dir>]
+starci app release push [--execute] [--remote <name>] [--urgent --reason <text>] [--json] [--cwd <dir>]
 starci app upgrade [--plan] [--cwd <dir>]
 starci app stack <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
 starci app stack <prepare|doctor|connect|disconnect|build-args|render|deploy|converge|verify|rollback|prune|backup|jobs> --env <env> [--execute] [--json] [--cwd <dir>]
+starci app stack deploy --env <env> --source-sha <sha> --urgent [--db-url-env <NAME>] [--backup-out <dir>] [--execute] [--json] [--cwd <dir>]
 starci app explain <path> [--cwd <dir>] [--json]
 starci app emit [--cwd <dir>]
 starci app new service <dir> <name> [--inject <binding>...] [--cwd <dir>]
@@ -342,7 +345,7 @@ async function installedStackMain(cwd) {
 function databaseMain(argv, io) {
   const [verb, ...rest] = argv;
   const dispatch = DATABASE_VERBS.get(verb);
-  if (!dispatch) throw new Error('starci app db takes baseline, restamp, plan, migrate, post-cutover, dump or reset');
+  if (!dispatch) throw new Error('starci app db takes baseline, restamp, plan, migrate, post-cutover, dump, reset or drift');
   return dispatch(rest, io);
 }
 

package/stack/cli.mjs

@@ -14,8 +14,8 @@ const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollb
 
 export const ACTIONS = Object.freeze(['prepare', 'doctor', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept']);
 
-const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push']);
-const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding']);
+const BOOLEAN = new Set(['--execute', '--json', '--swarm-state', '--init-swarm', '--owner-approved', '--fix-live-restore', '--skip-public', '--skip-internal', '--allow-unpinned', '--push', '--urgent']);
+const VALUE = new Set(['--env', '--image', '--source-sha', '--previous', '--out', '--release', '--since', '--timeout', '--retry', '--keep', '--app', '--ssh-cmd', '--extra-compose', '--project', '--target-binding', '--db-url-env', '--backup-out']);
 const REPEAT = new Set(['--image', '--keep', '--extra-compose', '--project']);
 
 /** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
@@ -71,6 +71,7 @@ const OPTIONS = {
   deploy: ({ flags, cwd }) => ({
     images: parseImages(flags.image), sourceSha: flags['source-sha'], execute: flags.execute === true,
     out: flags.out ? path.resolve(cwd, flags.out) : null, timeoutSeconds: number(flags, 'timeout'), retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true,
+    urgent: flags.urgent === true, dbUrlEnv: flags['db-url-env'], backupOut: flags['backup-out'] ? path.resolve(cwd, flags['backup-out']) : undefined,
   }),
   converge: ({ flags }) => ({ since: flags.since, timeoutSeconds: number(flags, 'timeout') }),
   verify: ({ flags }) => ({ retrySeconds: number(flags, 'retry'), skipPublic: flags['skip-public'] === true, skipInternal: flags['skip-internal'] === true }),
@@ -125,6 +126,8 @@ export async function stackMain(argv, io = {}) {
     if (binding && (!['deploy', 'verify'].includes(action) || flags['ssh-cmd'] || flags['skip-public'] || flags['skip-internal']))
       throw refusal('STACK_USAGE', 'the bound native consumer supports only complete deploy or verify');
     const config = bindStackTarget(ctx, loadDeployConfig({ repoRoot: ctx.cwd, env: flags.env ?? 'production' }), binding);
+    if (action !== 'deploy' && (flags.urgent || flags['db-url-env'] || flags['backup-out'])) throw refusal('STACK_USAGE', '--urgent, --db-url-env and --backup-out belong to deploy');
+    if (action === 'deploy' && !flags.urgent && (flags['db-url-env'] || flags['backup-out'])) throw refusal('STACK_USAGE', '--db-url-env and --backup-out choose the urgent floor\'s database and backup folder: add --urgent');
     const options = OPTIONS[action]({ flags, positional, cwd: ctx.cwd });
     const handler = await handlerOf(action, io.importer ?? ((file) => import(file)));
     const sshCmd = flags['ssh-cmd'] ?? null;
@@ -132,6 +135,11 @@ export async function stackMain(argv, io = {}) {
     const toolContext = nativeToolContext(ctx, binding);
     const result = DOCKER_ACTIONS.has(action) ? await withDockerTransport(toolContext, config, { sshCmd }, call) : await call(toolContext);
     print(ctx, action, flags, result);
+    // A floor step of an urgent deploy that failed is a refusal with its own code (urgent-floor.mjs), printed after the lines that led to it.
+    if (result.refused) {
+      ctx.stderr(`starci app stack: ${result.refused.code}: ${result.refused.message}\n`);
+      return EXIT.refused;
+    }
     return result.ok ? EXIT.ok : EXIT.failed;
   } catch (error) {
     if (!(error instanceof StackError)) throw error;

package/stack/deploy.mjs

@@ -2,6 +2,8 @@
 // deploy: render, provision, store the release record, pre-pull, `docker stack deploy`, converge, post-deploy tasks (deploy.postDeploy, when declared), verify, accept, prune. A failure at or
 // after the stack deploy redeploys the previous accepted release from its STORED bytes; a failure before it leaves the services untouched.
 // Without `execute` a deploy renders locally and prints the plan: NO remote call at all. A rollback cannot undo data effects.
+// An urgent deploy (`urgent`, owner ruling urgent-release 2026-10-29) runs the safety floor of urgent-floor.mjs first (fresh verified encrypted
+// backup with a test decrypt, rollback target, migrate preview then execute) and refuses with the floor's own code when a step of it fails.
 //
 // `deps` are the collaborators, all factories or functions with the signature of their module, defaulting to lazy dynamic imports so this
 // module never needs render.mjs / provision.mjs / remote.mjs at load time (the specs inject stubs):
@@ -21,6 +23,7 @@ import { postDeployStack } from './post-deploy.mjs';
 import { pruneStack } from './prune.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { createReleaseStore } from './release-store.mjs';
+import { urgentDeploy } from './urgent-floor.mjs';
 import { verifyStack } from './verify.mjs';
 
 /** Loads `file` (relative to this module). Split out so a spec can load a real sibling module through `lazy`. */
@@ -39,8 +42,11 @@ export const DEFAULT_DEPS = Object.freeze({
   pruneStack,
   releaseStore: createReleaseStore,
   ssh: lazy('./remote.mjs', 'ownerSshRunner'),
+  floor: {},
 });
 
+const fileSha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
 const IMAGE_LINE = /^[ \t]+image:[ \t]*(\S+)[ \t]*$/gmu;
 const QUOTE = /^["']|["']$/gu;
 const IMAGE_REF = /^[A-Za-z0-9][A-Za-z0-9./_:@-]*$/u;
@@ -212,7 +218,7 @@ async function deployExecute(ctx, config, options, d, out, cleanups) {
 }
 
 /**
- * Deploys a release: `options` = { images, sourceSha, execute, out, timeoutSeconds, retrySeconds, skipPublic, sshCmd }.
+ * Deploys a release: `options` = { images, sourceSha, execute, out, timeoutSeconds, retrySeconds, skipPublic, sshCmd, urgent, dbUrlEnv, backupOut }.
  * skipPublic (the first deploy into a shared ingress, whose public routes exist only after `ingress publish`): the verification checks only what runs
  * inside the stack, and the release stays PENDING (stored and deployed, pointer not moved) until `acceptRelease` has verified it in full.
  * Returns { ok, lines, data: { releaseId, previous, steps: [{ step, ok }], rolledBack } }.
@@ -224,15 +230,26 @@ export async function deployRelease(ctx, config, options = {}, deps = {}) {
   const out = options.out ?? made;
   const cleanups = [];
   try {
-    const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, null));
-    const { releaseId } = inspectRendered(out, config);
-    if (options.execute !== true) {
+    // The local render and its inspection: a release that cannot render is refused before anything remote happens.
+    const render = async () => {
+      const rendered = await d.renderRelease(ctx, config, renderOptions(options, out, null));
+      return { rendered, releaseId: inspectRendered(out, config).releaseId };
+    };
+    const dryRun = async () => {
+      const { rendered, releaseId } = await render();
       const post = config.postDeploy.length > 0 ? ` post-deploy tasks (${config.postDeploy.join(', ')}),` : '';
       const plan = options.skipPublic
         ? `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} and verified inside the stack (public hosts skipped); it would stay pending until ingress publish and stack accept`
         : `dry run: release ${releaseId} would be provisioned, stored, pre-pulled, deployed, converged,${post} verified, accepted`;
       return { ok: true, lines: [...(rendered.lines ?? []), plan], data: { releaseId, steps: [{ step: 'render', ok: true }], executed: false } };
+    };
+    if (options.urgent === true) {
+      return await urgentDeploy(ctx, config, options, {
+        render, dryRun, openStore: () => openStore(ctx, config, options, d, cleanups), deployExecute: () => deployExecute(ctx, config, options, d, out, cleanups), sha256: fileSha256,
+      }, d.floor);
     }
+    if (options.execute !== true) return await dryRun();
+    await render();
     return await deployExecute(ctx, config, options, d, out, cleanups);
   } finally {
     cleanups.forEach((close) => close());