satisfies Is Not a Validator for Your Coding Agent's JSON

A coding agent encounters a type error in a JSON import workflow. It adds as ImportJob, the build turns green, and the task is reported complete. The application can now access the properties in its editor, but what changed about the bytes arriving from outside?

For maintainers reviewing TypeScript patches, the important distinction is not which syntax looks modern. It is whether a value was authored inside the checked program or arrived at runtime without the promised guarantees.

Methodology and selection criteria

We reviewed the TypeScript handbook's type assertions and narrowing sections alongside the release documentation introducing satisfies on October 12, 2026. The comparison concerns what each mechanism establishes, not compiler performance or the quality of a particular coding agent.

The import scenario and acceptance checks below are our proposed review procedure. We did not execute a third-party Skill or run these examples as a benchmark. Use the compiler and configuration pinned by your repository when checking a real patch.

Choose by the origin of the value

The TypeScript 4.9 documentation describes satisfies as checking compatibility with a target type while retaining the expression's resulting type information. That makes it useful for authored configuration whose individual properties should remain informative.

It does not turn a runtime payload into checked data. Replacing one type-level expression with another is not an input-validation strategy. Ask the agent to identify the boundary at which the external value becomes eligible for application use.

A type assertion is a claim, not a conversion

The handbook's type assertion section explains that assertions are removed during compilation and do not introduce runtime checks. An assertion does not manufacture a missing property, convert a numeric string or reject an unexpected object.

During review, require a short explanation beside any boundary assertion: which earlier operation established this shape? An upstream parser may provide that evidence. A comment saying the API always returns the type does not demonstrate it.

Be especially skeptical of a patch that introduces any, double assertions or a non-null assertion only to silence diagnostics. These constructs have legitimate uses, but the change should explain the lost check and why the application remains correct. A successful typecheck is one result, not a substitute for that explanation.

Keep parsing, validation and authorization separate

For the proposed import workflow, assign three distinct jobs.

First, parse the representation. Malformed JSON should produce a controlled failure, not an invented default job.

Second, validate the domain input. Treat the parsed value as unknown until the application checks the fields it will use. The narrowing handbook shows how runtime conditions and type predicates support more specific types. A hand-written predicate still needs a correct implementation; its declared return type is not an independent audit.

Third, check the intended action. A payload can have a valid project identifier and still refer to a project the caller cannot modify. Structural validity is not permission to import into that project. Keep the access check at the appropriate application boundary rather than encoding approval in a shape validator.

Our recommendation is to return either a validated domain value or a bounded error explanation. Avoid carrying the raw object further into the workflow and expecting every downstream component to repeat the same checks.

Give the agent a malformed-input acceptance set

Before requesting a fix, agree on the expected outcome for a small set of inputs:

• A valid minimal job: accepted with its intended values preserved.
• A missing required field: rejected with an actionable field-level explanation.
• A wrong primitive type: rejected, unless a specific normalization rule was approved.
• An unknown operation name: rejected rather than mapped to a convenient default.
• A structurally valid but unauthorized target: denied by the permission check.
• An extra field: handled according to an explicit strip, retain or reject policy.

These are proposed cases, not reported test results. Include the actual failure that motivated the patch. If the agent changes a validator, ask it to run both the failing case and an ordinary valid input; otherwise a repair that rejects everything may appear successful.

The deliverable should name the validator, show where its output enters the application and preserve the observed test outcomes. Keep raw payloads out of logs when they contain private content.

Limitations and a practical handoff

Hand-written checks become harder to maintain as shapes grow. A schema library can centralize that work, but adopting one adds dependencies and does not settle business rules automatically. Review its behavior for coercion, unknown fields and version changes before standardizing it.

For a source-maintained configuration, a runtime validation layer may be unnecessary overhead. For external input, type syntax alone is insufficient. The right repair depends on the boundary, not a blanket rule to replace every assertion.

When selecting a coding workflow from the Skill directory, look for an explicit distinction between passing compilation and validating inputs. Our guide to where agent review rules belong can help turn that distinction into a reusable review requirement.