@starci/hfs 4.4.0 → 4.5.0

package/release/index.mjs

@@ -1,12 +1,13 @@
 // index.mjs - `starci app release <gate|push>` and the plumbing the release and database verbs share: the context built from the app's IO, strict flag
 // parsing, the optional `release:` / `database:` blocks of .starcistacks/application-stacks.yaml, text and --json output and the exit-code mapping.
-//   starci app release gate [--execute] [--source <ref>] [--tag-prefix <prefix>] [--json]
+//   starci app release gate [--execute] [--sonar] [--source <ref>] [--tag-prefix <prefix>] [--json]
 //   starci app release push [--execute] [--remote <name>] [--json]
 // Every action is a dry run unless --execute is given. A refusal is a StackError (exit 2); a failed step returns ok false (exit 1).
 import fs from 'node:fs';
 import path from 'node:path';
 import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { STACKS_DIR, STACKS_FILE } from '../stack/config.mjs';
 import { stackContext } from '../stack/context.mjs';
 import { EXIT, StackError, refusal } from '../stack/errors.mjs';
@@ -22,7 +23,7 @@ export function contextOf(io = {}) {
 }
 
 /** Splits argv into { flags, positional }; an unknown flag or a flag without its value is a refusal. */
-export function parseVerbFlags(argv, spec, code = 'RELEASE_USAGE') {
+function parseVerbFlags(argv, spec, code = 'RELEASE_USAGE') {
   const flags = {};
   const positional = [];
   for (let index = 0; index < argv.length; index += 1) {
@@ -53,10 +54,11 @@ function readPackage(root) {
 }
 
 /** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, tagMatchesVersion }. */
-export function loadReleaseConfig(root) {
+function loadReleaseConfig(root) {
   const pkg = readPackage(root);
   if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version)) throw refusal(RELEASE_CODE, 'package.json needs a version like 1.2.3 (the release tag derives from it)');
-  const { config, problems } = normalizeRelease(readDeclaration(root).release, pkg.scripts);
+  const declaration = readDeclaration(root);
+  const { config, problems } = normalizeRelease(declaration.release, pkg.scripts, declaration.services, { example: isRuntimeExampleApp(root) });
   if (!config) throw refusal(RELEASE_CODE, `${problems.length} problem(s) in release: ${problems.slice(0, 6).join('; ')}`);
   return { root, version: pkg.version, ...config };
 }
@@ -83,8 +85,8 @@ export async function runVerb({ label, name, io, argv, spec, run, code = 'RELEAS
 
 const ACTIONS = {
   gate: {
-    spec: { boolean: ['--execute', '--json'], value: ['--source', '--tag-prefix'] },
-    run: (ctx, flags) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), { execute: flags.execute === true, source: flags.source, tagPrefix: flags['tag-prefix'] }),
+    spec: { boolean: ['--execute', '--json', '--sonar'], value: ['--source', '--tag-prefix'] },
+    run: (ctx, flags) => releaseGate(ctx, loadReleaseConfig(ctx.cwd), { execute: flags.execute === true, sonar: flags.sonar === true, source: flags.source, tagPrefix: flags['tag-prefix'] }),
   },
   push: {
     spec: { boolean: ['--execute', '--json'], value: ['--remote'] },

package/release/push.mjs

@@ -17,7 +17,7 @@ const greenRecord = (record, head, tag) => record?.head === head && record?.tag
   && Array.isArray(record.gates) && record.gates.length > 0 && record.gates.every((gate) => gate?.pass === true);
 
 /** The release gate as the hook reads it: the annotated tag on HEAD whose L4 record names head and tag. Returns { tag } or { reason }. */
-export function gateState(ctx, head, prefix) {
+function gateState(ctx, head, prefix) {
   const tags = annotatedOnHead(ctx, prefix);
   if (tags.length === 0) return { reason: `no ANNOTATED tag ${prefix}[0-9]* on HEAD: run starci app release gate --execute first` };
   const file = path.join(releaseDir(ctx), `${head}.l4.json`);

package/report/sonar.mjs

@@ -50,7 +50,7 @@ export function mergeReports(reports) {
  * indexes, and a finding about hfs.json, a workflow, a config file or a directory is not on one, so it is filed on this
  * file and its message names the real path. Null when the tracked tree has no source file.
  */
-export function anchorOf(tracked, sourceRoots) {
+function anchorOf(tracked, sourceRoots) {
   const roots = sourceRoots.map((root) => `${posix(root).replace(/\/$/, '')}/`);
   return [...tracked].map(posix).filter((file) => SOURCE_FILE.test(file) && roots.some((root) => file.startsWith(root))).sort(cmp)[0] ?? null;
 }

package/runtime/config.example.yaml

@@ -185,10 +185,11 @@ sonar: {organization: null}
 #   minFreeRamPct  free-RAM percentage below which no new heavy op starts
 # set them only in the gitignored config.yaml copy, e.g.
 #   resources: {minFreeDiskGb: 5, minFreeDiskPct: 1, minFreeRamPct: 10}
-# release — where the full test suite of a release is judged (scripts/guards/release-suite-mode.mjs; docs/releasing.md "Where the suite runs"). One key:
-#   suite: local   the shipped default: `starci release cut` runs the root suite and the Linux parity container before it pushes, and the pre-push gate asks for their green rows
-#   suite: ci      the owner's recorded choice (2026-10-09): no local full suite and no Linux container; the GitHub ci workflow runs the suite (with coverage, Codecov, SonarCloud) AFTER the push.
-#                  The cut still runs npm run check, npm run test:packages, the specs affected by the release, the live Orca smokes and the example apps; the record lists the root suite as
-#                  delegated, never green. A release can reach GitHub and its tag before the suite has run; a red CI is fixed forward with the next pre-release (starci release ci-status).
-# "none" is refused: the suite does not vanish, it moves to CI. Set it only in the gitignored config.yaml copy: release: {suite: ci}
+# release - where the Linux parity of a release is judged (scripts/guards/release-suite-mode.mjs; docs/releasing.md "Where the suite runs"). One key:
+#   suite: local   the shipped default: `starci release cut` runs the root rows (npm run test:packages, npm run test:e2e, npm run check) and the Linux parity container before it pushes,
+#                  and the pre-push gate asks for the green root rows
+#   suite: ci      the owner's recorded choice (2026-10-09): no local Linux container; the GitHub ci workflow runs the Linux parity (and SonarCloud) AFTER the push.
+#                  The cut still runs the same root rows and the example apps; the record lists linux-parity as delegated, never green.
+#                  A release can reach GitHub and its tag before the Linux parity has run; a red CI is fixed forward with the next pre-release (starci release ci-status).
+# "none" is refused: the Linux parity does not vanish, it moves to CI. Set it only in the gitignored config.yaml copy: release: {suite: ci}
 release: {suite: local}

package/runtime/engine/config.mjs

@@ -9,7 +9,7 @@ import {validateSonar} from './sonar-config.mjs';
 import {validateRelease,RELEASE_KEYS} from './release-config.mjs';
 import {validateOrca,ORCA_KEYS} from './orca-config.mjs';
 import {validateResources,RESOURCE_KEYS} from './resources-config.mjs';
-import {ENV_NAME,secretEnv,connectorSecret} from './secrets.mjs';
+import { ENV_NAME, connectorSecret } from './secrets.mjs';
 import {byCodeUnit} from './by-code-unit.mjs';
 import {EFFORT_LEVELS,MODELS_KEYS,validateModelsBlock,refuseRemovedKeys,shippedTiers} from './model-config.mjs';
 const knownNames=names=>[...names].sort(byCodeUnit).join(', ');
@@ -162,8 +162,6 @@ function validateConnectors(connectors){
   if(connectors.cloudflare!==undefined)validateCloudflareConnector(connectors.cloudflare);
   if(connectors.telegram!==undefined)validateTelegramConnector(connectors.telegram);
 }
-/** Load connector credentials from the explicitly verified runtime main; never print the returned environment. */
-export function connectorEnv(config,env=process.env,verifiedRuntimeRoot=undefined){return secretEnv(verifiedRuntimeRoot,env);}
 /**
  * The normalized `connectors` block: defaults filled in, the secrets' PRESENCE (booleans, never values),
  * whether each connector is ready to run, and the owner-facing warnings the security posture earns.
@@ -243,8 +241,8 @@ export function uatSettings(config=loadConfig()){
 const GRANT=/^([a-z0-9][a-z0-9.-]*)=(\d+)@([a-z]+(?:\+[a-z]+)*)$/;
 /** One grant string `<pool>=<slots>@<role>+<role>` as {pool, slots, roles}, or null when it is not that shape. */
 /** The closed set of top-level config.yaml blocks: the validator accepts these and refuses every other key. */
-export const CONFIG_BLOCKS=Object.freeze(['language','model','effort','models','allocation','kernel','budgets','supervisor','parallel','delegation','connectors','asks','uat','specs','reconciler','debugLoop','orca','roots','resources','sonar','release','launchTrust','retention']);
-export function parseAllocationGrant(text){
+const CONFIG_BLOCKS=Object.freeze(['language','model','effort','models','allocation','kernel','budgets','supervisor','parallel','delegation','connectors','asks','uat','specs','reconciler','debugLoop','orca','roots','resources','sonar','release','launchTrust','retention']);
+function parseAllocationGrant(text){
   const m=typeof text==='string'?GRANT.exec(text.trim()):null;
   return m?{pool:m[1],slots:Number(m[2]),roles:m[3].split('+')}:null;
 }
@@ -327,7 +325,7 @@ const validateEarlyConfigBlocks=(config)=>{
   if(config?.orca!==undefined){validateOrca(config.orca);} if(config?.roots!==undefined){validateRoots(config.roots);} if(config?.resources!==undefined){validateResources(config.resources);} if(config?.sonar!==undefined){validateSonar(config.sonar);} if(config?.release!==undefined){validateRelease(config.release);}
 };
 const validateConfigBlocks=(config,knownProviders,runtimes,profile)=>{
-  // specs (owner 2026-09-28): {harness?, unit?, e2e?} booleans - each family a boolean; absent = its default (SPEC_DEFAULTS: harness off, unit on, e2e off; specsSettings).
+  // specs (owner 2026-09-28): {unit?, e2e?} booleans - each family a boolean; absent = its default (SPEC_DEFAULTS: unit on, e2e off; specsSettings).
   if(config?.specs!==undefined&&config.specs!==null&&(!plain(config.specs)||Object.keys(config.specs).some(key=>!CONFIG_KEY_TREE.specs.includes(key)||typeof config.specs[key]!=='boolean')))throw new Error(`Invalid config.yaml: specs must be {${SPEC_FAMILIES.map(k=>k+'?: boolean').join(', ')}}, or null.`);
   // reconciler (scripts/reconciler/state.mjs reconcilerConfig): {enabled?: boolean, profile?: operational|observe, controllers?: {<name>: {mode: off|shadow|active}}}, or null.
   if(config?.reconciler!==undefined&&config.reconciler!==null){validateReconcilerBlock(config.reconciler);} if(config?.allocation!==undefined){validateAllocationBlock(config.allocation,runtimes);}
@@ -356,8 +354,8 @@ export function configuredAllocationPolicy(config=loadConfig()){
     :null;
   return {grants,source:allocation?'allocation':'default'};
 }
-/** The variable that confines the owner's `config.yaml` to a directory tree: set, an owner file is read only from under that directory (tests/setup/isolated-temp.mjs points it at a spec's own temp root). */
-export const OWNER_CONFIG_WITHIN_ENV='STARCI_OWNER_CONFIG_WITHIN';
+/** The variable that confines the owner's `config.yaml` to a directory tree: set, an owner file is read only from under that directory (e2e/setup/isolated-temp.mjs points it at a spec's own temp root). */
+const OWNER_CONFIG_WITHIN_ENV='STARCI_OWNER_CONFIG_WITHIN';
 const foldPath=p=>process.platform==='win32'?path.resolve(p).toLowerCase():path.resolve(p);
 /**
  * Whether the owner's `config.yaml` under `root` is visible to this process. Unconfined (the variable unset) every owner file is visible; confined, only the files under the named
@@ -398,31 +396,25 @@ export function inspectOwnerConfig(root=configRoot){
 }
 /**
  * The owner's spec switches (config.yaml root `specs`, owner 2026-09-28; defaults set 2026-09-29, none needs a config block):
- *   harness - .claude's own specs. Default false = touching-only: harness work writes and runs the specs of new or changed code
- *             and the land gate runs only the specs touching the landed files (`land.mjs --specs touching`, its default);
- *             the whole suite never runs in a land - `--specs all` is refused unless this is true. The full suite runs in
- *             the owner-approved /starci release flow (scripts/supervisor/release-cut.mjs), which needs no key. true = `--specs all` may run;
  *   unit    - product unit specs in workflows. Default on: a code-writing op writes/updates the unit specs of the source it
  *             adds or changes and runs only those; the full unit suite is unit.verify's or the approved /starci release flow's. false = the ops'
  *             policy.specsToggle deferral path (scripts/route/spec-deferral.mjs);
  *   e2e     - product e2e in workflows. Default OFF: e2e runs only when the goal or the owner explicitly asks (set true,
  *             or `starci kernel run-deferred-tests`); e2e.verify then runs the FULL e2e suite.
- * An absent, null or unreadable owner file reads as the defaults: harness off, unit on, e2e off.
+ * An absent, null or unreadable owner file reads as the defaults: unit on, e2e off. The runtime itself has no specs (owner ruling no-runtime-specs), so there is no switch for them.
  */
-const SPEC_FAMILIES=Object.freeze(['harness','unit','e2e']);
+const SPEC_FAMILIES=Object.freeze(['unit','e2e']);
 const SEAT_KEYS=Object.freeze(['agent','model','effort']);
 /** The keys each config block accepts directly under it (the validators read these lists; docs/config-format.md and the example are checked against them). Blocks whose keys are open or deeper than this are not listed. */
-export const CONFIG_KEY_TREE=Object.freeze({
+const CONFIG_KEY_TREE=Object.freeze({
   models:MODELS_KEYS,allocation:Object.freeze(['grants']),kernel:SEAT_KEYS,budgets:Object.freeze(['maxOps']),parallel:Object.freeze(['gear']),
   supervisor:Object.freeze(['mode','pollIntervalMs','repos','stallMinutes','kernel','workers','landGate','frozenMinutes']),
   delegation:Object.freeze(['asks','until','excludes','note']),asks:Object.freeze(['autoAcceptRecommended','excludes']),uat:Object.freeze(['maxConcurrent']),
   specs:SPEC_FAMILIES,reconciler:Object.freeze(['enabled','profile','controllers']),debugLoop:Object.freeze(['interval','worktreeLimit']),
   orca:ORCA_KEYS,roots:ROOT_KEYS,resources:RESOURCE_KEYS,release:RELEASE_KEYS,
 });
-export const SPEC_DEFAULTS=Object.freeze({harness:false,unit:true,e2e:false});
+export const SPEC_DEFAULTS=Object.freeze({unit:true,e2e:false});
 export function specsSettings(config){const specs=plain(config?.specs)?config.specs:{};return Object.fromEntries(SPEC_FAMILIES.map(key=>[key,typeof specs[key]==='boolean'?specs[key]:SPEC_DEFAULTS[key]]));}
-/** specs.harness of the owner file under `root` (tolerant read: inspectOwnerConfig): true only when the owner opted in to `--specs all`. */
-export function harnessSpecsEnabled(root=configRoot){return specsSettings(inspectOwnerConfig(root).config).harness;}
 /**
  * config.yaml `debugLoop` (skills/starci, scripts/debug/digest): {interval?, worktreeLimit?}, each optional.
  *   interval       <n>s | <n>m | <n>h — the cadence of the chat /loop that runs `starci debug digest`.

package/runtime/engine/removed-vocabulary.mjs

@@ -12,8 +12,6 @@ function loaded(){
   return cache.doc;
 }
 
-/** The kinds a removed spelling has. */
-export const removedKinds=()=>loaded().kinds;
 
 /** modules/kernel/removed-vocabulary.yaml: the one list of spellings the runtime refuses, each with its replacement and the release that removed it. */
 export const removedVocabulary=()=>loaded().removed;

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.0
+    version: 3.4.2
     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.0
+    version: 8.4.2
     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.4.0
+    version: 1.5.0
     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.4.0
+    version: 4.5.0
     group: starci
     install: registry
     side: both