# Internal Data Access

> Company-specific patterns for using the approved CorpData Python package safely and testably.

- Skill: `jacobragsdale/internal-data-access` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jacobragsdale/internal-data-access`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jacobragsdale/internal-data-access/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jacobragsdale (https://skillmd.com/u/jacobragsdale)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jacobragsdale/internal-data-access

---

# CorpData access requirements

Use the approved `corpdata.session.UnitOfWork` boundary; services must not construct raw
SQLAlchemy engines or sessions. Obtain repositories from `uow.repositories`, write through those
repositories, and call `uow.commit()` exactly once at the application-service boundary.

Golden path:

```python
async with UnitOfWork.for_tenant(tenant_id) as uow:
    customer = await uow.repositories.customers.require(customer_id)
    customer.rename(display_name)
    await uow.commit()
```

Do not call `session.commit()` inside a repository: it breaks CorpData's audit outbox and makes
multi-repository operations partially durable. Do not catch `CorpDataError` and return `None`;
translate `RecordNotFound` at the API boundary and let retryable infrastructure errors reach the
company retry middleware.

Tests must use `corpdata.testing.FakeUnitOfWork`, assert resulting domain state and emitted outbox
events, and never mock SQLAlchemy internals. Before handing off, run:

```text
uv run pytest tests/unit tests/contract/corpdata
uv run basedpyright src
```

Canonical reference: `ENG-DATA-014`. Stop for data-platform review before adding a new database,
bypassing tenant scoping, or changing transaction isolation.