@astrale-os/kernel-core 0.9.0-beta.62 → 0.9.0-beta.64

package/dist/auth/expression/authoring/builder.js

@@ -13,27 +13,6 @@ class Expression {
     build() {
         return this.value;
     }
-    union(other) {
-        return compose('union', this, other);
-    }
-    intersect(other) {
-        return compose('intersect', this, other);
-    }
-    exclude(other) {
-        const current = this.value;
-        if (current.kind === 'exclude') {
-            return expression({
-                kind: 'exclude',
-                base: current.base,
-                excluded: [...current.excluded, other.build()],
-            });
-        }
-        return expression({
-            kind: 'exclude',
-            base: current,
-            excluded: [other.build()],
-        });
-    }
 }
 /** Build one resolved Identity leaf. */
 export function identity(id) {
@@ -55,33 +34,10 @@ export function cred(credential) {
     }
     return expression(Object.freeze({ kind: 'identity', credential: credential.slice() }));
 }
-/** Re-enter the fluent algebra from an already trusted or separately admitted expression. */
+/** Re-enter from an already trusted or separately admitted Identity leaf. */
 export function raw(expr) {
     return expression(expr);
 }
-/** Compose at least two expressions of the same resolved or unresolved phase. */
-export function union(first, second, ...rest) {
-    return compose('union', first, second, ...rest);
-}
-/** Intersect at least two expressions of the same resolved or unresolved phase. */
-export function intersect(first, second, ...rest) {
-    return compose('intersect', first, second, ...rest);
-}
-/** Exclude one expression from another expression of the same phase. */
-export function exclude(base, excluded) {
-    return base.exclude(excluded);
-}
-function compose(kind, first, second, ...rest) {
-    const operands = [];
-    for (const builder of [first, second, ...rest]) {
-        const value = builder.build();
-        if (value.kind === kind)
-            operands.push(...value.operands);
-        else
-            operands.push(value);
-    }
-    return expression({ kind, operands });
-}
 function expression(value) {
     return Object.freeze(new Expression(value));
 }

package/dist/auth/expression/authoring/index.d.ts

@@ -1,2 +1,2 @@
 export type { BuiltExpr, Expr, ExprBuilder } from './builder.js';
-export { cred, exclude, identity, intersect, isExprBuilder, raw, self, union } from './builder.js';
+export { cred, identity, isExprBuilder, raw, self } from './builder.js';

package/dist/auth/expression/authoring/index.js

@@ -1 +1 @@
-export { cred, exclude, identity, intersect, isExprBuilder, raw, self, union } from './builder.js';
+export { cred, identity, isExprBuilder, raw, self } from './builder.js';

package/dist/auth/expression/index.d.ts

@@ -1,4 +1,3 @@
 export type { BuiltExpr, Expr, ExprBuilder } from './authoring/index.js';
-export { cred, exclude, identity, intersect, isExprBuilder, raw, self, union, } from './authoring/index.js';
+export { cred, identity, isExprBuilder, raw, self } from './authoring/index.js';
 export type { IdentityExpr, SelfIdentityExpr, UnresolvedIdentityExpr } from './language/index.js';
-export { canonicalize, raiseDenials } from './normalization/index.js';

package/dist/auth/expression/index.js

@@ -1,2 +1 @@
-export { cred, exclude, identity, intersect, isExprBuilder, raw, self, union, } from './authoring/index.js';
-export { canonicalize, raiseDenials } from './normalization/index.js';
+export { cred, identity, isExprBuilder, raw, self } from './authoring/index.js';

package/dist/auth/expression/language/identity-expression.d.ts

@@ -5,33 +5,13 @@ export type SelfIdentityExpr = {
     readonly kind: 'identity';
     readonly self: true;
 };
-/** Resolved Identity set algebra. Every leaf is one stable IdentityId. */
+/** The one resolved Identity leaf carried by Kernel bearer and delegation proof claims. */
 export type IdentityExpr = {
     readonly kind: 'identity';
     readonly id: IdentityId;
-} | {
-    readonly kind: 'union';
-    readonly operands: readonly IdentityExpr[];
-} | {
-    readonly kind: 'intersect';
-    readonly operands: readonly IdentityExpr[];
-} | {
-    readonly kind: 'exclude';
-    readonly base: IdentityExpr;
-    readonly excluded: readonly IdentityExpr[];
 };
-/** Caller-authored expression accepted only inside a versioned credential claim. */
+/** Caller-authored single leaf accepted only inside a versioned credential claim. */
 export type UnresolvedIdentityExpr = SelfIdentityExpr | {
     readonly kind: 'identity';
     readonly credential: CredentialInput;
-} | {
-    readonly kind: 'union';
-    readonly operands: readonly UnresolvedIdentityExpr[];
-} | {
-    readonly kind: 'intersect';
-    readonly operands: readonly UnresolvedIdentityExpr[];
-} | {
-    readonly kind: 'exclude';
-    readonly base: UnresolvedIdentityExpr;
-    readonly excluded: readonly UnresolvedIdentityExpr[];
 };

package/dist/auth/grant/index.d.ts

@@ -1,4 +1,4 @@
-export { accept, canonicalize, self } from './resolved/index.js';
+export { accept, self } from './resolved/index.js';
 export type { Grant } from './resolved/index.js';
 export { acceptUnresolved, limits } from './unresolved/index.js';
 export type { UnresolvedGrant } from './unresolved/index.js';

package/dist/auth/grant/index.js

@@ -1,2 +1,2 @@
-export { accept, canonicalize, self } from './resolved/index.js';
+export { accept, self } from './resolved/index.js';
 export { acceptUnresolved, limits } from './unresolved/index.js';

package/dist/auth/grant/resolved/admission.d.ts

@@ -1,5 +1,6 @@
 import type { Grant } from './grant.js';
-/** Admit one exact resolved Grant. */
+/**
+ * Admit one exact resolved claim value `{ expr: { kind: 'identity', id } }`. Compound structure
+ * keeps the unresolved claim's stable code, AUTH_GRANT_COMPOUND.
+ */
 export declare function accept(input: unknown): Grant;
-/** Re-canonicalize a trusted Grant value. */
-export declare function canonicalize(input: Grant): Grant;

package/dist/auth/grant/resolved/admission.js

@@ -1,30 +1,40 @@
 import * as portable from '@astrale-os/kernel-dsl/value';
+import { isNodeId, NodeId } from '../../../graph/node/index.js';
 import { AuthValueError } from '../../error.js';
-import { admitResolvedExpression, canonicalize as canonicalizeExpression, } from '../../expression/normalization/index.js';
-/** Admit one exact resolved Grant. */
+const COMPOUND = new Set(['union', 'intersect', 'exclude']);
+/**
+ * Admit one exact resolved claim value `{ expr: { kind: 'identity', id } }`. Compound structure
+ * keeps the unresolved claim's stable code, AUTH_GRANT_COMPOUND.
+ */
 export function accept(input) {
     try {
         const value = portable.accept(input);
-        if (value === null || Array.isArray(value) || typeof value !== 'object') {
-            invalid('', 'Expected a Grant object');
-        }
-        const grant = value;
+        const grant = record(value, '', 'Expected a Grant object');
         exact(grant, ['expr'], '');
-        if (grant.expr === undefined)
-            invalid('/expr', 'Expected a resolved Identity expression');
-        return Object.freeze({ expr: admitResolvedExpression(grant.expr, '/expr', 0) });
+        const expr = record(grant.expr, '/expr', 'Expected one resolved Identity leaf');
+        if (typeof expr.kind === 'string' && COMPOUND.has(expr.kind)) {
+            throw new AuthValueError('AUTH_GRANT_COMPOUND', 'Resolved Grant must name exactly one Identity', '/expr');
+        }
+        exact(expr, ['id', 'kind'], '/expr');
+        if (expr.kind !== 'identity')
+            invalid('/expr/kind', 'Expected one resolved Identity leaf');
+        if (typeof expr.id !== 'string' || !isNodeId(expr.id)) {
+            invalid('/expr/id', 'Expected one canonical IdentityId');
+        }
+        return Object.freeze({ expr: Object.freeze({ kind: 'identity', id: NodeId(expr.id) }) });
     }
     catch (cause) {
         if (cause instanceof AuthValueError)
             throw cause;
-        throw new AuthValueError('AUTH_GRANT_INVALID', 'Expected a canonical resolved Grant', '', {
+        throw new AuthValueError('AUTH_GRANT_INVALID', 'Expected a resolved single-Identity Grant', '', {
             cause,
         });
     }
 }
-/** Re-canonicalize a trusted Grant value. */
-export function canonicalize(input) {
-    return Object.freeze({ expr: canonicalizeExpression(input.expr) });
+function record(value, path, message) {
+    if (value === null || Array.isArray(value) || typeof value !== 'object')
+        invalid(path, message);
+    return value;
 }
 function exact(value, expected, path) {
     const actual = Object.keys(value).sort(compare);

package/dist/auth/grant/resolved/grant.d.ts

@@ -1,5 +1,5 @@
 import type { IdentityExpr } from '../../expression/language/index.js';
-/** One resolved, canonical authority expression. */
+/** The resolved single-identity claim value carried by Kernel bearers and delegation proofs. */
 export interface Grant {
     readonly expr: IdentityExpr;
 }

package/dist/auth/grant/resolved/index.d.ts

@@ -1,3 +1,3 @@
-export { accept, canonicalize } from './admission.js';
+export { accept } from './admission.js';
 export { self } from './self.js';
 export type { Grant } from './grant.js';

package/dist/auth/grant/resolved/index.js

@@ -1,2 +1,2 @@
-export { accept, canonicalize } from './admission.js';
+export { accept } from './admission.js';
 export { self } from './self.js';

package/dist/auth/grant/unresolved/admission.d.ts

@@ -1,3 +1,6 @@
 import type { UnresolvedGrant } from './grant.js';
-/** Admit the exact bounded unresolved Grant wire language. */
+/**
+ * Admit the exact version-1 unresolved Grant claim: exactly one `self` or one credential leaf.
+ * Compound structure is refused before any nested credential could be verified.
+ */
 export declare function acceptUnresolved(input: unknown): UnresolvedGrant;

package/dist/auth/grant/unresolved/admission.js

@@ -1,17 +1,17 @@
 import { AuthValueError } from '../../error.js';
-import { EXPRESSION_DEPTH_LIMIT, EXPRESSION_OPERAND_LIMIT, } from '../../expression/normalization/index.js';
-import { CREDENTIAL_BYTES_LIMIT, CREDENTIAL_NESTING_DEPTH_LIMIT } from './limits.js';
-/** Admit the exact bounded unresolved Grant wire language. */
+import { CREDENTIAL_BYTES_LIMIT } from './limits.js';
+const COMPOUND = new Set(['union', 'intersect', 'exclude']);
+/**
+ * Admit the exact version-1 unresolved Grant claim: exactly one `self` or one credential leaf.
+ * Compound structure is refused before any nested credential could be verified.
+ */
 export function acceptUnresolved(input) {
     try {
         const value = record(input, '');
         exact(value, ['expr', 'v'], '');
         if (data(value, 'v', '/v') !== 1)
             invalid('/v', 'Unsupported unresolved Grant version');
-        return Object.freeze({
-            v: 1,
-            expr: expression(data(value, 'expr', '/expr'), '/expr', 0, 0, new WeakSet()),
-        });
+        return Object.freeze({ v: 1, expr: leaf(data(value, 'expr', '/expr'), '/expr') });
     }
     catch (cause) {
         if (cause instanceof AuthValueError)
@@ -21,61 +21,29 @@ export function acceptUnresolved(input) {
         });
     }
 }
-function expression(input, path, depth, credentialDepth, active) {
-    if (depth > EXPRESSION_DEPTH_LIMIT)
-        invalid(path, 'Identity expression exceeds its depth limit');
+function leaf(input, path) {
     const value = record(input, path);
-    if (active.has(value))
-        invalid(path, 'Cyclic Identity expressions are not supported');
-    active.add(value);
-    try {
-        const kind = data(value, 'kind', `${path}/kind`);
-        switch (kind) {
-            case 'identity': {
-                const hasSelf = own(value, 'self');
-                const hasCredential = own(value, 'credential');
-                if (hasSelf === hasCredential)
-                    invalid(path, 'Expected exactly one unresolved Identity leaf');
-                if (hasSelf) {
-                    exact(value, ['kind', 'self'], path);
-                    if (data(value, 'self', `${path}/self`) !== true)
-                        invalid(`${path}/self`, 'Expected true');
-                    return Object.freeze({ kind: 'identity', self: true });
-                }
-                exact(value, ['credential', 'kind'], path);
-                if (credentialDepth >= CREDENTIAL_NESTING_DEPTH_LIMIT) {
-                    invalid(`${path}/credential`, 'Credential nesting exceeds its limit');
-                }
-                return Object.freeze({
-                    kind: 'identity',
-                    credential: credential(data(value, 'credential', `${path}/credential`), `${path}/credential`),
-                });
-            }
-            case 'union':
-            case 'intersect': {
-                exact(value, ['kind', 'operands'], path);
-                const operands = list(data(value, 'operands', `${path}/operands`), `${path}/operands`, 2);
-                return Object.freeze({
-                    kind,
-                    operands: Object.freeze(operands.map((operand, index) => expression(operand, `${path}/operands/${index}`, depth + 1, credentialDepth, active))),
-                });
-            }
-            case 'exclude': {
-                exact(value, ['base', 'excluded', 'kind'], path);
-                const excluded = list(data(value, 'excluded', `${path}/excluded`), `${path}/excluded`, 1);
-                return Object.freeze({
-                    kind: 'exclude',
-                    base: expression(data(value, 'base', `${path}/base`), `${path}/base`, depth + 1, credentialDepth, active),
-                    excluded: Object.freeze(excluded.map((operand, index) => expression(operand, `${path}/excluded/${index}`, depth + 1, credentialDepth, active))),
-                });
-            }
-            default:
-                invalid(`${path}/kind`, 'Expected identity, union, intersect, or exclude');
-        }
+    const kind = data(value, 'kind', `${path}/kind`);
+    if (typeof kind === 'string' && COMPOUND.has(kind)) {
+        throw new AuthValueError('AUTH_GRANT_COMPOUND', 'Unresolved Grant must name exactly one Identity', path);
+    }
+    if (kind !== 'identity')
+        invalid(`${path}/kind`, 'Expected identity');
+    const hasSelf = own(value, 'self');
+    if (hasSelf === own(value, 'credential')) {
+        invalid(path, 'Expected exactly one unresolved Identity leaf');
     }
-    finally {
-        active.delete(value);
+    if (hasSelf) {
+        exact(value, ['kind', 'self'], path);
+        if (data(value, 'self', `${path}/self`) !== true)
+            invalid(`${path}/self`, 'Expected true');
+        return Object.freeze({ kind: 'identity', self: true });
     }
+    exact(value, ['credential', 'kind'], path);
+    return Object.freeze({
+        kind: 'identity',
+        credential: credential(data(value, 'credential', `${path}/credential`), `${path}/credential`),
+    });
 }
 function credential(input, path) {
     if (typeof input === 'string') {
@@ -120,14 +88,6 @@ function exact(input, expected, path) {
         invalid(path, `Expected exactly ${expected.join(', ')}`);
     }
 }
-function list(input, path, minimum) {
-    if (!Array.isArray(input) || input.length < minimum || input.length > EXPRESSION_OPERAND_LIMIT) {
-        invalid(path, `Expected ${minimum}-${EXPRESSION_OPERAND_LIMIT} operands`);
-    }
-    if (Object.keys(input).length !== input.length)
-        invalid(path, 'Expected a dense array');
-    return input;
-}
 function compare(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }

package/dist/auth/grant/unresolved/limits.d.ts

@@ -1,7 +1,5 @@
-export declare const CREDENTIAL_NESTING_DEPTH_LIMIT = 3;
 export declare const CREDENTIAL_BYTES_LIMIT: number;
 export declare const limits: {
-    readonly expressionDepth: 32;
-    readonly operandsPerExpression: 64;
-    readonly credentialNestingDepth: 3;
+    /** One nested Kernel delegation proof; proofs never nest further. */
+    readonly credentialNestingDepth: 1;
 };

package/dist/auth/grant/unresolved/limits.js

@@ -1,8 +1,4 @@
-import { EXPRESSION_DEPTH_LIMIT, EXPRESSION_OPERAND_LIMIT, } from '../../expression/normalization/index.js';
-export const CREDENTIAL_NESTING_DEPTH_LIMIT = 3;
 export const CREDENTIAL_BYTES_LIMIT = 64 * 1024;
 export const limits = Object.freeze({
-    expressionDepth: EXPRESSION_DEPTH_LIMIT,
-    operandsPerExpression: EXPRESSION_OPERAND_LIMIT,
-    credentialNestingDepth: CREDENTIAL_NESTING_DEPTH_LIMIT,
+    credentialNestingDepth: 1,
 });

package/dist/auth/index.d.ts

@@ -1,6 +1,6 @@
 export { AuthValueError } from './error.js';
 export type { Attestation } from './attestation/index.js';
-export type { AuthorityExpr, AuthorityPredicate, ClosedEdgeExtent, } from './authority/language/index.js';
+export type { AuthorityExpr, AuthorityPredicate, AuthorityProgram, PredicateRef, ClosedEdgeExtent, } from './authority/language/index.js';
 export type { ClaimConstraint } from './claims/index.js';
 export type { AuthenticationEvidence, AuthenticationMethod, CredentialAudience, CredentialInput, MintedCredential, UnverifiedCredential, VerifiedCredential, } from './credential/index.js';
 export type { AuthContext, Authenticated, CredentialContext } from './context/index.js';

package/dist/graph/graph/graph.d.ts

@@ -1,18 +1,15 @@
-import type { Node } from '../node/index.js';
-import type { PathLike } from '../path/index.js';
 import type { GraphAdmissionContext } from './admission/index.js';
 import type { Delta, DeltaResult } from './delta/index.js';
 import type { GraphEdges, GraphNodes } from './indexes/index.js';
 import type { MergeResult } from './merge/index.js';
 import type { GraphData } from './model/index.js';
-import type { GraphPathWalker } from './navigation/index.js';
 /** Immutable indexed behavioral view over exactly one admitted GraphData value. */
 export declare class Graph {
     #private;
     readonly nodes: GraphNodes;
     readonly edges: GraphEdges;
     private constructor();
-    static admit(data: GraphData, context: GraphAdmissionContext, walker?: GraphPathWalker): Graph;
+    static admit(data: GraphData, context: GraphAdmissionContext): Graph;
     static empty(): Graph;
     /** Compare reference-open observations without deriving deletion from absence. */
     static delta(left: Graph, right: Graph): DeltaResult;
@@ -22,7 +19,6 @@ export declare class Graph {
     static merge(base: Graph, current: Graph, target: Graph): MergeResult;
     /** Apply the same exact merge rule to canonical finite values without schema re-admission. */
     static mergeData(base: GraphData, current: GraphData, target: GraphData): MergeResult;
-    walk(path: PathLike): Node | undefined;
     toData(): GraphData;
     equals(other: Graph): boolean;
 }

package/dist/graph/graph/graph.js

@@ -1,11 +1,9 @@
 import { edgeKeyOf } from '../edge/index.js';
-import { Path } from '../path/index.js';
 import { equal as equalProperties } from '../properties/index.js';
 import { admitGraphData } from './admission/index.js';
 import { apply as applyDelta, delta as graphDelta } from './delta/index.js';
 import { buildIndexes, createCollections } from './indexes/index.js';
 import { mergeData as mergeGraphData } from './merge/index.js';
-import { GraphPathWalkerRequiredError } from './navigation/index.js';
 const EMPTY_DATA = Object.freeze({
     nodes: Object.freeze([]),
     edges: Object.freeze([]),
@@ -17,30 +15,17 @@ export class Graph {
     nodes;
     edges;
     #data;
-    #indexes;
-    #walker;
-    #pathContext;
-    constructor(data, indexes, walker) {
+    constructor(data, indexes) {
         this.#data = data;
-        this.#indexes = indexes;
-        this.#walker = walker;
         const collections = createCollections(data.nodes, data.edges, indexes);
         this.nodes = collections.nodes;
         this.edges = collections.edges;
-        this.#pathContext = Object.freeze({
-            nodes: this.nodes,
-            edges: this.edges,
-            orientation: (classKey) => {
-                const info = this.#indexes.classes.byKey.get(classKey);
-                return info?.kind === 'edge' ? info.orientation : undefined;
-            },
-        });
         Object.freeze(this);
     }
-    static admit(data, context, walker) {
+    static admit(data, context) {
         const admitted = admitGraphData(data, context);
         const indexes = buildIndexes(admitted.data.nodes, admitted.data.edges, admitted.classes);
-        return new Graph(admitted.data, indexes, walker);
+        return new Graph(admitted.data, indexes);
     }
     static empty() {
         return Graph.#EMPTY;
@@ -61,15 +46,6 @@ export class Graph {
     static mergeData(base, current, target) {
         return mergeGraphData(base, current, target);
     }
-    walk(path) {
-        const value = Path.from(path);
-        if (this.#walker !== undefined)
-            return this.#walker.walk(value, this.#pathContext);
-        if (value.ast.anchor.kind === 'id' && value.ast.steps.length === 0) {
-            return this.#indexes.nodes.byId.get(value.ast.anchor.id);
-        }
-        throw new GraphPathWalkerRequiredError(value.raw);
-    }
     toData() {
         return this.#data;
     }

package/dist/graph/graph/index.d.ts

@@ -1,4 +1,4 @@
-/** Stable aggregate facade over Graph model, admission, indexes, navigation, delta, and merge. */
+/** Stable aggregate facade over Graph model, admission, indexes, delta, and merge. */
 export { Graph } from './graph.js';
 export type { Delta, DeltaConflict, DeltaResult } from './delta/index.js';
 export type { MergeConflict, MergeResult } from './merge/index.js';
@@ -8,5 +8,3 @@ export { LocalBinding, isLocalBinding } from './model/index.js';
 export type { GraphAdmissionContext, GraphClassInfo, GraphDiagnostic } from './admission/index.js';
 export { GraphAdmissionError } from './admission/index.js';
 export type { GraphEdges, GraphNodes } from './indexes/index.js';
-export type { GraphPathContext, GraphPathWalker } from './navigation/index.js';
-export { GraphPathAmbiguousError, GraphPathWalkerRequiredError } from './navigation/index.js';

package/dist/graph/graph/index.js

@@ -1,6 +1,5 @@
-/** Stable aggregate facade over Graph model, admission, indexes, navigation, delta, and merge. */
+/** Stable aggregate facade over Graph model, admission, indexes, delta, and merge. */
 export { Graph } from './graph.js';
 export { GraphData, GraphDataDecodeError, GraphSpec, GraphSpecDecodeError } from './model/index.js';
 export { LocalBinding, isLocalBinding } from './model/index.js';
 export { GraphAdmissionError } from './admission/index.js';
-export { GraphPathAmbiguousError, GraphPathWalkerRequiredError } from './navigation/index.js';

package/dist/graph/query/index.d.ts

@@ -5,5 +5,7 @@ export { QueryAST, QueryASTDecodeError } from './language/index.js';
 export type { EdgeBinding, NodeBinding, QueryBinding, QueryClassFilter, QueryClassPredicate, QueryClassSourceTerm, QueryClassSatisfiesPredicate, QueryClassEqualPredicate, QueryDirection, QueryEdgeSource, QueryEdgeSourceTerm, QueryEdgeSelect, QueryEdgeAST, QueryEdgeIdentityPredicate, QueryEdgeProjection, QueryExpand, QueryFingerprint, QueryIdentityFilter, QueryIdentityPredicate, QueryGraphSelect, QueryNodeAST, QueryNodeIdentityPredicate, QueryNodeProjection, QueryNodeSelect, QueryNodeSource, QueryNodeSourceTerm, QueryNodeTerminalSelect, QueryEdgeTerminalSelect, QueryOrderDirection, QueryPathSourceTerm, QueryPredicate, QueryProjectionShape, QueryPropertyEqualPredicate, QueryPropertyFilter, QueryPropertyOrder, QueryPropertyPredicate, QueryPropertyPresentPredicate, QuerySelect, QuerySingleSourceClassOf, QuerySource, QuerySourceClassesOf, QuerySourceTerm, QueryStep, QueryStructuralLimits, QueryUnrankedPlacement, } from './language/index.js';
 export { QueryResult, QueryResultDecodeError } from './result/index.js';
 export type { QueryEdgeComponentFor, QueryEdgeGraphResult, QueryEdgeItemFor, QueryEdgeResult, QueryGraphResult, QueryNodeComponentFor, QueryNodeGraphResult, QueryNodeItemFor, QueryNodeReference, QueryNodeResult, QueryResultFor, QueryResultForSelect, QuerySelection, QuerySelectionFor, } from './result/index.js';
+export { compareQueryIdentity, compareQueryRank, compareQueryText, compareQueryValue, } from './order/index.js';
+export type { QueryRank, QueryRankIdentity, QueryRankOrder, QueryRankValue } from './order/index.js';
 export { QueryReference, QueryReferenceError } from './reference/index.js';
 export type { QueryReferenceContext, QueryReferenceClassClosure, QueryReferenceEvaluation, QueryReferenceFrontier, QueryReferenceIdentity, QueryReferenceOptions, QueryReferencePathWitness, QueryReferenceProperty, QueryReferenceTrace, } from './reference/index.js';

package/dist/graph/query/index.js

@@ -2,4 +2,5 @@
 export { Property, Query } from './authoring/index.js';
 export { QueryAST, QueryASTDecodeError } from './language/index.js';
 export { QueryResult, QueryResultDecodeError } from './result/index.js';
+export { compareQueryIdentity, compareQueryRank, compareQueryText, compareQueryValue, } from './order/index.js';
 export { QueryReference, QueryReferenceError } from './reference/index.js';

package/dist/graph/query/order/index.d.ts

@@ -0,0 +1,46 @@
+import type { OrderingKind } from '@astrale-os/kernel-dsl/v1/language';
+import type { EdgeKey } from '../../edge/index.js';
+import type { NodeId } from '../../node/index.js';
+import type { QueryOrderDirection, QueryUnrankedPlacement } from '../language/index.js';
+/** The identity of one selected fact: a Node's NodeId or an Edge's complete EdgeKey. */
+export type QueryRankIdentity = NodeId | EdgeKey;
+/** A scalar ordering value of one proven kind; an instant is its canonical text. */
+export type QueryRankValue = boolean | number | string;
+/** One selected fact's position: its bucket, its ordering value when ranked, and its identity. */
+export type QueryRank<Identity extends QueryRankIdentity = QueryRankIdentity> = {
+    readonly bucket: 'identity';
+    readonly identity: Identity;
+} | {
+    readonly bucket: 'ranked';
+    readonly value: QueryRankValue;
+    readonly identity: Identity;
+} | {
+    readonly bucket: 'unranked';
+    readonly identity: Identity;
+};
+/** The ordering of one Property order: its proven value kind, direction and unranked placement. */
+export interface QueryRankOrder {
+    readonly kind: OrderingKind;
+    readonly direction: QueryOrderDirection;
+    readonly unranked: QueryUnrankedPlacement;
+}
+/**
+ * The one observable Query order. Without a Property order, facts follow identity order. With one,
+ * unranked facts sit first or last regardless of direction, ranked values compare by their kind in
+ * the requested direction, and identity breaks every tie: NodeId byte order, or EdgeKey order by
+ * source, target and ClassKey.
+ */
+export declare function compareQueryRank(left: QueryRank, right: QueryRank, order: QueryRankOrder | undefined): number;
+/**
+ * Compare two ordering values of one kind: false before true, numeric order, and code-point order
+ * for strings and instants.
+ */
+export declare function compareQueryValue(left: QueryRankValue, right: QueryRankValue, kind: OrderingKind): number;
+/**
+ * Unicode code-point order, which equals the byte order of the UTF-8 encodings. UTF-16 unit order
+ * differs from it only where a surrogate meets a unit at or above U+E000; the fixup reorders
+ * exactly that range.
+ */
+export declare function compareQueryText(left: string, right: string): number;
+/** Identity order: NodeId byte order, or EdgeKey (source, target, ClassKey) tuple order. */
+export declare function compareQueryIdentity(left: QueryRankIdentity, right: QueryRankIdentity): number;

package/dist/graph/query/order/index.js

@@ -0,0 +1,59 @@
+import { compareEdgeKeys } from '../../edge/index.js';
+import { compareNodeIds } from '../../node/index.js';
+/**
+ * The one observable Query order. Without a Property order, facts follow identity order. With one,
+ * unranked facts sit first or last regardless of direction, ranked values compare by their kind in
+ * the requested direction, and identity breaks every tie: NodeId byte order, or EdgeKey order by
+ * source, target and ClassKey.
+ */
+export function compareQueryRank(left, right, order) {
+    if (order !== undefined && left.bucket !== right.bucket) {
+        const first = order.unranked === 'first' ? 'unranked' : 'ranked';
+        return left.bucket === first ? -1 : 1;
+    }
+    if (order !== undefined && left.bucket === 'ranked' && right.bucket === 'ranked') {
+        const compared = compareQueryValue(left.value, right.value, order.kind);
+        if (compared !== 0)
+            return order.direction === 'asc' ? compared : -compared;
+    }
+    return compareQueryIdentity(left.identity, right.identity);
+}
+/**
+ * Compare two ordering values of one kind: false before true, numeric order, and code-point order
+ * for strings and instants.
+ */
+export function compareQueryValue(left, right, kind) {
+    if (kind === 'boolean')
+        return Number(left) - Number(right);
+    if (kind === 'number')
+        return Math.sign(left - right);
+    return compareQueryText(left, right);
+}
+/**
+ * Unicode code-point order, which equals the byte order of the UTF-8 encodings. UTF-16 unit order
+ * differs from it only where a surrogate meets a unit at or above U+E000; the fixup reorders
+ * exactly that range.
+ */
+export function compareQueryText(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index++) {
+        let a = left.charCodeAt(index);
+        let b = right.charCodeAt(index);
+        if (a === b)
+            continue;
+        if (a >= 0xd800 && b >= 0xd800) {
+            a += a >= 0xe000 ? -0x800 : 0x2000;
+            b += b >= 0xe000 ? -0x800 : 0x2000;
+        }
+        return a < b ? -1 : 1;
+    }
+    return Math.sign(left.length - right.length);
+}
+/** Identity order: NodeId byte order, or EdgeKey (source, target, ClassKey) tuple order. */
+export function compareQueryIdentity(left, right) {
+    if (typeof left === 'string' && typeof right === 'string')
+        return compareNodeIds(left, right);
+    if (typeof left !== 'string' && typeof right !== 'string')
+        return compareEdgeKeys(left, right);
+    throw new TypeError('Query rank identities of different kinds are not comparable.');
+}