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

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

@@ -0,0 +1,39 @@
+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;
+}
+/** 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,112 @@
+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;
+            const values = [];
+            // Iterative in the dependency order, so a deep valid composition needs no call stack.
+            for (const ordinal of order) {
+                const row = children[ordinal];
+                const truth = leaf(members[ordinal]);
+                const full = (child) => values[child].full;
+                const positive = (child) => values[child].positive;
+                const denied = (child) => values[child].denied;
+                values[ordinal] = Object.freeze({
+                    full: (truth || row.extensions.some(full)) &&
+                        row.constraints.every(full) &&
+                        !row.exclusions.some(full),
+                    positive: (truth || row.extensions.some(positive)) && row.constraints.every(positive),
+                    denied: row.exclusions.some(full) ||
+                        row.extensions.some(denied) ||
+                        row.constraints.some(denied),
+                });
+            }
+            return values[0];
+        },
+    });
+}
+/** 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,11 @@
+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 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,5 @@
+export { classAuthorityMeaning } from './class-authority.js';
+export { allowed, closeComposition } from './composition.js';
+export { AuthorityFailure } from './failure.js';
+export { binderRoots, createAuthorityEvaluator } from './interpret.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/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;
+}