resourcey 0.0.1__tar.gz

resourcey-0.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+*.egg-info/
+dist/
+build/
+
+# uv
+# uv.lock IS committed — it pins the resolved dependency graph.
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Editor
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/tasks.json
+
+# OS
+.DS_Store
+examples/02_mongodb/uv.lock

resourcey-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tofarr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

resourcey-0.0.1/PKG-INFO

@@ -0,0 +1,504 @@
+Metadata-Version: 2.5
+Name: resourcey
+Version: 0.0.1
+Summary: A resource-oriented Python web framework built on FastAPI, SQLAlchemy, and Alembic — progressive enhancement with escape hatches to the underlying stack.
+Project-URL: Repository, https://github.com/tofarr/resourcey
+Project-URL: Issues, https://github.com/tofarr/resourcey/issues
+Project-URL: Changelog, https://github.com/tofarr/resourcey/releases
+Author: tofarr
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alembic,async,fastapi,framework,resource,rest,sqlalchemy
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: fastapi>=0.115
+Requires-Dist: joserfc>=1.7.5
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.22; extra == 'dev'
+Requires-Dist: fakeredis>=2.38.0; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mongomock>=4.3; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pymongo>=4.18.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: mongodb
+Requires-Dist: motor>=3.6; extra == 'mongodb'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Provides-Extra: webhooks
+Requires-Dist: httpx>=0.27; extra == 'webhooks'
+Description-Content-Type: text/markdown
+
+# resourcey
+
+A resource-oriented Python web framework built on FastAPI, SQLAlchemy, and
+Alembic — **progressive enhancement with escape hatches to the underlying
+stack.**
+
+## Installation
+
+```bash
+pip install resourcey
+```
+
+```bash
+uv add resourcey
+```
+
+Optional extras pull in a driver for the parts you use:
+
+| Extra | Adds | For |
+|---|---|---|
+| `resourcey[mongodb]` | `motor` | the Mongo backend |
+| `resourcey[s3]` | `boto3` | the S3 file-store medium |
+| `resourcey[redis]` | `redis` | `RedisTrigger` / `RedisChannel` |
+| `resourcey[webhooks]` | `httpx` | `WebhookTrigger` |
+| `resourcey[dev]` | pytest, ruff, mypy, test drivers | working on `resourcey` itself |
+
+## Why?
+
+Most web frameworks either hide the database entirely or make you wire every
+layer by hand. `resourcey` takes a middle path: you declare a **resource**
+with enough metadata to describe how it should be stored, validated, and
+exposed, and the framework generates a service for you. When the abstraction
+gets in the way, you drop back a rung — to FastAPI, SQLAlchemy, or Alembic —
+and nothing breaks.
+
+The guiding principles:
+
+* **Resource-oriented.** A resource is the central unit. Define it once — for
+  SQL, by declaring your SQLAlchemy model — and derive the DTO, the REST
+  models, the service, and the permission checks from that single declaration.
+* **Progressive enhancement.** Each layer is opt-in. Use the generated
+  service, or write your own route that calls the repository directly, or
+  query SQLAlchemy yourself. The layers compose; they don't trap you.
+* **Escape hatches.** FastAPI, SQLAlchemy, and Alembic are first-class
+  citizens, not implementation details. You can always reach them.
+
+## What a resource gives you
+
+Declaring a resource produces:
+
+* **A REST service** exposing the standard actions:
+  `create`, `read`, `update`, `delete`, `search`, `count`, `batch_read`, plus one
+  app-level `POST /batch-edit` spanning every resource.
+* **Pydantic models** for request/response validation, projected from the
+  resource's DTO declaration — create / update / read / search shapes, never
+  hand-written.
+* **Persistence**, from whichever backend you declared it against. For SQL the
+  workflow is **model-first**: your SQLAlchemy model is the schema of record and
+  the DTO is inferred from it, so the mapping you already write stays
+  authoritative (and Alembic autogenerates from that same metadata). The Mongo
+  and list backends are DTO-first, since they have no schema of record.
+* **Search filtering** — `search` and `count` accept `<field>__<op>` query
+  params (`?title__contains=ali&id__gt=5`). A field is filterable exactly when
+  the read model exposes it, so a hidden field is rejected `400`; a resource can
+  declare a richer filter via `get_search_filter_type`. Filters lower to a
+  storage-agnostic tree and are pushed into the SQL `WHERE` clause; an
+  unconvertible filter fails loudly unless the resource opts into an in-memory
+  fallback.
+* **Sorting and cursor paging** — `?sort=<field>&desc=true` over any sortable
+  (i.e. readable) field, with opaque keyset cursors instead of `offset`.
+* **Caching** — an `ETag` / `Last-Modified` strategy chosen from the resource's
+  shape, marked `private` whenever a response is caller-scoped.
+* **Authorization** — pluggable `Policy` rules reduce a principal to a
+  per-action filter: API-key / cookie authentication, per-app roles, and a
+  stored users / groups / roles RBAC store.
+
+## Storage backends
+
+A resource is declared against one of three backends; the action contract,
+paging, sort, filters, and cache headers are identical across all three.
+
+| Backend | Base class | Storage |
+|---|---|---|
+| SQL | `resourcey.sql.sql_resource.SqlResource` | SQLAlchemy 2 (async) table |
+| Mongo | `resourcey.mongo.mongo_resource.MongoResource` | an async `motor` collection |
+| List | `resourcey.list.list_resource.ListResource` | an in-process list of Pydantic objects |
+
+(There are no `__init__.py` re-exports, so import from the module that defines
+the class — `from resourcey.sql.sql_resource import SqlResource`.)
+
+A **list-backed** resource is read-only: it narrows its actions to
+`read` / `search` / `count` / `batch_read` and serves data already modelled as
+Pydantic objects (country codes, feature flags, catalog entries) without
+copying it into a table. Because the objects already exist as Pydantic models,
+there is no schema generation — the model is projected onto the DTO the REST
+shapes derive from, and (being read-only) there is no create/update model and
+no columns. The list *is* the storage, so there is no table and no migration.
+
+```python
+from pydantic import BaseModel
+
+from resourcey.core.manifest import Manifest
+from resourcey.list.list_resource import ListResource
+
+
+class Country(BaseModel):
+    id: str
+    name: str
+    iso3: str
+
+
+countries = [
+    Country(id="us", name="United States", iso3="USA"),
+    Country(id="ca", name="Canada", iso3="CAN"),
+]
+resource = ListResource(countries, path="countries")
+
+manifest = Manifest(resources=(resource,))
+```
+
+That manifest serves `GET /countries` (search), `GET /countries/count`,
+`GET /countries/batch-read`, and `GET /countries/{id}` — and nothing else: a
+write route is never mounted, so a `POST` is a `405`.
+
+`defensive=True` is the default: every object the resource outputs is a deep
+copy of the stored object, so a caller cannot mutate the served collection
+through a result. Pass `defensive=False` to serve the stored objects directly.
+
+## The `core` package — DTO, Resource, Service, Manifest
+
+`src/resourcey/core/` is a deliberately minimal package that states the
+architecture in terms of a **DTO**, a **Resource**, a **Service**, and a
+**Manifest**. It is the foundation every backend and transport layer is built
+on.
+
+The split separates **the DTO** (the data object you work with internally) from
+**the six REST models** (the wire shapes), which the older code entangled, and
+does away with six hand-written models per resource — those are now *derived*.
+
+Here is a whole manifest against the SQL backend — the ORM models are the only
+declarations:
+
+```python
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from resourcey.core.manifest import Manifest
+from resourcey.sql.sql_resource import SqlResource
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Thread(Base):
+    __tablename__ = "threads"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    title: Mapped[str]
+
+
+class Message(Base):
+    __tablename__ = "messages"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    thread_id: Mapped[int] = mapped_column(ForeignKey("threads.id"))
+    body: Mapped[str]
+
+
+manifest = Manifest(resources=(SqlResource(Thread), SqlResource(Message)))
+```
+
+From those two classes `create_app(manifest)` serves `POST /threads` and
+`GET /threads` (search), `GET|PATCH|DELETE /threads/{id}`, `GET /threads/count`,
+and `GET /threads/batch-read` — and the same set for `messages` — plus
+`POST /batch-edit`, which spans both resources, and the OpenAPI docs.
+
+`POST /batch-edit` takes one ordered list of `create` / `update` / `delete`
+nodes, each naming its target resource, and answers with a positionally aligned
+list. Nodes apply in the order given, so a later node sees an earlier node's
+write. The first failure aborts the batch; rollback is best effort, holding
+wherever the backend provides a shared transaction (SQL resources on one
+session factory roll back together). It is mounted by default — pass
+`create_app(manifest, batch_edit=False)` to turn it off, or
+`batch_edit_path="/ops/edits"` to move it. The node count is capped by
+`batch_edit_max_edits`, which defaults to `RequestLimitsConfig.max_batch_edits`
+(`APP_MAX_BATCH_EDITS`, 100). A resource opts out by declaring no write action,
+and a hidden resource is never reachable through it. It is the **only** batch
+write surface: there is no per-resource `/batch-edit`, and each node is
+authorized against its own singular action.
+
+SQLAlchemy is the schema of record: the DTO and the six REST models are
+inferred from the ORM model, so a developer keeps the mapping they already
+write. The Mongo backend is DTO-first instead (there is no schema of record);
+see its section below.
+
+The five files:
+
+* **`dto.py`** — a `DTO` is a plain declaration class (not a Pydantic model).
+  Fields carry ordinary Pydantic annotations plus a `DtoField` describing how
+  each projects into the six REST shapes via six `in_*` flags
+  (`in_create_request`, `in_create_response`, `in_update_request`,
+  `in_update_response`, `in_read_response`, `in_search_response` — all default
+  `True`, superseding the older `creatable` / `updatable` / `readable` triple).
+  Tag a field with `Annotated[T, DtoField(...)]` — the canonical Pydantic
+  mechanism; it keeps the real field type (the assignment form
+  `key: str = DtoField(...)` is a type error under `mypy --strict`), and no
+  explicit `| Missing` is needed because the generator widens every field
+  itself:
+
+  ```python
+  class MyStoredKey(DTO):
+      id: Annotated[
+          UUID,
+          DtoField(
+              in_create_request=False, in_update_request=False, default_factory_for_create=uuid4
+          ),
+      ]
+      key: Annotated[str, DtoField(in_read_response=False)]
+      description: Annotated[str | None, DtoField(default_for_create=None)]
+      created_at: Annotated[
+          datetime,
+          DtoField(
+              in_create_request=False, in_update_request=False, default_factory_for_create=utc_now
+          ),
+      ]
+      updated_at: Annotated[
+          datetime,
+          DtoField(
+              in_create_request=False,
+              in_update_request=False,
+              default_factory_for_create=utc_now,
+              default_factory_for_update=utc_now,
+          ),
+      ]
+  ```
+
+  `DtoField` carries **operation-scoped** defaults (`default_for_create` /
+  `default_factory_for_create` and `default_for_update` /
+  `default_factory_for_update`), whose precedence is *client value → default
+  for that operation → `MISSING`*. Create and update do not want the same
+  default: an omitted update field with no update default is *left unchanged*
+  (PATCH semantics), while an `in_update_request=False` field is always omitted
+  and so always takes its update default (the "always overwrite" case — how
+  `updated_at` is re-set on every update while `created_at` is written once).
+  Optionality is never inferred from the annotation: a nullable field with no
+  create default is required on create. `DTO.__init_subclass__` applies the
+  `id` / timestamp conventions and wraps every field as `ann | Missing`
+  defaulting to `MISSING`, so an omitted field is distinguishable from an
+  explicit `None`. The create request carries concrete defaults; the update
+  request keeps the `MISSING` sentinel on the wire boundary so an omitted field
+  is distinguishable from an explicit `null`, and the route converts a request
+  into a DTO through the single sanctioned hop (`request_to_dto`, i.e.
+  `model_dump(exclude_unset=True)` + `model_validate`).
+  `Missing` is a usable annotation type (it carries a Pydantic core schema and
+  serializes to `null`), so `UUID | Missing` validates. The six REST models are
+  field-selection projections of the DTO — never hand-written — and the
+  one-time-reveal case (`key` in the create response only) is expressible.
+  Both `DTO` and `DtoField` carry a free-form `metadata: dict[str, Any]`, a
+  general-purpose store for extra data that `core` never reads. A DTO's
+  metadata is inherited and merged down the MRO and is not a field; a
+  `DtoField`'s metadata is per-field and excluded from equality/hash, so
+  differing metadata never churns the derived models.
+  `DTO.id_field_name` selects the identifier — `id` by default, overridable
+  with the `id_field_name=` class keyword to make another declared field the
+  identifier (a natural key). It is validated at declaration time: a name with
+  no matching field raises `TypeError`. The identifier is always immutable
+  (never in an update request); the conventional `id` is also server-generated
+  in the SQL backend and so excluded from create requests, while a custom
+  identifier stays client-supplied on create, e.g.
+  `class Country(DTO, id_field_name="code")` with a `code: str` field.
+
+* **`resource.py`** — `Resource` is a genuine ABC: every method is abstract, so
+  `core` holds no backend behaviour and a backend supplies the whole contract.
+  It is generic over the DTO and the identifier type (`Resource[T, K]`).
+  `get_service(ctx)` is **async** and takes an optional call-scoped
+  `MutableMapping`; awaiting it builds the service (a backend may resolve a
+  connection first) and the returned `Service` is the async context manager that
+  owns the storage, so the call site is
+  `async with await resource.get_service(ctx)`. `get_supported_actions()` is the
+  single action declaration (there is no `actions` property), and
+  `get_exposed_resource()` composes on top of it — the exposed resource's
+  declaration wins outright.
+* **`service.py`** — `Service` is generic over the DTO, declares the eight
+  actions, and *is* the async context manager; a call before `__aenter__`
+  raises clearly. `Action` is the action enum, `Edit` the
+  create/update/delete union, and `ForbiddenError` / `NotFoundError` /
+  `ServiceError` live here.
+* **`errors.py`** — the framework error base `ResourceyError` and the
+  storage-neutral errors a backend raises and the transport maps:
+  `ResourceyConfigError`, `InvalidInputError`, `UnsupportedFilterError`,
+  `ConflictError`.
+* **`manifest.py`** — the `Manifest` owns the resource set and its lifecycle
+  (it may also own app-lifecycle managers, e.g. a `SqlSessionManager`, entered
+  before the resources and exited after them),
+  and asserts at construction that every resource's supported actions name only
+  real `Action` members (a typo would otherwise silently drop a route).
+
+Storage ownership follows one rule, letting session-per-service and
+session-per-operation both live:
+
+> Whoever opens the storage owns its commit and close. A resource that finds
+> storage already in `ctx` reuses it and neither commits nor closes it.
+
+`ctx` is a plain `MutableMapping` keyed by module-level sentinels, so a caller
+can pre-seed storage (the escape hatch) and every resource in the call adopts
+it. `AppContext` (app-scoped) stays a separate concept. HTTP construction
+(`create_app`) is deliberately **not** part of `core` — it belongs to the
+transport layer, where the per-request service dependency is built through a
+configurable `DependencyBuilder` (its default, `OpenDependencyBuilder`, opens
+the resource's own service over the request-scoped `ctx` and applies no
+authentication). `util` is the bottom layer: an isolation test pins the layer
+ranks `util < core < {sql, mongo, list, view, filestore, http, config, cache,
+encryption, auth, jobs, tasks, triggers, realtime}`, so no module imports a
+higher layer at runtime.
+
+### Configuration — env-driven edges
+
+`core` stays config-free (a service is built from the objects it is handed),
+while each env-driven *edge* is a `BaseConfig` block living with what it
+configures: `SqlConfig` in `sql/`, `EncryptionKeysConfig` in `encryption/`,
+`FileStoreConfig` in `filestore/`, `RealtimeConfig` in `realtime/`,
+`ApiKeysConfig` / `IdpConfig` / `SessionCookieConfig` in `auth/`,
+`BackgroundTasksConfig` in `tasks/`, `JobsConfig` in `jobs/`. All read the one
+process-wide prefix, `APP` by default, so connection `n` is
+`APP_SQL_CONNECTIONS_<n>_NAME` / `_URL` / `_PASSWORD` and the key is
+`APP_ENCRYPTION_KEY_ID` / `_VALUE` (plus `APP_DECRYPTION_KEYS_<n>_*` for
+rotation). An absent encryption key degrades to a loud dev default
+(`changeme` plus a warning); a partially specified one is a hard
+`ResourceyConfigError`.
+
+An app composes the blocks by inheritance and calls the composed config once at
+its entry point:
+
+```python
+from resourcey.encryption.encryption_config import EncryptionKeysConfig
+from resourcey.sql.sql_config import SqlConfig
+
+
+class AppConfig(SqlConfig, EncryptionKeysConfig):
+    """The app's single config object, composed from the framework blocks."""
+
+
+config = AppConfig.get_instance()  # reads APP_* from os.environ
+print(config.generate_env_template())  # a commented .env skeleton, secrets redacted
+```
+
+`get_instance()` caches **per class**, so `AppConfig.get_instance()` and
+`SqlConfig.get_instance()` are distinct instances whose values agree (both read
+the same env namespace). Framework internals resolve their own block;
+`SqlResource` uses `get_encryption_service()` / `get_sql_session_manager()` by
+default and accepts an explicit `encryption_service=` / `session_factory=` to
+override. The framework does no `.env` loading — use `uvicorn --env-file` or a
+wrapper script to populate the environment. A pluggable medium or channel is
+chosen by name with a `LazyField` (`APP_MEDIUM_CLASS`, `APP_CHANNEL_CLASS`), so
+swapping the implementation needs no code change.
+
+## Stack
+
+| Concern | Tool |
+|---|---|
+| HTTP | FastAPI |
+| Validation | Pydantic v2 |
+| ORM | SQLAlchemy 2 (async) |
+| Migrations | Alembic |
+| Package management | uv |
+| Formal specs | Quint |
+| Tests | pytest (≥90% coverage enforced) |
+
+## Authorization (users, groups, roles)
+
+`resourcey.auth` secures a resource through two composable seams: an
+`Authenticator` (API-key, cookie, and OAuth / OIDC authenticators) that produces
+a `Principal`, and a `PolicyResolver` that maps that principal to `Policy` rules.
+The built-ins are `AllowAll` / `DenyAll` / `ReadOnly` / `Owner`, with a
+per-app role vocabulary (`RolePolicyResolver`) and a store-backed RBAC resolver
+(`RbacPolicyResolver`) over `users` / `groups` / `roles` / `role_permissions` /
+`resource_acls` tables. An `AuthorizedService` enforces the reduced filter per
+action: a denied create is `403`, an out-of-scope read/update/delete is `404`,
+and a denied search/count yields an empty page / `0`.
+
+### Who am I — the `me` endpoint
+
+`register_me_routes(app, authenticator=..., user_resource=...)` (issue #150)
+mounts `GET` / `POST /me` **after** `create_app`, reading the same `Authenticator`
+the app's builder uses, so it works uniformly across the API-key, cookie, and
+OAuth methods. The response is an [OIDC UserInfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
+object: `sub` (the caller's internal principal id — always present), plus the
+framework's `kind` / `roles` / `scopes` and, for an external-IdP caller,
+`external_id`. When a `user_resource` is supplied, the caller's **own** row adds
+profile claims (`email`, `preferred_username`, …); an unavailable claim is
+omitted, never `null`. The route reads that row directly (not through the
+`users` policy) and can only ever return the id the credential already proved, so
+an admin-only `users` surface does not block a caller from seeing its own `me`.
+It is guarded by the **strict** principal dependency: an absent or invalid
+credential is a `401` regardless of the builder's posture. See
+[`examples/04_simple_roles`](https://github.com/tofarr/resourcey/tree/main/examples/04_simple_roles) / [`07_oauth`](https://github.com/tofarr/resourcey/tree/main/examples/07_oauth).
+
+### OAuth / OIDC (external identity providers)
+
+The OAuth method (issue #151) federates to an external IdP. `OAuthAuthenticator`
+verifies an `Authorization: Bearer` token — issuer-keyed client lookup, JWKS
+signature check, and `alg` pinned to the client row's allowlist (no algorithm
+confusion) — maps `(iss, sub)` through an `ExternalIdentity` table to a local
+user, and validates that user against the local store (a missing / disabled user
+is rejected: the local store stays authoritative over the IdP). Provider
+configuration and tokens are **resources**, so they live in the environment
+(`APP_OAUTH_CLIENTS_<n>_*`) or the database; the refresh token lives only,
+encrypted at rest, in an `oauth_tokens` table, and refresh is serialized across
+processes with a lease / compare-and-swap column. `configure_oauth(...)` wires
+the whole subsystem in one call and `register_oauth_routes` mounts the
+interactive login / callback / refresh flow (BFF session, PKCE). See
+[`examples/07_oauth`](https://github.com/tofarr/resourcey/tree/main/examples/07_oauth).
+
+## Configuration
+
+A typed environment-variable parser is bundled in `resourcey.util.env_parser`
+(vendored from the
+[OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk/blob/28e8ed273617992e9556410804f54937cc059878/openhands-agent-server/openhands/agent_server/env_parser.py),
+written by the same author). It supports complex nested types and polymorphism
+that `pydantic-settings` cannot express. There is **no runtime dependency** on
+the SDK.
+
+A `DiscriminatedUnionMixin` is also bundled in `resourcey.util.models` for
+polymorphic models keyed by a `kind` discriminator — likewise vendored from
+the SDK with no dependency.
+
+## Migrations
+
+Database revisions are generated with [Alembic](https://alembic.sqlalchemy.org/)
+from the current resource models. There is no `resourcey migrate` wrapper:
+SQLAlchemy is the schema of record, so Alembic is driven directly against
+`Base.metadata` (see the examples' `migrations/` directories):
+
+```bash
+alembic revision --autogenerate -m "add widget table"
+alembic upgrade head                # apply
+alembic downgrade -1                # one step back
+```
+
+**Generated revisions are drafts.** Alembic's autogeneration cannot detect
+table or column *renames* — a rename looks like a drop followed by a create,
+which loses data. Review every generated revision before applying it.
+
+## Status
+
+Early-stage. The roadmap is tracked in
+[GitHub issues](https://github.com/tofarr/resourcey/issues). See `AGENTS.md`
+for contributor rules and `specs/` for the formal Quint specifications.
+
+## License
+
+MIT