@nexia/sdk 0.5.0

package/dist/resource-composition.js

@@ -0,0 +1,576 @@
+export class CompositionSpecValidationError extends Error {
+    code;
+    path;
+    constructor(code, path, message) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.name = 'CompositionSpecValidationError';
+    }
+}
+/**
+ * Parses the stable wire shape. Resource, field, operator, relationship, grain,
+ * and authorization semantics remain live host-catalog decisions.
+ */
+export function parseCompositionSpec(value) {
+    const candidate = plainObject(value, '$');
+    const schemaVersion = candidate.schema_version;
+    if (schemaVersion !== 1 && schemaVersion !== 2 && schemaVersion !== 3 && schemaVersion !== 4) {
+        fail('unsupported_schema_version', 'schema_version', 'Resource Composition schema_version must be 1, 2, 3, or 4.');
+    }
+    if (schemaVersion === 4)
+        return parseV4(candidate);
+    const root = object(candidate, '$', schemaVersion === 1 ? [
+        'schema_version',
+        'sources',
+        'relationship',
+        'fields',
+        'filters',
+        'dimensions',
+        'measures',
+        'result',
+    ] : [
+        'schema_version',
+        'sources',
+        'relationships',
+        'fields',
+        'filters',
+        'dimensions',
+        'measures',
+        'result',
+    ]);
+    const sourceValues = list(root.sources, 'sources');
+    if ((schemaVersion === 1 && (sourceValues.length < 1 || sourceValues.length > 2))
+        || (schemaVersion === 2 && sourceValues.length !== 3)
+        || (schemaVersion === 3 && sourceValues.length < 2)) {
+        fail('invalid_source_count', 'sources', schemaVersion === 1
+            ? 'Resource Composition schema v1 requires one or two sources.'
+            : (schemaVersion === 2
+                ? 'Resource Composition schema v2 requires exactly three sources.'
+                : 'Resource Composition schema v3 requires at least two sources.'));
+    }
+    if (schemaVersion === 1 && sourceValues.length === 2 && root.relationship === null) {
+        fail('relationship_required', 'relationship', 'Two-source Resource Composition requires one relationship.');
+    }
+    if (schemaVersion === 1 && sourceValues.length === 1 && root.relationship !== null) {
+        fail('relationship_not_allowed', 'relationship', 'Single-source Resource Composition cannot declare a relationship.');
+    }
+    const sourceAliases = new Set();
+    const resourceKeys = new Set();
+    const sources = sourceValues.map((value, index) => {
+        const path = `sources.${index}`;
+        const source = object(value, path, ['alias', 'resource_key']);
+        const alias = identifier(source.alias, `${path}.alias`, ALIAS_PATTERN);
+        const resourceKey = identifier(source.resource_key, `${path}.resource_key`, RESOURCE_KEY_PATTERN);
+        if (sourceAliases.has(alias) || (schemaVersion !== 3 && resourceKeys.has(resourceKey))) {
+            fail('duplicate_identifier', path, schemaVersion === 3
+                ? 'Resource Composition source aliases must be unique.'
+                : 'Resource Composition source aliases and Resource keys must be unique.');
+        }
+        sourceAliases.add(alias);
+        resourceKeys.add(resourceKey);
+        return { alias, resource_key: resourceKey };
+    });
+    const aliases = sources.map(({ alias }) => alias);
+    const fields = parseSelections(root.fields, 'fields', aliases);
+    const filters = list(root.filters, 'filters').map((value, index) => {
+        const path = `filters.${index}`;
+        const filter = object(value, path, ['source', 'field', 'operator', 'value']);
+        const operator = oneOf(filter.operator, `${path}.operator`, ['eq', 'in'], 'invalid_filter_value');
+        const filterValue = operator === 'in'
+            ? scalarList(filter.value, `${path}.value`)
+            : scalar(filter.value, `${path}.value`);
+        return {
+            source: source(filter.source, aliases, `${path}.source`),
+            field: identifier(filter.field, `${path}.field`, FIELD_PATTERN),
+            operator,
+            value: filterValue,
+        };
+    });
+    const dimensions = [];
+    const dimensionKeys = new Set();
+    for (const [index, value] of list(root.dimensions, 'dimensions').entries()) {
+        const path = `dimensions.${index}`;
+        const dimension = object(value, path, ['source', 'field', 'bucket']);
+        const selectedSource = source(dimension.source, aliases, `${path}.source`);
+        const field = identifier(dimension.field, `${path}.field`, FIELD_PATTERN);
+        const bucket = dimension.bucket === null
+            ? null
+            : oneOf(dimension.bucket, `${path}.bucket`, ['day', 'week', 'month']);
+        const key = `${selectedSource}.${field}`;
+        if (dimensionKeys.has(key))
+            fail('duplicate_identifier', path, 'Resource Composition entries must be unique.');
+        dimensionKeys.add(key);
+        dimensions.push({ source: selectedSource, field, bucket });
+    }
+    const measures = [];
+    const measureAliases = new Set();
+    for (const [index, value] of list(root.measures, 'measures').entries()) {
+        const measure = parseMeasure(value, index, aliases, measureAliases);
+        measures.push(measure);
+    }
+    const resultValue = object(root.result, 'result', ['shape']);
+    const result = { shape: oneOf(resultValue.shape, 'result.shape', ['rows', 'aggregate']) };
+    assertResultShape(result.shape, fields, dimensions, measures);
+    const body = {
+        sources,
+        fields,
+        filters,
+        dimensions,
+        measures,
+        result,
+    };
+    if (schemaVersion === 1) {
+        return { schema_version: 1, ...body, relationship: parseRelationship(root.relationship) };
+    }
+    if (schemaVersion === 2) {
+        return { schema_version: 2, ...body, relationships: parseRelationships(root.relationships) };
+    }
+    return { schema_version: 3, ...body, relationships: parseGraphRelationships(root.relationships, aliases) };
+}
+function parseV4(candidate) {
+    const root = object(candidate, '$', ['schema_version', 'sources', 'relationships', 'fields', 'timezone', 'where', 'dimensions', 'measures', 'having', 'derived', 'comparison', 'sort', 'limit', 'result']);
+    let nodes = 0;
+    const boundedList = (value, path) => {
+        const values = list(value, path);
+        if (values.length > 100)
+            fail('invalid_shape', path, 'Resource Composition list is too large.');
+        return values;
+    };
+    const node = (path, depth = 0) => {
+        if (depth > 8 || ++nodes > 100)
+            fail('invalid_shape', path, 'Resource Composition is too complex.');
+    };
+    const scalarV4 = (value, path) => {
+        if ((typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') || (typeof value === 'number' && !Number.isFinite(value)) || (typeof value === 'string' && value.length > 512))
+            fail('invalid_filter_value', path, 'Resource Composition scalar is invalid.');
+        return value;
+    };
+    const target = (value, path, allowDerived = true) => {
+        const item = plainObject(value, path);
+        if (item.kind === 'field') {
+            object(item, path, ['kind', 'source', 'field']);
+            return { kind: 'field', source: source(item.source, aliases, `${path}.source`), field: identifier(item.field, `${path}.field`, FIELD_PATTERN) };
+        }
+        if (allowDerived && item.kind === 'derived') {
+            object(item, path, ['kind', 'alias']);
+            return { kind: 'derived', alias: identifier(item.alias, `${path}.alias`, ALIAS_PATTERN) };
+        }
+        fail('invalid_shape', `${path}.kind`, 'Resource Composition target is invalid.');
+    };
+    const predicate = (value, path, depth = 0, aggregate = false) => {
+        node(path, depth);
+        const item = plainObject(value, path);
+        const kind = item.kind;
+        if (kind === 'all' || kind === 'any') {
+            object(item, path, ['kind', 'children']);
+            return { kind, children: boundedList(item.children, `${path}.children`).map((child, index) => predicate(child, `${path}.children.${index}`, depth + 1, aggregate)) };
+        }
+        if (kind === 'not') {
+            object(item, path, ['kind', 'child']);
+            return { kind, child: predicate(item.child, `${path}.child`, depth + 1, aggregate) };
+        }
+        if (kind === 'relative_date') {
+            if (aggregate)
+                fail('invalid_shape', path, 'Aggregate predicates cannot use relative dates.');
+            object(item, path, ['kind', 'target', 'period']);
+            return { kind, target: target(item.target, `${path}.target`), period: oneOf(item.period, `${path}.period`, ['today', 'yesterday', 'this_week', 'last_week', 'this_month', 'last_month', 'this_quarter', 'last_quarter', 'this_year', 'last_year'], 'invalid_filter_value') };
+        }
+        if (kind !== 'condition')
+            fail('invalid_shape', `${path}.kind`, 'Resource Composition predicate is invalid.');
+        object(item, path, ['kind', 'target', 'operator', 'value']);
+        const operator = oneOf(item.operator, `${path}.operator`, ['eq', 'in', 'neq', 'not_in', 'gt', 'gte', 'lt', 'lte', 'between', 'is_null', 'not_null', 'contains', 'not_contains', 'starts_with', 'ends_with'], 'invalid_filter_value');
+        let predicateValue = item.value;
+        if (operator === 'in' || operator === 'not_in') {
+            const values = boundedList(item.value, `${path}.value`);
+            if (values.length === 0)
+                fail('invalid_filter_value', `${path}.value`, 'The in filter requires a non-empty scalar list.');
+            predicateValue = values.map((entry) => scalarV4(entry, `${path}.value`));
+        }
+        else if (operator === 'between') {
+            const bounds = object(item.value, `${path}.value`, ['from', 'to']);
+            scalarV4(bounds.from, `${path}.value.from`);
+            scalarV4(bounds.to, `${path}.value.to`);
+        }
+        else if (operator === 'is_null' || operator === 'not_null') {
+            if (item.value !== null)
+                fail('invalid_filter_value', `${path}.value`, 'Null predicate requires null.');
+        }
+        else
+            scalarV4(item.value, `${path}.value`);
+        if (!aggregate)
+            return { kind, target: target(item.target, `${path}.target`), operator, value: predicateValue };
+        const aggregateTarget = object(item.target, `${path}.target`, ['kind', 'alias']);
+        return { kind, target: { kind: oneOf(aggregateTarget.kind, `${path}.target.kind`, ['measure', 'derived']), alias: identifier(aggregateTarget.alias, `${path}.target.alias`, ALIAS_PATTERN) }, operator, value: predicateValue };
+    };
+    const sources = boundedList(root.sources, 'sources').map((value, index) => {
+        const item = object(value, `sources.${index}`, ['alias', 'resource_key']);
+        return { alias: identifier(item.alias, `sources.${index}.alias`, ALIAS_PATTERN), resource_key: identifier(item.resource_key, `sources.${index}.resource_key`, RESOURCE_KEY_PATTERN) };
+    });
+    if (sources.length === 0)
+        fail('invalid_source_count', 'sources', 'Resource Composition schema v4 requires at least one source.');
+    const aliases = sources.map((source) => source.alias);
+    if (new Set(aliases).size !== aliases.length)
+        fail('duplicate_identifier', 'sources', 'Resource Composition source aliases must be unique.');
+    const relationships = boundedList(root.relationships, 'relationships');
+    if (sources.length === 1 && relationships.length !== 0)
+        fail('relationship_not_allowed', 'relationships', 'Single-source Resource Composition cannot declare relationships.');
+    const parsedRelationships = sources.length === 1 ? [] : parseGraphRelationships(relationships, aliases);
+    const timezone = identifier(root.timezone, 'timezone', /^[A-Za-z_]+(?:\/[A-Za-z_+-]+)+$/);
+    const fields = boundedList(root.fields, 'fields').map((value, index) => {
+        node(`fields.${index}`);
+        const item = plainObject(value, `fields.${index}`);
+        if ('derived' in item) {
+            object(item, `fields.${index}`, ['derived']);
+            return { derived: identifier(item.derived, `fields.${index}.derived`, ALIAS_PATTERN) };
+        }
+        object(item, `fields.${index}`, ['source', 'field']);
+        return { source: source(item.source, aliases, `fields.${index}.source`), field: identifier(item.field, `fields.${index}.field`, FIELD_PATTERN) };
+    });
+    const where = predicate(root.where, 'where');
+    const dimensions = boundedList(root.dimensions, 'dimensions').map((value, index) => { node(`dimensions.${index}`); const item = object(value, `dimensions.${index}`, ['target', 'bucket']); return { target: target(item.target, `dimensions.${index}.target`), bucket: item.bucket === null ? null : oneOf(item.bucket, `dimensions.${index}.bucket`, ['day', 'week', 'month', 'quarter', 'year']) }; });
+    const measures = boundedList(root.measures, 'measures').map((value, index) => {
+        node(`measures.${index}`);
+        const path = `measures.${index}`;
+        const item = object(value, path, ['alias', 'source', 'field', 'operation', 'result_type', 'null_behavior', 'unit', 'where']);
+        const operation = oneOf(item.operation, `${path}.operation`, ['count', 'distinct_count', 'sum', 'avg', 'min', 'max', 'median'], 'invalid_measure');
+        const result_type = oneOf(item.result_type, `${path}.result_type`, ['integer', 'decimal'], 'invalid_measure');
+        const null_behavior = oneOf(item.null_behavior, `${path}.null_behavior`, ['zero', 'null_if_empty'], 'invalid_measure');
+        const unit = identifier(item.unit, `${path}.unit`, UNIT_PATTERN, 'invalid_measure');
+        if (operation === 'count' && item.field !== null) {
+            fail('invalid_measure', `${path}.field`, 'Count cannot have a field.');
+        }
+        if ((operation === 'count' || operation === 'distinct_count')
+            && (result_type !== 'integer' || null_behavior !== 'zero' || unit !== 'count')) {
+            fail('invalid_measure', path, 'Count measures require integer result, zero null behavior, and count unit.');
+        }
+        return {
+            alias: identifier(item.alias, `${path}.alias`, ALIAS_PATTERN),
+            source: source(item.source, aliases, `${path}.source`),
+            field: operation === 'count' ? null : target(item.field, `${path}.field`),
+            operation,
+            result_type,
+            null_behavior,
+            unit,
+            where: predicate(item.where, `${path}.where`),
+        };
+    });
+    if (new Set(measures.map((measure) => measure.alias)).size !== measures.length)
+        fail('duplicate_identifier', 'measures', 'Measure aliases must be unique.');
+    const measureAliases = new Set(measures.map((measure) => measure.alias));
+    const derived = boundedList(root.derived, 'derived').map((value, index) => { node(`derived.${index}`); const path = `derived.${index}`; const item = plainObject(value, path); const stage = oneOf(item.stage, `${path}.stage`, ['row', 'aggregate']); const required = stage === 'row' ? ['alias', 'stage', 'source', 'result_type', 'unit', 'null_behavior', 'expression'] : ['alias', 'stage', 'result_type', 'unit', 'expression']; object(item, path, required); return { ...item, alias: identifier(item.alias, `${path}.alias`, ALIAS_PATTERN), stage, ...(stage === 'row' ? { source: source(item.source, aliases, `${path}.source`) } : {}), expression: item.expression }; });
+    if (new Set(derived.map((entry) => entry.alias)).size !== derived.length)
+        fail('duplicate_identifier', 'derived', 'Derived aliases must be unique.');
+    const stages = new Map(derived.map((entry) => [entry.alias, entry.stage]));
+    dimensions.forEach((dimension, index) => { if (dimension.target.kind === 'derived' && stages.get(dimension.target.alias) !== 'row')
+        fail('invalid_identifier', `dimensions.${index}.target.alias`, 'Row derived dimension is unavailable.'); });
+    measures.forEach((measure, index) => { if (measure.field?.kind === 'derived' && stages.get(measure.field.alias) !== 'row')
+        fail('invalid_identifier', `measures.${index}.field.alias`, 'Row derived measure field is unavailable.'); });
+    const expression = (value, path, stage, depth = 0) => {
+        node(path, depth);
+        const item = plainObject(value, path);
+        const allowed = stage === 'row'
+            ? ['field', 'derived', 'literal', 'coalesce', 'date_diff_days', 'case', 'add', 'subtract', 'multiply', 'divide']
+            : ['measure', 'derived', 'literal', 'add', 'subtract', 'multiply', 'divide'];
+        const kind = oneOf(item.kind, `${path}.kind`, allowed);
+        if (kind === 'field') {
+            object(item, path, ['kind', 'source', 'field']);
+            return { kind, source: source(item.source, aliases, `${path}.source`), field: identifier(item.field, `${path}.field`, FIELD_PATTERN) };
+        }
+        if (kind === 'measure' || kind === 'derived') {
+            object(item, path, ['kind', 'alias']);
+            const alias = identifier(item.alias, `${path}.alias`, ALIAS_PATTERN);
+            if (kind === 'measure' && !measureAliases.has(alias))
+                fail('invalid_identifier', `${path}.alias`, 'Measure is unavailable.');
+            if (kind === 'derived' && stages.get(alias) !== stage)
+                fail('invalid_identifier', `${path}.alias`, 'Derived reference is unavailable.');
+            return { kind, alias };
+        }
+        if (kind === 'literal') {
+            object(item, path, ['kind', 'literal_type', 'value']);
+            const literalType = oneOf(item.literal_type, `${path}.literal_type`, ['number', 'string', 'boolean', 'null']);
+            const literal = item.value;
+            const invalidLiteral = (literalType === 'number' && (typeof literal !== 'number' || !Number.isFinite(literal)))
+                || (literalType === 'string' && (typeof literal !== 'string' || literal.length > 512))
+                || (literalType === 'boolean' && typeof literal !== 'boolean')
+                || (literalType === 'null' && literal !== null);
+            if (invalidLiteral)
+                fail('invalid_shape', `${path}.value`, 'Literal type does not match value.');
+            return { kind, literal_type: literalType, value: literal };
+        }
+        if (kind === 'coalesce') {
+            object(item, path, ['kind', 'values']);
+            return { kind, values: boundedList(item.values, `${path}.values`).map((child, index) => expression(child, `${path}.values.${index}`, stage, depth + 1)) };
+        }
+        if (kind === 'case') {
+            object(item, path, ['kind', 'branches', 'otherwise']);
+            return {
+                kind,
+                branches: boundedList(item.branches, `${path}.branches`).map((branch, index) => {
+                    const branchPath = `${path}.branches.${index}`;
+                    const parsedBranch = object(branch, branchPath, ['when', 'then']);
+                    return { when: predicate(parsedBranch.when, `${branchPath}.when`, depth + 1), then: expression(parsedBranch.then, `${branchPath}.then`, stage, depth + 1) };
+                }),
+                otherwise: expression(item.otherwise, `${path}.otherwise`, stage, depth + 1),
+            };
+        }
+        if (kind === 'date_diff_days') {
+            object(item, path, ['kind', 'start', 'end']);
+            return { kind, start: expression(item.start, `${path}.start`, stage, depth + 1), end: expression(item.end, `${path}.end`, stage, depth + 1) };
+        }
+        object(item, path, ['kind', 'left', 'right']);
+        return { kind, left: expression(item.left, `${path}.left`, stage, depth + 1), right: expression(item.right, `${path}.right`, stage, depth + 1) };
+    };
+    derived.forEach((entry, index) => { entry.expression = expression(entry.expression, `derived.${index}.expression`, entry.stage); });
+    const dependencies = new Map(derived.map((entry) => [entry.alias, []]));
+    const collectDependencies = (value, into) => {
+        if (value.kind === 'derived')
+            into.push(value.alias);
+        for (const key of ['left', 'right', 'start', 'end', 'otherwise'])
+            if (value[key] && typeof value[key] === 'object')
+                collectDependencies(value[key], into);
+        for (const item of (value.values ?? []))
+            collectDependencies(item, into);
+        for (const branch of (value.branches ?? []))
+            collectDependencies(branch.then, into);
+    };
+    derived.forEach((entry) => collectDependencies(entry.expression, dependencies.get(entry.alias)));
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (alias) => { if (visiting.has(alias))
+        fail('invalid_identifier', 'derived', 'Derived expressions cannot form a cycle.'); if (visited.has(alias))
+        return; visiting.add(alias); dependencies.get(alias).forEach(visit); visiting.delete(alias); visited.add(alias); };
+    dependencies.forEach((_, alias) => visit(alias));
+    const having = predicate(root.having, 'having', 0, true);
+    const validateHaving = (item, path) => {
+        if (item.kind === 'all' || item.kind === 'any') {
+            item.children.forEach((child, index) => validateHaving(child, `${path}.children.${index}`));
+            return;
+        }
+        if (item.kind === 'not') {
+            validateHaving(item.child, `${path}.child`);
+            return;
+        }
+        const aggregateTarget = item.target;
+        if ((aggregateTarget.kind !== 'measure' || !measureAliases.has(aggregateTarget.alias)) && (aggregateTarget.kind !== 'derived' || stages.get(aggregateTarget.alias) !== 'aggregate'))
+            fail('invalid_identifier', `${path}.target.alias`, 'Aggregate target is unavailable.');
+    };
+    validateHaving(having, 'having');
+    const comparison = root.comparison === null ? null : (() => {
+        node('comparison');
+        const item = object(root.comparison, 'comparison', ['kind', 'dimension', 'targets']);
+        const dimension = object(item.dimension, 'comparison.dimension', ['source', 'field', 'bucket']);
+        const targets = boundedList(item.targets, 'comparison.targets').map((value, index) => {
+            const path = `comparison.targets.${index}`;
+            const target = object(value, path, ['kind', 'alias']);
+            const kind = oneOf(target.kind, `${path}.kind`, ['measure', 'derived']);
+            const alias = identifier(target.alias, `${path}.alias`, ALIAS_PATTERN);
+            if ((kind === 'measure' && !measureAliases.has(alias)) || (kind === 'derived' && stages.get(alias) !== 'aggregate'))
+                fail('invalid_identifier', `${path}.alias`, 'Comparison target is unavailable.');
+            return { kind, alias };
+        });
+        if (!targets.length)
+            fail('invalid_shape', 'comparison.targets', 'Comparison requires targets.');
+        return { kind: oneOf(item.kind, 'comparison.kind', ['previous_period', 'previous_year']), dimension: { source: source(dimension.source, aliases, 'comparison.dimension.source'), field: identifier(dimension.field, 'comparison.dimension.field', FIELD_PATTERN), bucket: oneOf(dimension.bucket, 'comparison.dimension.bucket', ['day', 'week', 'month', 'quarter', 'year']) }, targets };
+    })();
+    const sort = boundedList(root.sort, 'sort').map((value, index) => { const path = `sort.${index}`; const item = object(value, path, ['target', 'direction', 'nulls']); const target = plainObject(item.target, `${path}.target`); const kind = oneOf(target.kind, `${path}.target.kind`, ['field', 'dimension', 'measure', 'derived']); if (kind === 'field' || kind === 'dimension') {
+        object(target, `${path}.target`, ['kind', 'source', 'field']);
+        return { target: { kind, source: source(target.source, aliases, `${path}.target.source`), field: identifier(target.field, `${path}.target.field`, FIELD_PATTERN) }, direction: oneOf(item.direction, `${path}.direction`, ['asc', 'desc']), nulls: oneOf(item.nulls, `${path}.nulls`, ['first', 'last']) };
+    } object(target, `${path}.target`, ['kind', 'alias']); const alias = identifier(target.alias, `${path}.target.alias`, ALIAS_PATTERN); if ((kind === 'measure' && !measureAliases.has(alias)) || (kind === 'derived' && !stages.has(alias)))
+        fail('invalid_identifier', `${path}.target.alias`, 'Sort target is unavailable.'); return { target: { kind, alias }, direction: oneOf(item.direction, `${path}.direction`, ['asc', 'desc']), nulls: oneOf(item.nulls, `${path}.nulls`, ['first', 'last']) }; });
+    const limit = root.limit === null ? null : object(root.limit, 'limit', ['count']);
+    if (limit !== null && (!Number.isInteger(limit.count) || limit.count < 1 || limit.count > 1000))
+        fail('invalid_shape', 'limit.count', 'Limit is invalid.');
+    const result = object(root.result, 'result', ['shape']);
+    const shape = oneOf(result.shape, 'result.shape', ['rows', 'aggregate']);
+    if (shape === 'rows' && (fields.length === 0 || dimensions.length || measures.length || derived.some((entry) => entry.stage !== 'row')))
+        fail('result_shape_mismatch', 'result.shape', 'Row results cannot declare aggregate constructs.');
+    if (shape === 'aggregate' && (fields.length || !measures.length))
+        fail('result_shape_mismatch', 'result.shape', 'Aggregate results require measures and cannot declare row fields.');
+    return { schema_version: 4, sources, relationships: parsedRelationships, fields, timezone, where, dimensions, measures, having, derived, comparison, sort, limit: limit, result: { shape } };
+}
+function parseRelationship(value) {
+    if (value === null)
+        return null;
+    const relationship = object(value, 'relationship', ['key']);
+    return {
+        key: identifier(relationship.key, 'relationship.key', RELATIONSHIP_KEY_PATTERN),
+    };
+}
+function parseRelationships(value) {
+    const values = list(value, 'relationships');
+    if (values.length !== 2) {
+        fail('relationship_required', 'relationships', 'Resource Composition schema v2 requires exactly two relationships.');
+    }
+    const seen = new Set();
+    const relationships = values.map((value, index) => {
+        const path = `relationships.${index}`;
+        const relationship = object(value, path, ['key']);
+        const key = identifier(relationship.key, `${path}.key`, RELATIONSHIP_KEY_PATTERN);
+        if (seen.has(key))
+            fail('duplicate_identifier', `${path}.key`, 'Resource Composition entries must be unique.');
+        seen.add(key);
+        return { key };
+    });
+    return relationships;
+}
+function parseGraphRelationships(value, aliases) {
+    const values = list(value, 'relationships');
+    if (values.length === 0) {
+        fail('relationship_required', 'relationships', 'Resource Composition schema v3 requires at least one relationship.');
+    }
+    const seen = new Set();
+    return values.map((value, index) => {
+        const path = `relationships.${index}`;
+        const relationship = object(value, path, ['key', 'source', 'target']);
+        const key = identifier(relationship.key, `${path}.key`, RELATIONSHIP_KEY_PATTERN);
+        const sourceAlias = source(relationship.source, aliases, `${path}.source`);
+        const targetAlias = source(relationship.target, aliases, `${path}.target`);
+        const identity = `${key}\0${sourceAlias}\0${targetAlias}`;
+        if (seen.has(identity))
+            fail('duplicate_identifier', path, 'Resource Composition entries must be unique.');
+        seen.add(identity);
+        return { key, source: sourceAlias, target: targetAlias };
+    });
+}
+function parseSelections(value, path, aliases) {
+    const selections = [];
+    const keys = new Set();
+    for (const [index, itemValue] of list(value, path).entries()) {
+        const itemPath = `${path}.${index}`;
+        const item = object(itemValue, itemPath, ['source', 'field']);
+        const selectedSource = source(item.source, aliases, `${itemPath}.source`);
+        const field = identifier(item.field, `${itemPath}.field`, FIELD_PATTERN);
+        const key = `${selectedSource}.${field}`;
+        if (keys.has(key))
+            fail('duplicate_identifier', itemPath, 'Resource Composition entries must be unique.');
+        keys.add(key);
+        selections.push({ source: selectedSource, field });
+    }
+    return selections;
+}
+function parseMeasure(value, index, aliases, seenAliases) {
+    const path = `measures.${index}`;
+    const measure = object(value, path, [
+        'alias',
+        'source',
+        'field',
+        'operation',
+        'result_type',
+        'null_behavior',
+        'unit',
+    ]);
+    const alias = identifier(measure.alias, `${path}.alias`, ALIAS_PATTERN);
+    if (seenAliases.has(alias))
+        fail('duplicate_identifier', `${path}.alias`, 'Resource Composition entries must be unique.');
+    seenAliases.add(alias);
+    const selectedSource = source(measure.source, aliases, `${path}.source`);
+    const operation = oneOf(measure.operation, `${path}.operation`, ['count', 'distinct_count', 'sum', 'avg'], 'invalid_measure');
+    const resultType = oneOf(measure.result_type, `${path}.result_type`, ['integer', 'decimal'], 'invalid_measure');
+    const nullBehavior = oneOf(measure.null_behavior, `${path}.null_behavior`, ['zero', 'null_if_empty'], 'invalid_measure');
+    const unit = identifier(measure.unit, `${path}.unit`, UNIT_PATTERN, 'invalid_measure');
+    let field;
+    if (operation === 'count') {
+        if (measure.field !== null || resultType !== 'integer' || nullBehavior !== 'zero' || unit !== 'count') {
+            fail('invalid_measure', path, 'Count measures require a null field, integer result, zero null behavior, and count unit.');
+        }
+        field = null;
+    }
+    else if (operation === 'distinct_count') {
+        field = identifier(measure.field, `${path}.field`, FIELD_PATTERN);
+        if (resultType !== 'integer' || nullBehavior !== 'zero' || unit !== 'count') {
+            fail('invalid_measure', path, 'Distinct count measures require a field, integer result, zero null behavior, and count unit.');
+        }
+    }
+    else {
+        field = identifier(measure.field, `${path}.field`, FIELD_PATTERN);
+        if (resultType !== 'decimal' || nullBehavior !== 'null_if_empty' || unit === 'count') {
+            fail('invalid_measure', path, 'Sum and avg measures require a field, decimal result, null_if_empty behavior, and a declared unit.');
+        }
+    }
+    return {
+        alias,
+        source: selectedSource,
+        field,
+        operation,
+        result_type: resultType,
+        null_behavior: nullBehavior,
+        unit,
+    };
+}
+function assertResultShape(shape, fields, dimensions, measures) {
+    if (shape === 'rows') {
+        if (fields.length === 0 || dimensions.length > 0 || measures.length > 0) {
+            fail('result_shape_mismatch', 'result.shape', 'Row results require fields and cannot declare dimensions or measures.');
+        }
+        return;
+    }
+    if (fields.length > 0 || measures.length === 0) {
+        fail('result_shape_mismatch', 'result.shape', 'Aggregate results require measures and cannot declare row fields.');
+    }
+}
+function object(value, path, keys) {
+    const record = plainObject(value, path);
+    for (const key of Object.keys(record)) {
+        if (!keys.includes(key)) {
+            fail('unknown_key', path === '$' ? key : `${path}.${key}`, 'Resource Composition contains an unknown key.');
+        }
+    }
+    for (const key of keys) {
+        if (!Object.hasOwn(record, key)) {
+            fail('invalid_shape', path === '$' ? key : `${path}.${key}`, 'Resource Composition is missing a required key.');
+        }
+    }
+    return record;
+}
+function plainObject(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        fail('invalid_shape', path, 'Resource Composition value must be an object.');
+    }
+    return value;
+}
+function list(value, path) {
+    if (!Array.isArray(value))
+        fail('invalid_shape', path, 'Resource Composition value must be a list.');
+    return value;
+}
+function source(value, aliases, path) {
+    const selected = identifier(value, path, ALIAS_PATTERN);
+    if (!aliases.includes(selected)) {
+        fail('unknown_source_alias', path, 'Resource Composition source alias is not declared.');
+    }
+    return selected;
+}
+function identifier(value, path, pattern, code = 'invalid_identifier') {
+    if (typeof value !== 'string' || !pattern.test(value)) {
+        fail(code, path, 'Resource Composition identifier is invalid.');
+    }
+    return value;
+}
+function oneOf(value, path, choices, code = 'invalid_shape') {
+    if (typeof value !== 'string' || !choices.includes(value)) {
+        fail(code, path, 'Resource Composition value is invalid.');
+    }
+    return value;
+}
+function scalar(value, path) {
+    if ((typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+        || (typeof value === 'number' && !Number.isFinite(value))) {
+        fail('invalid_filter_value', path, 'The eq filter value must be a scalar.');
+    }
+    return value;
+}
+function scalarList(value, path) {
+    const values = list(value, path);
+    if (values.length === 0)
+        fail('invalid_filter_value', path, 'The in filter requires a non-empty scalar list.');
+    return values.map((value) => scalar(value, path));
+}
+function fail(code, path, message) {
+    throw new CompositionSpecValidationError(code, path, message);
+}
+const ALIAS_PATTERN = /^[a-z][a-z0-9_]{0,31}$/;
+const FIELD_PATTERN = /^[a-z][a-z0-9_]{0,159}$/;
+const RELATIONSHIP_KEY_PATTERN = /^[a-z][a-z0-9_.-]{0,159}$/;
+const RESOURCE_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*\.[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
+const UNIT_PATTERN = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;

package/dist/resource-create-destination.d.ts

@@ -0,0 +1,17 @@
+export interface ResourceCreateDestinationRegistration {
+    /** Stable Resource key, independent of the owning App's route layout. */
+    resourceKey: string;
+    /** Canonical host route for creating the Resource. */
+    route: string;
+    /** Permissions the owner requires before offering a create action. */
+    requiredPermissions: readonly string[];
+    ownerAppKey?: string | null;
+}
+export interface ResourceCreateDestination extends ResourceCreateDestinationRegistration {
+    route: string;
+}
+export interface ResourceCreateDestinationRegistry {
+    register(registration: ResourceCreateDestinationRegistration): void;
+    resolve(resourceKey: string, query?: Readonly<Record<string, string>>): ResourceCreateDestination | null;
+    resetForTests(): void;
+}

package/dist/resource-create-destination.js

@@ -0,0 +1 @@
+export {};