@openclaw/matrix 2026.9.4 → 2026.9.6

package/node_modules/zod/src/v4/classic/tests/from-json-schema.test.ts

@@ -54,6 +54,33 @@ test("number with constraints", () => {
   expect(() => schema.parse(47)).toThrow(); // not multiple of 5
 });
 
+test("draft-04 boolean exclusive bounds do not emit a redundant inclusive bound", () => {
+  const schema = fromJSONSchema({
+    type: "number",
+    minimum: 5,
+    maximum: 10,
+    exclusiveMinimum: true,
+    exclusiveMaximum: true,
+  });
+  // exclusive on both ends: boundaries rejected, interior accepted
+  expect(() => schema.parse(5)).toThrow();
+  expect(() => schema.parse(10)).toThrow();
+  expect(schema.parse(7)).toBe(7);
+  // the dominated inclusive bound would otherwise report a second, weaker issue alongside the exclusive one
+  expect(schema.safeParse(4).error!.issues).toHaveLength(1);
+  expect(schema.safeParse(11).error!.issues).toHaveLength(1);
+  // the inclusive .min()/.max() must be skipped so only the exclusive checks remain
+  const checks = (schema as any)._zod.def.checks.map((c: any) => [
+    c._zod.def.check,
+    c._zod.def.value,
+    c._zod.def.inclusive,
+  ]);
+  expect(checks).toEqual([
+    ["greater_than", 5, false],
+    ["less_than", 10, false],
+  ]);
+});
+
 test("integer schema", () => {
   const schema = fromJSONSchema({ type: "integer" });
   expect(schema.parse(42)).toBe(42);
@@ -127,11 +154,76 @@ test("tuple with prefixItems (draft-2020-12)", () => {
     type: "array",
     prefixItems: [{ type: "string" }, { type: "number" }],
   });
+  expect(schema.parse([])).toEqual([]);
+  expect(schema.parse(["hello"])).toEqual(["hello"]);
   expect(schema.parse(["hello", 42])).toEqual(["hello", 42]);
-  expect(() => schema.parse(["hello"])).toThrow();
+  // no `items`, so the tail is unconstrained
+  expect(schema.parse(["hello", 42, "extra"])).toEqual(["hello", 42, "extra"]);
+  expect(() => schema.parse([1])).toThrow();
   expect(() => schema.parse(["hello", "world"])).toThrow();
 });
 
+test("tuple with prefixItems and minItems (draft-2020-12)", () => {
+  const partialItems = fromJSONSchema({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "array",
+    prefixItems: [{ type: "string" }, { type: "number" }],
+    minItems: 1,
+  });
+  expect(() => partialItems.parse([])).toThrow();
+  expect(partialItems.parse(["hello"])).toEqual(["hello"]);
+
+  const allRequired = fromJSONSchema({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "array",
+    prefixItems: [{ type: "string" }, { type: "number" }],
+    minItems: 2,
+  });
+  expect(() => allRequired.parse(["hello"])).toThrow();
+  expect(allRequired.parse(["hello", 42])).toEqual(["hello", 42]);
+});
+
+test("tuple with prefixItems allows extra items by default (draft-2020-12)", () => {
+  const schema = fromJSONSchema({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "array",
+    prefixItems: [{ type: "string" }],
+  });
+  expect(schema.parse(["hello", 42, true])).toEqual(["hello", 42, true]);
+});
+
+test("tuple with prefixItems respects items schema (draft-2020-12)", () => {
+  const schema = fromJSONSchema({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "array",
+    prefixItems: [{ type: "string" }],
+    items: { type: "number" },
+  });
+  expect(schema.parse(["hello", 1, 2])).toEqual(["hello", 1, 2]);
+  expect(() => schema.parse(["hello", 1, "extra"])).toThrow();
+});
+
+test("tuple with prefixItems and items true allows extra items (draft-2020-12)", () => {
+  const schema = fromJSONSchema({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "array",
+    prefixItems: [{ type: "string" }, { type: "number" }],
+    items: true,
+  });
+  expect(schema.parse(["hello", 42, "extra", true])).toEqual(["hello", 42, "extra", true]);
+});
+
+test("tuple with prefixItems and items false rejects extra items (draft-2020-12)", () => {
+  const schema = fromJSONSchema({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "array",
+    prefixItems: [{ type: "string" }],
+    items: false,
+  });
+  expect(schema.parse(["hello"])).toEqual(["hello"]);
+  expect(() => schema.parse(["hello", 42])).toThrow();
+});
+
 test("tuple with items array (draft-7)", () => {
   const schema = fromJSONSchema({
     $schema: "http://json-schema.org/draft-07/schema#",
@@ -139,10 +231,66 @@ test("tuple with items array (draft-7)", () => {
     items: [{ type: "string" }, { type: "number" }],
     additionalItems: false,
   });
+  expect(schema.parse([])).toEqual([]);
+  expect(schema.parse(["hello"])).toEqual(["hello"]);
   expect(schema.parse(["hello", 42])).toEqual(["hello", 42]);
+  expect(() => schema.parse([1])).toThrow();
+  expect(() => schema.parse(["hello", "world"])).toThrow();
   expect(() => schema.parse(["hello", 42, "extra"])).toThrow();
 });
 
+test("tuple with items array and minItems (draft-7)", () => {
+  const partialItems = fromJSONSchema({
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "array",
+    items: [{ type: "string" }, { type: "number" }],
+    additionalItems: false,
+    minItems: 1,
+  });
+  expect(() => partialItems.parse([])).toThrow();
+  expect(partialItems.parse(["hello"])).toEqual(["hello"]);
+
+  const allRequired = fromJSONSchema({
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "array",
+    items: [{ type: "string" }, { type: "number" }],
+    additionalItems: false,
+    minItems: 2,
+  });
+  expect(() => allRequired.parse(["hello"])).toThrow();
+  expect(allRequired.parse(["hello", 42])).toEqual(["hello", 42]);
+});
+
+test("tuple with items array allows extra items by default (draft-7)", () => {
+  const schema = fromJSONSchema({
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "array",
+    items: [{ type: "string" }],
+  });
+  expect(schema.parse(["hello", 42, true])).toEqual(["hello", 42, true]);
+});
+
+test("tuple with items array and additionalItems true allows extra items (draft-7)", () => {
+  const schema = fromJSONSchema({
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "array",
+    items: [{ type: "string" }, { type: "number" }],
+    additionalItems: true,
+  });
+  expect(schema.parse(["hello", 42, "extra", true])).toEqual(["hello", 42, "extra", true]);
+});
+
+test("tuple with items array respects additionalItems schema (draft-7)", () => {
+  const schema = fromJSONSchema({
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "array",
+    items: [{ type: "string" }],
+    additionalItems: { type: "number" },
+  });
+  expect(schema.parse(["hello", 1, 2])).toEqual(["hello", 1, 2]);
+  expect(() => schema.parse(["hello", 1, "extra"])).toThrow();
+});
+
 test("enum schema", () => {
   const schema = fromJSONSchema({
     enum: ["red", "green", "blue"],
@@ -299,6 +447,15 @@ test("local $ref resolution", () => {
   expect(() => schema.parse({})).toThrow();
 });
 
+test("local $ref resolution unescapes JSON Pointer tokens", () => {
+  // `~1` must be decoded before `~0`, so the id "a~1b" survives as itself and not as "a/b".
+  for (const id of ["Shared/User", "My~Model", "a~b/c", "a~1b"]) {
+    const inner = z.object({ name: z.string() }).meta({ id });
+    const schema = fromJSONSchema(z.toJSONSchema(z.object({ inner })));
+    expect(schema.parse({ inner: { name: "John" } })).toEqual({ inner: { name: "John" } });
+  }
+});
+
 test("circular $ref with lazy", () => {
   const schema = fromJSONSchema({
     $defs: {
@@ -336,10 +493,156 @@ test("patternProperties", () => {
   expect(result.S_age).toBe("30");
 });
 
+test("propertyNames with enum does not require keys", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    propertyNames: { enum: ["a", "b"] },
+    additionalProperties: { type: "string" },
+  });
+  expect(schema.parse({ a: "x" })).toEqual({ a: "x" });
+  expect(schema.parse({ b: "y" })).toEqual({ b: "y" });
+  expect(schema.parse({})).toEqual({});
+  expect(() => schema.parse({ c: "z" })).toThrow();
+});
+
+test("propertyNames with enum alongside properties", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    properties: { a: { type: "string" } },
+    propertyNames: { enum: ["a", "b"] },
+    additionalProperties: { type: "string" },
+  });
+  expect(schema.parse({ a: "x" })).toEqual({ a: "x" });
+  expect(schema.parse({})).toEqual({});
+  expect(() => schema.parse({ c: "z" })).toThrow();
+  expect(() => schema.parse({ a: "x", c: "z" })).toThrow();
+});
+
+test("propertyNames with enum still honors required", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    properties: { a: { type: "string" }, b: { type: "string" } },
+    required: ["a"],
+    propertyNames: { enum: ["a", "b"] },
+    additionalProperties: { type: "string" },
+  });
+  expect(schema.parse({ a: "x" })).toEqual({ a: "x" });
+  expect(schema.parse({ a: "x", b: "y" })).toEqual({ a: "x", b: "y" });
+  expect(() => schema.parse({})).toThrow();
+  expect(() => schema.parse({ b: "y" })).toThrow();
+});
+
+test("propertyNames does not apply additionalProperties to declared properties", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    properties: { a: { type: "number" } },
+    propertyNames: { enum: ["a", "b"] },
+    additionalProperties: { type: "string" },
+  });
+  expect(schema.parse({ a: 1 })).toEqual({ a: 1 });
+  expect(schema.parse({ a: 1, b: "x" })).toEqual({ a: 1, b: "x" });
+  expect(() => schema.parse({ b: 1 })).toThrow();
+});
+
+test("propertyNames alongside additionalProperties: false", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    properties: { a: { type: "string" } },
+    propertyNames: { enum: ["a", "b"] },
+    additionalProperties: false,
+  });
+  expect(schema.parse({ a: "x" })).toEqual({ a: "x" });
+  expect(() => schema.parse({ a: "x", b: "y" })).toThrow();
+  expect(() => schema.parse({ c: "z" })).toThrow();
+});
+
+test("propertyNames alongside patternProperties", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    patternProperties: { "^S_": { type: "string" } },
+    propertyNames: { type: "string", pattern: "^S_" },
+  });
+  expect(schema.parse({ S_a: "x" })).toEqual({ S_a: "x" });
+  expect(() => schema.parse({ S_a: 1 })).toThrow();
+  expect(() => schema.parse({ other: "x" })).toThrow();
+});
+
+test("propertyNames rejects keys the object parse would drop or synthesize", () => {
+  const schema = fromJSONSchema({ type: "object", propertyNames: { enum: ["a"] } });
+  // An object parse strips `__proto__`, so the guard has to see the raw input.
+  expect(() => schema.parse(JSON.parse('{"__proto__":1}'))).toThrow();
+
+  // A property `default` adds a key that was never in the instance.
+  const withDefault = fromJSONSchema({
+    type: "object",
+    properties: { AB: { type: "string", default: "x" } },
+    propertyNames: { type: "string", pattern: "^[a-z]+$" },
+  });
+  expect(withDefault.parse({})).toEqual({ AB: "x" });
+});
+
+test("propertyNames subschema without a type still constrains keys", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    propertyNames: { pattern: "^[A-Za-z_][A-Za-z0-9_]*$" },
+  });
+  expect(schema.parse({ valid_key: "x" })).toEqual({ valid_key: "x" });
+  expect(() => schema.parse({ "001 invalid": "x" })).toThrow();
+});
+
+test("boolean propertyNames", () => {
+  expect(() => fromJSONSchema({ type: "object", propertyNames: false }).parse({ a: 1 })).toThrow();
+  expect(fromJSONSchema({ type: "object", propertyNames: false }).parse({})).toEqual({});
+  expect(fromJSONSchema({ type: "object", propertyNames: true }).parse({ anything: 1 })).toEqual({ anything: 1 });
+});
+
+test("propertyNames metadata is not attached where it is inert", () => {
+  // Not an object: nothing enforces it, so it must not be advertised either.
+  expect(z.toJSONSchema(fromJSONSchema({ type: "string", propertyNames: { enum: ["a"] } }))).not.toHaveProperty(
+    "propertyNames"
+  );
+
+  // A $ref target is shared by every reference to it; metadata must not leak onto it.
+  const shared = z.toJSONSchema(
+    fromJSONSchema({
+      $defs: { N: { type: "object", properties: { v: { type: "string" } } } },
+      type: "object",
+      properties: { a: { $ref: "#/$defs/N", propertyNames: { enum: ["v"] } }, b: { $ref: "#/$defs/N" } },
+    })
+  ) as any;
+  expect(shared.properties.b).not.toHaveProperty("propertyNames");
+});
+
+test("propertyNames survives a toJSONSchema round trip", () => {
+  const roundTripped = z.toJSONSchema(
+    fromJSONSchema({
+      type: "object",
+      propertyNames: { enum: ["a", "b"] },
+      additionalProperties: { type: "string" },
+    })
+  ) as Record<string, unknown>;
+  expect(roundTripped.propertyNames).toEqual({ enum: ["a", "b"] });
+  expect(roundTripped.required).toBeUndefined();
+
+  // The key guard is a pipe; neither side may swallow the object it wraps.
+  for (const io of ["input", "output"] as const) {
+    const out = z.toJSONSchema(
+      fromJSONSchema({
+        type: "object",
+        properties: { a: { type: "string" } },
+        propertyNames: { enum: ["a", "b"] },
+        additionalProperties: { type: "string" },
+      }),
+      { io }
+    ) as Record<string, unknown>;
+    expect(out.type).toBe("object");
+    expect(out.properties).toEqual({ a: { type: "string" } });
+    expect(out.propertyNames).toEqual({ enum: ["a", "b"] });
+  }
+});
+
 test("patternProperties with regular properties", () => {
-  // Note: When patternProperties is combined with properties, the intersection
-  // validates all keys against the pattern. This test uses a pattern that
-  // matches the regular property name as well.
+  // Note: When patternProperties is combined with properties, the intersection validates all keys against the pattern. This test uses a pattern that matches the regular property name as well.
   const schema = fromJSONSchema({
     type: "object",
     properties: {
@@ -387,13 +690,55 @@ test("multiple overlapping patternProperties", () => {
   expect(() => schema.parse({ S_N: "ab" })).toThrow(); // too short for ^S_N pattern
 });
 
+test("patternProperties with additionalProperties false", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    patternProperties: {
+      "^S_": { type: "string" },
+    },
+    additionalProperties: false,
+  });
+  expect(schema.parse({ S_name: "ok" })).toEqual({ S_name: "ok" });
+  expect(() => schema.parse({ X_A: false })).toThrow();
+  expect(() => schema.parse({ S_name: 1 })).toThrow();
+});
+
+test("patternProperties and properties with additionalProperties false", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    properties: {
+      name: { type: "string" },
+    },
+    patternProperties: {
+      "^S_": { type: "string" },
+    },
+    additionalProperties: false,
+    required: ["name"],
+  });
+  expect(schema.parse({ name: "ok", S_count: "1" })).toEqual({ name: "ok", S_count: "1" });
+  expect(() => schema.parse({ name: "ok", S_count: 1 })).toThrow();
+  expect(() => schema.parse({ name: "ok", other: "value" })).toThrow();
+});
+
+test("multiple patternProperties with additionalProperties false", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    patternProperties: {
+      "^S_": { type: "string" },
+      "^N_": { type: "number" },
+    },
+    additionalProperties: false,
+  });
+  expect(schema.parse({ S_a: "a", N_b: 1 })).toEqual({ S_a: "a", N_b: 1 });
+  expect(() => schema.parse({ S_a: "a", N_b: 1, other: "value" })).toThrow();
+});
+
 test("default value", () => {
   const schema = fromJSONSchema({
     type: "string",
     default: "hello",
   });
-  // Default is applied during parsing if value is missing/undefined
-  // This depends on Zod's default behavior
+  // Default is applied during parsing if value is missing/undefined. This depends on Zod's default behavior
   expect(schema.parse("world")).toBe("world");
 });
 
@@ -457,6 +802,53 @@ test("string format - uuid", () => {
   expect(schema.parse(uuid)).toBe(uuid);
 });
 
+test("string format - date-time", () => {
+  const schema = fromJSONSchema({
+    type: "string",
+    format: "date-time",
+  });
+  expect(schema.safeParse("2026-07-29T14:30:00Z").success).toBe(true);
+  expect(schema.safeParse("2026-07-29T16:30:00+02:00").success).toBe(true);
+  expect(schema.safeParse("2026-07-29T14:30:00").success).toBe(false);
+  expect(schema.safeParse("2026-07-29T16:30:00+0200").success).toBe(false);
+
+  const zuluOnly = fromJSONSchema({
+    type: "string",
+    format: "date-time",
+    pattern: "Z$",
+  });
+  expect(zuluOnly.safeParse("2026-07-29T14:30:00Z").success).toBe(true);
+  expect(zuluOnly.safeParse("2026-07-29T16:30:00+02:00").success).toBe(false);
+  expect(zuluOnly.safeParse("garbageZ").success).toBe(false);
+
+  const roundTripped = fromJSONSchema(z.toJSONSchema(z.iso.datetime({ offset: true })));
+  expect(roundTripped.safeParse("2026-07-29T16:30:00+02:00").success).toBe(true);
+});
+
+test("string format - time", () => {
+  const schema = fromJSONSchema({
+    type: "string",
+    format: "time",
+  });
+  // full-time, so seconds and an offset are both required
+  expect(schema.safeParse("14:30:00Z").success).toBe(true);
+  expect(schema.safeParse("16:30:00+02:00").success).toBe(true);
+  expect(schema.safeParse("16:30:00.123-05:30").success).toBe(true);
+  expect(schema.safeParse("14:30:00").success).toBe(false);
+  expect(schema.safeParse("14:30Z").success).toBe(false);
+  expect(schema.safeParse("16:30:00+0200").success).toBe(false);
+  expect(schema.safeParse("16:30:00+24:00").success).toBe(false);
+});
+
+test("string format - hostname", () => {
+  const schema = fromJSONSchema({
+    type: "string",
+    format: "hostname",
+  });
+  expect(schema.parse("example.com")).toBe("example.com");
+  expect(() => schema.parse("not a hostname!")).toThrow();
+});
+
 test("exclusiveMinimum and exclusiveMaximum", () => {
   const schema = fromJSONSchema({
     type: "number",
@@ -648,8 +1040,7 @@ test("metadata on nested schemas", () => {
   // Verify parent schema has its metadata
   expect(customRegistry.get(parentSchema)?.title).toBe("User");
 
-  // We can't easily access nested schemas directly, but we can verify
-  // the registry is being used correctly by checking a separate schema
+  // We can't easily access nested schemas directly, but we can verify the registry is being used correctly by checking a separate schema
   const simpleSchema = fromJSONSchema(
     {
       type: "string",
@@ -673,8 +1064,7 @@ test("no metadata added when no unrecognized keys", () => {
     { registry: customRegistry }
   );
 
-  // description is handled via .describe(), so it shouldn't be in metadata
-  // All other keys are recognized, so no metadata should be added
+  // description is handled via .describe(), so it shouldn't be in metadata. All other keys are recognized, so no metadata should be added
   expect(customRegistry.get(schema)).toBeUndefined();
 });
 
@@ -893,3 +1283,185 @@ test("Date default is coerced to its JSON string form", () => {
   const schema = fromJSONSchema({ type: "string", default: date as any });
   expect(schema.parse(undefined)).toBe(date.toISOString());
 });
+
+// An object literal can't express an own "__proto__" key — `{ __proto__: x }` sets the literal's prototype instead. JSON.parse is both the realistic source of a JSON Schema and the only way to write these cases.
+test("required __proto__ property is represented in the shape but stripped during parsing", () => {
+  const schema = fromJSONSchema(
+    JSON.parse(`{
+      "type": "object",
+      "properties": { "__proto__": { "type": "string", "const": "admin" }, "role": { "type": "string" } },
+      "required": ["__proto__", "role"]
+    }`)
+  );
+
+  expect(Object.prototype.hasOwnProperty.call((schema as z.ZodObject).shape, "__proto__")).toBe(true);
+  expect(schema.parse({ role: "x" })).toEqual({ role: "x" });
+  expect(schema.parse(JSON.parse(`{ "role": "x", "__proto__": "wrong" }`))).toEqual({ role: "x" });
+  expect(schema.parse(JSON.parse(`{ "role": "x", "__proto__": "admin" }`))).toEqual({ role: "x" });
+});
+
+test("__proto__ annotation key reaches the registry", () => {
+  const registry = z.registry<Record<string, unknown>>();
+  const schema = fromJSONSchema(JSON.parse(`{ "type": "string", "__proto__": { "custom": 1 } }`), { registry });
+
+  const meta = registry.get(schema)!;
+  expect(Object.prototype.hasOwnProperty.call(meta, "__proto__")).toBe(true);
+  expect(meta.__proto__).toEqual({ custom: 1 });
+});
+
+test("minProperties and maxProperties count the raw input", () => {
+  const schema = fromJSONSchema({
+    type: "object",
+    properties: { a: { type: "string" } },
+    minProperties: 1,
+    maxProperties: 2,
+  });
+  expect(schema.safeParse({ a: "x" }).success).toBe(true);
+  expect(schema.safeParse({}).error!.issues[0]).toMatchObject({ code: "too_small", origin: "object", minimum: 1 });
+  expect(schema.safeParse({ a: "x", b: 1, c: 2 }).error!.issues[0]).toMatchObject({
+    code: "too_big",
+    origin: "object",
+    maximum: 2,
+  });
+  // raw input: a defaulted property does not satisfy the minimum, and a dropped __proto__ still counts
+  const defaulted = fromJSONSchema({
+    type: "object",
+    properties: { a: { type: "string", default: "x" } },
+    minProperties: 1,
+  });
+  expect(defaulted.safeParse({}).success).toBe(false);
+  const capped = fromJSONSchema({ type: "object", maxProperties: 1 });
+  expect(capped.safeParse(JSON.parse('{"__proto__":1,"a":1}')).success).toBe(false);
+  expect(z.toJSONSchema(schema)).toMatchObject({ minProperties: 1, maxProperties: 2 });
+});
+
+test("minProperties composes with propertyNames in one guard", () => {
+  const schema = fromJSONSchema({ type: "object", propertyNames: { pattern: "^a" }, minProperties: 1 });
+  expect(schema.safeParse({}).error!.issues[0]!.code).toBe("too_small");
+  expect(schema.safeParse({ b: 1 }).error!.issues[0]!.code).toBe("invalid_key");
+  expect(schema.safeParse({ a: 1 }).success).toBe(true);
+});
+
+test("uniqueItems rejects structural duplicates", () => {
+  const schema = fromJSONSchema({ type: "array", uniqueItems: true });
+  expect(
+    schema.safeParse([
+      { a: 1, b: 2 },
+      { b: 2, a: 1 },
+    ]).error!.issues[0]
+  ).toMatchObject({
+    code: "custom",
+    path: [1],
+  });
+  expect(schema.safeParse([1, "1", true, 1]).success).toBe(false);
+  expect(schema.safeParse([{ a: 1 }, { a: 2 }, [1], [2]]).success).toBe(true);
+  expect(z.toJSONSchema(schema)).toMatchObject({ uniqueItems: true });
+});
+
+test("contains with minContains and maxContains", () => {
+  const schema = fromJSONSchema({ type: "array", contains: { type: "integer" } });
+  expect(schema.safeParse(["a"]).success).toBe(false);
+  expect(schema.safeParse(["a", 1]).success).toBe(true);
+  const bounded = fromJSONSchema({ type: "array", contains: { type: "integer" }, minContains: 2, maxContains: 3 });
+  expect(bounded.safeParse([1, "a"]).success).toBe(false);
+  expect(bounded.safeParse([1, 2, "a"]).success).toBe(true);
+  expect(bounded.safeParse([1, 2, 3, 4]).success).toBe(false);
+  // minContains: 0 accepts an array with no matches at all
+  expect(fromJSONSchema({ type: "array", contains: { type: "integer" }, minContains: 0 }).safeParse([]).success).toBe(
+    true
+  );
+  expect(z.toJSONSchema(bounded)).toMatchObject({ contains: { type: "integer" }, minContains: 2, maxContains: 3 });
+});
+
+test("uniqueItems and contains see the raw instance, not the parsed output", () => {
+  const items = { type: "object", properties: { a: { type: "string", default: "x" } } } as const;
+  // no instance item carries `a`; the default must not synthesize the match
+  const contains = fromJSONSchema({
+    type: "array",
+    items,
+    contains: { type: "object", properties: { a: { const: "x" } }, required: ["a"] },
+  });
+  expect(contains.safeParse([{}]).success).toBe(false);
+  expect(contains.safeParse([{ a: "x" }]).success).toBe(true);
+  // the instance items differ; the default must not collapse them into duplicates
+  const unique = fromJSONSchema({ type: "array", items, uniqueItems: true });
+  expect(unique.safeParse([{ a: "x" }, {}]).success).toBe(true);
+  expect(unique.safeParse([{}, {}]).error!.issues[0]).toMatchObject({ code: "custom", path: [1] });
+});
+
+test("a guard keyword takes precedence over the length keywords", () => {
+  const schema = fromJSONSchema({ type: "array", items: { type: "integer" }, minItems: 3, uniqueItems: true });
+  // the guard runs on the input side of the pipe, so its issue aborts before minItems is reached
+  expect(schema.safeParse([1, 1]).error!.issues.map((i) => i.code)).toEqual(["custom"]);
+  expect(schema.safeParse([1, 2]).error!.issues.map((i) => i.code)).toEqual(["too_small"]);
+});
+
+test("a guard keyword drops default and examples from the input-mode document", () => {
+  // the guard is a transform on the pipe's input side, and toJSONSchema strips annotations from a transforming schema in input mode
+  const schema = fromJSONSchema({ type: "array", uniqueItems: true, default: [], examples: [[1]] });
+  expect(z.toJSONSchema(schema, { io: "input" })).not.toHaveProperty("default");
+  expect(z.toJSONSchema(schema, { io: "output" })).toMatchObject({ default: [], examples: [[1]] });
+  // without a guard keyword both modes carry them
+  const plain = fromJSONSchema({ type: "array", default: [], examples: [[1]] });
+  expect(z.toJSONSchema(plain, { io: "input" })).toMatchObject({ default: [], examples: [[1]] });
+});
+
+test("uniqueItems equality follows JSON semantics", () => {
+  const schema = fromJSONSchema({ type: "array", uniqueItems: true });
+  expect(schema.safeParse([1, "1", true, null]).success).toBe(true);
+  expect(schema.safeParse([{ a: undefined }, {}]).success).toBe(true);
+  expect(
+    schema.safeParse([
+      [1, [2]],
+      [1, [2]],
+    ]).success
+  ).toBe(false);
+  expect(schema.safeParse([{ a: "b=c" }, { "a=b": "c" }]).success).toBe(true);
+  // every duplicate is reported against the first element it matches
+  expect(schema.safeParse([1, 1, 1]).error!.issues.map((i) => i.path[0])).toEqual([1, 2]);
+  // a cycle cannot be compared, so it is never called a duplicate rather than hanging
+  const cyclic: any = {};
+  cyclic.self = cyclic;
+  expect(schema.safeParse([cyclic, cyclic]).success).toBe(true);
+});
+
+test("a carried subschema that references $defs is dropped rather than emitted dangling", () => {
+  const schema = fromJSONSchema({
+    type: "array",
+    contains: { $ref: "#/$defs/Hit" },
+    $defs: { Hit: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+  });
+  // enforcement is unaffected; only the round trip gives the keyword up
+  expect(schema.safeParse([{ id: "a" }]).success).toBe(true);
+  expect(schema.safeParse([{}]).success).toBe(false);
+  expect(JSON.stringify(z.toJSONSchema(schema))).not.toContain("$ref");
+  expect(z.toJSONSchema(schema)).not.toHaveProperty("contains");
+  // an inline subschema is self-contained, so it still round-trips
+  const inline = fromJSONSchema({ type: "array", contains: { type: "integer" } });
+  expect(z.toJSONSchema(inline)).toMatchObject({ contains: { type: "integer" } });
+  // only schema positions are walked, so a `$ref` key in instance data or an unknown annotation still travels
+  for (const annotation of [{ default: { $ref: "literal" } }, { "x-note": { $ref: "literal" } }]) {
+    const annotated = fromJSONSchema({ type: "array", contains: { type: "integer", ...annotation } });
+    expect(annotated.safeParse(["x"]).success).toBe(false);
+    expect(z.toJSONSchema(annotated)).toMatchObject({ contains: { type: "integer" } });
+  }
+  // draft-7 `dependencies` is a schema map; its array form names properties and holds no reference
+  const dependent = fromJSONSchema({
+    type: "array",
+    contains: { type: "object", dependencies: { a: { $ref: "#/definitions/Hit" } } },
+    definitions: { Hit: { type: "object" } },
+  });
+  expect(z.toJSONSchema(dependent)).not.toHaveProperty("contains");
+  const named = fromJSONSchema({
+    type: "array",
+    contains: { type: "object", dependencies: { a: ["b"] } },
+  });
+  expect(z.toJSONSchema(named)).toMatchObject({ contains: { dependencies: { a: ["b"] } } });
+  // a reference nested in a schema position is still caught
+  const nested = fromJSONSchema({
+    type: "array",
+    contains: { type: "array", items: { $ref: "#/$defs/Hit" } },
+    $defs: { Hit: { type: "string" } },
+  });
+  expect(z.toJSONSchema(nested)).not.toHaveProperty("contains");
+});