@astrale-os/kernel-dsl 1.0.0-beta.2 → 1.0.0-beta.20

package/dist/v1/language/limits.js

@@ -0,0 +1,60 @@
+/**
+ * The limits of the V1 language, each defined once: every check of a source Schema, a Bundle or a
+ * compiled closure reads its bound here. Every limit is inclusive: a count equal to it is
+ * accepted, one more is refused. `schema.limits` publishes this object, and each rule of
+ * `schema.RULES` and `schema.values.RULES` that enforces some of them names them in `limits`.
+ */
+export const limits = Object.freeze({
+    /** Bounds of the dependency graph of one Domain (`DV_DEPENDENCY_LIMITS`). */
+    dependency: Object.freeze({
+        /** Direct dependencies one Domain declares. */
+        direct: 32,
+        /** Domains of a dependency closure, the Domain itself included. */
+        closure: 256,
+        /** Dependencies on the longest chain from a Domain: a direct dependency is at depth 1. */
+        depth: 32,
+    }),
+    /** Bounds of one I-Regexp in a value schema (`VS_REGEX_PORTABLE`), as RFC 9485 §8 allows. */
+    regexp: Object.freeze({
+        /** Code points of one source. */
+        maxCodePoints: 4096,
+        /** Groups nested in one another in one source. */
+        maxNesting: 32,
+        /** The greatest bound of a counted repetition `{n}` or `{n,m}`. */
+        maxRepeat: 1000,
+        /** States of one compiled machine; the counted-run form never expands and is not bounded. */
+        maxStates: 10_000,
+    }),
+    /**
+     * Bounds of the Policy language. A named Policy is measured once normalized and once each
+     * composition is expanded into the Policies it names; a check tree, the checks of a callable or
+     * of a Node Class rule, once normalized (`PL_BUDGET`). The structure bounds the others
+     * (`STRUCTURE_MAXIMUM`).
+     */
+    policy: Object.freeze({
+        /**
+         * Levels of a Policy pattern: an Edge or sameNode is one, and each allOf, anyOf, exists and
+         * composition adds one.
+         */
+        patternDepth: 4,
+        /**
+         * Branches of a Policy's normal form: an anyOf adds those of its operands, an allOf multiplies
+         * them.
+         */
+        normalizedBranches: 8,
+        /** Nodes one exists declares. */
+        variablesPerExists: 4,
+        /** Graph predicates, Edges and sameNode equalities, of one normalized branch. */
+        edgePredicates: 6,
+        /** The greatest bound of a repeated Edge. */
+        repetition: 3,
+        /** Domains a Policy names: its own, and the origin of every Class and object it references. */
+        referencedDomains: 4,
+        /** Levels of a check tree: a check or sameNode is one, and each allOf and anyOf adds one. */
+        checkDepth: 4,
+        /** Branches of a check tree: an anyOf adds those of its operands, an allOf multiplies them. */
+        checkBranches: 8,
+        /** Checks and sameNode equalities of a check tree. */
+        checkLeaves: 8,
+    }),
+});

package/dist/v1/language/policy/analysis/branches.d.ts

@@ -18,3 +18,11 @@ export declare function capBranches(values: readonly PatternBranch[]): readonly
 export declare function isConnected(branch: PatternBranch): boolean;
 export declare function targetMode(branch: PatternBranch): PolicyTargetMode | undefined;
 export declare function termKey(term: PolicyPatternTerm, namespace: string): string;
+/** Disjoint sets of term keys, merged by the equalities of one Policy branch. */
+export declare class UnionFind {
+    #private;
+    constructor(values: Iterable<string>);
+    add(value: string): void;
+    find(value: string): string;
+    join(left: string, right: string): void;
+}

package/dist/v1/language/policy/analysis/branches.js

@@ -146,7 +146,8 @@ function collectVariableClasses(pattern, namespace) {
 function variableKey(namespace, id) {
     return `variable:${namespace}:${id}`;
 }
-class UnionFind {
+/** Disjoint sets of term keys, merged by the equalities of one Policy branch. */
+export class UnionFind {
     #parents = new Map();
     constructor(values) {
         for (const value of values)

package/dist/v1/language/policy/analysis/budgets.d.ts

@@ -1,16 +1,49 @@
-import type { PolicyCheckExpression } from '../model/policy.js';
-export declare const MAX_PATTERN_DEPTH = 4;
-export declare const MAX_BRANCHES = 8;
-export declare const MAX_VARIABLES = 4;
-export declare const MAX_EDGES = 6;
-export declare const MAX_REPEAT = 3;
-export declare const MAX_DOMAINS = 4;
-export declare const MAX_CHECK_DEPTH = 4;
-export declare const MAX_CHECK_LEAVES = 8;
+import type { PolicyRef } from '../../../addressing/index.js';
+import type { PolicyCheckExpression, PolicyExpression } from '../model/policy.js';
+import { limits } from '../../limits.js';
+/** A key of `limits.policy`. */
+export type PolicyLimit = keyof typeof limits.policy;
+/**
+ * Where a count of Policy branches stops: one past its limit. Each branch count is exact up to its
+ * limit plus one and reads as that once it is over, so expansion stays bounded.
+ */
 export declare const BRANCH_OVERFLOW: number;
+/**
+ * What `PL_BUDGET` compares with `limits.policy` for one named Policy once normalized and each of
+ * its compositions expanded, every count under the key of its limit. The branch count stops one
+ * past its limit: it is exact up to that, and once it is over, `edgePredicates` reads the branches
+ * it counted only. The other counts are exact.
+ */
+export interface PolicyMeasure {
+    /** Levels of the expanded pattern. */
+    readonly patternDepth: number;
+    /** Branches of its normal form, at most `limits.policy.normalizedBranches + 1`. */
+    readonly normalizedBranches: number;
+    /** The most graph predicates, Edges and sameNode equalities, of one branch. */
+    readonly edgePredicates: number;
+    /** Domains the expanded pattern names, its own included. */
+    readonly referencedDomains: number;
+}
+/**
+ * What `PL_BUDGET` compares with `limits.policy` for one check tree once normalized, every count
+ * under the key of its limit. The branch count stops one past its limit; the other counts are
+ * exact.
+ */
 export interface CheckMeasure {
-    readonly depth: number;
-    readonly branches: number;
-    readonly leaves: number;
+    /** Levels of the tree. */
+    readonly checkDepth: number;
+    /** Branches of its normal form, at most `limits.policy.checkBranches + 1`. */
+    readonly checkBranches: number;
+    /** Checks and sameNode equalities of the tree. */
+    readonly checkLeaves: number;
 }
+/** The limits of `limits.policy` a measure exceeds, in the order the measure lists them. */
+export declare function exceededLimits<Measure extends PolicyMeasure | CheckMeasure>(measure: Measure): readonly (keyof Measure & PolicyLimit)[];
+/**
+ * Measure named Policies by their expanded branches, depth and referenced Domains. A Policy has no
+ * measure when it is not normalized, when its expansion reaches itself, or when a composition names
+ * a Policy `isLocal` refuses or one without a measure.
+ */
+export declare function policyMeasurer(origin: string, normalized: ReadonlyMap<string, PolicyExpression>, isLocal: (ref: PolicyRef) => boolean): (name: string) => PolicyMeasure | undefined;
+/** Measure one normalized check tree. */
 export declare function measureChecks(expression: PolicyCheckExpression): CheckMeasure;

package/dist/v1/language/policy/analysis/budgets.js

@@ -1,25 +1,139 @@
-export const MAX_PATTERN_DEPTH = 4;
-export const MAX_BRANCHES = 8;
-export const MAX_VARIABLES = 4;
-export const MAX_EDGES = 6;
-export const MAX_REPEAT = 3;
-export const MAX_DOMAINS = 4;
-export const MAX_CHECK_DEPTH = 4;
-export const MAX_CHECK_LEAVES = 8;
-export const BRANCH_OVERFLOW = MAX_BRANCHES + 1;
+import { limits } from '../../limits.js';
+import { policyObjectOrigin, policyVariableClass } from '../model/policy.js';
+/**
+ * Where a count of Policy branches stops: one past its limit. Each branch count is exact up to its
+ * limit plus one and reads as that once it is over, so expansion stays bounded.
+ */
+export const BRANCH_OVERFLOW = limits.policy.normalizedBranches + 1;
+const CHECK_BRANCH_OVERFLOW = limits.policy.checkBranches + 1;
+/** The limits of `limits.policy` a measure exceeds, in the order the measure lists them. */
+export function exceededLimits(measure) {
+    return Object.keys(measure).filter((limit) => measure[limit] > limits.policy[limit]);
+}
+/**
+ * Measure named Policies by their expanded branches, depth and referenced Domains. A Policy has no
+ * measure when it is not normalized, when its expansion reaches itself, or when a composition names
+ * a Policy `isLocal` refuses or one without a measure.
+ */
+export function policyMeasurer(origin, normalized, isLocal) {
+    // Measure every distinct composition node once. A node's expanded measure is independent of the
+    // path that reaches it (the only path-sensitive outcome, the back-edge `undefined`, already holds
+    // for every node on or reaching a composition cycle, regardless of entry), so caching the
+    // completed result by node identity turns path enumeration over the composition DAG into work
+    // linear in the number of nodes while preserving the exact measure.
+    const measures = new Map();
+    const measurePolicy = (name, visiting) => {
+        if (visiting.has(name))
+            return undefined;
+        if (measures.has(name))
+            return measures.get(name);
+        const declaration = normalized.get(name);
+        if (declaration === undefined)
+            return undefined;
+        const nested = new Set(visiting);
+        nested.add(name);
+        const measure = measureDeclaration(declaration, nested);
+        measures.set(name, measure);
+        return measure;
+    };
+    const measureDeclaration = (declaration, nested) => {
+        if ('match' in declaration)
+            return measurePattern(declaration.match, origin);
+        const refs = 'allOf' in declaration ? declaration.allOf : declaration.anyOf;
+        const children = refs.flatMap((ref) => {
+            if (!isLocal(ref))
+                return [];
+            const value = measurePolicy(ref.name, nested);
+            return value === undefined ? [] : [value];
+        });
+        if (children.length !== refs.length || children.length === 0)
+            return undefined;
+        return combineMeasures('allOf' in declaration ? 'allOf' : 'anyOf', children);
+    };
+    return (name) => {
+        const measure = measurePolicy(name, new Set());
+        return measure === undefined
+            ? undefined
+            : {
+                patternDepth: measure.depth,
+                normalizedBranches: measure.edgeCounts.length,
+                edgePredicates: Math.max(0, ...measure.edgeCounts),
+                referencedDomains: measure.domains.size,
+            };
+    };
+}
+function measurePattern(pattern, origin) {
+    if ('sameNode' in pattern)
+        return {
+            depth: 1,
+            edgeCounts: [1],
+            domains: new Set([
+                origin,
+                ...[pattern.sameNode.left, pattern.sameNode.right].flatMap((term) => term.kind === 'ref' ? [policyObjectOrigin(term.ref)] : []),
+            ]),
+        };
+    if ('source' in pattern)
+        return {
+            depth: 1,
+            edgeCounts: [1],
+            domains: new Set([
+                origin,
+                pattern.class.origin,
+                ...[pattern.source, pattern.target].flatMap((term) => term.kind === 'ref' ? [policyObjectOrigin(term.ref)] : []),
+            ]),
+        };
+    if ('exists' in pattern) {
+        const child = measurePattern(pattern.exists.where, origin);
+        return {
+            depth: child.depth + 1,
+            edgeCounts: child.edgeCounts,
+            domains: new Set([
+                ...child.domains,
+                ...pattern.exists.nodes.flatMap((node) => {
+                    const ref = policyVariableClass(node);
+                    return ref === undefined ? [] : [ref.origin];
+                }),
+            ]),
+        };
+    }
+    return combineMeasures('allOf' in pattern ? 'allOf' : 'anyOf', ('allOf' in pattern ? pattern.allOf : pattern.anyOf).map((child) => measurePattern(child, origin)));
+}
+function combineMeasures(kind, children) {
+    const depth = 1 + Math.max(0, ...children.map((child) => child.depth));
+    const domains = new Set(children.flatMap((child) => [...child.domains]));
+    if (kind === 'anyOf')
+        return {
+            depth,
+            edgeCounts: children.flatMap((child) => child.edgeCounts).slice(0, BRANCH_OVERFLOW),
+            domains,
+        };
+    let edgeCounts = [0];
+    for (const child of children) {
+        const next = [];
+        for (const left of edgeCounts) {
+            for (const right of child.edgeCounts) {
+                next.push(left + right);
+                if (next.length >= BRANCH_OVERFLOW)
+                    break;
+            }
+            if (next.length >= BRANCH_OVERFLOW)
+                break;
+        }
+        edgeCounts = next;
+    }
+    return { depth, edgeCounts, domains };
+}
+/** Measure one normalized check tree. */
 export function measureChecks(expression) {
     if ('check' in expression || 'sameNode' in expression)
-        return { depth: 1, branches: 1, leaves: 1 };
+        return { checkDepth: 1, checkBranches: 1, checkLeaves: 1 };
     const children = ('allOf' in expression ? expression.allOf : expression.anyOf).map(measureChecks);
-    const branches = 'allOf' in expression
-        ? children.reduce((value, child) => saturatingProduct(value, child.branches), 1)
-        : children.reduce((value, child) => Math.min(BRANCH_OVERFLOW, value + child.branches), 0);
+    const checkBranches = 'allOf' in expression
+        ? children.reduce((value, child) => Math.min(CHECK_BRANCH_OVERFLOW, value * child.checkBranches), 1)
+        : children.reduce((value, child) => Math.min(CHECK_BRANCH_OVERFLOW, value + child.checkBranches), 0);
     return {
-        depth: 1 + Math.max(0, ...children.map((child) => child.depth)),
-        branches,
-        leaves: children.reduce((value, child) => value + child.leaves, 0),
+        checkDepth: 1 + Math.max(0, ...children.map((child) => child.checkDepth)),
+        checkBranches,
+        checkLeaves: children.reduce((value, child) => value + child.checkLeaves, 0),
     };
 }
-function saturatingProduct(left, right) {
-    return Math.min(BRANCH_OVERFLOW, left * right);
-}

package/dist/v1/language/policy/analysis/checks.js

@@ -1,5 +1,6 @@
+import { limits } from '../../limits.js';
 import { policyObjectKey } from '../model/policy.js';
-import { MAX_BRANCHES, measureChecks } from './budgets.js';
+import { measureChecks } from './budgets.js';
 /** Names a callable check object. Every leaf over one object sees the same Node at runtime. */
 function checkObjectName(object) {
     if (object.kind === 'self')
@@ -36,7 +37,7 @@ export function admittedCheckClasses(typing) {
  * check budget is already refused, so it is not expanded.
  */
 export function neverAdmittedClasses(expression, leaves) {
-    if (measureChecks(expression).branches > MAX_BRANCHES)
+    if (measureChecks(expression).checkBranches > limits.policy.checkBranches)
         return [];
     const accepted = new Map();
     for (const [leaf, classes] of leaves)

package/dist/v1/language/policy/analysis/typing.d.ts

@@ -0,0 +1,51 @@
+import type { ClassRef, PolicyRef } from '../../../addressing/index.js';
+import type { EdgeContract } from '../../class/model/edge.js';
+import type { PolicyExpression, PolicyObjectRef } from '../model/policy.js';
+import type { CheckLeafClasses } from './checks.js';
+import { type ClassAncestry } from '../../class/inheritance.js';
+import { type PatternBranch } from './branches.js';
+export type ObjectContract = {
+    readonly kind: 'default';
+} | {
+    readonly kind: 'exact';
+    readonly ref: ClassRef;
+};
+export type PolicyUseContract = {
+    readonly kind: 'object';
+    readonly object: ObjectContract;
+} | {
+    readonly kind: 'edge';
+    readonly source: ObjectContract;
+    readonly target: ObjectContract;
+};
+/** What Policy typing reads of the closure it types against: source or compiled admission. */
+export interface PolicyTypingScope {
+    readonly normalized: ReadonlyMap<string, PolicyExpression>;
+    /** Each resolves, through `resolveClass`, to a Node Class. */
+    readonly allNodeClasses: readonly ClassRef[];
+    /** The concrete Classes of `allNodeClasses`, in its order. */
+    readonly concreteNodeClasses: readonly ClassRef[];
+    isLocalPolicy(ref: PolicyRef): boolean;
+    /** The Class a ref names in the closure, as satisfaction reads it. */
+    resolveClass(ref: ClassRef): ClassAncestry | undefined;
+    edgeDeclaration(ref: ClassRef): EdgeContract | undefined;
+    /** The contract of a Node a Policy pattern references, `undefined` when it has none. */
+    referenceContract(ref: PolicyObjectRef): ObjectContract | undefined;
+}
+export declare class PolicyTyping {
+    #private;
+    readonly scope: PolicyTypingScope;
+    constructor(scope: PolicyTypingScope);
+    /** The normalized branches of a named Policy, `undefined` when it does not expand. */
+    expandedBranches(name: string, namespace: string): readonly PatternBranch[] | undefined;
+    policyAccepts(name: string, object: ObjectContract): boolean;
+    /** Whether the Policy accepts every concrete source and target pair the Edge Class accepts. */
+    policyAcceptsEdgeClass(name: string, declaration: EdgeContract): boolean;
+    /**
+     * How a check of the Policy types against each contract of its object, `undefined` when the
+     * Policy does not expand or one of its branches is typed for no contract.
+     */
+    checkLeafClasses(name: string, contracts: readonly ObjectContract[]): CheckLeafClasses | undefined;
+    endpointsOverlap(left: readonly ClassRef[], right: readonly ClassRef[]): boolean;
+    branchIsTyped(branch: PatternBranch, use: PolicyUseContract): boolean;
+}