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

package/dist/auth/authority/normalization/normalize.js

@@ -1,21 +1,30 @@
 import * as portable from '@astrale-os/kernel-dsl/value';
 import { NodeId } from '../../../graph/node/index.js';
 import { AuthValueError } from '../../error.js';
-import { canonicalize as canonicalizeGrant } from '../../grant/index.js';
 import { admitAuthorityExpr, limits } from '../admission/index.js';
 import { AUTHORITY_PREDICATE_VERSION } from '../language/index.js';
+import { ownCanonical, ownedExpression, ownsExpression } from '../ownership.optimization.js';
 /** Validate and canonicalize one authority expression into its versioned crossing envelope. */
 export function canonicalize(expr) {
-    const admitted = admitAuthorityExpr(portable.accept(expr));
+    const owned = ownedExpression(expr);
+    if (owned !== undefined)
+        return owned;
+    const admitted = admitAuthorityExpr(portable.acceptForRead(expr));
     return canonicalizeAdmitted(admitted);
 }
 export function canonicalizeAdmitted(expr) {
-    return Object.freeze({
+    return ownCanonical(Object.freeze({
         version: AUTHORITY_PREDICATE_VERSION,
         predicate: normalize(expr, '/predicate', new Set(), false),
-    });
+    }));
+}
+/** Internal scoped normalization; this body is not a closed owned authority expression. */
+export function normalizeBinderBodyAdmitted(expr) {
+    return normalize(expr, '/predicate/where', new Set(), true);
 }
 function normalize(expr, path, locals, subjectBound) {
+    if (ownsExpression(expr))
+        return expr;
     switch (expr.op) {
         case 'true':
         case 'false':
@@ -33,17 +42,24 @@ function normalize(expr, path, locals, subjectBound) {
         case 'all':
         case 'any':
             return normalizeBoolean(expr.op, expr.predicates, path, locals, subjectBound);
-        case 'grant':
+        case 'as':
             return Object.freeze({
-                op: 'grant',
-                grant: canonicalizeGrant(expr.grant),
+                op: 'as',
+                identity: NodeId(expr.identity),
                 where: normalize(expr.where, `${path}/where`, locals, true),
             });
+        case 'same-node': {
+            const left = normalizeTerm(expr.left);
+            const right = normalizeTerm(expr.right);
+            return Object.freeze(compare(portable.json.serialize(left), portable.json.serialize(right)) <= 0
+                ? { op: 'same-node', left, right }
+                : { op: 'same-node', left: right, right: left });
+        }
         case 'related':
             return Object.freeze({
                 op: 'related',
                 source: normalizeTerm(expr.source),
-                class: Object.freeze({ ...expr.class }),
+                via: normalizeClasses(expr.via),
                 target: normalizeTerm(expr.target),
                 ...(expr.repeat === undefined ? {} : { repeat: Object.freeze({ ...expr.repeat }) }),
             });
@@ -71,12 +87,6 @@ function normalize(expr, path, locals, subjectBound) {
                 class: Object.freeze({ ...expr.class }),
                 evidence: expr.evidence,
             });
-        case 'domain-control':
-            return Object.freeze({
-                op: 'domain-control',
-                identity: normalizeTerm(expr.identity),
-                origin: expr.origin,
-            });
     }
 }
 function normalizeBoolean(op, input, path, locals, subjectBound) {
@@ -95,7 +105,8 @@ function normalizeBoolean(op, input, path, locals, subjectBound) {
     for (const expr of flattened) {
         if (expr.op === identity)
             continue;
-        unique.set(portable.json.serialize(expr), expr);
+        // Admission and normalization own these detached subtrees; sorting does not lose that proof.
+        unique.set(portable.json.serializeAdmitted(expr), expr);
     }
     const predicates = [...unique.entries()]
         .sort(([left], [right]) => compare(left, right))
@@ -119,6 +130,8 @@ function normalizeTerm(term) {
             return Object.freeze({ kind: 'class', ref: Object.freeze({ ...term.ref }) });
         case 'domain':
             return Object.freeze({ kind: 'domain', origin: term.origin });
+        case 'ref':
+            return Object.freeze({ kind: 'ref', ref: Object.freeze({ ...term.ref }) });
         case 'core':
             return Object.freeze({ kind: 'core', ref: Object.freeze({ ...term.ref }) });
         case 'local':
@@ -128,7 +141,16 @@ function normalizeTerm(term) {
     }
 }
 function normalizeLocal(local) {
-    return Object.freeze({ id: local.id, class: Object.freeze({ ...local.class }) });
+    if (local.kind === 'any')
+        return Object.freeze({ id: local.id, kind: 'any' });
+    return Object.freeze({ id: local.id, kind: 'classes', classes: normalizeClasses(local.classes) });
+}
+function normalizeClasses(input) {
+    const classes = new Map(input.map((ref) => [classKey(ref), Object.freeze({ ...ref })]));
+    return Object.freeze([...classes.entries()].sort(([left], [right]) => compare(left, right)).map(([, ref]) => ref));
+}
+function classKey(ref) {
+    return `${ref.origin}:${ref.kind}.${ref.name}`;
 }
 function compare(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;

package/dist/auth/authority/ownership.optimization.d.ts

@@ -0,0 +1,8 @@
+import { type AuthorityExpr, type AuthorityPredicate } from './language/index.js';
+/** Called only by the owner after detachment, admission and immutable normalization. */
+export declare function ownCanonical(predicate: AuthorityPredicate): AuthorityPredicate;
+/** Closed subprograms retain their lexical proof when composed outside another local binder. */
+export declare function ownsExpression(expression: unknown, remainingDepth?: number): boolean;
+/** Rewrap only owner-proven closed expressions, never a leaf borrowed from a lexical binder. */
+export declare function ownedExpression(expression: AuthorityExpr): AuthorityPredicate | undefined;
+export declare function ownsCanonical(input: unknown): boolean;

package/dist/auth/authority/ownership.optimization.js

@@ -0,0 +1,83 @@
+import * as portable from '@astrale-os/kernel-dsl/value';
+import { AUTHORITY_PREDICATE_VERSION, } from './language/index.js';
+// Static construction provenance only. No evaluated authority or graph facts live here.
+const canonical = new WeakSet();
+const expressions = new WeakMap();
+const depths = new WeakMap();
+/** Called only by the owner after detachment, admission and immutable normalization. */
+export function ownCanonical(predicate) {
+    // Carry immutable structural provenance through containing Plans as well as Core calls.
+    // The normalized envelope can exceed a portable boundary's default budget even when the
+    // constructor's expression fits. In that case retain Core ownership only: a later crossing
+    // still applies its own limits, without adding a new constructor failure here.
+    try {
+        predicate = Object.freeze({
+            ...predicate,
+            predicate: portable.acceptImmutable(predicate.predicate),
+        });
+        predicate = portable.acceptImmutable(predicate);
+    }
+    catch (cause) {
+        if (!(cause instanceof portable.BoundaryError) || cause.code !== 'VALUE_LIMIT')
+            throw cause;
+    }
+    canonical.add(predicate);
+    retainClosedExpression(predicate.predicate);
+    expressions.set(predicate.predicate, predicate);
+    return predicate;
+}
+/** Closed subprograms retain their lexical proof when composed outside another local binder. */
+export function ownsExpression(expression, remainingDepth = Infinity) {
+    if (expression === null ||
+        typeof expression !== 'object' ||
+        !expressions.has(expression))
+        return false;
+    if (remainingDepth === Infinity)
+        return true;
+    const value = expression;
+    return expressionDepth(value) <= remainingDepth;
+}
+function expressionDepth(expression) {
+    const known = depths.get(expression);
+    if (known !== undefined)
+        return known;
+    const children = expression.op === 'all' || expression.op === 'any'
+        ? expression.predicates
+        : expression.op === 'not'
+            ? [expression.predicate]
+            : expression.op === 'as' || expression.op === 'exists'
+                ? [expression.where]
+                : [];
+    const depth = children.length === 0 ? 0 : 1 + Math.max(...children.map(expressionDepth));
+    depths.set(expression, depth);
+    return depth;
+}
+/** Rewrap only owner-proven closed expressions, never a leaf borrowed from a lexical binder. */
+export function ownedExpression(expression) {
+    const known = expressions.get(expression);
+    if (known === undefined)
+        return undefined;
+    if (known !== null)
+        return known;
+    const predicate = ownCanonical(Object.freeze({
+        version: AUTHORITY_PREDICATE_VERSION,
+        predicate: expression,
+    }));
+    expressions.set(expression, predicate);
+    return predicate;
+}
+function retainClosedExpression(expression) {
+    if (expressions.has(expression))
+        return;
+    expressions.set(expression, null);
+    if (expression.op === 'all' || expression.op === 'any') {
+        for (const child of expression.predicates)
+            retainClosedExpression(child);
+    }
+    else if (expression.op === 'not')
+        retainClosedExpression(expression.predicate);
+    // An identity binder or existential is closed, but its body may depend on its binder.
+}
+export function ownsCanonical(input) {
+    return input !== null && typeof input === 'object' && canonical.has(input);
+}

package/dist/auth/authority/prepare-binder-body.d.ts

@@ -0,0 +1,4 @@
+import type { IdentityId } from '../identity/index.js';
+import type { AuthorityExpr, AuthorityPredicate } from './language/index.js';
+/** Prepare one body in a fresh subject scope, independently of the Identity it will bind. */
+export declare function prepareBinderBody(where: AuthorityExpr): (identity: IdentityId) => AuthorityPredicate;

package/dist/auth/authority/prepare-binder-body.js

@@ -0,0 +1,31 @@
+import * as portable from '@astrale-os/kernel-dsl/value';
+import { isNodeId } from '../../graph/node/index.js';
+import { AuthValueError } from '../error.js';
+import { admitBinderBody } from './admission/index.js';
+import { AUTHORITY_PREDICATE_VERSION } from './language/index.js';
+import { normalizeBinderBodyAdmitted } from './normalization/index.js';
+import { ownCanonical } from './ownership.optimization.js';
+/** Prepare one body in a fresh subject scope, independently of the Identity it will bind. */
+export function prepareBinderBody(where) {
+    const admitted = admitBinderBody(portable.acceptForRead(where));
+    const body = portable.acceptImmutable(normalizeBinderBodyAdmitted(admitted));
+    return identityBinder(body);
+}
+// A distinct closure scope retains only the normalized body, never an initial Identity or input.
+function identityBinder(where) {
+    return (identity) => {
+        // Charge the entire expression on every binding, including the body and its outer container.
+        const value = portable.acceptForRead({ op: 'as', identity, where });
+        return ownCanonical(Object.freeze({
+            version: AUTHORITY_PREDICATE_VERSION,
+            predicate: Object.freeze({ op: 'as', identity: identityOf(value.identity), where }),
+        }));
+    };
+}
+// The same failure ordinary canonicalization reports for a malformed binder Identity.
+function identityOf(input) {
+    if (!isNodeId(input)) {
+        throw new AuthValueError('AUTHORITY_PREDICATE_INVALID', 'Expected one canonical IdentityId', '/predicate/identity');
+    }
+    return input;
+}

package/dist/auth/authority/program.d.ts

@@ -0,0 +1,28 @@
+import type { ClassRef } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { AuthorityPredicate } from './language/index.js';
+import { type AuthorityProgram, type PredicateRef } from './language/index.js';
+/** Collect one plan's predicates, then close them into one canonical program. */
+export interface AuthorityProgramBuilder {
+    /**
+     * Reserve a provisional handle. A thunk is compiled only when `finish` selects its handle, so a
+     * planner may reserve programs for positions it later drops.
+     */
+    intern(predicate: AuthorityPredicate | (() => AuthorityPredicate)): PredicateRef;
+    /** Close over the used handles (every reserved handle by default); the builder then closes. */
+    finish(used?: Iterable<PredicateRef>): ClosedAuthorityProgram;
+}
+export interface ClosedAuthorityProgram {
+    readonly program: AuthorityProgram;
+    /** Final ordinal of one used provisional handle. Equal predicates share one ordinal. */
+    ref(handle: PredicateRef): PredicateRef;
+}
+/**
+ * Start one plan's program over the concrete Identity Classes Runtime closed from the pinned
+ * Registry. Equal predicate sets always close to equal programs: members are canonical, unique and
+ * sorted by their canonical JSON text, so equal meaning yields equal plans.
+ */
+export declare function createAuthorityProgram(identities: readonly ClassRef[]): AuthorityProgramBuilder;
+/** Re-admit one crossing or persisted program; an owned program is returned as is. */
+export declare function acceptProgram(input: unknown): AuthorityProgram;
+/** True exactly for an in-range ordinal of `program`. */
+export declare function isPredicateRef(program: AuthorityProgram, value: unknown): value is PredicateRef;

package/dist/auth/authority/program.js

@@ -0,0 +1,191 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import * as portable from '@astrale-os/kernel-dsl/value';
+import { AuthValueError } from '../error.js';
+import { accept } from './accept.js';
+import { AUTHORITY_PREDICATE_VERSION, AUTHORITY_PROGRAM_VERSION, } from './language/index.js';
+import { ownsCanonical } from './ownership.optimization.js';
+/** Programs closed by this owner; admission of an owned program is an identity check. */
+const owned = new WeakSet();
+/**
+ * Start one plan's program over the concrete Identity Classes Runtime closed from the pinned
+ * Registry. Equal predicate sets always close to equal programs: members are canonical, unique and
+ * sorted by their canonical JSON text, so equal meaning yields equal plans.
+ */
+export function createAuthorityProgram(identities) {
+    const classes = canonicalIdentities(identities);
+    const entries = [];
+    const handles = new Map();
+    let closed = false;
+    return Object.freeze({
+        intern(predicate) {
+            if (closed)
+                throw new TypeError('Authority program is already closed.');
+            let handle = handles.get(predicate);
+            if (handle === undefined) {
+                handle = entries.length;
+                entries.push(predicate);
+                handles.set(predicate, handle);
+            }
+            return handle;
+        },
+        finish(used) {
+            if (closed)
+                throw new TypeError('Authority program is already closed.');
+            closed = true;
+            const selected = new Set(used ?? entries.keys());
+            const keys = new Map();
+            const members = new Map();
+            for (const handle of [...selected].sort((left, right) => left - right)) {
+                const entry = entries[handle];
+                if (entry === undefined)
+                    throw new TypeError('Unknown provisional Authority handle.');
+                const value = typeof entry === 'function' ? entry() : entry;
+                const predicate = ownsCanonical(value) ? value : accept(value);
+                const key = portable.json.serializeAdmitted(predicate.predicate);
+                keys.set(handle, key);
+                if (!members.has(key))
+                    members.set(key, predicate.predicate);
+            }
+            const sorted = [...members.keys()].sort(compare);
+            const ordinals = new Map(sorted.map((key, ordinal) => [key, ordinal]));
+            const program = own({
+                version: AUTHORITY_PROGRAM_VERSION,
+                identities: classes,
+                predicates: Object.freeze(sorted.map((key) => members.get(key))),
+            });
+            return Object.freeze({
+                program,
+                ref(handle) {
+                    const key = keys.get(handle);
+                    if (key === undefined)
+                        throw new TypeError('Authority handle was not closed.');
+                    return ordinals.get(key);
+                },
+            });
+        },
+    });
+}
+/** Re-admit one crossing or persisted program; an owned program is returned as is. */
+export function acceptProgram(input) {
+    if (input !== null && typeof input === 'object' && owned.has(input)) {
+        return input;
+    }
+    try {
+        const value = portable.accept(input);
+        if (value === null || Array.isArray(value) || typeof value !== 'object') {
+            invalid('', 'Expected an authority program object');
+        }
+        const record = value;
+        exact(record, ['identities', 'predicates', 'version'], '');
+        if (record.version !== AUTHORITY_PROGRAM_VERSION) {
+            invalid('/version', `Unsupported authority program version ${String(record.version)}`);
+        }
+        if (!Array.isArray(record.identities))
+            invalid('/identities', 'Expected an array');
+        const identities = record.identities.map((entry, index) => identityClass(entry, `/identities/${index}`));
+        const keys = identities.map(classKey);
+        for (let index = 1; index < keys.length; index++) {
+            if (compare(keys[index - 1], keys[index]) >= 0) {
+                invalid(`/identities/${index}`, 'Expected sorted unique Identity Classes');
+            }
+        }
+        if (!Array.isArray(record.predicates))
+            invalid('/predicates', 'Expected an array');
+        let previous;
+        const predicates = record.predicates.map((entry, index) => {
+            const path = `/predicates/${index}`;
+            let predicate;
+            try {
+                predicate = accept({ version: AUTHORITY_PREDICATE_VERSION, predicate: entry });
+            }
+            catch (cause) {
+                const pointer = cause instanceof AuthValueError ? cause.path.replace(/^\/predicate/u, '') : '';
+                throw new AuthValueError('AUTHORITY_PROGRAM_INVALID', 'Expected a canonical predicate', `${path}${pointer}`, {
+                    cause,
+                });
+            }
+            const key = portable.json.serializeAdmitted(predicate.predicate);
+            if (key !== portable.json.serializeAdmitted(entry)) {
+                invalid(path, 'Expected a canonical predicate');
+            }
+            if (previous !== undefined && compare(previous, key) >= 0) {
+                invalid(path, 'Expected sorted unique predicates');
+            }
+            previous = key;
+            return predicate.predicate;
+        });
+        return own({
+            version: AUTHORITY_PROGRAM_VERSION,
+            identities: Object.freeze(identities),
+            predicates: Object.freeze(predicates),
+        });
+    }
+    catch (cause) {
+        if (cause instanceof AuthValueError && cause.code === 'AUTHORITY_PROGRAM_INVALID')
+            throw cause;
+        const path = cause instanceof portable.BoundaryError ? cause.pointer : '';
+        throw new AuthValueError('AUTHORITY_PROGRAM_INVALID', 'Expected a canonical authority program', path, {
+            cause,
+        });
+    }
+}
+/**
+ * Retain the portable owner's immutable proof when the program fits its default bounds, so a
+ * read-only containing Plan capture keeps this identity; otherwise retain Core ownership only.
+ */
+function own(value) {
+    let program = Object.freeze(value);
+    try {
+        program = portable.acceptImmutable(program);
+    }
+    catch (cause) {
+        if (!(cause instanceof portable.BoundaryError) || cause.code !== 'VALUE_LIMIT')
+            throw cause;
+    }
+    owned.add(program);
+    return program;
+}
+/** True exactly for an in-range ordinal of `program`. */
+export function isPredicateRef(program, value) {
+    return (Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value < program.predicates.length);
+}
+function canonicalIdentities(input) {
+    const classes = new Map();
+    input.forEach((ref, index) => {
+        const value = identityClass(ref, `/identities/${index}`);
+        classes.set(classKey(value), value);
+    });
+    return Object.freeze([...classes.entries()].sort(([left], [right]) => compare(left, right)).map(([, ref]) => ref));
+}
+function identityClass(input, path) {
+    if (input === null || Array.isArray(input) || typeof input !== 'object') {
+        invalid(path, 'Expected a Class reference');
+    }
+    const value = input;
+    exact(value, ['kind', 'name', 'origin'], path);
+    if (value.kind !== 'class' ||
+        typeof value.origin !== 'string' ||
+        !patterns.origin.test(value.origin) ||
+        typeof value.name !== 'string' ||
+        !patterns.memberName.test(value.name)) {
+        invalid(path, 'Expected a canonical Class reference');
+    }
+    return Object.freeze({ origin: value.origin, kind: 'class', name: value.name });
+}
+function classKey(ref) {
+    return `${ref.origin}:${ref.kind}.${ref.name}`;
+}
+function exact(value, expected, path) {
+    const actual = Object.keys(value).sort(compare);
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        invalid(path, `Expected exactly ${expected.join(', ')}`);
+    }
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid(path, message) {
+    throw new AuthValueError('AUTHORITY_PROGRAM_INVALID', message, path);
+}

package/dist/auth/authority/semantics/class-authority.d.ts

@@ -0,0 +1,8 @@
+import type { AuthorityExpr, Requirement } from '../language/index.js';
+import type { AuthorityVocabulary } from './vocabulary.js';
+/**
+ * The meaning of `class-authority`. `owner` holds when the identity is the Domain that declares
+ * the Class. `allowed` holds for that owner, or when a capability Edge for the operation leads
+ * from the identity to the Class projection.
+ */
+export declare function classAuthorityMeaning(requirement: Requirement, vocabulary: AuthorityVocabulary): AuthorityExpr;

package/dist/auth/authority/semantics/class-authority.js

@@ -0,0 +1,26 @@
+/**
+ * The meaning of `class-authority`. `owner` holds when the identity is the Domain that declares
+ * the Class. `allowed` holds for that owner, or when a capability Edge for the operation leads
+ * from the identity to the Class projection.
+ */
+export function classAuthorityMeaning(requirement, vocabulary) {
+    const owner = {
+        op: 'same-node',
+        left: requirement.identity,
+        right: { kind: 'domain', origin: requirement.class.origin },
+    };
+    if (requirement.evidence === 'owner')
+        return owner;
+    return {
+        op: 'any',
+        predicates: [
+            owner,
+            {
+                op: 'related',
+                source: requirement.identity,
+                via: [vocabulary.capabilities[requirement.operation]],
+                target: { kind: 'class', ref: requirement.class },
+            },
+        ],
+    };
+}

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

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