hivecast-sdk/STANDALONE-AUDIT.md

# Standalone SDK Audit

Date: 2026-06-07

This repository is intended to be a standalone Matrix SDK repository. The SDK
packages must be usable without the HiveCast application monorepo, without
Matrix-3 path assumptions, and without platform-only concepts such as Device
Link, Host Link, system-auth, or gateway internals.

## Current Result

The SDK package surface is standalone enough for the current authoring proof:

- A fresh consumer can install `@open-matrix/sdk` and `@open-matrix/cli` from an
  npm-compatible registry.
- `matrix broker setup` installs a project-local `nats-server` binary for demos.
- `matrix broker start` starts that local broker without a HiveCast account or
  preinstalled Matrix binary.
- `matrix actor run <entry> --check-op <op>` starts a direct actor and calls it
  through the Matrix runtime/transport path.
- Actor handlers are validated before broker connection: `accepts.echo` must be
  implemented as `onEcho(payload)`, not `echo(payload)`.

The fresh Docker proof checks that the package-manager install path has no
Matrix/HiveCast preinstall dependency and that bad actor handlers fail loudly
instead of timing out.

Checked-in demos now cover the same boundary in user-facing form:

- `pnpm demo:standalone` runs `demos/standalone-greeter` without provider
  credentials.
- `demos/fresh-server-actor` shows a server-side actor using HiveCast-exchanged
  broker credentials.
- `demos/fresh-web-page` shows a browser actor/web page using HiveCast-exchanged
  broker credentials.

## Cleanup Completed

- Root README now describes this as a provider-neutral SDK, not a HiveCast
  application shard.
- Core package README and metadata use `@open-matrix/*` names and this repo URL.
- Browser host strings describe generic managed HTTP/broker surfaces instead of
  HiveCast-specific local/dev URLs.
- CLI docs describe standalone SDK boundaries and optional provider-managed
  broker credential files without naming product-only packages as part of the
  SDK.
- The SDK CLI proof no longer defaults to a HiveCast binary, `dev.hivecast.ai`,
  Host Service, or Device Link.
- The internal theme manifest uses `@open-matrix/theme`.

## Intentional Guard Strings

Some upper-layer names remain only as forbidden-token checks inside proof
scripts. They are not dependencies, defaults, or runtime integration points.
They fail the proof if a generated SDK author package leaks those names.

Examples:

- `hivecast`
- `projects/matrix-3`
- `matrix-work-harness`
- `@matrix/mx-cli`

## Remaining Structural Debt

The repo still contains extraction residue that should be cleaned in the next
repo-hygiene slice:

- Top-level `src/` is an Omega source tree used by `@open-matrix/omega-core`
  through relative imports.
- `packages/oracle/` is not part of the current SDK workspace packages, but it
  remains in the repository and some top-level Omega files reference it.
- Some non-workspace Omega/oracle files reference `@open-matrix/inference`.
  Those are not part of the current SDK authoring proof, but they are not clean
  standalone SDK shape.
- `packages/omega-core/build.mjs` still emits declarations from the broad Omega
  tree with `--skipLibCheck` because the extraction has not yet been narrowed to
  package-local source only.

The next cleanup should copy the exact Omega subset used by
`@open-matrix/omega-core` into that package (or an explicit sibling package),
switch imports to package-local paths, remove the broad root `src/` dependency
from the build, and archive or extract oracle-specific code outside the SDK
repo surface.

## Verification Commands

Run from the repository root:

```bash
pnpm prove:cli
pnpm prove:fresh-samples
pnpm prove
```

Expected:

- `prove:cli` builds/tests the SDK CLI and runs the standalone greeter demo.
- `prove:fresh-samples` proves the fresh server and browser demos.
- `prove` builds, tests, type-checks, and packs all workspace packages.

Demo checks:

```bash
pnpm demo:standalone
```