@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/packages/index-file.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/** IC-023: a bounded, closed, local index. Reading and selecting write and spawn nothing. */
+const fs = require('node:fs');
+const { isPackageId } = require('../../helper/package-ids.js');
+const { parseSemVer, compareSemVer, parseHostRange, satisfiesHostRange } = require('../../helper/semver.js');
+
+const MAX_BYTES = 4 * 1024 * 1024;
+const object = (value     )          => value !== null && typeof value === 'object' && !Array.isArray(value);
+const exact = (value     )          => typeof value === 'string' && parseSemVer(value) !== null;
+const text = (value     )          => typeof value === 'string' && value.length > 0;
+const problem = (field        , code        , message        , allowed     )      => ({
+  package: null, field, code, severity: 'error', message, allowed,
+});
+
+function closed(value     , allowed          , field        , findings       )          {
+  if (!object(value)) {
+    findings.push(problem(field, 'bad-type', 'must be an object', allowed));
+    return false;
+  }
+  for (const name of Object.keys(value)) {
+    if (!allowed.includes(name)) findings.push(problem(`${field}.${name}`, 'unknown-key', 'unknown index field', allowed));
+  }
+  return true;
+}
+
+/** Shared with the plan reader: only safe, fully pinned remote records are accepted. */
+function pinnedSourceFindings(source     , field = 'source')        {
+  const findings        = [];
+  if (!object(source)) return [problem(field, 'bad-type', 'must be a pinned source object', 'git or npm')];
+  if (source.type === 'git') {
+    closed(source, ['type', 'url', 'commit', 'path'], field, findings);
+    let validUrl = false;
+    if (text(source.url) && source.url.length <= 512 && !/[\s\u0000-\u001f\u007f]/u.test(source.url)) {
+      try {
+        const url = new URL(source.url);
+        validUrl = url.protocol === 'https:' && Boolean(url.host) && !url.username && !url.password && !url.hash;
+      } catch { /* invalid URL */ }
+    }
+    if (!validUrl) findings.push(problem(`${field}.url`, 'bad-type', 'must be an https URL without credentials or a fragment', 'an https URL of at most 512 characters'));
+    if (typeof source.commit !== 'string' || !/^[0-9a-fA-F]{40}$/u.test(source.commit)) {
+      findings.push(problem(`${field}.commit`, 'source-unpinned', 'git source needs a full commit', '40 hexadecimal characters'));
+    }
+    if (Object.hasOwn(source, 'path') && (!text(source.path) || source.path.length > 512
+      || source.path.startsWith('/') || source.path.startsWith('-') || source.path.includes('\\')
+      || source.path.split('/').some((part        ) => part === '..' || part === '')
+      || /[\s\u0000-\u001f\u007f]/u.test(source.path))) {
+      findings.push(problem(`${field}.path`, 'bad-type', 'must be a safe relative subdirectory', 'a relative path without .., backslashes, whitespace or a leading -'));
+    }
+  } else if (source.type === 'npm') {
+    closed(source, ['type', 'name', 'version', 'integrity'], field, findings);
+    if (!text(source.name) || source.name.length > 214 || source.name.startsWith('-')
+      || !/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u.test(source.name)) {
+      findings.push(problem(`${field}.name`, 'bad-type', 'invalid npm package name', 'an npm name that does not start with -'));
+    }
+    if (!exact(source.version)) findings.push(problem(`${field}.version`, 'source-unpinned', 'npm source needs an exact version', 'an exact semver'));
+    if (typeof source.integrity !== 'string' || !/^sha512-[A-Za-z0-9+/]+={0,2}$/u.test(source.integrity)) {
+      findings.push(problem(`${field}.integrity`, 'source-unpinned', 'npm source needs sha512 integrity', 'sha512-<base64>'));
+    }
+  } else {
+    findings.push(problem(`${field}.type`, 'bad-type', 'index sources must be remote and pinned', ['git', 'npm']));
+  }
+  return findings;
+}
+
+function readIndex(file        , { fsImpl = fs }      = {})      {
+  const fail = (field        , code        , message        , allowed     )      => ({
+    ok: false, findings: [problem(field, code, message, allowed)],
+  });
+  let raw        ;
+  try {
+    if (fsImpl.statSync(file).size > MAX_BYTES) return fail('index', 'too-large', 'index exceeds 4 MiB', MAX_BYTES);
+    raw = String(fsImpl.readFileSync(file, 'utf8'));
+    if (Buffer.byteLength(raw, 'utf8') > MAX_BYTES) return fail('index', 'too-large', 'index exceeds 4 MiB', MAX_BYTES);
+  } catch {
+    return fail('index', 'bad-type', 'index cannot be read', 'a readable local JSON file');
+  }
+  let index     ;
+  try { index = JSON.parse(raw); } catch { return fail('index', 'bad-type', 'index is not JSON', 'a JSON object'); }
+  const findings        = [];
+  if (closed(index, ['format', 'packages'], 'index', findings)) {
+    if (index.format !== 1) findings.push(problem('index.format', 'bad-type', 'unsupported index format', 1));
+    if (!Array.isArray(index.packages)) {
+      findings.push(problem('index.packages', 'bad-type', 'must be an array', 'an array of packages'));
+    } else {
+      const ids = new Set        ();
+      index.packages.forEach((pkg     , p        ) => {
+        const field = `index.packages[${p}]`;
+        if (!closed(pkg, ['id', 'versions'], field, findings)) return;
+        if (!isPackageId(pkg.id) || ids.has(pkg.id)) {
+          findings.push(problem(`${field}.id`, 'bad-id', 'invalid or duplicate package id', 'a unique IC-003 package id'));
+        }
+        ids.add(pkg.id);
+        if (!Array.isArray(pkg.versions)) {
+          findings.push(problem(`${field}.versions`, 'bad-type', 'must be an array', 'an array of versions'));
+          return;
+        }
+        const versions = new Set        ();
+        pkg.versions.forEach((entry     , v        ) => {
+          const at = `${field}.versions[${v}]`;
+          if (!closed(entry, ['version', 'doflow', 'source'], at, findings)) return;
+          if (!exact(entry.version) || versions.has(entry.version)) {
+            findings.push(problem(`${at}.version`, 'bad-type', 'invalid or duplicate version', 'a unique exact semver'));
+          }
+          versions.add(entry.version);
+          if (!parseHostRange(entry.doflow).ok) {
+            findings.push(problem(`${at}.doflow`, 'bad-type', 'invalid host range', 'the IC-016 host range grammar'));
+          }
+          findings.push(...pinnedSourceFindings(entry.source, `${at}.source`));
+        });
+      });
+    }
+  }
+  return findings.length ? { ok: false, findings } : { ok: true, index };
+}
+
+function pickVersion(index     , id        , { version, host }     )      {
+  const pkg = index.packages.find((entry     ) => entry.id === id);
+  if (!pkg) return { ok: false, findings: [problem('id', 'bad-id', `no index package '${id}'`, index.packages.map((entry     ) => entry.id))] };
+  if (version !== undefined) {
+    const entry = pkg.versions.find((candidate     ) => candidate.version === version);
+    return entry ? { ok: true, entry } : {
+      ok: false, findings: [problem('version', 'bad-id', `no version '${version}' of '${id}'; available versions: ${pkg.versions.map((candidate     ) => candidate.version).join(', ')}`, pkg.versions.map((candidate     ) => candidate.version))],
+    };
+  }
+  const candidates = pkg.versions.filter((entry     ) => parseSemVer(entry.version).prerelease.length === 0
+    && satisfiesHostRange(host, entry.doflow));
+  candidates.sort((left     , right     ) => compareSemVer(right.version, left.version));
+  return candidates.length ? { ok: true, entry: candidates[0] } : {
+    ok: false, findings: [problem('version', 'host-incompatible', `no stable version of '${id}' admits host ${host}`, 'a non-prerelease version compatible with this host')],
+  };
+}
+
+module.exports = { readIndex, pickVersion, pinnedSourceFindings };

package/src/runtime/packages/instruction.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { qualifiedId, projectedName } = require('../../helper/package-ids.js');
+
+function readFrontmatter(text     )                                {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!match) return null;
+  const values                         = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    if (line.trim() === '') continue;
+    const item = /^([A-Za-z][A-Za-z0-9_-]*):[ \t]*(.*)$/.exec(line);
+    if (!item || Object.hasOwn(values, item[1])) return null;
+    let value = item[2].trim();
+    if (value.startsWith('"')) {
+      if (value.length < 2 || !value.endsWith('"')) return null;
+      value = value.slice(1, -1);
+    } else if (value.endsWith('"')) return null;
+    values[item[1]] = value;
+  }
+  return values;
+}
+
+function finding(field        , code        , message        , allowed     )      {
+  return { field, code, message, allowed };
+}
+
+function judgeInstruction(validatorKey        , localId        , realPath        , { packageId, fsImpl = fs }     )        {
+  const findings        = [];
+  const qualified = qualifiedId(packageId, localId);
+  const name = qualified ? projectedName(qualified) : null;
+  if (!name) return [finding('.name', 'contribution-invalid', 'the projected instruction name cannot be derived', 'a valid package and local id')];
+
+  if (validatorKey === 'skill-v1') {
+    let skillFile        ;
+    try {
+      skillFile = path.join(realPath, 'SKILL.md');
+      if (!fsImpl.statSync(skillFile).isFile()) {
+        return [finding('.file', 'file-missing', 'SKILL.md is not a regular file in the skill directory', 'a regular SKILL.md file')];
+      }
+    } catch {
+      return [finding('.file', 'file-missing', 'SKILL.md is missing from the skill directory', 'a regular SKILL.md file')];
+    }
+    if (path.basename(realPath) !== name) {
+      findings.push(finding('.dir', 'name-mismatch', `skill directory name must be '${name}'`, name));
+    }
+    let metadata                               ;
+    try {
+      metadata = readFrontmatter(fsImpl.readFileSync(skillFile, 'utf8'));
+    } catch {
+      metadata = null;
+    }
+    if (!metadata) findings.push(finding('', 'contribution-invalid', 'SKILL.md must begin with valid name/value frontmatter', 'frontmatter between --- lines'));
+    else if (!metadata.name) findings.push(finding('.name', 'contribution-invalid', 'skill frontmatter name is required', name));
+    else if (metadata.name !== name) findings.push(finding('.name', 'name-mismatch', `skill frontmatter name must be '${name}'`, name));
+    return findings;
+  }
+
+  if (validatorKey === 'agent-v1') {
+    let metadata                               ;
+    try {
+      metadata = readFrontmatter(fsImpl.readFileSync(realPath, 'utf8'));
+    } catch {
+      metadata = null;
+    }
+    if (!metadata) return [finding('', 'contribution-invalid', 'agent file must begin with valid name/value frontmatter', 'frontmatter between --- lines')];
+    if (!metadata.name) findings.push(finding('.name', 'contribution-invalid', 'agent frontmatter name is required', name));
+    else if (metadata.name !== name) findings.push(finding('.name', 'name-mismatch', `agent frontmatter name must be '${name}'`, name));
+    if (typeof metadata.description !== 'string' || metadata.description.length < 1 || metadata.description.length > 160) {
+      findings.push(finding('.description', 'contribution-invalid', 'agent description must be 1 to 160 characters', '1 to 160 characters'));
+    }
+    if (metadata.access !== 'read-only' && metadata.access !== 'write') {
+      findings.push(finding('.access', 'contribution-invalid', "agent access must be 'read-only' or 'write'", ['read-only', 'write']));
+    }
+    return findings;
+  }
+
+  return [finding('', 'contribution-invalid', `unknown instruction validator '${validatorKey}'`, ['skill-v1', 'agent-v1'])];
+}
+
+function skillValidator(localId     , realPath     , context      = {})           {
+  return judgeInstruction('skill-v1', localId, realPath, context).map((item     ) => item.message);
+}
+
+function agentValidator(localId     , realPath     , context      = {})           {
+  return judgeInstruction('agent-v1', localId, realPath, context).map((item     ) => item.message);
+}
+
+module.exports = { judgeInstruction, skillValidator, agentValidator };

package/src/runtime/packages/manifest.js

@@ -0,0 +1,331 @@
+'use strict';
+
+/**
+ * The package manifest checker (122 IC-001, IC-003, IC-004). `checkManifest` judges one `doflow-package.json`
+ * (text or parsed) and returns IC-004 findings; with `root` it also reads and validates each contribution
+ * file through the point's validator. `checkPackage` adds the IC-005 tree rules and the digests for a package
+ * directory. Neither throws on content and neither writes. Collisions with recorded packages are not judged
+ * here: no records exist before the lifecycle verbs (Phase B).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseSemVer, parseHostRange, satisfiesHostRange } = require('../../helper/semver.js');
+const { isPackageId, isLocalId, isReservedPackageId, qualifiedId } = require('../../helper/package-ids.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { loadPoints, judgeContribution, POINT_VALIDATORS } = require('./points.js');
+const { judgeInstruction } = require('./instruction.js');
+const { walkTree, digestFiles, capabilityDigest, SEGMENT, SEGMENT_GRAMMAR } = require('./digest.js');
+const { duplicateKeys, loadProtocols, lensIds, coreTiers } = require('../review/protocols.js');
+const { dominates } = require('../review/dominance.js');
+const { programFindings } = require('./programs.js');
+
+const MANIFEST_FILE = 'doflow-package.json';
+const MANIFEST_MAX_BYTES = 64 * 1024;
+const TOP_KEYS = ['manifest', 'id', 'version', 'summary', 'doflow', 'programs', 'contributions'];
+const ENTRY_KEYS = ['point', 'version', 'id', 'file', 'dir', 'programs'];
+const PRESET_KIND                         = { 'review-preset-v1': 'review', 'debate-preset-v1': 'debate' };
+const PACKAGE_ID_GRAMMAR = '2 to 16 characters of a-z, 0-9 and single hyphens, starting with a letter and ending with a letter or digit';
+const LOCAL_ID_GRAMMAR = '2 to 15 characters of a-z, 0-9 and single hyphens, starting with a letter and ending with a letter or digit';
+const BARE_ID = /^[a-z][a-z0-9-]*$/;
+
+const isObject = (value     )          => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Names of the core agents: `all`, and `readOnly` (`access: read-only`, the seats of INV-2, which covers review only).
+ * Read from core/registry/workflows.json `agents.access`, which an installed runtime ships (it has no core/shared);
+ * G63 holds that map equal to the spec frontmatter.
+ */
+function coreAgents(repoRoot        , fsImpl     )                                        {
+  const found = { all: []            , readOnly: []             };
+  try {
+    const access = JSON.parse(String(fsImpl.readFileSync(path.join(repoRoot, 'core', 'registry', 'workflows.json'), 'utf8'))).agents.access;
+    found.all = Object.keys(access).sort();
+    found.readOnly = found.all.filter((name) => access[name] === 'read-only');
+  } catch { /* an unreadable map leaves no agent usable; the validator then names that */ }
+  return found;
+}
+
+/** `allowed` for a point validator's message: the part after "must be (one of)", else the whole message. */
+function allowedOf(message        )                    {
+  const list = message.match(/must be one of (.+)$/);
+  if (list) return list[1].split(', ');
+  const rest = message.match(/must (?:be|match|not exceed) (.+)$/);
+  return rest ? rest[1] : message;
+}
+
+/**
+ * Check a manifest. `input` is the manifest text (preferred: duplicate keys and the size limit are only
+ * visible there) or a parsed object. Options: `pointsRegistry` (a loaded point registry, required),
+ * `hostVersion` (an unreadable one is `host-incompatible`: the range cannot be shown to hold), `bundled` (ids of the first-party manifests, which alone may use reserved and bare ids),
+ * `root` (the package directory, to read contribution files), `protocols` (the core protocol registry;
+ * default: the installed one), `repoRoot`, `fsImpl`, `hostExempt` (a person `exempt` grant matched, IC-008: a host
+ * outside the range is then a `host-incompatible` warning, never an error). Returns the IC-004 findings.
+ */
+function checkManifest(input     , options      = {})        {
+  const { pointsRegistry, hostVersion, root, repoRoot = REPO_ROOT, fsImpl = fs } = options;
+  const bundled           = (options.bundled ?? []).map((b     ) => (typeof b === 'string' ? b : b?.id));
+  const findings        = [];
+  let packageId                = null;
+  const report = (field        , code        , message        , allowed     , severity = 'error') =>
+    findings.push({ package: packageId, field, code, severity, message, allowed });
+  try {
+    check();
+  } catch (error     ) {
+    report('manifest', 'bad-type', `the manifest could not be checked: ${error?.message || String(error)}`, 'a JSON object');
+  }
+  return findings;
+
+  function check()       {
+    const forbidden           = pointsRegistry.forbiddenFields;
+    let manifest = input;
+    if (typeof input === 'string') {
+      if (Buffer.byteLength(input) > MANIFEST_MAX_BYTES) {
+        report(MANIFEST_FILE, 'too-large', `the manifest is larger than ${MANIFEST_MAX_BYTES} bytes`, `at most ${MANIFEST_MAX_BYTES} bytes`);
+        return;
+      }
+      try { manifest = JSON.parse(input); } catch (error     ) {
+        report(MANIFEST_FILE, 'bad-type', `the manifest is not valid JSON: ${error.message}`, 'a JSON object');
+        return;
+      }
+      for (const message of duplicateKeys(input)) report(message.replace(/^.* in /, ''), 'duplicate-key', message, 'each key at most once');
+    }
+    if (!isObject(manifest)) { report('manifest', 'bad-type', 'the manifest must be a JSON object', 'a JSON object'); return; }
+    if (typeof manifest.id === 'string') packageId = manifest.id;
+    const isBundled = typeof manifest.id === 'string' && bundled.includes(manifest.id);
+
+    for (const key of Object.keys(manifest)) {
+      if (TOP_KEYS.includes(key)) continue;
+      if (forbidden.includes(key)) report(key, 'forbidden-field', `'${key}' is decided by DoFlow or the person, never by a package`, 'omit the field');
+      else report(key, 'unknown-key', `'${key}' is not a manifest field`, TOP_KEYS);
+    }
+
+    if (!Object.hasOwn(manifest, 'manifest')) report('manifest', 'bad-type', 'manifest is required', [1]);
+    else if (manifest.manifest !== 1) report('manifest', 'unsupported-manifest', `manifest format ${JSON.stringify(manifest.manifest)} is not supported`, [1]);
+
+    if (!isPackageId(manifest.id)) report('id', 'bad-id', `package id ${JSON.stringify(manifest.id)} breaks the grammar`, PACKAGE_ID_GRAMMAR);
+    else if (isReservedPackageId(manifest.id) && !isBundled) {
+      report('id', 'reserved-id', `package id '${manifest.id}' is reserved`, 'an id that is not doflow, do, core, user, project, local, env, auto, package, packages and does not start with do- or doflow-');
+    }
+
+    if (typeof manifest.version !== 'string' || manifest.version.length > 64 || parseSemVer(manifest.version) === null) {
+      report('version', 'bad-type', `version ${JSON.stringify(manifest.version)} is not a semver 2.0.0 string of at most 64 characters`, 'an exact semver 2.0.0 version');
+    }
+    if (Object.hasOwn(manifest, 'summary')
+      && (typeof manifest.summary !== 'string' || manifest.summary.length > 120 || /[\u0000-\u001f\u007f<>`]/.test(manifest.summary))) {
+      report('summary', 'bad-type', 'summary is not plain text of at most 120 characters', 'at most 120 characters, no control characters, < > or backticks');
+    }
+
+    if (!Object.hasOwn(manifest, 'doflow')) report('doflow', 'bad-type', 'doflow (the host range) is required', 'a host range');
+    else {
+      const range = parseHostRange(manifest.doflow);
+      if (!range.ok) report('doflow', range.error.code, range.error.message, range.error.allowed);
+      else if (!hostVersion) {
+        report('doflow', 'host-incompatible', 'the running DoFlow version cannot be read', manifest.doflow);
+      } else if (!satisfiesHostRange(hostVersion, range)) {
+        report('doflow', 'host-incompatible', `DoFlow ${hostVersion} is outside the range ${manifest.doflow}`, manifest.doflow, options.hostExempt === true ? 'warning' : 'error');
+      }
+    }
+
+    const contributions = manifest.contributions;
+    let executable = false;
+    if (!Array.isArray(contributions) || contributions.length === 0 || contributions.length > 64) {
+      report('contributions', 'bad-type', 'contributions must be a non-empty array of at most 64 entries', 'an array of 1 to 64 contributions');
+    } else {
+      const seen = new Set        ();
+      const protocols = options.protocols ?? loadProtocols({ repoRoot }).registry;
+      const context = { protocols, agents: coreAgents(repoRoot, fsImpl), manifest };
+      contributions.forEach((entry     , index        ) => {
+        const where = `contributions[${index}]`;
+        if (!isObject(entry)) { report(where, 'bad-type', 'a contribution must be an object', 'an object'); return; }
+        const point = pointsRegistry.points.find((p     ) => p.id === entry.point);
+        if (point?.tier === 'executable') executable = true;
+        checkEntry(entry, index, point, isBundled, seen, context);
+      });
+    }
+    if (Object.hasOwn(manifest, 'programs') && !executable) {
+      report('programs', 'forbidden-field', 'programs belong only to a package that contributes to an executable point', 'omit the field');
+    }
+    if (executable) {
+      findings.push(...programFindings(manifest, { root, pointsRegistry, fsImpl, packageId }));
+    }
+  }
+
+  function checkEntry(entry     , index        , point     , isBundled         , seen             , context     )       {
+    const where = `contributions[${index}]`;
+    for (const key of Object.keys(entry)) {
+      if (ENTRY_KEYS.includes(key)) continue;
+      if (pointsRegistry.forbiddenFields.includes(key)) report(`${where}.${key}`, 'forbidden-field', `'${key}' is decided by DoFlow or the person, never by a package`, 'omit the field');
+      else report(`${where}.${key}`, 'unknown-key', `'${key}' is not a contribution field`, ENTRY_KEYS);
+    }
+    if (Object.hasOwn(entry, 'programs') && point?.tier !== 'executable') {
+      report(`${where}.programs`, 'forbidden-field', 'programs belong only to a contribution on an executable point', 'omit the field');
+    }
+    if (typeof entry.point !== 'string') { report(`${where}.point`, 'bad-type', 'point must be a string', pointsRegistry.points.map((p     ) => p.id)); return; }
+    if (!Number.isInteger(entry.version)) { report(`${where}.version`, 'bad-type', 'version must be an integer', point?.versions ?? 'an integer'); return; }
+    const judged = judgeContribution(pointsRegistry, entry, { packageId, index });
+    if (judged) findings.push(judged);
+
+    // The id: a local id, or for a first-party manifest any bare built-in id; a bare built-in id elsewhere is reserved.
+    const builtin = new Set        (Object.keys(context.protocols?.presets ?? {}));
+    let qid                = null;
+    if (typeof entry.id !== 'string' || !(isBundled ? BARE_ID.test(entry.id) : isLocalId(entry.id))) {
+      report(`${where}.id`, 'bad-id', `contribution id ${JSON.stringify(entry.id)} breaks the grammar`, LOCAL_ID_GRAMMAR);
+    } else if (!isBundled && builtin.has(entry.id)) {
+      report(`${where}.id`, 'reserved-id', `'${entry.id}' is a built-in id; only the first-party package uses a bare built-in id`, 'a local id that is not a built-in id');
+    } else {
+      const key = `${entry.point}\0${entry.id}`;
+      if (seen.has(key)) report(`${where}.id`, 'bad-id', `(${entry.point}, ${entry.id}) is contributed twice`, 'each (point, id) at most once');
+      seen.add(key);
+      qid = isBundled ? entry.id : qualifiedId(packageId          , entry.id);
+    }
+
+    const wanted = point?.entry;
+    const given = ['file', 'dir'].filter((key) => Object.hasOwn(entry, key));
+    if (given.length !== 1 || (wanted && given[0] !== wanted)) {
+      report(`${where}.${wanted ?? 'file'}`, 'bad-type', `exactly one of file or dir is required${wanted ? `; point '${point.id}' takes ${wanted}` : ''}`, wanted ?? ['file', 'dir']);
+      return;
+    }
+    const kind = given[0];
+    const found = locate(entry[kind], `${where}.${kind}`, kind);
+    if (judged || !found || !qid) return;
+    if (point?.validator === 'skill-v1' || point?.validator === 'agent-v1') {
+      if (point.validator === 'agent-v1' && fsImpl.statSync(found).size > pointsRegistry.limits.fileBytes) return;
+      const instructionFindings = judgeInstruction(point.validator, entry.id, found, { packageId, fsImpl });
+      for (const item of instructionFindings) report(`${qid}${item.field}`, item.code, item.message, item.allowed);
+      return;
+    }
+    if (kind !== 'file') return;
+    validateFile(found, entry, point, qid, context);
+  }
+
+  /** Lexical and realpath checks on a manifest path; returns the real path when it is usable. */
+  function locate(rel     , field        , kind        )                {
+    const limits = pointsRegistry.limits;
+    if (typeof rel !== 'string' || rel.length === 0) { report(field, 'bad-type', 'the path must be a non-empty string', 'a POSIX path relative to the package root'); return null; }
+    if (rel.startsWith('/') || rel.split('/').includes('..')) { report(field, 'path-escapes-root', `${rel} leaves the package root`, 'a path inside the package root'); return null; }
+    if (rel.length > limits.pathLength || rel.split('/').some((s        ) => !SEGMENT.test(s))) {
+      report(field, 'bad-type', `${rel} breaks the path rules`, `${SEGMENT_GRAMMAR} per segment, at most ${limits.pathLength} characters`);
+      return null;
+    }
+    if (!root) return null;
+    let real        ;
+    let rootReal        ;
+    try {
+      rootReal = fsImpl.realpathSync(root);
+      real = fsImpl.realpathSync(path.join(root, rel));
+    } catch {
+      report(field, 'file-missing', `${rel} does not exist`, `an existing ${kind === 'dir' ? 'directory' : 'file'}`);
+      return null;
+    }
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep)) {
+      report(field, 'path-escapes-root', `${rel} resolves outside the package root`, 'a path inside the package root');
+      return null;
+    }
+    const stat = fsImpl.statSync(real);
+    if (kind === 'file' ? !stat.isFile() : !stat.isDirectory()) {
+      report(field, 'file-missing', `${rel} is not a ${kind === 'dir' ? 'directory' : 'regular file'}`, `an existing ${kind === 'dir' ? 'directory' : 'file'}`);
+      return null;
+    }
+    return real;
+  }
+
+  /** Read one contribution file and run the point's validator, then comparability for a preset. */
+  function validateFile(real        , entry     , point     , qid        , context     )       {
+    if (fsImpl.statSync(real).size > pointsRegistry.limits.fileBytes) return; // the tree rules report too-large
+    const text = fsImpl.readFileSync(real, 'utf8');
+    const invalid = (field        , message        ) => report(field, 'contribution-invalid', message, allowedOf(message));
+    let parsed     ;
+    try { parsed = JSON.parse(text); } catch (error     ) { invalid(qid, `${entry.file} is not valid JSON: ${error.message}`); return; }
+    for (const message of duplicateKeys(text)) report(`${qid}.${message.replace(/^.* in /, '')}`, 'duplicate-key', message, 'each key at most once');
+    const validator = POINT_VALIDATORS[point.validator];
+    const kind = PRESET_KIND[point.validator];
+    const protocols = context.protocols;
+    if (!validator) return;
+    if (kind && !protocols) { invalid(qid, 'the core protocol registry is unreadable, so a preset cannot be checked'); return; }
+    let errors          ;
+    let comparable                 = null;
+    if (kind) {
+      const judged = judgePackagePreset(point.validator, entry.id, parsed, { protocols, agents: context.agents });
+      if (judged.depth) report(`${qid}.depth`, 'forbidden-field', 'depth is not allowed in a package preset (the depth vocabulary stays core)', 'omit the field');
+      errors = judged.errors;
+      comparable = judged.comparable;
+    } else {
+      errors = validator(entry.id, parsed, { ...context, entry, packageId });
+    }
+    const prefix = `presets.${entry.id}`;
+    for (const message of errors) {
+      const token = message.split(' ')[0];
+      invalid(token.startsWith(prefix) ? `${qid}${token.slice(prefix.length)}` : qid, message);
+    }
+    if (errors.length > 0 || !kind) return;
+    if (!comparable) {
+      report(qid, 'incomparable', `${qid} dominates no core ${kind} preset, so it cannot be ordered against them`, `a ${kind} preset that is at least as strict as one core ${kind} preset`);
+    }
+  }
+}
+
+/**
+ * One contributed preset in package mode (IC-014): the validator `check` runs on a package file, shared with the
+ * runtime seam (`contributionsFor`) so the two cannot disagree. `validatorKey` is the point's validator
+ * (`review-preset-v1` or `debate-preset-v1`), `protocols` the core registry, `agents` the `coreAgents` result.
+ * Returns `{ kind, depth, errors, comparable }`: `depth` says the preset carried the refused `depth` field (judged
+ * without it, as `check` reports it separately), `errors` are the validator messages, and `comparable` is whether
+ * it dominates at least one core preset of its kind (null while there are errors).
+ */
+function judgePackagePreset(validatorKey        , localId        , parsed     , { protocols, agents }     )                                                                                 {
+  const kind = PRESET_KIND[validatorKey];
+  const depth = isObject(parsed) && 'depth' in parsed;
+  let body = parsed;
+  if (depth) { body = { ...parsed }; delete body.depth; }
+  const tiers = coreTiers();
+  const errors           = POINT_VALIDATORS[validatorKey](localId, body, {
+    mode: 'package', lensIds: lensIds(protocols), hardRoundCap: protocols.hardRoundCap, tiers, agents: kind === 'review' ? agents.readOnly : agents.all,
+  });
+  const comparable = errors.length > 0 ? null : Object.values     (protocols.presets).some((core) => core?.kind === kind
+    && dominates(body, core, { tiers, synthesizerStrength: protocols.synthesizerStrength }));
+  return { kind, depth, errors, comparable };
+}
+
+/**
+ * Check a package directory: the manifest, the IC-005 tree rules and, when there is no error, both digests.
+ * Returns `{ ok, findings, contentDigest?, capabilityDigest? }`; never throws on content, writes nothing.
+ */
+function checkPackage(dir        , options      = {})      {
+  const { fsImpl = fs, repoRoot = REPO_ROOT } = options;
+  const loaded = options.pointsRegistry ? { ok: true, registry: options.pointsRegistry } : loadPoints({ repoRoot });
+  if (!loaded.ok) {
+    return { ok: false, findings: [{ package: null, field: 'points', code: 'state-unreadable', severity: 'error', message: (loaded       ).errors.join('; '), allowed: 'a readable point registry' }] };
+  }
+  const pointsRegistry = loaded.registry;
+  const fail = (code        , message        , allowed        ) => ({
+    ok: false, findings: [{ package: null, field: MANIFEST_FILE, code, severity: 'error', message, allowed }],
+  });
+  let text        ;
+  let walked                                   ;
+  try {
+    if (!fsImpl.statSync(dir).isDirectory()) return fail('file-missing', `${dir} is not a directory`, 'a package directory');
+    walked = walkTree(dir, pointsRegistry.limits, { fsImpl });
+    const manifestFile = walked.files.find((f     ) => f.rel === MANIFEST_FILE);
+    if (!manifestFile) return { ok: false, findings: [...walked.findings, { package: null, field: MANIFEST_FILE, code: 'file-missing', severity: 'error', message: `${MANIFEST_FILE} is missing`, allowed: `a ${MANIFEST_FILE} at the package root` }] };
+    if (manifestFile.size > MANIFEST_MAX_BYTES) return { ok: false, findings: [...walked.findings, { package: null, field: MANIFEST_FILE, code: 'too-large', severity: 'error', message: `the manifest is larger than ${MANIFEST_MAX_BYTES} bytes`, allowed: `at most ${MANIFEST_MAX_BYTES} bytes` }] };
+    text = fsImpl.readFileSync(manifestFile.abs, 'utf8');
+  } catch (error     ) {
+    return fail('file-missing', `cannot read ${dir}: ${error.message}`, 'a readable package directory');
+  }
+  const findings = checkManifest(text, { ...options, pointsRegistry, root: dir });
+  let id                = null;
+  try { id = JSON.parse(text)?.id ?? null; } catch { /* checkManifest reported it */ }
+  for (const finding of walked.findings) findings.push({ ...finding, package: typeof id === 'string' ? id : null });
+  const ok = !findings.some((f) => f.severity === 'error');
+  const result      = { ok, findings };
+  if (ok) {
+    const manifest = JSON.parse(text);
+    const tiers = Object.fromEntries(pointsRegistry.points.map((p     ) => [p.id, p.tier]));
+    result.contentDigest = digestFiles(walked.files, fsImpl);
+    result.capabilityDigest = capabilityDigest(manifest, { trustPolicyVersion: pointsRegistry.trustPolicyVersion, tiers });
+  }
+  return result;
+}
+
+module.exports = { checkManifest, checkPackage, judgePackagePreset, coreAgents, MANIFEST_FILE, MANIFEST_MAX_BYTES };