@rayspec/spec 1.5.0

package/dist/errors.js

@@ -0,0 +1,165 @@
+/**
+ * SpecError — the closed-code error envelope for the RaySpec config grammar.
+ *
+ * Mirrors the auth-core `ErrorCode`/`ErrorEnvelope` pattern (packages/auth-core/src/errors.ts):
+ * a CLOSED Zod enum of codes + a flat `{ code, message, path? }` envelope. Closed-by-construction
+ * so a fresh session reading a parse failure sees a finite, documented vocabulary — never a free
+ * string. `parseSpec`/`lintSpec` aggregate the FULL list of violations (not the first), so an
+ * author sees every problem in one pass.
+ *
+ * `path` is a JSON path into the spec (dot/bracket notation, e.g. `agents[0].backend`) so a
+ * violation points at the exact offending node. It is absent for whole-document failures
+ * (`yaml_parse_error`, `unsupported_version`) where no in-document path applies.
+ */
+import { z } from 'zod';
+/**
+ * The CLOSED set of spec-error codes. Every parse/lint failure carries exactly one of these.
+ *
+ *  - `yaml_parse_error`       — the raw text is not valid YAML (the `yaml` lib threw).
+ *  - `unsupported_version`    — `version` is missing or not the supported literal ('1.0').
+ *  - `schema_violation`       — a Zod shape failure that is not a pure unknown-key rejection
+ *                               (wrong type, missing required field, bad enum value, …).
+ *  - `unknown_field`          — a `.strict()` unknown-key rejection (fail-closed: any extra key).
+ *  - `dangling_ref`          — a cross-reference points at an id/name that is not declared.
+ *  - `duplicate_name`         — two entries in one section share an id/name.
+ *  - `capability_violation`   — an agent demands a capability its chosen backend lacks
+ *                               (via core `validateSpec`; e.g. native structured output on pi).
+ *  - `invalid_embedded_schema`— an embedded JSON-Schema (tool `parameters`/`outputSchema`,
+ *                               agent `outputSchema.schema`) failed to compile through Ajv2020.
+ *  - `reserved_column_name`   — a store declares a business column whose name collides with a
+ *                               tenancy/GDPR column the table generator injects (`id`,
+ *                               `tenant_id`, `created_at`, `deleted_at`, `retention_days`,
+ *                               `region`) — fail-closed against a shadow/tenancy collision.
+ *  - `reserved_query_keyword` — a store declares a business column whose name is one of the
+ *                               list-query CONTROL keywords (`order`, `after`, `limit`). Those keys
+ *                               steer the declarative `list` route's sorting + keyset pagination, so a
+ *                               column of that name would be silently un-equality-filterable AND would
+ *                               emit a DUPLICATE OpenAPI query parameter (control param + per-column
+ *                               filter param, same name+location) → an invalid OpenAPI 3.1 document.
+ *                               Rename the business column.
+ *  - `frontend_route_collision` — a declared static frontend mount's `route` collides with another
+ *                               mount, with a declared `api[].path`, or with a reserved system prefix
+ *                               (`/v1`, `/health`, `/oidc`) — the static mount would either shadow or be
+ *                               shadowed by that route. Root `/` is exempt (it coexists with `/v1/*` via
+ *                               registration order). Rename the frontend route.
+ *  - `frontend_dir_missing`   — a declared frontend `dir` does not resolve to a readable directory of
+ *                               built assets (surfaced by `doctor`, which checks the filesystem).
+ *  - `fk_cycle`               — the declared stores form a CIRCULAR foreign-key reference (store A
+ *                               references B and B references A, directly or transitively). Such a set is
+ *                               UNORDERABLE: each store's FK ADD needs its parent table to already exist,
+ *                               so no CREATE order satisfies every FK. Rejected fail-closed at config time
+ *                               rather than surfacing as a cryptic `42P01 relation does not exist` at
+ *                               apply. Self-references are EXEMPT (a self-FK applies after its own CREATE).
+ *
+ * PRODUCT-YAML codes — used ONLY by the Product-YAML validation path (`parseProductSpec`,
+ * `product-lint.ts`). They share this closed envelope so a fresh session sees ONE error vocabulary
+ * across both document families; the RaySpec path never emits them.
+ *  - `no_code_in_yaml`        — a code/handler/SQL/shell key or an inline-code string value appears
+ *                               in a Product-YAML doc: implementation belongs in Tier A/B, not
+ *                               in product meaning. The message names what the offending key should be.
+ *  - `provider_native_leak`   — a provider-native wire blob (raw request/response payload) or a
+ *                               provider/model policy field / provider name leaked into the executable
+ *                               `workflows`/`agents` graph (which must stay provider-neutral so it
+ *                               compiles through the workflow bridge). Provider policy is only allowed
+ *                               in `capabilities[].provider_policy` / `deployment_overrides`.
+ *  - `invalid_capability_status` — RESERVED (closed-code discipline). The earlier doc-level
+ *                               rejection of `status:'available'` was retired (the Tier B
+ *                               runtime is wired now); capability WIREDNESS is enforced at the deploy
+ *                               composition (fail-closed `unsupported_spec`), not by the parser.
+ *  - `invalid_contract`       — a `contracts[]` schema uses a key/type outside the closed, declarative
+ *                               JSON-Schema-like vocabulary (no functions/transforms/computed
+ *                               expressions/provider-native shapes).
+ *  - `prompt_execution_claim` — a Product-YAML `workflows`/`agents` graph STRING claims prompt/LLM
+ *                               EXECUTION (`llm call`, `agent call`, `prompt execution`, `execute
+ *                               prompt`). Mirrors the workflow-bridge's `prompt_execution_claim` so a
+ *                               doc that validates here also compiles through the bridge (anti-drift;
+ *                               parity-tested). Prompt/agent execution is a Tier-B runtime concern.
+ *  - `production_execution_claim` — a graph STRING claims production EXECUTION (`production_ready`,
+ *                               `production execution`, `prod runtime`). Mirrors the bridge's
+ *                               `production_execution_claim` (parity-tested): a product doc declares
+ *                               meaning, not that it EXECUTES in production.
+ *  - `invalid_dependency_order` — a workflow step's `depends_on` references a step that is NOT declared
+ *                               before it (a forward/self reference). Declaration-order is required, which
+ *                               structurally forbids dependency CYCLES (a cycle needs a forward edge).
+ *  - `invalid_view`           — a view declaration violates the view semantics (product-views-lint):
+ *                               a source/contract conflation (a source ref that names a
+ *                               contract instead of a store/artifact/capability contract), a read/shape
+ *                               context violation (page fields outside `list` mode, group outside `collect`,
+ *                               …), incomplete param coverage, a shape that does not conform to its declared
+ *                               response contract, a reserved (`__proto__`-class) name, or a pagination law
+ *                               violation. Every mis-declared view construct is rejected — never skipped.
+ *  - `invalid_store`          — a declared product store / store-step declaration violates the store
+ *                               semantics: a store name colliding with a
+ *                               derived collection store, a column name on the graph key denylist (it could
+ *                               never be referenced from a workflow step), a key naming an undeclared or
+ *                               nullable column, a store step targeting an undeclared store, a filter/values
+ *                               column outside the store's declared columns, a write omitting the conflict-
+ *                               key column, or store vocabulary on a non-store step type. Fail-closed.
+ */
+export const SpecErrorCode = z.enum([
+    'yaml_parse_error',
+    'unsupported_version',
+    'schema_violation',
+    'unknown_field',
+    'dangling_ref',
+    'duplicate_name',
+    'capability_violation',
+    'invalid_embedded_schema',
+    'reserved_column_name',
+    'reserved_query_keyword',
+    'frontend_route_collision',
+    'frontend_dir_missing',
+    'fk_cycle',
+    'no_code_in_yaml',
+    'provider_native_leak',
+    'invalid_capability_status',
+    'invalid_contract',
+    'prompt_execution_claim',
+    'production_execution_claim',
+    'invalid_dependency_order',
+    'invalid_view',
+    'invalid_store',
+]);
+/** A single fail-closed spec violation (closed code + message + optional JSON path). */
+export const SpecError = z.object({
+    code: SpecErrorCode,
+    message: z.string(),
+    /** JSON path into the spec document (e.g. `agents[0].backend`); absent for whole-doc failures. */
+    path: z.string().optional(),
+});
+/** Construct a SpecError (path omitted when undefined so the envelope stays minimal). */
+export function specError(code, message, path) {
+    return path !== undefined ? { code, message, path } : { code, message };
+}
+/**
+ * The CLOSED set of NON-FATAL spec-warning codes. A warning flags a documented, deliberately-permitted
+ * interaction the author should be AWARE of — it does NOT fail `doctor`/`plan` (unlike a `SpecError`).
+ * Kept a distinct closed vocabulary from `SpecErrorCode` so a fresh session never confuses "advisory"
+ * with "fail-closed".
+ *
+ *  - `softdelete_fk_restrict` — a `softDelete` store is the TARGET of a `restrict` business-key
+ *                               (`referencesColumn`) foreign key. Soft-deleting such a parent is an
+ *                               `UPDATE(deleted_at)` that does NOT fire the database ON DELETE restrict,
+ *                               so children keep pointing at the tombstoned row — the restrict guarantee
+ *                               only binds on a HARD delete. This is a permitted, documented interaction.
+ *  - `fk_forward_reference`   — a store declares a foreign key onto another store declared LATER in the
+ *                               `stores` array. The product-SQL generator topo-sorts stores so the parent
+ *                               table is created before the child's FK is added, so a forward reference
+ *                               still applies cleanly; this advisory notes only that the declared order
+ *                               relies on that reordering (declaring the parent first makes it explicit).
+ *                               Acyclic by construction — a true cycle is the fail-closed `fk_cycle`
+ *                               error, never a warning.
+ */
+export const SpecWarningCode = z.enum(['softdelete_fk_restrict', 'fk_forward_reference']);
+/** A single NON-FATAL spec warning (closed code + message + optional JSON path). Never fails a parse. */
+export const SpecWarning = z.object({
+    code: SpecWarningCode,
+    message: z.string(),
+    /** JSON path into the spec document (e.g. `stores[0].softDelete`); absent for whole-doc warnings. */
+    path: z.string().optional(),
+});
+/** Construct a SpecWarning (path omitted when undefined so the envelope stays minimal). */
+export function specWarning(code, message, path) {
+    return path !== undefined ? { code, message, path } : { code, message };
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,CAAC;IAClC,kBAAkB;IAClB,qBAAqB;IACrB,kBAAkB;IAClB,eAAe;IACf,cAAc;IACd,gBAAgB;IAChB,sBAAsB;IACtB,yBAAyB;IACzB,sBAAsB;IACtB,wBAAwB;IACxB,0BAA0B;IAC1B,sBAAsB;IACtB,UAAU;IACV,iBAAiB;IACjB,sBAAsB;IACtB,2BAA2B;IAC3B,kBAAkB;IAClB,wBAAwB;IACxB,4BAA4B;IAC5B,0BAA0B;IAC1B,cAAc;IACd,eAAe;CAChB,CAAC,CAAC;AAGH,wFAAwF;AACxF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,kGAAkG;IAClG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAGH,yFAAyF;AACzF,MAAM,UAAU,SAAS,CAAC,IAAmB,EAAE,OAAe,EAAE,IAAa;IAC3E,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,wBAAwB,EAAE,sBAAsB,CAAC,CAAC,CAAC;AAG1F,yGAAyG;AACzG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,qGAAqG;IACrG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAGH,2FAA2F;AAC3F,MAAM,UAAU,WAAW,CAAC,IAAqB,EAAE,OAAe,EAAE,IAAa;IAC/E,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC1E,CAAC"}

package/dist/export.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Export the `RaySpec` grammar as a JSON-Schema (draft-2020-12) object. Every STRICT grammar
+ * object level carries `additionalProperties:false` (the fail-closed shape an Ajv2020 instance
+ * enforces byte-for-byte); the three embedded JSON-Schema slots (tool `parameters`/`outputSchema`,
+ * agent `outputSchema.schema`) are intentionally OPEN records.
+ *
+ * `io: 'input'` is LOAD-BEARING: `z.toJSONSchema` defaults to `io: 'output'`, which marks every
+ * `.default()`ed field REQUIRED — making the exported artifact REJECT a default-omitting minimal
+ * spec (`{version, metadata}`) that `parseSpec` ACCEPTS (the parser fills the defaults). `io:'input'`
+ * exports the PRE-default INPUT shape, so the artifact validates exactly what an author may WRITE —
+ * matching the parser's accept set (the round-trip contract test drives a default-omitting object
+ * through the artifact to lock this).
+ *
+ * `unrepresentable` defaults to `'throw'`; the grammar uses only representable types
+ * (string/literal/enum/array/record/object/boolean/number/discriminatedUnion), all verified to
+ * export, so this never throws for the current grammar.
+ */
+export declare function exportJsonSchema(): Record<string, unknown>;
+/**
+ * Export the `ProductSpec` (Product-YAML) grammar as a JSON-Schema (draft-2020-12) — the SAME
+ * `io:'input'` discipline as `exportJsonSchema` (so a default-omitting minimal product doc validates
+ * against the artifact exactly as `parseProductSpec` accepts it). The Product-YAML `contracts` slot is
+ * an intentionally OPEN record (its closed vocabulary is enforced by product-lint, not this artifact),
+ * mirroring how the RaySpec artifact leaves a tool's `parameters` open. This artifact is kept
+ * fresh by the `gate:spec-schema` drift gate alongside `spec.schema.json` (`packages/spec/product.schema.json`).
+ */
+export declare function exportProductJsonSchema(): Record<string, unknown>;
+/**
+ * Export the ONE canonical schema for the `version:'1.0'` document. A
+ * `version:'1.0'` doc is one of two PROFILES, discriminated by the presence of the `product:` section:
+ * the BACKEND profile (`RaySpec` — the low-level surface AND the internal engine target) or the
+ * PRODUCT profile (`ProductSpec` — the high-level product-meaning surface). This is a hand-composed
+ * `oneOf` over the two existing profile schemas (a `oneOf` with a `product` required/forbidden
+ * discriminant is clearer + diff-reviewable than `z.toJSONSchema` over a top-level union of two strict
+ * objects). It is UNAMBIGUOUS by construction: the backend arm keeps `additionalProperties:false`, so a
+ * `product`-carrying doc CANNOT match it, and the product arm REQUIRES `product` — so exactly one arm
+ * matches. Both arms stay draft-2020-12 + `io:'input'` (defaults-applied-on-parse) and fail-closed
+ * (every strict level keeps `additionalProperties:false`). The dialect `$schema` declaration lives ONLY
+ * at the unified root; the inner profile `$schema` keys are stripped so the artifact is one well-formed
+ * 2020-12 document. Kept fresh by `gate:spec-schema` alongside the two profile views.
+ *
+ * `$defs` HOISTING (the BLOCKER fix): `z.toJSONSchema` factors a reused sub-schema into a ROOT-scoped
+ * `$defs.__schemaN` with document-root-relative `"$ref": "#/$defs/__schemaN"` pointers (the product
+ * profile emits one such def today; the backend profile emits none). A JSON-Pointer `$ref` is ALWAYS
+ * resolved from the DOCUMENT ROOT (`#`), NOT from the `oneOf[n]` object it sits under — so leaving a
+ * profile's `$defs` NESTED under an arm leaves its refs dangling (Ajv2020 raises `can't resolve
+ * reference #/$defs/__schema0 from id #`). This exporter therefore HOISTS every arm's `$defs` up to the
+ * unified ROOT (deleting it from the arm), so the inner `#/$defs/...` refs resolve against the
+ * now-present root `$defs`. A cross-arm `$defs` key collision throws (fail loud, never silently clobber).
+ * The `packages/spec/src/export.test.ts` Ajv2020 compile test is the forcing-function that keeps this
+ * honest (a regression to nested `$defs` turns it red with a MissingRefError).
+ */
+export declare function exportUnifiedJsonSchema(): Record<string, unknown>;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAK1D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwCjE"}

package/dist/export.js

@@ -0,0 +1,121 @@
+/**
+ * JSON-Schema exporter for the RaySpec config grammar.
+ *
+ * The design calls for "Zod + JSON-Schema export". The pinned `zod@4.4.3` ships a native
+ * `z.toJSONSchema` (verified doc-first) so this needs NO new dependency. We export at the
+ * draft-2020-12 dialect — the SAME dialect `packages/platform/src/dispatch.ts` compiles tool
+ * schemas with (`ajv/dist/2020`) — so the runtime exporter and the runtime validator speak one
+ * JSON-Schema language.
+ *
+ * Scope: build the RUNTIME exporter + the round-trip contract test.
+ *
+ * The MINIMAL schema-emit + drift-gate: this exporter is now ALSO the source for a CHECKED-IN
+ * `packages/spec/spec.schema.json` artifact, kept fresh by the structural CI gate `gate:spec-schema`
+ * (`scripts/check-spec-schema.mjs` — re-derives the schema, serializes it through one shared helper, and
+ * byte-compares to the committed file; regenerate with `--write`). The gate only checks FRESHNESS — this
+ * function stays the single source of truth. Generated handler TYPES remain deferred.
+ */
+import { z } from 'zod';
+import { RaySpec } from './grammar.js';
+import { ProductSpec } from './product-grammar.js';
+/**
+ * Export the `RaySpec` grammar as a JSON-Schema (draft-2020-12) object. Every STRICT grammar
+ * object level carries `additionalProperties:false` (the fail-closed shape an Ajv2020 instance
+ * enforces byte-for-byte); the three embedded JSON-Schema slots (tool `parameters`/`outputSchema`,
+ * agent `outputSchema.schema`) are intentionally OPEN records.
+ *
+ * `io: 'input'` is LOAD-BEARING: `z.toJSONSchema` defaults to `io: 'output'`, which marks every
+ * `.default()`ed field REQUIRED — making the exported artifact REJECT a default-omitting minimal
+ * spec (`{version, metadata}`) that `parseSpec` ACCEPTS (the parser fills the defaults). `io:'input'`
+ * exports the PRE-default INPUT shape, so the artifact validates exactly what an author may WRITE —
+ * matching the parser's accept set (the round-trip contract test drives a default-omitting object
+ * through the artifact to lock this).
+ *
+ * `unrepresentable` defaults to `'throw'`; the grammar uses only representable types
+ * (string/literal/enum/array/record/object/boolean/number/discriminatedUnion), all verified to
+ * export, so this never throws for the current grammar.
+ */
+export function exportJsonSchema() {
+    return z.toJSONSchema(RaySpec, {
+        target: 'draft-2020-12',
+        io: 'input',
+    });
+}
+/**
+ * Export the `ProductSpec` (Product-YAML) grammar as a JSON-Schema (draft-2020-12) — the SAME
+ * `io:'input'` discipline as `exportJsonSchema` (so a default-omitting minimal product doc validates
+ * against the artifact exactly as `parseProductSpec` accepts it). The Product-YAML `contracts` slot is
+ * an intentionally OPEN record (its closed vocabulary is enforced by product-lint, not this artifact),
+ * mirroring how the RaySpec artifact leaves a tool's `parameters` open. This artifact is kept
+ * fresh by the `gate:spec-schema` drift gate alongside `spec.schema.json` (`packages/spec/product.schema.json`).
+ */
+export function exportProductJsonSchema() {
+    return z.toJSONSchema(ProductSpec, {
+        target: 'draft-2020-12',
+        io: 'input',
+    });
+}
+/**
+ * Export the ONE canonical schema for the `version:'1.0'` document. A
+ * `version:'1.0'` doc is one of two PROFILES, discriminated by the presence of the `product:` section:
+ * the BACKEND profile (`RaySpec` — the low-level surface AND the internal engine target) or the
+ * PRODUCT profile (`ProductSpec` — the high-level product-meaning surface). This is a hand-composed
+ * `oneOf` over the two existing profile schemas (a `oneOf` with a `product` required/forbidden
+ * discriminant is clearer + diff-reviewable than `z.toJSONSchema` over a top-level union of two strict
+ * objects). It is UNAMBIGUOUS by construction: the backend arm keeps `additionalProperties:false`, so a
+ * `product`-carrying doc CANNOT match it, and the product arm REQUIRES `product` — so exactly one arm
+ * matches. Both arms stay draft-2020-12 + `io:'input'` (defaults-applied-on-parse) and fail-closed
+ * (every strict level keeps `additionalProperties:false`). The dialect `$schema` declaration lives ONLY
+ * at the unified root; the inner profile `$schema` keys are stripped so the artifact is one well-formed
+ * 2020-12 document. Kept fresh by `gate:spec-schema` alongside the two profile views.
+ *
+ * `$defs` HOISTING (the BLOCKER fix): `z.toJSONSchema` factors a reused sub-schema into a ROOT-scoped
+ * `$defs.__schemaN` with document-root-relative `"$ref": "#/$defs/__schemaN"` pointers (the product
+ * profile emits one such def today; the backend profile emits none). A JSON-Pointer `$ref` is ALWAYS
+ * resolved from the DOCUMENT ROOT (`#`), NOT from the `oneOf[n]` object it sits under — so leaving a
+ * profile's `$defs` NESTED under an arm leaves its refs dangling (Ajv2020 raises `can't resolve
+ * reference #/$defs/__schema0 from id #`). This exporter therefore HOISTS every arm's `$defs` up to the
+ * unified ROOT (deleting it from the arm), so the inner `#/$defs/...` refs resolve against the
+ * now-present root `$defs`. A cross-arm `$defs` key collision throws (fail loud, never silently clobber).
+ * The `packages/spec/src/export.test.ts` Ajv2020 compile test is the forcing-function that keeps this
+ * honest (a regression to nested `$defs` turns it red with a MissingRefError).
+ */
+export function exportUnifiedJsonSchema() {
+    const strip$schema = (s) => {
+        const { $schema: _dialect, ...rest } = s;
+        return rest;
+    };
+    // The two profile arms, each stripped of its inner dialect `$schema` (the unified root carries it).
+    const arms = [strip$schema(exportJsonSchema()), strip$schema(exportProductJsonSchema())];
+    // Hoist each arm's ROOT-scoped `$defs` up to the unified root, deleting it from the arm (see the
+    // `$defs` HOISTING note above). A JSON-Pointer `$ref` resolves from the DOCUMENT ROOT, NOT the
+    // `oneOf[n]` object it sits under, so a profile's `#/$defs/...` refs would DANGLE if its `$defs`
+    // stayed nested. Merge under one root `$defs`; a cross-arm key collision throws (fail loud).
+    const rootDefs = {};
+    for (const arm of arms) {
+        const armDefs = arm.$defs;
+        if (!armDefs)
+            continue;
+        for (const [key, def] of Object.entries(armDefs)) {
+            if (key in rootDefs) {
+                throw new Error(`exportUnifiedJsonSchema: $defs key collision '${key}' across the backend/product profiles — ` +
+                    'namespace the arm defs before hoisting (both arms cannot share a root-scoped def name).');
+            }
+            rootDefs[key] = def;
+        }
+        delete arm.$defs;
+    }
+    const unified = {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        title: 'RaySpec spec (version 1.0) — one language, two profiles (backend | product)',
+        description: "A version:'1.0' document is one of two profiles, discriminated by the presence of the " +
+            '`product:` section: the backend profile (low-level RaySpec, the internal engine target) ' +
+            'or the product profile (high-level product meaning, lowered to the backend profile at deploy).',
+        oneOf: arms,
+    };
+    // Only emit `$defs` if any arm contributed one (keeps the artifact minimal when no arm factors a def).
+    if (Object.keys(rootDefs).length > 0)
+        unified.$defs = rootDefs;
+    return unified;
+}
+//# sourceMappingURL=export.js.map

package/dist/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE;QAC7B,MAAM,EAAE,eAAe;QACvB,EAAE,EAAE,OAAO;KACZ,CAA4B,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,CAAC,CAAC,YAAY,CAAC,WAAW,EAAE;QACjC,MAAM,EAAE,eAAe;QACvB,EAAE,EAAE,OAAO;KACZ,CAA4B,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,YAAY,GAAG,CAAC,CAA0B,EAA2B,EAAE;QAC3E,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,oGAAoG;IACpG,MAAM,IAAI,GAAG,CAAC,YAAY,CAAC,gBAAgB,EAAE,CAAC,EAAE,YAAY,CAAC,uBAAuB,EAAE,CAAC,CAAC,CAAC;IAEzF,iGAAiG;IACjG,+FAA+F;IAC/F,iGAAiG;IACjG,6FAA6F;IAC7F,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,OAAO,GAAI,GAA2C,CAAC,KAAK,CAAC;QACnE,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACjD,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;gBACpB,MAAM,IAAI,KAAK,CACb,iDAAiD,GAAG,0CAA0C;oBAC5F,yFAAyF,CAC5F,CAAC;YACJ,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QACtB,CAAC;QACD,OAAQ,GAA2B,CAAC,KAAK,CAAC;IAC5C,CAAC;IAED,MAAM,OAAO,GAA4B;QACvC,OAAO,EAAE,8CAA8C;QACvD,KAAK,EAAE,6EAA6E;QACpF,WAAW,EACT,wFAAwF;YACxF,0FAA0F;YAC1F,gGAAgG;QAClG,KAAK,EAAE,IAAI;KACZ,CAAC;IACF,uGAAuG;IACvG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC;IAC/D,OAAO,OAAO,CAAC;AACjB,CAAC"}