@telorun/analyzer 0.56.1 → 0.58.0

package/dist/migrations/match.d.ts

@@ -0,0 +1,162 @@
+/** The selector half of a migration: what a rule MATCHES, as data.
+ *
+ *  A patch addresses a known location; a migration has to find *every*
+ *  occurrence of a legacy spelling, so selection is the half a plain patch
+ *  format has none of. It is declarative for the same reason the operations
+ *  are: an entry travels to a Rust and a Go kernel, and a predicate expressed
+ *  in one language would mean one artifact is read two ways — invisibly, since
+ *  a migration that succeeds is silent.
+ *
+ *  **Containment is POSITIVE and required.** A rule states which document kinds
+ *  it may touch (`inKind`) and which region of those documents it may reach
+ *  into (`under`); nothing outside is reachable. The alternative — walk
+ *  everything and subtract — cannot be made sound, because the set to subtract
+ *  is unbounded: a `Run.Value` value, an `Assert.Equals` expected, any kind
+ *  whose config carries a user JSON blob can hold something shaped like the
+ *  node a rule looks for, and forgetting one corrupts a manifest with no
+ *  diagnostic. A denylist also cannot express the guarantee the module surface
+ *  is promised to carry — *a dependency can rename its own field and provably
+ *  nothing else* — which is a statement about what a rule may reach, so it has
+ *  to be said positively. `notUnder` remains for subtracting inside a region a
+ *  rule legitimately reaches, which is a narrowing, not the containment itself.
+ *
+ *  **`under` is ANCHORED at the document root**, not a set of key names to look
+ *  for anywhere on the path. Anchoring is what makes the containment claim
+ *  true: a `Telo.Definition`'s `resources:` template body carries other kinds'
+ *  configuration, and any of it may hold a key spelled `schema` over data that
+ *  merely looks like a schema — so "some segment of the path is `schema`" would
+ *  reach the very user JSON blob the positive form exists to keep out, and
+ *  would delete from it silently. Anchored, `under` names top-level document
+ *  keys and a region is a genuine subtree.
+ *
+ *  **`inSchema` is the one region a kind list cannot name.** An annotation
+ *  keyword occurs in author-written JSON Schema, and schema fragments are not
+ *  confined to kind documents: an inline `inputType:` / `outputType:` on ANY kind
+ *  that declares one, an API route's `request.schema.body`, a `Telo.JsonSchema`'s
+ *  `schema`. That set of kinds is open — any kind may declare a schema-valued
+ *  field — and enumerating the standard library's would put resource-kind
+ *  knowledge into the analyzer, against the topology-driven constraint. So a rule
+ *  may instead state that it reaches only inside a SCHEMA REGION, named by the
+ *  KERNEL's own schema-valued keys, which no kind owns.
+ *
+ *  With `inSchema`, and only with it, `inKind` / `under` may be `["*"]` — and
+ *  only for a rule keyed on a reserved `x-telo-*` annotation. That pairing IS the
+ *  containment: the region gate bounds where the walk may go, and the reserved-key
+ *  rule bounds what it may touch, since an `x-telo-*` key is Telo vocabulary
+ *  wherever it appears and cannot mean something else in someone's config. Both
+ *  halves are refused at entry-read time, so a module-shipped entry can no more
+ *  spell `"*"` than it can name another module's kind.
+ *
+ *  The residue is stated rather than claimed away: a manifest that asserts ABOUT
+ *  a schema — a schema literal under a key spelled `schema` inside an assertion's
+ *  expected value — is reachable, and would be rewritten into its own synonym.
+ *  That cannot be closed in a data-only matcher without naming kinds. It is
+ *  accepted because the sites the wildcards reach are exactly the ones no
+ *  enumeration covers, and the alternative leaves an author reading a deprecation
+ *  `telo migrate` refuses to act on.
+ *
+ *  The vocabulary is closed, which is what makes it a trust boundary once
+ *  module-shipped entries are aggregated beside core ones. An unrecognized key
+ *  is refused rather than ignored — a selector that silently matches wider than
+ *  it reads is the one failure this cannot tolerate. */
+import type { MigrationPath } from "./types.js";
+/** The wildcard `inKind` / `under` value. Legal only alongside `inSchema`, and
+ *  only for a rule keyed on an `x-telo-*` annotation. */
+export declare const MATCH_ANY = "*";
+export interface MigrationMatch {
+    /** The mapping key this rule rewrites. */
+    readonly key: string;
+    /** Document `kind:` values this rule may match in. Required and non-empty:
+     *  a rule that does not say which documents it touches cannot be reasoned
+     *  about, and is exactly the rule that reaches into a resource's config. */
+    readonly inKind: readonly string[];
+    /** The region of the document this rule may reach, named by TOP-LEVEL
+     *  document keys: the matched node must be AT or BELOW one of them. Required
+     *  and non-empty, for the same reason as `inKind`.
+     *
+     *  Anchored at the root rather than matched anywhere on the path — see the
+     *  file header; an unanchored `under` reaches into a nested resource's own
+     *  configuration and is not containment at all.
+     *
+     *  At-or-below rather than strictly-below so the vocabulary is complete — a
+     *  rule that rewrites a top-level key names that key, instead of the region
+     *  being unreachable and the grammar needing a second spelling for the
+     *  document root. */
+    readonly under: readonly string[];
+    /** The value must deep-equal this. Mutually exclusive with `valueOneOf`. */
+    readonly value?: unknown;
+    /** The value must be one of these. Matching against the KNOWN legacy values
+     *  rather than any value is what leaves an unrecognized one alone for the
+     *  ordinary validator to report, instead of silently rewriting it. */
+    readonly valueOneOf?: readonly unknown[];
+    /** A key that must be present in the same mapping. The matched key is often
+     *  stale only *because* of what sits beside it. */
+    readonly withSibling?: string;
+    /** Ancestor keys that disqualify a match inside the region `under` allows.
+     *  The data-bearing JSON Schema keywords (`const`, `default`, `enum`,
+     *  `examples`) hold values that may look like schemas. */
+    readonly notUnder?: readonly string[];
+    /** Narrow to a JSON Schema region: the match must be at or below a node
+     *  reached through one of {@link SCHEMA_REGION_KEYS}.
+     *
+     *  A second bound, never a replacement for `inKind` / `under` — it is what
+     *  makes their wildcard forms safe, and it narrows an enumerated region just as
+     *  usefully. See the file header for why an annotation rename needs it. */
+    readonly inSchema?: boolean;
+}
+export declare const MATCH_KEYS: readonly ["key", "inKind", "under", "value", "valueOneOf", "withSibling", "notUnder", "inSchema"];
+/** Structural equality over JSON values — what `value` / `valueOneOf` compare
+ *  with, so a match on `true` never also matches `"true"`.
+ *
+ *  Exported because the PATCHER asks the same question in the other direction:
+ *  "is the value already what this would write". Both answers have to come from
+ *  one rule, or a rule could match a spelling the patch then declares current. */
+export declare function deepEquals(a: unknown, b: unknown): boolean;
+/** Read a rule's `match` block, refusing anything the vocabulary does not
+ *  define. `describe` names the entry and rule so a failure says which. */
+export declare function readMigrationMatch(describe: string, raw: unknown): MigrationMatch;
+/** One candidate site: a mapping entry whose key some rule is interested in. */
+interface MatchSite {
+    readonly path: MigrationPath;
+    readonly value: unknown;
+    readonly parent: Record<string, unknown>;
+}
+/** Every candidate site in one document, keyed by mapping key.
+ *
+ *  Built ONCE per document and shared by every rule that can apply to it,
+ *  because the walk is the expensive part and it does not depend on the rule —
+ *  this is on the kernel's boot path for every file in the graph, so a walk per
+ *  rule would scale the cost of loading any manifest with the size of the
+ *  migration set.
+ *
+ *  The walk is bounded by the same containment the rules declare: `roots` is
+ *  the union of the applicable rules' `under`, so a region no rule can reach is
+ *  never descended into and a document no rule can match is never walked at
+ *  all. Only keys some rule asked for allocate a path array. */
+export type MatchIndex = ReadonlyMap<string, readonly MatchSite[]>;
+/**
+ * Index `document`'s candidate sites for `keys`, descending only into the
+ * top-level regions named by `roots`.
+ *
+ * The caller has already gated on `inKind` — see `selectMatches`, which repeats
+ * the check because it holds the individual rule.
+ */
+export declare function buildMatchIndex(document: unknown, keys: ReadonlySet<string>, roots: ReadonlySet<string>): MatchIndex;
+/** The rules in `entries` that may match a document of `kind`, with the key and
+ *  root sets their shared index needs. Empty rules mean the document is not
+ *  walked at all. */
+export declare function applicableRules<T extends {
+    readonly match: MigrationMatch;
+}>(rules: Iterable<T>, kind: unknown): {
+    rules: T[];
+    keys: Set<string>;
+    roots: Set<string>;
+};
+/** The sites in `index` this match selects, in document order. */
+export declare function selectMatches(index: MatchIndex, document: unknown, match: MigrationMatch): MigrationPath[];
+/** Convenience for a single match against a document — builds a one-rule index.
+ *  The driver uses `applicableRules` + `buildMatchIndex` + `selectMatches` so
+ *  one walk serves every rule that can reach the document. */
+export declare function findMatches(document: unknown, match: MigrationMatch): MigrationPath[];
+export {};
+//# sourceMappingURL=match.d.ts.map

package/dist/migrations/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/migrations/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wDA4DwD;AAGxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;yDACyD;AACzD,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;gFAE4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;;;;;;yBAWqB;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;0EAEsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACzC;uDACmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;8DAE0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;+EAK2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,eAAO,MAAM,UAAU,mGASb,CAAC;AAMX;;;;;kFAKkF;AAClF,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAY1D;AAUD;2EAC2E;AAC3E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,cAAc,CA6EjF;AAED,gFAAgF;AAChF,UAAU,SAAS;IACjB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;gEAWgE;AAChE,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC,CAAC;AAEnE;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EACjB,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EACzB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,UAAU,CA6CZ;AAED;;qBAEqB;AACrB,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,EAC1E,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAClB,IAAI,EAAE,OAAO,GACZ;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CAYvD;AAQD,kEAAkE;AAClE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,cAAc,GACpB,aAAa,EAAE,CA4BjB;AAED;;8DAE8D;AAC9D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,aAAa,EAAE,CAGrF"}

package/dist/migrations/match.js

@@ -0,0 +1,295 @@
+/** The selector half of a migration: what a rule MATCHES, as data.
+ *
+ *  A patch addresses a known location; a migration has to find *every*
+ *  occurrence of a legacy spelling, so selection is the half a plain patch
+ *  format has none of. It is declarative for the same reason the operations
+ *  are: an entry travels to a Rust and a Go kernel, and a predicate expressed
+ *  in one language would mean one artifact is read two ways — invisibly, since
+ *  a migration that succeeds is silent.
+ *
+ *  **Containment is POSITIVE and required.** A rule states which document kinds
+ *  it may touch (`inKind`) and which region of those documents it may reach
+ *  into (`under`); nothing outside is reachable. The alternative — walk
+ *  everything and subtract — cannot be made sound, because the set to subtract
+ *  is unbounded: a `Run.Value` value, an `Assert.Equals` expected, any kind
+ *  whose config carries a user JSON blob can hold something shaped like the
+ *  node a rule looks for, and forgetting one corrupts a manifest with no
+ *  diagnostic. A denylist also cannot express the guarantee the module surface
+ *  is promised to carry — *a dependency can rename its own field and provably
+ *  nothing else* — which is a statement about what a rule may reach, so it has
+ *  to be said positively. `notUnder` remains for subtracting inside a region a
+ *  rule legitimately reaches, which is a narrowing, not the containment itself.
+ *
+ *  **`under` is ANCHORED at the document root**, not a set of key names to look
+ *  for anywhere on the path. Anchoring is what makes the containment claim
+ *  true: a `Telo.Definition`'s `resources:` template body carries other kinds'
+ *  configuration, and any of it may hold a key spelled `schema` over data that
+ *  merely looks like a schema — so "some segment of the path is `schema`" would
+ *  reach the very user JSON blob the positive form exists to keep out, and
+ *  would delete from it silently. Anchored, `under` names top-level document
+ *  keys and a region is a genuine subtree.
+ *
+ *  **`inSchema` is the one region a kind list cannot name.** An annotation
+ *  keyword occurs in author-written JSON Schema, and schema fragments are not
+ *  confined to kind documents: an inline `inputType:` / `outputType:` on ANY kind
+ *  that declares one, an API route's `request.schema.body`, a `Telo.JsonSchema`'s
+ *  `schema`. That set of kinds is open — any kind may declare a schema-valued
+ *  field — and enumerating the standard library's would put resource-kind
+ *  knowledge into the analyzer, against the topology-driven constraint. So a rule
+ *  may instead state that it reaches only inside a SCHEMA REGION, named by the
+ *  KERNEL's own schema-valued keys, which no kind owns.
+ *
+ *  With `inSchema`, and only with it, `inKind` / `under` may be `["*"]` — and
+ *  only for a rule keyed on a reserved `x-telo-*` annotation. That pairing IS the
+ *  containment: the region gate bounds where the walk may go, and the reserved-key
+ *  rule bounds what it may touch, since an `x-telo-*` key is Telo vocabulary
+ *  wherever it appears and cannot mean something else in someone's config. Both
+ *  halves are refused at entry-read time, so a module-shipped entry can no more
+ *  spell `"*"` than it can name another module's kind.
+ *
+ *  The residue is stated rather than claimed away: a manifest that asserts ABOUT
+ *  a schema — a schema literal under a key spelled `schema` inside an assertion's
+ *  expected value — is reachable, and would be rewritten into its own synonym.
+ *  That cannot be closed in a data-only matcher without naming kinds. It is
+ *  accepted because the sites the wildcards reach are exactly the ones no
+ *  enumeration covers, and the alternative leaves an author reading a deprecation
+ *  `telo migrate` refuses to act on.
+ *
+ *  The vocabulary is closed, which is what makes it a trust boundary once
+ *  module-shipped entries are aggregated beside core ones. An unrecognized key
+ *  is refused rather than ignored — a selector that silently matches wider than
+ *  it reads is the one failure this cannot tolerate. */
+import { isInSchemaRegion } from "../schema-region.js";
+/** The wildcard `inKind` / `under` value. Legal only alongside `inSchema`, and
+ *  only for a rule keyed on an `x-telo-*` annotation. */
+export const MATCH_ANY = "*";
+export const MATCH_KEYS = [
+    "key",
+    "inKind",
+    "under",
+    "value",
+    "valueOneOf",
+    "withSibling",
+    "notUnder",
+    "inSchema",
+];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Structural equality over JSON values — what `value` / `valueOneOf` compare
+ *  with, so a match on `true` never also matches `"true"`.
+ *
+ *  Exported because the PATCHER asks the same question in the other direction:
+ *  "is the value already what this would write". Both answers have to come from
+ *  one rule, or a rule could match a spelling the patch then declares current. */
+export function deepEquals(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEquals(item, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const aKeys = Object.keys(a);
+        if (aKeys.length !== Object.keys(b).length)
+            return false;
+        return aKeys.every((k) => Object.hasOwn(b, k) && deepEquals(a[k], b[k]));
+    }
+    return false;
+}
+function requireStringList(describe, raw, key) {
+    const value = raw[key];
+    if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string")) {
+        throw new Error(`${describe}: 'match.${key}' must be a non-empty sequence of strings`);
+    }
+    return value;
+}
+/** Read a rule's `match` block, refusing anything the vocabulary does not
+ *  define. `describe` names the entry and rule so a failure says which. */
+export function readMigrationMatch(describe, raw) {
+    if (!isPlainObject(raw))
+        throw new Error(`${describe}: 'match' must be a mapping`);
+    for (const key of Object.keys(raw)) {
+        if (!MATCH_KEYS.includes(key)) {
+            throw new Error(`${describe}: 'match' has no key '${key}'. Known keys: ${MATCH_KEYS.join(", ")}.`);
+        }
+    }
+    if (typeof raw.key !== "string" || raw.key.length === 0) {
+        throw new Error(`${describe}: 'match.key' must be a non-empty string`);
+    }
+    if (Object.hasOwn(raw, "value") && Object.hasOwn(raw, "valueOneOf")) {
+        throw new Error(`${describe}: 'match' takes at most one of 'value' or 'valueOneOf'`);
+    }
+    if (Object.hasOwn(raw, "valueOneOf") && !Array.isArray(raw.valueOneOf)) {
+        throw new Error(`${describe}: 'match.valueOneOf' must be a sequence`);
+    }
+    if (Object.hasOwn(raw, "withSibling") && typeof raw.withSibling !== "string") {
+        throw new Error(`${describe}: 'match.withSibling' must be a string`);
+    }
+    if (Object.hasOwn(raw, "notUnder") &&
+        (!Array.isArray(raw.notUnder) || raw.notUnder.some((k) => typeof k !== "string"))) {
+        throw new Error(`${describe}: 'match.notUnder' must be a sequence of strings`);
+    }
+    if (Object.hasOwn(raw, "inSchema") && typeof raw.inSchema !== "boolean") {
+        throw new Error(`${describe}: 'match.inSchema' must be a boolean`);
+    }
+    // The two conditions that make a wildcard safe, refused here rather than
+    // narrowed later: a rule the reader accepts is a rule the driver will run, and
+    // a selector that matches wider than it reads is exactly what this vocabulary
+    // exists to prevent. A module-shipped entry therefore cannot spell `"*"` at
+    // all, because it cannot satisfy both halves for a keyword it does not own.
+    const wildcards = [
+        ...(Array.isArray(raw.inKind) ? raw.inKind : []),
+        ...(Array.isArray(raw.under) ? raw.under : []),
+    ].filter((value) => value === MATCH_ANY);
+    if (wildcards.length > 0) {
+        if (raw.inSchema !== true) {
+            throw new Error(`${describe}: 'match.inKind' / 'match.under' may only be '${MATCH_ANY}' together with ` +
+                `'inSchema: true' — the schema region is what bounds a walk the wildcard unbounds`);
+        }
+        if (!raw.key.startsWith("x-telo-")) {
+            throw new Error(`${describe}: '${MATCH_ANY}' is legal only for a rule keyed on an 'x-telo-*' annotation, ` +
+                `which is Telo vocabulary wherever it appears — '${raw.key}' could mean something else ` +
+                `inside a resource's own configuration`);
+        }
+    }
+    const match = {
+        key: raw.key,
+        inKind: requireStringList(describe, raw, "inKind"),
+        under: requireStringList(describe, raw, "under"),
+    };
+    if (Object.hasOwn(raw, "value"))
+        match.value = raw.value;
+    if (Object.hasOwn(raw, "valueOneOf"))
+        match.valueOneOf = raw.valueOneOf;
+    if (Object.hasOwn(raw, "withSibling"))
+        match.withSibling = raw.withSibling;
+    if (Object.hasOwn(raw, "notUnder"))
+        match.notUnder = raw.notUnder;
+    if (raw.inSchema === true)
+        match.inSchema = true;
+    return match;
+}
+/**
+ * Index `document`'s candidate sites for `keys`, descending only into the
+ * top-level regions named by `roots`.
+ *
+ * The caller has already gated on `inKind` — see `selectMatches`, which repeats
+ * the check because it holds the individual rule.
+ */
+export function buildMatchIndex(document, keys, roots) {
+    const index = new Map();
+    if (keys.size === 0 || roots.size === 0 || !isPlainObject(document))
+        return index;
+    // A mutable stack, materialized into an array only when a site is recorded.
+    const stack = [];
+    const record = (key, value, parent) => {
+        const bucket = index.get(key) ?? [];
+        bucket.push({ path: [...stack], value, parent });
+        index.set(key, bucket);
+    };
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                stack.push(i);
+                walk(node[i]);
+                stack.pop();
+            }
+            return;
+        }
+        if (!isPlainObject(node))
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            stack.push(key);
+            if (keys.has(key))
+                record(key, value, node);
+            walk(value);
+            stack.pop();
+        }
+    };
+    // Anchored containment, enforced by where the walk STARTS: everything the
+    // index holds is at or below a top-level key some rule named. A wildcard root
+    // starts everywhere instead — bounded not by where the walk begins but by the
+    // schema region and the reserved key its rule had to declare to earn it.
+    const everywhere = roots.has(MATCH_ANY);
+    for (const [key, value] of Object.entries(document)) {
+        if (!everywhere && !roots.has(key))
+            continue;
+        stack.push(key);
+        if (keys.has(key))
+            record(key, value, document);
+        walk(value);
+        stack.pop();
+    }
+    return index;
+}
+/** The rules in `entries` that may match a document of `kind`, with the key and
+ *  root sets their shared index needs. Empty rules mean the document is not
+ *  walked at all. */
+export function applicableRules(rules, kind) {
+    const applicable = [];
+    const keys = new Set();
+    const roots = new Set();
+    if (typeof kind !== "string")
+        return { rules: applicable, keys, roots };
+    for (const rule of rules) {
+        if (!rule.match.inKind.includes(kind) && !rule.match.inKind.includes(MATCH_ANY))
+            continue;
+        applicable.push(rule);
+        keys.add(rule.match.key);
+        for (const root of rule.match.under)
+            roots.add(root);
+    }
+    return { rules: applicable, keys, roots };
+}
+function valueMatches(match, value) {
+    if (Object.hasOwn(match, "value"))
+        return deepEquals(match.value, value);
+    if (match.valueOneOf)
+        return match.valueOneOf.some((candidate) => deepEquals(candidate, value));
+    return true;
+}
+/** The sites in `index` this match selects, in document order. */
+export function selectMatches(index, document, match) {
+    const kind = isPlainObject(document) ? document.kind : undefined;
+    if (typeof kind !== "string")
+        return [];
+    if (!match.inKind.includes(kind) && !match.inKind.includes(MATCH_ANY))
+        return [];
+    const sites = index.get(match.key);
+    if (!sites)
+        return [];
+    const anyRoot = match.under.includes(MATCH_ANY);
+    const out = [];
+    for (const site of sites) {
+        // The index may be shared with rules naming other regions, so the anchor is
+        // re-checked per rule. A numeric first segment cannot occur — a document is
+        // a mapping — but the guard keeps the containment claim independent of that.
+        const anchor = site.path[0];
+        if (!anyRoot && (typeof anchor !== "string" || !match.under.includes(anchor)))
+            continue;
+        // The schema region — the same ancestry rule every schema-bounded surface
+        // reads, so the migration and the validators cannot disagree about where a
+        // schema is.
+        if (match.inSchema && !isInSchemaRegion(site.path))
+            continue;
+        // `notUnder` subtracts within the region, so it reads the whole path. A
+        // numeric segment never equals a key name, so the raw path is enough.
+        if (match.notUnder?.some((segment) => site.path.includes(segment)))
+            continue;
+        if (!valueMatches(match, site.value))
+            continue;
+        if (match.withSibling !== undefined && !Object.hasOwn(site.parent, match.withSibling))
+            continue;
+        out.push(site.path);
+    }
+    return out;
+}
+/** Convenience for a single match against a document — builds a one-rule index.
+ *  The driver uses `applicableRules` + `buildMatchIndex` + `selectMatches` so
+ *  one walk serves every rule that can reach the document. */
+export function findMatches(document, match) {
+    const index = buildMatchIndex(document, new Set([match.key]), new Set(match.under));
+    return selectMatches(index, document, match);
+}

package/dist/migrations/patch.d.ts

@@ -0,0 +1,68 @@
+/** Planning and applying a migration patch.
+ *
+ *  Planning is separate from applying because a patch is ALL-OR-NOTHING at each
+ *  match: a rule whose second operation cannot apply must not leave the first
+ *  one's edit behind. `planPatch` resolves every operation against the tree
+ *  first and returns either a concrete effect list or one refusal; only then
+ *  does an applier run. The same plan drives both appliers — the JSON tree the
+ *  loader hands the analyzer, and the YAML document `telo migrate` writes — so
+ *  the in-memory rewrite and the on-disk repair cannot disagree about what an
+ *  operation means. */
+import type { MigrationOperation, MigrationPath, MigrationRefusal } from "./types.js";
+/** A resolved, unconditionally applicable edit. */
+export type MigrationEffect = {
+    readonly kind: "rename-key";
+    readonly parent: MigrationPath;
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: "set-value";
+    readonly path: MigrationPath;
+    readonly value: unknown;
+} | {
+    readonly kind: "set-tag";
+    readonly path: MigrationPath;
+    readonly tag: string;
+    readonly source: string;
+} | {
+    readonly kind: "insert-item";
+    readonly path: MigrationPath;
+    readonly index: number;
+    readonly value: unknown;
+} | {
+    readonly kind: "remove-entry";
+    readonly path: MigrationPath;
+};
+export interface PatchPlan {
+    readonly effects: readonly MigrationEffect[];
+    /** Where the matched node lives after the patch. Differs from the matched
+     *  path only when a `rename-key` moved it. */
+    readonly finalPath: MigrationPath;
+    /** The value at the match before anything was applied — the "before" half of
+     *  the generated diagnostic sentence. */
+    readonly before: unknown;
+    /** The value at the match after the patch, or `undefined` for a removal. */
+    readonly after: unknown;
+}
+export type PatchPlanResult = {
+    readonly ok: true;
+    readonly plan: PatchPlan;
+} | {
+    readonly ok: false;
+    readonly refusal: MigrationRefusal;
+};
+/**
+ * Resolve `ops` at `path` against `root`, or refuse.
+ *
+ * Refusing is the design's safety valve: the node is left exactly as the author
+ * wrote it and the ordinary validator reports it with an accurate message,
+ * rather than the migration guessing or dropping a value.
+ */
+export declare function planPatch(root: unknown, path: MigrationPath, ops: readonly MigrationOperation[]): PatchPlanResult;
+/** Apply a plan to the in-memory manifest tree. Mutates in place — the tree is
+ *  the loader's own projection of the document, never the author's file. */
+export declare function applyEffectsToTree(root: unknown, effects: readonly MigrationEffect[]): void;
+/** Dotted rendering of a path, in the form the position index and every
+ *  diagnostic's `data.path` use: `routes[0].handler`. */
+export declare function formatMigrationPath(path: MigrationPath): string;
+//# sourceMappingURL=patch.d.ts.map

package/dist/migrations/patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["../../src/migrations/patch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;uBASuB;AAIvB,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,mDAAmD;AACnD,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3G;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC/G;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C;kDAC8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC;6CACyC;IACzC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAoD/D;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,SAAS,kBAAkB,EAAE,GACjC,eAAe,CA4FjB;AAED;4EAC4E;AAC5E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CA6C3F;AAUD;yDACyD;AACzD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAO/D"}