Namespaces & Tenancy

In one sentence. A namespace is WIP's isolation and tenancy boundary — every document, template, and terminology carries a namespace (its prefix), and that Namespace record is what governs how cross-namespace references, ID generation, and deletion are allowed to behave for everything filed under it.

Why it exists. A Namespace is described in its own model as "a user-facing container for organizing data" (namespace.py), holding two things per tenant: isolation_mode, which decides whether other namespaces may reference into it at all, and id_config, which decides how identifiers are minted per entity type. It exists so that isolation and identity-generation policy are per-tenant configuration, not global platform behavior — and so a tenant can be removed (deletion_mode) without silently breaking tenants that still point into it (allowed_external_refs, and the inbound-reference checks run before deletion).

The model

Namespace (components/registry/src/registry/models/namespace.py) — Mongo collection namespaces, unique index on prefix, secondary index on status.

The model's own comment states the intended status lifecycle: active <-> archived (archive/restore), -> locked (deletion in progress), -> physical removal. The archive/restore transition itself is not implemented in this doc's scope — see the ⚠ GAP below.

Deletion touches more than the Namespace record. namespace_deletion.py enumerates every collection a namespace's data can live in:

namespace_grants and composite_key_claims are referenced here only as raw collection names to delete from; their document shape is not modeled in this doc's scope.

How it works

Dry run. NamespaceDeletionService.dry_run(prefix) is read-only: it counts every entity in the table above (_count_entities), lists the namespace's MinIO object keys (_get_minio_keys), and checks inbound references from other namespaces (_check_inbound_references). It returns safe_to_delete (true only if no high-severity inbound reference exists) and requires_force.

Starting a deletion. start_deletion(prefix, force, requested_by):

1. Loads the Namespace; fails if it doesn't exist.
2. Refuses if prefix == "wip" (the default namespace can never be deleted).
3. Refuses unless deletion_mode == "full".
4. Refuses if status == "locked" (a deletion is already in progress).
5. Re-checks inbound references; if any are high-severity and force was not passed, refuses.
6. Sets status = "locked" and saves the namespace.
7. Builds a DeletionJournal of ordered DeletionSteps (_build_journal) and persists it.
8. Executes the journal (_execute_journal).

Journal step order (_build_journal), each step only added if it has matching data:

1. MinIO objects for the namespace's files — must run before file metadata is deleted.
2. One step per non-empty collection in _EXTERNAL_COLLECTIONS (document-store, template-store, def-store).
3. One step per non-empty collection in _REGISTRY_COLLECTIONS (registry_entries, namespace_grants, composite_key_claims).
4. id_counters, matched by the counter_key regex rather than a namespace field.
5. A PostgreSQL step, only if REPORTING_SYNC_URL is configured — deletes rows via a reporting-sync HTTP DELETE call, not a direct DB connection.
6. A final step that deletes the namespaces record itself.

Execution and crash recovery. _execute_journal runs steps in order, saving the journal after every step. A step already status == "completed" (from an earlier, interrupted run) is skipped. MongoDB step failures raise, mark the journal status = "failed", and stop the journal — per the module docstring, "Mongo steps fail the journal loudly and resume idempotently." MinIO and PostgreSQL step failures are swallowed into step.error instead of raising, and the step is marked "completed_with_errors" — per the module docstring, this is deliberate: "a dead secondary store must not make a namespace undeletable." resume_deletion(prefix) re-runs _execute_journal on the most recent DeletionJournal with status == "in_progress". recover_incomplete_deletions() runs the same resume for every in_progress journal at process startup.

Terminal status. Once every step has been attempted, the journal's overall status is set to "completed_with_warnings" if any step ended "completed_with_errors", otherwise "completed".

Rules & invariants

• The wip namespace is permanently protected. start_deletion raises unconditionally if prefix == "wip" — this is a literal string check in the service, not a flag on the Namespace model.
• deletion_mode gates hard deletion. A namespace defaults to "retain" (soft-delete only); start_deletion refuses to run at all until deletion_mode is switched to "full".
• Deletion is single-flight per namespace. status == "locked" blocks a second start_deletion call outright.
• Inbound-reference severity gates force. template_extends (another namespace's template extends one of this namespace's templates) and terminology_reference (another namespace's template field points at one of this namespace's terminologies) are high severity and block deletion unless force=True. synonym_link (a registry synonym in another namespace pointing here) is low severity and never blocks — but it is still recorded in the journal's broken_references even on a forced, non-checked path, because — per the code's own comment — "gating on force would drop the only record of what broke."
• The dry-run count and the real deletion read the same collection lists. _count_entities deliberately iterates _REGISTRY_COLLECTIONS + _EXTERNAL_COLLECTIONS, the same lists _build_journal deletes from, specifically so the two can't drift — the code's own comment notes this was previously a source of a bug ("composite_key_claims went uncounted while being deleted").
• Only MongoDB deletion is guaranteed. MinIO and PostgreSQL cleanup are best-effort by design, so a namespace can finish deletion ("completed_with_warnings") with orphaned MinIO objects or PostgreSQL rows still present. A caller that treats "completed_with_warnings" as equivalent to full removal will be surprised — this is the kind of non-intuitive-friction behavior the PoNIFs doc catalogs; see See also.
• id_counters isn't namespace-scoped like everything else. Every other collection here is filtered on a namespace field; id_counters is filtered by a counter_key string-prefix regex instead, because counter documents are keyed "<prefix>:<entity_type>", not tagged with a namespace field.

⚠ GAP: no permission/authorization check is visible anywhere in namespace.py or namespace_deletion.py for who may call dry_run, start_deletion, or resume_deletion. If such a check exists, it lives outside this doc's source_scope (likely registry/api/ and/or the auth-gateway) — see Auth & Access.

Gotchas

• status = "deleted" is dead. It remains a legal value in the Literal and the model's own comment is explicit that it is retained "so pre-cutover records still load" — no code path in this doc's scope writes it. The live lifecycle is active / archived / locked, not active / deleted.
• A "safe" dry run can still break something. dry_run's safe_to_delete is computed only from high-severity references (template_extends, terminology_reference); a synonym_link reference from another namespace doesn't affect safe_to_delete or requires_force, so a dry run can report "safe" while the real deletion still silently breaks a synonym link elsewhere.
• A null count from reporting-sync is guarded, not trusted. The PostgreSQL cleanup step explicitly checks for a present-but-null total_deleted in the reporting-sync response and refuses to coerce it into the journal's int-typed count field, recording a degraded step instead — the code comment attributes this to a past reporting-sync response-shape change.
• Archive/restore isn't in this file. The status docstring documents active <-> archived as a transition, but neither namespace.py nor namespace_deletion.py contains the code that performs it (see the ⚠ GAP above).
• namespace_grants and composite_key_claims are deleted as raw collections. Their schemas aren't modeled anywhere in this doc's scope — you only see them here as (collection_name, filter_field) pairs the deletion journal iterates.
• A namespace with a stray cross-namespace synonym claim isn't fully covered by start_deletion's own inbound-reference check. The composite_key_claims collection's own in-code comment notes that a claim owned by an entry in another namespace but referencing this one is handled separately, by an orphan-reconciliation routine that runs at startup — not by anything in _check_inbound_references or the deletion journal itself.

See also

• Data Model Reference — the documents, templates, and terminologies that live inside a namespace.
• Identity & the Registry — id_config / IdAlgorithmConfig, identity hashing, and synonyms, which this doc treats only as a namespace-level configuration surface.
• Registry API — the REST surface for namespace management (create, archive/restore, dry-run, delete) is deliberately out of this doc's scope; the manifest's own scope note assigns it there. (Not part of the reading list's literal fixed cross-ref set for concept docs — flagged for the reading list to confirm; see report.)
• Auth & Access — for the permission model this doc's scope does not establish (see ⚠ GAP above).
• PoNIFs — for the best-effort-completion behavior named in Rules & invariants.