## Context S18 had no spec on 2026-10-01. Neither this issue nor its implementation issue had an assignee that day. Download count and 30-day trend is a P1 row of the GA epic gitlab-org&22707+s, tracked in gitlab-org/gitlab#608036+s. AR tracks S18 under gitlab-org&22812+s. Two P0 GA issues depend on the timestamps S18 owns: the last-download listing filter is gitlab-org/gitlab#630575+s, and cache retention is gitlab-org/gitlab#631533+s. Since this issue opened on 2026-07-14, the hosted `repositories.downloads_count` writers moved off S18 to the repository-column-writers plan. All five of its steps merged by 2026-09-17. Between them, S10, S11, S12, S14, S15, S16, S17, S23, and S32 still leave S18 the mechanism for every `last_downloaded_at` column, the per-artifact counts, the npm remote and container remote counter writers, and download trends. The asks conflict on history. A costing note on this issue says no approved spec asks for download trends or event history. The GA trend needs daily download totals. No table on `main` records them. ## What exists on main Each line holds at `f771c7325` (`f771c73254594d13fb83f23a477b906e818ecbd3`, 2026-10-01). The `docs/adr/` mirror showed no upstream drift that day. - `docs/specs/README.md`: the S18 row reads "Async download event recording, counters, trends", status `Planned`, with no spec file. The S19 retention and S29 cleanup rows are `Planned` with no file either. - `docs/roadmap/beta.md`: S18 is a `Fast-follow (GA)` row with no DRI. It left closed-beta scope on 2026-08-26. The same page strikes the provisional reduction, "ship the counter columns but defer the recording", as moot. The dependency graph draws S10, S11, S12, and S27 into S18, and S18 into S17 and S19. - `internal/datastore/migrations/structure.sql`: 12 public tables carry `last_downloaded_at`: packages and versions for Maven and npm, and images and manifests for container, each hosted and remote. Only `repositories` carries `downloads_count`. No public table records a download event. - `git grep -nE "UPDATE\([^)]*LastDownloadedAt" f771c7325 -- internal cmd` returns 12 writer sites on 10 tables, none on `container_images` or `container_manifests`. Four set `GREATEST(last_downloaded_at, NOW())`, on container remote and Maven hosted. The other eight set `NOW()` or a caller-supplied time with no max-wins guard, on npm hosted, npm remote, and Maven remote. No production code filters or sorts on the column outside these writers' own throttles. - `git grep -n "TODO(s18" f771c7325 -- internal ':!*_test.go'` returns 20 lines in 10 files. `internal/datastore/maven_invariants_test.go` requires the marker on every jet `UPDATE` in `maven_*.go`, so tombstone and credential writes carry it beside comments saying the swap must leave them direct. A health-check compare-and-set in `internal/datastore/npm_remote_repositories.go` and the size writes on `maven_versions` and `maven_remote_versions` carry it too. - Hosted npm and container reads book `repositories.downloads_count` through `EmitRepoDownloads` (`internal/accounting/emit.go:103`). Maven hosted, remote, and virtual reads book it through the direct `UPDATE` in `MavenRepositoryStore.BumpRepoDownloadCount` (`internal/datastore/maven_repositories.go:307`). No npm remote or container remote read books it. - `internal/usagedata/events.go`: `EventArtifactPulled` reports each delivered download to Snowplow under ADR-012. It writes nothing to the database. - `docs/plans/2026-09-03-repository-column-writers.md` (Dependencies, Open Questions, and Status): all five steps merged. The plan put the hosted npm and container writers on the `downloads_scoped` counter family, kept Maven's two writers on their direct `UPDATE`, and left the npm remote and container remote writers with this issue. It accepted container-pull volume on its writers because ADR-007 describes the target state this issue delivers. The plan amendment that ruled the two-slot `Family.Fields()` question recorded on this issue is gitlab-org/ops/artifact-registry!2441+s. - `docs/dev/storage-accounting.md` (The counter model, Out of scope): no reconciliation recomputes `downloads_count`, so a lost delta stays lost. `last_downloaded_at` stays off the pipeline because every layer sums and the timestamp merges max-wins. - S10 and S11 Interim implementation of buffered columns: S18 owns the Maven and npm `last_downloaded_at` columns. S11 leaves to S18 how it carries a max-wins timestamp. - S12 Counter and Timestamp Updates: both container hosted timestamps stay with S18, "which will be specced separately and has no spec yet". The mechanism decision for the container remote counter sits with this issue. - S14 Out of scope: Maven remote's direct `UPDATE`s carry swap markers, and their rebinding onto a pipeline sits with this issue. - S15 Tarball proxy: npm remote defines no `downloads_count` event and leaves the mechanism for the remote read paths to this issue. - S16 Dependencies and Download signals: S16 specifies the container remote counter event, emits none of it, and gates every `downloads_count` criterion on a writer no spec assigns. Its manifest bump skips a row stamped inside `last_downloaded_at_staleness_window` (default `1h`). - S17 Dependencies, Download figures, and Out of Scope: S18 owns the mechanism for every `last_downloaded_at` column and the per-artifact counters, which join the version response and the artifact lists as additive fields. "Download trends, time series, and event history" are S18's. Phase 8 serves point-in-time figures only. - S23 Out of Scope: "Download counters, trends, and their query surface: S18." S23 fixes the firing point of every ADR-012 event, `artifact_pulled` included. - S27 Out of Scope: download tracking defines and registers its own job types. - S32 Dependencies and Container virtual resolution: S18 writes the hosted container timestamps at every hosted serve point, the virtual one included. It must widen `emitDownload`, or give it another way to receive the image and, on a manifest read, the manifest. ## Change An approved S18 spec on `main` rules on every download obligation other specs leave to S18. The S18 index row links it. The spec sets the max-wins mechanism for the 12 `last_downloaded_at` columns and states what a retention rule can rely on. It picks a counter mechanism that keeps every increment, assigns the npm remote and container remote writers, and rules on Maven's direct writers. It carries the per-artifact rulings of gitlab-org/ops/artifact-registry#757+s. It covers the container hosted timestamps under either option of gitlab-org/ops/artifact-registry#1040+s. It defines the record and the query surface behind the 30-day trend. This scope replaces the counters-only fallback boundary the original description asks for. That fallback was the provisional reduction the roadmap struck when S18 left closed-beta scope. ## Acceptance criteria 1. **The spec is approved and indexed.** A `docs(specs)` MR adds the S18 spec under `docs/specs/` from `docs/specs/TEMPLATE.md` with status `Approved`. The S18 row in `docs/specs/README.md` links it. 1. **The scope names every column and writer (decision).** The spec lists what S18 owns: the mechanism for all 12 `last_downloaded_at` columns, the per-artifact counts, the trend and its query surface, the npm remote and container remote `downloads_count` writers, and the rebinding of Maven's direct writers. Its Out of Scope names the hosted `downloads_count` writers, which the column-writers plan owns, and the `artifact_pulled` event, which S23 owns. It also names `repositories.last_updated_at`, tracked in gitlab-org/ops/artifact-registry#442+s. The spec names each column it adds. Every `last_downloaded_at` column and `repositories.downloads_count` already landed with the format schemas. No schema holds a per-artifact count or a dated download record. 1. **The spec names the marker sites it rebinds (decision).** It lists each `TODO(s18-buffered-counters)` site it moves onto its mechanism and each it leaves direct, from `git grep -n "TODO(s18" -- internal` at its base commit. A swap keyed on the marker alone would also convert writes whose comments say to leave them direct, and size writes the format slices own. 1. **Download counts keep every increment (decision).** ADR-007 requires the counter mechanism to preserve every increment. No reconciliation recomputes `downloads_count`. The spec picks the mechanism for the repository total and the per-artifact counts. It says whether the hosted npm and container writers stay on the `downloads_scoped` family. That family sheds deltas before the Redis call and loses more on the paths the column-writers plan lists under Research Findings. One priced option is the delta outbox from gitlab-org/ops/artifact-registry#1026+s. At 2,000 downloads per second and a 30-second drain interval, the outbox holds about 60,000 rows (about 8 MB) in flight. A package and version key adds 32 bytes per row. The spec defines any job its mechanism needs and registers it on the S27 foundation. 1. **Timestamps merge max-wins on every writer (decision).** The storage-accounting pipeline sums, so it cannot carry a max-wins timestamp. ADR-007 reduces timestamps max-wins on the same buffering infrastructure as counters. The spec picks the mechanism for all 12 columns, holds every writer to max-wins, and rules on a throttle window. At `f771c7325`, eight of the 12 writer sites have no max-wins guard. S16's manifest bump skips a row stamped inside its window, Maven's hosted bump skips a row stamped within the hour, and no other site's statement carries a window. The counter and timestamp mechanisms both run after the response. A failed write never fails the request (S12 Emission timing). The write-amplification argument the window answers is gitlab-org/ops/artifact-registry#680+s. 1. **A retention rule can rely on the timestamps (decision).** ADR-010's default retention, S19, S29, and the two P0 GA issues in Context all plan to evict or filter on these columns. None is built on `main`. A lost bump repairs itself only when a later download follows. A precondition carries over from gitlab-org/ops/artifact-registry#632+s. No download-based retention consumer lands on the hosted npm and Maven timestamps until their write is durable or a source table exists. The spec states the write guarantee a retention consumer gets, or carries that precondition into S19 and S29. It also answers whether the remote timestamps are accurate enough to evict on, the question cache retention asks in gitlab-org/gitlab#631533+s. 1. **Container hosted timestamps follow the interim-or-wait ruling.** That ruling is criterion 1 of gitlab-org/ops/artifact-registry#1040+s. Under a wait, the spec covers `container_images.last_downloaded_at` and `container_manifests.last_downloaded_at` at every hosted serve point, S32's virtual serve point included. It widens `emitDownload`, or gives it another way to receive the image and manifest, as S32 Dependencies requires. Under an interim writer, the spec rebinds that writer onto its timestamp mechanism. 1. **Remote counters get a writer or a recorded absence (decision).** The spec assigns the writer for the container remote event S16 specifies. S15 defines no npm remote event, so the spec defines one or records why npm remote counts nothing. Maven remote counts archive reads under S14. The spec rules whether Maven's hosted and remote direct `UPDATE`s move onto the mechanism in criterion 4. The hosted half is also criterion 4 of gitlab-org/ops/artifact-registry#757+s. 1. **Per-artifact counts carry the per-artifact issue's rulings.** The spec rules on criteria 1 to 4, 7, and 8 of gitlab-org/ops/artifact-registry#757+s. Those cover the screens, the counting rule per format, the durable mechanism, Maven's increment, npm virtual reads, and remote rows against the repository total. 1. **The 30-day trend gets a record and a query surface (decision).** S17 and S23 assign download trends to S18. The trend issue is gitlab-org/gitlab#608036+s. It asks for a 30-day chart on repository detail and a sparkline per repository-list row, read from precomputed daily buckets, with a zero-download day drawn as zero. It says download events are already tracked and adds only the series and the chart. On `main` the count is a running total, and the database holds only each artifact's latest download time. The per-download `artifact_pulled` event goes to Snowplow rather than the database. The series therefore needs a new record. The costing in criterion 4 priced two designs: an outbox that keeps no history, and a per-download log at 22.5 GB a day at 2,000 downloads per second. It priced no daily buckets. ADR-006 section 5 names ClickHouse for usage trends, keeps it out of MVP scope, and requires the service to work without it. The spec rules on where the buckets live and states how that store squares with section 5. A store that departs from ADR-006 needs an escalation and a handbook ADR amendment. The spec also rules on the reads a bucket counts, the bucket retention and per-artifact granularity the trend issue leaves open, and the management API resource that serves the series. 1. **Live references match the merged spec.** Before the plan MR for the implementation issue opens, no spec under `docs/specs/` says S18 has no spec, or that this issue still owns a decision the spec ruled. The site list comes from `git grep -n -e "S18" -e "work_items/292" -- docs/specs` at the spec MR's base commit, which returns 75 lines in 15 files at `f771c7325`. ## Specs and ADRs - [S12 Counter and Timestamp Updates](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S12-container-oci-hosted.md#counter-and-timestamp-updates): the container event table, emission timing, and the timestamps S12 leaves with S18. - [S10 Interim implementation of buffered columns](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S10-maven-hosted.md#interim-implementation-of-buffered-columns) and [S11 Interim implementation of buffered columns](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S11-npm-hosted.md#interim-implementation-of-buffered-columns): the interim writers and the timestamp columns S18 owns. - [S14 Out of scope](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S14-maven-remote.md#out-of-scope): Maven remote's direct writers and their rebinding. - [S15 Tarball proxy](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S15-npm-remote.md#tarball-proxy): npm remote counts no download. - [S16 Dependencies](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S16-container-remote.md#dependencies) and [S16 Download signals](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S16-container-remote.md#download-signals): the container remote event table, its throttle, and the unassigned counter writer. - [S17 Dependencies](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S17-rest-management-api.md#dependencies), [S17 Download figures](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S17-rest-management-api.md#download-figures), and [S17 Out of Scope](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S17-rest-management-api.md#out-of-scope): the S18 row, the additive-field rule, and the trend assignment. - [S23 Out of Scope](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S23-usage-data-collection.md#out-of-scope): counters, trends, and their query surface. - [S27 Out of Scope](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S27-background-jobs-foundation.md#out-of-scope): the job types S18 registers. - [S32 Dependencies](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S32-container-virtual.md#dependencies) and [S32 Container virtual resolution](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/S32-container-virtual.md#container-virtual-resolution): one hosted timestamp writer for direct and virtual reads. - [Storage accounting: The counter model](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/storage-accounting.md#the-counter-model) and [Out of scope](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/dev/storage-accounting.md#out-of-scope): why `downloads_count` has no backstop and `last_downloaded_at` stays off the pipeline. - [ADR-007 Buffered and asynchronous writes](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/007_database_schema.md#buffered-and-asynchronous-writes): counters sum and keep every increment, and timestamps merge max-wins. - [ADR-006 Analytics Engine: ClickHouse](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/006_technology_stack.md#5-analytics-engine-clickhouse): long-term event records and usage trends. - [ADR-010 Default Retention Period](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/010_data_retention.md#default-retention-period), [Supported Strategies](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/010_data_retention.md#supported-strategies), and [Cache Retention](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/010_data_retention.md#cache-retention): the retention rules that read the timestamps. - [ADR-012 When a pull event fires](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/adr/012_usage_data_collection.md#when-a-pull-event-fires): the delivery rule each format's counter follows. ## Dependencies - The implementation issue is gitlab-org/ops/artifact-registry#293+s. This spec merges first, then a plan MR for that issue, then its step MRs, because AGENTS.md lets no implementation MR open before its plan merges. Both issues were open and unassigned on 2026-10-01. - The per-artifact issue is gitlab-org/ops/artifact-registry#757+s. Six of its criteria are rulings in this spec, so its implementation follows the spec. - The container hosted timestamp issue is gitlab-org/ops/artifact-registry#1040+s. Under its interim option, that issue can land first. This spec then rebinds its writer. Under its wait option, this spec comes first. That issue then closes with the implementation. - The `repositories.last_updated_at` mechanism is tracked in gitlab-org/ops/artifact-registry#442+s. The costing note on this issue says one outbox row with an event kind would carry both columns. A spec that picks an outbox settles the row layout with that issue's owner. No order applies. - The durability question started in gitlab-org/ops/artifact-registry#632+s. Its counter half moved to gitlab-org/ops/artifact-registry#1026+s, which closed by giving ownership to this issue. No order applies. - The write-amplification argument is gitlab-org/ops/artifact-registry#680+s. It informs criterion 5 and blocks nothing. - The 30-day trend is gitlab-org/gitlab#608036+s. Criterion 10 rules on its record. Its chart and sparkline wait on the series this spec defines. - S19 retention and S29 cleanup policies have no spec. The roadmap graph orders S19 after S18 and S29 after S19. Criterion 6 states what both can rely on. - The missing npm remote `artifact_pulled` event is gitlab-org/ops/artifact-registry#783+s, which the roadmap lists in its S18 row. S23 fixes the firing point of every ADR-012 event, so that issue needs no ruling here and blocks nothing. - The S17 S18 row also changes under gitlab-org/ops/artifact-registry#975+s. Criterion 11 edits the same row, so the second MR to land rebases onto the first. ## First step The first MR is a `docs(specs)` MR that adds the S18 spec from `docs/specs/TEMPLATE.md` with status `Approved` and links it from the S18 row in `docs/specs/README.md`. Its author settles criterion 10 before writing the Data Model, because the trend's store decides whether the spec adds a dated table beside the counter columns. This issue had no assignee on 2026-10-01, so it needs an owner before the MR opens. ## Original description Spec for S18 per [specs/README.md](https://gitlab.com/gitlab-org/ops/artifact-registry/-/blob/main/docs/specs/README.md): async download event recording, per-artifact and repository counters, trends. Must define the counters-only fallback boundary (which columns land with the format schemas vs. the recording pipeline).