@noeos/verification-engine 0.0.0

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

@@ -0,0 +1,536 @@
+// SPDX-License-Identifier: Apache-2.0
+import { CHAIN_SUMMARY_EVIDENCE_SCHEMA, LINK_EVIDENCE_SCHEMA } from "../domain/evidence.js";
+import { failure, success } from "../domain/operation-result.js";
+import { buildTrustedLinkFrame } from "../framing/frame-builders.js";
+import { hashTrustedFrame } from "../hashing/hash-frame.js";
+import { computeRecord, validateProfile, } from "../records/record-service.js";
+import { RuleSet } from "../rules/rule-set.js";
+import { DiagnosticCollector } from "../validation/diagnostic-collector.js";
+import { validateAlgorithmId } from "../validation/algorithm-validation.js";
+import { equalDigest, validateDigest } from "../validation/digest-validation.js";
+import { validateContextId, validateRecordId, validateSequenceId, } from "../validation/identifier-validation.js";
+import { inspectPlainObject } from "../validation/object-inspection.js";
+import { validatePosition } from "../validation/position-validation.js";
+import { createDuplicateDetector, observedLink } from "./duplicate-detector.js";
+export class ChainLifecycleError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "ChainLifecycleError";
+    }
+}
+export 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 DiagnosticCollector(options.limits);
+        this.duplicates = 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 = RuleSet.create(config.value.rules, options.limits);
+        if (!rules.ok)
+            return rules;
+        return success(new ChainBuilder(config.value, rules.value, options));
+    }
+    append(input) {
+        if (this.operationActive)
+            return 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 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 failure(collector.finish());
+        const record = 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"
+            ? validateDigest(chainInput.value.previous.value, this.config.algorithm)
+            : undefined;
+        if (previousDigest !== undefined && !previousDigest.ok)
+            return previousDigest;
+        const linkDigest = hashTrustedFrame(this.config.algorithm, 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: 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 failure(collector.finish());
+        const observed = observedLink(evidence);
+        const duplicate = this.duplicates.inspect(observed);
+        if (!duplicate.ok) {
+            this.state = "failed";
+            return duplicate;
+        }
+        addAll(collector, duplicate.value);
+        if (collector.hasErrors())
+            return failure(collector.finish());
+        try {
+            this.duplicates.commit(observed);
+            this.commit(evidence);
+        }
+        catch {
+            this.state = "failed";
+            return failure([createInternalDiagnostic()]);
+        }
+        addAll(this.diagnostics, collector.finish());
+        return success(evidence, collector.finish());
+    }
+    appendAll(input) {
+        if (this.operationActive)
+            return 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 failure([createStreamDiagnostic("INPUT_STREAM_FAILED")]);
+        }
+        return this.finalize();
+    }
+    async appendStream(input, options = {}) {
+        if (this.operationActive)
+            return 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 failure([createStreamDiagnostic("OPERATION_ABORTED")]);
+            }
+            try {
+                iterator = input[Symbol.asyncIterator]();
+            }
+            catch {
+                this.state = "failed";
+                terminal = true;
+                return failure([createStreamDiagnostic("INPUT_STREAM_FAILED")]);
+            }
+            for (;;) {
+                if (isAborted(options.signal)) {
+                    this.state = "aborted";
+                    terminal = true;
+                    closeIterator = true;
+                    return failure([createStreamDiagnostic("OPERATION_ABORTED")]);
+                }
+                let next;
+                try {
+                    next = await iterator.next();
+                }
+                catch {
+                    this.state = "failed";
+                    terminal = true;
+                    closeIterator = true;
+                    return failure([createStreamDiagnostic("INPUT_STREAM_FAILED")]);
+                }
+                if (next.done === true) {
+                    if (isAborted(options.signal)) {
+                        this.state = "aborted";
+                        terminal = true;
+                        closeIterator = true;
+                        return 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 failure([createStreamDiagnostic("OPERATION_ABORTED")]);
+                }
+                if (options.onEvidence !== undefined) {
+                    try {
+                        await options.onEvidence(appended.value);
+                    }
+                    catch {
+                        this.state = "failed";
+                        terminal = true;
+                        closeIterator = true;
+                        return 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 failure([{ ...createInternalDiagnostic("EMPTY_CHAIN_FORBIDDEN"), phase: "chain" }]);
+        }
+        const collector = new 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 failure(collector.finish());
+        addAll(this.diagnostics, collector.finish());
+        const evidence = this.summary("valid", "verified", "verified");
+        this.state = "finalized";
+        return 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: 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");
+    }
+}
+function validateChainConfig(value, limits) {
+    const entries = 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 = validateContextId(fields.get("contextId"));
+    const sequenceId = validateSequenceId(fields.get("sequenceId"));
+    const profile = validateProfile(fields.get("profile"), limits);
+    const algorithm = 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 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 success(Object.freeze({ kind: "none" }));
+    const entries = 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 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 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 success(Object.freeze({ kind, maxRecords }));
+    }
+    if (kind === "external" && fields.size === 2 && fields.has("index")) {
+        const index = fields.get("index");
+        const indexEntries = 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 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 = 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 = validateRecordId(fields.get("recordId"));
+    const position = 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 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 = inspectPlainObject(value);
+    if (entries === undefined)
+        return invalidConfig(limits);
+    const fields = new Map(entries);
+    if (fields.get("kind") === "none" && fields.size === 1)
+        return success(Object.freeze({ kind: "none" }));
+    if (fields.get("kind") === "digest" && fields.size === 2 && fields.has("value")) {
+        const digest = validateDigest(fields.get("value"), algorithm);
+        if (!digest.ok)
+            return digest;
+        return 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 = validateDigest(left.value, algorithm);
+    const actual = validateDigest(right.value, algorithm);
+    return expected.ok && actual.ok && 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 DiagnosticCollector(limits);
+    collector.addCode("INPUT_TYPE_INVALID", "input");
+    return 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;
+}