Skip to content

feat(data-contracts): make postcard a first-class JSON-free Linkable codec#176

Merged
lxsaah merged 1 commit into
aimdb-dev:mainfrom
thaodt:feat/issue-155-postcard-linkable
Jul 11, 2026
Merged

feat(data-contracts): make postcard a first-class JSON-free Linkable codec#176
lxsaah merged 1 commit into
aimdb-dev:mainfrom
thaodt:feat/issue-155-postcard-linkable

Conversation

@thaodt

@thaodt thaodt commented Jul 11, 2026

Copy link
Copy Markdown
Collaborator

Description

  • Split the format-neutral Linkable contract from its JSON convenience.
  • Make generated Postcard codecs an exercised, JSON-free embedded path.
  • Add mixed JSON + postcard compile coverage to prevent codegen dependency drift.
  • Extend the repository validation matrix and update affected documentation.

Context

After #170, Linkable already provides the typed byte-oriented boundary requested by #155. Adding another generic Codec<T> in aimdb-core would duplicate that boundary.

This PR therefore implements the re-scoped #155: harden postcard as the compact binary codec for shared-contract links while keeping self-describing remote interfaces unchanged.

Compatibility

This changes the semantics of the existing linkable feature. JSON derive users must migrate from:

features = ["linkable"]

to:

features = ["linkable-json"]

Manual Linkable implementations and postcard/custom codecs should continue using the base linkable feature.

Because changing linkable requires JSON derive users to opt into linkable-json, this PR also bumps aimdb-data-contracts from 0.3.0 to 0.4.0.
The version requirements in aimdb-sync, aimdb-wasm-adapter and aimdb-websocket-connector are updated accordingly.

Out of Scope

Related Issue

Checklist

  • I have read the CONTRIBUTING.md document.
  • My code follows the project's coding standards.
  • I have added tests to cover my changes.
  • All new and existing tests passed (make check).
  • I have updated the documentation accordingly.

- move `serde_json` and the JSON Linkable derive behind `linkable-json`
- keep base linkable limited to the typed byte contract and registrar verbs
- add generated Postcard roundtrip, Cortex-M, mixed-codec and JSON-free checks
- update consumers, validation matrices, changelogs and design docs
@thaodt thaodt requested a review from lxsaah as a code owner July 11, 2026 15:24

@lxsaah lxsaah left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm!

@lxsaah

lxsaah commented Jul 11, 2026

Copy link
Copy Markdown
Contributor

@thaodt I filed #177 and #178 as follow-up. Please tell me what you think. Thanks again!

@lxsaah lxsaah merged commit b5658b4 into aimdb-dev:main Jul 11, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEAT] Make postcard a first-class, JSON-free Linkable codec

2 participants