@shortlink-org/portolan 0.2.4 → 0.4.0

package/plugins/extract-argocd/options.schema.json

@@ -0,0 +1,44 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "repo": {
+      "type": "string",
+      "description": "The repository this tree is, spelled the way `Service.repo` spells it. A git generator pointing at another repository cannot be walked and is passed over with a warning; left out, every git generator is taken to mean this tree.",
+      "examples": ["github.com/acme/gitops"]
+    },
+    "paths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Directories under the input root that hold the Applications and ApplicationSets, so overlays and charts beside them are not read for Argo CD objects. Left out, the whole root is walked.",
+      "examples": [["bootstrap", "appsets"]]
+    },
+    "environmentLabel": {
+      "type": "string",
+      "default": "env",
+      "description": "The Application label that names the environment. An Application without it is placed by the cluster it deploys to."
+    },
+    "labels": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Which Application labels name the service it deploys. The defaults are the Kubernetes recommended labels, the same ones fetch-argocd and fetch-k8s read.",
+      "properties": {
+        "context": {
+          "type": "string",
+          "description": "The label whose value is the bounded context's slug.",
+          "default": "app.kubernetes.io/part-of"
+        },
+        "service": {
+          "type": "string",
+          "description": "The label whose value is the service's slug.",
+          "default": "app.kubernetes.io/name"
+        }
+      }
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "argocd.json"
+    }
+  }
+}

package/plugins/extract-celery/extract.py

@@ -155,8 +155,6 @@ def extract(input_: Input, opts: Options, b: Builder, cwd: str = "") -> None:
     flows.sort(key=lambda f: f["slug"])
 
     fragment: Dict[str, Any] = {
-        "generatedAt": input_.generated_at,
-        "commit": input_.commit,
         "contexts": [
             {
                 "id": context,

package/plugins/extract-celery/extract_test.py

@@ -27,7 +27,7 @@ ROOT = os.path.abspath(os.path.join(HERE, "..", ".."))
 def run(fixture, options):
     b = Builder()
     extract(
-        Input(root=os.path.relpath(os.path.join(HERE, "testdata", fixture), ROOT), commit="abc1234", generated_at="2026-09-05T00:00:00Z"),
+        Input(root=os.path.relpath(os.path.join(HERE, "testdata", fixture), ROOT)),
         Options.of(options),
         b,
         cwd=ROOT,

package/plugins/extract-celery/main.py

@@ -25,6 +25,7 @@ HERE = os.path.dirname(os.path.abspath(__file__))
 DESCRIPTOR = {
     "name": "extract-celery",
     "summary": "Reads Celery task declarations, the calls that enqueue them and the routes that place them into work queues and source-backed job flows.",
+    "category": "messaging",
     "phases": ["extract"],
 }
 

package/plugins/extract-csharp-ddd/README.md

@@ -0,0 +1,213 @@
+# extract-csharp-ddd
+
+A C# tree laid out by module and layer in, a catalog fragment out - three
+kinds, when the API host proves an HTTP contract and the database project a
+schema. The .NET twin of `extract-php-ddd`: like it, this reads a layout
+rather than a framework, and the layout is the claim. Nothing is annotated
+for the catalog; the directory a class sits in and the base it extends say
+what it is.
+
+The layout is the one [kgrzybek's modular-monolith-with-ddd](https://github.com/kgrzybek/modular-monolith-with-ddd)
+made common in .NET - `src/Modules/<Module>/{Domain,Application,Infrastructure,IntegrationEvents}`
+with one API host under `src/API` and one SQL Server database project under
+`src/Database` - and it is that project the site ships as a profile, read by
+this extractor alone.
+
+Written in C# and run as a process plugin, `dotnet plugins/extract-csharp-ddd/bin/portolan-extract-csharp-ddd.dll`,
+built by `npm run plugins:build` with the .NET SDK (8 or later). The parser
+is Roslyn, the compiler's own, and the one dependency; every `.cs` under the
+root goes into one `Compilation`, so a partial class is one type, a base
+chain is followed across files and modules, and the type of `new X(...)` or
+of a variable is a fact rather than a guess. **The application is never
+built or run, and none of its packages is restored.** What comes from NuGet
+- MediatR's `INotificationHandler`, EF's `IEntityTypeConfiguration`,
+ASP.NET's `ControllerBase` - is an error type with a name, and every rule
+that touches one goes by the name as written on the base list. Only the
+runtime's own assemblies are referenced, so that `Guid`, `string` and
+`List<T>` read as themselves.
+
+## The layout it reads
+
+```
+src/Modules/<Module>/Domain/<Aggregate>/      the model: root, entities, value objects, events, ports
+src/Modules/<Module>/Application/<Group>/     the use cases: commands, queries, their handlers, notification handlers
+src/Modules/<Module>/Infrastructure/          the adapters: repositories, EF configurations, the bus subscriptions
+src/Modules/<Module>/IntegrationEvents/       what the module tells the other modules
+src/API/**/Modules/<Module>/*Controller.cs    the HTTP edge of that module
+src/Database/**/Structure/<schema>/Tables/    the tables, one file each, T-SQL
+src/Database/**/Structure/<schema>/Views/     the views over them
+src/BuildingBlocks/                           the bases: Entity, ValueObject, DomainEventBase, IntegrationEvent
+```
+
+`modules`, `api` and `database` in the options rename the three roots. A
+directory named `Tests`, or ending in `Tests`, is not read; neither is `bin/`
+or `obj/`.
+
+## What becomes what
+
+**Context.** A directory under `src/Modules` with `Domain` or `Application`
+under it, with its slug as id - `user-access` for `UserAccess`.
+`classification` in the options applies to every module the tree declares;
+nothing in the tree says which is core.
+
+**Service.** One per module, `<module>.module` - `meetings.module` - because
+a module here has its own schema, its own outbox, its own composition root
+and its own slice of the API. There is one deployable, and the catalog says
+so where it matters: a call from one module to another is drawn as a `call`
+step with a note that it is in process. The controllers filed under the
+module's directory of the API host are its HTTP interfaces, one per
+controller, `meetings.module.meetings`.
+
+**Aggregate.** A directory under `Domain/` whose own files declare a root: a
+class implementing `IAggregateRoot` or extending a class named
+`AggregateRoot` (the event-sourced base Payments keeps in its `SeedWork`).
+Subdirectories with no root of their own fold in - `Events/`, `Rules/` - and
+one with a root is an aggregate in its own right, `Members/MemberSubscriptions`.
+`SharedKernel`, `SeedWork`, `Shared`, `Rules`, `Events` and `Exceptions` at
+the top of `Domain/` are not aggregates. A directory with types and no root
+is a group the application layer may claim as a `model-group`; unclaimed, it
+is reported.
+
+The root and every class extending `Entity` are the entities, the root first.
+Their fields are the public properties inherited from a base that is not the
+framework's, then their own members in source order, a private `_title`
+read as `title`, the `_domainEvents` list left out. A value object is a
+class extending `ValueObject`, `TypedIdValueBase` or `AggregateId<T>`, with
+its public properties read up the base chain, so `MeetingId` has the base's
+`value: Guid`; one with no fields is reported and not written. A C# `enum` in
+the directory is a closed set with its members, `[Obsolete]` carried as
+deprecated. Rules, exceptions, domain services and `I*Context` interfaces are
+not shape and are skipped.
+
+**Domain event.** A class extending `DomainEventBase` or implementing
+`IDomainEvent`, in the aggregate's directory. Its fields are its own public
+properties - `Id` and `OccurredOn` are the envelope. It has no wire: a
+domain event here is a MediatR notification in the same transaction, and a
+notification replayed from the outbox after it. Its consumers are the
+module's `INotificationHandler<TheEvent>` classes, and its
+`INotificationHandler<TheNotification>` classes where the notification
+extends `DomainNotificationBase<TheEvent>`, each `declared` with the
+handler's name. The id keeps the class name whole,
+`meetings.module.meetings.MeetingCreatedDomainEvent`, because the
+integration event that follows it is a different fact with the same stem.
+
+**Integration event.** A class extending `IntegrationEvent` under the
+module's `IntegrationEvents/`. Its publisher is the module whose application
+layer calls `IEventsBus.Publish(new X(...))`, and its aggregate is the one
+whose domain event the publishing handler's notification wraps; an event
+nobody publishes is reported and filed under the owning module's
+`integration-events` group. Its wire is the class name on its own channel,
+`<bus>.<Event>` with `bus` from the options, `integration-events` by
+default, because the code names the class `InMemoryEventBus` and nothing
+else. Its consumers are the modules whose
+infrastructure says `SubscribeToIntegrationEvent<X>` or
+`new IntegrationEventGenericHandler<X>()`, each with the
+`INotificationHandler<X>` that hears it - `declared` when both are there,
+`unresolved` and reported when a module subscribes without a handler or
+handles without subscribing.
+
+**Channel.** The bus has no named channels - `InMemoryEventBus` routes by
+type and a module subscribes to a type - so each integration event is a
+channel of its own, `<bus>.<Event>`, of kind `event`: the module that
+publishes it sends on it, the modules that subscribe receive. Every module
+whose application layer calls `ICommandsScheduler.EnqueueAsync(new C(...))`
+has a `job` channel, `<module>.internal-commands`: the command written to
+its `InternalCommands` table in the same transaction, read by the
+ProcessInternalCommands job and handed to its handler. A command enqueued
+that no handler in the module takes is reported.
+
+**Operation.** A class under `Application/` whose base list says
+`ICommandHandler<C>` or `ICommandHandler<C, R>` or `IQueryHandler<Q, R>`; the
+message names the operation, `create-meeting` for `CreateMeetingCommand`.
+Its fields are the message's widest constructor's parameters, or its
+settable properties when it has none; its doc the handler's `<summary>`, or
+the message's; its source the handler's `Handle`. The aggregate is the
+domain directory named like the first directory under `Application/`
+(`Application/Meetings/CreateMeeting/` is `Domain/Meetings`), and a group
+with no such directory - `Countries`, `Authentication` - is a model-group
+named after it. A message extending `InternalCommandBase` is reached from
+the job channel; one implementing `IRecurringCommand` runs on a Quartz
+schedule. A handler under `Infrastructure/` is plumbing - `ProcessOutboxCommandHandler`
+- and is not read. `exposedBy` names the actions of the module's own
+controllers that new the message up; an action in another module's
+controller is a call across contexts and lives in the flow.
+
+**Store.** One per schema of the database project, owned by the module
+whose EF configurations `ToTable("X", "schema")` into it, else the module
+named like it, else the module that writes it; a read owns nothing, and a
+schema with no owner - `app`, written by the building blocks - is reported
+and not read. The module's home schema is its `db`, `meetings.module.db`;
+a second schema keeps its name. `storeKind` in the options says what the
+schemas live in, `other` for SQL Server. A table is read from its
+`CREATE TABLE`: columns with type and nullability, the primary key from the
+constraint or the column, foreign keys, and the indexes created beside it.
+A view is read from its `CREATE VIEW`: the select list's names, each typed
+from the column it selects when the alias resolves, the tables it reads,
+and the SELECT itself as the definition.
+
+An `IEntityTypeConfiguration<T>` in the module's infrastructure says which
+table holds T: the `ToTable` in `Configure` is the table, `Property<X>("_f").HasColumnName("C")`
+and `Property(x => x.P)` map its columns to T's fields, an `OwnsOne` maps
+the value object's parts to the owner's field, and an `OwnsMany` with a
+`ToTable` of its own is the child's table. The table `persists` the block
+and takes the role `aggregate-root` or `child`; a table nobody maps is
+`outbox` when it is the outbox, `projection` when the application
+layer writes it with SQL, `lookup` when it is only ever read, `other`
+otherwise. A `Messages` or `Streams` table is where an event-sourced
+module's `IAggregateStore` keeps its streams.
+
+Accesses come from two places. A class in the infrastructure implementing an
+`I*Repository` port from the domain, or `IAggregateStore`, reads and writes
+the table that holds the port's root - `write MeetingRepository.AddAsync` -
+by the method's name: `Add`, `Save`, `Update`, `Append` write, `Remove` and
+`Delete` delete, the rest read. Every string in a method of the application
+or infrastructure layer is read as SQL: `FROM`, `JOIN`, `INSERT INTO`,
+`UPDATE` and `DELETE FROM` against a schema-qualified name are accesses by
+that method; a view read is an access on the tables the view reads; a name
+the database project does not declare is reported - which is how the
+project's `v_Countriess` was found.
+
+**Flow.** One per controller action: the request in, the command or query
+the action news up, then what the handler does, followed through the
+classes it holds and the domain methods it calls, by symbol. A call on a
+port is a step to the store; a Dapper query a step to the tables its SQL
+names; `AddDomainEvent(...)` an event raised in process, drawn as a
+self-message with the event's id; `IEventsBus.Publish(...)` an event on the
+bus with a `message` handoff; `ICommandsScheduler.EnqueueAsync(...)` a `job`
+handoff to the module's internal queue; a command handed to another module's
+facade a `call` across the boundary, followed there. One flow per
+notification handler of a domain event, from the event in; one per
+subscription a module handles, from the bus in; one per internal command,
+from the queue in; one per recurring command, on its schedule. Each flow
+carries the trigger it was read from: `http`, `event`, `message`, `job` or
+`scheduled`.
+
+**HTTP.** One OpenAPI 3.1 document per module with controllers,
+`openapi.<module>.yaml` (`openapiOut` in the options), one operation per
+action: the path from `[Route]` and `[HttpGet("...")]` with `[controller]`
+filled in, the `{parameters}` typed from the action's, the `[FromBody]`
+class as the request schema one level deep, `[ProducesResponseType]` as the
+responses, `[HasPermission]` as `x-portolan-permission`, the action's
+`<summary>` or its name as the summary.
+
+## Options
+
+See `options.schema.json`. `modules`, `api` and `database` default to
+`src/Modules`, `src/API` and `src/Database`; `bus` to `integration-events`;
+`storeKind` to `other`; `repo` and `classification` to nothing.
+
+## Tests
+
+```bash
+dotnet run --project plugins/extract-csharp-ddd/test
+```
+
+`testdata/mymeetings` is a small tree in the layout: three modules, one of
+them event-sourced, a module publishing an integration event two others
+hear, an internal command enqueued from a subscription, a recurring command,
+an EF configuration with owned types and a child table, views, and a
+controller filed under a module the tree does not have. `expected.json`,
+`expected-stores.json` and the `openapi.*.yaml` beside it are what the
+extractor writes for it, and `expected-warnings.txt` what it says on the
+way; `UPDATE_GOLDEN=1` writes them again after a deliberate change, and the
+diff is the review.

package/plugins/extract-csharp-ddd/options.schema.json

@@ -0,0 +1,55 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "modules": {
+      "type": "string",
+      "description": "The directory the modules are in, relative to the input root: one directory per module, `Domain`, `Application`, `Infrastructure` and `IntegrationEvents` under it. Each module is a bounded context with one service.",
+      "default": "src/Modules"
+    },
+    "api": {
+      "type": "string",
+      "description": "The directory the HTTP host is in, relative to the input root. Controllers under a `Modules/<Module>` directory beneath it are that module's HTTP edge.",
+      "default": "src/API"
+    },
+    "database": {
+      "type": "string",
+      "description": "The directory the database project is in, relative to the input root: `Structure/<schema>/Tables/*.sql` and `Structure/<schema>/Views/*.sql` beneath it, one schema per module.",
+      "default": "src/Database"
+    },
+    "repo": {
+      "type": "string",
+      "description": "Where the source lives, as `host/owner/name`. Nothing in a .NET tree says, so the manifest does.",
+      "examples": ["github.com/kgrzybek/modular-monolith-with-ddd"]
+    },
+    "bus": {
+      "type": "string",
+      "description": "The address of the bus integration events cross modules on. The code names the class, `InMemoryEventBus`, and nothing else, so the manifest says.",
+      "default": "integration-events"
+    },
+    "storeKind": {
+      "enum": ["postgres", "mysql", "sqlite", "other"],
+      "description": "What the schemas live in. SQL Server is `other`.",
+      "default": "other"
+    },
+    "classification": {
+      "enum": ["core", "supporting", "generic"],
+      "description": "Whether the modules are core to the business, support it, or are generic and could be bought. One value for every module the tree declares."
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "domain.json"
+    },
+    "openapiOut": {
+      "type": "string",
+      "description": "Name of the inferred OpenAPI 3.1 document, inside the step's output directory, one per module with controllers; `{service}` is replaced with the module's slug.",
+      "default": "openapi.{service}.yaml"
+    },
+    "storesOut": {
+      "type": "string",
+      "description": "Name of the store fragment, inside the step's output directory. Written when the database project declares a schema a module maps to.",
+      "default": "stores.json"
+    }
+  }
+}

package/plugins/extract-django/README.md

@@ -39,21 +39,41 @@ resolves them without a type checker.
 
 ## What becomes what
 
-**Aggregate.** One per application. The root is the model named after the
-application — `invoices` holds `Invoice` — or the only model there is, or the
-one `aggregates` names in the manifest; an application with several models and
-no such name is reported and skipped, because guessing which of them the others
-hang off is how an aggregate boundary gets drawn wrong and stays wrong. The
-aggregate is named and slugged after the root, so a Django `invoices` and a Go
-`invoice` package land on the same id. Every concrete model of the application
-is an entity, the root included and first; abstract models are not. The
-readme is `README.md` in the application, or the root's docstring.
+**Models and aggregates.** Every concrete, non-proxy model is visible. When
+an application has an explicitly configured root, a model named after the
+application (`invoices` → `Invoice`), or just one concrete model, it retains
+its existing aggregate representation and stable root-based id.
+
+Otherwise the application is emitted as a `kind: "model-group"` entry with
+an empty `root` and an id ending in `models-<application-package>`. All of its
+concrete models appear once, alongside the application's value objects,
+operations and events. This is a source grouping, not a claim that the models
+share a transactional boundary. Its tables link to the model blocks without
+being labelled aggregate roots or children. No root-selection warning is
+emitted, and no configuration is required to browse the models.
+
+`options.aggregates` remains an optional refinement: selecting a root replaces
+the source group with an aggregate. A configured root that no longer exists
+produces a warning with concrete candidates, while retaining every model in
+the group. Settings can help repair that configuration and save the choice to
+the matching extraction step. Regenerate to apply it; other options are kept.
 
 **Field.** Each model attribute assigned a field, with the type as written:
 `CharField`, `DateTimeField`, and a relation as `ForeignKey[Invoice]`. The doc
 is the field's own `help_text`, which is the one place a Django model already
-writes down what a column means. Value objects are the frozen dataclasses in
-`values.py`, their fields the annotations as written.
+writes down what a column means. What the field call says a value must
+satisfy is read into the catalog's own words (portolan.0015): `max_length`
+is `max_len`, `unique=True` is `unique`, `choices` is `in` with the stored
+values — read off a `Choices` class, a literal list of pairs or a module-level
+constant, and left out when they come from a call — an `EmailField`,
+`URLField` or `UUIDField` is `format`, a `PositiveIntegerField` is `gte 0`,
+and `MinValueValidator`, `MaxValueValidator`, `MinLengthValidator`,
+`MaxLengthValidator` and `RegexValidator` are the bounds they were given. The
+model is the source of truth for `required`: a field must be given unless
+the model fills it (`default`, `auto_now`, an auto id) or excuses it (`blank`,
+`null`); what a serializer adds is that layer's word and is not read here.
+Value objects are the frozen dataclasses in `values.py`, their fields the
+annotations as written.
 
 **Event.** `events.py`, in either of the two ways a Django project says it. A
 dataclass with `name = "billing.InvoiceIssued"` is an event, its payload the
@@ -162,9 +182,24 @@ observable effects. Traversal is bounded and cycles are cut by symbol, so a
 recursive helper cannot make extraction recursive. ORM models from routed
 applications remain visible here even when the application has no unambiguous
 aggregate root. A URLConf may directly mount an arbitrarily named method of a
-plain class, such as `Planet.fetch`; that is still an HTTP flow root. When no
-decorator or conventional handler name proves one verb, the flow is retained
-but the route is omitted from inferred OpenAPI rather than guessed. An
+plain class, such as `Planet.fetch`, or a plain function; that is still an
+HTTP flow root, and its verb is read off what the code declares, in the order
+a reviewer would trust it: a decorator on the handler (`@action(methods=…)`,
+`@api_view`, `@require_http_methods([…])`, `@require_GET`, `@require_POST`,
+`@require_safe`, also through `method_decorator`), the same decorators on the
+class (`@method_decorator(…, name="dispatch")`), the class's
+`http_method_names` (less `HEAD`, `OPTIONS` and `TRACE`, which every route
+answers), a branch on `request.method` in the handler body, and last a project
+wrapper — a decorator or a function the handler hands `request` to — whose own
+body does one of those, followed a bounded number of levels deep. The first
+tier that speaks decides; a declaration listing several verbs makes one
+endpoint per verb, `planet_status` and `planet_status_patch`. When none of
+them speaks, the verb is not guessed: the route stays in `provides` with an
+empty `http.method`, the inferred OpenAPI document keeps the path as an item
+with no operations and `x-portolan-verb: unknown`, the flow is retained, and
+a diagnostic names the route. The merge never matches an outbound call
+against a route whose verb is unknown, so the link waits for a declaration
+rather than being confirmed by the path alone. An
 inherited DRF generic action has no local handler body, so
 its framework behaviour is reconstructed instead: list/retrieve read the
 model, create/update validate through the selected serializer and persist it,
@@ -267,8 +302,7 @@ The primary store is inferred from `DATABASES["default"]` when that setting is
 statically readable; `store` remains the override for settings assembled at
 runtime or for a catalog that needs a different stable slug. Every concrete,
 non-proxy model becomes a table even when its application has several possible
-aggregate roots: ambiguity limits the domain model, not the persistence
-schema. Fields from abstract model bases are copied into those tables
+aggregate roots: both the model group and persistence schema stay visible. Fields from abstract model bases are copied into those tables
 regardless of which model module sorts first. `DEFAULT_AUTO_FIELD` supplies
 implicit primary-key types. PostgreSQL `ArrayField` nesting and
 `MultiSelectField` storage are rendered as their database types; `to_field`
@@ -323,9 +357,8 @@ Everything else means what it means for `extract-ts`.
 
 These cases do not become facts in the fragment:
 
-- a domain aggregate for an application with no models, or with several and no
-  root among them named after it (its statically resolvable HTTP routes are
-  still included);
+- a domain aggregate for an application with no models (its statically
+  resolvable HTTP routes are still included);
 - a model that declares no fields;
 - an events module holding a class with no wire name, and a signal with no
   payload;

package/plugins/extract-django/choices.py

@@ -0,0 +1,47 @@
+"""The `Choices` classes a model keeps, read as the values the column holds.
+
+`class Status(models.TextChoices): DRAFT = "draft", "Draft"` says two things:
+the states a lifecycle moves between, and the values a `status` field may
+take. Both readers want the same table, member name to stored value, and
+neither wants the label.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Dict
+
+from source import assigned, bases, inner_class
+
+
+def is_choices(node: ast.AST) -> bool:
+    return isinstance(node, ast.ClassDef) and any(b.split(".")[-1].endswith("Choices") for b in bases(node))
+
+
+def choices_of(model, name: str) -> Dict[str, str]:
+    """A Choices class, as member name to the value stored in the column. Looked
+    up inside the model first, then among the module's own classes."""
+    node = inner_class(model.node, name)
+    if node is None:
+        for other in model.module.classes():
+            if other.name == name:
+                node = other
+                break
+    if node is None or not is_choices(node):
+        return {}
+    out = {}
+    for member, value, _ in assigned(node):
+        if isinstance(value, ast.Constant) and not isinstance(value.value, bool):
+            out[member] = str(value.value)
+        elif isinstance(value, ast.Tuple) and value.elts and isinstance(value.elts[0], ast.Constant):
+            out[member] = str(value.elts[0].value)
+    return out
+
+
+def choice_tables(model) -> Dict[str, Dict[str, str]]:
+    """Every Choices class in reach of the model, by class name."""
+    out = {}
+    for node in list(model.node.body) + list(model.module.tree.body):
+        if is_choices(node):
+            out[node.name] = choices_of(model, node.name)
+    return out

package/plugins/extract-django/domain.py

@@ -1,21 +1,22 @@
 """`models.py` read as the model.
 
-A Django application is one aggregate: the root is the model named after the
-application, the other models in it are its entities, and the frozen
-dataclasses in `values.py` are its value objects. Nothing is annotated for the
-catalog - the application is the claim, the same way a directory is the claim
-in `extract-ts`.
+A Django application groups its models. When a root is known, the group is
+an aggregate; otherwise it remains a model-group with no asserted boundary.
+Frozen dataclasses in `values.py` are its value objects. Ambiguity never hides
+the concrete models or requires configuration to browse them.
 """
 
 from __future__ import annotations
 
 import ast
+import json
 from dataclasses import dataclass, field as dc_field
 from typing import Dict, List, Optional
 
 import catalog
 from apps import App
 from ids import aggregate_id, block_id, pascal, singular, slug
+from rules import rules_of
 from source import (
     Module,
     Project,
@@ -90,7 +91,7 @@ class Aggregate:
     """One application, and the catalog object being built from it."""
 
     app: App
-    root: ModelDef
+    root: Optional[ModelDef]
     models: List[ModelDef]
     aggregate: Dict[str, object]
 
@@ -257,7 +258,7 @@ def root_of(app: App, models: List[ModelDef], named: Dict[str, str], b) -> Optio
         for m in concrete:
             if m.name == want:
                 return m
-        b.warn(app.rel, "aggregates names %s for %s, and no model there is called that" % (want, app.label))
+        b.warn(app.rel, "aggregates names %s for %s, and no model there is called that%s" % (want, app.label, aggregate_candidates(app, concrete)))
         return None
     for candidate in (pascal(singular(app.label)), pascal(app.label)):
         for m in concrete:
@@ -268,13 +269,20 @@ def root_of(app: App, models: List[ModelDef], named: Dict[str, str], b) -> Optio
     if not concrete:
         b.warn(app.rel, "no models in this application: nothing here to be an aggregate")
         return None
-    b.warn(
-        app.rel,
-        "no model called %s, and %d models to choose from: name the root in the aggregates option" % (pascal(singular(app.label)), len(concrete)),
-    )
     return None
 
 
+def aggregate_candidates(app: App, models: List[ModelDef]) -> str:
+    """Keep candidate evidence in the warning-only plugin protocol."""
+    return "; aggregate candidates: " + json.dumps({
+        "app": app.dotted,
+        "models": [
+            {"name": model.name, "path": model.module.rel, "line": model.node.lineno}
+            for model in sorted(models, key=lambda model: (model.name, model.module.rel))
+        ],
+    }, ensure_ascii=True)
+
+
 def read_aggregates(
     project: Project,
     applications: List[App],
@@ -289,14 +297,18 @@ def read_aggregates(
         if models is None:
             models = read_models(app)
         root = root_of(app, models, named, b)
-        if root is None:
-            continue
         concrete = [m for m in models if m.concrete]
-        ordered = [root] + [m for m in concrete if m is not root]
-        agg_slug = slug(root.name)
+        if not concrete:
+            continue
+        ordered = [root] + [m for m in concrete if m is not root] if root else concrete
+        # An application is a source grouping, not proof of a transactional
+        # boundary. Keep every model visible without inventing such a boundary.
+        agg_slug = slug(root.name) if root else "models-" + slug(app.dotted.replace(".", "-"))
         agg_id = aggregate_id(svc_id, agg_slug)
-        readme = app.readme or (ast.get_docstring(root.node, clean=True) or "").strip()
-        obj = catalog.aggregate(agg_id, agg_slug, root.name, readme, root.name)
+        readme = app.readme or ((ast.get_docstring(root.node, clean=True) or "").strip() if root else "")
+        obj = catalog.aggregate(agg_id, agg_slug, root.name if root else app.dotted, readme, root.name if root else "")
+        if root is None:
+            obj["kind"] = "model-group"
         for model in ordered:
             obj["entities"].append(
                 catalog.block(
@@ -304,7 +316,7 @@ def read_aggregates(
                     slug(model.name),
                     model.name,
                     doc(model.node),
-                    [catalog.field(f.name, f.type(), f.help()) for f in model.fields],
+                    [catalog.field(f.name, f.type(), f.help(), **rules_of(f, model)) for f in model.fields],
                 )
             )
         for module, node in value_objects(app):