log-foundry 0.10.2.dev129__tar.gz → 1.0.1__tar.gz

{log_foundry-0.10.2.dev129 → log_foundry-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev129
+Version: 1.0.1
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -41,6 +41,7 @@ Requires-Dist: psycopg[binary] (>=3.1) ; extra == "postgres"
 Requires-Dist: pymongo (>=4.6) ; extra == "mongo"
 Requires-Dist: redis (>=5.0) ; extra == "redis"
 Requires-Dist: sentry-sdk (>=2.66.1) ; extra == "sentry"
+Project-URL: Changelog, https://github.com/agriffi10/log-forge/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/agriffi10/log-forge#readme
 Project-URL: Homepage, https://github.com/agriffi10/log-forge
 Project-URL: Issues, https://github.com/agriffi10/log-forge/issues
@@ -51,6 +52,11 @@ Description-Content-Type: text/markdown
 
 # Log Foundry
 
+[![PyPI](https://img.shields.io/pypi/v/log-foundry?label=pypi)](https://pypi.org/project/log-foundry/)
+[![Python](https://img.shields.io/pypi/pyversions/log-foundry)](https://pypi.org/project/log-foundry/)
+[![Build](https://img.shields.io/github/actions/workflow/status/agriffi10/log-forge/release.yml?branch=main&label=build)](https://github.com/agriffi10/log-forge/actions/workflows/release.yml)
+[![License](https://img.shields.io/pypi/l/log-foundry)](https://github.com/agriffi10/log-forge/blob/main/LICENSE)
+
 Consistent, structured (JSON) logs for every decorated function call — correlated by shared
 trace/span IDs, ready to ship to any of 30-plus built-in sinks (stdout by default; SQS → ELK is
 the headline production path).
@@ -71,6 +77,27 @@ calls form a tree you can query later.
   a level call with **no open span**, which emits on your own thread, and `flush()`, which by
   definition waits for the drain it asked for.
 
+**The public API is frozen for the whole of `1.x`.** Everything in `log_foundry.__all__`, the
+`Sink` protocol, and every shipped sink class **at the import path documented for it below** —
+together with the public names those signatures use, such as `GroupIdSource`, `DedupIdSource` and
+`Backend` — stays put: nothing is removed, renamed or moved, and no signature changes in a way
+that breaks a caller, until `2.0.0`. The import path is part of that promise because it has to
+be — no concrete sink is exported from the top level, so `from log_foundry.sinks.sqs import
+SQSSink` is the only way to reach one, and a class pinned at a path free to move is not pinned at
+all. `1.0.0` is where they last moved; the upgrade note below says which.
+
+Behaviour is not frozen by that promise — a defect is still a defect, and fixing one can change
+what a broken path does. The private half is genuinely private: underscore-prefixed modules —
+`_lifecycle`, `_fork`, `_diag`, and the `sinks/_*.py` helpers — move without notice.
+
+`1.0.0` was a reliability release rather than a feature release: three audit arcs worked through
+the paths where the library could lose an event, fail its caller, block forever, or report health
+it could not back up. If you are coming from any `0.x`, read its release notes before you bump —
+several of the changes are silent, and they are written against `0.10.1`, the release immediately
+before this one:
+[`docs/release-notes/v1.0.0.md`](https://github.com/agriffi10/log-forge/blob/v1.0.0/docs/release-notes/v1.0.0.md).
+[`CHANGELOG.md`](https://github.com/agriffi10/log-forge/blob/main/CHANGELOG.md) indexes every version.
+
 ---
 
 ## Requirements
@@ -82,12 +109,14 @@ calls form a tree you can query later.
 Published on PyPI as **[`log-foundry`](https://pypi.org/project/log-foundry/)**:
 
 ```bash
-pip install log-foundry          # core, zero dependencies
-pip install 'log-foundry[aws]'   # + boto3 for the SQS/SNS/Kinesis/Firehose sinks
+pip install log-foundry           # core, zero dependencies
+pip install 'log-foundry[aws]'    # + boto3 for the SQS/SNS/Kinesis/Firehose sinks
+pip install 'log-foundry>=1,<2'   # pin to the frozen API above
 ```
 
-> **Breaking in `1.0.0`.** Three public shapes change once, before the API is frozen under
-> semantic versioning, because none of them could be changed afterwards without a major version:
+> **Breaking in `1.0.0`, if you are upgrading from any `0.x`.** Three public shapes changed once,
+> in the release that froze the API, because none of them could have been changed afterwards
+> without a major version:
 >
 > - **`health()` and `sink.losses()` return frozen dataclasses**, not `NamedTuple`s. Attribute
 >   access (`h.dropped`, `losses.failed`) is unchanged and is the whole contract; `len(h)`,
@@ -97,29 +126,36 @@ pip install 'log-foundry[aws]'   # + boto3 for the SQS/SNS/Kinesis/Firehose sink
 > - **`flush()` returns a `FlushResult` and `continue_trace()` a `ContinueResult`**, each truthy
 >   or falsy with a `reason` naming *why*. `if lf.flush():` is unchanged; **`lf.flush() is True`
 >   is not** — the result is an object. A one-bit return could not grow a reason later without
->   silently changing what `if flush():` means, which is why it moved now.
+>   silently changing what `if flush():` means, which is why it moved before the freeze.
 > - **`SQSSink`'s injected client is keyword-only** (`SQSSink(queue_url, client=…)`), **`SentrySink`
 >   injects through `client=`** rather than the old `sdk` keyword, with no alias, and the sink attribute the
 >   library assigns for interruptible backoff is **`log_foundry_stop_signal`**, not
 >   `stop_signal` — a prefixed name cannot silently overwrite one your own sink already uses.
 >
+> Those are the three changes of *shape*, and not the three most likely to reach you:
+> `log_foundry.sinks.util` was deleted with no alias — the `MemorySink`, `NullSink` and
+> `StderrSink` it held are now at `log_foundry.sinks.memory`, `…null` and `…stdout` — and
+> several new construction-time refusals land, all of which rank above two of the three above in
+> the release notes' own ordering. Read the full list of twenty-two before you upgrade —
+> [`docs/release-notes/v1.0.0.md`](https://github.com/agriffi10/log-forge/blob/v1.0.0/docs/release-notes/v1.0.0.md).
+>
 > `echo`, `message` and `fields` are reserved parameter names on the emitters; pass fields of
 > those names through `fields={...}`, which also takes keys that are not Python identifiers.
 
-> **Renamed in 0.2.0: `log_forge` → `log_foundry`.** The import package now matches the
-> distribution name — `pip install log-foundry`, then `import log_foundry`. If you are on
-> `0.1.x`, update your imports; there is no compatibility shim. The project was originally
-> called *log-forge*, but PyPI rejects that name as too similar to the unrelated, pre-existing
-> [`logforge`](https://pypi.org/project/logforge/) project — its similarity check collapses
-> separators, so `log-forge` and `logforge` count as the same name. Rather than keep a
-> distribution and an import name that disagreed, everything is now `log-foundry` /
-> `log_foundry`.
+> **Why `log-foundry`, when the repository is `log-forge`.** The distribution and the import
+> package match each other — `pip install log-foundry`, then `import log_foundry`. The project was
+> originally called *log-forge*, but PyPI rejects that name as too similar to the unrelated,
+> pre-existing [`logforge`](https://pypi.org/project/logforge/) project — its similarity check
+> collapses separators, so `log-forge` and `logforge` count as the same name. Rather than keep a
+> distribution and an import name that disagreed, everything became `log-foundry` / `log_foundry`
+> in `0.2.0`.
 >
-> Migrating from `0.1.x` is a find-and-replace on `log_forge` → `log_foundry`; no module moved
-> and no public API changed. A handful of *emitted* defaults carry the name and shift with it:
-> `LoggingSink`'s default logger (`logging.getLogger("log_foundry")`), `SyslogSink(app_name=…)`,
-> `SplunkHECSink(source=…)`, Datadog's `ddsource`, and Sentry's client tag. Override them
-> explicitly if a downstream query or dashboard pins the old string.
+> If you are still on `0.1.x`, there is no compatibility shim: migrating is a find-and-replace on
+> `log_forge` → `log_foundry`; no module moved and no public API changed. A handful of *emitted*
+> defaults carry the name and shift with it: `LoggingSink`'s default logger
+> (`logging.getLogger("log_foundry")`), `SyslogSink(app_name=…)`, `SplunkHECSink(source=…)`,
+> Datadog's `ddsource`, and Sentry's client tag. Override them explicitly if a downstream query
+> or dashboard pins the old string.
 
 ```python
 import log_foundry
@@ -191,7 +227,7 @@ with the child span pointing at its parent via `parent_span_id`:
 
 ## How it works
 
-![log-foundry pipeline: a traced call opens a span, gathers events, then closes and hands off to a background worker that batches events and ships them to a sink. Steps 1–4 run on your thread; the worker and sink run on a background thread. Support modules — config, ids, model, context, console — assist every step.](docs/assets/pipeline.svg)
+![log-foundry pipeline: a traced call opens a span, gathers events, then closes and hands off to a background worker that batches events and ships them to a sink. Steps 1–4 run on your thread; the worker and sink run on a background thread. Support modules — config, ids, model, context, console — assist every step.](https://raw.githubusercontent.com/agriffi10/log-forge/main/docs/assets/pipeline.svg)
 
 A traced call travels through a small pipeline. The first four steps run on your own thread
 and are deliberately fast; the last two run on a background thread so your code never waits on
@@ -578,7 +614,8 @@ nothing.
 Wire one up by passing an instance to `configure(sink=...)`; if you never do, the first decorated
 call falls back to `StdoutSink()`. The **protocol** is a top-level export, alongside
 `SinkDeliveryError`, `SinkLosses`, `read_losses` and `flush_sink` — the last two being the probes
-a wrapper sink needs to ask a child for its losses and to push its client-side buffer. The
+a wrapper sink needs to ask a child for its losses and to push its client-side buffer — plus the
+two default bounds, `DEFAULT_SHUTDOWN_TIMEOUT` and `DEFAULT_SWAP_TIMEOUT`. The
 **concrete sinks** are not exported, so import each from its own module, e.g.
 `from log_foundry.sinks.sqs import SQSSink`.
 
@@ -892,8 +929,8 @@ disconnected, so a sustained outage moves `health().failed_batches` instead of b
 | `KafkaSink` | `log_foundry.sinks.kafka` | `kafka` | `KafkaSink(topic, *, flush_timeout=10.0, bootstrap_servers="…", key_field="trace_id", producer_config=None)` — `producer_config` is merged **beneath** the sink's own keys, so it reaches `message.timeout.ms` and friends without displacing `bootstrap.servers`; passing it with `producer=` is a `ValueError` |
 | `RedisStreamsSink` | `log_foundry.sinks.redis` | `redis` | `RedisStreamsSink(stream, *, url=None, maxlen=None)` — `XADD`. `maxlen` caps the stream (`approximate=True`); trimming happens **at Redis**, after delivery, so it is invisible to `health()` — which is why the default is unbounded |
 | `RedisListSink` | `log_foundry.sinks.redis` | `redis` | `RedisListSink(key, *, url=None, maxlen=None)` — `RPUSH` + `LTRIM` to the newest `maxlen`; same destination-side trimming caveat |
-| `RabbitMQSink` | `log_foundry.sinks.rabbitmq` | `amqp` | `RabbitMQSink(*, exchange, routing_key, url=None)` — persistent messages |
-| `NATSSink` | `log_foundry.sinks.nats` | `nats` | `NATSSink(subject, *, jetstream=False, servers=None, publish_timeout=10.0, connect_timeout=None, max_reconnect_attempts=None, reconnect_time_wait=None, drain_timeout=None)` — `publish_timeout` bounds one whole `emit` and applies to an injected `client=` too; the four `None` timeouts are forwarded to `nats.connect` only when set, and passing one with `client=` is a `ValueError` |
+| `RabbitMQSink` | `log_foundry.sinks.rabbitmq` | `amqp` | `RabbitMQSink(*, exchange, routing_key, url=None, blocked_connection_timeout=None, socket_timeout=None, stack_timeout=None)` — persistent messages; `pika` leaves `blocked_connection_timeout` unset, so a broker under a memory or disk alarm blocks every publish indefinitely — the sink applies `DEFAULT_BLOCKED_CONNECTION_TIMEOUT` (30 s) unless the URL's query names one, and an explicit keyword overrides the URL. **Read from `pika` 1.4.4 and not executed against a broker** — verify it against yours |
+| `NATSSink` | `log_foundry.sinks.nats` | `nats` | `NATSSink(subject, *, jetstream=False, servers=None, publish_timeout=10.0, connect_timeout=None, max_reconnect_attempts=None, reconnect_time_wait=None, drain_timeout=None)` — a non-positive `max_reconnect_attempts` is a `ValueError` at construction, since `nats-py` retires a server from its pool only under `max_reconnect_attempts > 0` and a non-positive value therefore never returns; `publish_timeout` bounds one whole `emit` and applies to an injected `client=` too; the four `None` timeouts are forwarded to `nats.connect` only when set, and passing one with `client=` is a `ValueError` |
 | `GooglePubSubSink` | `log_foundry.sinks.pubsub` | `gcp-pubsub` | `GooglePubSubSink(topic)` |
 | `AzureEventHubsSink` | `log_foundry.sinks.eventhubs` | `azure-eventhubs` | `AzureEventHubsSink(*, connection_str="…", eventhub=None)` |
 
@@ -908,9 +945,9 @@ Write-only inserts (querying is the downstream tool's job); each needs its own e
 
 | Sink | Import from | Extra | Configure |
 |---|---|---|---|
-| `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…")` |
+| `MongoDBSink` | `log_foundry.sinks.mongodb` | `mongo` | `MongoDBSink(*, uri="…", database="…", collection="…", socket_timeout=None, server_selection_timeout=None)` — `pymongo`'s `socketTimeoutMS` default is `None`, so a read that never returns holds the drain thread; the sink applies `DEFAULT_SOCKET_TIMEOUT` (30 s) only when neither the keyword nor the URI query names one |
 | `PostgresSink` | `log_foundry.sinks.postgres` | `postgres` | `PostgresSink(table, *, dsn="…", create_table=False, connect_timeout=5)` — JSONB `event` column + extracted columns. Reconnects an **owned** connection the server has closed; a `connection=` you inject is never reopened. `connect_timeout` is passed to libpq explicitly, so it **overrides** any `connect_timeout` in your DSN |
-| `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False)` — MergeTree, columnar insert |
+| `ClickHouseSink` | `log_foundry.sinks.clickhouse` | `clickhouse` | `ClickHouseSink(table, *, dsn="…", create_table=False, chunk_size=1000, send_receive_timeout=None)` — MergeTree, columnar insert; the driver's own 300 s `send_receive_timeout` is finite so it is left alone, and forwarded only when you set it |
 
 `PostgresSink` / `ClickHouseSink` default `create_table=False` (you own the schema and indexes); set
 it `True` for an idempotent `CREATE TABLE IF NOT EXISTS` convenience.
@@ -1103,9 +1140,11 @@ reported. They aggregate different failure populations — one can mean the dest
 data; the other never the destination — the data, or no drain thread at all (SPEC-050) — so a
 single number would hide which fix applies.
 
-`h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no worker
-exists yet, or when the configured sink reports nothing (`losses()` is optional, and a sink whose
-`losses()` raises reports `None` too). Note the two `dropped` fields count
+`h.sink` is a `SinkLosses`, carrying `dropped` and `failed`, or `None` — `None` when no sink has
+been configured at all, and `None` when the configured sink reports nothing (`losses()` is
+optional, and a sink whose `losses()` raises reports `None` too). It is **not** `None` merely
+because no worker exists: since SPEC-054 it is answered
+from the configuration, so it reports on the orphan path too. Note the two `dropped` fields count
 different things: the worker's is backpressure at *its* queue, the sink's is an event that never
 reached the wire. They are separate because the remedies do not overlap — and `sink.dropped` is
 itself two causes, which is why the diagnostic line matters. Most sinks drop only what can never
@@ -1133,10 +1172,13 @@ logging is doing the right thing; it is the *pair* — retired, and still being
 means every log line since the shutdown has gone nowhere. That state used to read as perfectly
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
-`retired`, `orphan_lost` and `in_span_lost` are the fields reported for a process that has **no
-worker at all**. A program that only ever calls `info()`/`error()` outside a span emits
-synchronously and builds no background worker, so the rest describe something that does not exist
-and read zero — which is why that path needs counters of its own. Until it had them, such a process
+**Six of the twelve fields report for a process that has no worker at all** — `sink`, `retired`,
+`closing_sinks`, `inherited_sink`, `orphan_lost` and `in_span_lost`. That set is not a list to
+maintain by hand: it is exactly the fields in `_lifecycle`'s `Health(...)` assembly that are *not*
+guarded by `counters is None`, and re-reading that call is how to check it. A program that only
+ever calls `info()`/`error()` outside a span emits synchronously and builds no background worker,
+so the other six describe something that does not exist and read their empty value — zero for the
+five counters, `None` for `stopped_reason` — which is why that path needs counters of its own. Until it had them, such a process
 reported `queued=0 dropped=0 failed_batches=0 stopped_reason=None` over total, permanent loss, and
 the only thing that said otherwise was a line on stderr. Its
 `shutdown()` still closes the sink, exactly once and without starting a thread, and `retired` reads
@@ -1359,7 +1401,7 @@ there. Any ceiling firing sets `truncated: true` on the event.
 length** (sign included) for an integer. They coincide for ASCII digits, and one ceiling for "how
 big may a single value get" was preferred to a second config key. Note that all four ceilings
 bound each *value* — an event of many bounded values can still be large; see
-[Known constraints](docs/architecture.md#known-constraints).
+[Known constraints](https://github.com/agriffi10/log-forge/blob/main/docs/architecture.md#known-constraints).
 
 ## Development
 
@@ -1385,7 +1427,7 @@ The library uses a src layout (`src/log_foundry/`) with a single concept per mod
 the internal `_lifecycle`, `_fork` and `_diag`, and the `sinks/` package (the `base` protocol,
 `stdout`, and one module per sink family — see [Sinks](#sinks)). Anything underscore-prefixed
 is internal and moves without notice.
-Deeper design docs live in [`docs/`](docs/) — start with [`docs/architecture.md`](docs/architecture.md).
+Deeper design docs live in [`docs/`](https://github.com/agriffi10/log-forge/tree/main/docs/) — start with [`docs/architecture.md`](https://github.com/agriffi10/log-forge/blob/main/docs/architecture.md).
 
 ### Continuous integration
 
@@ -1396,14 +1438,14 @@ worth reading before assuming a PR was audited:
 
 | Check | Does | When | Fails the build |
 |---|---|---|---|
-| [`ci.yml`](.github/workflows/ci.yml) | ruff → mypy → pytest, on 3.12 **and** 3.13 | every PR | yes |
-| [`spec-lint.yml`](.github/workflows/spec-lint.yml) | lints the design specs under `docs/specs/` | specs touched | yes |
-| [`dependency-review.yml`](.github/workflows/dependency-review.yml) | fails a PR that *introduces* a dependency with a known advisory (`moderate`+) | every PR | yes |
-| [`zizmor.yml`](.github/workflows/zizmor.yml) | static analysis of the workflow files themselves | workflow, action, dependabot or zizmor config touched; also weekly | no — reports to code scanning |
+| [`ci.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/ci.yml) | ruff → mypy → pytest, on 3.12 **and** 3.13 | every PR | yes |
+| [`spec-lint.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/spec-lint.yml) | lints the design specs under `docs/specs/` | specs touched | yes |
+| [`dependency-review.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/dependency-review.yml) | fails a PR that *introduces* a dependency with a known advisory (`moderate`+) | every PR | yes |
+| [`zizmor.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/zizmor.yml) | static analysis of the workflow files themselves | workflow, action, dependabot or zizmor config touched; also weekly | no — reports to code scanning |
 | CodeQL | `python` + `actions`, `extended` query suite; also weekly | every PR | no — reports to code scanning |
-| [`integration.yml`](.github/workflows/integration.yml) | the extras-backed sinks against nine real services in containers | sinks, `tests/integration/`, `pyproject.toml`, `poetry.lock` or that workflow touched; also weekly | it goes red, and like every check here it is advisory — `main` requires no status check at all, and this one is furthest from earning that: nine service containers are a flakiness budget |
-| [`pip-audit.yml`](.github/workflows/pip-audit.yml) | advisories across every extra, `--strict` | **not on PRs at all** — on the merge to `main` when the lockfile, extras, the ignore list or that workflow moved, and weekly | yes, on `main` |
-| [`scorecard.yml`](.github/workflows/scorecard.yml) | OpenSSF Scorecard over the repository's own supply chain | **not on PRs** — on the merge to `main` when `.github/`, `scripts/`, `SECURITY.md`, `LICENSE` or the lockfile moved, and weekly | no — reports to code scanning |
+| [`integration.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/integration.yml) | the extras-backed sinks against nine real services in containers | sinks, `tests/integration/`, `pyproject.toml`, `poetry.lock` or that workflow touched; also weekly | it goes red, and like every check here it is advisory — `main` requires no status check at all, and this one is furthest from earning that: nine service containers are a flakiness budget |
+| [`pip-audit.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/pip-audit.yml) | advisories across every extra, `--strict` | **not on PRs at all** — on the merge to `main` when the lockfile, extras, the ignore list or that workflow moved, and weekly | yes, on `main` |
+| [`scorecard.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/scorecard.yml) | OpenSSF Scorecard over the repository's own supply chain | **not on PRs** — on the merge to `main` when `.github/`, `scripts/`, `SECURITY.md`, `LICENSE` or the lockfile moved, and weekly | no — reports to code scanning |
 
 **`scripts/docs-lint.sh` is deliberately not in that table**, because nothing in CI runs it. It
 holds the always-loaded documentation tier to its budgets and is a local pre-push gate, so its
@@ -1411,8 +1453,8 @@ failure lands on whoever caused it rather than on a shared branch. Contributors
 with `scripts/spec-lint.sh`, before pushing.
 
 On a push to `main` the full `ci.yml` matrix still runs, but as the first job of
-[`release.yml`](.github/workflows/release.yml), which `uses:` this same workflow before it is
-allowed to publish — so on main the checks are listed under the *Release* workflow, named
+[`release.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/release.yml), which `uses:` this same workflow before it would
+be allowed to publish — so on main the checks are listed under the *Release* workflow, named
 `test / test (py3.12)` and `test / test (py3.13)`. `ci.yml` deliberately carries no `push`
 trigger of its own; it had one, and the result was that every merge ran the identical matrix
 twice. A `v*` tag is gated the same way, by that same reusable call.
@@ -1422,7 +1464,7 @@ why there is no `codeql.yml` here (adding one would disable the default setup an
 the uploads). The two scanners that don't fail a build report findings to code scanning
 deliberately: the alert count is the verdict there, not the green check mark.
 
-[`dependabot.yml`](.github/dependabot.yml) opens scheduled version updates for `pip` and
+[`dependabot.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/dependabot.yml) opens scheduled version updates for `pip` and
 `github-actions` on top of the security updates GitHub raises against advisories. Both ecosystems
 use a cooldown so a freshly published release isn't adopted within hours of appearing, and `pip`
 uses `increase-if-necessary` so an update never narrows a floor this library publishes to its
@@ -1432,7 +1474,7 @@ consumers.
 
 Please report a vulnerability through GitHub's **private** reporting rather than a public issue:
 [**open a draft advisory**](https://github.com/agriffi10/log-forge/security/advisories/new).
-[`SECURITY.md`](SECURITY.md) covers what to include and what to expect — an acknowledgement
+[`SECURITY.md`](https://github.com/agriffi10/log-forge/blob/main/SECURITY.md) covers what to include and what to expect — an acknowledgement
 within 7 days, an assessment within 30. Fixes land on the latest released minor; there are no
 long-term support branches.
 
@@ -1448,7 +1490,7 @@ everything it instruments:
 - **Every release ships a CycloneDX SBOM** as a release asset
   ([latest release](https://github.com/agriffi10/log-forge/releases/latest),
   `log-foundry-X.Y.Z.cdx.json`), describing the published wheel with every extra installed.
-  [`SECURITY.md`](SECURITY.md#software-bill-of-materials) has the detail.
+  [`SECURITY.md`](https://github.com/agriffi10/log-forge/blob/main/SECURITY.md#software-bill-of-materials) has the detail.
 
 Scanning runs continuously rather than at release time: CodeQL over the source and the workflows,
 zizmor over the workflows, `dependency-review` on every pull request, `pip-audit` across all
@@ -1464,17 +1506,20 @@ is published on the advisory database's clock, not on this repository's.
 `poetry-dynamic-versioning`, so `pyproject.toml` carries no literal version and the published
 number can't drift from what Git says.
 
-[`release.yml`](.github/workflows/release.yml) reuses the CI suite as a gate, then builds an
+[`release.yml`](https://github.com/agriffi10/log-forge/blob/main/.github/workflows/release.yml) reuses the CI suite as a gate, then builds an
 sdist and a wheel:
 
 | Trigger | Version built | Published to PyPI as |
 |---|---|---|
-| merge to `main` | `X.Y.Z.devN` | dev pre-release |
+| merge to `main` | `X.Y.Z.devN` | **nothing, for now** — `publish-dev` is disabled |
 | push tag `vX.Y.Z` | `X.Y.Z` | stable release |
 
-Dev pre-releases keep the upload path exercised on every merge, so a real release is never the
-first time it runs. `pip install log-foundry` still resolves to the latest **stable** version —
-pip ignores pre-releases unless you pass `--pre`.
+Dev pre-releases **kept** the upload path exercised on every merge, so a real release was never
+the first time it ran. That property is suspended along with the job, so **every** tag is now the
+first upload attempted since the previous one — `v1.0.0` was the first to sit in that position
+after `publish-dev` was disabled, and it succeeded, but nothing between releases exercises the
+path any more, so the next tag is always exposed the same way. `pip install log-foundry` resolves
+to the latest **stable** version either way — pip ignores pre-releases unless you pass `--pre`.
 
 Cutting a release is one tag:
 
@@ -1489,9 +1534,12 @@ one from the commit range. Both are valid, but the lookup is by exact tag name a
 takes the tag, so notes written for one version do nothing for another and notes added after
 the tagged commit are not seen. A release body cannot be amended once published — this
 repository has immutable releases — so check the file is there and named for the tag before
-pushing it. [`docs/release-notes/`](docs/release-notes/) holds the ones written so far, and
-[`docs/spec-delivery/RELEASES.md`](docs/spec-delivery/RELEASES.md) records which specs each
-released version carried.
+pushing it. **Add the version's section to [`CHANGELOG.md`](https://github.com/agriffi10/log-forge/blob/main/CHANGELOG.md) in the same commit** —
+it is user-facing and no gate holds it to the tags, so it goes stale by being forgotten.
+[`docs/release-notes/`](https://github.com/agriffi10/log-forge/tree/main/docs/release-notes/) holds the notes written so far, and
+[`docs/spec-delivery/RELEASES.md`](https://github.com/agriffi10/log-forge/blob/main/docs/spec-delivery/RELEASES.md) records which specs each
+version carried — its top row is written in the commit that version's tag is cut from, so it can
+name a tag that does not exist yet.
 
 Uploads authenticate with PyPI [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
 (OIDC) through the `pypi` GitHub Environment — there is no API token stored in the repository.
@@ -1505,5 +1553,5 @@ deliberately off the rolling `release/v1` branch PyPA recommends, because this i
 
 ## License
 
-[MIT](LICENSE) © Andrew Griffith
+[MIT](https://github.com/agriffi10/log-forge/blob/main/LICENSE) © Andrew Griffith