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

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

@@ -1,3 +1,18 @@
+# [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)
+
+
+### Bug Fixes
+
+* **deps:** decouple ORM from Common runtime ([4e1ca2e](https://github.com/project-david-ai/projectdavid-orm/commit/4e1ca2e9b2a1b84d014fc0447849964bf974daf5))
+* **exports:** expose Scratchpad through public ORM API ([205ae03](https://github.com/project-david-ai/projectdavid-orm/commit/205ae03ebe801701d9c19ce83e1b59764a8ab93b))
+
 # [1.13.0](https://github.com/project-david-ai/projectdavid-orm/compare/v1.12.0...v1.13.0) (2026-09-29)
 
 

{projectdavid_orm-1.13.0/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.0
+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
@@ -15,6 +15,8 @@ Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: pymysql
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dotenv
+Requires-Dist: passlib==1.7.4
+Requires-Dist: bcrypt==4.0.1
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: black==24.1.1; extra == "dev"

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "projectdavid-orm"
-version = "1.13.0"
+version = "1.14.0"
 description = "Shared SQLAlchemy ORM models for ProjectDavid services"
 readme = "README.md"
 authors = [
@@ -19,6 +19,8 @@ dependencies = [
   "pymysql",
   "pydantic>=2.0",
   "python-dotenv",
+  "passlib==1.7.4",
+  "bcrypt==4.0.1",
 ]
 
 [project.optional-dependencies]

{projectdavid_orm-1.13.0 → projectdavid_orm-1.14.0}/src/projectdavid_orm/__init__.py

@@ -15,6 +15,7 @@ from .ormInterface import (
     OrmInterface,
     Run,
     Sandbox,
+    Scratchpad,
     Thread,
     TrainingJob,
     User,
@@ -36,6 +37,7 @@ __all__ = [
     "Assistant",
     "Action",
     "Sandbox",
+    "Scratchpad",
     # File system
     "File",
     "FileStorage",

projectdavid_orm-1.14.0/src/projectdavid_orm/enums.py

@@ -0,0 +1,20 @@
+from enum import Enum
+
+
+class StatusEnum(str, Enum):
+    """Canonical persistence status values used by ORM models."""
+
+    deleted = "deleted"
+    active = "active"
+    queued = "queued"
+    in_progress = "in_progress"
+    pending_action = "action_required"
+    completed = "completed"
+    failed = "failed"
+    cancelling = "cancelling"
+    cancelled = "cancelled"
+    pending = "pending"
+    processing = "processing"
+    expired = "expired"
+    retrying = "retrying"
+    offline = "offline"

{projectdavid_orm-1.13.0 → projectdavid_orm-1.14.0}/src/projectdavid_orm/ormInterface.py

@@ -30,6 +30,8 @@ class OrmInterface:
     Action = Action
     # Sandbox model
     Sandbox = Sandbox
+    # Scratchpad model
+    Scratchpad = Scratchpad
     # File model
     File = File
     # FileStorage model

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.0 → projectdavid_orm-1.14.0}/src/projectdavid_orm/projectdavid_orm/models.py

@@ -3,9 +3,6 @@ import time
 from datetime import datetime
 
 from passlib.context import CryptContext
-from projectdavid_common import ValidationInterface
-from projectdavid_common.schemas.enums import StatusEnum
-from projectdavid_common.utilities.logging_service import LoggingUtility
 from sqlalchemy import JSON, BigInteger, Boolean, Column, DateTime
 from sqlalchemy import Enum as SAEnum
 from sqlalchemy import (
@@ -22,11 +19,13 @@ from sqlalchemy import (
 from sqlalchemy.ext.mutable import MutableDict
 from sqlalchemy.orm import joinedload, relationship
 
-from .base import Base
-
-logger = LoggingUtility()
+from projectdavid_orm.enums import StatusEnum
 
-validation = ValidationInterface
+# 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 ---
 
@@ -428,7 +427,7 @@ class Run(Base):
     required_action = Column(String(256), nullable=True)
     response_format = Column(String(64), nullable=True)
 
-    status = Column(SAEnum(validation.StatusEnum), nullable=False)
+    status = Column(SAEnum(StatusEnum), nullable=False)
 
     thread_id = Column(String(64), nullable=False)
     tool_choice = Column(String(64), nullable=True)

{projectdavid_orm-1.13.0 → 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.0
+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
@@ -15,6 +15,8 @@ Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: pymysql
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dotenv
+Requires-Dist: passlib==1.7.4
+Requires-Dist: bcrypt==4.0.1
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: black==24.1.1; extra == "dev"

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

@@ -10,6 +10,7 @@ src/projectdavid_common.egg-info/entry_points.txt
 src/projectdavid_common.egg-info/requires.txt
 src/projectdavid_common.egg-info/top_level.txt
 src/projectdavid_orm/__init__.py
+src/projectdavid_orm/enums.py
 src/projectdavid_orm/ormInterface.py
 src/projectdavid_orm.egg-info/PKG-INFO
 src/projectdavid_orm.egg-info/SOURCES.txt
@@ -19,6 +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_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.13.0 → projectdavid_orm-1.14.0}/src/projectdavid_orm.egg-info/requires.txt

@@ -2,6 +2,8 @@ sqlalchemy>=2.0
 pymysql
 pydantic>=2.0
 python-dotenv
+passlib==1.7.4
+bcrypt==4.0.1
 
 [dev]
 pytest

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

projectdavid_orm-1.14.0/tests/test_runtime_dependency_boundary.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+
+from projectdavid_orm.enums import StatusEnum
+from projectdavid_orm.projectdavid_orm.models import ApiKey
+
+EXPECTED_STATUS_VALUES = {
+    "deleted": "deleted",
+    "active": "active",
+    "queued": "queued",
+    "in_progress": "in_progress",
+    "pending_action": "action_required",
+    "completed": "completed",
+    "failed": "failed",
+    "cancelling": "cancelling",
+    "cancelled": "cancelled",
+    "pending": "pending",
+    "processing": "processing",
+    "expired": "expired",
+    "retrying": "retrying",
+    "offline": "offline",
+}
+
+
+def test_status_enum_persistence_contract_is_preserved():
+    assert {item.name: item.value for item in StatusEnum} == EXPECTED_STATUS_VALUES
+
+
+def test_models_have_no_runtime_dependency_on_common():
+    models_path = (
+        Path(__file__).parents[1]
+        / "src"
+        / "projectdavid_orm"
+        / "projectdavid_orm"
+        / "models.py"
+    )
+
+    source = models_path.read_text(encoding="utf-8")
+
+    assert "projectdavid_common" not in source
+    assert "ValidationInterface" not in source
+    assert "LoggingUtility" not in source
+
+
+def test_bcrypt_backend_hashes_and_verifies_api_keys():
+    plain = "project-david-runtime-dependency-probe"
+
+    hashed = ApiKey.hash_key(plain)
+
+    assert hashed != plain
+
+    api_key = ApiKey(
+        key_name="dependency-probe",
+        hashed_key=hashed,
+    )
+
+    assert api_key.verify_key(plain)
+    assert not api_key.verify_key(plain + "-invalid")

projectdavid_orm-1.14.0/tests/test_scratchpad_public_exports.py

@@ -0,0 +1,6 @@
+from projectdavid_orm import OrmInterface, Scratchpad
+
+
+def test_scratchpad_is_exposed_through_public_orm_api():
+    assert Scratchpad.__tablename__ == "scratchpads"
+    assert OrmInterface.Scratchpad is Scratchpad