@cornerstonejs/metadata 5.13.2 → 5.14.0

package/dist/esm/displayset/displaySetContext.js

@@ -0,0 +1,918 @@
+import { asArray, logging } from '@cornerstonejs/utils';
+import { at, collectReads, didYouMean, compileExpressionAt, FORBIDDEN_PROPERTIES, hasNoValue, hasOwn, invalidAt, isUnsafeKey, matchForm, parseExpressionSource, parseTemplate, readOwn, RuleCompileError, } from '../safeFunctions/index.js';
+import { keywordIgnoringCase, resolveHexFromKeyword } from '../utilities/Tags.js';
+import { sortInstancesCopy } from './sortInstances.js';
+import { instanceKey } from './seriesFunctions.js';
+import { bulkAnnotationSopClassUids, chartSopClassUids, ecgSopClassUids, encapsulatedDocumentSopClassUids, imageSopClassUids, longVideoMinFrames, longVideoSopClassUids, parametricMapSopClassUids, rtStructureSetSopClassUids, segmentationSopClassUids, structuredReportSopClassUids, videoSopClassUids, videoTransferSyntaxUids, wholeSlideSopClassUids, } from './sopClassUidLists.js';
+import { ATTRIBUTE_ONLY_NAMES, splitRuleSchema } from './splitRuleSchema.js';
+const log = logging.metadataLog.getLogger('displayset', 'displaySetContext');
+export const DISPLAY_SET_CONTEXT_FACT = 'displaySetContext';
+export const defaultMetadataContext = {
+    timeClustersMaxGap: 30,
+    timeClusters: {
+        function: 'timeClusters',
+        args: { maxGap: 'timeClustersMaxGap' },
+    },
+    longTimeClusters: { function: 'timeClusters', args: { maxGap: 60 } },
+    sweepCount: 'timeClusters.clusters',
+    sweepStart: 'timeClusters.start',
+    acquisitionSeconds: 'timeClusters.time',
+    sweepOffset: 'round(sweepStart - timeClusters.first)',
+    planeGeometryTolerance: 0.1,
+    planeGeometry: {
+        function: 'planeGeometry',
+        args: { tolerance: 'planeGeometryTolerance' },
+    },
+    sliceSpacing: 'planeGeometry.spacing',
+    sliceIndex: 'planeGeometry.index',
+    sliceDistance: 'planeGeometry.distance',
+    revisionChains: { function: 'revisionChains' },
+    revisionChainUid: 'revisionChains.active',
+    isActiveRevision: 'SOPInstanceUID == revisionChainUid',
+    seriesInstanceCount: 'series.instances.count()',
+    isMultiFrame: 'NumberOfFrames > 1',
+    imageId: { attribute: 'imageId' },
+    imageSopClassUids,
+    videoSopClassUids,
+    videoTransferSyntaxUids,
+    longVideoSopClassUids,
+    longVideoMinFrames,
+    ecgSopClassUids,
+    wholeSlideSopClassUids,
+    segmentationSopClassUids,
+    rtStructureSetSopClassUids,
+    parametricMapSopClassUids,
+    structuredReportSopClassUids,
+    encapsulatedDocumentSopClassUids,
+    bulkAnnotationSopClassUids,
+    chartSopClassUids,
+    isImage: 'SOPClassUID in imageSopClassUids',
+    transferSyntaxKnown: 'AvailableTransferSyntaxUID != null || TransferSyntaxUID != null',
+    isVideo: 'SOPClassUID in videoSopClassUids || ' +
+        'AvailableTransferSyntaxUID in videoTransferSyntaxUids || ' +
+        'TransferSyntaxUID in videoTransferSyntaxUids || ' +
+        '(!transferSyntaxKnown && SOPClassUID in longVideoSopClassUids && ' +
+        'NumberOfFrames >= longVideoMinFrames)',
+    isEcg: 'SOPClassUID in ecgSopClassUids',
+    isWsi: "SOPClassUID in wholeSlideSopClassUids || Modality == 'SM'",
+    isSegmentation: 'SOPClassUID in segmentationSopClassUids',
+    isRtStructureSet: 'SOPClassUID in rtStructureSetSopClassUids',
+    isParametricMap: 'SOPClassUID in parametricMapSopClassUids',
+    isStructuredReport: 'SOPClassUID in structuredReportSopClassUids',
+    isEncapsulatedDocument: 'SOPClassUID in encapsulatedDocumentSopClassUids',
+    isBulkAnnotation: 'SOPClassUID in bulkAnnotationSopClassUids',
+    isChart: 'SOPClassUID in chartSopClassUids',
+};
+const CONTEXT_NAME = /^[a-z][A-Za-z0-9_]*$/;
+const RESERVED_LITERALS = new Set([
+    'true',
+    'false',
+    'null',
+    'undefined',
+    'defined',
+]);
+const HEX_TAG = /^[0-9A-Fa-f]{8}$/;
+export function isTagKeyword(name) {
+    return resolveHexFromKeyword(name) !== undefined;
+}
+const DISPLAY_SETS_RESERVED = 'displaySets aggregates are not available yet; see https://github.com/cornerstonejs/cornerstone3D/issues/3000';
+const EXPRESSION_SCOPE = Object.freeze({
+    params: Object.freeze(['#values', '#instances']),
+    implicitScope: '#values',
+    receivers: Object.freeze({ series: '#instances' }),
+    unavailableReceivers: Object.freeze({
+        displaySet: 'displaySet.instances aggregates are available only in the { "expression" } form of attributes',
+        displaySets: DISPLAY_SETS_RESERVED,
+    }),
+});
+const ATTRIBUTE_EXPRESSION_SCOPE = Object.freeze({
+    params: Object.freeze(['#values', '#instances', '#displaySetInstances']),
+    implicitScope: '#values',
+    receivers: Object.freeze({
+        series: '#instances',
+        displaySet: '#displaySetInstances',
+    }),
+    unavailableReceivers: Object.freeze({ displaySets: DISPLAY_SETS_RESERVED }),
+});
+const RESERVED_RECEIVERS = new Set(['series', 'displaySet', 'displaySets']);
+const DISPLAY_SET_PLACES = new Set(['sortBy', 'attributes']);
+const DISPLAY_SET_PREFIX_ONLY = "the 'displaySet.' prefix is valid only in sortBy and attributes";
+let functionCount = 0;
+const functionIds = new WeakMap();
+function identityOf(raw) {
+    return JSON.stringify(raw, (_key, value) => {
+        if (typeof value !== 'function') {
+            return value;
+        }
+        let id = functionIds.get(value);
+        if (!id) {
+            id = `#function${++functionCount}`;
+            functionIds.set(value, id);
+        }
+        return id;
+    });
+}
+function unknownName(name, place, candidates) {
+    const suggestion = didYouMean(name, [
+        keywordIgnoringCase(name),
+        ...candidates,
+    ]);
+    if (suggestion) {
+        return `unknown name '${name}'${suggestion}`;
+    }
+    let hint;
+    if (HEX_TAG.test(name)) {
+        hint = `a hex tag needs a declaration in the context, e.g. "myValue": { "attribute": "${name}" }`;
+    }
+    else if (RESERVED_LITERALS.has(name)) {
+        hint = `'${name}' is a literal; write X == ${name} in a context entry`;
+    }
+    else if (/^[a-z]/.test(name)) {
+        hint = 'no context entry has this name';
+    }
+    else {
+        hint = `it is not a keyword of the DICOM dictionary; a private, vendor or synthetic attribute needs a declaration, e.g. "myValue": { "attribute": "${name}" }`;
+    }
+    const fixedText = place === 'attributes'
+        ? `; fixed text is { "template": ${JSON.stringify(name)} }`
+        : '';
+    return `unknown name '${name}': ${hint}${fixedText}`;
+}
+function checkContextName(name, site) {
+    if (isUnsafeKey(name) || FORBIDDEN_PROPERTIES.has(name)) {
+        invalidAt(site, `the context name "${name}" is not allowed`);
+    }
+    if (RESERVED_LITERALS.has(name) || RESERVED_RECEIVERS.has(name)) {
+        invalidAt(site, `'${name}' is reserved by the expression language, and cannot be a context name`);
+    }
+    if (isTagKeyword(name)) {
+        invalidAt(site, `the context name '${name}' is a DICOM keyword; a context cannot hide a value of the instance`);
+    }
+    if (!CONTEXT_NAME.test(name)) {
+        invalidAt(site, `the context name '${name}' must start with a lowercase letter, and hold only letters, digits and _`);
+    }
+    if (ATTRIBUTE_ONLY_NAMES.includes(name)) {
+        invalidAt(site, `'${name}' is a value of the display set, and cannot be a context name`);
+    }
+}
+function parseExpression(source, site, scope = EXPRESSION_SCOPE) {
+    const evaluate = compileExpressionAt(source, site, scope);
+    const ast = parseExpressionSource(source);
+    return {
+        evaluate,
+        reads: collectReads(ast, { aggregates: true }),
+        single: ast.type === 'identifier' ? ast.name : undefined,
+        ast,
+    };
+}
+function propertyReads(node) {
+    const found = [];
+    const walk = (current) => {
+        switch (current.type) {
+            case 'member':
+                found.push(current.property);
+                walk(current.object);
+                return;
+            case 'index':
+                if (current.index.type !== 'literal') {
+                    found.push(undefined);
+                }
+                else if (typeof current.index.value === 'string') {
+                    found.push(current.index.value);
+                }
+                walk(current.object);
+                walk(current.index);
+                return;
+            case 'call':
+                current.args.forEach(walk);
+                return;
+            case 'unary':
+                walk(current.argument);
+                return;
+            case 'binary':
+            case 'logical':
+                walk(current.left);
+                walk(current.right);
+                return;
+            case 'conditional':
+                walk(current.test);
+                walk(current.consequent);
+                walk(current.alternate);
+                return;
+            case 'array':
+                current.elements.forEach(walk);
+                return;
+            case 'template':
+                current.parts.forEach((part) => part.kind === 'expr' && walk(part.node));
+                return;
+        }
+    };
+    walk(node);
+    return found;
+}
+export function isFixedValue(raw, arrays = true) {
+    return (raw === null ||
+        typeof raw === 'boolean' ||
+        (typeof raw === 'number' && Number.isFinite(raw)) ||
+        (arrays && Array.isArray(raw)));
+}
+function copyFixedValue(raw) {
+    return Array.isArray(raw) ? [...raw] : raw;
+}
+function loopText(entries) {
+    return entries
+        .map(({ name, ruleId }) => ruleId === undefined ? name : `${name} (rule '${ruleId}')`)
+        .join(' -> ');
+}
+export function withInstances(series, instances) {
+    const values = readOwn(series, DISPLAY_SET_CONTEXT_FACT);
+    if (!(values instanceof DisplaySetContextValues)) {
+        return series;
+    }
+    const keyOf = (instance) => instanceKey(instance) ?? instance;
+    const known = new Set(values.instances.map(keyOf));
+    const added = instances.filter((instance) => !known.has(keyOf(instance)));
+    if (!added.length) {
+        return series;
+    }
+    return {
+        ...series,
+        [DISPLAY_SET_CONTEXT_FACT]: new DisplaySetContextValues(sortInstancesCopy([...values.instances, ...added])),
+    };
+}
+export class DisplaySetContextValues {
+    constructor(instances, seriesInstances = instances, split) {
+        this.instances = instances;
+        this.seriesInstances = seriesInstances;
+        this.split = split;
+        this.runtimes = new WeakMap();
+    }
+    runtime(program) {
+        let runtime = this.runtimes.get(program);
+        if (!runtime) {
+            runtime = new ContextRuntime(this.instances, this.seriesInstances, this.split?.runtime(program));
+            this.runtimes.set(program, runtime);
+        }
+        return runtime;
+    }
+}
+export function displaySetContextFor(series, instances) {
+    const values = readOwn(series, DISPLAY_SET_CONTEXT_FACT);
+    return values instanceof DisplaySetContextValues
+        ? new DisplaySetContextValues(instances, values.seriesInstances, values)
+        : new DisplaySetContextValues(instances);
+}
+export class ContextRuntime {
+    constructor(instances, seriesInstances = instances, split) {
+        this.instances = instances;
+        this.seriesInstances = seriesInstances;
+        this.split = split;
+        this.seriesValues = new Map();
+        this.instanceValues = new Map();
+        this.views = new Map();
+        this.envs = new Map();
+        this.instanceEnvs = new Map();
+        this.inProgress = [];
+    }
+    get seriesRuntime() {
+        return this.split ?? this;
+    }
+    value(bound, instance) {
+        if (bound.scope === 'series') {
+            if (this.split && !bound.perDisplaySet) {
+                return this.split.value(bound, undefined);
+            }
+            if (!this.seriesValues.has(bound.key)) {
+                this.seriesValues.set(bound.key, this.compute(bound, undefined));
+            }
+            return this.seriesValues.get(bound.key);
+        }
+        if (!instance) {
+            return undefined;
+        }
+        let values = this.instanceValues.get(instance);
+        if (!values) {
+            values = new Map();
+            this.instanceValues.set(instance, values);
+        }
+        if (!values.has(bound.key)) {
+            values.set(bound.key, this.compute(bound, instance));
+        }
+        return values.get(bound.key);
+    }
+    compute(bound, instance) {
+        const start = this.inProgress.findIndex((entry) => entry.bound === bound && entry.instance === instance);
+        if (start !== -1) {
+            const loop = [
+                ...this.inProgress.slice(start).map((entry) => entry.bound),
+                bound,
+            ];
+            throw new RuleCompileError('display set rules', bound.name, `Invalid display set rules: the context entries form a loop: ${loopText(loop)}`);
+        }
+        this.inProgress.push({ bound, instance });
+        try {
+            return bound.compute(this, instance);
+        }
+        finally {
+            this.inProgress.pop();
+        }
+    }
+    groupView(bound, instance) {
+        const result = this.value(bound, instance);
+        const fields = bound.group?.fields;
+        if (!instance || !fields || !result || typeof result !== 'object') {
+            return result;
+        }
+        let views = this.views.get(instance);
+        if (!views) {
+            views = new Map();
+            this.views.set(instance, views);
+        }
+        if (!views.has(bound.key)) {
+            const key = instanceKey(instance);
+            const view = Object.create(null);
+            for (const [field, scope] of Object.entries(fields)) {
+                const value = readOwn(result, field);
+                view[field] =
+                    scope === 'instance'
+                        ? key === undefined
+                            ? undefined
+                            : readOwn(value, key)
+                        : value;
+            }
+            views.set(bound.key, view);
+        }
+        return views.get(bound.key);
+    }
+    read(name, dependency, instance, extras) {
+        if (!dependency) {
+            return undefined;
+        }
+        switch (dependency.kind) {
+            case 'keyword':
+                return instance ? readOwn(instance, name) : undefined;
+            case 'attribute':
+                return readOwn(extras, name);
+            case 'entry':
+                return dependency.bound.group
+                    ? this.groupView(dependency.bound, instance)
+                    : this.value(dependency.bound, instance);
+            case 'series':
+                return this.seriesRuntime.read(name, dependency.inner, instance, extras);
+            case 'displaySet': {
+                const fields = Object.create(null);
+                dependency.fields.forEach((field, fieldName) => {
+                    fields[fieldName] = this.read(fieldName, field, instance, extras);
+                });
+                return fields;
+            }
+        }
+    }
+    env(bound, instance, extras, fresh = false) {
+        const cacheable = !extras && !fresh;
+        let byInstance = cacheable ? this.envs.get(bound.key) : undefined;
+        const cached = byInstance?.get(instance);
+        if (cached) {
+            return cached;
+        }
+        const env = new Proxy(Object.create(null), {
+            has: () => true,
+            get: (_target, name) => {
+                if (typeof name !== 'string') {
+                    return undefined;
+                }
+                const dependency = bound.deps.get(name) ??
+                    bound.layer?.dynamicDependency(name, bound.definition);
+                return this.read(name, dependency, instance, extras);
+            },
+        });
+        if (cacheable) {
+            if (!byInstance) {
+                byInstance = new Map();
+                this.envs.set(bound.key, byInstance);
+            }
+            byInstance.set(instance, env);
+        }
+        return env;
+    }
+    envsOf(bound, instances = this.seriesInstances, extras) {
+        if (extras || instances !== this.seriesInstances) {
+            return instances.map((instance) => this.env(bound, instance, extras));
+        }
+        if (this.split && !bound.perDisplaySet) {
+            return this.split.envsOf(bound, this.split.seriesInstances);
+        }
+        let envs = this.instanceEnvs.get(bound.key);
+        if (!envs) {
+            envs = instances.map((instance) => this.env(bound, instance));
+            this.instanceEnvs.set(bound.key, envs);
+        }
+        return envs;
+    }
+}
+export class ContextLayer {
+    constructor(program, ruleId, local) {
+        this.program = program;
+        this.ruleId = ruleId;
+        this.local = local;
+        this.memo = new Map();
+        this.dynamic = new Map();
+    }
+    resolve(name, from) {
+        if (from && from.ruleId !== undefined && from.name === name) {
+            return this.program.global.get(name);
+        }
+        return this.local.get(name) ?? this.program.global.get(name);
+    }
+    dynamicDependency(name, from) {
+        let byName = this.dynamic.get(from);
+        if (!byName) {
+            byName = new Map();
+            this.dynamic.set(from, byName);
+        }
+        if (!byName.has(name)) {
+            let dependency;
+            if (this.program.isDenied(name)) {
+                log.warn(`a code entry of the context read '${name}', which is on the deny list of the host; the read gives undefined`);
+            }
+            else if (isTagKeyword(name)) {
+                dependency = { kind: 'keyword' };
+            }
+            else {
+                const definition = this.resolve(name, from);
+                if (definition) {
+                    dependency = {
+                        kind: 'entry',
+                        bound: this.program.bind(definition, this, []),
+                    };
+                }
+                else if (ATTRIBUTE_ONLY_NAMES.includes(name)) {
+                    dependency = { kind: 'attribute' };
+                }
+            }
+            byName.set(name, dependency);
+        }
+        return byName.get(name);
+    }
+}
+export class ContextProgram {
+    constructor(context, options) {
+        this.global = new Map();
+        this.bounds = new Map();
+        this.fallbackLogged = false;
+        this.seriesHook = ({ instances, series }) => hasOwn(series, DISPLAY_SET_CONTEXT_FACT)
+            ? {}
+            : { [DISPLAY_SET_CONTEXT_FACT]: new DisplaySetContextValues(instances) };
+        this.seriesFunctions = options.seriesFunctions;
+        this.denied = new Set(options.deniedNames ?? []);
+        this.deniedTags = new Set([...this.denied].map(resolveHexFromKeyword).filter(Boolean));
+        for (const definition of this.parseLayer(context, options.site, undefined)) {
+            this.global.set(definition.name, definition);
+        }
+        this.empty = new ContextLayer(this, undefined, new Map());
+        for (const definition of this.global.values()) {
+            this.bind(definition, this.empty, []);
+        }
+    }
+    isDenied(name) {
+        return this.denied.has(name);
+    }
+    parseExpression(source, site, scope) {
+        const parsed = parseExpression(source, site, scope);
+        if (this.denied.size) {
+            for (const property of propertyReads(parsed.ast)) {
+                if (property === undefined) {
+                    invalidAt(site, 'a computed field name is not allowed when the host has a deny list; use a literal index, e.g. ViewCodeSequence[0].CodeValue');
+                }
+                if (this.denied.has(property)) {
+                    invalidAt(site, `the name '${property}' is on the deny list of the host, so no rule can read it`);
+                }
+            }
+        }
+        return parsed;
+    }
+    runtimeFrom(context, fallback) {
+        const displaySet = readOwn(context, 'displaySet');
+        if (displaySet instanceof DisplaySetContextValues) {
+            return displaySet.runtime(this);
+        }
+        const values = readOwn(readOwn(context, 'series'), DISPLAY_SET_CONTEXT_FACT);
+        if (values instanceof DisplaySetContextValues) {
+            return values.runtime(this);
+        }
+        if (!this.fallbackLogged) {
+            this.fallbackLogged = true;
+            log.debug('a split rule hook was called with no split context; its context values cover only the instances of the call');
+        }
+        return new DisplaySetContextValues(fallback ? asArray(fallback) : []).runtime(this);
+    }
+    instanceValue(name, instance) {
+        const definition = this.global.get(name);
+        if (!definition) {
+            throw new Error(`the metadata context has no entry '${name}'`);
+        }
+        const bound = this.bind(definition, this.empty, []);
+        if (bound.scope !== 'instance') {
+            throw new Error(`the context entry '${name}' has the series scope, so one instance cannot give its value`);
+        }
+        return new DisplaySetContextValues([instance])
+            .runtime(this)
+            .read(name, { kind: 'entry', bound }, instance);
+    }
+    layer(ruleId, context, site) {
+        if (context === undefined) {
+            return this.empty;
+        }
+        const local = new Map();
+        for (const definition of this.parseLayer(context, site, ruleId)) {
+            local.set(definition.name, definition);
+            log.debug(this.global.has(definition.name)
+                ? `rule '${ruleId}': the context entry '${definition.name}' replaces the global entry for this rule`
+                : `rule '${ruleId}': the context entry '${definition.name}' defines a new name for this rule`);
+        }
+        const layer = new ContextLayer(this, ruleId, local);
+        for (const definition of local.values()) {
+            this.bind(definition, layer, []);
+        }
+        return layer;
+    }
+    readerAt(layer, name, site, options = {}) {
+        const place = options.place ?? '';
+        let { field } = options;
+        let target = name;
+        const prefixed = name === 'displaySet' || name.startsWith('displaySet.');
+        if (prefixed) {
+            if (!DISPLAY_SET_PLACES.has(place)) {
+                invalidAt(site, DISPLAY_SET_PREFIX_ONLY);
+            }
+            const path = name.split('.').slice(1);
+            if (field !== undefined) {
+                path.push(field);
+            }
+            if (!path.length || path.length > 2 || path.some((part) => !part)) {
+                invalidAt(site, `'${name}' must be displaySet.<name> or displaySet.<name>.<field>, e.g. displaySet.sliceSpacing`);
+            }
+            [target, field] = path;
+        }
+        let dependency = this.dependencyOf({ name: target, field, inAggregate: false }, undefined, layer, [], site, place);
+        if (!prefixed && DISPLAY_SET_PLACES.has(place)) {
+            dependency = { kind: 'series', inner: dependency };
+        }
+        return (runtime, instance, extras) => {
+            const value = runtime.read(target, dependency, instance, extras);
+            return field === undefined ? value : readOwn(value, field);
+        };
+    }
+    attributeExpression(layer, source, site) {
+        const { evaluate, reads } = this.parseExpression(source, site, ATTRIBUTE_EXPRESSION_SCOPE);
+        const deps = new Map();
+        const displaySetFields = new Map();
+        for (const read of reads) {
+            if (read.name === 'displaySet') {
+                if (read.field === undefined) {
+                    invalidAt(site, "'displaySet' needs a name, e.g. displaySet.sliceSpacing");
+                }
+                displaySetFields.set(read.field, this.dependencyOf({ name: read.field, inAggregate: read.inAggregate }, undefined, layer, [], site, 'attributes'));
+                continue;
+            }
+            const dependency = this.dependencyOf(read, undefined, layer, [], site, 'attributes');
+            deps.set(read.name, { kind: 'series', inner: dependency });
+        }
+        if (displaySetFields.size) {
+            deps.set('displaySet', { kind: 'displaySet', fields: displaySetFields });
+        }
+        const perDisplaySet = displaySetFields.size > 0 ||
+            [...deps.values()].some((dependency) => dependency.kind === 'series' && dependency.inner.kind === 'attribute');
+        const scope = { key: `#attribute:${site.path}`, deps, perDisplaySet };
+        return (runtime, instances, extras) => evaluate(runtime.env(scope, instances[0], extras), perDisplaySet
+            ? runtime.envsOf(scope, runtime.seriesInstances, extras)
+            : runtime.envsOf(scope), runtime.envsOf(scope, instances, extras));
+    }
+    bind(definition, layer, stack) {
+        const memo = layer.memo.get(definition);
+        if (memo) {
+            return memo;
+        }
+        const loopStart = stack.indexOf(definition);
+        if (loopStart !== -1) {
+            const loop = [...stack.slice(loopStart), definition]
+                .map(({ name }) => name)
+                .join(' -> ');
+            return invalidAt(definition.site, `the context entries form a loop: ${loop}`);
+        }
+        stack.push(definition);
+        try {
+            const deps = new Map();
+            const closure = new Set();
+            if (definition.ruleId !== undefined) {
+                closure.add(definition.name);
+            }
+            if (definition.kind === 'code') {
+                layer.local.forEach((_entry, name) => closure.add(name));
+            }
+            let scope = definition.kind === 'declaration' || definition.kind === 'code'
+                ? 'instance'
+                : 'series';
+            for (const read of definition.reads) {
+                const dependency = this.dependencyOf(read, definition, layer, stack, definition.site, 'context');
+                deps.set(read.name, dependency);
+                if (dependency.kind === 'entry') {
+                    dependency.bound.closure.forEach((name) => closure.add(name));
+                }
+                if (!read.inAggregate && readsInstance(read, dependency)) {
+                    scope = 'instance';
+                }
+            }
+            if (definition.kind === 'group') {
+                for (const argument of definition.args) {
+                    const instanceRead = argument.reads.find((read) => !read.inAggregate && readsInstance(read, deps.get(read.name)));
+                    if (instanceRead) {
+                        invalidAt(at(at(definition.site, 'args'), argument.name), `the argument must have one value for the series, but '${instanceRead.name}' has one value for each instance`);
+                    }
+                }
+                scope = 'series';
+            }
+            const replaced = [...closure].sort();
+            const level = definition.ruleId === undefined ? '' : '@';
+            const key = replaced.length
+                ? `${level}${definition.name}{${replaced
+                    .map((name) => `${name}=${layer.local.get(name)?.identity}`)
+                    .join(',')}}`
+                : `${level}${definition.name}`;
+            let bound = this.bounds.get(key);
+            if (!bound) {
+                bound = this.createBound(definition, layer, key, scope, deps, closure);
+                this.bounds.set(key, bound);
+            }
+            layer.memo.set(definition, bound);
+            return bound;
+        }
+        finally {
+            stack.pop();
+        }
+    }
+    dependencyOf(read, from, layer, stack, site, place) {
+        const { name, field } = read;
+        if (this.denied.has(name)) {
+            return invalidAt(site, `the name '${name}' is on the deny list of the host, so no rule can read it`);
+        }
+        if (name === 'displaySet') {
+            return invalidAt(site, DISPLAY_SET_PREFIX_ONLY);
+        }
+        if (isTagKeyword(name)) {
+            if (field !== undefined) {
+                return invalidAt(site, `'${name}' is a DICOM keyword and has no field '${field}'; read an item of a sequence with an index, e.g. ${name}[0].${field}`);
+            }
+            return { kind: 'keyword' };
+        }
+        const definition = layer.resolve(name, from);
+        if (!definition) {
+            if (ATTRIBUTE_ONLY_NAMES.includes(name)) {
+                if (place === 'attributes') {
+                    return { kind: 'attribute' };
+                }
+                return invalidAt(site, `'${name}' is a value of the display set, and only attributes can read it`);
+            }
+            if (from && from.ruleId !== undefined && from.name === name) {
+                return invalidAt(site, `the rule entry '${name}' reads its own name, but the global context has no entry '${name}'`);
+            }
+            return invalidAt(site, unknownName(name, place, [
+                ...layer.local.keys(),
+                ...this.global.keys(),
+                ...ATTRIBUTE_ONLY_NAMES,
+            ]));
+        }
+        const bound = this.bind(definition, layer, stack);
+        if (read.indexed && bound.group) {
+            return invalidAt(site, `read a field of the group '${name}' by path, e.g. ${name}.${Object.keys(bound.group.fields ?? {})[0] ?? 'field'}`);
+        }
+        if (field !== undefined) {
+            if (!bound.group) {
+                return invalidAt(site, `'${name}' is not a group, so '${name}.${field}' reads nothing`);
+            }
+            const { fields } = bound.group;
+            if (fields && !hasOwn(fields, field)) {
+                return invalidAt(site, `the group '${name}' has no field '${field}'${didYouMean(field, Object.keys(fields))}; fields: ${Object.keys(fields).join(', ')}`);
+            }
+        }
+        return { kind: 'entry', bound };
+    }
+    createBound(definition, layer, key, scope, deps, closure) {
+        const bound = {
+            key,
+            name: definition.name,
+            scope,
+            deps,
+            closure,
+            ruleId: definition.ruleId,
+            perDisplaySet: definition.kind === 'code' ||
+                definition.kind === 'group' ||
+                [...deps.values()].some((dependency) => dependency.kind === 'entry' && dependency.bound.perDisplaySet),
+            compute: () => undefined,
+        };
+        switch (definition.kind) {
+            case 'fixed': {
+                const { value } = definition;
+                bound.compute = () => value;
+                break;
+            }
+            case 'declaration': {
+                const { attribute } = definition;
+                bound.compute = (_runtime, instance) => readOwn(instance, attribute);
+                break;
+            }
+            case 'code': {
+                const { fn } = definition;
+                bound.layer = layer;
+                bound.definition = definition;
+                bound.compute = (runtime, instance) => instance
+                    ? fn(instance, runtime.env(bound, instance, undefined, true))
+                    : undefined;
+                break;
+            }
+            case 'expression': {
+                const target = definition.aliasOf !== undefined
+                    ? deps.get(definition.aliasOf)
+                    : undefined;
+                if (target?.kind === 'entry' && target.bound.group) {
+                    const group = target.bound;
+                    bound.group = group.group;
+                    bound.scope = 'series';
+                    bound.compute = (runtime) => runtime.value(group, undefined);
+                    break;
+                }
+                const { evaluate } = definition;
+                bound.compute = (runtime, instance) => evaluate(runtime.env(bound, instance), runtime.envsOf(bound));
+                break;
+            }
+            case 'template': {
+                const parts = definition.segments.map((segment) => 'literal' in segment
+                    ? () => segment.literal
+                    : (runtime, instance) => {
+                        const value = runtime.read(segment.name, deps.get(segment.name), instance);
+                        return segment.field === undefined
+                            ? value
+                            : readOwn(value, segment.field);
+                    });
+                bound.compute = (runtime, instance) => parts
+                    .map((part) => {
+                    const value = part(runtime, instance);
+                    return hasNoValue(value) ? '' : String(value);
+                })
+                    .join('');
+                break;
+            }
+            case 'group': {
+                const { compute, args } = definition;
+                bound.group = { fields: definition.fields };
+                bound.compute = (runtime) => {
+                    const values = {};
+                    for (const argument of args) {
+                        values[argument.name] = argument.evaluate
+                            ? argument.evaluate(runtime.env(bound, undefined), runtime.envsOf(bound))
+                            : argument.fixed;
+                    }
+                    return compute(runtime.instances, {
+                        args: Object.freeze(values),
+                    });
+                };
+                break;
+            }
+        }
+        return bound;
+    }
+    parseLayer(context, site, ruleId) {
+        if (!context || typeof context !== 'object' || Array.isArray(context)) {
+            return invalidAt(site, 'expected an object of context entries, keyed by context name', context);
+        }
+        return Object.entries(context).map(([name, raw]) => {
+            const entrySite = at(site, name);
+            checkContextName(name, entrySite);
+            if (this.denied.has(name)) {
+                invalidAt(entrySite, `the context name '${name}' is on the deny list of the host`);
+            }
+            return this.parseEntry(name, raw, entrySite, ruleId);
+        });
+    }
+    parseEntry(name, raw, site, ruleId) {
+        const base = { name, ruleId, site, identity: identityOf(raw) };
+        if (typeof raw === 'function') {
+            return {
+                ...base,
+                kind: 'code',
+                reads: [],
+                fn: raw,
+            };
+        }
+        if (isFixedValue(raw)) {
+            return { ...base, kind: 'fixed', reads: [], value: copyFixedValue(raw) };
+        }
+        if (typeof raw === 'string') {
+            const { evaluate, reads, single } = this.parseExpression(raw, site);
+            return { ...base, kind: 'expression', reads, evaluate, aliasOf: single };
+        }
+        if (!raw || typeof raw !== 'object') {
+            return invalidAt(site, 'expected a fixed value (a number, a boolean, null or an array), an expression string, { attribute }, { template }, { function, args? }, or a function', raw);
+        }
+        const [form] = matchForm(splitRuleSchema.contextEntry, raw, site);
+        const fields = raw;
+        if (form === 'declaration') {
+            if (!fields.attribute) {
+                return invalidAt(at(site, 'attribute'), 'expected a non-empty string');
+            }
+            const attribute = String(fields.attribute);
+            if (this.denied.has(attribute) ||
+                this.deniedTags.has(attribute.replace(/^x/i, '').toUpperCase())) {
+                return invalidAt(at(site, 'attribute'), `the attribute '${attribute}' is on the deny list of the host, so no rule can read it`);
+            }
+            return {
+                ...base,
+                kind: 'declaration',
+                reads: [],
+                attribute: fields.attribute,
+                vr: fields.vr,
+                vm: fields.vm,
+            };
+        }
+        if (form === 'template') {
+            const segments = parseTemplate(fields.template, at(site, 'template'));
+            const reads = segments.flatMap((segment) => 'literal' in segment
+                ? []
+                : [{ name: segment.name, field: segment.field, inAggregate: false }]);
+            return { ...base, kind: 'template', reads, segments };
+        }
+        const definition = this.seriesFunctionOf(fields.function, at(site, 'function'));
+        const args = this.parseArguments(fields.args, at(site, 'args'));
+        return {
+            ...base,
+            kind: 'group',
+            reads: args.flatMap((argument) => argument.reads),
+            compute: definition.compute,
+            fields: definition.fields,
+            args,
+        };
+    }
+    seriesFunctionOf(value, site) {
+        if (typeof value === 'function') {
+            return { compute: value };
+        }
+        if (value &&
+            typeof value === 'object' &&
+            typeof value.compute === 'function') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const registered = readOwn(this.seriesFunctions, value);
+            if (typeof registered === 'function') {
+                return { compute: registered };
+            }
+            if (registered && typeof registered === 'object') {
+                return registered;
+            }
+        }
+        return invalidAt(site, `unknown series function ${JSON.stringify(value)}; known: ${Object.keys(this.seriesFunctions).join(', ') || '(none)'}`);
+    }
+    parseArguments(args, site) {
+        if (args === undefined) {
+            return [];
+        }
+        if (!args || typeof args !== 'object' || Array.isArray(args)) {
+            return invalidAt(site, 'expected an object of arguments', args);
+        }
+        return Object.entries(args).map(([name, raw]) => {
+            const argumentSite = at(site, name);
+            if (isUnsafeKey(name)) {
+                invalidAt(argumentSite, `the argument name "${name}" is not allowed`);
+            }
+            if (isFixedValue(raw)) {
+                return { name, fixed: copyFixedValue(raw), reads: [] };
+            }
+            if (typeof raw === 'string') {
+                const { evaluate, reads } = this.parseExpression(raw, argumentSite);
+                return { name, evaluate, reads };
+            }
+            return invalidAt(argumentSite, 'an argument is a fixed value (a number, a boolean, null or an array) or an expression string', raw);
+        });
+    }
+}
+function readsInstance(read, dependency) {
+    if (!dependency) {
+        return false;
+    }
+    switch (dependency.kind) {
+        case 'keyword':
+            return true;
+        case 'attribute':
+        case 'displaySet':
+            return false;
+        case 'series':
+            return readsInstance(read, dependency.inner);
+        case 'entry': {
+            const { bound } = dependency;
+            if (read.field !== undefined) {
+                return bound.group?.fields?.[read.field] === 'instance';
+            }
+            return bound.scope === 'instance';
+        }
+    }
+}