112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# 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-uat
|
|
pnpm prove
|
|
```
|
|
|
|
Expected:
|
|
|
|
- `prove:cli-uat` reports `ok: true`.
|
|
- `legacyMonorepoPathReferences` is `false`.
|
|
- `managedHostProof` is skipped unless `MATRIX_SDK_RUNTIME_HOST_BIN` is supplied.
|
|
- `prove` builds, tests, type-checks, and packs all workspace packages.
|
|
|
|
Demo checks:
|
|
|
|
```bash
|
|
pnpm demo:standalone
|
|
pnpm demo:hivecast-login -- --check
|
|
```
|
|
|
|
`demo:hivecast-login -- --check` proves the demo wiring without requiring a
|
|
secret. A real HiveCast proof requires `MATRIX_API_KEY`, `MATRIX_CLOUD`, and
|
|
`MATRIX_SPACE` from the user.
|