pam-python 0.2.9__tar.gz → 0.2.11__tar.gz

{pam_python-0.2.9/pam_python.egg-info → pam_python-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.9
+Version: 0.2.11
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python

{pam_python-0.2.9 → pam_python-0.2.11}/pam/__init__.py

@@ -1,3 +1,3 @@
 """PAM Data Plugin framework."""
 
-__version__ = "0.2.9"
+__version__ = "0.2.11"

pam_python-0.2.11/pam/datetime_utils.py

@@ -0,0 +1,20 @@
+"""PAM's canonical suffix-free UTC+0 datetime contract."""
+
+from datetime import datetime, timezone
+
+
+PAM_DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def parse_pam_datetime(value: str) -> datetime:
+    """Parse an exact PAM datetime string and attach UTC without shifting it."""
+    return datetime.strptime(value, PAM_DATETIME_FORMAT).replace(tzinfo=timezone.utc)
+
+
+def format_pam_datetime(value: datetime) -> str:
+    """Format a datetime as PAM UTC+0 without a timezone suffix."""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    else:
+        value = value.astimezone(timezone.utc)
+    return value.strftime(PAM_DATETIME_FORMAT)

{pam_python-0.2.9 → pam_python-0.2.11}/pam/interface_task_manager.py

@@ -79,5 +79,6 @@ class ITaskManager(ABC):
         service: Service,
         report_key: str,
         pointer: dict,
+        tracker_name: str,
     ):
         pass

{pam_python-0.2.9 → pam_python-0.2.11}/pam/logger.py

@@ -4,9 +4,11 @@ from datetime import datetime, timezone
 from threading import Lock
 from typing import Any
 
+from pam.datetime_utils import format_pam_datetime
 from pam.utils import log as stdout_log
 from pam.service import Service
 
+
 class Logger:
     def __init__(self, service: Service, buffer_size: int = 20, source: str = "worker"):
         self.service = service
@@ -92,4 +94,4 @@ class Logger:
 
     @staticmethod
     def _utc_now() -> str:
-        return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+        return format_pam_datetime(datetime.now(timezone.utc))

{pam_python-0.2.9 → pam_python-0.2.11}/pam/models/data_input_v2.py

@@ -2,12 +2,12 @@ from __future__ import annotations
 
 import csv
 from dataclasses import dataclass
-from datetime import datetime, timezone
 from hashlib import sha256
 import json
 from pathlib import Path
 from typing import Any, Iterator
 
+from pam.datetime_utils import parse_pam_datetime
 from pam.temp_file_utils import TempfileUtils
 
 
@@ -15,7 +15,6 @@ V2_PROTOCOL_VERSION = "data-plugin-input/v2"
 V2_MANIFEST_FILE_NAME = "manifest.json"
 V2_MAX_DATASETS = 5
 V2_POPULATION_MODES = {"contacts", "event_any", "event_all"}
-PAM_TIMESTAMP_FORMAT = "%Y-%m-%d %H:%M:%S"
 
 
 @dataclass(frozen=True)
@@ -365,11 +364,6 @@ def _required_optional_string(source: dict[str, Any], key: str) -> str:
     return value
 
 
-def _parse_pam_timestamp(value: str) -> datetime:
-    """Parse PAM's suffix-free timestamp as UTC+0 without shifting it."""
-    return datetime.strptime(value, PAM_TIMESTAMP_FORMAT).replace(tzinfo=timezone.utc)
-
-
 def _parse_time_window(raw_time_window: Any) -> DataInputV2TimeWindow | None:
     if raw_time_window is None:
         return None
@@ -380,8 +374,8 @@ def _parse_time_window(raw_time_window: Any) -> DataInputV2TimeWindow | None:
     start_inclusive = _required_bool(raw_time_window, "start_inclusive")
     end_inclusive = _required_bool(raw_time_window, "end_inclusive")
     try:
-        start_time = _parse_pam_timestamp(start)
-        end_time = _parse_pam_timestamp(end)
+        start_time = parse_pam_datetime(start)
+        end_time = parse_pam_datetime(end)
     except ValueError as error:
         raise ValueError("V2 manifest time_window timestamps are invalid") from error
     if start_time >= end_time:

{pam_python-0.2.9 → pam_python-0.2.11}/pam/reports/manager.py

@@ -31,9 +31,15 @@ class ReportStoreManager:
         self._sleep = sleep_fn
         self._stores = {}
 
-    def create(self, file_name: str, shared: bool = False) -> ReportStore:
+    def create(
+        self,
+        file_name: str,
+        shared: bool = False,
+        tracker_name: str | None = None,
+    ) -> ReportStore:
         """Start a fresh local file without performing a download."""
         self._validate_file_name(file_name)
+        tracker_name = self._resolve_tracker_name(tracker_name)
         session_key = (file_name, shared)
         self._assert_not_open(session_key)
         path = self._new_local_path(file_name)
@@ -41,18 +47,29 @@ class ReportStoreManager:
             path,
             file_name,
             shared,
+            tracker_name=tracker_name,
             transport=self._transport,
             cleanup_on_close=True,
         )
         self._stores[session_key] = store
         return store
 
-    def open(self, file_name: str, shared: bool = False) -> ReportStore:
+    def open(
+        self,
+        file_name: str,
+        shared: bool = False,
+        tracker_name: str | None = None,
+    ) -> ReportStore:
         """Resume remote state, or create only after an authoritative 404."""
         self._validate_file_name(file_name)
+        tracker_name = self._resolve_tracker_name(tracker_name)
         session_key = (file_name, shared)
         existing = self._stores.get(session_key)
         if existing is not None:
+            if existing.tracker_name != tracker_name:
+                raise ReportStoreLocalIOError(
+                    "This report store is already open with a different tracker_name"
+                )
             return existing
 
         path = self._new_local_path(file_name)
@@ -64,6 +81,7 @@ class ReportStoreManager:
                     downloaded_path,
                     file_name,
                     shared,
+                    tracker_name=tracker_name,
                     transport=self._transport,
                     cleanup_on_close=True,
                 )
@@ -75,6 +93,7 @@ class ReportStoreManager:
                     path,
                     file_name,
                     shared,
+                    tracker_name=tracker_name,
                     transport=self._transport,
                     cleanup_on_close=True,
                 )
@@ -138,6 +157,15 @@ class ReportStoreManager:
                 "This report store is already open for the current service run"
             )
 
+    def _resolve_tracker_name(self, tracker_name: str | None) -> str:
+        if tracker_name is None:
+            tracker_name = self._service.request.service_name
+        if not isinstance(tracker_name, str) or not tracker_name.strip():
+            raise ReportStoreLocalIOError(
+                "tracker_name must be a non-empty string"
+            )
+        return tracker_name.strip()
+
     @staticmethod
     def _validate_file_name(file_name: str) -> None:
         if not isinstance(file_name, str) or not file_name.strip():

{pam_python-0.2.9 → pam_python-0.2.11}/pam/reports/record.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass, field
 from datetime import date, datetime, timezone
 from typing import Any, Dict, Optional, Tuple
 
+from pam.datetime_utils import parse_pam_datetime
 from pam.reports.errors import ReportStoreValidationError
 
 
@@ -75,14 +76,15 @@ def normalize_timestamp(value: Any) -> Optional[int]:
         parsed = datetime.combine(value, datetime.min.time(), tzinfo=timezone.utc)
     elif isinstance(value, str) and value:
         try:
-            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+            parsed = parse_pam_datetime(value)
         except ValueError as exc:
             raise ReportStoreValidationError(
-                f"Timestamp value is not ISO-8601: {value}"
+                f"Timestamp value must use PAM UTC format YYYY-MM-DD HH:mm:ss: {value}"
             ) from exc
     else:
         raise ReportStoreValidationError(
-            "Timestamp values must be epoch milliseconds, date, datetime, or ISO-8601 string"
+            "Timestamp values must be epoch milliseconds, date, datetime, "
+            "or a PAM UTC string using YYYY-MM-DD HH:mm:ss"
         )
     if parsed.tzinfo is None:
         parsed = parsed.replace(tzinfo=timezone.utc)

{pam_python-0.2.9 → pam_python-0.2.11}/pam/reports/store.py

@@ -8,6 +8,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Iterable, List, Optional, Set
 
+from pam.datetime_utils import format_pam_datetime
 from pam.reports.errors import (
     DuplicateReportRecordError,
     ReportDefinitionConflictError,
@@ -48,7 +49,7 @@ from pam.reports.treemap import TreemapReport
 
 
 def _now() -> str:
-    return datetime.now(timezone.utc).isoformat()
+    return format_pam_datetime(datetime.now(timezone.utc))
 
 
 class ReportStore:
@@ -59,12 +60,14 @@ class ReportStore:
         path: Path,
         file_name: str,
         shared: bool,
+        tracker_name: str = "",
         transport=None,
         cleanup_on_close: bool = False,
     ):
         self.path = Path(path)
         self.file_name = file_name
         self.shared = shared
+        self.tracker_name = tracker_name
         self._transport = transport
         self._cleanup_on_close = cleanup_on_close
         self._lock = threading.RLock()
@@ -86,6 +89,7 @@ class ReportStore:
         path: Path,
         file_name: str,
         shared: bool,
+        tracker_name: str = "",
         transport=None,
         cleanup_on_close: bool = False,
     ):
@@ -96,7 +100,14 @@ class ReportStore:
         except OSError as exc:
             raise ReportStoreLocalIOError(str(exc)) from exc
 
-        store = cls(path, file_name, shared, transport, cleanup_on_close)
+        store = cls(
+            path,
+            file_name,
+            shared,
+            tracker_name=tracker_name,
+            transport=transport,
+            cleanup_on_close=cleanup_on_close,
+        )
         try:
             with store._connection:
                 store._connection.executescript(CREATE_SCHEMA_SQL)
@@ -115,10 +126,18 @@ class ReportStore:
         path: Path,
         file_name: str,
         shared: bool,
+        tracker_name: str = "",
         transport=None,
         cleanup_on_close: bool = False,
     ):
-        store = cls(path, file_name, shared, transport, cleanup_on_close)
+        store = cls(
+            path,
+            file_name,
+            shared,
+            tracker_name=tracker_name,
+            transport=transport,
+            cleanup_on_close=cleanup_on_close,
+        )
         try:
             store._migrate_compatible_schema()
             store.validate()

{pam_python-0.2.9 → pam_python-0.2.11}/pam/reports/transport.py

@@ -51,6 +51,7 @@ class ReportStoreTransport:
                 self._service,
                 report_key,
                 pointer,
+                tracker_name=store.tracker_name,
             ):
                 raise ReportStoreUploadError(
                     f"Failed to publish pointer for report '{report_key}'"

{pam_python-0.2.9 → pam_python-0.2.11}/pam/task_manager.py

@@ -476,6 +476,7 @@ class TaskManager(ITaskManager):
         service: Service,
         report_key: str,
         pointer: dict,
+        tracker_name: str,
     ) -> bool:
         """Synchronously publish one V2 pointer through the existing response API."""
         adapter_id = service.get_adapter_id()
@@ -496,7 +497,7 @@ class TaskManager(ITaskManager):
                 writer.writeheader()
                 writer.writerow({
                     "customer": adapter_id,
-                    "_tracker_name": "",
+                    "_tracker_name": tracker_name,
                     column_name: json.dumps(pointer, ensure_ascii=False, sort_keys=True),
                 })
 

{pam_python-0.2.9 → pam_python-0.2.11}/pam/templates/init/AGENT.md

@@ -112,7 +112,10 @@ Notes
 
 - All values are strings. Cast with defaults to avoid errors.
 - `dry_run` is the only built-in parameter. If missing, it runs for real. If `dry_run="true"`, the service runs fully but does not upload results to CDP.
-- You do not need to check `dry_run` manually. Always call `_upload_result`; the system handles it.
+- You do not need to check `dry_run` manually. Submit tabular results through
+  `ResultBatchUploader` and managed reports through `ReportStore.publish()`; the
+  framework suppresses their remote transport during a dry run. Never call the
+  private `_upload_result` path directly from plugin code.
 
 **Important:** `on_start` must return quickly because CDP calls via HTTP. If it hangs, the client may time out and the job will be terminated. If work is long-running, move it to a thread and return from `on_start` first. This applies to all lifecycle functions.
 
@@ -146,8 +149,9 @@ Column meaning
 
 Date format is always:
 `"2025-09-11 13:07:38"`
-Timezone may vary by customer data (usually Bangkok time).
-You may sometimes be asked for the exact time zone if it is logically important for the program.
+The timezone of customer-owned source fields is an external data contract and may
+vary by customer. Confirm it when business logic depends on calendar boundaries,
+then convert explicitly. This does not change PAM's internal UTC+0 contract above.
 
 ---
 
@@ -238,6 +242,20 @@ the optional half-open `data.time_window` expose the captured run semantics.
 The framework rejects callback-token/run-ID mismatches and contradictory event
 population or time-window metadata before plugin code runs.
 
+Data Input V2 and Report Store V2 are independent contracts. A service may use
+Data Input V2 without producing managed reports, and report calculations are not
+required to use Data Input V2.
+
+For Data Input V2 pagination:
+
+- Use `data.run_complete`, not legacy `req.is_end`, as the completion signal.
+- Use only the opaque `data.next` cursor when requesting the next page.
+- Materialize every lazy computation that still reads the page before calling
+  `data.cleanup()`.
+- Treat a failed cleanup as an error before requesting the next page.
+- If the service produces managed reports, do not publish a partially calculated
+  store on an intermediate page. Publish after all intended pages and writes finish.
+
 ---
 
 ## Upload Results to CDP
@@ -400,7 +418,7 @@ Use it for cleanup.
 
 ---
 
-# 4. Persist State Between Runs (sqlite/duckdb)
+# 5. Persist State Between Runs (sqlite/duckdb)
 
 Services can be killed and restarted at any time. If you need state across runs, use sqlite or duckdb via the provided API.
 
@@ -434,17 +452,97 @@ Notes
 
 Note: `file_name` acts like a server key, while `sqlite_file` is the local file path.
 
-## Managed reports are a separate contract
+# 6. Managed Report Store V2 Agent Contract
 
 The low-level SQLite API above is for custom plugin state. Do not use it to invent
 SQLite tables or JSON payloads for reports rendered by PAM CMS.
 
-For managed reports, read `REPORTS.md` and use only one of its typed report builders.
-Report types outside that closed contract require a newer framework and CMS release.
+Before implementing a managed report, read `REPORTS.md` completely and use only its
+public typed report builders. Report types outside that closed contract require a
+newer framework and CMS release. Do not use `_request_sqlite`, `_upload_sqlite`,
+`_upload_report`, private declaration methods, raw SQLite schema changes, handwritten
+renderer/schema identifiers, or handcrafted report-pointer CSV files for Report
+Store V2.
+
+## Store, tracker group, and report identity
+
+These identifiers have different responsibilities:
+
+- `file_name` identifies one managed SQLite store. One store may contain many report
+  definitions and their records.
+- `tracker_name` is the stable, user-facing Analytics Tracker group shown in PAM CMS.
+  Related reports in the same store should normally use one shared tracker name.
+- `report key` uniquely identifies one report inside the store and must remain stable.
+  Every changed report key is published as its own Analytics Tracker attribute, so
+  PAM CMS can list every report separately even though they share one tracker group
+  and one SQLite file.
+
+Always pass a non-empty, customer-facing `tracker_name` to both `self.reports.open`
+and `self.reports.create` when the service owns managed reports:
+
+```python
+REPORT_FILE = "reports.sqlite"
+REPORT_TRACKER_NAME = "Customer Overall Reports"
+
+fresh = self.request.get_runtime_bool("fresh", default=False)
+if fresh:
+    self.report_store = self.reports.create(
+        REPORT_FILE,
+        tracker_name=REPORT_TRACKER_NAME,
+    )
+else:
+    self.report_store = self.reports.open(
+        REPORT_FILE,
+        tracker_name=REPORT_TRACKER_NAME,
+    )
+```
+
+If `tracker_name` is omitted, the framework falls back to `request.service_name`,
+but an explicit label is preferred for customer projects. Never generate one tracker
+name per report merely to separate reports. Never write `_tracker_name` yourself;
+the framework propagates the store's tracker name to every V2 pointer. Reopening the
+same file in one service run with a different tracker name is an error.
+
+The framework also publishes the service adapter ID as the Analytics Tracker owner.
+PAM and PAM CMS use that metadata for Hard Refresh routing. Plugin code must not ask
+a user to select an owner, encode the owner in `tracker_name` or `report key`, or add
+an ad-hoc owner field to the pointer.
+
+## Required lifecycle
+
+1. Open the store once during service initialization. Use `create` only for an
+   explicit human-requested fresh reset. Normal first use calls `open`; the framework
+   creates a store only after an authoritative not-found response.
+2. Do not catch authorization, transient download, or unknown remote-state errors and
+   replace the store. Let the framework retry or raise the typed error.
+3. Declare every report once after opening the store. Multiple reports should share
+   the same `ReportStore` when they belong to the same customer report group.
+4. Bind input datasets by their configured positions and complete all required page
+   calculations before publishing. Report calculations may accumulate in memory or
+   write incrementally to the local store, depending on the domain requirement.
+5. For refreshed `DAY` or `MONTH` facts, delete the source-derived partition before
+   writing its complete replacement. Never derive a business partition from plugin
+   run time unless that is explicitly the source contract.
+6. Call `self.report_store.publish()` once after the complete calculation succeeds,
+   then call `_exit()`. Do not publish after a calculation, validation, or cleanup
+   failure, and normally do not publish once per input page.
+
+One successful `publish()` uploads the SQLite file once, then publishes one pointer
+for every report key changed during the run. All of those pointers carry the same
+stable tracker name. The framework handles `dry_run` and local-file cleanup; plugin
+code must not reproduce the transport lifecycle.
+
+An existing report key cannot silently change renderer, schema, field declaration,
+granularity, or presentation contract. Use a deliberate new key or an explicitly
+approved fresh reset when the compatibility contract changes.
+
+Before using a report API, verify that the project's pinned `pam-python` release
+contains it. Customer plugins consume the framework package from their dependency
+manager; do not copy framework internals into the plugin as a workaround.
 
 ---
 
-# 5. Batch upload policy (DataFrame batching)
+# 7. Batch upload policy (DataFrame batching)
 
 ## Goal
 
@@ -518,7 +616,7 @@ After retries are exhausted, the uploader logs the failed batch, records
 
 ---
 
-# 6. Memory / RAM safety policy (Data Plugin)
+# 8. Memory / RAM safety policy (Data Plugin)
 
 ## Goal
 

{pam_python-0.2.9 → pam_python-0.2.11}/pam/templates/init/REPORTS.md

@@ -127,17 +127,29 @@ store; an authoritative not-found response creates the first store automatically
 fresh = self.request.get_runtime_bool("fresh", default=False)
 
 if fresh:
-    store = self.reports.create("reports.sqlite")
+    store = self.reports.create(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
 else:
-    store = self.reports.open("reports.sqlite")
+    store = self.reports.open(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
 ```
 
+`tracker_name` is the Analytics Tracker group label shown in PAM CMS. Keep it stable
+for all reports in the store. If omitted, the framework uses the service name.
+
 Declare reports once after opening the store. Append data across as many input
 pages as required, then publish once after all intended work is complete.
 
 ```python
 def on_start(self):
-    self.report_store = self.reports.open("reports.sqlite")
+    self.report_store = self.reports.open(
+        "reports.sqlite",
+        tracker_name="Customer Report Group",
+    )
     self._declare_reports()
     self._request_data(file_format=RequestFileFormat.PARQUET)
 
@@ -230,7 +242,8 @@ Initial value types:
 - `number`
 - `boolean`
 - `date` — calendar date, serialized as `YYYY-MM-DD`
-- `datetime` — timestamp normalized to epoch milliseconds internally
+- `datetime` — timestamp normalized to epoch milliseconds internally; string
+  inputs must use PAM UTC format `YYYY-MM-DD HH:mm:ss`
 
 Objects and arrays are not initial field types. A report that requires a complex
 cell or point must first introduce an explicit framework and CMS contract.
@@ -1127,8 +1140,8 @@ ranges.append_ranges([
         {
             "task": "Phase A",
             "group": "Project 1",
-            "start": "2026-08-01T09:00:00+07:00",
-            "end": "2026-08-05T18:00:00+07:00",
+            "start": "2026-08-01 09:00:00",
+            "end": "2026-08-05 18:00:00",
         },
 ], partition_key="2026-08")
 ```

{pam_python-0.2.9 → pam_python-0.2.11}/pam/tester_task.py

@@ -18,7 +18,7 @@ UploadSqliteCallbackType = Callable[[str, bool, str], Optional[str]]
 UploadResultCallbackType = Callable[[str], None]
 UploadReportCallbackType = Callable[[str], None]
 RequestReportStoreCallbackType = Callable[[str, bool, str], SQLiteDownloadResult]
-PublishReportPointerCallbackType = Callable[[str, dict], bool]
+PublishReportPointerCallbackType = Callable[..., bool]
 
 class TesterTask(ITaskManager):
     """
@@ -289,8 +289,29 @@ class TesterTask(ITaskManager):
         service: Service,
         report_key: str,
         pointer: dict,
+        tracker_name: str,
     ) -> bool:
         if self.publish_report_pointer_callback is not None:
+            parameters = list(
+                inspect.signature(self.publish_report_pointer_callback).parameters.values()
+            )
+            accepts_varargs = any(
+                parameter.kind is inspect.Parameter.VAR_POSITIONAL
+                for parameter in parameters
+            )
+            positional_count = sum(
+                parameter.kind in (
+                    inspect.Parameter.POSITIONAL_ONLY,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                )
+                for parameter in parameters
+            )
+            if accepts_varargs or positional_count >= 3:
+                return self.publish_report_pointer_callback(
+                    report_key,
+                    pointer,
+                    tracker_name,
+                )
             return self.publish_report_pointer_callback(report_key, pointer)
         print("Publish Report Store V2 pointer callback is not set.")
         return False

{pam_python-0.2.9 → pam_python-0.2.11/pam_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pam-python
-Version: 0.2.9
+Version: 0.2.11
 Summary: Pam Python Library
 Author-email: Narongrit Kanhanoi <narongrit@pams.ai>
 Project-URL: Homepage, https://github.com/heart/pam-python

{pam_python-0.2.9 → pam_python-0.2.11}/pam_python.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 pam/__init__.py
 pam/api.py
 pam/cli.py
+pam/datetime_utils.py
 pam/interface_task_manager.py
 pam/logger.py
 pam/request_file_format.py
@@ -84,6 +85,7 @@ tests/test_cli_templates.py
 tests/test_data_error_v2.py
 tests/test_data_input_v2.py
 tests/test_data_timeout_v2.py
+tests/test_datetime_utils.py
 tests/test_range_transform.py
 tests/test_report_store.py
 tests/test_request_data_v2.py

{pam_python-0.2.9 → pam_python-0.2.11}/tests/test_cli_templates.py

@@ -47,6 +47,23 @@ class CLITemplateTest(unittest.TestCase):
             self.assertIn("Customer-based Pagination Contract", agent_guide)
             self.assertIn("same customer-ID cohort", agent_guide)
             self.assertIn("customer-cohort cursor", agent_guide)
+            normalized_agent_guide = " ".join(agent_guide.split())
+            self.assertIn(
+                "Data Input V2 and Report Store V2 are independent contracts",
+                normalized_agent_guide,
+            )
+            self.assertIn(
+                "One store may contain many report",
+                normalized_agent_guide,
+            )
+            self.assertIn(
+                "Never generate one tracker name per report",
+                normalized_agent_guide,
+            )
+            self.assertIn(
+                "publishes one pointer for every report key changed",
+                normalized_agent_guide,
+            )
             self.assertTrue((root / "run_unit_test.sh").is_file())
             self.assertTrue(os.access(root / "run_unit_test.sh", os.X_OK))
             self.assertTrue((root / "run_unit_test.ps1").is_file())

pam_python-0.2.11/tests/test_datetime_utils.py

@@ -0,0 +1,43 @@
+import unittest
+from datetime import datetime, timedelta, timezone
+
+from pam.datetime_utils import format_pam_datetime, parse_pam_datetime
+from pam.logger import Logger
+
+
+class PAMDateTimeUtilsTest(unittest.TestCase):
+    def test_round_trip_uses_suffix_free_utc_format(self):
+        parsed = parse_pam_datetime("2026-03-31 02:37:44")
+
+        self.assertEqual(timezone.utc, parsed.tzinfo)
+        self.assertEqual("2026-03-31 02:37:44", format_pam_datetime(parsed))
+
+    def test_format_converts_aware_datetime_to_utc(self):
+        value = datetime(
+            2026,
+            3,
+            31,
+            9,
+            37,
+            44,
+            tzinfo=timezone(timedelta(hours=7)),
+        )
+
+        self.assertEqual("2026-03-31 02:37:44", format_pam_datetime(value))
+
+    def test_parse_rejects_rfc3339(self):
+        with self.assertRaises(ValueError):
+            parse_pam_datetime("2026-03-31T02:37:44Z")
+
+    def test_structured_logger_uses_pam_utc_format(self):
+        logged_at = Logger._utc_now()
+
+        self.assertEqual(19, len(logged_at))
+        self.assertEqual(
+            logged_at,
+            format_pam_datetime(parse_pam_datetime(logged_at)),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

{pam_python-0.2.9 → pam_python-0.2.11}/tests/test_report_store.py

@@ -1,6 +1,7 @@
 import csv
 import importlib
 import json
+import re
 import shutil
 import sqlite3
 import tempfile
@@ -15,6 +16,7 @@ from pam.reports import (
     ReportDefinitionConflictError,
     ReportStore,
     ReportStoreDownloadError,
+    ReportStoreLocalIOError,
     ReportStoreManager,
     ReportStoreValidationError,
 )
@@ -44,7 +46,9 @@ class FakeTransport:
         return result
 
     def publish(self, store, changed_report_keys):
-        self.publish_calls.append((store.file_name, tuple(changed_report_keys)))
+        self.publish_calls.append(
+            (store.file_name, store.tracker_name, tuple(changed_report_keys))
+        )
 
 
 def make_service():
@@ -69,8 +73,14 @@ class FakeTaskManager:
         self.uploads.append((file_name, shared, sqlite_file))
         return file_name
 
-    def service_publish_report_pointer_v2(self, service, report_key, pointer):
-        self.pointers.append((report_key, pointer))
+    def service_publish_report_pointer_v2(
+        self,
+        service,
+        report_key,
+        pointer,
+        tracker_name,
+    ):
+        self.pointers.append((report_key, pointer, tracker_name))
         return True
 
 
@@ -136,6 +146,23 @@ class ReportStoreTest(unittest.TestCase):
                 definition_json="{}",
             )
 
+    def test_metadata_timestamps_use_pam_utc_format(self):
+        self.report()
+        self.store._append_records(
+            "test-report-a",
+            [ReportRecord(dimensions={"customer": "contact-1"}, measures={})],
+        )
+
+        timestamps = self.store._connection.execute(
+            "SELECT created_at, updated_at FROM report_definitions "
+            "UNION ALL SELECT created_at, updated_at FROM report_records"
+        ).fetchall()
+        pattern = re.compile(r"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$")
+        self.assertTrue(timestamps)
+        for created_at, updated_at in timestamps:
+            self.assertRegex(created_at, pattern)
+            self.assertRegex(updated_at, pattern)
+
         with self.assertRaises(ReportStoreValidationError):
             self.store._declare_report(
                 key="invalid-range",
@@ -259,7 +286,7 @@ class ReportStoreTest(unittest.TestCase):
         self.store.publish()
 
         self.assertEqual([
-            ("reports.sqlite", ("test-report-a", "test-report-b"))
+            ("reports.sqlite", "", ("test-report-a", "test-report-b"))
         ], self.transport.publish_calls)
 
     def test_generated_consumer_contract_uses_public_framework_api(self):
@@ -320,9 +347,28 @@ class ReportStoreManagerTest(unittest.TestCase):
         store = manager.create("reports.sqlite")
 
         self.assertTrue(store.path.is_file())
+        self.assertEqual("test-service", store.tracker_name)
         self.assertEqual([], transport.download_calls)
         manager.close()
 
+    def test_create_accepts_explicit_tracker_name(self):
+        transport = FakeTransport()
+        manager = ReportStoreManager(self.service, transport=transport)
+
+        store = manager.create(
+            "reports.sqlite",
+            tracker_name="Customer Report Group",
+        )
+
+        self.assertEqual("Customer Report Group", store.tracker_name)
+        manager.close()
+
+    def test_create_rejects_empty_tracker_name(self):
+        manager = ReportStoreManager(self.service, transport=FakeTransport())
+
+        with self.assertRaises(ReportStoreLocalIOError):
+            manager.create("reports.sqlite", tracker_name="  ")
+
     def test_discard_local_removes_only_open_local_store_and_allows_recreate(self):
         transport = FakeTransport()
         manager = ReportStoreManager(self.service, transport=transport)
@@ -429,6 +475,7 @@ class ReportStoreTransportTest(unittest.TestCase):
         store = SimpleNamespace(
             file_name="reports.sqlite",
             shared=False,
+            tracker_name="Customer Report Group",
             path=Path("/tmp/reports.sqlite"),
         )
 
@@ -436,10 +483,11 @@ class ReportStoreTransportTest(unittest.TestCase):
 
         self.assertEqual(1, len(service.task_manager.uploads))
         self.assertEqual(2, len(service.task_manager.pointers))
-        report_key, pointer = service.task_manager.pointers[0]
+        report_key, pointer, tracker_name = service.task_manager.pointers[0]
         self.assertEqual("test-report-a", report_key)
         self.assertEqual("REPORT_STORE_V2", pointer["protocol"])
         self.assertEqual("adapter-1", pointer["namespace"])
+        self.assertEqual("Customer Report Group", tracker_name)
 
     def test_task_manager_wraps_pointer_in_existing_report_csv_format(self):
         with tempfile.TemporaryDirectory() as temp_dir:
@@ -477,7 +525,10 @@ class ReportStoreTransportTest(unittest.TestCase):
 
             try:
                 published = manager.service_publish_report_pointer_v2(
-                    service, "test-report-a", pointer
+                    service,
+                    "test-report-a",
+                    pointer,
+                    tracker_name="Customer Report Group",
                 )
             finally:
                 TempfileUtils.temp_datasource_path = previous_temp_path
@@ -485,6 +536,7 @@ class ReportStoreTransportTest(unittest.TestCase):
         self.assertTrue(published)
         self.assertEqual(request.response_api, captured["endpoint"])
         self.assertEqual("adapter-1", captured["row"]["customer"])
+        self.assertEqual("Customer Report Group", captured["row"]["_tracker_name"])
         self.assertEqual(
             pointer,
             json.loads(captured["row"]["data_test-report-a_no_index"]),

{pam_python-0.2.9 → pam_python-0.2.11}/tests/test_typed_range_bar_report.py

@@ -50,8 +50,8 @@ class TypedRangeBarReportTest(unittest.TestCase):
             [{
                 "task": "Phase A",
                 "group": "Project 1",
-                "start": "2026-08-01T09:00:00+07:00",
-                "end": "2026-08-05T18:00:00+07:00",
+                "start": "2026-08-01 09:00:00",
+                "end": "2026-08-05 18:00:00",
             }],
             "2026-08",
         )
@@ -61,6 +61,16 @@ class TypedRangeBarReportTest(unittest.TestCase):
         measures = json.loads(row[0])
         self.assertIsInstance(measures["start"], int)
         self.assertGreater(measures["end"], measures["start"])
+        with self.assertRaises(ReportStoreValidationError):
+            report.append_ranges(
+                [{
+                    "task": "Wrong format",
+                    "group": "Project 1",
+                    "start": "2026-08-01T09:00:00Z",
+                    "end": "2026-08-05T18:00:00Z",
+                }],
+                "2026-08",
+            )
         with self.assertRaises(ReportStoreValidationError):
             report.append_ranges(
                 [{"task": "Bad", "group": "Project 1", "start": 20, "end": 10}],