Namespaces

Grace operates within a multi-workspace ecosystem where different systems maintain their own unit registries and documentation platforms. Namespaces are the abstraction layer that allows these systems to reference each other reliably, regardless of whether the target is in the local filesystem or a remote HTTP endpoint.

Core Concepts

A namespace is defined by:

• Scheme: The URI prefix (e.g., stratt://, choco://)
• Description: What kinds of artifacts live in this namespace
• Resolver: The mechanism for converting URIs to actual resources
• Trust: Whether this namespace is cryptographically verified or just filesystem-resolved
• Local path: The filesystem location of the namespace root (for development)
• Web path: The HTTP endpoint for remote resolution (for production)

URI Format

All cross-workspace references follow this pattern:

{scheme}://{resource_path}@{version}

Examples:

• stratt://dev/chain/domain-extension-pipeline@1.0.0 — a chain from STRATT
• choco://security/threat-model@2.1 — a document from Choco HQ
• grace://architecture/protocol-layers@1.0 — an architectural specification (planned)

Active Namespaces

STRATT (stratt://)

The STRATT prompt unit registry — the reference implementation of the GRACE Protocol.

Property	Value
Domains	dev, ops, docs, neuro, finance, nutrition, legal, film, artist, core, shared
Types	role, rule, task, chain, supply
Trust	✅ Cryptographically verified (Blake3 fingerprints)
Resolution	UnitRegistry (local filesystem, always available during development)
Local path	~/code/workspace/stratt-hq/packages/units/
Format	stratt://{domain}/{type}/{slug}@{version}

When you write a GRACE document that references a STRATT unit, use the full URI:

The domain extension pipeline is defined in `stratt://core/chain/domain-extension-pipeline@1.0.0`.

Choco HQ (choco://)

Choco is the TimeChain-driven documentation engine. It manages namespace-aware documentation across the entire Grace ecosystem.

Property	Value
Paths	docs, api, specifications
Trust	✅ Filesystem-resolved (environment-verified)
Resolution	ChocoBridgeResolver (filesystem mode active; HTTP mode pending)
Local path	~/code/workspace/choco-hq/
Web path	~/code/workspace/cho-co/ (frontend)
API endpoint	https://api.cho.co/resolve (future)
Format	choco://{namespace}/{path}@{version}

Choco uses namespace awareness to track which workspace owns each document:

namespaces:
  stratt:
    path: ~/code/workspace/stratt-hq
    registry: packages/units
  grace:
    path: ~/code/workspace/grace-hq
    registry: architecture
  choco:
    path: ~/code/workspace/choco-hq
    registry: docs

When you reference a Choco document from Grace, you explicitly name the source namespace:

See the Choco threat model at `choco://security/threat-model@2.1`.

Planned Namespaces

Grace (grace://) — Coming Soon

Once Grace is deployed as a standalone artifact registry, it will have its own namespace:

- scheme: grace
  description: Grace orchestration artifacts
  trusted: true
  local_path: ~/code/workspace/grace-hq
  paths: [architecture, automation, protocols]
  uri_format: "grace://{path}@{version}"

This will allow external systems to reference Grace specifications directly:

grace://protocol/overview@1.0.0

Cross-Workspace Navigation

The Grace ecosystem supports five navigation patterns:

1. Local Filesystem Resolution (Development)

When both workspaces are cloned locally, the resolver uses the filesystem:

stratt://dev/chain/build-pipeline@1.0.0
↓
~/code/workspace/stratt-hq/packages/units/dev/chain/build-pipeline.md@1.0.0

Environment variable:

GRACE_RESOLUTION_MODE=filesystem

2. HTTP Endpoint Resolution (Production)

For cloud deployments, HTTP resolvers fetch from remote registries:

stratt://dev/chain/build-pipeline@1.0.0
↓
https://api.stratt.dev/units/dev/chain/build-pipeline?version=1.0.0

Environment variable:

GRACE_RESOLUTION_MODE=http
STRATT_API_ENDPOINT=https://api.stratt.dev

3. Trust Verification (STRATT only)

STRATT units are cryptographically signed. When resolving a stratt:// URI, the resolver:

1. Fetches the unit metadata
2. Verifies the Blake3 fingerprint matches the canonical serialization
3. Checks that the unit’s state is not tampered or tombstoned
4. Returns the unit or raises FM-01 (fingerprint tamper detected)

4. Version Pinning

All URIs include version constraints:

stratt://dev/role/engineer@1.2.3     ← exact version
stratt://ops/rule/circuit-breaker@2  ← major version (resolved to latest 2.x.x)
stratt://docs/task/review-pr@*       ← any version (always latest)

5. Relative References

Within a single namespace, documents can use relative paths:

See [the protocol overview](./overview.md) for details.

But cross-namespace references must always be absolute:

See [STRATT units](stratt://dev/role/engineer@1.0.0) for details.

Namespace Awareness in Documents

When you author a document that references multiple namespaces, include a reference table at the top or bottom:

## Cross-Namespace References

| Reference | Namespace | Path |
|-----------|-----------|------|
| Domain extension pipeline | STRATT | `stratt://core/chain/domain-extension-pipeline@1.0.0` |
| Threat model | Choco | `choco://security/threat-model@2.1` |
| Protocol specification | Grace | `grace://protocol/specification@1.0.0` |

This ensures readers understand the provenance of each reference and can navigate to the authoritative source.

Environment Variables

Grace respects these namespace configuration variables:

Variable	Default	Purpose
GRACE_RESOLUTION_MODE	filesystem	Switch between filesystem and http
STRATT_LOCAL_PATH	~/code/workspace/stratt-hq	Override STRATT workspace location
CHOCO_RESOLVE_MODE	filesystem	Choco resolution strategy
CHOCO_LOCAL_PATH	~/code/workspace/choco-hq	Override Choco workspace location
CHOCO_API_ENDPOINT	(unset)	Future HTTP resolver for Choco

Resolving Namespace Conflicts

If two namespaces define the same resource slug, the resolver applies this priority:

1. Exact match in declared namespace — highest priority
2. Wildcard namespace match — medium priority
3. Local filesystem — lowest priority (fallback)

Example: If both stratt:// and choco:// define a security/threat-model resource, and you reference threat-model without a scheme, it resolves to the one declared in your document’s frontmatter:

---
referenced_namespaces: [stratt, choco]
default_namespace: stratt
---

In this case, threat-model resolves to stratt://security/threat-model@* by default.

See Also

• STRATT units: stratt://core/chain/domain-extension-pipeline@1.0.0
• Choco documentation: choco://docs/namespace-awareness@1.0
• Grace architecture: See Protocol Layers