ff-639 entitlement tokens consumption - #529
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR expands the entitlement/token system by introducing a generic ffun.resources accounting contract, updating entitlement semantics (including lifetime tokens and transaction IDs), and refactoring dispatch/queue flows to support per-entry token consumption and improved processing bookkeeping.
Changes:
- Introduce a Resources module specification + backend resource reservation/conversion primitives (used/reserved counters, ordered reservation, usage aggregation).
- Revise Entitlements to be transaction-identified grants + explicit revocations, add
lifetime_tokens, and update CLI/specs accordingly. - Refactor queue and dispatcher flows (typed secondary IDs, new dispatching status table/cache, configurable dispatcher batch size + concurrency).
Reviewed changes
Copilot reviewed 92 out of 94 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| workflows/polish.donna.md | Reorders polish workflow steps. |
| workflows/inconsistency-check.donna.md | Clarifies inconsistency-check workflow guidance. |
| specs/meta/general.md | Adds spec prose formatting + edit guidance. |
| specs/meta/backend_modules.md | Tightens module spec abstraction boundary rules. |
| specs/intro.md | Links new resources module spec. |
| specs/dictionary.md | Defines dictionary-term stability requirements. |
| specs/behavior/cli/entitlements.md | Updates entitlement CLI contract (transaction id, lifetime). |
| specs/backend_architecture/python.md | Defines validation vs resolution rules. |
| specs/backend_architecture/modules/resources.md | New resources module contract/spec. |
| specs/backend_architecture/modules/audit.md | Refines audit module to public-contract focus. |
| specs/backend_architecture/modules_layout.md | Clarifies ffun.product ownership + resource kind ids. |
| specs/backend_architecture/db.md | Adds rule prohibiting undocumented cross-module transactions. |
| ffun/tach.toml | Updates module dependency graph (queues/resources/etc). |
| ffun/pyproject.toml | Registers local pytest plugin via addopts. |
| ffun/ffun/resources/operations.py | Implements bulk init/reserve/convert operations. |
| ffun/ffun/resources/errors.py | Adds resources error types. |
| ffun/ffun/resources/entities.py | Adds reservation option/spec/result entities. |
| ffun/ffun/resources/domain.py | Adds ordered reservation domain API. |
| ffun/ffun/queues/tests/test_operations.py | Updates tests for new queue push API/secondary ids. |
| ffun/ffun/queues/tests/test_domain.py | Updates domain tests for new queue push API. |
| ffun/ffun/queues/tests/helpers.py | Updates queue test helpers for secondary ids. |
| ffun/ffun/queues/operations.py | Refactors push/pull types; typed secondary ids. |
| ffun/ffun/queues/entities.py | Introduces QueueSecondaryId and QueueItemToPush. |
| ffun/ffun/pytest_plugin.py | Adds --detect-async-leaks pytest option. |
| ffun/ffun/product/entities.py | Adds product resource kind enums for token usage. |
| ffun/ffun/meta/tests/test_domain.py | Updates dispatcher status-setting API usage in tests. |
| ffun/ffun/meta/domain.py | Removes entry dispatching statuses during cleanup. |
| ffun/ffun/markers/tests/test_operations.py | Updates marker API tests for batch set. |
| ffun/ffun/markers/operations.py | Refactors marker setting to batch insert. |
| ffun/ffun/loader/tests/test_domain.py | Updates loader tests to push via queues. |
| ffun/ffun/loader/domain.py | Switches entry enqueueing to queues domain. |
| ffun/ffun/llms_framework/tests/test_keys_rotator.py | Updates tests to new resources reservation/conversion API. |
| ffun/ffun/llms_framework/tests/test_domain.py | Updates tests to new resources reservation API helper. |
| ffun/ffun/llms_framework/tests/helpers.py | New helper to reserve resources in tests. |
| ffun/ffun/llms_framework/tests/fixtures.py | Updates fixtures to use ordered reservation API. |
| ffun/ffun/llms_framework/keys_rotator.py | Uses ordered resource reservation; updates conversion call. |
| ffun/ffun/librarian/tests/test_background_processors.py | Updates queue interactions and subqueue typing. |
| ffun/ffun/librarian/processors/tests/test_llm_general.py | Adjusts route behavior and collection/user key expectations. |
| ffun/ffun/librarian/processors/llm_general.py | Adds collection-aware key selection (temporary). |
| ffun/ffun/librarian/domain.py | Updates dispatcher status update API usage. |
| ffun/ffun/librarian/background_processors.py | Switches dispatcher queues to queues domain. |
| ffun/ffun/feeds_collections/tests/helpers.py | Adds helper for collection-feed test setup. |
| ffun/ffun/entitlements/tests/test_entities.py | Updates entitlement entity invariants/tests (lifetime, ids). |
| ffun/ffun/entitlements/tests/make.py | Updates entitlement test factory for new fields. |
| ffun/ffun/entitlements/tests/helpers.py | Updates helpers for transaction-id keyed rows. |
| ffun/ffun/entitlements/operations.py | Splits insert vs revoke; adds transaction id + revoked_at. |
| ffun/ffun/entitlements/migrations/20260717_01_c0DeX-entitlements.py | Alters entitlements table schema for transaction grants. |
| ffun/ffun/entitlements/errors.py | Adds conflict/not-found entitlement errors. |
| ffun/ffun/entitlements/entities.py | Adds NonEmpty IDs, lifetime kind, revocation semantics. |
| ffun/ffun/entitlements/domain.py | Refactors grant/revoke flows; rebuild effective timeline w/ revocation. |
| ffun/ffun/domain/tests/test_datetime_intervals.py | Adds lifetime markers + day/month interval tests. |
| ffun/ffun/domain/entities.py | Makes SerializedId a non-empty string type. |
| ffun/ffun/domain/datetime_intervals.py | Adds lifetime markers + day_interval_start. |
| ffun/ffun/dispatcher/tests/test_entries_cache.py | New tests for dispatcher entries cache behavior. |
| ffun/ffun/dispatcher/tests/test_entities.py | New tests for EntryAuthorization semantics. |
| ffun/ffun/dispatcher/tests/test_background_dispatcher.py | Updates to dispatcher batch size + concurrency settings. |
| ffun/ffun/dispatcher/tests/make.py | Updates dispatch info to typed subqueue id. |
| ffun/ffun/dispatcher/settings.py | Renames chunk -> batch size; adds concurrency. |
| ffun/ffun/dispatcher/operations.py | Adds dispatching status CRUD; batches processing status updates. |
| ffun/ffun/dispatcher/migrations/20260728_01_c0DeX-entry-dispatching-status.py | Adds dispatching-status table. |
| ffun/ffun/dispatcher/errors.py | Adds dispatcher-level error types. |
| ffun/ffun/dispatcher/entries_cache.py | New cache to bulk-load authorization inputs. |
| ffun/ffun/dispatcher/entities.py | Adds status update entity + authorization model. |
| ffun/ffun/dispatcher/background_dispatcher.py | Passes batch size + concurrency into dispatch loop. |
| ffun/ffun/core/utils.py | Adds has_timezone() helper. |
| ffun/ffun/core/tests/test_utils.py | Tests timezone detection helper. |
| ffun/ffun/core/tests/test_logging.py | Adds tests for measure_block_time decorator. |
| ffun/ffun/core/tests/test_entities.py | Tests NonEmptyString behavior. |
| ffun/ffun/core/tests/test_concurrency.py | Tests ConcurrentMapper. |
| ffun/ffun/core/logging.py | Adds measure_block_time decorator helper. |
| ffun/ffun/core/errors.py | Adds concurrency-related core errors. |
| ffun/ffun/core/entities.py | Introduces NonEmptyString pydantic-compatible type. |
| ffun/ffun/core/concurrency.py | Adds ConcurrentMapper utility. |
| ffun/ffun/conftest.py | Gates leak detection fixture behind CLI option. |
| ffun/ffun/cli/commands/tests/test_queues.py | Updates tests for typed secondary queue id. |
| ffun/ffun/cli/commands/tests/test_entitlements.py | Updates tests for new grant/revoke commands + lifetime. |
| ffun/ffun/cli/commands/queues.py | Converts subqueue to QueueSecondaryId. |
| ffun/ffun/cli/commands/entitlements.py | Reworks CLI around grant/revoke with transaction ids. |
| ffun/ffun/api/spa/http_handlers.py | Updates set-marker call to batch API. |
| ffun/ffun/api/spa/entities.py | Adds new resource kind strings. |
| consistency.toml | Updates inconsistency-check config schema (validator/reviewer roles). |
| changes/unreleased.md | Documents new env vars + token spending behavior. |
| bin/backend-tests.sh | Allows passing args through to pytest. |
| AGENTS.md | Updates agent tool/workflow guidance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+59
to
+63
| kind: int, | ||
| interval_started_at: datetime.datetime, | ||
| amount: int, | ||
| ) -> list[ResourceReservation]: | ||
| if not user_limits: |
Comment on lines
+87
to
+93
| # Temporary solution until collection access handling moves fully to the dispatcher. | ||
| entries_in_collections = await d_domain.entries_in_collections([entry.id]) | ||
| entry_is_from_collection = entry.id in entries_in_collections | ||
|
|
||
| if entry_is_from_collection: | ||
| assert route.api_key is not None | ||
|
|
Comment on lines
+47
to
+56
| async def try_to_reserve_in_order( # noqa: CCR001 | ||
| *, | ||
| amount: int, | ||
| options: Sequence[ResourceReservationOption], | ||
| specifications: Sequence[ResourceReservationSpecification], | ||
| ) -> list[ResourceReservation]: | ||
| for specification in specifications: | ||
| if len(specification.limits) != len(options): | ||
| raise errors.ReservationOptionsAndLimitsMismatch() | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.