@starci/hfs 4.7.14 → 4.7.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.7.16 - 2026-10-21
+- Fixed: `DB_MIGRATION_DESTRUCTIVE` counts a be/src source as a reference of a dropped or altered column only when the source names the column's table too, so a same-named column of another table (`public.brain_lessons.origin` beside a drop of `transactions.origin`) no longer blocks a contract migration; table and other object drops keep the leaf match; canon pins follow the matching package cohort.
+
+## 4.7.15 - 2026-10-21
+- Added: slot `be.contract.mcp-tools` (opt-in, slot manifest 3.4.0) for the committed MCP tool catalog `be/contracts/<app>/<contract>.tools.json`, and R302 `HFS_MCP_TOOLS_SNAPSHOT`: the catalog names a declared be app, its contract is `<server>@<major>` equal to the file name and the server name, and every tool has a unique name, a description and an object `inputSchema`; canon pins follow the matching package cohort.
+
 ## 4.7.14 - 2026-10-20
 - Added: `starci app hygiene` (the managed pre-commit hook) refuses a back-end logic file the index adds without its `<name>.<role>.spec.ts` beside it, naming the file (`BE_UNIT_SPEC_NOT_STAGED`, R47); the measured roles and roots come from the coverage scope.
 - Added: `starci app check` reports `HFS_HOOKS_NOT_INSTALLED` (R13, error) when a set `core.hooksPath` names a hooks folder that is missing or holds no husky dispatcher in the checkout, with the install remedy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.14",
+  "version": "4.7.16",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.22
+    version: 3.4.24
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.21
+    version: 8.4.23
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.14
+    version: 1.7.16
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.14
+    version: 4.7.16
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -4985,3 +4985,18 @@ rules:
       - {path: packages/hfs/templates/app/ci-workflows/github/workflows/ci.yml, edition: full}
     specNa: "owner:no-runtime-specs (2026-10-17): the runtime has no specs of its own; the scaffold e2e (e2e/hfs-scaffold-app.spec.mjs: a fresh scaffold has no finding) and the example apps prove it"
     witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): the runtime has no spec fixtures", date: "2026-10-18"}
+  - id: R302
+    code: "HFS_MCP_TOOLS_SNAPSHOT"
+    law: "An app that commits the MCP tool catalog of its server keeps it at `be/contracts/<app>/<contract>.tools.json` (slot be.contract.mcp-tools, opt-in), `<contract>` being `<server>@<major>`, as the server's `tools/list` result: `{ contract, server: { name, version }, tools }` where the contract equals the file name and the server name, and every tool has a unique name, a description and an object `inputSchema`."
+    kinds: [check]
+    gates: [land, ci]
+    failureCodes: ["HFS_MCP_TOOLS_SNAPSHOT"]
+    enforcers:
+      - {kind: hfs, id: mcp-tools-snapshot, at: scripts/hfs/rules/mcp-tools.mjs}
+    editions: [lite, full]
+    docs:
+      - {path: docs/hfs-contract-snapshots.md#r302, editions: [lite, full]}
+    templateNa: "The canon emits no MCP catalog: the app commits its server's tools/list result, so there is no scaffolded snapshot."
+    exampleNa: "owner:mcp-tools-snapshot-no-example (2026-10-21): no example app serves an MCP server; the package spec judges a passing and a violating catalog"
+    specNa: "owner:no-runtime-specs (2026-10-17): the enforcer is runtime code with no spec of its own; the @starci/hfs package spec packages/hfs/src/mcp-tools-snapshot.spec.mjs runs it from the bundled copy"
+    witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): the runtime has no spec fixtures; the package spec proves the rule", date: "2026-10-21"}

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.3.0
+version: 3.4.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -38,6 +38,7 @@ versioning:
 # or environment reads (BE_APP_OPTIONS_COMPOSITION). Secrets use EnvSource.secret(): <NAME>_FILE first, plain <NAME> only
 # when the file key is absent; .starcistacks owns custody. Capability <capability>.config.ts roles stay unchanged.
 # 3.3.0 is a minor (alpha.16): it ADDS the optional app.ci-stack-deploy slot, the managed workflow of the starci app stack verbs.
+# 3.4.0 is a minor (alpha.24): it ADDS the opt-in be.contract.mcp-tools slot, the committed MCP tool-catalog snapshot of an app.
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.
@@ -1153,6 +1154,19 @@ slots:
     why: the previously published event contract of a service, the same format as its events.json (copied over when the contract is published, never edited); the current events.json may only extend it additively, a breaking change is a new `<event>.v2` key (R177 BE_CONTRACT_BREAKING)
     rules: [BE_CONTRACT_BREAKING]
 
+  - id: be.contract.mcp-tools
+    since: 3.4.0
+    profiles: [be]
+    path: "contracts/<app>/<contract>.tools.json"
+    presence: opt-in
+    tracked: tracked
+    tier: none
+    tests: none
+    coverage: none
+    why: the MCP tool catalog an app's MCP server publishes at one contract major (`<server>@<major>`), the `tools/list` result its clients rely on, committed as a cross-repo interface; the canon emits no MCP catalog, so its shape is judged (R302 HFS_MCP_TOOLS_SNAPSHOT)
+    exampleNa: "owner:mcp-tools-snapshot-no-example (2026-10-21): no example app serves an MCP server; the package spec judges the shape"
+    rules: [HFS_MCP_TOOLS_SNAPSHOT]
+
   # ----- BE: apps (one slot per app kind; a new kind = a new slot, minor bump) ---------------------------
   # The files of every app (owner ruling 2026-10-14, R245 and R246, since 3.1.0), each with a line budget that
   # BE_APP_COMPOSITION_BUDGET holds absolutely (not a ratchet):

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

@@ -3602,6 +3602,17 @@ HFS_MANIFEST_MAJOR_MISMATCH:
   owner: owner
   kind: check-finding
 
+HFS_MCP_TOOLS_SNAPSHOT:
+  title: "A committed MCP tool catalog has the canonical tools/list shape"
+  title_vi: "Snapshot danh mục tool MCP sai hình dạng chuẩn"
+  meaning_vi: "Tệp `<file>` dưới `be/contracts/<app>/<contract>.tools.json` không phải danh mục tool MCP chuẩn: thiếu app khai báo, `contract` không phải `<server>@<major>` khớp tên tệp và `server.name`, hoặc có tool thiếu tên, mô tả hay `inputSchema` kiểu object, hoặc trùng tên."
+  causes_vi:
+    - "Vi phạm luật R302: snapshot là kết quả `tools/list` của server MCP ở một major hợp đồng, được commit như giao diện giữa các repo."
+    - "Snapshot được chép tay hoặc đặt dưới thư mục của một app không khai báo trong hfs.json"
+  nextStep_vi: "Lấy lại kết quả `tools/list` của server, ghi `{ contract, server: { name, version }, tools }` vào đúng tệp của app phục vụ server đó và khai báo slot `be.contract.mcp-tools` trong `sides.be.optionalSlots`. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
+  owner: op-retry
+  kind: check-finding
+
 HFS_MIN_INSTANCES:
   title: "Fewer instances of a slot than required"
   title_vi: "Số thực thể của ô ít hơn mức tối thiểu"

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "1ac457c26ee05922e910a56fab64d9bdc9b0bc251466dd4a2f341bf698ff3e73",
+  "hash": "c7ef5f72727b2b906b541669c413050b7abd34206c123a87fe90502330271856",
   "global": [
     {
       "name": "json",
@@ -2729,7 +2729,7 @@ export const CATALOG = {
             {
               "name": "changed",
               "type": "list",
-              "summary": "explicit files in the operation slice"
+              "summary": "files added to the slice beside the delta from the base"
             },
             {
               "name": "tests",
@@ -2773,6 +2773,12 @@ export const CATALOG = {
           "impl": {
             "script": "scripts/cli/gate-run.mjs"
           },
+          "conventions": [
+            "the slice is every file that differs from the base (committed, staged, dirty and untracked) plus the --changed files",
+            "--changed extends the slice and never narrows it, so a report cannot hide an edit; narrow it with --base",
+            "the base is --base, else the workflow's previous checkpoint, else the merge-base of HEAD with its upstream or main",
+            "a TypeScript file with no tsconfig.json of its own under a hfs.json sides.<side>.reads tree is checked by that side's programs"
+          ],
           "runtimeSide": "tree"
         },
         "runtime-artifact": {

package/runtime/scripts/hfs/check.mjs

@@ -20,6 +20,7 @@
 //   HFS_CI_MISSING_CANON          (R13, rules/pipeline.mjs) CI without the pinned `starci app check`, pre-push without typecheck or lint
 //   HFS_DEP_VERSION_SKEW          (R14, rules/deps.mjs) a dependency at two versions in the workspace, or a nested copy in the lockfile
 //   HFS_CONTRACT_SNAPSHOT_DRIFT   (R23, rules/contract.mjs) an uncommitted back-end snapshot, or a front-end copy that differs from it
+//   HFS_MCP_TOOLS_SNAPSHOT        (R302, rules/mcp-tools.mjs) a committed MCP tool catalog that is not the canonical `tools/list` snapshot
 //   BE_TEST_TOPOLOGY              (R47, rules/test-topology.mjs) a `.test` file, a testing/ folder, a second jest configuration
 //   FE_NO_TESTS                   (R97, rules/fe-no-tests.mjs) a front end holds a spec, e2e or test-tool file, a test script or a test dependency; no exception
 //   FE_STACK_FORBIDDEN            (rules/fe-stack.mjs) a front-end manifest (the fe side's, or the app root's minus the back end's own libraries)
@@ -72,6 +73,7 @@ import { gitOutputOf } from '../lib/git.mjs';
 import { posixPath } from '../lib/path-key.mjs';
 import { treeFindings } from './tree-findings.mjs';
 import { contractFindings } from './rules/contract.mjs';
+import { mcpToolsSnapshotFindings } from './rules/mcp-tools.mjs';
 import { appRootFindings } from './rules/app-root.mjs';
 import { frontendFindings } from './rules/frontend-tree.mjs';
 import { lintSuppressionFindings } from './rules/lint-suppression.mjs';
@@ -102,7 +104,7 @@ export const CHECK_CODES = Object.freeze([
   'HFS_SLOT_UNDECLARED', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
   'HFS_SLOT_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG', 'BE_SOURCE_FORM',
   'HFS_MANAGED_FILE_DRIFT', 'HFS_TOOL_CONFIG_LOCAL', 'HFS_RULE_OFF_WITHOUT_REPLACEMENT', 'HFS_TS_STRICT',
-  'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT',
+  'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT', 'HFS_MCP_TOOLS_SNAPSHOT',
   'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'HFS_MONO_WORKSPACES', 'HFS_MONO_FE_WORKSPACE', 'HFS_MONO_NEST_PROJECTS', 'HFS_MONO_WORKSPACE_DEP', 'BE_CLI_REQUIRED', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG', 'HFS_SERVICE_PLACEMENT', 'HFS_IMAGE_UNPINNED', 'HFS_SERVICE_STACK_DECLARATION', 'HFS_EVENT_CONTRACT', 'BE_ASYNC_SPEC_MISSING', 'BE_SAGA_STEP_COMPENSATION', 'BE_SAGA_STATE_VERSIONED', 'BE_SAGA_EVENT_CONTRACT', 'BE_SAGA_CONSUMER_DEDUPE', 'BE_EVENT_CLASS_CONTRACT', 'BE_PATTERN_SPEC_MISSING', 'BE_CONTRACT_BREAKING', 'BE_KIND_DECLARATION', 'BE_KIND_EMPTY', 'HFS_DOCKER_BUILD_CONTEXT', 'HFS_DOCKER_STAGES', 'HFS_DOCKER_ENTRY', 'HFS_DOCKER_BASE_PIN', 'HFS_DOCKER_SECRETS', 'BE_SAGA_E2E_MISSING',
   'FE_STACK_FORBIDDEN', 'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_LITE_SECRET_CUSTODY', 'HFS_STARCIWORK_LITE_FORBIDDEN',
   'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'DB_CONFIG_POLICY', 'DB_TYPES_DRIFT',
@@ -220,7 +222,7 @@ function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pin
       ...checkAppRoot({ root: repoRoot, resolver, tree: trackedTreeView(all) }).violations.map((item) => ({ code: item.ruleId, level: 'error', path: item.path, line: item.line, column: item.column, source: 'machine', message: `${item.path}: ${item.message}` })),
     );
   } else if (repo.profile === 'be') {
-    findings.push(...contractFindings({ repoRoot, files, repo, resolver }), ...testTopologyFindings({ repoRoot, files }));
+    findings.push(...contractFindings({ repoRoot, files, repo, resolver }), ...mcpToolsSnapshotFindings({ repoRoot, files, repo }), ...testTopologyFindings({ repoRoot, files }));
   } else {
     findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter((file) => inScope(file)) }));
   }

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

@@ -392,8 +392,15 @@ function sourceNames(ts, text, file) {
   return names;
 }
 
+/**
+ * Whether a be/src source references a destroyed object. A column (`<schema>.<table>.<column>`) is referenced only by a source that
+ * names both its table and the column, so a same-named column of another table is not a reference; the check stays conservative,
+ * since any mention of the table beside the column counts. Every other object kind is referenced by its leaf name.
+ */
+const referencesObject = (names, object) => names.has(object.leaf) && (object.kind !== 'column' || !object.table || names.has(object.table));
+
 function destructiveObjectFinding(file, object, contract, references) {
-  const reference = references.find(({ names }) => names.has(object.leaf));
+  const reference = references.find(({ names }) => referencesObject(names, object));
   if (contract && !reference) return null;
   const reason = reference && contract ? `${reference.file} still references this object; remove the reference before the contract migration`
     : 'use a *_contract_* migration after the application stops using this object';

package/runtime/scripts/hfs/rules/mcp-tools.mjs

@@ -0,0 +1,63 @@
+// mcp-tools.mjs - HFS_MCP_TOOLS_SNAPSHOT (R302): the committed MCP tool-catalog snapshot of an app has the canonical shape.
+// An app that serves an MCP server commits the catalog its clients rely on at `contracts/<app>/<contract>.tools.json` (slot
+// be.contract.mcp-tools): `{ contract: "<server>@<major>", server: { name, version }, tools: [{ name, description, inputSchema, ... }] }`,
+// the `tools/list` result of the server at that contract major. The canon emits no MCP catalog, so the check is the shape: the
+// file names a declared be app and its own contract, the contract is the server name at an integer major, every tool has a unique
+// name, a description and an object input schema. A file that is not JSON is a finding too.
+import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
+import { found, readText } from './read.mjs';
+
+const MCP_TOOLS_SNAPSHOT = 'HFS_MCP_TOOLS_SNAPSHOT';
+const SNAPSHOT = /^contracts\/([^/]+)\/([^/]+)\.tools\.json$/u;
+const CONTRACT = /^([a-z][a-z0-9-]*)@([1-9]\d*)$/u;
+
+const text = (value) => typeof value === 'string' && value.trim() !== '';
+
+/** The shape problems of one tool entry at index `index`, given the names already seen. */
+function toolProblems(tool, index, seen) {
+  if (!plain(tool)) return [`tools[${index}] is not an object`];
+  const at = text(tool.name) ? `tool ${tool.name}` : `tools[${index}]`;
+  const problems = [];
+  if (!text(tool.name)) problems.push(`${at} has no name`);
+  else if (seen.has(tool.name)) problems.push(`${at} is listed twice`);
+  else seen.add(tool.name);
+  if (!text(tool.description)) problems.push(`${at} has no description`);
+  if (!plain(tool.inputSchema) || tool.inputSchema.type !== 'object') problems.push(`${at} has no inputSchema of type object`);
+  return problems;
+}
+
+/** The shape problems of a parsed snapshot whose file stem is `stem`. */
+function snapshotProblems(doc, stem) {
+  if (!plain(doc)) return ['is not a JSON object'];
+  const problems = [];
+  const contract = CONTRACT.exec(String(doc.contract ?? ''));
+  if (!contract) problems.push('contract is not `<server>@<major>` (a kebab-case server name and an integer major from 1)');
+  else if (doc.contract !== stem) problems.push(`contract ${doc.contract} differs from the file name ${stem}.tools.json`);
+  if (!plain(doc.server) || !text(doc.server.name) || !text(doc.server.version)) problems.push('server has no name and version');
+  else if (contract && doc.server.name !== contract[1]) problems.push(`server.name ${doc.server.name} differs from the contract server ${contract[1]}`);
+  if (!Array.isArray(doc.tools) || doc.tools.length === 0) return [...problems, 'tools is not a non-empty list'];
+  const seen = new Set();
+  return [...problems, ...doc.tools.flatMap((tool, index) => toolProblems(tool, index, seen))];
+}
+
+/** The findings of R302 for the be side at `repoRoot` (be-relative `files`, the side view `repo`). */
+export function mcpToolsSnapshotFindings({ repoRoot, files, repo }) {
+  if (repo.profile !== 'be') return [];
+  const apps = new Set((repo.apps ?? []).map((app) => app.name));
+  const findings = [];
+  for (const file of files) {
+    const match = SNAPSHOT.exec(file);
+    if (!match) continue;
+    const [, app, stem] = match;
+    const fix = 'commit the server\'s `tools/list` result as `{ contract: "<server>@<major>", server: { name, version }, tools: [...] }`';
+    if (!apps.has(app)) {
+      findings.push(found(MCP_TOOLS_SNAPSHOT, file, `${file} belongs to no be app: ${app} is not declared in hfs.json sides.be.apps; a tool catalog lives under contracts/<app>/ of the app that serves it`, { app }));
+      continue;
+    }
+    let doc;
+    try { doc = JSON.parse(readText(repoRoot, file) ?? ''); } catch { doc = undefined; }
+    const problems = doc === undefined ? ['is not readable JSON'] : snapshotProblems(doc, stem);
+    if (problems.length) findings.push(found(MCP_TOOLS_SNAPSHOT, file, `${file} is not a canonical MCP tool catalog: ${problems.join('; ')}; ${fix}`, { app, problems }));
+  }
+  return findings;
+}