Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(contracts): resolve local schema references within their resource
morluto46cc5ce056f9
diff --git a/src/contracts/compactInputSchema.test.ts b/src/contracts/compactInputSchema.test.tsindex 4854524a8..b2bc919fe 100644--- a/src/contracts/compactInputSchema.test.ts+++ b/src/contracts/compactInputSchema.test.ts@@ -1,3 +1,4 @@+import { Ajv } from "ajv";import { Ajv2020 } from "ajv/dist/2020.js";import { describe, expect, it } from "vitest";@@ -352,3 +353,210 @@ describe("compact input schema budget and reduction", () => {expect(serializedBytes(schema)).toBeLessThanOrEqual(13312);});});++it.each([+ ["draft-2020-12", "https://example.test/nested"],+ ["draft-2020-12", "nested.json"],+ ["draft-07", "https://example.test/nested"],+ ["draft-07", "nested.json"],+] as const)(+ "keeps embedded resource references scoped when inlining twice in %s with %s",+ (dialect, id) => {+ const source = {+ $schema:+ dialect === "draft-07"+ ? "http://json-schema.org/draft-07/schema#"+ : "https://json-schema.org/draft/2020-12/schema",+ $id: "https://example.test/root.json",+ type: "object",+ definitions: {+ target: { type: "string" },+ nested: {+ $id: id,+ type: "object",+ definitions: { target: { type: "number" } },+ properties: { value: { $ref: "#/definitions/target" } },+ required: ["value"],+ },+ },+ properties: {+ before: { $ref: "#/definitions/nested" },+ after: { $ref: "#/definitions/nested" },+ },+ required: ["before", "after"],+ };+ const compact = compactAdvertisedInputSchema(source, 13312);+ expect(compact.presentation).toBe("inline");+ expect(JSON.stringify(compact.schema)).not.toContain('"$ref":');+ const createAjv = () =>+ dialect === "draft-07"+ ? new Ajv({ strict: false })+ : new Ajv2020({ strict: false });+ const canonical = createAjv().compile(source);+ const advertised = createAjv().compile(compact.schema);+ for (const value of [7, "seven", null]) {+ const input = { before: { value }, after: { value } };+ expect(advertised(input)).toBe(canonical(input));+ }+ },+);++it("decodes URI fragments and JSON Pointer escapes through schema arrays", () => {+ const source = {+ type: "object",+ definitions: { "a/b~": { prefixItems: [{ type: "number" }] } },+ properties: { value: { $ref: "#/definitions/a%7E1b%7E0/prefixItems/0" } },+ };+ const result = compactAdvertisedInputSchema(source, 13312);+ expect(result.presentation).toBe("inline");+ const canonical = new Ajv2020({ strict: false }).compile(source);+ const advertised = new Ajv2020({ strict: false }).compile(result.schema);+ for (const value of [7, "seven", null])+ expect(advertised({ value })).toBe(canonical({ value }));+});++it.each(["$dynamicRef", "$recursiveRef"])(+ "does not strip resource identities from a partially expanded %s closure",+ (keyword) => {+ const result = compactAdvertisedInputSchema(+ {+ type: "object",+ definitions: {+ nested: {+ $id: "https://example.test/nested",+ type: "object",+ properties: { next: { [keyword]: "#" } },+ },+ },+ properties: { child: { $ref: "#/definitions/nested" } },+ },+ 13312,+ );+ expect(result.presentation).toBe("reduced");+ expect(JSON.stringify(result.schema)).not.toContain('"$ref":');+ expect(result.schema.description).toContain("canonical");+ },+);++it.each(["", "#legacy", "https://example.test/root.json"])(+ "does not invent a pointer resource for an aliased or ambiguous nested ID %j",+ (id) => {+ const result = compactAdvertisedInputSchema(+ {+ $id: "https://example.test/root.json",+ type: "object",+ definitions: {+ target: { type: "string" },+ nested: {+ $id: id,+ type: "object",+ definitions: { target: { type: "number" } },+ properties: { value: { $ref: "#/definitions/target" } },+ },+ },+ properties: { child: { $ref: "#/definitions/nested" } },+ },+ 13312,+ );+ expect(result.presentation).toBe("reduced");+ expect(result.schema.properties).toEqual({ child: {} });+ },+);++it("uses explicit reduction for Draft 7 reference siblings with conflicting client semantics", () => {+ const result = compactAdvertisedInputSchema(+ {+ $schema: "http://json-schema.org/draft-07/schema#",+ type: "object",+ definitions: { value: { type: "number" } },+ properties: { value: { $ref: "#/definitions/value", maximum: 5 } },+ },+ 13312,+ );+ expect(result.presentation).toBe("reduced");+ expect(result.schema.properties).toEqual({ value: { type: "number" } });+});++it.each(["draft-2020-12", "draft-07"] as const)(+ "removes embedded dialect declarations only after static expansion in %s",+ (dialect) => {+ const $schema =+ dialect === "draft-07"+ ? "http://json-schema.org/draft-07/schema#"+ : "https://json-schema.org/draft/2020-12/schema";+ const shared = { $ref: "#/definitions/value" };+ const source = {+ $schema,+ $id: "https://example.test/root",+ type: "object",+ properties: Object.fromEntries(+ ["string", "number"].map((type) => [+ type,+ {+ $schema,+ $id: `${type}.json#`,+ type: "object",+ definitions: { value: { type } },+ properties: { value: shared },+ required: ["value"],+ },+ ]),+ ),+ required: ["string", "number"],+ };+ const result = compactAdvertisedInputSchema(source, 13312);+ expect(result.presentation).toBe("inline");+ expect(result.schema.$schema).toBe($schema);+ expect(JSON.stringify(result.schema).match(/"\$schema"/gu)).toHaveLength(1);+ const createAjv = () =>+ dialect === "draft-07"+ ? new Ajv({ strict: false })+ : new Ajv2020({ strict: false });+ const canonical = createAjv().compile(source);+ const advertised = createAjv().compile(result.schema);+ for (const value of [+ { string: { value: "a" }, number: { value: 7 } },+ { string: { value: 7 }, number: { value: "a" } },+ ])+ expect(advertised(value)).toBe(canonical(value));+ },+);++it.each(["child.json", "https://example.test/child.json"])(+ "does not expand ambiguous sibling resources with ID %s",+ ($id) => {+ const result = compactAdvertisedInputSchema(+ {+ type: "object",+ properties: Object.fromEntries(+ ["string", "number"].map((type) => [+ type,+ {+ $id,+ type: "object",+ definitions: { value: { type } },+ properties: { value: { $ref: "#/definitions/value" } },+ },+ ]),+ ),+ },+ 13312,+ );+ expect(result.presentation).toBe("reduced");+ expect(result.schema.properties).toEqual({ string: {}, number: {} });+ },+);++it("includes restored root identity in the compact byte budget", () => {+ const result = compactAdvertisedInputSchema(+ {+ $id: `https://example.test/${"a".repeat(1024)}`,+ type: "object",+ properties: { value: { type: "number" } },+ },+ 512,+ );+ expect(result.presentation).toBe("reduced");+ expect(serializedBytes(result.schema)).toBeLessThanOrEqual(512);+ expect(result.schema.properties).toEqual({ value: { type: "number" } });+});diff --git a/src/contracts/compactInputSchema.ts b/src/contracts/compactInputSchema.tsindex f37651172..1a11749fe 100644--- a/src/contracts/compactInputSchema.ts+++ b/src/contracts/compactInputSchema.ts@@ -1,3 +1,7 @@+import {+ JsonSchemaReferences,+ type JsonSchemaScope,+} from "./jsonSchemaReferences.js";import {schemaArrays,schemaChildren,@@ -124,66 +128,104 @@ const stripChildAnnotations = (child: unknown): unknown => {return kept;};-const resolveLocalReference = (- root: Record<string, unknown>,- reference: string,-): unknown => {- if (reference === "#") return root;- if (!reference.startsWith("#/")) return undefined;- let value: unknown = root;- for (const token of reference.slice(2).split("/")) {- const key = token.replaceAll("~1", "/").replaceAll("~0", "~");- if (!isSchemaObject(value) || !Object.hasOwn(value, key)) return undefined;- value = value[key];- }- return value;-};-/** Stop serialization at the budget before allocating an expanded schema. */const inlineWithinBudget = (root: Record<string, unknown>,budgetBytes: number,): Record<string, unknown> | undefined => {+ const references = new JsonSchemaReferences(root);+ const identity = Object.fromEntries(+ ["$id", "$anchor", "$schema"].flatMap((key) =>+ Object.hasOwn(root, key) ? [[key, root[key]]] : [],+ ),+ );+ const identityBytes =+ Object.keys(identity).length === 0 ? 0 : serializedBytes(identity) - 2;+ if (identityBytes > budgetBytes) return undefined;let resolved = true;function* serialize(value: unknown,position: "schema" | "map" | "data",- active: ReadonlySet<string>,+ scope: JsonSchemaScope | undefined,+ active: ReadonlyMap<JsonSchemaScope, ReadonlySet<string>>,): Generator<string> {if (Array.isArray(value)) {yield "[";for (const [index, child] of value.entries()) {if (index > 0) yield ",";- yield* serialize(child, position, active);+ yield* serialize(child, position, scope, active);}yield "]";} else if (isSchemaObject(value)) {+ const currentScope =+ position === "schema" ? references.enter(value, scope) : scope;+ if (+ position === "schema" &&+ (currentScope === undefined ||+ currentScope.dialect !== references.rootScope.dialect ||+ [+ "$dynamicRef",+ "$recursiveRef",+ "$dynamicAnchor",+ "$recursiveAnchor",+ ].some((key) => Object.hasOwn(value, key)))+ ) {+ resolved = false;+ return;+ }if (position === "schema" && Object.keys(value).length === 0) {yield JSON.stringify(jsonValueSchema());return;}if (position === "schema" && typeof value.$ref === "string") {- const target = resolveLocalReference(root, value.$ref);- if (target === undefined || active.has(value.$ref)) {+ const target = references.resolve(currentScope, value.$ref);+ if (+ target.kind !== "target" ||+ currentScope === undefined ||+ active.get(currentScope)?.has(value.$ref)+ ) {resolved = false;return;}- const { $ref, ...siblings } = value;- // Reference siblings are independent constraints in draft 2020-12.- // Merging their keys into the target would overwrite validation rules.- yield* serialize(- Object.keys(siblings).length === 0- ? target- : { allOf: [target, siblings] },- "schema",- new Set([...active, $ref]),+ const {+ $ref,+ $id: _id,+ $anchor: _anchor,+ $schema: _schema,+ ...siblings+ } = value;+ const nextActive = new Map(active);+ nextActive.set(+ currentScope,+ new Set([...(active.get(currentScope) ?? []), $ref]),);+ // Draft 7 ignores siblings, while clients such as Ajv also apply them.+ // Do not label either interpretation an equivalent inline advertisement.+ if (+ currentScope.dialect === "draft-07" &&+ Object.keys(siblings).length > 0+ ) {+ resolved = false;+ return;+ }+ const expanded =+ Object.keys(siblings).length === 0+ ? target.value+ : { allOf: [target.value, siblings] };+ yield* serialize(expanded, "schema", currentScope, nextActive);return;}yield "{";let first = true;for (const [key, child] of Object.entries(value)) {- if (position === "schema" && definitionKeys.has(key)) continue;+ if (+ position === "schema" &&+ (definitionKeys.has(key) ||+ key === "$id" ||+ key === "$anchor" ||+ key === "$schema")+ )+ continue;if (!first) yield ",";first = false;yield JSON.stringify(key) + ":";@@ -196,7 +238,7 @@ const inlineWithinBudget = ((schemaArrays.has(key) || schemaChildren.has(key))? "schema": "data";- yield* serialize(child, childPosition, active);+ yield* serialize(child, childPosition, currentScope, active);}yield "}";} else {@@ -204,31 +246,47 @@ const inlineWithinBudget = (}}const chunks: string[] = [];- let bytes = 0;- for (const chunk of serialize(root, "schema", new Set())) {+ let bytes = identityBytes;+ for (const chunk of serialize(+ root,+ "schema",+ references.rootScope,+ new Map(),+ )) {bytes += Buffer.byteLength(chunk, "utf8");if (bytes > budgetBytes || !resolved) return undefined;chunks.push(chunk);}- return resolved- ? (JSON.parse(chunks.join("")) as Record<string, unknown>)- : undefined;+ if (!resolved) return undefined;+ const expanded: unknown = JSON.parse(chunks.join(""));+ if (!isSchemaObject(expanded)) return undefined;+ // Every emitted dependency is now static and reference-free. Nested resource+ // identifiers/anchors can leave without duplicating identities at call sites.+ const schema = { ...identity, ...expanded };+ return serializedBytes(schema) <= budgetBytes ? schema : undefined;};/** Preserve every possible type, including referenced and nullable unions. */const detectedTypes = (schema: unknown,- root: Record<string, unknown>,- active: ReadonlySet<string> = new Set(),+ references: JsonSchemaReferences,+ inherited: JsonSchemaScope | undefined,+ active: ReadonlySet<object> = new Set(),): readonly string[] | undefined => {if (!isSchemaObject(schema)) return undefined;+ const scope = references.enter(schema, inherited);+ if (scope === undefined) return undefined;if (typeof schema.$ref === "string") {- if (active.has(schema.$ref)) return undefined;- return detectedTypes(- resolveLocalReference(root, schema.$ref),- root,- new Set([...active, schema.$ref]),- );+ if (active.has(schema)) return undefined;+ const target = references.resolve(scope, schema.$ref);+ return target.kind === "target"+ ? detectedTypes(+ target.value,+ references,+ scope,+ new Set([...active, schema]),+ )+ : undefined;}if (typeof schema.type === "string") return [schema.type];if (@@ -243,7 +301,7 @@ const detectedTypes = (: [];if (alternatives.length === 0) return undefined;const types = alternatives.map((branch) =>- detectedTypes(branch, root, active),+ detectedTypes(branch, references, scope, active),);if (types.some((type) => type === undefined)) return undefined;return [...new Set(types.flatMap((type) => type ?? []))];@@ -281,9 +339,10 @@ const reduceToShallowProperties = (].filter((text) => text !== undefined).join(" ");+ const references = new JsonSchemaReferences(schema);const shallow = Object.fromEntries(Object.entries(properties).map(([name, value]) => {- const types = detectedTypes(value, schema);+ const types = detectedTypes(value, references, references.rootScope);const type = types?.length === 1 ? types[0] : types;const description =isSchemaObject(value) && typeof value.description === "string"diff --git a/src/contracts/inputSchemaPresentation.ts b/src/contracts/inputSchemaPresentation.tsindex 61868b044..f6f66b4b6 100644--- a/src/contracts/inputSchemaPresentation.ts+++ b/src/contracts/inputSchemaPresentation.ts@@ -1,3 +1,7 @@+import {+ JsonSchemaReferences,+ type JsonSchemaScope,+} from "./jsonSchemaReferences.js";import { isDeepStrictEqual } from "node:util";import {@@ -9,43 +13,38 @@ import {const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>typeof value === "object" && value !== null && !Array.isArray(value);-const resolveReference = (- root: Readonly<Record<string, unknown>>,- reference: string,-): unknown => {- if (reference === "#") return root;- if (!reference.startsWith("#/")) return undefined;- let value: unknown = root;- for (const token of reference.slice(2).split("/")) {- const key = token.replaceAll("~1", "/").replaceAll("~0", "~");- if (!isObject(value) || !Object.hasOwn(value, key)) return undefined;- value = value[key];- }- return value;-};-const referencedDescription = (- root: Readonly<Record<string, unknown>>,+ references: JsonSchemaReferences,schema: Readonly<Record<string, unknown>>,+ inherited: JsonSchemaScope | undefined,): string | undefined => {let value: unknown = schema;- const active = new Set<string>();+ let scope = inherited;+ const active = new Set<object>();while (isObject(value)) {- if (typeof value.description === "string") return value.description;- if (typeof value.$ref !== "string" || active.has(value.$ref))- return undefined;- active.add(value.$ref);- value = resolveReference(root, value.$ref);+ scope = references.enter(value, scope);+ if (+ typeof value.description === "string" &&+ (typeof value.$ref !== "string" || scope?.dialect !== "draft-07")+ )+ return value.description;+ if (typeof value.$ref !== "string" || active.has(value)) return undefined;+ active.add(value);+ const target = references.resolve(scope, value.$ref);+ if (target.kind !== "target") return undefined;+ value = target.value;}return undefined;};const describeSchema = (schema: unknown,- root: Readonly<Record<string, unknown>>,+ references: JsonSchemaReferences,+ inherited: JsonSchemaScope | undefined,describeProperty: (property: string) => string | undefined,): unknown => {if (!isObject(schema)) return schema;+ const scope = references.enter(schema, inherited);return Object.fromEntries(Object.entries(schema).map(([key, value]) => {if (schemaMaps.has(key) && isObject(value))@@ -53,11 +52,20 @@ const describeSchema = (key,Object.fromEntries(Object.entries(value).map(([name, child]) => {- const described = describeSchema(child, root, describeProperty);- if (key !== "properties" || !isObject(described))+ const described = describeSchema(+ child,+ references,+ scope,+ describeProperty,+ );+ if (+ key !== "properties" ||+ !isObject(described) ||+ !isObject(child)+ )return [name, described];const description =- referencedDescription(root, described) ??+ referencedDescription(references, child, scope) ??describeProperty(name);return [name,@@ -71,16 +79,18 @@ const describeSchema = (if (schemaArrays.has(key) && Array.isArray(value))return [key,- value.map((child) => describeSchema(child, root, describeProperty)),+ value.map((child) =>+ describeSchema(child, references, scope, describeProperty),+ ),];if (schemaChildren.has(key))return [key,Array.isArray(value)? value.map((child) =>- describeSchema(child, root, describeProperty),+ describeSchema(child, references, scope, describeProperty),)- : describeSchema(value, root, describeProperty),+ : describeSchema(value, references, scope, describeProperty),];// Annotation values and literal const/enum data are not schemas.return [key, value];@@ -89,18 +99,29 @@ const describeSchema = (};const objectBranch = (- root: Readonly<Record<string, unknown>>,+ references: JsonSchemaReferences,branch: unknown,): Readonly<Record<string, unknown>> | undefined => {// Reference siblings evaluate separately from the target in 2020-12, so a// merged object could accept inputs the branch rejects.- const resolved =- isObject(branch) && typeof branch.$ref === "string"- ? Object.keys(branch).length === 1- ? resolveReference(root, branch.$ref)- : undefined- : branch;+ let resolved = branch;+ if (isObject(branch) && typeof branch.$ref === "string") {+ if (Object.keys(branch).length !== 1) return undefined;+ const target = references.resolve(references.rootScope, branch.$ref);+ if (target.kind !== "target") return undefined;+ resolved = target.value;+ }return isObject(resolved) &&+ references.enter(resolved, references.rootScope) === references.rootScope &&+ ![+ "$id",+ "$schema",+ "$anchor",+ "$dynamicAnchor",+ "$recursiveAnchor",+ "$dynamicRef",+ "$recursiveRef",+ ].some((key) => Object.hasOwn(resolved, key)) &&resolved.type === "object" &&isObject(resolved.properties)? resolved@@ -324,6 +345,7 @@ const normalizeAdvertisedSchema = (value: unknown): SchemaNormalization => {// union of the groups. The canonical Zod schema still enforces the exact group.const flattenRootObjectUnion = (root: Record<string, unknown>,+ references: JsonSchemaReferences,): Record<string, unknown> => {const { anyOf, oneOf, ...rest } = root;const alternatives = Array.isArray(anyOf) ? anyOf : oneOf;@@ -333,7 +355,21 @@ const flattenRootObjectUnion = (root.properties !== undefined)return root;- const branches = alternatives.map((branch) => objectBranch(root, branch));+ // Lifting removes union locations and branch identities. References into those+ // locations, named anchors or unresolved bases cannot survive that rewrite.+ for (const { scope, target } of references.references())+ if (+ (target.kind === "unresolved" && target.reason === "dynamic") ||+ (scope === references.rootScope &&+ (target.kind !== "target" ||+ target.path.length === 0 ||+ target.path[0] === "anyOf" ||+ target.path[0] === "oneOf"))+ )+ return root;+ const branches = alternatives.map((branch) =>+ objectBranch(references, branch),+ );if (!branches.every((branch) => branch !== undefined)) return root;const variants = new Map<string, unknown[]>();for (const branch of branches)@@ -385,15 +421,17 @@ const presentDiscriminatedRoot = (root: Record<string, unknown>,): Record<string, unknown> => {const { "x-rea-root-discriminator": discriminator, ...canonical } = root;- const flattened = flattenRootObjectUnion(canonical);- if (typeof discriminator !== "string") return flattened;+ const references = new JsonSchemaReferences(canonical);+ const flattened = flattenRootObjectUnion(canonical, references);+ if (typeof discriminator !== "string" || flattened === canonical)+ return flattened;const alternatives = canonical.anyOf ?? canonical.oneOf;if (!Array.isArray(alternatives) || alternatives.length !== 2)throw new TypeError("A presented root discriminator requires two object alternatives",);const branches = alternatives.map((alternative) => {- const branch = objectBranch(canonical, alternative);+ const branch = objectBranch(references, alternative);if (branch === undefined || branch.additionalProperties !== false)throw new TypeError("A presented root discriminator requires strict objects",@@ -487,7 +525,13 @@ export const presentInputJsonSchema = (describeProperty: (property: string) => string | undefined,): Record<string, unknown> => {const flattened = presentDiscriminatedRoot(root);- const described = describeSchema(flattened, flattened, describeProperty);+ const references = new JsonSchemaReferences(flattened);+ const described = describeSchema(+ flattened,+ references,+ references.rootScope,+ describeProperty,+ );if (!isObject(described))return normalizeAdvertisedSchema(flattened).schema as Record<string,diff --git a/src/contracts/jsonSchemaReferences.ts b/src/contracts/jsonSchemaReferences.tsnew file mode 100644index 000000000..b72267e38--- /dev/null+++ b/src/contracts/jsonSchemaReferences.ts@@ -0,0 +1,249 @@+import {+ schemaArrays,+ schemaChildren,+ schemaMaps,+} from "./jsonSchemaKeywords.js";++type SchemaObject = Readonly<Record<string, unknown>>;+type Dialect = "draft-07" | "draft-2020-12";++/** A fragment's resource and URI base are distinct facts. */+export interface JsonSchemaScope {+ readonly root: SchemaObject;+ readonly baseUri: string | undefined;+ readonly dialect: Dialect | undefined;+ readonly parent?: JsonSchemaScope;+}++type LocalReference =+ | {+ readonly kind: "target";+ readonly value: unknown;+ readonly path: readonly string[];+ }+ | { readonly kind: "anchor" }+ | {+ readonly kind: "unresolved";+ readonly reason:+ | "scope"+ | "external"+ | "fragment"+ | "pointer"+ | "resource-boundary"+ | "dynamic";+ };++const isObject = (value: unknown): value is SchemaObject =>+ value !== null && typeof value === "object" && !Array.isArray(value);++const dialectOf = (+ schema: SchemaObject,+ inherited: Dialect | undefined,+): Dialect | undefined =>+ schema.$schema === undefined+ ? inherited+ : schema.$schema === "http://json-schema.org/draft-07/schema#" ||+ schema.$schema === "http://json-schema.org/draft-07/schema"+ ? "draft-07"+ : schema.$schema === "https://json-schema.org/draft/2020-12/schema"+ ? "draft-2020-12"+ : undefined;++/** Per-projection scope ownership; no external resource loading or dynamic-reference evaluation. */+export class JsonSchemaReferences {+ readonly rootScope: JsonSchemaScope;+ readonly #scopes = new WeakMap<+ object,+ WeakMap<JsonSchemaScope, JsonSchemaScope | undefined>+ >();+ readonly #referenceSites: {+ scope: JsonSchemaScope;+ reference: string;+ keyword: string;+ }[] = [];+ readonly #identities = new Map<string, JsonSchemaScope>();+ readonly #relativeIdentities = new WeakMap<+ JsonSchemaScope,+ Map<string, JsonSchemaScope>+ >();+ readonly #ambiguous = new WeakSet<JsonSchemaScope>();++ constructor(root: SchemaObject) {+ let baseUri: string | undefined;+ if (typeof root.$id === "string" && URL.canParse(root.$id)) {+ const url = new URL(root.$id);+ url.hash = "";+ baseUri = url.href;+ }+ this.rootScope = {+ root,+ baseUri,+ dialect: dialectOf(root, "draft-2020-12"),+ };+ if (baseUri !== undefined) this.#identities.set(baseUri, this.rootScope);+ // Index resources before consumers resolve anything, so later duplicate IDs+ // cannot invalidate facts that have already escaped from the owner.+ const pending = [{ value: root as unknown, scope: this.rootScope }];+ const visited = new WeakMap<JsonSchemaScope, WeakSet<object>>();+ while (pending.length > 0) {+ const { value, scope: parent } = pending.pop()!;+ if (!isObject(value)) continue;+ const scope = this.#scope(value, parent);+ if (scope === undefined) continue;+ let seen = visited.get(scope);+ if (seen === undefined) {+ seen = new WeakSet();+ visited.set(scope, seen);+ }+ if (seen.has(value)) continue;+ seen.add(value);+ for (const keyword of ["$ref", "$dynamicRef", "$recursiveRef"]) {+ const reference = value[keyword];+ if (typeof reference !== "string") continue;+ this.#referenceSites.push({ scope, reference, keyword });+ if (keyword !== "$ref") continue;+ const target = this.resolve(scope, reference);+ if (target.kind === "target")+ pending.push({ value: target.value, scope });+ }+ for (const [key, child] of Object.entries(value)) {+ if (schemaMaps.has(key) && isObject(child)) {+ for (const item of Object.values(child))+ pending.push({ value: item, scope });+ } else if (+ (schemaArrays.has(key) || schemaChildren.has(key)) &&+ Array.isArray(child)+ ) {+ for (const item of child) pending.push({ value: item, scope });+ } else if (schemaChildren.has(key))+ pending.push({ value: child, scope });+ }+ }+ }++ enter(+ schema: SchemaObject,+ parent: JsonSchemaScope | undefined,+ ): JsonSchemaScope | undefined {+ if (parent === undefined) return undefined;+ const scope = this.#scope(schema, parent);+ for (let current = scope; current !== undefined; current = current.parent)+ if (this.#ambiguous.has(current)) return undefined;+ return scope?.dialect === undefined ? undefined : scope;+ }++ #scope(+ schema: SchemaObject,+ parent: JsonSchemaScope,+ ): JsonSchemaScope | undefined {+ if (schema === parent.root) return parent;+ if (schema.$id === undefined) return parent;+ let cached = this.#scopes.get(schema);+ if (cached?.has(parent)) return cached.get(parent);+ if (cached === undefined) {+ cached = new WeakMap();+ this.#scopes.set(schema, cached);+ }+ let scope: JsonSchemaScope | undefined;+ if (+ typeof schema.$id === "string" &&+ schema.$id !== "" &&+ (!schema.$id.includes("#") ||+ (schema.$id !== "#" &&+ schema.$id.indexOf("#") === schema.$id.length - 1))+ ) {+ let baseUri: string | undefined;+ try {+ if (parent.baseUri !== undefined || URL.canParse(schema.$id)) {+ const url = new URL(schema.$id, parent.baseUri);+ url.hash = "";+ baseUri = url.href;+ }+ scope = {+ root: schema,+ baseUri,+ dialect: dialectOf(schema, parent.dialect),+ parent,+ };+ if (baseUri !== undefined) {+ const existing = this.#identities.get(baseUri);+ if (existing !== undefined && existing.root !== schema) {+ this.#ambiguous.add(existing);+ this.#ambiguous.add(scope);+ } else if (existing !== undefined) scope = existing;+ else this.#identities.set(baseUri, scope);+ } else {+ let identities = this.#relativeIdentities.get(parent);+ if (identities === undefined) {+ identities = new Map();+ this.#relativeIdentities.set(parent, identities);+ }+ const identity = schema.$id.replace(/#$/u, "");+ const existing = identities.get(identity);+ if (existing !== undefined && existing.root !== schema) {+ this.#ambiguous.add(existing);+ this.#ambiguous.add(scope);+ } else if (existing !== undefined) scope = existing;+ else identities.set(identity, scope);+ }+ } catch {+ // An opaque or unknown URI base must not be replaced with a guessed scope.+ }+ }+ // Empty/fragment IDs can alias a resource or be legacy anchors. Keep them+ // unresolved rather than resetting the pointer root to that subschema.+ cached.set(parent, scope);+ return scope;+ }++ *references(): IterableIterator<{+ readonly scope: JsonSchemaScope;+ readonly target: LocalReference;+ }> {+ for (const { scope, reference, keyword } of this.#referenceSites)+ yield {+ scope,+ target:+ keyword === "$ref"+ ? this.resolve(scope, reference)+ : { kind: "unresolved", reason: "dynamic" },+ };+ }++ resolve(+ scope: JsonSchemaScope | undefined,+ reference: string,+ ): LocalReference {+ if (scope === undefined || this.enter(scope.root, scope) === undefined)+ return { kind: "unresolved", reason: "scope" };+ if (!reference.startsWith("#"))+ return { kind: "unresolved", reason: "external" };+ let fragment: string;+ try {+ fragment = decodeURIComponent(reference.slice(1));+ } catch {+ return { kind: "unresolved", reason: "fragment" };+ }+ if (fragment === "") return { kind: "target", value: scope.root, path: [] };+ if (!fragment.startsWith("/")) return { kind: "anchor" };+ let value: unknown = scope.root;+ const path: string[] = [];+ for (const token of fragment.slice(1).split("/")) {+ if (/~(?:[^01]|$)/u.test(token))+ return { kind: "unresolved", reason: "pointer" };+ const key = token.replaceAll("~1", "/").replaceAll("~0", "~");+ if (+ value === null ||+ typeof value !== "object" ||+ !Object.hasOwn(value, key) ||+ (Array.isArray(value) && !/^(?:0|[1-9][0-9]*)$/u.test(key))+ )+ return { kind: "unresolved", reason: "pointer" };+ if (value !== scope.root && isObject(value) && "$id" in value)+ return { kind: "unresolved", reason: "resource-boundary" };+ path.push(key);+ value = Reflect.get(value, key);+ }+ return { kind: "target", value, path };+ }+}diff --git a/src/contracts/toolInputReferences.test.ts b/src/contracts/toolInputReferences.test.tsindex 9f6127727..cb1f0765a 100644--- a/src/contracts/toolInputReferences.test.ts+++ b/src/contracts/toolInputReferences.test.ts@@ -608,3 +608,132 @@ describe("advertised Boolean schema composition", () => {expect(presented.examples).toEqual([literal]);});});++it.each(["draft-2020-12", "draft-07"] as const)(+ "describes references from their containing resource in %s",+ (dialect) => {+ const presented = presentInputJsonSchema(+ {+ $schema:+ dialect === "draft-07"+ ? "http://json-schema.org/draft-07/schema#"+ : "https://json-schema.org/draft/2020-12/schema",+ $id: "https://example.test/root.json",+ type: "object",+ definitions: { value: { type: "string", description: "Outer text." } },+ properties: {+ child: {+ $id: "child.json",+ type: "object",+ definitions: {+ value: { type: "number", description: "Nested number." },+ },+ properties: { value: { $ref: "#/definitions/value" } },+ },+ },+ },+ () => undefined,+ );+ expect(presented).toMatchObject({+ properties: {+ child: { properties: { value: { description: "Nested number." } } },+ },+ });+ },+);++it.each(["draft-2020-12", "draft-07"] as const)(+ "keeps root union resource identities when lifting would change relative refs in %s",+ (dialect) => {+ const source = {+ $schema:+ dialect === "draft-07"+ ? "http://json-schema.org/draft-07/schema#"+ : "https://json-schema.org/draft/2020-12/schema",+ $id: "https://example.test/root.json",+ anyOf: ["first", "second"].map((kind) => ({+ $id: `https://example.test/${kind}/schema.json`,+ type: "object",+ properties: { kind: { const: kind }, value: { $ref: "child.json" } },+ required: ["kind", "value"],+ additionalProperties: false,+ })),+ };+ const presented = presentInputJsonSchema(source, () => undefined);+ const createAjv = () => {+ const ajv =+ dialect === "draft-07"+ ? new Ajv({ strict: false })+ : new Ajv2020({ strict: false });+ ajv.addSchema({+ $id: "https://example.test/first/child.json",+ type: "string",+ });+ ajv.addSchema({+ $id: "https://example.test/second/child.json",+ type: "number",+ });+ return ajv;+ };+ const canonical = createAjv().compile(source);+ const advertised = createAjv().compile(presented);+ for (const kind of ["first", "second"])+ for (const value of [7, "seven", null])+ expect(advertised({ kind, value })).toBe(canonical({ kind, value }));+ },+);++it("does not lift properties that still refer to deleted root-union locations", () => {+ const source = {+ anyOf: [+ {+ type: "object",+ properties: { value: { $ref: "#/anyOf/1/properties/value" } },+ required: ["value"],+ },+ {+ type: "object",+ properties: { value: { type: "number" } },+ required: ["value"],+ },+ ],+ };+ const presented = presentInputJsonSchema(source, () => undefined);+ const canonical = new Ajv2020({ strict: false }).compile(source);+ const advertised = new Ajv2020({ strict: false }).compile(presented);+ for (const value of [7, "seven", null])+ expect(advertised({ value })).toBe(canonical({ value }));+});++it.each(["$ref", "$dynamicRef"])(+ "preserves the root union used by recursive %s children",+ (keyword) => {+ const source = {+ anyOf: [+ {+ type: "object",+ properties: { end: { const: "done" } },+ required: ["end"],+ additionalProperties: false,+ },+ {+ type: "object",+ properties: { next: { [keyword]: "#" } },+ required: ["next"],+ additionalProperties: false,+ },+ ],+ };+ const presented = presentInputJsonSchema(source, () => undefined);+ expect(presented.anyOf).toBeDefined();+ const canonical = new Ajv2020({ strict: false }).compile(source);+ const advertised = new Ajv2020({ strict: false }).compile(presented);+ for (const value of [+ { end: "done" },+ { next: { end: "done" } },+ { next: {} },+ { next: { end: "invalid" } },+ ])+ expect(advertised(value)).toBe(canonical(value));+ },+);diff --git a/src/contracts/toolOutputReferences.test.ts b/src/contracts/toolOutputReferences.test.tsindex f5e53656f..ee66a4711 100644--- a/src/contracts/toolOutputReferences.test.ts+++ b/src/contracts/toolOutputReferences.test.ts@@ -327,3 +327,33 @@ it.each(["relative/", "https://example.test/nested.json"])(expect(projected).not.toHaveProperty("$id");},);++it("does not synthesize an output base for duplicate embedded resource identifiers", () => {+ const canonical = z.looseObject({}).meta({+ type: "object",+ properties: {+ before: { $id: "https://example.test/repeated", type: "string" },+ after: { $id: "https://example.test/repeated", type: "number" },+ },+ });+ const projected = toolOutputSchemaWithMetadata({+ ...toolContract("binary_session"),+ outputSchema: canonical,+ })["~standard"].jsonSchema.output({ target: "draft-2020-12" });+ expect(projected).not.toHaveProperty("$id");+});++it.each(["$dynamicRef", "$recursiveRef"])(+ "preserves the output base for %s",+ (keyword) => {+ const canonical = z.looseObject({}).meta({+ type: "object",+ properties: { next: { [keyword]: "#" } },+ });+ const projected = toolOutputSchemaWithMetadata({+ ...toolContract("binary_session"),+ outputSchema: canonical,+ })["~standard"].jsonSchema.output({ target: "draft-2020-12" });+ expect(projected).not.toHaveProperty("$id");+ },+);diff --git a/src/contracts/toolSchemaMetadata.ts b/src/contracts/toolSchemaMetadata.tsindex d0468ec48..5344f66c0 100644--- a/src/contracts/toolSchemaMetadata.ts+++ b/src/contracts/toolSchemaMetadata.ts@@ -1,3 +1,7 @@+import {+ JsonSchemaReferences,+ type JsonSchemaScope,+} from "./jsonSchemaReferences.js";import { z } from "zod";import type { ToolContract } from "./toolContractTypes.js";@@ -164,10 +168,14 @@ const hasRelativeSchemaReference = (): boolean => {// Local pointers can make even annotation values executable schemas. Keep// their resource root and traversal role separate from ordinary instance data.- const pending: { value: unknown; root: object; position: SchemaPosition }[] =- [{ value: schema, root: schema, position: "schema" }];+ const references = new JsonSchemaReferences(schema);+ const pending: {+ value: unknown;+ scope: JsonSchemaScope | undefined;+ position: SchemaPosition;+ }[] = [{ value: schema, scope: references.rootScope, position: "schema" }];const visited = new WeakMap<- object,+ JsonSchemaScope,Record<SchemaPosition, WeakSet<object>>>();while (pending.length > 0) {@@ -175,26 +183,24 @@ const hasRelativeSchemaReference = (const current = entry.value;if (current === null || typeof current !== "object") continue;const { position } = entry;- const root =- position !== "map" &&- isSchemaRecord(current) &&- typeof current.$id === "string" &&- URL.canParse(current.$id)- ? current- : entry.root;- let positions = visited.get(root);+ const scope =+ position !== "map" && isSchemaRecord(current)+ ? references.enter(current, entry.scope)+ : entry.scope;+ if (scope === undefined) return true;+ let positions = visited.get(scope);if (positions === undefined) {positions = {schema: new WeakSet(),map: new WeakSet(),unknown: new WeakSet(),};- visited.set(root, positions);+ visited.set(scope, positions);}if (positions[position].has(current)) continue;positions[position].add(current);if (Array.isArray(current)) {- for (const value of current) pending.push({ value, root, position });+ for (const value of current) pending.push({ value, scope, position });continue;}for (const [key, value] of Object.entries(current)) {@@ -203,14 +209,15 @@ const hasRelativeSchemaReference = (["$id", "$ref", "$dynamicRef", "$recursiveRef"].includes(key) &&typeof value === "string") {+ if (key === "$dynamicRef" || key === "$recursiveRef") return true;if (!value.startsWith("#") && !URL.canParse(value)) return true;if (key !== "$id" && value.startsWith("#")) {- const target = localSchemaReference(root, value);+ const target = references.resolve(scope, value);// Unknown anchors are already examined at their schema positions.// Unresolvable pointers retain the existing reference base.- if (target === undefined) return true;+ if (target.kind === "unresolved") return true;if (target.kind === "target")- pending.push({ value: target.value, root, position: "schema" });+ pending.push({ value: target.value, scope, position: "schema" });}}if (position === "schema" && schemaLiteralValues.has(key)) continue;@@ -224,44 +231,12 @@ const hasRelativeSchemaReference = (? "schema": "unknown";if (value !== null && typeof value === "object")- pending.push({ value, root, position: childPosition });+ pending.push({ value, scope, position: childPosition });}}return false;};-/** Decode URI-fragment JSON Pointers without interpreting literal data as schemas. */-const localSchemaReference = (- root: object,- reference: string,-): { kind: "target"; value: unknown } | { kind: "anchor" } | undefined => {- let fragment: string;- try {- fragment = decodeURIComponent(reference.slice(1));- } catch {- return undefined;- }- if (fragment === "") return { kind: "target", value: root };- if (!fragment.startsWith("/")) return { kind: "anchor" };- let value: unknown = root;- for (const token of fragment.slice(1).split("/")) {- if (/~(?:[^01]|$)/u.test(token)) return undefined;- const key = token.replaceAll("~1", "/").replaceAll("~0", "~");- if (- value === null ||- typeof value !== "object" ||- !Object.hasOwn(value, key)- )- return undefined;- // A pointer can cross a resource boundary even inside literal data.- // Preserve the original projection rather than guess the reference scope.- if (value !== root && isSchemaRecord(value) && "$id" in value)- return undefined;- value = Reflect.get(value, key);- }- return { kind: "target", value };-};-const withAdvertisedJsonSchema = <Schema extends z.ZodType>(canonical: Schema,io: "input" | "output",diff --git a/tests/boundary/mcp/compactInputSchemaMcp.test.ts b/tests/boundary/mcp/compactInputSchemaMcp.test.tsindex d63c1223e..30a1221c5 100644--- a/tests/boundary/mcp/compactInputSchemaMcp.test.ts+++ b/tests/boundary/mcp/compactInputSchemaMcp.test.ts@@ -459,3 +459,77 @@ describe("MCP compact input schema canonical enforcement", () => {expect(ajv.validateSchema(advertised.inputSchema)).toBe(true);});});++it.each(["full", "compact"] as const)(+ "preserves nested resource validation through the %s SDK catalog and canonical handler",+ async (profile) => {+ const source = {+ $schema: "https://json-schema.org/draft/2020-12/schema",+ $id: "https://example.test/root.json",+ type: "object",+ definitions: {+ value: { type: "string" },+ child: {+ $id: "child.json",+ type: "object",+ definitions: { value: { type: "number" } },+ properties: { value: { $ref: "#/definitions/value" } },+ required: ["value"],+ additionalProperties: false,+ },+ },+ properties: { child: { $ref: "#/definitions/child" } },+ required: ["child"],+ additionalProperties: false,+ };+ const canonical = new Ajv2020({ strict: false }).compile(source);+ const registration = toolRegistrationOptions(+ toolContract("binary_session"),+ );+ const inputSchema = {+ "~standard": {+ ...registration.inputSchema["~standard"],+ vendor: "rea-resource-fixture",+ jsonSchema: {+ ...registration.inputSchema["~standard"].jsonSchema,+ input: () => source,+ },+ validate: (value: unknown) =>+ canonical(value)+ ? { value }+ : { issues: [{ message: "Invalid resource value" }] },+ },+ };+ const server = profile === "compact" ? compactServer() : fullServer();+ let calls = 0;+ server.registerTool("resource_fixture", { inputSchema }, async () => {+ calls++;+ return { content: [{ type: "text", text: "accepted" }] };+ });+ const client = new Client({ name: "resource-scope", version: "1" });+ const [ct, st] = InMemoryTransport.createLinkedPair();+ try {+ await server.connect(st);+ await client.connect(ct);+ const definition = (await client.listTools()).tools.find(+ ({ name }) => name === "resource_fixture",+ );+ if (definition === undefined) throw new Error("Missing resource fixture");+ const advertised = new Ajv2020({ strict: false }).compile(+ definition.inputSchema,+ );+ for (const value of [7, "seven"]) {+ const args = { child: { value } };+ expect(advertised(args)).toBe(canonical(args));+ const result = await client.callTool({+ name: "resource_fixture",+ arguments: args,+ });+ expect(result.isError === true).toBe(!canonical(args));+ }+ expect(calls).toBe(1);+ } finally {+ await Promise.allSettled([client.close(), server.close()]);+ }+ },+);