@astrale-os/kernel-dsl 1.0.0-beta.2 → 1.0.0-beta.20

package/dist/v1/language/class/inheritance.js

@@ -1,6 +1,8 @@
+/** The origin of the Kernel, whose Schema every Domain depends on. */
+export const KERNEL_ORIGIN = 'kernel.astrale.ai';
 /** Kernel graph roots are intrinsic supertypes, not authored structural Edge contracts. */
 export function isGraphRoot(value) {
-    return (value.ref.origin === 'kernel.astrale.ai' &&
+    return (value.ref.origin === KERNEL_ORIGIN &&
         value.ref.name === (value.kind === 'node' ? 'Node' : 'Edge'));
 }
 /** Same-kind satisfaction includes the intrinsic root and the declared parent closure. */
@@ -23,3 +25,87 @@ export function classSatisfies(candidate, required, resolve) {
     };
     return visit(candidate);
 }
+/** The inheritance a Class declares, `'internal'` when it declares none. */
+export function inheritanceOf(declaration) {
+    return declaration.inheritance ?? 'internal';
+}
+/**
+ * Whether a Class of another Domain may extend this Class: only an `'open'` one admits it. Its own
+ * Domain may extend any Class that is not `'final'`.
+ */
+export function admitsForeignSubclass(declaration) {
+    return inheritanceOf(declaration) === 'open';
+}
+/**
+ * Whether `child` safely refines its parent Edge contract `parent`: same orientation, at least the
+ * parent's constraints, and endpoints whose accepted Classes `satisfies` one the paired parent
+ * endpoint accepts, within its count. Undirected endpoints may pair in either order.
+ */
+export function edgeContractRefines(child, parent, satisfies) {
+    if (isGraphRoot(parent))
+        return true;
+    if (child.orientation !== parent.orientation)
+        return false;
+    if (parent.constraints.noSelf === true && child.constraints.noSelf !== true)
+        return false;
+    if (parent.constraints.acyclic === true && child.constraints.acyclic !== true)
+        return false;
+    const endpointRefines = (childEndpoint, parentEndpoint) => childEndpoint.accepts.every((accepted) => satisfies(accepted, parentEndpoint.accepts));
+    if (child.orientation === 'directed' && parent.orientation === 'directed') {
+        return (endpointRefines(child.endpoints.source, parent.endpoints.source) &&
+            countRefines(child.endpoints.source.outgoing, parent.endpoints.source.outgoing) &&
+            endpointRefines(child.endpoints.target, parent.endpoints.target) &&
+            countRefines(child.endpoints.target.incoming, parent.endpoints.target.incoming));
+    }
+    if (child.orientation !== 'undirected' || parent.orientation !== 'undirected')
+        return false;
+    const refines = (childIndex, parentIndex) => endpointRefines(child.endpoints[childIndex], parent.endpoints[parentIndex]) &&
+        countRefines(child.endpoints[childIndex].incident, parent.endpoints[parentIndex].incident);
+    const direct = refines(0, 0) && refines(1, 1);
+    if (direct)
+        return true;
+    return refines(0, 1) && refines(1, 0);
+}
+function countRefines(child, parent) {
+    const [childMinimum, childMaximum] = countBounds(child);
+    const [parentMinimum, parentMaximum] = countBounds(parent);
+    return childMinimum >= parentMinimum && childMaximum <= parentMaximum;
+}
+/** Interpret an Edge count as inclusive degree bounds. */
+export function countBounds(value) {
+    switch (value) {
+        case '0..*':
+            return [0, Number.POSITIVE_INFINITY];
+        case '1..*':
+            return [1, Number.POSITIVE_INFINITY];
+        case '0..1':
+            return [0, 1];
+        case '1':
+            return [1, 1];
+    }
+}
+/** Whether Edges of one Class, read from source to target, close a cycle (`acyclic` forbids it). */
+export function hasDirectedCycle(edges) {
+    const outgoing = new Map();
+    for (const edge of edges) {
+        const targets = outgoing.get(edge.source.key) ?? [];
+        targets.push(edge.target.key);
+        outgoing.set(edge.source.key, targets);
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (key) => {
+        if (visiting.has(key))
+            return true;
+        if (visited.has(key))
+            return false;
+        visiting.add(key);
+        for (const target of outgoing.get(key) ?? [])
+            if (visit(target))
+                return true;
+        visiting.delete(key);
+        visited.add(key);
+        return false;
+    };
+    return [...outgoing.keys()].some(visit);
+}

package/dist/v1/language/class/lifetime.d.ts

@@ -1,17 +1,56 @@
 import type { ClassRef } from '../../addressing/index.js';
-import type { EdgeContract } from './model/edge.js';
+import type { ClassDefinition, EdgeClassDefinition } from './model/class.js';
+import type { EdgeContract, EdgeCount, EdgeEndpointBase, EdgeLifetime } from './model/edge.js';
+export type { EdgeLifetime } from './model/edge.js';
+/** The Classes lifetimes read: those of an Edge Class's Domain and of its dependency closure. */
+export interface LifetimeScope {
+    /**
+     * Whether a Node of another Domain may be of the Class: it is `'open'`, or a Class of its own
+     * Domain that extends it is.
+     */
+    readonly extendable: (ref: ClassRef) => boolean;
+}
+/** The lifetime scope of `classes`. */
+export declare function lifetimeScope(classes: Iterable<ClassDefinition>): LifetimeScope;
+/** One endpoint of an Edge contract and how many Edges of the Class each Node in it has. */
+export interface ContractEndpoint {
+    readonly endpoint: EdgeEndpointBase;
+    readonly count: EdgeCount;
+}
+/** The endpoints of an Edge contract in order: source then target, or the two incident ones. */
+export declare function contractEndpoints(contract: EdgeContract): readonly [ContractEndpoint, ContractEndpoint];
 /**
- * What deleting the Node at one endpoint does to an Edge: `restrict` requires the transition to
- * delete the Edge explicitly; `detach` deletes the Edge with the Node.
+ * Whether an endpoint of an Edge Class of `origin` can hold a Node of another Domain: it accepts a
+ * Class `origin` does not own, or one another Domain may extend. The Kernel's own relations are the
+ * exception: every Domain depends on the Kernel and extends its roots, so its relations bind every
+ * Node and keep the lifetimes they have as closed Classes, however open the Kernel's Classes are.
  */
-export type EdgeLifetime = 'restrict' | 'detach';
+export declare function reachesAnotherDomain(origin: ClassRef['origin'], endpoint: EdgeEndpointBase, scope: LifetimeScope): boolean;
 /**
- * The lifetime of each endpoint of an Edge Class, in endpoint order (source then target, or the two
- * incident endpoints), derived from the contract its Domain `origin` declares.
+ * The lifetime of each endpoint of `edge`, in endpoint order: the one it declares, else the derived
+ * one.
  *
- * An Edge Class binds only the Nodes of its own Domain and of the Domains that depend on it. An
- * endpoint that accepts a Class `origin` does not own can therefore reach a Node it does not bind,
- * and such a foreign endpoint detaches, unless an endpoint declares a minimum count that
- * detaching would break. Every other endpoint restricts.
+ * An Edge Class binds only the Nodes of its own Domain and of the Domains that depend on it, and a
+ * Domain blocks only the deletion of its own Nodes. An endpoint that can hold a Node of another
+ * Domain therefore detaches, unless an endpoint of the Class declares a minimum count that
+ * detaching could break (`requiredEndpoint`). Every other endpoint restricts.
  */
-export declare function edgeLifetimes(origin: ClassRef['origin'], contract: EdgeContract): readonly [EdgeLifetime, EdgeLifetime];
+export declare function edgeLifetimes(edge: EdgeClassDefinition, scope: LifetimeScope): readonly [EdgeLifetime, EdgeLifetime];
+/** One breach of the lifetime laws at one endpoint of an Edge Class: its index and why. */
+export interface LifetimeBreach {
+    readonly index: 0 | 1;
+    readonly reason: string;
+}
+/**
+ * The breaches of the lifetime laws (LANGUAGE-EDGE-LIFETIME) by the lifetimes `edge` declares: an
+ * endpoint that can hold a Node of another Domain never restricts, and none detaches in a Class
+ * with an endpoint that requires an Edge (`requiredEndpoint`). A derived lifetime breaks neither.
+ */
+export declare function lifetimeBreaches(edge: EdgeClassDefinition, scope: LifetimeScope): readonly LifetimeBreach[];
+/**
+ * The first endpoint of an Edge Class that requires an Edge, if one does, with its index. Detaching
+ * there could leave a Node below its count, so an endpoint of such a Class never detaches.
+ */
+export declare function requiredEndpoint(edge: EdgeContract): (ContractEndpoint & {
+    readonly index: 0 | 1;
+}) | undefined;

package/dist/v1/language/class/lifetime.js

@@ -1,26 +1,95 @@
-/**
- * The lifetime of each endpoint of an Edge Class, in endpoint order (source then target, or the two
- * incident endpoints), derived from the contract its Domain `origin` declares.
- *
- * An Edge Class binds only the Nodes of its own Domain and of the Domains that depend on it. An
- * endpoint that accepts a Class `origin` does not own can therefore reach a Node it does not bind,
- * and such a foreign endpoint detaches, unless an endpoint declares a minimum count that
- * detaching would break. Every other endpoint restricts.
- */
-export function edgeLifetimes(origin, contract) {
-    const endpoints = contract.orientation === 'directed'
+import { definitionRefIndex } from '../../addressing/ordering.js';
+import { KERNEL_ORIGIN } from './inheritance.js';
+/** The lifetime scope of `classes`. */
+export function lifetimeScope(classes) {
+    const declarations = new Map();
+    for (const declaration of classes)
+        declarations.set(definitionRefIndex(declaration.ref), declaration);
+    const extendable = new Set();
+    const open = (ref) => {
+        const key = definitionRefIndex(ref);
+        if (extendable.has(key))
+            return;
+        extendable.add(key);
+        for (const parent of declarations.get(key)?.extends ?? [])
+            if (parent.origin === ref.origin)
+                open(parent);
+    };
+    for (const declaration of declarations.values())
+        if (declaration.kind === 'node' && declaration.inheritance === 'open')
+            open(declaration.ref);
+    return Object.freeze({
+        extendable: (ref) => extendable.has(definitionRefIndex(ref)),
+    });
+}
+/** The endpoints of an Edge contract in order: source then target, or the two incident ones. */
+export function contractEndpoints(contract) {
+    return contract.orientation === 'directed'
         ? [
-            [contract.endpoints.source.accepts, contract.endpoints.source.outgoing],
-            [contract.endpoints.target.accepts, contract.endpoints.target.incoming],
+            { endpoint: contract.endpoints.source, count: contract.endpoints.source.outgoing },
+            { endpoint: contract.endpoints.target, count: contract.endpoints.target.incoming },
         ]
         : [
-            [contract.endpoints[0].accepts, contract.endpoints[0].incident],
-            [contract.endpoints[1].accepts, contract.endpoints[1].incident],
+            { endpoint: contract.endpoints[0], count: contract.endpoints[0].incident },
+            { endpoint: contract.endpoints[1], count: contract.endpoints[1].incident },
         ];
-    const required = endpoints.some(([, count]) => minimum(count) > 0);
-    const lifetime = ([accepts]) => !required && accepts.some((ref) => ref.origin !== origin) ? 'detach' : 'restrict';
-    return Object.freeze([lifetime(endpoints[0]), lifetime(endpoints[1])]);
 }
-function minimum(count) {
-    return count === '1' || count === '1..*' ? 1 : 0;
+/**
+ * Whether an endpoint of an Edge Class of `origin` can hold a Node of another Domain: it accepts a
+ * Class `origin` does not own, or one another Domain may extend. The Kernel's own relations are the
+ * exception: every Domain depends on the Kernel and extends its roots, so its relations bind every
+ * Node and keep the lifetimes they have as closed Classes, however open the Kernel's Classes are.
+ */
+export function reachesAnotherDomain(origin, endpoint, scope) {
+    return endpoint.accepts.some((ref) => ref.origin !== origin || (origin !== KERNEL_ORIGIN && scope.extendable(ref)));
+}
+/**
+ * The lifetime of each endpoint of `edge`, in endpoint order: the one it declares, else the derived
+ * one.
+ *
+ * An Edge Class binds only the Nodes of its own Domain and of the Domains that depend on it, and a
+ * Domain blocks only the deletion of its own Nodes. An endpoint that can hold a Node of another
+ * Domain therefore detaches, unless an endpoint of the Class declares a minimum count that
+ * detaching could break (`requiredEndpoint`). Every other endpoint restricts.
+ */
+export function edgeLifetimes(edge, scope) {
+    const required = requiredEndpoint(edge) !== undefined;
+    const [head, tail] = contractEndpoints(edge).map(({ endpoint }) => endpoint.onDelete ??
+        (!required && reachesAnotherDomain(edge.ref.origin, endpoint, scope) ? 'detach' : 'restrict'));
+    return Object.freeze([head, tail]);
+}
+/**
+ * The breaches of the lifetime laws (LANGUAGE-EDGE-LIFETIME) by the lifetimes `edge` declares: an
+ * endpoint that can hold a Node of another Domain never restricts, and none detaches in a Class
+ * with an endpoint that requires an Edge (`requiredEndpoint`). A derived lifetime breaks neither.
+ */
+export function lifetimeBreaches(edge, scope) {
+    const required = requiredEndpoint(edge)?.count;
+    return Object.freeze(contractEndpoints(edge).flatMap(({ endpoint }, index) => {
+        const at = index;
+        if (endpoint.onDelete === 'restrict' &&
+            reachesAnotherDomain(edge.ref.origin, endpoint, scope))
+            return [
+                {
+                    index: at,
+                    reason: 'can hold Nodes of another Domain and cannot restrict their deletion.',
+                },
+            ];
+        if (endpoint.onDelete === 'detach' && required !== undefined)
+            return [
+                {
+                    index: at,
+                    reason: `cannot detach: an endpoint of the Class requires ${required} Edges.`,
+                },
+            ];
+        return [];
+    }));
+}
+/**
+ * The first endpoint of an Edge Class that requires an Edge, if one does, with its index. Detaching
+ * there could leave a Node below its count, so an endpoint of such a Class never detaches.
+ */
+export function requiredEndpoint(edge) {
+    const index = contractEndpoints(edge).findIndex(({ count }) => count === '1' || count === '1..*');
+    return index === -1 ? undefined : { ...contractEndpoints(edge)[index], index: index };
 }

package/dist/v1/language/class/model/class.d.ts

@@ -1,32 +1,68 @@
-import type { ClassRef, DefinitionBase } from '../../../addressing/index.js';
+import type { ClassRef, DefinitionBase, PropertyKey } from '../../../addressing/index.js';
 import type { MethodRecord } from '../../callable/model/callable.js';
-import type { ClassPolicy, NodeClassPolicy } from '../../policy/model/policy.js';
+import type { EdgeClassPolicy, EdgeClassWritePolicy, NodeClassCreatePolicy, NodeClassPolicy, NodeClassWritePolicy } from '../../policy/model/policy.js';
 import type { DataFacet } from './data.js';
 import type { EdgeContract } from './edge.js';
-import type { PropertyFacet } from './property.js';
+import type { EdgePropertyDefinition, NodePropertyDefinition, PropertyFacet } from './property.js';
 export type ClassKind = 'node' | 'edge';
-/** An absent observation Policy admits every caller under the principal's Class capability. */
+/**
+ * Which Classes may extend a Class: `'open'`, those of its Domain and of every Domain that depends
+ * on that Domain; `'internal'`, those of its Domain only; `'final'`, none.
+ */
+export type Inheritance = 'open' | 'internal' | 'final';
+/**
+ * An absent observation rule admits every caller; a delegation is still scoped by its ceiling. An
+ * absent write rule admits only the Domain that declares the Class.
+ */
 export interface NodeClassPolicies {
     readonly read?: NodeClassPolicy;
     readonly traverse?: NodeClassPolicy;
+    readonly create?: NodeClassCreatePolicy;
+    readonly update?: NodeClassWritePolicy;
+    readonly delete?: NodeClassWritePolicy;
 }
-/** An absent observation Policy admits every caller under the principal's Class capability. */
+/**
+ * An absent observation rule admits every caller; a delegation is still scoped by its ceiling. An
+ * absent write rule admits only the Domain that declares the Class.
+ */
 export interface EdgeClassPolicies {
-    readonly read?: ClassPolicy;
-    readonly traverse?: ClassPolicy;
+    readonly read?: EdgeClassPolicy;
+    readonly traverse?: EdgeClassPolicy;
+    readonly create?: EdgeClassWritePolicy;
+    readonly update?: EdgeClassWritePolicy;
+    readonly delete?: EdgeClassWritePolicy;
 }
-export interface NodeClassDefinition extends DefinitionBase<ClassRef>, PropertyFacet, DataFacet {
+/**
+ * The Properties one key of a Node Class names, own or inherited, which no two Nodes of the Classes
+ * it covers share while each of them is present: distinct, by key in code-point order.
+ */
+export type NodeUniqueTuple = readonly [PropertyKey, ...PropertyKey[]];
+/**
+ * The form of a Node key tuple: its fields are Properties, whatever their keys and number. A
+ * backend announces it to enforce Node keys, so a tuple is never ignored where it is not.
+ */
+export type NodeUniqueForm = readonly ['property'];
+export interface NodeClassDefinition extends DefinitionBase<ClassRef>, PropertyFacet<NodePropertyDefinition>, DataFacet {
     readonly kind: 'node';
     readonly abstract: boolean;
+    /** Absent when `'internal'`, the default, so a Class that keeps the default keeps its revision. */
+    readonly inheritance?: Exclude<Inheritance, 'internal'>;
     readonly description?: string;
     readonly extends: readonly ClassRef[];
     readonly methods: MethodRecord;
     readonly icon?: string;
     readonly policies: NodeClassPolicies;
+    /**
+     * The tuples no two Nodes of this Class and of its active concrete descendants share while every
+     * Property is present; absent, none. A descendant is covered without declaring them again.
+     */
+    readonly unique?: readonly [NodeUniqueTuple, ...NodeUniqueTuple[]];
 }
-export type EdgeClassDefinition = DefinitionBase<ClassRef> & PropertyFacet & EdgeContract & {
+export type EdgeClassDefinition = DefinitionBase<ClassRef> & PropertyFacet<EdgePropertyDefinition> & EdgeContract & {
     readonly kind: 'edge';
     readonly abstract: boolean;
+    /** Absent when `'internal'`, the default, so a Class that keeps the default keeps its revision. */
+    readonly inheritance?: Exclude<Inheritance, 'internal'>;
     readonly description?: string;
     readonly extends: readonly ClassRef[];
     readonly policies: EdgeClassPolicies;

package/dist/v1/language/class/model/edge.d.ts

@@ -1,9 +1,16 @@
-import type { ClassRef } from '../../../addressing/index.js';
+import type { ClassRef, PropertyKey } from '../../../addressing/index.js';
 export type EdgeCount = '0..*' | '1..*' | '0..1' | '1';
 export type EdgeOrientation = 'directed' | 'undirected';
+/**
+ * What deleting the Node at one endpoint does to an Edge: `restrict` requires the transition to
+ * delete the Edge explicitly; `detach` deletes the Edge with the Node.
+ */
+export type EdgeLifetime = 'restrict' | 'detach';
 export interface EdgeEndpointBase {
     readonly role: string;
-    readonly accepts: readonly ClassRef[];
+    readonly accepts: readonly [ClassRef, ...ClassRef[]];
+    /** Declared only when authored; otherwise derived (`edgeLifetimes`). */
+    readonly onDelete?: EdgeLifetime;
 }
 export interface DirectedSourceEndpoint extends EdgeEndpointBase {
     readonly outgoing: EdgeCount;
@@ -22,6 +29,22 @@ export interface UndirectedEdgeConstraints {
     readonly noSelf?: true;
     readonly acyclic?: never;
 }
+/** A field a key tuple names: an endpoint of the Edge, its slug, or one of its Properties. */
+export type EdgeUniqueField = 'source' | 'target' | 'slug' | {
+    readonly property: PropertyKey;
+};
+/**
+ * The fields one key of a directed Edge Class names, which no two Edges of the Classes it covers
+ * share while each of them is present: distinct, in canonical order (`compareEdgeUniqueFields`).
+ */
+export type EdgeUniqueTuple = readonly [EdgeUniqueField, ...EdgeUniqueField[]];
+/** The kind of a key field: an endpoint, the slug, or a Property whatever its key. */
+export type EdgeUniqueFieldKind = 'source' | 'target' | 'slug' | 'property';
+/**
+ * The form of a key tuple: the kinds of its fields, each once, in canonical order. A backend
+ * announces the forms it enforces, so a tuple of a form it does not announce is never ignored.
+ */
+export type EdgeUniqueForm = readonly [EdgeUniqueFieldKind, ...EdgeUniqueFieldKind[]];
 export interface DirectedEdgeContract {
     readonly orientation: 'directed';
     readonly endpoints: {
@@ -29,10 +52,16 @@ export interface DirectedEdgeContract {
         readonly target: DirectedTargetEndpoint;
     };
     readonly constraints: DirectedEdgeConstraints;
+    /**
+     * The tuples no two Edges of this Class and of its active concrete descendants share. Absent
+     * when the Class declares none, so a Class without one keeps its revision; never empty.
+     */
+    readonly unique?: readonly [EdgeUniqueTuple, ...EdgeUniqueTuple[]];
 }
 export interface UndirectedEdgeContract {
     readonly orientation: 'undirected';
     readonly endpoints: readonly [IncidentEndpoint, IncidentEndpoint];
     readonly constraints: UndirectedEdgeConstraints;
+    readonly unique?: never;
 }
 export type EdgeContract = DirectedEdgeContract | UndirectedEdgeContract;

package/dist/v1/language/class/model/property.d.ts

@@ -1,20 +1,29 @@
+import type { StateTopology } from '../../state/index.js';
+import type { JsonSchema } from '../../value/model/schema.js';
 export type AutoEvent = 'create' | 'update';
 export type AutoSet = 'instant';
 /** `create`: written only by node or edge creation. `once`: written while absent, never unset. */
 export type PropertyImmutability = 'create' | 'once';
 export interface PropertyAuto {
-    readonly on: readonly AutoEvent[];
+    readonly on: readonly [AutoEvent, ...AutoEvent[]];
     readonly set: AutoSet;
 }
-export interface PropertyDefinition {
-    readonly schema: import('../../value/model/schema.js').JsonSchema;
+/** A Property of a Node Class, which may be a State Property. */
+export interface NodePropertyDefinition {
+    readonly schema: JsonSchema;
     readonly required: boolean;
     readonly auto?: PropertyAuto;
     readonly immutable?: PropertyImmutability;
     readonly description?: string;
-    readonly state?: import('../../state/index.js').StateTopology;
+    readonly state?: StateTopology;
 }
-export type PropertyRecord = Readonly<Record<string, PropertyDefinition>>;
-export interface PropertyFacet {
-    readonly properties: PropertyRecord;
+/** A Property of an Edge Class: an Edge has no State Property. */
+export interface EdgePropertyDefinition extends Omit<NodePropertyDefinition, 'state'> {
+    readonly state?: never;
+}
+/** A Property of a Class of either kind. */
+export type PropertyDefinition = NodePropertyDefinition | EdgePropertyDefinition;
+export type PropertyRecord<Definition extends PropertyDefinition = PropertyDefinition> = Readonly<Record<string, Definition>>;
+export interface PropertyFacet<Definition extends PropertyDefinition = PropertyDefinition> {
+    readonly properties: PropertyRecord<Definition>;
 }

package/dist/v1/language/class/property-values.js

@@ -1,6 +1,7 @@
 import { acceptPropertyRoot } from '../../../value/accept.js';
 import { isImmutableSnapshot } from '../../../value/immutable.optimization.js';
 import { PropertyKey as admitPropertyKey } from '../../addressing/index.js';
+import { compareCodeUnits } from '../../addressing/ordering.js';
 export function acceptPropertyValues(input, pointer = '') {
     const admitted = acceptPropertyRoot(input);
     if (admitted === null || typeof admitted !== 'object' || Array.isArray(admitted)) {
@@ -10,7 +11,7 @@ export function acceptPropertyValues(input, pointer = '') {
 }
 export function createPropertyValues(entries) {
     const output = Object.create(null);
-    for (const [key, value] of [...entries].sort(([left], [right]) => compare(left, right))) {
+    for (const [key, value] of [...entries].sort(([left], [right]) => compareCodeUnits(left, right))) {
         Object.defineProperty(output, key, { enumerable: true, value: freeze(value) });
     }
     return Object.freeze(output);
@@ -28,6 +29,3 @@ function freeze(value) {
         freeze(member);
     return Object.freeze(value);
 }
-function compare(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}

package/dist/v1/language/class/unique.d.ts

@@ -0,0 +1,143 @@
+import type { Value as PortableValue } from '@astrale-os/kernel-dsl/value';
+import type { ClassRef } from '../../addressing/index.js';
+import type { OrderingKind } from '../value/ordering.js';
+import type { ClassAncestry } from './inheritance.js';
+import type { NodeUniqueForm, NodeUniqueTuple } from './model/class.js';
+import type { EdgeUniqueField, EdgeUniqueForm, EdgeUniqueTuple } from './model/edge.js';
+import { ClassKey } from '../../addressing/class-key.js';
+/**
+ * Every form a key tuple may take, in canonical order: each nonempty set of field kinds. A Property
+ * kind stands for one Property or more, whatever their keys.
+ */
+export declare const EDGE_UNIQUE_FORMS: readonly EdgeUniqueForm[];
+/** The one form a Node key tuple takes: its fields are Properties, whatever their keys. */
+export declare const NODE_UNIQUE_FORMS: readonly NodeUniqueForm[];
+/**
+ * The forms of key tuples a backend enforces, by the kind of the Classes they constrain: a Node key
+ * reads Node Properties and an Edge key the fields of an Edge, so announcing one says nothing of
+ * the other.
+ */
+export interface UniqueForms {
+    readonly edge: readonly EdgeUniqueForm[];
+    readonly node: readonly NodeUniqueForm[];
+}
+/** Every form of every kind, which a backend enforcing any key tuple announces. */
+export declare const UNIQUE_FORMS: UniqueForms;
+/** No form of either kind: a backend that announces none enforces no key tuple. */
+export declare const NO_UNIQUE_FORMS: UniqueForms;
+/** The fields of an Edge a key tuple reads; the slug is absent from an Edge without one. */
+export interface EdgeUniqueFacts {
+    readonly source: string;
+    readonly target: string;
+    readonly slug?: string;
+    /** Its Property values by key; a Property it lacks is absent. */
+    readonly props: Readonly<Record<string, PortableValue>>;
+}
+/** The Properties of a Node a key tuple reads by key; a Property it lacks is absent. */
+export interface NodeUniqueFacts {
+    readonly props: Readonly<Record<string, PortableValue>>;
+}
+/** The canonical order of fields: source, target, slug, then Properties by key. */
+export declare function compareEdgeUniqueFields(left: EdgeUniqueField, right: EdgeUniqueField): number;
+/** The canonical order of tuples: field by field, a tuple before every tuple it prefixes. */
+export declare const compareEdgeUniqueTuples: (left: EdgeUniqueTuple, right: EdgeUniqueTuple) => number;
+/**
+ * The tuple `value` spells, detached, or undefined when it spells none: a nonempty list of fields,
+ * distinct and in canonical order, so one set of fields has one spelling.
+ */
+export declare function edgeUniqueTuple(value: unknown): EdgeUniqueTuple | undefined;
+/**
+ * The tuple the endpoints and slug `named` holds spell, in canonical order, or undefined when it
+ * holds none: the key a selector names an Edge by. A selector names no Property.
+ */
+export declare function namedEdgeUniqueTuple(named: {
+    readonly source?: unknown;
+    readonly target?: unknown;
+    readonly slug?: unknown;
+}): EdgeUniqueTuple | undefined;
+/** The canonical order of Node tuples: Property by Property, a tuple before every one it prefixes. */
+export declare const compareNodeUniqueTuples: (left: NodeUniqueTuple, right: NodeUniqueTuple) => number;
+/**
+ * The Node tuple `value` spells, detached, or undefined when it spells none: a nonempty list of
+ * Property keys, distinct and in code-point order, so one set of Properties has one spelling.
+ */
+export declare function nodeUniqueTuple(value: unknown): NodeUniqueTuple | undefined;
+/** The form of `NODE_UNIQUE_FORMS` that `value` spells, or undefined when it spells none. */
+export declare function nodeUniqueForm(value: unknown): NodeUniqueForm | undefined;
+/**
+ * Whether a backend announcing `forms` for Nodes enforces the Node tuple `value` spells: every
+ * Node tuple has the one Node form. False when `value` spells no tuple.
+ */
+export declare function enforcesNodeUniqueTuple(forms: readonly NodeUniqueForm[], value: unknown): boolean;
+/** The form of `tuple`: the kinds of its fields, each once. */
+export declare function edgeUniqueFormOf(tuple: EdgeUniqueTuple): EdgeUniqueForm;
+/** The form of `EDGE_UNIQUE_FORMS` that `value` spells, or undefined when it spells none. */
+export declare function edgeUniqueForm(value: unknown): EdgeUniqueForm | undefined;
+/**
+ * Whether a backend announcing `forms` enforces the tuple `value` spells: its form is one of them.
+ * False when `value` spells no tuple, so a tuple is never taken as enforced by mistake.
+ */
+export declare function enforcesEdgeUniqueTuple(forms: readonly EdgeUniqueForm[], value: unknown): boolean;
+/**
+ * Whether a Property may be a key field (D-S1): a single-kind scalar by its ordering facet, a
+ * string, number, boolean or instant, that no automatic program writes.
+ */
+export declare function keyableProperty(ordering: OrderingKind | undefined, auto: unknown): boolean;
+/**
+ * The values of the fields of `tuple` on `edge`, in order, or undefined when one of them is absent,
+ * so that an Edge without a slug or without a Property never collides.
+ */
+export declare function edgeUniqueValues(tuple: EdgeUniqueTuple, edge: EdgeUniqueFacts): readonly PortableValue[] | undefined;
+/**
+ * The value `edge` takes under `tuple`, the canonical JSON of the values of its fields, or
+ * undefined when one of them is absent: two distinct Edges of the Classes a tuple covers collide
+ * exactly when they take one value. Endpoints compare by NodeId, slugs by exact text and
+ * Properties by canonical Value.
+ */
+export declare function edgeUniqueValue(tuple: EdgeUniqueTuple, edge: EdgeUniqueFacts): string | undefined;
+/**
+ * The values of the Properties of `tuple` on `node`, in order, or undefined when one of them is
+ * absent, so that a Node without one of them never collides, like NULL in an SQL UNIQUE.
+ */
+export declare function nodeUniqueValues(tuple: NodeUniqueTuple, node: NodeUniqueFacts): readonly PortableValue[] | undefined;
+/**
+ * The value `node` takes under `tuple`, the canonical JSON of the values of its Properties, or
+ * undefined when one of them is absent: two distinct Nodes of the Classes a tuple covers collide
+ * exactly when they take one value. Properties compare by canonical Value, nothing normalized.
+ */
+export declare function nodeUniqueValue(tuple: NodeUniqueTuple, node: NodeUniqueFacts): string | undefined;
+/** A Class with the key tuples it declares, an Edge Class or a Node Class. */
+type KeyedClass = ClassAncestry & {
+    readonly unique?: readonly (EdgeUniqueTuple | NodeUniqueTuple)[];
+};
+/** A key tuple together with the Class declaring it, whose descendants it covers. */
+export interface DeclaredEdgeUniqueTuple {
+    readonly class: ClassKey;
+    readonly fields: EdgeUniqueTuple;
+}
+/** A Node key tuple together with the Class declaring it, whose descendants it covers. */
+export interface DeclaredNodeUniqueTuple {
+    readonly class: ClassKey;
+    readonly fields: NodeUniqueTuple;
+}
+/**
+ * The tuples covering `candidate`: those it and each of its ancestors declare, each with the Class
+ * declaring it, ancestors found by `resolve`. A descendant never restates them.
+ */
+export declare function coveringEdgeUniqueTuples<Declaration extends KeyedClass>(candidate: Declaration, resolve: (ref: ClassRef) => Declaration | undefined): readonly DeclaredEdgeUniqueTuple[];
+/**
+ * The Node tuples covering `candidate`: those it and each of its ancestors declare, each with the
+ * Class declaring it, ancestors found by `resolve`. A descendant never restates them.
+ */
+export declare function coveringNodeUniqueTuples<Declaration extends KeyedClass>(candidate: Declaration, resolve: (ref: ClassRef) => Declaration | undefined): readonly DeclaredNodeUniqueTuple[];
+/**
+ * The keys `edge` holds: its value under each tuple of `tuples`, tagged by the Class declaring the
+ * tuple, so two Edges collide exactly when they hold one key.
+ */
+export declare function edgeUniqueKeys(tuples: readonly DeclaredEdgeUniqueTuple[], edge: EdgeUniqueFacts): readonly string[];
+/**
+ * The keys `node` holds: its value under each tuple of `tuples`, tagged by the Class declaring the
+ * tuple, so two Nodes collide exactly when they hold one key.
+ */
+export declare function nodeUniqueKeys(tuples: readonly DeclaredNodeUniqueTuple[], node: NodeUniqueFacts): readonly string[];
+export {};