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 installs the SDK CLI as a package-manager dependency.
• matrix init creates a fresh author package.
• matrix add actor creates an actor importing @open-matrix/core.
• matrix configure writes package-local .matrix credentials/config.
• matrix run starts the actor directly.
• matrix invoke calls the actor through the SDK CLI.
• The generated package can be packed, installed into a separate consumer, run, and invoked again.

The proof script also checks that generated author-package files do not contain legacy monorepo paths or upper-layer package dependencies.

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

• pnpm demo:standalone runs examples/standalone-greeter without provider credentials.
• pnpm demo:hivecast-login validates a user-supplied HiveCast API key and writes package-local SDK config/credentials in a temporary demo home.

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 contracts describe standalone SDK boundaries and optional managed-host integration without naming product-only packages as part of the SDK.
• The SDK CLI UAT proof no longer defaults to a HiveCast binary or dev.hivecast.ai; managed-host proof requires explicit MATRIX_SDK_RUNTIME_HOST_BIN.
• 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-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:

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.