Single partition key: All override docs in one logical partition for admin queries
Deterministic IDs: Enable point-reads (fastest Cosmos operation) at each cascade level
Resolution Algorithm
Define an ordered list of scopes from most-specific to least-specific
For each level, attempt a point-read by composite ID
First match wins — no merging, no inheritance between levels
Final fallback = existing global default (backward-compatible)
Key Principles
No merging: A match at level N completely determines the result. Don't partially inherit from level N+1.
Backward-compatible: If the scoping context is absent (e.g., query params not passed), the resolver skips all levels and falls through to the existing global behavior.
Cacheable: Deterministic ID → Redis/in-memory cache by exact key, 30s TTL.
Auditable: Store sourceProfileId in resolution result so logs show which override was used.
Cosmos Implementation
public interface IScopedOverrideResolver<TResult>
{
Task<TResult?> ResolveAsync(params string[] scopeValues);
}
Resolution attempts point-reads in order:
{prefix}:{entity}:{scope1}:{scope2} → most specific
{prefix}:{entity}:{scope1}:_all → scope1 only
{prefix}:{entity}:_global:_all → entity-wide default
null → fall through to legacy
Anti-Patterns
❌ Merging fields from multiple levels (complex, hard to debug)
❌ Regex or glob matching in scope values (unpredictable, uncacheable)
❌ Implicit defaults (always require explicit creation of override docs)
❌ Dynamic evaluation order (levels are fixed at design time)
Examples in This Codebase
AccessProfile (access-profile partition): resolves Plan+Routing per (client, api, operation)
cosmos-repository-pattern — base repository class used for storage
additive-feature-extension — how to add features without breaking existing behavior
1---2name: scoped-override-cascade3description: Scoped Override Cascade4---5# Scoped Override Cascade67**Confidence:** medium 8**Validated:** AAA Access Profile architecture independently reviewed and approved by Zack (2026-05-21)910## When to Use1112When adding **per-scope overrides** on top of a **global default** setting. Examples:13- Per-client-per-endpoint Plan/Routing overrides (Access Profiles)14- Per-API pricing overrides on top of global pricing15- Per-operation DLP policy overrides on top of API-level settings1617## Pattern1819### Data Model20- **Composite ID:** `{prefix}:{entity}:{scope1}:{scope2}:{scopeN|_all}`21- **Single partition key:** All override docs in one logical partition for admin queries22- **Deterministic IDs:** Enable point-reads (fastest Cosmos operation) at each cascade level2324### Resolution Algorithm251. Define an ordered list of scopes from most-specific to least-specific262. For each level, attempt a point-read by composite ID273. **First match wins** — no merging, no inheritance between levels284. Final fallback = existing global default (backward-compatible)2930### Key Principles31- **No merging:** A match at level N completely determines the result. Don't partially inherit from level N+1.32- **Backward-compatible:** If the scoping context is absent (e.g., query params not passed), the resolver skips all levels and falls through to the existing global behavior.33- **Cacheable:** Deterministic ID → Redis/in-memory cache by exact key, 30s TTL.34- **Auditable:** Store `sourceProfileId` in resolution result so logs show which override was used.3536### Cosmos Implementation3738```csharp39public interface IScopedOverrideResolver<TResult>40{41 Task<TResult?> ResolveAsync(params string[] scopeValues);42}43```4445Resolution attempts point-reads in order:46```47{prefix}:{entity}:{scope1}:{scope2} → most specific48{prefix}:{entity}:{scope1}:_all → scope1 only49{prefix}:{entity}:_global:_all → entity-wide default50null → fall through to legacy51```5253### Anti-Patterns54- ❌ Merging fields from multiple levels (complex, hard to debug)55- ❌ Regex or glob matching in scope values (unpredictable, uncacheable)56- ❌ Implicit defaults (always require explicit creation of override docs)57- ❌ Dynamic evaluation order (levels are fixed at design time)5859## Examples in This Codebase6061- `AccessProfile` (access-profile partition): resolves Plan+Routing per `(client, api, operation)`62- Future: per-API pricing tiers, per-operation content policies6364## Related Skills6566- `cosmos-repository-pattern` — base repository class used for storage67- `additive-feature-extension` — how to add features without breaking existing behavior
Run npx skillmds@latest add azure-samples/scoped-override-cascade in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Scoped Override Cascade It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Azure-Samples (@azure-samples) published this skill. Their other Agent Skills are listed on their SkillMD profile.
Azure-Samples