@starci/hfs 4.2.17 → 4.4.0

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

@@ -1,15 +1,16 @@
 // edition.mjs - L01, the edition rule. An hfs.json edition is `full` or `lite` (absent means full); under lite the standard is a
-// filter plus a few additions over the same manifest, never a second engine. Lite is the full architecture deployed without
-// self-hosted infrastructure (owner ruling 2026-10-12): the same slots, patterns and unit specs, Supabase adapters behind the same
-// ports, and no e2e or contract world. The slot layer already answers the paths lite removed (slots lite excludes, or whose
-// litePresence is forbidden, come back HFS_FORBIDDEN_PRESENT with their goesTo); this rule reports what no path can state:
-//   - inside a package.json: an e2e, contract, stack or browser script (`test:e2e`, `test:contract`, `test:stack`, `test:browser`,
+// filter plus a few additions over the same manifest, never a second engine. Lite declares Docker Swarm production infrastructure
+// (owner:lite-production-swarm, ruling:R212/case-4): the same slots, patterns and unit specs, provider adapters behind the same
+// ports, optional contract specs, and no e2e world (owner:lite-contract-specs). The slot layer already answers the paths lite
+// removed (slots lite excludes, or whose litePresence is forbidden, come back HFS_FORBIDDEN_PRESENT with their goesTo);
+// this rule reports what no path can state:
+//   - inside a package.json: an e2e, stack or browser script (`test:e2e`, `test:stack`, `test:browser`,
 //     with a pre/post prefix too) or a dependency of the infrastructure lite does not run - a test-world container or proxy
 //     (testcontainers, toxiproxy) or a browser runner (playwright, cypress), and every library the lite infraOwners own nowhere
 //     while full owns them (BullMQ, Kafka, Redis: lite runs pgmq and Postgres locks instead);
 //   - a declaration of what lite does not have: an app kind, pattern or trigger kind every slot of which is forbidden under
 //     lite. The forbidden names are DERIVED from the manifest, so adding or restoring a kind is a manifest edit, not an edit here
-//     (under the 2026-10-12 ruling no pattern, trigger or app kind is gone).
+//     (under the 2026-10-13 ruling no pattern, trigger or app kind is gone).
 // A full app answers []: the rule tests the edition once and a full view forbids none of these names.
 import { found, readJson } from './read.mjs';
 import { DEPENDENCY_SECTIONS } from './fe-no-tests.mjs';
@@ -18,8 +19,8 @@ import { editionRuleParams } from '../edition-slots.mjs';
 export const HFS_EDITION_FORBIDDEN_PRESENT = 'HFS_EDITION_FORBIDDEN_PRESENT';
 
 const PACKAGE_JSON = /(?:^|\/)package\.json$/;
-/** The scripts of a world lite does not have: the e2e and contract layers, the self-hosted stack and the browser journey. */
-const LITE_FORBIDDEN_SCRIPT = /^(?:pre|post)?test:(?:e2e|contract|stack|browser)$/;
+/** The scripts of a world lite does not have: the e2e layer, the self-hosted stack and the browser journey. */
+const LITE_FORBIDDEN_SCRIPT = /^(?:pre|post)?test:(?:e2e|stack|browser)$/;
 /** The dependencies of a test infrastructure lite does not run: containers, fault proxies and browser runners. */
 const LITE_FORBIDDEN_TEST_INFRA = /^(?:testcontainers|@testcontainers\/.+|toxiproxy-node-client|playwright|playwright-core|@playwright\/.+|cypress)$/;
 
@@ -68,7 +69,7 @@ function scriptFindings(rel, pkg) {
   const scripts = isPlainObject(pkg.scripts) ? pkg.scripts : {};
   return Object.keys(scripts)
     .filter((name) => LITE_FORBIDDEN_SCRIPT.test(name))
-    .map((name) => found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} has script ${JSON.stringify(name)}: a lite app has unit specs and optional integration specs on the local Supabase stack, never an e2e, contract, stack or browser run`, { name }));
+    .map((name) => found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} has script ${JSON.stringify(name)}: a lite app has unit specs, optional integration specs on the local Supabase stack and optional contract specs, never an e2e, stack or browser run`, { name }));
 }
 
 function dependencyFindings(rel, pkg, removed) {
@@ -78,7 +79,7 @@ function dependencyFindings(rel, pkg, removed) {
     if (!isPlainObject(deps)) continue;
     for (const name of Object.keys(deps)) {
       if (LITE_FORBIDDEN_TEST_INFRA.test(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: a lite app runs no test containers, fault proxy or browser journey - its integration specs run against \`supabase start\``, { section, name }));
-      else if (removed.has(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: lite runs no self-hosted infrastructure - the pattern's port is implemented on Supabase (pgmq, Postgres locks)`, { section, name }));
+      else if (removed.has(name)) findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: lite replaces backing infrastructure with Supabase - the pattern's port is implemented on Supabase (pgmq, Postgres locks)`, { section, name }));
     }
   }
   return findings;

package/runtime/scripts/hfs/rules/env-parity.mjs

@@ -0,0 +1,373 @@
+// env-parity.mjs - R248 HFS_ENV_PARITY (OPS K5/K11): the environment keys a back end reads, the
+// keys sealed under `.starcistacks/<env>/secrets/*.enc` and the keys the stack declares or passes are one set,
+// compared by name only (owner ruling 0.1.7: every back-end app reads its environment only through the typed
+// `EnvSource` of `<app>.env.ts` and the capability `*.config.ts` parse helpers).
+//   R = keys the typed `EnvSource` readers consume, found by a static TypeScript walk of `*.env.ts`, `*.config.ts`
+//       and `apps/<app>/src/main.ts`: `env.string|url|enum|secret` and `env.int|bool|duration` without a literal
+//       fallback are required reads; `env.optional`, `env.has`, `env.anyDeclared` and a fallback read are optional.
+//       A template key `${prefix}_WEBHOOK_SECRET` resolves through the literal arguments of its reader's call sites
+//       (`parseWebhookProviderConfig(env, "CALENDAR")` yields the key CALENDAR_WEBHOOK_SECRET).
+//   S = the key names of the sealed members: a sops envelope keeps its key names cleartext, so `envelopeOf` answers
+//       them without decrypting anything.
+//   D = keys declared as public config or passed by the stack: the backticked names of
+//       `.starcistacks/<env>/runtime/env/KEYS.md`, and the `environment:`/`env:` entries, `runtimeSecrets`, `secrets`
+//       and `vars[].name` of every `.starcistacks` yaml. A `<KEY>_FILE` name declares `<KEY>`.
+// Findings: ENV_REQUIRED_UNSET a required read sits in neither S nor D; ENV_SEALED_UNREAD a sealed key sits in
+// neither R nor a declared consumer; ENV_DUPLICATE one key in two members of one environment; ENV_PUBLIC_SEALED a NEXT_PUBLIC_* key in
+// custody; ENV_EXAMPLE_DRIFT a `*.env.example` key nothing reads. The rule judges the app root (`isRoot`): the whole
+// tree `all` is its input, both editions.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { envelopeOf } from '../secret-document.mjs';
+import { found, readText } from './read.mjs';
+
+export const ENV_REQUIRED_UNSET = 'ENV_REQUIRED_UNSET';
+export const ENV_SEALED_UNREAD = 'ENV_SEALED_UNREAD';
+export const ENV_DUPLICATE = 'ENV_DUPLICATE';
+export const ENV_PUBLIC_SEALED = 'ENV_PUBLIC_SEALED';
+export const ENV_EXAMPLE_DRIFT = 'ENV_EXAMPLE_DRIFT';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ENV_SOURCE = /(?:\.env|\.config)\.ts$/u;
+const APP_MAIN = /(?:^|\/)apps\/[^/]+\/src\/main\.ts$/u;
+const SEALED_MEMBER = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc$/u;
+const KEYS_ROSTER = /^\.starcistacks\/[^/]+\/runtime\/env\/KEYS\.md$/u;
+const STACK_YAML = /^\.starcistacks\/.+\.ya?ml$/u;
+const ENV_EXAMPLE = /\.env\.example$/u;
+const PUBLIC_PREFIX = /^NEXT_PUBLIC_/u;
+const KEY_NAME = /^[A-Za-z_]\w*$/u;
+const FILE_SUFFIX = /_FILE$/u;
+const EXAMPLE_LINE = /^[ \t]*(?:export[ \t]+)?([A-Za-z_]\w*)[ \t]*=(.*)$/u;
+const ROSTER_KEY = /`([A-Za-z_][A-Za-z0-9_]*)`/gu;
+
+const REQUIRED_ALWAYS = new Set(['string', 'url', 'secret', 'enum']);
+const FALLBACK_OPTIONAL = new Set(['int', 'bool', 'duration']);
+const OPTIONAL_ONLY = new Set(['optional', 'has', 'anyDeclared']);
+const READER_METHODS = new Set([...REQUIRED_ALWAYS, ...FALLBACK_OPTIONAL, ...OPTIONAL_ONLY]);
+
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+/** A path the static walk reads: `<app>.env.ts`, `<capability>.config.ts` or an app `main.ts`. */
+export const isEnvSourcePath = (file) => ENV_SOURCE.test(file) || APP_MAIN.test(file);
+
+/** The `KEY=value` entries of one `*.env.example` text, comments and blank lines out, quotes unwrapped. */
+export function envExampleEntries(text) {
+  const entries = [];
+  for (const line of String(text).split(/\r?\n/u)) {
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const match = EXAMPLE_LINE.exec(line);
+    if (!match) continue;
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    entries.push({ key: match[1], value });
+  }
+  return entries;
+}
+
+/** The literal key or template parts a key argument holds; null when it is not statically a name. */
+function keyParts(ts, node, params) {
+  if (ts.isStringLiteralLike(node)) return [node.text];
+  if (!ts.isTemplateExpression(node)) return null;
+  const parts = [node.head.text];
+  for (const span of node.templateSpans) {
+    if (!ts.isIdentifier(span.expression) || !params.includes(span.expression.text)) return null;
+    parts.push({ param: span.expression.text }, span.literal.text);
+  }
+  return parts;
+}
+
+/** The env reader context of a function: its EnvSource-typed (or bare `env`) parameter, or null. */
+function envContextOf(ts, sourceFile, node) {
+  const params = node.parameters ?? [];
+  const names = params.map((param) => (ts.isIdentifier(param.name) ? param.name.text : null));
+  const index = params.findIndex((param, i) => names[i] !== null
+    && (param.type?.getText(sourceFile) === 'EnvSource' || (param.type === undefined && names[i] === 'env')));
+  if (index === -1) return null;
+  let fn = null;
+  if (node.name && ts.isIdentifier(node.name)) fn = node.name.text;
+  else if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) fn = node.parent.name.text;
+  return { envParam: names[index], params: names.filter(Boolean), fn };
+}
+
+const isFunction = (ts, node) => ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node);
+
+/** The shape a reader method declares: `{kind}` for the typed readers, `{kind:'enum', allowed}` for env.enum, null else. */
+function shapeOf(ts, method, args) {
+  if (method === 'enum') {
+    const list = args[1];
+    if (!list || !ts.isArrayLiteralExpression(list)) return null;
+    const allowed = list.elements.map((element) => (ts.isStringLiteralLike(element) ? element.text : null));
+    return allowed.every((value) => value !== null) ? { kind: 'enum', allowed } : null;
+  }
+  const kind = { string: 'string', secret: 'string', int: 'int', bool: 'bool', url: 'url', duration: 'duration' }[method] ?? null;
+  return kind === null ? null : { kind };
+}
+
+function noteReadParts(ctx, parts, entry, literals, templates) {
+  if (parts === null) return;
+  if (parts.every((part) => typeof part === 'string')) literals.push({ key: parts.join(''), ...entry });
+  else templates.push({ ...ctx, parts, ...entry });
+}
+
+function readAnyDeclared(ts, ctx, keyArg, entry, literals, templates) {
+  if (!keyArg || !ts.isArrayLiteralExpression(keyArg)) return;
+  const optionalEntry = { ...entry, required: false, shape: null };
+  for (const element of keyArg.elements) {
+    const parts = ts.isStringLiteralLike(element) ? [element.text] : keyParts(ts, element, ctx.params);
+    noteReadParts(ctx, parts, optionalEntry, literals, templates);
+  }
+}
+
+/** One `env.<method>(...)` call of context `ctx` as a read entry; `required` follows the reader's fallback contract. */
+function readCall(ts, ctx, node, file, literals, templates) {
+  const method = node.expression.name.text;
+  const args = [...node.arguments];
+  const required = REQUIRED_ALWAYS.has(method) || (FALLBACK_OPTIONAL.has(method) && args.length < 2);
+  const entry = { method, required, shape: required || FALLBACK_OPTIONAL.has(method) ? shapeOf(ts, method, args) : null, file };
+  const keyArg = args[0];
+  if (method === 'anyDeclared') {
+    readAnyDeclared(ts, ctx, keyArg, entry, literals, templates);
+    return;
+  }
+  const parts = keyArg === undefined ? null : keyParts(ts, keyArg, ctx.params);
+  noteReadParts(ctx, parts, entry, literals, templates);
+}
+
+/** Every env read of one parsed file: concrete literals, per-reader templates and every named call site. */
+function readsInFile(ts, sourceFile, rel) {
+  const literals = [];
+  const templates = [];
+  const calls = [];
+  const walk = (node, ctx) => {
+    if (isFunction(ts, node)) ctx = envContextOf(ts, sourceFile, node) ?? ctx;
+    if (ts.isCallExpression(node)) {
+      if (ctx && ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.expression)
+        && node.expression.expression.text === ctx.envParam && READER_METHODS.has(node.expression.name.text)) {
+        readCall(ts, ctx, node, rel, literals, templates);
+      } else if (ts.isIdentifier(node.expression)) {
+        calls.push({ name: node.expression.text, args: node.arguments.map((arg) => (ts.isStringLiteralLike(arg) ? arg.text : null)), file: rel });
+      }
+    }
+    ts.forEachChild(node, (child) => walk(child, ctx));
+  };
+  walk(sourceFile, null);
+  return { literals, templates, calls };
+}
+
+function noteEnvRead(reads, { key, required, shape, file }) {
+  const held = reads.get(key);
+  if (!held) { reads.set(key, { key, required, shape, file }); return; }
+  held.required = held.required || required;
+  held.shape = held.shape ?? shape;
+}
+
+function noteReaderTemplates(readers, templates) {
+  for (const template of templates) {
+    if (!template.fn) continue;
+    if (!readers.has(template.fn)) readers.set(template.fn, { params: template.params, templates: [] });
+    readers.get(template.fn).templates.push(template);
+  }
+}
+
+function resolvedTemplateRead(reader, template, call) {
+  const parts = template.parts.map((part) => {
+    if (typeof part === 'string') return part;
+    const arg = call.args[reader.params.indexOf(part.param)];
+    return typeof arg === 'string' ? arg : null;
+  });
+  if (parts.includes(null)) return null;
+  return { key: parts.join(''), required: template.required, shape: template.shape, file: call.file };
+}
+
+function noteReaderCall(reads, readers, call) {
+  const reader = readers.get(call.name);
+  if (!reader) return;
+  for (const template of reader.templates) {
+    const read = resolvedTemplateRead(reader, template, call);
+    if (read !== null) noteEnvRead(reads, read);
+  }
+}
+
+/**
+ * The keys the repository's EnvSource readers consume: Map `KEY` -> {key, required, shape, file}. `relPaths` are
+ * repository-relative paths; the env source files (`isEnvSourcePath`) among them are walked. `ts` is the caller's
+ * already-resolved compiler; null when none resolves, so the caller decides what "cannot be judged" means.
+ */
+export function collectEnvReads(repoRoot, relPaths, ts = typescriptFor(repoRoot)) {
+  if (!ts) return null;
+  const reads = new Map();
+  const readers = new Map();
+  const calls = [];
+  for (const rel of relPaths.filter(isEnvSourcePath)) {
+    const text = readText(repoRoot, rel);
+    if (text === null) continue;
+    const foundIn = readsInFile(ts, ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS), rel);
+    for (const literal of foundIn.literals) noteEnvRead(reads, literal);
+    noteReaderTemplates(readers, foundIn.templates);
+    calls.push(...foundIn.calls);
+  }
+  for (const call of calls) noteReaderCall(reads, readers, call);
+  return reads;
+}
+
+/** The sealed members' key names without decrypting: Map `KEY` -> the member paths holding it, sorted. */
+function sealedKeys(repoRoot, all) {
+  const members = new Map();
+  for (const file of all) {
+    if (!SEALED_MEMBER.test(file)) continue;
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    let envelope;
+    try { envelope = envelopeOf(text); } catch { continue; }
+    for (const key of envelope.keys) {
+      if (!members.has(key)) members.set(key, []);
+      members.get(key).push(file);
+    }
+  }
+  for (const list of members.values()) list.sort((left, right) => (left < right ? -1 : Number(left > right)));
+  return members;
+}
+
+function declaredEnvironment(value, add) {
+  if (!Array.isArray(value)) {
+    for (const name of Object.keys(value)) add(name);
+    return;
+  }
+  for (const entry of value) {
+    if (typeof entry !== 'string') continue;
+    const name = /^([A-Za-z_]\w*)\s*=/u.exec(entry)?.[1] ?? (KEY_NAME.test(entry) ? entry : null);
+    if (name) add(name);
+  }
+}
+
+function declaredEntryName(entry, allowString) {
+  if (allowString && typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object' && typeof entry.name === 'string') return entry.name;
+  return null;
+}
+
+function declaredNamedEntries(entries, add, allowString) {
+  for (const entry of entries) {
+    const name = declaredEntryName(entry, allowString);
+    if (name !== null) add(name);
+  }
+}
+
+function declaredYamlEntry(key, value, add) {
+  if ((key === 'environment' || key === 'env') && value && typeof value === 'object') {
+    declaredEnvironment(value, add);
+    return;
+  }
+  if ((key === 'runtimeSecrets' || key === 'secrets') && Array.isArray(value)) {
+    declaredNamedEntries(value, add, true);
+    return;
+  }
+  if (key === 'vars' && Array.isArray(value)) {
+    declaredNamedEntries(value, add, false);
+    return;
+  }
+  declaredFromYaml(value, add);
+}
+
+/** The env names one yaml node declares: `environment:`/`env:` keys or `K=V` entries, `runtimeSecrets`, `secrets` and `vars[].name`. */
+function declaredFromYaml(node, add) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const item of node) declaredFromYaml(item, add); return; }
+  for (const [key, value] of Object.entries(node)) declaredYamlEntry(key, value, add);
+}
+
+function addDeclaredKey(declared, name) {
+  if (!KEY_NAME.test(name)) return;
+  declared.add(name);
+  if (FILE_SUFFIX.test(name)) declared.add(name.replace(FILE_SUFFIX, ''));
+}
+
+function declareKeysFromText(file, text, add) {
+  if (KEYS_ROSTER.test(file)) {
+    for (const match of text.matchAll(ROSTER_KEY)) if (/[A-Z]/u.test(match[1])) add(match[1]);
+    return;
+  }
+  try { declaredFromYaml(parseYaml(text), add); } catch { /* a malformed stacks yaml is the shape rule's finding, not this one's */ }
+}
+
+/** The keys declared as public config or passed by the stack: KEYS.md rosters plus `.starcistacks` yaml; `<KEY>_FILE` declares `<KEY>`. */
+function declaredKeys(repoRoot, all) {
+  const declared = new Set();
+  const add = (name) => addDeclaredKey(declared, name);
+  for (const file of all) {
+    if (!KEYS_ROSTER.test(file) && !STACK_YAML.test(file)) continue;
+    const text = readText(repoRoot, file);
+    if (text !== null) declareKeysFromText(file, text, add);
+  }
+  return declared;
+}
+
+function addRequiredFindings(reads, sealed, declared, findings) {
+  for (const read of reads.values()) {
+    if (read.required && !sealed.has(read.key) && !declared.has(read.key)) {
+      findings.push(found(ENV_REQUIRED_UNSET, read.file, `${read.file} reads required ${read.key}, which is neither sealed under .starcistacks/<env>/secrets/*.enc nor declared by the stack or KEYS.md`));
+    }
+  }
+}
+
+function sealedMemberFinding(key, member, reads, declared) {
+  // The specific public-custody code wins over the generic unread one for a NEXT_PUBLIC_* key.
+  if (PUBLIC_PREFIX.test(key)) {
+    return found(ENV_PUBLIC_SEALED, member, `${member} seals the public key ${key}; NEXT_PUBLIC_* values are public configuration and never enter custody`);
+  }
+  if (!reads.has(key) && !declared.has(key)) {
+    return found(ENV_SEALED_UNREAD, member, `${member} seals ${key}, which no EnvSource reader and no declared consumer uses; unseal it or declare who consumes it`);
+  }
+  return null;
+}
+
+function addSealedFindings(sealed, reads, declared, findings) {
+  for (const [key, members] of sealed) {
+    for (const member of members) {
+      const finding = sealedMemberFinding(key, member, reads, declared);
+      if (finding !== null) findings.push(finding);
+    }
+    addDuplicateFindings(key, members, findings);
+  }
+}
+
+function addDuplicateFindings(key, members, findings) {
+  const firstByEnvironment = new Map();
+  for (const member of members) {
+    const environment = member.split('/')[1];
+    const first = firstByEnvironment.get(environment);
+    if (first === undefined) {
+      firstByEnvironment.set(environment, member);
+      continue;
+    }
+    findings.push(found(ENV_DUPLICATE, member, `${key} is sealed in ${first} and again in ${member}; one key lives in one member per environment`));
+  }
+}
+
+function addExampleFindings(repoRoot, all, reads, findings) {
+  for (const file of all.filter((rel) => ENV_EXAMPLE.test(rel))) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    for (const { key } of envExampleEntries(text)) {
+      if (!reads.has(key)) findings.push(found(ENV_EXAMPLE_DRIFT, file, `${file} names ${key}, which no EnvSource reader consumes; align the example with the keys the code reads`));
+    }
+  }
+}
+
+/** The findings of R248 over the tracked paths `all` of an app judged at its root scope (both editions). */
+export function envParityFindings({ repoRoot, all = [], isRoot }) {
+  if (!isRoot) return [];
+  const reads = collectEnvReads(repoRoot, all);
+  if (reads === null) {
+    return [found(ENV_REQUIRED_UNSET, 'be/', 'the env-key parity cannot be judged: no TypeScript resolves from the app; install the app\'s dependencies', { missing: ['typescript'] })];
+  }
+  const sealed = sealedKeys(repoRoot, all);
+  const declared = declaredKeys(repoRoot, all);
+  const findings = [];
+  addRequiredFindings(reads, sealed, declared, findings);
+  addSealedFindings(sealed, reads, declared, findings);
+  addExampleFindings(repoRoot, all, reads, findings);
+  return findings;
+}

package/runtime/scripts/hfs/rules/env-value-shape.mjs

@@ -0,0 +1,113 @@
+// env-value-shape.mjs - R249 HFS_ENV_VALUE_SHAPE (OPS K6: `OPENCLAW_MANAGE_AGENTS=1` for an `env.bool`
+// read): a stored environment value parses as the type its `EnvSource` reader declares. The reader shapes come from
+// the same static TypeScript walk as the env-key parity (collectEnvReads).
+//   - the finder judges the concrete values of `*.env.example` files: a value that is not a placeholder must parse;
+//   - `starci app secret verify <env>` (verifySecrets) decrypts every member of the environment in memory through the
+//     sops seam and checks each stored value against its reader's shape; output names the environment, the member,
+//     the key and the violated shape - never a value.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { envelopeOf } from '../secret-document.mjs';
+import { sealedFiles } from '../secret-store.mjs';
+import { SecretError } from '../secret-errors.mjs';
+import { collectEnvReads, envExampleEntries, isEnvSourcePath } from './env-parity.mjs';
+import { found, readText } from './read.mjs';
+
+export const ENV_VALUE_SHAPE = 'ENV_VALUE_SHAPE';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const FILE_SUFFIX = /_FILE$/u;
+const ENV_EXAMPLE = /\.env\.example$/u;
+const SKIP_DIRECTORY = new Set(['node_modules', 'dist', 'coverage', '.git']);
+
+const SHAPES = Object.freeze({
+  int: { text: 'an integer', ok: (value) => value.trim() !== '' && Number.isInteger(Number(value)) },
+  bool: { text: 'true or false', ok: (value) => value === 'true' || value === 'false' },
+  url: { text: 'an absolute URL', ok: (value) => URL.canParse(value) },
+  duration: { text: 'a duration (250, 250ms, 30s, 5m or 2h)', ok: (value) => /^\d+(?:ms|s|m|h)?$/u.test(value) },
+  string: { text: 'a nonempty value', ok: (value) => value.length > 0 },
+});
+
+/** What a shape violation is called in output; the enum shape names its allowed values. */
+const shapeText = (shape) => (shape.kind === 'enum' ? `one of ${shape.allowed.join(', ')}` : SHAPES[shape.kind].text);
+
+/** Whether `value` parses as `shape` declares. */
+const shapeOk = (shape, value) => (shape.kind === 'enum' ? shape.allowed.includes(value) : SHAPES[shape.kind]?.ok(value) ?? true);
+
+/** An example line holds a documented stand-in, not a value to parse: empty, an `<...>` name or a `${...}` reference. */
+const isPlaceholder = (value) => value === '' || value.includes('${') || (value.startsWith('<') && value.endsWith('>'));
+
+/** The repository-relative env source files on disk: the be side of an app, else the src tree of a back-end repository. */
+function listEnvSourceFiles(repoRoot) {
+  const out = [];
+  const walk = (dir, rel) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRECTORY.has(entry.name)) walk(path.join(dir, entry.name), `${rel}${entry.name}/`);
+      } else if (isEnvSourcePath(rel + entry.name)) out.push(rel + entry.name);
+    }
+  };
+  const roots = ['be', 'src'].map((name) => path.join(repoRoot, name)).filter((dir) => { try { return fs.statSync(dir).isDirectory(); } catch { return false; } });
+  for (const root of roots) walk(root, `${path.basename(root)}/`);
+  return out.sort(byCodeUnit);
+}
+
+/** The ENV_VALUE_SHAPE violations of one decrypted map against the walked reader shapes; keys and shapes only. */
+function shapeViolations(reads, map) {
+  const violations = [];
+  for (const [key, value] of Object.entries(map)) {
+    if (FILE_SUFFIX.test(key)) continue;
+    const shape = reads.get(key)?.shape;
+    if (shape && !shapeOk(shape, value)) violations.push({ key, expected: shapeText(shape) });
+  }
+  return violations;
+}
+
+/** The findings of R249 over the `*.env.example` files of an app judged at its root scope (both editions). */
+export function envValueShapeFindings({ repoRoot, all = [], isRoot }) {
+  if (!isRoot) return [];
+  const examples = all.filter((file) => ENV_EXAMPLE.test(file));
+  if (!examples.length) return [];
+  const reads = collectEnvReads(repoRoot, all);
+  if (reads === null) return [];
+  const findings = [];
+  for (const file of examples) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    for (const { key, value } of envExampleEntries(text)) {
+      if (isPlaceholder(value)) continue;
+      const shape = reads.get(key)?.shape;
+      if (shape && !shapeOk(shape, value)) {
+        findings.push(found(ENV_VALUE_SHAPE, file, `${file} gives ${key} a value that is not ${shapeText(shape)}; an env example must parse as the EnvSource reader declares`));
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * `starci app secret verify <env>`: decrypt every member of `directory` in memory through the `sops` seam and check
+ * each value against the shape its EnvSource reader declares. Output names the environment, the member, the key and
+ * the violated shape, never a value. Returns the CLI exit code: 0 verified, 2 violations.
+ */
+export function verifySecrets({ repoRoot, directory, environment, sops, stdout, typescript }) {
+  const ts = typescript ?? loadTypescript(repoRoot, HERE);
+  if (!ts) throw new SecretError('verify needs the app\'s TypeScript to read <app>.env.ts; install the app\'s dependencies');
+  const reads = collectEnvReads(repoRoot, listEnvSourceFiles(repoRoot), ts);
+  const violations = [];
+  let keys = 0;
+  for (const name of sealedFiles(directory)) {
+    const file = path.join(directory, name);
+    const map = sops.decrypt(file, envelopeOf(fs.readFileSync(file, 'utf8')).format);
+    keys += Object.keys(map).length;
+    for (const violation of shapeViolations(reads, map)) violations.push({ member: name, ...violation });
+  }
+  for (const violation of violations) stdout(`ENV_VALUE_SHAPE ${environment}/${violation.member}: ${violation.key} is not ${violation.expected}\n`);
+  if (!violations.length) stdout(`verified ${environment}: ${keys} key${keys === 1 ? '' : 's'} sealed\n`);
+  return violations.length ? 2 : 0;
+}

package/runtime/scripts/hfs/rules/event-bus.mjs

@@ -2,7 +2,7 @@
 //   BE_EVENT_CLASS_CONTRACT   every typed event class `be/src/modules/events/<service>/<event>.event.ts` equals an entry of the vendored
 //                             contract `be/contracts/<service>/events.json` (the same name and version), every entry of a vendored
 //                             contract has its class, and a class file is named after its event (`order.placed` -> `order-placed.event.ts`);
-//   BE_PATTERN_SPEC_MISSING   a declared pattern has its required scenarios: ruleParams.be.patternScenarios.<pattern> lists scenario ids,
+//   BE_PATTERN_SPEC_MISSING   a full-edition declared pattern has its required scenarios: ruleParams.be.patternScenarios.<pattern> lists scenario ids,
 //                             and an e2e or integration spec of the back end holds a test whose title starts `<pattern>/<scenario>:`.
 // Class members are read with TypeScript's own parser (a `static readonly eventName` and `version` with literal initializers), spec
 // titles are the first argument of `it(` and `test(` calls; no source text is matched by a regular expression.
@@ -181,8 +181,9 @@ let memoScenarios;
 /** ruleParams.be.patternScenarios of the slot manifest this runtime ships. */
 const scenariosTable = () => (memoScenarios ??= ruleParams(loadSlotManifest(), 'be').patternScenarios ?? {});
 
-/** Findings of BE_PATTERN_SPEC_MISSING: each declared pattern's required scenarios have a test. */
+/** Full-edition proof scenarios; lite integration proofs are judged by lite-proof-lane.mjs. */
 export function patternSpecFindings({ repoRoot, files, repo, scenarios = scenariosTable() }) {
+  if (repo.edition === 'lite') return [];
   const patterns = (repo.sides?.be?.patterns ?? []).filter((name) => (scenarios[name] ?? []).length > 0);
   if (patterns.length === 0) return [];
   const ts = typescriptFor(repoRoot);

package/runtime/scripts/hfs/rules/event-tables.mjs

@@ -0,0 +1,100 @@
+// Literal service event tables share the vendored contract with typed event classes.
+import { isDeepStrictEqual } from 'node:util';
+import { nameText } from '../../lib/ts-ast.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+const CODE = 'HFS_EVENT_CONTRACT';
+const TABLE = /^be\/apps\/([^/]+)\/src\/(events|consumes)\.ts$/;
+const SNAPSHOT = /^be\/contracts\/([^/]+)\/events\.json$/;
+
+function literal(ts, node) {
+  if (!node) throw new Error('missing initializer');
+  if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node)) return literal(ts, node.expression);
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (!ts.isObjectLiteralExpression(node)) throw new Error('expected a literal object, string or number');
+  return Object.fromEntries(node.properties.map((property) => {
+    const key = nameText(ts, property.name);
+    if (!ts.isPropertyAssignment(property) || key === null) throw new Error('expected a named literal property');
+    return [key, literal(ts, property.initializer)];
+  }));
+}
+
+function tableOf(ts, text, name) {
+  const source = ts.createSourceFile('table.ts', text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  if (source.parseDiagnostics.length) throw new Error('invalid TypeScript');
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    const declaration = statement.declarationList.declarations.find((entry) => ts.isIdentifier(entry.name) && entry.name.text === name);
+    if (declaration) {
+      const value = literal(ts, declaration.initializer);
+      if (value === null || typeof value !== 'object') throw new Error('expected a literal table');
+      return value;
+    }
+  }
+  throw new Error(`missing ${name} table`);
+}
+
+function readTables(ts, repoRoot, files) {
+  const tables = [];
+  const findings = [];
+  for (const file of files.filter((candidate) => TABLE.test(candidate))) {
+    const [, service, kind] = TABLE.exec(file);
+    try {
+      const name = kind === 'events' ? 'EVENTS' : 'CONSUMES';
+      tables.push({ file, service, kind, value: tableOf(ts, readText(repoRoot, file) ?? '', name) });
+    } catch (error) {
+      findings.push(found(CODE, file, `${file}: ${error.message}; declare a literal event contract table.`));
+    }
+  }
+  return { tables, findings };
+}
+
+function providerFindings(table, snapshots, declared) {
+  const findings = [];
+  const expected = { schema: 'starci/event-contract@1', service: table.service, events: table.value };
+  if (!isDeepStrictEqual(snapshots.get(table.service), expected)) {
+    findings.push(found(CODE, table.file, `${table.file}: be/contracts/${table.service}/events.json is missing or differs from EVENTS; commit the emitted provider snapshot.`));
+  }
+  for (const [name, event] of Object.entries(table.value)) {
+    if (!Number.isInteger(event?.version) || event.version < 1 || !event.payload || typeof event.payload !== 'object') {
+      findings.push(found(CODE, table.file, `${table.file}: ${name} needs a positive integer version and a literal payload.`));
+    }
+    if (event?.compensates !== undefined && !declared.has(event.compensates)) {
+      findings.push(found(CODE, table.file, `${table.file}: ${name} compensates undeclared event ${event.compensates}.`));
+    }
+  }
+  return findings;
+}
+
+function consumerFindings(table, snapshots) {
+  const findings = [];
+  for (const [provider, events] of Object.entries(table.value)) {
+    if (events === null || typeof events !== 'object') {
+      findings.push(found(CODE, table.file, `${table.file}: CONSUMES.${provider} must be a literal event/version table.`));
+      continue;
+    }
+    for (const [name, version] of Object.entries(events)) {
+      const snapshot = snapshots.get(provider);
+      const event = snapshot?.events?.[name];
+      if (snapshot?.schema !== 'starci/event-contract@1' || snapshot?.service !== provider || !event || event.version !== version) {
+        findings.push(found(CODE, table.file, `${table.file}: ${provider} event ${name} at version ${version} is not declared by its vendored snapshot.`));
+      }
+    }
+  }
+  return findings;
+}
+
+export function eventTableFindings({ ts, repoRoot, files }) {
+  const snapshots = new Map(files.filter((file) => SNAPSHOT.test(file))
+    .map((file) => [SNAPSHOT.exec(file)[1], readJson(repoRoot, file)]));
+  const declared = new Set([...snapshots.values()].flatMap((snapshot) => Object.keys(snapshot?.events ?? {})));
+  const { tables, findings } = readTables(ts, repoRoot, files);
+  for (const table of tables) {
+    findings.push(...(table.kind === 'events' ? providerFindings(table, snapshots, declared) : consumerFindings(table, snapshots)));
+  }
+  return findings;
+}
+
+export const eventTableServices = (files) => files.filter((file) => TABLE.test(file) && TABLE.exec(file)[2] === 'events')
+  .map((file) => TABLE.exec(file)[1]);