D-SafeLogger 0.2.2__tar.gz → 0.3.0__tar.gz

{d_safelogger-0.2.2 → d_safelogger-0.3.0}/BENCHMARK.md

@@ -14,7 +14,7 @@ D-SafeLogger is competitive in single-process logging, especially in async mode
 
 Multiprocess results should be interpreted differently. D-SafeLogger is not the fastest multiprocess backend in this benchmark; stdlib logging leads throughput in all measured multiprocess performance cells. D-SafeLogger's multiprocess value is not raw speed. Its value is Writer-owned sinks, explicit attach/detach, bounded shutdown, and classified delivery-state observability under operational stress.
 
-The resilience profile is the strongest multiprocess evidence. Across 12 D-SafeLogger resilience summary rows, D-SafeLogger produced classified loss/reject/drop fields for 12/12 rows and fully explained 12/12 rows. That is the benchmark-backed claim: D-SafeLogger can explain what happened to records under backpressure, sink rejection, and mixed worker shutdown, instead of leaving delivery state ambiguous.
+The resilience profile is the strongest multiprocess evidence. Across 16 D-SafeLogger resilience summary rows, D-SafeLogger produced classified loss/reject/drop fields for 16/16 rows and fully explained 16/16 rows. That is the benchmark-backed claim: D-SafeLogger can explain what happened to records under backpressure, sink rejection, mixed worker shutdown, and warning-IPC fallback, instead of leaving delivery state ambiguous.
 
 ## Published Summaries
 
@@ -30,7 +30,7 @@ The resilience profile is the strongest multiprocess evidence. Across 12 D-SafeL
 | Single-process | `benchmark_20260506_180018` | Throughput and latency comparison across D-SafeLogger, stdlib logging, loguru, and structlog |
 | Multiprocess integrity | `benchmarks_multi_integ_20260506_185947` | Normal-condition delivery completeness and JSON/route integrity |
 | Multiprocess performance | `benchmarks_multi_perf_20260506_190518` | Raw multiprocess throughput and latency comparison |
-| Multiprocess resilience | `benchmarks_multi_resilience_20260506_211129` | Operational failure-mode observability and classified delivery state |
+| Multiprocess resilience | `benchmarks_multi_resilience_20260523_084326` | Operational failure-mode observability and classified delivery state |
 
 The selected sessions are controlled by [`benchmarks/summary/manifest.json`](benchmarks/summary/manifest.json). Running a new benchmark does not automatically change the public analysis.
 
@@ -112,27 +112,38 @@ The resilience profile measures what can be explained during operational stress.
 
 Selected result summary:
 
-- D-SafeLogger produced classified loss/reject/drop fields for 12/12 summary rows.
-- D-SafeLogger fully explained 12/12 summary rows.
+- D-SafeLogger produced classified loss/reject/drop fields for 16/16 summary rows.
+- D-SafeLogger fully explained 16/16 summary rows.
 - stdlib logging and loguru rows are marked `observability_gap` where accepted/dropped/unexplained state cannot be classified by the benchmarked backend contract.
 
 Representative D-SafeLogger rows:
 
 | Scenario | Python/GIL | Attempted | Accepted | Delivered | KnownRejected | KnownDropped | UnexplainedLost | Shutdown |
 |---|---|---:|---:|---:|---:|---:|---:|---|
-| burst_backpressure | 3.13/enabled | 100 | 100 | 99 | 0 | 1 | 0 | clean |
-| burst_backpressure | 3.14/enabled | 100 | 100 | 100 | 0 | 0 | 0 | clean |
-| burst_backpressure | 3.14/disabled | 100 | 100 | 100 | 0 | 0 | 0 | clean |
-| rolling_restart_mixed_shutdown | all measured | 62 | 62 | 62 | 0 | 0 | 0 | clean_with_worker_crash |
+| burst_backpressure | all measured | 100 | 100 | 100 | 0 | 0 | 0 | clean |
+| ipc_forced_disconnect | all measured | 100 | 100 | 100 | 0 | 0 | 0 | clean |
+| rolling_restart_mixed_shutdown | all measured | 50 | 62 | 62 | 0 | 0 | 0 | clean_with_worker_crash |
 | sink_temporarily_unavailable | all measured | 100 | 100 | 0 | 100 | 0 | 0 | clean |
 
 Interpretation:
 
 - In backpressure scenarios, D-SafeLogger may drop records, but the drops are classified as known drops rather than unexplained loss.
+- In warning-IPC fallback scenarios, D-SafeLogger records per-worker fallback warning files while preserving delivery accounting.
 - In mixed shutdown scenarios, D-SafeLogger can distinguish a clean writer shutdown with worker crash/termination from unexplained record loss.
+- In mixed shutdown rows, `attempted` can be lower than `accepted` because a crashed worker may enqueue records before it can report its local attempted count via DETACH. `clean_with_worker_crash` and `snapshot_complete=false` mark that attempted-side worker accounting is incomplete.
 - In sink-unavailable scenarios, D-SafeLogger classifies rejected records as known sink rejects rather than reporting ambiguous loss.
 - This is the core multiprocess claim: D-SafeLogger does not promise impossible failure-free logging; it promises explicit accounting of what happened.
 
+### Console-less Observability
+
+The resilience benchmark now reads D-SafeLogger delivery state through the public `dsafelogger.mp.GetDeliveryStatus()` API instead of a Writer runtime private method. The benchmark records the public accounting schema, including `writer_reject_breakdown`, `worker_drop_breakdown`, `writer_drop_breakdown`, and `partial_delivered` as a separate non-reject category.
+
+`partial_delivered` is a third terminal state: it is neither `delivered` (all required sinks succeeded) nor `known_rejected` (zero required sinks succeeded). The writer-side invariant is `accepted = delivered + partial_delivered + known_rejected + writer_known_dropped + unexplained_lost`.
+
+For new resilience sessions, D-SafeLogger also enables `runtime_warning_path` and `shutdown_report_path` in the benchmark scratch directory. Runtime warnings are emitted to an independent JSON Lines sink, and shutdown reports provide an atomic final snapshot for post-run diagnosis without requiring console output. Workers that cannot reach the Writer warning IPC path fall back to per-pid local files named `<runtime_warning_path>.<pid>.fallback.jsonl`; console-less deployments should collect both the primary warning file and any fallback files.
+
+See [`docs/design/v23k_supplements/delivery_status_schema.md`](docs/design/v23k_supplements/delivery_status_schema.md) for the authoritative accounting contract.
+
 ## What To Claim
 
 - D-SafeLogger has zero runtime dependencies.
@@ -141,6 +152,7 @@ Interpretation:
 - D-SafeLogger async is competitive in single-process logging and leads several low-latency cells in the selected benchmark.
 - D-SafeLogger multiprocess mode centralizes sink ownership in a Writer runtime.
 - D-SafeLogger multiprocess resilience profiling exposes classified delivery-state counters: attempted, accepted, delivered, known rejected, known dropped, and unexplained lost.
+- D-SafeLogger multiprocess observability can be consumed without console output through `GetDeliveryStatus()`, runtime warning JSON Lines, and shutdown report JSON.
 
 ## What Not To Claim
 

{d_safelogger-0.2.2 → d_safelogger-0.3.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-23
+
+### Added
+- Multiprocess observability artifacts: `mp.GetDeliveryStatus()` / `DeliveryStatus`, `runtime_warning_path` JSON Lines output with per-pid worker fallback files, and `shutdown_report_path` JSON shutdown reports.
+- Tests for runtime warning output, shutdown report generation, public delivery-status snapshots, writer/worker accounting invariants, and runtime-vs-shutdown missing-detach semantics.
+- v23k public design documents and supplements for delivery status schema, runtime warning design, and multiprocess observability test coverage.
+
+### Changed
+- Multiprocess resilience benchmark summaries now use the public `mp.GetDeliveryStatus()` schema, keep `partial_delivered` separate from `known_rejected`, include writer/worker drop/reject breakdowns, and record runtime warning fallback files plus shutdown-report crash fields.
+- Public multiprocess docs now describe console-less observability through status snapshots, runtime warning JSON Lines, and shutdown report JSON instead of relying on stderr-only guidance.
+
 ## [0.2.2] - 2026-05-21
 
 ### Added

{d_safelogger-0.2.2 → d_safelogger-0.3.0}/MANIFEST.in

@@ -27,8 +27,8 @@ include benchmarks/results/benchmarks_multi_integ_20260506_185947/summary.json
 include benchmarks/results/benchmarks_multi_integ_20260506_185947/summary.md
 include benchmarks/results/benchmarks_multi_perf_20260506_190518/summary.json
 include benchmarks/results/benchmarks_multi_perf_20260506_190518/summary.md
-include benchmarks/results/benchmarks_multi_resilience_20260506_211129/summary.json
-include benchmarks/results/benchmarks_multi_resilience_20260506_211129/summary.md
+include benchmarks/results/benchmarks_multi_resilience_20260523_084326/summary.json
+include benchmarks/results/benchmarks_multi_resilience_20260523_084326/summary.md
 
 prune .claude
 prune .github

{d_safelogger-0.2.2/src/D_SafeLogger.egg-info → d_safelogger-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: D-SafeLogger
-Version: 0.2.2
+Version: 0.3.0
 Summary: Zero-dependency, thread-safe, append-only logging library for Python with 3-layer config pipeline
 Author: D
 License-Expression: Apache-2.0
@@ -31,19 +31,37 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/d-safelogger.svg?cacheSeconds=3600)](https://pypi.org/project/d-safelogger/)
 [![Python](https://img.shields.io/pypi/pyversions/d-safelogger.svg?cacheSeconds=3600)](https://pypi.org/project/d-safelogger/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#main-features)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#highlights)
 
 Languages: [English](README.md) | [日本語](README_ja.md)
 
-## Overview
-
 D-SafeLogger is a zero-dependency, stdlib logging-compatible logger built on Python's standard `logging` module.
 
-It extends the standard logging path instead of replacing it. Existing `logging.getLogger()` and `logger.info()` call sites can participate without modification, while D-SafeLogger adds append-only file routing, structured JSON Lines output, contextual logging, SHA-256 sidecars, environment-based operational overrides, and Writer-owned multiprocess logging.
+It extends the standard logging path instead of replacing it, so existing application code and third-party library logs can stay on the stdlib logging path. It is intended for Python applications that need local file logging to start small in development and become explicit, inspectable, and operationally controlled for services, scheduled jobs, audit-oriented logs, and multiprocess workers.
+
+## Highlights
+
+1. **Stdlib `logging` compatible.** Existing `logger.info()` call sites and third-party libraries using `logging.getLogger()` participate without modification.
+
+2. **Append-only routing, no rename.** D-SafeLogger opens the next destination file instead of renaming or truncating the active log. This avoids the Windows file-lock failure mode of rename-based rotation and the POSIX case where a successful rename can leave the writer attached to the previous file descriptor.
+
+3. **Zero runtime dependencies.** The runtime package uses only the Python standard library. No extra runtime dependency chain is added to your application.
 
-Append-only routing means D-SafeLogger opens the next destination file instead of renaming or truncating the active log file. This avoids the common Windows file-lock failure mode of rename-based rotation. It also sidesteps the POSIX failure mode where a rename succeeds at the filesystem layer while existing file descriptors keep writing to the previous file.
+4. **Start in three lines, add policy through configuration.** A minimal setup is three lines. The same call sites can stay in place while configuration adds 9 routing strategies (`daily`, `hourly`, `size`, and more), JSON Lines, SHA-256 sidecars and manifests, sensitive-keyword masking, diagnostic mode, and code / INI-dict / environment deployment layers.
 
-The "Safe" in the name refers to operational safety: fail-fast setup, append-only file handling, producer-side context snapshots, bounded queues, explicit timeouts, and classified delivery-state accounting.
+5. **Robust and flexible multiprocess logging.** A parent-side Writer owns file output while workers submit records over IPC. Process, Pool, and ProcessPoolExecutor patterns are covered, with delivery outcomes classified instead of hidden.
+
+## When to Use It
+
+Use D-SafeLogger when you want to keep standard `logging.getLogger()` call sites while adding:
+
+- append-only local file routing,
+- environment-driven operational overrides,
+- optional SHA-256 sidecars and manifests,
+- Writer-owned multiprocess file output,
+- classified delivery-state accounting.
+
+You probably do not need it if your application only writes to stdout/stderr and an external collector owns routing, retention, aggregation, and durability.
 
 ## Installation
 
@@ -90,43 +108,36 @@ For multiprocess setup, see [Multiprocess Logging](#multiprocess-logging). For I
 
 Configuration is fail-fast. D-SafeLogger rejects feature combinations that cannot take effect, such as cyclic routing with hash/archive retention, `routing_mode='none'` with D-SafeLogger-owned retention, or `structured=True` with custom formatter strings.
 
-## When to Use It
-
-Use D-SafeLogger when you want to keep standard `logging.getLogger()` call sites while adding:
-
-- append-only local file routing,
-- environment-driven operational overrides,
-- optional SHA-256 sidecars and manifests,
-- Writer-owned multiprocess file output,
-- classified delivery-state accounting.
-
-You probably do not need it if your application only writes to stdout/stderr and an external collector owns routing, retention, aggregation, and durability.
-
 ## Why D-SafeLogger?
 
-D-SafeLogger extends the standard logging path rather than replacing it: you keep using `logging.getLogger()` and existing `logger.info()` call sites, and the library adds safe local-file output on top: rename-free append-only routing, fail-fast configuration, SHA-256 sidecars, sensitive-data masking, environment-driven operational control, and a parent-side multiprocess Writer.
+D-SafeLogger extends the standard logging path rather than replacing it: you keep using `logging.getLogger()` and existing `logger.info()` call sites, and the library adds safe local-file output on top.
 
-If you already use `structlog` as a structured-logging frontend, D-SafeLogger coexists rather than replaces. `structlog` builds the event dictionary; D-SafeLogger handles file output, routing, sidecars, masking, and operational control. See [Structlog Coexistence](examples/16_structlog_coexistence.md) for two integration patterns.
+That matters when an application already has stdlib logging calls, or depends on libraries that emit through `logging.getLogger()`. D-SafeLogger lets those records enter the same routing, formatting, context, integrity, async, and multiprocess Writer path without forcing a new application-wide logging API.
+
+If you already use `structlog` as a structured-logging frontend, D-SafeLogger coexists rather than replaces it. `structlog` builds the event dictionary; D-SafeLogger handles file output, routing, sidecars, masking, and operational control. See [Structlog Coexistence](examples/16_structlog_coexistence.md) for two integration patterns.
 
 ## Why Routing Instead of External Rotation?
 
 External rotation typically renames or truncates an active log file, creates a replacement, and asks the application to reopen its sink. That is plumbing for a design that mutates the active file after the fact, not the core of writing log records.
 
-On POSIX systems, the rename can succeed even while the writer keeps writing through the old file descriptor. The filesystem call returned success, but the logger never actually moved to the new file.
+On Windows, active-file rename can fail because the writer still holds the file. On POSIX systems, the rename can succeed while the writer keeps writing through the old file descriptor. The filesystem call returned success, but the logger never actually moved to the new file.
 
 D-SafeLogger avoids that dependency by choosing the destination at write time. It opens the next destination at the routing boundary instead of mutating the active file and relying on a signal/reopen handshake.
 
 ## What "Safe" Means
 
-The "Safe" in the name is a design stance that runs across several dimensions of everyday operation, not only failure handling:
+"Safe" is not a promise that every record survives every possible failure. It is a design stance for reducing avoidable logging failures and making observable failures explainable.
+
+| Dimension | Meaning |
+|---|---|
+| Startup safety | Invalid settings, inconsistent options, and unwritable destinations fail during setup before the application starts doing real work. |
+| File safety | Routed log files are treated as append-only artifacts with an explicit lifecycle: active writing, closed routed file, optional SHA-256 sidecar, optional manifest, and downstream transfer or archive. Integrity support is for closed-file verification, not access control. |
+| Record and context safety | Context is snapshotted on the producer side at hand-off; diagnostics and Writer-side formatting use the sensitive-keyword set established at configure time. |
+| Operational control | Runtime overrides are intentionally explicit and operator-owned. Log levels, routing, hashing, and timeout behavior can be changed without rebuilding, while diagnostic local-variable expansion is limited to environment-variable opt-in and cannot be enabled by an unowned INI file. |
+| Concurrency and multiprocess safety | Cross-thread and cross-process logging paths use bounded queues, explicit timeouts, rejection/drop paths, and shutdown drain limits. The design favors hard ceilings over indefinite waiting. |
+| Delivery visibility | Abnormal delivery outcomes remain visible through `mp.GetDeliveryStatus()`, runtime warning JSON Lines, and shutdown report JSON. Even `UnexplainedLost` is preserved as an explicit state, so abnormal runs do not collapse into “the file is just shorter than expected.” |
 
-- **Startup safety:** invalid settings, inconsistent options, and unwritable destinations fail during setup. D-SafeLogger stops a broken logging configuration before the application starts doing real work, instead of silently degrading later.
-- **File safety:** the routing layer opens the next destination instead of renaming or truncating the active log file, which avoids the common Windows failure mode where active log files cannot be renamed. It also avoids the POSIX case where a successful rename leaves the writer appending to the previous file. Routed files can be paired with SHA-256 sidecars and an optional manifest, so log content is verifiable after the fact.
-- **Record and context safety:** request IDs, user IDs, job IDs, and other context are snapshotted on the producer side at hand-off, so listeners and Writers do not depend on live `contextvars`. Diagnostic local-variable snapshots and Writer-side formatting use the sensitive-keyword set established at configure time.
-- **Operational control:** environment variables provide explicit runtime overrides for diagnostics, routing, hashing, log levels, and queue/timeout behavior without rebuilding or editing application code.
-- **Concurrency and multiprocess safety:** multiprocess workers do not open the shared log files themselves. A parent-side Writer owns the sinks and accepts records over IPC, with bounded queues and explicit timeouts that keep the host process from unbounded waits.
-- **Failure observability:** when records cannot be delivered, the runtime classifies the outcome where it can: `KnownRejected`, `KnownDropped`, or `UnexplainedLost`. Counters and shutdown summaries make abnormal scenarios describable rather than silent.
-- **Filesystem scope:** append-only routing avoids external rename/truncate of active log files. It does not make every destination filesystem equally safe. NFS, SMB/CIFS, FUSE mounts, cloud-synced folders, container bind mounts, and in-memory filesystems can have different rename, unlink, cache, durability, or lifetime semantics. For audit-oriented deployments, prefer writing active logs to a durable local filesystem and transferring closed routed files to archive or network storage.
+Append-only routing avoids external rename/truncate of active log files. It does not make every destination filesystem equally safe. NFS, SMB/CIFS, FUSE mounts, cloud-synced folders, container bind mounts, and in-memory filesystems can have different rename, unlink, cache, durability, or lifetime semantics. For audit-oriented deployments, prefer writing active logs to a durable local filesystem and transferring closed routed files to archive or network storage.
 
 ## Feature Comparison
 
@@ -173,39 +184,21 @@ Notes:
 - **※9** loguru's `enqueue=True` provides queued, multiprocessing-safe logging, but it is not a parent-side Writer ownership model and does not expose D-SafeLogger-style delivery-state accounting.
 - **※10** stdlib logging can be assembled into a listener/queue architecture, but this is not a packaged parent-side Writer API.
 
-**Delivery-state accounting** refers to per-record classification (`KnownRejected`, `KnownDropped`, `UnexplainedLost`) exposed through counters and shutdown summaries. See [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md) and [BENCHMARK.md](BENCHMARK.md).
-
-## Main Features
-
-- **Zero runtime dependencies:** the package uses only the Python standard library at runtime.
-- **Stdlib logging compatibility:** existing `logger.info()` calls and libraries that use `logging.getLogger()` participate in the same logging setup.
-- **Centralized setup:** replace common `basicConfig()`, `dictConfig()`, formatter, handler, and rotating-file boilerplate with `ConfigureLogger()`.
-- **Fail-fast initialization:** invalid configuration and unwritable log destinations fail during setup instead of degrading silently.
-- **Append-only file routing:** the routing layer opens the next destination instead of renaming or truncating the active log file. This avoids the common Windows failure mode where active log files cannot be renamed, and it avoids the POSIX case where a writer may continue writing to the previous file after a successful rename.
-- **Retention for routed files:** routed files can be kept by `backup_count`; older files can be deleted by the purge worker or ZIP-archived with `archive_mode=True`.
-- **Classified delivery state:** loss, reject, and drop events are not treated as invisible file gaps. When records cannot be delivered, the runtime classifies the outcome as known-rejected, known-dropped, or unexplained-lost where applicable.
-- **Bounded logging path:** D-SafeLogger uses bounded queues, explicit timeouts, and explicit rejection paths to avoid unbounded logging-side waits in the host process.
-- **Structured JSON Lines:** emit log records as JSON fields for log collectors and observability pipelines.
-- **Contextual logging:** attach request IDs, user IDs, job IDs, or other context with thread-safe and async-safe propagation. Producer-side context snapshots are taken at hand-off so listeners and Writers do not look up live `contextvars`.
-- **Integrity sidecars:** generate SHA-256 sidecars and optional manifest entries for routed log files. This is tamper-evidence for closed files, not an access-control or compliance system.
-- **Operational overrides:** change log level, module routing, console output, color, hashing, config file path, and queue/timeout parameters through environment variables, typically to raise diagnostics in production without code changes.
-- **Environment-only diagnostic mode:** opt in via `D_LOG_DIAGNOSE=1` for `f_locals` expansion of selected frames; deliberately not exposed through INI or arguments, so it cannot be enabled by an unowned configuration file.
-- **Async transport:** opt in to queue-backed logging when application threads should avoid direct sink writes.
-- **Custom log levels:** `register_level()` to add named levels alongside the built-in five before `ConfigureLogger()`.
-- **External rotation reopen:** `ReopenLogFiles()` and its multiprocess equivalent reopen sinks after external log rotators such as `logrotate`.
-- **Delivery-state visibility (multiprocess):** worker logging exposes per-record delivery-state counters and shutdown summaries, so abnormal shutdowns, sink unavailability, and worker crashes are described rather than silent.
+**Delivery-state accounting** refers to per-record classification (`KnownRejected`, `KnownDropped`, `UnexplainedLost`, plus `partial_delivered`) exposed through `mp.GetDeliveryStatus()`, runtime warning JSON Lines, and shutdown report JSON. See [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md), [`docs/design/v23k_supplements/delivery_status_schema.md`](docs/design/v23k_supplements/delivery_status_schema.md), and [BENCHMARK.md](BENCHMARK.md).
 
 ## Multiprocess Logging
 
 `dsafelogger.mp` is for applications where multiple worker processes need to send logs to shared destinations without each worker independently opening the same files.
 
-In this mode, a parent-side Writer owns the file sinks. Workers attach to the Writer and submit log records through IPC. This centralizes file ownership and exposes delivery-state counters such as accepted, delivered, rejected, dropped, and unexplained-lost.
+In this mode, a parent-side Writer owns the file sinks. Workers attach to the Writer and submit log records through IPC. This centralizes file ownership and exposes delivery-state counters such as attempted, accepted, delivered, partial-delivered, known-rejected, known-dropped, and unexplained-lost.
+
+The public API is designed for three common worker patterns: `multiprocessing.Process`, `multiprocessing.Pool`, and `concurrent.futures.ProcessPoolExecutor`. The same Writer session can be bootstrapped into each pattern through explicit attach calls or the `GetWorkerInitializer()` helper used by pools and executors.
 
-The Writer shutdown path is bounded: it attempts to drain and join within a timeout, emits a visible warning if drain is incomplete, and avoids hanging the host process indefinitely.
+The Writer shutdown path is bounded: it attempts to drain and join within a timeout, records runtime warnings when configured, writes a shutdown report when configured, and avoids hanging the host process indefinitely.
 
 For setup code, the `multiprocessing` context rules, pool initializer, `ProcessPoolExecutor` integration, Windows spawn caveats, custom log levels, attach/detach lifecycle, environment-variable knobs, and shutdown handling, see [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md).
 
-Public API in `dsafelogger.mp`: `ConfigureLogger`, `AttachCurrentProcess`, `DetachCurrentProcess`, `GetLogger`, `GetWorkerInitializer`, `ReopenLogFiles`.
+Public API in `dsafelogger.mp`: `ConfigureLogger`, `AttachCurrentProcess`, `DetachCurrentProcess`, `GetLogger`, `GetWorkerInitializer`, `GetDeliveryStatus`, `DeliveryStatus`, `ReopenLogFiles`.
 
 ## Configuration
 
@@ -222,7 +215,7 @@ Common environment overrides, using the default `D_LOG_*` prefix; the prefix is
 - Single-process: `D_LOG_LEVEL`, `D_LOG_MODULES`, `D_LOG_CONFIG`, `D_LOG_DIAGNOSE`, `D_LOG_CONSOLE`, `D_LOG_COLOR`, `D_LOG_HASH`, `D_LOG_MANIFEST`, plus the industry-standard `NO_COLOR`, which is not affected by `env_prefix`.
 - Multiprocess (`dsafelogger.mp`): `D_LOG_IPC_LOG_TIMEOUT`, `D_LOG_IPC_LOG_QUEUE_MAXSIZE`, `D_LOG_IPC_CLIENT_QUEUE_MAXSIZE`, `D_LOG_WRITER_FLUSH_BATCH`. These tune backpressure behavior and are normally left at defaults.
 
-See [Configuration Guide](examples/02_configuration_guide.md) for INI files, dict configuration, module-specific routing, and precedence rules.
+See [Configuration Guide](examples/02_configuration_guide.md) for INI files, dict configuration, module-specific routing, and precedence rules. For routing-mode selection, purge/archive retention, and long-running file lifecycle examples, see [Long-Running Service](examples/07_long_running_service.md).
 
 ## Tutorials / Examples
 
@@ -259,13 +252,13 @@ Suggested reading paths:
 
 D-SafeLogger is competitive in the selected single-process async benchmark runs. In multiprocess benchmarks, raw throughput is not the differentiator; parent-side file output and classified delivery-state accounting are.
 
-The benchmark suite also includes multiprocess resilience profiles, such as sink-unavailable, burst backpressure, worker crash, mixed worker behavior, and shutdown behavior. These runs are not throughput claims; they check whether attempted records can be accounted for as delivered, known-rejected, known-dropped, or unexplained-lost.
+The benchmark suite also includes multiprocess resilience profiles, such as sink-unavailable, burst backpressure, worker crash, warning-IPC fallback, mixed worker behavior, and shutdown behavior. These runs are not throughput claims; they check whether attempted records can be accounted for as delivered, partial-delivered, known-rejected, known-dropped, or unexplained-lost.
 
 See [BENCHMARK.md](BENCHMARK.md) for the selected runs, methodology, and the explicit "what to claim / what not to claim" boundaries, and [`benchmarks/summary/`](benchmarks/summary/) for the published summaries.
 
 ## Testing / Quality
 
-The release gate runs the full dev test suite across Windows, macOS, and Linux on Python 3.11-3.14. CI also runs Ubuntu free-threaded CPython `3.13t` and `3.14t` compatibility jobs with `PYTHON_GIL=0`. Publication checks also verify generated API docs, public design documents, benchmark summaries, and package build output.
+The release gate runs the full dev test suite across Windows, macOS, and Linux on Python 3.11-3.14. CI also runs Ubuntu free-threaded CPython `3.13t` and `3.14t` compatibility jobs with `PYTHON_GIL=0`. Publication checks verify source typing, typing smoke tests, packaged `pyright --verifytypes`, generated API docs, public design documents, benchmark summaries, and package build output.
 
 See [TESTING.md](TESTING.md) for details.
 
@@ -287,8 +280,8 @@ For vulnerability reporting, see [SECURITY.md](SECURITY.md).
 
 For deeper architectural rationale and specification details, see:
 
-- [Architecture Analysis White Paper](docs/design/D-SafeLogger_v23j_WhitePaper_en.md)
-- [Basic Design Specification](docs/design/D_SafeLogger_Specification_v23j_full_en.md)
+- [Architecture Analysis White Paper](docs/design/D-SafeLogger_v23k_WhitePaper_en.md)
+- [Basic Design Specification](docs/design/D_SafeLogger_Specification_v23k_full_en.md)
 - [API Reference](docs/api/index.md)
 
 Japanese design documents are also available under [`docs/design/`](docs/design/).

{d_safelogger-0.2.2 → d_safelogger-0.3.0}/README.md

@@ -4,19 +4,37 @@
 [![PyPI version](https://img.shields.io/pypi/v/d-safelogger.svg?cacheSeconds=3600)](https://pypi.org/project/d-safelogger/)
 [![Python](https://img.shields.io/pypi/pyversions/d-safelogger.svg?cacheSeconds=3600)](https://pypi.org/project/d-safelogger/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#main-features)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](#highlights)
 
 Languages: [English](README.md) | [日本語](README_ja.md)
 
-## Overview
-
 D-SafeLogger is a zero-dependency, stdlib logging-compatible logger built on Python's standard `logging` module.
 
-It extends the standard logging path instead of replacing it. Existing `logging.getLogger()` and `logger.info()` call sites can participate without modification, while D-SafeLogger adds append-only file routing, structured JSON Lines output, contextual logging, SHA-256 sidecars, environment-based operational overrides, and Writer-owned multiprocess logging.
+It extends the standard logging path instead of replacing it, so existing application code and third-party library logs can stay on the stdlib logging path. It is intended for Python applications that need local file logging to start small in development and become explicit, inspectable, and operationally controlled for services, scheduled jobs, audit-oriented logs, and multiprocess workers.
+
+## Highlights
+
+1. **Stdlib `logging` compatible.** Existing `logger.info()` call sites and third-party libraries using `logging.getLogger()` participate without modification.
+
+2. **Append-only routing, no rename.** D-SafeLogger opens the next destination file instead of renaming or truncating the active log. This avoids the Windows file-lock failure mode of rename-based rotation and the POSIX case where a successful rename can leave the writer attached to the previous file descriptor.
+
+3. **Zero runtime dependencies.** The runtime package uses only the Python standard library. No extra runtime dependency chain is added to your application.
 
-Append-only routing means D-SafeLogger opens the next destination file instead of renaming or truncating the active log file. This avoids the common Windows file-lock failure mode of rename-based rotation. It also sidesteps the POSIX failure mode where a rename succeeds at the filesystem layer while existing file descriptors keep writing to the previous file.
+4. **Start in three lines, add policy through configuration.** A minimal setup is three lines. The same call sites can stay in place while configuration adds 9 routing strategies (`daily`, `hourly`, `size`, and more), JSON Lines, SHA-256 sidecars and manifests, sensitive-keyword masking, diagnostic mode, and code / INI-dict / environment deployment layers.
 
-The "Safe" in the name refers to operational safety: fail-fast setup, append-only file handling, producer-side context snapshots, bounded queues, explicit timeouts, and classified delivery-state accounting.
+5. **Robust and flexible multiprocess logging.** A parent-side Writer owns file output while workers submit records over IPC. Process, Pool, and ProcessPoolExecutor patterns are covered, with delivery outcomes classified instead of hidden.
+
+## When to Use It
+
+Use D-SafeLogger when you want to keep standard `logging.getLogger()` call sites while adding:
+
+- append-only local file routing,
+- environment-driven operational overrides,
+- optional SHA-256 sidecars and manifests,
+- Writer-owned multiprocess file output,
+- classified delivery-state accounting.
+
+You probably do not need it if your application only writes to stdout/stderr and an external collector owns routing, retention, aggregation, and durability.
 
 ## Installation
 
@@ -63,43 +81,36 @@ For multiprocess setup, see [Multiprocess Logging](#multiprocess-logging). For I
 
 Configuration is fail-fast. D-SafeLogger rejects feature combinations that cannot take effect, such as cyclic routing with hash/archive retention, `routing_mode='none'` with D-SafeLogger-owned retention, or `structured=True` with custom formatter strings.
 
-## When to Use It
-
-Use D-SafeLogger when you want to keep standard `logging.getLogger()` call sites while adding:
-
-- append-only local file routing,
-- environment-driven operational overrides,
-- optional SHA-256 sidecars and manifests,
-- Writer-owned multiprocess file output,
-- classified delivery-state accounting.
-
-You probably do not need it if your application only writes to stdout/stderr and an external collector owns routing, retention, aggregation, and durability.
-
 ## Why D-SafeLogger?
 
-D-SafeLogger extends the standard logging path rather than replacing it: you keep using `logging.getLogger()` and existing `logger.info()` call sites, and the library adds safe local-file output on top: rename-free append-only routing, fail-fast configuration, SHA-256 sidecars, sensitive-data masking, environment-driven operational control, and a parent-side multiprocess Writer.
+D-SafeLogger extends the standard logging path rather than replacing it: you keep using `logging.getLogger()` and existing `logger.info()` call sites, and the library adds safe local-file output on top.
 
-If you already use `structlog` as a structured-logging frontend, D-SafeLogger coexists rather than replaces. `structlog` builds the event dictionary; D-SafeLogger handles file output, routing, sidecars, masking, and operational control. See [Structlog Coexistence](examples/16_structlog_coexistence.md) for two integration patterns.
+That matters when an application already has stdlib logging calls, or depends on libraries that emit through `logging.getLogger()`. D-SafeLogger lets those records enter the same routing, formatting, context, integrity, async, and multiprocess Writer path without forcing a new application-wide logging API.
+
+If you already use `structlog` as a structured-logging frontend, D-SafeLogger coexists rather than replaces it. `structlog` builds the event dictionary; D-SafeLogger handles file output, routing, sidecars, masking, and operational control. See [Structlog Coexistence](examples/16_structlog_coexistence.md) for two integration patterns.
 
 ## Why Routing Instead of External Rotation?
 
 External rotation typically renames or truncates an active log file, creates a replacement, and asks the application to reopen its sink. That is plumbing for a design that mutates the active file after the fact, not the core of writing log records.
 
-On POSIX systems, the rename can succeed even while the writer keeps writing through the old file descriptor. The filesystem call returned success, but the logger never actually moved to the new file.
+On Windows, active-file rename can fail because the writer still holds the file. On POSIX systems, the rename can succeed while the writer keeps writing through the old file descriptor. The filesystem call returned success, but the logger never actually moved to the new file.
 
 D-SafeLogger avoids that dependency by choosing the destination at write time. It opens the next destination at the routing boundary instead of mutating the active file and relying on a signal/reopen handshake.
 
 ## What "Safe" Means
 
-The "Safe" in the name is a design stance that runs across several dimensions of everyday operation, not only failure handling:
+"Safe" is not a promise that every record survives every possible failure. It is a design stance for reducing avoidable logging failures and making observable failures explainable.
+
+| Dimension | Meaning |
+|---|---|
+| Startup safety | Invalid settings, inconsistent options, and unwritable destinations fail during setup before the application starts doing real work. |
+| File safety | Routed log files are treated as append-only artifacts with an explicit lifecycle: active writing, closed routed file, optional SHA-256 sidecar, optional manifest, and downstream transfer or archive. Integrity support is for closed-file verification, not access control. |
+| Record and context safety | Context is snapshotted on the producer side at hand-off; diagnostics and Writer-side formatting use the sensitive-keyword set established at configure time. |
+| Operational control | Runtime overrides are intentionally explicit and operator-owned. Log levels, routing, hashing, and timeout behavior can be changed without rebuilding, while diagnostic local-variable expansion is limited to environment-variable opt-in and cannot be enabled by an unowned INI file. |
+| Concurrency and multiprocess safety | Cross-thread and cross-process logging paths use bounded queues, explicit timeouts, rejection/drop paths, and shutdown drain limits. The design favors hard ceilings over indefinite waiting. |
+| Delivery visibility | Abnormal delivery outcomes remain visible through `mp.GetDeliveryStatus()`, runtime warning JSON Lines, and shutdown report JSON. Even `UnexplainedLost` is preserved as an explicit state, so abnormal runs do not collapse into “the file is just shorter than expected.” |
 
-- **Startup safety:** invalid settings, inconsistent options, and unwritable destinations fail during setup. D-SafeLogger stops a broken logging configuration before the application starts doing real work, instead of silently degrading later.
-- **File safety:** the routing layer opens the next destination instead of renaming or truncating the active log file, which avoids the common Windows failure mode where active log files cannot be renamed. It also avoids the POSIX case where a successful rename leaves the writer appending to the previous file. Routed files can be paired with SHA-256 sidecars and an optional manifest, so log content is verifiable after the fact.
-- **Record and context safety:** request IDs, user IDs, job IDs, and other context are snapshotted on the producer side at hand-off, so listeners and Writers do not depend on live `contextvars`. Diagnostic local-variable snapshots and Writer-side formatting use the sensitive-keyword set established at configure time.
-- **Operational control:** environment variables provide explicit runtime overrides for diagnostics, routing, hashing, log levels, and queue/timeout behavior without rebuilding or editing application code.
-- **Concurrency and multiprocess safety:** multiprocess workers do not open the shared log files themselves. A parent-side Writer owns the sinks and accepts records over IPC, with bounded queues and explicit timeouts that keep the host process from unbounded waits.
-- **Failure observability:** when records cannot be delivered, the runtime classifies the outcome where it can: `KnownRejected`, `KnownDropped`, or `UnexplainedLost`. Counters and shutdown summaries make abnormal scenarios describable rather than silent.
-- **Filesystem scope:** append-only routing avoids external rename/truncate of active log files. It does not make every destination filesystem equally safe. NFS, SMB/CIFS, FUSE mounts, cloud-synced folders, container bind mounts, and in-memory filesystems can have different rename, unlink, cache, durability, or lifetime semantics. For audit-oriented deployments, prefer writing active logs to a durable local filesystem and transferring closed routed files to archive or network storage.
+Append-only routing avoids external rename/truncate of active log files. It does not make every destination filesystem equally safe. NFS, SMB/CIFS, FUSE mounts, cloud-synced folders, container bind mounts, and in-memory filesystems can have different rename, unlink, cache, durability, or lifetime semantics. For audit-oriented deployments, prefer writing active logs to a durable local filesystem and transferring closed routed files to archive or network storage.
 
 ## Feature Comparison
 
@@ -146,39 +157,21 @@ Notes:
 - **※9** loguru's `enqueue=True` provides queued, multiprocessing-safe logging, but it is not a parent-side Writer ownership model and does not expose D-SafeLogger-style delivery-state accounting.
 - **※10** stdlib logging can be assembled into a listener/queue architecture, but this is not a packaged parent-side Writer API.
 
-**Delivery-state accounting** refers to per-record classification (`KnownRejected`, `KnownDropped`, `UnexplainedLost`) exposed through counters and shutdown summaries. See [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md) and [BENCHMARK.md](BENCHMARK.md).
-
-## Main Features
-
-- **Zero runtime dependencies:** the package uses only the Python standard library at runtime.
-- **Stdlib logging compatibility:** existing `logger.info()` calls and libraries that use `logging.getLogger()` participate in the same logging setup.
-- **Centralized setup:** replace common `basicConfig()`, `dictConfig()`, formatter, handler, and rotating-file boilerplate with `ConfigureLogger()`.
-- **Fail-fast initialization:** invalid configuration and unwritable log destinations fail during setup instead of degrading silently.
-- **Append-only file routing:** the routing layer opens the next destination instead of renaming or truncating the active log file. This avoids the common Windows failure mode where active log files cannot be renamed, and it avoids the POSIX case where a writer may continue writing to the previous file after a successful rename.
-- **Retention for routed files:** routed files can be kept by `backup_count`; older files can be deleted by the purge worker or ZIP-archived with `archive_mode=True`.
-- **Classified delivery state:** loss, reject, and drop events are not treated as invisible file gaps. When records cannot be delivered, the runtime classifies the outcome as known-rejected, known-dropped, or unexplained-lost where applicable.
-- **Bounded logging path:** D-SafeLogger uses bounded queues, explicit timeouts, and explicit rejection paths to avoid unbounded logging-side waits in the host process.
-- **Structured JSON Lines:** emit log records as JSON fields for log collectors and observability pipelines.
-- **Contextual logging:** attach request IDs, user IDs, job IDs, or other context with thread-safe and async-safe propagation. Producer-side context snapshots are taken at hand-off so listeners and Writers do not look up live `contextvars`.
-- **Integrity sidecars:** generate SHA-256 sidecars and optional manifest entries for routed log files. This is tamper-evidence for closed files, not an access-control or compliance system.
-- **Operational overrides:** change log level, module routing, console output, color, hashing, config file path, and queue/timeout parameters through environment variables, typically to raise diagnostics in production without code changes.
-- **Environment-only diagnostic mode:** opt in via `D_LOG_DIAGNOSE=1` for `f_locals` expansion of selected frames; deliberately not exposed through INI or arguments, so it cannot be enabled by an unowned configuration file.
-- **Async transport:** opt in to queue-backed logging when application threads should avoid direct sink writes.
-- **Custom log levels:** `register_level()` to add named levels alongside the built-in five before `ConfigureLogger()`.
-- **External rotation reopen:** `ReopenLogFiles()` and its multiprocess equivalent reopen sinks after external log rotators such as `logrotate`.
-- **Delivery-state visibility (multiprocess):** worker logging exposes per-record delivery-state counters and shutdown summaries, so abnormal shutdowns, sink unavailability, and worker crashes are described rather than silent.
+**Delivery-state accounting** refers to per-record classification (`KnownRejected`, `KnownDropped`, `UnexplainedLost`, plus `partial_delivered`) exposed through `mp.GetDeliveryStatus()`, runtime warning JSON Lines, and shutdown report JSON. See [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md), [`docs/design/v23k_supplements/delivery_status_schema.md`](docs/design/v23k_supplements/delivery_status_schema.md), and [BENCHMARK.md](BENCHMARK.md).
 
 ## Multiprocess Logging
 
 `dsafelogger.mp` is for applications where multiple worker processes need to send logs to shared destinations without each worker independently opening the same files.
 
-In this mode, a parent-side Writer owns the file sinks. Workers attach to the Writer and submit log records through IPC. This centralizes file ownership and exposes delivery-state counters such as accepted, delivered, rejected, dropped, and unexplained-lost.
+In this mode, a parent-side Writer owns the file sinks. Workers attach to the Writer and submit log records through IPC. This centralizes file ownership and exposes delivery-state counters such as attempted, accepted, delivered, partial-delivered, known-rejected, known-dropped, and unexplained-lost.
+
+The public API is designed for three common worker patterns: `multiprocessing.Process`, `multiprocessing.Pool`, and `concurrent.futures.ProcessPoolExecutor`. The same Writer session can be bootstrapped into each pattern through explicit attach calls or the `GetWorkerInitializer()` helper used by pools and executors.
 
-The Writer shutdown path is bounded: it attempts to drain and join within a timeout, emits a visible warning if drain is incomplete, and avoids hanging the host process indefinitely.
+The Writer shutdown path is bounded: it attempts to drain and join within a timeout, records runtime warnings when configured, writes a shutdown report when configured, and avoids hanging the host process indefinitely.
 
 For setup code, the `multiprocessing` context rules, pool initializer, `ProcessPoolExecutor` integration, Windows spawn caveats, custom log levels, attach/detach lifecycle, environment-variable knobs, and shutdown handling, see [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md).
 
-Public API in `dsafelogger.mp`: `ConfigureLogger`, `AttachCurrentProcess`, `DetachCurrentProcess`, `GetLogger`, `GetWorkerInitializer`, `ReopenLogFiles`.
+Public API in `dsafelogger.mp`: `ConfigureLogger`, `AttachCurrentProcess`, `DetachCurrentProcess`, `GetLogger`, `GetWorkerInitializer`, `GetDeliveryStatus`, `DeliveryStatus`, `ReopenLogFiles`.
 
 ## Configuration
 
@@ -195,7 +188,7 @@ Common environment overrides, using the default `D_LOG_*` prefix; the prefix is
 - Single-process: `D_LOG_LEVEL`, `D_LOG_MODULES`, `D_LOG_CONFIG`, `D_LOG_DIAGNOSE`, `D_LOG_CONSOLE`, `D_LOG_COLOR`, `D_LOG_HASH`, `D_LOG_MANIFEST`, plus the industry-standard `NO_COLOR`, which is not affected by `env_prefix`.
 - Multiprocess (`dsafelogger.mp`): `D_LOG_IPC_LOG_TIMEOUT`, `D_LOG_IPC_LOG_QUEUE_MAXSIZE`, `D_LOG_IPC_CLIENT_QUEUE_MAXSIZE`, `D_LOG_WRITER_FLUSH_BATCH`. These tune backpressure behavior and are normally left at defaults.
 
-See [Configuration Guide](examples/02_configuration_guide.md) for INI files, dict configuration, module-specific routing, and precedence rules.
+See [Configuration Guide](examples/02_configuration_guide.md) for INI files, dict configuration, module-specific routing, and precedence rules. For routing-mode selection, purge/archive retention, and long-running file lifecycle examples, see [Long-Running Service](examples/07_long_running_service.md).
 
 ## Tutorials / Examples
 
@@ -232,13 +225,13 @@ Suggested reading paths:
 
 D-SafeLogger is competitive in the selected single-process async benchmark runs. In multiprocess benchmarks, raw throughput is not the differentiator; parent-side file output and classified delivery-state accounting are.
 
-The benchmark suite also includes multiprocess resilience profiles, such as sink-unavailable, burst backpressure, worker crash, mixed worker behavior, and shutdown behavior. These runs are not throughput claims; they check whether attempted records can be accounted for as delivered, known-rejected, known-dropped, or unexplained-lost.
+The benchmark suite also includes multiprocess resilience profiles, such as sink-unavailable, burst backpressure, worker crash, warning-IPC fallback, mixed worker behavior, and shutdown behavior. These runs are not throughput claims; they check whether attempted records can be accounted for as delivered, partial-delivered, known-rejected, known-dropped, or unexplained-lost.
 
 See [BENCHMARK.md](BENCHMARK.md) for the selected runs, methodology, and the explicit "what to claim / what not to claim" boundaries, and [`benchmarks/summary/`](benchmarks/summary/) for the published summaries.
 
 ## Testing / Quality
 
-The release gate runs the full dev test suite across Windows, macOS, and Linux on Python 3.11-3.14. CI also runs Ubuntu free-threaded CPython `3.13t` and `3.14t` compatibility jobs with `PYTHON_GIL=0`. Publication checks also verify generated API docs, public design documents, benchmark summaries, and package build output.
+The release gate runs the full dev test suite across Windows, macOS, and Linux on Python 3.11-3.14. CI also runs Ubuntu free-threaded CPython `3.13t` and `3.14t` compatibility jobs with `PYTHON_GIL=0`. Publication checks verify source typing, typing smoke tests, packaged `pyright --verifytypes`, generated API docs, public design documents, benchmark summaries, and package build output.
 
 See [TESTING.md](TESTING.md) for details.
 
@@ -260,8 +253,8 @@ For vulnerability reporting, see [SECURITY.md](SECURITY.md).
 
 For deeper architectural rationale and specification details, see:
 
-- [Architecture Analysis White Paper](docs/design/D-SafeLogger_v23j_WhitePaper_en.md)
-- [Basic Design Specification](docs/design/D_SafeLogger_Specification_v23j_full_en.md)
+- [Architecture Analysis White Paper](docs/design/D-SafeLogger_v23k_WhitePaper_en.md)
+- [Basic Design Specification](docs/design/D_SafeLogger_Specification_v23k_full_en.md)
 - [API Reference](docs/api/index.md)
 
 Japanese design documents are also available under [`docs/design/`](docs/design/).