Production Standards

Binding rules for a generated client's public surface, not a checklist to work through once. This file's predecessor called itself a checklist and was read as advisory: nothing checked most of its rules, and every client audited against it violated them. Every rule below states whether a machine checks it today. A rule with no check is an invitation to build one, not a permanent exception.

How to read a rule

Each rule (S1, S2, ...) has three parts:

• Rule: one or two sentences, precise enough to grep for a violation.
• Why: usually a real defect the rule closes.
• Enforcement: one of:
  • truewire <command>: a real, run-today command fails or warns on a violation.
  • review checklist (manual): a reviewer reads the code against the rule; no command checks it.
  • not applicable: the rule belonged to a multi-project release process.

Rule IDs are stable once assigned. Code cites them (check_reserved_names cites S8, no_call.py cites S29), so a retired number stays retired, gaps included.

Entry point

Run every mechanically enforced check in one pass:

truewire standards

It runs truewire check, truewire surface, truewire examples --require-verified, truewire docs check and truewire docs lint, plus six in-process checks (links/S1, docstrings/S3, duplicate-schemas/S6, secret-placeholders/S16, router-coverage/S26, no-call/S29), and reports one summary. --only/--skip filter by slug; --list-checks lists them. links is excluded from a plain run because it makes live HTTP requests to documentation hosts; select it with --only links. A green run is a precondition for calling a client done, not proof: a rule enforced by the review checklist still needs that review.

General

S1. Every upstream documentation URL resolves to the exact endpoint or topic page cited, not a stale redirect or a domain-level landing page.

Why: a link that 404s or lands somewhere generic reads as verified when it was never checked.

Enforcement: truewire standards --only links. It fetches every URL cited in upstream.md, README.md, docs/** and router.json files and flags a non-2xx status or a redirect to a domain-level page. warning-severity, opt-in, and a heuristic: a human still judges each finding.

S2. Public docs describe the real, current client surface. A doc section either reflects what the package does, or is deleted, never a stale scaffold placeholder.

Why: one client shipped its docs as a literal unedited scaffold, down to a misspelled env var.

Enforcement: partial. truewire docs check fails a placeholder code example, since a call to a method nobody filled in does not type-check (S20); truewire docs lint catches pipeline-voiced prose (S21). Placeholder prose with no code stays manual.

Docstring Formatting

S3. Every function, class and module carries a docstring in the Google-compatible section style: Args:/Returns:/Raises:/Examples:/References:, no custom section markers, and a multi-line docstring's closing """ on its own line.

Why: a docstring reaches a user through editor hover and any generated reference, and a renderer mis-renders a non-standard section rather than erroring on it.

Enforcement: truewire standards --only docstrings. It walks the package source with ast and flags a closing """ sharing a line with prose, and a Word: header line outside the five sections above. warning-severity. Docstring presence is not checked.

S26. Every grouping directory under spec/endpoints/ declares a router.json with a real description and a working upstream link, so every hover point in the client's attribute chain carries a real docstring. A directory spanning several pages cites the one covering the most of them, or reuses a parent's link. Inventing one is refused.

Why: docs/spec/authoring.md rule 14. A router class rendered no docstring before this, so a fresh caller had no way to orient from the code.

Enforcement: presence is truewire standards --only router-coverage, error-severity; shape is validated on load; reachability is --only links (S1). Whether the text reaches the generated class's docstring stays manual.

Typing

S4. Every published package ships py.typed.

Why: without it a downstream type checker treats every import from the package as untyped.

Enforcement: manual. truewire init writes the file; nothing checks that it survives to the built distribution.

S5. A value with a documented, finite set of possible values is typed Literal[...] via a spec enum, never a bare str/int.

Why: docs/spec/authoring.md rule 2. A Literal catches a typo at the call site.

Enforcement: truewire check, the enum rule, warning-severity by design: a field name that usually denotes a closed set is a heuristic, not proof.

S6. A public response or item type carries an idiomatic, semantic name for the API concept it represents (OrderStatus, AccountTrade), never a generated placeholder (Response200), an anonymous schema-position name, or an unreduced duplicate of a shared shape that should have been reused.

Why: found in three generators: Response200 on every ping endpoint, and one shared Money shape inlined eight times, each copy titled the same, so the disambiguator appended path segments until the names differed (LimitLimitGtc0OrderConfigurationAnyOf3LimitLimitGtc). Two mechanisms: a missing title, which rule 1 now requires on an empty object too, and a missing $ref for a shared shape (rule 0), which no title requirement catches.

Enforcement: the empty-object half is truewire check, the title-empty-object rule, warning-severity. The duplicate half is truewire standards --only duplicate-schemas: an inline object schema's property-name signature shared by two or more occurrences across the spec tree (at two properties or more, to cut noise) is one finding naming the locations. warning-severity.

Timestamps

S7. A wire timestamp declares its real format: epoch-seconds, epoch-millis, epoch-micros, epoch-nanos, or date-time for an RFC 3339 string, never a bare string/integer with the shape only in prose. A plain calendar date declares date. Applies identically to a request parameter, a request body property and a response field.

Why: docs/spec/authoring.md rule 3. An undeclared timestamp renders as a raw int/str, and a request-side one is sent to the wire wrong. One client read 0 errors while declaring a format on 0 of 218 endpoints.

Enforcement: truewire check, the timestamp-format rule, warning-severity: a field name ending in time/timestamp/date/datetime/ts/since/at with no declared format is flagged. Only the last word of a split name is matched, so timeInForce is never mistaken for a timestamp. Each format's runtime type lives in the project's own core types module, built from truewire_core.times converters.

S27. A project's core types module pairs every timestamp and date type's BeforeValidator with a matching PlainSerializer(converter.dump, when_used='json').

Why: ADR 0008. Without the serializer half, validator(Type).dump() (S28) silently renders ISO-8601 regardless of the declared wire format. Latent on every client at the time.

Enforcement: manual. truewire init's core template includes the pairing for every format.

Validation And Errors

S8. Every generated rpc endpoint method accepts validate: bool | None = None (None follows the client-level default). When an API's own wire parameter is named validate, the codegen backend resolves the Python parameter to a distinct name.

Why: two hand-rolled generators accepted no override on most methods. Worse, one client's order endpoints reused the wire name validate for the API's own dry-run flag, so validate=True there meant "don't submit the order," the opposite of its meaning everywhere else.

Enforcement: truewire surface reports a missing_validate entry for every generated rpc method lacking the parameter, and fails like a surface gap. truewire check's reserved-param rule flags a spec parameter named validate, warning-severity: the spec is right to use the real wire name, so this never promotes to error.

S9. API error envelopes map to truewire_core.exceptions (ApiError, BadRequest, AuthError, RateLimited), not ad hoc local exception classes. A missing credential raises AuthError from an early credential-resolution path, never a raw os.environ[...] lookup left to surface a bare KeyError. A rate-limit failure raises RateLimited where the API distinguishes one.

Why: one client's resolve_credentials() correctly raised AuthError, and every constructor bypassed it for a raw os.environ[...] lookup, so a missing credential raised KeyError anyway.

Enforcement: review checklist (manual).

Core And Instantiation

S10. A client subclasses truewire_core transport (truewire_core.http.HttpClient, or Socket/Streams/Rpc/StreamsRpc from truewire_core.ws) and never constructs a raw httpx.AsyncClient, opens a raw websockets.connect socket, or defines its own class shadowing a runtime primitive's name without inheriting from it. If the runtime cannot express what an API needs, extend the runtime; never keep a private copy.

Why: one client overrode Socket.force_open with a direct websockets.connect(...) call to lift max_size for a 5MB snapshot, "otherwise identical" by its own docstring: a private copy of a change every client would benefit from.

Enforcement: review checklist (manual). The repository-wide AST test suite that enforced this in the original monorepo is not applicable to a standalone project; grep -rn "httpx.AsyncClient\|websockets.connect" src/ covers the first half.

S23. When an API serves the same request/reply surface over both HTTP and WebSocket, the generated method takes a transport keyword choosing between them per call, never a transport chosen once at construction that yields two disconnected objects.

An endpoint with more than one entry in spec.transports renders one method with transport: Literal[...], in declaration order, defaulting to the first. A single-transport endpoint gets no parameter.

Why: binding the transport at construction forces a caller to pick one for the client's lifetime, or hold two instances.

Enforcement: review checklist (manual). A surface-style check that the method carries the keyword is buildable but not built.

Package Structure

S11. One endpoint method per module. The last-level package __init__.py composes sibling endpoint classes through inheritance (MarketData(AssetPairs, Assets, Depth)). A higher-level composite, root or mid-level, is a plain @dataclass(kw_only=True) composing grouped objects as fields, never further inheritance. A mid-level composite is defined inside the subpackage it composes (Spot in spot/__init__.py), never inline in the root's wiring file.

"Plain" means wired through __init__, never field(init=False) + __post_init__ + object.__setattr__, the pattern a composite falls into when it also subclasses a frozen endpoint base. Expose a classmethod new(cls, *, client) that builds every child and passes them to cls(...) instead.

Why: one generator did the object.__setattr__ dance on every mid-level composite, found after the client's root class had been cited as a clean example. Review a composite at every level it appears.

Enforcement: review checklist (manual). grep -rn "object\.__setattr__" src/ is a strong signal, as is any class beyond the root in the root wiring file.

S12. A request body whose valid or required fields differ by a discriminant (order type, side) is spec'd as an anyOf of the variant shapes, never a flat list of named parameters with every variant-specific field optional.

Why: two clients flattened price/stopPrice/timeInForce as NotRequired regardless of order type, so a market order with a price, or a limit order without one, type-checks cleanly. A spec defect, not a codegen gap: rule 0 states the anyOf shape, and the generator renders it as a tagged union.

Enforcement: review checklist (manual).

S28. A generated rpc endpoint method with a request body serializes it through content=validator(BodyType).dump(body), not per-field conversion lines.

Why: ADR 0008. Per-field conversion rewrites formatted fields one level deep; one client's order body nested decimal-string fields inside an anyOf past that walk and raised TypeError on a real call. Needs a module-level body adapter named distinctly from the response adapter, and S27 first.

Enforcement: review checklist (manual).

S29. No generated class defines __call__. An endpoint's method is always inherited directly onto its parent, real and distinctly named, never reached through a cached_property wrapping a __call__-only leaf class, at any depth, including a client's outermost transport root.

Why: a leaf endpoint class defines no __init__, so multiply-inheriting several leaves onto a parent works at any depth; __call__ is never needed. The motivating bug was a leaf with both a named sibling method and a __call__, producing two disagreeing docstrings for one call.

Enforcement: truewire standards --only no-call, error-severity.

S30. A spec/endpoints/ directory is a leaf endpoint or a router grouping, never both.

Why: docs/spec/authoring.md rule 16. A directory holding its own endpoint.json beside an endpoint-bearing descendant has no name left to render its leaf under; the only mechanical answer is __call__, which S29 forbids. Every real instance found already had its leaf's function one segment deeper than its directory, which is exactly the subdirectory it needs to move into.

Enforcement: truewire check, error-severity. The generator also raises, naming the directory, when a leaf's resolved function collides with a node already in the function tree.

Spec Coverage

S13. spec/ reflects the implemented public surface: one endpoint.json per endpoint, upstream.md where upstream docs exist, and at least one paired example where it is safe to capture one. An endpoint that is unsafe, stateful, credential-blocked or otherwise unavailable declares why on the endpoint itself (unverified: {reason, detail}), not as prose in a status document.

Why: ADR 0001. A per-endpoint declaration is checkable; a paragraph is not. One status document asserted 0 errors while a fresh run reported 202.

Enforcement: truewire examples --require-verified and truewire check. Whether any prose still agrees with what they report is manual: re-run before trusting a claim.

S14. Pagination is declared per docs/spec/authoring.md rule 8 / ADR 0002, not hand-rolled per endpoint and not left for a caller to infer from bare limit/cursor parameters.

Enforcement: truewire check, the pagination rule, error-severity.

S15. A kind: 'stream' endpoint declares envelope.verb: the field, and its two literal values, that states subscribe-vs-unsubscribe intent on the wire.

Why: ADR 0004. Without it the mock server guesses intent rather than reading a declared fact.

Enforcement: truewire check, the ws-verb rule, warning-severity while existing specs migrate; promoting it to error is that migration's last step.

S16. A response field carrying a genuine secret, credential or PII gets an obviously fake, shape-preserving placeholder in a captured example: never the real value, and never something implausible about the field's shape.

Why: docs/spec/authoring.md rule 6. REDACTED_CLIENT_SECRET in an API-key listing's response is the worked reference.

Enforcement: truewire standards --only secret-placeholders. The mock server never compares or redacts a response body (unlike a request-side credential, which redacted/ADR 0007 strips), so the check reads the project's [secrets] names from truewire.toml plus a built-in denylist (apiKey, secret, privateKey, ...) and flags a credential-shaped field in any recorded example whose value carries no fake marker (REDACTED, FAKE, TEST, ...). warning-severity: a heuristic, not proof.

Runtime And Type Tests

S17. A type-usage test file exists, exercises representative public call patterns (constructors, endpoint calls, response types, stream usage), and passes pyright. Not an empty stub, and not orphaned by a pyrightconfig.json pointing at a file that does not exist.

Why: the one committed guardrail against a change silently degrading a public return type to Any, missing or empty on six of eight clients in one audit.

Enforcement: manual. truewire generate runs pyright when [python].pyright is set or a pyrightconfig.json sits at the project root, but nothing checks that the file exists or is non-trivial; what counts as non-trivial is a design call.

S18. Every endpoint method with pagination parameters has an ergonomic _paged variant (unless the API's own pagination model cannot be made safe), covered by a mock-backed test walking several pages. One page cannot distinguish a correct walk from one that happens to terminate immediately.

Why: off-by-one, cursor-advance and termination bugs are what a single-page test cannot see. A declared block generates the walk but does not prove it.

Enforcement: review checklist (manual).

S24. A _paged variant is truewire_core.util.paging.PaginatedResponse-shaped (async for page in x(...) and await x(...) both work) wherever the generator has that rendering: token with absent_cursor, page with a total terminator and done.rows, and plain seek with no overlap. A plain async generator is the wrong choice on those three, and the only choice elsewhere until the rendering widens.

Why: strictly more capable at zero cost to a caller who only iterates. One client's published, awaitable _paged methods were silently replaced with plain async generators during a regeneration, breaking downstream await callers.

Enforcement: review checklist (manual). Before regenerating a client, check whether it already has a published awaitable contract worth preserving.

S19. Both HTTP and WebSocket examples are covered by mock-backed tests when the client supports both transports. A mock test uses a local base-URL override, never a live network call.

Enforcement: review checklist (manual).

Docs And Examples

S20. Every code block in README.md and docs/ type-checks against the package it documents.

Enforcement: truewire docs check.

S21. Docs describe a fact about the API or the credential when stating a limit ("this endpoint requires a partner whitelist"), never a fact about the build ("out of scope for this run," "deliberately deferred"), and never an internal path (spec/, truewire.toml, codegen).

Enforcement: truewire docs lint, the internal-reference rule.

S25. Every relative link in README.md, docs/**/*.md and docs/quickstart.yaml resolves to a real source file.

Why: a same-repository link is knowable before publish and should never depend on a live HTTP probe.

Enforcement: truewire docs lint, the broken-doc-link rule, no network access. The rule's original second half, canonical routes on a hosted documentation site, is not applicable outside that host; see your own release process. Heading fragments are not validated.

Export And Publish

S22. Retired. It tied a catalog tier to export sync between a monorepo and a public mirror, not applicable outside a multi-project monorepo; see your own release process. The point stands: source-tree quality that never reaches the published package reaches nobody.

Notes For Future Rules

• Don't add a rule restating something docs/spec/authoring.md or an ADR states more precisely; point at it (S5, S7, S14, S15, S16 do). Two sources of truth for one fact is how this file's predecessor rotted.
• A rule with manual enforcement is a to-do, not a lesser rule. If you build the check, update the rule's Enforcement line and the slug list above in the same change.