log-foundry 0.10.2.dev128__tar.gz → 1.0.0__tar.gz

{log_foundry-0.10.2.dev128 → log_foundry-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev128
+Version: 1.0.0
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -578,7 +578,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 +893,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 +909,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.
@@ -1086,7 +1087,7 @@ They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
 |---|---|---|
-| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
+| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. It counts **submissions** — one per span close, or per open span a `flush()` sweeps — so the events lost are a multiple of it. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
 | `failed_batches` | A sink stayed broken through the whole retry budget. Delivery continues. | Fix the destination. |
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
@@ -1095,16 +1096,19 @@ They tell you different things, and they want different responses:
 | `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 | `inherited_sink` | This process is delivering to a sink it **inherited across a `fork`** and may not release, so it will not be closed here. Not a loss and not an alert term. | Nothing, usually. It explains a handle still open after `shutdown()`, and tells you a deployment shares one sink across a fork at all. `True` for a shared `StdoutSink` too, whose `close()` only flushes — so a `True` is not by itself evidence that anything is held. If you want the child to own its transport, build the sink in the worker process (see Forking). |
 | `orphan_lost` | An event logged **with no open span** never reached the sink. That call emits on your own thread with no worker behind it, so no other field here can carry it — it is not a batch, there was no retry, and there may be no worker at all. Covers a sink that failed to *construct* as well as one that raised. | Fix the destination, or the data. The stderr line names the exception type. If a process logs this way at all, this is the field to alert on: nothing else describes that path. |
-| `in_span_lost` | An event logged **inside a span** could not be built — a value that could not be turned into an event. Always the data, never the destination: the in-span path cannot fail at delivery, which is `failed_batches`. | Fix the call site. Passing a non-string message (an exception object, say) is the common cause. |
+| `in_span_lost` | An event logged **inside a span** was lost before delivery, for one of two reasons the count tells apart: **the data** — a value that could not be turned into an event, one per call — or **no drain thread at all** — the process could not start the worker, and the span's whole buffer is counted at once (SPEC-050). Never a destination that failed at delivery; that is `failed_batches`. | One event at a time: fix the call site — a non-string message (an exception object, say) is the common cause. A whole buffer at once: the process cannot start a thread; the stderr line names it. |
 | `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter. It and `queued` are the two fields here that fall as well as rise; the other integer counters only climb. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `orphan_lost` and `in_span_lost` are deliberately two fields and their sum is deliberately not
 reported. They aggregate different failure populations — one can mean the destination *or* the
-data, the other can only mean the data — 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
+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 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
@@ -1132,10 +1136,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
@@ -1410,8 +1417,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`](.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.
@@ -1468,12 +1475,14 @@ 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: the next `vX.Y.Z` tag is
+the first attempt at the upload path since `publish-dev` was disabled. `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:
 
@@ -1490,7 +1499,8 @@ the tagged commit are not seen. A release body cannot be amended once published
 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.
+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.

{log_foundry-0.10.2.dev128 → log_foundry-1.0.0}/README.md

@@ -527,7 +527,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`.
 
@@ -841,8 +842,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)` |
 
@@ -857,9 +858,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.
@@ -1035,7 +1036,7 @@ They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
 |---|---|---|
-| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
+| `dropped` | The queue filled — the destination is not keeping up. Delivery continues. It counts **submissions** — one per span close, or per open span a `flush()` sweeps — so the events lost are a multiple of it. | Make the destination keep up: scale the sink, or reduce what you log. The worker's batch size, flush interval and queue depth are **not** reachable from the public API, so tuning them is not an option this version offers you. |
 | `failed_batches` | A sink stayed broken through the whole retry budget. Delivery continues. | Fix the destination. |
 | `stopped_reason` | The background thread **died** on that exception type. Nothing further will be delivered, ever. | Restart the process; investigate the named exception. |
 | `sink.dropped` | The sink discarded events **before** attempting delivery — an oversized record, or one the client refused outright. | Read the stderr line: it names the cause. An oversized record means shrink what you log; a refused local produce/publish (Kafka, Pub/Sub) points at the client — a saturated buffer, a bad topic, a credential. |
@@ -1044,16 +1045,19 @@ They tell you different things, and they want different responses:
 | `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
 | `inherited_sink` | This process is delivering to a sink it **inherited across a `fork`** and may not release, so it will not be closed here. Not a loss and not an alert term. | Nothing, usually. It explains a handle still open after `shutdown()`, and tells you a deployment shares one sink across a fork at all. `True` for a shared `StdoutSink` too, whose `close()` only flushes — so a `True` is not by itself evidence that anything is held. If you want the child to own its transport, build the sink in the worker process (see Forking). |
 | `orphan_lost` | An event logged **with no open span** never reached the sink. That call emits on your own thread with no worker behind it, so no other field here can carry it — it is not a batch, there was no retry, and there may be no worker at all. Covers a sink that failed to *construct* as well as one that raised. | Fix the destination, or the data. The stderr line names the exception type. If a process logs this way at all, this is the field to alert on: nothing else describes that path. |
-| `in_span_lost` | An event logged **inside a span** could not be built — a value that could not be turned into an event. Always the data, never the destination: the in-span path cannot fail at delivery, which is `failed_batches`. | Fix the call site. Passing a non-string message (an exception object, say) is the common cause. |
+| `in_span_lost` | An event logged **inside a span** was lost before delivery, for one of two reasons the count tells apart: **the data** — a value that could not be turned into an event, one per call — or **no drain thread at all** — the process could not start the worker, and the span's whole buffer is counted at once (SPEC-050). Never a destination that failed at delivery; that is `failed_batches`. | One event at a time: fix the call site — a non-string message (an exception object, say) is the common cause. A whole buffer at once: the process cannot start a thread; the stderr line names it. |
 | `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter. It and `queued` are the two fields here that fall as well as rise; the other integer counters only climb. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `orphan_lost` and `in_span_lost` are deliberately two fields and their sum is deliberately not
 reported. They aggregate different failure populations — one can mean the destination *or* the
-data, the other can only mean the data — 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
+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 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
@@ -1081,10 +1085,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,8 +1366,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`](.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.
@@ -1417,12 +1424,14 @@ 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: the next `vX.Y.Z` tag is
+the first attempt at the upload path since `publish-dev` was disabled. `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:
 
@@ -1439,7 +1448,8 @@ the tagged commit are not seen. A release body cannot be amended once published
 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.
+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.

{log_foundry-0.10.2.dev128 → log_foundry-1.0.0}/pyproject.toml

@@ -30,9 +30,11 @@ dependencies = [
 classifiers = [
     # Asserts what the NEXT STABLE TAG will be, not what the current version is. Safe only
     # because PyPI's default project page renders the latest stable release, which is still
-    # `v0.10.1` and carries none of this; the artifacts carrying it in the meantime are the
-    # `.devN` pre-releases that SECURITY.md declares unsupported and that `pip install` does
-    # not select. Their own per-version pages DO show it, so this is narrow, not free.
+    # `v0.10.1` and carries none of this. The artifacts that carried it in the meantime were the
+    # `.devN` pre-releases SECURITY.md declares unsupported and `pip install` does not select;
+    # their own per-version pages DO show it, so this was narrow rather than free. With
+    # `publish-dev` disabled no new artifact carries it at all, which narrows the exposure
+    # further — the claim is not more true, it just reaches nobody until the next tag.
     # Revisit if the next stable tag is not `v1.0.0`: README still says three public shapes
     # change once, before the API is frozen, and Production/Stable on the default page would
     # then contradict it.
@@ -74,7 +76,7 @@ keywords = [
 # vulnerability-reporting channel. The repository is still named `log-forge` — the ORIGINAL name,
 # which PyPI rejected for the distribution — so these URLs deliberately do not match the package
 # name. See the note on `name` above before "correcting" them.
-version = "0.10.2.dev128"
+version = "1.0.0"
 
 [project.urls]
 Homepage = "https://github.com/agriffi10/log-forge"

{log_foundry-0.10.2.dev128 → log_foundry-1.0.0}/src/log_foundry/__init__.py

@@ -87,8 +87,8 @@ def health() -> Health:
     an event that cannot be *built* never reaches a queue at all — so every other field here
     describes machinery those two losses never touched, and a process that only logs outside a
     span read all zeros over total loss until they existed. They stay separate because one can
-    mean the destination or the data and the other can only mean the data; their sum is a number
-    nobody can act on.
+    mean the destination or the data and the other never the destination — the data, or no drain
+    thread at all (SPEC-050 FR-003); their sum is a number nobody can act on.
 
     ``retired`` alone is not a fault — a process that shuts down and then stops logging is
     doing the right thing, which is why it is paired with the count rather than alerted on.