Spaces

A Space is the durable unit of public identity on Matrix. Every signed-in user gets at least one Space; every public URL on hivecast.ai resolves to one. Spaces are how the platform routes traffic, scopes data, presents identity in URLs, and bills usage. They are also the federation unit: typed service contracts cross Space boundaries, not arbitrary network access.

The user-facing term is Space path. Internal-only terms (spaceId, authorityRoot, publicNamespace) appear only when these docs are explaining the data model — they never appear in CLI prose, marketing copy, or browser URLs.

The four canonical fields

Per CLAUDE.md (Public Space identity, canonical) and WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md, a Space has four distinct fields. Do not conflate them.

Concept	Field	Example	Scope
User-facing public path	spacePath	alt.stories.ghost-stories.funny	dot-delimited public Space route handle; goes in URLs as /<spacePath>/<appName>/
Typed namespace claim	publicNamespace	space.alt.stories.ghost-stories.funny	derived as space.<spacePath>; never appears in user URLs
Durable Space identity	spaceId	spc_7f3a9b2c	product-stable Space id
Internal authority root	authorityRoot	SPACE.SPC_7F3A9B2C	bus/security/runtime root; for new Spaces derived from spaceId, never from public path text

A user editing the public name of their Space changes spacePath and publicNamespace. Their spaceId and authorityRoot are stable across renames — they do not change. This is the rename-safety guarantee.

v1 compatibility: routeKey

The pre-v2 contract used routeKey as the user-facing path field. Its values were single-segment slugs like richard-santomauro-gmail. New code, specs, and UI copy say "Space path" and use the dot-delimited form. Existing stored routeKey fields remain as compatibility aliases during the v1 transition. The CLI flag --route-key is preserved as a v1 alias of --space-path.

When you see routeKey in system-auth ops (auth.namespace.check, auth.hostLink.create, etc.), read it as spacePath for v2 callers. The wire fields are dual-emitted: an op response includes both routeKey and publicNamespace.

Source: projects/matrix-3/packages/system-auth/src/index.ts:582-608 (onAuthNamespaceClaim) emits both fields.

Where a Space lives in code

system-auth's HostSpaceStore and HostNamespaceStore (in host-auth.ts) own Space records and the public-namespace claim index. The IHostSpaceRecord interface (host-auth.ts:61-69):

export interface IHostSpaceRecord {
  readonly id: string;            // spaceId
  readonly authorityRoot: string; // SPACE.SPC_xxx
  readonly ownerPrincipalId?: string;
  readonly ownerType?: HostSpaceOwnerType; // 'principal' | 'organization' | 'system' | 'service'
  readonly status: HostSpaceStatus;        // 'active' | 'suspended'
  readonly createdAt: string;
  updatedAt: string;
}

IHostPublicNamespaceClaim (host-auth.ts:71-85) ties a publicNamespace (and optional routeKey alias) to a spaceId + authorityRoot:

export interface IHostPublicNamespaceClaim {
  readonly routeKey?: string;
  readonly publicNamespace: string;
  readonly canonicalRouteKey?: string;
  readonly canonicalNamespace?: string;
  readonly spaceId: string;
  readonly authorityRoot: string;
  readonly canonical: boolean;
  readonly claimType: 'space' | 'domain' | 'system';
  readonly verificationLevel: 'self' | 'org-admin' | 'dns' | 'platform';
  readonly status: 'active' | 'reserved' | 'suspended' | 'released';
  ...
}

verificationLevel: 'self' is the only level implemented today: the user claimed the path themselves on first login. org-admin, dns, and platform are target state for organizational and verified Spaces.

How a URL maps to a Space

A URL like https://hivecast.ai/alt.stories.ghost-stories.funny/director/ is parsed as:

1. system-gateway-http extracts spacePath = "alt.stories.ghost-stories.funny" and appName = "director".
2. Calls system.auth auth.namespace.resolve with routeKey: "alt.stories.ghost-stories.funny" (v1 wire field).
3. Receives back { spaceId, authorityRoot, claim, space }.
4. Looks up the runtime hosting director for that authorityRoot via system.runtimes / system.registry.
5. Routes the HTTP request to that runtime's asset endpoint actor.

If the URL is https://hivecast.ai/apps/director/, no spacePath is provided. The gateway treats it as a current-host route and serves Director from whatever runtime is hosting it locally. Browsers belonging to a signed-in user are redirected to their Space path — see P1.22 for the silent-substitution rules.

Creating a Space

auth.space.create (system-auth/src/index.ts:655-682) creates a Space owned by a principal:

matrix invoke system.auth auth.space.create \
  '{"principalId":"p_xxx","authorityRoot":"SPACE.SPC_NEW"}'

If authorityRoot is omitted, the implementation uses the principal's first registered addressRoots[0].root or workspaceRealm or the configured platform-wide authorityRoot. The current code does NOT yet derive authorityRoot from a freshly-generated spaceId for new Spaces — that work is target state per P1.23f. Existing Spaces use whatever authorityRoot they were created with (typically derived from the user's email domain at first OIDC login).

Default Space per principal

A principal has at most one default Space — the one used when no explicit spaceId is supplied to operations like auth.hostLink.create or auth.device.approve. HostSpaceStore.getDefaultForPrincipal reads the mapping; HostSpaceStore.setDefaultForPrincipal updates it. The first Space created for a principal automatically becomes their default.

Target state

• Domain-verified Spaces. A Space whose claimType is domain would carry a DNS TXT proof linking the public path to a controlled domain. The data model exists; verification is not implemented.
• Multi-Space accounts. A principal can have multiple Spaces today (the store supports it), but UI for switching the active Space in the platform shell is partial.
• Authority root from spaceId for new Spaces. New Spaces should derive authorityRoot = SPACE.<UPPER(spaceId)> to make the bus root rename-safe. Today new Spaces inherit the principal's authority root.
• Organization Spaces. ownerType: 'organization' is in the schema; org membership and admin tooling are target state.

See also

• Accounts and Spaces / Spaces — operator workflow, claim/check/resolve.
• Accounts and Spaces / Namespace claims — claim type and verification levels.
• Accounts and Spaces / Ownership — owner types and transfer.
• Reference: Actor surfaces — full op list for system.auth.

Source: projects/matrix-3/packages/system-auth/src/host-auth.ts:55-90 for the schema. WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md for the v2 contract decisions. CLAUDE.md "Public Space identity (canonical)" table is the SSOT for terminology.