@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/gates/canon-digest.mjs

@@ -0,0 +1,81 @@
+// canon-digest.mjs — the one content digest of a lint canon package (modules/models/code-patterns.yaml `canon.contentDigest`).
+// The policy names the algorithm, the include/exclude globs and the framing; the only framing is
+// `sorted-posix-relative-path-null-raw-bytes-null`: every selected file, sorted by its posix relative path (ICU 'en' collation),
+// contributes its path as UTF-8, one NUL byte, its raw bytes, one NUL byte. An unknown algorithm or framing, a malformed
+// policy and a symlink in the file set are refused with a typed code, never hashed around.
+//
+// The file set is either the canon's PUBLISHED set (`packedFiles`: the npm pack list of its source directory, what the
+// registry tarball carries) or an installed copy on disk (`installedFiles`: every regular file under the package root,
+// node_modules excluded). Both feed `canonContentDigest`, so the runtime check and the product gate hash one way.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { packDryRun } from '../api/npm/pack-dry-run.mjs';
+import { braceVariants, globExpression } from '../lib/glob.mjs';
+import { posixPath } from '../lib/path-key.mjs';
+import { stringList } from '../lib/list.mjs';
+
+const CANON_DIGEST_ALGORITHMS = Object.freeze(['sha256']);
+const CANON_DIGEST_FRAMINGS = Object.freeze(['sorted-posix-relative-path-null-raw-bytes-null']);
+
+// The framing's order is the ICU collation of the 'en' locale (what String#localeCompare gives on a default Node host), fixed
+// here so the order never follows the host's locale; the bound profile values are computed in it.
+const ORDER = new Intl.Collator('en', { usage: 'sort', sensitivity: 'variant' });
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const matchAny = (file, globs) => globs.flatMap(braceVariants).some((pattern) => globExpression(pattern).test(file));
+const globList = (value) => stringList(value, { blank: false });
+
+/** The policy itself, or a typed refusal: CANON_DIGEST_ALGORITHM_UNKNOWN, CANON_DIGEST_FRAMING_UNKNOWN, CANON_DIGEST_POLICY_INVALID. */
+function assertDigestPolicy(policy) {
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) throw fail('CANON_DIGEST_POLICY_INVALID', 'The canon content digest policy is not an object.');
+  if (!CANON_DIGEST_ALGORITHMS.includes(policy.algorithm)) throw fail('CANON_DIGEST_ALGORITHM_UNKNOWN', `The canon digest algorithm ${JSON.stringify(policy.algorithm)} is not one of ${CANON_DIGEST_ALGORITHMS.join(', ')}.`);
+  if (!CANON_DIGEST_FRAMINGS.includes(policy.framing)) throw fail('CANON_DIGEST_FRAMING_UNKNOWN', `The canon digest framing ${JSON.stringify(policy.framing)} is not one of ${CANON_DIGEST_FRAMINGS.join(', ')}.`);
+  if (!globList(policy.include) || !policy.include.length || !globList(policy.exclude)) throw fail('CANON_DIGEST_POLICY_INVALID', 'The canon digest policy needs a non-empty include glob list and an exclude glob list.');
+  return policy;
+}
+
+/** Whether posix relative `file` is selected by the policy's include and exclude globs. */
+const selectedByPolicy = (file, policy) => matchAny(file, policy.include) && !matchAny(file, policy.exclude);
+
+/** The PUBLISHED file list of the package whose source is `directory`: `npm pack --dry-run --json --ignore-scripts`. */
+export function packedFiles(directory) {
+  const run = packDryRun(directory);
+  let listed;
+  try { listed = JSON.parse(run.stdout)?.[0]?.files; } catch { listed = null; }
+  if (run.status !== 0 || !Array.isArray(listed)) throw fail('CANON_PACK_UNAVAILABLE', `npm pack --dry-run could not list ${directory}: ${String(run.stderr ?? run.error?.message ?? '').trim().split(/\r?\n/).at(-1) ?? ''}`);
+  return listed.map((entry) => posixPath(entry.path));
+}
+
+/** Every regular file of an installed package at `root` (node_modules skipped); a symlink is refused (CANON_PACKAGE_SYMLINK). */
+export function installedFiles(root) {
+  const files = [];
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === 'node_modules') continue;
+      const absolute = path.join(directory, entry.name), relative = posixPath(path.relative(root, absolute)), stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw fail('CANON_PACKAGE_SYMLINK', `The canon package holds the symlink ${relative}; a canon is hashed from regular files only.`);
+      if (stat.isDirectory()) visit(absolute);
+      else if (stat.isFile()) files.push(relative);
+    }
+  };
+  visit(root);
+  return files;
+}
+
+/** {value, files} of the files of `root` the policy selects out of `files` (posix paths relative to `root`). */
+export function canonContentDigest(root, policy, files) {
+  assertDigestPolicy(policy);
+  const selected = [...new Set(files.map(posixPath))].filter((file) => selectedByPolicy(file, policy)).sort(ORDER.compare);
+  const hash = crypto.createHash(policy.algorithm), nul = Buffer.from([0]);
+  for (const file of selected) {
+    const absolute = path.join(root, file), segments = file.split('/');
+    let stat;
+    for (let depth = 1; depth <= segments.length; depth += 1) {
+      try { stat = fs.lstatSync(path.join(root, ...segments.slice(0, depth))); } catch { throw fail('CANON_PACKAGE_UNREADABLE', `The canon file ${file} is missing.`); }
+      if (stat.isSymbolicLink()) throw fail('CANON_PACKAGE_SYMLINK', `The canon file ${file} is reached through the symlink ${segments.slice(0, depth).join('/')}; a canon is hashed from regular files only.`);
+    }
+    if (!stat.isFile()) throw fail('CANON_PACKAGE_UNREADABLE', `The canon file ${file} is not a regular file.`);
+    hash.update(Buffer.from(file, 'utf8')); hash.update(nul); hash.update(fs.readFileSync(absolute)); hash.update(nul);
+  }
+  return { value: hash.digest('hex'), files: selected.length };
+}

package/runtime/scripts/gates/canon-pins.mjs

@@ -0,0 +1,16 @@
+// canon-pins.mjs - where the canon pins live and how they are read: knowledge/hfs/canon-pins.yaml (shape:
+// modules/schemas/canon-pins.schema.yaml) and the profiles bound to the canons, modules/models/code-patterns.yaml.
+// The gates read the pins here; scripts/checks/check-canon-pins.mjs is the self-check that judges them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+export const PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
+export const SCHEMA_FILE = 'modules/schemas/canon-pins.schema.yaml';
+export const PROFILES_FILE = 'modules/models/code-patterns.yaml';
+
+/** The parsed canon pins of the runtime at `root`. */
+export function loadPins(root = skillRoot) {
+  return parseYaml(fs.readFileSync(path.join(root, PINS_FILE), 'utf8'));
+}

package/runtime/scripts/gates/commit-proof.mjs

@@ -0,0 +1,53 @@
+// commit-proof.mjs — locations and file IO for a commit's verification and release evidence. Each producer owns its schema.
+import fs from 'node:fs';
+import path from 'node:path';
+import { runtimeStateDir, starciLocalRoot } from '../../engine/runtime-root.mjs';
+import { sha256 } from '../../engine/digest.mjs';
+import { readJsonFile } from '../lib/json.mjs';
+import { sameResolvedPath } from '../lib/path-key.mjs';
+import { writeJsonFile } from '../api/fs/write-json-file.mjs';
+
+const RELEASE_KINDS = Object.freeze({ l4: 'l4', affected: 'affected', rows: 'l4-rows', ci: 'ci', report: 'affected-report' });
+const SHORT = 12;
+/** The local git note namespace used to write and read land proof. */
+export const LAND_NOTE_REF = 'land';
+
+/** The directory shared by release proofs of every worktree of a repository. */
+const proofDirOf = (commonDir) => path.join(commonDir, 'starci-release');
+
+/** The location of an affected, verify, deploy/check or release receipt; existing references keep their established paths. */
+export function proofFileOf({ kind, sha, base, root, env, commonDir }) {
+  if (kind === 'verify') return path.join(runtimeStateDir(root), 'verify', `${sha}.json`);
+  if (kind === 'affected-receipt') return path.join(runtimeStateDir(root), 'affected', `${String(base).slice(0, SHORT)}-${String(sha).slice(0, SHORT)}.json`);
+  if (kind === 'deploy') return path.join(starciLocalRoot(env), 'deploy', 'receipts', `${sha}.json`);
+  if (!Object.hasOwn(RELEASE_KINDS, kind)) throw new Error(`unknown commit proof kind: ${kind}`);
+  return path.join(proofDirOf(commonDir), `${sha}.${RELEASE_KINDS[kind]}.json`);
+}
+
+/** Every release proof of one kind under the git common directory, or [] when the directory is absent. */
+export function proofFilesOf({ commonDir, kind }) {
+  if (!Object.hasOwn(RELEASE_KINDS, kind)) throw new Error(`unknown release proof kind: ${kind}`);
+  const folder = proofDirOf(commonDir);
+  const suffix = `.${RELEASE_KINDS[kind]}.json`;
+  return fs.existsSync(folder) ? fs.readdirSync(folder).filter((name) => name.endsWith(suffix)).map((name) => path.join(folder, name)) : [];
+}
+
+/** Writes one receipt atomically; a reader sees a complete JSON document. Returns its file. */
+export function writeProofFile(file, record) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeJsonFile(tmp, record);
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/** A proof file's parsed document, or null when it is missing, unreadable or malformed; its producer validates the schema. */
+export const readProofFile = (file) => readJsonFile(file, null);
+
+/** The digest of the schema's ordered binding fields. */
+export const proofDigest = (fields) => sha256(fields.join('\n'));
+
+/** Whether a receipt binds the requested commit and tree. */
+export const proofBinds = (record, { sha, tree }) => record?.sha === sha && record?.tree === tree;
+
+/** Whether the specs judged this source root; a missing root never supplies proof for another checkout. */
+export const judgedIn = (recorded, root) => typeof recorded === 'string' && recorded !== '' && sameResolvedPath(recorded, root);

package/runtime/scripts/gates/gate-input.mjs

@@ -0,0 +1,98 @@
+// gate-input.mjs - the one base, Git delta and current-input reader of a code gate and its settle observer.
+import fs from 'node:fs';
+import path from 'node:path';
+import { byCodeUnit } from '../lib/list.mjs';
+import { revParseQuery } from '../api/git/rev-parse-query.mjs';
+import { diff as gitDiff } from '../api/git/diff.mjs';
+import { lsFiles } from '../api/git/ls-files.mjs';
+import { mergeBase as mergeBaseOf } from '../api/git/merge-base.mjs';
+import { posixPath, underAny } from '../lib/path-key.mjs';
+import { sha256File } from '../../engine/digest.mjs';
+import { gateBaseAt } from '../machine/workflow-tree.mjs';
+
+/** Run a gate-owned Git query with its existing text/rename output settings and caller options. */
+const git = (call, root, args, options = {}) => call(args, { cwd: root, config: { 'core.quotepath': 'off' }, maxBuffer: 256 * 1024 * 1024, ...options });
+
+/** Return a completed query's text, or null when the native child failed; input readers reject missing text. */
+const gitText = (call, root, args) => { const r = git(call, root, args); return !r.error && r.status === 0 ? r.stdout : null; };
+export { git as gateGit, gitText as gateGitText, gateDelta };
+
+/**
+ * The base commit: --base verified as a commit; else, when --root is a workflow worktree (the registry knows it, never a
+ * branch-name guess), the workflow's previous checkpoint (workflow-checkpoint.mjs gateBaseAt), so only the op's own new
+ * findings block; else the merge-base of HEAD with its upstream, main or master.
+ */
+export function resolveGateBase(root, base = null, { workflowBase = (dir) => gateBaseAt({ env: process.env }, dir) } = {}) {
+  if (base) {
+    const sha = gitText(revParseQuery, root, ['--verify', '--quiet', `${base}^{commit}`])?.trim();
+    if (!sha) throw Object.assign(new Error(`--base ${base} is not a commit of ${root}`), { code: 'GATE_BASE_UNKNOWN' });
+    return sha;
+  }
+  const checkpoint = workflowBase(root);
+  if (checkpoint) return checkpoint;
+  for (const ref of ['@{upstream}', 'main', 'master', 'origin/HEAD']) {
+    const sha = mergeBaseOf(root, 'HEAD', ref);
+    if (sha) return sha;
+  }
+  throw Object.assign(new Error(`no base: ${root} has no upstream, main or master to measure against; pass --base`), { code: 'GATE_BASE_UNKNOWN' });
+}
+
+/**
+ * The delta between the base and the working tree, relative to --root: {changed[] (existing files), added Set, deleted Set,
+ * renamed Map(new -> old)}. A rename's old path counts as deleted and its new path is measured against the old path's base
+ * blob, so the findings a move carries stay preexisting; untracked files are additions.
+ */
+/** Files one non-rename diff status line into the delta sets. */
+const recordStatus = (kind, rel, { added, deleted, changed }) => {
+  if (kind === 'D') { deleted.add(rel); return; }
+  changed.add(rel);
+  if (kind === 'A') added.add(rel);
+};
+
+function gateDelta(root, base) {
+  const diff = gitText(gitDiff, root, ['--name-status', '-z', '--find-renames', '--relative', base]);
+  const untracked = gitText(lsFiles, root, ['--others', '--exclude-standard', '-z']);
+  if (diff === null || untracked === null) throw new Error(`the actual gate delta of ${root} could not be listed`);
+  const status = String(diff).split('\0');
+  const added = new Set(), deleted = new Set(), changed = new Set(), renamed = new Map();
+  for (let i = 0; i < status.length && status[i]; i += 1) {
+    const kind = status[i], file = status[++i];
+    if (!file) throw new Error('the gate diff has an incomplete path record');
+    const rel = posixPath(file);
+    if (kind.startsWith('R')) {
+      const to = status[++i];
+      if (!to) throw new Error('the gate rename has no destination');
+      deleted.add(rel); changed.add(posixPath(to)); renamed.set(posixPath(to), rel);
+    }
+    else recordStatus(kind, rel, { added, deleted, changed });
+  }
+  for (const file of String(untracked).split('\0').filter(Boolean)) { const rel = posixPath(file); changed.add(rel); added.add(rel); }
+  return { changed: [...changed].filter((file) => fs.existsSync(path.join(root, file))).sort(byCodeUnit), added, deleted, renamed };
+}
+
+/**
+ * Read the gate's actual base, HEAD and current input bytes without preparing or running a tool. Deleted paths carry null;
+ * named files extend the real delta. Settle uses the same reader against persisted placement and ownership, so a report's
+ * changed list cannot manufacture an empty slice or hide a later edit.
+ */
+export function gateInputSnapshot(root, base = null, files = [], owned = null) {
+  root = path.resolve(root);
+  base = resolveGateBase(root, base);
+  const head = gitText(revParseQuery, root, ['--verify', 'HEAD'])?.trim();
+  if (!head) throw new Error(`the gate HEAD of ${root} could not be resolved`);
+  const delta = gateDelta(root, base);
+  const named = files.map((file) => {
+    const rel = path.relative(root, path.resolve(root, file));
+    if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+      throw new Error(`gate input ${file} is not a file inside ${root}`);
+    return posixPath(rel);
+  });
+  if (owned && (!Array.isArray(owned) || !owned.length || named.some((file) => !underAny(file, owned, { dot: true }))))
+    throw new Error('the named gate inputs are outside the admitted owned scope');
+  const inputs = [...new Set([...delta.changed, ...delta.deleted, ...named])]
+    .filter((file) => !owned || underAny(file, owned, { dot: true })).sort(byCodeUnit).map((file) => {
+    const absolute = path.join(root, file);
+    return { path: file, sha256: fs.existsSync(absolute) ? sha256File(absolute) : null };
+  });
+  return { root: posixPath(root), base, head, changed: inputs.filter((file) => file.sha256 !== null).map((file) => file.path), inputs };
+}