plm-shared 0.1.0__tar.gz

plm_shared-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: plm-shared
+Version: 0.1.0
+Summary: TracePulse PLM shared contracts: Kernel API surface, idempotency, capabilities, knowledge envelope, pricing, artifact store, trace context. Frozen in US-W1.0; consumed by US-W1.1+ and US-CR.0+.
+Author: TracePulse
+License: Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: starlette<1.0,>=0.27
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: db
+Requires-Dist: SQLAlchemy>=2.0; extra == "db"
+Requires-Dist: psycopg[binary]>=3.1; extra == "db"
+Requires-Dist: alembic>=1.13; extra == "db"
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == "s3"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: httpx<1.0,>=0.27; extra == "test"
+
+# plm-shared
+
+Frozen contracts shared across TracePulse PLM product lines (Core,
+Skill Kernel, Skill Packages, Knowledge, Workbench, Studio,
+Connectors). Owned by US-W1.0; consumed by US-W1.1 → US-W1.13 and
+US-CR.0 → US-CR.13 without modification.
+
+US-W1.0 ships in 7 PRs:
+
+| PR  | Scope                                                             |
+|-----|-------------------------------------------------------------------|
+| PR-1 | package skeleton + Pydantic models + IdempotencyKey + Capability |
+| PR-2 | Alembic migrations 0001-0007 + SQLAlchemy ORM + `db.py`          |
+| PR-3 | migration 0008 (Postgres roles) + append-only audit suite         |
+| PR-4 | migration 0009 (RLS) + `middleware.py` + tenant-isolation audit   |
+| PR-5 | `ObjectStoreBackend` (S3 wire protocol) + `[s3]` extra + tests    |
+| PR-6 | `SqlAlchemyKernelEmitter` + migration 0011 (pricing dedup) + integ |
+| PR-7 | `import-linter` contracts + BL5 + CI workflow + AC + QA + close   |
+
+## Surface
+
+| Module                      | Purpose                                                     |
+|-----------------------------|-------------------------------------------------------------|
+| `kernel_api`                | Pydantic args + `KernelEmitter` Protocol (frozen)           |
+| `sqlalchemy_kernel_emitter` | Concrete `SqlAlchemyKernelEmitter` impl (PR-6)              |
+| `idempotency`               | `IdempotencyKey` + `compute_content_hash`                   |
+| `capabilities`              | `Capability` enum + YAML loader                             |
+| `knowledge_envelope`        | `KnowledgeEnvelopeV1` frozen schema                         |
+| `trace_context`             | `TraceContext` ContextVar + W0.6 bridge                     |
+| `pricing`                   | `compute_cost` + `CostStatus` + `PricingSnapshot` dataclass |
+| `artifact_store`            | `ArtifactStorageBackend` Protocol + `LocalFilesystemBackend` + `ObjectStoreBackend` |
+| `middleware`                | `PlmTenantMiddleware` (ASGI) + `parse_core_caller` + `cors_allowed_headers` |
+| `db`                        | SQLAlchemy 2.0 ORM models + `tenant_scoped_session`         |
+
+## Kernel API (US-W1.0 / AC-2)
+
+`plm_shared.kernel_api.KernelEmitter` is the **frozen** 4-method
+Protocol that every product line uses to record events. The
+authorised emitter boundary is Core: product lines submit decisions
+to Core (e.g. Workbench routes HITL approvals), and Core is the
+authorised emitter through `plm-shared`.
+
+### Protocol
+
+```python
+from plm_shared.kernel_api import KernelEmitter
+from plm_shared.kernel_api import (
+    EmitTelemetryArgs,
+    EmitGovernanceArgs,
+    EmitLlmCallArgs,
+    EmitConnectorCallArgs,
+)
+
+class KernelEmitter(Protocol):
+    def emit_telemetry(self, args: EmitTelemetryArgs) -> None: ...
+    def emit_governance(self, args: EmitGovernanceArgs) -> None: ...
+    def record_llm_call(self, args: EmitLlmCallArgs) -> None: ...
+    def record_connector_call(self, args: EmitConnectorCallArgs) -> None: ...
+```
+
+Every method returns `None` on success — including the **silent replay**
+path (200 OK: same key + same content). A logical-key collision
+(same identity, different content) raises
+`plm_shared.sqlalchemy_kernel_emitter.IdempotencyConflict`.
+
+### Args
+
+```python
+EmitTelemetryArgs(
+    event_type:      str,                  # e.g. "knowledge_call"
+    span_id:         str,
+    capability:      str,                  # capability tag for the event
+    payload:         Dict[str, Any] = {},  # event-specific shape
+    idempotency_key: IdempotencyKey,
+)
+
+EmitGovernanceArgs(
+    governance_event_type: str,            # e.g. "hitl_resolved"
+    span_id:               str,
+    payload:               Dict[str, Any] = {},
+    idempotency_key:       IdempotencyKey,
+)
+
+EmitLlmCallArgs(
+    span_id:           str,
+    model:             str,
+    prompt_tokens:     int,
+    completion_tokens: int,
+    pricing_version:   str,                 # "litellm-live" | "overrides-static" | "unavailable"
+    cost_eur:          Optional[float] = None,
+    cost_status:       str,                 # "pending" | "calculated" | "unavailable"
+    idempotency_key:   IdempotencyKey,
+)
+
+EmitConnectorCallArgs(
+    span_id:         str,
+    connector_id:    str,                   # e.g. "3dx-rest"
+    capability:      str,                   # e.g. "read.parts"
+    envelope:        Dict[str, Any] = {},
+    pricing_version: str,
+    cost_eur:        Optional[float] = None,
+    cost_status:     str,
+    idempotency_key: IdempotencyKey,
+)
+```
+
+### Concrete emitter — `SqlAlchemyKernelEmitter`
+
+```python
+from plm_shared.sqlalchemy_kernel_emitter import (
+    IdempotencyConflict,
+    SqlAlchemyKernelEmitter,
+)
+from plm_shared.idempotency import IdempotencyKey, compute_content_hash
+from plm_shared.kernel_api import EmitLlmCallArgs
+
+tenant_id = "00000000-0000-0000-0000-000000000000"
+emitter = SqlAlchemyKernelEmitter(tenant_id=tenant_id)
+
+payload = {"model": "gpt-4o", "prompt_tokens": 100}
+key = IdempotencyKey(
+    tenant_id=tenant_id,
+    trace_id="trace-X",
+    span_id="span-1",
+    event_type="llm_call",
+    content_hash=compute_content_hash(payload),
+)
+
+try:
+    emitter.record_llm_call(EmitLlmCallArgs(
+        span_id="span-1",
+        model="gpt-4o",
+        prompt_tokens=100,
+        completion_tokens=50,
+        pricing_version="litellm-live",
+        cost_eur=0.0042,
+        cost_status="calculated",
+        idempotency_key=key,
+    ))
+    # 200 — inserted, OR 200 — silent replay (same key + same content)
+except IdempotencyConflict:
+    # 409 — same logical identity, different content
+    raise
+```
+
+The emitter:
+
+- Opens a `tenant_scoped_session(tenant_id)` so RLS engages on INSERT
+  (migration 0009 — fail-closed for an unset GUC).
+- Stamps the `idempotency_key` UNIQUE; on collision, dispatches by
+  constraint name (`<table>_idempotency_key_key` → 200 silent replay,
+  `uq_<table>_logical` → 409 raise).
+- For LLM and connector calls, upserts a `pricing_snapshots` row keyed
+  on `(tenant_id, model, snapshot_date)` (migration 0011) and stores
+  the FK on the call row. `pricing_version="unavailable"` skips the
+  snapshot — the `cost_status` column carries the authoritative signal.
+
+### Backend wiring (deferred to US-CR.0)
+
+`PlmTenantMiddleware` is published in `plm_shared.middleware` but is
+NOT yet installed in `02_App/backend/main.py`. US-CR.0 owns the
+ordering — it adds `IdentityMiddleware` first, then plumbs
+`PlmTenantMiddleware` behind it, then wires CORS so that
+`CORSMiddleware` wraps both (failure responses still carry CORS
+headers). Conv D leaves the middleware available-but-unwired so
+US-CR.0 lands the full ordering in one place.
+
+## Migration chain
+
+| Rev | Subject                                                       |
+|-----|---------------------------------------------------------------|
+| 0001 | foundational tables `tenants`, `runs` + `quality_level` ENUM + `actor_kind` ENUM |
+| 0002 | `telemetry_events` + composite index + UNIQUE `idempotency_key` |
+| 0003 | `llm_calls` + `cost_*` columns + UNIQUE `idempotency_key`     |
+| 0004 | `connector_calls` + connector-specific fields                |
+| 0005 | `artifacts` + storage_uri + retention_until                   |
+| 0006 | quality_level + cost_status transition triggers               |
+| 0007 | `mcrc_v1_view` (§1-§8 projection)                             |
+| 0008 | Postgres roles `plm_kernel_writer` + `plm_migrator`           |
+| 0009 | Row-Level Security on the 5 tenant-scoped tables + `plm_migrator BYPASSRLS` |
+| 0010 | logical UNIQUE constraints (backs the 200/409 IdempotencyKey contract) |
+| 0011 | `pricing_snapshots` dedup table + nullable FKs                |
+| 0012 | `plm_migrator` table privileges (SELECT/INSERT/UPDATE/DELETE on the 7 tenant-scoped tables — closes the privilege gap surfaced by the live-Postgres validation event; BYPASSRLS alone does not grant table access) |
+
+Run the chain with `alembic upgrade head` from `02_App/plm-shared/`
+(needs `PG_DSN` exported).
+
+## Install (developer)
+
+From the `02_App/backend/` virtualenv:
+
+```bash
+cd 02_App/backend
+pip install -e ../plm-shared           # base install
+pip install -e "../plm-shared[db]"     # + SQLAlchemy / psycopg / alembic
+pip install -e "../plm-shared[s3]"     # + boto3 (ObjectStoreBackend)
+pip install -e "../plm-shared[db,s3]"  # combined
+```
+
+The `02_App/backend/requirements.txt` already lists `-e ../plm-shared`
+so a clean `pip install -r requirements.txt` from `02_App/backend/`
+picks it up. **`pip install` MUST run from `02_App/backend/`** because
+pip resolves the editable path relative to the invocation CWD.
+
+## Tests
+
+```bash
+cd 02_App/plm-shared
+python -m pytest tests/ -v
+```
+
+Audit + migration suites under `tests/audit/` and `tests/migrations/`
+are gated on `PG_DSN`. Bring up the dev compose first:
+
+```bash
+docker compose -f dev/postgres.yml up -d
+export PG_DSN=postgresql+psycopg://tracepulse:tracepulse@localhost:5432/tracepulse_dev
+cd 02_App/plm-shared
+python -m pytest tests/audit/ tests/migrations/ -v
+```
+
+S3-protocol live tests under `tests/test_object_store_backend.py` gate
+on `S3_ENDPOINT_URL` (skip-when-unset). Bring up minio (or any
+S3-protocol endpoint) and export `S3_ENDPOINT_URL`, `S3_ACCESS_KEY`,
+`S3_SECRET_KEY`, `S3_BUCKET`.
+
+## Architecture conformance gate (US-W1.0 / AC-4)
+
+`pyproject.toml` declares one `[tool.importlinter]` Forbidden contract
+banning `sqlalchemy` from every plm-shared module except `db` and
+`sqlalchemy_kernel_emitter`. Run it from the package root:
+
+```bash
+cd 02_App/plm-shared
+lint-imports --config pyproject.toml
+```
+
+The companion **BL5** rule in
+`02_App/backend/scripts/architecture_guardrails.py` (warn-only at
+launch) regex-scans for `INSERT INTO {telemetry_events|llm_calls|connector_calls|pricing_snapshots}`
+outside `kernel_api` / `sqlalchemy_kernel_emitter` / migrations.

plm_shared-0.1.0/README.md

@@ -0,0 +1,241 @@
+# plm-shared
+
+Frozen contracts shared across TracePulse PLM product lines (Core,
+Skill Kernel, Skill Packages, Knowledge, Workbench, Studio,
+Connectors). Owned by US-W1.0; consumed by US-W1.1 → US-W1.13 and
+US-CR.0 → US-CR.13 without modification.
+
+US-W1.0 ships in 7 PRs:
+
+| PR  | Scope                                                             |
+|-----|-------------------------------------------------------------------|
+| PR-1 | package skeleton + Pydantic models + IdempotencyKey + Capability |
+| PR-2 | Alembic migrations 0001-0007 + SQLAlchemy ORM + `db.py`          |
+| PR-3 | migration 0008 (Postgres roles) + append-only audit suite         |
+| PR-4 | migration 0009 (RLS) + `middleware.py` + tenant-isolation audit   |
+| PR-5 | `ObjectStoreBackend` (S3 wire protocol) + `[s3]` extra + tests    |
+| PR-6 | `SqlAlchemyKernelEmitter` + migration 0011 (pricing dedup) + integ |
+| PR-7 | `import-linter` contracts + BL5 + CI workflow + AC + QA + close   |
+
+## Surface
+
+| Module                      | Purpose                                                     |
+|-----------------------------|-------------------------------------------------------------|
+| `kernel_api`                | Pydantic args + `KernelEmitter` Protocol (frozen)           |
+| `sqlalchemy_kernel_emitter` | Concrete `SqlAlchemyKernelEmitter` impl (PR-6)              |
+| `idempotency`               | `IdempotencyKey` + `compute_content_hash`                   |
+| `capabilities`              | `Capability` enum + YAML loader                             |
+| `knowledge_envelope`        | `KnowledgeEnvelopeV1` frozen schema                         |
+| `trace_context`             | `TraceContext` ContextVar + W0.6 bridge                     |
+| `pricing`                   | `compute_cost` + `CostStatus` + `PricingSnapshot` dataclass |
+| `artifact_store`            | `ArtifactStorageBackend` Protocol + `LocalFilesystemBackend` + `ObjectStoreBackend` |
+| `middleware`                | `PlmTenantMiddleware` (ASGI) + `parse_core_caller` + `cors_allowed_headers` |
+| `db`                        | SQLAlchemy 2.0 ORM models + `tenant_scoped_session`         |
+
+## Kernel API (US-W1.0 / AC-2)
+
+`plm_shared.kernel_api.KernelEmitter` is the **frozen** 4-method
+Protocol that every product line uses to record events. The
+authorised emitter boundary is Core: product lines submit decisions
+to Core (e.g. Workbench routes HITL approvals), and Core is the
+authorised emitter through `plm-shared`.
+
+### Protocol
+
+```python
+from plm_shared.kernel_api import KernelEmitter
+from plm_shared.kernel_api import (
+    EmitTelemetryArgs,
+    EmitGovernanceArgs,
+    EmitLlmCallArgs,
+    EmitConnectorCallArgs,
+)
+
+class KernelEmitter(Protocol):
+    def emit_telemetry(self, args: EmitTelemetryArgs) -> None: ...
+    def emit_governance(self, args: EmitGovernanceArgs) -> None: ...
+    def record_llm_call(self, args: EmitLlmCallArgs) -> None: ...
+    def record_connector_call(self, args: EmitConnectorCallArgs) -> None: ...
+```
+
+Every method returns `None` on success — including the **silent replay**
+path (200 OK: same key + same content). A logical-key collision
+(same identity, different content) raises
+`plm_shared.sqlalchemy_kernel_emitter.IdempotencyConflict`.
+
+### Args
+
+```python
+EmitTelemetryArgs(
+    event_type:      str,                  # e.g. "knowledge_call"
+    span_id:         str,
+    capability:      str,                  # capability tag for the event
+    payload:         Dict[str, Any] = {},  # event-specific shape
+    idempotency_key: IdempotencyKey,
+)
+
+EmitGovernanceArgs(
+    governance_event_type: str,            # e.g. "hitl_resolved"
+    span_id:               str,
+    payload:               Dict[str, Any] = {},
+    idempotency_key:       IdempotencyKey,
+)
+
+EmitLlmCallArgs(
+    span_id:           str,
+    model:             str,
+    prompt_tokens:     int,
+    completion_tokens: int,
+    pricing_version:   str,                 # "litellm-live" | "overrides-static" | "unavailable"
+    cost_eur:          Optional[float] = None,
+    cost_status:       str,                 # "pending" | "calculated" | "unavailable"
+    idempotency_key:   IdempotencyKey,
+)
+
+EmitConnectorCallArgs(
+    span_id:         str,
+    connector_id:    str,                   # e.g. "3dx-rest"
+    capability:      str,                   # e.g. "read.parts"
+    envelope:        Dict[str, Any] = {},
+    pricing_version: str,
+    cost_eur:        Optional[float] = None,
+    cost_status:     str,
+    idempotency_key: IdempotencyKey,
+)
+```
+
+### Concrete emitter — `SqlAlchemyKernelEmitter`
+
+```python
+from plm_shared.sqlalchemy_kernel_emitter import (
+    IdempotencyConflict,
+    SqlAlchemyKernelEmitter,
+)
+from plm_shared.idempotency import IdempotencyKey, compute_content_hash
+from plm_shared.kernel_api import EmitLlmCallArgs
+
+tenant_id = "00000000-0000-0000-0000-000000000000"
+emitter = SqlAlchemyKernelEmitter(tenant_id=tenant_id)
+
+payload = {"model": "gpt-4o", "prompt_tokens": 100}
+key = IdempotencyKey(
+    tenant_id=tenant_id,
+    trace_id="trace-X",
+    span_id="span-1",
+    event_type="llm_call",
+    content_hash=compute_content_hash(payload),
+)
+
+try:
+    emitter.record_llm_call(EmitLlmCallArgs(
+        span_id="span-1",
+        model="gpt-4o",
+        prompt_tokens=100,
+        completion_tokens=50,
+        pricing_version="litellm-live",
+        cost_eur=0.0042,
+        cost_status="calculated",
+        idempotency_key=key,
+    ))
+    # 200 — inserted, OR 200 — silent replay (same key + same content)
+except IdempotencyConflict:
+    # 409 — same logical identity, different content
+    raise
+```
+
+The emitter:
+
+- Opens a `tenant_scoped_session(tenant_id)` so RLS engages on INSERT
+  (migration 0009 — fail-closed for an unset GUC).
+- Stamps the `idempotency_key` UNIQUE; on collision, dispatches by
+  constraint name (`<table>_idempotency_key_key` → 200 silent replay,
+  `uq_<table>_logical` → 409 raise).
+- For LLM and connector calls, upserts a `pricing_snapshots` row keyed
+  on `(tenant_id, model, snapshot_date)` (migration 0011) and stores
+  the FK on the call row. `pricing_version="unavailable"` skips the
+  snapshot — the `cost_status` column carries the authoritative signal.
+
+### Backend wiring (deferred to US-CR.0)
+
+`PlmTenantMiddleware` is published in `plm_shared.middleware` but is
+NOT yet installed in `02_App/backend/main.py`. US-CR.0 owns the
+ordering — it adds `IdentityMiddleware` first, then plumbs
+`PlmTenantMiddleware` behind it, then wires CORS so that
+`CORSMiddleware` wraps both (failure responses still carry CORS
+headers). Conv D leaves the middleware available-but-unwired so
+US-CR.0 lands the full ordering in one place.
+
+## Migration chain
+
+| Rev | Subject                                                       |
+|-----|---------------------------------------------------------------|
+| 0001 | foundational tables `tenants`, `runs` + `quality_level` ENUM + `actor_kind` ENUM |
+| 0002 | `telemetry_events` + composite index + UNIQUE `idempotency_key` |
+| 0003 | `llm_calls` + `cost_*` columns + UNIQUE `idempotency_key`     |
+| 0004 | `connector_calls` + connector-specific fields                |
+| 0005 | `artifacts` + storage_uri + retention_until                   |
+| 0006 | quality_level + cost_status transition triggers               |
+| 0007 | `mcrc_v1_view` (§1-§8 projection)                             |
+| 0008 | Postgres roles `plm_kernel_writer` + `plm_migrator`           |
+| 0009 | Row-Level Security on the 5 tenant-scoped tables + `plm_migrator BYPASSRLS` |
+| 0010 | logical UNIQUE constraints (backs the 200/409 IdempotencyKey contract) |
+| 0011 | `pricing_snapshots` dedup table + nullable FKs                |
+| 0012 | `plm_migrator` table privileges (SELECT/INSERT/UPDATE/DELETE on the 7 tenant-scoped tables — closes the privilege gap surfaced by the live-Postgres validation event; BYPASSRLS alone does not grant table access) |
+
+Run the chain with `alembic upgrade head` from `02_App/plm-shared/`
+(needs `PG_DSN` exported).
+
+## Install (developer)
+
+From the `02_App/backend/` virtualenv:
+
+```bash
+cd 02_App/backend
+pip install -e ../plm-shared           # base install
+pip install -e "../plm-shared[db]"     # + SQLAlchemy / psycopg / alembic
+pip install -e "../plm-shared[s3]"     # + boto3 (ObjectStoreBackend)
+pip install -e "../plm-shared[db,s3]"  # combined
+```
+
+The `02_App/backend/requirements.txt` already lists `-e ../plm-shared`
+so a clean `pip install -r requirements.txt` from `02_App/backend/`
+picks it up. **`pip install` MUST run from `02_App/backend/`** because
+pip resolves the editable path relative to the invocation CWD.
+
+## Tests
+
+```bash
+cd 02_App/plm-shared
+python -m pytest tests/ -v
+```
+
+Audit + migration suites under `tests/audit/` and `tests/migrations/`
+are gated on `PG_DSN`. Bring up the dev compose first:
+
+```bash
+docker compose -f dev/postgres.yml up -d
+export PG_DSN=postgresql+psycopg://tracepulse:tracepulse@localhost:5432/tracepulse_dev
+cd 02_App/plm-shared
+python -m pytest tests/audit/ tests/migrations/ -v
+```
+
+S3-protocol live tests under `tests/test_object_store_backend.py` gate
+on `S3_ENDPOINT_URL` (skip-when-unset). Bring up minio (or any
+S3-protocol endpoint) and export `S3_ENDPOINT_URL`, `S3_ACCESS_KEY`,
+`S3_SECRET_KEY`, `S3_BUCKET`.
+
+## Architecture conformance gate (US-W1.0 / AC-4)
+
+`pyproject.toml` declares one `[tool.importlinter]` Forbidden contract
+banning `sqlalchemy` from every plm-shared module except `db` and
+`sqlalchemy_kernel_emitter`. Run it from the package root:
+
+```bash
+cd 02_App/plm-shared
+lint-imports --config pyproject.toml
+```
+
+The companion **BL5** rule in
+`02_App/backend/scripts/architecture_guardrails.py` (warn-only at
+launch) regex-scans for `INSERT INTO {telemetry_events|llm_calls|connector_calls|pricing_snapshots}`
+outside `kernel_api` / `sqlalchemy_kernel_emitter` / migrations.

plm_shared-0.1.0/plm_shared/__init__.py

@@ -0,0 +1,11 @@
+"""plm-shared — frozen contracts shared across TracePulse PLM product lines.
+
+US-W1.0 (PR-1): the modules in this package publish the Kernel emission
+API surface, idempotency key, capability registry, knowledge envelope,
+trace context, pricing helpers, and artifact-store protocol consumed by
+the rest of Wave 1. Models in `kernel_api`, `idempotency`,
+`knowledge_envelope`, and `capabilities` are frozen — never modified by
+downstream stories — so the rest of the wave can be implemented in
+parallel without contract drift.
+"""
+__version__ = "0.1.0"

plm_shared-0.1.0/plm_shared/_w1_13_backfill.py

@@ -0,0 +1,159 @@
+"""US-W1.13 / Conv I — idempotent backfill of Wave 0 metadata to typed columns.
+
+Private module implementing the actual UPDATE statements + summary
+shape used by the W1.13 backfill. Surfaced at the CLI level by
+``02_App/plm-shared/scripts/backfill_w1_13_typed_columns.py``; the
+audit test (`tests/audit/test_w1_13_backfill.py`) imports
+``run_backfill`` from this module directly.
+
+Walks every `telemetry_events` row whose typed column is NULL,
+reads the equivalent value from `payload` JSONB, writes it into
+the new column. Re-running on a fully-backfilled DB yields zero
+further updates (W1.13 §AC-7 — idempotency).
+
+Runs as `plm_migrator` per migration 0008 + Decision #16:
+`plm_kernel_writer` is REVOKED UPDATE on `telemetry_events` per
+the append-only rule, and a backfill IS an UPDATE. The script
+issues `SET LOCAL ROLE plm_migrator` inside each transaction so
+even a superuser-mode invocation stays faithful to the production
+privilege contract.
+
+llm_calls.pricing_source backfill is NOT covered here — the column
+lives in PG, but pre-0016 telemetry-side rows that carried
+`pricing_source` rode in `telemetry_events.payload`, not
+`llm_calls.payload` (`llm_calls` has no payload JSONB column).
+The legacy backend's SQLite `agent_invocations.metadata.pricing_source`
+column is handled by `02_App/backend/database.py`'s startup
+ALTER-TABLE pattern, not by this PG backfill.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine
+
+
+@dataclass(frozen=True)
+class BackfillSummary:
+    """Per-column rowcounts from a single backfill invocation.
+
+    A second invocation against a fully-backfilled DB returns
+    all-zeros — that's the AC-7 idempotency contract.
+    """
+
+    updated_invocation_kind: int
+    updated_is_eval: int
+    updated_parent_invocation_id: int
+    updated_root_invocation_id: int
+    updated_system_context: int
+
+    @property
+    def total(self) -> int:
+        return (
+            self.updated_invocation_kind
+            + self.updated_is_eval
+            + self.updated_parent_invocation_id
+            + self.updated_root_invocation_id
+            + self.updated_system_context
+        )
+
+
+_INVOCATION_KIND_VALUES = ("user", "system", "hidden_retry", "background")
+
+
+_BACKFILL_INVOCATION_KIND = text("""
+    UPDATE telemetry_events
+    SET invocation_kind = (payload->>'invocation_kind')::invocation_kind_v1
+    WHERE invocation_kind IS NULL
+      AND payload ? 'invocation_kind'
+      AND payload->>'invocation_kind' = ANY(:valid_kinds)
+""")
+
+# `is_eval` is non-nullable with default `false`. The migration
+# already populated every legacy row to `false` via the server
+# default; the only useful UPDATE is for rows whose payload
+# explicitly carries `is_eval=true`. Idempotent: re-run on a
+# flipped row no-ops because the WHERE filters it out.
+_BACKFILL_IS_EVAL = text("""
+    UPDATE telemetry_events
+    SET is_eval = true
+    WHERE is_eval = false
+      AND payload ? 'is_eval'
+      AND lower(payload->>'is_eval') IN ('true', '1')
+""")
+
+_BACKFILL_PARENT_INVOCATION_ID = text("""
+    UPDATE telemetry_events
+    SET parent_invocation_id = (payload->>'parent_invocation_id')::uuid
+    WHERE parent_invocation_id IS NULL
+      AND payload ? 'parent_invocation_id'
+      AND payload->>'parent_invocation_id' ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+""")
+
+_BACKFILL_ROOT_INVOCATION_ID = text("""
+    UPDATE telemetry_events
+    SET root_invocation_id = (payload->>'root_invocation_id')::uuid
+    WHERE root_invocation_id IS NULL
+      AND payload ? 'root_invocation_id'
+      AND payload->>'root_invocation_id' ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+""")
+
+_BACKFILL_SYSTEM_CONTEXT = text("""
+    UPDATE telemetry_events
+    SET system_context = payload->>'system_context'
+    WHERE system_context IS NULL
+      AND payload ? 'system_context'
+""")
+
+
+def run_backfill(engine: Engine) -> BackfillSummary:
+    """Apply every per-column backfill UPDATE; return a counts summary.
+
+    Each UPDATE runs in its own transaction so a partial failure
+    on one column doesn't roll back successful work on previous
+    columns. `SET LOCAL ROLE plm_migrator` is issued inside each
+    transaction so the privilege check happens even when the
+    connecting user is the dev superuser. Idempotent — every
+    WHERE clause filters rows that already have the typed column
+    populated.
+    """
+    counts = {}
+    for label, statement in (
+        ("invocation_kind", _BACKFILL_INVOCATION_KIND),
+        ("is_eval", _BACKFILL_IS_EVAL),
+        ("parent_invocation_id", _BACKFILL_PARENT_INVOCATION_ID),
+        ("root_invocation_id", _BACKFILL_ROOT_INVOCATION_ID),
+        ("system_context", _BACKFILL_SYSTEM_CONTEXT),
+    ):
+        with engine.begin() as conn:
+            conn.execute(text("SET LOCAL ROLE plm_migrator"))
+            params = (
+                {"valid_kinds": list(_INVOCATION_KIND_VALUES)}
+                if label == "invocation_kind"
+                else {}
+            )
+            result = conn.execute(statement, params)
+            counts[label] = result.rowcount or 0
+
+    return BackfillSummary(
+        updated_invocation_kind=counts["invocation_kind"],
+        updated_is_eval=counts["is_eval"],
+        updated_parent_invocation_id=counts["parent_invocation_id"],
+        updated_root_invocation_id=counts["root_invocation_id"],
+        updated_system_context=counts["system_context"],
+    )
+
+
+def build_engine_from_env(dsn: Optional[str] = None) -> Engine:
+    """Resolve `PG_DSN` from env (or the explicit override) and bind."""
+    url = (dsn or os.environ.get("PG_DSN", "")).strip()
+    if not url:
+        raise RuntimeError(
+            "PG_DSN is not set. Export it before running the W1.13 "
+            "backfill (e.g. "
+            "`postgresql+psycopg://tracepulse:tracepulse@localhost:5432/tracepulse_dev`)."
+        )
+    return create_engine(url, future=True)

plm_shared-0.1.0/plm_shared/agents/__init__.py

@@ -0,0 +1,14 @@
+"""Lifted ``agents/`` modules (Wave 6.7 Conv A).
+
+Per Decision #177 — these are not Protocol indirections; they are the
+**canonical** homes of ``BaseAgent`` (abstract base class for the multi-
+agent PDF→BPMN chain), the domain classifier / RACI extractor, and the
+domain-specific prompt prefixes. Lifted from
+``02_App/backend/agents/`` via ``git mv`` so sibling packages
+(:mod:`plm_skill_packages`) can import them without depending on
+``02_App/backend/``.
+
+The legacy paths under ``02_App/backend/agents/`` remain as thin
+re-export shims for the duration of the DC-1 90-day soak, matching the
+W1.4 RunTaskTracker + Wave 6.5 Conv A/B precedent.
+"""