orca/docs/namespace.md

# Namespace and Paths

Orca stores all on-disk state under a single **namespace root**
directory. The v0.9 re-architecture introduced a multi-namespace
layout (R-002) where each namespace is a self-contained directory tree
with its own database, jobs, allocs, env, and secrets. A `cluster/`
directory holds cluster-wide artifacts shared across namespaces.

> **v0.9 layout (canonical)**: This document describes the v0.9
> multi-namespace layout. The v0.8 flat layout (`orca.db`, `ca.crt`,
> `server.crt` at the root) is deprecated and will be removed in
> v0.11. See [v0.8 flat layout](#deprecated-v08-flat-layout) below.

## Namespace root resolution

The namespace root is resolved in this order:

1. If `--system` flag is passed → root is `/root/.orca` (errors if
   `ORCA_HOME` is set to a conflicting value).
2. Else if `ORCA_HOME` is set → root is `$ORCA_HOME`.
3. Else → root is `~/.orca` (`$HOME/.orca`).

### `ORCA_HOME` (REQ-041)

Set the `ORCA_HOME` environment variable to change the namespace root
for all orca components:

```bash
export ORCA_HOME=/var/lib/orca
orca init          # creates /var/lib/orca/
orca ns create prod
```

### `--system` (REQ-042)

The `--system` persistent flag selects the system-level namespace root
`/root/.orca`:

```bash
sudo orca --system init          # creates /root/.orca/
sudo orca --system ns list
```

If `ORCA_HOME` is already set to a different value, `--system` returns
an error (to avoid silent namespace mismatches).

## v0.9 multi-namespace layout (R-002)

```
$ORCA_HOME/
├── cluster/                  # cluster-wide (NOT a workload namespace)
│   ├── ca.crt, ca.key        # step-ca root (R-006, D-101)
│   ├── master.key            # AES-256-GCM root (R-011, mode 0600)
│   ├── config.md             # Markdown frontmatter config (R-014)
│   ├── known_hosts           # SSH known_hosts (D-035)
│   ├── orca_ssh_key          # orca SSH private key (D-037)
│   ├── orca_ssh_key.pub      # orca SSH public key
│   ├── peers/<host>/         # per-peer directory
│   ├── txns/                 # cluster transaction log (R-016)
│   └── state/                # cluster state
├── _defaults/                # implicit root namespace (always exists)
│   ├── ns.md                 # namespace frontmatter (kind: Namespace)
│   ├── .env                  # per-namespace env
│   ├── .env.secrets          # encrypted secrets
│   ├── db/orca.db            # per-namespace SQLite database
│   ├── jobs/                 # submitted jobspecs
│   └── alloc/                # allocation state
├── <explicit-namespace>/     # operator-created (e.g., prod, staging)
│   ├── ns.md
│   ├── .env, .env.secrets
│   ├── db/orca.db
│   ├── jobs/, alloc/
│   └── syncthing/            # Syncthing config (if replicated volumes)
└── orca_cache.db             # CLI-side cache (R-008)
```

### Key points

- **`_defaults/`** is the implicit root namespace (D-159). It always
  exists. Every namespace inherits from `_defaults` and cannot opt out
  (D-185, D-187).
- **`cluster/`** is NOT a workload namespace — it holds cluster-wide
  artifacts (CA, master key, SSH keys, known_hosts, peers, txns).
- **Per-namespace DBs**: each namespace has its own
  `db/orca.db` (R-002). No namespace column in SQLite.
- **Namespace inheritance**: child namespaces inherit env and
  constraints from parents (via `ns.md` frontmatter `parents:` field).
  `_defaults` is always appended last in the inheritance chain.
- **`orca ns` subcommands**: `list`, `create`, `delete`, `inspect`,
  `validate` — see [docs/cli.md](cli.md#orca-ns).

### Path reference (`internal/paths/`)

| Function | Path | Contents |
|----------|------|----------|
| `Root()` | `$ORCA_HOME` | Namespace root |
| `ClusterDir()` | `Root()/cluster` | Cluster-wide artifacts |
| `NamespaceDir(ns)` | `Root()/ns` | Per-namespace directory |
| `NSDb(ns)` | `Root()/ns/db/orca.db` | Per-namespace SQLite DB |
| `NSEnv(ns)` | `Root()/ns/.env` | Per-namespace env |
| `NSSecrets(ns)` | `Root()/ns/.env.secrets` | Encrypted secrets |
| `NSJobs(ns)` | `Root()/ns/jobs` | Jobs dir |
| `NSAlloc(ns)` | `Root()/ns/alloc` | Alloc dir |
| `NSMd(ns)` | `Root()/ns/ns.md` | Namespace frontmatter |
| `DefaultNamespace()` | `_defaults` | Implicit root (D-159) |
| `CACertPath()` | `ClusterDir()/ca.crt` | step-ca root (D-101) |
| `MasterKeyPath()` | `ClusterDir()/master.key` | AES-256-GCM root key |
| `KnownHostsPath()` | `ClusterDir()/known_hosts` | SSH known_hosts |
| `SSHKeyPath()` | `ClusterDir()/orca_ssh_key` | orca SSH private key |
| `ConfigPath()` | `ClusterDir()/config.md` | Markdown config (R-014) |
| `CacheDB()` | `Root()/orca_cache.db` | CLI-side cache (R-008) |
| `PeersDir()` | `ClusterDir()/peers` | Peers directory |
| `TxnDir()` | `ClusterDir()/txns` | Transaction log (R-016) |

## Creating and managing namespaces

```bash
# List all namespaces
orca ns list

# Create a namespace (inherits from _defaults)
orca ns create prod

# Create a namespace with an explicit parent
orca ns create staging --parent prod

# Inspect the effective inheritance chain + merged env
orca ns inspect prod

# Validate a namespace's inheritance chain
orca ns validate prod

# Delete an empty namespace (refuses if jobs/ or alloc/ non-empty)
orca ns delete staging
```

See [docs/cli.md](cli.md#orca-ns) for the full `orca ns` reference.

## `ORCA_DB` override

For finer-grained control, `ORCA_DB` overrides only the database path
(not the cert/namespace paths). This is primarily a testing affordance.

```bash
export ORCA_DB=/tmp/test.db
orca init   # uses /tmp/test.db for the DB, ~/.orca/ for everything else
```

## Deprecated: v0.8 flat layout

> **Deprecated in v0.9**: The v0.8 flat layout (`orca.db`, `ca.crt`,
> `ca.key`, `server.crt`, `server.key` at the namespace root) is
> superseded by the v0.9 multi-namespace layout (R-002). The v0.8
> layout is supported during the dual-write window via
> `internal/certpaths` (a thin shim) and will be removed in v0.11.

The v0.8 flat layout stored all state at the namespace root:

| Path | Contents |
|------|----------|
| `~/.orca/orca.db` | SQLite database |
| `~/.orca/ca.crt` | CA certificate |
| `~/.orca/ca.key` | CA private key |
| `~/.orca/server.crt` | Server certificate |
| `~/.orca/server.key` | Server private key |

The v0.9 re-architecture moved these to `cluster/` (CA, SSH keys) and
per-namespace `db/` (SQLite) to support multi-tenancy (R-002). The
`orca doctor --legacy-paths` command (v0.11-P14c) will detect v0.8
residue and recommend migration.

## See also

- [Install Guide](install.md) — 1-liner install with `install.sh`.
- [Docker Guide](docker.md) — running orca in a container.
- [CLI Reference](cli.md) — `orca ns` subcommands.
- [Jobspec Reference](jobspec.md) — markdown frontmatter schema.