Spaces

A Space is a shared public address that one or more Devices can publish actors into. Where principal authority is "this is my account," Space authority is "this is our shared address."

Status: Spaces architecture is in flux. P1.23f Gate 2 has landed (the new authority-root decision); Gates 3-4 (full multi-Device Space participation, public-Space discovery, Space-scoped revocation) are target state. This page documents what works today plus where things are going. See WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md.

Four names every Space has

From the repo-root CLAUDE.md:

Concept	Field	Example	Where it appears
User-facing public path	spacePath	alt.stories.ghost-stories.funny	URLs (/<spacePath>/<appName>/), CLI flags, copy
Typed namespace claim	publicNamespace	space.alt.stories.ghost-stories.funny	bus subjects (derived as space.<spacePath>); never in user URLs
Durable Space identity	spaceId	spc_7f3a9b2c	product-stable id; the only thing that survives spacePath rename
Internal authority root	authorityRoot	SPACE.SPC_7F3A9B2C	bus/security/runtime root; derived from spaceId, NOT from public path text

routeKey is the v1 compatibility alias for spacePath. The CLI flag --route-key is preserved through v1; new code says "Space path."

Why four names

The split is forced by competing requirements:

• Users want a memorable, dot-delimited path: alt.stories.ghost-stories.funny.
• The bus needs an immutable subject prefix: rename a Space and the bus subjects can't move.
• Security needs a stable authority root that doesn't change when the public name does.
• Operators need a durable id for cross-system references.

Hence: spacePath is mutable user-facing. spaceId is durable. authorityRoot is derived from spaceId so it's stable across renames. publicNamespace exists for typed bus claims.

Pairing into a Space

When you pair a Device, the --route-key (a.k.a. --space-path) flag pre-claims the public path:

hivecast login --device \
  --cloud https://hivecast.ai \
  --route-key alt.stories.ghost-stories.funny

The cloud:

1. Validates the path is unclaimed (or that you own the existing claim).
2. Allocates / reuses the spaceId.
3. Derives or fetches the authorityRoot.
4. Returns the four-tuple in the link record.

After pairing, the Device knows: this is the principal, this is the Space, this is the authority root for new operations, this is the public namespace for typed claims.

Authority-root derivation (current, post-P1.23f Gate 2)

Per WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md:

• New Spaces — authorityRoot is derived from spaceId. Format: SPACE.<UPPERCASE-SPACEID>. Example: SPACE.SPC_7F3A9B2C.
• Legacy principal accounts — authorityRoot may still be email-derived (e.g. richard-santomauro@nimbletec.com → COM.NIMBLETEC.RICHARD-SANTOMAURO). These are preserved for backward compatibility.
• The wire root — the local Host's bus prefix (host.json transport.root) is independent of any Space. It's per-Host and doesn't change when Spaces come and go.

The key invariant: authorityRoot is never derived from spacePath. Renaming a Space does not change its authority. This was a real bug at one point and is now P1.23f-prevented.

What works today

• Pre-claiming a Space path during pairing
• Carrying spacePath, spaceId, authorityRoot, publicNamespace through the link record
• The cloud's Devices page shows the Space metadata for paired Devices
• Public Space-path validation (you can't claim someone else's)

Target state (P1.23f Gates 3-4)

• Multiple Devices participating in the same Space (today: one Device per pairing, one principal owns the Space)
• Public Space-path discovery in the cloud UI ("browse Spaces")
• Space-scoped revocation (revoke one Device from a Space without affecting that Device's other links)
• system.devices projections per Space (today: per principal)
• Space-level audit / billing

These are explicitly not in code today. The data model supports them; the UX surfaces don't.

Spaces vs principals

A principal is a single authenticated user. A Space is a shared address that may have multiple principals contributing.

Today, the simple shape is: one principal owns one Space, that principal's Devices publish into it. Multi-principal Spaces are tracked in P1.23f's later gates.

Don't confuse:

• A principal's authority root (COM.NIMBLETEC.RICHARD-SANTOMAURO for legacy, PRINCIPAL.<id> for new) — for personal actors that don't need to be public-shared.
• A Space's authority root (SPACE.SPC_7F3A9B2C) — for actors that should be addressable from outside the principal's own world.

In the URL

A user navigating to a Space-hosted webapp uses the public path:

https://hivecast.ai/alt.stories.ghost-stories.funny/chat/

The cloud's gateway routes that to the runtime owning chat under that Space's authority root. The user does NOT see spaceId, authorityRoot, or publicNamespace in the URL.

See also

• Device pairing — the ceremony that pre-claims a Space path.
• Security model — per-Device and (target state) per-Space credentials.
• Overview → Glossary — spacePath, spaceId, authorityRoot, publicNamespace definitions.
• WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md — the authoritative spec for current and target state.

Source: WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md; projects/matrix-3/packages/host-service/src/types.ts lines 28-37 (IHostTransportConfig carries authorityRoot, addressRoot, spaceId, routeKey, publicNamespace); repo-root CLAUDE.md "Public Space identity" table.