# Cicadel batteries

This is the long-term capability inventory and support policy. It records the bigger picture before implementation, including features we deliberately will not build. It takes precedence over broad completion claims in the original [implementation plan](https://cicadel.fauzaanu.com/en/0.2.7/sources/PLAN.md). A working helper, dependency wrapper, or example is a foundation—not a complete battery.

Baseline: Django **6.1** documentation, reviewed **2026-10-29**. The official stable documentation resolved to this version during review. This inventory groups public capabilities into maintainable units rather than listing every API symbol. Review it against Django's [contents](https://docs.djangoproject.com/en/6.1/contents/), [topic index](https://docs.djangoproject.com/en/6.1/topics/), [reference](https://docs.djangoproject.com/en/6.1/ref/), and [contrib inventory](https://docs.djangoproject.com/en/6.1/ref/contrib/) when updating the baseline. Django ecosystem packages are distinguished from Django itself below.

## Product boundaries

- Keep the core small and familiar: project/app conventions, settings, URLs, model-centered data access, complete migration workflows, forms, templates, security, and development tools.
- **Default styling:** Tailwind CSS has first-party support through the component build/check workflow. Generated apps use it by default; alternative CSS libraries remain supported. See [Tailwind](https://cicadel.fauzaanu.com/en/0.2.7/howto/tailwind/index.md).
- **Component-first UI:** adopt React-style composition and Django Cotton-inspired reusable components with props, children and named slots. Django’s template language/inheritance model is not the UI foundation. See [the component engine design](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md).
- Use mature Go libraries where appropriate. Cicadel still owns the consistency, documentation, failure behavior, and tests of every battery it promises.
- **No native internationalization or localization.** Translation catalogs, language negotiation, localized URLs, locale-specific formatting, and humanization belong to third-party packages. The earlier experimental `locale` package has been removed. Unicode text, accessible HTML, correct timestamps, and time-zone-safe storage remain requirements.
- **No first-party GeoDjango equivalent.** Spatial models, GIS database adapters, geometry operations, map widgets, GIS serializers/GeoJSON tooling, and geographic data import/export belong outside the supported core. Ordinary JSON may contain geographic data; that does not create a GIS support commitment.
- **Current priority: a ready, released core (owner decision 2026-11-10).** Close the open core gaps in the [README readiness checklist](https://cicadel.fauzaanu.com/en/0.2.7/sources/README.md#readiness-checklist) first and release each one. Administration and other contrib extras are not required for readiness. Independent security review and external beta adoption are not release gates. Develop new batteries as installable apps through the public contract. First-party capabilities become core defaults through these installable contracts. Build the package integration system so excluded capabilities can be supplied externally. Use Go modules for distribution; do not build a new dependency resolver or require runtime-loaded binaries.
- Feature selection is a product decision, not a claim that we have measured what most Django users use. Browser/AI translation may help some applications, but it does not replace every server-side localization requirement; those requirements remain addressable through packages.
- This is a long-term backlog with dependency order and complexity estimates, not calendar durations or a promise to reproduce all of Django.

## How to read and update this tracker

**Target:** `Core` = first-party supported foundation; `Package` = first-party supported, core battery packaged as an installable module; `Third-party` = extension route only, no first-party implementation commitment; `No port` = Django-specific mechanism we intentionally replace with Go conventions. Core/Package means a decision to fully support the stated Cicadel scope eventually, not current readiness or Django API compatibility.

**Current:** `Partial` = repository code covers part of the battery; `Absent` = not implemented; `Dependency` = available directly through Go or an upstream library, not a verified Cicadel battery; `Excluded` = intentionally outside first-party scope. No row is marked complete merely because its underlying library has that feature. Accounts, formsets, migrations and query generation have independent modules released together from v0.1.0 under the [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#stability-guarantee); further package extraction remains work.

**Effort:** `S` = comparatively small and contained; `M` = several contracts/integrations; `L` = substantial cross-cutting work; `XL` = major subsystem with long-term compatibility obligations. These are engineering judgments, not time estimates. Security-sensitive work still needs careful testing even if labeled S.

A selected battery becomes **Complete** only when its documented scope works end to end in a newly generated application, default configuration is usable, errors and recovery are defined, public APIs and upgrades are documented, and conformance tests pass for every claimed provider/version. Record the evidence and remaining limitations alongside the row. Implementation tasks can be checked off without declaring the parent battery complete.

## Project conventions, packages, and developer tools

Django references: [applications](https://docs.djangoproject.com/en/6.1/ref/applications/), [management commands](https://docs.djangoproject.com/en/6.1/ref/django-admin/), [system checks](https://docs.djangoproject.com/en/6.1/topics/checks/), and [reusable apps](https://docs.djangoproject.com/en/6.1/intro/reusable-apps/).

| ID | Battery | Target | Current | Effort | Completion gap / intended scope |
| --- | --- | --- | --- | --- | --- |
| DEV-01 | Project and app scaffolding | Core | Complete | M | Validated project/app scaffolds, generated executable invocation, documented model layouts and non-overwriting upgrade workflow; [foundation evidence](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md). |
| DEV-02 | Settings and environment configuration | Core | Complete | M | Typed constructor options, every operational environment override, isolated lookups, copied hosts and redacted diagnostics; [settings contract](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md#configuration-and-registration). |
| DEV-03 | App registry, dependencies and lifecycle | Core | Complete | L | Explicit dependency-ordered startup, reverse/partial-failure cleanup, immutable descriptors, resource ownership and readiness; [foundation contract](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md#configuration-and-registration). |
| DEV-04 | Reusable app/package installation | Core | Partial | XL | First working contract ships: Go-module install, manifests, compatibility checks, commands/resources/migrations and lifecycle. Typed component, model, static-file, package-settings and event contracts are now verified; render-helper contracts and module extraction remain. See PKG checklist and installable-app guide. |
| DEV-05 | Built-in and custom management commands | Core | Complete | M | Unified discovery, per-command help, custom flags, namespaced commands and process exit statuses tested in generated executables; [command contract](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md#management-commands). |
| DEV-06 | Extensible system/deployment checks | Core | Complete | M | Namespaced severity diagnostics, deployment-only checks, JSON output and failure thresholds; [check contract](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md#structured-system-and-deployment-checks). |
| DEV-07 | Development server, reload and diagnostics | Core | Complete | M | Content-hash watching, component/CSS builds, failed-build recovery, bounded shutdown, port-conflict diagnostics and generated component reload; [development contract](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md#development-rebuild-and-restart). |
| DEV-08 | Database shell and model/schema inspection commands | Package | Absent | M | Explicit provider-aware diagnostics and command availability; no secret leakage. |
| DEV-09 | Interactive Python model shell | No port | Excluded | — | Use Go programs, tests and supported inspection commands; no embedded Python/Go interpreter commitment. |
| DEV-10 | Django class inheritance/decorators/import magic | No port | Excluded | — | Deliver equivalent workflows through functions, interfaces and explicit composition. |

Evidence: [foundation completion](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md), [application.go](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/application.go), [settings](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/settings/settings.go), [management](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/management/management.go), [scaffold](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/scaffold.go). The [installable-app foundation](https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md) implements dependency-ordered startup/cleanup; the full package battery remains partial.

## Models, queries, databases, and migrations

**Database scope: PostgreSQL only.** SQLite, MySQL, MariaDB and other backends are excluded from the framework and this roadmap. Do not implement or test provider parity. This supersedes earlier multi-provider plans; see [AGENTS.md](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/AGENTS.md).

Django references: [models/databases](https://docs.djangoproject.com/en/6.1/topics/db/), [database backends](https://docs.djangoproject.com/en/6.1/ref/databases/), [migrations](https://docs.djangoproject.com/en/6.1/topics/migrations/), [multiple databases](https://docs.djangoproject.com/en/6.1/topics/db/multi-db/), [fixtures](https://docs.djangoproject.com/en/6.1/topics/db/fixtures/), and [serialization](https://docs.djangoproject.com/en/6.1/topics/serialization/).

| ID | Battery | Target | Current | Effort | Completion gap / intended scope |
| --- | --- | --- | --- | --- | --- |
| DB-01 | Model fields, relations, constraints, indexes | Core | Partial | L | Supported GORM mapping contract, validation, relationships/deletion behavior, model metadata and provider tests. |
| DB-02 | Query API, eager loading, aggregation, expressions, bulk operations | Core | Partial | L | Keep native GORM access; document/test supported query behavior, cancellation, errors and common performance pitfalls. |
| DB-03 | Transactions, savepoints and post-commit hooks | Core | Complete | L | `database.Atomic` (savepoints when nested) and `database.OnCommit`; model forms and admin save through it. Evidence: PostgreSQL tests in `database/transaction_test.go` (order, rollback, panic, savepoints, cancellation, hook failures, concurrent `-race`), `forms/model` hook tests, generated-consumer `internal/scaffold/commit_hooks_test.go`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/transactions/index.md). Formset saves run through `Atomic` from v0.2.4. |
| DB-04 | Connection lifecycle, pools and database errors | Core | Partial | M | Consistent provider setup, bounded failures, health, cleanup and error mapping. |
| DB-05 | PostgreSQL provider | Core | Partial | L | Current sole integrated provider; complete migration/type/constraint conformance before a full-support claim. |
| DB-06 | SQLite provider | Excluded | Excluded | — | PostgreSQL-only framework; not an implementation target. |
| DB-07 | MySQL provider | Excluded | Excluded | — | PostgreSQL-only framework; not an implementation target. |
| DB-08 | MariaDB compatibility | Excluded | Excluded | — | PostgreSQL-only framework; not an implementation target. |
| DB-09 | Oracle and additional backends | Third-party | Excluded | — | Provider extension contract; no first-party Oracle promise. |
| DB-10 | Multiple database aliases and query/migration routing | Package | Absent | L | Explicit selection, checks and migration placement; no distributed transactions or cross-database foreign-key promise. |
| DB-11 | Custom fields, managers/query helpers, raw SQL escape hatches | Core | Dependency | L | Document extension metadata, serialization, parameterization and migration participation. |
| DB-12 | Composite keys, inheritance/proxy-style model patterns | Package | Dependency | L | Test deliberate Go equivalents and their admin/forms/migration limits; no Python inheritance emulation. |
| DB-13 | Legacy database introspection (`inspectdb` workflow) | Package | Absent | L | Generate reviewable model declarations, preserve unmapped features and report ambiguities. |
| DB-14 | Fixtures, load/dump, natural identifiers and initial data | Package | Absent | L | Dependency ordering, stable references, transactions, validation and excluded secrets. |
| DB-15 | Backend-specific fields, indexes and search | Package | Dependency | L | PostgreSQL-specific features need explicit migration semantics and verified support. |
| DB-16 | Query instrumentation and optimization diagnostics | Core | Partial | M | Query counts/timing and safe diagnostics; general HTTP logging is not database instrumentation. |
| DB-17 | Tablespace placement | Third-party | Excluded | — | Provider/operations extension, not core configuration. |
| MIG-01 | Model changes → generated migrations (`makemigrations`) | Core | Partial | XL | The core `contrib/migrations` module reads registered GORM models and generates immutable PostgreSQL history, with explicit rename/removal/conversion declarations. See its supported operation matrix. |
| MIG-02 | Apply, inspect, plan and reverse migrations | Core | Partial | XL | Checksum-aware runner supplies execution, status, dependency plans, SQL preview, target rollback and schema verification. |
| MIG-03 | Cross-app migration dependencies and branch merging | Core | Partial | XL | Implemented version-level graph, pinned cross-app references, conflict diagnosis and explicit compatible merges. |
| MIG-04 | Historical model state and data migrations | Core | Partial | XL | Immutable historical snapshots and recorded schema/data SQL replay independently of current models. |
| MIG-05 | Migration squashing, replacement and upgrades | Core | Partial | XL | Verified replacement bundles support fresh and partially applied histories; originals must be retained. |
| MIG-06 | Schema-editor/provider capability contract | Core | Partial | XL | Versioned PostgreSQL renderer and capability validation; transactional DDL and explicit concurrent-index recovery are tested. |

Evidence: [database integration](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/database/database.go), [SQL migration runner](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/contrib/migrations/runner.go), [PostgreSQL tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/database/database_test.go). GORM capabilities and Goose execution do not establish Django-style migration completeness.

## HTTP, templates, forms, and files

Django references: [URL dispatch](https://docs.djangoproject.com/en/6.1/topics/http/urls/), [requests/responses](https://docs.djangoproject.com/en/6.1/ref/request-response/), [middleware](https://docs.djangoproject.com/en/6.1/topics/http/middleware/), [generic views](https://docs.djangoproject.com/en/6.1/topics/class-based-views/), [templates](https://docs.djangoproject.com/en/6.1/topics/templates/), [forms](https://docs.djangoproject.com/en/6.1/topics/forms/), [model forms](https://docs.djangoproject.com/en/6.1/topics/forms/modelforms/), [formsets](https://docs.djangoproject.com/en/6.1/topics/forms/formsets/), [uploads](https://docs.djangoproject.com/en/6.1/topics/http/file-uploads/), and [staticfiles](https://docs.djangoproject.com/en/6.1/ref/contrib/staticfiles/).

| ID | Battery | Target | Current | Effort | Completion gap / intended scope |
| --- | --- | --- | --- | --- | --- |
| HTTP-01 | URL inclusion, names, reversal and parameter conversion | Core | Partial | M | Existing single-segment routing; complete converter/error/mount contracts and URL helper integration. |
| HTTP-02 | Request parsing, responses, cookies and shortcuts | Core | Partial | M | Stable parsing/error contracts, streaming/files, content negotiation where promised and response tests. |
| HTTP-03 | Middleware and request lifecycle | Core | Partial | M | Ordering, error handling, context ownership and streaming-compatible composition. v0.2.7 (unreleased on `main`): `errorpages.Middleware` renders HTML pages for plain-text 4xx/5xx responses (router 404/405, `http.Error`, CSRF) and recovers panics as a 500 page with a report hook; `bodylimit` makes `MaxBodyBytes` a per-request default that routes raise or lower ([error pages](https://cicadel.fauzaanu.com/en/0.2.7/howto/error-pages/index.md), [request limits](https://cicadel.fauzaanu.com/en/0.2.7/howto/request-limits/index.md)). |
| HTTP-04 | Reusable list/detail/create/update/delete view helpers | Package | Absent | M | Go composition with forms, pagination and object-level permission checks. |
| HTTP-05 | Conditional responses, ETags, modified dates and caching headers | Core | Dependency | M | Consistent helpers and behavior tests; standard-library availability alone is not integration. |
| HTTP-06 | Compression and common redirect/slash middleware | Package | Dependency | M | Explicit ordering, cache variation and security-sensitive compression defaults. |
| HTTP-07 | Async request handling and streaming | Core | Dependency | L | Go concurrency/cancellation equivalents; no WSGI/ASGI compatibility promise. |
| TPL-01 | UI loading, namespaces, overrides and layout composition | Core | Complete | L | Typed namespaces, explicit compatible project overrides and layout composition; [verified scope](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md). |
| TPL-02 | Context and rendering extensibility (Django counterpart: processors/tags/filters) | Core | Complete | L | Explicit typed props/dependencies and Go helpers; no implicit context processors or Django tags/filters. [Evidence](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/component-verification.md). |
| TPL-03 | Deferred/template responses and fragment rendering | Package | Absent | M | Middleware-safe rendering lifecycle and buffered/streamed behavior. |
| TPL-04 | Component engine: props, children, slots and isolated composition | Core | Complete | XL | Pinned parser/IR, Go type checking, explicit children/slots, diagnostics and bounded safe server rendering. [Scope/evidence](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md). |
| TPL-05 | Reusable component libraries and application integration | Core | Complete | L | Versioned library exports, overrides/assets, starter/articles/admin conversion and independent generated-host installation. [Evidence](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/component-verification.md). |
| FORM-01 | Typed fields, validators, binding, widgets and accessible errors | Core | Complete | L | Standalone typed fields, reusable/cross-field validators, immutable binding, accessible widgets and generated-consumer verification. See [completed forms contract](https://cicadel.fauzaanu.com/en/0.2.7/topics/forms-completion/index.md). |
| FORM-02 | Model-derived forms and persistence | Core | Complete | L | Explicit GORM field allowlists, typed binding, authorized locked updates, scoped foreign keys, constraint errors and transactional hooks. See [contract and acceptance evidence](https://cicadel.fauzaanu.com/en/0.2.7/topics/model-forms/index.md); inline collections are provided by FORM-03. |
| FORM-03 | Formsets and inline related-object editing | Package | Complete | L | Core `contrib/formsets`: bounded integer-key collections, explicit identity/deletion, scoped inline ownership, parent locking, cross-row validation and atomic saves. See [contract and tests](https://cicadel.fauzaanu.com/en/0.2.7/ref/formsets/index.md); nested/automatic UI editing is excluded. |
| FILE-01 | Upload parsing, file fields and storage integration | Core | Complete | L | Bounded multipart parsing, required/clear fields, content validation, random storage keys, compensating cleanup, model persistence and multipart CSRF. See [lifecycle contract](https://cicadel.fauzaanu.com/en/0.2.7/topics/forms-completion/index.md#file-fields-and-persistence). |
| FILE-02 | Local storage and replaceable remote storage | Core | Partial | M | Backend errors, collision policy, read/write/delete/URL contracts; signed URLs currently require a caller-provided signer. |
| FILE-03 | Static discovery, collection, hashed manifests and development serving | Package | Partial | L | `App.Static` discovery, app-namespaced serving, content-hashed manifest URLs, immutable/revalidated caching, CDN `StaticURL` and offline `collectstatic` are implemented and verified in generated consumers; see [static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md). CSS `url()` rewriting, precompressed variants and htmx runtime consolidation remain. |
| FILE-04 | Image fields and validation | Package | Absent | M | Format/dimension checks and safe decoding through established libraries, not an image editor. |

Evidence: [urls](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/urls/urls.go), [templates](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/templates/templates.go), [forms](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/forms/forms.go), [response](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/response/response.go), [storage](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/storage/storage.go), [static](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/static/static.go).

## Authentication, security, sessions, and administration

Django references: [authentication](https://docs.djangoproject.com/en/6.1/topics/auth/), [default auth workflows](https://docs.djangoproject.com/en/6.1/topics/auth/default/), [custom authentication](https://docs.djangoproject.com/en/6.1/topics/auth/customizing/), [sessions](https://docs.djangoproject.com/en/6.1/topics/http/sessions/), [security](https://docs.djangoproject.com/en/6.1/topics/security/), [signing](https://docs.djangoproject.com/en/6.1/topics/signing/), and [admin](https://docs.djangoproject.com/en/6.1/ref/contrib/admin/).

| ID | Battery | Target | Current | Effort | Completion gap / intended scope |
| --- | --- | --- | --- | --- | --- |
| AUTH-01 | Users, authentication backends and current-user context | Package | Partial | L | Reusable PostgreSQL users, explicit credential backend, disabled-user enforcement and current-user middleware in [accounts](https://cicadel.fauzaanu.com/en/0.2.7/ref/accounts/index.md). |
| AUTH-02 | Password hashing, validation and upgrades | Package | Partial | L | Password policy hooks, bounded bcrypt input/cost and compare-and-swap rehash upgrades in accounts; PostgreSQL workflow tests cover upgrades. |
| AUTH-03 | Login/logout, password change/reset and session revocation | Package | Partial | L | Accounts service and JSON login/logout, password change/reset, injected recovery delivery, single-use tokens and revocation implemented. Browser HTML pages, cookie/CSRF integration and an accounts starter now ship; public registration/verification and admin integration remain application or later-package work. |
| AUTH-04 | Groups, permissions and authorization | Package | Partial | L | Persisted groups, memberships and exact model/action permissions in accounts; object access remains an explicit host policy with no implicit bypass. |
| AUTH-05 | Session API, lifecycle, cleanup and store choices | Core | Partial | L | Accounts provides PostgreSQL bearer sessions, absolute/idle lifetime configuration, revocation and accounts:cleanup. Reusable SCS browser bridging now resolves account revocation on every request; PostgreSQL browser sessions have an additive package migration. |
| SEC-01 | CSRF protection | Core | Partial | L | Session token protection exists; full form/AJAX/upload integration, origins/proxies and documented failure behavior. v0.2.7 (unreleased): `layout.Props.CSRFToken` sends the token as `X-CSRF-Token` on htmx requests; CSRF failures get an HTML page. Plain multipart forms under `Browser.Middleware` still need the header or `upload.Middleware` outside CSRF. |
| SEC-02 | Escaping, safe SQL, host/redirect validation and input limits | Core | Partial | L | Existing primitives; enforce their integration and test escape hatches across supported workflows. v0.2.7 (unreleased): `response.LocalPath` also rejects whitespace and control characters (tab/newline open redirects); accounts sign-in validates `next` the same way. |
| SEC-03 | Security middleware and deployment checks | Core | Complete | L | v0.2.1: HSTS, HTTPS redirect, trusted-proxy X-Forwarded-For/Proto, default CSP, nosniff, referrer and framing headers, deployment checks. Guide: docs/security-headers.md. |
| SEC-04 | Cryptographic signing, timestamped tokens and key rotation | Core | Complete | M | v0.2.2: `signing` package with HMAC-SHA256 per-purpose derived keys, issue timestamps and max-age expiry, clock-skew bound, typed JSON payloads, `SecretKey`/`SecretKeyFallbacks` rotation, request-context and `Application.Signer` access, `check --deploy` warning, `cicadel secretkey`; unit, fuzz, application and generated-consumer tests. Guide: docs/signing.md. Encrypted (confidential) tokens are out of scope. |
| ADMIN-01 | Model registration, CRUD and permission-safe forms | Package | Partial | XL | CRUD now uses shared model forms, revisions and atomic inline formsets; broader administration/account integration remains separately tracked. |
| ADMIN-02 | Search, filters, ordering, pagination and actions | Package | Absent | L | Safe bounded queries, permission-aware actions and configurable list behavior. |
| ADMIN-03 | Relations, inlines, widgets and customization | Package | Partial | XL | Explicit atomic inlines and shared widgets are implemented; autocomplete, read-only fields and broader customization remain. |
| ADMIN-04 | Audit history, admin checks and staff access | Package | Absent | L | Attributed changes, reusable staff policy, checks and tested extension contracts. |

Evidence: [security primitives](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/security/security.go), [admin prototype](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/admin/admin.go), [articles](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/examples/articles/project/application_test.go), [catalog](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/examples/catalog/project/application_test.go). Passing example tests does not complete auth or admin as batteries.

## Shared services, core modules, and testing

Django references: [cache](https://docs.djangoproject.com/en/6.1/topics/cache/), [email](https://docs.djangoproject.com/en/6.1/topics/email/), [tasks](https://docs.djangoproject.com/en/6.1/topics/tasks/), [testing](https://docs.djangoproject.com/en/6.1/topics/testing/), [logging](https://docs.djangoproject.com/en/6.1/topics/logging/), [signals](https://docs.djangoproject.com/en/6.1/topics/signals/), and [contrib](https://docs.djangoproject.com/en/6.1/ref/contrib/).

| ID | Battery | Target | Current | Effort | Completion gap / intended scope |
| --- | --- | --- | --- | --- | --- |
| SVC-01 | Cache API, aliases, backends and invalidation | Package | Partial | L | Context-aware backend errors, isolated aliases/versioned keys, bounded local adapter and cancellation-aware coalesced loading implemented; shared providers, consistency operations and provider conformance remain. See [cache contract](https://cicadel.fauzaanu.com/en/0.2.7/topics/cache/index.md). |
| SVC-02 | Per-view/site/template fragment caching | Package | Absent | L | Correct variation, authentication boundaries and explicit invalidation; cannot leak private responses. |
| SVC-03 | Email messages, transport backends, attachments and testing | Package | Complete | L | Verified-TLS SMTP, reusable batches, MIME text/HTML, CC/BCC, reply-to, attachments and development backends are implemented; see [supported email contract](https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md). |
| SVC-04 | Background task definitions, enqueueing, results and backend contracts | Package | Partial | L | River integration is useful but provider-specific; finish command/config/test contracts and task observability. |
| SVC-05 | Logging, exception reporting and sensitive-data filtering | Core | Complete | M | Named routing, levels/filters, JSON/text/custom handlers, file rotation, error-email hooks, grouped redaction, correlated panic events and private query timing are implemented; see [logging contract](https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md). |
| SVC-06 | Paginator and reusable page links | Core | Complete | S | `paginate`: validated parsing, ordered snapshot queries, slices, relative links, elided ranges and `paginate.Nav`; PostgreSQL and generated-consumer tests. [Guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/pagination-and-messages/index.md). Keyset pagination is out of scope. |
| SVC-07 | Temporary user/flash messages | Core | Complete | S | `flash`: session-backed consume-once messages, levels, limits, missing-session errors and `flash.List`; HTTP redirect and generated-consumer tests. [Guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/pagination-and-messages/index.md). The starter does not pre-create the store yet. |
| SVC-08 | Signals and lifecycle events | Core | Complete | M | `events` package: typed `Event[T]` declared by the owning app (`App.Events`), explicit `App.Subscriptions`, construction-time ownership/duplicate/undeclared checks, synchronous dependency-ordered delivery with error propagation, cancellation and bounded nesting; dispatcher on requests, hooks and commands plus `Application.Context` for jobs. Accounts emits five transactional events. Unit, application, management, PostgreSQL accounts and generated-consumer tests. Guide: docs/events.md. Automatic model save/delete events and cross-process delivery are out of scope (GORM hooks, River). |
| CONTRIB-01 | Content types and generic model relationships | Third-party | Excluded | — | Keep generic polymorphic persistence out of the core; auth/admin metadata should not require it. |
| CONTRIB-02 | Database-backed flat pages | Third-party | Excluded | — | Content-management app rather than framework foundation. |
| CONTRIB-03 | Database-managed redirects | Package | Absent | S | Separate from HTTP redirect safety; status/lookup/admin/cache behavior. |
| CONTRIB-04 | Sitemap generation | Package | Absent | S | Escaped XML, chunking/indexes, URL construction and tests. |
| CONTRIB-05 | RSS/Atom syndication feeds | Third-party | Excluded | — | Ordinary reusable app using Go XML libraries and package hooks. |
| CONTRIB-06 | Sites/multiple-domain content registry | Third-party | Excluded | — | Application tenancy/content policy, not mandatory global state. |
| CONTRIB-07 | Generated admin documentation | Third-party | Excluded | — | API/package metadata may enable external documentation tools. |
| TEST-01 | Request client, test settings and assertions | Core | Partial | M | Standard `httptest` is used; provide coherent app fixtures and package testing helpers. |
| TEST-02 | Test databases, transactions, fixtures and provider matrix | Core | Partial | L | Disposable PostgreSQL tests exist; isolation and every promised provider must be supported. |
| TEST-03 | Live-server testing helpers | Package | Dependency | M | Go server lifecycle and deterministic readiness; browser tooling is external and is not needed for framework verification. |
| TEST-04 | Email/task/cache test backends and query assertions | Core | Partial | M | Capture and task integration tests exist; unified backend contracts and query-count assertions remain. |

Django's Tasks framework includes task APIs and development/test backends; production execution requires an external backend/worker. Do not count a production worker fleet as a battery Django itself ships. Cicadel's River integration is a chosen implementation, not a claim of Python task compatibility. See [Django Tasks](https://docs.djangoproject.com/en/6.1/topics/tasks/).

## Explicit exclusions and adjacent ecosystem features

Django references: [internationalization/localization](https://docs.djangoproject.com/en/6.1/topics/i18n/), [time zones](https://docs.djangoproject.com/en/6.1/topics/i18n/timezones/), [humanize](https://docs.djangoproject.com/en/6.1/ref/contrib/humanize/), and [GeoDjango](https://docs.djangoproject.com/en/6.1/ref/contrib/gis/).

| ID | Capability | Target | Current | Effort | Policy |
| --- | --- | --- | --- | --- | --- |
| EX-01 | Translation catalogs, pluralization, extraction and compilation | Third-party | Excluded | — | No native translation runtime or commands. |
| EX-02 | Locale selection, negotiation and localized URLs | Third-party | Excluded | — | Request/template hooks permit optional packages; no native locale middleware. |
| EX-03 | Localized dates/numbers/input formats and humanization | Third-party | Excluded | — | No first-party locale formatter or bundled catalogs. |
| EX-04 | GIS models, spatial backends, geometry and map admin | Third-party | Excluded | — | No first-party GeoDjango equivalent. |
| EX-05 | GeoJSON/GIS serializers and geographic imports | Third-party | Excluded | — | Basic JSON encoding remains available; geospatial semantics are external. |
| TIME-01 | Correct timestamps, UTC storage and explicit time zones | Core | Partial | M | Keep temporal correctness; this is not a translation/locale-formatting battery. |
| EXTRA-01 | REST framework, OpenAPI, API auth conventions | Package | Partial | L | Cicadel JSON helpers exist; a full REST framework is an additional product, not Django core. |
| EXTRA-02 | WebSockets/channels and realtime infrastructure | Third-party | Excluded | — | Do not confuse Django async HTTP support with a bundled Channels stack. |
| EXTRA-03 | Social login, OAuth/OIDC, MFA, account registration workflows | Third-party | Excluded | — | Provider integrations beyond the selected account battery; core hooks must permit them. |
| EXTRA-04 | CORS middleware and API-specific policies | Package | Absent | M | Adjacent integration, not a claim that Django ships a general CORS middleware package. |
| EXTRA-05 | Debug toolbar, profiling UI, CMS and full-text search service | Third-party | Excluded | — | Development/product extensions; provider-native query/search features remain separately tracked. |

## Complete component UI battery

TPL-01/02/04/05 follow [the component UI acceptance checklist](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md#acceptance-checklist). The initial server component contract is complete with [recorded verification](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/component-verification.md), including a generated host consuming an independent module. The `html/template` package remains compatibility-only. Django template syntax is not a compatibility target. React-like UI composition does not imply a React dependency or an implemented client-side reactive runtime.

## Complete migration battery: acceptance checklist

**Parent batteries:** MIG-01–06, DB-01 and DB-05. This is a major subsystem. Management now uses the recorded-history runner. Existing Goose-only databases require verified adoption; handwritten histories require reviewed import metadata.

Django generates changes against recorded model history, not simply against whatever a developer's live database happens to contain. Cicadel needs an equivalent reliable workflow, adapted to Go. See [Django migration workflow and historical models](https://docs.djangoproject.com/en/6.1/topics/migrations/).

- [x] Define a versioned, deterministic model-state format covering fields, types, nullability, defaults, relations, keys, constraints, indexes and custom-field metadata.
- [x] Define discovery for `apps/<app>/models.go`, multiple model declaration files, and `apps/<app>/models/*.go`; use Go package/type analysis, respecting imports and build constraints, rather than regex or a filename-only scan.
- [x] Tie discovery to explicitly installed apps; generate or validate an explicit model registry without runtime directory scanning or hidden import side effects. Diagnose incompatible build-tag model sets.
- [x] Implement `makemigrations` to compare discovered declarations with recorded historical state, emitting stable, reviewable migration files; an unchanged model must generate nothing.
- [x] Keep model-state diffing independent of database drift inspection. Detect drift separately; never use an arbitrary development database as the sole canonical schema history.
- [x] Represent changes as versioned operations with provider rendering; preserve generated artifacts and historical adapters after current Go model types evolve.
- [x] Implement additions, alterations, deletion, indexes, unique/check constraints, foreign keys and relationship tables on PostgreSQL.
- [x] Handle renames and ambiguous/destructive changes through explicit declarative hints/flags and diagnostics; never silently guess a drop/create or invent a data backfill. Noninteractive runs fail clearly when intent is missing.
- [x] Support nullable/default/backfill transitions and data migrations without requiring today's model structs to represent yesterday's schema.
- [x] Build a version-level dependency graph spanning apps and packages; detect cycles, missing history and divergent branches; support explicit merge migrations.
- [x] Supply `migrate`, `showmigrations`, `sqlmigrate`, plan/dry-run output, target versions, supported rollback and `makemigrations --check` for CI.
- [x] Separate generating from applying migrations. No schema mutation on web startup, model import, or file save.
- [x] Establish locking, history integrity, interruption/retry behavior and checksums/immutability rules for already-applied artifacts.
- [x] Define and test PostgreSQL transactional DDL rollback and explicit recovery for supported nontransactional SQL.
- [x] Test clean installs and upgrades with real PostgreSQL databases; publish exact supported versions, types and unsupported-operation diagnostics.
- [x] Support package-supplied migrations, installation order, upgrades and removal policy without silently deleting user tables.
- [x] Support historical-state data operations, migration squashing/replacements and projects upgrading from different prior states.
- [x] Provide a documented transition for existing app-scoped Goose SQL histories; never reinterpret executed SQL as a portable model graph without explicit conversion evidence.
- [x] Prove the whole workflow in a generated app with model declarations split across files/folders, related models, a rename, a non-null backfill, package upgrades and PostgreSQL.

PostgreSQL is the only supported and planned database. Other providers are excluded, not unfinished acceptance requirements.

Acceptance evidence: [module checklist](https://cicadel.fauzaanu.com/en/0.2.7/sources/contrib/migrations/ACCEPTANCE.md),
[generated consumer upgrade](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/contrib/migrations/scaffold/scaffold_test.go),
[lifecycle walkthrough](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/contrib/migrations/example/workflow/main_test.go), and
[verification record](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/automated-migrations-progress.md). These checks cover
the documented operation subset. Parent batteries remain Partial because the
installable is experimental and has no published versioned release; advanced
indexes, native enum/domain lifecycle and implicit join generation are excluded
from inferred operations. This is not universal GORM or Django feature parity.

## Package system: acceptance checklist

**Parent battery:** DEV-04. This is a composition boundary for core batteries and third-party extensions, including external localization. Go modules solve fetching/version selection; Cicadel must solve application integration. Django's [reusable-app workflow](https://docs.djangoproject.com/en/6.1/intro/reusable-apps/) is the reference, not a requirement to recreate Python packaging.

- [x] Specify package identity, Go module/version, required Cicadel API range, app dependencies, capabilities and optional provider requirements.
- [x] Use normal `go.mod`/`go.sum` pinning and standard Go installation; document private modules, reproducible builds and upgrades without a second resolver/registry.
- [x] Provide explicit installation/registration and clear missing-dependency, incompatible-version, duplicate-name and cycle errors.
- [ ] Define typed contribution contracts for routes, model metadata/migrations, commands, settings/checks, middleware, lifecycle hooks, component libraries/render helpers and static assets.
  - [x] Static assets: `App.Static` with app-namespaced hashed URLs, `static.URL`, collision/route-conflict errors and offline `collectstatic` ([guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md), [manifest tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/static/manifest_test.go), [application tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/static_test.go), generated-consumer [project](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/scaffold_test.go), [accounts](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/accounts_test.go) and [external package](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/package_test.go) evidence).
  - [x] Settings: typed `App.Settings` via `settings.NewPackage[T]` with Go defaults, `CICADEL_<APP>_<NAME>` overrides, validation naming keys not values, secret redaction, collision errors and `check` integration ([guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/package-settings/index.md), [unit and fuzz tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/settings/package_test.go), [application tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/package_settings_test.go), [management tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/management/package_settings_test.go), generated-consumer [package and accounts evidence](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/package_settings_test.go)).
  - [x] Events: typed `events.Event[T]` declared in `App.Events` and handled through `App.Subscriptions`, validated by `cicadel.New`, delivered synchronously in dependency order on requests, hooks and commands and through `Application.Context` ([guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/events/index.md), [unit tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/events/events_test.go), [application tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/events_test.go), [management test](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/management/package_settings_test.go), [accounts PostgreSQL test](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/contrib/accounts/events_test.go), [generated-consumer test](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/events_test.go)).
  - [ ] Render-helper contracts beyond component exports remain.
- [x] Establish namespaces, override precedence and resource ownership; an installed package must not silently replace another package's routes, commands or settings.
- [x] Run startup/shutdown hooks in dependency order with cleanup after failed initialization; document concurrent request behavior and test isolation.
- [x] Define package database support and migration ownership; optional packages must not claim more providers than their conformance suite proves.
- [ ] Extract first-party batteries into independently usable modules as appropriate, composing them into the standard core project.
- [x] Supply a package scaffold, author tutorial and conformance harness; test installation in an independent application rather than only inside this repository.
- [x] Verify an external example can add translation middleware/template helpers through public hooks without importing a native Cicadel locale engine or patching core. The sample is a contract test, not a supported translation product.
- [x] Verify a second external package contributes commands, templates/assets and versioned migrations; exercise upgrade, disablement and removal without automatic data deletion.
- [x] Document trusted-code execution, supply-chain responsibility, compatible version ranges, deprecation and security reporting. Installed Go packages execute with application privileges; this is not a sandbox.

External translation evidence: [generated-consumer contract test](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/translation_test.go) installs a real module through a local proxy and verifies Unicode rendering, escaping, request isolation, disablement and dependency removal. This is an extension probe, not a supported localization package.

Implemented evidence: [public app contracts](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/apps.go), [lifecycle](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/lifecycle.go), [management integration](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/management/management.go), [package scaffold](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/package.go), [external install/upgrade/removal test](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/package_test.go), and [author/consumer guide](https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md). Capabilities currently mean the typed contributions present on `App`; typed component exports, required assets and project overrides are implemented; runtime model contributions now expose explicit table/type ownership through `App.Models` and `ModelRegistry`; historical snapshots remain a separate migration-generator contract. The namespace contract permits only explicit compatible local-project component overrides; other contributions cannot be silently replaced. Provider evidence is PostgreSQL only.

The generated-consumer lifecycle test now runs separate command-only and combined
component package variants. The combined variant installs compiled typed components,
assets, commands and recorded migrations through a local Go proxy, then verifies
upgrade, disablement, restoration and removal with retained PostgreSQL data.
Component assertions cover escaping, named slots, required props and export removal
on disablement. The component-library fixture separately verifies project overrides
and execution outside the source tree. Accounts, formsets, migrations and query
generation have independent modules. Other first-party integrations still share
the root module; complete extraction is not claimed.

No runtime binary plugin loader, automatic network installation during startup, global side-effect registry, or custom package marketplace is required for the first complete version.

## Delivery order and comparatively small batteries

This order was reset on 2026-11-10 to reach a ready framework. It supersedes earlier orderings.

1. **Core gaps, released one at a time:** pagination (SVC-06, done), flash messages (SVC-07, done), security headers and HTTPS policy (SEC-03, done), signed tokens (SEC-04, done), transaction post-commit hooks (DB-03, done) and the typed package settings contract (DEV-04, done). Each needs its own acceptance checklist, generated-consumer tests and a release.
2. **Package system completion (DEV-04):** event hooks and first-party module extraction.
3. **PostgreSQL migration scope:** extend the documented operation subset under the data guarantee.
4. **Extras, after the core:** administration (ADMIN-01–04), cache and task backends, sitemaps (CONTRIB-04), managed redirects (CONTRIB-03), fixtures and further diagnostics.

No feature becomes mandatory merely because it appears in Django. Third-party-only rows remain visible so future contributors can see that omission was intentional. Revisit a support decision explicitly, with reasons and dependency impact, before expanding core.

## Maintenance rules

- Keep stable IDs when splitting batteries; record superseded scope rather than deleting inconvenient gaps.
- When implementing a row, add its detailed checklist and evidence here or in a linked design document. Link code/tests and provider/version coverage before changing status to Complete.
- Keep [PLAN.md](https://cicadel.fauzaanu.com/en/0.2.7/sources/PLAN.md) for concrete implementation tasks and historical foundation work. Its checked boxes do not imply that the larger batteries in this file are complete.
- Update README, API docs and release scope together when support policy changes. A dependency present in `go.mod` is not itself a promised user-facing capability.
- Maintain exclusions alongside supported work; never quietly reintroduce native i18n/l10n or GIS through a convenience dependency.

## Migration installable progress

- [x] Detailed installable-development skill with authoring, lifecycle, data and verification references.
- [x] Separate `contrib/migrations` Go module and offline `migrations:makemigrations` command.
- [x] Explicit model registration across Go files; deterministic snapshots recorded inside SQL files.
- [x] PostgreSQL table creation, additive columns/indexes and same-app belongs-to foreign keys.
- [x] Read-only preview/check, no-op detection and rejection of unsupported or edited histories.
- [x] PostgreSQL create/upgrade/data-preservation and reverse/reapply integration tests.
- [x] Automatic source discovery, verified baseline/adoption, recorded data operations and declared supported schema alterations.
- [x] PostgreSQL conformance for the documented supported subset and migration graph/history workflow above.
- [x] Evaluate an first-party GORM GEN installable for type-safe query generation from authored models; test version compatibility and reproducible regeneration. GEN is complementary to schema migrations.

Evidence: [migration module and limitations](https://cicadel.fauzaanu.com/en/0.2.7/ref/migrations/index.md),
[tests](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/contrib/migrations/generate_test.go), [GORM GEN documentation](https://gorm.io/gen/index.html).

## Browser accounts, email and logging evidence

[Authentication](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md), [email](https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md) and [logging](https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md) define current supported scope and exclusions. Browser account tests use real PostgreSQL, generated-consumer tests cover provisioning/login/password changes, SMTP tests use verified local TLS servers, and logging tests cover routing/redaction/failures. Authentication remains Partial as a broader battery because public signup/verification, broader identity-provider workflows and administration integration are not bundled by this change. SMTPUTF8/DSN, automatic mail queues, arbitrary free-text secret detection and third-party log exporters are outside the documented email/logging scope.