Spec: DEFINE NAMESPACE

Global conventions and notation: spec/README.md.

Ground truth: the 3.3.0 parser (the =3.3.0 embed — the 2026-09-25 floor move; originally pinned against v3.2.4) — parser (parse_define_namespace) and the seeding logic (kvs/ds.rs::initialise_defaults, server/src/dbs/mod.rs). Cross-checked against a local in-memory 3.2.3 server (2026-09-18). The simplest statement: a name plus a doc comment. Nothing else.

struct Namespace {
  name: Ident,                        // SurrealQL identifier rules
  comment: Option<DocComment>,        // from /// (lines joined with \n)
}

/// <doc comment>                        // optional — emitted as COMMENT
namespace <name>;
namespace <name> {
};

The empty block may be collapsed (both forms equivalent). A non-empty block is an error — there are no clauses.

Emit: DEFINE NAMESPACE <name> [COMMENT …]; (OVERWRITE implied per the codegen model), followed by USE NS <name>; (codegen model item 1).

Reverse parser (INFO → SDL)

Input: INFO FOR ROOT returns namespaces as a map of name → DDL string; entries are plain DEFINE (no kind prefix; strip if present). COMMENT '…' maps back to /// lines. The server conditionally auto-seeds a default namespace — main by default, overridable via --default-namespace, suppressible via --no-defaults, only on brand-new instances — carrying the comment 'Default namespace generated by SurrealDB'. Identify it by that comment fingerprint (not the name); the differ reports it as expected-unmanaged unless the SDL file declares it.

Empirically verified on the 3.3.0 embed (2026-09-25 floor move; first verified in-memory 3.2.3, 2026-09-18): define + round-trip ✅; the main namespace seeding observed with that exact comment ✅.

File-context role: namespace typically heads an SDL file and scopes everything below it; each namespace statement in a file emits its own USE NS. One namespace per file is the recommended layout; multiple are legal.

Examples (one per clause)

doc comment:

/// Acme Corporation
namespace acme;

DEFINE NAMESPACE OVERWRITE acme COMMENT 'Acme Corporation';
USE NS acme;

DEFINE NAMESPACE acme COMMENT 'Acme Corporation';

bare:

namespace staging;

DEFINE NAMESPACE OVERWRITE staging;
USE NS staging;

DEFINE NAMESPACE staging;