Module coerce 

CLI-facing value construction for set/add (cli-shell-config-todo.md §3, which supersedes the earlier cli-design-review-todo.md D3): a bare VALUE/FIELD=VALUE is always Value::String with zero coercion — no shape-guessing, no type prefixes. An exact type is requested explicitly via ValueType (set’s --value-type flag); guard_bare_overwrite implements the “异型覆盖守卫” (heterogeneous-overwrite guard) that turns a bare VALUE silently changing an existing scalar’s type into an argument error instead.

Enums

ScalarKind

The four AFDATA scalar “kinds” the heterogeneous-overwrite guard distinguishes. Number covers Integer/Unsigned/Float/ Value::Number — the guard cares whether VALUE would change a scalar from one of these kinds to a bare string, not which numeric representation was in play.

ValueType

The exact type an explicit --value-type requests for a set VALUE.

Functions

coerce_toward

Coerce a CLI string toward the type already present at existing, for a consumer that knows the target type from the value it is replacing (a config setter reading typed leaves out of a serialized document).

coerce_values_toward

Coerce a CLI value slice toward the type at existing via coerce_toward: one value becomes a scalar, several become an array whose elements are each coerced toward the existing array’s element type. An empty slice is an error.

guard_bare_overwrite

The §3 “异型覆盖守卫” (heterogeneous-overwrite guard, closing design rule 4 — “no silent type rewrites”): a bare VALUE (implicit --value-type string) is always a string, so overwriting an existing scalar of a different kind would silently change its type. That is an argument error, not a coercion decision. Returns the existing kind so the caller can build a message with the two escape hatches (--value-type <kind> to keep the type, or --value-type string to convert explicitly).

scalar_kind

The scalar kind of value, or None for an array/object (the guard does not apply to containers — see cli-shell-config-todo.md §3).

value_from_type

Construct a Value from a CLI string per an explicit ValueType.

value_matches_type

Whether value satisfies expected for a typed read — the GET-side counterpart to value_from_type. Json matches any value; Number matches every numeric representation; the rest match their one kind. A consumer that asks for a type gets a value back only when it actually is that type, so a wrong-typed leaf is a caught error rather than a surprise.