# 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.

## 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:

```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.