@elytracms/core 0.0.6

package/dist/data-binding/issues.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { jsonValueSchema } from '@elytracms/core/project-graph';
+/**
+ * Stable codes for structured binding issues. Broken bindings are represented as data —
+ * never thrown — so the renderer can show a fallback and the inspector can surface the
+ * problem (brief §4.6, §7.5; AGENTS.md "validation is first-class").
+ *
+ * - `unknown-source`     the binding's `sourceId` is not in the source registry
+ * - `unresolved-token`   the token does not resolve to a value in the payload
+ * - `missing-item`       a `repeaterItem` binding was resolved with no item context
+ * - `invalid-spread`     a `spread` binding resolved to a non-object (cannot spread)
+ * - `no-sample`          an operation needed a captured sample but none was present
+ */
+export const bindingIssueCodeSchema = z.enum([
+    'unknown-source',
+    'unresolved-token',
+    'missing-item',
+    'invalid-spread',
+    'no-sample',
+]);
+/**
+ * A structured binding issue. Mirrors `@elytracms/core/project-graph`'s ValidationIssue shape
+ * (code/message/meta) but scoped to binding resolution, where the relevant locator is the
+ * source id and token rather than a graph path.
+ */
+export const bindingIssueSchema = z.object({
+    code: bindingIssueCodeSchema,
+    message: z.string(),
+    /** The data source the binding targeted, when known. */
+    sourceId: z.string().optional(),
+    /** The path token that failed to resolve, when applicable. */
+    token: z.string().optional(),
+    meta: z.record(z.string(), jsonValueSchema).optional(),
+});
+/** Construct a {@link BindingIssue} with optional locator/meta fields omitted when absent. */
+export function bindingIssue(code, message, fields = {}) {
+    const { sourceId, token, meta } = fields;
+    return {
+        code,
+        message,
+        ...(sourceId !== undefined ? { sourceId } : {}),
+        ...(token !== undefined ? { token } : {}),
+        ...(meta !== undefined ? { meta } : {}),
+    };
+}
+//# sourceMappingURL=issues.js.map

package/dist/data-binding/issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.js","sourceRoot":"","sources":["../../src/data-binding/issues.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC3C,gBAAgB;IAChB,kBAAkB;IAClB,cAAc;IACd,gBAAgB;IAChB,WAAW;CACZ,CAAC,CAAA;AAGF;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,wDAAwD;IACxD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,8DAA8D;IAC9D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAA;AAGF,8FAA8F;AAC9F,MAAM,UAAU,YAAY,CAC1B,IAAsB,EACtB,OAAe,EACf,SAA6E,EAAE;IAE/E,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAAA;IACxC,OAAO;QACL,IAAI;QACJ,OAAO;QACP,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAA;AACH,CAAC"}

package/dist/data-binding/resolve.d.ts

@@ -0,0 +1,87 @@
+import type { BindingReference, Condition, JsonValue } from '@elytracms/core/project-graph';
+import type { BindingIssue } from './issues';
+import type { SourceRegistry } from './sources';
+/**
+ * Binding resolution (EC-024). Resolves the five binding modes against captured payloads, in a
+ * form the renderer can inject directly. A binding that cannot be resolved (unknown source,
+ * unresolvable token, missing repeater context, non-object spread) yields a structured
+ * {@link BindingIssue} — never a throw or crash (AGENTS.md "validation is first-class").
+ */
+/**
+ * The repeater item context (EC-024). When the renderer is inside a repeater, each iteration
+ * supplies the current `item` and its zero-based `index`. `repeaterItem` bindings resolve their
+ * token relative to `item` rather than the source payload.
+ */
+export interface RepeaterItemContext {
+    item: JsonValue;
+    index: number;
+}
+/**
+ * What the renderer needs to apply a binding. Discriminated by `kind`:
+ * - `value`     a single resolved value to set on a prop
+ * - `props`     a record of props to spread onto the component (`spread` mode)
+ * - `condition` a boolean gate (`condition` mode)
+ * - `issue`     the binding is broken; carries the structured {@link BindingIssue}
+ */
+export type BindingResolution = {
+    kind: 'value';
+    value: JsonValue;
+} | {
+    kind: 'props';
+    props: Record<string, JsonValue>;
+} | {
+    kind: 'condition';
+    pass: boolean;
+} | {
+    kind: 'issue';
+    issue: BindingIssue;
+};
+/**
+ * A payload store: the resolved payload for each source id, keyed by id. The renderer builds
+ * this by running each source's fetch/query (via the project adapters). Passing the registry
+ * instead — or in addition — lets resolution detect *unknown* sources distinctly from sources
+ * that simply have not loaded yet.
+ */
+export type PayloadStore = Readonly<Record<string, JsonValue>>;
+export interface ResolveContext {
+    /** Resolved payloads keyed by source id. */
+    payloads: PayloadStore;
+    /** Optional registry, used to distinguish an unknown source from one that has not loaded. */
+    registry?: Pick<SourceRegistry, 'has'>;
+}
+/**
+ * Resolve a binding reference against a payload store, suitable for the renderer to inject
+ * (EC-024). The optional `itemContext` supplies the current `{ item, index }` for bindings used
+ * inside a repeater.
+ *
+ * Mode behaviour:
+ * - `value`        resolve the token to a single value
+ * - `object`       resolve the token to an object value (same resolution as `value`; the mode
+ *                  records authoring intent that the result is an object)
+ * - `spread`       resolve the token to an object and expose it as props to spread; a non-object
+ *                  result is an `invalid-spread` issue
+ * - `repeaterItem` resolve the token relative to `itemContext.item`; missing context is a
+ *                  `missing-item` issue
+ * - `condition`    resolve the token to a value and coerce to a boolean gate (truthiness). Use
+ *                  {@link resolveCondition} for full operator support.
+ */
+export declare function resolveBinding(ref: BindingReference, ctx: ResolveContext, itemContext?: RepeaterItemContext): BindingResolution;
+/**
+ * Evaluate a project-graph {@link Condition} against a payload store (EC-024). The left operand
+ * is resolved from the condition's binding; the operator compares it to the condition's `value`.
+ * A broken left operand yields a structured issue instead of a pass/fail so the renderer can
+ * surface it. `exists` checks the token resolved at all (using a sentinel-free probe).
+ */
+export type ConditionResolution = {
+    kind: 'condition';
+    pass: boolean;
+} | {
+    kind: 'issue';
+    issue: BindingIssue;
+};
+export declare function resolveCondition(condition: Condition, ctx: ResolveContext, itemContext?: RepeaterItemContext): ConditionResolution;
+/** True if a resolution is a broken binding (a structured issue). Convenience for the renderer. */
+export declare function isBindingIssue(resolution: BindingResolution | ConditionResolution): resolution is {
+    kind: 'issue';
+    issue: BindingIssue;
+};

package/dist/data-binding/resolve.js

@@ -0,0 +1,204 @@
+import { bindingIssue } from './issues';
+import { resolveToken } from './tokens';
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Look up a source's payload, returning a structured issue when the source is unknown/unloaded. */
+function lookupPayload(ref, ctx) {
+    const known = ctx.registry ? ctx.registry.has(ref.sourceId) : ref.sourceId in ctx.payloads;
+    if (!known) {
+        return {
+            ok: false,
+            issue: bindingIssue('unknown-source', `Binding references unknown data source "${ref.sourceId}".`, {
+                sourceId: ref.sourceId,
+                token: ref.token,
+            }),
+        };
+    }
+    if (!(ref.sourceId in ctx.payloads)) {
+        // Known source, but no payload captured/loaded — treat as an unresolved token at the root.
+        return {
+            ok: false,
+            issue: bindingIssue('unresolved-token', `No payload loaded for source "${ref.sourceId}".`, {
+                sourceId: ref.sourceId,
+                token: ref.token,
+            }),
+        };
+    }
+    return { ok: true, payload: ctx.payloads[ref.sourceId] };
+}
+/** Resolve a token against a base value, producing the value or an `unresolved-token` issue. */
+function resolveAgainst(base, ref) {
+    const result = resolveToken(base, ref.token);
+    if (!result.found) {
+        return {
+            ok: false,
+            issue: bindingIssue('unresolved-token', `Token "${ref.token}" did not resolve in source "${ref.sourceId}".`, {
+                sourceId: ref.sourceId,
+                token: ref.token,
+            }),
+        };
+    }
+    return { ok: true, value: result.value };
+}
+/**
+ * Resolve a binding reference against a payload store, suitable for the renderer to inject
+ * (EC-024). The optional `itemContext` supplies the current `{ item, index }` for bindings used
+ * inside a repeater.
+ *
+ * Mode behaviour:
+ * - `value`        resolve the token to a single value
+ * - `object`       resolve the token to an object value (same resolution as `value`; the mode
+ *                  records authoring intent that the result is an object)
+ * - `spread`       resolve the token to an object and expose it as props to spread; a non-object
+ *                  result is an `invalid-spread` issue
+ * - `repeaterItem` resolve the token relative to `itemContext.item`; missing context is a
+ *                  `missing-item` issue
+ * - `condition`    resolve the token to a value and coerce to a boolean gate (truthiness). Use
+ *                  {@link resolveCondition} for full operator support.
+ */
+export function resolveBinding(ref, ctx, itemContext) {
+    if (ref.mode === 'repeaterItem') {
+        if (!itemContext) {
+            return {
+                kind: 'issue',
+                issue: bindingIssue('missing-item', `Binding "${ref.token}" requires a repeater item context.`, {
+                    sourceId: ref.sourceId,
+                    token: ref.token,
+                }),
+            };
+        }
+        const resolved = resolveAgainst(itemContext.item, ref);
+        return resolved.ok ? { kind: 'value', value: resolved.value } : { kind: 'issue', issue: resolved.issue };
+    }
+    const found = lookupPayload(ref, ctx);
+    if (!found.ok)
+        return { kind: 'issue', issue: found.issue };
+    const resolved = resolveAgainst(found.payload, ref);
+    if (!resolved.ok)
+        return { kind: 'issue', issue: resolved.issue };
+    switch (ref.mode) {
+        case 'value':
+        case 'object':
+            return { kind: 'value', value: resolved.value };
+        case 'spread': {
+            if (!isPlainObject(resolved.value)) {
+                return {
+                    kind: 'issue',
+                    issue: bindingIssue('invalid-spread', `Spread binding "${ref.token}" did not resolve to an object.`, {
+                        sourceId: ref.sourceId,
+                        token: ref.token,
+                    }),
+                };
+            }
+            return { kind: 'props', props: { ...resolved.value } };
+        }
+        case 'condition':
+            return { kind: 'condition', pass: isTruthy(resolved.value) };
+        default: {
+            // Exhaustiveness guard: every BindingMode is handled above.
+            const never = ref.mode;
+            return never;
+        }
+    }
+}
+/** JS-style truthiness for a JSON value (empty string, 0, false, null are falsy). */
+function isTruthy(value) {
+    return Boolean(value);
+}
+export function resolveCondition(condition, ctx, itemContext) {
+    const ref = condition.source;
+    // Resolve the base value the token is read from (repeater item or source payload).
+    let base;
+    if (ref.mode === 'repeaterItem') {
+        if (!itemContext) {
+            return {
+                kind: 'issue',
+                issue: bindingIssue('missing-item', `Condition "${ref.token}" requires a repeater item context.`, {
+                    sourceId: ref.sourceId,
+                    token: ref.token,
+                }),
+            };
+        }
+        base = itemContext.item;
+    }
+    else {
+        const found = lookupPayload(ref, ctx);
+        if (!found.ok) {
+            // Unknown/unloaded source. For `exists`, that is a legitimate `false`, not an issue.
+            if (condition.operator === 'exists')
+                return { kind: 'condition', pass: false };
+            return { kind: 'issue', issue: found.issue };
+        }
+        base = found.payload;
+    }
+    const probe = resolveToken(base, ref.token);
+    if (condition.operator === 'exists') {
+        return { kind: 'condition', pass: probe.found };
+    }
+    if (!probe.found) {
+        return {
+            kind: 'issue',
+            issue: bindingIssue('unresolved-token', `Condition token "${ref.token}" did not resolve in source "${ref.sourceId}".`, {
+                sourceId: ref.sourceId,
+                token: ref.token,
+            }),
+        };
+    }
+    return { kind: 'condition', pass: compare(probe.value, condition.operator, condition.value) };
+}
+function compare(left, operator, right) {
+    switch (operator) {
+        case 'truthy':
+            return isTruthy(left);
+        case 'exists':
+            // Handled by resolveCondition (token presence); reaching here means the token resolved.
+            return true;
+        case 'eq':
+            return deepEqual(left, right ?? null);
+        case 'neq':
+            return !deepEqual(left, right ?? null);
+        case 'gt':
+        case 'gte':
+        case 'lt':
+        case 'lte': {
+            if (typeof left !== 'number' || typeof right !== 'number')
+                return false;
+            if (operator === 'gt')
+                return left > right;
+            if (operator === 'gte')
+                return left >= right;
+            if (operator === 'lt')
+                return left < right;
+            return left <= right;
+        }
+        default: {
+            const never = operator;
+            return never;
+        }
+    }
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/** True if a resolution is a broken binding (a structured issue). Convenience for the renderer. */
+export function isBindingIssue(resolution) {
+    return resolution.kind === 'issue';
+}
+//# sourceMappingURL=resolve.js.map

package/dist/data-binding/resolve.js.map

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

package/dist/data-binding/sample.d.ts

@@ -0,0 +1,21 @@
+import type { JsonValue } from '@elytracms/core/project-graph';
+import type { DataSource } from './sources';
+import type { InferredSchema } from './tokens';
+/** A source guaranteed to carry a captured sample + inferred schema. */
+export type SampledSource<S extends DataSource = DataSource> = S & {
+    sample: JsonValue;
+    schema: InferredSchema;
+};
+/**
+ * Sample capture (EC-023). Attach a representative payload to a source and infer its schema in
+ * one step. This is deliberately pure: actually performing the REST fetch / CMS query / Convex
+ * call lives behind the project-owned adapters; this package only models the captured result so
+ * inference, tokens, and resolution are deterministic and testable from fixtures.
+ */
+export declare function captureSample<S extends DataSource>(source: S, sample: JsonValue): SampledSource<S>;
+/**
+ * The stable path tokens a source exposes, derived from its captured sample (EC-023). Returns
+ * an empty list when no sample has been captured yet. Tokens are JSON Pointers that survive UI
+ * label changes — see {@link tokensForSchema}.
+ */
+export declare function sourceTokens(source: DataSource): string[];

package/dist/data-binding/sample.js

@@ -0,0 +1,23 @@
+import { inferSchema, tokensForSchema } from './tokens';
+/**
+ * Sample capture (EC-023). Attach a representative payload to a source and infer its schema in
+ * one step. This is deliberately pure: actually performing the REST fetch / CMS query / Convex
+ * call lives behind the project-owned adapters; this package only models the captured result so
+ * inference, tokens, and resolution are deterministic and testable from fixtures.
+ */
+export function captureSample(source, sample) {
+    return { ...source, sample, schema: inferSchema(sample) };
+}
+/**
+ * The stable path tokens a source exposes, derived from its captured sample (EC-023). Returns
+ * an empty list when no sample has been captured yet. Tokens are JSON Pointers that survive UI
+ * label changes — see {@link tokensForSchema}.
+ */
+export function sourceTokens(source) {
+    if (source.schema)
+        return tokensForSchema(source.schema);
+    if (source.sample !== undefined)
+        return tokensForSchema(inferSchema(source.sample));
+    return [];
+}
+//# sourceMappingURL=sample.js.map

package/dist/data-binding/sample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample.js","sourceRoot":"","sources":["../../src/data-binding/sample.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAQvD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAuB,MAAS,EAAE,MAAiB;IAC9E,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,CAAA;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB;IAC7C,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACxD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IACnF,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/data-binding/sources.d.ts

@@ -0,0 +1,225 @@
+import { z } from 'zod';
+/**
+ * Data sources (EC-022). One uniform shape across the three kinds the product supports
+ * (brief §4.6, §7.5):
+ *
+ * - `rest`   an HTTP fetch source (external API)
+ * - `cms`    an internal CMS collection query (resolved by `@elytracms/core/cms-core`)
+ * - `convex` a Convex query or mutation, behind the project-owned repository adapter
+ *
+ * Every source shares the same envelope: a stable `id` (the binding `sourceId` addresses it),
+ * a human label, the kind-specific `config`, and an optional captured `sample` + inferred
+ * `schema` (EC-023). The kind-specific config differs, but resolution, sampling, inference and
+ * tokenization treat all three identically.
+ */
+/** HTTP methods permitted for a REST fetch source. */
+export declare const httpMethodSchema: z.ZodEnum<{
+    GET: "GET";
+    POST: "POST";
+    PUT: "PUT";
+    PATCH: "PATCH";
+    DELETE: "DELETE";
+}>;
+export type HttpMethod = z.infer<typeof httpMethodSchema>;
+/** Per-source fetch configuration for a REST source. */
+export declare const restConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    method: z.ZodDefault<z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+    }>>;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    query: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodOptional<z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>;
+}, z.core.$strip>;
+export type RestConfig = z.infer<typeof restConfigSchema>;
+export declare const restSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rest">;
+    id: z.ZodString;
+    label: z.ZodString;
+    config: z.ZodObject<{
+        url: z.ZodString;
+        method: z.ZodDefault<z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+        }>>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        query: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Single-field sort of a CMS list query (EC-166 repeating sections). Matches
+ * the canonical AD-3 sort shape (`@elytracms/core/content`'s `SortInput` with the
+ * direction explicit); ties always break by document id ascending downstream.
+ */
+export declare const cmsSortSchema: z.ZodObject<{
+    field: z.ZodString;
+    direction: z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>;
+}, z.core.$strip>;
+export type CmsSort = z.infer<typeof cmsSortSchema>;
+/** Per-source query configuration for an internal CMS collection query. */
+export declare const cmsConfigSchema: z.ZodObject<{
+    collectionId: z.ZodString;
+    documentId: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodString>;
+    filter: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>>;
+    sort: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CmsConfig = z.infer<typeof cmsConfigSchema>;
+export declare const cmsSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"cms">;
+    id: z.ZodString;
+    label: z.ZodString;
+    config: z.ZodObject<{
+        collectionId: z.ZodString;
+        documentId: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        filter: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>>;
+        sort: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            direction: z.ZodEnum<{
+                asc: "asc";
+                desc: "desc";
+            }>;
+        }, z.core.$strip>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Whether a Convex source reads (query) or writes (mutation). */
+export declare const convexOperationSchema: z.ZodEnum<{
+    query: "query";
+    mutation: "mutation";
+}>;
+export type ConvexOperation = z.infer<typeof convexOperationSchema>;
+/** Per-source query/mutation configuration for a Convex function reference. */
+export declare const convexConfigSchema: z.ZodObject<{
+    operation: z.ZodDefault<z.ZodEnum<{
+        query: "query";
+        mutation: "mutation";
+    }>>;
+    functionRef: z.ZodString;
+    args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>>;
+}, z.core.$strip>;
+export type ConvexConfig = z.infer<typeof convexConfigSchema>;
+export declare const convexSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"convex">;
+    id: z.ZodString;
+    label: z.ZodString;
+    config: z.ZodObject<{
+        operation: z.ZodDefault<z.ZodEnum<{
+            query: "query";
+            mutation: "mutation";
+        }>>;
+        functionRef: z.ZodString;
+        args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * The captured sample (EC-023) and inferred schema are attached uniformly to any source kind.
+ * Kept separate from the kind-specific union so the discriminated union stays clean and the
+ * sample fields can be merged on after parse.
+ */
+export declare const sampleEnvelopeSchema: z.ZodObject<{
+    sample: z.ZodOptional<z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>;
+    schema: z.ZodOptional<z.ZodType<import("./tokens").InferredSchema, unknown, z.core.$ZodTypeInternals<import("./tokens").InferredSchema, unknown>>>;
+}, z.core.$strip>;
+/** The uniform source shape: kind-specific envelope plus the shared sample/schema fields. */
+export declare const dataSourceSchema: z.ZodIntersection<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"rest">;
+    id: z.ZodString;
+    label: z.ZodString;
+    config: z.ZodObject<{
+        url: z.ZodString;
+        method: z.ZodDefault<z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+        }>>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        query: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"cms">;
+    id: z.ZodString;
+    label: z.ZodString;
+    config: z.ZodObject<{
+        collectionId: z.ZodString;
+        documentId: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodString>;
+        filter: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>>;
+        sort: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            direction: z.ZodEnum<{
+                asc: "asc";
+                desc: "desc";
+            }>;
+        }, z.core.$strip>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"convex">;
+    id: z.ZodString;
+    label: z.ZodString;
+    config: z.ZodObject<{
+        operation: z.ZodDefault<z.ZodEnum<{
+            query: "query";
+            mutation: "mutation";
+        }>>;
+        functionRef: z.ZodString;
+        args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "kind">, z.ZodObject<{
+    sample: z.ZodOptional<z.ZodType<import("@elytracms/core/project-graph").JsonValue, unknown, z.core.$ZodTypeInternals<import("@elytracms/core/project-graph").JsonValue, unknown>>>;
+    schema: z.ZodOptional<z.ZodType<import("./tokens").InferredSchema, unknown, z.core.$ZodTypeInternals<import("./tokens").InferredSchema, unknown>>>;
+}, z.core.$strip>>;
+export type DataSource = z.infer<typeof dataSourceSchema>;
+export type DataSourceKind = DataSource['kind'];
+export type RestSource = z.infer<typeof restSourceSchema> & z.infer<typeof sampleEnvelopeSchema>;
+export type CmsSource = z.infer<typeof cmsSourceSchema> & z.infer<typeof sampleEnvelopeSchema>;
+export type ConvexSource = z.infer<typeof convexSourceSchema> & z.infer<typeof sampleEnvelopeSchema>;
+/** Parse an unknown value into a {@link DataSource}, applying per-config defaults. Never throws. */
+export declare function parseDataSource(input: unknown): ReturnType<typeof dataSourceSchema.safeParse>;
+/**
+ * A registry of data sources addressable by stable id (EC-022). Construction de-duplicates by
+ * id (last write wins) and validates each entry; lookups are O(1). The registry is immutable —
+ * `with`/`without` return new registries — so it can be stored in the graph/editor state safely.
+ */
+export declare class SourceRegistry {
+    private readonly byId;
+    private constructor();
+    /** Build a registry from a list of sources. Each is validated via {@link dataSourceSchema}. */
+    static from(sources: Iterable<DataSource>): SourceRegistry;
+    /** An empty registry. */
+    static empty(): SourceRegistry;
+    has(id: string): boolean;
+    get(id: string): DataSource | undefined;
+    list(): DataSource[];
+    ids(): string[];
+    /** The set of known ids, suitable for `validateProjectGraph`'s `knownSourceIds` option. */
+    knownSourceIds(): ReadonlySet<string>;
+    /** Return a new registry with `source` added or replacing any existing entry with the same id. */
+    with(source: DataSource): SourceRegistry;
+    /** Return a new registry without the source `id` (no-op if absent). */
+    without(id: string): SourceRegistry;
+    get size(): number;
+}