@astrale-os/kernel-core 0.9.0-beta.8 → 0.9.0

package/dist/auth/authority/semantics/composition.d.ts

@@ -0,0 +1,46 @@
+import type { NodeId } from '../../../graph/node/index.js';
+import type { ClassRef } from '../language/index.js';
+import type { AuthoritySnapshot } from './snapshot.js';
+import type { AuthorityVocabulary } from './vocabulary.js';
+/** Ceilings a backend places on one binder's composition; overflow is a failure, never false. */
+export interface CompositionLimits {
+    readonly compositionNodes: number;
+    readonly compositionEdges: number;
+}
+/**
+ * Composed status of one Identity. `full` is the complete truth, `positive` ignores exclusions,
+ * and `denied` records an exclusion that was reached in positive position.
+ */
+export interface CompositionStatus {
+    readonly full: boolean;
+    readonly positive: boolean;
+    readonly denied: boolean;
+}
+/** One binder's live composition: every Identity reachable from its root. */
+export interface CompositionClosure {
+    readonly root: NodeId;
+    /** Closure members, root first, in breadth-first order. */
+    readonly identities: readonly NodeId[];
+    /** False when the closure contains a cycle; the binder is then false. */
+    readonly acyclic: boolean;
+    /**
+     * Fold the closure children first from one leaf decision per member. Every member's leaf is
+     * decided. Undefined when the closure is cyclic.
+     */
+    status(leaf: (identity: NodeId) => boolean): CompositionStatus | undefined;
+    /**
+     * The binder's decision, `allowed` of `status`, from leaves of which some are unknown
+     * (undefined): the same fold in Kleene's strong three-valued logic, so a decision it returns is
+     * the one every value of the unknown leaves gives (`decide3_sound` of `proofs/Authority.lean`).
+     * Undefined when they can change it. A cyclic closure is false.
+     */
+    decide(leaf: (identity: NodeId) => boolean | undefined): boolean | undefined;
+}
+/** A binder admits its Identity when its composed status is positive and not denied. */
+export declare function allowed(status: CompositionStatus): boolean;
+/**
+ * Close the composition of one binder root: the outgoing `extends_with`, `constrained_by` and
+ * `excluded_from` Edges, followed transitively. The root must be live and every member must have a
+ * concrete Identity Class of `identities`; otherwise the composition is invalid, not false.
+ */
+export declare function closeComposition(root: NodeId, snapshot: AuthoritySnapshot, vocabulary: AuthorityVocabulary, identities: readonly ClassRef[], limits?: CompositionLimits): CompositionClosure;

package/dist/auth/authority/semantics/composition.js

@@ -0,0 +1,150 @@
+import { AuthorityFailure } from './failure.js';
+/** A binder admits its Identity when its composed status is positive and not denied. */
+export function allowed(status) {
+    return status.positive && !status.denied;
+}
+/**
+ * Close the composition of one binder root: the outgoing `extends_with`, `constrained_by` and
+ * `excluded_from` Edges, followed transitively. The root must be live and every member must have a
+ * concrete Identity Class of `identities`; otherwise the composition is invalid, not false.
+ */
+export function closeComposition(root, snapshot, vocabulary, identities, limits) {
+    const allowedClasses = new Set(identities.map(classKey));
+    const { extension, constraint, exclusion } = vocabulary.composition;
+    const members = [];
+    const ordinals = new Map();
+    const children = [];
+    let edges = 0;
+    const admit = (id) => {
+        let ordinal = ordinals.get(id);
+        if (ordinal !== undefined)
+            return ordinal;
+        const node = snapshot.node(id);
+        if (node === undefined) {
+            throw new AuthorityFailure('AUTHORITY_COMPOSITION_INVALID', 'An Identity binder names no live Node.', { identity: id });
+        }
+        if (!allowedClasses.has(classKey(node.class))) {
+            throw new AuthorityFailure('AUTHORITY_COMPOSITION_INVALID', 'An Identity composition reaches a Node that is not an Identity.', { identity: id });
+        }
+        ordinal = members.length;
+        if (limits !== undefined && ordinal >= limits.compositionNodes) {
+            throw new AuthorityFailure('AUTHORITY_BUDGET_EXCEEDED', 'An Identity composition exceeds its Node ceiling.', { root, limit: limits.compositionNodes });
+        }
+        members.push(id);
+        ordinals.set(id, ordinal);
+        children.push({ extensions: [], constraints: [], exclusions: [] });
+        return ordinal;
+    };
+    admit(root);
+    for (let next = 0; next < members.length; next++) {
+        const id = members[next];
+        const row = children[next];
+        const follow = (edge, bucket) => {
+            for (const child of snapshot.edges(id, edge, 'out')) {
+                edges += 1;
+                if (limits !== undefined && edges > limits.compositionEdges) {
+                    throw new AuthorityFailure('AUTHORITY_BUDGET_EXCEEDED', 'An Identity composition exceeds its Edge ceiling.', { root, limit: limits.compositionEdges });
+                }
+                bucket.push(admit(child));
+            }
+        };
+        follow(extension, row.extensions);
+        follow(constraint, row.constraints);
+        follow(exclusion, row.exclusions);
+    }
+    const order = childrenFirst(children);
+    const acyclic = order.length === members.length;
+    return Object.freeze({
+        root,
+        identities: Object.freeze(members),
+        acyclic,
+        status(leaf) {
+            if (!acyclic)
+                return undefined;
+            // Known leaves keep every value of the fold known.
+            const status = fold(leaf);
+            return Object.freeze({
+                full: status.full === true,
+                positive: status.positive === true,
+                denied: status.denied === true,
+            });
+        },
+        decide(leaf) {
+            if (!acyclic)
+                return false;
+            const status = fold(leaf);
+            return and(status.positive, not(status.denied));
+        },
+    });
+    /**
+     * The composed status of the root, children first, in Kleene's strong three-valued logic: an
+     * unknown leaf (undefined) leaves unknown only what it can change, and known leaves keep every
+     * value known. Iterative in the dependency order, so a deep valid composition needs no call
+     * stack; every member's leaf is decided once.
+     */
+    function fold(leaf) {
+        const values = [];
+        // The children's `field`, combined by `or` when `absorbing` is true and by `and` otherwise.
+        const combine = (list, field, absorbing) => {
+            let result = !absorbing;
+            for (const child of list) {
+                const truth = values[child][field];
+                if (truth === absorbing)
+                    return absorbing;
+                if (truth === undefined)
+                    result = undefined;
+            }
+            return result;
+        };
+        for (const ordinal of order) {
+            const { extensions, constraints, exclusions } = children[ordinal];
+            const truth = leaf(members[ordinal]);
+            values[ordinal] = {
+                full: and(and(or(truth, combine(extensions, 'full', true)), combine(constraints, 'full', false)), not(combine(exclusions, 'full', true))),
+                positive: and(or(truth, combine(extensions, 'positive', true)), combine(constraints, 'positive', false)),
+                denied: or(or(combine(exclusions, 'full', true), combine(extensions, 'denied', true)), combine(constraints, 'denied', true)),
+            };
+        }
+        return values[0];
+    }
+}
+function and(left, right) {
+    if (left === false || right === false)
+        return false;
+    return left === undefined || right === undefined ? undefined : true;
+}
+function or(left, right) {
+    if (left === true || right === true)
+        return true;
+    return left === undefined || right === undefined ? undefined : false;
+}
+function not(value) {
+    return value === undefined ? undefined : !value;
+}
+/** Kahn order over the closure; shorter than the closure exactly when it contains a cycle. */
+function childrenFirst(children) {
+    const parents = children.map(() => []);
+    const pending = new Uint32Array(children.length);
+    children.forEach((row, ordinal) => {
+        const dependencies = new Set([...row.extensions, ...row.constraints, ...row.exclusions]);
+        pending[ordinal] = dependencies.size;
+        for (const child of dependencies)
+            parents[child].push(ordinal);
+    });
+    const order = [];
+    pending.forEach((count, ordinal) => {
+        if (count === 0)
+            order.push(ordinal);
+    });
+    for (let next = 0; next < order.length; next++) {
+        for (const parent of parents[order[next]]) {
+            pending[parent] = pending[parent] - 1;
+            if (pending[parent] === 0)
+                order.push(parent);
+        }
+    }
+    return order;
+}
+function classKey(ref) {
+    return `${ref.origin}:${ref.kind}.${ref.name}`;
+}

package/dist/auth/authority/semantics/failure.d.ts

@@ -0,0 +1,21 @@
+/**
+ * An authority decision that cannot be made. A failure is never `false`: under `not` it would
+ * become `true`, so every backend surfaces it as a failed request instead of a decision.
+ */
+export type AuthorityFailureCode = 
+/** A bound input names no live Node. */
+'AUTHORITY_TARGET_NOT_FOUND'
+/** A term reads an input the decision frame does not bind. */
+ | 'AUTHORITY_INPUT_UNBOUND'
+/** A fixed term does not resolve to exactly one live Node. */
+ | 'AUTHORITY_REFERENCE_INVALID'
+/** A binder root is absent, or its composition reaches a Node that is not an Identity. */
+ | 'AUTHORITY_COMPOSITION_INVALID'
+/** A binder composition exceeds the evaluating backend's ceilings. */
+ | 'AUTHORITY_BUDGET_EXCEEDED';
+export declare class AuthorityFailure extends Error {
+    readonly code: AuthorityFailureCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    readonly name: 'AuthorityFailure';
+    constructor(code: AuthorityFailureCode, message: string, details?: Readonly<Record<string, unknown>>);
+}

package/dist/auth/authority/semantics/failure.js

@@ -0,0 +1,10 @@
+export class AuthorityFailure extends Error {
+    code;
+    details;
+    name = 'AuthorityFailure';
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/auth/authority/semantics/index.d.ts

@@ -0,0 +1,13 @@
+export { classAuthorityMeaning } from './class-authority.js';
+export { allowed, closeComposition } from './composition.js';
+export type { CompositionClosure, CompositionLimits, CompositionStatus } from './composition.js';
+export { AuthorityFailure } from './failure.js';
+export type { AuthorityFailureCode } from './failure.js';
+export { binderRoots, createAuthorityEvaluator } from './interpret.js';
+export type { AuthorityAtom, AuthorityEvaluationOptions, AuthorityEvaluator } from './interpret.js';
+export { residualProgram, staticAtoms } from './residual.js';
+export type { StaticAtom } from './residual.js';
+export type { AuthorityInputs, AuthorityNode, AuthoritySnapshot } from './snapshot.js';
+export { fixedPaths, isFixedTerm, requiredInputs, termPath } from './terms.js';
+export type { FixedTerm } from './terms.js';
+export type { AuthorityVocabulary } from './vocabulary.js';

package/dist/auth/authority/semantics/index.js

@@ -0,0 +1,6 @@
+export { classAuthorityMeaning } from './class-authority.js';
+export { allowed, closeComposition } from './composition.js';
+export { AuthorityFailure } from './failure.js';
+export { binderRoots, createAuthorityEvaluator } from './interpret.js';
+export { residualProgram, staticAtoms } from './residual.js';
+export { fixedPaths, isFixedTerm, requiredInputs, termPath } from './terms.js';

package/dist/auth/authority/semantics/interpret.d.ts

@@ -0,0 +1,41 @@
+import type { NodeId } from '../../../graph/node/index.js';
+import type { AuthorityExpr, AuthorityProgram, PredicateRef } from '../language/index.js';
+import type { CompositionLimits } from './composition.js';
+import type { AuthorityInputs, AuthoritySnapshot } from './snapshot.js';
+import type { AuthorityVocabulary } from './vocabulary.js';
+/** A leaf the Boolean and binder structure does not decompose. */
+export type AuthorityAtom = Exclude<AuthorityExpr, {
+    readonly op: 'true' | 'false' | 'all' | 'any' | 'not' | 'as';
+}>;
+export interface AuthorityEvaluationOptions {
+    /** The evaluating backend's composition ceilings. */
+    readonly limits?: CompositionLimits;
+    /**
+     * Decide an atom outside every existential scope from evidence the snapshot does not hold, such
+     * as a captured fact table. Undefined leaves the atom to its meaning over the snapshot.
+     */
+    readonly atom?: (atom: AuthorityAtom, subject: NodeId | undefined) => boolean | undefined;
+    /**
+     * Pure observation of the snapshot's evidence token. It changes (Object.is) at every
+     * acquisition and stays stable otherwise; observing it must not acquire evidence.
+     * Stable snapshots may omit it. Tokens must not be mutated or reused across acquisitions.
+     */
+    readonly evidenceEpoch?: () => unknown;
+}
+/** Decisions of one program over one snapshot. Memoized evidence never outlives the evaluator. */
+export interface AuthorityEvaluator {
+    /**
+     * Resolve every fixed reference and admit every binder composition of the program, as a backend
+     * does for its whole request family before it exposes any decision.
+     */
+    admit(): void;
+    /** Decide one predicate for one input frame; throws `AuthorityFailure`, never returns it. */
+    evaluate(predicate: PredicateRef, inputs?: AuthorityInputs): boolean;
+}
+/**
+ * The reference interpreter of authority. It is parametric over one snapshot and the Kernel
+ * vocabulary, and every backend lowering must agree with it.
+ */
+export declare function createAuthorityEvaluator(program: AuthorityProgram, snapshot: AuthoritySnapshot, vocabulary: AuthorityVocabulary, options?: AuthorityEvaluationOptions): AuthorityEvaluator;
+/** Every Identity a binder of the program names, sorted. */
+export declare function binderRoots(expressions: readonly AuthorityExpr[]): readonly NodeId[];