@xyo-network/dapp-kit

Portable, environment-neutral model and validation contracts for headless XL1 dApps.

The package contains pure schemas, canonical document encoding/hashing, deterministic cross-document validation, neutral lifecycle ownership facades, durable effect contracts, and capability-driven XL1 transaction reconciliation. Dapp-kit documents use RFC 8785 JCS with document-kind domain separation and SHA-256; this codec is intentionally distinct from XYO payload and Bound Witness hashing. Current policy models cover actor effect authority, datalake access/protection/availability constraints, and opaque auxiliary-store capability bindings. Projection models add reducer/input declarations, per-chain floors, durable capability bindings, and verifiable checkpoint positions. Deterministic reducer and publication traces cover canonical input order, exact redelivery, historical protocol input, immutable generation hashing, and verified publish-head-last visibility. Coordination models make non-canonical side-channel criticality, limits, detached-signing capabilities, replay, audience, and expiry explicit. The D-029 neutral foundation adds version-aware document domains, stable event identity, complete accepted-byte fingerprints, strict event draft/record schemas, and pure append decisions for new, duplicate, and colliding events. It also defines retained/external event-stream and event-subscription resource requests, exact subscription-to-stream dependencies, idle | scheduled | running | blocked cursor transitions, fresh lease fences, exact durable consumer outcome proofs, retry-bound poison blocking, and a bounded for await pump over injected stream/subscription/consumer ports. Atomic append/read port contracts and a coalescing, generation-fenced wake-outbox state machine ensure that stale delivery completion cannot clear a newer request. This is neutral model and deterministic runtime evidence; it does not claim a crash-durable event provider, fan-out adapter, provider wake delivery, or exactly-once transport. External observation models bind declared source, provenance/finality evidence, and typed content hashes while generic outbound actuation remains rejected in V1. Pure lifecycle transitions cover bounded boot, pre-ready stop, draining, failure teardown, and idempotent terminal stop. Status documents keep health, liveness, readiness, per-operation writability, convergence, and incarnation identity separate. planXl1TransactionEffect() derives the next baseline action from a valid append-only receipt. createXl1TransactionEffectReconciler() dispatches that action through stage-specific injected capabilities and checks returned evidence against the planned content, transaction, or inclusion. recoverEffectJournal() captures a finite, effect-ID-ordered snapshot of every incomplete durable receipt, reconstructs each prepared prefix, selects a reconciler from its durable identity, and returns bounded complete/pending/cancelled/effect-limit state. The package performs no provider acquisition, actor construction, chain I/O, datalake I/O, key custody, concrete cryptographic implementation, projection storage, replay scheduling, transport, or ambient host access.

ObjectStoreReader and ObjectStoreWriter define the portable byte-object capability used by projection and checkpoint resources. The contract includes conditional writes, content metadata, deterministic listing, and paging without exposing a filesystem path, S3 bucket, database handle, or provider lifecycle. PrefixedObjectStore and RoutedObjectStore compose least-scope logical views; concrete durable implementations remain host adapters.

V1 side-channel envelopes use domain-separated JCS/SHA-256 signing hashes and XYO-compatible compact secp256k1 signature bytes. The neutral validator invokes an injected detached-signature verifier keyed by the authorized sender role; it does not own keys, construct accounts, or import a concrete signer/verifier.

Identity bindings remain opaque capabilities. Optional deterministic metadata records canonical XL1 BIP-44 child paths, expected addresses, exact-chain scope, and explicit rotation without carrying mnemonic or private-key material.

The package is published with UNLICENSED metadata; the repository's licensing and governance decision remains open.