@rayspec/spec 1.5.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Socialinsiders UG (haftungsbeschränkt)
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/dist/brace-params.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `{param}` extraction/rewriting for declared route paths — a single forward character scan, with NO
+ * regular expression, so the work is strictly linear in the input length for EVERY input (no
+ * backtracking, no quantifier, and no length cap on the param name).
+ *
+ * The two helpers are the shared, byte-exact equivalent of iterating the pattern `\{([^}/]+)\}`
+ * globally over a path — the form the route/view emitters and the Hono-path rewrite historically used.
+ * They preserve that pattern's EXACT semantics for every input, including its edges:
+ *   - `{}`        → NOT a param (the run needs at least one character);
+ *   - `{a/b}`     → NOT a param (a `/` ends the run before a `}` can close it);
+ *   - `{a}{b}`    → two params (`a`, `b`);
+ *   - `{a{b}`     → one param whose name is `a{b` (an inner `{` is an ordinary name character);
+ *   - `{unclosed` → no param (no closing `}`);
+ *   - names of ANY length (1, 128, 129, thousands) and ANY code points (ASCII, emoji, astral).
+ *
+ * A `{param}` here is `{`, then a maximal run of ≥1 characters that are neither `}` nor `/`, then a
+ * `}`. Because the run stops at the first `}` or `/`, a match exists at a `{` iff that first stopping
+ * character is a `}` (a `/` or end-of-input means no match at this `{`); on a non-match the scan
+ * advances by a single character, exactly as a global regex retries at the next position.
+ */
+/**
+ * Extract the `{param}` names from a declared route path in order (e.g. `/meetings/{id}/x` → `['id']`).
+ * Byte-exact equivalent of collecting capture group 1 of a global `\{([^}/]+)\}` scan.
+ */
+export declare function braceParamNames(path: string): string[];
+/**
+ * Rewrite each `{param}` in a declared route path via `replace(name)`, copying every other character
+ * verbatim (e.g. `toHonoPath` uses `(name) => ':' + name`; the operationId slug uses
+ * `(name) => '_by_' + name + '_'`). Byte-exact equivalent of `path.replace(/\{([^}/]+)\}/g, cb)`.
+ */
+export declare function rewriteBraceParams(path: string, replace: (name: string) => string): string;
+//# sourceMappingURL=brace-params.d.ts.map

package/dist/brace-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brace-params.d.ts","sourceRoot":"","sources":["../src/brace-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAmBH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAqB1F"}

package/dist/brace-params.js

@@ -0,0 +1,89 @@
+/**
+ * `{param}` extraction/rewriting for declared route paths — a single forward character scan, with NO
+ * regular expression, so the work is strictly linear in the input length for EVERY input (no
+ * backtracking, no quantifier, and no length cap on the param name).
+ *
+ * The two helpers are the shared, byte-exact equivalent of iterating the pattern `\{([^}/]+)\}`
+ * globally over a path — the form the route/view emitters and the Hono-path rewrite historically used.
+ * They preserve that pattern's EXACT semantics for every input, including its edges:
+ *   - `{}`        → NOT a param (the run needs at least one character);
+ *   - `{a/b}`     → NOT a param (a `/` ends the run before a `}` can close it);
+ *   - `{a}{b}`    → two params (`a`, `b`);
+ *   - `{a{b}`     → one param whose name is `a{b` (an inner `{` is an ordinary name character);
+ *   - `{unclosed` → no param (no closing `}`);
+ *   - names of ANY length (1, 128, 129, thousands) and ANY code points (ASCII, emoji, astral).
+ *
+ * A `{param}` here is `{`, then a maximal run of ≥1 characters that are neither `}` nor `/`, then a
+ * `}`. Because the run stops at the first `}` or `/`, a match exists at a `{` iff that first stopping
+ * character is a `}` (a `/` or end-of-input means no match at this `{`); on a non-match the scan
+ * advances by a single character, exactly as a global regex retries at the next position.
+ */
+/**
+ * Locate the `{param}` span starting at `open` (where `path[open] === '{'`). Returns the closing-brace
+ * index and the param name when a valid `{name}` (name length ≥ 1, first stopping char is `}`) begins
+ * there, or `undefined` when this `{` does not open a param. Shared by both public helpers so the
+ * extract and rewrite paths can never drift.
+ */
+function braceSpanAt(path, open) {
+    // Walk to the first `}` or `/` after the `{` (or the end of the string).
+    let j = open + 1;
+    while (j < path.length && path[j] !== '}' && path[j] !== '/')
+        j++;
+    // A param exists iff that stopping char is a `}` AND at least one name char preceded it.
+    if (j < path.length && path[j] === '}' && j > open + 1) {
+        return { close: j, name: path.slice(open + 1, j) };
+    }
+    return undefined;
+}
+/**
+ * Extract the `{param}` names from a declared route path in order (e.g. `/meetings/{id}/x` → `['id']`).
+ * Byte-exact equivalent of collecting capture group 1 of a global `\{([^}/]+)\}` scan.
+ */
+export function braceParamNames(path) {
+    const out = [];
+    let i = 0;
+    while (i < path.length) {
+        if (path[i] !== '{') {
+            i++;
+            continue;
+        }
+        const span = braceSpanAt(path, i);
+        if (span) {
+            out.push(span.name);
+            i = span.close + 1; // continue after the closing `}`
+        }
+        else {
+            i++; // not a param — advance one char and retry (a global regex does the same)
+        }
+    }
+    return out;
+}
+/**
+ * Rewrite each `{param}` in a declared route path via `replace(name)`, copying every other character
+ * verbatim (e.g. `toHonoPath` uses `(name) => ':' + name`; the operationId slug uses
+ * `(name) => '_by_' + name + '_'`). Byte-exact equivalent of `path.replace(/\{([^}/]+)\}/g, cb)`.
+ */
+export function rewriteBraceParams(path, replace) {
+    let out = '';
+    let last = 0; // start of the not-yet-copied verbatim region
+    let i = 0;
+    while (i < path.length) {
+        if (path[i] !== '{') {
+            i++;
+            continue;
+        }
+        const span = braceSpanAt(path, i);
+        if (span) {
+            out += path.slice(last, i); // verbatim text before this `{param}`
+            out += replace(span.name);
+            i = span.close + 1;
+            last = i;
+        }
+        else {
+            i++;
+        }
+    }
+    out += path.slice(last); // trailing verbatim text
+    return out;
+}
+//# sourceMappingURL=brace-params.js.map

package/dist/brace-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brace-params.js","sourceRoot":"","sources":["../src/brace-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY;IAC7C,yEAAyE;IACzE,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;IACjB,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;QAAE,CAAC,EAAE,CAAC;IAClE,yFAAyF;IACzF,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACrD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACpB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAClC,IAAI,IAAI,EAAE,CAAC;YACT,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,iCAAiC;QACvD,CAAC;aAAM,CAAC;YACN,CAAC,EAAE,CAAC,CAAC,0EAA0E;QACjF,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAiC;IAChF,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,8CAA8C;IAC5D,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACpB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAClC,IAAI,IAAI,EAAE,CAAC;YACT,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,sCAAsC;YAClE,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;YACnB,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;aAAM,CAAC;YACN,CAAC,EAAE,CAAC;QACN,CAAC;IACH,CAAC;IACD,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,yBAAyB;IAClD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/detect.d.ts

@@ -0,0 +1,44 @@
+import type { SpecError } from './errors.js';
+import { type RaySpec } from './grammar.js';
+import type { ProductSpec } from './product-grammar.js';
+/** Which document PROFILE a raw YAML string is. `unknown` = not parseable to an object root. */
+export type SpecKind = 'rayspec' | 'product' | 'unknown';
+/**
+ * Detect the document profile. A `version:'1.0'` doc is the PRODUCT profile iff it carries a top-level
+ * `product:` section, else the BACKEND profile. Any other object root (a version-less doc, or one with
+ * an unsupported version) → the backend parser, which fails closed there with a clean
+ * `unsupported_version`. Fail-closed: a non-object / unparseable root → `unknown`.
+ */
+export declare function detectSpecKind(rawYamlText: string): SpecKind;
+/** A validate-only envelope for callers (doctor/plan/deploy) that only need the fail-closed verdict. */
+export interface ValidateResult {
+    readonly ok: boolean;
+    readonly kind: SpecKind;
+    readonly errors: SpecError[];
+}
+/**
+ * Validate a raw spec of EITHER family, collapsing to `{ ok, kind, errors }`. Routes to the correct
+ * parser by `detectSpecKind`. An `unknown` root is routed to `parseSpec` so its existing
+ * `unsupported_version`/`yaml_parse_error` message is preserved (no behavior change for RaySpec).
+ */
+export declare function validateAnySpec(rawYamlText: string): ValidateResult;
+/**
+ * A discriminated parse result carrying the typed value of whichever family the doc is. Callers that
+ * need the parsed value (not just the verdict) use this. `unknown`/`rayspec` roots parse as RaySpec.
+ */
+export type AnySpecParse = {
+    readonly ok: true;
+    readonly kind: 'rayspec';
+    readonly spec: RaySpec;
+} | {
+    readonly ok: true;
+    readonly kind: 'product';
+    readonly spec: ProductSpec;
+} | {
+    readonly ok: false;
+    readonly kind: SpecKind;
+    readonly errors: SpecError[];
+};
+/** Parse a raw spec of either family, returning the typed value on success. */
+export declare function parseAnySpec(rawYamlText: string): AnySpecParse;
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,KAAK,OAAO,EAAgB,MAAM,cAAc,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,gGAAgG;AAChG,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAY5D;AAED,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAUnE;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AAElF,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,CAY9D"}

package/dist/detect.js

@@ -0,0 +1,72 @@
+/**
+ * Document-kind detection + a unified validator.
+ *
+ * RaySpec is ONE declarative language — `version: '1.0'` — with two PROFILES, told apart by the
+ * presence of the `product:` archetype discriminant:
+ *   • RaySpec (backend profile)  — a `version:'1.0'` doc with NO `product:` section (grammar.ts /
+ *                                       parse.ts) — the low-level surface AND the internal engine target.
+ *   • Product-YAML (product profile)  — a `version:'1.0'` doc that carries the required `product:`
+ *                                       section (product-grammar.ts / product-parse.ts) — the
+ *                                       high-level product-meaning surface that lowers to the backend.
+ *
+ * `detectSpecKind` keys on `version:'1.0'` + `product:` presence: a doc that carries a top-level
+ * `product:` section is the product profile, else the backend profile. A YAML parse/shape failure is
+ * reported as `unknown` so the caller can surface a clean error.
+ */
+import { parse as parseYaml } from 'yaml';
+import { SPEC_VERSION } from './grammar.js';
+import { parseSpec } from './parse.js';
+import { parseProductSpec } from './product-parse.js';
+/**
+ * Detect the document profile. A `version:'1.0'` doc is the PRODUCT profile iff it carries a top-level
+ * `product:` section, else the BACKEND profile. Any other object root (a version-less doc, or one with
+ * an unsupported version) → the backend parser, which fails closed there with a clean
+ * `unsupported_version`. Fail-closed: a non-object / unparseable root → `unknown`.
+ */
+export function detectSpecKind(rawYamlText) {
+    let loaded;
+    try {
+        loaded = parseYaml(rawYamlText);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (loaded === null || typeof loaded !== 'object' || Array.isArray(loaded))
+        return 'unknown';
+    const doc = loaded;
+    // version:'1.0' + the `product:` discriminant selects the product profile; everything else is backend.
+    if (doc.version === SPEC_VERSION && 'product' in doc)
+        return 'product';
+    return 'rayspec';
+}
+/**
+ * Validate a raw spec of EITHER family, collapsing to `{ ok, kind, errors }`. Routes to the correct
+ * parser by `detectSpecKind`. An `unknown` root is routed to `parseSpec` so its existing
+ * `unsupported_version`/`yaml_parse_error` message is preserved (no behavior change for RaySpec).
+ */
+export function validateAnySpec(rawYamlText) {
+    const kind = detectSpecKind(rawYamlText);
+    if (kind === 'product') {
+        const res = parseProductSpec(rawYamlText);
+        return res.ok ? { ok: true, kind, errors: [] } : { ok: false, kind, errors: res.errors };
+    }
+    const res = parseSpec(rawYamlText);
+    return res.ok
+        ? { ok: true, kind: 'rayspec', errors: [] }
+        : { ok: false, kind: 'rayspec', errors: res.errors };
+}
+/** Parse a raw spec of either family, returning the typed value on success. */
+export function parseAnySpec(rawYamlText) {
+    const kind = detectSpecKind(rawYamlText);
+    if (kind === 'product') {
+        const res = parseProductSpec(rawYamlText);
+        return res.ok
+            ? { ok: true, kind: 'product', spec: res.value }
+            : { ok: false, kind: 'product', errors: res.errors };
+    }
+    const res = parseSpec(rawYamlText);
+    return res.ok
+        ? { ok: true, kind: 'rayspec', spec: res.value }
+        : { ok: false, kind: 'rayspec', errors: res.errors };
+}
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAgB,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAKtD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7F,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,uGAAuG;IACvG,IAAI,GAAG,CAAC,OAAO,KAAK,YAAY,IAAI,SAAS,IAAI,GAAG;QAAE,OAAO,SAAS,CAAC;IACvE,OAAO,SAAS,CAAC;AACnB,CAAC;AASD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,MAAM,IAAI,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAC1C,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAC3F,CAAC;IACD,MAAM,GAAG,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;IACnC,OAAO,GAAG,CAAC,EAAE;QACX,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE;QAC3C,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;AACzD,CAAC;AAWD,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,WAAmB;IAC9C,MAAM,IAAI,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,GAAG,GAAmC,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAC1E,OAAO,GAAG,CAAC,EAAE;YACX,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,EAAE;YAChD,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,GAAG,GAA+B,SAAS,CAAC,WAAW,CAAC,CAAC;IAC/D,OAAO,GAAG,CAAC,EAAE;QACX,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,EAAE;QAChD,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;AACzD,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 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 declare const SpecErrorCode: z.ZodEnum<{
+    yaml_parse_error: "yaml_parse_error";
+    unsupported_version: "unsupported_version";
+    schema_violation: "schema_violation";
+    unknown_field: "unknown_field";
+    dangling_ref: "dangling_ref";
+    duplicate_name: "duplicate_name";
+    capability_violation: "capability_violation";
+    invalid_embedded_schema: "invalid_embedded_schema";
+    reserved_column_name: "reserved_column_name";
+    reserved_query_keyword: "reserved_query_keyword";
+    frontend_route_collision: "frontend_route_collision";
+    frontend_dir_missing: "frontend_dir_missing";
+    fk_cycle: "fk_cycle";
+    no_code_in_yaml: "no_code_in_yaml";
+    provider_native_leak: "provider_native_leak";
+    invalid_capability_status: "invalid_capability_status";
+    invalid_contract: "invalid_contract";
+    prompt_execution_claim: "prompt_execution_claim";
+    production_execution_claim: "production_execution_claim";
+    invalid_dependency_order: "invalid_dependency_order";
+    invalid_view: "invalid_view";
+    invalid_store: "invalid_store";
+}>;
+export type SpecErrorCode = z.infer<typeof SpecErrorCode>;
+/** A single fail-closed spec violation (closed code + message + optional JSON path). */
+export declare const SpecError: z.ZodObject<{
+    code: z.ZodEnum<{
+        yaml_parse_error: "yaml_parse_error";
+        unsupported_version: "unsupported_version";
+        schema_violation: "schema_violation";
+        unknown_field: "unknown_field";
+        dangling_ref: "dangling_ref";
+        duplicate_name: "duplicate_name";
+        capability_violation: "capability_violation";
+        invalid_embedded_schema: "invalid_embedded_schema";
+        reserved_column_name: "reserved_column_name";
+        reserved_query_keyword: "reserved_query_keyword";
+        frontend_route_collision: "frontend_route_collision";
+        frontend_dir_missing: "frontend_dir_missing";
+        fk_cycle: "fk_cycle";
+        no_code_in_yaml: "no_code_in_yaml";
+        provider_native_leak: "provider_native_leak";
+        invalid_capability_status: "invalid_capability_status";
+        invalid_contract: "invalid_contract";
+        prompt_execution_claim: "prompt_execution_claim";
+        production_execution_claim: "production_execution_claim";
+        invalid_dependency_order: "invalid_dependency_order";
+        invalid_view: "invalid_view";
+        invalid_store: "invalid_store";
+    }>;
+    message: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SpecError = z.infer<typeof SpecError>;
+/** Construct a SpecError (path omitted when undefined so the envelope stays minimal). */
+export declare function specError(code: SpecErrorCode, message: string, path?: string): SpecError;
+/**
+ * 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 declare const SpecWarningCode: z.ZodEnum<{
+    softdelete_fk_restrict: "softdelete_fk_restrict";
+    fk_forward_reference: "fk_forward_reference";
+}>;
+export type SpecWarningCode = z.infer<typeof SpecWarningCode>;
+/** A single NON-FATAL spec warning (closed code + message + optional JSON path). Never fails a parse. */
+export declare const SpecWarning: z.ZodObject<{
+    code: z.ZodEnum<{
+        softdelete_fk_restrict: "softdelete_fk_restrict";
+        fk_forward_reference: "fk_forward_reference";
+    }>;
+    message: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SpecWarning = z.infer<typeof SpecWarning>;
+/** Construct a SpecWarning (path omitted when undefined so the envelope stays minimal). */
+export declare function specWarning(code: SpecWarningCode, message: string, path?: string): SpecWarning;
+/**
+ * The result of `parseSpec` — a discriminated `Result` so a caller MUST check `ok` before
+ * touching `value` (the fail-closed contract: a spec with any violation yields `ok:false` and
+ * the full violation list, never a partially-trusted value).
+ */
+export type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: E[];
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;EAuBxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,wFAAwF;AACxF,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAExF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe;;;EAA6D,CAAC;AAC1F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,yGAAyG;AACzG,eAAO,MAAM,WAAW;;;;;;;iBAKtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAE9F;AAED;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,CAAC,EAAE,CAAA;CAAE,CAAC"}