Skip to content

feat: add atomic-facade — native API layer over command-level reads - #152

Closed
vinceblock99 wants to merge 4 commits into
devfrom
feat/native-api-facade
Closed

vinceblock99 wants to merge 4 commits into
devfrom
feat/native-api-facade

Conversation

@vinceblock99

@vinceblock99 vinceblock99 commented Aug 6, 2026 •

Copy link
Copy Markdown
Contributor

What

A new library crate, atomic-facade, that exposes the read operations behind the CLI as plain functions returning serde-serializable DTOs:

  • change_detail / list_log — what atomic change -f json / atomic log -f json print, including hash / prefix / #seq / @ identifier resolution
  • list_views / view_summary — view state, scope, parent, change counts
  • list_intents / intent_detail, list_memories / memory_detail — including the attestation dual-read (tracked vault entry first, legacy sidecar fallback, fresh/stale classification)

Additive only — no existing crate changes beyond registering the workspace member.

Why

Everything an integration needs is already on the laptop, inside the repo — but today the only way for a local UI, tool, or agent harness to read it is shelling out to the atomic binary and parsing its output, because the best JSON shapes and the attestation/identifier plumbing are trapped inside the atomic-cli binary. This crate makes those reads a typed, in-process library call.

Deliberately not a server contract: Atomic is local-first and the storage server is primarily transport. Whether any of this ever gets exposed server-side is a separate, intentional decision — this crate neither implies nor requires it.

For changes/log, JSON field names mirror the CLI's -f json output exactly, so serialized responses and CLI output stay interchangeable.

Notes

  • The CLI still has its own copies of this logic for now. Migrating atomic-cli onto the facade (removing the duplication) is a planned follow-up PR.

Test plan

  • 13 unit tests + 4 integration tests (cargo test -p atomic-facade) covering identifier forms, list/detail round-trips, not-found mapping, JSON serialization
  • cargo check --workspace and cargo clippy -p atomic-facade clean

Adds a library crate exposing the read operations behind the CLI as
callable functions with serde-serializable DTOs, so a server can link
them in-process instead of shelling out to the atomic binary:

- change_detail / list_log with hash / prefix / #seq / @ identifier
  resolution (mirrors atomic change/log -f json field-for-field)
- list_views / view_summary (ViewInfo as JSON with scope + parent)
- list_intents / intent_detail and list_memories / memory_detail,
  including the tracked-entry-then-legacy-sidecar attestation dual-read
  with Fresh/Stale classification promoted from the CLI bridges

The CLI keeps its own copies for now; migrating atomic-cli onto the
facade is a follow-up refactor.
- Scope the CLI-interchangeability doc claim to changes/log; the
  view/intent/memory DTOs are new richer shapes, not a CLI contract
- Propagate resolver infrastructure errors instead of mapping every
  resolve_intent_key failure to NotFound (a DB error is a 500, not 404)
- An existing-but-unreadable attestation sidecar is a hard IO error
  again (CLI parity), not silently 'no attestation'
- Reject '@~N' with the CLI's explicit not-yet-supported message
- Drop needless clones in the detail/summary builders
Team decision: Atomic's strength is that everything a client needs is
on the laptop — the storage server is primarily transport, and any
server-side read surface is a separate, deliberate call. Frame the
crate for its real consumers (local UIs, tools, agent harnesses) and
drop the retired atomic-enterprise reference.
@vinceblock99 vinceblock99 reopened this Aug 7, 2026
@graywolf336
graywolf336 deleted the feat/native-api-facade branch August 7, 2026 15:52
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.

1 participant