arch-scaffold-namespace git:20261014.fec008fA

Immutable. This exact content never changes and is served at /api/v1/blob/ef7b29db14126223.

---
name: arch-scaffold-namespace
description: "Create an object-model namespace (a swimlane) with its first entity: the manager interface and impl, storage in Postgres and memory, its README, and the wiring into both roots, in the shape of the scaffold's own namespaces. Python."
allowed-tools: Read, Grep, Glob, Write, Edit, Bash(make check), Bash(make infra-up), Bash(make migrate), Bash(make migrate-check), Bash(make openapi), Bash(docker info:*), Bash(uv run:*), Bash(git status:*)
---

# arch-scaffold-namespace

A path that starts with `../` is read from this skill's folder
as `realpath` resolves it.
Conventions: `../_shared/scaffold-conventions.md`.
Sections of `../../architecture.md`: Namespaces as
Swimlanes, Interfaces (Injectability), The Business Layer
(Cross-Manager Dependencies), The Storage Layer (Namespace Shape,
Storage Root, Cross-Storage Dependencies), Documentation as Code (A
README at Every Level).

## Input

`<namespace> <FirstEntity> [field:type ...] [--role core|activity|queue|admin] [--scope system|org|identity|both]`

Example: `inventory Warehouse address:str timezone:str`. Both are
required; ask for them when missing. A namespace arrives with its first
entity, since `om/tests/unit/test_interfaces.py` refuses an interface
that declares no method. The entity arguments, the role, and the scope
go to `arch-scaffold-entity` in step 3.

## Created

The shape is the `media` namespace, `om/src/<name>/om/media/`. Under
`om/src/<name>/om/<ns>/`:

| File | Holds |
|------|-------|
| `__init__.py` | `from .manager import <Ns>ManagerInterface` |
| `README.md` | the namespace in the product's language, one level below `om/README.md`: its nouns, what can happen to them, the rules that hold; no developer or operator instruction |
| `manager.py` | `<Ns>ManagerInterface`, a docstring naming the swimlane |
| `impl/manager.py` | `<Ns>ManagerImpl`, taking its storage interface, the `OutboxRelayInterface`, and every manager it calls, each by interface |
| `storage/__init__.py` | `<Ns>StorageInterface`, a docstring saying every operation takes `org_id` first |
| `storage/impl/postgres.py` | `<Ns>StoragePostgresImpl(PgStorageBase, <Ns>StorageInterface)` |
| `storage/impl/memory.py` | `<Ns>StorageMemoryImpl(MemoryStorageBase, <Ns>StorageInterface)` |
| `types/__init__.py`, `impl/__init__.py`, `storage/impl/__init__.py`, `storage/tables/__init__.py` | empty; the entity skill fills `types/` and `storage/tables/` |

In a tree whose ops skills read `.agents/skills/_shared/signals/`, the
namespace's signals file is created there too, `<ns>.md`: `# Signals:
<ns>` and one sentence on what the namespace does, in the shape of the
scaffold's own files beside it. A skill that later gives the namespace
a kind, an outcome, a log line, or a failure event adds it there, under
the heading the folder's `README.md` names.

## Changed

| File | Change |
|------|--------|
| `om/src/<name>/om/storage/root.py` | `get_<ns_singular>_storage()` on the storage root, below the marker |
| `om/src/<name>/om/storage/impl/postgres.py`, `memory.py` | each root builds its impl and returns it from the getter, each below its marker |
| `om/src/<name>/om/root.py` | below each marker: the field `<ns>` on `Managers`, the namespace's options on `build_managers`, the call `<ns> = build_<ns>(...)` in its body, `<ns>=<ns>` in `Managers(...)`, and, at the end of the module, `build_<ns>`, which builds `<Ns>ManagerImpl` |
| `om/README.md` | the namespace's nouns, each defined for a reader with no code, the first linked to the namespace's README, and in the relations the page names |
| `llms.txt` | a line that links the namespace's README and says what it covers, as the lines of the scaffold's namespaces do, below the section's marker under System developers, and under Tenant users and admins when a tenant's users work with its nouns |

## Procedure

1. Write the files, then wire both storage roots and `build_managers`,
   as `media` is wired. A manager this one calls is a constructor
   parameter typed by its interface, and `build_managers` builds the
   callee first.
2. The namespace reaches the API with its first entity, whose skill
   adds the service, its impl, and its router.
3. Read `../arch-scaffold-entity/SKILL.md` and
   follow it with `<namespace> <FirstEntity> <field:type ...> --role
   <role> --scope <scope>`, before the gates run.

## Output

As `../_shared/scaffold-conventions.md` states.