# Domain Glossary

Domain terms used throughout the ows-coda documentation. For technical architecture terms, see individual architecture docs.

## Music Industry / Royalties

- **Account** -- a payee entity in the Abacus platform (label, distributor, publisher). Accounts own contracts and receive royalty payments.
- **Contract** -- agreement between an account and the platform governing royalty terms, including rates, territory exclusions, and advance recoupment schedules.
- **Advance** -- upfront payment to an account, recouped from future royalties before the account receives net payments.
- **Statement period** -- a time window for royalty accounting (e.g., quarterly). Revenue earned during a statement period is aggregated and reported to the account.
- **Accounting period** -- internal period for financial processing, distinct from statement periods. Used by the platform to organize ledger entries and reconciliation.
- **Payee** -- the entity receiving payments. Each account has payee information including payment method and banking details.
- **Run controller** -- automated process that manages royalty computation runs for a contract, tracking pipeline state and completion.
- **Subaccount** -- child account under a parent account (e.g., regional divisions). Revenue can be broken down by subaccount for reporting.
- **Paythrough/flowthrough** -- revenue that passes through adjustments rather than the standard royalty computation pipeline.
- **UPC** -- Universal Product Code, a barcode identifying a release or album. Used to look up products across the platform.
- **ISRC** -- International Standard Recording Code, a unique identifier for a specific sound recording. Used to find products containing a particular track.
- **DSP** -- Digital Service Provider (e.g., Spotify, Apple Music). Revenue is reported and broken down by DSP in the platform.

## Financial

- **Ledger** -- the authoritative record of all financial transactions for an account. Tracks balances, adjustments, and payment history.
- **Adjustment** -- a correction or modification to ledger entries, such as revenue corrections or manual credits. Adjustments go through a validation and approval pipeline.
- **Reserve release** -- releasing held funds back to the payee. Reserves are amounts withheld from payment and later released on a schedule.
- **Payment hold** -- temporarily blocking payments to an account. Holds include a reason, start date, and creator for audit purposes.
- **Balance** -- current financial position of an account, including receivable and payable amounts broken down by contract.

## Platform

- **Tenant** -- an isolated organizational unit in the multi-tenant platform. Each tenant has its own users, data, and access policies.
- **Identity** -- a user's unique identifier, sourced from ows-grass/Auth0. Stored as an HMAC-SHA256 hash for lookup and AES-256-GCM encrypted for reversibility.
- **ows-grass** -- the API gateway that sits in front of ows-coda. It handles JWT verification, injects identity headers (`orchard-identity-id`, `orchard-user-name`), and proxies requests to backend services.

## Technical

- **BM25** -- Best Matching 25, a keyword scoring formula that ranks documents by term frequency, inverse document frequency, and document length. The standard text-retrieval baseline used in the search service.
- **HNSW** -- Hierarchical Navigable Small World, a graph-based approximate nearest-neighbor index for vector search. Supports O(log n) lookups over dense embeddings.
- **RRF** -- Reciprocal Rank Fusion, a method for combining multiple ranked lists into one. Each document's score is the sum of `1/(k + rank)` across all lists it appears in.
- **Prompt cache** -- Bedrock feature that caches the system prompt and tool definitions across requests, reducing latency and cost. Seeded at server startup via a warm-up call.
- **Warm pool** -- pre-created V8 isolates in the sandbox engine, ready to serve code execution requests without the ~10-50ms creation overhead.
- **ConnectRPC** -- RPC framework used for internal service communication (search, platform, runner). Supports both JSON and binary protobuf over standard HTTP/1.1.
- **Skill** -- a high-level aggregation tool that composes multiple domain handler calls into a single result, reducing LLM round trips for broad questions.