docs: fix AimX v1/v2 rot, dead spec links, and removed-API references#145
Merged
Conversation
…6 W1 inbound) Replace the per-message Box<dyn Any> inbound path (DeserializerKind -> produce_any downcast) with a fused IngestFn built in InboundConnectorBuilder::finish() where T is known: deserialize + produce in one typed closure, no erasure crossing and no boxed future per message (Producer::produce is sync + infallible, design 029). - IngestFn / IngestFactoryFn replace DeserializerFn/ContextDeserializerFn/ DeserializerKind and ProducerTrait/ProducerFactoryFn (all deleted) - InboundConnectorLink carries the ingest factory (non-optional; finish() validates the deserializer before registering, unchanged error strings) - Router::route is now a sync fn taking &RuntimeContext (every production caller already passed Some(&ctx); the context-skip branch is unrepresentable with fused closures, its test removed) - collect_inbound_routes returns Vec<(String, IngestFn)> - pump_source / pump_client inbound / ws dispatch drop one .await - delete dead TypedRecord::create_producer_trait Registrar API (with_deserializer/_raw, link_from) is source-compatible; MQTT/KNX/WS builders pass routes opaquely and compile unchanged. Part of design 036 W1 (data-plane de-Any). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ion (036 W1 outbound)
Replace the per-message Box<dyn Any> outbound path (subscribe_any ->
recv_any -> SerializerFn(&dyn Any) downcast, plus topic_any(&dyn Any))
with a fused SerializedSource built in OutboundConnectorBuilder::finish()
where T is known: its readers yield destination + serialized payload
directly (subscribe -> recv -> resolve topic -> serialize, all typed).
- SerializedSource / SerializedReader / SerializedValue / SourceFactoryFn
replace ConsumerTrait/AnyReader/SerializerKind/SerializerFn/
ContextSerializerFn/ConsumerFactoryFn and the erased TopicProviderAny/
TopicProviderWrapper/TopicProviderFn (all deleted; the typed
TopicProvider<T> trait is now stored as-is)
- OutboundRoute is { topic, source, config }; ConnectorLink carries the
source factory (non-optional; finish() validates the serializer before
registering, unchanged error strings; the "skip links without
serializer" branch in collect_outbound_routes is gone)
- RuntimeContext is threaded into SerializedReader::recv per call (026
context serializers), not captured; raw serializers skip the ctx clone
- Buffer errors propagate unchanged (BufferLagged => pump continues,
other => pump stops); serialize failures are logged and skipped inside
the reader, observably identical to the old pump-side continue
- pump_sink / pump_client outbound collapse to recv + publish
What disappears per message: the Box<dyn Any> allocation, two downcasts,
the topic_any erasure crossing, and the subscribe_any boxed future. The
one remaining Box::pin per recv is the object-safe-async cost that
already existed.
Registrar API (with_serializer/_raw, with_topic_provider, link_to) is
source-compatible; the KNX fake-gateway and session smoke tests pass
unmodified.
Part of design 036 W1 (data-plane de-Any).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…asure (036 W1 wrap-up) - delete SerializeError::TypeMismatch — both constructors died with the W1 fusion (the downcasts are gone); DbError::TypeMismatch is unrelated and stays - delete dead ConnectorClient (held Arc<dyn Any>, zero users) and OutboundConnectorLink (zero users) - document on JoinTrigger why the join fan-in deliberately keeps its Box<dyn Any + Send> (the erasure is the multi-type join API) - CHANGELOG entries (global + aimdb-core + websocket-connector) - check in design docs 034/035/036 and amend the 036 W1 acceptance grep: DynBuffer::as_any and the session auth ext slots are setup-time hits the original literal grep missed Part of design 036 W1 (data-plane de-Any). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
AnyRecord carried ~22 methods spanning four concerns; every remote-access or profiling change churned the core storage contract. Split by consumer: - AnyRecord (6 methods): storage/lifecycle only — validate, as_any(_mut), drain_config_errors, set_writable_erased, plus the cfg-gated json_access() accessor so the remote-access gate lives in one place. - RecordIntrospect (supertrait): graph/metadata introspection consumed by the builder's dependency-graph construction, route collection, and list_records. - JsonRecordAccess (cfg remote-access): latest_json / subscribe_json / set_from_json, reached via json_access(); the runtime .with_remote_access() checks stay inside the methods, so behavior is unchanged. Gate is `remote-access` (the 036 sketch said json-serialize). - RecordMetricsReset (supertrait): the cfg-gated no-op-default resets. Supertrait wiring keeps every dyn AnyRecord call site compiling unchanged; only the four JSON call sites switch to the accessor. Registry storage stays Vec<Box<dyn AnyRecord>>. Drops the dead outbound_connector_urls (cfg std) — zero callers in-tree and in aimdb-pro. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…036 W5) intern() leaked a fresh allocation on every call, so re-interning the same key leaked again. A global dedup table (std Mutex / spin Mutex, same pattern as the TypedRecord field locks) now returns the existing 'static allocation for a known key, bounding the leak by the number of *distinct* dynamic keys — the actual lifetime contract of a record key. The contract is documented loudly on intern(), and the debug-build tripwire now counts distinct keys instead of calls. The &'static str / Copy design stays; an Arc<str> key variant remains rejected (forks RecordKey into two shapes — the 034 §3.1 mistake). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…tion (036 W6) The 18-line no-op #[defmt::global_logger] + panic handler + host time driver block existed in three copies (embassy-adapter session_smoke, embassy-adapter buffer.rs tests, serial-connector embassy_smoke). Per 035 §2.4, an exported host_test_stubs! macro in aimdb-embassy-adapter now holds the single definition; each test binary expands it once, preserving the once-per-binary requirement of #[global_logger]/time_driver_impl!. The time driver uses the wake_by_ref variant (buffer.rs's superset behavior: zero-duration sleeps complete; the smokes never sleep). The serial-connector defmt/embassy-time-driver dev-deps stay — the expansion references them at the invocation site; the Cargo.toml comment now says so. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…, W7 skipped - W3: Nucleo firmware build verified (thumbv8m.main-none-eabihf); single run on a main build is the bar now that #140 is merged. Bench session is the remaining work and the gate for closing 035. - W4: deferred pending W3 scenario-1 AckTimeout evidence (decision 2026-06-12). Design pre-decided for the trigger: buffer the sent frame (option a) — GroupWrite already carries a 254-byte APDU buffer, so the semantic-content variant saves ~350 B total, no real RAM argument. - W7: skipped entirely (decision 2026-06-12); no audit will be run. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…d miss (036 W4) KNXnet/IP 3.8.4 says: repeat an unACKed TUNNELING_REQUEST once after the timeout, then tear the connection down on the second miss. The engine previously expired and warned only — hardware bench evidence (W3, 2026-06-12) showed ten button-press writes silently lost during a link outage's heartbeat-detection window (~65 s). TunnelConfig gains ack_retransmits (default 1 = spec behavior; 0 = the old expire-and-warn for the previous semantics). The pending-ACK slot buffers the sent frame (option (a) per the 036 W4 decision record: GroupWrite already carries a 254-byte APDU, so rebuilding from semantic content saves ~350 B total — not worth the rebuild path). On expiry with retries left the identical frame is re-sent (same sequence counter) and the timer re-armed; on final expiry AckTimeout is reported and the engine disconnects so queued commands flush after the re-handshake instead of vanishing into a dead tunnel. Eviction on map overflow stays warn-only (overflow is not confirmed loss). Behavior change at default config: a tunnel with a persistently unanswered write now reconnects within ~2× ack_timeout_ms instead of staying connected. Retransmit delay is ack_timeout_ms (3 s, the pre-engine constant); strict spec timing is one config knob away (ack_timeout_ms = 1_000). Tests: engine units (identical-frame retransmit, ack-after-retransmit, disconnect on second miss, legacy mode pinned at ack_retransmits=0) + fake-gateway test dropping the first ACK and asserting the byte-identical repeat and tunnel survival. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…dings Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… W3 scope Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Doc-rot fixes from the post-036 debt scan; no wire or API behavior changes (the one wire-visible byte change — the client hello version — is corrected from a stale "1.0" to the "2.0" the server already announces; the server never validates it). - remote::PROTOCOL_VERSION corrected to "2.0", documented, and exported; the AimX dispatch Welcome and aimdb-client both use it now, so client and server can no longer drift. The dead, never-exported v1 untagged Message envelope and its helpers are deleted. - remote module docs: "AimX v1" + link to the nonexistent docs/design/remote-access/aimx-v1.md replaced with the v2 NDJSON tagged-frame description pointing at session::aimx and remote-access-via-connectors.md; stale .build()? example fixed to the (db, runner) = build().await? shape. - connector module docs: removed-`.link()` API replaced with the real configure/link_to pattern (the old example used a RecordConfig::builder API that never existed); ConnectorUrl no longer advertises Kafka/HTTP connector semantics for connectors that don't exist — documented as scheme-agnostic with real schemes (mqtt, knx, ws, uds, serial). - builder.rs AimDb example fixed: register_record returns &mut Self, so the old chained .build() could not compile. - aimdb-client README rewritten to match reality (AimxConnection, v2 wire, endpoint URLs incl. serial); crate doc + aimdb-cli doc updated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jun 12, 2026
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.
Summary
Doc-rot fixes surfaced by a fresh technical-debt scan after the 034→036 refactor cycle. Stacked on #144 (retarget to main as the stack merges). No wire or API behavior changes — the one wire-visible byte change is the client hello version, corrected from a stale
"1.0"to the"2.0"the server already announces (the server never validates it).AimX v1/v2 identity rot
remote::PROTOCOL_VERSIONcorrected to"2.0", documented, and exported; the AimX dispatchWelcome(was a hardcoded"2.0") andaimdb-client(was a stale local"1.0") both consume it now, so client and server can no longer drift.Messageenvelope + helpers fromremote::protocol(v2 uses tagged frames insession::aimx; this had zero users).remotemodule docs: "AimX v1" and the link to the nonexistentdocs/design/remote-access/aimx-v1.mdreplaced with the v2 NDJSON tagged-frame description, pointing atsession::aimxanddocs/design/remote-access-via-connectors.md. Same fix inremote::protocolandaimdb-cliheaders.aimdb-clientREADME rewritten to match reality:AimxConnection(not the retiredAimxClient), v2 framing, runtime-selected transports via endpoint URLs (UDS + serial).Removed-API references (034 §3.6 leftovers)
connectormodule docs referenced the removed.link()API and an example built onRecordConfig::builder()— an API that never existed. Replaced with the realconfigure/link_topattern.ConnectorUrldocs no longer advertise Kafka/HTTP connector semantics for connectors that don't exist; documented as scheme-agnostic with the schemes actually in-tree (mqtt, knx, ws, uds, serial). Parser code untouched.Stale doc examples
builder.rsAimDbexample couldn't compile as written (register_recordreturns&mut Self, so chaining.build()by value is impossible); fixed to the canonicallet (db, runner) = builder.build().await?shape. Same fix for theremotemodule example (.build()?→.await?+ tuple).Validation
make fmt-check✅make clippy(all feature combos,-D warnings) ✅cargo test -p aimdb-core -p aimdb-client -p aimdb-cli -p aimdb-mcp✅, plusaimdb-core --no-default-features✅cargo check --workspaceagainst this branch ✅🤖 Generated with Claude Code