projectdavid-orm 1.13.1__tar.gz → 1.14.0__tar.gz

{projectdavid_orm-1.13.1 → projectdavid_orm-1.14.0}/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.14.0](https://github.com/project-david-ai/projectdavid-orm/compare/v1.13.1...v1.14.0) (2026-11-13)
+
+
+### Features
+
+* **orm:** add durable execution lineage and forensic audit models ([21f89d3](https://github.com/project-david-ai/projectdavid-orm/commit/21f89d385273d21e39fcc32911039fcde6457032))
+
 ## [1.13.1](https://github.com/project-david-ai/projectdavid-orm/compare/v1.13.0...v1.13.1) (2026-09-29)
 
 

{projectdavid_orm-1.13.1/src/projectdavid_orm.egg-info → projectdavid_orm-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: projectdavid-orm
-Version: 1.13.1
+Version: 1.14.0
 Summary: Shared SQLAlchemy ORM models for ProjectDavid services
 Author-email: "Francis N." <engineering@projectdavid.co.uk>
 License: PolyForm Noncommercial License 1.0.0

{projectdavid_orm-1.13.1 → projectdavid_orm-1.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "projectdavid-orm"
-version = "1.13.1"
+version = "1.14.0"
 description = "Shared SQLAlchemy ORM models for ProjectDavid services"
 readme = "README.md"
 authors = [

projectdavid_orm-1.14.0/src/projectdavid_orm/projectdavid_orm/execution_ledger.py

@@ -0,0 +1,340 @@
+"""Durable execution lineage and forensic evidence metadata.
+
+These tables survive normal ephemeral Assistant lifecycle operations.
+
+Foreign keys to Runs and Actions use RESTRICT, not CASCADE. Controlled
+retention and erasure services must reconcile lineage before deletion.
+
+Import this module to register its models on the shared ORM Base.
+"""
+
+from __future__ import annotations
+
+import time
+
+from sqlalchemy import (
+    JSON,
+    BigInteger,
+    Boolean,
+    Column,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    UniqueConstraint,
+)
+
+from .base import Base
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+def _now_us() -> int:
+    return time.time_ns() // 1_000
+
+
+class RunExecutionEpoch(Base):
+    """One execution attempt belonging to a durable logical Run."""
+
+    __tablename__ = "run_execution_epochs"
+
+    id = Column(String(64), primary_key=True)
+
+    run_id = Column(
+        String(64),
+        ForeignKey("runs.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+
+    root_run_id = Column(
+        String(64),
+        ForeignKey("runs.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+
+    owner_user_id = Column(String(64), nullable=False)
+    epoch_number = Column(Integer, nullable=False)
+
+    state = Column(
+        String(32),
+        nullable=False,
+        default="reserved",
+    )
+
+    created_at = Column(BigInteger, nullable=False, default=_now)
+    started_at = Column(BigInteger, nullable=True)
+    last_seen_at = Column(BigInteger, nullable=True)
+    ended_at = Column(BigInteger, nullable=True)
+    terminal_status = Column(String(32), nullable=True)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "run_id",
+            "epoch_number",
+            name="uq_exec_epoch_run_number",
+        ),
+        Index(
+            "ix_exec_epoch_root_created",
+            "root_run_id",
+            "created_at",
+        ),
+        Index(
+            "ix_exec_epoch_owner_root",
+            "owner_user_id",
+            "root_run_id",
+        ),
+        Index(
+            "ix_exec_epoch_state_seen",
+            "state",
+            "last_seen_at",
+        ),
+    )
+
+
+class ExecutionActor(Base):
+    """Durable actor reservation and identity snapshot.
+
+    One actor can occupy a named slot within a Run execution epoch.
+    Database uniqueness prevents competing supervisor reservations.
+    """
+
+    __tablename__ = "execution_actors"
+
+    id = Column(String(64), primary_key=True)
+
+    epoch_id = Column(
+        String(64),
+        ForeignKey(
+            "run_execution_epochs.id",
+            ondelete="RESTRICT",
+        ),
+        nullable=False,
+    )
+
+    slot = Column(String(48), nullable=False)
+    execution_role = Column(String(48), nullable=False)
+
+    # Snapshots intentionally have no FK to assistants.
+    # Assistant cleanup must not invalidate execution provenance.
+    assistant_id_snapshot = Column(String(64), nullable=True)
+    model_snapshot = Column(String(128), nullable=True)
+
+    ephemeral = Column(Boolean, nullable=False, default=False)
+
+    state = Column(
+        String(32),
+        nullable=False,
+        default="reserved",
+    )
+
+    reserved_at = Column(BigInteger, nullable=False, default=_now)
+    activated_at = Column(BigInteger, nullable=True)
+    retired_at = Column(BigInteger, nullable=True)
+    last_seen_at = Column(BigInteger, nullable=True)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "epoch_id",
+            "slot",
+            name="uq_exec_actor_epoch_slot",
+        ),
+        Index(
+            "ix_exec_actor_assistant",
+            "assistant_id_snapshot",
+        ),
+        Index(
+            "ix_exec_actor_state_seen",
+            "state",
+            "last_seen_at",
+        ),
+    )
+
+
+class RunDelegation(Base):
+    """Links a parent Action to a delegated child execution."""
+
+    __tablename__ = "run_delegations"
+
+    id = Column(String(64), primary_key=True)
+
+    parent_epoch_id = Column(
+        String(64),
+        ForeignKey(
+            "run_execution_epochs.id",
+            ondelete="RESTRICT",
+        ),
+        nullable=False,
+    )
+
+    child_epoch_id = Column(
+        String(64),
+        ForeignKey(
+            "run_execution_epochs.id",
+            ondelete="RESTRICT",
+        ),
+        nullable=False,
+    )
+
+    parent_action_id = Column(
+        String(64),
+        ForeignKey("actions.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+
+    initiating_actor_id = Column(
+        String(64),
+        ForeignKey("execution_actors.id", ondelete="RESTRICT"),
+        nullable=True,
+    )
+
+    created_at = Column(BigInteger, nullable=False, default=_now)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "child_epoch_id",
+            name="uq_run_delegation_child_epoch",
+        ),
+        Index(
+            "ix_run_delegation_parent",
+            "parent_epoch_id",
+        ),
+        Index(
+            "ix_run_delegation_parent_action",
+            "parent_action_id",
+        ),
+    )
+
+
+class ExecutionEvent(Base):
+    """Structured, ordered execution evidence.
+
+    Raw reasoning, credentials and unfiltered tool outputs must not be
+    stored in details. The writer service must enforce an allowlist,
+    redact secrets, and protect events against unauthorised mutation.
+
+    Evidence digests require protected external checkpoints to provide
+    meaningful tamper-evidence.
+    """
+
+    __tablename__ = "execution_events"
+
+    id = Column(
+        BigInteger,
+        primary_key=True,
+        autoincrement=True,
+    )
+
+    epoch_id = Column(
+        String(64),
+        ForeignKey(
+            "run_execution_epochs.id",
+            ondelete="RESTRICT",
+        ),
+        nullable=False,
+    )
+
+    actor_id = Column(
+        String(64),
+        ForeignKey(
+            "execution_actors.id",
+            ondelete="RESTRICT",
+        ),
+        nullable=True,
+    )
+
+    origin_run_id = Column(
+        String(64),
+        ForeignKey("runs.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+
+    event_type = Column(String(64), nullable=False)
+    schema_version = Column(Integer, nullable=False, default=1)
+
+    evidence_class = Column(
+        String(24),
+        nullable=False,
+        default="operational",
+    )
+
+    # Microsecond timestamps permit high-resolution reconstruction
+    # of interleaved agent and tool activity.
+    occurred_at_us = Column(BigInteger, nullable=False)
+    recorded_at_us = Column(
+        BigInteger,
+        nullable=False,
+        default=_now_us,
+    )
+
+    evidence_expires_at = Column(BigInteger, nullable=True)
+
+    action_id_snapshot = Column(String(64), nullable=True)
+    tool_call_id_snapshot = Column(String(64), nullable=True)
+
+    details = Column(JSON, nullable=False, default=dict)
+
+    # Opaque reference to governed, separately protected evidence.
+    evidence_ref = Column(String(255), nullable=True)
+    evidence_sha256 = Column(String(64), nullable=True)
+
+    previous_digest = Column(String(64), nullable=True)
+    record_digest = Column(String(64), nullable=True)
+
+    __table_args__ = (
+        Index(
+            "ix_exec_event_epoch_id",
+            "epoch_id",
+            "id",
+        ),
+        Index(
+            "ix_exec_event_origin_time",
+            "origin_run_id",
+            "occurred_at_us",
+        ),
+        Index(
+            "ix_exec_event_type_time",
+            "event_type",
+            "occurred_at_us",
+        ),
+    )
+
+
+class EvidenceRetentionHold(Base):
+    """Authorised preservation hold for one root Run.
+
+    An open hold blocks ordinary retention purging. Releasing a hold
+    does not independently authorise deletion of otherwise protected data.
+    """
+
+    __tablename__ = "evidence_retention_holds"
+
+    id = Column(String(64), primary_key=True)
+
+    root_run_id = Column(
+        String(64),
+        ForeignKey("runs.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+
+    case_reference = Column(String(128), nullable=False)
+    reason_code = Column(String(48), nullable=False)
+    authorised_by = Column(String(64), nullable=False)
+
+    created_at = Column(BigInteger, nullable=False, default=_now)
+    reviewed_at = Column(BigInteger, nullable=True)
+    expires_at = Column(BigInteger, nullable=True)
+    released_at = Column(BigInteger, nullable=True)
+
+    __table_args__ = (
+        Index(
+            "ix_evidence_hold_root_released",
+            "root_run_id",
+            "released_at",
+        ),
+        Index(
+            "ix_evidence_hold_case",
+            "case_reference",
+        ),
+    )

{projectdavid_orm-1.13.1 → projectdavid_orm-1.14.0}/src/projectdavid_orm/projectdavid_orm/models.py

@@ -21,6 +21,10 @@ from sqlalchemy.orm import joinedload, relationship
 
 from projectdavid_orm.enums import StatusEnum
 
+# Register execution-lineage models on the shared declarative Base.
+# This import is intentionally placed after existing model declarations.
+# Required for Alembic and normal ORM metadata discovery.
+from . import execution_ledger as _execution_ledger  # noqa: E402, F401
 from .base import Base
 
 # --- Association Tables ---

{projectdavid_orm-1.13.1 → projectdavid_orm-1.14.0/src/projectdavid_orm.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: projectdavid-orm
-Version: 1.13.1
+Version: 1.14.0
 Summary: Shared SQLAlchemy ORM models for ProjectDavid services
 Author-email: "Francis N." <engineering@projectdavid.co.uk>
 License: PolyForm Noncommercial License 1.0.0

{projectdavid_orm-1.13.1 → projectdavid_orm-1.14.0}/src/projectdavid_orm.egg-info/SOURCES.txt

@@ -20,8 +20,11 @@ src/projectdavid_orm.egg-info/top_level.txt
 src/projectdavid_orm/constants/__init__.py
 src/projectdavid_orm/projectdavid_orm/__init__.py
 src/projectdavid_orm/projectdavid_orm/base.py
+src/projectdavid_orm/projectdavid_orm/execution_ledger.py
 src/projectdavid_orm/projectdavid_orm/models.py
 src/projectdavid_orm/utilities/__init__.py
 tests/test_clients.py
+tests/test_execution_ledger_registration.py
+tests/test_execution_ledger_schema.py
 tests/test_runtime_dependency_boundary.py
 tests/test_scratchpad_public_exports.py

projectdavid_orm-1.14.0/tests/test_execution_ledger_registration.py

@@ -0,0 +1,42 @@
+"""Verify normal ORM imports register the execution ledger.
+
+The test runs in a fresh Python interpreter so that earlier test imports
+cannot accidentally register the tables and mask a packaging defect.
+"""
+
+import subprocess
+import sys
+
+
+def test_fresh_models_import_registers_execution_ledger():
+    code = """
+from projectdavid_orm.projectdavid_orm import models
+
+expected = {
+    "run_execution_epochs",
+    "execution_actors",
+    "run_delegations",
+    "execution_events",
+    "evidence_retention_holds",
+}
+
+registered = set(models.User.metadata.tables)
+missing = expected - registered
+
+assert not missing, (
+    f"Unregistered execution ledger tables: {sorted(missing)}"
+)
+"""
+
+    result = subprocess.run(
+        [sys.executable, "-c", code],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 0, (
+        "Fresh ORM import failed.\n"
+        f"STDOUT:\n{result.stdout}\n"
+        f"STDERR:\n{result.stderr}"
+    )

projectdavid_orm-1.14.0/tests/test_execution_ledger_schema.py

@@ -0,0 +1,82 @@
+"""Structural tests for Project David execution-lineage models."""
+
+from sqlalchemy import UniqueConstraint
+from sqlalchemy.dialects.mysql import dialect as mysql_dialect
+from sqlalchemy.schema import CreateTable
+
+from projectdavid_orm.projectdavid_orm import execution_ledger, models
+
+EXPECTED_TABLES = {
+    "run_execution_epochs",
+    "execution_actors",
+    "run_delegations",
+    "execution_events",
+    "evidence_retention_holds",
+}
+
+
+def test_models_share_existing_metadata():
+    metadata = models.User.metadata
+
+    assert EXPECTED_TABLES.issubset(metadata.tables.keys())
+
+
+def test_supervisor_and_epoch_uniqueness():
+    metadata = models.User.metadata
+
+    expected = {
+        "run_execution_epochs": "uq_exec_epoch_run_number",
+        "execution_actors": "uq_exec_actor_epoch_slot",
+        "run_delegations": "uq_run_delegation_child_epoch",
+    }
+
+    for table_name, constraint_name in expected.items():
+        table = metadata.tables[table_name]
+        names = {
+            constraint.name
+            for constraint in table.constraints
+            if isinstance(constraint, UniqueConstraint)
+        }
+        assert constraint_name in names
+
+
+def test_protected_foreign_keys_restrict_deletion():
+    metadata = models.User.metadata
+
+    for name in EXPECTED_TABLES:
+        table = metadata.tables[name]
+
+        assert table.foreign_keys
+
+        for foreign_key in table.foreign_keys:
+            assert foreign_key.ondelete == "RESTRICT"
+
+
+def test_actor_identity_survives_assistant_deletion():
+    actor_table = models.User.metadata.tables["execution_actors"]
+
+    assistant_id = actor_table.c.assistant_id_snapshot
+
+    # This is an identity snapshot, deliberately not a foreign key.
+    assert not assistant_id.foreign_keys
+
+
+def test_forensic_event_resolution():
+    table = models.User.metadata.tables["execution_events"]
+
+    assert "occurred_at_us" in table.c
+    assert "recorded_at_us" in table.c
+    assert "evidence_sha256" in table.c
+    assert "evidence_expires_at" in table.c
+
+
+def test_mysql_ddl_compiles_for_every_new_table():
+    metadata = models.User.metadata
+    dialect = mysql_dialect()
+
+    for table_name in EXPECTED_TABLES:
+        statement = CreateTable(metadata.tables[table_name])
+        compiled = str(statement.compile(dialect=dialect))
+
+        assert "CREATE TABLE" in compiled
+        assert "RESTRICT" in compiled