docs: ConduitError + structured-output design (v0.16 foundation)#2523
Merged
Conversation
Design doc for the v0.16 linchpin: a uniform, machine-actionable error model (ConduitError, dual Go-error/proto encoding) and structured `--json` output that the MCP server, CLI, React UI, and `conduit generate` all consume. Reviewed against the codebase. The load-bearing compat claim is verified: adding a google.rpc.ErrorInfo detail to the existing status is preserved through grpc-gateway into the HTTP JSON body with no error-handler change (purely additive). Corrections folded in: mandatory NewConduitError constructor (leaf errors otherwise carry no stack trace); explicit GRPCCode per registry entry (not string-inferred); a no-nested-error invariant; honest re-costing of the ecdysis --json work (framework wiring O(1), per-command Result extraction O(n)); correct scoping of configPath (real only for the provisioning-YAML boundary, JSON-pointer generation is net-new elsewhere); a concrete CI-guard mechanism (runtime interceptor, CI-fatal); and an explicit gap — plugin-originated errors need a versioned conduit-connector-protocol change and their own ADR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design doc for the v0.16 linchpin — a uniform, machine-actionable error model + structured
--jsonoutput that the MCP server, CLI, React UI, andconduit generateall consume.Reviewed and corrected
An independent technical review verified it against the codebase. Headline: the load-bearing compatibility claim is CONFIRMED live — adding a
google.rpc.ErrorInfodetail to the existingStatusis preserved through grpc-gateway into the HTTP JSON body with no error-handler change (the marshal was run and verified). So the core bet holds; no public-contract fork.Corrections folded in:
NewConduitErrorconstructor — a leaf error otherwise carries zero stack frames (*ConduitErrorisn't an xerrors type).GRPCCodeper registry entry, not inferred by string-matching the code name.ConduitErrorinvariant (errors.Asreturns the outermost, shadowing inner codes).--jsonre-cost: framework wiring is O(1), but per-commandResultextraction across ~16–23 commands is not eliminated.configPathscoped correctly: the existing YAML line/column data covers only the provisioning-file boundary; JSON-pointer generation for API/CLI + semantic-validation errors is net-new work.schemaVersionis its own minimal mechanism, not the config-YAML version machinery (different problem).UnaryServerInterceptorthat's CI-fatal; static analysis / handler refactor is later hardening.conduit-connector-protocolchange — breaking territory, gets its own ADR before rollout touches it.Tier 3 (docs). Scopes v0.16 §1.1.
🤖 Generated with Claude Code