Add module-level CLAUDE.md files for models, api, core, and tests

Each file documents non-obvious patterns specific to that module:
- models/: new model checklist, fill_from_dict pattern, _last_persistent_instance
  lifecycle, EnumCoercionMixin usage, standard field requirements
- api/: function signature conventions, REST call patterns, pagination helpers,
  new service file checklist
- core/: async_to_sync internals, retry strategies, credentials chain,
  upload/download resilience, concrete types registration
- tests/: async-only test convention, unit test socket blocking, integration
  test cleanup with schedule_for_cleanup(), fixture scoping

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: BryanFauble

synapseclient/api/CLAUDE.md

@@ -0,0 +1,45 @@
+<!-- Last reviewed: 2026-03 -->
+
+## Project
+
+REST API service layer — thin async functions that map to Synapse REST endpoints. One file per resource type. Called by model layer, never by end users directly.
+
+## Conventions
+
+### Function signature pattern
+```python
+async def verb_resource(
+    required_param: str,
+    optional_param: str = None,
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> Dict[str, Any]:
+```
+- All functions are `async def`
+- `synapse_client` is always the last parameter, keyword-only (after `*`)
+- Use `Synapse.get_client(synapse_client=synapse_client)` to get the client instance
+- Use `TYPE_CHECKING` guard for `Synapse` import to avoid circular dependencies
+
+### REST call pattern
+```python
+client = Synapse.get_client(synapse_client=synapse_client)
+return await client.rest_post_async(uri="/endpoint", body=json.dumps(request))
+```
+Available methods: `rest_get_async`, `rest_post_async`, `rest_put_async`, `rest_delete_async`. Pass `endpoint=client.fileHandleEndpoint` for file handle operations; omit for the default repository endpoint.
+
+### Return values
+- Most functions return raw `Dict[str, Any]` — transformation happens in the model layer via `fill_from_dict()`
+- Some return dataclass instances (e.g., `EntityHeader`) when the data is only used internally
+- Delete operations return `None`
+
+### Pagination
+Use helpers from `api_client.py`:
+- `rest_get_paginated_async()` — for GET endpoints with limit/offset. Expects `results` or `children` key.
+- `rest_post_paginated_async()` — for POST endpoints with `nextPageToken`. Expects `page` array.
+Both are async generators yielding individual items.
+
+### Adding a new service file
+1. Create `synapseclient/api/new_service.py`
+2. Import and add all public functions to `api/__init__.py` and its `__all__`
+3. Use `json.dumps()` for request bodies (not dict)
+4. Reference `entity_services.py` for CRUD pattern, `table_services.py` for pagination pattern

synapseclient/core/CLAUDE.md

@@ -0,0 +1,38 @@
+<!-- Last reviewed: 2026-03 -->
+
+## Project
+
+Infrastructure layer — authentication, file transfer, retry logic, caching, OpenTelemetry tracing, and the `async_to_sync` decorator that powers the dual sync/async API.
+
+## Conventions
+
+### async_to_sync decorator (`async_utils.py`)
+- Scans class for `*_async` methods and creates sync wrappers stripping the suffix
+- Uses `ClassOrInstance` descriptor — methods work on both class and instance
+- Detects running event loop: uses `nest_asyncio.apply()` for nested loops, raises on Python 3.14+
+- `wrap_async_to_sync()` for standalone functions (not class methods)
+- `wrap_async_generator_to_sync_generator()` for async generators — must `aclose()` in finally block
+
+### Retry patterns (`retry.py`)
+- `with_retry()` — simple exponential backoff, fixed retry count (default 3)
+- `with_retry_time_based_async()` — time-bounded (default 20 min), exponential backoff with jitter
+- Default retryable status codes: `[429, 500, 502, 503, 504]`
+- `NON_RETRYABLE_ERRORS` list overrides status code retry (e.g., "is not a table or view")
+- 429 throttling: wait bumps to 16 seconds minimum
+
+### Credentials chain (`credentials/`)
+Provider chain tries in order: login args → config file → env var (`SYNAPSE_AUTH_TOKEN`) → AWS SSM. Credentials implement `requests.auth.AuthBase`, adding `Authorization: Bearer` header. Profile selection via `SYNAPSE_PROFILE` env var or `--profile` arg.
+
+### Upload/download
+- Both use 60-retry params spanning ~30 minutes for resilience
+- Upload determines storage location from project settings, supports S3/SFTP/GCP
+- Download validates MD5 post-transfer, raises `SynapseMd5MismatchError` on mismatch
+- Progress via `tqdm`; multi-threaded uploads suppress per-file messages via `cumulative_transfer_progress`
+
+### concrete_types.py
+Maps Java class names from Synapse REST API for polymorphic deserialization. When adding a new entity type, add its concrete type string here AND in `api/entity_factory.py` type map.
+
+## Constraints
+
+- Bearer tokens must never appear in logs — use `BEARER_TOKEN_PATTERN` regex for redaction.
+- `delete_none_keys()` must be called on all dicts before sending to the API — Synapse rejects null values.

synapseclient/models/CLAUDE.md

@@ -0,0 +1,54 @@
+<!-- Last reviewed: 2026-03 -->
+
+## Project
+
+Dataclass-based entity models for the Synapse REST API. Each model represents a Synapse resource (Project, File, Folder, Table, etc.) with async-first methods and auto-generated sync wrappers.
+
+## Conventions
+
+### New model checklist
+1. Decorate with `@dataclass()` then `@async_to_sync` (order matters — `@async_to_sync` must be outer)
+2. Inherit from: `SynchronousProtocol`, then mixins (`AccessControllable`, `StorableContainer`, etc.)
+3. Create a matching protocol file in `protocols/` with sync method signatures
+4. Register concrete type in `core/constants/concrete_types.py`
+5. Add to `models/__init__.py` exports and `__all__`
+6. Add to entity factory type map in `api/entity_factory.py` if it's an entity type
+
+### Standard fields every entity model must have
+```python
+id: Optional[str] = None
+name: Optional[str] = None
+etag: Optional[str] = None
+created_on: Optional[str] = field(default=None, compare=False)
+modified_on: Optional[str] = field(default=None, compare=False)
+created_by: Optional[str] = field(default=None, compare=False)
+modified_by: Optional[str] = field(default=None, compare=False)
+create_or_update: bool = field(default=True, repr=False)
+_last_persistent_instance: Optional["Self"] = field(default=None, repr=False, compare=False)
+```
+
+Use `compare=False` for read-only timestamps, child collections, annotations, and internal state — this makes `has_changed` compare only user-modifiable fields.
+
+### fill_from_dict() pattern
+Maps camelCase REST keys to snake_case fields via `.get("camelCaseKey", None)`. Must return `self`. Handle annotations separately with `set_annotations` parameter. Reference: `folder.py`, `file.py`.
+
+### _last_persistent_instance lifecycle
+- Set via `_set_last_persistent_instance()` after every successful `store_async()` and `get_async()`
+- Uses `dataclasses.replace(self)` with `deepcopy` for annotations
+- Enables `has_changed` property — skips redundant API calls when nothing changed
+- Drives `create_or_update` logic: if no `_last_persistent_instance`, attempts merge with existing Synapse entity
+
+### @otel_trace_method on every async method
+Apply to all async methods that call Synapse. Format: `f"{ClassName}_{Operation}: ID: {self.id}, Name: {self.name}"`.
+
+### delete_none_keys() before API calls
+Always call `delete_none_keys()` on request dicts before passing to `store_entity()` — the Synapse API rejects `None` values.
+
+### EnumCoercionMixin for enum fields
+If a model has enum-typed fields, inherit from `EnumCoercionMixin` and declare `_ENUM_FIELDS: ClassVar[Dict[str, type]]` mapping field names to enum classes. Auto-coerces strings to enums on assignment via `__setattr__`.
+
+## Constraints
+
+- Never manually write sync methods on models — `@async_to_sync` generates them. Use `@skip_async_to_sync` to exclude specific methods.
+- Protocol files must exactly match the async method signatures (minus `_async` suffix) — they exist for IDE type hints, not runtime dispatch.
+- Child collections (files, folders, tables) must use `compare=False` to avoid breaking `has_changed`.

tests/CLAUDE.md

@@ -0,0 +1,33 @@
+<!-- Last reviewed: 2026-03 -->
+
+## Project
+
+Test suite for the Synapse Python Client. Unit tests run without network access; integration tests hit the live Synapse API.
+
+## Conventions
+
+### Write async tests only
+Do not create synchronous test files. The `@async_to_sync` decorator is validated by a dedicated smoke test. Duplicate sync tests were removed to cut CI cost and maintenance burden.
+
+### Unit tests (`tests/unit/`)
+- `pytest-socket` blocks all network calls (unix sockets allowed on non-Windows for async event loop)
+- Session-scoped `syn` fixture: `Synapse(skip_checks=True, cache_client=False)` with silent logger
+- Autouse `set_timezone` fixture forces `TZ=UTC` for deterministic timestamps
+- Client caching disabled via `Synapse.allow_client_caching(False)`
+- Use `AsyncMock` for async method mocking, `create_autospec` for type-safe mocks
+- Class-based test organization with `@pytest.fixture(scope="function", autouse=True)` for setup
+
+### Integration tests (`tests/integration/`)
+- All async tests share one event loop: `asyncio_default_fixture_loop_scope = session`
+- `schedule_for_cleanup(item)` — defer entity/file cleanup to session teardown. Always use this instead of inline deletion.
+- Per-worker project fixtures (`project_model`, `project`) created during session setup
+- `--reruns 3` for flaky retry, `-n 8 --dist loadscope` for parallelism
+- OpenTelemetry tracing opt-in via `SYNAPSE_INTEGRATION_TEST_OTEL_ENABLED` env var
+
+### No `@pytest.mark.asyncio` needed
+`asyncio_mode = auto` in pytest.ini — all async test functions are auto-detected.
+
+## Constraints
+
+- Unit tests must never make network calls — `pytest-socket` will fail them. Mock all HTTP interactions.
+- Integration test cleanup is mandatory — use `schedule_for_cleanup()` for every created resource to avoid orphaned Synapse entities.