@world-engines/ladybug-bridge 0.1.0-alpha.0

package/dist/view-access-policy.js

@@ -0,0 +1,835 @@
+export const VIEW_ACCESS_POLICY_SCHEMA_VERSION = 2;
+export const VIEW_ACCESS_POLICY_ROOT_SUBJECT_ID = "view_policy_root_v2";
+const MAX_IDENTIFIER_BYTES = 512;
+const MAX_PATH_SEGMENTS = 64;
+const MAX_POLICY_SUBJECTS = 1_000_000;
+const SHA256_LENGTH = 32;
+const encoder = new TextEncoder();
+export const VIEW_ACCESS_POLICY_DENY_ROOT = Object.freeze({
+    id: VIEW_ACCESS_POLICY_ROOT_SUBJECT_ID,
+    kind: "root",
+    address: Object.freeze({ kind: "root" }),
+    structuralParentId: null,
+    mode: "deny",
+});
+export function derivedGraphViewAccessPolicy(snapshot) {
+    validateViewAccessPolicy(snapshot);
+    return Object.freeze({
+        schemaVersion: 3,
+        derivation: "graph-v5",
+        policySha256: Object.freeze([...snapshot.policySha256]),
+    });
+}
+const VIEW_ACCESS_MODES = new Set([
+    "inherit",
+    "deny",
+    "read",
+    "read_write",
+]);
+const EFFECTIVE_VIEW_ACCESS_MODES = new Set([
+    "deny",
+    "read",
+    "read_write",
+]);
+const SUBJECT_KINDS = new Set([
+    "root",
+    "node",
+    "attr",
+    "edge",
+]);
+function fail(code) {
+    throw new Error(`view_access_policy.${code}`);
+}
+function assertExactKeys(value, expected, field) {
+    const actual = Object.keys(value).sort();
+    const canonicalExpected = [...expected].sort();
+    if (actual.length !== canonicalExpected.length
+        || actual.some((key, index) => key !== canonicalExpected[index])) {
+        fail(`${field}_shape_invalid`);
+    }
+}
+function assertIdentifier(value, field) {
+    if (typeof value !== "string"
+        || value.length === 0
+        || value.includes("\0")
+        || encoder.encode(value).byteLength > MAX_IDENTIFIER_BYTES) {
+        fail(`${field}_invalid`);
+    }
+}
+function assertMode(value, field) {
+    if (typeof value !== "string" || !VIEW_ACCESS_MODES.has(value)) {
+        fail(`${field}_invalid`);
+    }
+}
+function assertEffectiveMode(value, field) {
+    if (typeof value !== "string"
+        || !EFFECTIVE_VIEW_ACCESS_MODES.has(value)) {
+        fail(`${field}_invalid`);
+    }
+}
+function assertLeafPath(value, field) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_PATH_SEGMENTS) {
+        fail(`${field}_invalid`);
+    }
+    for (const segment of value)
+        assertIdentifier(segment, `${field}_segment`);
+}
+function assertAttributeOwner(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(`${field}_invalid`);
+    }
+    const owner = value;
+    if (owner.kind === "node") {
+        assertExactKeys(value, ["kind", "nodeId"], field);
+        assertIdentifier(owner.nodeId, `${field}_node_id`);
+        return;
+    }
+    if (owner.kind === "edge") {
+        assertExactKeys(value, ["kind", "sourceNodeId", "destinationNodeId", "relationKind"], field);
+        assertIdentifier(owner.sourceNodeId, `${field}_source_node_id`);
+        assertIdentifier(owner.destinationNodeId, `${field}_destination_node_id`);
+        assertIdentifier(owner.relationKind, `${field}_relation_kind`);
+        return;
+    }
+    fail(`${field}_kind_invalid`);
+}
+function assertPolicyAddress(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(`${field}_invalid`);
+    }
+    const address = value;
+    switch (address.kind) {
+        case "root":
+            assertExactKeys(value, ["kind"], field);
+            return;
+        case "node":
+            assertExactKeys(value, ["kind", "nodeId"], field);
+            assertIdentifier(address.nodeId, `${field}_node_id`);
+            return;
+        case "attr":
+            assertExactKeys(value, ["kind", "owner", "path"], field);
+            assertAttributeOwner(address.owner, `${field}_owner`);
+            assertLeafPath(address.path, `${field}_path`);
+            return;
+        case "edge":
+            assertExactKeys(value, ["kind", "sourceNodeId", "destinationNodeId", "relationKind"], field);
+            assertIdentifier(address.sourceNodeId, `${field}_source_node_id`);
+            assertIdentifier(address.destinationNodeId, `${field}_destination_node_id`);
+            assertIdentifier(address.relationKind, `${field}_relation_kind`);
+            return;
+        default:
+            fail(`${field}_kind_invalid`);
+    }
+}
+function assertPolicyTarget(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(`${field}_invalid`);
+    }
+    const target = value;
+    if (value.kind === "root")
+        fail(`${field}_root_forbidden`);
+    if (target.kind === "vector") {
+        assertExactKeys(value, ["kind", "nodeId", "vectorSpace"], field);
+        assertIdentifier(target.nodeId, `${field}_node_id`);
+        assertIdentifier(target.vectorSpace, `${field}_vector_space`);
+        return;
+    }
+    assertPolicyAddress(value, field);
+}
+function assertTarget(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(`${field}_invalid`);
+    }
+    const target = value;
+    switch (target.kind) {
+        case "node":
+            assertIdentifier(target.nodeId, `${field}_node_id`);
+            return;
+        case "attribute":
+            if (target.ownerKind !== "node" && target.ownerKind !== "edge") {
+                fail(`${field}_owner_kind_invalid`);
+            }
+            assertIdentifier(target.ownerId, `${field}_owner_id`);
+            assertLeafPath(target.path, `${field}_path`);
+            return;
+        case "edge":
+            assertIdentifier(target.edgeId, `${field}_edge_id`);
+            assertIdentifier(target.sourceNodeId, `${field}_source_node_id`);
+            assertIdentifier(target.destinationNodeId, `${field}_destination_node_id`);
+            return;
+        case "vector":
+            assertIdentifier(target.nodeId, `${field}_node_id`);
+            assertIdentifier(target.vectorSpace, `${field}_vector_space`);
+            return;
+        default:
+            fail(`${field}_kind_invalid`);
+    }
+}
+function assertSubject(value, index) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        fail(`subjects_${index}_invalid`);
+    }
+    const subject = value;
+    assertExactKeys(value, ["id", "kind", "address", "structuralParentId", "mode"], `subjects_${index}`);
+    assertIdentifier(subject.id, `subjects_${index}_id`);
+    if (typeof subject.kind !== "string" || !SUBJECT_KINDS.has(subject.kind)) {
+        fail(`subjects_${index}_kind_invalid`);
+    }
+    assertPolicyAddress(subject.address, `subjects_${index}_address`);
+    if (subject.kind !== subject.address.kind)
+        fail(`subjects_${index}_kind_address_mismatch`);
+    if (subject.id !== deriveViewAccessPolicySubjectId(subject.address)) {
+        fail(`subjects_${index}_id_address_mismatch`);
+    }
+    if (subject.structuralParentId !== null) {
+        assertIdentifier(subject.structuralParentId, `subjects_${index}_structural_parent_id`);
+    }
+    assertMode(subject.mode, `subjects_${index}_mode`);
+}
+function indexAndValidateSubjects(subjects, requireCanonicalOrder) {
+    if (!Array.isArray(subjects))
+        fail("subjects_invalid");
+    if (subjects.length > MAX_POLICY_SUBJECTS)
+        fail("subject_count_exceeded");
+    const byId = new Map();
+    let rootCount = 0;
+    let previousId = null;
+    for (let index = 0; index < subjects.length; index += 1) {
+        const subject = subjects[index];
+        assertSubject(subject, index);
+        if (byId.has(subject.id))
+            fail("subject_id_duplicate");
+        // assertSubject 已把非 root id 收敛为 `view_subject_<sha256 hex>`；两种合法 id 都是 ASCII，
+        // 因此代码单元序与 UTF-8 字节序相同。这里不要推广到任意 Unicode address。
+        if (requireCanonicalOrder && previousId !== null && previousId >= subject.id) {
+            fail("subjects_not_sorted_unique");
+        }
+        previousId = subject.id;
+        if (subject.kind === "root") {
+            rootCount += 1;
+            if (subject.id !== VIEW_ACCESS_POLICY_ROOT_SUBJECT_ID
+                || subject.address.kind !== "root"
+                || subject.structuralParentId !== null
+                || subject.mode !== "deny") {
+                fail("root_not_fixed_deny");
+            }
+        }
+        else if (subject.structuralParentId === null) {
+            fail("non_root_structural_parent_missing");
+        }
+        byId.set(subject.id, subject);
+    }
+    if (rootCount !== 1)
+        fail("root_count_invalid");
+    for (const subject of byId.values()) {
+        if (subject.kind === "root")
+            continue;
+        if (subject.structuralParentId === null)
+            fail("non_root_structural_parent_missing");
+        const parent = byId.get(subject.structuralParentId);
+        if (parent === undefined)
+            fail("structural_parent_missing");
+        switch (subject.address.kind) {
+            case "node":
+                if (parent.kind !== "root" && parent.kind !== "node") {
+                    fail("node_structural_parent_kind_invalid");
+                }
+                break;
+            case "edge":
+                if (parent.id !== VIEW_ACCESS_POLICY_ROOT_SUBJECT_ID) {
+                    fail("edge_structural_parent_invalid");
+                }
+                if (!byId.has(deriveViewAccessPolicySubjectId({
+                    kind: "node",
+                    nodeId: subject.address.sourceNodeId,
+                }))
+                    || !byId.has(deriveViewAccessPolicySubjectId({
+                        kind: "node",
+                        nodeId: subject.address.destinationNodeId,
+                    }))) {
+                    fail("edge_endpoint_subject_missing");
+                }
+                break;
+            case "attr": {
+                const ownerAddress = subject.address.owner.kind === "node"
+                    ? { kind: "node", nodeId: subject.address.owner.nodeId }
+                    : {
+                        kind: "edge",
+                        sourceNodeId: subject.address.owner.sourceNodeId,
+                        destinationNodeId: subject.address.owner.destinationNodeId,
+                        relationKind: subject.address.owner.relationKind,
+                    };
+                const ownerSubjectId = deriveViewAccessPolicySubjectId(ownerAddress);
+                const ownerSubject = byId.get(ownerSubjectId);
+                if (ownerSubject === undefined)
+                    fail("attribute_owner_subject_missing");
+                if (parent.id === ownerSubjectId)
+                    break;
+                if (parent.address.kind !== "attr")
+                    fail("attribute_structural_parent_invalid");
+                const parentOwnerAddress = parent.address.owner.kind === "node"
+                    ? { kind: "node", nodeId: parent.address.owner.nodeId }
+                    : {
+                        kind: "edge",
+                        sourceNodeId: parent.address.owner.sourceNodeId,
+                        destinationNodeId: parent.address.owner.destinationNodeId,
+                        relationKind: parent.address.owner.relationKind,
+                    };
+                if (deriveViewAccessPolicySubjectId(parentOwnerAddress) !== ownerSubjectId) {
+                    fail("attribute_structural_parent_owner_mismatch");
+                }
+                const childPath = subject.address.path;
+                if (parent.address.path.length >= childPath.length
+                    || !parent.address.path.every((segment, index) => segment === childPath[index])) {
+                    fail("attribute_structural_parent_path_invalid");
+                }
+                break;
+            }
+            case "root":
+                fail("root_structural_parent_forbidden");
+        }
+    }
+    const fullyVisited = new Set();
+    for (const subject of byId.values()) {
+        if (fullyVisited.has(subject.id))
+            continue;
+        const currentChain = new Set();
+        let current = subject;
+        while (current !== undefined && !fullyVisited.has(current.id)) {
+            if (currentChain.has(current.id))
+                fail("structural_parent_cycle");
+            currentChain.add(current.id);
+            if (current.structuralParentId === null) {
+                if (current.id !== VIEW_ACCESS_POLICY_ROOT_SUBJECT_ID)
+                    fail("chain_not_rooted");
+                current = undefined;
+            }
+            else {
+                current = byId.get(current.structuralParentId);
+            }
+        }
+        for (const id of currentChain)
+            fullyVisited.add(id);
+    }
+    return byId;
+}
+const CANONICAL_WRITER_CHUNK_BYTES = 16 * 1024;
+const CANONICAL_ADDRESS_CHUNK_BYTES = 256;
+class CanonicalWriter {
+    #chunks;
+    #emit;
+    #buffer;
+    #used = 0;
+    #length = 0;
+    #finished = false;
+    constructor(emit, chunkBytes = CANONICAL_WRITER_CHUNK_BYTES) {
+        this.#emit = emit ?? null;
+        this.#chunks = emit === undefined ? [] : null;
+        this.#buffer = new Uint8Array(chunkBytes);
+    }
+    #assertWritable() {
+        if (this.#finished)
+            fail("canonical_writer_finished");
+    }
+    #flush() {
+        if (this.#used === 0)
+            return;
+        const bytes = this.#buffer.subarray(0, this.#used);
+        if (this.#emit === null)
+            this.#chunks.push(bytes.slice());
+        else
+            this.#emit(bytes);
+        this.#used = 0;
+    }
+    u8(value) {
+        this.#assertWritable();
+        if (this.#used === this.#buffer.length)
+            this.#flush();
+        this.#buffer[this.#used] = value & 0xff;
+        this.#used += 1;
+        this.#length += 1;
+    }
+    u16(value) {
+        this.u8((value >>> 8) & 0xff);
+        this.u8(value & 0xff);
+    }
+    u32(value) {
+        this.u8((value >>> 24) & 0xff);
+        this.u8((value >>> 16) & 0xff);
+        this.u8((value >>> 8) & 0xff);
+        this.u8(value & 0xff);
+    }
+    raw(value) {
+        this.#assertWritable();
+        let offset = 0;
+        while (offset < value.length) {
+            if (this.#used === this.#buffer.length)
+                this.#flush();
+            const count = Math.min(value.length - offset, this.#buffer.length - this.#used);
+            this.#buffer.set(value.subarray(offset, offset + count), this.#used);
+            this.#used += count;
+            this.#length += count;
+            offset += count;
+        }
+    }
+    string(value) {
+        const bytes = encoder.encode(value);
+        this.u32(bytes.length);
+        this.raw(bytes);
+    }
+    finish() {
+        this.#assertWritable();
+        if (this.#emit !== null)
+            fail("canonical_writer_materialize_stream");
+        this.#flush();
+        this.#finished = true;
+        const output = new Uint8Array(this.#length);
+        let offset = 0;
+        for (const chunk of this.#chunks) {
+            output.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return output;
+    }
+    finishStreaming() {
+        this.#assertWritable();
+        if (this.#emit === null)
+            fail("canonical_writer_stream_missing");
+        this.#flush();
+        this.#finished = true;
+    }
+}
+function canonicalAddressBytes(address) {
+    assertPolicyAddress(address, "address");
+    // 单 address 上限受 identifier/path cap 约束，通常远小于整份 policy。
+    const writer = new CanonicalWriter(undefined, CANONICAL_ADDRESS_CHUNK_BYTES);
+    switch (address.kind) {
+        case "root":
+            writer.u8(1);
+            break;
+        case "node":
+            writer.u8(2);
+            writer.string(address.nodeId);
+            break;
+        case "attr":
+            writer.u8(3);
+            if (address.owner.kind === "node") {
+                writer.u8(1);
+                writer.string(address.owner.nodeId);
+            }
+            else {
+                writer.u8(2);
+                writer.string(address.owner.sourceNodeId);
+                writer.string(address.owner.destinationNodeId);
+                writer.string(address.owner.relationKind);
+            }
+            writer.u16(address.path.length);
+            for (const segment of address.path)
+                writer.string(segment);
+            break;
+        case "edge":
+            writer.u8(4);
+            writer.string(address.sourceNodeId);
+            writer.string(address.destinationNodeId);
+            writer.string(address.relationKind);
+            break;
+    }
+    return writer.finish();
+}
+function hashParts(domain, parts) {
+    const hasher = new Sha256Incremental();
+    hasher.update(encoder.encode(domain));
+    const lengthBytes = new Uint8Array(8);
+    for (const part of parts) {
+        if (!Number.isSafeInteger(part.length) || part.length < 0)
+            fail("canonical_length_invalid");
+        let remaining = BigInt(part.length);
+        for (let index = 0; index < lengthBytes.length; index += 1) {
+            lengthBytes[index] = Number(remaining & 0xffn);
+            remaining >>= 8n;
+        }
+        hasher.update(lengthBytes);
+        hasher.update(part);
+    }
+    return hasher.digest();
+}
+function hexDigest(bytes) {
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Canonical Ladybug relation identity shared with the Rust store. */
+export function canonicalLadybugRelationId(sourceNodeId, destinationNodeId, relationKind) {
+    assertIdentifier(sourceNodeId, "relation_source_node_id");
+    assertIdentifier(destinationNodeId, "relation_destination_node_id");
+    assertIdentifier(relationKind, "relation_kind");
+    return `rel_${hexDigest(hashParts("ladybug-relation-id-v1", [
+        encoder.encode(sourceNodeId),
+        encoder.encode(destinationNodeId),
+        encoder.encode(relationKind),
+    ]))}`;
+}
+/** Domain-separated stable identity of one typed policy address. */
+export function deriveViewAccessPolicySubjectId(address) {
+    assertPolicyAddress(address, "subject_address");
+    if (address.kind === "root")
+        return VIEW_ACCESS_POLICY_ROOT_SUBJECT_ID;
+    return `view_subject_${hexDigest(hashParts("ladybug-view-access-subject-id-v2", [canonicalAddressBytes(address)]))}`;
+}
+/** Constructs a bound non-root subject; the root is the exported fixed constant. */
+export function createViewAccessPolicySubject(address, structuralParentId, mode) {
+    assertPolicyAddress(address, "subject_address");
+    if (address.kind === "root") {
+        fail("root_requires_fixed_constructor");
+    }
+    assertIdentifier(structuralParentId, "structural_parent_id");
+    assertMode(mode, "mode");
+    const cloned = clonePolicyAddress(address);
+    return {
+        id: deriveViewAccessPolicySubjectId(cloned),
+        kind: cloned.kind,
+        address: cloned,
+        structuralParentId,
+        mode,
+    };
+}
+/**
+ * Reduces a runtime target to its policy address. Vector spaces cannot carry
+ * policy overrides and always resolve through their owning node.
+ */
+export function viewAccessPolicyAddressForTarget(target) {
+    assertPolicyTarget(target, "target");
+    if (target.kind === "vector")
+        return { kind: "node", nodeId: target.nodeId };
+    return clonePolicyAddress(target);
+}
+/**
+ * Stable target-to-subject mapping used by every query and mutation gate.
+ * Vector-space names are validated but deliberately do not influence the id:
+ * every vector is governed by the policy subject of its owning node.
+ */
+export function deriveViewAccessPolicySubjectIdForTarget(target) {
+    return deriveViewAccessPolicySubjectId(viewAccessPolicyAddressForTarget(target));
+}
+function clonePolicyAddress(address) {
+    switch (address.kind) {
+        case "root":
+            return { kind: "root" };
+        case "node":
+            return { kind: "node", nodeId: address.nodeId };
+        case "edge":
+            return {
+                kind: "edge",
+                sourceNodeId: address.sourceNodeId,
+                destinationNodeId: address.destinationNodeId,
+                relationKind: address.relationKind,
+            };
+        case "attr":
+            return {
+                kind: "attr",
+                owner: address.owner.kind === "node"
+                    ? { kind: "node", nodeId: address.owner.nodeId }
+                    : {
+                        kind: "edge",
+                        sourceNodeId: address.owner.sourceNodeId,
+                        destinationNodeId: address.owner.destinationNodeId,
+                        relationKind: address.owner.relationKind,
+                    },
+                path: [...address.path],
+            };
+    }
+}
+function canonicalPolicyBytes(subjects, writer) {
+    writer.raw(encoder.encode("ladybug-view-access-policy\0"));
+    writer.u16(VIEW_ACCESS_POLICY_SCHEMA_VERSION);
+    writer.u32(subjects.length);
+    for (const subject of subjects) {
+        writer.string(subject.id);
+        writer.u8({ root: 1, node: 2, attr: 3, edge: 4 }[subject.kind]);
+        writer.raw(canonicalAddressBytes(subject.address));
+        if (subject.structuralParentId === null) {
+            writer.u8(0);
+        }
+        else {
+            writer.u8(1);
+            writer.string(subject.structuralParentId);
+        }
+        writer.u8({ inherit: 0, deny: 1, read: 2, read_write: 3 }[subject.mode]);
+    }
+}
+function canonicalPolicySha256(subjects) {
+    const hasher = new Sha256Incremental();
+    const writer = new CanonicalWriter((bytes) => hasher.update(bytes));
+    canonicalPolicyBytes(subjects, writer);
+    writer.finishStreaming();
+    return hasher.digest();
+}
+/** Sorts, validates and seals one canonical fail-closed policy snapshot. */
+export function sealViewAccessPolicy(subjects) {
+    if (!Array.isArray(subjects))
+        fail("subjects_invalid");
+    indexAndValidateSubjects(subjects, false);
+    const canonicalSubjects = subjects
+        .map((subject) => ({ ...subject, address: clonePolicyAddress(subject.address) }))
+        // subject.id 已经过 assertSubject 的派生 identity 检查，只可能是 ASCII root/hex id。
+        .sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+    indexAndValidateSubjects(canonicalSubjects, true);
+    return {
+        schemaVersion: VIEW_ACCESS_POLICY_SCHEMA_VERSION,
+        subjects: canonicalSubjects,
+        policySha256: [...canonicalPolicySha256(canonicalSubjects)],
+    };
+}
+/** Validates canonical ordering, graph invariants and digest. */
+export function validateViewAccessPolicy(snapshot) {
+    if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+        fail("snapshot_invalid");
+    }
+    assertExactKeys(snapshot, ["schemaVersion", "subjects", "policySha256"], "snapshot");
+    if (snapshot.schemaVersion !== VIEW_ACCESS_POLICY_SCHEMA_VERSION) {
+        fail("schema_version_unsupported");
+    }
+    indexAndValidateSubjects(snapshot.subjects, true);
+    if (!Array.isArray(snapshot.policySha256)
+        || snapshot.policySha256.length !== SHA256_LENGTH
+        || snapshot.policySha256.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+        fail("digest_invalid");
+    }
+    const expected = canonicalPolicySha256(snapshot.subjects);
+    if (!expected.every((octet, index) => octet === snapshot.policySha256[index])) {
+        fail("digest_mismatch");
+    }
+}
+/**
+ * Resolves the closest explicit mode on the subject's structural parent chain.
+ * A chain with only `inherit` modes ends at the sealed fixed-deny root.
+ */
+export function resolveViewAccessMode(subjects, subjectId) {
+    assertIdentifier(subjectId, "subject_id");
+    const byId = indexAndValidateSubjects(subjects, false);
+    let current = byId.get(subjectId);
+    if (current === undefined)
+        fail("subject_missing");
+    while (current !== undefined) {
+        if (current.mode !== "inherit") {
+            return { mode: current.mode, decidedBySubjectId: current.id };
+        }
+        if (current.structuralParentId === null)
+            fail("resolution_chain_terminated_before_decision");
+        current = byId.get(current.structuralParentId);
+    }
+    fail("resolution_chain_missing");
+}
+export function isViewReadable(mode) {
+    assertEffectiveMode(mode, "mode");
+    return mode === "read" || mode === "read_write";
+}
+export function isViewWritable(mode) {
+    assertEffectiveMode(mode, "mode");
+    return mode === "read_write";
+}
+/**
+ * Edge access never inherits through its endpoints. Endpoints are gates only:
+ * both must be readable; writing additionally requires the edge itself to be
+ * explicitly/effectively `read_write`.
+ */
+export function resolveEdgeViewAccessMode(edgeMode, sourceMode, destinationMode) {
+    assertEffectiveMode(edgeMode, "edge_mode");
+    assertEffectiveMode(sourceMode, "source_mode");
+    assertEffectiveMode(destinationMode, "destination_mode");
+    if (!isViewReadable(sourceMode) || !isViewReadable(destinationMode))
+        return "deny";
+    if (edgeMode === "read_write")
+        return "read_write";
+    if (edgeMode === "read")
+        return "read";
+    return "deny";
+}
+function pathsEqual(left, right) {
+    return left.length === right.length && left.every((segment, index) => segment === right[index]);
+}
+function targetsEqual(left, right) {
+    if (left.kind !== right.kind)
+        return false;
+    switch (left.kind) {
+        case "node":
+            return right.kind === "node" && left.nodeId === right.nodeId;
+        case "attribute":
+            return right.kind === "attribute"
+                && left.ownerKind === right.ownerKind
+                && left.ownerId === right.ownerId
+                && pathsEqual(left.path, right.path);
+        case "edge":
+            return right.kind === "edge"
+                && left.edgeId === right.edgeId
+                && left.sourceNodeId === right.sourceNodeId
+                && left.destinationNodeId === right.destinationNodeId;
+        case "vector":
+            return right.kind === "vector"
+                && left.nodeId === right.nodeId
+                && left.vectorSpace === right.vectorSpace;
+    }
+}
+function assertWalChange(change, index) {
+    if (typeof change !== "object" || change === null || Array.isArray(change)) {
+        fail(`canonical_wal_changes_${index}_invalid`);
+    }
+    const candidate = change;
+    assertTarget(candidate.target, `canonical_wal_changes_${index}_target`);
+    assertLeafPath(candidate.leafPath, `canonical_wal_changes_${index}_leaf_path`);
+    if (candidate.provenance !== "baseline" && candidate.provenance !== "overlay_created") {
+        fail(`canonical_wal_changes_${index}_provenance_invalid`);
+    }
+    if (candidate.target.kind === "attribute" && !pathsEqual(candidate.target.path, candidate.leafPath)) {
+        fail("attribute_leaf_path_mismatch");
+    }
+    if (candidate.target.kind === "vector")
+        fail("vector_leaf_change_forbidden");
+}
+/**
+ * Makes a leaf-scoped overlay decision. Canonical WAL visibility is granted
+ * only for an exact typed target and changed-leaf path; neither ancestor-prefix
+ * matches, a changed sibling nor another owner can make baseline data visible.
+ */
+export function resolveOverlayLeafViewAccessMode(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        fail("overlay_leaf_input_invalid");
+    }
+    assertTarget(input.target, "overlay_leaf_target");
+    assertLeafPath(input.leafPath, "overlay_leaf_path");
+    if (input.target.kind === "attribute" && !pathsEqual(input.target.path, input.leafPath)) {
+        fail("attribute_leaf_path_mismatch");
+    }
+    if (input.target.kind === "vector")
+        fail("vector_leaf_change_forbidden");
+    if (input.provenance !== "baseline" && input.provenance !== "overlay_created") {
+        fail("overlay_leaf_provenance_invalid");
+    }
+    assertEffectiveMode(input.policyMode, "overlay_leaf_policy_mode");
+    if (!Array.isArray(input.canonicalWalChanges))
+        fail("canonical_wal_changes_invalid");
+    let exactWalChange = false;
+    for (let index = 0; index < input.canonicalWalChanges.length; index += 1) {
+        const change = input.canonicalWalChanges[index];
+        assertWalChange(change, index);
+        if (targetsEqual(input.target, change.target) && pathsEqual(input.leafPath, change.leafPath)) {
+            exactWalChange = true;
+        }
+    }
+    if (input.provenance === "overlay_created" || exactWalChange)
+        return "read_write";
+    return input.policyMode;
+}
+function rotateRight(value, count) {
+    return (value >>> count) | (value << (32 - count));
+}
+class Sha256Incremental {
+    #words = new Uint32Array(64);
+    #hash = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+        0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    #block = new Uint8Array(64);
+    #blockLength = 0;
+    #byteLength = 0n;
+    #finished = false;
+    #compress(bytes, offset) {
+        for (let index = 0; index < 16; index += 1) {
+            const at = offset + index * 4;
+            this.#words[index] = ((bytes[at] << 24) | (bytes[at + 1] << 16)
+                | (bytes[at + 2] << 8) | bytes[at + 3]) >>> 0;
+        }
+        for (let index = 16; index < 64; index += 1) {
+            const a = this.#words[index - 15];
+            const b = this.#words[index - 2];
+            const s0 = rotateRight(a, 7) ^ rotateRight(a, 18) ^ (a >>> 3);
+            const s1 = rotateRight(b, 17) ^ rotateRight(b, 19) ^ (b >>> 10);
+            this.#words[index] = (this.#words[index - 16] + s0 + this.#words[index - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = this.#hash;
+        for (let index = 0; index < 64; index += 1) {
+            const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+            const choice = (e & f) ^ (~e & g);
+            const t1 = (h + sum1 + choice + SHA256_K[index] + this.#words[index]) >>> 0;
+            const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (sum0 + majority) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        this.#hash[0] = (this.#hash[0] + a) >>> 0;
+        this.#hash[1] = (this.#hash[1] + b) >>> 0;
+        this.#hash[2] = (this.#hash[2] + c) >>> 0;
+        this.#hash[3] = (this.#hash[3] + d) >>> 0;
+        this.#hash[4] = (this.#hash[4] + e) >>> 0;
+        this.#hash[5] = (this.#hash[5] + f) >>> 0;
+        this.#hash[6] = (this.#hash[6] + g) >>> 0;
+        this.#hash[7] = (this.#hash[7] + h) >>> 0;
+    }
+    update(bytes) {
+        if (this.#finished)
+            fail("sha256_finished");
+        this.#byteLength += BigInt(bytes.length);
+        let offset = 0;
+        if (this.#blockLength > 0) {
+            const count = Math.min(bytes.length, 64 - this.#blockLength);
+            this.#block.set(bytes.subarray(0, count), this.#blockLength);
+            this.#blockLength += count;
+            offset += count;
+            if (this.#blockLength === 64) {
+                this.#compress(this.#block, 0);
+                this.#blockLength = 0;
+            }
+        }
+        while (offset + 64 <= bytes.length) {
+            this.#compress(bytes, offset);
+            offset += 64;
+        }
+        if (offset < bytes.length) {
+            const remaining = bytes.subarray(offset);
+            this.#block.set(remaining, 0);
+            this.#blockLength = remaining.length;
+        }
+    }
+    digest() {
+        if (this.#finished)
+            fail("sha256_finished");
+        this.#finished = true;
+        const bitLength = this.#byteLength * 8n;
+        const used = this.#blockLength;
+        this.#block[used] = 0x80;
+        this.#block.fill(0, used + 1);
+        if (used >= 56) {
+            this.#compress(this.#block, 0);
+            this.#block.fill(0);
+        }
+        for (let index = 0; index < 8; index += 1) {
+            this.#block[63 - index] = Number((bitLength >> BigInt(index * 8)) & 0xffn);
+        }
+        this.#compress(this.#block, 0);
+        const digest = new Uint8Array(SHA256_LENGTH);
+        for (let index = 0; index < this.#hash.length; index += 1) {
+            const word = this.#hash[index];
+            const at = index * 4;
+            digest[at] = (word >>> 24) & 0xff;
+            digest[at + 1] = (word >>> 16) & 0xff;
+            digest[at + 2] = (word >>> 8) & 0xff;
+            digest[at + 3] = word & 0xff;
+        }
+        return digest;
+    }
+}
+const SHA256_K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);