@elytracms/core 0.0.6

package/dist/content/locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.js","sourceRoot":"","sources":["../../src/content/locale.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AA4BvD;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAuB,EACvB,UAAyB,EACzB,GAAgB,EAChB,WAAoB,EAAE;IAEtB,MAAM,MAAM,GAAgB,EAAE,CAAA;IAC9B,MAAM,SAAS,GAA0B,EAAE,CAAA;IAE3C,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;QAC3F,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS;YAAE,SAAQ;QAC1C,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAA;QACnC,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACtB,SAAS,CAAC,IAAI,CAAC;gBACb,IAAI,EAAE,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC;gBAC/B,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,eAAe,EAAE,OAAO,CAAC,MAAM;gBAC/B,YAAY,EAAE,QAAQ,CAAC,YAAY;aACpC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAA;AAC9B,CAAC"}

package/dist/content/perspective.d.ts

@@ -0,0 +1,29 @@
+import type { CmsDocument, DocumentHistory } from '@elytracms/core/cms-core';
+import type { ContentContext } from './context';
+/**
+ * What delivery resolution accepts as a document source: either a bare stored
+ * row (`CmsDocument`, always a working draft — EC-224 retired the `state` flag)
+ * or the full draft/published history (`DocumentHistory`, EC-021) whose
+ * `published` field carries the pinned snapshot. Lookups hand these in;
+ * resolution stays pure — no fetching at this layer.
+ */
+export type ContentDocumentSource = CmsDocument | DocumentHistory;
+/** Narrow a source to a `DocumentHistory` (draft/published split, EC-021). */
+export declare function isDocumentHistory(source: ContentDocumentSource): source is DocumentHistory;
+/**
+ * Select the stored row visible under the context's perspective (EC-021):
+ *
+ * - For a `DocumentHistory`: `draft` returns the working draft, `published`
+ *   returns the last published snapshot — or `null` if the document has never
+ *   been published. Draft content is never leaked into `published`.
+ * - For a bare `CmsDocument`: `draft` sees the row as-is; `published` returns
+ *   `null`. A bare row carries no publish signal (EC-224 retired `state`), so
+ *   it is treated as never-published here — fail-closed. Published content
+ *   reaches this layer ONLY as a `DocumentHistory` whose `published` field the
+ *   feeder set (the live host wraps each published snapshot; the adapter path
+ *   wraps a pinned record), never as a bare row.
+ *
+ * Returning `null` means "not visible in this perspective" — that is correct
+ * delivery behavior for unpublished content, not a validation issue.
+ */
+export declare function selectPerspective(context: ContentContext, source: ContentDocumentSource): CmsDocument | null;

package/dist/content/perspective.js

@@ -0,0 +1,31 @@
+/** Narrow a source to a `DocumentHistory` (draft/published split, EC-021). */
+export function isDocumentHistory(source) {
+    return 'draft' in source && 'versions' in source;
+}
+/**
+ * Select the stored row visible under the context's perspective (EC-021):
+ *
+ * - For a `DocumentHistory`: `draft` returns the working draft, `published`
+ *   returns the last published snapshot — or `null` if the document has never
+ *   been published. Draft content is never leaked into `published`.
+ * - For a bare `CmsDocument`: `draft` sees the row as-is; `published` returns
+ *   `null`. A bare row carries no publish signal (EC-224 retired `state`), so
+ *   it is treated as never-published here — fail-closed. Published content
+ *   reaches this layer ONLY as a `DocumentHistory` whose `published` field the
+ *   feeder set (the live host wraps each published snapshot; the adapter path
+ *   wraps a pinned record), never as a bare row.
+ *
+ * Returning `null` means "not visible in this perspective" — that is correct
+ * delivery behavior for unpublished content, not a validation issue.
+ */
+export function selectPerspective(context, source) {
+    if (isDocumentHistory(source)) {
+        if (context.perspective === 'draft')
+            return source.draft;
+        return source.published ?? null;
+    }
+    if (context.perspective === 'draft')
+        return source;
+    return null;
+}
+//# sourceMappingURL=perspective.js.map

package/dist/content/perspective.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perspective.js","sourceRoot":"","sources":["../../src/content/perspective.ts"],"names":[],"mappings":"AAYA,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,MAA6B;IAC7D,OAAO,OAAO,IAAI,MAAM,IAAI,UAAU,IAAI,MAAM,CAAA;AAClD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAuB,EACvB,MAA6B;IAE7B,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,WAAW,KAAK,OAAO;YAAE,OAAO,MAAM,CAAC,KAAK,CAAA;QACxD,OAAO,MAAM,CAAC,SAAS,IAAI,IAAI,CAAA;IACjC,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,OAAO;QAAE,OAAO,MAAM,CAAA;IAClD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/content/populate.d.ts

@@ -0,0 +1,25 @@
+import type { DocumentRef, RelationFieldDef } from '@elytracms/core/cms-core';
+/**
+ * The unpopulated form of a relation in delivery shape (vision AD-4): always a
+ * `{ id, collection }` object, never a bare id string. Returned when a field
+ * declares `populate: false`, and for relations *inside* a populated document
+ * (population never recurses past depth-1).
+ */
+export interface DocumentStub {
+    id: string;
+    collection: string;
+}
+/**
+ * Whether delivery resolution populates this relation to depth-1 (EC-142).
+ * Population is the default; `populate: false` is the schema-level opt-out.
+ */
+export declare function isPopulatedRelation(field: RelationFieldDef): boolean;
+/** Build the reference stub for a relation target. */
+export declare function relationStub(ref: DocumentRef): DocumentStub;
+/**
+ * Parse a stored relation value into a `DocumentRef`, tolerating malformed data:
+ * anything not relation-shaped yields `undefined` so the caller can surface a
+ * structured issue instead of crashing. Accepts the EC-277 self-typed envelope
+ * (`{ type:'reference', collection, id }`) and legacy bare `{ collection, id }`.
+ */
+export declare function parseRelationRef(value: unknown): DocumentRef | undefined;

package/dist/content/populate.js

@@ -0,0 +1,22 @@
+import { readDocumentRef } from '@elytracms/core/cms-core';
+/**
+ * Whether delivery resolution populates this relation to depth-1 (EC-142).
+ * Population is the default; `populate: false` is the schema-level opt-out.
+ */
+export function isPopulatedRelation(field) {
+    return field.populate !== false;
+}
+/** Build the reference stub for a relation target. */
+export function relationStub(ref) {
+    return { id: ref.id, collection: ref.collection };
+}
+/**
+ * Parse a stored relation value into a `DocumentRef`, tolerating malformed data:
+ * anything not relation-shaped yields `undefined` so the caller can surface a
+ * structured issue instead of crashing. Accepts the EC-277 self-typed envelope
+ * (`{ type:'reference', collection, id }`) and legacy bare `{ collection, id }`.
+ */
+export function parseRelationRef(value) {
+    return readDocumentRef(value);
+}
+//# sourceMappingURL=populate.js.map

package/dist/content/populate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"populate.js","sourceRoot":"","sources":["../../src/content/populate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAc1D;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAuB;IACzD,OAAO,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAA;AACjC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,GAAgB;IAC3C,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAA;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,eAAe,CAAC,KAAK,CAAC,CAAA;AAC/B,CAAC"}

package/dist/content/query.d.ts

@@ -0,0 +1,122 @@
+import type { CmsPath, CollectionDef, FieldDef } from '@elytracms/core/cms-core';
+/**
+ * The closed v1 filter vocabulary (vision AD-3): equality, `in`, comparisons
+ * (lt/lte/gt/gte), AND-only composition. Multiple `where` keys AND together;
+ * multiple operators inside one condition AND together. There is no OR, no
+ * nesting, no anything else — by design, so every query is enumerable,
+ * cache-taggable, and honest about backend indexes.
+ */
+export declare const FILTER_OPERATORS: readonly ["eq", "gt", "gte", "in", "lt", "lte"];
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+/** A scalar a filter can compare against (relation/asset filters use the id). */
+export type FilterScalar = string | number | boolean;
+/** One field's filter: every present operator must hold (AND). */
+export interface FilterCondition {
+    eq?: FilterScalar;
+    gt?: FilterScalar;
+    gte?: FilterScalar;
+    in?: readonly FilterScalar[];
+    lt?: FilterScalar;
+    lte?: FilterScalar;
+}
+/**
+ * The `where` input: field name → condition. A bare scalar is shorthand for
+ * `{ eq: value }`. Generated per-collection types (`PostWhere`) narrow the
+ * keys to the fields declared `filterable` in the schema.
+ */
+export type WhereInput = Readonly<Record<string, FilterScalar | FilterCondition | undefined>>;
+export type SortDirection = 'asc' | 'desc';
+/** Single-field sort; ties always break by document id ascending. */
+export interface SortInput {
+    field: string;
+    direction?: SortDirection;
+}
+/** The full `listDocuments` query envelope (vision AD-3, rung 3). */
+export interface ListDocumentsQuery<TWhere extends WhereInput = WhereInput> {
+    where?: TWhere;
+    sort?: SortInput;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Codes for structured accessor query errors (EC-143). These describe *caller*
+ * mistakes (bad filter, bad cursor), as opposed to `CmsValidationIssue`s which
+ * describe content/schema problems. Accessors never throw — invalid queries
+ * come back as an error result carrying these.
+ */
+export type ContentQueryErrorCode = 'unknown-collection' | 'list-not-supported' | 'non-filterable-field' | 'invalid-filter' | 'invalid-sort' | 'invalid-limit' | 'invalid-cursor';
+export interface ContentQueryError {
+    code: ContentQueryErrorCode;
+    message: string;
+    /** Path into the query input, e.g. ['where', 'title'] or ['sort', 'field']. */
+    path: CmsPath;
+    meta?: Record<string, unknown>;
+}
+export declare function queryError(code: ContentQueryErrorCode, message: string, path: CmsPath, meta?: Record<string, unknown>): ContentQueryError;
+/** A condition with the `eq` shorthand expanded, operators in stable order. */
+export type NormalizedCondition = Partial<Record<FilterOperator, FilterScalar | readonly FilterScalar[]>>;
+export interface NormalizedWhereEntry {
+    field: string;
+    condition: NormalizedCondition;
+}
+/**
+ * Normalize a `where` input into entries sorted by field name, with the bare
+ * scalar shorthand expanded to `{ eq: value }` and operators in the stable
+ * `FILTER_OPERATORS` order. Both serialization and execution run on this
+ * normal form, so `{ slug: 'x' }` and `{ slug: { eq: 'x' } }` are the same
+ * query (and produce the same cache key).
+ */
+export declare function normalizeWhere(where: WhereInput): NormalizedWhereEntry[];
+/** The fields of a collection declared `filterable` (EC-143 schema flag). */
+export declare function filterableFields(collection: CollectionDef): FieldDef[];
+/**
+ * Validate a `where` input against a collection schema. Filters are permitted
+ * **only** on fields declared `filterable` — anything else is a structured
+ * `non-filterable-field` error. Unknown operators and malformed operator
+ * values are `invalid-filter` errors. All errors are collected (sorted by
+ * field, deterministic), never thrown.
+ */
+export declare function validateWhere(collection: CollectionDef, where: WhereInput): ContentQueryError[];
+/**
+ * Validate a sort input. Sorting uses the same `filterable` declaration as
+ * filtering (same rationale: backend indexes stay honest).
+ */
+export declare function validateSort(collection: CollectionDef, sort: SortInput): ContentQueryError[];
+/** Validate a limit: a positive integer (or absent = no pagination). */
+export declare function validateLimit(limit: number): ContentQueryError[];
+/**
+ * Reduce a stored field value to the scalar filters compare against: scalars
+ * pass through, relation refs compare by target id, anything else (arrays,
+ * rich objects, missing) is `null` and never matches a condition.
+ */
+export declare function filterScalarOf(value: unknown): FilterScalar | null;
+/**
+ * Does a stored field value satisfy one normalized condition? Scalars and single
+ * relation/asset refs reduce via {@link filterScalarOf} and match directly. An
+ * ARRAY field — a `many` relation/asset (EC-255) — matches with **contains**
+ * semantics: the condition holds if ANY element satisfies it, so
+ * `where: { categories: catId }` lists products whose `categories` array
+ * contains `catId`. An empty array matches nothing. Scalar fields keep their
+ * exact prior behavior (the non-array branch is the original reduce-then-match).
+ */
+export declare function matchesFieldValue(value: unknown, condition: NormalizedCondition): boolean;
+/** Does a (scalar-reduced) value satisfy one normalized condition? AND-only. */
+export declare function matchesCondition(value: FilterScalar | null, condition: NormalizedCondition): boolean;
+/**
+ * Total, deterministic order over sort values: numbers first (numeric order),
+ * then strings (code-unit order), then booleans (false < true), then missing
+ * values (`null`). `desc` flips this entire order; the id tiebreak stays
+ * ascending either way (see `compareListEntries`).
+ */
+export declare function compareSortValues(a: FilterScalar | null, b: FilterScalar | null): number;
+/** One row in list ordering: its id plus its (scalar-reduced) sort value. */
+export interface ListPosition {
+    id: string;
+    sortValue: FilterScalar | null;
+}
+/**
+ * The canonical list order (and cursor position order): sort value in the
+ * requested direction, then id ascending as the unconditional tiebreak — so
+ * pagination is total, stable, and reproducible from fixtures.
+ */
+export declare function compareListEntries(a: ListPosition, b: ListPosition, direction: SortDirection): number;

package/dist/content/query.js

@@ -0,0 +1,257 @@
+/**
+ * The closed v1 filter vocabulary (vision AD-3): equality, `in`, comparisons
+ * (lt/lte/gt/gte), AND-only composition. Multiple `where` keys AND together;
+ * multiple operators inside one condition AND together. There is no OR, no
+ * nesting, no anything else — by design, so every query is enumerable,
+ * cache-taggable, and honest about backend indexes.
+ */
+export const FILTER_OPERATORS = ['eq', 'gt', 'gte', 'in', 'lt', 'lte'];
+export function queryError(code, message, path, meta) {
+    return { code, message, path, ...(meta ? { meta } : {}) };
+}
+function isFilterScalar(value) {
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+function isOperator(key) {
+    return FILTER_OPERATORS.includes(key);
+}
+/**
+ * Normalize a `where` input into entries sorted by field name, with the bare
+ * scalar shorthand expanded to `{ eq: value }` and operators in the stable
+ * `FILTER_OPERATORS` order. Both serialization and execution run on this
+ * normal form, so `{ slug: 'x' }` and `{ slug: { eq: 'x' } }` are the same
+ * query (and produce the same cache key).
+ */
+export function normalizeWhere(where) {
+    const entries = [];
+    for (const field of Object.keys(where).sort()) {
+        const raw = where[field];
+        if (raw === undefined)
+            continue;
+        if (isFilterScalar(raw)) {
+            entries.push({ field, condition: { eq: raw } });
+            continue;
+        }
+        const condition = {};
+        for (const op of FILTER_OPERATORS) {
+            const value = raw[op];
+            if (value === undefined)
+                continue;
+            condition[op] = value;
+        }
+        entries.push({ field, condition });
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Validation (filterable-field enforcement, EC-143)
+// ---------------------------------------------------------------------------
+function fieldByName(collection, name) {
+    return collection.fields.find((f) => f.name === name);
+}
+/** The fields of a collection declared `filterable` (EC-143 schema flag). */
+export function filterableFields(collection) {
+    return collection.fields.filter((f) => f.filterable === true);
+}
+/**
+ * Validate a `where` input against a collection schema. Filters are permitted
+ * **only** on fields declared `filterable` — anything else is a structured
+ * `non-filterable-field` error. Unknown operators and malformed operator
+ * values are `invalid-filter` errors. All errors are collected (sorted by
+ * field, deterministic), never thrown.
+ */
+export function validateWhere(collection, where) {
+    const errors = [];
+    for (const field of Object.keys(where).sort()) {
+        const raw = where[field];
+        if (raw === undefined)
+            continue;
+        const path = ['where', field];
+        const def = fieldByName(collection, field);
+        if (!def || def.filterable !== true) {
+            errors.push(queryError('non-filterable-field', def
+                ? `Field "${field}" on "${collection.id}" is not declared filterable.`
+                : `Field "${field}" does not exist on "${collection.id}".`, path, { collection: collection.id, field }));
+            continue;
+        }
+        if (isFilterScalar(raw))
+            continue;
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push(queryError('invalid-filter', `Filter for "${field}" must be a scalar or an operator object.`, path));
+            continue;
+        }
+        const keys = Object.keys(raw).sort();
+        if (keys.length === 0) {
+            errors.push(queryError('invalid-filter', `Filter for "${field}" has no operators.`, path));
+            continue;
+        }
+        for (const key of keys) {
+            const value = raw[key];
+            if (value === undefined)
+                continue;
+            const opPath = ['where', field, key];
+            if (!isOperator(key)) {
+                errors.push(queryError('invalid-filter', `Unknown filter operator "${key}" on "${field}" — the vocabulary is exactly ${FILTER_OPERATORS.join(', ')}.`, opPath, { operator: key }));
+                continue;
+            }
+            if (key === 'in') {
+                if (!Array.isArray(value) || !value.every(isFilterScalar)) {
+                    errors.push(queryError('invalid-filter', `Operator "in" on "${field}" requires an array of scalars.`, opPath));
+                }
+                continue;
+            }
+            if (!isFilterScalar(value)) {
+                errors.push(queryError('invalid-filter', `Operator "${key}" on "${field}" requires a scalar value.`, opPath));
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Validate a sort input. Sorting uses the same `filterable` declaration as
+ * filtering (same rationale: backend indexes stay honest).
+ */
+export function validateSort(collection, sort) {
+    const def = fieldByName(collection, sort.field);
+    if (!def || def.filterable !== true) {
+        return [
+            queryError('invalid-sort', def
+                ? `Sort field "${sort.field}" on "${collection.id}" is not declared filterable.`
+                : `Sort field "${sort.field}" does not exist on "${collection.id}".`, ['sort', 'field'], { collection: collection.id, field: sort.field }),
+        ];
+    }
+    if (sort.direction !== undefined && sort.direction !== 'asc' && sort.direction !== 'desc') {
+        return [
+            queryError('invalid-sort', `Sort direction must be "asc" or "desc".`, ['sort', 'direction']),
+        ];
+    }
+    return [];
+}
+/** Validate a limit: a positive integer (or absent = no pagination). */
+export function validateLimit(limit) {
+    if (!Number.isInteger(limit) || limit < 1) {
+        return [queryError('invalid-limit', 'Limit must be a positive integer.', ['limit'])];
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Matching & ordering (pure, deterministic)
+// ---------------------------------------------------------------------------
+/**
+ * Reduce a stored field value to the scalar filters compare against: scalars
+ * pass through, relation refs compare by target id, anything else (arrays,
+ * rich objects, missing) is `null` and never matches a condition.
+ */
+export function filterScalarOf(value) {
+    if (isFilterScalar(value))
+        return value;
+    if (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        typeof value.id === 'string') {
+        return value.id;
+    }
+    return null;
+}
+/**
+ * Three-way compare, or `null` when the values are uncomparable: an UNSET field
+ * (`value === null`) or a type mismatch. Callers treat `null` as "does not
+ * match", so an unset field is EXCLUDED from every comparison operator — unset
+ * never satisfies a value comparison (EC-205). Pinned by query.test.ts.
+ */
+function compares(value, bound) {
+    if (value === null)
+        return null;
+    if (typeof value === 'number' && typeof bound === 'number') {
+        return value < bound ? -1 : value > bound ? 1 : 0;
+    }
+    if (typeof value === 'string' && typeof bound === 'string') {
+        // Code-unit comparison: deterministic across environments (no locale tables).
+        return value < bound ? -1 : value > bound ? 1 : 0;
+    }
+    return null;
+}
+/**
+ * Does a stored field value satisfy one normalized condition? Scalars and single
+ * relation/asset refs reduce via {@link filterScalarOf} and match directly. An
+ * ARRAY field — a `many` relation/asset (EC-255) — matches with **contains**
+ * semantics: the condition holds if ANY element satisfies it, so
+ * `where: { categories: catId }` lists products whose `categories` array
+ * contains `catId`. An empty array matches nothing. Scalar fields keep their
+ * exact prior behavior (the non-array branch is the original reduce-then-match).
+ */
+export function matchesFieldValue(value, condition) {
+    if (Array.isArray(value)) {
+        return value.some((element) => matchesCondition(filterScalarOf(element), condition));
+    }
+    return matchesCondition(filterScalarOf(value), condition);
+}
+/** Does a (scalar-reduced) value satisfy one normalized condition? AND-only. */
+export function matchesCondition(value, condition) {
+    for (const op of FILTER_OPERATORS) {
+        const bound = condition[op];
+        if (bound === undefined)
+            continue;
+        switch (op) {
+            case 'eq':
+                if (value !== bound)
+                    return false;
+                break;
+            case 'in':
+                if (value === null || !bound.includes(value))
+                    return false;
+                break;
+            case 'lt':
+            case 'lte':
+            case 'gt':
+            case 'gte': {
+                const cmp = compares(value, bound);
+                if (cmp === null)
+                    return false;
+                if (op === 'lt' && !(cmp < 0))
+                    return false;
+                if (op === 'lte' && !(cmp <= 0))
+                    return false;
+                if (op === 'gt' && !(cmp > 0))
+                    return false;
+                if (op === 'gte' && !(cmp >= 0))
+                    return false;
+                break;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Total, deterministic order over sort values: numbers first (numeric order),
+ * then strings (code-unit order), then booleans (false < true), then missing
+ * values (`null`). `desc` flips this entire order; the id tiebreak stays
+ * ascending either way (see `compareListEntries`).
+ */
+export function compareSortValues(a, b) {
+    const rank = (v) => typeof v === 'number' ? 0 : typeof v === 'string' ? 1 : typeof v === 'boolean' ? 2 : 3;
+    const ra = rank(a);
+    const rb = rank(b);
+    if (ra !== rb)
+        return ra - rb;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === 'string' && typeof b === 'string')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === 'boolean' && typeof b === 'boolean')
+        return a === b ? 0 : a ? 1 : -1;
+    return 0;
+}
+/**
+ * The canonical list order (and cursor position order): sort value in the
+ * requested direction, then id ascending as the unconditional tiebreak — so
+ * pagination is total, stable, and reproducible from fixtures.
+ */
+export function compareListEntries(a, b, direction) {
+    const byValue = compareSortValues(a.sortValue, b.sortValue);
+    const directed = direction === 'desc' ? -byValue : byValue;
+    if (directed !== 0)
+        return directed;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+//# sourceMappingURL=query.js.map

package/dist/content/query.js.map

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

package/dist/content/raw.d.ts

@@ -0,0 +1,13 @@
+import type { CmsDocument } from '@elytracms/core/cms-core';
+import type { ContentContext } from './context';
+import type { ContentDocumentSource } from './perspective';
+/**
+ * Escape hatch (vision AD-4, `content.raw`): the stored row, untouched — no
+ * locale fallback, no relation population, no asset resolution. Relations stay
+ * `DocumentRef`s, assets stay ids, localized values stay per-locale bags.
+ *
+ * Perspective still applies: even raw access never leaks draft content into
+ * the published perspective. Returns `null` when the document is not visible
+ * under the context perspective.
+ */
+export declare function rawDocument(context: ContentContext, source: ContentDocumentSource): CmsDocument | null;

package/dist/content/raw.js

@@ -0,0 +1,14 @@
+import { selectPerspective } from './perspective';
+/**
+ * Escape hatch (vision AD-4, `content.raw`): the stored row, untouched — no
+ * locale fallback, no relation population, no asset resolution. Relations stay
+ * `DocumentRef`s, assets stay ids, localized values stay per-locale bags.
+ *
+ * Perspective still applies: even raw access never leaks draft content into
+ * the published perspective. Returns `null` when the document is not visible
+ * under the context perspective.
+ */
+export function rawDocument(context, source) {
+    return selectPerspective(context, source);
+}
+//# sourceMappingURL=raw.js.map

package/dist/content/raw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.js","sourceRoot":"","sources":["../../src/content/raw.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGjD;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,OAAuB,EACvB,MAA6B;IAE7B,OAAO,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC3C,CAAC"}

package/dist/content/resolve.d.ts

@@ -0,0 +1,97 @@
+import type { CmsValidationIssue, CollectionDef, DocumentRef, Locale } from '@elytracms/core/cms-core';
+import type { AssetLookup } from './assets';
+import type { ContentContext, Perspective } from './context';
+import type { FieldLocaleFallback } from './locale';
+import type { ContentDocumentSource } from './perspective';
+/**
+ * Pure lookup boundary for delivery resolution (vision AD-4): the caller
+ * (content kit, export, tests) pre-fetches schema, documents, and asset
+ * metadata; resolution only reads through these synchronous functions. No
+ * fetching, no Convex, no React at this layer.
+ */
+export interface ContentLookup extends AssetLookup {
+    collection(id: string): CollectionDef | undefined;
+    document(ref: DocumentRef): ContentDocumentSource | undefined;
+    /**
+     * All document sources of a collection (EC-143, additive). Required by
+     * `listDocuments` and by `getDocument`'s slug fallback; a lookup without it
+     * still supports plain resolution, and `listDocuments` degrades to a
+     * structured `list-not-supported` error.
+     */
+    documents?(collectionId: string): readonly ContentDocumentSource[];
+}
+/**
+ * A document in delivery shape: identity plus resolved field values, flat —
+ * `post.title`, `post.author.name`, `post.cover.url`. The precise per-collection
+ * shape is what `generateDeliveryTypes` emits (EC-142 codegen).
+ */
+export type ResolvedDocument = {
+    id: string;
+    collection: string;
+} & Record<string, unknown>;
+/**
+ * The minimal structural face of any delivery-shaped document — what the typed
+ * accessors (EC-143) constrain their per-collection generics against. The
+ * generated interfaces from `generateDeliveryTypes` (e.g. `Post`) satisfy this
+ * where they cannot satisfy `ResolvedDocument`'s index signature.
+ */
+export interface DeliveryDocument {
+    id: string;
+    collection: string;
+}
+/**
+ * Structured information about *how* a document was resolved — most notably
+ * which fields served their value via EC-018 locale fallback.
+ */
+export interface ResolutionInfo {
+    locale: Locale;
+    perspective: Perspective;
+    localeFallbacks: FieldLocaleFallback[];
+}
+export interface ResolveDocumentResult {
+    /**
+     * The delivery-shaped document, or `null` when the source is not visible in
+     * the context perspective (e.g. never published) or its collection is
+     * unknown. `null` plus an empty issue list simply means "not available
+     * here" — unpublished content in the published perspective is correct
+     * behavior, not an error.
+     */
+    document: ResolvedDocument | null;
+    info: ResolutionInfo;
+    issues: CmsValidationIssue[];
+}
+/**
+ * Resolve one document source into delivery shape (vision AD-4): locale
+ * fallback applied (EC-018), draft/published perspective applied (EC-021),
+ * relations populated to depth-1 as declared in schema, and assets resolved to
+ * `{ url, width, height, alt, mimeType }` objects. Pure and total: invalid
+ * states surface as structured issues alongside the result — never thrown.
+ */
+export declare function resolveDocument(context: ContentContext, lookup: ContentLookup, source: ContentDocumentSource): ResolveDocumentResult;
+/** Result of populating a single relation reference (EC-254). */
+export interface PopulateRelationResult {
+    /**
+     * The relation target populated to depth-1 delivery shape (`{ id, collection,
+     * ...fields }`), or `null` when the target's collection is unknown, the
+     * document is missing, or it is not visible in the context perspective — so a
+     * consuming block degrades cleanly rather than rendering a stub.
+     */
+    document: ResolvedDocument | null;
+    issues: CmsValidationIssue[];
+}
+/**
+ * Populate a single relation reference to depth-1 delivery shape — the public
+ * entry a renderer host wires as `RenderContext.resolveRelation` to populate a
+ * COMPOSITION-NODE relation PROP (EC-254). This is distinct from a document
+ * FIELD relation, which {@link resolveDocument} already populates inline via the
+ * internal `resolveRelationTarget`: a page's `blocks` field passes through as raw
+ * composition, so the relation props of the nodes inside it (e.g. a ProductGrid's
+ * picked `product`s) are never touched by document resolution and need this.
+ *
+ * Mirrors `resolveRelationTarget`'s populated branch exactly — perspective gated
+ * (EC-021), relations inside the target stay stubs (depth-1), assets inside it
+ * resolve to objects — but returns `null` (not the `{ id, collection }` stub) on
+ * a miss, the cleaner "populated or nothing" contract a prop wants. Pure and
+ * total: never throws; the reason for a miss is collected as a structured issue.
+ */
+export declare function populateRelationRef(context: ContentContext, lookup: ContentLookup, ref: DocumentRef): PopulateRelationResult;