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

package/dist/v1/schema/validation/domain.structure.js

@@ -1,61 +1,156 @@
-import { array, boolean, custom, discriminatedUnion, enum as enumeration, lazy, literal, null as nullSchema, number, record, strictObject, string, tuple, union, } from 'zod';
+import { array, boolean, custom, discriminatedUnion, enum as enumeration, lazy, literal, null as nullSchema, number, record, registry, strictObject, string, tuple, union, } from 'zod';
 import { PropertyKey as SemanticPropertyKey } from '../../addressing/index.js';
-import { CORE_SLUG_PATTERN, DEPENDENCY_ALIAS_PATTERN, DOMAIN_ORIGIN_PATTERN, DOMAIN_REVISION_PATTERN, MEMBER_NAME_PATTERN, } from '../../addressing/patterns.js';
+import { CORE_SLUG_PATTERN, DEPENDENCY_ALIAS_PATTERN, DOMAIN_ORIGIN_PATTERN, DOMAIN_REVISION_PATTERN, MEMBER_NAME_PATTERN, PROPERTY_KEY_PATTERN, } from '../../addressing/patterns.js';
 import { MEDIA_TYPE_PATTERN } from '../../language/class/model/data.js';
 import * as metadata from '../../language/definition/metadata.js';
-import { SchemaError, diagnostic } from '../diagnostic.js';
+import { limits } from '../../language/limits.js';
+import { BLOB_VALUE_KIND, isBlobValueSchema } from '../../language/value/model/blob.js';
+import { escapePointerToken } from '../../language/value/syntax/pointer.js';
+import { SchemaError, diagnostic, } from '../diagnostic.js';
 import { DOMAIN_FORMAT, DOMAIN_VERSION } from '../model/format.js';
-const originSchema = string().min(3).max(253).regex(DOMAIN_ORIGIN_PATTERN);
-const memberNameSchema = string().regex(MEMBER_NAME_PATTERN);
+export const documentJsonSchema = registry();
+/**
+ * The checks of the structure JSON Schema cannot state. The published document names each with the
+ * positions it constrains, so that a validator of the document knows what it leaves to the Kernel.
+ */
+export const structureRules = {
+    'unique-tuple-set': {
+        code: 'STRUCTURE_DUPLICATE_ITEM',
+        statement: 'A unique tuple is a set of fields: two tuples naming the same fields in another order are one tuple, repeated.',
+    },
+    'length-in-utf16-code-units': {
+        code: 'STRUCTURE_MAXIMUM',
+        statement: 'A maxLength counts UTF-16 code units, where JSON Schema counts code points: a string within the bound in code points and beyond it in code units is refused.',
+    },
+};
+// The pattern refuses `__proto__`, which zod skips before any key check (`lostProtoKeys`).
+const RESERVED_DEPENDENCY_ALIASES = ['prototype', 'constructor'];
+const originSchema = string()
+    .min(3)
+    .max(253)
+    .regex(DOMAIN_ORIGIN_PATTERN)
+    .register(documentJsonSchema, { id: 'origin' });
+const memberNameSchema = string()
+    .regex(MEMBER_NAME_PATTERN)
+    .register(documentJsonSchema, { id: 'name' });
 const dependencyAliasSchema = string()
     .regex(DEPENDENCY_ALIAS_PATTERN)
-    .refine((value) => value !== '__proto__' && value !== 'prototype' && value !== 'constructor', 'Expected a non-reserved dependency alias.');
-const propertyKeySchema = string().refine(SemanticPropertyKey.is, 'Expected a canonical PropertyKey.');
-const coreSlugSchema = string().min(1).max(100).regex(CORE_SLUG_PATTERN);
-const revisionSchema = string().regex(DOMAIN_REVISION_PATTERN);
+    .refine((value) => !RESERVED_DEPENDENCY_ALIASES.includes(value), {
+    message: 'Expected a non-reserved dependency alias.',
+    params: { structureCode: 'STRUCTURE_DEPENDENCY_ALIAS' },
+})
+    .register(documentJsonSchema, {
+    id: 'dependency-alias',
+    not: { enum: [...RESERVED_DEPENDENCY_ALIASES] },
+});
+const propertyKeySchema = string()
+    .refine(SemanticPropertyKey.is, {
+    message: 'Expected a canonical PropertyKey.',
+    params: { structureCode: 'STRUCTURE_PROPERTY_KEY' },
+})
+    .register(documentJsonSchema, { id: 'property-key', pattern: PROPERTY_KEY_PATTERN.source });
+const coreSlugSchema = string()
+    .min(1)
+    .max(100)
+    .regex(CORE_SLUG_PATTERN)
+    .register(documentJsonSchema, { id: 'core-slug' });
+const revisionSchema = string()
+    .regex(DOMAIN_REVISION_PATTERN)
+    .register(documentJsonSchema, { id: 'revision' });
 const descriptionSchema = string()
     .min(metadata.description.minLength)
-    .max(metadata.description.maxLength);
-const iconSchema = string().min(metadata.icon.minLength).max(metadata.icon.maxLength);
+    .max(metadata.description.maxLength)
+    .register(documentJsonSchema, { id: 'description' });
+const iconSchema = string()
+    .min(metadata.icon.minLength)
+    .max(metadata.icon.maxLength)
+    .register(documentJsonSchema, { id: 'icon' });
 const domainNameSchema = string()
     .min(metadata.name.minLength)
     .max(metadata.name.maxLength)
-    .refine(metadata.isDomainNameText, 'Expected one trimmed line of text.');
+    .refine(metadata.isDomainNameText, {
+    message: 'Expected one trimmed line of text.',
+    params: { structureCode: 'STRUCTURE_DOMAIN_NAME' },
+})
+    .register(documentJsonSchema, {
+    id: 'domain-name',
+    description: 'The display name of the Domain: one trimmed line of text.',
+    pattern: metadata.DOMAIN_NAME_TEXT_PATTERN.source,
+});
+// Zod skips a `__proto__` member, which the structure therefore refuses (`lostProtoKeys`). The JSON
+// Schema refuses it by the fields of a closed object and the pattern of a record's names; a record
+// of any string states it here, by its property names.
+const PROTO_KEY = '__proto__';
+const anyKeyRecord = { propertyNames: { not: { const: PROTO_KEY } } };
 const jsonValueSchema = lazy(() => union([
     nullSchema(),
     boolean(),
     number(),
     string(),
     array(jsonValueSchema),
-    record(string(), jsonValueSchema),
-]));
-const jsonObjectSchema = record(string(), jsonValueSchema);
-const jsonSchemaSchema = union([boolean(), jsonObjectSchema]);
+    record(string(), jsonValueSchema).register(documentJsonSchema, anyKeyRecord),
+])).register(documentJsonSchema, { id: 'json-value' });
+const jsonObjectSchema = record(string(), jsonValueSchema).register(documentJsonSchema, anyKeyRecord);
+const jsonSchemaSchema = union([boolean(), jsonObjectSchema]).register(documentJsonSchema, {
+    id: 'value-schema',
+    description: 'A value schema of the dialect https://schemas.astrale.ai/dsl/v1/value-schema. The structure admits any boolean or object; the language admits its keywords.',
+});
 const dataDeclarationSchema = strictObject({
-    mediaType: string().regex(MEDIA_TYPE_PATTERN),
+    mediaType: string().regex(MEDIA_TYPE_PATTERN).register(documentJsonSchema, { id: 'media-type' }),
 });
 const stateNameSchema = string().min(1);
-const stateTransitionsSchema = custom(isStateTransitions);
+// A custom check reads the relation in place: a record would copy it and drop a `__proto__` state.
+const stateTransitionsSchema = custom(isStateTransitions, {
+    message: 'Expected each non-empty state to map non-empty events to non-empty states.',
+    params: { structureCode: 'STRUCTURE_STATE_TRANSITIONS' },
+}).register(documentJsonSchema, {
+    type: 'object',
+    propertyNames: { type: 'string', minLength: 1 },
+    additionalProperties: {
+        type: 'object',
+        propertyNames: { type: 'string', minLength: 1 },
+        additionalProperties: { type: 'string', minLength: 1 },
+    },
+});
 const stateTopologySchema = strictObject({
     initial: stateNameSchema,
     transitions: stateTransitionsSchema,
-});
-const propertyDefinitionSchema = strictObject({
+}).register(documentJsonSchema, { id: 'state-topology' });
+const propertyShape = {
     schema: jsonSchemaSchema,
     required: boolean(),
     auto: strictObject({
-        on: uniqueArray(enumeration(['create', 'update'])).min(1),
+        on: nonEmpty(uniqueArray(enumeration(['create', 'update']))),
         set: literal('instant'),
-    }).optional(),
+    })
+        .register(documentJsonSchema, { id: 'auto' })
+        .optional(),
     immutable: enumeration(['create', 'once']).optional(),
     description: descriptionSchema.optional(),
-    state: stateTopologySchema.optional(),
+};
+const nodePropertyRecordSchema = record(memberNameSchema, strictObject({ ...propertyShape, state: stateTopologySchema.optional() }).register(documentJsonSchema, { id: 'node-property-definition' })).register(documentJsonSchema, { id: 'node-property-record' });
+// An Edge has no State Property, and only a Node holds Blob contents.
+const BLOB_KIND_KEYWORD = 'x-astrale-value-kind';
+const edgePropertySchema = jsonSchemaSchema
+    .refine((value) => !isBlobValueSchema(value), {
+    message: 'Blob values are held only by Node Properties.',
+    path: [BLOB_KIND_KEYWORD],
+    params: { structureCode: 'STRUCTURE_EDGE_BLOB' },
+})
+    .register(documentJsonSchema, {
+    not: {
+        type: 'object',
+        required: [BLOB_KIND_KEYWORD],
+        properties: { [BLOB_KIND_KEYWORD]: { const: BLOB_VALUE_KIND } },
+    },
 });
-const propertyRecordSchema = record(memberNameSchema, propertyDefinitionSchema);
+const edgePropertyRecordSchema = record(memberNameSchema, strictObject({ ...propertyShape, schema: edgePropertySchema }).register(documentJsonSchema, {
+    id: 'edge-property-definition',
+})).register(documentJsonSchema, { id: 'edge-property-record' });
 const domainDependencySchema = strictObject({
     origin: originSchema,
     revision: revisionSchema,
-});
+}).register(documentJsonSchema, { id: 'dependency' });
 const classRefSchema = absoluteRefSchema('class');
 const functionRefSchema = absoluteRefSchema('function');
 const policyRefSchema = absoluteRefSchema('policy');
@@ -64,40 +159,67 @@ const coreRefSchema = strictObject({
     origin: originSchema,
     kind: literal('core'),
     name: coreSlugSchema,
+}).register(documentJsonSchema, { id: 'core-ref' });
+const domainRefSchema = strictObject({ kind: literal('domain') }).register(documentJsonSchema, {
+    id: 'domain-endpoint',
 });
-const domainRefSchema = strictObject({ kind: literal('domain') });
 /** Every Definition whose installed projection resolves through one exact member Path. */
 const projectedMemberRefOptions = [
-    strictObject({ kind: literal('method'), owner: classRefSchema, name: memberNameSchema }),
+    strictObject({
+        kind: literal('method'),
+        owner: classRefSchema,
+        name: memberNameSchema,
+    }).register(documentJsonSchema, { id: 'method-address' }),
     classRefSchema,
     functionRefSchema,
     policyRefSchema,
     viewRefSchema,
     coreRefSchema,
 ];
-const policyObjectRefSchema = discriminatedUnion('kind', projectedMemberRefOptions);
+const policyObjectRefSchema = discriminatedUnion('kind', projectedMemberRefOptions).register(documentJsonSchema, { id: 'projected-member-ref' });
 const coreEndpointRefSchema = discriminatedUnion('kind', [
     ...projectedMemberRefOptions,
     domainRefSchema,
-]);
+]).register(documentJsonSchema, { id: 'core-endpoint' });
 const edgeEndpointBaseShape = {
     role: memberNameSchema,
-    accepts: uniqueArray(classRefSchema).min(1),
+    accepts: nonEmpty(uniqueArray(classRefSchema)),
+    onDelete: enumeration(['restrict', 'detach'])
+        .register(documentJsonSchema, { id: 'edge-lifetime' })
+        .optional(),
 };
-const edgeCountSchema = enumeration(['0..*', '1..*', '0..1', '1']);
-const directedEdgeEndpointsSchema = strictObject({
-    source: strictObject({ ...edgeEndpointBaseShape, outgoing: edgeCountSchema }),
-    target: strictObject({ ...edgeEndpointBaseShape, incoming: edgeCountSchema }),
+const edgeCountSchema = enumeration(['0..*', '1..*', '0..1', '1']).register(documentJsonSchema, {
+    id: 'edge-count',
 });
+const directedEdgeEndpointsSchema = strictObject({
+    source: strictObject({ ...edgeEndpointBaseShape, outgoing: edgeCountSchema }).register(documentJsonSchema, { id: 'directed-source-endpoint' }),
+    target: strictObject({ ...edgeEndpointBaseShape, incoming: edgeCountSchema }).register(documentJsonSchema, { id: 'directed-target-endpoint' }),
+}).register(documentJsonSchema, { id: 'directed-endpoints' });
 const incidentEndpointSchema = strictObject({
     ...edgeEndpointBaseShape,
     incident: edgeCountSchema,
-});
-const undirectedEdgeEndpointsSchema = tuple([incidentEndpointSchema, incidentEndpointSchema]);
+}).register(documentJsonSchema, { id: 'incident-endpoint' });
+const undirectedEdgeEndpointsSchema = tuple([
+    incidentEndpointSchema,
+    incidentEndpointSchema,
+]).register(documentJsonSchema, { id: 'undirected-endpoints' });
 const edgeConstraintsSchema = strictObject({
     noSelf: literal(true).optional(),
     acyclic: literal(true).optional(),
-});
+}).register(documentJsonSchema, { id: 'edge-constraints' });
+// A tuple names distinct fields: endpoints, the slug and Properties by key. Normalization puts
+// them, and the tuples, in canonical order (`compareEdgeUniqueFields`). No tuple is spelled by the
+// absence of the field, never by an empty list: one spelling per meaning, one revision.
+const edgeUniqueFieldSchema = union([
+    literal('source'),
+    literal('target'),
+    literal('slug'),
+    strictObject({ property: propertyKeySchema }),
+]).register(documentJsonSchema, { id: 'edge-unique-field' });
+const edgeUniqueSchema = nonEmpty(uniqueTupleSet(nonEmpty(uniqueArray(edgeUniqueFieldSchema))));
+// A Node tuple names distinct Properties by key, which normalization puts in code-point order, as
+// it does the tuples (`compareNodeUniqueTuples`). Two orders of one set of keys are one tuple.
+const nodeUniqueSchema = nonEmpty(uniqueTupleSet(nonEmpty(uniqueArray(propertyKeySchema))));
 const policyPatternSubjectSchema = strictObject({ kind: literal('subject') });
 const policyPatternObjectSchema = strictObject({ kind: literal('object') });
 const policyPatternSourceSchema = strictObject({ kind: literal('source') });
@@ -105,7 +227,7 @@ const policyPatternTargetSchema = strictObject({ kind: literal('target') });
 const policyPatternVariableSchema = strictObject({
     kind: literal('variable'),
     id: number().int().min(0),
-});
+}).register(documentJsonSchema, { id: 'policy-pattern-variable' });
 const policyPatternNodeSchema = discriminatedUnion('kind', [
     policyPatternSubjectSchema,
     policyPatternObjectSchema,
@@ -113,19 +235,19 @@ const policyPatternNodeSchema = discriminatedUnion('kind', [
     policyPatternTargetSchema,
     policyPatternVariableSchema,
     strictObject({ kind: literal('ref'), ref: policyObjectRefSchema }),
-]);
+]).register(documentJsonSchema, { id: 'policy-pattern-node' });
 const policyVariableSelectorSchema = discriminatedUnion('kind', [
     strictObject({ kind: literal('any') }),
     strictObject({ kind: literal('satisfies'), class: classRefSchema }),
-]);
+]).register(documentJsonSchema, { id: 'policy-variable-selector' });
 const policyVariableSchema = union([
     strictObject({ variable: policyPatternVariableSchema, class: classRefSchema }),
     strictObject({ variable: policyPatternVariableSchema, selector: policyVariableSelectorSchema }),
-]);
+]).register(documentJsonSchema, { id: 'policy-variable' });
 const policyRepeatSchema = strictObject({
-    min: number().int().min(0).max(3),
-    max: number().int().min(0).max(3),
-});
+    min: number().int().min(0).max(limits.policy.repetition),
+    max: number().int().min(0).max(limits.policy.repetition),
+}).register(documentJsonSchema, { id: 'policy-repeat' });
 const policyPatternExpressionSchema = lazy(() => union([
     strictObject({
         sameNode: strictObject({ left: policyPatternNodeSchema, right: policyPatternNodeSchema }),
@@ -138,17 +260,13 @@ const policyPatternExpressionSchema = lazy(() => union([
     }),
     strictObject({
         exists: strictObject({
-            nodes: array(policyVariableSchema).min(1).max(4),
+            nodes: nonEmpty(array(policyVariableSchema).max(limits.policy.variablesPerExists)),
             where: policyPatternExpressionSchema,
         }),
     }),
-    strictObject({
-        allOf: array(policyPatternExpressionSchema).min(1),
-    }),
-    strictObject({
-        anyOf: array(policyPatternExpressionSchema).min(1),
-    }),
-]));
+    strictObject({ allOf: nonEmpty(array(policyPatternExpressionSchema)) }),
+    strictObject({ anyOf: nonEmpty(array(policyPatternExpressionSchema)) }),
+])).register(documentJsonSchema, { id: 'policy-pattern-expr' });
 const selfObjectSchema = strictObject({ kind: literal('self') });
 const refObjectSchema = strictObject({ kind: literal('ref'), ref: policyObjectRefSchema });
 const policyCheckObjectSchema = discriminatedUnion('kind', [
@@ -158,21 +276,26 @@ const policyCheckObjectSchema = discriminatedUnion('kind', [
         field: memberNameSchema,
     }),
     refObjectSchema,
-]);
-/** A Node Class rule checks the observed Node or one exact member: it has no input. */
-const classRuleObjectSchema = discriminatedUnion('kind', [selfObjectSchema, refObjectSchema]);
+]).register(documentJsonSchema, { id: 'policy-check-object' });
+/** A Class rule checks the observed or written instance or one exact member: it has no input. */
+const classRuleObjectSchema = discriminatedUnion('kind', [
+    selfObjectSchema,
+    refObjectSchema,
+]).register(documentJsonSchema, { id: 'class-rule-object' });
 /** The recursive Policy check grammar, over the objects one use site admits. */
-function policyChecksSchema(objectSchema) {
+function policyChecksSchema(objectSchema, id) {
     const checks = lazy(() => union([
         strictObject({ sameNode: strictObject({ left: objectSchema, right: objectSchema }) }),
         strictObject({ check: policyRefSchema, object: objectSchema }),
-        strictObject({ allOf: array(checks).min(1) }),
-        strictObject({ anyOf: array(checks).min(1) }),
-    ]));
+        strictObject({ allOf: nonEmpty(array(checks)) }),
+        strictObject({ anyOf: nonEmpty(array(checks)) }),
+    ])).register(documentJsonSchema, { id });
     return checks;
 }
-const policyCheckExpressionSchema = policyChecksSchema(policyCheckObjectSchema);
-const classRuleChecksSchema = policyChecksSchema(classRuleObjectSchema);
+const policyCheckExpressionSchema = policyChecksSchema(policyCheckObjectSchema, 'policy-check-expr');
+const classRuleChecksSchema = policyChecksSchema(classRuleObjectSchema, 'class-rule-check-expr');
+/** A Node create rule has no Node to check yet: its objects are exact members only. */
+const createRuleChecksSchema = policyChecksSchema(refObjectSchema, 'create-rule-check-expr');
 const callableOutputSchema = discriminatedUnion('mode', [
     strictObject({
         mode: literal('value'),
@@ -185,139 +308,191 @@ const callableOutputSchema = discriminatedUnion('mode', [
     strictObject({
         mode: literal('binary'),
     }),
-]);
+]).register(documentJsonSchema, { id: 'callable-output' });
 const binaryInputSchema = strictObject({
     mode: literal('binary'),
     metadata: jsonSchemaSchema,
     maximumBytes: number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+}).register(documentJsonSchema, { id: 'binary-input' });
+const valueFunctionInputSchema = jsonSchemaSchema
+    .refine((value) => typeof value !== 'object' || value === null || value.mode !== 'binary', {
+    message: 'Binary input must declare metadata and maximumBytes.',
+    params: { structureCode: 'STRUCTURE_BINARY_INPUT' },
+})
+    .register(documentJsonSchema, {
+    not: { type: 'object', required: ['mode'], properties: { mode: { const: 'binary' } } },
 });
-const valueFunctionInputSchema = jsonSchemaSchema.refine((value) => typeof value !== 'object' || value === null || value.mode !== 'binary', 'Binary input must declare metadata and maximumBytes.');
 const callableExecutionSchema = strictObject({
     durable: boolean(),
-});
+}).register(documentJsonSchema, { id: 'callable-execution' });
+// Its range is language meaning, refused by callable validation with DV_CALLABLE_ADMISSION.
+const callableAdmissionSchema = strictObject({
+    maxAge: number(),
+}).register(documentJsonSchema, { id: 'callable-admission' });
 const callableShape = {
     description: descriptionSchema.optional(),
     input: jsonSchemaSchema,
     output: callableOutputSchema,
     execution: callableExecutionSchema.optional(),
+    admission: callableAdmissionSchema.optional(),
     auth: enumeration(['anonymous', 'authenticated', 'authorized']),
-    policy: union([literal(true), policyCheckExpressionSchema]).optional(),
+    policy: union([literal(true), policyCheckExpressionSchema])
+        .register(documentJsonSchema, { id: 'callable-policy' })
+        .optional(),
+};
+const authorizedPolicy = {
+    if: { properties: { auth: { enum: ['anonymous', 'authenticated'] } }, required: ['auth'] },
+    // oxlint-disable-next-line unicorn/no-thenable -- the JSON Schema keyword
+    then: { properties: { policy: false } },
 };
 const methodDeclarationSchema = strictObject({
     ...callableShape,
     static: boolean(),
     abstract: boolean(),
-}).superRefine((method, context) => {
-    if (method.auth !== 'authorized' && method.policy !== undefined) {
-        context.addIssue({
-            code: 'custom',
-            path: ['policy'],
-            message: 'Only an authorized method may declare a policy.',
-            params: { structureCode: 'STRUCTURE_CALLABLE_POLICY_AUTH' },
-        });
-    }
+})
+    .refine((method) => method.auth === 'authorized' || method.policy === undefined, callablePolicyIssue('method'))
+    .register(documentJsonSchema, { id: 'method-definition', ...authorizedPolicy });
+const methodRecordSchema = record(memberNameSchema, methodDeclarationSchema).register(documentJsonSchema, {
+    id: 'method-record',
 });
-const methodRecordSchema = record(memberNameSchema, methodDeclarationSchema);
-const classPolicySchema = union([literal(false), policyRefSchema]);
-const nodeClassPolicySchema = union([classPolicySchema, classRuleChecksSchema]);
+// Each slot spells one constant: the other one is what its absence already means.
+const observationPolicySchema = union([
+    literal(false),
+    policyRefSchema,
+    classRuleChecksSchema,
+]).register(documentJsonSchema, { id: 'observation-policy' });
+const writePolicySchema = union([literal(true), policyRefSchema, classRuleChecksSchema]).register(documentJsonSchema, { id: 'write-policy' });
+const createPolicySchema = union([literal(true), createRuleChecksSchema]).register(documentJsonSchema, { id: 'create-policy' });
 const nodeClassPoliciesSchema = strictObject({
-    read: nodeClassPolicySchema.optional(),
-    traverse: nodeClassPolicySchema.optional(),
+    read: observationPolicySchema.optional(),
+    traverse: observationPolicySchema.optional(),
+    create: createPolicySchema.optional(),
+    update: writePolicySchema.optional(),
+    delete: writePolicySchema.optional(),
 });
 const edgeClassPoliciesSchema = strictObject({
-    read: classPolicySchema.optional(),
-    traverse: classPolicySchema.optional(),
+    read: observationPolicySchema.optional(),
+    traverse: observationPolicySchema.optional(),
+    create: writePolicySchema.optional(),
+    update: writePolicySchema.optional(),
+    delete: writePolicySchema.optional(),
 });
+// The default `'internal'` is the absence of the field: one spelling per meaning, one revision.
+const inheritanceSchema = enumeration(['open', 'final']);
 const nodeClassSchema = strictObject({
     ref: classRefSchema,
     kind: literal('node'),
     abstract: boolean(),
+    inheritance: inheritanceSchema.optional(),
     description: descriptionSchema.optional(),
     extends: uniqueArray(classRefSchema),
-    properties: propertyRecordSchema,
+    properties: nodePropertyRecordSchema,
     methods: methodRecordSchema,
     data: dataDeclarationSchema.optional(),
     icon: iconSchema.optional(),
     policies: nodeClassPoliciesSchema,
-});
-const edgeClassShape = {
+    unique: nodeUniqueSchema.optional(),
+}).register(documentJsonSchema, { id: 'node-class' });
+const orientationIssue = { params: { structureCode: 'STRUCTURE_EDGE_ORIENTATION' } };
+const edgeClassSchema = strictObject({
     ref: classRefSchema,
     kind: literal('edge'),
     abstract: boolean(),
+    inheritance: inheritanceSchema.optional(),
     description: descriptionSchema.optional(),
     extends: uniqueArray(classRefSchema),
-    properties: propertyRecordSchema,
+    properties: edgePropertyRecordSchema,
     constraints: edgeConstraintsSchema,
-};
-const edgeClassSchema = strictObject({
-    ...edgeClassShape,
+    unique: edgeUniqueSchema.optional(),
     orientation: enumeration(['directed', 'undirected']),
     endpoints: union([directedEdgeEndpointsSchema, undirectedEdgeEndpointsSchema]),
     policies: edgeClassPoliciesSchema,
-}).superRefine(validateEdgeOrientationShape);
-const classDeclarationSchema = discriminatedUnion('kind', [nodeClassSchema, edgeClassSchema]);
-function validateEdgeOrientationShape(value, context) {
-    if ((value.orientation === 'undirected') === Array.isArray(value.endpoints))
-        return;
-    context.addIssue({
-        code: 'custom',
-        path: ['endpoints'],
-        message: `${value.orientation} Edge endpoints have the wrong structural shape.`,
-        params: { structureCode: 'STRUCTURE_EDGE_ORIENTATION' },
-    });
-}
-const functionDefinitionSchema = strictObject({
-    ref: functionRefSchema,
+})
+    .refine((edge) => (edge.orientation === 'undirected') === Array.isArray(edge.endpoints), {
+    ...orientationIssue,
+    path: ['endpoints'],
+    error: 'Edge endpoints do not have the structural shape of its orientation.',
+})
+    .refine((edge) => edge.orientation === 'directed' || edge.unique === undefined, {
+    ...orientationIssue,
+    path: ['unique'],
+    error: 'Only a directed Edge Class declares unique tuples.',
+})
+    .refine((edge) => edge.orientation === 'directed' || edge.constraints.acyclic === undefined, {
+    ...orientationIssue,
+    path: ['constraints', 'acyclic'],
+    error: 'Only a directed Edge Class is acyclic.',
+})
+    .register(documentJsonSchema, {
+    id: 'edge-class',
+    if: { properties: { orientation: { const: 'undirected' } }, required: ['orientation'] },
+    // oxlint-disable-next-line unicorn/no-thenable -- the JSON Schema keyword
+    then: {
+        properties: {
+            endpoints: { type: 'array' },
+            unique: false,
+            constraints: { type: 'object', properties: { acyclic: false } },
+        },
+    },
+    else: { properties: { endpoints: { type: 'object' } } },
+});
+const classDeclarationSchema = discriminatedUnion('kind', [
+    nodeClassSchema,
+    edgeClassSchema,
+]).register(documentJsonSchema, { id: 'class-definition' });
+const functionContractShape = {
     ...callableShape,
     input: union([binaryInputSchema, valueFunctionInputSchema]),
-}).superRefine((callable, context) => {
-    if (callable.auth !== 'authorized' && callable.policy !== undefined) {
-        context.addIssue({
-            code: 'custom',
-            path: ['policy'],
-            message: 'Only an authorized function may declare a policy.',
-            params: { structureCode: 'STRUCTURE_CALLABLE_POLICY_AUTH' },
-        });
-    }
-});
+};
+const functionDefinitionSchema = strictObject({
+    ref: functionRefSchema,
+    ...functionContractShape,
+})
+    .refine((callable) => callable.auth === 'authorized' || callable.policy === undefined, callablePolicyIssue('function'))
+    .register(documentJsonSchema, { id: 'function-definition', ...authorizedPolicy });
+// A callable contract has the structure of a Function declaration without its ref, wherever it is.
+const callableContractSchema = strictObject(functionContractShape).refine((callable) => callable.auth === 'authorized' || callable.policy === undefined, callablePolicyIssue('function'));
 const policyExpressionSchema = union([
     strictObject({
         match: policyPatternExpressionSchema,
     }),
-    strictObject({
-        allOf: array(policyRefSchema).min(1),
-    }),
-    strictObject({
-        anyOf: array(policyRefSchema).min(1),
-    }),
+    strictObject({ allOf: nonEmpty(array(policyRefSchema)) }),
+    strictObject({ anyOf: nonEmpty(array(policyRefSchema)) }),
 ]);
 const policyDefinitionSchema = strictObject({
     ref: policyRefSchema,
     expression: policyExpressionSchema,
     description: descriptionSchema.optional(),
+}).register(documentJsonSchema, { id: 'policy-definition' });
+const viewTargetSchema = strictObject({ kind: literal('domain') }).register(documentJsonSchema, {
+    id: 'view-target',
+    description: 'Every View targets its owning Domain.',
 });
-const viewTargetSchema = strictObject({ kind: literal('domain') });
 const viewDefinitionSchema = strictObject({
     ref: viewRefSchema,
     description: descriptionSchema.optional(),
     target: viewTargetSchema,
+}).register(documentJsonSchema, { id: 'view-definition' });
+const propertyValuesSchema = record(propertyKeySchema, jsonValueSchema).register(documentJsonSchema, {
+    id: 'property-values',
 });
 const coreNodeSchema = strictObject({
     ref: coreRefSchema,
     class: classRefSchema,
-    properties: record(propertyKeySchema, jsonValueSchema),
-});
+    properties: propertyValuesSchema,
+}).register(documentJsonSchema, { id: 'core-definition' });
 const coreEdgeSchema = strictObject({
     class: classRefSchema,
     source: coreEndpointRefSchema,
     target: coreEndpointRefSchema,
-    properties: record(propertyKeySchema, jsonValueSchema),
-});
+    properties: propertyValuesSchema,
+}).register(documentJsonSchema, { id: 'core-edge' });
 const coreSchema = strictObject({
     nodes: record(coreSlugSchema, coreNodeSchema),
     edges: array(coreEdgeSchema),
-});
-const structuralSchema = strictObject({
+}).register(documentJsonSchema, { id: 'core' });
+/** The structure of an authored Domain schema document, the single source of its JSON Schema. */
+export const domainSchemaStructure = strictObject({
     format: literal(DOMAIN_FORMAT),
     version: literal(DOMAIN_VERSION),
     origin: originSchema,
@@ -330,19 +505,65 @@ const structuralSchema = strictObject({
     views: record(memberNameSchema, viewDefinitionSchema),
     core: coreSchema,
 });
-const domainSchemaStructuralSchema = structuralSchema;
 export function parseDomainSchemaStructure(input) {
-    const result = domainSchemaStructuralSchema.safeParse(input);
-    if (result.success)
-        return result.data;
-    throw new SchemaError(result.error.issues.flatMap((issue) => diagnosticsForIssue(issue, input)));
+    const result = domainSchemaStructure.safeParse(input);
+    if (!result.success) {
+        throw new SchemaError(result.error.issues.flatMap((issue) => diagnosticsForIssue(issue, input)));
+    }
+    const lost = lostProtoKeys(input, result.data, []);
+    if (lost.length > 0)
+        throw new SchemaError(lost);
+    return modelOf(result.data);
+}
+/**
+ * Each `__proto__` member of the input that the parsed document lost. Zod skips that member in an
+ * object or a record, so the structure would accept the document without it; it refuses the
+ * document instead. A State's transitions are read in place and keep the member.
+ */
+function lostProtoKeys(input, parsed, path) {
+    if (!isObject(input) || !isObject(parsed))
+        return [];
+    const lost = Object.hasOwn(input, PROTO_KEY) && !Object.hasOwn(parsed, PROTO_KEY)
+        ? [
+            diagnostic('STRUCTURE_PROTO_KEY', pointer([...path, PROTO_KEY]), 'A member named __proto__ is refused: the parsed document cannot keep it.'),
+        ]
+        : [];
+    return [
+        ...lost,
+        ...Object.keys(parsed).flatMap((key) => lostProtoKeys(Reflect.get(input, key), Reflect.get(parsed, key), [...path, key])),
+    ];
+}
+/** Parse the structure of one callable contract: a Function declaration without its ref. */
+export function parseCallableContract(input) {
+    const result = callableContractSchema.safeParse(input);
+    if (!result.success) {
+        throw new SchemaError(result.error.issues.flatMap((issue) => diagnosticsForIssue(issue, input)));
+    }
+    const lost = lostProtoKeys(input, result.data, []);
+    if (lost.length > 0)
+        throw new SchemaError(lost);
+    return result.data;
+}
+/**
+ * The structure admits the document the model types: this parameter checks one direction, and
+ * `domain.structure.typecheck.ts` both. The brands are the model's own proofs from here on.
+ */
+function modelOf(document) {
+    return document;
 }
 function absoluteRefSchema(kind) {
     return strictObject({
         origin: originSchema,
         kind: literal(kind),
         name: memberNameSchema,
-    });
+    }).register(documentJsonSchema, { id: `${kind}-ref` });
+}
+function callablePolicyIssue(owner) {
+    return {
+        path: ['policy'],
+        params: { structureCode: 'STRUCTURE_CALLABLE_POLICY_AUTH' },
+        error: `Only an authorized ${owner} may declare a policy.`,
+    };
 }
 function isStateTransitions(input) {
     if (!isRecord(input))
@@ -366,13 +587,31 @@ function isStateTransitions(input) {
     return true;
 }
 function isRecord(input) {
-    return input !== null && typeof input === 'object' && !Array.isArray(input);
+    return isObject(input) && !Array.isArray(input);
+}
+function isObject(input) {
+    return input !== null && typeof input === 'object';
+}
+/** At least one item, which `min(1)` proves: the output is typed as the non-empty tuple it is. */
+function nonEmpty(list) {
+    return list.min(1);
 }
+/** Items distinct by JSON equality, which JSON Schema states as `uniqueItems`. */
 function uniqueArray(element) {
+    return distinctArray(element, canonicalJson).register(documentJsonSchema, { uniqueItems: true });
+}
+/**
+ * Tuples distinct as sets of fields. JSON Schema states their JSON equality, `uniqueItems`; the
+ * rule `unique-tuple-set` names the rest.
+ */
+function uniqueTupleSet(tuple) {
+    return distinctArray(tuple, (fields) => JSON.stringify(fields.map(canonicalJson).sort())).register(documentJsonSchema, { uniqueItems: true, 'x-astrale-rule': 'unique-tuple-set' });
+}
+function distinctArray(element, keyOf) {
     return array(element).superRefine((values, context) => {
         const firstIndexByValue = new Map();
         values.forEach((value, index) => {
-            const key = canonicalJson(value);
+            const key = keyOf(value);
             const firstIndex = firstIndexByValue.get(key);
             if (firstIndex === undefined) {
                 firstIndexByValue.set(key, index);
@@ -401,24 +640,40 @@ function diagnosticsForIssue(issue, input) {
     if (issue.code === 'unrecognized_keys') {
         return issue.keys.map((key) => diagnostic('STRUCTURE_UNKNOWN_FIELD', pointer([...issue.path, key]), `Unknown field ${JSON.stringify(key)}.`));
     }
-    const customCode = issue.code === 'custom' ? customStructureCode(issue.params?.structureCode) : undefined;
+    // A record key refused by a refinement reports that refinement, at the key.
+    const refinement = issue.code === 'invalid_key' ? issue.issues.find(isRefinement) : undefined;
+    if (refinement !== undefined) {
+        return [diagnostic(refinementCode(refinement), pointer(issue.path), refinement.message)];
+    }
     return [
-        diagnostic(customCode ?? structureCode(issue, input), pointer(issue.path), structureMessage(issue, input)),
+        diagnostic(structureCode(issue, input), pointer(issue.path), structureMessage(issue, input)),
     ];
 }
-function customStructureCode(input) {
-    switch (input) {
-        case 'STRUCTURE_ABSTRACT_POLICY':
+function isRefinement(issue) {
+    return issue.code === 'custom';
+}
+/** Every refinement of the structure names its own code. */
+function refinementCode(issue) {
+    const code = issue.params?.structureCode;
+    switch (code) {
+        case 'STRUCTURE_BINARY_INPUT':
         case 'STRUCTURE_CALLABLE_POLICY_AUTH':
+        case 'STRUCTURE_DEPENDENCY_ALIAS':
+        case 'STRUCTURE_DOMAIN_NAME':
         case 'STRUCTURE_DUPLICATE_ITEM':
+        case 'STRUCTURE_EDGE_BLOB':
         case 'STRUCTURE_EDGE_ORIENTATION':
-            return input;
+        case 'STRUCTURE_PROPERTY_KEY':
+        case 'STRUCTURE_STATE_TRANSITIONS':
+            return code;
         default:
-            return undefined;
+            throw new TypeError(`A structure refinement names no Schema code: ${String(code)}.`);
     }
 }
 function structureCode(issue, input) {
     switch (issue.code) {
+        case 'custom':
+            return refinementCode(issue);
         case 'invalid_type':
             return valueAtPath(input, issue.path) === undefined ? 'STRUCTURE_REQUIRED' : 'STRUCTURE_TYPE';
         case 'invalid_value':
@@ -433,10 +688,9 @@ function structureCode(issue, input) {
             return 'STRUCTURE_MINIMUM';
         case 'too_big':
             return 'STRUCTURE_MAXIMUM';
-        case 'not_multiple_of':
-            return 'STRUCTURE_MULTIPLE';
         default:
-            return 'STRUCTURE_INVALID';
+            // The structure declares no multipleOf, Map or Set.
+            throw new TypeError(`The structure raised a ${issue.code} issue it declares no check for.`);
     }
 }
 function structureMessage(issue, input) {
@@ -463,8 +717,5 @@ function valueAtPath(input, path) {
 function pointer(path) {
     if (path.length === 0)
         return '';
-    return `/${path.map((segment) => escapePointerSegment(String(segment))).join('/')}`;
-}
-function escapePointerSegment(segment) {
-    return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+    return `/${path.map((segment) => escapePointerToken(String(segment))).join('/')}`;
 }