@astrale-os/kernel-dsl 1.0.0-beta.10 → 1.0.0-beta.12

package/dist/v1/schema/validation/value-api.d.ts

@@ -1,4 +1,5 @@
 /** The exact V1 value-schema grammar embedded in DomainSchema declarations. */
+import type { ValueKind } from '@astrale-os/kernel-dsl/value';
 import type { Diagnostic } from '../../language/validation/diagnostic.js';
 import type { JsonSchema } from '../../language/value/model/schema.js';
 import type { OrderingKind } from '../../language/value/ordering.js';
@@ -13,3 +14,11 @@ export type { OrderingKind } from '../../language/value/ordering.js';
 export declare function validate(owner: DomainSchema, contract: JsonSchema, input: unknown, pointer?: string): readonly Diagnostic[];
 /** Return the one portable scalar ordering domain admitted by a property schema, if any. */
 export declare function classifyOrdering(owner: DomainSchema, contract: JsonSchema): OrderingKind | undefined;
+/** The value kind of a property schema: what a graph language may test on the property (Y4). */
+export declare function classifyValueKind(owner: DomainSchema, contract: JsonSchema): ValueKind;
+/**
+ * A warning for each class property whose value kind is `json` (an ambiguous union, an object, an
+ * array with repetitions): a Query filters it by equality only. Nothing refuses such a property;
+ * the CLI shows the warning to its author.
+ */
+export declare function valueKindWarnings(owner: DomainSchema): readonly Diagnostic<'VS_VALUE_KIND_JSON'>[];

package/dist/v1/schema/validation/value-api.js

@@ -1,7 +1,9 @@
 /** The exact V1 value-schema grammar embedded in DomainSchema declarations. */
+import { diagnostic } from '../../language/validation/diagnostic.js';
 import { validateJsonInstance } from '../../language/value/evaluate/validate.js';
-import { classifyOrdering as classifyOrderingWithRegistry } from '../../language/value/ordering.js';
+import { classifyOrdering as classifyOrderingWithRegistry, classifyValueKind as classifyValueKindWithRegistry, } from '../../language/value/ordering.js';
 import { createDomainValueSchemaRegistry } from '../resolution/value.registry.js';
+import { escapePointer } from './policy/context.js';
 const registries = new WeakMap();
 export { VALUE_SCHEMA_DIALECT as DIALECT, VALUE_SCHEMA_VOCABULARY as VOCABULARY, } from '../../language/value/model/schema.js';
 export { blob, isBlobValueSchema as isBlob } from '../../language/value/model/blob.js';
@@ -14,6 +16,26 @@ export function validate(owner, contract, input, pointer = '') {
 export function classifyOrdering(owner, contract) {
     return classifyOrderingWithRegistry(contract, registryFor(owner));
 }
+/** The value kind of a property schema: what a graph language may test on the property (Y4). */
+export function classifyValueKind(owner, contract) {
+    return classifyValueKindWithRegistry(contract, registryFor(owner));
+}
+/**
+ * A warning for each class property whose value kind is `json` (an ambiguous union, an object, an
+ * array with repetitions): a Query filters it by equality only. Nothing refuses such a property;
+ * the CLI shows the warning to its author.
+ */
+export function valueKindWarnings(owner) {
+    const warnings = [];
+    for (const [className, definition] of Object.entries(owner.classes)) {
+        for (const [name, property] of Object.entries(definition.properties)) {
+            if (classifyValueKind(owner, property.schema) !== 'json')
+                continue;
+            warnings.push(diagnostic('VS_VALUE_KIND_JSON', `/classes/${escapePointer(className)}/properties/${escapePointer(name)}`, `The value kind of ${className}.${name} is json: a Query filters it by equality only.`));
+        }
+    }
+    return warnings;
+}
 function registryFor(owner) {
     let registry = registries.get(owner);
     if (registry === undefined) {

package/dist/value/canonical.d.ts

@@ -6,7 +6,8 @@ export declare function serialize(input: unknown, options?: Options): string;
 export declare function serializeAdmitted(input: Value): string;
 export declare function encode(input: unknown, options?: Options): Uint8Array;
 /**
- * The UTF-8 byte length of a trusted Value's canonical JSON, `encode(input).byteLength`: an
- * admission-owned immutable root counted its bytes when it was admitted, so it is not serialized.
+ * The UTF-8 byte length of a trusted Value's canonical JSON, `encode(input).byteLength`, without
+ * serializing it: an admission-owned immutable root counted its bytes when it was admitted, and any
+ * other container is counted member by member.
  */
 export declare function byteLength(input: Value): number;

package/dist/value/canonical.js

@@ -32,16 +32,40 @@ export function encode(input, options) {
     return encoder.encode(serialize(input, options));
 }
 /**
- * The UTF-8 byte length of a trusted Value's canonical JSON, `encode(input).byteLength`: an
- * admission-owned immutable root counted its bytes when it was admitted, so it is not serialized.
+ * The UTF-8 byte length of a trusted Value's canonical JSON, `encode(input).byteLength`, without
+ * serializing it: an admission-owned immutable root counted its bytes when it was admitted, and any
+ * other container is counted member by member.
  */
 export function byteLength(input) {
     if (input !== null && typeof input === 'object') {
-        const bytes = immutableSnapshotBytes(input);
-        if (bytes !== undefined)
-            return bytes;
+        const owned = immutableSnapshotBytes(input);
+        if (owned !== undefined)
+            return owned;
     }
-    return utf8Length(serializeAdmitted(input));
+    // As serializing it would, a Value beyond the default emitted-byte bound refuses.
+    const bytes = measure(input);
+    if (bytes > defaultLimits.maxBytes)
+        throw new BoundaryError('VALUE_LIMIT', `Canonical JSON exceeds the ${defaultLimits.maxBytes}-byte limit`);
+    return bytes;
+}
+/** The canonical JSON bytes of a trusted Value, counted member by member, owned roots at once. */
+function measure(value) {
+    if (value === null || typeof value !== 'object')
+        return canonicalPrimitiveBytes(value);
+    const owned = immutableSnapshotBytes(value);
+    if (owned !== undefined)
+        return owned;
+    if (Array.isArray(value)) {
+        let bytes = 2 + Math.max(0, value.length - 1);
+        for (const item of value)
+            bytes += measure(item);
+        return bytes;
+    }
+    const keys = Object.keys(value);
+    let bytes = 2 + Math.max(0, keys.length - 1) + keys.length;
+    for (const key of keys)
+        bytes += canonicalPrimitiveBytes(key) + measure(value[key]);
+    return bytes;
 }
 function serializeValue(value) {
     if (value === null)

package/dist/value/decode.d.ts

@@ -2,3 +2,10 @@ import type { Value } from './types.js';
 import { type Options } from './limits.js';
 /** Strictly decode one bounded JSON value. */
 export declare function decode(input: string | Uint8Array, options?: Options): Value;
+/**
+ * Strictly decode one bounded JSON value as the deeply frozen snapshot `acceptImmutable` returns
+ * for it, within the same complete canonical byte budget. Native parsing built every container
+ * from scanned text, so none needs host reflection: the scan counts its receipt, and freezing it
+ * completes its admission.
+ */
+export declare function decodeImmutable(input: string | Uint8Array, options?: Options): Value;

package/dist/value/decode.js

@@ -1,16 +1,137 @@
 import { printParseErrorCode, visit } from 'jsonc-parser';
 import { DecodeError } from './error.js';
+import { retainImmutableSnapshot } from './immutable.optimization.js';
 import { limitsFor } from './limits.js';
-import { assertDecodedString, assertSourceString } from './unicode.js';
+import { assertDecodedString, assertSourceString, canonicalPrimitiveBytes, utf8Length, } from './unicode.js';
 const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 /** Strictly decode one bounded JSON value. */
 export function decode(input, options) {
+    return decodeWith(input, limitsFor(options), undefined);
+}
+/**
+ * Strictly decode one bounded JSON value as the deeply frozen snapshot `acceptImmutable` returns
+ * for it, within the same complete canonical byte budget. Native parsing built every container
+ * from scanned text, so none needs host reflection: the scan counts its receipt, and freezing it
+ * completes its admission.
+ */
+export function decodeImmutable(input, options) {
     const limits = limitsFor(options);
+    const summary = { members: 0, depth: 0, stringBytes: 0, canonicalBytes: 0 };
+    // Canonical text may decode to null, so only undefined sends it to the strict scan.
+    const canonical = decodeCanonical(input, limits, summary);
+    const value = canonical === undefined ? decodeWith(input, limits, summary) : canonical;
+    if (value !== null && typeof value === 'object') {
+        freeze(value);
+        retainImmutableSnapshot(value, summary);
+    }
+    return value;
+}
+/**
+ * The value `input` parses to when `input` is exactly the text `JSON.stringify` writes for that
+ * value, with its receipt counted into `summary`; canonical JSON, as this package serializes it,
+ * is such text. That text holds no whitespace, no duplicate member and no number the strict scan
+ * refuses, and its byte length is the canonical length, so one walk of the parsed value checks
+ * what remains, its strings and limits, as the scan would. Any other input answers undefined, and
+ * the strict scan decides it.
+ */
+function decodeCanonical(input, limits, summary) {
+    let source;
+    let bytes;
+    if (typeof input === 'string') {
+        source = input;
+        bytes = utf8Length(input, limits.maxBytes);
+        if (bytes < 0)
+            return undefined;
+    }
+    else {
+        bytes = input.byteLength;
+        try {
+            source = decoder.decode(input);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (bytes > limits.maxBytes)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+    // In ASCII text, a string holds U+0000 or a lone surrogate only through its escape; without one,
+    // each string's UTF-8 length is its length.
+    const ascii = bytes === source.length && !source.includes('\\u0000') && !source.includes('\\ud');
+    const walk = { limits, ascii, members: 0, depth: 0, strings: 0 };
+    if (!portable(value, 0, walk) || JSON.stringify(value) !== source)
+        return undefined;
+    summary.members = walk.members;
+    summary.depth = walk.depth;
+    summary.stringBytes = walk.strings;
+    summary.canonicalBytes = bytes;
+    return value;
+}
+/** Whether a parsed value's strings and limits hold as the strict scan checks them. */
+function portable(value, depth, walk) {
+    if (typeof value === 'string')
+        return portableString(value, walk);
+    // A number the scan refuses, -0 or one past binary64, never reads back as the text written for it.
+    if (value === null || typeof value !== 'object')
+        return true;
+    if (depth >= walk.limits.maxDepth)
+        return false;
+    if (depth >= walk.depth)
+        walk.depth = depth + 1;
+    if (Array.isArray(value)) {
+        walk.members += value.length;
+        if (walk.members > walk.limits.maxMembers)
+            return false;
+        for (let index = 0; index < value.length; index += 1) {
+            if (!portable(value[index], depth + 1, walk))
+                return false;
+        }
+        return true;
+    }
+    const keys = Object.keys(value);
+    walk.members += keys.length;
+    if (walk.members > walk.limits.maxMembers)
+        return false;
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index];
+        if (!portableString(key, walk))
+            return false;
+        if (!portable(value[key], depth + 1, walk))
+            return false;
+    }
+    return true;
+}
+function portableString(value, walk) {
+    let bytes = value.length;
+    if (!walk.ascii) {
+        if (value.includes('\u0000'))
+            return false;
+        bytes = utf8Length(value, walk.limits.maxStringBytes);
+        if (bytes < 0)
+            return false;
+    }
+    if (bytes > walk.limits.maxStringBytes)
+        return false;
+    if (bytes > walk.strings)
+        walk.strings = bytes;
+    return true;
+}
+function decodeWith(input, limits, summary) {
     const source = sourceFor(input, limits);
     if (source.charCodeAt(0) === 0xfeff) {
         throw new DecodeError('JSON_SYNTAX', 'A byte-order mark is not JSON whitespace', 0);
     }
-    scan(source, limits);
+    scan(source, limits, summary);
+    // An immutable snapshot keeps to the canonical byte budget, which a value's text need not.
+    if (summary !== undefined && summary.canonicalBytes > limits.maxBytes) {
+        throw new DecodeError('JSON_LIMIT', `Canonical JSON exceeds the ${limits.maxBytes}-byte limit`, 0);
+    }
     try {
         return JSON.parse(source);
     }
@@ -18,6 +139,13 @@ export function decode(input, options) {
         throw new DecodeError('JSON_SYNTAX', 'Native JSON decoding rejected the strictly scanned input', 0, { cause: error });
     }
 }
+function freeze(value) {
+    for (const member of Object.values(value)) {
+        if (member !== null && typeof member === 'object')
+            freeze(member);
+    }
+    Object.freeze(value);
+}
 function sourceFor(input, limits) {
     if (typeof input === 'string') {
         assertSourceString(input, limits.maxBytes);
@@ -33,14 +161,18 @@ function sourceFor(input, limits) {
         throw new DecodeError('JSON_UTF8', 'Malformed UTF-8 JSON input', 0, { cause: error });
     }
 }
-function scan(source, limits) {
-    const state = { frames: [], limits, members: 0 };
+function scan(source, limits, summary) {
+    const state = { frames: [], limits, members: 0, summary };
     const beginContainer = (kind, offset) => {
         countArrayItem(state, offset);
         if (state.frames.length >= limits.maxDepth) {
             throw new DecodeError('JSON_LIMIT', `JSON nesting exceeds the ${limits.maxDepth}-level limit`, offset);
         }
-        state.frames.push(kind === 'object' ? { kind, names: new Set() } : { kind });
+        state.frames.push(kind === 'object' ? { kind, names: new Set(), entries: 0 } : { kind, entries: 0 });
+        if (summary !== undefined) {
+            summary.depth = Math.max(summary.depth, state.frames.length);
+            summary.canonicalBytes += 2;
+        }
     };
     const visitor = {
         onObjectBegin: (offset) => beginContainer('object', offset),
@@ -48,12 +180,18 @@ function scan(source, limits) {
             const frame = state.frames.at(-1);
             if (frame?.kind !== 'object')
                 failSyntax('Object member outside an Object', offset);
-            assertDecodedString(name, offset, limits.maxStringBytes);
+            const bytes = assertDecodedString(name, offset, limits.maxStringBytes);
             if (frame.names.has(name)) {
                 throw new DecodeError('JSON_DUPLICATE_MEMBER', `Duplicate object member ${JSON.stringify(name)}`, offset);
             }
             frame.names.add(name);
             addMembers(state, 1, offset);
+            if (summary !== undefined) {
+                // The name, its colon, and a comma before every member but the first.
+                summary.stringBytes = Math.max(summary.stringBytes, bytes);
+                summary.canonicalBytes += canonicalPrimitiveBytes(name) + (frame.entries > 0 ? 2 : 1);
+            }
+            frame.entries += 1;
         },
         onObjectEnd: (offset) => endContainer(state, 'object', offset),
         onArrayBegin: (offset) => beginContainer('array', offset),
@@ -61,7 +199,9 @@ function scan(source, limits) {
         onLiteralValue: (value, offset) => {
             countArrayItem(state, offset);
             if (typeof value === 'string') {
-                assertDecodedString(value, offset, limits.maxStringBytes);
+                const bytes = assertDecodedString(value, offset, limits.maxStringBytes);
+                if (summary !== undefined)
+                    summary.stringBytes = Math.max(summary.stringBytes, bytes);
             }
             else if (typeof value === 'number') {
                 if (!Number.isFinite(value)) {
@@ -71,6 +211,8 @@ function scan(source, limits) {
                     throw new DecodeError('JSON_NUMBER', 'JSON number resolves to negative zero', offset);
                 }
             }
+            if (summary !== undefined)
+                summary.canonicalBytes += canonicalPrimitiveBytes(value);
         },
         onError: (error, offset) => {
             failSyntax(`Invalid JSON: ${printParseErrorCode(error)}`, offset);
@@ -88,10 +230,18 @@ function scan(source, limits) {
             throw error;
         throw new DecodeError('JSON_SYNTAX', 'JSON scanner failed', 0, { cause: error });
     }
+    if (summary !== undefined)
+        summary.members = state.members;
 }
 function countArrayItem(state, offset) {
-    if (state.frames.at(-1)?.kind === 'array')
-        addMembers(state, 1, offset);
+    const frame = state.frames.at(-1);
+    if (frame?.kind !== 'array')
+        return;
+    addMembers(state, 1, offset);
+    // A comma before every item but the first.
+    if (state.summary !== undefined && frame.entries > 0)
+        state.summary.canonicalBytes += 1;
+    frame.entries += 1;
 }
 function addMembers(state, count, offset) {
     state.members += count;

package/dist/value/index.d.ts

@@ -6,4 +6,4 @@ export type { BoundaryErrorCode, DecodeErrorCode } from './error.js';
 export { defaultLimits } from './limits.js';
 export type { LimitOverrides, Limits, Options } from './limits.js';
 export * as json from './json.js';
-export type { Array, Object, Primitive, Value } from './types.js';
+export type { Array, Object, Primitive, Value, ValueKind } from './types.js';

package/dist/value/json.d.ts

@@ -1,3 +1,3 @@
 export { byteLength, encode, serialize, serializeAdmitted } from './canonical.js';
-export { decode } from './decode.js';
+export { decode, decodeImmutable } from './decode.js';
 export { DecodeError } from './error.js';

package/dist/value/json.js

@@ -1,3 +1,3 @@
 export { byteLength, encode, serialize, serializeAdmitted } from './canonical.js';
-export { decode } from './decode.js';
+export { decode, decodeImmutable } from './decode.js';
 export { DecodeError } from './error.js';

package/dist/value/types.d.ts

@@ -4,3 +4,9 @@ export type Object = {
     readonly [name: string]: Value;
 };
 export type Value = Primitive | Array | Object;
+/**
+ * The value kind of a property (page "Fondations Query v7", § Atoms et value kinds, Y4): what a
+ * graph language may test on its values. The schema of the property derives it; `null` is a point
+ * of every kind, outside every order (R6).
+ */
+export type ValueKind = 'text' | 'number' | 'instant' | 'enum' | 'boolean' | 'set' | 'json';

package/dist/value/unicode.d.ts

@@ -3,5 +3,6 @@ import type { Primitive } from './types.js';
 export declare function canonicalPrimitiveBytes(value: Primitive): number;
 export declare function utf8Length(value: string, max?: number): number;
 export declare function assertHostString(value: string, pointer: string, maxBytes: number): number;
-export declare function assertDecodedString(value: string, offset: number, maxBytes: number): void;
+/** Its UTF-8 length, once it is a portable string within `maxBytes`. */
+export declare function assertDecodedString(value: string, offset: number, maxBytes: number): number;
 export declare function assertSourceString(value: string, maxBytes: number): void;

package/dist/value/unicode.js

@@ -63,6 +63,7 @@ export function assertHostString(value, pointer, maxBytes) {
     }
     return length;
 }
+/** Its UTF-8 length, once it is a portable string within `maxBytes`. */
 export function assertDecodedString(value, offset, maxBytes) {
     if (value.includes('\u0000')) {
         throw new DecodeError('JSON_STRING', 'JSON string contains U+0000', offset);
@@ -74,6 +75,7 @@ export function assertDecodedString(value, offset, maxBytes) {
     if (length > maxBytes) {
         throw new DecodeError('JSON_LIMIT', `JSON string exceeds the ${maxBytes}-byte UTF-8 limit`, offset);
     }
+    return length;
 }
 export function assertSourceString(value, maxBytes) {
     const length = utf8Length(value, maxBytes);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-dsl",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.12",
   "description": "Astrale Kernel DSL - Schema authoring, inference, and IR serialization",
   "license": "Apache-2.0",
   "repository": {