@telorun/analyzer 0.62.0 → 0.63.0

package/dist/resource-rule.js

@@ -0,0 +1,236 @@
+/**
+ * The single reader for `x-telo-resource-rules` — a kind declaring, as data,
+ * relationships between the fields of one resource that JSON Schema cannot
+ * state: an index naming a column its table does not declare, a foreign key
+ * whose two sides differ in length, a rename whose source is still declared.
+ *
+ * The predicate is CEL over `self` (the whole resource) and `this` (the element
+ * under test), so correlating two collections is a comprehension closure rather
+ * than a path language with wildcard bindings to design. `in:` names the
+ * collection to iterate and IS the diagnostic anchor: iterating what the pointer
+ * names is what makes a reported path exist by construction.
+ *
+ * Vocabulary borrowed from `Telo.JsonSchema.rules` — `condition` true when the
+ * rule HOLDS, the subject bound as `this`, plus `code` and `message` — because
+ * two CEL rule vocabularies with opposite polarity is a trap an author falls
+ * into once per rule. The two mechanisms stay separate: a `Telo.JsonSchema` rule
+ * runs at dispatch against a value, this one at `telo check` against a manifest.
+ *
+ * Lenient by design, the `ref-slot.ts` precedent: anything unreadable here reads
+ * as absent, and `validate-resource-rules.ts` is the strict half that reports it.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+export const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/** True for a node the loader produced from a `!cel` tag or a `${{ }}` string.
+ *  Both markers are tested because they are not always both present: a
+ *  registered definition's schema reaches the analyzer with `call` and
+ *  `__compiled` dropped, keeping only `__tagged` + `source`. Testing one would
+ *  make a rule readable on some paths and invisible on others. */
+function isCelNode(value) {
+    return isObject(value) && (value.__compiled === true || value.__tagged === true);
+}
+/** A precompiled `!cel` node keeps its author-written text on `source`; a plain
+ *  string is taken verbatim so a rule reads the same however the loader was
+ *  configured (a round-trip view runs with `compile` off). */
+export function celSourceOf(value) {
+    if (typeof value === "string")
+        return value;
+    if (isCelNode(value) && typeof value.source === "string")
+        return value.source;
+    return undefined;
+}
+/** The annotation exactly as written, for the strict half. `undefined` when the
+ *  kind declares none; a non-array is returned as-is so the shape can be
+ *  reported rather than silently skipped. */
+export function readRawResourceRules(schema) {
+    if (!isObject(schema))
+        return undefined;
+    return schema[RESOURCE_RULES_ANNOTATION];
+}
+/** Every rule this kind declares that is well-formed enough to run. */
+export function readResourceRules(schema) {
+    const raw = readRawResourceRules(schema);
+    if (!Array.isArray(raw))
+        return [];
+    const rules = [];
+    raw.forEach((entry, index) => {
+        if (!isObject(entry))
+            return;
+        const condition = celSourceOf(entry.condition);
+        const { code, message } = entry;
+        if (!condition || typeof code !== "string" || typeof message !== "string")
+            return;
+        if (code.length === 0 || message.length === 0)
+            return;
+        const severity = entry.severity === "warning" ? "warning" : "error";
+        if (entry.severity !== undefined && entry.severity !== "warning" && entry.severity !== "error") {
+            return;
+        }
+        const pointer = entry.in;
+        if (pointer !== undefined && typeof pointer !== "string")
+            return;
+        rules.push({
+            ...(pointer === undefined ? {} : { in: pointer }),
+            condition,
+            code,
+            message,
+            severity,
+            index,
+        });
+    });
+    return rules;
+}
+/** Split a JSON Pointer into its unescaped segments. `/` alone is the root. */
+export function pointerSegments(pointer) {
+    if (pointer === "" || pointer === "/")
+        return [];
+    if (!pointer.startsWith("/"))
+        return undefined;
+    return pointer
+        .slice(1)
+        .split("/")
+        .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+/** Navigate a pointer within a value, stopping at anything that is not a plain
+ *  container. Returns `undefined` for a pointer that does not resolve — which a
+ *  resource legitimately produces by omitting an optional collection. */
+export function resolvePointer(value, pointer) {
+    const segments = pointerSegments(pointer);
+    if (!segments)
+        return undefined;
+    let current = value;
+    for (const segment of segments) {
+        if (Array.isArray(current)) {
+            const index = Number(segment);
+            if (!Number.isInteger(index))
+                return undefined;
+            current = current[index];
+        }
+        else if (isObject(current)) {
+            current = current[segment];
+        }
+        else {
+            return undefined;
+        }
+        if (current === undefined)
+            return undefined;
+    }
+    return current;
+}
+/** Path prefix for a pointer, in the dotted/bracketed spelling diagnostics use
+ *  (`foreignKeys[0].references`), so `data.path` is one grammar throughout. */
+export function pointerToPath(pointer) {
+    const segments = pointerSegments(pointer) ?? [];
+    return segments.reduce((acc, segment) => {
+        if (/^\d+$/.test(segment))
+            return `${acc}[${segment}]`;
+        return acc === "" ? segment : `${acc}.${segment}`;
+    }, "");
+}
+/**
+ * The elements a rule iterates. An array yields one subject per item, a map one
+ * per entry with its key bound; a collection that is absent yields none, which
+ * is a rule that had nothing to say rather than a rule that failed.
+ *
+ * A scalar at the pointer is `undefined` — not an empty list — because that is a
+ * declaration defect the strict half reports, and an empty list would hide it.
+ */
+export function resolveRuleSubjects(config, pointer) {
+    const collection = resolvePointer(config, pointer);
+    if (collection === undefined || collection === null)
+        return [];
+    const base = pointerToPath(pointer);
+    if (Array.isArray(collection)) {
+        return collection.map((value, index) => ({ path: `${base}[${index}]`, value }));
+    }
+    if (isObject(collection)) {
+        return Object.entries(collection).map(([key, value]) => ({
+            path: `${base}.${key}`,
+            value,
+            key,
+        }));
+    }
+    return undefined;
+}
+/**
+ * Path of the first CEL leaf inside a value, or `undefined` when every leaf is
+ * literal. A rule reading an expression would be evaluating a placeholder, so
+ * the subject is skipped — and the skip is reported, never silent.
+ *
+ * Stops at nested inline `{ kind }` declarations for the reason every other walk
+ * does: that CEL belongs to the nested kind, evaluated in its own scope.
+ */
+export function findDynamicLeaf(value, base = "") {
+    if (isObject(value)) {
+        if (isCelNode(value))
+            return base || "(value)";
+        if (typeof value.kind === "string" && base !== "")
+            return undefined;
+        for (const [key, child] of Object.entries(value)) {
+            const found = findDynamicLeaf(child, base === "" ? key : `${base}.${key}`);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const found = findDynamicLeaf(value[i], `${base}[${i}]`);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/**
+ * The nodes a condition actually READS, resolved against the resource and the
+ * element under test — the input to the dynamic-leaf check.
+ *
+ * Scanning the whole subject instead would make the check useless in exactly
+ * the shape it matters most: a resource-wide rule takes the whole resource as
+ * its subject, so one unrelated `!cel` anywhere (a `version:` read from
+ * `module.version`, which is the conventional spelling) would switch off every
+ * such rule. Chains are the same primitive the binding-order derivation uses:
+ * parsed, never lexed, so a name inside a string literal reads nothing.
+ *
+ * A chain stops at a computed index (`INDEX_SEGMENT`): what it selects is not
+ * known statically, so the node reached so far is what gets checked — the
+ * over-approximating direction, which errs toward skipping rather than toward
+ * evaluating a placeholder.
+ */
+export function readNodes(chains, 
+/** The bindings in scope, by name — `self`/`this`/`key` for a resource rule,
+ *  `self`/`referrer` for a referrer rule. A chain rooted at a name that is not
+ *  bound reads nothing. */
+roots) {
+    const nodes = [];
+    for (const chain of chains) {
+        const root = chain[0];
+        let current = root !== undefined && root in roots ? roots[root] : undefined;
+        if (current === undefined)
+            continue;
+        for (const segment of chain.slice(1)) {
+            if (segment === "[*]")
+                break;
+            if (Array.isArray(current)) {
+                const index = Number(segment);
+                current = Number.isInteger(index) ? current[index] : undefined;
+            }
+            else if (isObject(current)) {
+                current = current[segment];
+            }
+            else {
+                current = undefined;
+            }
+            if (current === undefined)
+                break;
+        }
+        if (current !== undefined)
+            nodes.push(current);
+    }
+    return nodes;
+}

package/dist/rule-condition.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A rule's CEL condition: compiling it once, and refusing the ones that cannot
+ * be checks.
+ *
+ * Shared by `x-telo-resource-rules` (fields of one resource) and
+ * `x-telo-referrer-rules` (a requirement on whoever references it). The two
+ * families differ in what they bind — `this` and `key` versus `referrer` — and
+ * in nothing else: same polarity, same cache, same refusals, same budget. Two
+ * copies would eventually disagree about which functions a rule may call, which
+ * is a soundness property rather than a style one.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { buildCelEnvironment } from "@telorun/templating";
+/**
+ * Wall-clock ceiling for one rule over one resource. The rules run on the
+ * kernel's boot path and at the editor's keystroke-time analysis, and the
+ * comprehension nesting is the RULE AUTHOR's — a dependency's quadratic rule
+ * must not be able to hang a consumer's `telo check`.
+ *
+ * It bounds the SUBJECT LOOP, not one expression: cel-js offers no step limit,
+ * so a single pathological expression over one huge element still runs to
+ * completion. Stated rather than hidden — the budget catches the shape that
+ * actually occurs (a cheap expression over many subjects) and reports the rule
+ * as defective rather than truncating coverage silently.
+ */
+export declare const RULE_BUDGET_MS = 50;
+/** The analyzer's own environment — no host handlers, so every `hostBacked`
+ *  entry is a throwing stub. Built once; it is stateless. */
+export declare function ruleEnv(): ReturnType<typeof buildCelEnvironment>;
+export type CompiledRule = {
+    parsed: (ctx: Record<string, unknown>) => unknown;
+    chains: readonly (readonly string[])[];
+} | {
+    reason: string;
+};
+export declare function compileRuleCondition(condition: string, 
+/** Chain roots to assume when the parse yields no AST — "unknown", not
+ *  "reads nothing", so the caller checks the whole of every binding. */
+fallbackRoots: readonly string[]): CompiledRule;
+/**
+ * Why a condition cannot serve as a check, as messages for the declaring kind.
+ *
+ * Two refusals beyond the CEL diagnostics themselves: a function the kernel
+ * supplies at boot (a throwing stub here, so the rule could never run at
+ * `telo check`), and a non-deterministic one (a verdict that depends on when it
+ * ran is not a verdict).
+ */
+export declare function conditionRefusals(condition: string): string[];
+//# sourceMappingURL=rule-condition.d.ts.map

package/dist/rule-condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-condition.d.ts","sourceRoot":"","sources":["../src/rule-condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAEL,mBAAmB,EAGpB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAQjC;6DAC6D;AAC7D,wBAAgB,OAAO,IAAI,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAGhE;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CAAE,GAC7F;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBvB,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM;AACjB;wEACwE;AACxE,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,YAAY,CAoBd;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB7D"}

package/dist/rule-condition.js

@@ -0,0 +1,108 @@
+/**
+ * A rule's CEL condition: compiling it once, and refusing the ones that cannot
+ * be checks.
+ *
+ * Shared by `x-telo-resource-rules` (fields of one resource) and
+ * `x-telo-referrer-rules` (a requirement on whoever references it). The two
+ * families differ in what they bind — `this` and `key` versus `referrer` — and
+ * in nothing else: same polarity, same cache, same refusals, same budget. Two
+ * copies would eventually disagree about which functions a rule may call, which
+ * is a soundness property rather than a style one.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { CEL_FUNCTIONS, buildCelEnvironment, celEngine, extractAccessChains, } from "@telorun/templating";
+/**
+ * Wall-clock ceiling for one rule over one resource. The rules run on the
+ * kernel's boot path and at the editor's keystroke-time analysis, and the
+ * comprehension nesting is the RULE AUTHOR's — a dependency's quadratic rule
+ * must not be able to hang a consumer's `telo check`.
+ *
+ * It bounds the SUBJECT LOOP, not one expression: cel-js offers no step limit,
+ * so a single pathological expression over one huge element still runs to
+ * completion. Stated rather than hidden — the budget catches the shape that
+ * actually occurs (a cheap expression over many subjects) and reports the rule
+ * as defective rather than truncating coverage silently.
+ */
+export const RULE_BUDGET_MS = 50;
+const HOST_BACKED = new Set(CEL_FUNCTIONS.filter((f) => f.hostBacked).map((f) => f.name));
+const NON_DETERMINISTIC = new Set(CEL_FUNCTIONS.filter((f) => !f.deterministic).map((f) => f.name));
+let sharedEnv;
+/** The analyzer's own environment — no host handlers, so every `hostBacked`
+ *  entry is a throwing stub. Built once; it is stateless. */
+export function ruleEnv() {
+    sharedEnv ??= buildCelEnvironment();
+    return sharedEnv;
+}
+/**
+ * A rule's condition, parsed once per process rather than once per resource.
+ *
+ * The pass runs over every resource of a kind and at the editor's
+ * keystroke-time analysis, so a workspace with fifty tables parsed the same
+ * six conditions fifty times each. The source string is the whole key: the
+ * environment is stateless and shared, so two identical conditions genuinely
+ * compile to the same program. A parse FAILURE is cached too — it is a property
+ * of the condition, and re-deriving it per resource costs the same as the
+ * success it replaced.
+ *
+ * BOUNDED, because the editor analyses on every keystroke: a kind author editing
+ * a `condition:` interns one entry per character typed, and every one of those
+ * intermediate strings is dead the moment the next arrives. Insertion-ordered
+ * eviction is enough — the working set is the conditions a workspace actually
+ * declares, and a stale entry costs one re-parse.
+ */
+const RULE_CACHE_LIMIT = 512;
+const compiledRules = new Map();
+export function compileRuleCondition(condition, 
+/** Chain roots to assume when the parse yields no AST — "unknown", not
+ *  "reads nothing", so the caller checks the whole of every binding. */
+fallbackRoots) {
+    const cached = compiledRules.get(condition);
+    if (cached)
+        return cached;
+    let result;
+    try {
+        const parsed = ruleEnv().parse(condition);
+        const ast = parsed.ast;
+        result = {
+            parsed,
+            chains: ast ? extractAccessChains(ast) : fallbackRoots.map((root) => [root]),
+        };
+    }
+    catch (err) {
+        result = { reason: err instanceof Error ? err.message : String(err) };
+    }
+    if (compiledRules.size >= RULE_CACHE_LIMIT) {
+        const oldest = compiledRules.keys().next();
+        if (!oldest.done)
+            compiledRules.delete(oldest.value);
+    }
+    compiledRules.set(condition, result);
+    return result;
+}
+/**
+ * Why a condition cannot serve as a check, as messages for the declaring kind.
+ *
+ * Two refusals beyond the CEL diagnostics themselves: a function the kernel
+ * supplies at boot (a throwing stub here, so the rule could never run at
+ * `telo check`), and a non-deterministic one (a verdict that depends on when it
+ * ran is not a verdict).
+ */
+export function conditionRefusals(condition) {
+    const out = [];
+    const result = celEngine.analyze(condition, { celEnv: ruleEnv(), contextSchema: null });
+    for (const diagnostic of result.diagnostics)
+        out.push(`Rule condition: ${diagnostic.message}`);
+    for (const call of result.calls) {
+        if (HOST_BACKED.has(call.name)) {
+            out.push(`Rule condition calls '${call.name}()', which the kernel supplies at boot ` +
+                "(it needs Node crypto / Buffer). The analyzer registers a throwing stub, so " +
+                "the rule cannot run at telo check.");
+        }
+        else if (NON_DETERMINISTIC.has(call.name) || call.deterministic === false) {
+            out.push(`Rule condition calls '${call.name}()', which re-evaluates per call. A check ` +
+                "whose verdict depends on when it ran is not a check.");
+        }
+    }
+    return out;
+}

package/dist/schema-keywords.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-keywords.d.ts","sourceRoot":"","sources":["../src/schema-keywords.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D;iDACiD;AACjD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AASrE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAuJ/D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,WAAW,EACzD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgIxB,CAAC"}
+{"version":3,"file":"schema-keywords.d.ts","sourceRoot":"","sources":["../src/schema-keywords.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D;iDACiD;AACjD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AASrE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAuJ/D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,WAAW,EACzD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwJxB,CAAC"}

package/dist/schema-keywords.js

@@ -245,6 +245,26 @@ export const TELO_SCHEMA_ANNOTATIONS = {
         description: "Derive this field's validation schema from a sibling ref's definition schema.",
         type: "string",
     },
+    "x-telo-schema-map": {
+        title: "Schema map",
+        description: "On the field a projection keys on: the JSON Schema node each of its values means. A lookup, never a computed expression.",
+        type: "object",
+    },
+    "x-telo-schema-projection": {
+        title: "Schema projection",
+        description: "How a collection of typed entries projects to a JSON Schema object — which collection, which field keys it, and which fields modify it. Belongs on the kind DOCUMENT, beside 'schema:' rather than inside it, because it describes the whole declaration and not one field; written here it still works and is reported so it can be moved.",
+        type: "object",
+    },
+    "x-telo-resource-rules": {
+        title: "Resource rules",
+        description: "Relationships between this kind's own fields that JSON Schema cannot state, as CEL over `self` (the resource) and `this` (the element `in:` iterates). `condition` is TRUE when the rule holds.",
+        type: "array",
+    },
+    "x-telo-schema-projection-from": {
+        title: "Schema projection from",
+        description: "Replace this node with the projection of the entry collection declared by the kind referenced at the named field.",
+        type: "string",
+    },
     "x-telo-value-schema-from": {
         title: "Value schema from",
         description: "The value here must satisfy the type declared at the named field — checked for EVERY such slot, not only the branch a given input selects.",

package/dist/schema-projection.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The schema-projection annotations' single reader — the `ref-slot.ts` /
+ * `zone-slot.ts` precedent.
+ *
+ * A kind whose configuration is a COLLECTION OF TYPED ENTRIES can say what that
+ * collection means as a JSON Schema object, so a consumer can type the values
+ * it will read without the analyzer learning anything about the domain. A SQL
+ * table's columns are the first consumer; nothing in either annotation says
+ * SQL, column or table.
+ *
+ * Two halves, because the two facts have different owners:
+ *
+ * - `x-telo-schema-map`, on the field a projection keys on, gives the schema
+ *   node each of its values means (`citext → {type: string}`). It sits with the
+ *   field because that is where the value vocabulary is declared.
+ * - `x-telo-schema-projection`, on the KIND DOCUMENT (a sibling of `schema:`,
+ *   not a keyword inside it), names the entry collection, the keying field, and
+ *   the fields that MODIFY the mapped node. It sits on the document because it
+ *   describes the kind's whole declaration rather than one field of it — but
+ *   `schema:` is where every other `x-telo-*` keyword lives, so the reader
+ *   accepts it in both positions and `validate-schema-projection.ts` reports the
+ *   inner one. Silently ignoring a misplaced annotation is the exact failure the
+ *   strict half exists to prevent: the projection stops typing its consumers and
+ *   the diagnostic lands on the CONSUMER, blaming the wrong author.
+ *
+ * It is a declared LOOKUP, never a computed expression. The analyzer
+ * type-checks CEL and substitutes placeholders; it never evaluates, and a
+ * `base:`-style mapping is evaluated by the kernel at `create()` — too late for
+ * `telo check` to type the rows a consumer reads, which is the projection's
+ * whole purpose.
+ *
+ * Distinct from `x-telo-schema-from`, which derives a field's schema from a
+ * referenced KIND's definition schema. A projection is DECLARATION-derived: the
+ * row shape lives in one instance's own `columns:`, which no definition-level
+ * derivation can reach.
+ */
+/** How a kind's entry collection projects to an object schema. */
+export interface SchemaProjection {
+    /** JSON Pointer, from the resource root, to the entries. */
+    readonly entries: string;
+    /** The entry field whose value keys the `x-telo-schema-map` lookup. */
+    readonly key: string;
+    /** The entry field naming an entry's identity, when entries are an ARRAY.
+     *  Absent for a keyed map, where the map key is the identity. */
+    readonly nameField?: string;
+    /** Entry field that widens the mapped node to admit null. */
+    readonly nullable?: string;
+    /** Entry field that wraps the mapped node in an array. */
+    readonly array?: string;
+}
+export type SchemaMap = Readonly<Record<string, Record<string, unknown>>>;
+/** The projection a kind declares, or undefined. Invalid shapes read as absent;
+ *  `validate-schema-projection.ts` is the half that reports them. */
+export declare function readSchemaProjection(definition: unknown): SchemaProjection | undefined;
+/** The annotation as written, from either position — the document (canonical)
+ *  or `schema:` (accepted, and reported by the strict half). The document wins:
+ *  a kind spelling it in both places is describing its own document. */
+export declare function rawSchemaProjection(definition: unknown): unknown;
+/** True when the annotation was found inside `schema:` rather than on the
+ *  document — the misplacement the strict half reports. */
+export declare function schemaProjectionIsMisplaced(definition: unknown): boolean;
+export declare function readSchemaMap(node: unknown): SchemaMap | undefined;
+/** The consumer-side annotation: a JSON Pointer to this resource's ref slot
+ *  whose target declares the projection. */
+export declare function readProjectionFrom(node: unknown): string | undefined;
+/**
+ * Find the `x-telo-schema-map` a projection keys on. The map sits on the entry
+ * field's schema, which is reached through the collection's own schema — a
+ * keyed map's `additionalProperties`, or an array's `items`.
+ */
+export declare function projectionKeyMap(kindSchema: unknown, projection: SchemaProjection): SchemaMap | undefined;
+/**
+ * Project one declaration to an object schema.
+ *
+ * Modifiers are a CLOSED set applied in a FIXED order — `array` wraps, then
+ * `nullable` widens. Closed because each changes how the schema is assembled,
+ * so a third-party modifier would be a name nothing acts on; ordered because
+ * leaving it implicit is how two implementations come to disagree.
+ *
+ * The projection is deliberately LOSSY. Length, precision, collation and check
+ * constraints do not reach it: a consumer needs the type, its nullability and
+ * its repetition, and the database enforces the rest. A per-entry schema rich
+ * enough to double as a validator would move the domain's semantics into the
+ * type layer.
+ */
+export declare function projectEntries(manifest: unknown, projection: SchemaProjection, map: SchemaMap): Record<string, unknown> | undefined;
+/** A reference as the analyzer sees it: the internal `{kind, name, alias?}`
+ *  shape `resolveRefSentinels` rewrites `!ref` to. */
+export interface ProjectionRef {
+    readonly name: string;
+    readonly kind?: string;
+    readonly alias?: string;
+}
+/** The `{kind, name, alias?}` reference a value holds, or undefined. Exported so
+ *  a host whose slot may hold EITHER shape can fall back to this reading. */
+export declare function readProjectionRef(value: unknown): ProjectionRef | undefined;
+/** What a reference resolved to. `"ambiguous"` is distinct from `undefined`
+ *  because the two need different advice: one says disambiguate, the other says
+ *  the name resolves to nothing. */
+export type ProjectionLookup = {
+    readonly manifest: Record<string, any>;
+} | {
+    readonly ambiguous: true;
+} | undefined;
+/**
+ * What projecting a consumer's slot needs: resolving a reference to the manifest
+ * it names, and the definition that manifest's `kind` names.
+ *
+ * A RESOLVER rather than a list of manifests, because resolution is scoped and
+ * only the host knows the scope: an alias-qualified `!ref Alias.users` names an
+ * import's exported instance, and a bare name means the enclosing module's — a
+ * distinction a name filter over one flattened list erases, which is how an
+ * unambiguous cross-module reference came to read as ambiguous. It is also what
+ * lets the kernel supply its own context lookup, so the contract the analyzer
+ * types and the contract the kernel enforces are the same schema.
+ */
+export interface ProjectionScope {
+    /**
+     * The declaration the value at a projected slot names.
+     *
+     * Takes the RAW slot value rather than a parsed reference, because what sits
+     * there depends on the host and only the host can read it: the analyzer sees
+     * the `{kind, name, alias?}` reference the loader produced, while the kernel
+     * binds contracts AFTER Phase-5 injection has replaced that reference with the
+     * live instance. Parsing it here would have hardcoded the analyzer's shape and
+     * left the kernel unable to resolve anything — which is a contract enforced
+     * statically and not at dispatch.
+     */
+    resolveManifest(value: unknown): ProjectionLookup;
+    resolveDefinition(kind: string): Record<string, any> | undefined;
+}
+/**
+ * The resolver for a FLATTENED manifest list — the analyzer's own shape.
+ *
+ * An alias narrows to the manifests forwarded from that import (stamped
+ * `metadata.alias` by flatten), so two libraries each exporting a `users` table
+ * stay distinguishable. Only when nothing carries the alias does it fall back to
+ * matching by name alone, which is the pre-flatten shape a standalone module
+ * analysis has.
+ */
+export declare function manifestListScope(manifests: readonly Record<string, any>[], resolveDefinition: (kind: string) => Record<string, any> | undefined): ProjectionScope;
+export type ProjectionFailure = {
+    readonly reason: "no-ref";
+    readonly pointer: string;
+} | {
+    readonly reason: "unresolved";
+    readonly pointer: string;
+    readonly name: string;
+} | {
+    readonly reason: "ambiguous";
+    readonly pointer: string;
+    readonly name: string;
+} | {
+    readonly reason: "no-projection";
+    readonly pointer: string;
+    readonly kind: string;
+};
+export declare function describeProjectionFailure(failure: ProjectionFailure): string;
+/**
+ * Replace every `x-telo-schema-projection-from` node with the projection of the
+ * declaration it points at.
+ *
+ * Structural: returns a new schema and never mutates the one handed in. A node
+ * that cannot be projected is left exactly as it was — degrading to the slot's
+ * own schema rather than to a wrong one — and the reason is pushed to
+ * `failures`, because degrading SILENTLY is the failure this whole mechanism
+ * exists to move earlier: the consumer's contract quietly reopens and a
+ * misspelled field passes `telo check` exactly as it did before.
+ */
+export declare function resolveSchemaProjections(schema: unknown, manifest: Record<string, any> | undefined, scope: ProjectionScope, failures?: ProjectionFailure[]): unknown;
+//# sourceMappingURL=schema-projection.d.ts.map

package/dist/schema-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-projection.d.ts","sourceRoot":"","sources":["../src/schema-projection.ts"],"names":[],"mappings":"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"}