icv-trace 0.1.0rc4__tar.gz

icv_trace-0.1.0rc4/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [Unreleased]
+
+## [0.1.0rc4] - 2026-09-09
+
+### Changed
+
+- Prepared the CI and tag workflow for public PyPI publishing through a PyPI
+  trusted publisher on GitHub-hosted runners. The release gate now also checks
+  that `human.py` is included in the wheel.
+- Added self-contained public contracts and renderer guides, contributor and
+  release instructions, and source-distribution copies of docs and examples.
+
+### Consumer behaviour
+
+- Runtime behaviour and the supported package-root API are unchanged from
+  `0.1.0rc3`. This release moves the distribution target to PyPI. Private-index
+  consumers should validate an explicit `0.1.0rc4` PyPI install before removing
+  their private extra index, and retain that index while other private packages
+  still need it.
+
+## [0.1.0rc3] - 2026-09-09
+
+### Added
+
+- Added `HumanRenderer` and `HumanTraceSink` for bounded, readable projection
+  and optional exact JSONL fanout of trace records.
+
+### Consumer behaviour
+
+- Existing trace bindings, canonical human output, structured records and
+  admission budgets retain their behaviour. Readable rendering is opt-in:
+  hosts bind `HumanTraceSink` as the structured destination and inspect its
+  output health separately from core health. Its human view omits correlation
+  IDs; optional JSONL fanout preserves the original records. The core charges
+  structured bytes, not downstream presentation/fanout bytes.
+
+## [0.1.0rc2] - 2026-09-09
+
+### Fixed
+
+- Added explicit Python setup before the private publish workflow validates
+  release metadata. `v0.1.0rc1` stopped in that pre-upload job because the
+  bare self-hosted runner had no `python` command; no distribution was
+  uploaded and the trace API is unchanged.
+
+## [0.1.0rc1] - 2026-09-09
+
+### Unpublished
+
+- `v0.1.0rc1` did not upload a distribution. It remains historical evidence
+  of the failed pre-upload workflow run and must not be retagged.
+
+### Added
+
+- Extracted the pure-Python trace core from icvlocal at source commit
+  `087479b96929a56447c2ac8011011023b4df2dcd`.
+- Added bounded lifecycle diagnostics, correlation context, sink health and
+  same-thread callback capture as the initial private release candidate.
+
+### Changed
+
+- Existing incubated consumers keep the same public API and runtime behaviour.
+  The implementation is now distributed as `icv-trace` for index installation.
+
+### Release gate record
+
+- The release owner completes and records all six private release gates on the
+  exact tagged commit before pushing `v0.1.0rc2`: version and changelog,
+  green CI, clean publish-workflow simulation, artefact inspection and clean
+  installation, tagged-workflow review, and consumer-facing behaviour notes.
+
+[Unreleased]: https://github.com/icvoss/icv-trace/compare/v0.1.0rc4...HEAD
+[0.1.0rc4]: https://github.com/icvoss/icv-trace/releases/tag/v0.1.0rc4
+[0.1.0rc3]: https://github.com/icvoss/icv-trace/releases/tag/v0.1.0rc3
+[0.1.0rc2]: https://github.com/icvoss/icv-trace/releases/tag/v0.1.0rc2
+[0.1.0rc1]: https://github.com/icvoss/icv-trace/releases/tag/v0.1.0rc1

icv_trace-0.1.0rc4/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to icv-trace
+
+## Prerequisites
+
+- Python 3.11 or later
+- `uv` or pip
+
+The package is pure Python. Django, a database and ICV sibling packages are
+not required for development or tests.
+
+## Local setup and checks
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy src/icv_trace
+pytest tests -v --tb=short
+```
+
+Use conventional commits and work on a branch. Public behaviour is the
+package-root API and the `icv-trace.*.v1` contracts in
+[docs/contracts.md](docs/contracts.md). Preserve caller ownership of domain
+truth and safe facts, and host ownership of settings, transport, audit and
+error reporting. Update the normative package contracts in `docs/` alongside
+any change to supported behaviour.
+
+## Test modes
+
+The normal suite supports an editable installation. CI additionally runs a
+built-wheel job with `ICV_TRACE_REQUIRE_WHEEL=1`; it removes `src` from the
+import path and fails unless `icv_trace` resolves from `site-packages`.
+
+## Releasing
+
+See [RELEASING.md](RELEASING.md). A `v<version>` tag publishes to PyPI, so it
+is pushed only after all release gates pass on that exact commit. The release
+guide also records the transition for existing private-index consumers.

icv_trace-0.1.0rc4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nigel Copley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

icv_trace-0.1.0rc4/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include LICENSE
+include PROVENANCE.md
+include RELEASING.md
+include VERIFICATION.md
+recursive-include docs *.md
+recursive-include examples *.py

icv_trace-0.1.0rc4/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: icv-trace
+Version: 0.1.0rc4
+Summary: Bounded operation diagnostics, correlation and output health for Python hosts
+Author: Nigel Copley
+License: MIT
+Project-URL: Homepage, https://github.com/icvoss/icv-trace
+Project-URL: Documentation, https://github.com/icvoss/icv-trace/tree/main/docs
+Project-URL: Changelog, https://github.com/icvoss/icv-trace/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/icvoss/icv-trace/issues
+Project-URL: Source, https://github.com/icvoss/icv-trace
+Keywords: diagnostics,observability,trace,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Dynamic: license-file
+
+# icv-trace
+
+`icv-trace` is a pure-Python diagnostic boundary for meaningful operations.
+It creates correlation identity, attempts immediate baseline lifecycle records,
+admits bounded detail when enabled, and exposes local output health. It has no
+Django, database, ICV-package, logger or exporter dependency.
+
+The package consumes caller-selected safe scalar facts, a `TracePolicy`,
+`TraceSinks`, and optional parent or retry context. It produces human and
+JSONL records plus local sink health. The caller and host retain ownership of
+domain truth, persistence, policy resolution, destinations, propagation,
+error reporting, metrics and audit.
+
+## Install
+
+```bash
+python -m pip install "icv-trace==0.1.0rc4"
+```
+
+Public release candidates use PyPI and an explicit version as shown above.
+`0.1.0rc3` remains available from the private index at `pypi.icvoss.com` for
+existing consumers. Validate the explicit PyPI version before removing a
+private extra index, and retain that index while any other private dependency
+requires it. Install by distribution name, never by a sibling path.
+
+## Use
+
+The default `trace()` binding writes baseline records to stderr. It reads the
+documented `TRACE_*` environment values and has detail disabled by default.
+
+```python
+from icv_trace import trace
+
+with trace("catalogue.import", source="supplier") as operation:
+    operation.note("rows_loaded", count=12)
+    operation.result(imported=12, rejected=0)
+```
+
+For explicit policy and separate human and JSONL destinations, a host binds a
+callable. Sinks receive one complete rendered line and own writing, buffering
+and flushing it.
+
+```python
+import sys
+
+from icv_trace import TracePolicy, TraceSinks, bind_trace, textio_sink
+
+policy = TracePolicy(
+    TRACE_ENABLED=True,
+    TRACE_DESTINATIONS=("human", "structured"),
+    TRACE_MAX_DETAIL_EVENTS=100,
+    TRACE_MAX_BYTES=65536,
+)
+with open("trace.jsonl", "x", encoding="utf-8") as jsonl_file:
+    trace_scan = bind_trace(
+        lambda: policy,
+        TraceSinks(human=textio_sink(sys.stderr), structured=textio_sink(jsonl_file)),
+    )
+    with trace_scan("scan") as operation:
+        operation.note("classification", matched=4)
+        operation.result(completed=True)
+```
+
+`TRACE_ENABLED` controls additional detail only. Baseline START and END are
+attempted independently of `TRACE_ENABLED`, `DEBUG` and logging levels.
+`TextIOSink` rejects short writes and never flushes or closes the caller's
+stream. Logging, Eliot and OpenTelemetry trial adapters are retained as
+internal comparison code in `icv_trace.adapters`; they are not supported
+public delivery APIs.
+
+## Public API and contract
+
+The supported package-root exports are `trace`, `bind_trace`,
+`current_trace_context`, `emit_incomplete`, `capture_callback`, `TracePolicy`,
+`TraceSinks`, `TraceContext`, `TraceAttempt`, `TraceIncomplete`,
+`TraceOutputHealth`, `TraceHandle`, `TextIOSink`, `textio_sink`,
+`HumanRenderer`, `HumanTraceSink`, `TraceInputError`,
+`TraceConfigurationError` and `TraceSinkError`. The complete v1 input, output,
+failure and compatibility contracts are in [docs/contracts.md](docs/contracts.md).
+
+## Readable projection of structured traces
+
+`HumanRenderer` turns admitted JSONL records into compact, indented terminal
+lines. It has no Django or worker dependency and only retains a bounded set of
+open span identities for indentation. `HumanTraceSink` makes this useful with
+the existing core: bind the core to its `structured` input, then it writes the
+readable line and optionally forwards the original JSONL line unchanged.
+
+```python
+import sys
+from secrets import token_hex
+
+from icv_trace import (
+    HumanTraceSink, TraceContext, TraceIncomplete, TracePolicy, TraceSinks,
+    bind_trace, emit_incomplete, textio_sink, trace,
+)
+
+human_sink = HumanTraceSink(human=textio_sink(sys.stderr))
+policy = TracePolicy(TRACE_ENABLED=True, TRACE_DESTINATIONS=("structured",))
+run = bind_trace(lambda: policy, TraceSinks(structured=human_sink))
+
+with run("example.command", entrypoint="management_command") as command:
+    with trace("example.pipeline"):
+        with trace("example.service") as service:
+            service.note("loaded", count=2)
+            service.result(count=2)
+    command.result(completed=True)
+    command_context = command.context
+
+# This simulates a supervisor observation of a context it saved at dispatch.
+# A missing END alone never authorises an incomplete record.
+assert command_context is not None
+remote_context = TraceContext(command_context.trace_id, token_hex(8), token_hex(16), command_context.span_id)
+emit_incomplete(
+    TraceIncomplete(remote_context, "example.worker.task", "worker_lost"),
+    policy=policy,
+    sinks=TraceSinks(structured=human_sink),
+)
+```
+
+Labels can replace operation names for a particular host:
+
+```python
+from icv_trace import HumanRenderer
+
+renderer = HumanRenderer(labels={"example.command": "import command"})
+```
+
+Retry and continuation records include their attempt kind and number in this
+view. Correlation IDs remain in the original JSONL rather than the compact
+line. `HumanTraceSink.output_health` is sticky and must be checked separately
+from core trace health because the core sees the composite as one destination.
+The host owns prompt flushing: `textio_sink()` does not flush or close the
+stream. The human and optional JSONL callables must be different underlying
+channels. The adapter rejects the same callable object, but cannot detect two
+wrappers around one stream. Do not make either destination call the same
+`HumanTraceSink` recursively. If the host's warning channel is also broken,
+it cannot report that diagnostic failure elsewhere.
+
+The runnable dependency-free example mirrors a command invoking a pipeline of
+services. It writes compact output to stderr, can fan the original JSONL to a
+new file, and labels the remote incomplete record as an explicit simulated
+supervisor observation rather than an inference from a missing END. The
+[human-renderer guide](docs/human-renderer.md) covers labels, bounded nesting,
+fanout, health and host-owned task supervision.
+
+```bash
+python examples/human_trace.py
+python examples/human_trace.py --detail --jsonl-file trace.jsonl
+python examples/human_trace.py --fail
+python examples/human_trace.py --simulate-worker-lost
+```
+
+The same-thread `capture_callback()` bridge is bounded to its live owner and
+creator thread. It does not register callbacks or transfer work across
+threads or processes.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy src/icv_trace
+pytest tests -v --tb=short
+```
+
+The normal development suite permits the editable install. CI and release
+verification also build a wheel, install it without the source tree on the
+import path, and assert that `icv_trace` resolves from `site-packages`.
+
+## Documentation
+
+- [Contracts](docs/contracts.md): v1 inputs, policy and limits, records,
+  output health, task context and compatibility.
+- [Human renderer](docs/human-renderer.md): readable services, commands,
+  pipelines and task observations.
+- [Example](examples/human_trace.py): runnable dependency-free program.
+- [Contributing](CONTRIBUTING.md), [verification](VERIFICATION.md), and
+  [releasing](RELEASING.md): development and publication practice.
+
+## Provenance
+
+This package extracts the site-owned incubation core from icvlocal commit
+`087479b96929a56447c2ac8011011023b4df2dcd`. See
+[PROVENANCE.md](PROVENANCE.md) for historical source, retained hashes and
+extraction adaptations. The public package documentation above is sufficient
+to install and use the distribution; the historical material is not a runtime
+dependency.

icv_trace-0.1.0rc4/PROVENANCE.md

@@ -0,0 +1,40 @@
+# Historical extraction provenance
+
+This record explains the private incubation history. It is not required to
+install or use the package. Current public contracts are in
+[`docs/contracts.md`](docs/contracts.md) and
+[`docs/human-renderer.md`](docs/human-renderer.md).
+
+The package was extracted from site commit
+`087479b96929a56447c2ac8011011023b4df2dcd`, which includes the initial trial
+source, the local module-name substitution and the bounded callback-capture
+extension. The archived source remains under
+`docs/reviews/trace-adapter-trial-2026-09-08/` in the ICV OSS umbrella.
+
+| Archived file | SHA-256 |
+| --- | --- |
+| `runtime/src/trace_trial/core.py` | `c28fbce7140fb5a1e1b35b82d0bb180ca2c0407969ca781f8a023d8f494638b5` |
+| `runtime/src/trace_trial/adapters.py` | `8734ed435e3c2de4d5053f4ffe6aacc41bbbd72f5cb2fe52ccfaffbb9fd8a489` |
+| `checks/conftest.py` | `34989ba7b5e7d738d79746a12e448d004305c13c8f24e299bc238eef38107c1b` |
+| `checks/test_admission_precision.py` | `2c5d785fe76ad8d53a871c8db1c01cda2e9006d0c57c967aa62004b2ce10bba3` |
+| `checks/test_core_hardening.py` | `6c6c6f1662d69184613733590a23ca1ac9896d2d6180d2c776fdd7fb450f395d` |
+| `checks/test_invalid_child_admission.py` | `7d156e1dd344b1e1ca62916329b049df02ed49a0572294b00e1247629b29623b` |
+| `checks/test_trace_contract.py` | `f929a0d2b31e8a3ab7e451c66cba40a535fa1d7cc0ac4fe18aba3abcecf0bd34` |
+| `checks/test_trace_edges.py` | `7e359d32d57afc4d7f0cd3a258f5944f830a33c8b36fc13c55283a4b464547f2` |
+
+The extracted files are not byte-identical to the archive. The module import
+was substituted from `trace_trial` to `icv_trace`, and the callback bridge was
+added during incubation. Extraction adds packaging metadata, public module
+docstrings and `__version__`, and replaces the former `ICV_TRACE_SRC`
+source-mode fixture with a built-wheel origin guard. It also adds
+non-behavioural annotations and casts required by the blocking mypy gate, and
+removes one unused test import. The archived hashes above remain provenance for
+the source history; they are not hashes of the extracted files.
+
+At extraction time, the rejected comparison-adapter delivery selector was not
+a supported API. The historical statement that `TextIOSink` and `textio_sink`
+were the only supported delivery helpers predates the released human renderer.
+Today, `HumanRenderer` and `HumanTraceSink` are supported package-root APIs;
+the complete current surface is documented in the README. Logging, Eliot and
+OpenTelemetry helpers remain experimental comparison code, with no delivery or
+conformance promise.

icv_trace-0.1.0rc4/README.md

@@ -0,0 +1,191 @@
+# icv-trace
+
+`icv-trace` is a pure-Python diagnostic boundary for meaningful operations.
+It creates correlation identity, attempts immediate baseline lifecycle records,
+admits bounded detail when enabled, and exposes local output health. It has no
+Django, database, ICV-package, logger or exporter dependency.
+
+The package consumes caller-selected safe scalar facts, a `TracePolicy`,
+`TraceSinks`, and optional parent or retry context. It produces human and
+JSONL records plus local sink health. The caller and host retain ownership of
+domain truth, persistence, policy resolution, destinations, propagation,
+error reporting, metrics and audit.
+
+## Install
+
+```bash
+python -m pip install "icv-trace==0.1.0rc4"
+```
+
+Public release candidates use PyPI and an explicit version as shown above.
+`0.1.0rc3` remains available from the private index at `pypi.icvoss.com` for
+existing consumers. Validate the explicit PyPI version before removing a
+private extra index, and retain that index while any other private dependency
+requires it. Install by distribution name, never by a sibling path.
+
+## Use
+
+The default `trace()` binding writes baseline records to stderr. It reads the
+documented `TRACE_*` environment values and has detail disabled by default.
+
+```python
+from icv_trace import trace
+
+with trace("catalogue.import", source="supplier") as operation:
+    operation.note("rows_loaded", count=12)
+    operation.result(imported=12, rejected=0)
+```
+
+For explicit policy and separate human and JSONL destinations, a host binds a
+callable. Sinks receive one complete rendered line and own writing, buffering
+and flushing it.
+
+```python
+import sys
+
+from icv_trace import TracePolicy, TraceSinks, bind_trace, textio_sink
+
+policy = TracePolicy(
+    TRACE_ENABLED=True,
+    TRACE_DESTINATIONS=("human", "structured"),
+    TRACE_MAX_DETAIL_EVENTS=100,
+    TRACE_MAX_BYTES=65536,
+)
+with open("trace.jsonl", "x", encoding="utf-8") as jsonl_file:
+    trace_scan = bind_trace(
+        lambda: policy,
+        TraceSinks(human=textio_sink(sys.stderr), structured=textio_sink(jsonl_file)),
+    )
+    with trace_scan("scan") as operation:
+        operation.note("classification", matched=4)
+        operation.result(completed=True)
+```
+
+`TRACE_ENABLED` controls additional detail only. Baseline START and END are
+attempted independently of `TRACE_ENABLED`, `DEBUG` and logging levels.
+`TextIOSink` rejects short writes and never flushes or closes the caller's
+stream. Logging, Eliot and OpenTelemetry trial adapters are retained as
+internal comparison code in `icv_trace.adapters`; they are not supported
+public delivery APIs.
+
+## Public API and contract
+
+The supported package-root exports are `trace`, `bind_trace`,
+`current_trace_context`, `emit_incomplete`, `capture_callback`, `TracePolicy`,
+`TraceSinks`, `TraceContext`, `TraceAttempt`, `TraceIncomplete`,
+`TraceOutputHealth`, `TraceHandle`, `TextIOSink`, `textio_sink`,
+`HumanRenderer`, `HumanTraceSink`, `TraceInputError`,
+`TraceConfigurationError` and `TraceSinkError`. The complete v1 input, output,
+failure and compatibility contracts are in [docs/contracts.md](docs/contracts.md).
+
+## Readable projection of structured traces
+
+`HumanRenderer` turns admitted JSONL records into compact, indented terminal
+lines. It has no Django or worker dependency and only retains a bounded set of
+open span identities for indentation. `HumanTraceSink` makes this useful with
+the existing core: bind the core to its `structured` input, then it writes the
+readable line and optionally forwards the original JSONL line unchanged.
+
+```python
+import sys
+from secrets import token_hex
+
+from icv_trace import (
+    HumanTraceSink, TraceContext, TraceIncomplete, TracePolicy, TraceSinks,
+    bind_trace, emit_incomplete, textio_sink, trace,
+)
+
+human_sink = HumanTraceSink(human=textio_sink(sys.stderr))
+policy = TracePolicy(TRACE_ENABLED=True, TRACE_DESTINATIONS=("structured",))
+run = bind_trace(lambda: policy, TraceSinks(structured=human_sink))
+
+with run("example.command", entrypoint="management_command") as command:
+    with trace("example.pipeline"):
+        with trace("example.service") as service:
+            service.note("loaded", count=2)
+            service.result(count=2)
+    command.result(completed=True)
+    command_context = command.context
+
+# This simulates a supervisor observation of a context it saved at dispatch.
+# A missing END alone never authorises an incomplete record.
+assert command_context is not None
+remote_context = TraceContext(command_context.trace_id, token_hex(8), token_hex(16), command_context.span_id)
+emit_incomplete(
+    TraceIncomplete(remote_context, "example.worker.task", "worker_lost"),
+    policy=policy,
+    sinks=TraceSinks(structured=human_sink),
+)
+```
+
+Labels can replace operation names for a particular host:
+
+```python
+from icv_trace import HumanRenderer
+
+renderer = HumanRenderer(labels={"example.command": "import command"})
+```
+
+Retry and continuation records include their attempt kind and number in this
+view. Correlation IDs remain in the original JSONL rather than the compact
+line. `HumanTraceSink.output_health` is sticky and must be checked separately
+from core trace health because the core sees the composite as one destination.
+The host owns prompt flushing: `textio_sink()` does not flush or close the
+stream. The human and optional JSONL callables must be different underlying
+channels. The adapter rejects the same callable object, but cannot detect two
+wrappers around one stream. Do not make either destination call the same
+`HumanTraceSink` recursively. If the host's warning channel is also broken,
+it cannot report that diagnostic failure elsewhere.
+
+The runnable dependency-free example mirrors a command invoking a pipeline of
+services. It writes compact output to stderr, can fan the original JSONL to a
+new file, and labels the remote incomplete record as an explicit simulated
+supervisor observation rather than an inference from a missing END. The
+[human-renderer guide](docs/human-renderer.md) covers labels, bounded nesting,
+fanout, health and host-owned task supervision.
+
+```bash
+python examples/human_trace.py
+python examples/human_trace.py --detail --jsonl-file trace.jsonl
+python examples/human_trace.py --fail
+python examples/human_trace.py --simulate-worker-lost
+```
+
+The same-thread `capture_callback()` bridge is bounded to its live owner and
+creator thread. It does not register callbacks or transfer work across
+threads or processes.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy src/icv_trace
+pytest tests -v --tb=short
+```
+
+The normal development suite permits the editable install. CI and release
+verification also build a wheel, install it without the source tree on the
+import path, and assert that `icv_trace` resolves from `site-packages`.
+
+## Documentation
+
+- [Contracts](docs/contracts.md): v1 inputs, policy and limits, records,
+  output health, task context and compatibility.
+- [Human renderer](docs/human-renderer.md): readable services, commands,
+  pipelines and task observations.
+- [Example](examples/human_trace.py): runnable dependency-free program.
+- [Contributing](CONTRIBUTING.md), [verification](VERIFICATION.md), and
+  [releasing](RELEASING.md): development and publication practice.
+
+## Provenance
+
+This package extracts the site-owned incubation core from icvlocal commit
+`087479b96929a56447c2ac8011011023b4df2dcd`. See
+[PROVENANCE.md](PROVENANCE.md) for historical source, retained hashes and
+extraction adaptations. The public package documentation above is sufficient
+to install and use the distribution; the historical material is not a runtime
+dependency.

icv_trace-0.1.0rc4/RELEASING.md

@@ -0,0 +1,58 @@
+# Releasing icv-trace
+
+`0.1.0rc3` remains available from the private index at `pypi.icvoss.com`.
+The public repository publishes new releases to PyPI through the GitHub Actions
+trusted publisher.
+Pushing a `v<semver>` tag is irreversible and must point to the merged `main`
+commit.
+
+This is a pure-Python package. There are no Django, database or migration
+legs, but static, built-wheel and clean-environment checks are required.
+
+## Before tagging
+
+Record all six gates for the exact commit:
+
+1. `pyproject.toml` and `src/icv_trace/__init__.py` contain the same version,
+   and `CHANGELOG.md` has a dated matching heading with nothing to ship under
+   Unreleased.
+2. Every lint, mypy and Python 3.11 through 3.14 test leg in `ci.yml` is green.
+3. In a clean virtual environment, reproduce the `publish.yml` install list
+   and pass its installed-wheel test command.
+4. Build wheel and sdist, run `twine check`, inspect the wheel for
+   `icv_trace`, `core.py`, `adapters.py`, `human.py` and `py.typed`, then
+   install the wheel cleanly and import the documented package-root API. After
+   publication repeat the installation by name from the target index.
+5. Review the tagged commit's own `publish.yml`.
+6. State all existing-consumer behaviour in the release notes. For `0.1.0rc3`,
+   the human renderer is opt-in and core record semantics remain unchanged.
+   Logging, Eliot and OpenTelemetry helpers remain experimental and unsupported.
+
+## Tag
+
+```bash
+git checkout main
+git pull
+git tag v<version>
+git push origin v<version>
+```
+
+Confirm the workflow publishes to PyPI, creates the appropriate release
+record, and that the package installs by name. Do not move a tag. If any gate
+or publish step fails, fix it on a new commit and publish a new release-
+candidate version.
+
+## Public PyPI release and private-index transition
+
+The repository is public and its trusted publisher is restricted to
+`icvoss/icv-trace`, workflow `publish.yml`, environment `pypi`. Run every gate
+above against the exact commit whose workflow targets PyPI, including a clean
+PyPI installation after publication.
+
+The first public version is a deliberate compatibility point. Release notes
+must state the upgrade path for private-index consumers: pin the version while
+validating the PyPI artefact, remove the private extra index only after all
+private dependencies are absent, and retain the private index where other
+private packages still require it. Do not replace an existing tag or silently
+move consumers across indexes. Record the target index, installed artefact
+version and consumer-visible behaviour in the release evidence.