@noeos/verification-engine 0.0.0

package/dist/cjs/chains/chain-builder.js

@@ -0,0 +1,541 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainBuilder = exports.ChainLifecycleError = void 0;
+const evidence_js_1 = require("../domain/evidence.js");
+const operation_result_js_1 = require("../domain/operation-result.js");
+const frame_builders_js_1 = require("../framing/frame-builders.js");
+const hash_frame_js_1 = require("../hashing/hash-frame.js");
+const record_service_js_1 = require("../records/record-service.js");
+const rule_set_js_1 = require("../rules/rule-set.js");
+const diagnostic_collector_js_1 = require("../validation/diagnostic-collector.js");
+const algorithm_validation_js_1 = require("../validation/algorithm-validation.js");
+const digest_validation_js_1 = require("../validation/digest-validation.js");
+const identifier_validation_js_1 = require("../validation/identifier-validation.js");
+const object_inspection_js_1 = require("../validation/object-inspection.js");
+const position_validation_js_1 = require("../validation/position-validation.js");
+const duplicate_detector_js_1 = require("./duplicate-detector.js");
+class ChainLifecycleError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "ChainLifecycleError";
+    }
+}
+exports.ChainLifecycleError = ChainLifecycleError;
+class ChainBuilder {
+    config;
+    rules;
+    options;
+    state = "active";
+    nextPosition = 0;
+    previous = Object.freeze({ kind: "none" });
+    firstDigest;
+    finalDigest;
+    diagnostics;
+    count = 0;
+    duplicates;
+    operationActive = false;
+    recordServiceOptions;
+    constructor(config, rules, options) {
+        this.config = config;
+        this.rules = rules;
+        this.options = options;
+        this.diagnostics = new diagnostic_collector_js_1.DiagnosticCollector(options.limits);
+        this.duplicates = (0, duplicate_detector_js_1.createDuplicateDetector)(config.duplicatePolicy, options.limits);
+        this.recordServiceOptions = Object.freeze({
+            limits: options.limits,
+            profiles: options.profiles,
+            rules,
+        });
+    }
+    static create(input, options) {
+        const config = validateChainConfig(input, options.limits);
+        if (!config.ok)
+            return config;
+        const rules = rule_set_js_1.RuleSet.create(config.value.rules, options.limits);
+        if (!rules.ok)
+            return rules;
+        return (0, operation_result_js_1.success)(new ChainBuilder(config.value, rules.value, options));
+    }
+    append(input) {
+        if (this.operationActive)
+            return (0, operation_result_js_1.failure)([createInternalDiagnostic("CONCURRENT_USE_FORBIDDEN")]);
+        return this.appendCore(input);
+    }
+    appendCore(input) {
+        this.requireActive();
+        const chainInput = validateChainRecordInput(input, this.config.algorithm, this.options.limits);
+        if (!chainInput.ok)
+            return chainInput;
+        const collector = new diagnostic_collector_js_1.DiagnosticCollector(this.options.limits);
+        if (chainInput.value.position !== this.nextPosition) {
+            collector.addCode("POSITION_MISMATCH", "link", { position: chainInput.value.position });
+        }
+        if (!samePrevious(chainInput.value.previous, this.previous, this.config.algorithm)) {
+            collector.addCode("PREVIOUS_LINK_MISMATCH", "link", { position: chainInput.value.position });
+        }
+        if (collector.hasErrors())
+            return (0, operation_result_js_1.failure)(collector.finish());
+        const record = (0, record_service_js_1.computeRecord)({
+            contextId: this.config.contextId,
+            recordId: chainInput.value.recordId,
+            payload: chainInput.value.payload,
+            profile: this.config.profile,
+            algorithm: this.config.algorithm,
+        }, this.recordServiceOptions);
+        if (!record.ok)
+            return record;
+        addAll(collector, record.diagnostics);
+        const previousDigest = chainInput.value.previous.kind === "digest"
+            ? (0, digest_validation_js_1.validateDigest)(chainInput.value.previous.value, this.config.algorithm)
+            : undefined;
+        if (previousDigest !== undefined && !previousDigest.ok)
+            return previousDigest;
+        const linkDigest = (0, hash_frame_js_1.hashTrustedFrame)(this.config.algorithm, (0, frame_builders_js_1.buildTrustedLinkFrame)({
+            algorithm: this.config.algorithm,
+            contextId: this.config.contextId,
+            sequenceId: this.config.sequenceId,
+            position: chainInput.value.position,
+            recordId: chainInput.value.recordId,
+            recordDigest: record.value.recordDigest,
+            ...(previousDigest === undefined ? {} : { previousLinkDigest: previousDigest.value }),
+        }, this.options.limits));
+        if (!linkDigest.ok)
+            return linkDigest;
+        const evidence = freezeLinkEvidence({
+            ...record.value.evidence,
+            $schema: evidence_js_1.LINK_EVIDENCE_SCHEMA,
+            sequenceId: this.config.sequenceId,
+            position: chainInput.value.position,
+            previous: chainInput.value.previous,
+            linkDigest: linkDigest.value.toHex(),
+        });
+        if (this.rules.hasRules()) {
+            addAll(collector, this.rules.evaluate(Object.freeze({
+                phase: "link",
+                link: evidence,
+                recordId: evidence.recordId,
+                position: evidence.position,
+            }), this.options.limits));
+        }
+        if (collector.hasErrors())
+            return (0, operation_result_js_1.failure)(collector.finish());
+        const observed = (0, duplicate_detector_js_1.observedLink)(evidence);
+        const duplicate = this.duplicates.inspect(observed);
+        if (!duplicate.ok) {
+            this.state = "failed";
+            return duplicate;
+        }
+        addAll(collector, duplicate.value);
+        if (collector.hasErrors())
+            return (0, operation_result_js_1.failure)(collector.finish());
+        try {
+            this.duplicates.commit(observed);
+            this.commit(evidence);
+        }
+        catch {
+            this.state = "failed";
+            return (0, operation_result_js_1.failure)([createInternalDiagnostic()]);
+        }
+        addAll(this.diagnostics, collector.finish());
+        return (0, operation_result_js_1.success)(evidence, collector.finish());
+    }
+    appendAll(input) {
+        if (this.operationActive)
+            return (0, operation_result_js_1.failure)([createInternalDiagnostic("CONCURRENT_USE_FORBIDDEN")]);
+        this.requireActive();
+        try {
+            for (const item of input) {
+                const result = this.append(item);
+                if (!result.ok)
+                    return result;
+            }
+        }
+        catch {
+            this.state = "failed";
+            return (0, operation_result_js_1.failure)([createStreamDiagnostic("INPUT_STREAM_FAILED")]);
+        }
+        return this.finalize();
+    }
+    async appendStream(input, options = {}) {
+        if (this.operationActive)
+            return (0, operation_result_js_1.failure)([createInternalDiagnostic("CONCURRENT_USE_FORBIDDEN")]);
+        this.requireActive();
+        this.operationActive = true;
+        let iterator;
+        let terminal = false;
+        let closeIterator = false;
+        try {
+            if (isAborted(options.signal)) {
+                this.state = "aborted";
+                terminal = true;
+                return (0, operation_result_js_1.failure)([createStreamDiagnostic("OPERATION_ABORTED")]);
+            }
+            try {
+                iterator = input[Symbol.asyncIterator]();
+            }
+            catch {
+                this.state = "failed";
+                terminal = true;
+                return (0, operation_result_js_1.failure)([createStreamDiagnostic("INPUT_STREAM_FAILED")]);
+            }
+            for (;;) {
+                if (isAborted(options.signal)) {
+                    this.state = "aborted";
+                    terminal = true;
+                    closeIterator = true;
+                    return (0, operation_result_js_1.failure)([createStreamDiagnostic("OPERATION_ABORTED")]);
+                }
+                let next;
+                try {
+                    next = await iterator.next();
+                }
+                catch {
+                    this.state = "failed";
+                    terminal = true;
+                    closeIterator = true;
+                    return (0, operation_result_js_1.failure)([createStreamDiagnostic("INPUT_STREAM_FAILED")]);
+                }
+                if (next.done === true) {
+                    if (isAborted(options.signal)) {
+                        this.state = "aborted";
+                        terminal = true;
+                        closeIterator = true;
+                        return (0, operation_result_js_1.failure)([createStreamDiagnostic("OPERATION_ABORTED")]);
+                    }
+                    const finalized = this.finalize();
+                    terminal = true;
+                    return finalized;
+                }
+                const appended = this.appendCore(next.value);
+                if (!appended.ok) {
+                    this.state = "failed";
+                    terminal = true;
+                    closeIterator = true;
+                    return appended;
+                }
+                if (isAborted(options.signal)) {
+                    this.state = "aborted";
+                    terminal = true;
+                    closeIterator = true;
+                    return (0, operation_result_js_1.failure)([createStreamDiagnostic("OPERATION_ABORTED")]);
+                }
+                if (options.onEvidence !== undefined) {
+                    try {
+                        await options.onEvidence(appended.value);
+                    }
+                    catch {
+                        this.state = "failed";
+                        terminal = true;
+                        closeIterator = true;
+                        return (0, operation_result_js_1.failure)([createStreamDiagnostic("OUTPUT_SINK_FAILED")]);
+                    }
+                }
+            }
+        }
+        finally {
+            if (iterator !== undefined && (closeIterator || !terminal)) {
+                try {
+                    await iterator.return?.();
+                }
+                catch {
+                    this.state = "failed";
+                }
+            }
+            this.operationActive = false;
+        }
+    }
+    snapshot() {
+        this.requireReadable();
+        return Object.freeze({
+            contextId: this.config.contextId,
+            sequenceId: this.config.sequenceId,
+            profile: Object.freeze({ ...this.config.profile }),
+            algorithm: this.config.algorithm,
+            nextPosition: this.nextPosition,
+            previous: freezePrevious(this.previous),
+            count: this.count,
+        });
+    }
+    finalize() {
+        this.requireActive();
+        if (this.count === 0 && !this.config.allowEmpty) {
+            return (0, operation_result_js_1.failure)([{ ...createInternalDiagnostic("EMPTY_CHAIN_FORBIDDEN"), phase: "chain" }]);
+        }
+        const collector = new diagnostic_collector_js_1.DiagnosticCollector(this.options.limits);
+        if (this.rules.hasRules()) {
+            addAll(collector, this.rules.evaluate(Object.freeze({ phase: "chain", chain: this.snapshot() }), this.options.limits));
+        }
+        if (collector.hasErrors())
+            return (0, operation_result_js_1.failure)(collector.finish());
+        addAll(this.diagnostics, collector.finish());
+        const evidence = this.summary("valid", "verified", "verified");
+        this.state = "finalized";
+        return (0, operation_result_js_1.success)(evidence, this.diagnostics.finish());
+    }
+    abort(reason) {
+        void reason;
+        if (this.state === "active")
+            this.state = "aborted";
+    }
+    commit(evidence) {
+        if (this.count === 0)
+            this.firstDigest = evidence.linkDigest;
+        this.finalDigest = evidence.linkDigest;
+        this.previous = Object.freeze({ kind: "digest", value: evidence.linkDigest });
+        this.nextPosition += 1;
+        this.count += 1;
+    }
+    summary(status, start, end) {
+        const diagnostics = this.diagnostics.finish();
+        const summary = diagnosticSummary(diagnostics);
+        const base = {
+            $schema: evidence_js_1.CHAIN_SUMMARY_EVIDENCE_SCHEMA,
+            protocolVersion: 1,
+            contextId: this.config.contextId,
+            sequenceId: this.config.sequenceId,
+            profile: Object.freeze({ ...this.config.profile }),
+            algorithm: this.config.algorithm,
+            count: this.count,
+            boundaries: Object.freeze({ start, end }),
+            status,
+            diagnostics: summary,
+        };
+        if (this.count === 0)
+            return Object.freeze(base);
+        if (this.firstDigest === undefined || this.finalDigest === undefined) {
+            throw new Error("chain summary invariant broken");
+        }
+        return Object.freeze({
+            ...base,
+            firstPosition: 0,
+            lastPosition: this.count - 1,
+            firstLinkDigest: this.firstDigest,
+            finalLinkDigest: this.finalDigest,
+        });
+    }
+    requireActive() {
+        if (this.state === "finalized")
+            throw new ChainLifecycleError("BUILDER_FINALIZED");
+        if (this.state === "failed" || this.state === "aborted")
+            throw new ChainLifecycleError("BUILDER_FAILED");
+    }
+    requireReadable() {
+        if (this.state === "failed" || this.state === "aborted")
+            throw new ChainLifecycleError("BUILDER_FAILED");
+    }
+}
+exports.ChainBuilder = ChainBuilder;
+function validateChainConfig(value, limits) {
+    const entries = (0, object_inspection_js_1.inspectPlainObject)(value);
+    if (entries === undefined)
+        return invalidConfig(limits);
+    const fields = new Map(entries);
+    for (const key of fields.keys()) {
+        if (![
+            "contextId",
+            "sequenceId",
+            "profile",
+            "algorithm",
+            "duplicatePolicy",
+            "rules",
+            "allowEmpty",
+        ].includes(key))
+            return invalidConfig(limits);
+    }
+    if (!fields.has("contextId") ||
+        !fields.has("sequenceId") ||
+        !fields.has("profile") ||
+        !fields.has("algorithm")) {
+        return invalidConfig(limits);
+    }
+    const contextId = (0, identifier_validation_js_1.validateContextId)(fields.get("contextId"));
+    const sequenceId = (0, identifier_validation_js_1.validateSequenceId)(fields.get("sequenceId"));
+    const profile = (0, record_service_js_1.validateProfile)(fields.get("profile"), limits);
+    const algorithm = (0, algorithm_validation_js_1.validateAlgorithmId)(fields.get("algorithm"));
+    const duplicates = validateDuplicatePolicy(fields.get("duplicatePolicy"), limits);
+    const allowEmpty = fields.get("allowEmpty") ?? false;
+    if (!contextId.ok)
+        return contextId;
+    if (!sequenceId.ok)
+        return sequenceId;
+    if (!profile.ok)
+        return profile;
+    if (!algorithm.ok)
+        return algorithm;
+    if (!duplicates.ok || typeof allowEmpty !== "boolean")
+        return invalidConfig(limits);
+    return (0, operation_result_js_1.success)(Object.freeze({
+        contextId: contextId.value.value,
+        sequenceId: sequenceId.value.value,
+        profile: profile.value,
+        algorithm: algorithm.value,
+        duplicatePolicy: duplicates.value,
+        rules: fields.get("rules"),
+        allowEmpty,
+    }));
+}
+function validateDuplicatePolicy(value, limits) {
+    if (value === undefined)
+        return (0, operation_result_js_1.success)(Object.freeze({ kind: "none" }));
+    const entries = (0, object_inspection_js_1.inspectPlainObject)(value);
+    if (entries === undefined)
+        return invalidConfig(limits);
+    const fields = new Map(entries);
+    const kind = fields.get("kind");
+    if (kind === "none" && fields.size === 1)
+        return (0, operation_result_js_1.success)(Object.freeze({ kind }));
+    if (kind === "window" && fields.size === 2 && typeof fields.get("size") === "number") {
+        const size = fields.get("size");
+        if (typeof size !== "number" ||
+            !Number.isSafeInteger(size) ||
+            size < 1 ||
+            size > limits.maxFullRecords)
+            return invalidConfig(limits);
+        return (0, operation_result_js_1.success)(Object.freeze({ kind, size }));
+    }
+    if (kind === "full" && fields.size === 2 && typeof fields.get("maxRecords") === "number") {
+        const maxRecords = fields.get("maxRecords");
+        if (typeof maxRecords !== "number" ||
+            !Number.isSafeInteger(maxRecords) ||
+            maxRecords < 1 ||
+            maxRecords > limits.maxFullRecords)
+            return invalidConfig(limits);
+        return (0, operation_result_js_1.success)(Object.freeze({ kind, maxRecords }));
+    }
+    if (kind === "external" && fields.size === 2 && fields.has("index")) {
+        const index = fields.get("index");
+        const indexEntries = (0, object_inspection_js_1.inspectPlainObject)(index);
+        if (indexEntries === undefined) {
+            return invalidConfig(limits);
+        }
+        const indexFields = new Map(indexEntries);
+        const observe = indexFields.get("observe");
+        if (indexFields.size !== 1 || typeof observe !== "function")
+            return invalidConfig(limits);
+        return (0, operation_result_js_1.success)(Object.freeze({
+            kind,
+            index: Object.freeze({
+                observe(batch) {
+                    return Reflect.apply(observe, undefined, [batch]);
+                },
+            }),
+        }));
+    }
+    return invalidConfig(limits);
+}
+function validateChainRecordInput(value, algorithm, limits) {
+    const entries = (0, object_inspection_js_1.inspectPlainObject)(value);
+    if (entries === undefined)
+        return invalidConfig(limits);
+    const fields = new Map(entries);
+    if (fields.size !== 4 ||
+        !fields.has("recordId") ||
+        !fields.has("payload") ||
+        !fields.has("position") ||
+        !fields.has("previous")) {
+        return invalidConfig(limits);
+    }
+    const recordId = (0, identifier_validation_js_1.validateRecordId)(fields.get("recordId"));
+    const position = (0, position_validation_js_1.validatePosition)(fields.get("position"));
+    const previous = validatePrevious(fields.get("previous"), algorithm, limits);
+    if (!recordId.ok)
+        return recordId;
+    if (!position.ok)
+        return position;
+    if (!previous.ok)
+        return previous;
+    return (0, operation_result_js_1.success)(Object.freeze({
+        recordId: recordId.value.value,
+        payload: fields.get("payload"),
+        position: position.value.value,
+        previous: previous.value,
+    }));
+}
+function validatePrevious(value, algorithm, limits) {
+    const entries = (0, object_inspection_js_1.inspectPlainObject)(value);
+    if (entries === undefined)
+        return invalidConfig(limits);
+    const fields = new Map(entries);
+    if (fields.get("kind") === "none" && fields.size === 1)
+        return (0, operation_result_js_1.success)(Object.freeze({ kind: "none" }));
+    if (fields.get("kind") === "digest" && fields.size === 2 && fields.has("value")) {
+        const digest = (0, digest_validation_js_1.validateDigest)(fields.get("value"), algorithm);
+        if (!digest.ok)
+            return digest;
+        return (0, operation_result_js_1.success)(Object.freeze({ kind: "digest", value: digest.value.toHex() }));
+    }
+    return invalidConfig(limits);
+}
+function samePrevious(left, right, algorithm) {
+    if (left.kind !== right.kind)
+        return false;
+    if (left.kind === "none" || right.kind === "none")
+        return true;
+    const expected = (0, digest_validation_js_1.validateDigest)(left.value, algorithm);
+    const actual = (0, digest_validation_js_1.validateDigest)(right.value, algorithm);
+    return expected.ok && actual.ok && (0, digest_validation_js_1.equalDigest)(expected.value, actual.value);
+}
+function freezePrevious(value) {
+    return value.kind === "none"
+        ? Object.freeze({ kind: "none" })
+        : Object.freeze({ kind: "digest", value: value.value });
+}
+function freezeLinkEvidence(value) {
+    return Object.freeze({
+        ...value,
+        profile: Object.freeze({ ...value.profile }),
+        previous: freezePrevious(value.previous),
+    });
+}
+function diagnosticSummary(diagnostics) {
+    let errors = 0;
+    let warnings = 0;
+    let info = 0;
+    for (const diagnostic of diagnostics) {
+        if (diagnostic.severity === "error")
+            errors += 1;
+        else if (diagnostic.severity === "warning")
+            warnings += 1;
+        else
+            info += 1;
+    }
+    return Object.freeze({
+        errors,
+        warnings,
+        info,
+        truncated: diagnostics.some(({ code }) => code === "DIAGNOSTIC_LIMIT_REACHED"),
+    });
+}
+function addAll(collector, diagnostics) {
+    for (const diagnostic of diagnostics)
+        collector.add(diagnostic);
+}
+function invalidConfig(limits) {
+    const collector = new diagnostic_collector_js_1.DiagnosticCollector(limits);
+    collector.addCode("INPUT_TYPE_INVALID", "input");
+    return (0, operation_result_js_1.failure)(collector.finish());
+}
+function createInternalDiagnostic(code = "INTERNAL_INVARIANT_BROKEN") {
+    return Object.freeze({
+        $schema: "urn:noeos:verification-engine:diagnostic:1",
+        code,
+        severity: "error",
+        phase: "chain",
+        messageKey: code.toLowerCase().replaceAll("_", "."),
+    });
+}
+function createStreamDiagnostic(code) {
+    return Object.freeze({
+        $schema: "urn:noeos:verification-engine:diagnostic:1",
+        code,
+        severity: code === "OPERATION_ABORTED" ? "info" : "error",
+        phase: "output",
+        messageKey: code.toLowerCase().replaceAll("_", "."),
+    });
+}
+function isAborted(signal) {
+    return signal?.aborted === true;
+}