octwin-cli 0.3.0 → 0.6.0

package/dist/lib/args-check.js

@@ -29,7 +29,7 @@
  */
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { lookupKbSubdir } from './kb-path.js';
+import { lookupKbSubdir, isEntryFile } from './kb-path.js';
 /**
  * Load `primitive -> ArgSpec` from the pulled KB.
  *
@@ -37,14 +37,14 @@ import { lookupKbSubdir } from './kb-path.js';
  * distinguish "checked and clean" from "could not check". See `kb-path.ts`.
  */
 export function loadPrimitiveArgSpecs(packDir) {
-    const lookup = lookupKbSubdir(packDir, 'primitives', dir => readdirSync(dir).some(f => f.endsWith('.json')));
+    const lookup = lookupKbSubdir(packDir, 'primitives', dir => readdirSync(dir).some(isEntryFile));
     if (lookup.state !== 'ok')
         return { lookup, specs: null };
     const dir = lookup.dir;
     const out = new Map();
     try {
         for (const file of readdirSync(dir)) {
-            if (!file.endsWith('.json'))
+            if (!isEntryFile(file))
                 continue;
             const entry = JSON.parse(readFileSync(join(dir, file), 'utf8'));
             const schema = entry.inputSchema;
@@ -77,9 +77,9 @@ export function loadPrimitiveArgSpecs(packDir) {
  */
 export function findArgViolations(doc, file, specs) {
     const findings = [];
-    const walk = (node) => {
+    const walk = (node, path) => {
         if (Array.isArray(node)) {
-            node.forEach(walk);
+            node.forEach((v, i) => walk(v, [...path, i]));
             return;
         }
         if (!node || typeof node !== 'object')
@@ -97,14 +97,14 @@ export function findArgViolations(doc, file, specs) {
                 const missing = spec.required.filter(k => !(k in args));
                 const unscoped = spec.requiresOneOf.filter(g => !g.some(k => k in args));
                 if (unknown.length || missing.length || unscoped.length) {
-                    findings.push({ file, primitive: obj.do, unknown, missing, unscoped, declared: [...spec.keys].sort() });
+                    findings.push({ file, primitive: obj.do, path: [...path], unknown, missing, unscoped, declared: [...spec.keys].sort() });
                 }
             }
         }
-        for (const v of Object.values(obj))
-            walk(v);
+        for (const [k, v] of Object.entries(obj))
+            walk(v, [...path, k]);
     };
-    walk(doc);
+    walk(doc, []);
     return findings;
 }
 /** One-line human message per finding. */
@@ -123,5 +123,6 @@ export function describeArgFinding(f) {
         // "so what?", and for the scope groups the answer is a data leak.
         parts.push(`no ${g.map(k => `'${k}'`).join(' or ')} — the read is project-wide and returns other contacts' records`);
     }
-    return `${f.file}: \`${f.primitive}\` has ${parts.join('; ')}. It takes: ${f.declared.join(', ') || 'no arguments'}`;
+    const at = f.line != null ? `:${f.line}` : (f.path.length ? ` (${f.path.join('.')})` : '');
+    return `${f.file}${at}: \`${f.primitive}\` has ${parts.join('; ')}. It takes: ${f.declared.join(', ') || 'no arguments'}`;
 }

package/dist/lib/builtin-check.js

@@ -0,0 +1,130 @@
+/**
+ * Offline expression-builtin check, driven by the pulled platform KB.
+ *
+ * WHY it matters: the expression language has a CLOSED function set, generated
+ * from the runtime into `builtins/*.json`. A call to something outside it —
+ * `$sum_by(…)`, `$format_date(…)`, `$first(…)` — is not a syntax error and not a
+ * missing import; it is a name the evaluator cannot resolve, and the failure
+ * surfaces mid-conversation to a customer rather than at authoring time. An
+ * invented builtin also reads EXACTLY like a real one, which is why it survives
+ * review: the repo's own KB gate exists for the same reason on the docs side
+ * (`scripts/check-kb-examples.mjs`), and it found eight fictional functions in
+ * prose that every other gate was blind to.
+ *
+ * WHAT IT CHECKS: every `$name(` occurrence in every string in the pack's YAML.
+ * Not just `assign:` — expressions appear in `args:`, in render fields, inside
+ * `{$…}` interpolation, in `when:`, in `item_template`, and in locale values.
+ *
+ * WHAT IT DOES NOT CHECK — stated because a check that hides its edges gets
+ * trusted past them:
+ *   • ARITY. The catalog publishes a TypeScript signature string, not a machine
+ *     schema; parsing "(arr: unknown, mapping: unknown): unknown[]" into an
+ *     arity is guesswork the moment a signature carries a default or a rest
+ *     parameter, and a wrong arity error is worse than no arity error.
+ *   • Whether the argument VALUES make sense — that is the platform's job.
+ *   • Anything inside a `use:` template body (the platform expands those).
+ *
+ * NO WHITESPACE before the paren, deliberately: `$name(` is how the grammar is
+ * written, and allowing `$name (` starts matching customer-facing copy.
+ *
+ * Degrades to a no-op when the KB has not been pulled — see `kb-path.ts` and the
+ * sibling checks; a skip is reported, never silently passed.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { lookupKbSubdir, isEntryFile } from './kb-path.js';
+/**
+ * Names that look like builtins and are not — they belong to a DIFFERENT engine.
+ *
+ * `$opt(` is the `taps.yaml` agent-token vocabulary, substituted at tap-match
+ * time, never evaluated by the expression runtime. The repo's KB gate carries
+ * the same exclusion for the same reason.
+ */
+const OTHER_ENGINE_VOCAB = new Set(['opt']);
+/** `$name(` — the only shape the expression grammar accepts for a call. */
+const CALL = /\$([a-z_][a-z0-9_]*)\(/g;
+/** Load the closed builtin set from the pulled KB. */
+export function loadBuiltinNames(packDir) {
+    const lookup = lookupKbSubdir(packDir, 'builtins', dir => readdirSync(dir).some(isEntryFile));
+    if (lookup.state !== 'ok')
+        return { lookup, names: null };
+    const dir = lookup.dir;
+    const names = new Set();
+    try {
+        for (const file of readdirSync(dir)) {
+            if (!isEntryFile(file))
+                continue;
+            const entry = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+            if (entry.name)
+                names.add(entry.name);
+        }
+    }
+    catch (err) {
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, names: null };
+    }
+    if (!names.size)
+        return { lookup: { state: 'malformed', dir, reason: 'no builtin entries parsed' }, names: null };
+    return { lookup, names };
+}
+/**
+ * Builtins whose name is close to the one written — edit distance is overkill
+ * here; a shared 4-character prefix or a containment catches the real typos.
+ *
+ * The 4-character floor on containment is load-bearing, not tidiness. Without
+ * it, the short names in the set (`t`, `in`, `get`, `min`, `sum`, `map`) are a
+ * substring of almost anything: `$first_of()` suggested `$t()`, because
+ * `'first_of'.includes('t')`. A suggestion list with an absurd entry in it is
+ * read as noise, and then the good entry beside it is ignored too.
+ */
+function suggest(name, names) {
+    const near = (a, b) => a.length >= 4 && b.includes(a);
+    const hits = [];
+    for (const n of names) {
+        if (n === name)
+            continue;
+        if (n.slice(0, 4) === name.slice(0, 4) || near(n, name) || near(name, n))
+            hits.push(n);
+    }
+    return hits.sort().slice(0, 4);
+}
+/** Walk parsed YAML and report every `$name(` naming a function that does not exist. */
+export function findBuiltinViolations(doc, file, names) {
+    const findings = [];
+    const seen = new Set(); // one finding per name per file — a helper used ten times is one mistake
+    const scan = (text, path) => {
+        for (const m of text.matchAll(CALL)) {
+            const name = m[1];
+            if (names.has(name) || OTHER_ENGINE_VOCAB.has(name) || seen.has(name))
+                continue;
+            seen.add(name);
+            findings.push({ file, path: [...path], name, didYouMean: suggest(name, names) });
+        }
+    };
+    const walk = (node, path) => {
+        if (typeof node === 'string') {
+            scan(node, path);
+            return;
+        }
+        if (Array.isArray(node)) {
+            node.forEach((v, i) => walk(v, [...path, i]));
+            return;
+        }
+        if (!node || typeof node !== 'object')
+            return;
+        // KEYS can carry expressions too — `outputs:` port names cannot, but a
+        // `{$…}`-interpolated map key can, and walking values only would miss it.
+        for (const [k, v] of Object.entries(node)) {
+            scan(k, [...path, k]);
+            walk(v, [...path, k]);
+        }
+    };
+    walk(doc, []);
+    return findings;
+}
+/** One-line human message per finding. */
+export function describeBuiltinFinding(f) {
+    const at = f.line != null ? `:${f.line}` : (f.path.length ? ` (${f.path.join('.')})` : '');
+    return `${f.file}${at}: \`$${f.name}()\` is not an expression builtin`
+        + (f.didYouMean.length ? ` — did you mean ${f.didYouMean.map(n => `$${n}()`).join(', ')}?` : '')
+        + ' The set is closed and generated from the runtime; grep SYMBOLS.md for the name you want.';
+}

package/dist/lib/declaration-check.js

@@ -0,0 +1,192 @@
+/**
+ * Offline declaration-file check — validates `manifest.yaml`, `xrm.yaml`,
+ * `scheduling.yaml` and their siblings against the JSON Schemas the platform
+ * publishes in `declarations/*.json`.
+ *
+ * WHY it matters: the manifest is `.strict()`, so an unknown key is a DEPLOY
+ * rejection, and every sibling declaration is parsed the same way at load. Today
+ * an author learns about a misspelt key from a round-trip (`validate --remote`),
+ * or from a boot failure. The schema that decides it is already on disk after a
+ * pull; there is no reason to ask the platform.
+ *
+ * ## A DELIBERATELY NARROW subset of JSON Schema
+ *
+ * This is the check where a false positive costs the most: it fires on the
+ * author's own declaration files, and an author who is told a valid `xrm.yaml`
+ * is wrong will stop trusting `validate` entirely — which also silences the two
+ * checks that were catching real bugs. So the rule is: **report only what is
+ * unambiguous, and walk away from anything else.**
+ *
+ * It reports exactly four things:
+ *   1. a key not in `properties` where `additionalProperties: false`
+ *   2. a missing `required` key
+ *   3. a scalar whose `type` is plainly wrong
+ *   4. a value outside a closed `enum`
+ *
+ * It STOPS DESCENDING (reports nothing at all for that subtree) at any node
+ * carrying `anyOf` / `oneOf` / `allOf` / `not`, at an unresolvable `$ref`, and at
+ * an empty schema `{}` — which is what `z.toJSONSchema(…, { unrepresentable:
+ * 'any' })` emits for everything Zod cannot express, including every custom
+ * refinement and transform in these schemas. A union is not "invalid", it is
+ * "more than this validator can read", and those two must never be confused.
+ *
+ * No dependency: adding `ajv` to ship four rules would put a full JSON Schema
+ * engine (and its own draft quirks) into a CLI that authors install globally.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { lookupKbSubdir, isEntryFile } from './kb-path.js';
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Load `declarations/*.json` from the pulled KB, keyed by the FILE an author writes. */
+export function loadDeclarationSpecs(packDir) {
+    const lookup = lookupKbSubdir(packDir, 'declarations', dir => readdirSync(dir).some(isEntryFile));
+    if (lookup.state !== 'ok')
+        return { lookup, specs: null };
+    const dir = lookup.dir;
+    const out = new Map();
+    try {
+        for (const f of readdirSync(dir)) {
+            if (!isEntryFile(f))
+                continue;
+            const entry = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+            if (entry.file && isObj(entry.schema))
+                out.set(entry.file, { file: entry.file, schema: entry.schema });
+        }
+    }
+    catch (err) {
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, specs: null };
+    }
+    if (!out.size)
+        return { lookup: { state: 'malformed', dir, reason: 'no declaration entries parsed' }, specs: null };
+    return { lookup, specs: out };
+}
+/** The JSON-Schema type name for a YAML-parsed value, or null for null/undefined. */
+function jsonTypeOf(v) {
+    if (v === null || v === undefined)
+        return null;
+    if (Array.isArray(v))
+        return 'array';
+    if (typeof v === 'number')
+        return Number.isInteger(v) ? 'integer' : 'number';
+    if (typeof v === 'boolean')
+        return 'boolean';
+    if (typeof v === 'string')
+        return 'string';
+    if (v instanceof Date)
+        return 'string'; // YAML parses bare dates; the schema calls them strings
+    if (typeof v === 'object')
+        return 'object';
+    return null;
+}
+/** True when the declared type accepts the observed one. */
+function typeAccepts(declared, actual) {
+    if (declared === actual)
+        return true;
+    if (declared === 'number' && actual === 'integer')
+        return true; // every integer is a number
+    return false;
+}
+/**
+ * Validate `value` against `schema`, appending findings.
+ *
+ * Returns silently the moment the schema uses anything outside the subset — see
+ * the header. `depth` is a hard stop against a `$ref` cycle the deref cannot see.
+ */
+function walk(value, schema, path, defs, out, file, depth) {
+    if (depth > 24)
+        return;
+    // `$ref` — follow one hop into `$defs`; anything else is out of subset.
+    const ref = schema.$ref;
+    if (typeof ref === 'string') {
+        const name = ref.startsWith('#/$defs/') ? ref.slice('#/$defs/'.length) : null;
+        const target = name ? defs[name] : undefined;
+        if (!isObj(target))
+            return;
+        return walk(value, target, path, defs, out, file, depth + 1);
+    }
+    // Combinators and the empty schema: more than this validator can read.
+    if (schema.anyOf || schema.oneOf || schema.allOf || schema.not)
+        return;
+    if (Object.keys(schema).length === 0)
+        return;
+    if (value === null || value === undefined)
+        return; // an explicit null is the platform's to judge
+    const actual = jsonTypeOf(value);
+    if (!actual)
+        return;
+    // 4. Closed enum.
+    if (Array.isArray(schema.enum)) {
+        if (!schema.enum.includes(value)) {
+            out.push({
+                file, path,
+                message: `${JSON.stringify(value)} is not one of ${schema.enum.map(e => JSON.stringify(e)).join(', ')}`,
+            });
+        }
+        return;
+    }
+    // 3. Scalar type.
+    const declared = schema.type;
+    if (typeof declared === 'string' && !typeAccepts(declared, actual)) {
+        out.push({ file, path, message: `expected ${declared}, got ${actual}` });
+        return; // shape is wrong; descending would cascade noise
+    }
+    if (actual === 'array') {
+        const items = schema.items;
+        if (isObj(items)) {
+            value.forEach((v, i) => walk(v, items, `${path}[${i}]`, defs, out, file, depth + 1));
+        }
+        return;
+    }
+    if (actual !== 'object')
+        return;
+    const obj = value;
+    const props = isObj(schema.properties) ? schema.properties : undefined;
+    const addl = schema.additionalProperties;
+    // A map schema (`additionalProperties: <schema>`, no `properties`) — every
+    // value shares one shape. This is how `entities:` and `agents:` are declared.
+    if (!props && isObj(addl)) {
+        for (const [k, v] of Object.entries(obj))
+            walk(v, addl, path ? `${path}.${k}` : k, defs, out, file, depth + 1);
+        return;
+    }
+    if (!props)
+        return;
+    // 2. Required.
+    if (Array.isArray(schema.required)) {
+        for (const key of schema.required) {
+            if (typeof key === 'string' && !(key in obj)) {
+                out.push({ file, path: path ? `${path}.${key}` : key, message: 'required key is missing' });
+            }
+        }
+    }
+    // 1. Unknown keys — ONLY when the schema closes itself.
+    if (addl === false) {
+        const known = Object.keys(props);
+        for (const k of Object.keys(obj)) {
+            if (!known.includes(k)) {
+                out.push({
+                    file, path: path ? `${path}.${k}` : k,
+                    message: `unknown key — this file is strict, so it is rejected on deploy. Declared keys here: ${known.join(', ')}`,
+                });
+            }
+        }
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        const sub = props[k];
+        if (isObj(sub))
+            walk(v, sub, path ? `${path}.${k}` : k, defs, out, file, depth + 1);
+        else if (isObj(addl))
+            walk(v, addl, path ? `${path}.${k}` : k, defs, out, file, depth + 1);
+    }
+}
+/** Validate one parsed declaration document against its published schema. */
+export function findDeclarationViolations(doc, spec) {
+    const out = [];
+    const defs = isObj(spec.schema.$defs) ? spec.schema.$defs : {};
+    walk(doc, spec.schema, '', defs, out, spec.file, 0);
+    return out;
+}
+/** One-line human message per finding. */
+export function describeDeclarationFinding(f) {
+    return `${f.file}${f.path ? ` → ${f.path}` : ''}: ${f.message}`;
+}

package/dist/lib/entity-check.js

@@ -0,0 +1,150 @@
+/**
+ * Offline reserved-entity check for `xrm.yaml`, driven by the pulled platform KB.
+ *
+ * WHY it matters: the seven system entities (`order`, `cart`, `product`, `case`,
+ * `booking`, `survey_response`, `campaign`) are RESERVED keys. Declaring one as
+ * your own entity is a BOOT error — not a validate error and not a deploy error,
+ * a boot error — so the pack deploys clean and then fails to load on the first
+ * inbound message, which reads to an author as "the platform is broken". The
+ * same is true of the `journey_` prefix and of `extends: system` on a key that
+ * is not a system entity.
+ *
+ * Every rule here is replayed from `system-entities/`, which publishes each
+ * template's shipped field set per entry AND the catalog-level rules in
+ * `_catalog.json`. Nothing is hand-listed.
+ *
+ * The two rules this file used to name as gaps — `contact` as a reserved key, and
+ * the `EXTENSION_FORBIDDEN` set — are covered as of 2026-08-09: the platform now
+ * exports those constants and the catalog publishes them, so the check reads the
+ * same values the boot-time validator does instead of guessing at them.
+ *
+ * WHAT IT STILL DOES NOT CHECK: anything requiring the merged entity shape (an
+ * extension's interaction with a pipeline it inherits, say). `--remote` owns that.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { lookupKbSubdir, isEntryFile } from './kb-path.js';
+/**
+ * Fallback for the journey prefix when the pulled KB predates `_catalog.json`.
+ *
+ * Unlike the other two rules, this one keeps a hardcoded default: it was already
+ * enforced here before the catalog published anything, so dropping it for an old
+ * KB would REMOVE a working check. The catalog's value wins whenever it is there.
+ */
+const JOURNEY_PREFIX = 'journey_';
+/** Load the system-entity templates + the catalog-level rules from the pulled KB. */
+export function loadSystemEntities(packDir) {
+    const lookup = lookupKbSubdir(packDir, 'system-entities', dir => readdirSync(dir).some(isEntryFile));
+    if (lookup.state !== 'ok')
+        return { lookup, entities: null, rules: null };
+    const dir = lookup.dir;
+    const out = new Map();
+    let rules = null;
+    try {
+        for (const file of readdirSync(dir)) {
+            if (!isEntryFile(file))
+                continue;
+            const key = file.slice(0, -'.json'.length);
+            const entry = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+            out.set(key, { key, fields: Object.keys(entry.fields ?? {}) });
+        }
+        // The catalog-level block, when the platform published one. Absent on a KB
+        // pulled before 2026-08-09 — the two rules it feeds then simply do not run.
+        const catalogFile = join(dir, '_catalog.json');
+        if (existsSync(catalogFile)) {
+            const raw = JSON.parse(readFileSync(catalogFile, 'utf8'));
+            const r = raw.rules;
+            if (r) {
+                rules = {
+                    reservedKeys: Array.isArray(r.reserved_keys) ? r.reserved_keys.filter((x) => typeof x === 'string') : [],
+                    reservedPrefix: typeof r.reserved_prefix === 'string' ? r.reserved_prefix : null,
+                    extensionForbidden: Array.isArray(r.extension_forbidden) ? r.extension_forbidden.filter((x) => typeof x === 'string') : [],
+                };
+            }
+        }
+    }
+    catch (err) {
+        return { lookup: { state: 'malformed', dir, reason: String(err?.message ?? err) }, entities: null, rules: null };
+    }
+    if (!out.size)
+        return { lookup: { state: 'malformed', dir, reason: 'no system-entity entries parsed' }, entities: null, rules: null };
+    return { lookup, entities: out, rules };
+}
+/**
+ * Check one parsed `xrm.yaml`. Takes the whole document and reads `entities:` —
+ * anything else in the file is another check's business.
+ */
+export function findEntityViolations(doc, file, system, rules) {
+    const entities = doc?.entities;
+    if (!entities || typeof entities !== 'object' || Array.isArray(entities))
+        return [];
+    // Only from the catalog. A KB pulled before these were published leaves them
+    // empty, and the rules that read them do not fire — deliberately, rather than
+    // falling back to a hardcoded copy that could drift from the platform.
+    const reservedKeys = new Set(rules?.reservedKeys ?? []);
+    const forbidden = rules?.extensionForbidden ?? [];
+    const journeyPrefix = rules?.reservedPrefix ?? JOURNEY_PREFIX;
+    const findings = [];
+    for (const [key, raw] of Object.entries(entities)) {
+        const spec = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+        const extendsSystem = spec.extends === 'system';
+        const sys = system.get(key);
+        // Not declarable under any form — it names the platform contacts table in
+        // `relations.to`, so an entity of this name makes every relation ambiguous.
+        if (reservedKeys.has(key)) {
+            findings.push({ kind: 'reserved-key', file, entity: key });
+            continue;
+        }
+        if (key.startsWith(journeyPrefix)) {
+            findings.push({ kind: 'journey-prefix', file, entity: key });
+            continue;
+        }
+        if (extendsSystem && sys) {
+            const overridden = forbidden.filter(k => spec[k] != null);
+            if (overridden.length)
+                findings.push({ kind: 'extension-override', file, entity: key, keys: overridden });
+        }
+        if (extendsSystem && !sys) {
+            findings.push({ kind: 'not-system', file, entity: key, known: [...system.keys()].sort() });
+            continue;
+        }
+        if (!extendsSystem && sys) {
+            findings.push({ kind: 'reserved', file, entity: key });
+            continue;
+        }
+        if (extendsSystem && sys) {
+            const fields = spec.fields;
+            const declared = fields && typeof fields === 'object' && !Array.isArray(fields)
+                ? Object.keys(fields)
+                : [];
+            const clash = declared.filter(f => sys.fields.includes(f));
+            if (clash.length)
+                findings.push({ kind: 'field-clash', file, entity: key, fields: clash });
+        }
+    }
+    return findings;
+}
+/** One-line human message per finding. */
+export function describeEntityFinding(f) {
+    switch (f.kind) {
+        case 'reserved':
+            return `${f.file}: entity '${f.entity}' is a platform system entity — add 'extends: system' to extend it (add-only), or pick another key. `
+                + 'Left as is, the pack DEPLOYS and then fails to load on the first inbound message.';
+        case 'not-system':
+            return `${f.file}: entity '${f.entity}' declares 'extends: system', but the platform ships no such entity. `
+                + `System entities: ${f.known.join(', ')}`;
+        case 'field-clash':
+            return `${f.file}: entity '${f.entity}' redeclares field${f.fields.length === 1 ? '' : 's'} ${f.fields.map(x => `'${x}'`).join(', ')} `
+                + 'that the system template already ships — an extension may only ADD fields';
+        case 'journey-prefix':
+            return `${f.file}: entity '${f.entity}' uses the reserved '${JOURNEY_PREFIX}' prefix (entities synthesized from journeys live there) `
+                + `— rename it, or declare it as journeys/${f.entity.slice(JOURNEY_PREFIX.length)}.journey.yaml`;
+        case 'reserved-key':
+            return `${f.file}: '${f.entity}' is a reserved entity key — it names the platform contacts table in \`relations.to\`, `
+                + 'so an entity of that name makes every relation ambiguous. Pick another key; there is no `extends:` form for this one.';
+        case 'extension-override':
+            return `${f.file}: entity '${f.entity}' is an 'extends: system' extension and may not override `
+                + `${f.keys.map(k => `'${k}'`).join(', ')} — the template's shape is platform-owned. `
+                + 'Declare your own entity if you need a different shape.';
+    }
+}