circuitjson-toolkit 1.0.16 → 1.1.0

package/src/core/context/CircuitJsonSchematicTableNormalizer.mjs

@@ -0,0 +1,314 @@
+import { CircuitJsonUnits } from '../CircuitJsonUnits.mjs'
+
+/**
+ * Projects grid-addressed table cells onto upstream CircuitJSON geometry.
+ */
+export class CircuitJsonSchematicTableNormalizer {
+    /**
+     * Normalizes every table cell in one model.
+     * @param {object[]} rows Model rows.
+     * @param {boolean} owned Whether rows may be mutated in place.
+     * @returns {boolean} Whether any cell changed.
+     */
+    static normalize(rows, owned) {
+        const tables = new Map()
+        for (let index = 0; index < rows.length; index += 1) {
+            const table = CircuitJsonSchematicTableNormalizer.#table(
+                rows[index]
+            )
+            if (table) tables.set(table.id, table)
+        }
+        if (!tables.size) return false
+
+        let changed = false
+        for (let index = 0; index < rows.length; index += 1) {
+            const descriptors = CircuitJsonSchematicTableNormalizer.#record(
+                rows[index]
+            )
+            if (descriptors?.type?.value !== 'schematic_table_cell') continue
+            const fields =
+                CircuitJsonSchematicTableNormalizer.#fields(descriptors)
+            const table = tables.get(String(fields.schematic_table_id || ''))
+            const normalized = CircuitJsonSchematicTableNormalizer.#cell(
+                fields,
+                table
+            )
+            if (
+                !normalized ||
+                !CircuitJsonSchematicTableNormalizer.#changed(
+                    normalized,
+                    descriptors
+                )
+            ) {
+                continue
+            }
+            changed = true
+            if (owned) {
+                for (const key of Object.keys(rows[index])) {
+                    delete rows[index][key]
+                }
+                Object.assign(rows[index], normalized)
+            } else {
+                rows[index] = normalized
+            }
+        }
+        return changed
+    }
+
+    /**
+     * Builds table grid offsets from one table row.
+     * @param {unknown} row Table row candidate.
+     * @returns {Record<string, any> | null} Table geometry.
+     */
+    static #table(row) {
+        const descriptors = CircuitJsonSchematicTableNormalizer.#record(row)
+        if (descriptors?.type?.value !== 'schematic_table') return null
+        const fields = CircuitJsonSchematicTableNormalizer.#fields(descriptors)
+        const id = String(fields.schematic_table_id || '').trim()
+        const columns = CircuitJsonSchematicTableNormalizer.#lengths(
+            fields.column_widths
+        )
+        const rows = CircuitJsonSchematicTableNormalizer.#lengths(
+            fields.row_heights
+        )
+        const anchor = CircuitJsonUnits.optionalPoint(fields.anchor_position)
+        if (!id || !columns.length || !rows.length || !anchor) return null
+        const width = columns.reduce((total, value) => total + value, 0)
+        const height = rows.reduce((total, value) => total + value, 0)
+        const name = String(fields.anchor || 'top_left').toLowerCase()
+        const [vertical, horizontal] =
+            name === 'center' || name === 'middle'
+                ? ['center', 'center']
+                : name.split('_')
+        return {
+            id,
+            x: CircuitJsonSchematicTableNormalizer.#anchorCoordinate(
+                anchor.x,
+                width,
+                horizontal
+            ),
+            y: CircuitJsonSchematicTableNormalizer.#anchorCoordinate(
+                anchor.y,
+                height,
+                vertical
+            ),
+            columns,
+            rows,
+            columnOffsets:
+                CircuitJsonSchematicTableNormalizer.#offsets(columns),
+            rowOffsets: CircuitJsonSchematicTableNormalizer.#offsets(rows)
+        }
+    }
+
+    /**
+     * Converts one grid-addressed cell to canonical geometry and indexes.
+     * @param {Record<string, any>} fields Cell fields.
+     * @param {Record<string, any> | undefined} table Parent table geometry.
+     * @returns {Record<string, any> | null} Canonical cell fields.
+     */
+    static #cell(fields, table) {
+        if (!table) return null
+        const startRow = CircuitJsonSchematicTableNormalizer.#index(
+            fields.start_row_index ??
+                fields.row ??
+                fields.row_index ??
+                fields.rowIndex
+        )
+        const startColumn = CircuitJsonSchematicTableNormalizer.#index(
+            fields.start_column_index ??
+                fields.column ??
+                fields.col ??
+                fields.column_index ??
+                fields.columnIndex
+        )
+        if (
+            startRow === null ||
+            startColumn === null ||
+            startRow >= table.rows.length ||
+            startColumn >= table.columns.length
+        ) {
+            return null
+        }
+        const endRow = CircuitJsonSchematicTableNormalizer.#endIndex(
+            fields.end_row_index,
+            startRow,
+            fields.row_span ?? fields.rowSpan,
+            table.rows.length
+        )
+        const endColumn = CircuitJsonSchematicTableNormalizer.#endIndex(
+            fields.end_column_index,
+            startColumn,
+            fields.col_span ?? fields.column_span ?? fields.colSpan,
+            table.columns.length
+        )
+        if (endRow < startRow || endColumn < startColumn) return null
+        const x = table.x + table.columnOffsets[startColumn]
+        const y = table.y + table.rowOffsets[startRow]
+        const width =
+            table.columnOffsets[endColumn + 1] -
+            table.columnOffsets[startColumn]
+        const height = table.rowOffsets[endRow + 1] - table.rowOffsets[startRow]
+        const normalized = {
+            ...fields,
+            start_row_index: startRow,
+            end_row_index: endRow,
+            start_column_index: startColumn,
+            end_column_index: endColumn,
+            center: { x: x + width / 2, y: y + height / 2 },
+            width,
+            height
+        }
+        for (const key of [
+            'row',
+            'row_index',
+            'rowIndex',
+            'row_span',
+            'rowSpan',
+            'column',
+            'col',
+            'column_index',
+            'columnIndex',
+            'col_span',
+            'column_span',
+            'colSpan'
+        ]) {
+            delete normalized[key]
+        }
+        return normalized
+    }
+
+    /**
+     * Resolves an anchored axis coordinate.
+     * @param {number} coordinate Anchor coordinate.
+     * @param {number} length Axis length.
+     * @param {string} alignment Axis alignment.
+     * @returns {number} Leading coordinate.
+     */
+    static #anchorCoordinate(coordinate, length, alignment) {
+        if (alignment === 'right' || alignment === 'bottom') {
+            return coordinate - length
+        }
+        return alignment === 'center' || alignment === 'middle'
+            ? coordinate - length / 2
+            : coordinate
+    }
+
+    /**
+     * Resolves a bounded inclusive ending index.
+     * @param {unknown} explicit Explicit ending index.
+     * @param {number} start Starting index.
+     * @param {unknown} span Span candidate.
+     * @param {number} length Axis length.
+     * @returns {number} Inclusive ending index.
+     */
+    static #endIndex(explicit, start, span, length) {
+        return Math.min(
+            CircuitJsonSchematicTableNormalizer.#index(explicit) ??
+                start + CircuitJsonSchematicTableNormalizer.#span(span) - 1,
+            length - 1
+        )
+    }
+
+    /**
+     * Normalizes a table dimension array.
+     * @param {unknown} values Dimension candidates.
+     * @returns {number[]} Positive lengths.
+     */
+    static #lengths(values) {
+        return (Array.isArray(values) ? values : [])
+            .map((value) => CircuitJsonUnits.optionalLength(value))
+            .filter((value) => value !== null && value > 0)
+    }
+
+    /**
+     * Builds cumulative table grid offsets.
+     * @param {number[]} values Lengths.
+     * @returns {number[]} Boundary offsets.
+     */
+    static #offsets(values) {
+        const offsets = [0]
+        for (const value of values) {
+            offsets.push(offsets[offsets.length - 1] + value)
+        }
+        return offsets
+    }
+
+    /**
+     * Normalizes a zero-based table index.
+     * @param {unknown} value Index candidate.
+     * @returns {number | null} Normalized index.
+     */
+    static #index(value) {
+        const number = Number(value)
+        return Number.isInteger(number) && number >= 0 ? number : null
+    }
+
+    /**
+     * Normalizes a positive table span.
+     * @param {unknown} value Span candidate.
+     * @returns {number} Normalized span.
+     */
+    static #span(value) {
+        const number = Number(value)
+        return Number.isInteger(number) && number > 0 ? number : 1
+    }
+
+    /**
+     * Copies own data descriptors into a plain record.
+     * @param {Record<string, PropertyDescriptor>} descriptors Descriptors.
+     * @returns {Record<string, any>} Plain fields.
+     */
+    static #fields(descriptors) {
+        return Object.fromEntries(
+            Object.entries(descriptors).map(([key, descriptor]) => [
+                key,
+                descriptor.value
+            ])
+        )
+    }
+
+    /**
+     * Returns whether normalized fields differ from original descriptors.
+     * @param {Record<string, any>} fields Normalized fields.
+     * @param {Record<string, PropertyDescriptor>} descriptors Original fields.
+     * @returns {boolean} Whether fields changed.
+     */
+    static #changed(fields, descriptors) {
+        const keys = Object.keys(fields)
+        return (
+            keys.length !== Object.keys(descriptors).length ||
+            keys.some(
+                (key) =>
+                    !descriptors[key] || fields[key] !== descriptors[key].value
+            )
+        )
+    }
+
+    /**
+     * Reads a safe plain record through data descriptors only.
+     * @param {unknown} value Record candidate.
+     * @returns {Record<string, PropertyDescriptor> | null} Safe descriptors.
+     */
+    static #record(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return null
+        }
+        try {
+            const prototype = Object.getPrototypeOf(value)
+            const descriptors = Object.getOwnPropertyDescriptors(value)
+            if (prototype !== Object.prototype && prototype !== null) {
+                return null
+            }
+            return Object.values(descriptors).some(
+                (descriptor) => !Object.hasOwn(descriptor, 'value')
+            )
+                ? null
+                : descriptors
+        } catch {
+            return null
+        }
+    }
+}
+
+Object.freeze(CircuitJsonSchematicTableNormalizer.prototype)
+Object.freeze(CircuitJsonSchematicTableNormalizer)

package/src/core/context/CircuitJsonValidationAuthority.mjs

@@ -0,0 +1,39 @@
+import { CircuitJsonElementValidator } from '../CircuitJsonElementValidator.mjs'
+
+const PROVEN_MODELS = new WeakSet()
+const validateCircuitJsonModel = CircuitJsonElementValidator.validateModel.bind(
+    CircuitJsonElementValidator
+)
+
+/**
+ * Owns the unforgeable deep-validation authority used by document sealing.
+ */
+export class CircuitJsonValidationAuthority {
+    /**
+     * Validates and freezes one model before granting private sealing authority.
+     * @param {unknown} model CircuitJSON model candidate.
+     * @returns {string[]} Validation errors.
+     */
+    static validateAndFreeze(model) {
+        const errors = validateCircuitJsonModel(model, { freeze: true })
+        if (errors.length === 0) PROVEN_MODELS.add(model)
+        return errors
+    }
+
+    /**
+     * Tests the module-private authority for one exact deeply frozen model.
+     * @param {unknown} model Model candidate.
+     * @returns {boolean} Whether validation granted sealing authority.
+     */
+    static permitsSeal(model) {
+        return Boolean(
+            model &&
+            typeof model === 'object' &&
+            PROVEN_MODELS.has(model) &&
+            Object.isFrozen(model)
+        )
+    }
+}
+
+Object.freeze(CircuitJsonValidationAuthority.prototype)
+Object.freeze(CircuitJsonValidationAuthority)

package/src/core/context/CircuitJsonValidationProof.mjs

@@ -0,0 +1,217 @@
+import { CircuitJsonReadOnlyDocument } from './CircuitJsonReadOnlyDocument.mjs'
+import { CircuitJsonValidationAuthority } from './CircuitJsonValidationAuthority.mjs'
+
+const VALIDATION_PROOF = Symbol('CircuitJsonValidationProof')
+const VALIDATED_INDEX_ACCESS = Symbol('CircuitJsonValidatedIndexAccess')
+const VALIDATION_TOKEN_SECRET = Object.freeze({})
+
+/**
+ * Holds an unforgeable runtime binding to one validated model.
+ */
+class CircuitJsonValidationToken {
+    #model
+
+    /**
+     * Creates a token for one already validated immutable model.
+     * @param {object[]} model Proven CircuitJSON model.
+     * @param {object} secret Module-private construction authority.
+     */
+    constructor(model, secret) {
+        if (secret !== VALIDATION_TOKEN_SECRET) {
+            throw new TypeError('CircuitJSON validation proofs are internal.')
+        }
+        this.#model = model
+        Object.freeze(this)
+    }
+
+    /**
+     * Tests whether a candidate token is bound to the supplied model.
+     * @param {unknown} candidate Token candidate.
+     * @param {unknown} model Model candidate.
+     * @returns {boolean} Whether the private model slot matches.
+     */
+    static matches(candidate, model) {
+        try {
+            return (
+                candidate.#model === model &&
+                Array.isArray(model) &&
+                Object.isFrozen(model)
+            )
+        } catch {
+            return false
+        }
+    }
+}
+
+Object.freeze(CircuitJsonValidationToken.prototype)
+Object.freeze(CircuitJsonValidationToken)
+
+/**
+ * Owns runtime-only proof metadata for immutable CircuitJSON documents.
+ */
+export class CircuitJsonValidationProof {
+    /**
+     * Validates, freezes, and proves one canonical document envelope.
+     * @param {Record<string, any>} document Canonical document envelope.
+     * @returns {Record<string, any>} The same read-only document envelope.
+     */
+    static validateAndAttach(document) {
+        const model = CircuitJsonValidationProof.#requireModelData(document)
+        if (!CircuitJsonValidationProof.#matches(document, model)) {
+            const errors =
+                CircuitJsonValidationAuthority.validateAndFreeze(model)
+            if (errors.length) throw new TypeError(errors[0])
+            if (
+                CircuitJsonValidationProof.#requireModelData(document) !== model
+            ) {
+                throw new TypeError(
+                    'CircuitJSON document model changed during validation.'
+                )
+            }
+            Object.defineProperty(document, VALIDATION_PROOF, {
+                configurable: false,
+                enumerable: false,
+                value: new CircuitJsonValidationToken(
+                    model,
+                    VALIDATION_TOKEN_SECRET
+                ),
+                writable: false
+            })
+        }
+        const readonlyDocument = CircuitJsonReadOnlyDocument.freezeValidated(
+            document,
+            model
+        )
+        if (
+            CircuitJsonValidationProof.#requireModelData(readonlyDocument) !==
+                model ||
+            !CircuitJsonValidationProof.#matches(readonlyDocument, model)
+        ) {
+            throw new TypeError(
+                'CircuitJSON document model changed while sealing its validation proof.'
+            )
+        }
+        return readonlyDocument
+    }
+
+    /**
+     * Returns true when an envelope proof matches its current model reference.
+     * @param {unknown} document Document candidate.
+     * @returns {boolean} Whether the envelope carries a reusable proof.
+     */
+    static has(document) {
+        if (!document || typeof document !== 'object') return false
+        const descriptor = Object.getOwnPropertyDescriptor(document, 'model')
+        if (!descriptor || !Object.hasOwn(descriptor, 'value')) return false
+        const model = descriptor.value
+        return CircuitJsonValidationProof.#matches(document, model)
+    }
+
+    /**
+     * Creates context-owned indexer options branded by a matching proof.
+     * @param {Record<string, any>} document Proven document envelope.
+     * @param {string[] | null} [families] Requested index work families.
+     * @returns {{ validated: true, families: string[] | null }} Trusted indexer options.
+     */
+    static indexOptions(document, families = null) {
+        if (!CircuitJsonValidationProof.has(document)) {
+            throw new TypeError(
+                'Validated index access requires a matching document proof.'
+            )
+        }
+
+        const normalizedFamilies = Array.isArray(families)
+            ? Object.freeze([...new Set(families.map(String))])
+            : null
+        const options = { validated: true, families: normalizedFamilies }
+        Object.defineProperty(options, VALIDATED_INDEX_ACCESS, {
+            enumerable: false,
+            value: CircuitJsonValidationProof.#proof(document)
+        })
+        return Object.freeze(options)
+    }
+
+    /**
+     * Returns true only for an index request branded by a matching proof.
+     * @param {unknown} model CircuitJSON model candidate.
+     * @param {unknown} options Indexer options candidate.
+     * @returns {boolean} Whether public validation may be skipped.
+     */
+    static permitsIndex(model, options) {
+        const proof = options?.[VALIDATED_INDEX_ACCESS]
+        return Boolean(
+            options?.validated === true &&
+            CircuitJsonValidationToken.matches(proof, model)
+        )
+    }
+
+    /**
+     * Returns trusted requested index families or null for the legacy full index.
+     * @param {unknown} model CircuitJSON model candidate.
+     * @param {unknown} options Indexer options candidate.
+     * @returns {string[] | null} Requested families, or null for full work.
+     */
+    static indexFamilies(model, options) {
+        if (!CircuitJsonValidationProof.permitsIndex(model, options)) {
+            return null
+        }
+        return Array.isArray(options.families) ? options.families : null
+    }
+
+    /**
+     * Tests one envelope proof against an already captured model reference.
+     * @param {unknown} document Document candidate.
+     * @param {unknown} model Captured model candidate.
+     * @returns {boolean} Whether the proof is valid for that exact model.
+     */
+    static #matches(document, model) {
+        return CircuitJsonValidationToken.matches(
+            CircuitJsonValidationProof.#proof(document),
+            model
+        )
+    }
+
+    /**
+     * Reads one validation proof through its own data descriptor.
+     * @param {unknown} document Document candidate.
+     * @returns {unknown} Captured proof value.
+     */
+    static #proof(document) {
+        if (!document || typeof document !== 'object') return undefined
+        let descriptor
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(
+                document,
+                VALIDATION_PROOF
+            )
+        } catch {
+            return undefined
+        }
+        return descriptor && Object.hasOwn(descriptor, 'value')
+            ? descriptor.value
+            : undefined
+    }
+
+    /**
+     * Returns an envelope's stable own model data property.
+     * @param {unknown} document Document candidate.
+     * @returns {unknown} Captured model value.
+     */
+    static #requireModelData(document) {
+        if (!document || typeof document !== 'object') {
+            throw new TypeError(
+                'CircuitJSON document model must be an own data property.'
+            )
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(document, 'model')
+        if (!descriptor || !Object.hasOwn(descriptor, 'value')) {
+            throw new TypeError(
+                'CircuitJSON document model must be an own data property.'
+            )
+        }
+        return descriptor.value
+    }
+}
+
+Object.freeze(CircuitJsonValidationProof.prototype)
+Object.freeze(CircuitJsonValidationProof)