docs: document structural transformations, apply required/partial to array elements

[lprnmns]

Problem

On current main, applying .partial() to a type with a root .narrow() predicate silently removes that predicate. For example, a narrowed user type accepts { email: "bad" } after .partial() and no longer enforces the original validation.

Fix

Reject .partial() when the object branch contains a root predicate. Since .partial() makes originally required properties optional, an arbitrary predicate cannot be preserved safely; the explicit ParseError prevents a silent validation change.

Tests

• pnpm testTyped --skipTypes --grep rejects ark/type/__tests__/narrow.test.ts — passed
• pnpm test — passed; 1,712 tests
• pnpm lint — passed
• pnpm prChecks — passed

Compatibility

Unrefined partial types and nested property predicates retain their existing behavior. Calls that previously created an unconstrained partial type from a root-predicate type now fail at construction with a clear ParseError instead of silently weakening validation.

Related issue

Fixes #1596

[pullfrog]

Important

The partial guard closes the silent predicate-drop for .partial(), but the identical hole remains open through .required() — see the inline comment on the guard.

Reviewed changes — .partial() on a type carrying a root predicate (via .narrow() or .filter(), including inside unions) now throws partial cannot be applied to a type with a predicate at construction instead of silently producing a partial type with the predicate stripped; a regression test pins the throw. I reproduced the original bug on the current head and confirmed the guard fires, the new test is load-bearing (it fails on the unfixed code), and existing nested-prop-predicate behavior is untouched as claimed.

• ark/schema/roots/root.ts — new guard in applyStructuralOperation that throws a ParseError when operation === "partial" and the branch is an intersection carrying a root predicate.
• ark/type/__tests__/narrow.test.ts — rejects narrowed types asserts User.partial() throws with the exact message.

ℹ️ Breaking behavior not recorded in CHANGELOG

The Compatibility note in the PR description acknowledges that calls which previously returned a partial type now throw, but the unreleased section of ark/type/CHANGELOG.md (2.2.3) gets no entry. Existing fixes in that section credit contributors, so one line here keeps the break documented when 2.2.3 ships.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

The partial guard closes one entrance to the silent predicate-drop, but .required() still hits it: type({ name: "string", email: "string" }).narrow(u => u.email.includes("@")).required() accepts { name: "Yi", email: "bad" } even though the narrowed type rejects it. required reaches the same drop because the intersection node rebuilt below at lines ~345-348 omits predicate for every structural operation, not just partial.

Technical details

# `.required()` still silently drops root predicates

## Affected sites
- ark/schema/roots/root.ts:345-348 — the rebuilt `intersection` node passes only `domain` + `structure`, dropping `branch.inner.predicate` for all structural ops; the new guard only special-cases `operation === "partial"`.
- Repro (verified on head): `type({ name: "string", email: "string" }).narrow(u => u.email.includes("@")).required()` accepts `{ name: "Yi", email: "bad" }` (original narrowed type rejects it).

## Required outcome
- No silent predicate loss for `required`. Prefer preserving the predicate for `required` — every value accepted by the required shape was already accepted by the pre-op shape, so the predicate stays well-defined — or reject it like `partial` does. At minimum, file the remaining hole before merge rather than leaving it implicit.

## Open questions for the human
- Is the `partial`-only line deliberate? The existing `merge` behavior is pinned by the "structural operation removes narrow" test (ark/type/__tests__/objects/props.test.ts:75), so the maintainer may want a uniform stance or per-operation policies (partial = reject, required = preserve, merge = drop, as today).

[ssalbdivad]

Thanks for digging into this - partial quietly dropping a root narrow is a real problem and it's the kind of thing that's easy to miss until it bites someone in production, so I appreciate you chasing it down with a repro and a test.

I went a different direction than throwing, though. merge, pick, omit, required and map all drop a root predicate through the same path, because each returns a new object built from the properties it extracts - rejecting two of the six would be inconsistent. So I've documented the behavior instead and left the description above as you wrote it. Here's what's on the branch now.

Both of your commits are reverted, so partial and required still succeed on a narrowed type.

Docs: a structural transformations section in the objects docs, linked from the merge, pick / omit, required / partial and map sections, plus a matching JSDoc note on all six methods.

Arrays: required and partial now preserve an array or tuple base and apply to its elements - type(["string", "number"]).partial() is [string?, number?], and type("string[]").partial() no longer accepts {}.