@starci/hfs 4.12.2 → 4.13.2

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

@@ -1764,7 +1764,7 @@ CI_STANDARD:
 CI_TRIGGERS_RELEASE_ONLY:
   title: "Workflow trigger outside R221"
   title_vi: "Workflow có trigger ngoài R221"
-  meaning_vi: "Workflow khai báo trigger ngoài R221: main được phép trong workflow runtime và ci.yml của app; các nhánh, sự kiện và bộ lọc khác phải theo R221."
+  meaning_vi: "Workflow khai báo trigger ngoài R221: main được phép trong workflow runtime và ci.yml của app; pull_request tới main chỉ được phép trong ci.yml, workflow_call dành cho workflow dùng lại; pull_request_target, workflow_run, lịch chạy và các nhánh, sự kiện, bộ lọc khác phải theo R221."
   causes_vi:
     - "Khai báo nhánh, sự kiện hoặc bộ lọc không thuộc R221"
     - "Khai báo nhánh, sự kiện hoặc bộ lọc không thuộc R221"
@@ -3180,7 +3180,7 @@ HFS_APP_LEXICON:
 HFS_APP_WORKFLOW_TRIGGER:
   title: "App workflow trigger outside R251"
   title_vi: "Workflow ứng dụng có sự kiện khởi chạy không hợp lệ"
-  meaning_vi: "Workflow ứng dụng khai báo trigger ngoài R251; ci.yml được chạy trên main và nhánh release candidate, các workflow khác giữ phạm vi trigger của R251."
+  meaning_vi: "Workflow ứng dụng khai báo trigger ngoài R251; ci.yml được chạy trên main, nhánh release candidate và pull_request tới main (quyền chỉ đọc, không gắn environment), images.yml và stack-deploy.yml là workflow dùng lại (workflow_call), các workflow khác giữ phạm vi trigger của R251."
   causes_vi:
     - "Khai báo trigger không thuộc R251"
   nextStep_vi: "Sửa trigger theo R251 và chạy starci app sync --execute."
@@ -3351,7 +3351,7 @@ HFS_DB_DEPLOY_UNGUARDED:
   title_vi: "Triển khai cơ sở dữ liệu chấp nhận ref không phải tag"
   meaning_vi: "Mỗi đường chạy triển khai migration phải từ chối ref không phải tag phát hành trước khi tác động cơ sở dữ liệu."
   causes_vi:
-    - "Workflow db-deploy thiếu chốt kiểm tag hoặc chốt không chặn đường chạy migration theo luật R271."
+    - "Workflow db-deploy thiếu chốt kiểm tag hoặc chốt không chặn đường chạy migration theo luật R271 (app lite không còn db-deploy: migration chạy trong bước migrate của stack deploy)."
   nextStep_vi: "Thêm chốt kiểm ref tag trước mỗi bước triển khai migration, rồi chứng minh ref nhánh bị từ chối."
   owner: op-retry
   kind: check-finding
@@ -3653,6 +3653,37 @@ HFS_FORBIDDEN_PRESENT:
   owner: op-retry
   kind: check-finding
 
+HFS_CHECK_CACHE_FORGED:
+  title: "A committed check cache record disagrees with what the check computes"
+  title_vi: "Bản ghi cache kiểm tra đã commit không khớp kết quả kiểm tra thật"
+  meaning_vi: "`<file>`: bản ghi trong `.starcistacks/cache/` có khóa khớp cây hiện tại nhưng phát hiện (findings) của nó khác với kết quả mà bộ kiểm tra tính ra từ cache tại base tin cậy. CI chỉ tin cache như nó đang có ở base, nên bản ghi này bị sửa tay hoặc một bước kiểm tra không xác định (khác nhau giữa các máy)."
+  causes_vi:
+    - "Sửa tay một tệp trong `.starcistacks/cache/` (xóa phát hiện để qua mặt kiểm tra)"
+    - "Một bước kiểm tra cho kết quả khác nhau trên các máy khác nhau"
+  nextStep_vi: "Chạy lại `starci app check` trên cây sạch để sinh lại cache rồi commit; không sửa tay thư mục cache. Lỗi này chặn ở mọi số lượng."
+  owner: op-retry
+  kind: check-finding
+
+HFS_CHECK_CACHE_STALE:
+  title: "A changed file has no current record in the committed check cache"
+  title_vi: "Tệp đã đổi nhưng cache kiểm tra đã commit chưa có bản ghi hiện hành"
+  meaning_vi: "`<file>` đổi so với base tin cậy mà `.starcistacks/cache/` đã commit không có bản ghi khớp nội dung hiện tại. CI vẫn kiểm tra đầy đủ tệp này nên kết quả đúng, chỉ tốn thời gian (cảnh báo)."
+  causes_vi:
+    - "Quên chạy `starci app check` và commit cache sau khi sửa"
+  nextStep_vi: "Chạy `starci app check` rồi commit `.starcistacks/cache/` cùng thay đổi."
+  owner: op-retry
+  kind: check-finding
+
+HFS_CHECK_CACHE_MISSING:
+  title: "The app commits no check cache"
+  title_vi: "Ứng dụng chưa commit cache kiểm tra"
+  meaning_vi: "`.starcistacks/cache/` không có bản ghi nào nên mọi lần chạy đều kiểm tra đầy đủ (cảnh báo, kết quả vẫn đúng)."
+  causes_vi:
+    - "Ứng dụng mới hoặc vừa nâng cấp, chưa chạy `starci app check` lần đầu"
+  nextStep_vi: "Chạy `starci app check` một lần rồi commit `.starcistacks/cache/` để các lần sau chỉ kiểm tra phần thay đổi."
+  owner: op-retry
+  kind: check-finding
+
 HFS_FORMAT:
   title: "Prettier is the only formatter"
   title_vi: "Chưa format bằng Prettier"
@@ -4026,7 +4057,7 @@ HFS_README_WORK_POINTER_MISSING:
 HFS_RELEASE_TAG_MISMATCH:
   title: "Product release tag does not match its version or image tag"
   title_vi: "Tag phát hành sản phẩm không khớp phiên bản hoặc tag image"
-  meaning_vi: "Tag phát hành phải có dạng v cộng phiên bản package.json; workflow images.yml phải dùng tag phát hành đó cho image trong lite và full."
+  meaning_vi: "Tag phát hành phải có dạng v cộng phiên bản package.json; workflow images.yml đẩy image với tag bất biến sha-<commit>, còn tên phát hành v<phiên bản> chỉ là retag của digest đó trên lần chạy tag phát hành, sau một chốt kiểm ref."
   causes_vi:
     - "Phiên bản package và tag khác nhau hoặc image dùng tag khác theo luật R271."
   nextStep_vi: "Đồng bộ phiên bản package và tag phát hành, rồi dùng cùng tag trong workflow xây image."
@@ -5541,6 +5572,17 @@ BE_ENTITY_SCHEMA_DRIFT:
   owner: op-retry
   kind: check-finding
 
+BE_ENTITY_EXTENDS_BASE:
+  title: "An entity repeats the columns every table shares instead of extending the base"
+  title_vi: "Entity lặp lại các cột mọi bảng đều có thay vì kế thừa lớp nền"
+  meaning_vi: "File `<path>` khai một lớp @Entity tự map cột created_at hoặc updated_at do cơ sở dữ liệu đặt (CreateDateColumn, UpdateDateColumn, hoặc Column với insert false, update false hay default) và có thể cả khóa uuid được sinh ra bên cạnh cả hai."
+  causes_vi:
+    - "Vi phạm R342 (BE-PERSISTENCE-3, phán quyết entity-base): các cột mọi bảng cùng có được kế thừa, không lặp lại trong từng entity."
+    - "Entity được viết tay hoặc sao chép từ entity cũ trước khi có AbstractEntity và UuidAbstractEntity trong platform/database."
+  nextStep_vi: "Xóa các thuộc tính đó và khai `extends UuidAbstractEntity` (có khóa uuid id) hoặc `extends AbstractEntity` (không có), import từ `@modules/platform/database`. Bảng có timestamp do ứng dụng đặt hoặc thiếu một trong hai cột thì không kế thừa gì và map cột đó bằng `@Column` thường."
+  owner: op-retry
+  kind: check-finding
+
 BE_AUTH_PASSPORT_OWNER:
   title: "An identity library is imported outside integrations/passport"
   title_vi: "Thư viện định danh bị import ngoài integrations/passport"

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -288,6 +288,12 @@ $defs:
             enum: [public, private]
       secrets: {type: array, items: {$ref: '#/$defs/ciSecret'}}
       vars: {type: array, items: {$ref: '#/$defs/ciVariable'}}
+      imageCache:
+        description: >-
+          Where the images job keeps its BuildKit layer cache: gha (default, the repository's GitHub Actions cache, one scope per image) or registry (a buildcache tag
+          beside the image in the registry, for images large enough to be evicted from the 10 GB Actions cache).
+        enum: [gha, registry]
+        default: gha
       jobs:
         description: >-
           Per-job settings of the managed CI (the CI standard, knowledge/hfs/ci-standard.yaml defaults): timeoutMinutes per job and the number of unit-run shards.
@@ -598,6 +604,26 @@ $defs:
         description: Host variable names interpolated into the rendered stack (names only).
         type: array
         items: {$ref: '#/$defs/deployKey'}
+      auto:
+        description: >-
+          true: every release tag whose CI is green deploys to this environment by itself, in the order the environments are declared (the owner's yes, given once by this setting;
+          ruling app-cicd-auto-deploy). The variable STARCI_DEPLOY_PAUSED=true on the GitHub Environment stops it without a code change. Default false (a manual dispatch deploys).
+        type: boolean
+        default: false
+      approval:
+        description: >-
+          none (default): the pipeline deploys without a human step. reviewers: the GitHub Environment has required reviewers (a public repository or Enterprise; Free, Pro and Team
+          private repositories cannot set them), which the owner configures on the environment.
+        enum: [none, reviewers]
+        default: none
+      platforms:
+        description: >-
+          The platforms the images are built for. Default [linux/amd64], the architecture of the VPS; add linux/arm64 only when an environment declares a node of that architecture
+          (the build then uses QEMU, and the release record keeps the index digest).
+        type: array
+        uniqueItems: true
+        minItems: 1
+        items: {enum: [linux/amd64, linux/arm64]}
       verify: {$ref: '#/$defs/deployVerify'}
       jobs: {$ref: '#/$defs/deployJobs'}
       tasks: {$ref: '#/$defs/deployTasks'}
@@ -607,6 +633,7 @@ $defs:
         uniqueItems: true
         items: {type: string, pattern: '^[a-z][a-z0-9-]{0,40}$'}
       backup: {$ref: '#/$defs/deployBackup'}
+      notify: {$ref: '#/$defs/deployNotify'}
       registry: {$ref: '#/$defs/deployRegistry'}
       ingress:
         description: The shared host ingress (stack-ingress-config.mjs is the authority for the fields; starci app check R294 judges them).
@@ -824,6 +851,27 @@ $defs:
         type: array
         minItems: 1
         items: {$ref: '#/$defs/deployBackupVolume'}
+  deployNotify:
+    description: >-
+      One webhook message per deploy outcome (accepted, rolled-back, rollback-failed, failed; `refused` only when listed): the outcome, the environment, the commit, the tag, the
+      release and the attempt, as JSON with a `text` and a `content` line so a chat webhook shows it. Off unless declared. The URL is a sealed value of the environment
+      (https only), never written here; a failing webhook is a line of the result and never fails the deploy.
+    type: object
+    additionalProperties: false
+    required: [webhook]
+    properties:
+      webhook:
+        type: object
+        additionalProperties: false
+        required: [member, key]
+        properties:
+          member: {$ref: '#/$defs/deployName'}
+          key: {$ref: '#/$defs/deployKey'}
+      on:
+        type: array
+        uniqueItems: true
+        minItems: 1
+        items: {enum: [accepted, rolled-back, rollback-failed, failed, refused]}
   deployRegistry:
     description: >-
       The image registry and the visibility the app's packages are meant to have. The canon scaffold writes `public`; the value then belongs to the app.

package/runtime/scripts/hfs/architecture/hfs.d.mts

@@ -50,7 +50,7 @@ export declare function checkHfs(config: HfsConfig): {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         rootEntries: number;
         apps: string[];
         ruleIds: string[];
@@ -69,7 +69,7 @@ export declare function checkAppRoot({ root, resolver, tree }: {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         hooksPath: {
             status: string;
             reason: string;
@@ -80,7 +80,7 @@ export declare function checkAppRoot({ root, resolver, tree }: {
             hooks?: never;
         } | {
             status: string;
-            hooks: "missing" | "installed" | "empty" | "unreadable";
+            hooks: "installed" | "missing" | "empty" | "unreadable";
             reason?: never;
         };
         rootEntries: number;
@@ -100,7 +100,7 @@ export declare function checkHfsWithoutConfig(repositoryRoot: string): {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         rootEntries: number;
         apps: string[];
         ruleIds: string[];
@@ -109,7 +109,7 @@ export declare function checkHfsWithoutConfig(repositoryRoot: string): {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         hooksPath: {
             status: string;
             reason: string;
@@ -120,7 +120,7 @@ export declare function checkHfsWithoutConfig(repositoryRoot: string): {
             hooks?: never;
         } | {
             status: string;
-            hooks: "missing" | "installed" | "empty" | "unreadable";
+            hooks: "installed" | "missing" | "empty" | "unreadable";
             reason?: never;
         };
         rootEntries: number;

package/runtime/scripts/hfs/check.mjs

@@ -113,7 +113,7 @@ export const CHECK_CODES = Object.freeze([
     'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'LITE_DB_MIGRATION',
     'HFS_DOCKER_HEALTHCHECK_FAKE', 'DB_APP_ROLE', 'DB_FORCE_RLS_DEFAULT',
     'DB_POLICY_TAUTOLOGY', 'DB_VIEW_UNSAFE', 'DB_STORAGE_PREFIX', 'DB_DEFINER_REVOKE',
-    'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT',
+    'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT', 'HFS_CHECK_CACHE_FORGED', 'HFS_CHECK_CACHE_STALE', 'HFS_CHECK_CACHE_MISSING',
     'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
     ...A15_CODES,
     ...REFUSAL_CODES,

package/runtime/scripts/hfs/gate-threshold.mjs

@@ -1,6 +1,6 @@
 // gate-threshold.mjs - the verdict of `starci app check` and `starci app lint` (owner ruling gate-threshold-20, 2026-10-30): green
 // while fewer than GATE_ERROR_LIMIT error findings remain and none of them is a hard blocker, so a release is not held back finding
-// by finding (5, 4, 3, ...) by the last few structural nits. A plaintext secret, a failed boot proof and a broken migration block at
+// by finding (5, 4, 3, ...) by the last few structural nits. A plaintext secret, a failed boot proof, a forged check cache record and a broken migration block at
 // any count. Every finding is still printed; only the exit code changes. Typecheck, build and the tests are not judged here.
 export const GATE_ERROR_LIMIT = 20;
 /** The limit in force: policy/quality.yaml `gate.errorLimit`, handed in by the harness CLI as STARCI_GATE_ERROR_LIMIT, else 20. */
@@ -14,6 +14,7 @@ export const HARD_BLOCKERS = Object.freeze(new Set([
     'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'RT_SECRET_TRACKED',
     'STACKS_SECRET_ENV_LITERAL', 'APP_SECRET_IN_CI', 'BE_LOG_SECRET',
     'BE_APP_BOOT_PROOF_MISSING',
+    'HFS_CHECK_CACHE_FORGED',
     'DB_MIGRATION_SHAPE', 'DB_MIGRATION_DESTRUCTIVE', 'LITE_DB_MIGRATION', 'BE_MIGRATION_REVERSIBLE',
 ]));
 export function gateVerdict(errors, limit = gateErrorLimit()) {

package/runtime/scripts/hfs/rules/boot-proof.d.mts

@@ -1,5 +1,10 @@
 import type { Repo } from './rule-types.mjs';
 export declare const BE_APP_BOOT_PROOF_MISSING = "BE_APP_BOOT_PROOF_MISSING";
+/**
+ * Runs `work` with the ordinary content finder's boot proof off. The app check cache runs the proof as its own scoped step (`--wiring`,
+ * keyed on the back-end side), so the always-run app pass must not compile the Nest graph a second time.
+ */
+export declare function withoutBootProof<T>(work: () => T): T;
 /** Root scopes delegate to the be side, so each app is compiled once. */
 export declare function bootProofFindings({ repoRoot, files, all, repo, isRoot, inScope }: {
     repoRoot: string;

package/runtime/scripts/hfs/rules/boot-proof.mjs

@@ -3,9 +3,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { appWiring } from '../app-wiring.mjs';
 export const BE_APP_BOOT_PROOF_MISSING = 'BE_APP_BOOT_PROOF_MISSING';
+let suppressed = 0;
+/**
+ * Runs `work` with the ordinary content finder's boot proof off. The app check cache runs the proof as its own scoped step (`--wiring`,
+ * keyed on the back-end side), so the always-run app pass must not compile the Nest graph a second time.
+ */
+export function withoutBootProof(work) {
+    suppressed += 1;
+    try {
+        return work();
+    }
+    finally {
+        suppressed -= 1;
+    }
+}
 /** Root scopes delegate to the be side, so each app is compiled once. */
 export function bootProofFindings({ repoRoot, files, all = files, repo, isRoot = Boolean(repo?.sides), inScope = () => true }) {
-    if (repo?.edition !== 'lite' || isRoot || repo?.profile === 'fe' || repo?.kind === 'fe')
+    if (suppressed > 0 || repo?.edition !== 'lite' || isRoot || repo?.profile === 'fe' || repo?.kind === 'fe')
         return [];
     // Dependencies not installed (a fresh scaffold, a lint-only checkout): the Nest graph cannot be compiled, so the proof is unavailable here; CI and every installed app judge it.
     const installed = [repoRoot, path.dirname(repoRoot ?? '.')].some((dir) => dir && fs.existsSync(path.join(dir, 'node_modules')));

package/runtime/scripts/hfs/rules/ci-custody.mjs

@@ -8,6 +8,8 @@ const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
 const named = (entry) => typeof entry.name === 'string' && /^[A-Z][A-Z0-9_]*$/.test(entry.name);
 const identity = (kind, name) => `${kind}:${name}`;
 const atCi = (section) => `${DECLARATION}#ci.${section}`;
+/** The variables the managed workflows themselves read; an app declares none of them. STARCI_DEPLOY_PAUSED is the brake of the automatic deploy, set per GitHub environment by the owner. */
+const MANAGED_VARIABLES = ['STARCI_DEPLOY_PAUSED'];
 /** A CI or Dependabot secret must never also live in a sealed app member. */
 function sealedFindings(ci, sealed) {
     const names = new Set([...ci.secrets, ...ci.dependabotSecrets].filter(named).map((entry) => entry.name));
@@ -44,7 +46,7 @@ function runtimeFindings(doc, ci, sealed) {
 /** Workflow reads are class-sensitive; legacy lists remain readable, but an absent ci block always signals migration once per name. */
 function workflowFindings(doc, declared, references) {
     const hasCi = doc.ci !== undefined;
-    const allowed = new Set(declared.map(({ kind, name }) => identity(kind, name)));
+    const allowed = new Set([...declared.map(({ kind, name }) => identity(kind, name)), ...MANAGED_VARIABLES.map((name) => identity('vars', name))]);
     if (hasCi) {
         for (const entry of ciNamesOfServices(doc).filter(named)) {
             const legacy = list(doc.services?.[entry.service]?.ci?.[`${entry.kind}s`]);

package/runtime/scripts/hfs/rules/ci-standard.mjs

@@ -47,11 +47,14 @@ function jobShape(doc, edition, standard, say) {
     const shape = standard.jobs[edition] ?? standard.jobs.full;
     const ids = jobsOf(doc).map(([id]) => id);
     const out = [];
-    const missing = shape.required.filter((id) => !ids.includes(id));
-    const extra = ids.filter((id) => !shape.required.includes(id) && !shape.optional.includes(id));
+    const prefix = String(standard.deployJobPrefix ?? 'deploy-');
+    const deployIds = ids.filter((id) => id.startsWith(prefix));
+    const must = [...shape.required, ...(shape.pipeline ?? [])];
+    const missing = must.filter((id) => !ids.includes(id));
+    const extra = ids.filter((id) => !must.includes(id) && !shape.optional.includes(id) && !deployIds.includes(id));
     const gaps = [missing.length ? 'missing ' + missing.join(', ') : '', extra.length ? 'not in the standard ' + extra.join(', ') : ''].filter(Boolean).join('; ');
     if (gaps)
-        out.push(say('job-shape', `the jobs must be ${shape.required.join(', ')} (optional ${shape.optional.join(', ')}); ${gaps}`));
+        out.push(say('job-shape', `the jobs must be ${must.join(', ')} (optional ${shape.optional.join(', ')}); ${gaps}`));
     const withStep = (match) => jobsOf(doc).filter(([, job]) => stepsOf(job).some((step) => match(step))).map(([id]) => id);
     const unit = withStep((step) => step.name === 'unit');
     const upload = withStep((step) => usesOf(step).startsWith('codecov/codecov-action@'));
@@ -65,6 +68,32 @@ function jobShape(doc, edition, standard, say) {
     const oidc = jobsOf(doc).filter(([, job]) => job.permissions?.['id-token'] === 'write').map(([id]) => id);
     if (upload.length && oidc.join() !== 'coverage')
         out.push(say('job-shape', `only the coverage job holds the OIDC id-token (id-token: write), not ${oidc.join(', ') || 'no job'}`));
+    out.push(...pipelineShape(doc, ids, deployIds, say));
+    return out;
+}
+const needsOf = (job) => (Array.isArray(job?.needs) ? job.needs.map(String) : typeof job?.needs === 'string' ? [job.needs] : []);
+/** The plan, images, verdict and deploy jobs: the verdict judges every other job and always runs, the images are the reusable images.yml, a deploy job calls stack-deploy.yml after the verdict. */
+function pipelineShape(doc, ids, deployIds, say) {
+    const out = [];
+    const others = ids.filter((id) => id !== 'verdict' && !deployIds.includes(id));
+    const verdict = doc.jobs?.verdict;
+    if (record(verdict)) {
+        const judged = needsOf(verdict);
+        const unjudged = others.filter((id) => !judged.includes(id));
+        if (unjudged.length)
+            out.push(say('job-shape', `the verdict job must need every other job; it does not need ${unjudged.join(', ')}`));
+        if (!/^(?:\$\{\{\s*)?always\(\)/.test(String(verdict.if ?? '').trim()))
+            out.push(say('job-shape', 'the verdict job runs under if: always(), so a skipped or red job reaches it'));
+    }
+    if (record(doc.jobs?.images) && doc.jobs.images.uses !== './.github/workflows/images.yml')
+        out.push(say('job-shape', 'the images job calls the reusable ./.github/workflows/images.yml'));
+    for (const id of deployIds) {
+        const job = doc.jobs[id];
+        if (!needsOf(job).includes('verdict'))
+            out.push(say('job-shape', `job ${id} deploys, so it must need the verdict job`));
+        if (job.uses !== './.github/workflows/stack-deploy.yml')
+            out.push(say('job-shape', `job ${id} deploys through the reusable ./.github/workflows/stack-deploy.yml, never with steps of its own`));
+    }
     return out;
 }
 function testSharding(doc, say) {

package/runtime/scripts/hfs/rules/database-migrations.d.mts

@@ -33,6 +33,20 @@ export declare function databaseSqlTokens(text: string): {
 export declare function databaseSqlStatements(tokens: Parsed): any[][];
 /** SQL and PL/pgSQL bodies are scanned; comments, data literals and other function languages are opaque. */
 export declare function databaseExecutableTokens(text: string, depth?: number): any[];
+/**
+ * A contract migration must not ship in the same release as the code change it depends on (cicd.md, Database migrations). The deploy applies
+ * a contract migration right after the accept, while the release it replaced is still the rollback target: if that release's code still names
+ * the destroyed object, a rollback after the contract would run code against a schema that no longer has it. The check judges exactly that
+ * with git: each contract migration that is new since the previous release tag (absent there) is read for the objects it destroys, and the
+ * be/src sources AS THEY WERE AT THE PREVIOUS RELEASE TAG must not reference them (the sources at HEAD are judged by destructiveMigrationFindings).
+ * The first release, a repository without a release tag, or an unreadable git history has no previous release and no finding. It reports
+ * DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
+ */
+export declare function contractReleaseFindings({ repoRoot, migrations, git }: {
+    repoRoot: string;
+    migrations: Parsed;
+    git: Parsed;
+}): Promise<any>;
 /** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
 export declare function destructiveMigrationFindings({ repoRoot, migrations, files }: {
     repoRoot: string;

package/runtime/scripts/hfs/rules/database-migrations.mjs

@@ -3,6 +3,7 @@
 import { lsTree } from '../../api/git/ls-tree.mjs';
 import { mergeBase } from '../../api/git/merge-base.mjs';
 import { show } from '../../api/git/show.mjs';
+import { tag } from '../../api/git/tag.mjs';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
 import { sameText } from '../../lib/same-text.mjs';
@@ -37,12 +38,21 @@ export function defaultGit(args, { cwd }) {
         const sha = mergeBase(cwd, rest[0], rest[1]);
         return { ok: sha !== null, stdout: sha ?? '' };
     }
+    if (verb === 'previous-release')
+        return previousReleaseTag(cwd, env, rest[0]);
     let call = show;
     if (verb === 'ls-tree')
         call = lsTree;
     const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
     return { ok: !result.error && result.status === 0, stdout: result.stdout };
 }
+/** The nearest release tag before HEAD: the newest version among the tags HEAD contains that do not point at HEAD itself. `pattern` is a tag glob (v*). */
+function previousReleaseTag(cwd, env, pattern) {
+    const listed = (args) => { const result = tag(args, { cwd, env }); return !result.error && result.status === 0 ? String(result.stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean) : []; };
+    const here = new Set(listed(['--points-at', 'HEAD']));
+    const previous = listed(['--merged', 'HEAD', '--list', pattern, '--sort=-v:refname']).find((name) => !here.has(name));
+    return { ok: previous !== undefined, stdout: previous ?? '' };
+}
 const runGit = (git, repoRoot, args) => Promise.resolve(git(args, { cwd: repoRoot }))
     .then((result) => ({ ok: result?.ok === true, stdout: String(result?.stdout ?? '') }));
 async function baseShaOf(git, repoRoot, base) {
@@ -515,6 +525,51 @@ function destructiveFileFindings(file, text, references) {
         return finding ? [finding] : [];
     });
 }
+const BE_SQL_SOURCE = /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/;
+/** The tag glob of a release (release.tagPrefix defaults to v). */
+const RELEASE_TAG_GLOB = 'v*';
+/**
+ * A contract migration must not ship in the same release as the code change it depends on (cicd.md, Database migrations). The deploy applies
+ * a contract migration right after the accept, while the release it replaced is still the rollback target: if that release's code still names
+ * the destroyed object, a rollback after the contract would run code against a schema that no longer has it. The check judges exactly that
+ * with git: each contract migration that is new since the previous release tag (absent there) is read for the objects it destroys, and the
+ * be/src sources AS THEY WERE AT THE PREVIOUS RELEASE TAG must not reference them (the sources at HEAD are judged by destructiveMigrationFindings).
+ * The first release, a repository without a release tag, or an unreadable git history has no previous release and no finding. It reports
+ * DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
+ */
+export async function contractReleaseFindings({ repoRoot, migrations, git }) {
+    const contracts = migrations.filter((file) => /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file));
+    if (!contracts.length)
+        return [];
+    const previous = await runGit(git, repoRoot, ['previous-release', RELEASE_TAG_GLOB]);
+    const release = previous.stdout.trim();
+    if (!previous.ok || !release)
+        return [];
+    const known = new Set(await migrationFilesAt(git, repoRoot, release));
+    const fresh = contracts.filter((file) => !known.has(file));
+    if (!fresh.length)
+        return [];
+    const listing = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', release, '--', 'be/src']);
+    const sources = listing.ok ? listing.stdout.split('\0').filter((file) => BE_SQL_SOURCE.test(file)) : [];
+    if (!sources.length)
+        return [];
+    const ts = loadTypescript(repoRoot, HERE);
+    if (!ts)
+        return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'the contract-release check requires the TypeScript parser to read the be/src references of the previous release')];
+    const references = [];
+    await eachInOrder(sources, async (file) => {
+        references.push({ file, scopes: sourceNameScopes(ts, await baseFileText(git, repoRoot, release, file) ?? '', file) });
+    });
+    return fresh.flatMap((file) => {
+        const text = readText(repoRoot, file);
+        if (text === null)
+            return [];
+        return databaseSqlStatements(databaseExecutableTokens(text)).flatMap(destructiveObjects).flatMap((object) => {
+            const reference = references.find(({ scopes }) => referencesObject(scopes, object));
+            return reference ? [found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
+        });
+    });
+}
 /** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
 export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
     const sources = files.filter((file) => /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/.test(file));

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

@@ -1,7 +1,7 @@
 // The database rules of a lite app's db/ tree (design 4.2, L02-L09). SQL migrations are parsed with libpg-query through
 // database-sql.mjs; Git history and generated-type checks are split into bounded sibling modules.
 import { found, readJson, readText } from './read.mjs';
-import { defaultGit, migrationShapeFindings } from './database-migrations.mjs';
+import { contractReleaseFindings, defaultGit, migrationShapeFindings } from './database-migrations.mjs';
 import { migrationSetPolicyFindings, sqlAnalysis } from './database-sql.mjs';
 import { migrationSetDefinerFindings } from './database-plpgsql.mjs';
 import { databaseAccessFindings } from './database-access.mjs';
@@ -66,6 +66,7 @@ export async function checkDatabase({ repoRoot, files, base, git, edition, db })
         findings.push(...liteDbPathFindings(files));
     const forceRls = new Set((declared?.forceRls ?? []).map((name) => (name.includes('.') ? name : `public.${name}`)));
     findings.push(...await migrationShapeFindings({ repoRoot, migrations, archived, git: git ?? defaultGit, base }));
+    findings.push(...await contractReleaseFindings({ repoRoot, migrations, git: git ?? defaultGit }));
     const analyses = await migrationAnalyses({ repoRoot, migrations, exposed: APP_SCHEMAS, forceRls, findings });
     findings.push(...migrationSetPolicyFindings(analyses), ...migrationSetDefinerFindings(analyses, APP_SCHEMAS), ...await databaseAccessFindings({ analyses, exposed: APP_SCHEMAS, db: declared }));
     return findings;

package/runtime/scripts/hfs/rules/deploy-workflow.mjs

@@ -1,4 +1,6 @@
 // R251: product workflow custody, immutable dependencies and release-only triggers, in both editions.
+// A release deploys through the reusable stack-deploy.yml: its jobs hold the environment, the age key and the transport; the job of ci.yml that calls it
+// (a deployment caller) holds permissions, concurrency and the environment name it passes. A pull_request run reads and never binds an environment.
 import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
 import { found } from './read.mjs';
 import { appWorkflowFindings } from './app-workflow-findings.mjs';
@@ -71,6 +73,7 @@ const deployName = (value) => !/authorize[\s_.-]+deploy[\s_.-]+key/i.test(value)
 const materializeCommand = (script) => commands(script).some(({ text }) => /^starci\s+app\s+secret\s+materialize\b/.test(commandBody(text)));
 const DEPLOYMENT_COMMANDS = [
     /^starci\s+(?:app\s+)?(?:deploy|secret\s+materialize)\b/,
+    /^(?:npx\s+(?:--no-install\s+)?)?starci\s+app\s+stack\s+(?:deploy|rollback|accept)\b/,
     /^docker\s+stack\s+deploy\b/,
     /^(?:ba?sh\s+)?(?:\.\/)?deploy\//,
     /^(?:ba?sh\s+)?(?:\.\/)?(?:scripts\/)?[\w.-]*deploy[\w.-]*\.sh\b/,
@@ -92,22 +95,46 @@ const CANDIDATE_BRANCHES = 'release/candidate-*';
 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 > 0 && new Set(options.branches).size === options.branches.length && options.branches.every((branch) => branch === CANDIDATE_BRANCHES || (ci && branch === 'main'))));
+const isCi = (file) => /(^|\/)ci\.ya?ml$/.test(file);
+/** A pull request to main in ci.yml: the checks of a change. Read-only workflow permissions, no environment on a job of the file itself (a call of a reusable workflow cannot have one). */
+function pullRequestFindings(doc, options, refuse, file) {
+    if (!isCi(file))
+        return [refuse(TRIGGER, 'pull_request may start only ci.yml: no other app workflow runs the code of a pull request')];
+    const findings = [];
+    const filters = record(options) ? options : {};
+    const branches = filters.branches;
+    if (!Array.isArray(branches) || branches.length !== 1 || branches[0] !== 'main' || Object.keys(filters).some((key) => key !== 'branches'))
+        findings.push(refuse(TRIGGER, "pull_request may contain only branches: ['main']"));
+    const permissions = doc.permissions;
+    const readOnly = record(permissions) && Object.values(permissions).every((value) => value === 'read' || value === 'none');
+    if (!readOnly)
+        findings.push(refuse(TRIGGER, 'a workflow that runs on pull_request declares read-only workflow permissions (permissions: contents: read); a job that needs more asks for it itself'));
+    for (const [name, job] of Object.entries(record(doc.jobs) ? doc.jobs : {})) {
+        if (record(job) && job.environment !== undefined)
+            findings.push(refuse(TRIGGER, `job ${name} binds an environment in a workflow that runs on pull_request; a pull request run reads no environment secret`));
+    }
+    return findings;
+}
 function triggerFindings(doc, refuse, file = '') {
     const on = workflowEventOptions(doc.on);
     if (!record(on) || !Object.keys(on).length)
         return [refuse(TRIGGER, 'declare release tags [v*] and/or workflow_dispatch')];
     const findings = [];
-    if (/(^|\/)ci\.ya?ml$/.test(file) && !(record(on.push) && Array.isArray(on.push.branches) && on.push.branches.includes(CANDIDATE_BRANCHES))) {
+    if (isCi(file) && !(record(on.push) && Array.isArray(on.push.branches) && on.push.branches.includes(CANDIDATE_BRANCHES))) {
         findings.push(refuse(TRIGGER, `the release CI must run on push of branches ['${CANDIDATE_BRANCHES}']: starci app release push waits for that run (starci app sync renders it)`));
     }
     for (const [event, options] of Object.entries(on)) {
-        if (event === 'workflow_dispatch')
+        if (event === 'workflow_dispatch' || event === 'workflow_call')
             continue;
+        if (event === 'pull_request') {
+            findings.push(...pullRequestFindings(doc, options, refuse, file));
+            continue;
+        }
         if (event !== 'push') {
-            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`));
+            findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches, main and pull requests to main in ci.yml, workflow_call or workflow_dispatch`));
             continue;
         }
-        if (!pushFilterValid(options, /(^|\/)ci\.ya?ml$/.test(file))) {
+        if (!pushFilterValid(options, isCi(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`));
         }
     }
@@ -158,6 +185,8 @@ function scriptWritesDotenv(value) {
 function writesDotenv(doc) {
     return entries(doc).some(({ key, value }) => key === 'env_file' || key === 'env-file' || (['run', 'script'].includes(key) && typeof value === 'string' && scriptWritesDotenv(value)));
 }
+/** The job of a workflow that calls a reusable workflow of the app (`uses: ./.github/workflows/<file>`): a deployment caller when the callee deploys. */
+const localCall = (job) => typeof job.uses === 'string' && job.uses.startsWith('./.github/workflows/');
 function deploymentJobs(doc, file) {
     const jobs = record(doc.jobs) ? Object.entries(doc.jobs).filter(([, job]) => record(job)) : [];
     const identified = jobs.filter(([name, job]) => deployName(name) || deployName(String(job.name ?? '')) || scripts(job).some(deploymentCommand) || (typeof job.uses === 'string' && deployName(job.uses)));
@@ -167,7 +196,23 @@ function deploymentJobs(doc, file) {
         return jobs;
     return [];
 }
+/** A deployment caller (ci.yml's deploy-<env>): permissions, concurrency and the environment it passes; the called job binds the environment and opens the key. */
+function callerFindings(name, job, doc, refuse) {
+    const findings = [];
+    const environment = record(job.with) ? job.with.environment : undefined;
+    if (job.environment !== undefined)
+        findings.push(refuse(DEPLOY, `job ${name} calls a reusable workflow, which cannot bind an environment itself; pass the name as with.environment and let the called job bind it`));
+    if (!nonempty(environment))
+        findings.push(refuse(DEPLOY, `job ${name} must pass with.environment: the GitHub environment the called deploy job binds`));
+    if (!validPermissions(job.permissions ?? doc.permissions))
+        findings.push(refuse(DEPLOY, `job ${name} must declare permissions at job or workflow scope`));
+    if (!validConcurrency(job.concurrency ?? doc.concurrency))
+        findings.push(refuse(DEPLOY, `job ${name} must declare concurrency at job or workflow scope`));
+    return findings;
+}
 function deploymentJobFindings(name, job, doc, refuse) {
+    if (localCall(job))
+        return callerFindings(name, job, doc, refuse);
     const findings = [];
     if (!validEnvironment(job.environment))
         findings.push(refuse(DEPLOY, `job ${name} must declare its protected environment`));
@@ -205,9 +250,11 @@ function deploymentFindings(doc, file, refuse) {
         findings.push(refuse(DEPLOY, 'the deploy workflow must declare a deployment job'));
     for (const [name, job] of deployment)
         findings.push(...deploymentJobFindings(name, job, doc, refuse));
-    for (const problem of secretProblems(doc))
+    // The secrets and dotenv writes are judged where the deploy runs: the workflow-level env and the deployment jobs, not a check job beside them (the Sonar token of ci.yml).
+    const judged = { env: doc.env, jobs: Object.fromEntries(deployment) };
+    for (const problem of secretProblems(judged))
         findings.push(refuse(DEPLOY, problem));
-    if (writesDotenv(doc))
+    if (writesDotenv(judged))
         findings.push(refuse(DEPLOY, 'deploy workflows must never write dotenv files or use env_file blobs; materialize sealed custody'));
     return findings;
 }