@astrale-os/kernel-dsl 0.2.0-beta.4 → 0.2.0-beta.41

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

@@ -0,0 +1,119 @@
+import { policyObjectOrigin, policyVariableClass } from '../../../language/index.js';
+import { BRANCH_OVERFLOW, MAX_BRANCHES, MAX_CHECK_DEPTH, MAX_CHECK_LEAVES, MAX_DOMAINS, MAX_EDGES, MAX_PATTERN_DEPTH, MAX_REPEAT, MAX_VARIABLES, measureChecks, } from '../../../language/policy/analysis/budgets.js';
+import { escapePointer } from './context.js';
+export { BRANCH_OVERFLOW, MAX_BRANCHES, MAX_CHECK_DEPTH, MAX_CHECK_LEAVES, MAX_DOMAINS, MAX_EDGES, MAX_PATTERN_DEPTH, MAX_REPEAT, MAX_VARIABLES, measureChecks, };
+export function validatePolicyBudgets(context) {
+    for (const name of Object.keys(context.environment.candidate.policies)) {
+        const measure = measurePolicy(context, name, new Set());
+        if (measure === undefined)
+            continue;
+        const pointer = `/policies/${escapePointer(name)}`;
+        if (measure.depth > MAX_PATTERN_DEPTH) {
+            context.add('PL_BUDGET', pointer, `Expanded Pattern depth ${measure.depth} exceeds ${MAX_PATTERN_DEPTH}.`);
+        }
+        if (measure.edgeCounts.length > MAX_BRANCHES) {
+            context.add('PL_BUDGET', pointer, `Expanded Pattern has more than ${MAX_BRANCHES} normalized branches.`);
+        }
+        const edgeMaximum = Math.max(0, ...measure.edgeCounts);
+        if (edgeMaximum > MAX_EDGES) {
+            context.add('PL_BUDGET', pointer, `A normalized branch contains ${edgeMaximum} graph predicates; the maximum is ${MAX_EDGES}.`);
+        }
+        if (measure.domains.size > MAX_DOMAINS) {
+            context.add('PL_BUDGET', pointer, `Expanded Pattern references ${measure.domains.size} Domains; the maximum is ${MAX_DOMAINS}.`);
+        }
+    }
+}
+function measurePolicy(context, name, visiting) {
+    if (visiting.has(name))
+        return undefined;
+    const declaration = context.normalized.get(name);
+    if (declaration === undefined)
+        return undefined;
+    const nested = new Set(visiting);
+    nested.add(name);
+    if ('match' in declaration) {
+        return measurePattern(declaration.match, context.environment.candidate.origin);
+    }
+    const refs = 'allOf' in declaration ? declaration.allOf : declaration.anyOf;
+    const children = refs.flatMap((ref) => {
+        if (!context.isLocalPolicy(ref))
+            return [];
+        const value = measurePolicy(context, 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);
+}
+function measurePattern(pattern, ownOrigin) {
+    if ('sameNode' in pattern)
+        return {
+            depth: 1,
+            edgeCounts: [1],
+            domains: new Set([
+                ownOrigin,
+                ...[pattern.sameNode.left, pattern.sameNode.right].flatMap((term) => term.kind === 'ref' ? [policyObjectOrigin(term.ref)] : []),
+            ]),
+        };
+    if (isEdge(pattern)) {
+        return {
+            depth: 1,
+            edgeCounts: [1],
+            domains: new Set([
+                ownOrigin,
+                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, ownOrigin);
+        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];
+                }),
+            ]),
+        };
+    }
+    const { key, values } = patternOperands(pattern);
+    return combineMeasures(key, values.map((child) => measurePattern(child, ownOrigin)));
+}
+function combineMeasures(key, children) {
+    const depth = 1 + Math.max(0, ...children.map((child) => child.depth));
+    const domains = new Set(children.flatMap((child) => [...child.domains]));
+    if (key === '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 };
+}
+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/context.d.ts

@@ -0,0 +1,28 @@
+import type { ClassDefinition } from '../../../language/class/model/class.js';
+import type { PolicyExpression } from '../../../language/policy/model/policy.js';
+import type { DefinitionAnalysisResult } from '../../analysis/class.js';
+import type { SchemaDiagnostic, SchemaDiagnosticCode } from '../../diagnostic.js';
+import type { DomainResolutionContext } from '../../resolution/context.js';
+import type { IndexedClassDefinition } from '../../resolution/definition.index.js';
+import { type ClassRef, type PolicyRef } from '../../../addressing/index.js';
+export declare class PolicyValidationContext {
+    #private;
+    readonly environment: DomainResolutionContext;
+    readonly analysis: DefinitionAnalysisResult;
+    readonly diagnostics: SchemaDiagnostic[];
+    readonly normalized: Map<string, PolicyExpression>;
+    readonly allNodeClasses: readonly ClassRef[];
+    readonly concreteNodeClasses: readonly ClassRef[];
+    constructor(environment: DomainResolutionContext, analysis: DefinitionAnalysisResult);
+    resolveNodeClass(ref: ClassRef, pointer: string): IndexedClassDefinition | undefined;
+    resolveEdge(ref: ClassRef, pointer: string): IndexedClassDefinition | undefined;
+    resolvePolicy(ref: PolicyRef, pointer: string): boolean;
+    isLocalPolicy(ref: PolicyRef): boolean;
+    edgeDeclaration(ref: ClassRef): Extract<ClassDefinition, {
+        readonly kind: 'edge';
+    }> | undefined;
+    /** Return true when candidate is the required Class or a same-kind descendant. */
+    classExtends(candidate: ClassRef, required: ClassRef): boolean;
+    add(code: SchemaDiagnosticCode, pointer: string, message: string, ref?: string): void;
+}
+export declare function escapePointer(value: string): string;

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

@@ -0,0 +1,89 @@
+import { Key } from '../../../addressing/index.js';
+import { definitionRefIndex } from '../../../addressing/ordering.js';
+import { diagnostic } from '../../diagnostic.js';
+const formatDefinitionRef = Key.of;
+export class PolicyValidationContext {
+    environment;
+    analysis;
+    diagnostics = [];
+    normalized = new Map();
+    allNodeClasses;
+    concreteNodeClasses;
+    #invalidPolicyRefs = new Set();
+    constructor(environment, analysis) {
+        this.environment = environment;
+        this.analysis = analysis;
+        const nodeClasses = [...environment.definitions.values()].filter((value) => value.ref.kind === 'class' && value.kind === 'node');
+        this.allNodeClasses = nodeClasses.map((value) => value.ref);
+        this.concreteNodeClasses = nodeClasses
+            .filter((value) => !value.declaration.abstract)
+            .map((value) => value.ref);
+    }
+    resolveNodeClass(ref, pointer) {
+        const resolved = this.environment.resolve(ref);
+        if (resolved === undefined || resolved.ref.kind !== 'class' || resolved.kind !== 'node') {
+            this.add('PL_REF', pointer, `${formatDefinitionRef(ref)} does not resolve to an owning/direct-dependency Node Class.`, formatDefinitionRef(ref));
+            return undefined;
+        }
+        return resolved;
+    }
+    resolveEdge(ref, pointer) {
+        const resolved = this.environment.resolve(ref);
+        if (resolved === undefined || resolved.ref.kind !== 'class' || resolved.kind !== 'edge') {
+            this.add('PL_REF', pointer, `${formatDefinitionRef(ref)} does not resolve to an owning/direct-dependency Edge Class.`, formatDefinitionRef(ref));
+            return undefined;
+        }
+        return resolved;
+    }
+    resolvePolicy(ref, pointer) {
+        const key = `${pointer}\u0000${definitionRefIndex(ref)}`;
+        if (this.#invalidPolicyRefs.has(key))
+            return false;
+        const declaration = this.environment.resolvePolicy(ref);
+        if (ref.origin !== this.environment.candidate.origin ||
+            ref.kind !== 'policy' ||
+            declaration === undefined) {
+            this.#invalidPolicyRefs.add(key);
+            this.add('PL_REF', pointer, `${formatDefinitionRef(ref)} is not an exact local named Policy ref.`, formatDefinitionRef(ref));
+            return false;
+        }
+        return true;
+    }
+    isLocalPolicy(ref) {
+        return (ref.origin === this.environment.candidate.origin &&
+            ref.kind === 'policy' &&
+            this.environment.candidate.policies[ref.name] !== undefined);
+    }
+    edgeDeclaration(ref) {
+        const resolved = this.environment.resolve(ref);
+        if (resolved === undefined || resolved.ref.kind !== 'class' || resolved.kind !== 'edge') {
+            return undefined;
+        }
+        return resolved.declaration;
+    }
+    /** Return true when candidate is the required Class or a same-kind descendant. */
+    classExtends(candidate, required) {
+        if (definitionRefIndex(candidate) === definitionRefIndex(required))
+            return true;
+        const visited = new Set();
+        const visit = (ref) => {
+            const key = definitionRefIndex(ref);
+            if (key === definitionRefIndex(required))
+                return true;
+            if (visited.has(key))
+                return false;
+            visited.add(key);
+            const resolved = this.environment.resolveAny(ref);
+            if (resolved === undefined || resolved.ref.kind !== 'class')
+                return false;
+            return resolved.declaration.extends.some(visit);
+        };
+        return visit(candidate);
+    }
+    add(code, pointer, message, ref) {
+        this.diagnostics.push(diagnostic(code, pointer, message, ref));
+    }
+}
+export function escapePointer(value) {
+    return value.replaceAll('~', '~0').replaceAll('/', '~1');
+}

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

@@ -0,0 +1,4 @@
+import type { PolicyObjectRef } from '../../../language/index.js';
+import type { PolicyValidationContext } from './context.js';
+import type { ObjectContract } from './typing.js';
+export declare function referenceContracts(validation: PolicyValidationContext, ref: PolicyObjectRef, pointer: string): readonly ObjectContract[] | undefined;

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

@@ -0,0 +1,71 @@
+import { definitionRefIndex } from '../../../addressing/ordering.js';
+import { isMethodExecutable } from '../../../language/callable/executable.js';
+import { policyObjectKey, policyObjectOrigin } from '../../../language/index.js';
+const KERNEL_ORIGIN = 'kernel.astrale.ai';
+const PROJECTION_CLASS = nodeClassRef('Class');
+const PROJECTION_FUNCTION = nodeClassRef('Function');
+const PROJECTION_POLICY = nodeClassRef('Policy');
+const PROJECTION_VIEW = nodeClassRef('View');
+export function referenceContracts(validation, ref, pointer) {
+    const candidate = validation.environment.candidate;
+    const local = policyObjectOrigin(ref) === candidate.origin;
+    const direct = Object.values(candidate.dependencies).some((entry) => entry.origin === policyObjectOrigin(ref));
+    const owner = local
+        ? candidate
+        : direct
+            ? validation.environment.dependencies.get(policyObjectOrigin(ref))
+            : undefined;
+    if (owner === undefined)
+        return invalidPolicyObjectRef(validation, ref, pointer);
+    switch (ref.kind) {
+        case 'class': {
+            const resolved = validation.environment.resolve(ref);
+            return resolved?.ref.kind === ref.kind
+                ? [{ kind: 'exact', ref: PROJECTION_CLASS }]
+                : invalidPolicyObjectRef(validation, ref, pointer);
+        }
+        case 'method': {
+            const declaringClass = owner.classes[ref.owner.name];
+            const method = declaringClass?.kind === 'node' ? declaringClass.methods[ref.name] : undefined;
+            return method === undefined || !isMethodExecutable(declaringClass, method)
+                ? invalidPolicyObjectRef(validation, ref, pointer)
+                : [{ kind: 'exact', ref: PROJECTION_FUNCTION }];
+        }
+        case 'function':
+            return owner.functions[ref.name] === undefined
+                ? invalidPolicyObjectRef(validation, ref, pointer)
+                : [{ kind: 'exact', ref: PROJECTION_FUNCTION }];
+        case 'policy':
+            return owner.policies[ref.name] === undefined
+                ? invalidPolicyObjectRef(validation, ref, pointer)
+                : [{ kind: 'exact', ref: PROJECTION_POLICY }];
+        case 'view':
+            return owner.views[ref.name] === undefined
+                ? invalidPolicyObjectRef(validation, ref, pointer)
+                : [{ kind: 'exact', ref: PROJECTION_VIEW }];
+        case 'core': {
+            const node = owner.core.nodes[ref.name];
+            if (node === undefined)
+                return invalidPolicyObjectRef(validation, ref, pointer);
+            const resolved = validation.environment.resolve(node.class);
+            const analyzed = validation.analysis.definitions.get(definitionRefIndex(node.class));
+            // Core validation owns invalid Core Class diagnostics. Avoid adding Policy noise for
+            // a Node that cannot materialize in the first place.
+            if (node.class.origin !== owner.origin ||
+                resolved?.ref.kind !== 'class' ||
+                resolved.kind !== 'node' ||
+                analyzed === undefined) {
+                return undefined;
+            }
+            return [{ kind: 'exact', ref: node.class }];
+        }
+    }
+    return invalidPolicyObjectRef(validation, ref, pointer);
+}
+function invalidPolicyObjectRef(validation, ref, pointer) {
+    validation.add('PL_REF', `${pointer}/ref`, `${policyObjectKey(ref)} is not an exact local or direct-dependency projected Policy object.`, policyObjectKey(ref));
+    return undefined;
+}
+function nodeClassRef(name) {
+    return { origin: KERNEL_ORIGIN, kind: 'class', name };
+}

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

@@ -0,0 +1,2 @@
+import type { PolicyValidationContext } from './context.js';
+export declare function validatePolicyReferences(context: PolicyValidationContext): void;

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

@@ -0,0 +1,155 @@
+import { branchesOf, isConnected, targetMode } from '../../../language/policy/analysis/branches.js';
+import { policyVariableClass } from '../../../language/policy/model/policy.js';
+import { normalizePolicyExpression, normalizePolicyPattern, } from '../../../language/policy/normalization/normalize.js';
+import { MAX_REPEAT, MAX_VARIABLES } from './budgets.js';
+import { escapePointer } from './context.js';
+import { referenceContracts } from './objects.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 at least one of 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, every referenced protected term, and every scoped term.`);
+        }
+    }
+}
+function validatePatternNode(context, pattern, pointer, scope, declarations, uses) {
+    if ('sameNode' in pattern) {
+        validateTerm(context, pattern.sameNode.left, `${pointer}/sameNode/left`, scope, uses);
+        validateTerm(context, pattern.sameNode.right, `${pointer}/sameNode/right`, scope, uses);
+        return;
+    }
+    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, { pointer: declarationPointer });
+            }
+            if (nested.has(id)) {
+                context.add('PL_VARIABLE_SCOPE', `${declarationPointer}/variable/id`, `Variable ${id} shadows an enclosing variable.`);
+            }
+            nested.add(id);
+            const classRef = policyVariableClass(node);
+            if (classRef !== undefined) {
+                context.resolveNodeClass(classRef, `${declarationPointer}/${'class' in node ? 'class' : 'selector/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 === 'ref')
+        referenceContracts(context, term.ref, pointer);
+    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;