hivecast-sdk/README.md

# HiveCast SDK

HiveCast SDK is the package-author layer for building Matrix actors, browser
surfaces, and broker-connected applications without depending on a managed
platform repo.

This repository contains the SDK packages under their target `@open-matrix/*`
package names. The workspace is
proven as a standalone workspace: a fresh clone can install, build, test,
type-check, pack every package, and compile an external consumer against the
packed tarballs.

## What You Can Build

- Headless actors with `MatrixActor`
- Browser custom elements with `MatrixActorHtmlElement`
- In-memory actor graphs for tests and local development
- NATS-backed transports for broker-connected actors
- Browser host integrations for Matrix web surfaces
- Package-author CLIs and project scaffolds

HiveCast SDK is provider-neutral. It does not require a managed platform account,
device-link ceremony, host-link implementation, managed host service, local
platform install, Postgres database, or provider-owned broker authority. A
provider overlay can issue broker credentials and host runtimes on top of the
SDK, but the SDK itself must remain usable against any compatible broker.

See [STANDALONE-AUDIT.md](STANDALONE-AUDIT.md) for the current standalone
boundary audit, including the remaining Omega/oracle extraction debt that is not
part of the package-author SDK proof.

## Packages

| Package | Purpose |
| --- | --- |
| `@open-matrix/hivecast-sdk` | Public umbrella facade for actor/package authors |
| `@open-matrix/core` | Actor kernel, runtime, transports, serialization, browser actor base classes |
| `@open-matrix/cli` | Package-author `matrix` CLI |
| `@open-matrix/browser-kit` | Browser app shims, theme tokens, Vite helpers, shell components |
| `@open-matrix/browser-host` | Browser runtime host shell and app-ready integration |
| `@open-matrix/contracts` | Shared type contracts for placement, service registry, and runtime presence |
| `@open-matrix/federation` | Cross-realm messaging, MX envelope handling, and routing helpers |
| `@open-matrix/omega-core` | Narrow Omega interpreter facade used by Matrix membranes |

Prefer narrow imports when possible:

```ts
import { MatrixActor } from '@open-matrix/core';
```

Use the umbrella package when you intentionally want the public SDK facade:

```ts
import { MatrixActor } from '@open-matrix/hivecast-sdk';
```

## Quick Start

```bash
git clone https://registry.hivecast.ai/open-matrix/hivecast-sdk.git
cd hivecast-sdk
pnpm install --frozen-lockfile
pnpm prove
```

`pnpm prove` runs the standalone proof:

```text
clean -> build -> test -> type-check -> pack all packages
```

For the external-consumer proof:

```bash
pnpm prove:external-consumer
```

That proof packs the SDK packages, creates a temporary consumer outside this
repo, installs the packed tarballs, compiles TypeScript, starts a `MatrixActor`,
and calls it through the Matrix runtime/transport path.

## Minimal Actor

```ts
import {
  InMemoryBroker,
  InMemoryTransport,
  MatrixActor,
  MatrixRuntime,
  TopicRouter,
} from '@open-matrix/core';

class EchoActor extends MatrixActor {
  static accepts = {
    echo: {},
  };

  onEcho(payload: { message?: string }) {
    return {
      ok: true,
      message: payload.message ?? null,
    };
  }
}

const broker = new InMemoryBroker();
const transport = new InMemoryTransport(broker, { name: 'demo' });
const runtime = new MatrixRuntime({ transport, logging: false });

await runtime.create(EchoActor, 'demo.echo');

const replyTo = '$replies.demo';
const response = new Promise((resolve) => {
  const unsubscribe = transport.subscribe(replyTo, (value) => {
    unsubscribe();
    resolve(value);
  });
});

transport.publish(TopicRouter.inbox('demo.echo'), {
  op: 'echo',
  payload: { message: 'hello' },
  replyTo,
  correlationId: 'demo-1',
});

console.log(await response);
await runtime.shutdown();
```

## CLI

The SDK CLI package owns the package-author `matrix` binary.

```bash
matrix init [dir]
matrix add actor <name>
matrix actor <name>
matrix configure --key <key> --cloud <url> --space <space>
matrix run <entry> --mount <mount>
matrix invoke <mount> <op> [json]
```

The current SDK CLI acceptance proof is:

```bash
pnpm prove:cli-uat
```

The command name uses `uat`, but its scope is only the SDK package-author CLI
flow. It is not managed-platform product UAT, browser signup/login UAT,
API-key UI UAT, or live deployment proof.

The CLI is intended to let a package author initialize a folder, add actors,
configure broker access, run actors, and invoke them without importing provider
overlay packages into the SDK layer. Managed-host promotion is optional and is
only exercised when `MATRIX_SDK_RUNTIME_HOST_BIN` is supplied.

## Demos

Standalone SDK demo, no provider account or key required:

```bash
pnpm demo:standalone
```

This builds the SDK and `examples/standalone-greeter`, starts the actor with
`matrix run`, calls it with `matrix invoke`, and shuts it down.

HiveCast API-key login/config demo:

```bash
export MATRIX_CLOUD=https://dev.hivecast.ai
export MATRIX_SPACE=<your-space-root>
export MATRIX_API_KEY=<your-api-key>
pnpm demo:hivecast-login
```

This validates the key with HiveCast and writes the SDK package-local
`.matrix/config.json` plus `.matrix/credentials/matrix-api-key.json` shape
without printing or committing the key. By default the demo uses a temporary
home and deletes it after success.

Current boundary: this HiveCast demo proves SDK-side key validation and config
storage. It does not yet prove a package running directly on a HiveCast-issued
broker credential. That requires the provider-owned login/credential-exchange
slice so `matrix login` can replace manual `matrix configure` and issue/store
the broker credentials needed by the SDK transport.

## Repository Layout

```text
packages/
  browser-host/
  browser-kit/
  cli/
  contracts/
  core/
  federation/
  omega-core/
  sdk/
scripts/
  demo:standalone
  demo:hivecast-login
  prove-external-consumer.mjs
  prove-sdk-cli-uat.mjs
```

## Current Status

Done and proven:

- The SDK packages build independently from their original source monorepo.
- Package identities use final `@open-matrix/*` names.
- `@open-matrix/hivecast-sdk` re-exports the public actor facade.
- A fresh clone passes `pnpm install --frozen-lockfile && pnpm prove`.
- A temporary external consumer can install packed SDK tarballs, compile, start
  a `MatrixActor`, and call it through Matrix runtime/transport.

Still planned:

- Provider-neutral credential resolution for `matrix configure` and SDK users.
- Provider login commands that write the same config shape as
  `matrix configure`.
- Direct broker mode with explicit broker URL/JWT/seed credentials.
- Managed-provider mode where an overlay issues scoped broker credentials.

Publishing is intentionally not part of this repository's normal developer
workflow yet. The repo proves source, package, and consumer behavior with
`pnpm pack`; public package release is an owner-controlled release decision and
must be added as an explicit release policy before any npm publication.

## Relationship To Provider Overlays

HiveCast SDK is the provider-neutral actor SDK.

Provider overlays can provide account management, namespaces, API keys, broker
credential issuance, runtime hosting, package distribution, and operator UI.
SDK users should still be able to connect to another broker directly when they
already manage their own broker credentials.