@astrale-os/kernel-dsl 0.1.5 → 0.2.0-beta.10

package/dist/v1/schema/validation/policy/references.js

@@ -0,0 +1,143 @@
+import { branchesOf, isConnected, targetMode } from '../../../language/policy/analysis/branches.js';
+import { normalizePolicyExpression, normalizePolicyPattern, } from '../../../language/policy/normalization/normalize.js';
+import { MAX_REPEAT, MAX_VARIABLES } from './budgets.js';
+import { escapePointer } from './context.js';
+export function validatePolicyReferences(context) {
+    for (const [name, declaration] of Object.entries(context.environment.candidate.policies)) {
+        const pointer = `/policies/${escapePointer(name)}`;
+        const expected = { origin: context.environment.candidate.origin, kind: 'policy', name };
+        if (declaration.ref.origin !== expected.origin ||
+            declaration.ref.kind !== expected.kind ||
+            declaration.ref.name !== expected.name) {
+            context.add('DV_REF_RESOLVES', `${pointer}/ref`, `Policy ref must be exactly ${expected.origin}:policy.${expected.name}.`);
+        }
+        const expression = declaration.expression;
+        context.normalized.set(name, normalizePolicyExpression(expression));
+        if ('match' in expression)
+            validateMatch(context, name, expression.match, pointer);
+        else
+            validateComposition(context, expression, pointer);
+    }
+    validateCycles(context);
+}
+function validateMatch(context, name, pattern, pointer) {
+    const declarations = new Map();
+    const uses = new Map();
+    validatePatternNode(context, pattern, `${pointer}/match`, new Set(), declarations, uses);
+    for (const [id, declaration] of declarations) {
+        if ((uses.get(id) ?? 0) === 0) {
+            context.add('PL_VARIABLE_SCOPE', declaration.pointer, `Variable ${id} is declared but never used.`);
+        }
+    }
+    const normalized = normalizePolicyPattern(pattern);
+    const branches = branchesOf(normalized, name);
+    for (const [index, branch] of branches.entries()) {
+        const mode = targetMode(branch);
+        if (mode === undefined) {
+            context.add('PL_TARGET', `${pointer}/match`, `Normalized branch ${index} must use object or both source and target, without mixing target modes.`);
+            continue;
+        }
+        if (!isConnected(branch)) {
+            context.add('PL_CONNECTIVITY', `${pointer}/match`, `Normalized ${mode} branch ${index} does not connect subject, its target terms, and every scoped term.`);
+        }
+    }
+}
+function validatePatternNode(context, pattern, pointer, scope, declarations, uses) {
+    if (isEdge(pattern)) {
+        context.resolveEdge(pattern.class, `${pointer}/class`);
+        validateTerm(context, pattern.source, `${pointer}/source`, scope, uses);
+        validateTerm(context, pattern.target, `${pointer}/target`, scope, uses);
+        if (pattern.repeat !== undefined) {
+            const { min, max } = pattern.repeat;
+            if (!Number.isInteger(min) ||
+                !Number.isInteger(max) ||
+                min < 0 ||
+                max < min ||
+                max > MAX_REPEAT) {
+                context.add('PL_REPEAT', `${pointer}/repeat`, `Repeat requires integral bounds 0 <= min <= max <= ${MAX_REPEAT}.`);
+            }
+        }
+        return;
+    }
+    if ('exists' in pattern) {
+        if (pattern.exists.nodes.length > MAX_VARIABLES) {
+            context.add('PL_BUDGET', `${pointer}/exists/nodes`, `An exists expression declares ${pattern.exists.nodes.length} variables; the maximum is ${MAX_VARIABLES}.`);
+        }
+        const nested = new Set(scope);
+        for (const [index, node] of pattern.exists.nodes.entries()) {
+            const id = node.variable.id;
+            const declarationPointer = `${pointer}/exists/nodes/${index}`;
+            if (declarations.has(id)) {
+                context.add('PL_VARIABLE_SCOPE', `${declarationPointer}/variable/id`, `Variable ${id} is declared more than once; variable IDs are globally unique.`);
+            }
+            else {
+                declarations.set(id, { ref: node.class, pointer: declarationPointer });
+            }
+            if (nested.has(id)) {
+                context.add('PL_VARIABLE_SCOPE', `${declarationPointer}/variable/id`, `Variable ${id} shadows an enclosing variable.`);
+            }
+            nested.add(id);
+            context.resolveNodeClass(node.class, `${declarationPointer}/class`);
+        }
+        validatePatternNode(context, pattern.exists.where, `${pointer}/exists/where`, nested, declarations, uses);
+        return;
+    }
+    const { key, values } = patternOperands(pattern);
+    if (values.length === 0) {
+        context.add('PL_COMPOSITION', `${pointer}/${key}`, `${key} must be non-empty.`);
+    }
+    values.forEach((child, index) => validatePatternNode(context, child, `${pointer}/${key}/${index}`, scope, declarations, uses));
+}
+function validateTerm(context, term, pointer, scope, uses) {
+    if (term.kind === 'variable') {
+        if (!scope.has(term.id)) {
+            context.add('PL_VARIABLE_SCOPE', pointer, `Variable ${term.id} is free, escaped, or outside its defining exists scope.`);
+        }
+        else {
+            uses.set(term.id, (uses.get(term.id) ?? 0) + 1);
+        }
+    }
+}
+function validateComposition(context, declaration, pointer) {
+    const key = 'allOf' in declaration ? 'allOf' : 'anyOf';
+    const refs = 'allOf' in declaration ? declaration.allOf : declaration.anyOf;
+    if (refs.length === 0) {
+        context.add('PL_COMPOSITION', `${pointer}/${key}`, `${key} must be non-empty.`);
+    }
+    refs.forEach((ref, index) => context.resolvePolicy(ref, `${pointer}/${key}/${index}`));
+}
+function validateCycles(context) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (name, stack) => {
+        if (visiting.has(name)) {
+            context.add('PL_COMPOSITION', `/policies/${escapePointer(name)}`, `Named Policy composition cycle: ${[...stack, name].join(' -> ')}.`);
+            return;
+        }
+        if (visited.has(name))
+            return;
+        visiting.add(name);
+        const declaration = context.environment.candidate.policies[name];
+        const expression = declaration?.expression;
+        if (expression !== undefined && !('match' in expression)) {
+            const refs = 'allOf' in expression ? expression.allOf : expression.anyOf;
+            for (const ref of refs) {
+                if (ref.origin === context.environment.candidate.origin && ref.kind === 'policy') {
+                    visit(ref.name, [...stack, name]);
+                }
+            }
+        }
+        visiting.delete(name);
+        visited.add(name);
+    };
+    for (const name of Object.keys(context.environment.candidate.policies))
+        visit(name, []);
+}
+function patternOperands(value) {
+    return 'allOf' in value
+        ? { key: 'allOf', values: value.allOf }
+        : { key: 'anyOf', values: value.anyOf };
+}
+function isEdge(value) {
+    return 'source' in value;
+}

package/dist/v1/schema/validation/policy/typing.d.ts

@@ -0,0 +1,19 @@
+import type { ClassRef } from '../../../addressing/index.js';
+import type { PolicyValidationContext } from './context.js';
+export type ObjectContract = {
+    readonly kind: 'default';
+} | {
+    readonly kind: 'exact';
+    readonly ref: ClassRef;
+};
+export declare class PolicyTyping {
+    #private;
+    readonly context: PolicyValidationContext;
+    constructor(context: PolicyValidationContext);
+    validatePolicies(): void;
+    policyAccepts(name: string, object: ObjectContract): boolean;
+    policyAcceptsEdge(name: string, source: ObjectContract, target: ObjectContract): boolean;
+    concreteEndpointClasses(accepts: readonly ClassRef[]): readonly ClassRef[];
+    endpointsOverlap(left: readonly ClassRef[], right: readonly ClassRef[]): boolean;
+}
+export declare function contractOfNodeDefinition(ref: ClassRef): ObjectContract;

package/dist/v1/schema/validation/policy/typing.js

@@ -0,0 +1,318 @@
+import { definitionRefIndex } from '../../../addressing/ordering.js';
+import { branchesOf, branchProduct, capBranches, targetMode, termKey, } from '../../../language/policy/analysis/branches.js';
+import { MAX_REPEAT } from './budgets.js';
+import { escapePointer } from './context.js';
+export class PolicyTyping {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    validatePolicies() {
+        for (const name of Object.keys(this.context.environment.candidate.policies)) {
+            const branches = this.#expandedBranches(name, new Set(), `$${name}`);
+            if (branches === undefined)
+                continue;
+            for (const [index, branch] of branches.entries()) {
+                const mode = targetMode(branch);
+                if (mode === undefined) {
+                    if (!('match' in this.context.environment.candidate.policies[name].expression)) {
+                        this.context.add('PL_TARGET', `/policies/${escapePointer(name)}`, `Expanded normalized branch ${index} must use object or both source and target, without mixing target modes.`);
+                    }
+                    continue;
+                }
+                const use = mode === 'object'
+                    ? { kind: 'object', object: { kind: 'default' } }
+                    : {
+                        kind: 'edge',
+                        source: { kind: 'default' },
+                        target: { kind: 'default' },
+                    };
+                if (!this.#branchIsTyped(branch, use)) {
+                    this.context.add('PL_TYPING', `/policies/${escapePointer(name)}`, `Expanded normalized branch ${index} has contradictory endpoint or repeat contracts.`);
+                }
+            }
+        }
+    }
+    policyAccepts(name, object) {
+        const branches = this.#expandedBranches(name, new Set(), `$use:${name}`);
+        const use = { kind: 'object', object };
+        return branches !== undefined && branches.every((branch) => this.#branchIsTyped(branch, use));
+    }
+    policyAcceptsEdge(name, source, target) {
+        const branches = this.#expandedBranches(name, new Set(), `$edge-use:${name}`);
+        const use = { kind: 'edge', source, target };
+        return branches !== undefined && branches.every((branch) => this.#branchIsTyped(branch, use));
+    }
+    concreteEndpointClasses(accepts) {
+        return this.context.concreteNodeClasses.filter((candidate) => this.#classSatisfiesEndpoint(candidate, accepts));
+    }
+    endpointsOverlap(left, right) {
+        const seed = [{ kind: 'open', requirements: [] }];
+        const afterLeft = this.#applyEndpoint(seed, left);
+        return this.#applyEndpoint(afterLeft, right).length > 0;
+    }
+    #expandedBranches(name, visiting, namespace) {
+        if (visiting.has(name))
+            return undefined;
+        const declaration = this.context.normalized.get(name);
+        if (declaration === undefined)
+            return undefined;
+        if ('match' in declaration)
+            return branchesOf(declaration.match, namespace);
+        const nested = new Set(visiting);
+        nested.add(name);
+        const refs = 'allOf' in declaration ? declaration.allOf : declaration.anyOf;
+        const children = [];
+        for (const [index, ref] of refs.entries()) {
+            if (!this.context.isLocalPolicy(ref))
+                return undefined;
+            const expanded = this.#expandedBranches(ref.name, nested, `${namespace}/${index}:${ref.name}`);
+            if (expanded === undefined)
+                return undefined;
+            children.push(expanded);
+        }
+        return 'allOf' in declaration ? branchProduct(children) : capBranches(children.flat());
+    }
+    #branchIsTyped(branch, use) {
+        if (targetMode(branch) !== use.kind)
+            return false;
+        const alternatives = edgeAlternatives(branch.edges, this);
+        return alternatives.some((variants) => this.#constraintsAreSatisfiable(branch, variants, use));
+    }
+    #constraintsAreSatisfiable(branch, variants, use) {
+        const terms = new Set(use.kind === 'object' ? ['subject', 'object'] : ['subject', 'source', 'target']);
+        for (const key of branch.variables.keys())
+            terms.add(key);
+        for (const edge of branch.edges) {
+            terms.add(termKey(edge.pattern.source, edge.namespace));
+            terms.add(termKey(edge.pattern.target, edge.namespace));
+        }
+        const union = new UnionFind(terms);
+        for (const variant of variants) {
+            for (const [left, right] of variant.equalities)
+                union.join(left, right);
+        }
+        const constraints = new Map();
+        for (const variant of variants) {
+            for (const [term, accepts] of variant.constraints) {
+                const root = union.find(term);
+                const values = constraints.get(root) ?? [];
+                values.push(accepts);
+                constraints.set(root, values);
+            }
+        }
+        const groups = new Map();
+        for (const term of terms) {
+            const root = union.find(term);
+            const members = groups.get(root) ?? [];
+            members.push(term);
+            groups.set(root, members);
+        }
+        for (const [root, members] of groups) {
+            const endpointConstraints = constraints.get(root) ?? [];
+            let candidates = [{ kind: 'open', requirements: [] }];
+            for (const member of members) {
+                candidates = this.#applyInitial(candidates, member, branch, use);
+                if (candidates.length === 0)
+                    return false;
+            }
+            for (const endpoint of endpointConstraints) {
+                candidates = this.#applyEndpoint(candidates, endpoint);
+                if (candidates.length === 0)
+                    return false;
+            }
+        }
+        return true;
+    }
+    #applyInitial(candidates, term, branch, use) {
+        if (term === 'subject')
+            return this.#applyAnyNodeClass(candidates);
+        const contract = targetContract(term, use);
+        if (contract !== undefined) {
+            if (contract.kind === 'exact')
+                return this.#applyExact(candidates, contract.ref);
+            if (contract.kind === 'default') {
+                return uniqueCandidates(this.context.allNodeClasses.flatMap((ref) => this.#applyExact(candidates, ref)));
+            }
+            return candidates;
+        }
+        const exact = this.#exactInitial(term, branch);
+        return exact === undefined ? [] : this.#applyExact(candidates, exact);
+    }
+    #exactInitial(term, branch) {
+        return branch.variables.get(term);
+    }
+    #applyExact(candidates, exact) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (definitionRefIndex(candidate.ref) === definitionRefIndex(exact))
+                    result.push(candidate);
+            }
+            else if (candidate.requirements.every((required) => this.context.classExtends(exact, required))) {
+                result.push({ kind: 'exact', ref: exact });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #applyAnyNodeClass(candidates) {
+        return uniqueCandidates(candidates.flatMap((candidate) => candidate.kind === 'exact'
+            ? [candidate]
+            : this.context.allNodeClasses
+                .filter((ref) => candidate.requirements.every((required) => this.context.classExtends(ref, required)))
+                .map((ref) => ({ kind: 'exact', ref }))));
+    }
+    #applyEndpoint(candidates, accepts) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (this.#classSatisfiesEndpoint(candidate.ref, accepts))
+                    result.push(candidate);
+                continue;
+            }
+            for (const accept of accepts) {
+                result.push({
+                    kind: 'open',
+                    requirements: uniqueClasses([...candidate.requirements, accept]),
+                });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #classSatisfiesEndpoint(candidate, accepts) {
+        return accepts.some((accept) => this.context.classExtends(candidate, accept));
+    }
+}
+function targetContract(term, use) {
+    if (use.kind === 'object')
+        return term === 'object' ? use.object : undefined;
+    if (term === 'source')
+        return use.source;
+    if (term === 'target')
+        return use.target;
+    return undefined;
+}
+export function contractOfNodeDefinition(ref) {
+    return { kind: 'exact', ref };
+}
+function edgeAlternatives(edges, typing) {
+    let result = [[]];
+    for (const edge of edges) {
+        const variants = variantsForEdge(edge, typing);
+        if (variants.length === 0)
+            return [];
+        const next = [];
+        for (const prefix of result) {
+            for (const variant of variants)
+                next.push([...prefix, variant]);
+        }
+        result = next;
+    }
+    return result;
+}
+function variantsForEdge(use, typing) {
+    const edge = use.pattern;
+    const declaration = typing.context.edgeDeclaration(edge.class);
+    if (declaration === undefined)
+        return [];
+    const endpoints = declaration.orientation === 'directed'
+        ? [declaration.endpoints.source, declaration.endpoints.target]
+        : declaration.endpoints;
+    const bounds = edge.repeat ?? { min: 1, max: 1 };
+    if (!Number.isInteger(bounds.min) ||
+        !Number.isInteger(bounds.max) ||
+        bounds.min < 0 ||
+        bounds.max < bounds.min ||
+        bounds.max > MAX_REPEAT) {
+        return [];
+    }
+    const sourceKey = termKey(edge.source, use.namespace);
+    const targetKey = termKey(edge.target, use.namespace);
+    const variants = [];
+    for (let length = bounds.min; length <= bounds.max; length++) {
+        if (length === 0) {
+            variants.push({ constraints: [], equalities: [[sourceKey, targetKey]] });
+            continue;
+        }
+        const orientationCount = declaration.orientation === 'undirected' ? 2 ** length : 1;
+        for (let mask = 0; mask < orientationCount; mask++) {
+            const orientations = Array.from({ length }, (_, index) => declaration.orientation === 'undirected' && (mask & (1 << index)) !== 0);
+            let transitionsValid = true;
+            for (let index = 0; index + 1 < length; index++) {
+                const incoming = endEndpoint(endpoints, orientations[index] ?? false);
+                const outgoing = startEndpoint(endpoints, orientations[index + 1] ?? false);
+                if (!typing.endpointsOverlap(incoming.accepts, outgoing.accepts)) {
+                    transitionsValid = false;
+                    break;
+                }
+            }
+            if (!transitionsValid)
+                continue;
+            const first = startEndpoint(endpoints, orientations[0] ?? false);
+            const last = endEndpoint(endpoints, orientations[length - 1] ?? false);
+            variants.push({
+                constraints: [
+                    [sourceKey, first.accepts],
+                    [targetKey, last.accepts],
+                ],
+                equalities: [],
+            });
+        }
+    }
+    return uniqueEdgeVariants(variants);
+}
+function startEndpoint(endpoints, reversed) {
+    return reversed ? endpoints[1] : endpoints[0];
+}
+function endEndpoint(endpoints, reversed) {
+    return reversed ? endpoints[0] : endpoints[1];
+}
+function uniqueEdgeVariants(values) {
+    const result = new Map();
+    for (const value of values) {
+        const key = `${value.constraints
+            .map(([term, accepts]) => `${term}:${accepts.map(definitionRefIndex).sort().join(',')}`)
+            .join('|')}=${value.equalities.map(([left, right]) => `${left}:${right}`).join('|')}`;
+        result.set(key, value);
+    }
+    return [...result.values()];
+}
+function uniqueCandidates(values) {
+    const result = new Map();
+    for (const value of values) {
+        const key = value.kind === 'exact'
+            ? `exact:${definitionRefIndex(value.ref)}`
+            : `open:${value.requirements.map(definitionRefIndex).sort().join('|')}`;
+        result.set(key, value);
+    }
+    return [...result.values()];
+}
+function uniqueClasses(values) {
+    return [...new Map(values.map((value) => [definitionRefIndex(value), value])).values()];
+}
+class UnionFind {
+    #parents = new Map();
+    constructor(values) {
+        for (const value of values)
+            this.add(value);
+    }
+    add(value) {
+        if (!this.#parents.has(value))
+            this.#parents.set(value, value);
+    }
+    find(value) {
+        this.add(value);
+        const parent = this.#parents.get(value);
+        if (parent === value)
+            return value;
+        const root = this.find(parent);
+        this.#parents.set(value, root);
+        return root;
+    }
+    join(left, right) {
+        const a = this.find(left);
+        const b = this.find(right);
+        if (a !== b)
+            this.#parents.set(b, a);
+    }
+}

package/dist/v1/schema/validation/policy/uses.d.ts

@@ -0,0 +1,5 @@
+import type { PolicyValidationContext } from './context.js';
+import { type PolicyTyping } from './typing.js';
+export declare function validateReadUses(context: PolicyValidationContext, typing: PolicyTyping): void;
+export declare function validateTraverseUses(context: PolicyValidationContext, typing: PolicyTyping): void;
+export declare function validateCallableUses(context: PolicyValidationContext, typing: PolicyTyping): void;