@dxos/halo 0.0.0

package/CONSUMER_MIGRATION.md

@@ -0,0 +1,343 @@
+# Consumer Migration — `@dxos/client` HALO → `@dxos/halo` services
+
+How to move Composer (`packages/apps/composer-app`) and the plugins
+(`packages/plugins/*`) off direct `@dxos/client` HALO access and onto the
+`@dxos/halo` Effect services (backed by `@dxos/halo-adapter-client`).
+
+Companion to [API_AUDIT.md](./API_AUDIT.md) (what the consumers use today) and
+[MIGRATION.md](./MIGRATION.md) (the HALO → Keyhive backend rewrite). This
+document is the practical cookbook: the decisive verdict on coverage, then
+before→after patterns for the cases the services already handle.
+
+## Verdict
+
+**The new API cannot yet replace `@dxos/client` everywhere in Composer and the
+plugins.** The two services (`Identity`, `Space`) — plus the serviceless
+`Invitation` flow types/verbs — cover the imperative HALO surface:
+identity/device lifecycle, space management and membership, and the invitation
+state machine (initiation and querying live on `Identity`/`Space`). The
+`layerClient(client)`
+composition root drops in wherever a plugin already holds a `Client`. That is
+enough to migrate imperative call sites (operation handlers, CLI commands,
+managers, import scripts).
+
+It is **not** enough to migrate the codebase wholesale. Four gaps remain, each
+with an agreed disposition:
+
+1. **React bindings — `@dxos/halo-react`.** There are ~368 uses of
+   `useIdentity` / `useDevices` / `useCredentials` / `useSpaces` / `useSpace` /
+   `useMembers` / `useSpaceInvitations` across 163 files — the bulk of the
+   consumer surface. The new [`@dxos/halo-react`](../halo-react) hook library
+   provides drop-in equivalents backed by the HALO services (each reactive read
+   is a current-value `Stream` surfaced through `@effect-atom` atoms and
+   `useAtomValue`). Components migrate hook-by-hook
+   by swapping the import and wrapping the tree in `HaloProvider` instead of
+   `ClientProvider`; see [Migrating React hooks](#migrating-react-hooks). Hooks
+   with no service verb yet (`useCredentials`) stay on `@dxos/react-client`.
+2. **ECHO database access — a separate track, by design.** `Space.Info` is a
+   plain snapshot, not a live proxy — it has no `.db`, `.crud`, `.properties`,
+   or `.internal`. The heavy `space.db.*` / `space.internal.*` usage is ECHO,
+   not HALO, and belongs on the `@dxos/echo` `Database` service keyed by
+   `SpaceId`. This is not folded into HALO. See API_AUDIT.md §3.6.
+3. **Deferred verbs — planned, not yet defined.** Credentials
+   (`halo.queryCredentials` / `writeCredentials`), recovery-credential
+   _creation_ (`createRecoveryCredential` / `requestRecoveryChallenge`), EDGE
+   `createEdgeIdentity` / attestation, and device _update_ will be added as
+   `Identity`-service verbs in a follow-up. Consumers of those stay on the
+   client until then.
+4. **Space create/lifecycle gaps — mostly closed.** `Space.create` now accepts
+   `{ name?, tags?, membershipPolicy? }`, and EDGE replication is toggled with
+   `Space.setEdgeReplication(id, setting)`. `migrate` is intentionally left out.
+   `State` remains the consumer-relevant subset (`inactive` / `closed` /
+   `ready`), not the full `SpaceState` enum.
+
+So: migrate imperative HALO call sites now; leave React components and ECHO
+access on `@dxos/client` until the binding rewrite and the ECHO `Database`
+service land, and the deferred verbs (§3) until they are defined. The rest of
+this doc covers the cases that _can_ move.
+
+## Composition root
+
+Every plugin already obtains its `Client` from the
+`ClientCapabilities.Client` capability provided by `plugin-client` — a single
+injection point. Build the HALO layer once from that client and provide it to
+any effect:
+
+```ts
+import { layerClient } from '@dxos/halo-adapter-client';
+import { Identity, Space } from '@dxos/halo';
+
+const halo = layerClient(client); // Layer<Identity.Service | Space.Service>
+
+const program = Effect.gen(function* () {
+  // Reactive reads are current-value streams; take the head for a one-shot snapshot.
+  const identity = yield* Stream.runHead(Identity.identity);
+  const spaces = yield* Stream.runHead(Space.spaces);
+  // ...
+});
+
+await Effect.runPromise(program.pipe(Effect.provide(halo)));
+```
+
+`layerClient` is the seam that replaces direct `@dxos/client` access for HALO
+concerns. The backend behind it (legacy client, EDGE shim, or Keyhive) can swap
+without touching consumers.
+
+## Migrating React hooks
+
+Most consumer usage is React hooks, not imperative calls. The
+[`@dxos/halo-react`](../halo-react) package mirrors `@dxos/react-client`'s
+HALO/space hooks, backed by the services. Migration is mechanical: swap the
+provider, then swap imports hook-by-hook.
+
+**1. Swap the provider.** `@dxos/halo-react` reads the services off a React
+context holding an Effect `Context.Context<Identity | Space | Invitation>`.
+Build that context once (from the client adapter, or any backing) and wrap the
+tree:
+
+```tsx
+import { Context } from 'effect';
+import { Identity, Space } from '@dxos/halo';
+import { makeIdentityService, makeSpaceService } from '@dxos/halo-adapter-client';
+import { HaloProvider } from '@dxos/halo-react';
+
+const services = Context.empty().pipe(
+  Context.add(Identity.Service, makeIdentityService(client)),
+  Context.add(Space.Service, makeSpaceService(client)),
+);
+
+// Replaces <ClientProvider> for HALO concerns.
+<HaloProvider services={services}>{children}</HaloProvider>;
+```
+
+In a plugin this context is built once at the `plugin-client` composition root
+(where the `Client` capability lives) and provided app-wide.
+
+**2. Swap the hooks.** Same names, same call shape; the returned values are the
+HALO snapshot types (`Identity.Info`, `Space.Info`, `Space.Member`,
+`Invitation.Flow`) instead of the client proxy types.
+
+| `@dxos/react-client` hook         | `@dxos/halo-react` hook                                         | Return type                       | Notes                                                         |
+| --------------------------------- | --------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------- |
+| `useIdentity(): Identity \| null` | `useIdentity(): Identity.Info \| undefined`                     | `{ did, displayName? }`           | `null` → `undefined`; `did` replaces `identityKey`/`spaceKey` |
+| `useDevices(): Device[]`          | `useDevices(): readonly Identity.DeviceInfo[]`                  | `{ key, kind?, label?, current }` | —                                                             |
+| `useSpaces({ all? }): Space[]`    | `useSpaces({ all? }): readonly Space.Info[]`                    | `{ id, name?, state }`            | same `all` option and `ready`-only default                    |
+| `useSpace(id \| key): Space`      | `useSpace(id?: SpaceId): Space.Info \| undefined`               | snapshot                          | `SpaceId` only — no `PublicKey`                               |
+| `useMembers(key): SpaceMember[]`  | `useMembers(id?: SpaceId): readonly Space.Member[]`             | `{ did?, role, online }`          | takes a `SpaceId`, not a key; `role` is `Space.Access`        |
+| `useSpaceInvitations(id \| key)`  | `useSpaceInvitations(id?: SpaceId): readonly Invitation.Flow[]` | `Invitation.Flow[]`               | drive each flow via the `Invitation` verbs                    |
+| `useHaloInvitations()`            | `useHaloInvitations(): readonly Invitation.Flow[]`              | `Invitation.Flow[]`               | —                                                             |
+| `useCredentials()`                | _not yet_                                                       | —                                 | no credential verb yet (§3) — stays on `@dxos/react-client`   |
+
+```tsx
+// Before
+import { useIdentity } from '@dxos/react-client/halo';
+import { useSpaces, useMembers } from '@dxos/react-client/echo';
+
+// After
+import { useIdentity, useSpaces, useMembers } from '@dxos/halo-react';
+```
+
+**3. ECHO stays put.** `useQuery` and other `@dxos/react-client/echo` database
+hooks are ECHO, not HALO — they do not move here (§2).
+
+For imperative call sites (operation handlers, CLI commands), use the service
+verbs directly rather than hooks — those patterns follow.
+
+## Patterns
+
+Each pattern shows the current `@dxos/client` call and its `@dxos/halo`
+equivalent. All effects require the corresponding service in `R`; provide
+`layerClient(client)`.
+
+### Identity — read / gate
+
+```ts
+// Before
+const identity = client.halo.identity.get();
+if (!identity) return;
+const did = identity.did;
+
+// After — reads are current-value streams; take the head for a one-shot read
+const maybe = Option.flatten(yield * Stream.runHead(Identity.identity)); // Option<Identity.Info>
+if (Option.isNone(maybe)) return;
+const did = maybe.value.did;
+```
+
+Field reads change shape: `Identity.Info` is `{ did, displayName? }`.
+`identityKey` / `spaceKey` (credential plumbing) are intentionally dropped in
+favor of the DID.
+
+### Identity — subscribe
+
+```ts
+// Before
+const sub = client.halo.identity.subscribe((identity) => onChange(identity));
+// ... sub.unsubscribe();
+
+// After — the same stream, subscribed instead of head-read; completes when the scope closes
+yield * Stream.runForEach(Identity.identity, (maybe) => Effect.sync(() => onChange(maybe)));
+```
+
+### Identity — create / update profile
+
+```ts
+// Before
+await client.halo.createIdentity({ displayName: 'Alice' });
+await client.halo.updateProfile({ displayName: 'Alice B.' });
+
+// After
+const info = yield * Identity.create({ displayName: 'Alice', deviceLabel: 'laptop' });
+yield * Identity.updateProfile({ displayName: 'Alice B.' });
+```
+
+### Devices
+
+```ts
+// Before
+const devices = client.halo.devices.get();
+
+// After — Identity.devices is a current-value stream
+const devices = yield * Stream.runHead(Identity.devices); // Option<readonly DeviceInfo[]>  ({ key, kind?, label?, current })
+```
+
+`DeviceInfo.kind` is the inlined `Identity.DeviceKind` literal
+(`'unknown' | 'browser' | 'native' | 'mobile' | 'agent' | 'agent-managed'`),
+replacing the protobuf `DeviceType` enum. **Device _update_ is not defined** —
+stay on the client for that.
+
+### Spaces — list / get
+
+```ts
+// Before
+const spaces = client.spaces.get();
+const space = getSpace(object) ?? client.spaces.get(spaceId);
+
+// After — Space.spaces is a current-value stream; get is a point lookup
+const spaces = yield * Stream.runHead(Space.spaces); // Option<readonly Space.Info[]>
+const maybe = yield * Space.get(spaceId); // Option<Space.Info>
+```
+
+`Space.Info` is `{ id, name?, state }` — a snapshot. For `space.db` / query /
+properties, use `@dxos/echo` keyed by `Space.Info.id`; do not expect a proxy.
+
+### Spaces — create
+
+```ts
+// Before
+const space = await client.spaces.create({ name: 'Project' }, { tags: ['team'], membershipPolicy });
+await space.internal.setEdgeReplicationPreference(EdgeReplicationSetting.ENABLED);
+
+// After
+const info = yield * Space.create({ name: 'Project', tags: ['team'], membershipPolicy: 'invite' });
+yield * Space.setEdgeReplication(info.id, 'enabled');
+```
+
+`membershipPolicy` is `'invite' | 'locked'` and `setEdgeReplication` takes
+`'disabled' | 'enabled'` (the adapter maps the legacy protobuf enums). **Gap:**
+`migrate` is intentionally not modeled — call sites needing it stay on the
+client.
+
+### Spaces — wait ready
+
+```ts
+// Before
+await space.waitUntilReady();
+
+// After
+yield * Space.waitReady(spaceId);
+```
+
+### Members
+
+```ts
+// Before
+const members = space.members.get(); // SpaceMember[]
+
+// After — Space.members(id) is a current-value stream
+const members = yield * Stream.runHead(Space.members(spaceId)); // Option<readonly Space.Member[]>  ({ did?, role, online })
+```
+
+`Member.role` is the Keyhive-aligned `Space.Access`
+(`'pull' | 'read' | 'edit' | 'admin'`); the adapter maps the legacy
+`SpaceMember.Role` enum. `updateMemberRole(id, did, role)` and
+`removeMember(id, did)` are defined (removal re-keys the space and does not
+converge in the in-memory test harness — see the e2e NOTE).
+
+### Export / import
+
+```ts
+// Before — via client space handle
+// After
+const archive = yield* Space.exportSpace(spaceId); // { filename, contents }
+const info = yield* Space.importSpace(archive, { tags: [...] });
+```
+
+### Invitations — share (host)
+
+Initiation lives on `Identity` / `Space` (not on `Invitation`); the returned
+`Flow` is then driven through the `Invitation` verbs.
+
+```ts
+// Before
+const observable = space.share({ authMethod: Invitation.AuthMethod.NONE });
+observable.subscribe((invitation) => {
+  /* switch on invitation.state */
+});
+const code = InvitationEncoder.encode(observable.get());
+
+// After
+const flow = yield * Space.share(spaceId, { authMethod: 'none' }); // Invitation.Flow
+const code = yield * Invitation.code(flow);
+yield *
+  Stream.runForEach(Invitation.events(flow), (event) =>
+    Effect.sync(() => {
+      // event._tag: 'connecting' | 'connected' | 'readyForAuthentication'
+      //           | 'authenticating' | 'success' | 'cancelled' | 'error'
+    }),
+  );
+```
+
+Device invitations are identical with `Identity.share(options?)`.
+
+### Invitations — join (guest) + authenticate
+
+```ts
+// Before
+const observable = client.spaces.join(InvitationEncoder.decode(code));
+observable.subscribe(/* ... */);
+await observable.authenticate(authCode);
+
+// After
+const flow = yield * Space.join(code); // decodes internally
+yield *
+  Stream.runForEach(Invitation.events(flow), (event) =>
+    event._tag === 'readyForAuthentication' ? Invitation.authenticate(flow, authCode) : Effect.void,
+  );
+```
+
+`Identity.join(code)` is the device equivalent. `Invitation.cancel(flow)` aborts.
+
+### Invitations — observe active flows
+
+```ts
+// Before
+const invitations = space.invitations.get();
+
+// After — querying lives on the owning service as a current-value stream
+const flows = yield * Stream.runHead(Space.invitations(spaceId)); // device: Identity.invitations
+```
+
+Drive an individual `Invitation.Flow` through the flow verbs (`Invitation.events`
+/ `authenticate` / `cancel` / `code`), which need no service.
+
+## What stays on `@dxos/client` (for now)
+
+| Area                                                                                          | Reason                               | Unblocks when                                                                              |
+| --------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `useCredentials`                                                                              | no service verb yet                  | credential verbs added to `Identity` (the other HALO hooks now live in `@dxos/halo-react`) |
+| `space.db` / `space.crud` / `space.properties` / `space.internal.*` (except edge replication) | ECHO, not HALO                       | migrate to the `@dxos/echo` `Database` service keyed by `SpaceId`                          |
+| `halo.queryCredentials` / `writeCredentials`; recovery-credential _creation_                  | deferred verb                        | credential + recovery verbs added to `Identity`                                            |
+| `createEdgeIdentity` / EDGE attestation                                                       | deferred verb                        | EDGE verbs added to `Identity`                                                             |
+| device _update_                                                                               | deferred verb                        | `Identity` device-update verb added                                                        |
+| `space.internal.migrate`                                                                      | intentionally out of scope           | (revisit if needed)                                                                        |
+| full `SpaceState` enum                                                                        | `Space.State` is the consumer subset | (by design)                                                                                |

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 DXOS
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.