policyengine-observability 0.2.1__tar.gz → 0.3.0__tar.gz

policyengine_observability-0.3.0/.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+# Copilot Instructions
+
+Repository-wide AI-facing engineering guidance lives in `AGENTS.md`.
+Canonical skills live under `docs/engineering/skills/`.
+
+Use those files as the source of truth. Keep this adapter thin and avoid
+duplicating detailed testing, CI, formatting, release, or architecture rules.

policyengine_observability-0.3.0/AGENTS.md

@@ -0,0 +1,23 @@
+# Agent Instructions
+
+These instructions apply repository-wide.
+
+## Skills System
+
+Canonical AI-facing engineering skills live under `docs/engineering/skills/`.
+Use those files as the source of truth across Codex, Claude, Copilot, and other
+AI tools.
+
+Before opening, replacing, or sharing any pull request, read
+`docs/engineering/skills/github-prs.md`.
+
+Before making or reviewing repository-wide API, testing, documentation, release,
+or package-boundary changes, read
+`docs/engineering/skills/repository-guidance.md`.
+
+## Repository Boundaries
+
+`policyengine-observability` is the shared PolicyEngine observability runtime.
+Keep framework-specific behavior in adapters or integrations, keep the core
+runtime usable outside HTTP requests, and keep observability failures from
+breaking application code.

{policyengine_observability-0.2.1 → policyengine_observability-0.3.0}/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.3.0] - 2026-06-23
+
+### Added
+
+- Add model-agnostic AI harness instructions and canonical engineering skills.
+
+### Fixed
+
+- Preserve internal dispatch segment timings on the parent worker operation log.
+
+
 ## [0.2.1] - 2026-06-22
 
 ### Changed

policyengine_observability-0.3.0/CLAUDE.md

@@ -0,0 +1,21 @@
+# Claude Instructions
+
+These instructions apply repository-wide.
+
+## Canonical Guidance
+
+Repository-wide AI-facing engineering guidance lives in `AGENTS.md`.
+Canonical skills live under `docs/engineering/skills/`.
+
+Use those files as the source of truth. This file is a Claude adapter and should
+stay thin; do not duplicate detailed testing, CI, formatting, release, or
+architecture rules here.
+
+## Required Skill Lookup
+
+Before opening, replacing, or sharing a PR, read
+`docs/engineering/skills/github-prs.md`.
+
+Before making or reviewing repository-wide API, testing, documentation, release,
+or package-boundary changes, read
+`docs/engineering/skills/repository-guidance.md`.

{policyengine_observability-0.2.1 → policyengine_observability-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine-observability
-Version: 0.2.1
+Version: 0.3.0
 Summary: Shared PolicyEngine observability runtime for logs, timings, metrics, and OpenTelemetry.
 Author-email: PolicyEngine <hello@policyengine.org>
 Requires-Python: >=3.12

policyengine_observability-0.3.0/docs/engineering/skills/README.md

@@ -0,0 +1,16 @@
+# Engineering Skills
+
+This directory is the canonical source for AI-facing engineering rules.
+
+Tool-specific instruction files such as `AGENTS.md`, `CLAUDE.md`, and
+`.github/copilot-instructions.md` should point here instead of duplicating
+implementation-specific guidance. When a rule changes, update the skill here
+first, then keep adapters thin.
+
+Current skills:
+
+- `github-prs.md`: same-repository PR workflow, required pre-PR checks,
+  changelog-fragment requirements, final formatter/linter requirements, PR head
+  verification, and title conventions.
+- `repository-guidance.md`: package structure, commands, runtime boundaries,
+  test expectations, release expectations, and repo-specific anti-patterns.

policyengine_observability-0.3.0/docs/engineering/skills/github-prs.md

@@ -0,0 +1,46 @@
+# GitHub PRs
+
+These rules apply to every developer and AI agent opening pull requests in this
+repository.
+
+## Same-Repository PRs
+
+Open PRs from branches in `PolicyEngine/policyengine-observability`, not from
+personal forks. Fork PRs are more likely to miss repository secrets and can
+produce different CI behavior from branches in the canonical repository.
+
+Before creating or sharing a PR:
+
+1. Confirm the canonical repository is reachable:
+   `gh repo view PolicyEngine/policyengine-observability --json nameWithOwner`.
+2. Open a GitHub issue for the work, or verify that an appropriate issue
+   already exists.
+3. Put `Fixes #ISSUE_NUMBER` as the first line of the PR description, using the
+   issue number from the issue created or found in the previous step.
+4. Add a Towncrier changelog fragment under `changelog.d/` using the issue
+   number or a clear slug and the appropriate configured type, for example
+   `changelog.d/ISSUE_NUMBER.fixed.md`.
+5. Before the final commit in the PR, run the formatter and linter:
+   `uv run --extra dev ruff format .` and
+   `uv run --extra dev ruff check .`. If formatting changes files, review and
+   stage those changes before committing.
+6. Run tests with coverage:
+   `uv run --extra dev --extra all coverage run -m pytest` and
+   `uv run --extra dev --extra all coverage report`.
+7. Push the current branch to the canonical repository:
+   `git push origin HEAD`.
+8. Create the PR as a draft from that same repository:
+   `gh pr create --draft --repo PolicyEngine/policyengine-observability --head "$(git branch --show-current)" --base main`.
+9. Verify the PR is draft and the head repository is canonical:
+   `gh pr view <PR> --repo PolicyEngine/policyengine-observability --json isDraft,headRepositoryOwner,headRepository`.
+10. Before sharing the PR, verify CI has been checked:
+    `gh pr checks <PR> --repo PolicyEngine/policyengine-observability`.
+
+If you cannot push to the canonical repository, stop and ask for access. Do not
+create a fork PR as a fallback. If you accidentally create one, close it and
+replace it with a same-repository draft PR.
+
+## PR Title
+
+Do not add `[codex]`, `[claude]`, `[copilot]`, or other agent labels to PR
+titles. Use a plain descriptive title.

policyengine_observability-0.3.0/docs/engineering/skills/repository-guidance.md

@@ -0,0 +1,80 @@
+# Repository Guidance
+
+Use this skill when making or reviewing repository-wide API, testing,
+documentation, release, or package-boundary changes.
+
+## Commands
+
+```bash
+uv sync --extra dev --extra all
+uv run --extra dev ruff format .
+uv run --extra dev ruff format --check .
+uv run --extra dev ruff check .
+uv run --extra dev --extra all coverage run -m pytest
+uv run --extra dev --extra all coverage report
+uv build
+```
+
+To check for a changelog fragment locally:
+
+```bash
+uv run --extra dev towncrier check --compare-with origin/main
+```
+
+## What Lives Here
+
+- `policyengine_observability/config.py` resolves environment-driven runtime
+  configuration.
+- `policyengine_observability/context.py` defines request and operation log
+  payload structures.
+- `policyengine_observability/runtime.py` owns context management, segments,
+  structured logs, metrics, traces, events, and fail-open behavior.
+- `policyengine_observability/adapters/` contains framework adapters such as
+  Flask and FastAPI.
+- `policyengine_observability/integrations/` contains optional integrations
+  such as HTTP client instrumentation.
+- `.github/` contains changelog, versioning, tagging, and PyPI publication
+  automation.
+- `tests/` should cover runtime behavior, framework adapters, public exports,
+  and release scripts.
+
+## Design Boundaries
+
+- Keep the core runtime framework-agnostic. HTTP frameworks belong in adapters.
+- Keep the context-manager API usable from HTTP requests, worker functions,
+  CLI scripts, and tests.
+- Keep OpenTelemetry optional and lazily imported. Timing and structured
+  logging must work without an OTel backend.
+- Observability failures must fail open: record an internal observability error
+  when practical, but do not break the application operation being observed.
+- Preserve structured log schemas. Make additive changes when possible; bump
+  schema versions for breaking payload changes.
+- Keep metric attributes bounded and low-cardinality. Do not put raw paths,
+  full URLs, request bodies, or unbounded user-provided values into metric
+  labels.
+- Keep segment names stable. Prefer registered segment enums in consuming
+  applications, while preserving safe string fallback behavior.
+
+## Testing
+
+Add focused tests for runtime context behavior and failure paths whenever
+changing `runtime.py`. Adapter changes should include framework-level tests that
+exercise request setup, response headers, error paths, and teardown behavior.
+
+Release automation changes should include tests for the helper scripts when the
+logic is non-trivial.
+
+## Release Expectations
+
+Every behavior change should include a Towncrier fragment in `changelog.d/`.
+The push workflow builds the changelog, bumps the package version, tags the
+release, and publishes to PyPI through trusted publishing.
+
+## Anti-Patterns
+
+- Do not add a hard dependency on a specific observability vendor.
+- Do not require OTel configuration for logs or timings to function.
+- Do not duplicate framework behavior in the core runtime.
+- Do not swallow application exceptions from observed code.
+- Do not use `[codex]`, `[claude]`, `[copilot]`, or other agent labels in PR
+  titles.

{policyengine_observability-0.2.1 → policyengine_observability-0.3.0}/policyengine_observability/runtime.py

@@ -306,6 +306,11 @@ class ObservabilityRuntime:
         context: RequestObservabilityContext,
     ) -> None:
         try:
+            parent_operation = _OPERATION_CONTEXT.get()
+            timings = context.timings_ms
+            if context.internal_dispatch and parent_operation is not None:
+                timings = parent_operation.timings_ms
+                context.timings_ms = timings
             operation = OperationObservabilityContext(
                 config=context.config,
                 name=context.route,
@@ -316,7 +321,7 @@ class ObservabilityRuntime:
                     "endpoint": context.endpoint,
                     "path": context.path,
                 },
-                timings_ms=context.timings_ms,
+                timings_ms=timings,
                 emit_log=False,
                 record_metric=False,
             )

{policyengine_observability-0.2.1 → policyengine_observability-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "policyengine-observability"
-version = "0.2.1"
+version = "0.3.0"
 description = "Shared PolicyEngine observability runtime for logs, timings, metrics, and OpenTelemetry."
 readme = "README.md"
 authors = [{ name = "PolicyEngine", email = "hello@policyengine.org" }]

{policyengine_observability-0.2.1 → policyengine_observability-0.3.0}/tests/test_runtime.py

@@ -628,6 +628,78 @@ def test_request_lifecycle_records_headers_and_context_metrics() -> None:
     assert observed.requests.calls[0][1] == 1
 
 
+def test_internal_dispatch_segments_merge_into_parent_operation() -> None:
+    observed = runtime()
+    handle = observed.start_operation(
+        "modal_worker_dispatch",
+        flavor="modal_worker",
+    )
+    parent_operation = handle["operation"]
+    context = RequestObservabilityContext(
+        config=observed.config,
+        request_id="request-1",
+        method="POST",
+        route="/calculate",
+        path="/calculate",
+        endpoint="calculate",
+        query_keys=[],
+        content_length_bytes=None,
+        inbound={},
+        internal_dispatch=True,
+    )
+
+    try:
+        observed.begin_request(context)
+        with observed.segment(SegmentName.LOAD):
+            pass
+        observed.finish_request(200)
+        observed.teardown_request(None)
+
+        assert context.timings_ms is parent_operation.timings_ms
+        assert "load" in parent_operation.timings_ms
+        assert observed.current_operation() is parent_operation
+    finally:
+        observed.end_operation(handle)
+
+    assert observed.current_context() is None
+    assert observed.current_operation() is None
+
+
+def test_non_internal_request_timings_do_not_leak_to_parent_operation() -> (
+    None
+):
+    observed = runtime()
+    handle = observed.start_operation("job", flavor="worker")
+    parent_operation = handle["operation"]
+    context = RequestObservabilityContext(
+        config=observed.config,
+        request_id="request-1",
+        method="POST",
+        route="/calculate",
+        path="/calculate",
+        endpoint="calculate",
+        query_keys=[],
+        content_length_bytes=None,
+        inbound={},
+    )
+
+    try:
+        observed.begin_request(context)
+        with observed.segment(SegmentName.LOAD):
+            pass
+        observed.finish_request(200)
+        observed.teardown_request(None)
+
+        assert context.timings_ms is not parent_operation.timings_ms
+        assert "load" not in parent_operation.timings_ms
+        assert observed.current_operation() is parent_operation
+    finally:
+        observed.end_operation(handle)
+
+    assert observed.current_context() is None
+    assert observed.current_operation() is None
+
+
 def test_request_methods_noop_without_current_context() -> None:
     observed = runtime()
 

{policyengine_observability-0.2.1 → policyengine_observability-0.3.0}/uv.lock

@@ -658,7 +658,7 @@ wheels = [
 
 [[package]]
 name = "policyengine-observability"
-version = "0.2.1"
+version = "0.3.0"
 source = { editable = "." }
 
 [package.optional-dependencies]