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

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

@@ -0,0 +1,388 @@
+import { Path } from '../../../graph/path/index.js';
+import { allowed, closeComposition } from './composition.js';
+import { AuthorityFailure } from './failure.js';
+import { fixedPaths, termPath } from './terms.js';
+/**
+ * The reference interpreter of authority. It is parametric over one snapshot and the Kernel
+ * vocabulary, and every backend lowering must agree with it.
+ */
+export function createAuthorityEvaluator(program, snapshot, vocabulary, options = {}) {
+    const references = new Map();
+    const closures = new Map();
+    const projections = new Map();
+    const walks = new Map();
+    const walkPlans = new WeakMap();
+    const existentialPlans = new WeakMap();
+    const instanceOf = classKey(vocabulary.instanceOf);
+    const reference = (path) => {
+        const known = references.get(path.raw);
+        if (known !== undefined)
+            return known;
+        const nodes = [...new Set(snapshot.resolve(path))].filter((id) => snapshot.node(id));
+        if (nodes.length !== 1) {
+            throw new AuthorityFailure('AUTHORITY_REFERENCE_INVALID', 'An authority fixed reference does not resolve to exactly one live Node.', { path: path.raw, candidates: nodes.length });
+        }
+        references.set(path.raw, nodes[0]);
+        return nodes[0];
+    };
+    const closure = (root) => {
+        let value = closures.get(root);
+        if (value === undefined) {
+            value = closeComposition(root, snapshot, vocabulary, program.identities, options.limits);
+            closures.set(root, value);
+        }
+        return value;
+    };
+    const term = (value, frame) => {
+        switch (value.kind) {
+            case 'input': {
+                const id = frame.inputs[value.input];
+                if (id === undefined) {
+                    throw new AuthorityFailure('AUTHORITY_INPUT_UNBOUND', `Authority input ${value.input} is not bound by the decision frame.`);
+                }
+                return id;
+            }
+            case 'subject':
+                if (frame.subject === undefined)
+                    throw new TypeError('Authority subject is unbound.');
+                return frame.subject;
+            case 'local': {
+                const id = frame.locals.get(value.id);
+                if (id === undefined)
+                    throw new TypeError(`Authority local ${value.id} is unbound.`);
+                return id;
+            }
+            default:
+                return reference(termPath(value));
+        }
+    };
+    const classOf = (id) => {
+        const node = snapshot.node(id);
+        if (node === undefined)
+            throw new TypeError('Authority evaluation reached a Node that is gone.');
+        return node.class;
+    };
+    /** `instance_of` is derived: the live projection of the Node's exact Class. */
+    const projection = (id) => {
+        const ref = classOf(id);
+        const key = classKey(ref);
+        let nodes = projections.get(key);
+        if (nodes === undefined) {
+            const candidates = snapshot.classProjection?.(ref) ?? snapshot.resolve(Path.project(ref));
+            nodes = Object.freeze([...new Set(candidates)].filter((node) => snapshot.node(node)));
+            projections.set(key, nodes);
+        }
+        return nodes;
+    };
+    const step = (from, edge) => classKey(edge) === instanceOf
+        ? projection(from)
+        : snapshot.edges(from, edge, snapshot.orientation(edge) === 'undirected' ? 'both' : 'out');
+    /**
+     * Bounded walks: a Node reached at any depth within [min, max], revisits allowed. Each hop may
+     * take any member of the Edge Class extent.
+     */
+    const related = (expression, source, target) => {
+        const { repeat, via: extent } = expression;
+        const min = repeat?.min ?? 1;
+        const max = repeat?.max ?? 1;
+        // The empty walk is already a proof. Do not spend a read budget exploring longer walks.
+        if (min === 0 && source === target)
+            return true;
+        let plan = walkPlans.get(expression);
+        if (plan === undefined) {
+            const key = JSON.stringify([min, max, extent.map(classKey)]);
+            plan = walks.get(key);
+            if (plan === undefined) {
+                plan = new Map();
+                walks.set(key, plan);
+            }
+            walkPlans.set(expression, plan);
+        }
+        const epoch = options.evidenceEpoch?.();
+        let walk = plan.get(source);
+        if (walk === undefined || !Object.is(walk.epoch, epoch)) {
+            walk = { epoch, layers: [new Set([source])] };
+            plan.delete(source);
+        }
+        let frontier = walk.layers[0];
+        for (let depth = 1; depth <= max && frontier.size > 0; depth++) {
+            let next = walk.layers[depth];
+            if (next === undefined) {
+                const before = options.evidenceEpoch?.();
+                const acquired = new Set();
+                for (const node of frontier) {
+                    for (const edge of extent)
+                        for (const reached of step(node, edge))
+                            acquired.add(reached);
+                }
+                next = acquired;
+                walk.layers.push(next);
+                // Every retained layer must belong to the same epoch. A provisional prefix remains
+                // usable for this search only, even if its later extensions acquire no further evidence.
+                if (Object.is(walk.epoch, before) && Object.is(before, options.evidenceEpoch?.())) {
+                    plan.set(source, walk);
+                }
+                else {
+                    plan.delete(source);
+                }
+            }
+            // Like the frozen interpreter, acquire no layer beyond the first admissible witness.
+            if (depth >= min && next.has(target))
+                return true;
+            frontier = next;
+        }
+        return false;
+    };
+    const holds = (expression, frame) => {
+        switch (expression.op) {
+            case 'true':
+                return true;
+            case 'false':
+                return false;
+            case 'all':
+                return expression.predicates.every((child) => holds(child, frame));
+            case 'any':
+                return expression.predicates.some((child) => holds(child, frame));
+            case 'not':
+                return !holds(expression.predicate, frame);
+            case 'as': {
+                // A cyclic composition makes this binder false; the scope of a cycle is the binder.
+                const status = closure(expression.identity).status((identity) => holds(expression.where, { ...frame, subject: identity }));
+                return status !== undefined && allowed(status);
+            }
+            default:
+                return atom(expression, frame);
+        }
+    };
+    const atom = (expression, frame) => {
+        if (options.atom !== undefined && frame.locals.size === 0) {
+            const decided = options.atom(expression, frame.subject);
+            if (decided !== undefined)
+                return decided;
+        }
+        switch (expression.op) {
+            case 'same-node':
+                return term(expression.left, frame) === term(expression.right, frame);
+            case 'related':
+                return related(expression, term(expression.source, frame), term(expression.target, frame));
+            case 'instance-of':
+                return sameClass(classOf(term(expression.node, frame)), expression.class);
+            case 'edge-class': {
+                if (frame.inputs.edge === undefined) {
+                    throw new AuthorityFailure('AUTHORITY_INPUT_UNBOUND', 'Authority edge-class requires a bound Edge object.');
+                }
+                return sameClass(frame.inputs.edge, expression.class);
+            }
+            case 'class-authority': {
+                // The meaning is `classAuthorityMeaning`; it is decided directly so no atom it expands to
+                // is ever asked of a captured fact table.
+                const identity = term(expression.identity, frame);
+                if (identity === reference(Path.domain(expression.class.origin)))
+                    return true;
+                if (expression.evidence === 'owner')
+                    return false;
+                const target = reference(Path.project(expression.class));
+                return snapshot
+                    .edges(identity, vocabulary.capabilities[expression.operation], 'out')
+                    .includes(target);
+            }
+            case 'exists':
+                return exists(expression, frame);
+        }
+    };
+    const exists = (expression, frame) => {
+        const candidates = expression.nodes.map((local) => local.kind === 'any' ? snapshot.nodes() : snapshot.nodes(local.classes));
+        // Acquire every extent in declaration order, even when the product has no tuple.
+        if (candidates.some((extent) => extent.length === 0))
+            return false;
+        let plan = existentialPlans.get(expression);
+        if (plan === undefined) {
+            const predicates = expression.where.op === 'all' ? expression.where.predicates : [expression.where];
+            const usedIndices = new Set();
+            // Each entry describes the whole prefix, including its earlier true predicates.
+            // gates[i] rejects values of local i; resets[i] invalidates their earlier context.
+            const gates = expression.nodes.map(() => []);
+            const resets = expression.nodes.map(() => []);
+            const dependency = predicates.map((predicate, item) => {
+                const used = localDependencies(predicate);
+                for (let index = 0; index < expression.nodes.length; index++) {
+                    if (used.has(expression.nodes[index].id))
+                        usedIndices.add(index);
+                }
+                const ordered = [...usedIndices].sort((left, right) => left - right);
+                const last = ordered.at(-1) ?? -1;
+                const earlier = ordered.at(-2) ?? -1;
+                if (last >= 0)
+                    gates[last].push(item);
+                // An exclusion of the last dependency is valid only while all earlier ones stay fixed.
+                for (let index = 0; index <= earlier; index++)
+                    resets[index].push(item);
+                return last;
+            });
+            plan = { predicates, dependency, gates, resets };
+            existentialPlans.set(expression, plan);
+        }
+        const { predicates, dependency, gates, resets } = plan;
+        const excluded = predicates.map(() => new Set());
+        const rejected = (index, node) => {
+            for (const item of gates[index])
+                if (excluded[item].has(node))
+                    return true;
+            return false;
+        };
+        const clear = (item) => {
+            if (excluded[item].size === 0)
+                return;
+            excluded[item].clear();
+        };
+        let prefix = 0;
+        let observedEpoch = options.evidenceEpoch?.();
+        const refresh = () => {
+            const current = options.evidenceEpoch?.();
+            if (Object.is(current, observedEpoch))
+                return false;
+            observedEpoch = current;
+            prefix = 0;
+            excluded.forEach((_, item) => clear(item));
+            return true;
+        };
+        // -2 means a witness. Every other result identifies the last bound variable that
+        // may change the evaluated prefix. Descendants cannot alter its reads or result.
+        const locals = new Map(frame.locals);
+        const complete = { ...frame, locals };
+        const bind = (index) => {
+            if (index === expression.nodes.length) {
+                for (let item = prefix; item < predicates.length; item++) {
+                    if (!holds(predicates[item], complete)) {
+                        if (refresh())
+                            return expression.nodes.length - 1;
+                        const target = dependency[item];
+                        if (target >= 0) {
+                            const value = locals.get(expression.nodes[target].id);
+                            if (!excluded[item].has(value)) {
+                                excluded[item].add(value);
+                            }
+                        }
+                        return dependency[item];
+                    }
+                    prefix = item + 1;
+                }
+                return -2;
+            }
+            const id = expression.nodes[index].id;
+            const previous = locals.get(id);
+            try {
+                for (let ordinal = 0; ordinal < candidates[index].length; ordinal++) {
+                    refresh();
+                    const node = candidates[index][ordinal];
+                    if (rejected(index, node)) {
+                        continue;
+                    }
+                    for (const item of resets[index])
+                        clear(item);
+                    while (prefix > 0 && dependency[prefix - 1] >= index)
+                        prefix--;
+                    locals.set(id, node);
+                    const result = bind(index + 1);
+                    if (result === -2 || result < index)
+                        return result;
+                }
+                return index - 1;
+            }
+            finally {
+                if (previous === undefined)
+                    locals.delete(id);
+                else
+                    locals.set(id, previous);
+            }
+        };
+        return bind(0) === -2;
+    };
+    return Object.freeze({
+        admit() {
+            for (const path of fixedPaths(program.predicates))
+                reference(path);
+            for (const root of binderRoots(program.predicates))
+                closure(root);
+        },
+        evaluate(predicate, inputs = {}) {
+            const expression = program.predicates[predicate];
+            if (expression === undefined)
+                throw new TypeError('Unknown Authority predicate ordinal.');
+            for (const input of ['object', 'source', 'target']) {
+                const id = inputs[input];
+                if (id !== undefined && snapshot.node(id) === undefined) {
+                    throw new AuthorityFailure('AUTHORITY_TARGET_NOT_FOUND', `Authority ${input} does not exist in the evaluated graph.`, { [input]: id });
+                }
+            }
+            return holds(expression, { inputs, subject: undefined, locals: new Map() });
+        },
+    });
+}
+/** Locals whose assignment can affect the result of this expression. */
+function localDependencies(expression) {
+    const result = new Set();
+    const addTerm = (term) => {
+        if (term.kind === 'local')
+            result.add(term.id);
+    };
+    const visit = (value) => {
+        switch (value.op) {
+            case 'all':
+            case 'any':
+                value.predicates.forEach(visit);
+                return;
+            case 'not':
+                visit(value.predicate);
+                return;
+            case 'as':
+            case 'exists':
+                visit(value.where);
+                return;
+            case 'same-node':
+                addTerm(value.left);
+                addTerm(value.right);
+                return;
+            case 'related':
+                addTerm(value.source);
+                addTerm(value.target);
+                return;
+            case 'instance-of':
+                addTerm(value.node);
+                return;
+            case 'class-authority':
+                addTerm(value.identity);
+        }
+    };
+    visit(expression);
+    return result;
+}
+/** Every Identity a binder of the program names, sorted. */
+export function binderRoots(expressions) {
+    const roots = new Set();
+    const visit = (expression) => {
+        switch (expression.op) {
+            case 'all':
+            case 'any':
+                expression.predicates.forEach(visit);
+                return;
+            case 'not':
+                visit(expression.predicate);
+                return;
+            case 'exists':
+                visit(expression.where);
+                return;
+            case 'as':
+                roots.add(expression.identity);
+                visit(expression.where);
+        }
+    };
+    expressions.forEach(visit);
+    return Object.freeze([...roots].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0)));
+}
+function sameClass(left, right) {
+    return left.origin === right.origin && left.kind === right.kind && left.name === right.name;
+}
+function classKey(ref) {
+    return `${ref.origin}:${ref.kind}.${ref.name}`;
+}

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

@@ -0,0 +1,32 @@
+import type { NodeId } from '../../../graph/node/index.js';
+import type { AuthorityExpr, AuthorityProgram } from '../language/index.js';
+import type { CompositionClosure } from './composition.js';
+import type { AuthorityAtom } from './interpret.js';
+/**
+ * An atom outside every existential scope that reads no input: one snapshot gives it one value,
+ * one per subject when it names the subject of its binder (`subject`).
+ */
+export interface StaticAtom {
+    readonly atom: AuthorityAtom;
+    readonly subject: boolean;
+}
+/**
+ * The static atoms of the expressions, each once by structure, in depth-first order: the atoms
+ * `residualProgram` asks to decide. An `exists` that reads no input is one atom.
+ */
+export declare function staticAtoms(expressions: readonly AuthorityExpr[]): readonly StaticAtom[];
+/**
+ * The program specialized to one snapshot: each static atom replaced by the value `atom` gives it,
+ * and each expression those values decide folded into it, in Kleene's strong three-valued logic.
+ * `atom` receives the subject only for an atom that names it, and undefined leaves the atom in
+ * place. A binder whose composition decides it from its members' specialized leaves
+ * (`CompositionClosure.decide`) is folded too. Otherwise it keeps the leaf every member
+ * specializes to alike, or the leaf specialized without a subject. `closure` is the admitted
+ * composition of a binder root.
+ *
+ * Once the program is admitted in that snapshot (AUTH-FAILURE-ADMITTED-EAGERLY), the residual
+ * decides every input frame as the program does (`pe_sound` of `proofs/Authority.lean`). Each
+ * member keeps its ordinal, so the residual is not canonical, and an expression nothing decides
+ * stays the same object.
+ */
+export declare function residualProgram(program: AuthorityProgram, closure: (root: NodeId) => CompositionClosure | undefined, atom: (atom: AuthorityAtom, subject: NodeId | undefined) => boolean | undefined): AuthorityProgram;

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

@@ -0,0 +1,166 @@
+import { ownTerms, requiredInputs } from './terms.js';
+/**
+ * The static atoms of the expressions, each once by structure, in depth-first order: the atoms
+ * `residualProgram` asks to decide. An `exists` that reads no input is one atom.
+ */
+export function staticAtoms(expressions) {
+    const found = new Map();
+    const visit = (value) => {
+        switch (value.op) {
+            case 'true':
+            case 'false':
+                return;
+            case 'all':
+            case 'any':
+                value.predicates.forEach(visit);
+                return;
+            case 'not':
+                visit(value.predicate);
+                return;
+            case 'as':
+                visit(value.where);
+                return;
+            default: {
+                const subject = names(value);
+                const key = JSON.stringify(value);
+                if (subject !== undefined && !found.has(key))
+                    found.set(key, { atom: value, subject });
+            }
+        }
+    };
+    expressions.forEach(visit);
+    return Object.freeze([...found.values()]);
+}
+/**
+ * The program specialized to one snapshot: each static atom replaced by the value `atom` gives it,
+ * and each expression those values decide folded into it, in Kleene's strong three-valued logic.
+ * `atom` receives the subject only for an atom that names it, and undefined leaves the atom in
+ * place. A binder whose composition decides it from its members' specialized leaves
+ * (`CompositionClosure.decide`) is folded too. Otherwise it keeps the leaf every member
+ * specializes to alike, or the leaf specialized without a subject. `closure` is the admitted
+ * composition of a binder root.
+ *
+ * Once the program is admitted in that snapshot (AUTH-FAILURE-ADMITTED-EAGERLY), the residual
+ * decides every input frame as the program does (`pe_sound` of `proofs/Authority.lean`). Each
+ * member keeps its ordinal, so the residual is not canonical, and an expression nothing decides
+ * stays the same object.
+ */
+export function residualProgram(program, closure, atom) {
+    const subjects = new Map();
+    const binders = new Map();
+    const known = (value, subject) => {
+        let named = subjects.get(value);
+        if (named === undefined)
+            subjects.set(value, (named = names(value) ?? null));
+        if (named === null)
+            return undefined;
+        if (!named)
+            return atom(value, undefined);
+        return subject === undefined ? undefined : atom(value, subject);
+    };
+    const specialize = (value, subject) => {
+        switch (value.op) {
+            case 'true':
+            case 'false':
+                return value;
+            case 'all':
+            case 'any': {
+                // `all` is false once one member is, `any` true once one member is.
+                const absorbing = value.op === 'any';
+                const kept = [];
+                let changed = false;
+                for (const child of value.predicates) {
+                    const residual = specialize(child, subject);
+                    const decided = truth(residual);
+                    if (decided === absorbing)
+                        return constant(absorbing);
+                    if (decided === undefined)
+                        kept.push(residual);
+                    if (residual !== child || decided !== undefined)
+                        changed = true;
+                }
+                if (!changed)
+                    return value;
+                if (kept.length === 0)
+                    return constant(!absorbing);
+                return kept.length === 1 ? kept[0] : Object.freeze({ op: value.op, predicates: kept });
+            }
+            case 'not': {
+                const residual = specialize(value.predicate, subject);
+                const decided = truth(residual);
+                if (decided !== undefined)
+                    return constant(!decided);
+                return residual === value.predicate
+                    ? value
+                    : Object.freeze({ op: 'not', predicate: residual });
+            }
+            case 'as': {
+                // A binder names its own subject: its residual is the same under every outer subject.
+                let residual = binders.get(value);
+                if (residual === undefined)
+                    binders.set(value, (residual = binder(value)));
+                return residual;
+            }
+            default: {
+                const decided = known(value, subject);
+                return decided === undefined ? value : constant(decided);
+            }
+        }
+    };
+    const binder = (value) => {
+        const composed = closure(value.identity);
+        if (composed === undefined)
+            return value;
+        const leaves = new Map(composed.identities.map((member) => [member, specialize(value.where, member)]));
+        const decided = composed.decide((member) => truth(leaves.get(member)));
+        if (decided !== undefined)
+            return constant(decided);
+        const [first, ...others] = leaves.values();
+        // Each member's leaf decides as its own specialization: one shared by every member replaces
+        // the leaf; otherwise only what no subject decides is specialized.
+        const where = others.every((leaf) => same(leaf, first))
+            ? first
+            : specialize(value.where, undefined);
+        return where === value.where ? value : Object.freeze({ ...value, where });
+    };
+    const predicates = program.predicates.map((predicate) => specialize(predicate, undefined));
+    if (predicates.every((predicate, index) => predicate === program.predicates[index])) {
+        return program;
+    }
+    return Object.freeze({ ...program, predicates: Object.freeze(predicates) });
+}
+const TRUE = Object.freeze({ op: 'true' });
+const FALSE = Object.freeze({ op: 'false' });
+function constant(value) {
+    return value ? TRUE : FALSE;
+}
+function truth(value) {
+    return value.op === 'true' ? true : value.op === 'false' ? false : undefined;
+}
+function same(left, right) {
+    return left === right || JSON.stringify(left) === JSON.stringify(right);
+}
+/**
+ * Undefined when the atom reads a decision input (`requiredInputs`); otherwise whether it names the
+ * subject of its binder, outside the binders nested in it.
+ */
+function names(atom) {
+    if (requiredInputs([atom]).size > 0)
+        return undefined;
+    const subject = (value) => {
+        switch (value.op) {
+            case 'all':
+            case 'any':
+                return value.predicates.some(subject);
+            case 'not':
+                return subject(value.predicate);
+            case 'as':
+                return false;
+            case 'exists':
+                return subject(value.where);
+            default:
+                return ownTerms(value).some((term) => term.kind === 'subject');
+        }
+    };
+    return subject(atom);
+}

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

@@ -0,0 +1,40 @@
+import type { NodeId } from '../../../graph/node/index.js';
+import type { Path } from '../../../graph/path/index.js';
+import type { ClassRef } from '../language/index.js';
+/** One live Node as authority sees it: its exact concrete Class. */
+export interface AuthorityNode {
+    readonly class: ClassRef;
+}
+/**
+ * One consistent graph state the interpreter reads. Every Node it exposes is live and has exactly
+ * one active concrete Class; every Edge connects two such Nodes.
+ */
+export interface AuthoritySnapshot {
+    /** The live Node, or undefined when the id names none. */
+    node(id: NodeId): AuthorityNode | undefined;
+    /**
+     * Distinct Nodes one Edge of the exact Class away: `out` follows source to target, `in` target
+     * to source, `both` either orientation. The derived `instance_of` relation is never asked.
+     */
+    edges(from: NodeId, edge: ClassRef, direction: 'out' | 'in' | 'both'): readonly NodeId[];
+    /** Orientation the pinned Registry declares for one Edge Class. */
+    orientation(edge: ClassRef): 'directed' | 'undirected';
+    /** Every live Node the Path reaches; a fixed term requires exactly one. */
+    resolve(path: Path): readonly NodeId[];
+    /**
+     * Pinned Registry candidates for derived `instance_of`, admitted through `node` before use.
+     * An absent hook falls back to `resolve(Path.project(ref))`; an empty result never does.
+     * Fixed terms always use `resolve` independently of this projection.
+     */
+    classProjection?(ref: ClassRef): readonly NodeId[];
+    /** Every live Node, restricted to exact Classes when given. */
+    nodes(classes?: readonly ClassRef[]): readonly NodeId[];
+}
+/** The input frame of one decision; each bound Node must be live. */
+export interface AuthorityInputs {
+    readonly object?: NodeId;
+    readonly source?: NodeId;
+    readonly target?: NodeId;
+    /** Exact Class of the bound Edge object, read only by `edge-class`. */
+    readonly edge?: ClassRef;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,22 @@
+import type { AuthorityExpr, Term } from '../language/index.js';
+import type { AuthorityInputs } from './snapshot.js';
+import { Path } from '../../../graph/path/index.js';
+/** A term that names one Node independently of any row, binder or local. */
+export type FixedTerm = Extract<Term, {
+    readonly kind: 'node' | 'class' | 'domain' | 'core' | 'ref';
+}>;
+export declare function isFixedTerm(term: Term): term is FixedTerm;
+/** The Path a fixed term denotes; the term holds when that Path reaches exactly one live Node. */
+export declare function termPath(term: FixedTerm): Path;
+/**
+ * Every fixed Path one expression depends on, sorted by raw text. `class-authority` depends on the
+ * projection of its Class and on the Domain of the Class origin.
+ */
+export declare function fixedPaths(expressions: readonly AuthorityExpr[]): readonly Path[];
+/**
+ * Every decision input the expressions read: each `input` term, and the bound Edge Class that
+ * `edge-class` reads. A decision whose frame leaves one of them unbound fails.
+ */
+export declare function requiredInputs(expressions: readonly AuthorityExpr[]): ReadonlySet<keyof AuthorityInputs>;
+/** The terms one expression reads itself, excluding those of its nested expressions. */
+export declare function ownTerms(expression: AuthorityExpr): readonly Term[];