@astrale-os/kernel-dsl 0.2.0-beta.9 → 1.0.0-beta.1

package/dist/v1/language/policy/analysis/checks.d.ts

@@ -0,0 +1,28 @@
+import type { PolicyCheckExpression } from '../model/policy.js';
+export type PolicyCheckLeaf = Extract<PolicyCheckExpression, {
+    readonly check: unknown;
+}>;
+/** How one check leaf types against the Classes its object accepts. */
+export interface CheckLeafClasses {
+    /** Every Class the leaf's object accepts. */
+    readonly accepted: readonly string[];
+    /** The accepted Classes at least one normalized branch of the leaf's Policy is typed for. */
+    readonly admitted: ReadonlySet<string>;
+}
+/**
+ * The Classes a leaf admits, from the typing of each normalized branch of its Policy for each
+ * accepted Class of its object. `undefined` when the Policy does not expand, or when one branch is
+ * typed for no accepted Class: that branch can never match this object, so it is refused rather
+ * than silently erased.
+ */
+export declare function admittedCheckClasses(typing: ReadonlyMap<string, readonly boolean[] | undefined>): ReadonlySet<string> | undefined;
+/**
+ * The accepted Classes of each object that the whole check tree can never admit.
+ *
+ * The tree is read in disjunctive normal form. A conjunction admits Class C of object O when every
+ * leaf over O in it admits C and every other object it checks keeps a Class that all of its leaves
+ * over that object admit; an object the conjunction does not check keeps every accepted Class.
+ * `sameNode` compares identities, not Classes, so it never removes a Class here. A tree over the
+ * check budget is already refused, so it is not expanded.
+ */
+export declare function neverAdmittedClasses(expression: PolicyCheckExpression, leaves: ReadonlyMap<PolicyCheckLeaf, CheckLeafClasses>): readonly (readonly [object: string, className: string])[];

package/dist/v1/language/policy/analysis/checks.js

@@ -0,0 +1,80 @@
+import { policyObjectKey } from '../model/policy.js';
+import { MAX_BRANCHES, measureChecks } from './budgets.js';
+/** Names a callable check object. Every leaf over one object sees the same Node at runtime. */
+function checkObjectName(object) {
+    if (object.kind === 'self')
+        return 'self';
+    if (object.kind === 'input')
+        return `input.${object.field}`;
+    return policyObjectKey(object.ref);
+}
+/**
+ * The Classes a leaf admits, from the typing of each normalized branch of its Policy for each
+ * accepted Class of its object. `undefined` when the Policy does not expand, or when one branch is
+ * typed for no accepted Class: that branch can never match this object, so it is refused rather
+ * than silently erased.
+ */
+export function admittedCheckClasses(typing) {
+    const rows = [...typing];
+    if (!rows.every((row) => row[1] !== undefined)) {
+        return undefined;
+    }
+    const branches = Math.max(0, ...rows.map(([, row]) => row.length));
+    for (let index = 0; index < branches; index++) {
+        if (!rows.some(([, row]) => row[index] === true))
+            return undefined;
+    }
+    return new Set(rows.filter(([, row]) => row.some(Boolean)).map(([name]) => name));
+}
+/**
+ * The accepted Classes of each object that the whole check tree can never admit.
+ *
+ * The tree is read in disjunctive normal form. A conjunction admits Class C of object O when every
+ * leaf over O in it admits C and every other object it checks keeps a Class that all of its leaves
+ * over that object admit; an object the conjunction does not check keeps every accepted Class.
+ * `sameNode` compares identities, not Classes, so it never removes a Class here. A tree over the
+ * check budget is already refused, so it is not expanded.
+ */
+export function neverAdmittedClasses(expression, leaves) {
+    if (measureChecks(expression).branches > MAX_BRANCHES)
+        return [];
+    const accepted = new Map();
+    for (const [leaf, classes] of leaves)
+        accepted.set(checkObjectName(leaf.object), classes.accepted);
+    const admitted = new Map();
+    for (const conjunction of disjunctiveForm(expression)) {
+        const constrained = new Map();
+        for (const leaf of conjunction) {
+            if (!('check' in leaf))
+                continue;
+            const classes = leaves.get(leaf);
+            if (classes === undefined)
+                continue;
+            const object = checkObjectName(leaf.object);
+            const previous = constrained.get(object);
+            constrained.set(object, previous === undefined
+                ? classes.admitted
+                : new Set([...previous].filter((name) => classes.admitted.has(name))));
+        }
+        if ([...constrained.values()].some((classes) => classes.size === 0))
+            continue;
+        for (const [object, all] of accepted) {
+            const reached = admitted.get(object) ?? new Set();
+            for (const name of constrained.get(object) ?? all)
+                reached.add(name);
+            admitted.set(object, reached);
+        }
+    }
+    return [...accepted].flatMap(([object, all]) => all
+        .filter((name) => admitted.get(object)?.has(name) !== true)
+        .map((name) => [object, name]));
+}
+function disjunctiveForm(expression) {
+    if ('check' in expression || 'sameNode' in expression)
+        return [[expression]];
+    if ('anyOf' in expression)
+        return expression.anyOf.flatMap(disjunctiveForm);
+    return expression.allOf
+        .map(disjunctiveForm)
+        .reduce((left, right) => left.flatMap((prefix) => right.map((suffix) => [...prefix, ...suffix])), [[]]);
+}

package/dist/v1/language/policy/index.d.ts

@@ -1,3 +1,4 @@
 export type * from './model/policy.js';
+export { isClassRuleChecks, policyVariableClass, policyVariableSelector, policyObjectKey, policyObjectOrigin, projectedMemberClass, } from './model/policy.js';
 export type * from './resolved.js';
 export * from './normalization/normalize.js';

package/dist/v1/language/policy/index.js

@@ -1 +1,2 @@
+export { isClassRuleChecks, policyVariableClass, policyVariableSelector, policyObjectKey, policyObjectOrigin, projectedMemberClass, } from './model/policy.js';
 export * from './normalization/normalize.js';

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

@@ -1,4 +1,4 @@
-import type { CoreRef, ClassRef, FunctionRef, PolicyRef, ViewRef, DefinitionBase } from '../../../addressing/index.js';
+import type { CoreRef, ClassRef, FunctionRef, PolicyRef, ViewRef, DefinitionBase, MethodAddress } from '../../../addressing/index.js';
 export type PolicyPatternTerm = {
     readonly kind: 'subject';
 } | {
@@ -10,14 +10,49 @@ export type PolicyPatternTerm = {
 } | {
     readonly kind: 'variable';
     readonly id: number;
+} | {
+    readonly kind: 'ref';
+    readonly ref: PolicyObjectRef;
 };
-export interface PolicyVariable {
+/** Identity equality; both terms must resolve to one valid Node. */
+export interface PolicySameNode<Term> {
+    readonly sameNode: {
+        readonly left: Term;
+        readonly right: Term;
+    };
+}
+export interface ExactPolicyVariable {
     readonly variable: {
         readonly kind: 'variable';
         readonly id: number;
     };
     readonly class: ClassRef;
 }
+export interface SelectedPolicyVariable {
+    readonly variable: {
+        readonly kind: 'variable';
+        readonly id: number;
+    };
+    readonly selector: {
+        readonly kind: 'any';
+    } | {
+        readonly kind: 'satisfies';
+        readonly class: ClassRef;
+    };
+}
+/**
+ * An existential Node binding. The class-bearing legacy form is deliberately retained as the
+ * canonical exact selector so persisted V1 DomainSchema documents keep their original meaning.
+ */
+export type PolicyVariable = ExactPolicyVariable | SelectedPolicyVariable;
+export type PolicyVariableSelector = {
+    readonly kind: 'exact';
+    readonly class: ClassRef;
+} | SelectedPolicyVariable['selector'];
+/** Resolve the semantic selector while preserving the legacy exact wire representation. */
+export declare function policyVariableSelector(variable: PolicyVariable): PolicyVariableSelector;
+/** Return the selector's referenced Class, when it has one. */
+export declare function policyVariableClass(variable: PolicyVariable): ClassRef | undefined;
 export interface PolicyRepeat {
     readonly min: number;
     readonly max: number;
@@ -28,7 +63,7 @@ export interface PolicyEdgePattern {
     readonly target: PolicyPatternTerm;
     readonly repeat?: PolicyRepeat;
 }
-export type PolicyPatternExpression = PolicyEdgePattern | {
+export type PolicyPatternExpression = PolicyEdgePattern | PolicySameNode<PolicyPatternTerm> | {
     readonly exists: {
         readonly nodes: readonly PolicyVariable[];
         readonly where: PolicyPatternExpression;
@@ -50,7 +85,33 @@ export interface PolicyDefinition extends DefinitionBase<PolicyRef> {
     readonly description?: string;
 }
 /** Local Domain members whose installed projection resolves through one exact member Path. */
-export type PolicyObjectRef = ClassRef | FunctionRef | PolicyRef | ViewRef | CoreRef;
+export type PolicyObjectRef = ClassRef | FunctionRef | PolicyRef | ViewRef | CoreRef | MethodAddress;
+/** Exact projected identity, including Class-owned Method declarations. */
+export declare function policyObjectKey(ref: PolicyObjectRef): string;
+export declare function policyObjectOrigin(ref: PolicyObjectRef): string;
+export declare function projectedMemberClass(ref: Exclude<PolicyObjectRef, CoreRef>): ClassRef;
+/**
+ * One Class observation slot: a named Policy, or `false`, the rule no caller satisfies. Its other
+ * value has no spelling there: an absent observation Policy already means `true`.
+ */
+export type ClassPolicy = PolicyRef | false;
+/** What a Node Class rule may check: the observed Node, or one exact projected member. */
+export type ClassRuleObject = Extract<PolicyCheckObject, {
+    readonly kind: 'self' | 'ref';
+}>;
+/**
+ * Policy checks deciding one Node Class observation. `self` is the observed Node; a `ref` object
+ * is the same Node for every candidate. A lone check of `self` is spelled as its Policy reference.
+ */
+export type ClassRuleChecks = PolicyCheckExpression<PolicyRef, ClassRuleObject>;
+/** One Node Class observation slot: a Class Policy, or Policy checks over the observed Node. */
+export type NodeClassPolicy = ClassPolicy | ClassRuleChecks;
+export declare function isClassRuleChecks(value: ClassPolicy | ClassRuleChecks | undefined): value is ClassRuleChecks;
+/**
+ * Whether every way Policy checks can hold passes through a check, so that the caller decides each
+ * admission. `sameNode` compares two objects and names no caller.
+ */
+export declare function checksNameTheCaller(value: PolicyCheckExpression<unknown, unknown>): boolean;
 export type PolicyCheckObject = {
     readonly kind: 'self';
 } | {
@@ -64,7 +125,7 @@ export type PolicyCheckObject = {
 export type PolicyCheckExpression<Policy = PolicyRef, Object = PolicyCheckObject> = {
     readonly check: Policy;
     readonly object: Object;
-} | {
+} | PolicySameNode<Object> | {
     readonly allOf: readonly [
         PolicyCheckExpression<Policy, Object>,
         ...PolicyCheckExpression<Policy, Object>[]
@@ -75,3 +136,8 @@ export type PolicyCheckExpression<Policy = PolicyRef, Object = PolicyCheckObject
         ...PolicyCheckExpression<Policy, Object>[]
     ];
 };
+/**
+ * One authorized callable's caller rule: Policy checks, or `true`, the rule every caller satisfies.
+ * Its other value has no spelling there: an absent callable Policy already means `false`.
+ */
+export type CallablePolicy = PolicyCheckExpression | true;

package/dist/v1/language/policy/model/policy.js

@@ -1 +1,52 @@
-export {};
+/** Resolve the semantic selector while preserving the legacy exact wire representation. */
+export function policyVariableSelector(variable) {
+    return 'class' in variable ? { kind: 'exact', class: variable.class } : variable.selector;
+}
+/** Return the selector's referenced Class, when it has one. */
+export function policyVariableClass(variable) {
+    const selector = policyVariableSelector(variable);
+    return selector.kind === 'any' ? undefined : selector.class;
+}
+/** Exact projected identity, including Class-owned Method declarations. */
+export function policyObjectKey(ref) {
+    return ref.kind === 'method'
+        ? `${ref.owner.origin}:class.${ref.owner.name}.method.${ref.name}`
+        : `${ref.origin}:${ref.kind}.${ref.name}`;
+}
+export function policyObjectOrigin(ref) {
+    return ref.kind === 'method' ? ref.owner.origin : ref.origin;
+}
+/**
+ * The Kernel declaration Class each projected member materializes as. A Core Node is absent: it
+ * keeps the concrete Class its own Domain authored, which only that Domain's schema can resolve.
+ */
+const PROJECTED_MEMBER_CLASSES = Object.freeze({
+    class: kernelClassRef('Class'),
+    function: kernelClassRef('Function'),
+    method: kernelClassRef('Function'),
+    policy: kernelClassRef('Policy'),
+    view: kernelClassRef('View'),
+});
+export function projectedMemberClass(ref) {
+    return PROJECTED_MEMBER_CLASSES[ref.kind];
+}
+function kernelClassRef(name) {
+    return Object.freeze({ origin: 'kernel.astrale.ai', kind: 'class', name });
+}
+export function isClassRuleChecks(value) {
+    return (typeof value === 'object' &&
+        ('check' in value || 'sameNode' in value || 'allOf' in value || 'anyOf' in value));
+}
+/**
+ * Whether every way Policy checks can hold passes through a check, so that the caller decides each
+ * admission. `sameNode` compares two objects and names no caller.
+ */
+export function checksNameTheCaller(value) {
+    if ('check' in value)
+        return true;
+    if ('sameNode' in value)
+        return false;
+    if ('allOf' in value)
+        return value.allOf.some(checksNameTheCaller);
+    return value.anyOf.every(checksNameTheCaller);
+}

package/dist/v1/language/policy/normalization/normalize.d.ts

@@ -1,4 +1,15 @@
-import type { PolicyCheckExpression, PolicyExpression, PolicyPatternExpression } from '../model/policy.js';
+import type { NodeClassPolicy, PolicyCheckExpression, PolicyExpression, PolicyPatternExpression } from '../model/policy.js';
 export declare function normalizePolicyExpression(value: PolicyExpression): PolicyExpression;
+/**
+ * The fixed point of the single pass: a Pattern the single pass reproduces is returned unchanged,
+ * so the canonical form of every Pattern that was already stable keeps its bytes.
+ */
 export declare function normalizePolicyPattern(value: PolicyPatternExpression): PolicyPatternExpression;
+/**
+ * The one spelling of a Node Class observation rule: normalized Policy checks without a composition
+ * of one operand, or the Policy that a lone check of `self` names, which is how a Class has always
+ * declared one. Callable checks keep their compositions of one operand: their revisions predate
+ * this rule.
+ */
+export declare function normalizeClassRule(value: NodeClassPolicy): NodeClassPolicy;
 export declare function normalizePolicyChecks(value: PolicyCheckExpression): PolicyCheckExpression;

package/dist/v1/language/policy/normalization/normalize.js

@@ -1,6 +1,6 @@
 import { json } from '@astrale-os/kernel-dsl/value';
 import { definitionRefIndex, compareDefinitionRefs } from '../../../addressing/ordering.js';
-const textEncoder = new TextEncoder();
+import { isClassRuleChecks, policyObjectKey, policyVariableSelector } from '../model/policy.js';
 export function normalizePolicyExpression(value) {
     if ('match' in value) {
         return { match: normalizePolicyPattern(value.match) };
@@ -10,13 +10,70 @@ export function normalizePolicyExpression(value) {
     }
     return { anyOf: uniqueRefs(value.anyOf) };
 }
+/**
+ * Passes after the first, while one still changes the Pattern. A pass numbers variables by the
+ * operands as written, then merges duplicate operands and flattens nested ones, so its result can
+ * number differently when normalized again; the next pass numbers that result by itself. One
+ * further pass reached the fixed point on every Pattern tested, the other is margin, and a
+ * Pattern still changing keeps its last pass rather than failing.
+ */
+const SETTLING_PASSES = 2;
+/**
+ * The fixed point of the single pass: a Pattern the single pass reproduces is returned unchanged,
+ * so the canonical form of every Pattern that was already stable keeps its bytes.
+ */
 export function normalizePolicyPattern(value) {
+    let current = normalizePatternOnce(value);
+    let encoding = json.serialize(current);
+    for (let pass = 0; pass < SETTLING_PASSES; pass++) {
+        const next = normalizePatternOnce(current);
+        const nextEncoding = json.serialize(next);
+        if (nextEncoding === encoding)
+            return current;
+        current = next;
+        encoding = nextEncoding;
+    }
+    return current;
+}
+function normalizePatternOnce(value) {
     const rewritten = rewriteVariables(value, canonicalVariableIds(value));
     return normalizePatternNode(rewritten);
 }
+/**
+ * The one spelling of a Node Class observation rule: normalized Policy checks without a composition
+ * of one operand, or the Policy that a lone check of `self` names, which is how a Class has always
+ * declared one. Callable checks keep their compositions of one operand: their revisions predate
+ * this rule.
+ */
+export function normalizeClassRule(value) {
+    if (!isClassRuleChecks(value))
+        return value;
+    const checks = unwrapSingleOperands(normalizePolicyChecks(value));
+    return 'check' in checks && checks.object.kind === 'self' ? checks.check : checks;
+}
+/** Replace each composition of one operand by that operand, merging what it then nests. */
+function unwrapSingleOperands(value) {
+    if ('check' in value || 'sameNode' in value)
+        return value;
+    const all = 'allOf' in value;
+    const children = uniqueJson((all ? value.allOf : value.anyOf).flatMap((child) => {
+        const unwrapped = unwrapSingleOperands(child);
+        if (all && 'allOf' in unwrapped)
+            return unwrapped.allOf;
+        if (!all && 'anyOf' in unwrapped)
+            return unwrapped.anyOf;
+        return [unwrapped];
+    }));
+    if (children.length === 1)
+        return children[0];
+    const operands = policyCheckComposition(children);
+    return all ? { allOf: operands } : { anyOf: operands };
+}
 export function normalizePolicyChecks(value) {
     if ('check' in value)
         return value;
+    if ('sameNode' in value)
+        return { sameNode: normalizeEquality(value.sameNode) };
     if ('allOf' in value) {
         const children = value.allOf.flatMap((child) => {
             const normalized = normalizePolicyChecks(child);
@@ -36,6 +93,8 @@ function policyCheckComposition(values) {
     return values;
 }
 function normalizePatternNode(value) {
+    if ('sameNode' in value)
+        return { sameNode: normalizeEquality(value.sameNode) };
     if (isEdge(value)) {
         const repeat = value.repeat;
         if (repeat?.min === 1 && repeat.max === 1) {
@@ -67,24 +126,34 @@ function normalizePatternNode(value) {
 }
 function canonicalVariableIds(value) {
     const declarations = new Map();
-    collectDeclarations(value, declarations);
-    const colors = new Map(declarations);
+    const depths = new Map();
+    collectDeclarations(value, declarations, depths);
+    const uses = new Map([...declarations.keys()].map((id) => [id, []]));
+    collectUses(value, uses);
+    let colors = declarations;
+    // Color refinement. Each round names a variable by its declaration and the sorted colors of its
+    // uses, then replaces every name by its fixed-width rank among the round's names. Ranks keep the
+    // names' byte order, so a round decides what it would decide over uncompressed names, while a
+    // name stays linear in its variable's degree instead of embedding every neighbour's name. A
+    // round that reproduces its input is a fixed point of the next ones.
     for (let iteration = 0; iteration < declarations.size + 1; iteration++) {
-        const next = new Map();
-        for (const id of declarations.keys()) {
-            const uses = [];
-            collectUses(value, id, colors, uses);
-            uses.sort(compareUtf8Bytes);
-            next.set(id, `${declarations.get(id) ?? ''}|${uses.join('|')}`);
-        }
+        const next = rank(new Map([...uses].map(([id, list]) => {
+            const named = list.map(([prefix, term]) => `${prefix}${termColor(term, colors)}`);
+            return [id, `${declarations.get(id) ?? ''}|${named.sort(compareUtf8Bytes).join('|')}`];
+        })));
         if ([...next].every(([id, color]) => colors.get(id) === color))
             break;
-        colors.clear();
-        for (const [id, color] of next)
-            colors.set(id, color);
+        colors = next;
     }
+    // Colors ignore where a variable is declared, so two variables can tie on color although
+    // different `exists` declare them, and which of them is numbered first decides which `exists`
+    // declares the smaller id. Their declaration depth tells them apart where it differs: operands of
+    // equal signature are ordered by their signature over depth-scoped colors before authored order,
+    // and the final order compares depth before the authored id (decision
+    // `policy-pattern-canonical-ties`). Both keys only order what color and first use leave tied.
+    const scoped = new Map([...colors].map(([id, color]) => [id, `${color}@${depths.get(id) ?? 0}`]));
     const firstUse = new Map();
-    collectFirstUseKeys(value, colors, firstUse);
+    collectFirstUseKeys(value, colors, scoped, firstUse);
     const ordered = [...declarations.keys()].sort((left, right) => {
         const byColor = compareUtf8Bytes(colors.get(left) ?? '', colors.get(right) ?? '');
         if (byColor !== 0)
@@ -92,49 +161,80 @@ function canonicalVariableIds(value) {
         const byUse = compareUtf8Bytes(firstUse.get(left) ?? '', firstUse.get(right) ?? '');
         if (byUse !== 0)
             return byUse;
-        // A remaining tie is an automorphic binder class: assigning either first
-        // yields the same recursively sorted canonical Pattern.
+        const byDepth = (depths.get(left) ?? 0) - (depths.get(right) ?? 0);
+        if (byDepth !== 0)
+            return byDepth;
+        // A remaining tie keeps the authored order of the ids: such variables were interchangeable in
+        // every admissible Pattern checked (`__tests__/canonical.test.ts`).
         return left - right;
     });
     return new Map(ordered.map((id, index) => [id, index]));
 }
-function collectDeclarations(value, result) {
+/** Each declared variable's selector signature and the number of `exists` around its declaration. */
+function collectDeclarations(value, result, depths, depth = 0) {
     if ('exists' in value) {
         for (const node of value.exists.nodes) {
-            result.set(node.variable.id, definitionRefIndex(node.class));
+            result.set(node.variable.id, selectorSignature(node));
+            depths.set(node.variable.id, depth + 1);
         }
-        collectDeclarations(value.exists.where, result);
+        collectDeclarations(value.exists.where, result, depths, depth + 1);
         return;
     }
     if ('allOf' in value)
         for (const child of value.allOf)
-            collectDeclarations(child, result);
+            collectDeclarations(child, result, depths, depth);
     if ('anyOf' in value)
         for (const child of value.anyOf)
-            collectDeclarations(child, result);
+            collectDeclarations(child, result, depths, depth);
 }
-function collectUses(value, target, colors, result) {
+function collectUses(value, result) {
+    if ('sameNode' in value) {
+        const { left, right } = value.sameNode;
+        if (left.kind === 'variable')
+            result.get(left.id)?.push(['same:', right]);
+        if (right.kind === 'variable')
+            result.get(right.id)?.push(['same:', left]);
+        return;
+    }
     if (isEdge(value)) {
-        if (value.source.kind === 'variable' && value.source.id === target) {
-            result.push(`s:${definitionRefIndex(value.class)}:${termColor(value.target, colors)}`);
-        }
-        if (value.target.kind === 'variable' && value.target.id === target) {
-            result.push(`t:${definitionRefIndex(value.class)}:${termColor(value.source, colors)}`);
-        }
+        const edge = definitionRefIndex(value.class);
+        if (value.source.kind === 'variable')
+            result.get(value.source.id)?.push([`s:${edge}:`, value.target]);
+        if (value.target.kind === 'variable')
+            result.get(value.target.id)?.push([`t:${edge}:`, value.source]);
         return;
     }
     if ('exists' in value)
-        return collectUses(value.exists.where, target, colors, result);
+        return collectUses(value.exists.where, result);
     const children = 'allOf' in value ? value.allOf : value.anyOf;
     for (const child of children)
-        collectUses(child, target, colors, result);
+        collectUses(child, result);
+}
+function rank(names) {
+    const distinct = [...new Set(names.values())].sort(compareUtf8Bytes);
+    const width = String(distinct.length).length;
+    const ranks = new Map(distinct.map((name, index) => [name, String(index).padStart(width, '0')]));
+    return new Map([...names].map(([id, name]) => [id, ranks.get(name) ?? '']));
 }
 function termColor(term, colors) {
     if (term.kind === 'variable')
         return `variable:${colors.get(term.id) ?? '?'}`;
+    if (term.kind === 'ref')
+        return `ref:${term.ref.kind === 'method' ? policyObjectKey(term.ref) : definitionRefIndex(term.ref)}`;
     return term.kind;
 }
-function collectFirstUseKeys(value, colors, result, prefix = '$') {
+function collectFirstUseKeys(value, colors, scoped, result, prefix = '$') {
+    if ('sameNode' in value) {
+        for (const term of [value.sameNode.left, value.sameNode.right]) {
+            if (term.kind !== 'variable')
+                continue;
+            const key = `${prefix}:same`;
+            const current = result.get(term.id);
+            if (current === undefined || key < current)
+                result.set(term.id, key);
+        }
+        return;
+    }
     if (isEdge(value)) {
         for (const [position, term] of [
             ['source', value.source],
@@ -150,15 +250,19 @@ function collectFirstUseKeys(value, colors, result, prefix = '$') {
         return;
     }
     if ('exists' in value) {
-        collectFirstUseKeys(value.exists.where, colors, result, `${prefix}:exists`);
+        collectFirstUseKeys(value.exists.where, colors, scoped, result, `${prefix}:exists`);
         return;
     }
     const key = 'allOf' in value ? 'allOf' : 'anyOf';
     const operands = 'allOf' in value ? value.allOf : value.anyOf;
-    const children = [...operands].sort((left, right) => compareUtf8Bytes(patternSignature(left, colors), patternSignature(right, colors)));
-    children.forEach((child, index) => collectFirstUseKeys(child, colors, result, `${prefix}:${key}:${index}`));
+    const children = operands
+        .map((child) => [patternSignature(child, colors), patternSignature(child, scoped), child])
+        .sort(([left, leftScoped], [right, rightScoped]) => compareUtf8Bytes(left, right) || compareUtf8Bytes(leftScoped, rightScoped));
+    children.forEach(([, , child], index) => collectFirstUseKeys(child, colors, scoped, result, `${prefix}:${key}:${index}`));
 }
 function patternSignature(value, colors) {
+    if ('sameNode' in value)
+        return `same:${[termColor(value.sameNode.left, colors), termColor(value.sameNode.right, colors)].sort(compareUtf8Bytes).join(':')}`;
     if (isEdge(value)) {
         return `edge:${definitionRefIndex(value.class)}:${termColor(value.source, colors)}:${termColor(value.target, colors)}:${value.repeat?.min ?? 1}:${value.repeat?.max ?? 1}`;
     }
@@ -176,6 +280,13 @@ function patternSignature(value, colors) {
         .join('|')}`;
 }
 function rewriteVariables(value, ids) {
+    if ('sameNode' in value)
+        return {
+            sameNode: {
+                left: rewriteTerm(value.sameNode.left, ids),
+                right: rewriteTerm(value.sameNode.right, ids),
+            },
+        };
     if (isEdge(value)) {
         return {
             ...value,
@@ -186,10 +297,15 @@ function rewriteVariables(value, ids) {
     if ('exists' in value) {
         return {
             exists: {
-                nodes: value.exists.nodes.map((node) => ({
-                    variable: { kind: 'variable', id: ids.get(node.variable.id) ?? node.variable.id },
-                    class: node.class,
-                })),
+                nodes: value.exists.nodes.map((node) => {
+                    const variable = {
+                        kind: 'variable',
+                        id: ids.get(node.variable.id) ?? node.variable.id,
+                    };
+                    return 'class' in node
+                        ? { variable, class: node.class }
+                        : { variable, selector: node.selector };
+                }),
                 where: rewriteVariables(value.exists.where, ids),
             },
         };
@@ -198,6 +314,10 @@ function rewriteVariables(value, ids) {
         return { allOf: value.allOf.map((child) => rewriteVariables(child, ids)) };
     return { anyOf: value.anyOf.map((child) => rewriteVariables(child, ids)) };
 }
+function selectorSignature(node) {
+    const selector = policyVariableSelector(node);
+    return selector.kind === 'any' ? 'any' : `${selector.kind}:${definitionRefIndex(selector.class)}`;
+}
 function rewriteTerm(value, ids) {
     return value.kind === 'variable' ? { kind: 'variable', id: ids.get(value.id) ?? value.id } : value;
 }
@@ -211,16 +331,30 @@ function uniqueJson(values) {
         .sort(([left], [right]) => compareUtf8Bytes(left, right))
         .map(([, value]) => value);
 }
+/**
+ * UTF-8 byte order without encoding: it is code-point order, which UTF-16 code units already follow
+ * except that surrogates (U+10000 and above) sort after U+E000–U+FFFF.
+ */
 function compareUtf8Bytes(left, right) {
-    const a = textEncoder.encode(left);
-    const b = textEncoder.encode(right);
-    const length = Math.min(a.length, b.length);
+    const length = Math.min(left.length, right.length);
     for (let index = 0; index < length; index++) {
-        if (a[index] !== b[index])
-            return (a[index] ?? 0) - (b[index] ?? 0);
+        const a = left.charCodeAt(index);
+        const b = right.charCodeAt(index);
+        if (a !== b)
+            return codePointOrder(a) - codePointOrder(b);
     }
-    return a.length - b.length;
+    return left.length - right.length;
+}
+function codePointOrder(unit) {
+    if (unit >= 0xd800 && unit <= 0xdfff)
+        return unit + 0x2000;
+    return unit >= 0xe000 ? unit - 0x800 : unit;
 }
 function isEdge(value) {
     return 'source' in value;
 }
+function normalizeEquality(value) {
+    return compareUtf8Bytes(json.serialize(value.left), json.serialize(value.right)) <= 0
+        ? value
+        : { left: value.right, right: value.left };
+}

package/dist/v1/language/state/index.d.ts

@@ -0,0 +1,3 @@
+export { stateMachine } from './machine.js';
+export type { EventOf, StateMachine, StateOf } from './machine.js';
+export type { StateTopology } from './topology.js';

package/dist/v1/language/state/index.js

@@ -0,0 +1 @@
+export { stateMachine } from './machine.js';