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

d_safelogger-0.2.2/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.2] - 2026-05-21
+
+### Added
+- Type validation as a CI quality gate: `mypy` and `pyright` are now required dev dependencies; `publication-checks` runs `uv run mypy src` and `uv run pyright src` on every push.
+- `scripts/install_built_wheel.py` — helper for installing the freshly built wheel into the uv-managed venv before running `pyright --verifytypes` against the packaged module (rather than the editable source tree).
+- `scripts/check_type_completeness.py` — threshold gate for `pyright --verifytypes dsafelogger --ignoreexternal`; CI now requires 100% public type completeness from the built wheel.
+- `scripts/check_distribution_contents.py` — standalone script replacing the inline heredoc in `publish.yml`; adds `dsafelogger/py.typed` (wheel) and `src/dsafelogger/py.typed` (sdist) to required-path checks. Also wired into `ci.yml` `publication-checks`.
+- `tests/typing_smoke/public_api_smoke.py` — pyright-only smoke test covering `ConfigureLogger`, `GetLogger`, `contextualize`, and `mp.ConfigureLogger` / `mp.GetWorkerInitializer` from a user import perspective. The directory is named `typing_smoke` (not `typing`) to avoid shadowing the stdlib `typing` module in spawn child processes. Not collected by pytest (filename does not match `test_*.py`); checked by `uv run pyright tests/typing_smoke` in `publication-checks`.
+- `dsafelogger._handler.ReopenableHandler` — `@runtime_checkable` Protocol that narrows `logging.Handler` references to those exposing `reopen()`; replaces internal `hasattr(h, 'reopen')` checks for static type checking.
+
+### Changed
+- `dsafelogger._pipeline.ResolvedConfig.sensitive_keywords` now defaults to `BUILTIN_SENSITIVE_KEYWORDS` directly (previously `field(default_factory=frozenset)`). Behaviour is preserved by the existing `or BUILTIN_SENSITIVE_KEYWORDS` consumer fallback; the API docs now show the concrete default value rather than `<factory>`.
+- `dsafelogger._mp_protocol.LogEvent` TypedDict fields `process`, `processName`, `thread`, `threadName` are now `int | None` / `str | None`, aligning with stdlib `logging.LogRecord` semantics (None is a legal value for these attributes).
+- `dsafelogger._formatter.DSafeFormatter.__init__` `style` parameter is now typed `Literal['%', '{', '$']` instead of `str`, matching `logging.Formatter`.
+
+### Fixed
+- `dsafelogger._routing.NoneStrategy.advance()` now returns the current path instead of implicitly returning `None`, satisfying its `Path` return-type contract (no observable behaviour change; `should_switch()` always returns `False` so the method is unreachable in production).
+- `dsafelogger._cli` tail follow loop asserts that the open file handle is non-`None` before reuse (defensive narrowing; the assert is unreachable in normal execution).
+- `dsafelogger._shutdown()` acquires the root logger reference before the `try` block so the `finally` block always has it available, even if an exception is raised before the original assignment site.
+
+### Internal
+- Removed 19 stale `# type: ignore[...]` comments that mypy 2.1 no longer requires.
+- Annotated 4 previously untyped functions (`_levels._make_log_method`, `_color.ColorStreamHandler.__init__`, `_transport.TransportFactory.create`).
+- `dsafelogger._mp_queue.TrackedQueue.__getstate__` / `__setstate__` are now explicitly marked `# type: ignore[override]` with a comment documenting the intentional `_QueueState` extension; cross-platform `qsize()` and `empty()` are coerced via `int(...)` / `bool(...)` to satisfy `warn_return_any`.
+- `dsafelogger._mp_attach._validate_attach_ack` and `dsafelogger.mp._validate_bootstrap_ready_ack` now accept `ControlAck` TypedDict directly (previously `dict[str, Any]` / `dict[str, object]`).
+- `pyproject.toml` adds `[tool.pyright]` (basic mode, `include = ["src"]`).
+- `TESTING.md` gains a Type Validation section describing the local-green-before-push policy, recorded versions, and the private module surface rule.
+- `README.md` / `README_ja.md` typing bullet updated to mention the CI type-check gate.
+- `CONTRIBUTING.md` adds `uv run mypy src` / `uv run pyright src` to the required PR pre-flight commands and documents the private module surface policy.
+- Public v23j design documents now describe the 0.2.2 type-validation gate, including source typing, `tests/typing_smoke`, built-wheel verifytypes, and the stdlib `typing` shadowing guard.
+- API docs regenerated for `_color`, `_formatter`, `_handler`, `_mp_attach`, `_pipeline`.
+
+## [0.2.1] - 2026-05-20
+
+### Fixed
+- Apply resolved `sens_kws` / `sens_kws_replace` to diagnostic local-variable snapshots across sync text, sync structured, async snapshot, and multiprocess Writer formatter paths.
+- Preserve async producer-side diagnostic frame snapshots in text diagnostic output.
+- Align daily routing examples with the implemented `YYYYMMDD` filename suffix.
+
+### Changed
+- Updated example tests to match the documented runnable examples for migration, web API, long-running service, compliance audit, production debugging, async performance, multiprocess logging, CLI operations, OpenTelemetry, structlog, and container collector coexistence scenarios.
+- Updated public docs, API docs, and test/coverage baselines for the 0.2.1 patch release.
+
+### Verified
+- Full local validation on Python 3.14.3 / Windows: `658 passed, 3 skipped` (`661` collected).
+- Coverage validation regenerated `coverage.xml`: terminal total `87%`, line-rate `88.97%`, branch-rate `81.46%`.
+- API docs, design-doc sync, and whitespace checks pass; `git diff --check` reports only CRLF/LF warnings.
+
+## [0.2.0] - 2026-05-05
+
+### Added
+- Formal multiprocess public API under `dsafelogger.mp`, including `ConfigureLogger`, `AttachCurrentProcess`, `DetachCurrentProcess`, `GetLogger`, `GetWorkerInitializer`, and `ReopenLogFiles`.
+- Writer-runtime multiprocess architecture with separate log plane and control plane, CloseMarker-based drain, explicit attach/detach, and bounded shutdown behavior.
+- Classified multiprocess delivery-state counters for route/reconstruct/close-marker/sink/policy rejects, partial delivery, best-effort failures, timeout drops, overload shed, and drain-deadline loss.
+- `TrackedQueue` for qsize-visible multiprocess log queues with platform fallback.
+- Multiprocess comparison benchmark runner at `benchmarks/run_multiprocess_compare_v23a.py` with integrity, performance, overload, and resilience profiles.
+- Benchmark summary manifest workflow via `benchmarks/summary/manifest.json` and `benchmarks/update_summary.py`.
+- Generated benchmark summary documents under `benchmarks/summary/` while keeping `BENCHMARK.md` manually edited.
+- `optional_integration` pytest marker for OpenTelemetry and structlog coexistence tests while keeping them in the official full test run.
+- v23j public design documents under `docs/design/` reflecting formal MP, dev full-test policy, manifest-based benchmark publication, and strict invalid-configuration handling.
+- Shared v23j configuration validation for single-process, module-specific, and multiprocess file sinks.
+- Generated API documentation under `docs/api/` with `scripts/generate_api_docs.py --check`.
+- Public design-document readiness check via `scripts/check_design_docs_sync.py`.
+- Multiprocess and external-rotation tutorials covering `dsafelogger.mp` and `ReopenLogFiles()`.
+
+### Changed
+- Updated `README.md`, `README_ja.md`, `TESTING.md`, and `BENCHMARK.md` to describe the current v23j design, test policy, benchmark interpretation, and formal multiprocess support.
+- Invalid routing/generation/hash combinations are now fail-fast `ValueError` cases instead of warnings or silent no-ops.
+- `structured=True` is mutually exclusive with `fmt`, `file_fmt`, and `console_fmt` after all config layers are merged.
+- `file_fmt` and `console_fmt` are now accepted by the single-process API and INI/config_dict loader, matching the public design docs.
+- Multiprocess module-specific levels are propagated to attached worker loggers.
+- Multiprocess spawn integration tests now use the same multiprocessing context for Writer IPC primitives and worker process creation.
+- Multiprocess log queue creation now classifies platform-rejected `ipc_log_queue_maxsize` values as `ValueError` before Writer sinks are started, while preserving runtime errors for non-validation OS failures.
+- Tests no longer depend on `multiprocessing.Queue.empty()` for correctness.
+- Benchmark runners now write session artifacts only; they no longer regenerate top-level `BENCHMARK.md`.
+- Official testing policy is now `uv sync --group dev` followed by the full `uv run pytest tests -v` run.
+- Package metadata version and public `dsafelogger.__version__` are both `0.2.0`; project classifier is now Beta.
+- Package license metadata now uses SPDX `license = "Apache-2.0"` and `license-files = ["LICENSE"]`.
+- GitHub CI now checks generated API docs, design-document sync, benchmark summaries, and package build output.
+- PyPI publish workflow now verifies tag/version consistency and repeats publication preflight checks before publishing.
+- GitHub CI now includes Ubuntu free-threaded CPython `3.13t` and `3.14t` test jobs with `PYTHON_GIL=0`.
+
+### Verified
+- Full local v23j validation on Python 3.14.3 / Windows: `651 passed, 3 skipped` (`654` collected). Skip counts can vary by platform because fork tests are POSIX-only and Windows spawn tests are Windows-only.
+- Targeted v23j configuration validation: `256 passed` across configure, routing, INI, reopen, and MP integration tests.
+- Coverage validation regenerated `coverage.xml`: terminal total `86%`, line-rate `88.49%`, branch-rate `80.53%`.
+- Targeted regression validation for MP runtime, MP integration, OpenTelemetry, and structlog tests: `91 passed`.
+- Benchmark summary manifest generation and `--check` verification pass.
+
+## [0.1.0] - 2026-04-03
+
+### Added
+- Initial release
+- 3-layer configuration pipeline (Environment → INI/Dict → Arguments)
+- 9 routing strategies (none, daily, hourly, min_interval, startup_interval, size, count, cyclic_weekday, cyclic_month)
+- Append-only file handler (Windows lock-safe)
+- SHA-256 integrity verification with sidecar files and manifest
+- Structured JSON Lines output
+- Diagnostic formatter with f_locals expansion and sensitive data masking
+- ANSI color console output with customizable palette
+- Async logging mode with context-preserving QueueHandler
+- Custom log level registration with `register_level()`
+- `contextualize()` context manager for structured log context
+- CLI tool (`dsafelogger init/ls/tail -f`)
+- Free-threaded Python (3.13t/3.14t) support with explicit locks
+- Per-module log level and file routing
+- INI file and dict-based configuration
+- Safe shutdown with worker thread join
+- Complete standard library `logging` compatibility

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/CONTRIBUTING.md

@@ -51,6 +51,9 @@ cd D-SafeLogger
 uv sync --group dev
 uv run pytest tests/ -v
 uv run ruff check src/ tests/
+uv run mypy src
+uv run pyright src
+uv run pyright tests/typing_smoke
 ```
 
 ## 6. Code Style
@@ -58,14 +61,17 @@ uv run ruff check src/ tests/
 - **PEP 8**, max **100** characters per line.
 - **ruff** for linting (`uv run ruff check src/ tests/`).
 - **Type hints required** — use Python 3.11+ `X | Y` union syntax.
+- **Typing must stay green**: `uv run mypy src`, `uv run pyright src`, and `uv run pyright tests/typing_smoke` must report `0 errors` locally before opening a PR. CI also enforces 100% public type completeness with `pyright --verifytypes` against the built wheel.
+- Private module surface (names starting with `_`, e.g. `dsafelogger._constants.MASK_STRING`) is **not** part of the public API even though `py.typed` exposes it to user type checkers. Do not encourage external dependence on these names; rename / reshape freely as needed.
 
 ## 7. Pull Request Process
 
 1. Create a feature branch from `main`.
 2. Add tests for new functionality.
 3. Ensure **all** tests pass: `uv run pytest tests/ -v`.
-4. Update documentation if needed.
-5. Submit a PR with a clear description referencing the accepted issue.
+4. Verify type checks pass: `uv run mypy src`, `uv run pyright src`, and `uv run pyright tests/typing_smoke` (all must report `0 errors`).
+5. Update documentation if needed.
+6. Submit a PR with a clear description referencing the accepted issue.
 
 ## License
 

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: D-SafeLogger
-Version: 0.2.0
+Version: 0.2.2
 Summary: Zero-dependency, thread-safe, append-only logging library for Python with 3-layer config pipeline
 Author: D
 License-Expression: Apache-2.0
@@ -28,8 +28,8 @@ Dynamic: license-file
 # D-SafeLogger
 
 [![CI](https://github.com/nightmarewalker/D-SafeLogger/actions/workflows/ci.yml/badge.svg)](https://github.com/nightmarewalker/D-SafeLogger/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/d-safelogger.svg)](https://pypi.org/project/d-safelogger/)
-[![Python](https://img.shields.io/pypi/pyversions/d-safelogger.svg)](https://pypi.org/project/d-safelogger/)
+[![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)
 
@@ -66,7 +66,7 @@ logger = GetLogger(__name__)
 logger.info("Application started")
 ```
 
-`pg_name` is the application name used as the prefix of routed log file names, for example `MyApp_2026-04-03.log`.
+`pg_name` is the application name used as the prefix of routed log file names, for example `MyApp_20260403.log`.
 
 Typical text output:
 
@@ -122,7 +122,7 @@ The "Safe" in the name is a design stance that runs across several dimensions of
 
 - **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`. Sensitive-keyword masking is applied on the Writer side using the keyword set established at configure time.
+- **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.
@@ -182,11 +182,12 @@ Notes:
 - **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.
+- **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.
@@ -200,6 +201,8 @@ Notes:
 
 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.
 
+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.
+
 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`.
@@ -256,11 +259,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.
+
 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. 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 also verify generated API docs, public design documents, benchmark summaries, and package build output.
 
 See [TESTING.md](TESTING.md) for details.
 
@@ -269,7 +274,7 @@ See [TESTING.md](TESTING.md) for details.
 - Python: 3.11 or newer.
 - OS: Windows, macOS, and Linux.
 - Runtime dependencies: none.
-- Typing: includes `py.typed`.
+- Typing: includes `py.typed`; CI checks `mypy`, `pyright`, typing smoke tests, and 100% public type completeness with `pyright --verifytypes`. See [TESTING.md](TESTING.md).
 - API docs: [`docs/api/`](docs/api/).
 - Design docs: [`docs/design/`](docs/design/).
 - Distribution name is `d-safelogger` (with hyphen); import name is `dsafelogger` (no separator).

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

@@ -1,8 +1,8 @@
 # D-SafeLogger
 
 [![CI](https://github.com/nightmarewalker/D-SafeLogger/actions/workflows/ci.yml/badge.svg)](https://github.com/nightmarewalker/D-SafeLogger/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/d-safelogger.svg)](https://pypi.org/project/d-safelogger/)
-[![Python](https://img.shields.io/pypi/pyversions/d-safelogger.svg)](https://pypi.org/project/d-safelogger/)
+[![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)
 
@@ -39,7 +39,7 @@ logger = GetLogger(__name__)
 logger.info("Application started")
 ```
 
-`pg_name` is the application name used as the prefix of routed log file names, for example `MyApp_2026-04-03.log`.
+`pg_name` is the application name used as the prefix of routed log file names, for example `MyApp_20260403.log`.
 
 Typical text output:
 
@@ -95,7 +95,7 @@ The "Safe" in the name is a design stance that runs across several dimensions of
 
 - **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`. Sensitive-keyword masking is applied on the Writer side using the keyword set established at configure time.
+- **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.
@@ -155,11 +155,12 @@ Notes:
 - **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.
+- **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.
@@ -173,6 +174,8 @@ Notes:
 
 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.
 
+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.
+
 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`.
@@ -229,11 +232,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.
+
 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. 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 also verify generated API docs, public design documents, benchmark summaries, and package build output.
 
 See [TESTING.md](TESTING.md) for details.
 
@@ -242,7 +247,7 @@ See [TESTING.md](TESTING.md) for details.
 - Python: 3.11 or newer.
 - OS: Windows, macOS, and Linux.
 - Runtime dependencies: none.
-- Typing: includes `py.typed`.
+- Typing: includes `py.typed`; CI checks `mypy`, `pyright`, typing smoke tests, and 100% public type completeness with `pyright --verifytypes`. See [TESTING.md](TESTING.md).
 - API docs: [`docs/api/`](docs/api/).
 - Design docs: [`docs/design/`](docs/design/).
 - Distribution name is `d-safelogger` (with hyphen); import name is `dsafelogger` (no separator).

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/README_ja.md

@@ -39,7 +39,7 @@ logger = GetLogger(__name__)
 logger.info("Application started")
 ```
 
-`pg_name` はルーティング後のログファイル名の接頭辞として使われるアプリケーション名です。例: `MyApp_2026-04-03.log`。
+`pg_name` はルーティング後のログファイル名の接頭辞として使われるアプリケーション名です。例: `MyApp_20260403.log`。
 
 標準的なテキスト出力:
 
@@ -95,7 +95,7 @@ D-SafeLogger は、active file を後から動かす代わりに、書き込み
 
 - **起動時の安全性:** 不正な設定値、矛盾したオプション、書き込めない出力先は初期化時に失敗させます。壊れた logging 構成のまま本体処理を進め、あとから気づきにくい形で動作が崩れることを防ぎます。
 - **ファイルの安全性:** ルーティング層は使用中のログファイルを rename / truncate せず、境界到達時に次の出力先を開きます。これにより active file の rename に起因する Windows 特有の失敗を避けられます。また、POSIX 系で rename が成功しても writer が古い file descriptor へ書き続ける、という世代切り替えのずれも避けられます。ルーティング済みファイルには SHA-256 sidecar と、任意で manifest を付けられ、後からログ内容を検証できます。
-- **レコードとコンテキストの安全性:** request ID、user ID、job ID といったコンテキストは producer 側で snapshot を取り、listener / Writer 側では live な `contextvars` を参照しません。機微情報のマスキングは Writer 側で、初期化時に確定したキーワード集合を使って適用されます。
+- **レコードとコンテキストの安全性:** request ID、user ID、job ID といったコンテキストは producer 側で snapshot を取り、listener / Writer 側では live な `contextvars` を参照しません。diagnostic のローカル変数 snapshot と Writer 側 formatting では、初期化時に確定した機微情報キーワード集合を使います。
 - **運用時の制御:** 環境変数により、コードを変更せずにログレベル、診断出力、モジュール別ルーティング、ハッシュ出力、キュー / timeout 設定を切り替えられます。
 - **並行性とマルチプロセスの安全性:** マルチプロセスでは worker が共有のログファイルを直接開かず、親プロセス側の Writer が出力先を所有して IPC でレコードを受け付けます。上限つきのキューと明示的な timeout により、本体プロセスが無制限に待ち続けることを避けます。
 - **失敗の可観測性:** 配送できなかったレコードは、可能な範囲で `KnownRejected` / `KnownDropped` / `UnexplainedLost` のいずれかに分類されます。カウンタと shutdown summary により、異常時のふるまいが見落とされず、説明できる形で残ります。
@@ -155,11 +155,12 @@ D-SafeLogger は、active file を後から動かす代わりに、書き込み
 - **中央初期化:** `basicConfig()`、`dictConfig()`、formatter、handler、rotation 設定の boilerplate を `ConfigureLogger()` に集約できます。
 - **fail-fast 初期化:** 不正な設定値や書き込めないログ出力先は初期化時に失敗させ、あとから気づきにくい形で動作が崩れることを避けます。
 - **追記専用のファイルルーティング:** ルーティング層は、使用中のログファイルを rename / truncate せず、境界到達時に次の出力先を開きます。Windows の active file rename 失敗だけでなく、POSIX 系で rename が成功したまま writer が旧世代へ書き続ける問題も避けられます。
+- **ルーティング済みファイルの保持管理:** ルーティング済みファイルは `backup_count` に基づいて保持できます。古いファイルは purge worker による削除、または `archive_mode=True` による ZIP archive 化が可能です。
 - **配送状態の分類:** 失われたレコードをファイル上の見えない欠損として扱わず、可能な範囲で known-rejected / known-dropped / unexplained-lost に分類します。
 - **境界をもった logging 経路:** 上限つきキュー、明示的な timeout、明示的な拒否経路を使うことで、logging 処理が本体プロセス側で無制限に待ち続ける設計を避けます。
 - **JSON Lines 出力:** ログ収集基盤や監視基盤へ渡しやすい JSON 形式で出力できます。
 - **コンテキスト付与:** request ID、user ID、job ID などを、スレッドや非同期境界をまたいでログへ付与できます。`contextvars` の snapshot は producer 側で取り、Writer 側では live な `contextvars` を参照しません。
-- **整合性 sidecar:** ルーティング済みログファイルに対して SHA-256 sidecar と、任意で manifest を出力できます。
+- **整合性 sidecar:** ルーティング済みログファイルに対して SHA-256 sidecar と、任意で manifest を出力できます。これは closed file の改ざんや破損を後から検出しやすくするためのもので、access-control system や compliance system ではありません。
 - **運用時の上書き:** ログレベル、モジュール別ルーティング、コンソール出力、色、ハッシュ、設定ファイルパス、キュー / timeout 関連を環境変数で変更できます。本番障害時にコードを変更せず診断レベルを上げる用途を主に想定しています。
 - **環境変数限定の診断モード:** `D_LOG_DIAGNOSE=1` を有効にすると、選択フレームの `f_locals` を展開できます。INI や引数からは意図的に有効化できないため、由来のわからない設定ファイルから ON にされることがありません。
 - **非同期出力:** アプリケーションスレッドが直接ファイル出力を待たないよう、キューを介した logging を選べます。
@@ -173,6 +174,8 @@ D-SafeLogger は、active file を後から動かす代わりに、書き込み
 
 このモードでは、親プロセス側の Writer がファイル出力先を所有します。worker は Writer に attach し、IPC 経由でログレコードを送ります。これによりファイル所有が一箇所に集約され、accepted / delivered / rejected / dropped / unexplained-lost といった配送状態のカウンターが公開されます。
 
+Writer の終了処理では上限つきの待機を行います。timeout 内で drain と join を試み、drain が完了しない場合は warning を出し、host process が無期限に hang し続けることを避けます。
+
 具体的なコード、`multiprocessing` の context ルール、Pool initializer、`ProcessPoolExecutor` 連携、Windows での spawn の注意、カスタムログレベル、attach / detach のライフサイクル、環境変数のチューニング、終了処理は [`examples/12_multiprocess_logging.md`](examples/12_multiprocess_logging.md) を参照してください。
 
 `dsafelogger.mp` の公開 API: `ConfigureLogger`, `AttachCurrentProcess`, `DetachCurrentProcess`, `GetLogger`, `GetWorkerInitializer`, `ReopenLogFiles`。
@@ -229,11 +232,13 @@ INI ファイル、dict 設定、モジュール別ルーティング、優先
 
 D-SafeLogger は、採用済みの単一プロセス async ベンチマークでは競争力があります。マルチプロセスでは、単純な throughput ではなく、親プロセス側 Writer によるファイル出力と配送状態の分類が主な価値です。
 
+ベンチマークには、sink-unavailable、burst backpressure、worker crash、mixed worker behavior、shutdown behavior などの multiprocess resilience profile も含まれます。これらは throughput claim ではなく、attempted record を delivered / known-rejected / known-dropped / unexplained-lost として説明できるかを確認するものです。
+
 採用 run、計測条件、主張できる範囲は [BENCHMARK.md](BENCHMARK.md) を、公開済みの summary は [`benchmarks/summary/`](benchmarks/summary/) を参照してください。
 
 ## テスト / 品質
 
-リリースゲートでは、Windows / macOS / Linux と Python 3.11-3.14 の組み合わせで dev 依存を含む full test suite を実行します。公開前チェックでは、生成済み API docs、公開設計書、ベンチマークサマリー、パッケージ build も検証します。
+リリースゲートでは、Windows / macOS / Linux と Python 3.11-3.14 の組み合わせで dev 依存を含む full test suite を実行します。CI では Ubuntu free-threaded CPython `3.13t` / `3.14t` の互換性ジョブも `PYTHON_GIL=0` で実行します。公開前チェックでは、生成済み API docs、公開設計書、ベンチマークサマリー、パッケージ build も検証します。
 
 詳しくは [TESTING.md](TESTING.md) を参照してください。
 
@@ -242,7 +247,7 @@ D-SafeLogger は、採用済みの単一プロセス async ベンチマークで
 - Python: 3.11 以上。
 - OS: Windows, macOS, Linux。
 - 実行時依存: なし。
-- 型情報: `py.typed` を同梱。
+- 型情報: `py.typed` を同梱。CI で `mypy` / `pyright`、typing smoke test、`pyright --verifytypes` による public type completeness 100% gate を検証。詳細は [TESTING.md](TESTING.md)。
 - API docs: [`docs/api/`](docs/api/)。
 - Design docs: [`docs/design/`](docs/design/)。
 - 配布パッケージ名は `d-safelogger` (ハイフン)、import 名は `dsafelogger` (区切りなし) です。

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/TESTING.md

@@ -29,8 +29,8 @@ uv run pytest tests -v
 Current v23j local validation on Python 3.14.3 / Windows:
 
 ```text
-651 passed, 3 skipped
-654 collected
+658 passed, 3 skipped
+661 collected
 ```
 
 The collected test count is the baseline. The number of skipped tests is platform-dependent because fork E2E tests are POSIX-only and Windows spawn E2E tests are Windows-only.
@@ -38,9 +38,9 @@ The collected test count is the baseline. The number of skipped tests is platfor
 Latest coverage validation generated `coverage.xml` on Python 3.14.3 / Windows:
 
 ```text
-TOTAL coverage: 86%
-XML line-rate: 88.49%
-XML branch-rate: 80.53%
+TOTAL coverage: 87%
+XML line-rate: 88.97%
+XML branch-rate: 81.46%
 ```
 
 `coverage.xml`, `.coverage`, and `htmlcov/` are local/CI artifacts and are ignored by `.gitignore`; keep coverage numbers in documentation, not the generated files themselves.
@@ -112,6 +112,11 @@ uv run pytest tests -x -v
 | Third-party coexistence | `tests/test_opentelemetry.py`, `tests/test_structlog.py` |
 | Branch coverage edge cases | `tests/test_coverage_boost.py` |
 
+Diagnostic masking coverage must include both component-level checks and
+configuration-to-output integration checks. In particular, `sens_kws` and
+`sens_kws_replace` are validated through `ConfigureLogger(...)` into sync text,
+sync structured, async snapshot, and multiprocess Writer formatter paths.
+
 ## Multiprocess Test Policy
 
 `dsafelogger.mp` is a formal feature, so multiprocess tests are part of the standard quality gate.
@@ -124,6 +129,60 @@ Important expectations:
 - Tests must not rely on `multiprocessing.Queue.empty()` for correctness. Use timeout-based `get()` or fake/recording queues instead.
 - CloseMarker drain, control-plane ACKs, backpressure, reject counters, partial delivery, and bounded shutdown warning paths are covered by MP tests.
 
+## Type Validation
+
+`D-SafeLogger` ships with `py.typed` (PEP 561), so source typing and public type completeness are part of the standard quality gate. CI runs `mypy`, `pyright`, a typing smoke test, and a 100% `pyright --verifytypes` gate on every push.
+
+### Tooling
+
+- `mypy>=2.1` — strict-ish config (`disallow_untyped_defs = true`, `warn_unused_ignores = true`, `warn_return_any = true`).
+- `pyright>=1.1.409` — `typeCheckingMode = "basic"` with `include = ["src"]`.
+
+### Required commands (PR pre-flight)
+
+```bash
+uv sync --group dev
+uv run pyright --version    # record first
+uv run mypy src             # → 0 errors
+uv run pyright src          # → 0 errors
+uv run pyright tests/typing_smoke # → 0 errors
+```
+
+Local green (`0 errors` from both tools) is the precondition for pushing. CI runs the same commands and treats any error as a hard fail.
+
+Package-level type completeness is checked from the built wheel, not the editable source tree:
+
+```bash
+uv build
+uv run python scripts/install_built_wheel.py
+uv run --no-sync python scripts/check_type_completeness.py --min-score 100
+uv sync --reinstall
+```
+
+Use `uv run --no-sync` for the completeness check so the wheel install is not replaced by the editable project before `pyright --verifytypes` runs.
+
+### Latest local validation (2026-05-21 / Python 3.14.3 / Windows)
+
+| Tool | Version | Result |
+|---|---|---|
+| `mypy` | 2.1.0 | `Success: no issues found in 27 source files` |
+| `pyright` | 1.1.409 | `0 errors, 0 warnings, 0 informations` |
+| `pyright --verifytypes dsafelogger --ignoreexternal` | 1.1.409 | `Type completeness score: 100%` (10 public symbols, 23 referenced internal symbols — all known type) |
+
+### Package name vs. type checker target
+
+D-SafeLogger uses three name forms — be careful when invoking type tools:
+
+- PyPI metadata: `D-SafeLogger`
+- Python import / `verifytypes` target: `dsafelogger`
+- Wheel filename: `d_safelogger-*.whl`
+
+For `pyright --verifytypes`, always pass `dsafelogger` (the import name).
+
+### Private module surface policy
+
+Names starting with a leading underscore (`_constants.MASK_STRING`, `_constants._resolved_sensitive_keywords`, `_pipeline.ResolvedConfig`, `_async.DSafeQueueHandler`, etc.) are **private** even though `py.typed` exposes them to user type checkers. Library consumers MUST NOT depend on private symbols; they may change without notice in PATCH or MINOR releases. Only names re-exported from `dsafelogger` / `dsafelogger.mp` `__init__.py` are public.
+
 ## Free-Threaded Python
 
 GitHub Actions runs Ubuntu free-threaded CPython `3.13t` and `3.14t` jobs with `PYTHON_GIL=0`.
@@ -161,13 +220,21 @@ See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
 The CI workflow also runs publication checks on Ubuntu/Python 3.13:
 
 ```bash
+uv run pyright --version
+uv run mypy src
+uv run pyright src
+uv run pyright tests/typing_smoke
 uv run python scripts/generate_api_docs.py --check
 uv run python scripts/check_design_docs_sync.py
 uv run python benchmarks/update_summary.py --check
 uv build
+uv run python scripts/check_distribution_contents.py
+uv run python scripts/install_built_wheel.py
+uv run --no-sync python scripts/check_type_completeness.py --min-score 100
+uv sync --reinstall --group dev
 ```
 
-The publish workflow repeats these checks, verifies the git tag matches the package version, runs the full test suite, and only then publishes.
+The publish workflow repeats release document, benchmark, build, distribution-content, metadata, and full-suite checks, verifies the git tag matches the package version, and only then publishes.
 
 ## Documentation Checks
 

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/docs/api/dsafelogger__async.md

@@ -33,5 +33,6 @@ Public methods:
 
 | Name | Type | Value |
 |---|---|---|
+| `MASK_STRING` | `str` | `'*** MASKED ***'` |
 | `QUEUE_DRAIN_TIMEOUT_SEC` | `float` | `10.0` |
 | `WORKER_JOIN_TIMEOUT_SEC` | `float` | `5.0` |

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/docs/api/dsafelogger__color.md

@@ -12,7 +12,7 @@ Enable ANSI escape sequences on Windows 10+.
 
 ## Classes
 
-### `ColorStreamHandler(stream=None, color_enabled: 'bool' = True, color_overrides: 'dict[str, str] | None' = None) -> 'None'`
+### `ColorStreamHandler(stream: 'IO[str] | None' = None, color_enabled: 'bool' = True, color_overrides: 'dict[str, str] | None' = None) -> 'None'`
 
 StreamHandler with ANSI color codes for log levels.
 

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/docs/api/dsafelogger__formatter.md

@@ -43,7 +43,7 @@ in high-throughput multi-threaded scenarios.
 
 ## Classes
 
-### `DSafeFormatter(fmt: 'str | None' = None, datefmt: 'str | None' = None, style: 'str' = '%') -> 'None'`
+### `DSafeFormatter(fmt: 'str | None' = None, datefmt: 'str | None' = None, style: "Literal['%', '{', '$']" = '%') -> 'None'`
 
 Standard D-SafeLogger formatter with level abbreviation and context suffix.
 

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/docs/api/dsafelogger__handler.md

@@ -24,3 +24,15 @@ Public methods:
 - `emit(self, record: 'logging.LogRecord') -> 'None'`
 - `flush(self) -> 'None'`
 - `reopen(self) -> 'None'`
+
+### `ReopenableHandler(*args, **kwargs)`
+
+Protocol for logging handlers that support external rotation reopen.
+
+`isinstance(h, ReopenableHandler)` narrows `logging.Handler` references
+to those that implement `reopen()`, replacing `hasattr(h, 'reopen')`
+for static type checking.
+
+Public methods:
+
+- `reopen(self) -> 'None'`

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/docs/api/dsafelogger__mp_attach.md

@@ -39,7 +39,7 @@ Restart pump threads that were lost due to a post-fork in the parent process.
 
 ### `_same_process_identity(state: 'MPProcessState') -> 'bool'`
 
-### `_validate_attach_ack(ack: 'dict[str, Any]', *, expected_protocol_version: 'int', expected_registry_hash: 'str') -> 'None'`
+### `_validate_attach_ack(ack: 'ControlAck', *, expected_protocol_version: 'int', expected_registry_hash: 'str') -> 'None'`
 
 ### `_validate_bootstrap_context(ctx: 'BootstrapContext') -> 'None'`
 

{d_safelogger-0.2.0 → d_safelogger-0.2.2}/docs/api/dsafelogger__pipeline.md

@@ -41,6 +41,12 @@ Public methods:
 
 - `build(self, config: 'ResolvedConfig') -> 'Pipeline'`
 
-### `ResolvedConfig(pg_name: 'str', log_dir: 'Path', file_fmt: 'str | FormatterConfigDict | logging.Formatter', console_fmt: 'str | FormatterConfigDict | logging.Formatter', routing_mode: 'str', routing_kwargs: 'dict', backup_count: 'int', archive_mode: 'bool', enable_hash: 'bool', manifest_path: 'Path | None', encoding: 'str', diagnose: 'bool', max_level: 'str', console: 'bool', is_async: 'bool', queue_size: 'int', log_level: 'str', color_stream: 'bool', module_configs: 'dict[str, dict]', color_overrides: 'dict[str, str]') -> None`
+### `ResolvedConfig(pg_name: 'str', log_dir: 'Path', file_fmt: 'str | FormatterConfigDict | logging.Formatter', console_fmt: 'str | FormatterConfigDict | logging.Formatter', routing_mode: 'str', routing_kwargs: 'dict', backup_count: 'int', archive_mode: 'bool', enable_hash: 'bool', manifest_path: 'Path | None', encoding: 'str', diagnose: 'bool', max_level: 'str', console: 'bool', is_async: 'bool', queue_size: 'int', log_level: 'str', color_stream: 'bool', module_configs: 'dict[str, dict]', color_overrides: 'dict[str, str]', sensitive_keywords: 'frozenset[str]' = frozenset({'access_key', 'api_key', 'apikey', 'auth', 'cookie', 'credential', 'passwd', 'password', 'private_key', 'secret', 'session_id', 'token'})) -> None`
 
 Resolved configuration holding 3-layer merged parameters.
+
+## Constants
+
+| Name | Type | Value |
+|---|---|---|
+| `BUILTIN_SENSITIVE_KEYWORDS` | `frozenset` | `frozenset({'access_key', 'api_key', 'apikey', 'auth', 'cookie', 'credential',...` |