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:

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:

pnpm demo:standalone