@storacha/clawracha 0.3.15 → 0.4.0

package/LICENSE.md

@@ -0,0 +1,204 @@
+The contents of this repository are Copyright (c) corresponding authors and
+contributors, licensed under the `Permissive License Stack` meaning either of:
+
+- Apache-2.0 Software License: https://www.apache.org/licenses/LICENSE-2.0
+  ([...4tr2kfsq](https://dweb.link/ipfs/bafkreiankqxazcae4onkp436wag2lj3ccso4nawxqkkfckd6cg4tr2kfsq))
+
+- MIT Software License: https://opensource.org/licenses/MIT
+  ([...vljevcba](https://dweb.link/ipfs/bafkreiepofszg4gfe2gzuhojmksgemsub2h4uy2gewdnr35kswvljevcba))
+
+You may not use the contents of this repository except in compliance
+with one of the listed Licenses. For an extended clarification of the
+intent behind the choice of Licensing please refer to
+https://protocol.ai/blog/announcing-the-permissive-license-stack/
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the terms listed in this notice is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied. See each License for the specific language
+governing permissions and limitations under that License.
+
+<!--- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+
+`SPDX-License-Identifier: Apache-2.0 OR MIT`
+
+Verbatim copies of both licenses are included below:
+
+<details><summary>Apache-2.0 Software License</summary>
+
+```
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+   1. Definitions.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+   END OF TERMS AND CONDITIONS
+```
+
+</details>
+
+<details><summary>MIT Software License</summary>
+
+```
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+</details>

package/README.md

@@ -1,172 +1,179 @@
 # @storacha/clawracha
 
-OpenClaw plugin for Storacha workspace sync via UCN Pail.
+Sync [OpenClaw](https://github.com/openclaw/openclaw) agent workspaces to [Storacha](https://storacha.network) — decentralized, encrypted, multi-device.
 
-## Overview
+No servers. No accounts to share. Just UCAN delegations and content-addressed data.
 
-Clawracha syncs OpenClaw agent workspaces to Storacha using UCN (User Controlled Names) with Pail — a CRDT-based KV store backed by merkle clocks.
+## What It Does
 
-**Features:**
+Clawracha watches your agent's workspace for file changes and syncs them to a Storacha Space via [UCN Pail](https://github.com/storacha/ucn) — a CRDT key-value store backed by merkle clocks. Multiple devices can sync the same workspace without conflicts.
 
-- 🔄 Live sync of workspace files (`.md` by default)
-- 🌐 Multi-device, multi-user via UCAN delegation
-- 🔀 CRDT-based conflict resolution (merkle clock)
-- 📦 Local-first with network sync
+- **Regular files** → content-addressed via UnixFS, stored as CIDs
+- **Markdown files** → CRDT merge via [md-merge](https://github.com/storacha/md-merge) — concurrent edits merge automatically, no conflicts
+- **Private spaces** → end-to-end encrypted via KMS before upload
+- **Multi-device** → delegation bundles let you grant access to other devices
 
-## Installation
+## Quick Start
+
+### 1. Install
 
 ```bash
-openclaw plugins install @storacha/clawracha
+# In your OpenClaw project
+pnpm add @storacha/clawracha
 ```
 
-## Setup
+Add to your OpenClaw config (`openclaw.config.json` or equivalent):
 
-Setup is done via CLI commands on the host (not slash commands in chat).
+```json
+{
+  "plugins": {
+    "clawracha": {
+      "enabled": true
+    }
+  }
+}
+```
 
-All commands require `--agent <id>` to specify which agent workspace to configure.
+### 2. Initialize
 
-### Step 1: Initialize the agent
+Generate an agent identity for your workspace:
 
 ```bash
-openclaw clawracha init --agent <id>
+openclaw clawracha init --agent myagent
 ```
 
-Generates an agent identity and displays the Agent DID. You'll need this DID to create delegations.
-
-### Step 2: Choose your path
+This creates a `.storacha/config.json` in the agent's workspace with a fresh Ed25519 keypair.
 
-**New workspace (first device):**
+### 3. Set Up a New Workspace
 
 ```bash
-openclaw clawracha setup <delegation> --agent <id>
+openclaw clawracha setup --agent myagent
 ```
 
-`<delegation>` can be a file path (raw CAR) or a base64 CID string. Have the space owner create an upload delegation for your Agent DID, then import it.
+This will:
+1. Ask for your Storacha email (sends a confirmation link)
+2. Wait for email confirmation and payment plan verification
+3. Ask you to choose **Public** or **Private (encrypted)** access
+4. Create a new Storacha Space
+5. Generate delegations (upload, name, plan)
+6. Do an initial sync of existing workspace files
+7. Start watching for changes
 
-**Join an existing workspace (additional devices):**
+### 4. Add Another Device
+
+On the **existing device** (the one already set up):
 
 ```bash
-openclaw clawracha join <upload-delegation> <name-delegation> --agent <id>
+openclaw clawracha grant did:key:z6Mk... --agent myagent
 ```
 
-Get both delegations by running `openclaw clawracha grant` on the existing device. Arguments can be file paths or base64 CID strings. The join command pulls all remote files before the watcher starts.
+This outputs a delegation bundle (a base64 string). Copy it.
 
-### Grant access to another device
+On the **new device**:
 
 ```bash
-openclaw clawracha grant <target-agent-DID> --agent <id>
+openclaw clawracha init --agent myagent
+openclaw clawracha join <paste-bundle-here> --agent myagent
 ```
 
-Generates upload and name delegations for the target device.
-
-### Check status
+The new device pulls all existing files and starts syncing.
 
-```bash
-openclaw clawracha status --agent <id>
-```
+### Interactive Setup
 
-After setup, restart the gateway to start syncing:
+Don't want to remember the steps? Use the guided flow:
 
 ```bash
-openclaw gateway restart
+openclaw clawracha onboard --agent myagent
 ```
 
-## How It Works
+This walks you through init → setup/join interactively.
 
-```
-Workspace Files                 UCN Pail KV Store
-================                ================
-/AGENTS.md          ────►       "AGENTS.md" → bafk...xyz
-/SOUL.md            ────►       "SOUL.md" → bafk...abc
-/memory/2026-02-10.md ────►     "memory/2026-02-10.md" → bafk...123
-```
+## CLI Commands
 
-The sync loop:
+All commands require `--agent <id>` to specify which agent workspace to operate on.
 
-1. **Watch** - File watcher detects changes
-2. **Encode** - Files → UnixFS DAG → root CID
-3. **Diff** - Compare local vs pail entries
-4. **Batch** - Generate UCN revision with all changes
-5. **Upload** - All blocks → CAR → Storacha
-6. **Apply** - Remote changes → local filesystem
+| Command | Description |
+|---------|-------------|
+| `init --agent <id>` | Generate agent identity (Ed25519 keypair) |
+| `setup --agent <id>` | Create a new Storacha Space via login |
+| `join <bundle> --agent <id>` | Join an existing workspace from a delegation bundle |
+| `grant <DID> --agent <id>` | Create a delegation bundle for another device |
+| `status --agent <id>` | Show sync status (delegations, space, running state) |
+| `inspect --agent <id>` | Debug internal state (pail entries, pending ops, revisions) |
+| `onboard --agent <id>` | Interactive guided setup |
 
-## Configuration
+### Grant Options
 
-In your OpenClaw config:
-
-```yaml
-plugins:
-  entries:
-    storacha-sync:
-      enabled: true
-      config:
-        watchPatterns:
-          - "**/*.md"
-        ignorePatterns:
-          - ".git"
-          - "node_modules"
-          - ".storacha"
+```bash
+# Output bundle as base64 to stdout (default)
+openclaw clawracha grant did:key:z6Mk... --agent myagent
+
+# Write bundle to a file instead
+openclaw clawracha grant did:key:z6Mk... --agent myagent -o bundle.car
 ```
 
 ## Agent Tools
 
-The plugin provides tools for manual sync control:
+When the plugin is running, agents get two MCP tools:
 
-- `storacha_sync_status` - Get current sync status
-- `storacha_sync_now` - Trigger immediate sync
+- **`storacha_sync_status`** — Check current sync state (running, last sync, entry count, pending changes)
+- **`storacha_sync_now`** — Trigger an immediate sync cycle
 
-## Architecture
+## How Sync Works
 
+1. **File watcher** (chokidar) detects changes in the workspace
+2. Changed files are encoded:
+   - Regular files → UnixFS DAG blocks
+   - Markdown files → CRDT entry via md-merge (RGA tree + event history)
+   - Private spaces → encrypted before encoding
+3. Changes become pail operations (put/del)
+4. Operations are batched into a UCN revision and published
+5. All blocks are packed into a CAR file and uploaded to Storacha
+6. Remote changes from other devices are pulled, diffed, and applied locally
+
+See [docs/architecture.md](docs/architecture.md) for the full technical deep-dive and [docs/reference.md](docs/reference.md) for hidden features, edge cases, and troubleshooting.
+
+## Configuration
+
+In your OpenClaw plugin config:
+
+```json
+{
+  "plugins": {
+    "clawracha": {
+      "enabled": true,
+      "watchPatterns": ["**/*"],
+      "ignorePatterns": [".git", "node_modules", ".storacha"]
+    }
+  }
+}
 ```
-┌─────────────────────────────────────────────────────────┐
-│  OpenClaw Agent Workspace                               │
-│  ┌─────────────────┐     ┌─────────────────┐            │
-│  │  Workspace      │◄───►│  File Watcher   │            │
-│  │  *.md files     │     │  (chokidar)     │            │
-│  └─────────────────┘     └────────┬────────┘            │
-│           │                       │                     │
-│           ▼                       ▼                     │
-│  ┌─────────────────┐     ┌─────────────────┐            │
-│  │  .storacha/     │     │  Sync Engine    │            │
-│  │  ├─ config.json │◄───►│  (UCN Pail)     │            │
-│  │  └─ blocks/     │     └────────┬────────┘            │
-│  └─────────────────┘              │                     │
-└───────────────────────────────────┼─────────────────────┘
-                                    │
-                                    ▼ publish/resolve
-┌───────────────────────────────────────────────────────┐
-│  Storacha Network                                     │
-│  ┌───────────────────┐  ┌───────────────────────────┐ │
-│  │  UCN Rendezvous   │  │  Storage Nodes            │ │
-│  │  (clock/head)     │  │  (blob storage)           │ │
-│  └───────────────────┘  └───────────────────────────┘ │
-└───────────────────────────────────────────────────────┘
-```
 
-## Local Data
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `false` | Enable/disable the sync plugin |
+| `watchPatterns` | `["**/*"]` | Glob patterns for files to sync |
+| `ignorePatterns` | `[".git", "node_modules", ".storacha"]` | Glob patterns to exclude |
+
+## Public vs Private Spaces
+
+During setup, you choose the access type:
 
-The plugin stores data in `.storacha/` within the workspace:
+- **Public** — Files are stored as plaintext on IPFS/Filecoin. Anyone with the CID can access them.
+- **Private (encrypted)** — Files are encrypted via Storacha's KMS before upload. Only devices with the proper delegations can decrypt.
 
-- `config.json` - Agent key, delegations, name archive (NOT synced)
-- `blocks/` - Local block cache (NOT synced)
+Private spaces use `@storacha/encrypt-upload-client` with Google KMS for key management. The plan delegation grants KMS access, and decrypt delegations are scoped per-CID with 15-minute expiry.
 
-Add `.storacha/` to your `.gitignore`.
+## Requirements
 
-## Status
+- Node.js ≥ 20
+- OpenClaw ≥ 2026.0.0
+- A [Storacha account](https://console.storacha.network) with an active payment plan
 
-🚧 **Work in Progress**
+## Docs
 
-- [x] Plugin scaffold
-- [x] Tiered blockstore (memory → disk → gateway)
-- [x] File encoder (UnixFS)
-- [x] Differ (local ↔ pail)
-- [x] Sync engine (UCN Pail batch)
-- [x] File watcher
-- [x] OpenClaw plugin integration
-- [ ] CAR upload to Storacha
-- [ ] Remote file download/apply
-- [ ] Encryption (encrypt-upload-client)
-- [ ] Full test coverage
+- **[Architecture Guide](docs/architecture.md)** — How it works under the hood (sync lifecycle, CRDT merge, blockstore tiers, encryption, delegation model)
+- **[Reference](docs/reference.md)** — `.clawrachaignore`, `inspect` command, delegation encoding, troubleshooting
 
 ## License
 

package/dist/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAe,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoB3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACpD,OAAO,CAAC,IAAI,CAAC,CAqCf;AAID,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,UAAU,EAAE,OAAO,EACnB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACnE,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAmC/B;AAID,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAsB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAsBnE;AAED,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,aAAa,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACrD,OAAO,CAAC,WAAW,CAAC,CAsGtB;AA2BD,wBAAsB,MAAM,CAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,aAAa,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACrD,OAAO,CAAC,UAAU,CAAC,CAkErB;AAED,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,MAAM,IAAI,MAAM,EAAE,GACnC,OAAO,CAAC,UAAU,CAAC,CAyDrB"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EACV,YAAY,EAEZ,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAoB3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAS9B;AAED,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACpD,OAAO,CAAC,IAAI,CAAC,CAqCf;AAID,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,UAAU,EAAE,OAAO,EACnB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACnE,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAmC/B;AAID,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAsB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAsBnE;AAED,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,aAAa,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACrD,OAAO,CAAC,WAAW,CAAC,CAsGtB;AA2BD,wBAAsB,MAAM,CAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,OAAO,CAAC,gBAAgB,CAAC,EACvC,aAAa,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,GACrD,OAAO,CAAC,UAAU,CAAC,CAkErB;AAED,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,MAAM,IAAI,MAAM,EAAE,GACnC,OAAO,CAAC,UAAU,CAAC,CAyDrB"}

package/dist/commands.js

@@ -9,7 +9,7 @@ import * as path from "node:path";
 import { SyncEngine } from "./sync.js";
 import { FileWatcher } from "./watcher.js";
 import { encodeDelegation, decodeDelegation, } from "./utils/delegation.js";
-import { createStorachaClient } from "./utils/client.js";
+import { createStorachaClient } from "./utils/config.js";
 import { createDelegationBundle, extractDelegationBundle, } from "./utils/bundle.js";
 import { Agent, Name } from "@storacha/ucn/pail";
 import { extract } from "@storacha/client/delegation";
@@ -72,8 +72,8 @@ export async function startWorkspaceSync(workspace, agentId, pluginConfig, initi
     if (!deviceConfig || !deviceConfig.setupComplete) {
         return null;
     }
-    const engine = new SyncEngine(workspace);
-    await engine.init(deviceConfig);
+    const engine = await SyncEngine.fromConfig(workspace, deviceConfig);
+    await engine.start();
     const watcher = new FileWatcher({
         workspace,
         config: {

package/dist/handlers/apply.d.ts

@@ -4,17 +4,9 @@
  * Cycle: operation → publish → return value.
  * Bootstraps with v0Put when no current value exists.
  */
-import type { ClockConnection, NameView, ValueView, EventBlock } from "@storacha/ucn/pail/api";
-import type { Block } from "multiformats";
+import type { ValueView, RevisionResult, BlockFetcher } from "@storacha/ucn/pail/api";
 import type { PailOp } from "../types/index.js";
-import type { WorkspaceBlockstore } from "../blockstore/index.js";
-export interface ApplyResult {
-    current: ValueView | null;
-    event: EventBlock | null;
-    revisionBlocks: Block[];
+export declare function applyPendingOps(blocks: BlockFetcher, current: ValueView | null, pendingOps: PailOp[]): Promise<RevisionResult & {
     remainingOps: PailOp[];
-}
-export declare function applyPendingOps(blocks: WorkspaceBlockstore, name: NameView, current: ValueView | null, pendingOps: PailOp[], options?: {
-    remotes?: ClockConnection[];
-}): Promise<ApplyResult>;
+}>;
 //# sourceMappingURL=apply.d.ts.map

package/dist/handlers/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/handlers/apply.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,SAAS,EACT,UAAU,EACX,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,KAAK,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,eAAe,EAAE,CAAA;CAAE,GACxC,OAAO,CAAC,WAAW,CAAC,CA8DtB"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/handlers/apply.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACb,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,cAAc,GAAG;IAAE,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA4BtD"}

package/dist/handlers/apply.js

@@ -6,39 +6,20 @@
  */
 import { Revision } from "@storacha/ucn/pail";
 import * as Batch from "@storacha/ucn/pail/batch";
-import { MemoryBlockstore, withCache } from "@storacha/ucn/block";
-export async function applyPendingOps(blocks, name, current, pendingOps, options) {
-    const revisionBlocks = [];
+export async function applyPendingOps(blocks, current, pendingOps) {
     let ops = [...pendingOps];
-    // Local cache so each step can read blocks produced by previous steps
-    const cache = new MemoryBlockstore();
-    const fetcher = withCache(blocks, cache);
-    const accumulate = (additions) => {
-        for (const block of additions) {
-            cache.put(block);
-        }
-        revisionBlocks.push(...additions);
-    };
     if (!current) {
         const firstPut = ops.find((op) => op.type === "put" && op.value);
         if (firstPut?.value) {
-            const result = await Revision.v0Put(fetcher, firstPut.key, firstPut.value);
-            accumulate(result.additions);
-            const pubResult = await Revision.publish(fetcher, name, result.revision, {
-                remotes: options?.remotes,
-            });
-            accumulate(pubResult.additions);
-            current = pubResult.value;
+            const result = await Revision.v0Put(blocks, firstPut.key, firstPut.value);
             return {
-                current,
-                event: result.revision.event,
-                revisionBlocks,
+                ...result,
                 remainingOps: ops.filter((op) => op !== firstPut),
             };
         }
         throw new Error("No current value or pending puts to initialize with");
     }
-    const batcher = await Batch.create(fetcher, current);
+    const batcher = await Batch.create(blocks, current);
     for (const op of ops) {
         if (op.type === "put" && op.value) {
             await batcher.put(op.key, op.value);
@@ -48,16 +29,8 @@ export async function applyPendingOps(blocks, name, current, pendingOps, options
         }
     }
     const result = await batcher.commit();
-    accumulate(result.additions);
-    const pubResult = await Revision.publish(fetcher, name, result.revision, {
-        remotes: options?.remotes,
-    });
-    accumulate(pubResult.additions);
-    current = pubResult.value;
     return {
-        current,
-        event: result.revision.event,
-        revisionBlocks,
+        ...result,
         remainingOps: [], // All ops were included in the batch, so none remain
     };
 }

package/dist/handlers/process.d.ts

@@ -7,14 +7,10 @@
  * When encryptionConfig is provided (private spaces), content is encrypted
  * before upload via encryptToBlockStream.
  */
-import { CID } from "multiformats/cid";
 import type { BlockFetcher, ValueView } from "@storacha/ucn/pail/api";
 import type { Block } from "multiformats";
-import type { FileChange, PailOp } from "../types/index.js";
-import type { EncryptionConfig } from "@storacha/encrypt-upload-client/types";
-/** Callback to persist a block to the CAR file for upload. */
+import type { ContentFetcher, Encoder, FileChange, PailOp } from "../types/index.js";
+/** Callback to persist a block (CAR file, local blockstore, etc). */
 export type BlockSink = (block: Block) => Promise<void>;
-/** Callback to persist a block to the local blockstore for future reads. */
-export type BlockStore = (block: Block) => Promise<void>;
-export declare function processChanges(changes: FileChange[], workspace: string, current: ValueView | null, blocks: BlockFetcher, sink: BlockSink, store?: BlockStore, encryptionConfig?: EncryptionConfig, decrypt?: (cid: CID) => Promise<Uint8Array>): Promise<PailOp[]>;
+export declare function processChanges(changes: FileChange[], workspace: string, current: ValueView | null, blocks: BlockFetcher, sink: BlockSink, encoder: Encoder, contentFetcher: ContentFetcher): Promise<PailOp[]>;
 //# sourceMappingURL=process.d.ts.map

package/dist/handlers/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/handlers/process.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAEvC,OAAO,KAAK,EACV,YAAY,EAEZ,SAAS,EACV,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAO9E,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExD,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAqBzD,wBAAsB,cAAc,CAClC,OAAO,EAAE,UAAU,EAAE,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,EACf,KAAK,CAAC,EAAE,UAAU,EAClB,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,UAAU,CAAC,GAC1C,OAAO,CAAC,MAAM,EAAE,CAAC,CA6GnB"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/handlers/process.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,YAAY,EAEZ,SAAS,EACV,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EACV,cAAc,EACd,OAAO,EACP,UAAU,EACV,MAAM,EACP,MAAM,mBAAmB,CAAC;AAK3B,qEAAqE;AACrE,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAqBxD,wBAAsB,cAAc,CAClC,OAAO,EAAE,UAAU,EAAE,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAiFnB"}