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

package/dist/v1/builder/lowering/property-keys.js

@@ -0,0 +1,108 @@
+import { PropertyKey as admitPropertyKey } from '../../addressing/index.js';
+import { definitionRefIndex } from '../../addressing/ordering.js';
+import { createPropertyValues } from '../../language/class/property-values.js';
+import { analyzeDefinitions } from '../../schema/analysis/class.js';
+import { buildDomainResolutionContext } from '../../schema/resolution/context.js';
+import { escapeToken, fail } from '../schema/diagnostic.js';
+/**
+ * Analyze the already-canonical Definition surface of `candidate` once, so Property shorthand
+ * resolves against each Class's own and inherited Properties. Core values and key tuples take no
+ * part in Class composition, so they are left out of the analysis.
+ */
+export function analyzePropertyOwners(candidate, lookup) {
+    const analysisCandidate = {
+        ...candidate,
+        core: { nodes: {}, edges: [] },
+    };
+    return analyzeDefinitions(buildDomainResolutionContext(analysisCandidate, lookup)).definitions;
+}
+/** Lower rich builder shorthand to the canonical full-key Core representation. */
+export function canonicalizeCorePropertyKeys(core, owners) {
+    const nodes = Object.fromEntries(Object.entries(core.nodes).map(([slug, node]) => {
+        const definition = owners.get(definitionRefIndex(node.class));
+        if (definition === undefined) {
+            fail('BUILDER_CORE_PROPERTY', `/core/nodes/${escapeToken(slug)}/class`, 'Core property shorthand requires a resolvable concrete Class.');
+        }
+        return [
+            slug,
+            {
+                ...node,
+                properties: qualify(node.properties, definition, `/core/nodes/${escapeToken(slug)}/properties`),
+            },
+        ];
+    }));
+    const edges = core.edges.map((edge, index) => {
+        const definition = owners.get(definitionRefIndex(edge.class));
+        if (definition === undefined) {
+            fail('BUILDER_CORE_PROPERTY', `/core/edges/${index}/class`, 'Core property shorthand requires a resolvable concrete Class.');
+        }
+        return {
+            ...edge,
+            properties: qualify(edge.properties, definition, `/core/edges/${index}/properties`),
+        };
+    });
+    return { nodes, edges };
+}
+/**
+ * Lower each Property a key tuple names by its name to its full key among the Class's own and
+ * inherited Properties; a full key stays as authored. Ambiguity and absence are refused here, so a
+ * tuple never names a Property the author did not mean. A Node tuple names Properties only; an Edge
+ * tuple names them as `{ property }` beside its structural fields.
+ */
+export function canonicalizeUniquePropertyKeys(classes, origin, owners) {
+    return Object.fromEntries(Object.entries(classes).map(([name, declaration]) => {
+        if (declaration.kind === 'edge' && declaration.orientation !== 'directed') {
+            return [name, declaration];
+        }
+        if (declaration.unique === undefined)
+            return [name, declaration];
+        const ref = { origin, kind: 'class', name };
+        const definition = owners.get(definitionRefIndex(ref));
+        const pointer = `/classes/${escapeToken(name)}/unique`;
+        const resolve = (input, at) => {
+            if (definition === undefined) {
+                fail('BUILDER_UNIQUE_PROPERTY', at, 'A key Property requires a resolvable Class.');
+            }
+            return resolveInputKey(input, definition, 'BUILDER_UNIQUE_PROPERTY', at);
+        };
+        if (declaration.kind === 'node') {
+            const unique = declaration.unique.map((tuple, t) => tuple.map((key, f) => resolve(key, `${pointer}/${t}/${f}`)));
+            return [name, { ...declaration, unique }];
+        }
+        const unique = declaration.unique.map((tuple, t) => tuple.map((field, f) => typeof field === 'string'
+            ? field
+            : { property: resolve(field.property, `${pointer}/${t}/${f}/property`) }));
+        return [name, { ...declaration, unique }];
+    }));
+}
+function qualify(input, definition, pointer) {
+    const result = {};
+    const sourceByKey = new Map();
+    for (const [inputKey, value] of Object.entries(input)) {
+        const key = resolveInputKey(inputKey, definition, 'BUILDER_CORE_PROPERTY', `${pointer}/${escapeToken(inputKey)}`);
+        const previous = sourceByKey.get(key);
+        if (previous !== undefined) {
+            fail('BUILDER_CORE_PROPERTY', `${pointer}/${escapeToken(inputKey)}`, `Property is supplied twice through ${JSON.stringify(previous)} and ${JSON.stringify(inputKey)}.`);
+        }
+        sourceByKey.set(key, inputKey);
+        result[key] = value;
+    }
+    return createPropertyValues(Object.entries(result).map(([key, value]) => [admitPropertyKey(key), value]));
+}
+/** The full key of the Property `input` names on `definition`: its full key, or its unique name. */
+function resolveInputKey(input, definition, code, pointer) {
+    if (admitPropertyKey.is(input)) {
+        const key = admitPropertyKey(input);
+        if (!definition.properties.has(key)) {
+            fail(code, pointer, `Property ${input} is not present on the Class.`);
+        }
+        return key;
+    }
+    const candidates = [...definition.properties].flatMap(([key, field]) => field.name === input ? [key] : []);
+    if (candidates.length === 1)
+        return candidates[0];
+    if (candidates.length === 0) {
+        fail(code, pointer, `Property ${JSON.stringify(input)} does not exist.`);
+    }
+    fail(code, pointer, `Property ${JSON.stringify(input)} is ambiguous; use one of: ${candidates.join(', ')}.`);
+}

package/dist/v1/builder/lowering/schema/compile.js

@@ -1,19 +1,20 @@
+import { deepFreeze } from '../../../language/freeze.js';
 import { acceptDomainSchema } from '../../../schema/admission/accept.js';
-import { canonicalizeDomainSchema } from '../../../schema/canonical/domain.js';
-import { deepFreeze } from '../../../schema/canonical/freeze.js';
 import { MemoryDomainSchemaLookup } from '../../../schema/dependency/lookup.js';
+import { normalizeDomainSchema } from '../../../schema/normalization/domain.js';
 import { lookupEntriesForDependencies } from '../../../schema/resolution/closure.js';
 import { parseDomainSchemaStructure } from '../../../schema/validation/domain.structure.js';
 import { assertKnownKeys, escapeToken } from '../../schema/diagnostic.js';
 import { V1CallableCompiler } from '../callable.js';
 import { V1DefinitionCompiler } from '../class.js';
-import { canonicalizeCorePropertyKeys } from '../core-properties.js';
 import { compileCore } from '../core.js';
 import { assertPolicyCompositionAcyclic, V1PolicyCompiler } from '../policy.js';
+import { analyzePropertyOwners, canonicalizeCorePropertyKeys, canonicalizeUniquePropertyKeys, } from '../property-keys.js';
 import { BuilderValueSchemas } from '../value/compile.js';
 import { V1ViewCompiler } from '../view.js';
 import { captureSchema, commitSchemaOwnership } from './capture.js';
 import { BuilderContext } from './context.js';
+import { assertAuthoredLifetimes } from './lifetime.js';
 /**
  * Compile the V1 TypeScript builder graph through the same semantic acceptance
  * path used for untrusted decoded schemas.
@@ -21,9 +22,11 @@ import { BuilderContext } from './context.js';
  * This is the private implementation behind defineSchema.
  */
 export function compileSchema(origin, input) {
-    const lookup = new MemoryDomainSchemaLookup(lookupEntriesForDependencies(input.dependencies ?? {}));
+    const dependencies = lookupEntriesForDependencies(input.dependencies ?? {});
+    const lookup = new MemoryDomainSchemaLookup(dependencies);
     const candidate = assembleDomainSchema(origin, input, lookup);
     const accepted = acceptDomainSchema(candidate, lookup);
+    assertAuthoredLifetimes(accepted, dependencies);
     commitSchemaOwnership(input, origin);
     return accepted;
 }
@@ -75,9 +78,11 @@ function assembleDomainSchema(origin, input, lookup) {
         views,
         core,
     };
+    const owners = analyzePropertyOwners(semanticContent, lookup);
     const qualifiedContent = {
         ...semanticContent,
-        core: canonicalizeCorePropertyKeys(semanticContent, lookup),
+        classes: canonicalizeUniquePropertyKeys(classes, origin, owners),
+        core: canonicalizeCorePropertyKeys(core, owners),
     };
     context.noteDomainEndpointReferences(qualifiedContent);
     const candidate = {
@@ -85,7 +90,7 @@ function assembleDomainSchema(origin, input, lookup) {
         dependencies: context.dependencies(),
     };
     const structured = parseDomainSchemaStructure(candidate);
-    const canonical = parseDomainSchemaStructure(canonicalizeDomainSchema(structured));
+    const canonical = parseDomainSchemaStructure(normalizeDomainSchema(structured));
     return deepFreeze(canonical);
 }
 function mapRecord(record, map) {

package/dist/v1/builder/lowering/schema/context.d.ts

@@ -6,7 +6,8 @@ import type { PolicyObjectRef } from '../../../language/index.js';
 import type { ValueSchemaRegistry } from '../../../language/value/reference/registry.js';
 import type { DomainSchema, DomainSchemaIR } from '../../../schema/model/schema.js';
 import type { Function, PolicyObjectInput } from '../../callable/authoring.js';
-import type { Class, ClassReferenceInput } from '../../class/authoring.js';
+import type { Class } from '../../class/handle.js';
+import type { ClassReferenceInput } from '../../class/input.js';
 import type { CoreEndpoint, CoreNode } from '../../core/authoring.js';
 import type { Policy } from '../../policy/authoring.js';
 import type { View } from '../../view/authoring.js';
@@ -29,8 +30,15 @@ export declare class BuilderContext {
     captureFunction(value: Function, ref: FunctionRef, pointer: string): void;
     captureView(value: View, ref: ViewRef, pointer: string): void;
     resolveClass(input: ClassReferenceInput, kind: ClassKind, pointer: string): ClassRef;
+    /** A parent of another Domain must be open to it in the dependency revision authored against. */
+    resolveParent(input: ClassReferenceInput, kind: ClassKind, pointer: string): ClassRef;
     resolveNodeClass(input: ClassReferenceInput, pointer: string): ClassRef;
     resolveEdgeClass(input: ClassReferenceInput, pointer: string): ClassRef;
+    /**
+     * The roles of a resolved Edge Class's source and target, or of an undirected Class's two
+     * endpoints in their stored order, which is the authored one.
+     */
+    edgeRoles(ref: ClassRef): readonly [source: string, target: string];
     resolvePolicy(input: Lazy<unknown>, pointer: string): PolicyRef;
     resolvePolicyObject(input: PolicyObjectInput | PolicyObjectRef, pointer: string): PolicyObjectRef;
     /** A Core fact belongs to the Domain that declares it, so a dependency endpoint never resolves. */

package/dist/v1/builder/lowering/schema/context.js

@@ -1,11 +1,14 @@
 import { compareDefinitionRefs, compareUnicode, definitionRefIndex, } from '../../../addressing/ordering.js';
 import { DEPENDENCY_ALIAS_PATTERN } from '../../../addressing/patterns.js';
 import { isMethodExecutable } from '../../../language/callable/executable.js';
+import { admitsForeignSubclass, inheritanceOf } from '../../../language/class/inheritance.js';
 import { policyObjectKey, policyObjectOrigin } from '../../../language/index.js';
 import { graphNodePathSchema } from '../../../language/value/syntax/node-path/schema.js';
+import { escapePointerToken } from '../../../language/value/syntax/pointer.js';
 import { revisionOfDomainSchema } from '../../../schema/canonical/revision.js';
 import { requireDomainClosure } from '../../../schema/resolution/closure.js';
 import { collectUsedForeignOrigins } from '../../../schema/resolution/origins.js';
+import { classConfiguration } from '../../class/authoring.js';
 import { fail } from '../../schema/diagnostic.js';
 import { resolveLazy } from '../../schema/lazy.js';
 import { OwnershipCapture } from './ownership.js';
@@ -14,6 +17,7 @@ export class BuilderContext {
     ownership = new OwnershipCapture();
     localDefinitions = new Map();
     localClassKinds = new Map();
+    #localClasses = new Map();
     policies = new Map();
     policyObjects = new Map();
     policyObjectRefs = new Set();
@@ -22,7 +26,7 @@ export class BuilderContext {
     constructor(origin, dependencies) {
         this.origin = origin;
         for (const [alias, schema] of Object.entries(dependencies)) {
-            const pointer = `/dependencies/${escapePointer(alias)}`;
+            const pointer = `/dependencies/${escapePointerToken(alias)}`;
             if (!DEPENDENCY_ALIAS_PATTERN.test(alias)) {
                 fail('BUILDER_DEPENDENCY_ALIAS', pointer, `Dependency alias ${JSON.stringify(alias)} must be an ASCII lower-camel identifier.`);
             }
@@ -47,6 +51,7 @@ export class BuilderContext {
         }
         this.localDefinitions.set(key, ref);
         this.localClassKinds.set(key, value.kind);
+        this.#localClasses.set(key, value);
         this.ownership.captureDefinition(value, ref, pointer);
         this.capturePolicyObject(value, ref);
     }
@@ -90,12 +95,42 @@ export class BuilderContext {
         }
         return { ...ref };
     }
+    /** A parent of another Domain must be open to it in the dependency revision authored against. */
+    resolveParent(input, kind, pointer) {
+        const ref = this.resolveClass(input, kind, pointer);
+        if (ref.origin === this.origin)
+            return ref;
+        const parent = this.#dependencies.get(ref.origin).schema.classes[ref.name];
+        if (!admitsForeignSubclass(parent)) {
+            fail('BUILDER_CLASS_INHERITANCE', pointer, `Class ${ref.origin}:class.${ref.name} is ${inheritanceOf(parent)}: only an open Class admits a subclass of another Domain.`);
+        }
+        return ref;
+    }
     resolveNodeClass(input, pointer) {
         return this.resolveClass(input, 'node', pointer);
     }
     resolveEdgeClass(input, pointer) {
         return this.resolveClass(input, 'edge', pointer);
     }
+    /**
+     * The roles of a resolved Edge Class's source and target, or of an undirected Class's two
+     * endpoints in their stored order, which is the authored one.
+     */
+    edgeRoles(ref) {
+        if (ref.origin === this.origin) {
+            const value = this.#localClasses.get(definitionRefIndex(ref));
+            if (value.orientation === 'directed') {
+                const input = classConfiguration(value);
+                return [input.source.as, input.target.as];
+            }
+            const input = classConfiguration(value);
+            return [input.endpoints[0].as, input.endpoints[1].as];
+        }
+        const definition = this.#dependencies.get(ref.origin).schema.classes[ref.name];
+        return definition.orientation === 'directed'
+            ? [definition.endpoints.source.role, definition.endpoints.target.role]
+            : [definition.endpoints[0].role, definition.endpoints[1].role];
+    }
     resolvePolicy(input, pointer) {
         const value = resolveLazy(input, pointer);
         if (typeof value !== 'object' || value === null) {
@@ -211,9 +246,6 @@ export class BuilderContext {
         this.policyObjectRefs.add(policyObjectKey(ref));
     }
 }
-function escapePointer(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}
 function isResolvedClass(value) {
     if (typeof value !== 'object' || value === null)
         return false;

package/dist/v1/builder/lowering/schema/lifetime.d.ts

@@ -0,0 +1,11 @@
+import type { DomainSchemaEntry } from '../../../schema/dependency/lookup.js';
+import type { DomainSchema } from '../../../schema/model/schema.js';
+/**
+ * Authoring refuses two Edge Classes that acceptance keeps, because a stored Schema must decode
+ * again with the lifetimes it derives (BUILDER-EDGE-LIFETIMES):
+ * - one with an endpoint that can hold a Node of another Domain while an endpoint requires an Edge.
+ *   It can neither restrict that Domain's deletions nor detach below the required count, so the
+ *   required endpoint must become optional;
+ * - one whose lifetimes differ from those of an Edge Class it extends, the root Edge aside.
+ */
+export declare function assertAuthoredLifetimes(schema: DomainSchema, dependencies: readonly DomainSchemaEntry[]): void;

package/dist/v1/builder/lowering/schema/lifetime.js

@@ -0,0 +1,55 @@
+import { Key } from '../../../addressing/key.js';
+import { definitionRefIndex } from '../../../addressing/ordering.js';
+import { isGraphRoot } from '../../../language/class/inheritance.js';
+import { contractEndpoints, edgeLifetimes, lifetimeScope, reachesAnotherDomain, requiredEndpoint, } from '../../../language/class/lifetime.js';
+import { BuilderError, diagnostic, escapeToken } from '../../schema/diagnostic.js';
+/**
+ * Authoring refuses two Edge Classes that acceptance keeps, because a stored Schema must decode
+ * again with the lifetimes it derives (BUILDER-EDGE-LIFETIMES):
+ * - one with an endpoint that can hold a Node of another Domain while an endpoint requires an Edge.
+ *   It can neither restrict that Domain's deletions nor detach below the required count, so the
+ *   required endpoint must become optional;
+ * - one whose lifetimes differ from those of an Edge Class it extends, the root Edge aside.
+ */
+export function assertAuthoredLifetimes(schema, dependencies) {
+    const classes = [
+        ...Object.values(schema.classes),
+        ...dependencies.flatMap((entry) => Object.values(entry.schema.classes)),
+    ];
+    const scope = lifetimeScope(classes);
+    const declarations = new Map(classes.map((declaration) => [definitionRefIndex(declaration.ref), declaration]));
+    const diagnostics = Object.entries(schema.classes).flatMap(([name, declaration]) => {
+        if (declaration.kind !== 'edge')
+            return [];
+        const pointer = `/classes/${escapeToken(name)}`;
+        const endpoints = contractEndpoints(declaration);
+        const keys = declaration.orientation === 'directed' ? ['source', 'target'] : ['0', '1'];
+        const counts = declaration.orientation === 'directed' ? ['outgoing', 'incoming'] : ['incident', 'incident'];
+        const found = [];
+        const required = requiredEndpoint(declaration);
+        const reaching = endpoints.find(({ endpoint }) => reachesAnotherDomain(schema.origin, endpoint, scope));
+        if (required !== undefined && reaching !== undefined)
+            found.push(diagnostic('BUILDER_EDGE_LIFETIME', `${pointer}/endpoints/${keys[required.index]}/${counts[required.index]}`, `${Key.of(declaration.ref)} endpoint ${reaching.endpoint.role} can hold Nodes of another ` +
+                `Domain, so it cannot restrict their deletion, and endpoint ${required.endpoint.role} ` +
+                `requires ${required.count} Edges, so it cannot detach: make ${required.endpoint.role} optional.`));
+        const lifetimes = edgeLifetimes(declaration, scope);
+        declaration.extends.forEach((ref, index) => {
+            const parent = declarations.get(definitionRefIndex(ref));
+            if (parent?.kind !== 'edge' || isGraphRoot(parent))
+                return;
+            const inherited = edgeLifetimes(parent, scope);
+            const same = (order) => order.every((at, position) => lifetimes[position] === inherited[at]);
+            if (same([0, 1]) || (declaration.orientation === 'undirected' && same([1, 0])))
+                return;
+            found.push(diagnostic('BUILDER_EDGE_LIFETIME', `${pointer}/extends/${index}`, `${Key.of(declaration.ref)} has lifetimes ${spell(endpoints, lifetimes)}, and ` +
+                `${Key.of(parent.ref)} it extends has ${spell(contractEndpoints(parent), inherited)}: ` +
+                `an Edge Class keeps the lifetimes of the Classes it extends.`));
+        });
+        return found;
+    });
+    if (diagnostics.length > 0)
+        throw new BuilderError(diagnostics);
+}
+function spell(endpoints, lifetimes) {
+    return `${endpoints[0].endpoint.role} ${lifetimes[0]} and ${endpoints[1].endpoint.role} ${lifetimes[1]}`;
+}

package/dist/v1/builder/lowering/value/path.d.ts

@@ -1,3 +1,3 @@
-import type { NodeClassReferenceInput } from '../../class/authoring.js';
+import type { NodeClassReferenceInput } from '../../class/input.js';
 import type { ZodValueSchemaOverrideContext } from './zod.js';
 export declare function lowerPathSchema(context: ZodValueSchemaOverrideContext, resolveAccepts: (inputs: readonly NodeClassReferenceInput[], pointer: string) => readonly unknown[], pointer: string): void;

package/dist/v1/builder/lowering/value/path.js

@@ -1,9 +1,10 @@
+import { escapePointerToken } from '../../../language/value/syntax/pointer.js';
 import { pathAccepts } from '../../value/path-metadata.js';
 export function lowerPathSchema(context, resolveAccepts, pointer) {
     const inputs = pathAccepts(context.zodSchema);
     if (inputs === undefined)
         return;
-    const location = context.path.reduce((current, segment) => `${current}/${escapeToken(String(segment))}`, pointer);
+    const location = context.path.reduce((current, segment) => `${current}/${escapePointerToken(String(segment))}`, pointer);
     for (const key of Object.keys(context.jsonSchema))
         delete context.jsonSchema[key];
     Object.assign(context.jsonSchema, {
@@ -15,6 +16,3 @@ export function lowerPathSchema(context, resolveAccepts, pointer) {
         },
     });
 }
-function escapeToken(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}

package/dist/v1/builder/lowering/value/zod.js

@@ -4,6 +4,7 @@ import { canonicalizeValueSchema } from '../../../language/value/profile/canonic
 import { validateValueSchema } from '../../../language/value/profile/validate.js';
 import { isIRegexp } from '../../../language/value/regexp/syntax.js';
 import { fullMatchSource } from '../../../language/value/syntax/full-match.js';
+import { escapePointerToken } from '../../../language/value/syntax/pointer.js';
 import { diagnostic } from '../../schema/diagnostic.js';
 /**
  * Converts only Zod contracts whose JSON-value acceptance is represented
@@ -289,9 +290,6 @@ function getCheckDefinition(value) {
 function isZodType(value) {
     return value instanceof ZodType;
 }
-function escapePointerToken(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}
 function isPlainRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }

package/dist/v1/builder/policy/authoring.d.ts

@@ -1,18 +1,79 @@
 import type { ClassRef } from '../../addressing/index.js';
+import type { ResolvedClass } from '../../language/class/resolved.js';
 import type { PolicyCheckExpression, PolicyPatternExpression, PolicyPatternTerm as CanonicalPolicyPatternTerm, PolicyObjectRef } from '../../language/policy/model/policy.js';
 import type { PolicyObjectInput } from '../callable/authoring.js';
-import type { EdgeClassReferenceInput, NodeClassReferenceInput } from '../class/authoring.js';
+import type { DirectedEdgeClass, EdgeClass, UndirectedEdgeClass } from '../class/handle.js';
+import type { EdgeClassReferenceInput, NodeClassReferenceInput } from '../class/input.js';
 import type { AuthoringValue } from '../schema/handle.js';
 import type { Lazy } from '../schema/lazy.js';
+import type { ResolveLazy } from '../schema/projection/identity.js';
+/**
+ * @deprecated Name the ends by their roles: `edge(classValue, { [role]: term }, { repeat })`
+ * lowers to this same pattern.
+ */
 export interface PolicyEdgeInput {
     readonly source: CanonicalPolicyPatternTerm;
     readonly class: EdgeClassReferenceInput;
     readonly target: CanonicalPolicyPatternTerm;
-    readonly repeat?: {
-        readonly min: number;
-        readonly max: number;
-    };
+    readonly repeat?: PolicyEdgeRepeat;
+}
+/** How many Edges of the Class a path between the two terms crosses, both bounds included. */
+export interface PolicyEdgeRepeat {
+    readonly min: number;
+    readonly max: number;
+}
+export interface PolicyEdgeOptions {
+    readonly repeat?: PolicyEdgeRepeat;
 }
+/** An Edge Class whose ends a Policy names by role: authored, resolved, or either lazily. */
+export type PolicyEdgeClassInput = Lazy<EdgeClass | ResolvedClass<'edge'>>;
+/**
+ * The roles of an Edge Class's two ends, as literal types: the `as` of an authored Class's ends,
+ * the `role` of a resolved Class's, read through a lazy reference.
+ */
+export type EdgeRolesOf<Value> = ResolveLazy<Value> extends infer Resolved ? Resolved extends DirectedEdgeClass<infer Config> ? Config extends {
+    readonly source: {
+        readonly as: infer Source;
+    };
+    readonly target: {
+        readonly as: infer Target;
+    };
+} ? Source | Target : never : Resolved extends UndirectedEdgeClass<infer Config> ? Config extends {
+    readonly endpoints: readonly [
+        {
+            readonly as: infer First;
+        },
+        {
+            readonly as: infer Second;
+        }
+    ];
+} ? First | Second : never : Resolved extends {
+    readonly kind: 'edge';
+    readonly definition: {
+        readonly endpoints: infer Endpoints;
+    };
+} ? Endpoints extends {
+    readonly source: {
+        readonly role: infer Source;
+    };
+    readonly target: {
+        readonly role: infer Target;
+    };
+} ? Source | Target : Endpoints extends readonly [
+    {
+        readonly role: infer First;
+    },
+    {
+        readonly role: infer Second;
+    }
+] ? First | Second : never : never : never;
+/**
+ * The two ends of an Edge, keyed by exactly the Class's two roles, both required. A Class whose
+ * roles the types do not know names no ends.
+ */
+export type PolicyEdgeEnds<Value> = [EdgeRolesOf<Value>] extends [never] ? never : string extends EdgeRolesOf<Value> ? never : {
+    readonly [Role in EdgeRolesOf<Value> & string]: CanonicalPolicyPatternTerm;
+};
 export interface PolicyNodeBinder {
     (): CanonicalPolicyPatternTerm;
     (definition: NodeClassReferenceInput): CanonicalPolicyPatternTerm;
@@ -36,6 +97,23 @@ export interface PolicyPatternContext {
     readonly object: CanonicalPolicyPatternTerm;
     readonly source: CanonicalPolicyPatternTerm;
     readonly target: CanonicalPolicyPatternTerm;
+    /**
+     * An Edge of `classValue` between two terms, each keyed by the role of its end: `{ [role]: term }`,
+     * the source's role written first by convention. It lowers to the pattern whose source is the
+     * term of the source's role and whose target is the term of the target's role. For an undirected
+     * Class, the first endpoint's role lowers to the source, and the roles only order the two terms:
+     * the pattern still matches an Edge between the two Nodes whichever end each Node holds.
+     *
+     * ```ts
+     * edge(project_owned_by, { owner: subject, project })
+     * edge(() => subtask_of, { child: a, parent: b }, { repeat: { min: 1, max: 3 } })
+     * ```
+     */
+    edge<ClassValue extends PolicyEdgeClassInput>(classValue: ClassValue, ends: PolicyEdgeEnds<ClassValue>, options?: PolicyEdgeOptions): PolicyPatternExpression;
+    /**
+     * @deprecated Name the ends by their roles: `edge(classValue, { [role]: term }, { repeat })`
+     * lowers to this same pattern.
+     */
     edge(input: PolicyEdgeInput): PolicyPatternExpression;
     exists(build: (context: PolicyExistsContext) => PolicyPatternExpression): PolicyPatternExpression;
     allOf(first: PolicyPatternExpression, ...rest: readonly PolicyPatternExpression[]): PolicyPatternExpression;
@@ -63,6 +141,8 @@ export declare const policy: PolicyBuilder;
 export declare function createPatternContext(options: {
     readonly resolveObject: (value: PolicyObjectInput, pointer: string) => PolicyObjectRef;
     readonly resolveEdgeClass: (value: EdgeClassReferenceInput, pointer: string) => ClassRef;
+    /** The roles of an Edge Class's source and target, or of an undirected Class's two endpoints. */
+    readonly edgeRoles: (ref: ClassRef) => readonly [source: string, target: string];
     readonly resolveNodeClass: (value: NodeClassReferenceInput, pointer: string) => ClassRef;
     readonly pointer: string;
 }): PolicyPatternContext;