v2: spec batch 2 — strict input JSON, the positional export with mixed-body decline, column_defaults, error reasons, known-crash list (ABI v2 d5323993) by EricAndrechek · Pull Request #655 · Wave-RF/chtypes

EricAndrechek · 2026-10-19T21:00:04Z

What spec batch 2 changes (ABI v2 dev)

Input JSON is strict everywhere; the library refuses an unknown key.
The export stays JSONCompactEachRow with one export_columns list. A body that mixes deferred and server-filled defaults declines with defer-defaults-mixed-body, only when an export is asked for.
column_defaults: where the server would fill a column from its DEFAULT, the caller's value is used.
records, graphite_rollup, identity and session are absent.
Rule r8 documents the known-crash list (known-crash-declined at create).
Errors carry a reason (chs_error_reason, errors.fields in sdk.json); documents carry reason, refused_at, refused_row, verdict_reason; a value that is not UTF-8 is {"b64": ...}; options documents (insert_options, filter_options, schema_options) on the calls that take them.

This PR integrates the four bindings that implement it (Go, Python, TypeScript, Rust) onto the spec batch 2 base, merges v2 (including build-level revocation), and adds the generator, parity-tool and doc follow-ups the ports found.

Fingerprint proof (measured, on the head)

gen.py --write (v1 and --major 2): no diff.
gen.py --check and gen.py --major 2 --check: exit 0.
gen.py --major 2 --fingerprint: sha256:d53239933966e15a3c363e631a94fbba1231d84c4300337115d3ae5377bb41c2, unchanged from the spec batch 2 base. spec/abi-v2/ and include/v2/chtypes.h are not touched by this PR beyond what v2 itself brought.

Beyond the ports

CODE_DECLINED. docs/reference/bindings-v1.md promises a declined-code constant (CHS_CODE_DECLINED, -2) in every binding, but only Go's emitter generated one. The generator now emits CODE_DECLINED = -2 into Python's generated vocabulary (exported from chtypes), CODE_DECLINED into TypeScript's vocab.gen.ts (exported from the package), and pub const CODE_DECLINED: i32 = -2 for Rust at the crate root (chtypes::CODE_DECLINED; not code::DECLINED, because code is the generated fetch-code table, and the doc's Rust cell now says so). The TS parity allow entry that carried the gap is removed. This is a maintainer-visible naming call.
scripts/parity-surface.py now reads the description of the major the bindings speak (spec/binding-majors.json, v1 where absent) and refuses mixed majors; its selftest covers both. Before, every v2 vocabulary growth read as drift (Source: 13 members vs 11).
docs/guides/settings.md describes the {"b64": ...} form and which bindings can send it. Rust cannot: it takes String.

Per-binding surface

Concern	Go	Python	TypeScript	Rust
insertable columns	`WithInsertableColumns`	`insertable_columns=`	`insertableColumns`	`insertable_columns`
column defaults	`WithColumnDefaults([]ColumnDefault)`	`column_defaults=` (`ColumnDefault`)	`columnDefaults`	`column_defaults`
verdict basis	`WithVerdictBasis`	`verdict_basis=`	`verdictBasis`	`verdict_basis`
defer defaults	`WithDeferDefaults`	`defer_defaults=`	`deferDefaults`	`defer_defaults`
raw option pass-through	`WithInsertOption` / `WithFilterOption` / `WithSchemaOption`	`*_options_extra=`	`*OptionsExtra`	`*_options_extra` (key, JSON text)
param encoding	`WithParamEncoding`	`param_encoding=`	`paramEncoding`	`param_encoding`
posture	`WithPosture`	`posture=`	`posture`	`posture`
error reason	`CallError.Reason`	`CallError.reason`	`CallError.reason`	`CallError::reason`
spans	`[]*Span`, nil = not exported	`tuple[Span or None]`	`(Span or null)[]`	nullable `spans`
non-UTF-8 value	any `string`	`str` with `surrogateescape`	`Uint8Array`	cannot (`String`)
`CODE_DECLINED`	`CodeDeclined` (existing)	`CODE_DECLINED` (new)	`CODE_DECLINED` (new)	`chtypes::CODE_DECLINED` (new)

Departures from Go: Rows.Spans is []*Span; AtMergeEntry.Row is PartRow in every binding; row-level unsupported_settings is removed everywhere; the row, batch and filter results gain reason, refused_at, refused_row; columns gain default_support, default_support_reason, reads; a schema description gains posture; a server profile's b64 settings decode to their bytes (Rust: RawText). The full naming table is in docs/reference/bindings-v1.md and each binding's CHANGELOG.

Expected red

The required examples job fails every tour at "CLI fetch of line 26.9 failed (ABI v2)": the fingerprint moved to d5323993, and no published build carries it yet. It clears once the artifact producer publishes a dev build at this fingerprint.

Supersedes

#650 (Go), #652 (Rust), #653 (TypeScript), #654 (Python). They are CI vehicles and are closed after this merges.

🤖 Generated with Claude Code

The maintainers' decided cell for the second v2 spec batch, with body_read added to every refused_at enum (the vocabulary already had it): - input JSON is strict everywhere; - the export stays JSONCompactEachRow with one export_columns list, and a body mixing deferred and server-filled defaults declines with defer-defaults-mixed-body; - column_defaults: where the server would fill a column from its DEFAULT, the caller's value is used; - records, graphite_rollup, identity and session are absent; - r8 documents the known-crash list (known-crash-declined at create); - errors carry a reason (chs_error_reason; sdk.json errors.fields). spec/abi-v2/abi.json, its schema, docs.md, sdk.json and the generator are the inputs; every generated file is the generator's output: gen.py --write leaves no diff, --check passes for both majors, and gen.py --major 2 --fingerprint prints sha256:d53239933966e15a3c363e631a94fbba1231d84c4300337115d3ae5377bb41c2. The bindings' hand-written surface for the new members follows in this branch before it lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… call arguments WithInsertableColumns, WithColumnDefaults, WithVerdictBasis, WithDeferDefaults and WithInsertOption build insert_options for Row, Rows, ParseBlock and Filter.Rows; WithParamEncoding and WithFilterOption build filter_options; WithPosture and WithSchemaOption build schema_options. WithColumns now applies to Filter.Rows. A settings, query-parameter, defaults or server-settings value that is not UTF-8 is the {"b64": ...} object form instead of a refusal. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…mbers RowResult, BatchResult, FilterResult and FilterRowError carry the reason, refused_at and refused_row members; the batch carries ExportColumns, ExportDeclinedReason and a Spans slice aligned with Rows (a nil entry for a row not exported); AtMergeEntry.Row is PartRow; the row-level UnsupportedSettings is removed; Column carries DefaultSupport, DefaultSupportReason and Reads; SchemaDescription carries Posture; a server settings value in the b64 form decodes to its bytes. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…de member Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

…he new names Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>