@astrale-os/kernel-dsl 1.0.0-beta.12 → 1.0.0-beta.13

package/dist/v1/language/core/facts.d.ts

@@ -0,0 +1,72 @@
+import type { ClassRef } from '../../addressing/index.js';
+import type { EdgeContract, EdgeCount, EdgeEndpointBase, IncidentEndpoint } from '../class/model/edge.js';
+/** One endpoint of a Core Edge: a Core Node, a projected member or the owning Domain. */
+export interface CoreFactEndpoint {
+    readonly key: string;
+    /** Set on a projected member: its Kernel Class, and where a breach of its degree is reported. */
+    readonly member?: {
+        readonly class: ClassRef;
+        readonly pointer: string;
+    };
+}
+/** One Core Edge whose endpoints satisfy its exact Class. */
+export interface CoreFactEdge<Edge> {
+    readonly edge: Edge;
+    /** The exact Class's key, as `CoreEdgeSet.classes` names it. */
+    readonly class: string;
+    readonly contract: EdgeContract;
+    readonly source: CoreFactEndpoint;
+    readonly target: CoreFactEndpoint;
+}
+/** One declared Core Node. It proves its own complete degree, so both bounds hold. */
+export interface CoreDegreeSubject {
+    readonly key: string;
+    readonly class: ClassRef;
+    readonly pointer: string;
+}
+export interface CoreEdgeSet<Edge> {
+    readonly edges: readonly CoreFactEdge<Edge>[];
+    /** The local exact Edge Classes, in the order their slices are checked. */
+    readonly classes: readonly {
+        readonly key: string;
+        readonly contract: EdgeContract;
+    }[];
+    readonly nodes: readonly CoreDegreeSubject[];
+    readonly satisfies: (ref: ClassRef, accepts: readonly ClassRef[]) => boolean;
+    /** The keys an Edge holds under the tuples covering its Class. */
+    readonly keys: (edge: CoreFactEdge<Edge>) => readonly string[];
+    /** Whether an undirected Edge's two endpoints state one contract, counted once. */
+    readonly sameIncident: (left: IncidentEndpoint, right: IncidentEndpoint) => boolean;
+    readonly report: (issue: CoreEdgeIssue<Edge>) => void;
+}
+export type CoreEdgeIssue<Edge> = {
+    readonly kind: 'identity';
+    readonly edge: Edge;
+    readonly previous: Edge;
+} | {
+    readonly kind: 'no-self';
+    readonly edge: Edge;
+} | {
+    readonly kind: 'key';
+    readonly edge: Edge;
+    readonly previous: Edge;
+} | {
+    readonly kind: 'acyclic';
+    readonly class: string;
+} | {
+    readonly kind: 'degree';
+    readonly pointer: string;
+    readonly endpoint: EdgeEndpointBase;
+    readonly count: EdgeCount;
+    readonly degree: number;
+};
+/** Whether the endpoints satisfy the contract: in order when directed, in either order when not. */
+export declare function coreEndpointsSatisfy<Endpoint>(contract: EdgeContract, source: Endpoint, target: Endpoint, satisfies: (endpoint: Endpoint, accepts: readonly ClassRef[]) => boolean): boolean;
+/**
+ * Report each fact that holds a key an earlier fact holds, with the first holder of that key. Core
+ * facts have no slug, so only tuples of endpoints and Properties bind them (DV-NODE-UNIQUE,
+ * DV-EDGE-UNIQUE); Activation checks them against stored data.
+ */
+export declare function checkHeldKeys<Fact>(facts: Iterable<Fact>, keys: (fact: Fact) => readonly string[], report: (fact: Fact, previous: Fact) => void): void;
+/** Check normalized Edge identity, noSelf, keys, exact-Class acyclicity and Core degrees. */
+export declare function checkCoreEdgeSet<Edge>(set: CoreEdgeSet<Edge>): void;

package/dist/v1/language/core/facts.js

@@ -0,0 +1,95 @@
+import { compareUnicode } from '../../addressing/ordering.js';
+import { countBounds, hasDirectedCycle } from '../class/inheritance.js';
+/** Whether the endpoints satisfy the contract: in order when directed, in either order when not. */
+export function coreEndpointsSatisfy(contract, source, target, satisfies) {
+    if (contract.orientation === 'directed') {
+        const { endpoints } = contract;
+        return (satisfies(source, endpoints.source.accepts) && satisfies(target, endpoints.target.accepts));
+    }
+    const [first, second] = contract.endpoints;
+    return ((satisfies(source, first.accepts) && satisfies(target, second.accepts)) ||
+        (satisfies(source, second.accepts) && satisfies(target, first.accepts)));
+}
+/**
+ * Report each fact that holds a key an earlier fact holds, with the first holder of that key. Core
+ * facts have no slug, so only tuples of endpoints and Properties bind them (DV-NODE-UNIQUE,
+ * DV-EDGE-UNIQUE); Activation checks them against stored data.
+ */
+export function checkHeldKeys(facts, keys, report) {
+    const holders = new Map();
+    for (const fact of facts) {
+        const held = keys(fact);
+        const holder = held.find((key) => holders.has(key));
+        if (holder !== undefined)
+            report(fact, holders.get(holder));
+        for (const key of held)
+            if (!holders.has(key))
+                holders.set(key, fact);
+    }
+}
+/** Check normalized Edge identity, noSelf, keys, exact-Class acyclicity and Core degrees. */
+export function checkCoreEdgeSet(set) {
+    const identities = new Map();
+    const slices = new Map(set.classes.map(({ key }) => [key, []]));
+    for (const fact of set.edges) {
+        const [source, target] = fact.contract.orientation === 'undirected' &&
+            compareUnicode(fact.source.key, fact.target.key) > 0
+            ? [fact.target.key, fact.source.key]
+            : [fact.source.key, fact.target.key];
+        const identity = `${fact.class}\u0000${source}\u0000${target}`;
+        const previous = identities.get(identity);
+        if (previous !== undefined)
+            set.report({ kind: 'identity', edge: fact.edge, previous });
+        else
+            identities.set(identity, fact.edge);
+        slices.get(fact.class)?.push(fact);
+        if (fact.contract.constraints.noSelf === true && fact.source.key === fact.target.key)
+            set.report({ kind: 'no-self', edge: fact.edge });
+    }
+    checkHeldKeys(set.edges, set.keys, (fact, previous) => set.report({ kind: 'key', edge: fact.edge, previous: previous.edge }));
+    for (const { key, contract } of set.classes) {
+        const slice = slices.get(key);
+        if (contract.constraints.acyclic === true && hasDirectedCycle(slice))
+            set.report({ kind: 'acyclic', class: key });
+        checkDegrees(set, contract, slice);
+    }
+}
+function checkDegrees(set, contract, slice) {
+    for (const subject of degreeSubjects(set.nodes, slice)) {
+        const check = (endpoint, count, degree) => {
+            const [minimum, maximum] = countBounds(count);
+            if (degree > maximum || (degree < minimum && subject.minimum))
+                set.report({ kind: 'degree', pointer: subject.pointer, endpoint, count, degree });
+        };
+        if (contract.orientation === 'directed') {
+            const { source, target } = contract.endpoints;
+            if (set.satisfies(subject.class, source.accepts))
+                check(source, source.outgoing, slice.filter((edge) => edge.source.key === subject.key).length);
+            if (set.satisfies(subject.class, target.accepts))
+                check(target, target.incoming, slice.filter((edge) => edge.target.key === subject.key).length);
+            continue;
+        }
+        const [first, second] = contract.endpoints;
+        const degree = slice.filter((edge) => edge.source.key === subject.key || edge.target.key === subject.key).length;
+        if (set.satisfies(subject.class, first.accepts))
+            check(first, first.incident, degree);
+        if (!set.sameIncident(first, second) && set.satisfies(subject.class, second.accepts))
+            check(second, second.incident, degree);
+    }
+}
+/**
+ * Every declared Core Node proves its own complete degree, so both bounds hold. A projected member
+ * is only named by the Edges that reach it: the Domain may also create ordinary Edges of the same
+ * Class against it, so a minimum is unprovable here and only the maximum is enforced.
+ */
+function degreeSubjects(nodes, slice) {
+    const subjects = new Map(nodes.map((node) => [node.key, { ...node, minimum: true }]));
+    for (const edge of slice) {
+        for (const { key, member } of [edge.source, edge.target]) {
+            if (member === undefined || subjects.has(key))
+                continue;
+            subjects.set(key, { key, class: member.class, pointer: member.pointer, minimum: false });
+        }
+    }
+    return subjects.values();
+}

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,4 +1,5 @@
-import type { PolicyCheckExpression } from '../model/policy.js';
+import type { PolicyRef } from '../../../addressing/index.js';
+import type { PolicyCheckExpression, PolicyExpression } from '../model/policy.js';
 export declare const MAX_PATTERN_DEPTH = 4;
 export declare const MAX_BRANCHES = 8;
 export declare const MAX_VARIABLES = 4;
@@ -8,6 +9,17 @@ export declare const MAX_DOMAINS = 4;
 export declare const MAX_CHECK_DEPTH = 4;
 export declare const MAX_CHECK_LEAVES = 8;
 export declare const BRANCH_OVERFLOW: number;
+export interface PatternMeasure {
+    readonly depth: number;
+    readonly edgeCounts: readonly number[];
+    readonly domains: ReadonlySet<string>;
+}
+/**
+ * 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) => PatternMeasure | undefined;
 export interface CheckMeasure {
     readonly depth: number;
     readonly branches: number;

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

@@ -1,3 +1,4 @@
+import { policyObjectOrigin, policyVariableClass } from '../model/policy.js';
 export const MAX_PATTERN_DEPTH = 4;
 export const MAX_BRANCHES = 8;
 export const MAX_VARIABLES = 4;
@@ -7,6 +8,109 @@ export const MAX_DOMAINS = 4;
 export const MAX_CHECK_DEPTH = 4;
 export const MAX_CHECK_LEAVES = 8;
 export const BRANCH_OVERFLOW = MAX_BRANCHES + 1;
+/**
+ * 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) => measurePolicy(name, new Set());
+}
+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 };
+}
 export function measureChecks(expression) {
     if ('check' in expression || 'sameNode' in expression)
         return { depth: 1, branches: 1, leaves: 1 };

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

@@ -0,0 +1,48 @@
+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 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>;
+    readonly allNodeClasses: readonly ClassRef[];
+    readonly concreteNodeClasses: readonly ClassRef[];
+    isLocalPolicy(ref: PolicyRef): boolean;
+    /** Whether `candidate` is the `required` Class or a same-kind descendant. */
+    classExtends(candidate: ClassRef, required: ClassRef): boolean;
+    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;
+}