@shortlink-org/portolan 0.2.3 → 0.3.0

package/plugin/schematest/schematest.go

@@ -0,0 +1,126 @@
+// Package schematest checks that a plugin's options schema still describes its
+// options struct.
+//
+// The schema is written by hand rather than reflected out of the struct,
+// because what makes it worth having is the prose: which slug a store expects,
+// whose proto package a peer answers for. None of that survives reflection.
+// What reflection is good for is the half nobody would notice going stale - a
+// field renamed, a field added, a schema left behind - so that is all this
+// does.
+package schematest
+
+import (
+	"encoding/json"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type document struct {
+	Type                 string                     `json:"type"`
+	AdditionalProperties *bool                      `json:"additionalProperties"`
+	Properties           map[string]json.RawMessage `json:"properties"`
+	Required             []string                   `json:"required"`
+}
+
+// Check reports every way the schema and the struct have come apart.
+//
+// options is a zero value of the plugin's options type; schema is the embedded
+// document it hands back when asked to describe itself.
+func Check(t *testing.T, schema []byte, options any) {
+	t.Helper()
+
+	var doc document
+	if err := json.Unmarshal(schema, &doc); err != nil {
+		t.Fatalf("options schema is not JSON: %v", err)
+	}
+
+	if doc.Type != "object" {
+		t.Errorf("options schema has type %q, want object", doc.Type)
+	}
+
+	// Without this an unknown key validates, and the misspelled option - the
+	// one error this whole mechanism exists to catch - goes through silently.
+	if doc.AdditionalProperties == nil || *doc.AdditionalProperties {
+		t.Error("options schema must set additionalProperties: false")
+	}
+
+	described := keys(doc.Properties)
+	declared := fields(reflect.TypeOf(options))
+
+	for _, name := range missing(declared, described) {
+		t.Errorf("option %q is in the struct but not in the schema", name)
+	}
+	for _, name := range missing(described, declared) {
+		t.Errorf("option %q is in the schema but not in the struct", name)
+	}
+
+	for _, name := range doc.Required {
+		if _, ok := doc.Properties[name]; !ok {
+			t.Errorf("option %q is required but not described", name)
+		}
+	}
+
+	// A property with nothing to say is a property the manifest schema will
+	// offer with no hint of what it means, which is where this started.
+	for name, raw := range doc.Properties {
+		var property struct {
+			Description string `json:"description"`
+		}
+		if err := json.Unmarshal(raw, &property); err != nil {
+			t.Errorf("option %q: %v", name, err)
+
+			continue
+		}
+		if strings.TrimSpace(property.Description) == "" {
+			t.Errorf("option %q has no description", name)
+		}
+	}
+}
+
+// fields are the json names of an options struct, which is the only shape this
+// takes: a plugin's options are a flat object read out of the manifest.
+func fields(t reflect.Type) []string {
+	var names []string
+
+	for i := 0; i < t.NumField(); i++ {
+		tag := t.Field(i).Tag.Get("json")
+		name, _, _ := strings.Cut(tag, ",")
+		if name == "" || name == "-" {
+			continue
+		}
+		names = append(names, name)
+	}
+
+	sort.Strings(names)
+
+	return names
+}
+
+func keys(m map[string]json.RawMessage) []string {
+	names := make([]string, 0, len(m))
+	for name := range m {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	return names
+}
+
+// missing is everything in a that is not in b.
+func missing(a, b []string) []string {
+	have := make(map[string]bool, len(b))
+	for _, name := range b {
+		have[name] = true
+	}
+
+	var gone []string
+	for _, name := range a {
+		if !have[name] {
+			gone = append(gone, name)
+		}
+	}
+
+	return gone
+}

package/plugins/README.md

@@ -54,7 +54,10 @@ Three obligations, and they are the whole of it:
    unsafe filename or invalid response fails the run. Non-fatal extraction
    notes go to stderr; there is no advisory response property a caller may
    accidentally ignore. A note that opens with `warning: ` is kept beside the
-   step in `.portolan/build-report.json` and listed on the Settings page.
+   step in `.portolan/build-report.json`. The Settings page classifies and
+   groups those notes by plugin, stable rule and severity. Typed CEL policies
+   in `portolan.json` can suppress reviewed diagnostics only with an explicit
+   reason; the host evaluates them and records the decision in the build report.
 
 The repository enforces those obligations with schema/field coverage tests,
 byte-for-byte permutation tests, generated-link and anchor checks, Mermaid
@@ -78,12 +81,14 @@ either be rendered or be explicitly acknowledged by the relevant exporter.
    `go:embed` and returned in the descriptor. `schematest.Check` in a test keeps
    it from drifting from the options struct: a field renamed on one side and not
    the other fails, and so does an option with no description.
-3. Build it. A built-in Go plugin is a library package with
+3. Build it. A sandboxed built-in Go plugin is a library package with
    `Serve(io.Reader, io.Writer) error`; add it to the map in
    `plugins/cmd/portolan-go/main.go`, and `plugins:build` in `package.json`
    puts it in `plugins/portolan-go.wasm` with the rest (a test keeps the map
-   and `portolan.json` in step). A plugin of your own is its own module:
-   `GOOS=wasip1 GOARCH=wasm go build`.
+   and `portolan.json` in step). A built-in that genuinely needs the Go
+   toolchain gets a small command under `plugins/cmd/` and is declared as a
+   `process`; `http-clients` is the example. A plugin of your own is its own
+   module: `GOOS=wasip1 GOARCH=wasm go build`.
 4. Declare it in `portolan.json`, under `plugins` (how to run it) and
    `generate` (what to run it on), then run `npm run schema` so the manifest
    schema learns its options.
@@ -179,10 +184,23 @@ the original collection layout for TypeScript, Rust, Java, or custom trees and
 may also point directly at one feature repository.
 
 `extract-river` is another independent enrichment for Go repositories. It
-joins a job argument's `Kind()` to `Client.Insert`/`InsertTx`, the selected
-queue, `Worker[Args].Work`, and `river.AddWorker`. The result is a work-queue
-channel plus a two-hop enqueue/dispatch flow, with payload fields and source
-lines. It does not need aggregates and does not treat a job as a domain event.
+joins a job argument's `Kind()` to `Client.Insert`/`InsertTx` and the
+`InsertMany*` batches, the selected queue, `Worker[Args].Work`, and
+`river.AddWorker`. The result is a work-queue channel plus a two-hop
+enqueue/dispatch flow, with payload fields and source lines. It does not need
+aggregates and does not treat a job as a domain event. The job type is
+followed through locals, constructors' results and parameters up to the
+callers, so an `Enqueue(ctx, args river.JobArgs, opts)` wrapper is read once
+per concrete job passed to it, and a worker registered as
+`river.AddWorker(workers, NewSendWorker(deps))` is registered. The queue is
+the `InsertOpts.Queue` at the call (a literal, a constant, a config `default:`
+tag, or what the callers pass), else the args type's own `InsertOpts()`, else
+`default`. What no Insert in the tree feeds is not dropped: a registered
+worker's queue is the one its type chooses or the one queue `river.Config`
+lists, and with several and no choice the worker is kept as a flow whose
+receive is unresolved. The diagnostics keep the two cases apart - an Insert
+whose job type or queue the reader could not follow is said at the call, a
+worker with no Insert in the tree is said at the worker.
 
 `extract-redis` finds runtime construction of go-redis, rueidis and redigo
 clients in non-test Go source. That source evidence adds a service-owned Redis
@@ -193,16 +211,27 @@ key patterns with their read/write/delete use, TTL, value type and source. The
 patterns remain Redis keyspaces rather than being presented as SQL tables.
 
 `extract-watermill` reads Watermill `Router.AddHandler` and
-`AddNoPublisherHandler` registrations. It resolves literal and constant topics,
-plus defaults on env-config structs, follows direct `Publisher.Publish` calls
-and one-hop publishing helpers, and traces JSON marshal/unmarshal values back to
-their Go payload structs. It carries enclosing `if`/`else` conditions and early
-returns through the handler's control flow: proven alternatives become one
-catalog `alt`; publications whose relationship cannot be proven remain separate
-possible routes. The channels merge normally with AsyncAPI declarations by address. Generic
-`NewEventHandler[T]` and `NewCommandHandler[T]` registrations on Watermill CQRS
-processors are also extracted; fixed topic generators and the standard
-event/command-name generator form are resolved from source.
+`AddNoPublisherHandler` registrations, and `Subscriber.Subscribe` calls made
+without a router. It resolves literal and constant topics - typed constants
+through `string(...)`, constants concatenated with `+`, single-return
+helpers - plus defaults on env-config structs, nested (`cfg.Kafka.Orders`) or
+not; a topic, a name or a handler that a registering function takes as a
+parameter is filled in once per caller, so a `handle(r, name, topic, fn)`
+wrapper yields one handler per call. The handler value may be a function
+literal, a function or method of the tree (`h.OnOrder`, `handlers.OnShipped`)
+or a constructor returning a literal. It follows direct `Publisher.Publish`
+calls and one-hop publishing helpers, records what the service publishes
+outside any handler as a `send` on the topic, and traces JSON marshal/unmarshal
+values back to their Go payload structs. It carries enclosing `if`/`else`
+conditions and early returns through the handler's control flow: proven
+alternatives become one catalog `alt`; publications whose relationship cannot
+be proven remain separate possible routes. A handler whose topic does not
+resolve is kept, with its receive step unresolved and no channel claimed, and
+named in a diagnostic. The channels merge normally with AsyncAPI declarations
+by address. Generic `NewEventHandler[T]` and `NewCommandHandler[T]`
+registrations on Watermill CQRS processors are also extracted; fixed topic
+generators and the standard event/command-name generator form are resolved
+from source.
 
 `extract-go-nats` reads nats.go and JetStream calls into the subjects a service
 listens on and publishes to. A call is known by the type it is made on -
@@ -260,16 +289,19 @@ literals, direct assignments, or setters. A standalone flow says whether no
 source caller exists or callers exist but no inbound/asynchronous root was
 proved, so the UI exposes the missing evidence instead of implying a complete
 business path.
-When a provider branch still ends before its transport, the extractor loads
-the module with `go/packages`, builds SSA, and uses `x/tools` VTA to resolve
+When a provider branch still ends before its transport, the extractor runs as
+a workspace-local native sidecar, loads the module with `go/packages`, builds
+SSA, and uses `x/tools` VTA to resolve
 calls through interface parameters, function values, return values, and
 interface-typed struct fields. Typed edges are followed only after a concrete
 factory branch is selected: applying context-insensitive VTA to a shared
 dispatcher would otherwise attach every request implementation to every
 endpoint. Factory conditions and HTTP/SOAP meaning continue to come from the
-source extractor. Module loading is read-only and bounded; unavailable private
-dependencies, type errors, or a timeout produce a warning and retain the
-syntax-only result rather than failing generation.
+source extractor. The sidecar is built from the Portolan package through the
+project's Go toolchain and runs with the project as its working directory.
+Module loading is read-only and bounded; unavailable private dependencies,
+type errors, or a timeout produce a warning and retain the syntax-only result
+rather than failing generation.
 Routes without a provider factory are also joined to their outbound calls,
 including handlers invoked from closures and methods on locally constructed
 values. A Swagger `@Router` annotation is medium-confidence root evidence for
@@ -454,9 +486,10 @@ far side.
 The demo estate's org-wide and context-wide records live in `data/adr`, and are
 read by a step that points at that directory with a glob of its own. Root
 `docs/` is where `gen-markdown` writes, so nothing hand-written can live there.
-`in` is the directory of records rather than `data` itself: a step's fragment is
-only left out of its own stamp when the output is *inside* the input root, and
-`in: data` with `out: data` would be stamped from the file it writes.
+`in` is the directory of records rather than `data` itself: what `gen --check`
+lists as changed inputs is the root less the output directories inside it, and
+`in: data` with `out: data` would list the file the step writes among the
+reasons it was rewritten.
 
 ```json
 {
@@ -775,9 +808,9 @@ enforces: a team that owns a directory is a team that gets the pull request.
 ```
 
 Point `in` at the directory the file is in, not at the repository root: the
-host dates a fragment from the last commit to touch the step's input, and the
-subject of this one is the `CODEOWNERS` file. Rooted at the repository, it
-would be restamped by every commit ever made. Left with no `file`, the three
+subject of this step is the `CODEOWNERS` file, and `gen --check` explains a
+changed fragment by what moved under the step's input. Rooted at the
+repository, every commit ever made would be named. Left with no `file`, the three
 places a forge looks are tried in order - `CODEOWNERS`, `.github/CODEOWNERS`,
 `docs/CODEOWNERS` - and a `file` that names something absent fails the run,
 because answering "nobody owns anything" to a typo is only noticed a month
@@ -822,21 +855,23 @@ the forge looks.
 `wasm` is the default and should stay that way. The module gets no network, no
 environment and no way to start a process. A generator gets no filesystem
 either. An extract or verify step gets the workspace preopened as `/`
-(portolan.0006), which is how the built-in Go extractors read a tree without a
-Go toolchain on the machine: every one of them, and the three generators, is
-the single module `plugins/portolan-go.wasm`, which answers to the plugin name
-the host passes as `argv[0]`. WASI preopens read-write, so an extractor is
+(portolan.0006), which is how syntax-only built-in Go extractors read a tree
+without a Go toolchain on the machine: those extractors and the three generators
+are the single module `plugins/portolan-go.wasm`, which answers to the plugin
+name the host passes as `argv[0]`. WASI preopens read-write, so an extractor is
 trusted not to write the tree it reads, the same trust a process plugin has
 today; a `sha256` pins that trust to a build.
 
-`process` is the escape hatch for a plugin that needs a toolchain: the Rust,
-Java, Python and TypeScript extractors run in their own runtimes, and
-`fetch-bsr` still talks to its registry from Go. It gets the same protocol
+`process` is the escape hatch for a plugin that needs a toolchain: the typed Go
+HTTP client analyzer and the Rust, Java, Python and TypeScript extractors run in
+their own runtimes. It gets the same protocol
 and none of the sandbox, which is the trade being made and the reason it is
 not the default. It declares `command` and an `args` array; the host never
-feeds a command string through a shell. A built-in Go plugin that still runs
-as a process is the same code reached as
-`go run ./plugins/cmd/portolan-go <name>`.
+feeds a command string through a shell. For a built-in declared as `go run`,
+the adapter compiles a workspace-local native sidecar from the package and
+then runs it with the scanned workspace as its current directory. This keeps
+module resolution in Portolan's shipped source and project loading in the
+project being analyzed.
 
 `host` is for Portolan's own code that needs what only the host has - a git
 binary, a socket - and so runs inside the host process (portolan.0008):
@@ -859,12 +894,18 @@ written.
 `fetch-git` is `fetch-bsr` for a repository rather than a registry, and it
 lives by the same four rules. A pin is a repository, a commit and the paths
 actually read; the step fetches exactly those directories at exactly that
-commit and hands them back as files, so the host writes them into the tree
+commit and hands their text files back, so the host writes them into the tree
 beside a `git.lock.json` naming the commit and the digest of every file. The
 paths inside the copy are the repository's own, which is the point: the
 extract step that follows points its `in` at the vendored service and reads
 it exactly as it would read that service's checkout.
 
+Binary files are not part of the extractor input. Known binary extensions are
+discarded before their blobs are read; files without a known extension are
+sniffed for NUL bytes and invalid UTF-8 before the response is assembled. The
+lock records only their path, byte size and skip reason, never Base64 content,
+so online fetch and offline replay produce the same bounded text-only copy.
+
 It runs inside the host (`scripts/host-plugins/fetch-git.mjs`,
 portolan.0008) rather than as a module, because it needs a git binary and a
 socket, and a manifest names it with `host` rather than `wasm` or `process`.
@@ -919,11 +960,12 @@ Nothing else can say it. A service says which repository it lives in, and an
 extractor reads a directory as a pure function of what is on disk; neither has
 any idea which commit somebody fetched. Without that line, every source path
 of every vendored service is dead text on the page - the file and the line are
-known, and there is nowhere to send a reader - and every fragment read out of
-the copy is stamped with the commit that VENDORED it, so the service looks
-fresh whenever the fetch is re-run and unchanged when its own repository
-moves. With it, `sourceHref` links the line at the commit it was read at and
-`stampFor` dates the fragment from the code rather than the vendoring.
+known, and there is nowhere to send a reader. With it, `sourceHref` links the
+line at the commit it was read at. The fragments read out of the copy are
+dated, like every other source, by the commit of THIS repository that last
+changed them (portolan.0010) - which is the fetch that brought the change in,
+and is what "how fresh is this" means to the estate that vendored it; the pin
+is what says which upstream commit that was.
 
 One more line is needed for the app itself: `SOURCE_GLOBS` in `src/data.ts`,
 where the same patterns are written out a second time because
@@ -1020,7 +1062,8 @@ workflow already does.
 
 Four rules govern what happens when a fetch does not:
 
-1. Fetch succeeded → the fetched files and a regenerated lock.
+1. Fetch succeeded → the fetched text files, binary-skip metadata and a
+   regenerated lock.
 2. Skipped or failed, cache complete and matching its digests → the cached files
    byte-identically, plus a warning. Output unchanged, so `--check` stays clean.
 3. Failed **and** no usable cache → a non-zero exit, never a short file list. The
@@ -1142,6 +1185,11 @@ live in another estate — would be the wrong end of the trade.
 service declares — the address the broker knows, and each message on it with the
 direction it travels. What it does **not** answer with is events.
 
+A message's `contentType`, or the document's `defaultContentType` when the
+message leaves it out, is kept as the exact declared media type. MessagePack
+media types are additionally normalized to `encoding: msgpack`, so source and
+contract extractors can be compared without depending on one MIME spelling.
+
 That looks like a gap and is a boundary. `Event.id` is
 `<service>.<aggregate>.<Name>`, and an AsyncAPI document knows the message on the
 wire, not the aggregate that raised it. An extractor that guessed would either
@@ -1197,3 +1245,23 @@ it, the call before the decorator before `task_routes` before the default,
 and `transaction.on_commit(...)` around an enqueue is a note on the step,
 which is the one fact about *when* a message leaves that the code states
 plainly.
+
+### HTTP destination provenance
+
+`extract-http-clients` emits structured `destination` evidence on HTTP consumes
+and flow steps: the request call site and endpoint expression, local path,
+base URL expression, config field and environment variable, source locations,
+and a full path when source proves the join. Functional options that assign a
+URL field to a returned client are followed through adapter constructors.
+Bindings belong to the adapter's client field; conflicting construction sites
+remain unresolved instead of sharing another client's settings.
+
+A Go `default` struct tag is recorded as `config-default`, not as the effective
+runtime configuration. For example, `WithBaseURL(cfg.SettingAddr)` with
+`default:"http://localhost:8000/settings"` and a concatenated
+`/get-admin-settings` yields `/settings/get-admin-settings`. The merge matches
+that full path exactly and never falls back to a suffix if it is absent.
+Legacy suffix matches remain explicitly labeled `unique-suffix` in the evidence
+shown in RPC step details. Later runtime URL modifiers are listed separately;
+the recovered full path describes the static join. Unreadable options may
+leave only the local route available.

package/plugins/cmd/portolan-http-clients/main.go

@@ -0,0 +1,19 @@
+// Command portolan-http-clients is the native sidecar for typed Go call-graph
+// analysis. It intentionally does not compile for WASI: go/packages needs the
+// project Go toolchain to load build tags and dependencies before SSA/VTA can
+// resolve interface calls.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	extracthttpclients "github.com/shortlink-org/portolan/plugins/extract-http-clients"
+)
+
+func main() {
+	if err := extracthttpclients.Serve(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-http-clients:", err)
+		os.Exit(1)
+	}
+}

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-django/README.md

@@ -39,15 +39,24 @@ 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
@@ -162,9 +171,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 +291,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 +346,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/domain.py

@@ -1,15 +1,15 @@
 """`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
 
@@ -90,7 +90,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 +257,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 +268,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 +296,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(