@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/settings/config-write.js

@@ -0,0 +1,314 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * `doflow config schema|validate|set|unset` (119 IC-007, IC-008, IC-009; D-2). One read, validate and
+ * write path over the settings registry, the resolver and the atomic `writeLayer`. A value is never
+ * judged by a copy of the fold's rules: the layer document as it would be after the write is served to
+ * `loadSettings` in place of the file, and the key's candidate for that layer is read back, so scope
+ * (rule 1), the value rules and narrowing (rule 3) are the resolver's own verdicts.
+ *
+ * Checks run in this order and the first failing one is reported per key: locked (`invariant.*`),
+ * unknown-key, security (a `securityRelevant` key is written by a person in the file, never by this
+ * verb), then at a layer too-large (the file as `writeLayer` would write it is over the reader's
+ * limit), scope, the value rules (type, enum, range, items, length), not-narrower. Nothing is written,
+ * and no directory is created, until every check passes.
+ */
+
+const path = require('node:path');
+const nodeFs = require('node:fs');
+const { configHome } = require('../config-home.js');
+const { finishRuntime, usageError } = require('../cli-result.js');
+const { validateValue, readLayerFile } = require('./files.js');
+const { loadSettings, clearSettingsCache } = require('./resolve.js');
+const { projectLayerSource } = require('./project-layers.js');
+const { writeLayer, layerDocument, serializeLayer, oversize } = require('./write.js');
+const { REF_META } = require('./refs.js');
+const { maskUrl } = require('./shared.js');
+const { loadProtocols, presetIds } = require('../review/protocols.js');
+const { LADDER_MAX, classifyWorkerId, retiredAdvisory } = require('../../registry/worker-ids.js');
+
+const LAYERS = ['user', 'project', 'local'];
+const LAYER_FILE                         = { user: 'settings.json', project: 'settings.json', local: 'settings.local.json' };
+/** A write that finds the layer changed since it was checked is checked again, this many times in all. */
+const WRITE_ATTEMPTS = 3;
+/** `writeLayer` refusals reported under their own code; any other write fault is `write-failed`. */
+const WRITER_CODES = new Set(['locked', 'changed', 'too-large']);
+/** The codes whose entry carries the key's `allowed` values (IC-009). */
+const VALUE_CODES = new Set(['type', 'enum', 'range', 'items', 'length', 'url', 'reserved']);
+
+                                                                                                                 
+                                                
+
+function isObject(value         )                               {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function allowedOf(registry     , key        )          {
+  const spec = registry.keys.get(key);
+  if (!spec) return null;
+  if (spec.type === 'enum' || spec.type === 'worker-list' || spec.type === 'worker-models' || (spec.type === 'string-list' && spec.valuesRef)) return registry.enumValues(key);
+  if (spec.type === 'integer') return { min: spec.min ?? null, max: spec.max ?? null };
+  return null;
+}
+
+function entryOf(registry     , key        , layer               , code        , message        )        {
+  return { key, layer, ok: false, code, message, allowed: VALUE_CODES.has(code) ? allowedOf(registry, key) : null };
+}
+
+function parseValue(text        )         {
+  try { return { ok: true, value: JSON.parse(text) }; } catch { return { ok: false, value: null }; }
+}
+
+const NOT_JSON = 'the value is not JSON; quote a string, for example \'"on"\'';
+
+/** The checks that need only the key: locked, unknown-key and, for a write, security. */
+function keyEntry(registry     , key        , layer               , writes         )               {
+  if (key.startsWith('invariant.')) {
+    return entryOf(registry, key, layer, 'locked', `invariant ${key.slice('invariant.'.length)} is locked in core/registry/protocols.json and is never a setting`);
+  }
+  const spec = registry.keys.get(key);
+  if (!spec) return entryOf(registry, key, layer, 'unknown-key', `${key} is not a registered setting`);
+  if (writes && spec.securityRelevant) {
+    return entryOf(registry, key, layer, 'security', `${key} is security-relevant: a person writes it in the settings file; config set and unset never do`);
+  }
+  return null;
+}
+
+/** `fsImpl` with one file's bytes replaced; everything else is read from `base`. */
+function servedFs(file        , bytes        , base     )      {
+  const asRead = (p        , options      )      => {
+    const encoding = typeof options === 'string' ? options : options?.encoding;
+    return encoding ? bytes.toString(encoding) : bytes;
+  };
+  return {
+    statSync: (p        ) => (p === file ? { isFile: () => true, size: bytes.length } : base.statSync(p)),
+    lstatSync: (p        ) => (p === file ? { isFile: () => true, isDirectory: () => false, isSymbolicLink: () => false, size: bytes.length } : base.lstatSync(p)),
+    readFileSync: (p        , options      ) => (p === file ? asRead(p, options) : base.readFileSync(p, options)),
+    accessSync: (p        , mode         ) => (p === file ? undefined : base.accessSync(p, mode)),
+    realpathSync: (p        ) => base.realpathSync(p),
+  };
+}
+
+                                
+/** The layer file for a layer, or the usage message when this machine or folder has none. */
+function layerFile(layer        , env     , projectRoot        , fsImpl     )                            {
+  if (layer === 'user') {
+    const home = configHome(env);
+    if (!home.dir) return { error: 'no config home resolves; set an absolute HOME or XDG_CONFIG_HOME' };
+    return { file: path.join(home.dir, LAYER_FILE.user) };
+  }
+  const source = projectLayerSource(projectRoot, fsImpl);
+  if (!source.layersFrom) return { error: `${projectRoot} has no usable project settings folder (.doflow)` };
+  return { file: path.join(source.layersFrom, LAYER_FILE[layer]) };
+}
+
+/**
+ * The layer-dependent verdict for `value` at `layer` in `file`: the existing document plus the value,
+ * served to the resolver as that file, and the key's candidate read back. Null when the write is fine.
+ * `read` is the caller's own `readLayerFile` result, so a write can require the file it then replaces
+ * to be the one judged here. For `review.rounds` the effective `review.preset` of the same view is read too:
+ * a value below that preset's `rounds.min` is refused; under `auto` it is accepted and, when below the
+ * strictest preset's `rounds.min`, an advisory is pushed to `notes` (the caller's array). `siblings` are other
+ * keys of the same change (a prepared run's settings), served in the document so keys are judged together.
+ */
+function layerEntry(registry     , key        , layer        , file        , parsed        ,
+  { env, projectRoot, fsImpl, repoRoot, notes, siblings, read = readLayerFile(file, { registry, fsImpl, includeDocument: true }) }     )               {
+  if (read.status === 'invalid') {
+    return entryOf(registry, key, layer, 'layer-invalid', `${file} ${read.reason}; fix or remove it first`);
+  }
+  const values                          = read.status === 'ok' ? { ...read.document, ...siblings } : { ...siblings };
+  values[key] = parsed.ok ? parsed.value : null;
+  const bytes = serializeLayer(layerDocument(registry, values));
+  const tooLarge = oversize(file, bytes);
+  if (tooLarge) return entryOf(registry, key, layer, 'too-large', tooLarge.detail);
+  const view = loadSettings({ projectRoot, env, fsImpl: servedFs(file, bytes, fsImpl), registry });
+  const candidate = view.get(key).candidates.find((c     ) => c.layer === layer && c.source === file && !c.legacy);
+  if (!candidate) throw new Error(`the resolver did not read ${file}`);
+  if (candidate.status === 'ignored-scope') return entryOf(registry, key, layer, 'scope', `${key} cannot be set at the ${layer} layer (${candidate.reason})`);
+  if (!parsed.ok) return entryOf(registry, key, layer, 'type', NOT_JSON);
+  if (candidate.status === 'invalid') return entryOf(registry, key, layer, candidate.code, candidate.reason);
+  if (candidate.code === 'retired' && notes && registry.keys.get(key).type === 'enum') notes.push(`note: ${candidate.reason}`);
+  // IC-002, IC-004: valid worker lists and model maps keep dangling ids advisory.
+  const type = registry.keys.get(key).type;
+  if ((type === 'worker-list' || type === 'worker-models') && notes) {
+    const known = registry.enumValues(key) ?? [];
+    const retired = registry.retired?.() ?? [];
+    const ids = type === 'worker-models' ? Object.keys(parsed.value                           ) : parsed.value            ;
+    for (const id of ids) {
+      if (id === 'primary') continue;
+      const kind = classifyWorkerId(id, known, retired);
+      if (kind === 'retired') notes.push(`note: ${retiredAdvisory(key, retired.find((entry     ) => entry.id === id))}`);
+      else if (kind === 'dangling') notes.push(`note: ${key}: worker '${id}' is not installed (ignored)`);
+    }
+    if (type === 'worker-list' && candidate.code === 'order-ignored') notes.push(`note: ${key}: the order is ignored at the ${layer} layer; the order below applies`);
+  }
+  if (candidate.status === 'not-narrower') return entryOf(registry, key, layer, 'not-narrower', `${candidate.reason} (the value is wider than the layers below)`);
+  if (key === 'review.rounds' && Number.isInteger(parsed.value)) return roundsFloor(registry, view, layer, parsed.value          , repoRoot, notes);
+  return null;
+}
+
+/** The `rounds.min` check of `review.rounds` against the preset the view resolves (see layerEntry). */
+function roundsFloor(registry     , view     , layer        , rounds        , repoRoot                    , notes                      )               {
+  const protocols = loadProtocols({ repoRoot });
+  if (!protocols.ok) throw new Error(protocols.errors.join('; '));
+  const preset = view.get('review.preset').value;
+  const presets = protocols.registry.presets;
+  if (typeof preset === 'string' && preset !== 'auto' && Object.hasOwn(presets, preset)) {
+    const floor = presets[preset].rounds.min;
+    return rounds < floor ? entryOf(registry, 'review.rounds', layer, 'not-narrower', `review.rounds ${rounds} is below ${preset} rounds.min ${floor}`) : null;
+  }
+  const strictest = presetIds(protocols.registry, 'review')[0];
+  const floor = presets[strictest]?.rounds.min;
+  if (preset === 'auto' && notes && floor !== undefined && rounds < floor) {
+    notes.push(`note: review.rounds ${rounds} is below ${strictest} rounds.min ${floor}; the resolver ignores it when the risk rule picks ${strictest}`);
+  }
+  return null;
+}
+
+function refuse(action        , errors         , json         )         {
+  if (json) console.log(JSON.stringify({ ok: false, errors }, null, 2));
+  else for (const error of errors) console.error(`config ${action}: ${error.key}: ${error.code}: ${error.message}`);
+  return finishRuntime(1);
+}
+
+function done(json         , payload     , text          )         {
+  if (json) console.log(JSON.stringify(payload, null, 2));
+  else for (const line of text) console.log(line);
+  return finishRuntime(0);
+}
+
+// ── schema ────────────────────────────────────────────────────────────────────────────────────────
+
+function defaultOf(registry     , key        )          {
+  const spec = registry.keys.get(key);
+  if (Object.hasOwn(spec, 'default')) return spec.default;
+  const deps                          = {};
+  for (const dep of REF_META[spec.defaultRef]?.dependsOn ?? []) deps[dep] = defaultOf(registry, dep);
+  return registry.resolveRef(spec.defaultRef, deps);
+}
+
+function presetSummary(preset     )         {
+  const seats = preset.seats.length;
+  const rounds = preset.rounds.default;
+  return `${seats} seat${seats === 1 ? '' : 's'}, ${rounds} round${rounds === 1 ? '' : 's'}, synthesizer ${preset.synthesizer}, decider ${preset.decider}`;
+}
+
+function buildSchema(registry     , protocols     )      {
+  const keys = [...registry.keys].map(([key, spec]               ) => {
+    const fallback = defaultOf(registry, key);
+    return {
+      key, type: spec.type, values: registry.enumValues(key), order: spec.order ?? null, tiers: spec.tiers ?? null,
+      min: spec.min ?? null, max: spec.max ?? null, maxItems: spec.type === 'worker-list' ? LADDER_MAX + 1 : spec.maxItems ?? null, maxLength: spec.maxLength ?? null,
+      default: spec.type === 'url' && typeof fallback === 'string' ? maskUrl(fallback) : fallback,
+      scope: spec.scope, combine: spec.combine, description: spec.description,
+      securityRelevant: spec.securityRelevant, writable: !spec.securityRelevant, locked: false,
+    };
+  });
+  const invariants = protocols.invariants.map((inv     ) => ({
+    id: inv.id, key: `invariant.${inv.id}`, locked: true, writable: false, statement: inv.statement, enforcedBy: inv.enforcedBy,
+    ...(inv.authorKinds ? { authorKinds: inv.authorKinds } : {}),
+  }));
+  const presets = ['review', 'debate'].flatMap((kind) => presetIds(protocols, kind)).map((id        ) => {
+    const preset = protocols.presets[id];
+    return {
+      id, kind: preset.kind, ...(preset.kind === 'review' ? { depth: preset.depth } : {}),
+      seats: preset.seats.length, rounds: preset.rounds.default, summary: presetSummary(preset),
+    };
+  });
+  return { schema: 1, keys, invariants, presets };
+}
+
+function handleSchema({ json, registry, repoRoot, fsImpl }     )         {
+  let schema     ;
+  try {
+    const protocols = loadProtocols({ repoRoot, fsImpl });
+    if (!protocols.ok) throw new Error(protocols.errors.join('; '));
+    schema = buildSchema(registry, protocols.registry);
+  } catch (error     ) {
+    const detail = error?.message || String(error);
+    if (json) console.log(JSON.stringify({ ok: false, status: 'ERROR', exitCode: 2, error: 'settings-registry-invalid', detail }, null, 2));
+    else console.error(`doflow config: settings schema unavailable: ${detail}`);
+    return finishRuntime(2);
+  }
+  const text = [
+    ...schema.keys.map((k     ) => `${k.key} ${k.type} default=${JSON.stringify(k.default)} scope=${k.scope} writable=${k.writable}`),
+    ...schema.invariants.map((i     ) => `${i.key} locked: ${i.statement}`),
+    ...schema.presets.map((p     ) => `preset ${p.id} ${p.kind} ${p.summary}`),
+  ];
+  return done(json, schema, text);
+}
+
+// ── validate, set, unset ──────────────────────────────────────────────────────────────────────────
+
+function handleChange({ action, key, valueText, layer, json, registry, repoRoot, projectRoot, env, fsImpl }     )         {
+  const writes = action !== 'validate';
+  const root = path.resolve(projectRoot);
+  const keyFault = keyEntry(registry, key, layer ?? null,
+    writes || (layer !== undefined && !['worker-list', 'worker-models'].includes(registry.keys.get(key)?.type)));
+  if (keyFault) return refuse(action, [keyFault], json);
+
+  const parsed         = action === 'unset' ? { ok: true, value: null } : parseValue(valueText);
+  const spec = registry.keys.get(key);
+  if (layer === undefined) {
+    if (!parsed.ok) return refuse(action, [entryOf(registry, key, null, 'type', NOT_JSON)], json);
+    const fault = validateValue(spec, parsed.value, registry.enumValues(key));
+    const retired = fault?.code === 'enum' && spec.valuesRef === 'harnesses.primaryIds'
+      ? (registry.retired?.() ?? []).find((entry     ) => entry.id === parsed.value) : null;
+    if (retired) {
+      const note = `note: ${retiredAdvisory(key, retired)}`;
+      return done(json, { ok: true, errors: [], notes: [note] }, [`${key}: valid`, note]);
+    }
+    if (fault) return refuse(action, [entryOf(registry, key, null, fault.code, fault.reason)], json);
+    return done(json, { ok: true, errors: [] }, [`${key}: valid`]);
+  }
+
+  const where = layerFile(layer, env, root, fsImpl);
+  if ('error' in where) return usageError('config', where.error, json);
+  const { file } = where;
+
+  // The layer is read, judged and written as one unit: `expect` makes writeLayer refuse (code `changed`)
+  // when another writer replaced the file in between, and the unit then runs again on the new file.
+  // `backup` keeps the replaced bytes in `<file>.config.bak` (IC-008 "atomic, backup"; one file, replaced).
+  for (let attempt = 1; ; attempt++) {
+    const read = readLayerFile(file, { registry, fsImpl, includeDocument: true });
+    const expect = read.status === 'ok' ? read.document : null;
+    const notes           = [];
+    let written     ;
+    if (action === 'unset') {
+      if (read.status === 'invalid') return refuse(action, [entryOf(registry, key, layer, 'layer-invalid', `${file} ${read.reason}; fix or remove it first`)], json);
+      if (read.status === 'absent' || !isObject(read.document) || !Object.hasOwn(read.document, key)) {
+        return done(json, { ok: true, key, layer, file, changed: false, errors: [] }, [`${key} is not set  (${layer}: ${file})`]);
+      }
+      written = writeLayer({ file, unset: [key], expect, backup: true, fsImpl });
+    } else {
+      const fault = layerEntry(registry, key, layer, file, parsed, { env, projectRoot: root, fsImpl, repoRoot, notes, read });
+      if (fault) return refuse(action, [fault], json);
+      if (action === 'validate') return done(json, { ok: true, errors: [], ...(notes.length ? { notes } : {}) }, [`${key}: valid  (${layer}: ${file})`, ...notes]);
+      written = writeLayer({ file, set: { [key]: parsed.value }, expect, backup: true, fsImpl });
+    }
+    if (!written.ok && written.code === 'changed' && attempt < WRITE_ATTEMPTS) continue;
+    if (!written.ok) {
+      const code = WRITER_CODES.has(written.code) ? written.code : 'write-failed';
+      return refuse(action, [entryOf(registry, key, layer, code, written.detail)], json);
+    }
+    clearSettingsCache();
+    if (action === 'unset') return done(json, { ok: true, key, layer, file, changed: true, errors: [] }, [`${key} unset  (${layer}: ${file})`]);
+    const resolution = loadSettings({ projectRoot: root, env, fsImpl, registry }).get(key);
+    const origin = { ...resolution.origin };
+    const shown = JSON.stringify(resolution.value);
+    const text = [`${key} = ${shown}  (${origin.layer}: ${origin.source})`];
+    if (origin.source !== file) text.push(`written: ${layer}: ${file}`);
+    text.push(...notes);
+    return done(json, { ok: true, key, layer, file, value: resolution.value, origin, errors: [], ...(notes.length ? { notes } : {}) }, text);
+  }
+}
+
+function handleConfigAction(options     )         {
+  const { action, fsImpl = nodeFs } = options;
+  if (action === 'schema') return handleSchema({ ...options, fsImpl });
+  return handleChange({ ...options, fsImpl });
+}
+
+module.exports = { handleConfigAction, buildSchema, keyEntry, layerFile, layerEntry, LAYERS };

package/src/runtime/settings/files.js

@@ -0,0 +1,271 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Reading one settings layer file (`settings.json` / `settings.local.json`; 086 IC-002, data-model §2)
+ * and the value encodings that file uses. A leaf module: it takes the registry as an argument and
+ * imports nothing from it.
+ *
+ * Nothing here ever returns file text. `JSON.parse` quotes the first bytes of the input in its
+ * "Unexpected token" messages (Node 24 and 26 both do), so a parse failure is reported as a code and a
+ * byte offset only, and `error.message` is never forwarded. `jsonFailure` is the shared helper for any
+ * other reader that parses a user's JSON (the legacy decision-model reads move onto it in C.4).
+ */
+
+const nodeFs = require('node:fs');
+const { workerIdFault, LADDER_MAX } = require('../../registry/worker-ids.js');
+
+/** A file larger than this is a layer fault, not a read (data-model §2). */
+const MAX_BYTES = 65536;
+const BOM = '\uFEFF';
+
+                                                                                                                  
+                                                                                 
+                                                                                                                      
+                                                                                    
+                     
+                                      
+                         
+                                                                                  
+                        
+                                         
+                        
+                             
+                
+                                                                                  
+                                     
+ 
+
+function isObject(value         )                                   {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * The error text of a failed `JSON.parse` reduced to a byte offset into `text`. V8 states a position as
+ * `... in JSON at position N` at the END of the message; the "Unexpected token" form quotes input, so
+ * only the anchored tail is trusted. `Unexpected end of JSON input` means the end of the text.
+ * @param text the string that was parsed (after any BOM was removed)
+ * @param bomBytes bytes removed before `text`, added to the result so the offset is a file offset
+ */
+function jsonFailure(error     , text        , bomBytes = 0)                                            {
+  const message = String(error?.message ?? '');
+  let index                = null;
+  if (message === 'Unexpected end of JSON input') index = text.length;
+  else {
+    const m = / in JSON at position (\d+)(?: \(line \d+ column \d+\))?$/.exec(message);
+    if (m) index = Math.min(Number(m[1]), text.length);
+  }
+  if (index === null) return { offset: null, reason: 'not valid JSON' };
+  const offset = Buffer.byteLength(text.slice(0, index), 'utf8') + bomBytes;
+  return { offset, reason: `not valid JSON at offset ${offset}` };
+}
+
+/** IC-002 `model-id`: 1 to 120 characters, a leading letter or digit (so never `-`), no trailing space. */
+const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9 ._:/@()[\]#+-]*$/;
+const MODEL_ID_MAX = 120;
+/** The two billing values a person may record (the registry's `unknown` is not a claim). */
+const RECORDED_BILLING = ['free', 'metered'];
+const BILLING_ENTRY_FIELDS = ['billing', 'asserted', 'basis'];
+const BILLING_MAX_ENTRIES = 16;
+const BILLING_BASIS_MAX = 120;
+
+/** `YYYY-MM-DD` naming a real calendar date. */
+function isCalendarDate(value         )          {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const at = new Date(Date.UTC(year, month - 1, day));
+  return at.getUTCFullYear() === year && at.getUTCMonth() === month - 1 && at.getUTCDate() === day;
+}
+
+/**
+ * The `workers.billing` record: an object of 1..16 entries keyed by worker id, each exactly
+ * `{billing, asserted[, basis]}`. The first fault wins and invalidates the whole key; a reason
+ * names the entry (when its id is well formed) and the field, never the value.
+ */
+function validateWorkerBilling(value         )                    {
+  if (!isObject(value)) return { code: 'type', reason: 'must be an object keyed by worker id' };
+  const ids = Object.keys(value);
+  if (ids.length < 1 || ids.length > BILLING_MAX_ENTRIES) return { code: 'range', reason: `must hold 1 to ${BILLING_MAX_ENTRIES} worker entries` };
+  for (const id of ids) {
+    const fault = workerIdFault(id);
+    if (fault) return fault.code === 'reserved' ? fault : { code: 'type', reason: 'has an entry key that is not a worker id (lowercase built-in or qualified id)' };
+    const entry = value[id];
+    const at = `entry '${id}'`;
+    if (!isObject(entry)) return { code: 'type', reason: `${at} must be an object` };
+    if (Object.keys(entry).some((field) => !BILLING_ENTRY_FIELDS.includes(field))) return { code: 'type', reason: `${at} has a field other than billing, asserted and basis` };
+    if (typeof entry.billing !== 'string') return { code: 'type', reason: `${at} field 'billing' must be a string` };
+    if (!RECORDED_BILLING.includes(entry.billing)) return { code: 'enum', reason: `${at} field 'billing' must be one of: ${RECORDED_BILLING.join(', ')}` };
+    if (!isCalendarDate(entry.asserted)) return { code: 'range', reason: `${at} field 'asserted' must be a real YYYY-MM-DD date` };
+    if (Object.hasOwn(entry, 'basis')) {
+      const basis = entry.basis;
+      if (typeof basis !== 'string') return { code: 'type', reason: `${at} field 'basis' must be a string` };
+      if (/[\r\n\v\f\u0085\u2028\u2029]/.test(basis) || basis.length < 1 || basis.length > BILLING_BASIS_MAX) return { code: 'range', reason: `${at} field 'basis' must be one line of 1 to ${BILLING_BASIS_MAX} characters` };
+    }
+  }
+  return null;
+}
+
+/**
+ * Whether a JSON value is acceptable for a key (data-model §2 encodings). The reason never echoes the
+ * value. `enumValues` is the allowed list for an enum key, or for a string-list key with a `valuesRef`.
+ */
+function validateValue(spec     , value         , enumValues                           = null)                    {
+  switch (spec.type) {
+    case 'boolean':
+      return typeof value === 'boolean' ? null : { code: 'type', reason: 'must be true or false' };
+    case 'enum':
+      if (typeof value !== 'string') return { code: 'type', reason: 'must be a string' };
+      if (!enumValues) return { code: 'enum', reason: 'has no allowed values available' };
+      return enumValues.includes(value) ? null : { code: 'enum', reason: `must be one of: ${enumValues.join(', ')}` };
+    case 'integer':
+      if (typeof value !== 'number' || !Number.isSafeInteger(value)) return { code: 'type', reason: 'must be a whole number' };
+      if (value < (spec.min ?? Number.MIN_SAFE_INTEGER)) return { code: 'range', reason: `must be at least ${spec.min}` };
+      return value > (spec.max ?? Number.MAX_SAFE_INTEGER) ? { code: 'range', reason: `must be at most ${spec.max}` } : null;
+    case 'string-list': {
+      if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) return { code: 'type', reason: 'must be a list of non-empty strings' };
+      if (value.length > spec.maxItems) return { code: 'items', reason: `must hold at most ${spec.maxItems} items` };
+      if (new Set(value).size !== value.length) return { code: 'items', reason: 'must not repeat an item' };
+      if (value.some((item) => item.length > spec.maxLength)) return { code: 'length', reason: `each item must be at most ${spec.maxLength} characters` };
+      if (!spec.valuesRef || value.length === 0) return null;
+      if (!enumValues) return { code: 'enum', reason: 'has no allowed values available' };
+      return value.every((item) => enumValues.includes(item)) ? null : { code: 'enum', reason: `each item must be one of: ${enumValues.join(', ')}` };
+    }
+    case 'string':
+      return typeof value === 'string' && value.trim() ? null : { code: 'type', reason: 'must be a non-empty string' };
+    case 'model-id':
+      if (typeof value !== 'string' || value === '') return { code: 'type', reason: 'must be a model name string' };
+      if (value.length > MODEL_ID_MAX) return { code: 'length', reason: `must be at most ${MODEL_ID_MAX} characters` };
+      return MODEL_ID_RE.test(value) && !value.endsWith(' ') ? null : { code: 'type', reason: 'must start with a letter or digit, use only letters, digits, spaces and . _ : / @ ( ) [ ] # + -, and not end with a space' };
+    case 'model-list': {
+      if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        return { code: 'type', reason: 'must be a list of model name strings' };
+      }
+      if (value.length > 64) {
+        return { code: 'items', reason: 'must hold at most 64 items' };
+      }
+      if (new Set(value).size !== value.length) {
+        return { code: 'items', reason: 'must not repeat an item' };
+      }
+      for (const item of value) {
+        if (item === '' || item.length > MODEL_ID_MAX || !MODEL_ID_RE.test(item) || item.endsWith(' ')) {
+          return { code: 'type', reason: 'each item must start with a letter or digit, use only letters, digits, spaces and . _ : / @ ( ) [ ] # + -, and not end with a space' };
+        }
+      }
+      return null;
+    }
+    case 'url':
+      if (typeof value !== 'string' || !value.trim()) return { code: 'type', reason: 'must be a URL string' };
+      try { new URL(value); return null; } catch { return { code: 'url', reason: 'must be a URL string' }; }
+    // IC-002: membership is advisory; only shape, count and the final primary token constrain validity.
+    case 'worker-list': {
+      if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) return { code: 'type', reason: 'must be a list of strings' };
+      if (value.length < 1 || value.length > LADDER_MAX + 1 || value.filter((item) => item !== 'primary').length > LADDER_MAX) {
+        return { code: 'items', reason: `must hold 1 to ${LADDER_MAX} worker ids plus an optional final primary` };
+      }
+      if (new Set(value).size !== value.length) return { code: 'items', reason: 'must not repeat an item' };
+      if (value.includes('primary') && value.at(-1) !== 'primary') return { code: 'items', reason: 'primary must be the last item' };
+      for (const item of value) {
+        if (item === 'primary') continue;
+        const fault = workerIdFault(item);
+        if (fault) return fault;
+      }
+      return null;
+    }
+    // IC-002: the first shape fault invalidates the entire worker model map.
+    case 'worker-models': {
+      if (!isObject(value) || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        return { code: 'type', reason: 'must be an object keyed by worker id' };
+      }
+      const ids = Object.keys(value);
+      if (ids.length < 1 || ids.length > 16) return { code: 'items', reason: 'must hold 1 to 16 worker entries' };
+      for (const id of ids) {
+        const fault = workerIdFault(id);
+        if (fault) return fault.code === 'reserved' ? fault : { code: 'type', reason: 'has an entry key that is not a worker id (lowercase built-in or qualified id)' };
+        const entry = value[id];
+        if (!isObject(entry) || (Object.getPrototypeOf(entry) !== Object.prototype && Object.getPrototypeOf(entry) !== null)) {
+          return { code: 'type', reason: 'each worker entry must be an object keyed by tier' };
+        }
+        const tiers = Object.keys(entry);
+        if (tiers.length < 1 || tiers.length > 3) return { code: 'items', reason: 'each worker entry must hold 1 to 3 tiers' };
+        for (const tier of tiers) {
+          if (!Array.isArray(spec.tiers) || spec.tiers.length === 0) return { code: 'enum', reason: 'has no allowed tiers available' };
+          if (!spec.tiers.includes(tier)) return { code: 'enum', reason: `each tier must be one of: ${spec.tiers.join(', ')}` };
+          const modelFault = validateValue({ type: 'model-id' }, entry[tier]);
+          if (modelFault) return { code: modelFault.code, reason: `a tier's model ${modelFault.reason}` };
+        }
+      }
+      return null;
+    }
+    case 'worker-billing':
+      return validateWorkerBilling(value);
+    default:
+      return { code: 'type', reason: 'has an unknown type' };
+  }
+}
+
+function invalid(code           , reason        , offset                = null, notes         = [])            {
+  return { status: 'invalid', code, offset, reason, values: new Map(), notes };
+}
+
+/**
+ * Read one layer file. Never throws, never creates a file or folder, never blocks on a FIFO.
+ * A missing file (including a dangling link) is `absent`; anything else that cannot be used is an
+ * invalid layer with a code (data-model §2): not-file, unreadable, too-large, unparseable, schema.
+ * @param registry `{ keys: Map<string, KeySpec>, enumValues(key): string[] | null }`
+ */
+function readLayerFile(file        , { registry, fsImpl = nodeFs, includeDocument = false }                                                            )            {
+  let stat     ;
+  try { stat = fsImpl.statSync(file); }
+  catch (error     ) {
+    if (error?.code === 'ENOENT') return { status: 'absent', code: null, offset: null, reason: null, values: new Map(), notes: [] };
+    return invalid('unreadable', 'cannot be read');
+  }
+  if (!stat.isFile()) return invalid('not-file', 'is not a regular file');
+  if (stat.size > MAX_BYTES) return invalid('too-large', `is larger than ${MAX_BYTES} bytes`);
+
+  let buffer        ;
+  try { buffer = fsImpl.readFileSync(file); }
+  catch { return invalid('unreadable', 'cannot be read'); }
+  if (buffer.length > MAX_BYTES) return invalid('too-large', `is larger than ${MAX_BYTES} bytes`);
+
+  let text = buffer.toString('utf8');
+  let bomBytes = 0;
+  if (text.startsWith(BOM)) { text = text.slice(1); bomBytes = 3; }
+
+  let parsed         ;
+  try { parsed = JSON.parse(text); }
+  catch (error     ) {
+    const failure = jsonFailure(error, text, bomBytes);
+    return invalid('unparseable', failure.reason, failure.offset);
+  }
+  if (!isObject(parsed)) return invalid('unparseable', 'must be a JSON object');
+
+  const notes         = [];
+  if (!Object.hasOwn(parsed, 'schema')) {
+    notes.push({ code: 'schema-missing', key: null, source: file, text: 'has no "schema"; read as schema 1' });
+  } else if (parsed.schema !== 1) {
+    return invalid('schema', 'schema must be 1');
+  }
+
+  const values = new Map               ();
+  for (const [key, raw] of Object.entries(parsed)) {
+    if (key === 'schema') continue;
+    const spec = registry.keys.get(key);
+    if (!spec) {
+      const shown = JSON.stringify(key.length > 80 ? `${key.slice(0, 80)}...` : key);
+      if (isObject(raw) || Array.isArray(raw)) {
+        notes.push({ code: 'nested', key, source: file, text: `${shown} is a nested object; use dotted keys (not applied)` });
+      } else {
+        notes.push({ code: 'unknown-key', key, source: file, text: `${shown} is not a DoFlow setting (ignored)` });
+      }
+      continue;
+    }
+    const error = validateValue(spec, raw, registry.enumValues(key));
+    values.set(key, { raw, value: error ? null : raw, error });
+  }
+  return { status: 'ok', code: null, offset: null, reason: null, values, notes,
+    ...(includeDocument ? { document: parsed                            } : {}) };
+}
+
+module.exports = { MAX_BYTES, jsonFailure, validateValue, readLayerFile };