@silvermoon-work/ipfs-payload 0.0.0-stage → 0.1.0-rc.0

package/dist/index.js

@@ -0,0 +1,192 @@
+import * as dagCbor from "@ipld/dag-cbor";
+import { asNativeCID, encodeDagCbor } from "./dag-cbor.js";
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import { inspectTaskSchema } from "./contract.js";
+import { ContentRef } from "./content-ref.js";
+import { formatCidPath, locate, parseCidPath } from "./paths.js";
+import { inspectSchema } from "./schema.js";
+import { Budget, snapshot } from "./value.js";
+export { addContentRefKeyword, inspectTaskSchema } from "./contract.js";
+export { ContentRef } from "./content-ref.js";
+export { parseCidPath } from "./paths.js";
+export { Budget, defaultPayloadLimits } from "./value.js";
+function sameLocations(a, b) {
+    if (a.size !== b.size || [...a.keys()].some((path) => !b.has(path)))
+        throw new Error("CID paths do not exactly match the content references.");
+}
+function inspector(options) {
+    if (options.inspect)
+        return options.inspect;
+    if (options.validate)
+        return (schema, data, budget) => inspectTaskSchema(schema, data, budget, options.validate);
+    return inspectSchema;
+}
+function checked(input, schema, budget, options = {}) {
+    const value = snapshot(input, budget);
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).length !== 2 ||
+        !Object.hasOwn(value, "data") ||
+        !Object.hasOwn(value, "cidPaths") ||
+        !Array.isArray(value.cidPaths))
+        throw new Error("Expected an IpfsPayload with exactly data and cidPaths.");
+    const data = value.data;
+    const cidPaths = value.cidPaths;
+    budget.bytes(value);
+    if (cidPaths.length > budget.limits.maxPaths)
+        throw new Error("CID path count capacity exceeded.");
+    const contract = schema === undefined ? undefined : inspector(options)(schema, data, budget);
+    const references = new Map();
+    const seen = new Set();
+    for (const path of cidPaths) {
+        if (typeof path !== "string")
+            throw new Error("CID paths must be strings.");
+        const ast = parseCidPath(path, budget.limits);
+        const normalized = formatCidPath(ast);
+        if (seen.has(normalized))
+            throw new Error("Duplicate CID path.");
+        seen.add(normalized);
+        const matches = locate(data, ast, budget);
+        if (contract && matches.size === 0 && !contract.rules.has(normalized))
+            throw new Error("CID path is not declared by the schema.");
+        for (const [location, cid] of matches) {
+            if (references.has(location))
+                throw new Error("Overlapping CID paths.");
+            if (typeof cid !== "string")
+                throw new Error("A CID path must select CID strings.");
+            references.set(location, CID.parse(cid));
+        }
+    }
+    if (contract)
+        sameLocations(references, contract.expected);
+    return { payload: { data, cidPaths: cidPaths }, references };
+}
+/** Encode ContentRef instances without a contract; lookalike strings stay ordinary. */
+export function encodeReferences(value, options = {}) {
+    const budget = new Budget(options.limits);
+    const actual = new Map();
+    const data = snapshot(value, budget, (input, path) => {
+        if (!(input instanceof ContentRef))
+            return undefined;
+        actual.set(path, input.cid);
+        return { value: input.cid.toString() };
+    });
+    budget.bytes(data);
+    const cidPaths = [...actual.keys()].sort();
+    const result = { data, cidPaths };
+    checked(result, undefined, budget, options);
+    return result;
+}
+/** Encode author values according to their contract; strings and lookalike objects stay ordinary. */
+export function encodePayload(schema, value, options = {}) {
+    const budget = new Budget(options.limits);
+    const actual = new Map();
+    const data = snapshot(value, budget, (input, path) => {
+        if (!(input instanceof ContentRef))
+            return undefined;
+        actual.set(path, input.cid);
+        return { value: input.cid.toString() };
+    });
+    budget.bytes(data);
+    const { expected } = inspector(options)(schema, data, budget);
+    sameLocations(actual, expected);
+    const cidPaths = [];
+    const covered = new Set();
+    for (const candidate of new Set(expected.values())) {
+        const matches = locate(data, parseCidPath(candidate, budget.limits), budget);
+        if ([...matches.keys()].some((path) => !expected.has(path) || covered.has(path)))
+            continue;
+        if (!matches.size)
+            continue;
+        cidPaths.push(candidate);
+        for (const path of matches.keys())
+            covered.add(path);
+    }
+    for (const path of expected.keys())
+        if (!covered.has(path))
+            cidPaths.push(path);
+    cidPaths.sort();
+    const result = { data, cidPaths };
+    // Generated metadata follows the very same limits and strict checks as received metadata.
+    checked(result, schema, budget, options);
+    return result;
+}
+export function validatePayload(payload, schema, options = {}) {
+    return checked(payload, schema, new Budget(options.limits), options).payload;
+}
+export function decodePayload(payload, schema, options = {}) {
+    const budget = new Budget(options.limits);
+    const verified = checked(payload, schema, budget, options);
+    return snapshot(verified.payload.data, budget, (_value, path) => {
+        const cid = verified.references.get(path);
+        return cid ? { value: ContentRef.fromCID(cid) } : undefined;
+    });
+}
+/** The DAG envelope preserves metadata, but reference positions contain real IPLD CID links. */
+export function toDagPayload(payload, schema, options = {}) {
+    const budget = new Budget(options.limits);
+    const verified = checked(payload, schema, budget, options);
+    return {
+        data: snapshot(verified.payload.data, budget, (_value, path) => {
+            const cid = verified.references.get(path);
+            return cid ? { value: cid } : undefined;
+        }),
+        cidPaths: verified.payload.cidPaths,
+    };
+}
+export function fromDagPayload(value, schema, options = {}) {
+    const budget = new Budget(options.limits);
+    const actual = new Map();
+    const json = snapshot(value, budget, (input, path) => {
+        const cid = asNativeCID(input);
+        if (!cid)
+            return undefined;
+        actual.set(path, cid);
+        return { value: cid.toString() };
+    });
+    const verified = checked(json, schema, budget, options);
+    const expected = new Map([...verified.references].map(([path, cid]) => [`$["data"]${path.slice(1)}`, cid]));
+    sameLocations(actual, expected);
+    return verified.payload;
+}
+export async function encodePayloadBlock(payload, schema, options = {}) {
+    const bytes = encodeDagCbor(toDagPayload(payload, schema, options));
+    if (bytes.byteLength > new Budget(options.limits).limits.maxBytes)
+        throw new Error("Payload block byte capacity exceeded.");
+    return { bytes, cid: CID.createV1(dagCbor.code, await sha256.digest(bytes)) };
+}
+export async function decodePayloadBlock(bytes, schema, options = {}) {
+    if (!(bytes instanceof Uint8Array) ||
+        bytes.byteLength > new Budget(options.limits).limits.maxBytes)
+        throw new Error("Payload block byte capacity exceeded.");
+    const owned = Uint8Array.from(bytes);
+    if (options.cid) {
+        const cid = CID.createV1(dagCbor.code, await sha256.digest(owned));
+        if (!cid.equals(options.cid))
+            throw new Error("Payload CID verification failed.");
+    }
+    const value = dagCbor.decode(owned);
+    const payload = fromDagPayload(value, schema, options);
+    const canonical = encodeDagCbor(toDagPayload(payload, schema, options));
+    if (canonical.length !== owned.length || canonical.some((byte, i) => byte !== owned[i]))
+        throw new Error("Non-canonical DAG-CBOR payload.");
+    return payload;
+}
+/** Trusted Task-dialect bridge: snapshot/path conversion plus full Schema validation. */
+export function compileTrustedContract(schema, options = {}) {
+    const inspect = (source, data, budget) => inspectTaskSchema(source, data, budget, options.validate);
+    const bound = { ...options, inspect };
+    return {
+        schema,
+        encode: (value) => encodePayload(schema, value, bound),
+        decode: (payload) => decodePayload(payload, schema, bound),
+        validate: (payload) => validatePayload(payload, schema, bound),
+        toDag: (payload) => toDagPayload(payload, schema, bound),
+        fromDag: (value) => fromDagPayload(value, schema, bound),
+        encodeBlock: (payload) => encodePayloadBlock(payload, schema, bound),
+        decodeBlock: (bytes, cid) => decodePayloadBlock(bytes, schema, cid ? { ...bound, cid } : bound),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/paths.d.ts

@@ -0,0 +1,20 @@
+import { Budget, type JsonValue, type PayloadLimits } from "./value.js";
+type Literal = string | number | boolean | null;
+export type CidPathStep = {
+    kind: "property";
+    key: string;
+} | {
+    kind: "index";
+    index: number;
+} | {
+    kind: "wildcard";
+} | {
+    kind: "filter";
+    key: string;
+    value: Literal;
+};
+export declare function parseCidPath(expression: string, limits?: Partial<PayloadLimits>): readonly CidPathStep[];
+export declare function formatCidPath(steps: readonly CidPathStep[]): string;
+export declare function locate(data: JsonValue, steps: readonly CidPathStep[], budget: Budget): Map<string, JsonValue>;
+export {};
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA8B,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpG,KAAK,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAChD,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM,GAClC,SAAS,WAAW,EAAE,CA6FxB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAcnE;AAED,wBAAgB,MAAM,CACpB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAqCxB"}

package/dist/paths.js

@@ -0,0 +1,161 @@
+import { Budget, propertyPath, validUnicode } from "./value.js";
+export function parseCidPath(expression, limits = {}) {
+    const budget = new Budget(limits);
+    if (typeof expression !== "string" ||
+        expression.length > budget.limits.maxPathLength ||
+        expression[0] !== "$")
+        throw new Error("Invalid CID path.");
+    let offset = 1;
+    const steps = [];
+    const fail = () => {
+        throw new Error("Unsupported CID path syntax.");
+    };
+    const take = (text) => {
+        if (!expression.startsWith(text, offset))
+            fail();
+        offset += text.length;
+    };
+    const string = () => {
+        const quote = expression[offset++];
+        if (quote !== '"' && quote !== "'")
+            fail();
+        let result = "";
+        while (offset < expression.length) {
+            const char = expression[offset++];
+            if (char === quote) {
+                if (!validUnicode(result))
+                    fail();
+                return result;
+            }
+            if (char.charCodeAt(0) < 32)
+                fail();
+            if (char !== "\\") {
+                result += char;
+                continue;
+            }
+            const escaped = expression[offset++];
+            if (escaped === "'" || escaped === '"' || escaped === "\\")
+                result += escaped;
+            else if (escaped === "u") {
+                const hex = expression.slice(offset, offset + 4);
+                if (!/^[\da-f]{4}$/i.test(hex))
+                    fail();
+                result += String.fromCharCode(Number.parseInt(hex, 16));
+                offset += 4;
+            }
+            else {
+                const escapes = {
+                    "/": "/",
+                    b: "\b",
+                    f: "\f",
+                    n: "\n",
+                    r: "\r",
+                    t: "\t",
+                };
+                if (!escaped || !Object.hasOwn(escapes, escaped))
+                    fail();
+                result += escapes[escaped];
+            }
+        }
+        return fail();
+    };
+    while (offset < expression.length) {
+        budget.visit(steps.length + 1);
+        take("[");
+        if (expression.startsWith("?@", offset)) {
+            take("?@[");
+            const key = string();
+            take("]");
+            while (expression[offset] === " ")
+                offset++;
+            take("==");
+            while (expression[offset] === " ")
+                offset++;
+            let value;
+            if (expression[offset] === '"' || expression[offset] === "'")
+                value = string();
+            else {
+                const literal = /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)/.exec(expression.slice(offset))?.[0];
+                if (!literal)
+                    fail();
+                value = JSON.parse(literal);
+                if (typeof value === "number" && (!Number.isFinite(value) || Object.is(value, -0)))
+                    fail();
+                offset += literal.length;
+            }
+            take("]");
+            steps.push({ kind: "filter", key, value });
+        }
+        else if (expression[offset] === "*") {
+            take("*]");
+            steps.push({ kind: "wildcard" });
+        }
+        else if (expression[offset] === "'" || expression[offset] === '"') {
+            const key = string();
+            take("]");
+            steps.push({ kind: "property", key });
+        }
+        else {
+            const value = /^(?:0|[1-9]\d*)/.exec(expression.slice(offset))?.[0];
+            if (!value || !Number.isSafeInteger(Number(value)))
+                fail();
+            offset += value.length;
+            take("]");
+            steps.push({ kind: "index", index: Number(value) });
+        }
+    }
+    return steps;
+}
+export function formatCidPath(steps) {
+    return steps.reduce((path, step) => {
+        switch (step.kind) {
+            case "property":
+                return propertyPath(path, step.key);
+            case "index":
+                return `${path}[${step.index}]`;
+            case "wildcard":
+                return `${path}[*]`;
+            case "filter":
+                return `${path}[?@[${JSON.stringify(step.key)}] == ${JSON.stringify(step.value)}]`;
+        }
+        throw new Error("Unsupported CID path step.");
+    }, "$");
+}
+export function locate(data, steps, budget) {
+    let matches = new Map([["$", data]]);
+    for (const step of steps) {
+        const next = new Map();
+        for (const [path, value] of matches) {
+            budget.visit();
+            if (step.kind === "property") {
+                if (value &&
+                    typeof value === "object" &&
+                    !Array.isArray(value) &&
+                    Object.hasOwn(value, step.key))
+                    next.set(propertyPath(path, step.key), value[step.key]);
+            }
+            else if (Array.isArray(value)) {
+                if (step.kind === "index") {
+                    if (step.index < value.length)
+                        next.set(`${path}[${step.index}]`, value[step.index]);
+                }
+                else {
+                    for (let i = 0; i < value.length; i++) {
+                        budget.visit();
+                        const item = value[i];
+                        if (step.kind === "wildcard" ||
+                            (item !== null &&
+                                typeof item === "object" &&
+                                !Array.isArray(item) &&
+                                Object.hasOwn(item, step.key) &&
+                                item[step.key] === step.value))
+                            next.set(`${path}[${i}]`, item);
+                    }
+                }
+            }
+        }
+        matches = next;
+    }
+    return matches;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/reference.d.ts

@@ -0,0 +1,15 @@
+import { Kind, type TSchema } from "@sinclair/typebox";
+import { ContentRef } from "./content-ref.js";
+export { ContentRef } from "./content-ref.js";
+export interface TContentRef extends TSchema {
+    [Kind]: "ContentRef";
+    static: ContentRef;
+    type: "string";
+    "x-ipfs-content-ref": true;
+}
+/** The JSON keyword survives contract serialization; Kind preserves author-side inference. */
+export declare function ContentRefSchema(options?: {
+    title?: string;
+    description?: string;
+}): TContentRef;
+//# sourceMappingURL=reference.d.ts.map

package/dist/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../src/reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAgB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,WAAW,WAAY,SAAQ,OAAO;IAC1C,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC;IACf,oBAAoB,EAAE,IAAI,CAAC;CAC5B;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,WAAW,CAOb"}

package/dist/reference.js

@@ -0,0 +1,14 @@
+import { Kind, TypeRegistry } from "@sinclair/typebox";
+import { ContentRef } from "./content-ref.js";
+export { ContentRef } from "./content-ref.js";
+/** The JSON keyword survives contract serialization; Kind preserves author-side inference. */
+export function ContentRefSchema(options = {}) {
+    return {
+        ...options,
+        [Kind]: "ContentRef",
+        type: "string",
+        "x-ipfs-content-ref": true,
+    };
+}
+TypeRegistry.Set("ContentRef", (_schema, value) => value instanceof ContentRef);
+//# sourceMappingURL=reference.js.map

package/dist/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../src/reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,YAAY,EAAgB,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAS9C,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAC9B,UAAoD,EAAE;IAEtD,OAAO;QACL,GAAG,OAAO;QACV,CAAC,IAAI,CAAC,EAAE,YAAY;QACpB,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,IAAI;KACZ,CAAC;AACnB,CAAC;AAED,YAAY,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,YAAY,UAAU,CAAC,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,6 @@
+import { Budget, type JsonValue } from "./value.js";
+export declare function inspectSchema(input: unknown, data: JsonValue, budget: Budget): {
+    expected: Map<string, string>;
+    rules: Set<string>;
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAA0B,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AA6C5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM;;;EAoM5E"}

package/dist/schema.js

@@ -0,0 +1,196 @@
+import { Ajv } from "ajv";
+import { CID } from "multiformats/cid";
+import { Budget, propertyPath, snapshot } from "./value.js";
+const keywords = new Set([
+    "$schema",
+    "$id",
+    "title",
+    "description",
+    "default",
+    "examples",
+    "type",
+    "anyOf",
+    "const",
+    "enum",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "additionalItems",
+    "minItems",
+    "maxItems",
+    "uniqueItems",
+    "minProperties",
+    "maxProperties",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "x-ipfs-content-ref",
+]);
+export function inspectSchema(input, data, budget) {
+    const root = snapshot(input, budget, undefined, true);
+    budget.bytes(root);
+    const discriminators = new Map();
+    const references = new Map();
+    const ajv = new Ajv({ strict: true, strictTuples: false, allErrors: false, ownProperties: true });
+    ajv.addKeyword({
+        keyword: "x-ipfs-content-ref",
+        schemaType: "boolean",
+        validate: (enabled, value) => {
+            if (!enabled || typeof value !== "string")
+                return false;
+            try {
+                CID.parse(value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        errors: false,
+    });
+    if (!ajv.validateSchema(root))
+        throw new Error("Invalid payload schema.");
+    const inspect = (schema, depth) => {
+        budget.visit(depth);
+        if (!schema || typeof schema !== "object" || Array.isArray(schema))
+            throw new Error("Expected a supported object schema.");
+        for (const key of Object.keys(schema))
+            if (!keywords.has(key))
+                throw new Error(`Unsupported payload schema keyword: ${key}.`);
+        if (schema.type !== undefined && typeof schema.type !== "string")
+            throw new Error("Use explicit union schemas.");
+        if (Object.hasOwn(schema, "x-ipfs-content-ref")) {
+            if (schema["x-ipfs-content-ref"] !== true ||
+                schema.type !== "string" ||
+                Object.keys(schema).some((key) => !["type", "x-ipfs-content-ref", "title", "description"].includes(key)))
+                throw new Error("Invalid ContentRef schema.");
+            references.set(schema, true);
+            return true;
+        }
+        let hasRefs = false;
+        for (const child of Object.values(schema.properties ?? {}))
+            hasRefs = inspect(child, depth + 1) || hasRefs;
+        if (schema.items)
+            for (const child of Array.isArray(schema.items) ? schema.items : [schema.items])
+                hasRefs = inspect(child, depth + 1) || hasRefs;
+        if (schema.additionalItems && typeof schema.additionalItems === "object")
+            throw new Error("Schema-valued additionalItems are unsupported; use a homogeneous array.");
+        if (schema.additionalProperties && typeof schema.additionalProperties === "object")
+            hasRefs = inspect(schema.additionalProperties, depth + 1) || hasRefs;
+        if (schema.anyOf) {
+            let unionRefs = false;
+            for (const branch of schema.anyOf)
+                unionRefs = inspect(branch, depth + 1) || unionRefs;
+            if (unionRefs) {
+                const first = schema.anyOf[0];
+                const key = Object.keys(first.properties ?? {}).find((key) => {
+                    const literals = new Set();
+                    for (const branch of schema.anyOf) {
+                        const property = branch.properties?.[key];
+                        if (branch.type !== "object" ||
+                            !branch.required?.includes(key) ||
+                            !property ||
+                            !Object.hasOwn(property, "const") ||
+                            (property.const !== null && typeof property.const === "object") ||
+                            property["x-ipfs-content-ref"] ||
+                            branch.anyOf)
+                            return false;
+                        const literal = JSON.stringify(property.const);
+                        if (literals.has(literal))
+                            return false;
+                        literals.add(literal);
+                    }
+                    return true;
+                });
+                if (!key)
+                    throw new Error("Reference unions require a unique required literal discriminator.");
+                discriminators.set(schema, key);
+            }
+            hasRefs = hasRefs || unionRefs;
+        }
+        // Sibling validation clauses can narrow a union but must not add a second reference meaning.
+        if (schema.anyOf && (schema.properties || schema.items || schema.additionalProperties))
+            throw new Error("Reference traversal does not support union structural siblings.");
+        references.set(schema, hasRefs);
+        return hasRefs;
+    };
+    inspect(root, 0);
+    const validate = ajv.compile(root);
+    if (!validate(data))
+        throw new Error(`Payload does not match schema: ${ajv.errorsText(validate.errors)}.`);
+    const expected = new Map();
+    const rules = new Set();
+    const selected = (schema, value) => {
+        const key = discriminators.get(schema);
+        if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, key))
+            throw new Error("Missing payload discriminator.");
+        const branches = schema.anyOf.filter((branch) => branch.properties[key].const === value[key]);
+        if (branches.length !== 1)
+            throw new Error("Invalid or ambiguous payload discriminator.");
+        return branches[0];
+    };
+    const filter = (path, key, literal) => `${path}[?@[${JSON.stringify(key)}] == ${JSON.stringify(literal)}]`;
+    const walk = (schema, value, path, rule, depth) => {
+        budget.visit(depth);
+        if (!references.get(schema))
+            return;
+        if (schema["x-ipfs-content-ref"]) {
+            rules.add(rule);
+            if (value !== undefined)
+                expected.set(path, rule);
+            return;
+        }
+        if (schema.anyOf) {
+            const branch = value === undefined ? undefined : selected(schema, value);
+            for (const option of schema.anyOf)
+                walk(option, option === branch ? value : undefined, path, rule, depth + 1);
+            return;
+        }
+        if (schema.properties)
+            for (const [key, child] of Object.entries(schema.properties))
+                walk(child, value && typeof value === "object" && !Array.isArray(value) && Object.hasOwn(value, key)
+                    ? value[key]
+                    : undefined, propertyPath(path, key), propertyPath(rule, key), depth + 1);
+        if (schema.additionalProperties &&
+            typeof schema.additionalProperties === "object" &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value))
+            for (const [key, item] of Object.entries(value))
+                if (!Object.hasOwn(schema.properties ?? {}, key))
+                    walk(schema.additionalProperties, item, propertyPath(path, key), propertyPath(rule, key), depth + 1);
+        if (schema.items) {
+            if (Array.isArray(schema.items)) {
+                schema.items.forEach((item, i) => {
+                    walk(item, Array.isArray(value) ? value[i] : undefined, `${path}[${i}]`, `${rule}[${i}]`, depth + 1);
+                });
+            }
+            else {
+                const item = schema.items;
+                const key = discriminators.get(item);
+                if (key) {
+                    for (const branch of item.anyOf)
+                        walk(branch, undefined, path, filter(rule, key, branch.properties[key].const), depth + 1);
+                }
+                else
+                    walk(item, undefined, path, `${rule}[*]`, depth + 1);
+                if (Array.isArray(value))
+                    value.forEach((child, i) => {
+                        const branch = key ? selected(item, child) : item;
+                        walk(branch, child, `${path}[${i}]`, key ? filter(rule, key, branch.properties[key].const) : `${rule}[*]`, depth + 1);
+                    });
+            }
+        }
+    };
+    walk(root, data, "$", "$", 0);
+    if (rules.size > budget.limits.maxPaths)
+        throw new Error("Schema reference path capacity exceeded.");
+    return { expected, rules };
+}
+//# sourceMappingURL=schema.js.map