@telorun/analyzer 0.72.0 → 0.74.0

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAiBzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAgC9B,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAWvF,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AA4DjE,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAkGpB;0CAC0C;AAC1C,eAAO,MAAM,eAAe,GAAI,OAAO;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAG,OACT,CAAC;AAErD;8EAC8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAqUD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC;AA6DD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAkFD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAsiEvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAyBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAiBzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAuC9B,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAWvF,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AA4DjE,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAwGpB;0CAC0C;AAC1C,eAAO,MAAM,eAAe,GAAI,OAAO;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAG,OACT,CAAC;AAErD;8EAC8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAqUD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC;AA6DD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAkFD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAsmEvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAyBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -4,12 +4,12 @@ import { AliasResolver, scopeResolverForModule, } from "./alias-resolver.js";
 import { buildCelEnvironment, isKindDocument, } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { readDeprecation } from "./deprecation.js";
-import { effectiveAuthorSchema } from "./extends-resolution.js";
+import { effectiveAuthorSchema, inheritedCapability, inheritedRequiredFields, } from "./extends-resolution.js";
 import { analyzerContractScope, resolveContract, } from "./invocation-contract.js";
 import { buildCallGraph } from "./call-graph.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import { buildKernelGlobalsIndex, KERNEL_GLOBAL_NAMES, } from "./kernel-globals.js";
-import { buildObservedStateIndex, buildObservedStateResourcesSchema, collectRunReachableNames, observedStateRead, validateObservedStateDeclarations, } from "./validate-observed-state.js";
+import { buildObservedStateIndex, buildObservedStateResourcesSchema, collectRunReachableNames, forwardedResourceKey, observedStateRead, validateObservedStateDeclarations, } from "./validate-observed-state.js";
 import { computeSuggestKind } from "./kind-suggest.js";
 import { visitManifest } from "./manifest-visitor.js";
 import { declaringModuleScope, moduleAliasScope } from "./module-alias-scope.js";
@@ -47,13 +47,15 @@ import { celTypeSatisfiesJsonSchema, checkSchemaCompatibility, navigateSchemaToE
 import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity, DiagnosticTag, } from "./types.js";
 import { extractAccessChains, } from "./validate-cel-context.js";
-import { celEvalModeAt, celEvalSites, mergeCelEvalSites, NO_CEL_EVAL_SITES, } from "./eval-paths.js";
+import { celEvalModeAt, celEvalSites, implicitEvalSites, mergeCelEvalSites, NO_CEL_EVAL_SITES, } from "./eval-paths.js";
 import { BINDINGS_ANNOTATION, findBindingSites, resolveBindingOrder, } from "./cel-bindings.js";
 import { CEL_RESERVED_WORDS, checkName } from "./identifier-name.js";
 import { validateIdentifierNames } from "./validate-identifier-names.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
 import { validateModuleArtifact } from "./validate-module-artifact.js";
+import { validateNativeEntries } from "./validate-native-entries.js";
+import { validateSourceEntries } from "./validate-source-entries.js";
 import { validateIncludePlacement } from "./validate-include-placement.js";
 import { validateModuleMetadata } from "./validate-module-metadata.js";
 import { validateRequires } from "./validate-requires.js";
@@ -66,8 +68,11 @@ import { kindSatisfies, validateReferences } from "./validate-references.js";
 import { validateReferenceForms } from "./validate-reference-forms.js";
 import { isInjectedDeclaration } from "./resource-input.js";
 import { validateResourceInputs } from "./validate-resource-inputs.js";
-import { validateTemplateDispatch } from "./validate-template-dispatch.js";
+import { validateExports } from "./validate-exports.js";
+import { validateTemplateBody } from "./validate-template-body.js";
 import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
+import { validateScopedNameReach } from "./validate-scope-reach.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 import { readStepSlot } from "./step-slot.js";
 const SELF_PREFIX = "Self.";
@@ -276,7 +281,7 @@ function validateStepInvokeReferences(allManifests, defs, aliases) {
         const meta = r.metadata;
         if (typeof meta?.name !== "string" || REF_VALIDATION_SKIP_KINDS.has(r.kind))
             continue;
-        if (meta.forwardedExport === true) {
+        if (isForwardedDeclaration(r)) {
             if (typeof meta.module === "string")
                 loadedModules.add(meta.module);
             continue;
@@ -342,7 +347,7 @@ function validateStepInvokeReferences(allManifests, defs, aliases) {
         const meta = m.metadata;
         if (typeof meta?.name !== "string" ||
             REF_VALIDATION_SKIP_KINDS.has(m.kind) ||
-            meta.forwardedExport === true)
+            isForwardedDeclaration(m))
             continue;
         const def = defs.resolve(aliases.resolveKind(m.kind) ?? m.kind);
         const defSchema = def?.schema;
@@ -1301,6 +1306,11 @@ export class StaticAnalyzer {
             // would otherwise fail on a consumer's machine — or, for a mistyped platform
             // axis, silently offer one platform's binary to every host.
             diagnostics.push(...validateModuleArtifact(allManifests));
+            // The module doc's `native:` block: each rule decides whether a platform's
+            // file can ever match a host, or whether two layers would write one path.
+            diagnostics.push(...validateNativeEntries(allManifests, rootModules));
+            // The module doc's `sources:` block: where each staged file comes from.
+            diagnostics.push(...validateSourceEntries(allManifests, rootModules));
             // The descriptive `metadata:` surface. Nothing in the kernel branches on
             // these fields, which is precisely why they need a check: a mistyped one
             // has no runtime failure mode that would ever surface it.
@@ -1551,9 +1561,8 @@ export class StaticAnalyzer {
             // `kind`/CEL are authored in that module's scope (e.g. `Self.X` → that module, not the
             // consumer). Re-validating against the consumer's scope yields false UNDEFINED_KIND /
             // scope-mismatch errors, so skip — they participate here only as resolution targets.
-            if (m.metadata?.forwardedExport === true) {
+            if (isForwardedDeclaration(m))
                 continue;
-            }
             // A kind-only stand-in for a `resources:` entry is a DECLARATION, not an
             // instantiation: its kind is routinely an abstract and its configuration
             // is the importer's to supply, so validating it here would report a
@@ -1746,12 +1755,37 @@ export class StaticAnalyzer {
                 // is caught here rather than on the one input that selects it.
                 const valueSchemaIssues = collectValueSchemaIssues(m, schema, allManifests);
                 const issues = [...ajvIssues, ...valueSchemaIssues];
+                // WHY A FIELD THIS KIND EXISTS TO SUPPLY IS STILL REQUIRED OF ITS
+                // CONSUMER. A child that `extends` and declares no `base:` is authored
+                // against merge(parent, own), so the parent's `required` stays on the
+                // CHILD's surface — and a kind written to wire that field internally
+                // then demands it from the consumer anyway. The `base:` mapping is what
+                // narrows (with it the surface is the child's own schema alone), and
+                // nothing in "is missing required property" points there, which is what
+                // turns one mistake into a three-step dead end.
+                //
+                // Matched against names DERIVED from the parent, never by parsing the
+                // message: which fields are inherited is a fact about the definition,
+                // and a check that reads a validator's prose breaks when the prose does.
+                const inheritedRequired = inheritedRequiredFields(definition, (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k));
+                const parentKind = definition?.extends;
                 for (const issue of issues) {
+                    // Keyed on the STRUCTURED failure, never on the sentence: the field
+                    // names are derived from the parent, and matching them against the
+                    // validator's prose would break when the prose changes and mis-fire on
+                    // any other issue quoting the same name (an `additionalProperties`
+                    // rejection, an `enum` listing).
+                    const inherited = issue.keyword === "required" && issue.missingProperty !== undefined
+                        ? inheritedRequired.filter((f) => f === issue.missingProperty)
+                        : [];
+                    const hint = inherited.length > 0 && parentKind
+                        ? ` — ${inherited.map((f) => `'${f}'`).join(", ")} ${inherited.length > 1 ? "come" : "comes"} from '${parentKind}', which this kind extends without a 'base:' mapping, so the parent's required fields stay on this kind's author surface. Add 'base:' to set them internally; that also narrows the surface to this kind's own schema.`
+                        : "";
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "SCHEMA_VIOLATION",
                         source: SOURCE,
-                        message: `${m.kind}/${resource.name}: ${issue.message}`,
+                        message: `${m.kind}/${resource.name}: ${issue.message}${hint}`,
                         data: { resource, filePath, path: issue.path },
                     });
                 }
@@ -2116,8 +2150,14 @@ export class StaticAnalyzer {
                 }
                 // The non-eval-field check only applies to runtime resource instances:
                 // structural / templating kinds (capability `Telo.Template`, or no
-                // definition) carry CEL the kernel evaluates by other rules.
-                const capability = e.definition?.capability;
+                // definition) carry CEL the kernel evaluates by other rules. The
+                // capability is INHERITED along `extends` — an inheritance kind
+                // writes none of its own — and reading the declared one left the
+                // rule off for every such kind, and its expressions untyped.
+                const resolveDef = (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k);
+                const capability = e.definition
+                    ? inheritedCapability(e.definition, resolveDef)
+                    : undefined;
                 celRuleApplies =
                     !!e.definition?.schema && capability !== undefined && capability !== "Telo.Template";
                 if (celRuleApplies) {
@@ -2129,12 +2169,14 @@ export class StaticAnalyzer {
                     // the own schema here reported `CEL_IN_NON_EVAL_FIELD` for an
                     // expression the runtime evaluates correctly, which is the two halves
                     // disagreeing about what the manifest means.
-                    const ownSchema = effectiveAuthorSchema(e.definition, (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k));
+                    const ownSchema = effectiveAuthorSchema(e.definition, resolveDef);
                     const capabilityDef = capability ? defs.resolve(capability) : undefined;
                     // A `Telo.Provider`'s fields are implicitly compile-eval — the
                     // capability abstract carries the root annotation — so its reads are
-                    // covered here without the provider restating anything.
-                    celSites = mergeCelEvalSites(celEvalSites(ownSchema), celEvalSites(capabilityDef?.schema));
+                    // covered here without the provider restating anything. A base-form
+                    // child's own fields are too (`implicitEvalSites`): `base:` reads
+                    // them once at create().
+                    celSites = mergeCelEvalSites(celEvalSites(ownSchema), celEvalSites(capabilityDef?.schema), implicitEvalSites(e.definition));
                 }
                 else {
                     celSites = NO_CEL_EVAL_SITES;
@@ -2175,8 +2217,16 @@ export class StaticAnalyzer {
                             continue;
                         // An import's exported instance is indexed under `<Alias>.<name>`,
                         // the two-level shape it publishes under, so a cross-module read
-                        // is checked exactly like a local one.
-                        const reported = observedState.get(read.alias ? `${read.alias}.${read.name}` : read.name);
+                        // is checked exactly like a local one. A bare name read inside a
+                        // dependency's own manifest names that dependency's resource.
+                        const readerModule = isForwardedDeclaration(m)
+                            ? m.metadata?.module
+                            : undefined;
+                        const reported = observedState.get(read.alias
+                            ? `${read.alias}.${read.name}`
+                            : readerModule !== undefined
+                                ? forwardedResourceKey(readerModule, read.name)
+                                : read.name);
                         if (celRuleApplies && celEvalModeAt(celSites, path) === "compile") {
                             diagnostics.push({
                                 severity: DiagnosticSeverity.Error,
@@ -2403,12 +2453,18 @@ export class StaticAnalyzer {
         diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv, aliasesByModule, rootModules, libraryManifests));
         // Warn about declared variables / secrets / ports that no CEL references.
         diagnostics.push(...validateUnusedDeclarations(allManifests, this.celEnv));
-        // A `!ref` at a definition's dispatch slot must name a sibling `resources:`
-        // entry — the slot no reference pass reaches, so the tag would otherwise
-        // advertise a resolution nothing performs.
-        diagnostics.push(...validateTemplateDispatch(allManifests, rootModules));
+        // A template body's reference surface — its entry names, its dispatch slots
+        // and the ref slots inside each entry — which no reference pass reaches,
+        // since a `Telo.Definition` is in both skip sets.
+        diagnostics.push(...validateTemplateBody(allManifests, defs, aliases, aliasesByModule, rootModules));
+        // A library's export list, resolved against what it declares — otherwise a
+        // listed name that exists nowhere fails in the consumer's file.
+        diagnostics.push(...validateExports(allManifests, defs, aliases, rootModules));
         // A library's declared resource inputs, and every import that supplies them.
         diagnostics.push(...validateResourceInputs(allManifests, defs, aliases, rootModules, (supplied, required, isDeclaration) => kindSatisfies(supplied, required, defs, isDeclaration)));
+        // An inline declaration referencing a name declared by a scope it was
+        // written inside but is created outside of.
+        diagnostics.push(...validateScopedNameReach(allManifests, defs, aliases, aliasesByModule, rootModules, (expr) => celAccessChains(this.celEnv, expr)));
         // Reroute diagnostics on synthetic (inline-extracted) resources back to
         // the chain root so position-index lookups land on the parent doc.
         return rewriteSyntheticOrigins(suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles), allManifests);

package/dist/artifact-axes.d.ts

@@ -0,0 +1,14 @@
+/** The selector platform axes, in canonical order. Closed as a set of axis
+ *  names; the set of values stays open. */
+export declare const PLATFORM_AXES: readonly ["os", "arch", "libc", "abi"];
+export type PlatformAxis = (typeof PLATFORM_AXES)[number];
+/** A form an axis value must take beyond the shared token grammar. */
+export interface AxisValueForm {
+    readonly pattern: RegExp;
+    /** The form as a reader writes it, e.g. `<family>-<version>`. */
+    readonly form: string;
+    readonly examples: readonly string[];
+}
+/** The axes whose values carry a form of their own. */
+export declare const AXIS_VALUE_FORMS: Readonly<Partial<Record<PlatformAxis, AxisValueForm>>>;
+//# sourceMappingURL=artifact-axes.d.ts.map

package/dist/artifact-axes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-axes.d.ts","sourceRoot":"","sources":["../src/artifact-axes.ts"],"names":[],"mappings":"AAEA;2CAC2C;AAC3C,eAAO,MAAM,aAAa,wCAAyC,CAAC;AAEpE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAMnF,CAAC"}

package/dist/artifact-axes.js

@@ -0,0 +1,12 @@
+// GENERATED by scripts/generate-artifact-axes.mjs from analyzer/artifact-axes/axes.json — do not edit.
+/** The selector platform axes, in canonical order. Closed as a set of axis
+ *  names; the set of values stays open. */
+export const PLATFORM_AXES = ["os", "arch", "libc", "abi"];
+/** The axes whose values carry a form of their own. */
+export const AXIS_VALUE_FORMS = {
+    abi: {
+        pattern: new RegExp("^[a-z][a-z0-9_]*-[0-9]+(\\.[0-9]+)*$"),
+        form: "<family>-<version>",
+        examples: ["node-137", "telo-2"],
+    },
+};

package/dist/artifact-layer-index.d.ts

@@ -30,7 +30,7 @@
 import { type ArtifactSelector, type LayerRole, type PlatformTarget } from "./artifact-selector.js";
 export interface ArtifactLayer {
     role: LayerRole;
-    /** Present on the code-bearing roles (`controller`, `library`) only. */
+    /** Present on the selector-keyed roles (`controller`, `library`, `native`) only. */
     selector?: ArtifactSelector;
     /** OCI blob digest — addresses the layer and verifies the transfer. */
     blob: string;
@@ -48,7 +48,7 @@ export declare class LayerIndexError extends Error {
  */
 export declare function parseLayerIndex(value: unknown, describe?: string): ArtifactLayer[];
 /** The singleton layer for a role, or undefined when the artifact has none. */
-export declare function singletonLayer(layers: readonly ArtifactLayer[], role: Exclude<LayerRole, "controller" | "library">): ArtifactLayer | undefined;
+export declare function singletonLayer(layers: readonly ArtifactLayer[], role: Exclude<LayerRole, "controller" | "library" | "native">): ArtifactLayer | undefined;
 /** The layer of one code role carrying exactly `selector`, or undefined.
  *
  *  By exact key rather than by re-matching a host: the candidate being resolved

package/dist/artifact-layer-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-layer-index.d.ts","sourceRoot":"","sources":["../src/artifact-layer-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAOL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAQhC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,yBAAyB;gBAE1B,MAAM,EAAE,MAAM;CAI3B;AAiBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAW,GAAG,aAAa,EAAE,CAmEpF;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,CAAC,GACjD,aAAa,GAAG,SAAS,CAE3B;AAED;;;;uBAIuB;AACvB,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,CAAC,EAClD,QAAQ,EAAE,gBAAgB,GACzB,aAAa,GAAG,SAAS,CAK3B;AAED;;;6BAG6B;AAC7B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,MAAM,EAAE,cAAc,GACrB,aAAa,EAAE,CAOjB"}
+{"version":3,"file":"artifact-layer-index.d.ts","sourceRoot":"","sources":["../src/artifact-layer-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAQhC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,yBAAyB;gBAE1B,MAAM,EAAE,MAAM;CAI3B;AAiBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAW,GAAG,aAAa,EAAE,CAuEpF;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,CAAC,GAC5D,aAAa,GAAG,SAAS,CAE3B;AAED;;;;uBAIuB;AACvB,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,CAAC,EAClD,QAAQ,EAAE,gBAAgB,GACzB,aAAa,GAAG,SAAS,CAK3B;AAED;;;6BAG6B;AAC7B,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,MAAM,EAAE,cAAc,GACrB,aAAa,EAAE,CAOjB"}

package/dist/artifact-layer-index.js

@@ -27,7 +27,7 @@
  * Browser-safe: `telo check`, the editor and the hub validate an index through
  * this module; only the kernel fetches and extracts.
  */
-import { LAYER_ROLES, isLayerRole, normalizeSelector, roleCarriesSelector, selectorKey, selectorMatches, } from "./artifact-selector.js";
+import { isLayerRole, normalizeSelector, roleCarriesSelector, selectorKey, selectorMatches, } from "./artifact-selector.js";
 /** OCI content digest: `sha256:` + 64 lowercase hex. */
 const BLOB_DIGEST = /^sha256:[0-9a-f]{64}$/;
 /** Telo content digest: `sha256-` + unpadded base64url of 32 bytes. */
@@ -70,9 +70,11 @@ export function parseLayerIndex(value, describe = "layers") {
         }
         const entry = raw;
         if (typeof entry.role !== "string" || entry.role === "") {
-            throw new LayerIndexError(`${where}: role is required and must be one of ${LAYER_ROLES.map((r) => `'${r}'`).join(", ")}; ` +
+            throw new LayerIndexError(`${where}: role is required and must be a non-empty string; ` +
                 `got ${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`);
         }
+        const blob = digest("blob", entry.blob, where);
+        const integrity = digest("integrity", entry.integrity, where);
         // A role this runtime does not know is SKIPPED, never rejected. Roles are
         // added over time, and a runtime that cannot name one cannot need it — while
         // throwing would make the whole manifest unreadable, so a module gaining a
@@ -88,6 +90,9 @@ export function parseLayerIndex(value, describe = "layers") {
                 throw new LayerIndexError(`${where}: a ${role} layer must declare a selector.`);
             }
             selector = normalizeSelector(entry.selector, where);
+            // An unknown axis skips the entry as an unknown role does (spec §3.1).
+            if (selector === undefined)
+                return;
             // Scoped by role: a module's `js` controller layer and its `js` library
             // layer are different layers with the same selector, and only a collision
             // *within* one role means two layers claim one address.
@@ -110,8 +115,8 @@ export function parseLayerIndex(value, describe = "layers") {
         layers.push({
             role,
             ...(selector ? { selector } : {}),
-            blob: digest("blob", entry.blob, where),
-            integrity: digest("integrity", entry.integrity, where),
+            blob,
+            integrity,
         });
     });
     return layers;

package/dist/artifact-selector.d.ts

@@ -3,7 +3,8 @@
  * controller candidate is chosen by, and the key a controller layer of a module
  * artifact is stored under.
  *
- * A selector is `format` plus the optional platform axes `os` / `arch` / `libc`.
+ * A selector is `format` plus the optional platform axes, whose vocabulary is
+ * data (`analyzer/artifact-axes/axes.json`, generated into `PLATFORM_AXES`).
  * Matching is one rule, applied per axis: an axis the selector omits accepts
  * anything, an axis it states must be equal. That is what lets a `js` controller
  * be platform-neutral and a `napi` controller be pinned to one triple, with no
@@ -24,9 +25,11 @@
  * canonical OCI/GOOS names at the kernel boundary, since these values are
  * published into OCI descriptors.
  */
-/** The role a layer plays in a module artifact. `controller` and `library` layers
- *  carry a selector; `assets` and `common` are singletons and carry none. */
-export type LayerRole = "controller" | "library" | "assets" | "common";
+import { PLATFORM_AXES, type PlatformAxis } from "./artifact-axes.js";
+/** The role a layer plays in a module artifact. `controller`, `library` and
+ *  `native` layers carry a selector; `assets` and `common` are singletons and
+ *  carry none. */
+export type LayerRole = "controller" | "library" | "native" | "assets" | "common";
 export declare const LAYER_ROLES: readonly LayerRole[];
 export declare function isLayerRole(value: unknown): value is LayerRole;
 /** The roles that hold executable code, and are therefore per format rather than
@@ -36,39 +39,41 @@ export declare function isLayerRole(value: unknown): value is LayerRole;
  *  A singleton would be wrong the moment a second runtime ships. */
 export declare const CODE_LAYER_ROLES: readonly LayerRole[];
 export declare function roleCarriesSelector(role: LayerRole): boolean;
-/** The platform axes, in canonical order. Not a closed vocabulary of *values* —
- *  new architectures appear without a Telo release — only of axis names. */
-export declare const PLATFORM_AXES: readonly ["os", "arch", "libc"];
-export type PlatformAxis = (typeof PLATFORM_AXES)[number];
-export interface ArtifactSelector {
+export { PLATFORM_AXES, type PlatformAxis };
+export interface ArtifactSelector extends Partial<Record<PlatformAxis, string>> {
     /** Bundled controller format: the PURL name segment (`js`, `napi`, `wasm`, …). */
     format: string;
-    os?: string;
-    arch?: string;
-    libc?: string;
 }
 /** What a selector is matched against: the host the kernel runs on, or the
- *  target `telo install --platform` is warming a cache for. An axis left
- *  undetermined (a host whose libc cannot be detected) matches no selector that
- *  constrains it — refusing to load is the safe direction for a native binary. */
-export interface PlatformTarget {
+ *  target `telo install` is warming a cache for. An axis left undetermined (a
+ *  host whose libc cannot be detected) matches no selector that constrains it —
+ *  refusing to load is the safe direction for a native binary. */
+export interface PlatformTarget extends Partial<Record<PlatformAxis, string>> {
     format?: string;
-    os?: string;
-    arch?: string;
-    libc?: string;
 }
 export declare class ArtifactSelectorError extends Error {
     readonly code = "INVALID_ARTIFACT_SELECTOR";
     constructor(detail: string);
 }
+/** Validate and normalize one selector value: the shared token grammar, plus the
+ *  axis's own value form where the vocabulary declares one. */
+export declare function normalizeAxisValue(axis: string, raw: unknown, describe: string): string;
 /**
  * Build a selector from a controller candidate's format and qualifier map.
  * Qualifier keys other than the platform axes are ignored — `path` and the
  * sibling list live in the same map and are not part of the selector.
  */
 export declare function selectorFromQualifiers(format: unknown, qualifiers: Readonly<Record<string, unknown>> | undefined, describe?: string): ArtifactSelector;
-/** Validate and normalize a selector read off a published layer index. */
-export declare function normalizeSelector(value: unknown, describe?: string): ArtifactSelector;
+/**
+ * Validate and normalize a selector read off a published layer index.
+ *
+ * Returns undefined when the selector carries an axis this runtime does not
+ * know: the layer is for a newer runtime, and the caller skips it whole. The
+ * unknown axis is never dropped — two layers differing only in it would then
+ * claim one address. The known axes are still validated, since their grammar
+ * does not change with the axis set.
+ */
+export declare function normalizeSelector(value: unknown, describe?: string): ArtifactSelector | undefined;
 /**
  * The canonical stable key for a selector: sorted `axis=value` pairs joined by
  * `;`. Used to group entry points into layers at publish time and to detect two
@@ -85,4 +90,25 @@ export declare function describeSelector(selector: ArtifactSelector): string;
  * not be handed a `libc=gnu` binary on the assumption it will run.
  */
 export declare function selectorMatches(selector: ArtifactSelector, target: PlatformTarget): boolean;
+/**
+ * The axes `selector` constrains and `target` leaves undetermined, when those
+ * alone keep the two from matching — what a warm skips for want of a value rather
+ * than because the selector is for another platform. `undefined` when the
+ * selector matches, or differs on a determined axis.
+ */
+export declare function undeterminedAxesBlockingMatch(selector: ArtifactSelector, target: PlatformTarget): PlatformAxis[] | undefined;
+/** A selector that no host can match as its author meant it. */
+export interface SelectorContradiction {
+    /** Suffix of the diagnostic code; each surface prefixes its own. */
+    readonly rule: "NAPI_ABI_FORBIDDEN" | "LIBC_OFF_LINUX";
+    readonly axis: PlatformAxis;
+    readonly detail: string;
+}
+/**
+ * The combinations of axes the grammar accepts and no host can mean: an N-API
+ * addon stating a runtime ABI, and a libc on an os that has none. Shared by every
+ * surface that authors a selector — `native:` entries, controller candidates and
+ * `exports.code:` entries — so each reports the same rule under its own prefix.
+ */
+export declare function selectorContradictions(selector: ArtifactSelector): SelectorContradiction[];
 //# sourceMappingURL=artifact-selector.d.ts.map

package/dist/artifact-selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-selector.d.ts","sourceRoot":"","sources":["../src/artifact-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;6EAC6E;AAC7E,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvE,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAkD,CAAC;AAE/F,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;;oEAIoE;AACpE,eAAO,MAAM,gBAAgB,EAAE,SAAS,SAAS,EAA8B,CAAC;AAEhF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAE5D;AAED;4EAC4E;AAC5E,eAAO,MAAM,aAAa,iCAAkC,CAAC;AAE7D,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;kFAGkF;AAClF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,+BAA+B;gBAEhC,MAAM,EAAE,MAAM;CAI3B;AAsBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACzD,QAAQ,SAAwB,GAC/B,gBAAgB,CAUlB;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,SAAmB,GAC1B,gBAAgB,CAelB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAO9D;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAKnE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAQ3F"}
+{"version":3,"file":"artifact-selector.d.ts","sourceRoot":"","sources":["../src/artifact-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAoB,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAExF;;kBAEkB;AAClB,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElF,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAM3C,CAAC;AAEF,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;;oEAIoE;AACpE,eAAO,MAAM,gBAAgB,EAAE,SAAS,SAAS,EAA8B,CAAC;AAOhF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAE5D;AAED,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,CAAC;AAE5C,MAAM,WAAW,gBAAiB,SAAQ,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC7E,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;kEAGkE;AAClE,MAAM,WAAW,cAAe,SAAQ,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,+BAA+B;gBAEhC,MAAM,EAAE,MAAM;CAI3B;AAMD;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAqBvF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EACzD,QAAQ,SAAwB,GAC/B,gBAAgB,CAUlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,SAAmB,GAC1B,gBAAgB,GAAG,SAAS,CAU9B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAO9D;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAKnE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAQ3F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,cAAc,GACrB,YAAY,EAAE,GAAG,SAAS,CAU5B;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAAC;IACvD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,qBAAqB,EAAE,CAqB1F"}

package/dist/artifact-selector.js

@@ -3,7 +3,8 @@
  * controller candidate is chosen by, and the key a controller layer of a module
  * artifact is stored under.
  *
- * A selector is `format` plus the optional platform axes `os` / `arch` / `libc`.
+ * A selector is `format` plus the optional platform axes, whose vocabulary is
+ * data (`analyzer/artifact-axes/axes.json`, generated into `PLATFORM_AXES`).
  * Matching is one rule, applied per axis: an axis the selector omits accepts
  * anything, an axis it states must be equal. That is what lets a `js` controller
  * be platform-neutral and a `napi` controller be pinned to one triple, with no
@@ -24,7 +25,14 @@
  * canonical OCI/GOOS names at the kernel boundary, since these values are
  * published into OCI descriptors.
  */
-export const LAYER_ROLES = ["controller", "library", "assets", "common"];
+import { AXIS_VALUE_FORMS, PLATFORM_AXES } from "./artifact-axes.js";
+export const LAYER_ROLES = [
+    "controller",
+    "library",
+    "native",
+    "assets",
+    "common",
+];
 export function isLayerRole(value) {
     return typeof value === "string" && LAYER_ROLES.includes(value);
 }
@@ -34,12 +42,14 @@ export function isLayerRole(value) {
  *  different files, and a consumer resolves the one its own runtime can import.
  *  A singleton would be wrong the moment a second runtime ships. */
 export const CODE_LAYER_ROLES = ["controller", "library"];
+/** Every role keyed by a selector, one layer per selector: the code roles, plus
+ *  `native` — a platform-specific file the runtime does not import as code,
+ *  declared in the module doc's `native:` block. */
+const SELECTOR_LAYER_ROLES = [...CODE_LAYER_ROLES, "native"];
 export function roleCarriesSelector(role) {
-    return CODE_LAYER_ROLES.includes(role);
+    return SELECTOR_LAYER_ROLES.includes(role);
 }
-/** The platform axes, in canonical order. Not a closed vocabulary of *values* —
- *  new architectures appear without a Telo release — only of axis names. */
-export const PLATFORM_AXES = ["os", "arch", "libc"];
+export { PLATFORM_AXES };
 export class ArtifactSelectorError extends Error {
     code = "INVALID_ARTIFACT_SELECTOR";
     constructor(detail) {
@@ -50,7 +60,9 @@ export class ArtifactSelectorError extends Error {
 /** Canonical token shape for every selector value. Lowercase, so the same
  *  platform written two ways is one layer rather than two. */
 const TOKEN = /^[a-z0-9][a-z0-9_.-]*$/;
-function normalizeToken(axis, raw, describe) {
+/** Validate and normalize one selector value: the shared token grammar, plus the
+ *  axis's own value form where the vocabulary declares one. */
+export function normalizeAxisValue(axis, raw, describe) {
     if (typeof raw !== "string") {
         throw new ArtifactSelectorError(`${describe}: ${axis} must be a string, got ${raw === null ? "null" : typeof raw}.`);
     }
@@ -59,6 +71,11 @@ function normalizeToken(axis, raw, describe) {
         throw new ArtifactSelectorError(`${describe}: ${axis} value '${raw}' is not a canonical token. ` +
             `Use lowercase letters, digits, '.', '-' or '_', starting with a letter or digit.`);
     }
+    const valueForm = AXIS_VALUE_FORMS[axis];
+    if (valueForm && !valueForm.pattern.test(value)) {
+        throw new ArtifactSelectorError(`${describe}: ${axis} value '${raw}' must have the form ${valueForm.form}, ` +
+            `e.g. ${valueForm.examples.map((e) => `'${e}'`).join(" or ")}.`);
+    }
     return value;
 }
 /**
@@ -68,28 +85,33 @@ function normalizeToken(axis, raw, describe) {
  */
 export function selectorFromQualifiers(format, qualifiers, describe = "controller selector") {
     const selector = {
-        format: normalizeToken("format", format, describe),
+        format: normalizeAxisValue("format", format, describe),
     };
     for (const axis of PLATFORM_AXES) {
         const raw = qualifiers?.[axis];
         if (raw === undefined || raw === "")
             continue;
-        selector[axis] = normalizeToken(axis, raw, describe);
+        selector[axis] = normalizeAxisValue(axis, raw, describe);
     }
     return selector;
 }
-/** Validate and normalize a selector read off a published layer index. */
+/**
+ * Validate and normalize a selector read off a published layer index.
+ *
+ * Returns undefined when the selector carries an axis this runtime does not
+ * know: the layer is for a newer runtime, and the caller skips it whole. The
+ * unknown axis is never dropped — two layers differing only in it would then
+ * claim one address. The known axes are still validated, since their grammar
+ * does not change with the axis set.
+ */
 export function normalizeSelector(value, describe = "layer selector") {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new ArtifactSelectorError(`${describe}: expected an object of selector axes.`);
     }
     const record = value;
-    const unknown = Object.keys(record).filter((k) => k !== "format" && !PLATFORM_AXES.includes(k));
-    if (unknown.length > 0) {
-        throw new ArtifactSelectorError(`${describe}: unknown selector ${unknown.length === 1 ? "axis" : "axes"} ` +
-            `${unknown.map((k) => `'${k}'`).join(", ")}. Known axes: format, ${PLATFORM_AXES.join(", ")}.`);
-    }
-    return selectorFromQualifiers(record.format, record, describe);
+    const selector = selectorFromQualifiers(record.format, record, describe);
+    const carriesUnknownAxis = Object.keys(record).some((k) => k !== "format" && !PLATFORM_AXES.includes(k));
+    return carriesUnknownAxis ? undefined : selector;
 }
 /**
  * The canonical stable key for a selector: sorted `axis=value` pairs joined by
@@ -129,3 +151,50 @@ export function selectorMatches(selector, target) {
     }
     return true;
 }
+/**
+ * The axes `selector` constrains and `target` leaves undetermined, when those
+ * alone keep the two from matching — what a warm skips for want of a value rather
+ * than because the selector is for another platform. `undefined` when the
+ * selector matches, or differs on a determined axis.
+ */
+export function undeterminedAxesBlockingMatch(selector, target) {
+    if (target.format !== undefined && selector.format !== target.format)
+        return undefined;
+    const axes = [];
+    for (const axis of PLATFORM_AXES) {
+        const constraint = selector[axis];
+        if (constraint === undefined)
+            continue;
+        if (target[axis] === undefined)
+            axes.push(axis);
+        else if (target[axis] !== constraint)
+            return undefined;
+    }
+    return axes.length > 0 ? axes : undefined;
+}
+/**
+ * The combinations of axes the grammar accepts and no host can mean: an N-API
+ * addon stating a runtime ABI, and a libc on an os that has none. Shared by every
+ * surface that authors a selector — `native:` entries, controller candidates and
+ * `exports.code:` entries — so each reports the same rule under its own prefix.
+ */
+export function selectorContradictions(selector) {
+    const out = [];
+    if (selector.format === "napi" && selector.abi !== undefined) {
+        out.push({
+            rule: "NAPI_ABI_FORBIDDEN",
+            axis: "abi",
+            detail: `an N-API addon is ABI-stable across runtime releases and states no abi — remove ` +
+                `abi ${selector.abi}, which would keep it from loading anywhere else.`,
+        });
+    }
+    if (selector.libc !== undefined && selector.os !== undefined && selector.os !== "linux") {
+        out.push({
+            rule: "LIBC_OFF_LINUX",
+            axis: "libc",
+            detail: `libc is only determined on linux, so a selector for os '${selector.os}' that states ` +
+                `libc ${selector.libc} could never match a host. Remove libc.`,
+        });
+    }
+    return out;
+}

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AA8OvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA+tB/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAkFA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAoSvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EA+pB/C,CAAC"}