docs: tighten standalone SDK boundary
This commit is contained in:
Ubuntu
parent
64cc68f293
commit
852cb27c7d
45
README.md
45
README.md
@ -1,11 +1,11 @@
|
||||
# Matrix SDK
|
||||
|
||||
Matrix SDK is the package-author layer for building Matrix actors, browser
|
||||
surfaces, and broker-connected applications without depending on the HiveCast
|
||||
surfaces, and broker-connected applications without depending on a managed
|
||||
platform repo.
|
||||
|
||||
This repository contains the SDK packages that were split out of Matrix-3 and
|
||||
renamed to their publishable `@open-matrix/*` package names. The split is
|
||||
This repository contains the SDK packages renamed to their publishable
|
||||
`@open-matrix/*` package names. The workspace is
|
||||
proven as a standalone workspace: a fresh clone can install, build, test,
|
||||
type-check, pack every package, and compile an external consumer against the
|
||||
packed tarballs.
|
||||
@ -19,9 +19,15 @@ packed tarballs.
|
||||
- Browser host integrations for Matrix web surfaces
|
||||
- Package-author CLIs and project scaffolds
|
||||
|
||||
Matrix SDK is provider-neutral. It does not require HiveCast, Device Link, Host
|
||||
Link, Host Service, or a local HiveCast install. HiveCast is one managed provider
|
||||
that can issue broker credentials and host runtimes on top of the SDK.
|
||||
Matrix SDK is provider-neutral. It does not require a managed platform account,
|
||||
device-link ceremony, host-link implementation, managed host service, local
|
||||
platform install, Postgres database, or provider-owned broker authority. A
|
||||
provider overlay can issue broker credentials and host runtimes on top of the
|
||||
SDK, but the SDK itself must remain usable against any compatible broker.
|
||||
|
||||
See [STANDALONE-AUDIT.md](STANDALONE-AUDIT.md) for the current standalone
|
||||
boundary audit, including the remaining Omega/oracle extraction debt that is not
|
||||
part of the package-author SDK proof.
|
||||
|
||||
## Packages
|
||||
|
||||
@ -142,12 +148,13 @@ pnpm prove:cli-uat
|
||||
```
|
||||
|
||||
The command name uses `uat`, but its scope is only the SDK package-author CLI
|
||||
flow. It is not HiveCast product UAT, browser UAT, signup/login UAT, API-key UI
|
||||
UAT, or live platform deployment proof.
|
||||
flow. It is not managed-platform product UAT, browser signup/login UAT,
|
||||
API-key UI UAT, or live deployment proof.
|
||||
|
||||
The CLI is intended to let a package author initialize a folder, add actors,
|
||||
configure broker access, run actors, and invoke them without importing HiveCast
|
||||
product packages into the SDK layer.
|
||||
configure broker access, run actors, and invoke them without importing provider
|
||||
overlay packages into the SDK layer. Managed-host promotion is optional and is
|
||||
only exercised when `MATRIX_SDK_RUNTIME_HOST_BIN` is supplied.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
@ -170,7 +177,7 @@ scripts/
|
||||
|
||||
Done and proven:
|
||||
|
||||
- The SDK packages build independently from Matrix-3.
|
||||
- The SDK packages build independently from their original source monorepo.
|
||||
- Package identities use final `@open-matrix/*` names.
|
||||
- `@open-matrix/sdk` re-exports the public actor facade.
|
||||
- A fresh clone passes `pnpm install --frozen-lockfile && pnpm prove`.
|
||||
@ -180,17 +187,17 @@ Done and proven:
|
||||
Still planned:
|
||||
|
||||
- Provider-neutral credential resolution for `matrix configure` and SDK users.
|
||||
- `matrix login --provider hivecast` to write the same config shape as
|
||||
- Provider login commands that write the same config shape as
|
||||
`matrix configure`.
|
||||
- Direct broker mode with explicit broker URL/JWT/seed credentials.
|
||||
- HiveCast provider mode where HiveCast issues scoped broker credentials.
|
||||
- Managed-provider mode where an overlay issues scoped broker credentials.
|
||||
- Publishing the packages to npm after the provider-login contract is complete.
|
||||
|
||||
## Relationship To HiveCast
|
||||
## Relationship To Provider Overlays
|
||||
|
||||
Matrix SDK is the open, provider-neutral actor SDK.
|
||||
Matrix SDK is the provider-neutral actor SDK.
|
||||
|
||||
HiveCast is a managed overlay on top of Matrix SDK. HiveCast can provide account
|
||||
management, Spaces, API keys, broker credential issuance, runtime hosting,
|
||||
package distribution, and operator UI. SDK users should still be able to connect
|
||||
to another broker directly when they already manage their own broker credentials.
|
||||
Provider overlays can provide account management, namespaces, API keys, broker
|
||||
credential issuance, runtime hosting, package distribution, and operator UI.
|
||||
SDK users should still be able to connect to another broker directly when they
|
||||
already manage their own broker credentials.
|
||||
|
||||
89
STANDALONE-AUDIT.md
Normal file
89
STANDALONE-AUDIT.md
Normal file
@ -0,0 +1,89 @@
|
||||
# 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.
|
||||
@ -88,7 +88,7 @@ export function resolveHostedRuntimeRecoveryPlan(
|
||||
|
||||
if (href) {
|
||||
try {
|
||||
const currentUrl = new URL(href, 'https://hivecast.ai');
|
||||
const currentUrl = new URL(href, 'https://matrix.invalid');
|
||||
const hasExplicitTarget = currentUrl.searchParams.has('daemonRoot') || currentUrl.searchParams.has('daemonRealm');
|
||||
const relativeCurrentHref = serializeRelativeUrl(currentUrl);
|
||||
actions.push({
|
||||
@ -105,14 +105,14 @@ export function resolveHostedRuntimeRecoveryPlan(
|
||||
key: 'auto',
|
||||
label: 'Use Auto',
|
||||
href: serializeRelativeUrl(autoUrl),
|
||||
title: 'Clear the explicit runtime target and let HiveCast pick the current live target.',
|
||||
title: 'Clear the explicit runtime target and let the shell pick the current live target.',
|
||||
});
|
||||
}
|
||||
actions.push({
|
||||
key: 'shell',
|
||||
label: 'Open Shell',
|
||||
href: `/apps/web/#dashboard?redirect=${encodeURIComponent(relativeCurrentHref)}`,
|
||||
title: 'Open the HiveCast shell and return to this app after choosing a target.',
|
||||
title: 'Open the Matrix shell and return to this app after choosing a target.',
|
||||
});
|
||||
return {
|
||||
requestedRoot,
|
||||
@ -131,7 +131,7 @@ export function resolveHostedRuntimeRecoveryPlan(
|
||||
key: 'shell',
|
||||
label: 'Open Shell',
|
||||
href: '/apps/web/#dashboard',
|
||||
title: 'Open the HiveCast shell to inspect or switch attached leaves.',
|
||||
title: 'Open the Matrix shell to inspect or switch attached runtimes.',
|
||||
});
|
||||
|
||||
return {
|
||||
|
||||
@ -334,7 +334,7 @@ export interface BootstrapOptions {
|
||||
* @example Federated (NATS backbone for cross-root)
|
||||
* ```html
|
||||
* <matrix-dsl-host root="flowpad" backbone="ws://localhost:4223">
|
||||
* <ralph-supervisor-view tracks="matrix-3/ralph" autoview>
|
||||
* <ralph-supervisor-view tracks="demo/ralph" autoview>
|
||||
* </ralph-supervisor-view>
|
||||
* </matrix-dsl-host>
|
||||
* ```
|
||||
@ -2008,7 +2008,7 @@ export class MatrixDSLHost extends HTMLElement {
|
||||
|| this._isAuthoritativeBootstrapIdentitySource(selectedAuthorityRootSource);
|
||||
const authenticated = this.dataset.authenticated === 'true' || this._isAuthenticated === true;
|
||||
|
||||
// Host Service deployments discover authority runtime state through
|
||||
// Managed host deployments discover authority runtime state through
|
||||
// system.runtimes. Retired actor paths are not a product path.
|
||||
return authenticated && rootCameFromAuthoritativeBootstrap && selectedAuthorityRoot === root;
|
||||
}
|
||||
@ -2101,7 +2101,7 @@ export class MatrixDSLHost extends HTMLElement {
|
||||
lines.push(healthLine, bootstrapLine);
|
||||
return classify(
|
||||
'nats-jwt-bootstrap',
|
||||
'The HiveCast HTTP surface may still be up. This usually means session-to-bus auth or first-boot provisioning failed, not that the whole Host is down.',
|
||||
'The Matrix HTTP surface may still be up. This usually means session-to-bus auth or first-boot provisioning failed, not that the whole host is down.',
|
||||
);
|
||||
}
|
||||
|
||||
@ -2111,13 +2111,13 @@ export class MatrixDSLHost extends HTMLElement {
|
||||
lines.push(`HTTP /healthz: ${healthResp.status} ${healthResp.ok ? 'ok' : 'not ok'}`);
|
||||
return classify(
|
||||
'http-bootstrap',
|
||||
'The browser reached the HiveCast origin but a bootstrap HTTP request failed. Check /api/bootstrap and auth/session routes before assuming the Host is down.',
|
||||
'The browser reached the Matrix origin but a bootstrap HTTP request failed. Check /api/bootstrap and auth/session routes before assuming the host is down.',
|
||||
);
|
||||
} catch (error) {
|
||||
lines.push(`HTTP /healthz: unreachable (${error instanceof Error ? error.message : String(error)})`);
|
||||
return classify(
|
||||
'host-gateway-unreachable',
|
||||
'The browser cannot reach the HiveCast HTTP gateway at all. This is the closest thing to “Host is down” in the bootstrap path.',
|
||||
'The browser cannot reach the Matrix HTTP gateway at all. This is the closest thing to “host is down” in the bootstrap path.',
|
||||
);
|
||||
}
|
||||
}
|
||||
@ -3230,7 +3230,7 @@ export class MatrixDSLHost extends HTMLElement {
|
||||
lastError = err instanceof Error ? err.message : String(err);
|
||||
// eslint-disable-next-line no-console -- browser bootstrap, not an actor
|
||||
console.warn(
|
||||
`[MatrixDSLHost] Host Service runtime discovery failed at "${discoveryTarget.target}": ${lastError}.`,
|
||||
`[MatrixDSLHost] Managed host runtime discovery failed at "${discoveryTarget.target}": ${lastError}.`,
|
||||
);
|
||||
}
|
||||
}
|
||||
@ -3445,13 +3445,13 @@ export class MatrixDSLHost extends HTMLElement {
|
||||
* (`system.runtimes`). Browser tabs claim child actors in `system.registry`
|
||||
* via `registry.claim`, but `system.runtimes.runtimes.list` is fed by
|
||||
* runtime presence — without this call, browser tabs are invisible to
|
||||
* Director Topology, Host Ops Workloads, and any other consumer of the
|
||||
* runtime inventory UIs, workload views, and any other consumer of the
|
||||
* runtime directory.
|
||||
*
|
||||
* We route through the explicit `runtimes.presence.update` op via
|
||||
* `RequestReply.execute("${controlPlaneRoot}/system.runtimes", ...)`, NOT through
|
||||
* `publishRuntimePresence(ctx, record, event)`. The pub/sub path uses bare
|
||||
* `$runtime.*` topics on the local transport — in federated HiveCast mode
|
||||
* `$runtime.*` topics on the local transport — in federated broker mode
|
||||
* the tab realm is a synthetic per-tab root (`s-b-root-*`) so the publish
|
||||
* lands on a NATS subject prefix the `RuntimeManagerActor` at the
|
||||
* authority root never subscribes to. Routed RequestReply.execute uses
|
||||
@ -3683,7 +3683,7 @@ export class MatrixDSLHost extends HTMLElement {
|
||||
// Explicit authority URLs already declare the target identity in the
|
||||
// path. Do not probe platform-local actors such as system.auth or
|
||||
// system.directory here; that turns a shareable user URL into a hidden
|
||||
// HiveCast-local lookup and can wait on unrelated platform timeouts.
|
||||
// provider-local lookup and can wait on unrelated platform timeouts.
|
||||
console.info('[MatrixDSLHost] Phase B platform probe skipped for explicit authority URL - retaining explicit authority root');
|
||||
finishPhaseBProfile({
|
||||
result: 'skipped-explicit-authority',
|
||||
@ -4091,7 +4091,7 @@ const RESERVED_ROUTE_KEYS = new Set([
|
||||
'well-known',
|
||||
'favicon.ico',
|
||||
'manifest.json',
|
||||
'hivecast',
|
||||
'provider',
|
||||
'open-matrix',
|
||||
'me',
|
||||
]);
|
||||
|
||||
@ -9,8 +9,8 @@ describe('htmlReferencesBundle', () => {
|
||||
assert.equal(
|
||||
htmlReferencesBundle(
|
||||
html,
|
||||
'https://dev.hivecast.ai/apps/director/assets/index-new.js',
|
||||
'https://dev.hivecast.ai/apps/director/',
|
||||
'https://example.invalid/apps/director/assets/index-new.js',
|
||||
'https://example.invalid/apps/director/',
|
||||
),
|
||||
true,
|
||||
);
|
||||
@ -21,8 +21,8 @@ describe('htmlReferencesBundle', () => {
|
||||
assert.equal(
|
||||
htmlReferencesBundle(
|
||||
html,
|
||||
'https://local.hivecast.ai/apps/web/index.ts',
|
||||
'https://local.hivecast.ai/apps/web/',
|
||||
'https://local.example.invalid/apps/web/index.ts',
|
||||
'https://local.example.invalid/apps/web/',
|
||||
),
|
||||
true,
|
||||
);
|
||||
@ -33,8 +33,8 @@ describe('htmlReferencesBundle', () => {
|
||||
assert.equal(
|
||||
htmlReferencesBundle(
|
||||
html,
|
||||
'https://dev.hivecast.ai/apps/director/assets/index-old.js',
|
||||
'https://dev.hivecast.ai/apps/director/',
|
||||
'https://example.invalid/apps/director/assets/index-old.js',
|
||||
'https://example.invalid/apps/director/',
|
||||
),
|
||||
false,
|
||||
);
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
# Boundary Identifiers — In-Package Reference
|
||||
|
||||
If you're editing files in this package, you must know which identifier
|
||||
you're touching. Full spec:
|
||||
`WORKSTREAMS/platform-control-plane-freeze/FOUR-ROOTS-DISENTANGLE.md`
|
||||
(working title preserved for grep continuity).
|
||||
you're touching. This file is the in-package boundary contract for the SDK
|
||||
browser host. Provider overlays may maintain their own deployment-specific
|
||||
mapping docs, but boundary names exported by this package stay provider-neutral.
|
||||
|
||||
## The Four Boundary Identifiers
|
||||
|
||||
@ -41,10 +41,9 @@ discipline is at the seams.
|
||||
in new code. The `root` attribute is ambiguous — it has meant all four
|
||||
identifiers at different times in git history. Pick the specific one.
|
||||
|
||||
3. **No fallbacks.** Per CLAUDE.md "no fallbacks or legacy crutches,"
|
||||
if `appName` is missing from a bootstrap that needs it, **throw**.
|
||||
Do not silently degrade to using `subjectScope` in the `appName` slot —
|
||||
that's the wire-crossing bug this workstream exists to fix.
|
||||
3. **No implicit substitution.** If `appName` is missing from a bootstrap that
|
||||
needs it, **throw**. Do not silently degrade to using `subjectScope` in the
|
||||
`appName` slot; that creates wire-crossing bugs.
|
||||
|
||||
4. **Forbidden boundary names** (do not introduce in new code at boundaries):
|
||||
- `root` — meant all four at different times
|
||||
|
||||
@ -10,13 +10,11 @@ It may depend on:
|
||||
|
||||
It must not depend on:
|
||||
|
||||
- `@matrix/mx-cli`
|
||||
- `@open-matrix/host-service`
|
||||
- `@open-matrix/host-control`
|
||||
- `@open-matrix/system-*`
|
||||
- `@open-matrix/system-auth`
|
||||
- `@open-matrix/system-gateway-http`
|
||||
- `@open-matrix/nats-auth`
|
||||
- `hivecast`
|
||||
- legacy product CLI packages
|
||||
- provider overlay CLIs
|
||||
- managed host or host-control packages
|
||||
- platform system actor packages
|
||||
- gateway/auth packages
|
||||
- broker-authority/signing packages
|
||||
|
||||
User packages must depend on SDK libraries, not on this CLI package.
|
||||
|
||||
@ -3,8 +3,8 @@
|
||||
Package-author CLI for the Matrix SDK layer.
|
||||
|
||||
This package owns the SDK/package-author `matrix` binary. It does not depend on
|
||||
Matrix-3 product packages, Host Service, Host Control, system actors, HiveCast,
|
||||
Device Link, or NATS authority packages.
|
||||
provider overlay packages, managed host packages, platform system actors,
|
||||
device-link implementations, or broker-authority/signing packages.
|
||||
|
||||
Initial command surface:
|
||||
|
||||
@ -17,7 +17,7 @@ matrix run <entry> --mount <mount>
|
||||
matrix invoke <mount> <op> [json]
|
||||
```
|
||||
|
||||
`matrix run` starts a standalone actor runner in the current folder. `matrix
|
||||
invoke` sends a Matrix request envelope to that runner through its local control
|
||||
port. Managed Runtime Host promotion belongs to the later Matrix-3/Runtime Host
|
||||
repoint phase.
|
||||
`matrix run` starts a standalone actor runner in the current folder.
|
||||
`matrix invoke` sends a Matrix request envelope to that runner through its local
|
||||
control port. Managed host promotion belongs to provider overlays that consume
|
||||
the SDK; it is not an SDK-layer requirement.
|
||||
|
||||
@ -56,7 +56,7 @@ test('init, add actor, and configure write package-local SDK state', async () =>
|
||||
assert.equal(credentialMode, 0o600);
|
||||
});
|
||||
|
||||
test('up delegates a Host-runnable package to an explicit Runtime Host command', async () => {
|
||||
test('up delegates a host-runnable package to an explicit managed host command', async () => {
|
||||
const root = await mkdtemp(join(tmpdir(), 'matrix-sdk-cli-up-test.'));
|
||||
const fakeRuntimeHost = join(root, 'fake-runtime-host.mjs');
|
||||
const calledPath = join(root, 'runtime-host-called.json');
|
||||
|
||||
@ -663,7 +663,7 @@ async function upCommand(rawArgs: string[]): Promise<void> {
|
||||
?? optionalString(config.runtimeHostBin)
|
||||
?? process.env.MATRIX_RUNTIME_HOST_BIN;
|
||||
if (!runtimeHostBin) {
|
||||
throw new Error('MATRIX_RUNTIME_HOST_BIN_REQUIRED: matrix up requires --runtime-host-bin or MATRIX_RUNTIME_HOST_BIN pointing to the Runtime Host matrix command');
|
||||
throw new Error('MATRIX_RUNTIME_HOST_BIN_REQUIRED: matrix up requires --runtime-host-bin or MATRIX_RUNTIME_HOST_BIN pointing to a managed host matrix command');
|
||||
}
|
||||
const routing = stringOption(parsed.options, 'runtime-host-routing')
|
||||
?? optionalString(config.runtimeHostRouting)
|
||||
@ -696,7 +696,7 @@ async function upCommand(rawArgs: string[]): Promise<void> {
|
||||
});
|
||||
if (result.error) throw result.error;
|
||||
if (result.status !== 0) {
|
||||
throw new Error(`matrix up Runtime Host command failed with exit ${result.status ?? 'unknown'}`);
|
||||
throw new Error(`matrix up managed host command failed with exit ${result.status ?? 'unknown'}`);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -59,7 +59,7 @@ export interface RuntimePresenceRecordV1 {
|
||||
/** Optional: authority root for deployment/ownership plane. */
|
||||
authorityRoot?: string;
|
||||
|
||||
/** Optional: platform root for HiveCast/hosting plane. */
|
||||
/** Optional: provider overlay root for hosting plane metadata. */
|
||||
platformRoot?: string;
|
||||
|
||||
/** Optional: human-readable application name. */
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
# @matrix/core
|
||||
# @open-matrix/core
|
||||
|
||||
Matrix runtime SDK — actors, Web Components, transports, serialization, and LISP-on-Protocol.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @matrix/core
|
||||
npm install @open-matrix/core
|
||||
```
|
||||
|
||||
## Usage
|
||||
@ -13,7 +13,7 @@ npm install @matrix/core
|
||||
### Headless Actor (daemon-side)
|
||||
|
||||
```typescript
|
||||
import { MatrixActor } from '@matrix/core';
|
||||
import { MatrixActor } from '@open-matrix/core';
|
||||
|
||||
class PingActor extends MatrixActor {
|
||||
static accepts = {
|
||||
@ -32,7 +32,7 @@ class PingActor extends MatrixActor {
|
||||
### Browser Web Component
|
||||
|
||||
```typescript
|
||||
import { MatrixActorHtmlElement } from '@matrix/core';
|
||||
import { MatrixActorHtmlElement } from '@open-matrix/core';
|
||||
|
||||
class StatusPanel extends MatrixActorHtmlElement {
|
||||
static accepts = { showStatus: { text: 'string' } };
|
||||
@ -50,11 +50,11 @@ customElements.define('status-panel', StatusPanel);
|
||||
### Programmatic Runtime
|
||||
|
||||
```typescript
|
||||
import { MatrixRuntime, InMemoryBroker } from '@matrix/core';
|
||||
import { InMemoryBroker, InMemoryTransport, MatrixRuntime } from '@open-matrix/core';
|
||||
|
||||
const broker = new InMemoryBroker();
|
||||
const runtime = new MatrixRuntime({ broker });
|
||||
await runtime.start();
|
||||
const transport = new InMemoryTransport(broker, { name: 'demo' });
|
||||
const runtime = new MatrixRuntime({ transport });
|
||||
```
|
||||
|
||||
## What's Included
|
||||
|
||||
@ -7,7 +7,7 @@
|
||||
"license": "MIT",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/nicholasgalante/Matrix-3.git",
|
||||
"url": "https://github.com/matrix-sdk/matrix-sdk.git",
|
||||
"directory": "packages/core"
|
||||
},
|
||||
"keywords": [
|
||||
|
||||
@ -61,7 +61,7 @@ export const UserDevicesContract: ServiceContract = {
|
||||
},
|
||||
},
|
||||
'devices.revoke': {
|
||||
description: 'Revoke/unlink one account-level Device Link.',
|
||||
description: 'Revoke/unlink one account-level device credential.',
|
||||
payload: {
|
||||
authorityRoot: { type: 'string', required: false },
|
||||
deviceId: { type: 'string', required: true },
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "@matrix/theme",
|
||||
"name": "@open-matrix/theme",
|
||||
"version": "0.1.0",
|
||||
"description": "Design token management and theme switching for Matrix components",
|
||||
"components": [
|
||||
|
||||
@ -354,7 +354,7 @@ export type {
|
||||
// Browser Runtime
|
||||
export { BrowserDomStrategy } from './runtime/BrowserDomStrategy';
|
||||
// MatrixDSLHost and BootstrapOptions moved to @open-matrix/browser-host
|
||||
// during Phase 1 of core-decontamination (see WORKSTREAMS/core-decontamination).
|
||||
// during the core package split.
|
||||
// Import from '@open-matrix/browser-host/host' instead.
|
||||
|
||||
// Remoting — ComponentProxy
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
// Input: (define (square x) (* x x))
|
||||
// Output: ["define", ["square", "x"], ["*", "x", "x"]]
|
||||
//
|
||||
// This enables running actual Scheme/LISP code on Matrix-3
|
||||
// This enables running actual Scheme/LISP code on Matrix.
|
||||
|
||||
import type { SExpr } from '../SExpr';
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
// src/lisp/index.ts
|
||||
// LISP-on-Protocol - Public API
|
||||
//
|
||||
// This module provides the core LISP evaluation engine for Matrix-3.
|
||||
// This module provides the core LISP evaluation engine for Matrix.
|
||||
// It enables:
|
||||
// - S-expression parsing (traditional LISP syntax to JSON wire format)
|
||||
// - Pure LISP evaluation (standalone or Matrix-integrated)
|
||||
|
||||
@ -76,7 +76,7 @@ interface ComponentInfo {
|
||||
}
|
||||
|
||||
/**
|
||||
* MatrixRuntime — the ONE unified runtime for Matrix-3.
|
||||
* MatrixRuntime — the unified runtime for Matrix actors.
|
||||
*
|
||||
* Supports both headless (no DOM) and browser (with IDomStrategy) modes.
|
||||
*
|
||||
|
||||
@ -13,6 +13,6 @@ It may export from the Node-safe root:
|
||||
Browser app build utilities remain in `@open-matrix/browser-kit` and are
|
||||
imported directly from that package.
|
||||
|
||||
It must not depend on Matrix-3 product packages, Host Service, Host Control,
|
||||
system actors, HiveCast installer state, Device Link state, Postgres, or NATS
|
||||
authority/signing packages.
|
||||
It must not depend on provider overlay packages, managed host packages,
|
||||
platform system actors, installer state, device-link state, Postgres, or
|
||||
broker-authority/signing packages.
|
||||
|
||||
@ -10,8 +10,6 @@ import { fileURLToPath } from 'node:url';
|
||||
const scriptDir = path.dirname(fileURLToPath(import.meta.url));
|
||||
const sourceWorkspaceDir = path.resolve(scriptDir, '..');
|
||||
let workspaceDir = sourceWorkspaceDir;
|
||||
const repoProjectsDir = path.resolve(sourceWorkspaceDir, '..');
|
||||
const defaultRuntimeHostBin = path.join(repoProjectsDir, 'matrix-3', 'packages', 'hivecast', 'bin', 'matrix.mjs');
|
||||
|
||||
const packages = [
|
||||
'@open-matrix/contracts',
|
||||
@ -236,8 +234,10 @@ async function main() {
|
||||
let keep = process.env.MATRIX_SDK_KEEP_CLI_UAT === '1';
|
||||
let runner;
|
||||
let packageRunner;
|
||||
const runtimeHostBin = process.env.MATRIX_SDK_RUNTIME_HOST_BIN || defaultRuntimeHostBin;
|
||||
const runtimeHostBin = envString('MATRIX_SDK_RUNTIME_HOST_BIN');
|
||||
const managedHostProofEnabled = Boolean(runtimeHostBin);
|
||||
let runtimeHostStarted = false;
|
||||
let managedHostProof = null;
|
||||
|
||||
try {
|
||||
await mkdir(tarballDir, { recursive: true });
|
||||
@ -296,19 +296,24 @@ async function main() {
|
||||
if (liveKeyConfig) {
|
||||
liveKeyValidation = await validateLiveKeyConfig(liveKeyConfig);
|
||||
}
|
||||
const configureKey = liveKeyConfig?.key ?? 'hc_uat_key_redacted';
|
||||
const configureCloud = liveKeyConfig?.cloud ?? 'https://dev.hivecast.ai';
|
||||
const configureKey = liveKeyConfig?.key ?? 'matrix_sdk_test_key_redacted';
|
||||
const configureCloud = liveKeyConfig?.cloud ?? 'https://example.invalid';
|
||||
const configureSpace = liveKeyConfig?.space ?? 'fresh-sdk-space';
|
||||
|
||||
run('pnpm', [
|
||||
const configureArgs = [
|
||||
'exec', 'matrix', 'configure',
|
||||
'--dir', authorDir,
|
||||
'--key', configureKey,
|
||||
'--cloud', configureCloud,
|
||||
'--space', configureSpace,
|
||||
'--runtime-host-bin', runtimeHostBin,
|
||||
'--runtime-host-routing', 'workspace-source',
|
||||
], { cwd: toolingDir });
|
||||
];
|
||||
if (runtimeHostBin) {
|
||||
configureArgs.push(
|
||||
'--runtime-host-bin', runtimeHostBin,
|
||||
'--runtime-host-routing', 'workspace-source',
|
||||
);
|
||||
}
|
||||
run('pnpm', configureArgs, { cwd: toolingDir });
|
||||
run('pnpm', ['install', '--ignore-scripts'], { cwd: authorDir });
|
||||
run('pnpm', ['run', 'build'], { cwd: authorDir });
|
||||
|
||||
@ -365,39 +370,55 @@ async function main() {
|
||||
await stopChild(runner);
|
||||
runner = undefined;
|
||||
|
||||
if (!existsSync(runtimeHostBin)) {
|
||||
throw new Error(`Runtime Host matrix command not found for managed proof: ${runtimeHostBin}`);
|
||||
}
|
||||
const up = run('pnpm', [
|
||||
'exec', 'matrix', 'up',
|
||||
'--dir', authorDir,
|
||||
'--http-port', 'auto',
|
||||
'--host-nats-port', 'auto',
|
||||
'--host-nats-ws-port', 'auto',
|
||||
'--runtime-id', 'SDK-UAT-GREETER',
|
||||
'--json',
|
||||
'--timeout', '45000',
|
||||
], { cwd: toolingDir, stdio: 'pipe' });
|
||||
runtimeHostStarted = true;
|
||||
const upResult = parseJsonFromOutput(up.stdout, 'matrix up');
|
||||
if (upResult.ok !== true || upResult.mode !== 'natural-launch-up') {
|
||||
throw new Error(`Unexpected matrix up output: ${up.stdout}`);
|
||||
}
|
||||
const upService = upResult.services?.find?.((service) => service.runtimeId === 'SDK-UAT-GREETER');
|
||||
if (!upService || upService.ok !== true) {
|
||||
throw new Error(`matrix up did not start SDK-UAT-GREETER: ${up.stdout}`);
|
||||
}
|
||||
const managedInvokeOutput = runRuntimeHost(runtimeHostBin, [
|
||||
'invoke',
|
||||
'demo.greeter',
|
||||
'getStatus',
|
||||
'{}',
|
||||
'--json',
|
||||
'--timeout', '10000',
|
||||
], { cwd: authorDir, stdio: 'pipe' });
|
||||
const managedInvoke = parseJsonFromOutput(managedInvokeOutput.stdout, 'managed matrix invoke');
|
||||
if (managedInvoke.ok !== true || managedInvoke.result?.mount !== 'demo.greeter') {
|
||||
throw new Error(`Unexpected managed matrix invoke output: ${managedInvokeOutput.stdout}`);
|
||||
if (managedHostProofEnabled) {
|
||||
if (!runtimeHostBin || !existsSync(runtimeHostBin)) {
|
||||
throw new Error(`Managed host matrix command not found for optional managed proof: ${runtimeHostBin}`);
|
||||
}
|
||||
const up = run('pnpm', [
|
||||
'exec', 'matrix', 'up',
|
||||
'--dir', authorDir,
|
||||
'--http-port', 'auto',
|
||||
'--host-nats-port', 'auto',
|
||||
'--host-nats-ws-port', 'auto',
|
||||
'--runtime-id', 'SDK-UAT-GREETER',
|
||||
'--json',
|
||||
'--timeout', '45000',
|
||||
], { cwd: toolingDir, stdio: 'pipe' });
|
||||
runtimeHostStarted = true;
|
||||
const upResult = parseJsonFromOutput(up.stdout, 'matrix up');
|
||||
if (upResult.ok !== true || upResult.mode !== 'natural-launch-up') {
|
||||
throw new Error(`Unexpected matrix up output: ${up.stdout}`);
|
||||
}
|
||||
const upService = upResult.services?.find?.((service) => service.runtimeId === 'SDK-UAT-GREETER');
|
||||
if (!upService || upService.ok !== true) {
|
||||
throw new Error(`matrix up did not start SDK-UAT-GREETER: ${up.stdout}`);
|
||||
}
|
||||
const managedInvokeOutput = runRuntimeHost(runtimeHostBin, [
|
||||
'invoke',
|
||||
'demo.greeter',
|
||||
'getStatus',
|
||||
'{}',
|
||||
'--json',
|
||||
'--timeout', '10000',
|
||||
], { cwd: authorDir, stdio: 'pipe' });
|
||||
const managedInvoke = parseJsonFromOutput(managedInvokeOutput.stdout, 'managed matrix invoke');
|
||||
if (managedInvoke.ok !== true || managedInvoke.result?.mount !== 'demo.greeter') {
|
||||
throw new Error(`Unexpected managed matrix invoke output: ${managedInvokeOutput.stdout}`);
|
||||
}
|
||||
managedHostProof = {
|
||||
runtimeHostBin,
|
||||
up: {
|
||||
ok: upResult.ok,
|
||||
mode: upResult.mode,
|
||||
runtimeId: upService.runtimeId,
|
||||
packageDir: upService.packageDir,
|
||||
},
|
||||
invoke: {
|
||||
ok: managedInvoke.ok,
|
||||
target: managedInvoke.target,
|
||||
result: managedInvoke.result,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
run('pnpm', ['pack', '--pack-destination', packageTarballDir], { cwd: authorDir, stdio: 'pipe' });
|
||||
@ -461,7 +482,7 @@ async function main() {
|
||||
authorDir,
|
||||
cliInstalledSeparately: true,
|
||||
authorPackageDependsOnCli: false,
|
||||
matrix3PathReferences: false,
|
||||
legacyMonorepoPathReferences: false,
|
||||
actorImport: '@open-matrix/core',
|
||||
configuredKeyStored: existsSync(path.join(authorDir, '.matrix', 'credentials', 'matrix-api-key.json')),
|
||||
validKeyConfigSupplied: Boolean(liveKeyConfig),
|
||||
@ -471,19 +492,9 @@ async function main() {
|
||||
ok: invoked.ok,
|
||||
result: invoked.result,
|
||||
},
|
||||
managedRuntimeHost: {
|
||||
runtimeHostBin,
|
||||
up: {
|
||||
ok: upResult.ok,
|
||||
mode: upResult.mode,
|
||||
runtimeId: upService.runtimeId,
|
||||
packageDir: upService.packageDir,
|
||||
},
|
||||
invoke: {
|
||||
ok: managedInvoke.ok,
|
||||
target: managedInvoke.target,
|
||||
result: managedInvoke.result,
|
||||
},
|
||||
managedHostProof: managedHostProof ?? {
|
||||
skipped: true,
|
||||
reason: 'MATRIX_SDK_RUNTIME_HOST_BIN not supplied',
|
||||
},
|
||||
packageManagerInstall: {
|
||||
tarball: path.basename(authorPackageTarball),
|
||||
@ -503,11 +514,11 @@ async function main() {
|
||||
} finally {
|
||||
if (runner) await stopChild(runner);
|
||||
if (packageRunner) await stopChild(packageRunner);
|
||||
if (runtimeHostStarted) {
|
||||
if (runtimeHostStarted && runtimeHostBin) {
|
||||
try {
|
||||
runRuntimeHost(runtimeHostBin, ['stop', '--timeout', '15000'], { cwd: authorDir, stdio: 'pipe' });
|
||||
} catch (error) {
|
||||
console.error(`[prove-sdk-cli-uat] failed to stop Runtime Host: ${error instanceof Error ? error.message : String(error)}`);
|
||||
console.error(`[prove-sdk-cli-uat] failed to stop managed host: ${error instanceof Error ? error.message : String(error)}`);
|
||||
}
|
||||
}
|
||||
if (!keep) {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user