@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, key custody, replay scheduling, or ambient host access. Capability-driven operations call only the explicitly supplied ports; concrete transports remain host adapters.

isEffectPreparationCompactable() requires durable signed evidence and the receipt summary's latest verified availability for every required content hash. Later known content loss prevents compaction even after finality. Retaining material increases storage/private-material lifetime; this predicate does not define authorized repair for arbitrary codecs. Already admitted signed work resumes its exact prepared prefix without recreating compacted preparation, including after availability regression. The selected repair capability must validate its retained codec/body evidence; absent material stays pending or fails closed. The concrete Node hydrated codec retains repairable body/ciphertext bytes in the signed receipt; automatic ongoing loss detection is separate.

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.

DatalakeObjectStore maps byte objects to immutable XYO payloads and logical references in an injected atomic control store. It verifies payload readback before publishing a reference, preserves ifNotExists / ifMatch semantics, and retains payloads after failed writes or reference deletion. DatalakeObjectReader needs only read capabilities, including anonymous public viewers. Both validate original-byte SHA-256/size separately from SDK payload identity. stat validates reference metadata without fetching content. Defaults bound objects to 16 MiB, references to 64 KiB, and complete listings to 10,000 keys / 10,001 pages. Hex envelopes require roughly twice the original byte budget at the transport. Transport deadlines, authentication, durable atomicity, and exact-operation retries belong to the supplied capabilities. This bridge does not provision or qualify a storage backend.

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.

This package is licensed under the GNU Lesser General Public License version 3 only (LGPL-3.0-only), not "or later", as its manifest declares; the full terms are in the LICENSE file included in this package. Earlier versions were published with UNLICENSED metadata, and this statement does not describe them. The repository's remaining governance decisions (maintainer approval, schema allocation, and compatibility and upgrade policy) are still open.

evaluateDappReleaseEvidence and recheckDappReleaseEvidence provide pure, strict release eligibility over supplied source, workflow and deployment evidence. Latest runs and deployment statuses supersede earlier successes; snapshots bind exact source and run attempts. These APIs grant no deployment authority and do not replace provider receipts, fencing or application recovery. See the repository's docs/BETA_RELEASE_EVIDENCE.md for the adapter contract and evidence boundaries.

The additive D-040 engine model exports DappEngineConfigurationZod, DappEngineStatusZod, validateDappEngineStatus, validateDappEngineSystemReference and validateDappEngineSystemReplacement. It preserves per-system launch/incarnation identity, required/isolated policy, profile selection, and offline or chain/genesis bindings. Aggregate readiness is separate from per-operation writability and per-network convergence. These functions validate supplied documents; they do not launch systems, verify an endpoint's chain identity, replace a graph, or authorize a write.

launchDappEngine owns multiple injected existing DappLaunch handles under the engine model. It returns before boot, validates launcher coverage and identity, aggregates required/isolated failure, and requests every child stop before awaiting teardown. The ownership facade exposes status, readiness, terminal failure, stop and trusted-host replaceSystem/bindSystemWork; it exposes no child ports or locators. Replacement requires an exact current reference and fresh launch ID, closes and drains the old graph before acquiring the new one, and preserves its logical identity, network and failure policy while allowing a profile change. Unrelated ready systems remain available. Stop owns in-flight replacement; retired launch/incarnation IDs cannot be reused to revive stale references. Explicit stop retains all observed lifecycle/cleanup failures, including isolated failures, in an AggregateError. Both launch and session expose passive whenStopped(): the same retained promise as stop(), settling after complete teardown without initiating it. whenTerminal() remains the failure-only signal. bindSystemWork checks an exact ready reference and delegates dynamic work ownership to the existing child session. Session bindWork reserves ownership before a synchronous work factory runs, retains detached work through drainage, and closes every registered owner before system teardown. The port package uses this seam for engine-aware dispatch; platform transport integration and recovery admission have separate qualification gates.

Operation recovery readiness

DappOperationRecoveryProfileZod classifies selected operations as read-only, externally recovered or kit-journal-backed. DappOperationRecoverySnapshotZod reports one operation's safe readiness against an exact engine/incarnation, plan, network/genesis and opaque authority scope. validateDappOperationRecoveryAdmission checks binding, capability kind, required guarantees and readiness. Its success is neither authorization nor durability qualification. Uncertain, pending, unavailable and corrupt outcomes remain explicit; a read-only check requires no private snapshot. The kit receipt executor remains authoritative for its own operations, and this model never synthesizes a second durable journal.

The language-neutral vectors are in conformance/recovery/admission.json and run through public package imports in Node and Chromium. Browser write admission still requires the selected adapter's actual interruption/exclusion evidence.

Bounded current-head observation

createDappHeadObserverState, requestDappHeadObservation, claimDappHeadObservation and completeDappHeadObservation retain one cell per exact source hash and logical consumer. Requests coalesce a position-only hint; completion accepts an independently verified { sourceHash, position, root }. Verified heads never regress or change root at the same position. Captured generations and lease fences preserve concurrent arrivals and reject stale or expired workers. reserveDappHeadObserverScheduling and finishDappHeadObserverScheduling bound disposable dispatch reservations; recoverDappHeadObservation supports quiet-source refresh and lease recovery. The running status describes a persisted lease, not a live process. This mode does not append per-hint events/results or provide complete history; use the separate finalized replay and durable event contracts when those are required.