Skip to content

[P3][kernel] Explore an async API face layered over the sync core #57

Description

@cevheri

Summary

Roadmap item (DESIGN.md Core API decision, ratified 2026-06-24: the core stays synchronous, and "an async face can be layered later as an adapter over the sync core, so this does not foreclose async backends"). This issue tracks exploring that face — it is explicitly NOT a proposal to make the kernel async.

Why

  • Worker-hosted deployments (the browser OPFS pattern in docs/BROWSER.md) already wrap the sync database in an async postMessage protocol by hand; a first-party async facade could standardize that.
  • Async-only storage backends (network file systems, async browser APIs without sync access handles) are unreachable through the current synchronous FileSystem seam.

Open questions (each must earn its place)

  • Facade over the same process (Promise-wrapping, trivial) vs a Worker/thread host (real value: moves fsync latency off the caller's thread) — the second is where the benefit is, and it subsumes the Comlink-style pattern the browser docs describe.
  • Transaction shape across an async boundary: the sync transact(run) closure cannot cross a postMessage boundary; an async face likely needs a batch/command API instead — design carefully so serializability stays a fact.
  • The ASYNC_TRANSACTION rejection stays: the sync core's contract is unchanged.

Constraints

  • src/core.ts unchanged; this is an edge package/entry, possibly a separate export path.
  • Do not ship without a real consumer driving the design (Studio or the browser Worker pattern).

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions