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

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[];

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;