# Resource Registry — API Query Parameters Reference

This section documents each query parameter in isolation: what it does, its default value, and how it behaves differently per role.

## Parameter Value Handling

Every query parameter follows the same four rules:

1. **Malformed or unknown value → `400 Bad Request`.** A value of the wrong type (e.g., `limit=abc`, `hierarchical=yes`), outside the accepted enumeration (e.g., `metadataPolicy=full`), or outside the documented domain (e.g., `depth=-5`, `offset=-1`, `limit=0`) is a client error. The server never replaces it with a default. Boolean parameters accept only `true` and `false`, case-insensitively; enumerated values follow the lowerCamelCase convention (see [Naming Conventions](12-is-architectural-decisions.html#naming-conventions)).
2. **Valid value not applicable to the operation, or overridden by another directive** (e.g., a `Prefer: return=minimal` header or an `_emit` projection) → ignored, with an `X-Warning` of the `ignored-query-parameters` family. An unknown parameter name is ignored the same way.
3. **Valid value beyond a server bound** (`limit` above the maximum, or `limit=-1`) → clamped, with an `X-Warning` of the `modified-query-parameters` family.
4. **Privilege-expanding value without the required role** → `403 Forbidden`; it is never ignored or narrowed (see [REST API Design Principles](07-api-foundations-and-roles.html#rest-api-design-principles)).

The rules are evaluated in this order: authorization first (rule 4), then value validity (rule 1), then applicability (rules 2 and 3). A privilege-expanding value is therefore rejected with `403 Forbidden` even when another directive would have ignored it (e.g., `membershipScope=global` together with `Prefer: return=minimal`, `_emit`, or `rawResult=true`); for an authorized role the same combination is ignored with `X-Warning`.

The sections below state, for each parameter, its accepted values; every other value falls under rule 1.

## Pagination Parameters

## `limit` and `offset`

**Purpose:** Pagination for list endpoints.

| Parameter | Type | Default |
|-----------|------|---------|
| `limit` | integer | 10 |
| `offset` | integer | 0 |

| Role | `limit` | `offset` |
|------|:-------:|:--------:|
| IS-M / Infra-M | ✅ | ✅ |
| IS-Admin | ✅ | ✅ |
| Ctx-M | ✅ | ✅ |
| IS-Editor | ✅ | ✅ |
| IS-Contrib | ✅ | ✅ |
| IS-Member | ✅ | ✅ |

**Applicable endpoints:**

- **List Contexts:** `GET /contexts`
- **Execute Context JSON Query:** `QUERY /contexts`
- **Execute Type JSON Query:** `QUERY /types`
- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances`
- **List Query Templates:** `GET /query-templates`
- **Execute Query Template JSON Query:** `QUERY /query-templates`
- **Execute Query Template:** `QUERY /query-templates/{name}`
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
*Note on maximum limit:* To prevent out-of-memory errors and Denial-of-Service attacks (especially on the public `/access` facade), the server enforces a hard maximum bound for the `limit` parameter of `50`. Passing `-1` explicitly requests "give me the maximum allowed by the server". This is a deliberate architectural affordance: it decouples client applications from the server's hardcoded threshold. If the server administrator later reduces the limit to `20` to mitigate load, clients passing `-1` will seamlessly continue to operate (receiving chunks of 20) without needing code updates. Passing `-1` or any integer exceeding the threshold will automatically be clamped to the system maximum, and the server will emit an `X-Warning` header to inform the client of the clamping (e.g., `199 resource-registry "modified-query-parameters=limit; requested-value=-1; applied-value=50; reason=Clamped to system maximum"`). Clients performing massive data exports must paginate.

**Normative pagination behavior (ordering, stability, and concurrent writes):**

- **Default order:** unless explicitly documented by a specific endpoint, result ordering is backend-defined.
- **No cross-request stability guarantee:** with `limit`/`offset`, when concurrent create/update/delete operations occur, page boundaries may shift between requests.
- **Duplicates and skips are possible:** clients may observe repeated or missing elements across subsequent pages under concurrent writes.
- **Operational recommendation:** for deterministic batch processing, clients should use a bounded/snapshot-like strategy (for example, constrain the dataset by stable filters and process in short windows) instead of assuming globally stable offset pagination over mutable collections.

## Behavioral Parameters

## `lifecycle`

**Purpose:** Select which Context lifecycle slice is visible when reading the Context collection.

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `lifecycle` | string | `live` | `live`, `deleted`, `all` |

| Role | Available | Effective values |
|------|:---------:|------------------|
| IS-M / Infra-M | ✅ | `live`, `deleted`, `all` |
| IS-Admin | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |
| Ctx-M | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |
| IS-Editor | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |
| IS-Contrib | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |
| IS-Member | ✅ | `live` *(requests for `deleted`/`all` are rejected)* |

**Applicable endpoints:**

- **List Contexts:** `GET /contexts`
- **Execute Context JSON Query:** `QUERY /contexts`
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**

- `live` (default): returns only non-cemetery contexts.
- `deleted`: returns only cemetery contexts (`state=deleted`).
- `all`: returns the union of live + cemetery contexts.
- The parameter affects only collection reads. Single-context reads by UUID (`GET /contexts/{context-uuid}`) and token-bound reads (`GET /contexts/@current`) keep their dedicated authorization and lookup semantics.

> ⚠️ **Authorization Gate:** Values `deleted` and `all` are restricted to `IS-M / Infra-M`. For all other roles, the server rejects the request with `403 Forbidden`.

## `polymorphic`

**Purpose:** Control whether subtypes are included alongside the explicitly requested type.

| Parameter | Type | Default |
|-----------|------|---------|
| `polymorphic` | boolean | `true` |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin | ✅ |
| Ctx-M | ✅ |
| IS-Editor | ✅ |
| IS-Contrib | ✅ |
| IS-Member | ✅ |

**Applicable endpoints:**

- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances`
- **Execute Query Template:** `QUERY /query-templates/{name}`
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
No role-based behavioral differences. Available uniformly to all callers.

> ⚠️ **Strict Type Filtering Warning:** Because the default value is `true`, queries will inherently return instances of the requested type *and all its subtypes*. Clients (especially strongly-typed parsers) that expect a rigid return structure and cannot handle unknown derived types **must explicitly pass `polymorphic=false`** to enforce strict type filtering and prevent deserialization errors.

## `depth`

**Purpose:** Control how much of the Type/Context hierarchy is considered by the operation — the depth of the retrieved tree when reading a single element (Context or Type), or the breadth of Type-name matching when querying the Types collection.

| Parameter | Type | Default |
|-----------|------|---------|
| `depth` | integer | `0` on Read endpoints; `-1` on `QUERY /types` (see note below) |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin | ✅ |
| Ctx-M | ✅ |
| IS-Editor | ✅ |
| IS-Contrib | ✅ |
| IS-Member | ✅ |

**Applicable endpoints:**

- **Read Context:** `GET /contexts/{context-uuid}`
- **Read Current Context:** `GET /contexts/@current`
- **Read Type:** `GET /types/{type-name}`
- **Execute Type JSON Query:** `QUERY /types` *(different consumption than the Read endpoints above — see the Type-Definition Query note below; different default — see Contrasting Defaults note below)*
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
No role-based behavioral differences. Available uniformly to all callers.

*Depth values (Read endpoints — `GET /contexts/{uuid}`, `GET /contexts/@current`, `GET /types/{type-name}`):*

- The response is always a flat array with the requested element first, followed by the included descendants level by level (see [Read shape and `depth`](08-api-contexts-and-types.html#operational-notes) for Contexts).
- `0` (default): only the requested element. *(Note: The baseline JSON representation of a Context inherently includes depth-limited summaries of its `parent` and `children` to allow graph navigation. `depth=0` ensures these remain as strictly minimal summaries without triggering recursive expansion).*
- positive integer `N`: the element and N levels of its descendants (if `N` exceeds the available descendant depth, the response is naturally bounded by existing data and no warning is emitted).
- `-1`: the element and all descendants recursively.
- Any other negative value is invalid and returns `400 Bad Request`.

*Depth values (`QUERY /types`):*

- `-1` (default): descendant closure is unbounded — a name match (the query's own `name`, or a Relation Type's `source`/`target` name) also matches any registered descendant of that name.
- positive integer `N`: the match expands to descendants up to N levels down.
- `0`: restricts the match to the exact literal name only (no polymorphic expansion).
- Any other negative value is invalid and returns `400 Bad Request`.

> **Contrasting defaults between Read and Query, by design:** `GET /types/{type-name}` defaults to `depth=0` because it is an identity fetch — asking for `Service` must return exactly `Service`, not a surprise blend of its subtypes. `QUERY /types` defaults to `depth=-1` because it is a search/filter operation, and every other `QUERY` endpoint in this API defaults to inclusive, polymorphic-equivalent matching (`polymorphic=true` on Instance queries and Query Template execution). The behavioral analogy that matters is Query-to-Query across collections (Types Query should feel like Instances Query), not Read-to-Query within the Types collection — reusing the same parameter *name* for both roles does not obligate reusing the same default *value*. Clients that need strict, non-polymorphic name matching on `QUERY /types` must explicitly pass `depth=0`.

> **Type-Definition Query Semantics (`QUERY /types`):** Type-definition records (`ResourceSchema`, `FacetSchema`, `IsRelatedToSchema`, `ConsistsOfSchema`, `PropertySchema`) form a flat collection: each definition is distinguished only by its own `name` and `extendedTypes`. For this endpoint, `depth` does not shape a returned tree (there is no tree to return — the response is a flat filtered array); instead, it bounds the *Type-hierarchy walk* used to resolve an equality match against a Type **name** — the query's own `name` field, or the `source`/`target` name inside a Relation Type definition — into a match against that name *and its descendants up to `depth` levels* (same walk that powers `GET /types/{type-name}?depth=N`, just consumed differently: to build a name-membership match instead of to serialize a tree). The same `depth` value applies uniformly to every name-position match within the query (the root match and any nested `source`/`target` match alike) — there is no per-field override. See [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#depth-based-type-name-matching-type-definition-queries-only) for worked examples, including how this composes with other constraints in the same query (e.g. filtering by a declared property name).

## `hierarchical`

**Purpose:** Extend the scope of an operation to include child (and descendant) Contexts of the current Context, in addition to the current Context itself. The current Context is determined by the authorization token.

Every request on which `hierarchical=true` takes effect returns `X-Result-Scope: hierarchical`, whether or not a descendant contributed to the result (a request on which the parameter is ignored with `X-Warning` does not return the token): the token states that the result was computed over the subtree, so an empty or unchanged result means there was nothing more to find, not that the expansion did not happen.

| Parameter | Type | Default |
|-----------|------|---------|
| `hierarchical` | boolean | `false` |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | Token Context + all descendants |
| IS-Admin | ✅ | Token Context + all descendants |
| Ctx-M | ✅ | Token Context + all descendants |
| IS-Editor | ✅ | Token Context + all descendants. Note: hierarchical writes skip **non-`active`** descendant Contexts. |
| IS-Contrib | ✅ (Reads only) | Token Context + all descendants. On writes the parameter is privilege-expanding and returns `403 Forbidden`. |
| IS-Member | ✅ (Reads only) | Token Context + all descendants. Write operations forbidden. |

**Applicable endpoints:**

- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances`
- **Exists Instance:** `HEAD /instances/{type}/{instance-uuid}`
- **Read Instance:** `GET /instances/{type}/{instance-uuid}`
- **List Instance Contexts:** `GET /instances/{type}/{instance-uuid}/contexts`
- **Create Instance:** `POST /instances/{type}`
- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`
- **Execute Query Template:** `QUERY /query-templates/{name}`
- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` *(write use restricted to `IS-M`, `Infra-M`, and `IS-Admin`)*
- **Remove from Context:** `DELETE /instances/{type}/{instance-uuid}/contexts/{context-uuid}` *(write use restricted to `IS-M`, `Infra-M`, and `IS-Admin`)*
- **Execute Raw Query:** `QUERY /admin/raw-query`
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**

**Hierarchical Support Matrix by Operation Type:**

| Operation Category | Endpoints | Supported | Operational Effect |
|--------------------|-----------|:---------:|--------------------|
| **Read / Lookup** | `GET /instances/{type}`<br>`HEAD /instances/{type}/{instance-uuid}`<br>`GET /instances/{type}/{instance-uuid}`<br>`GET /instances/{type}/{instance-uuid}/contexts`<br>`GET /access/...` | ✅ | Expands visibility subtree. Retrieves instances that exist *anywhere* within the authorized descendant Contexts, except, for roles without the administrative state override, those only in non-`active` descendants. |
| **Search / Query** | `QUERY /instances`<br>`QUERY /query-templates/{name}`<br>`QUERY /access/query-templates/{name}` | ✅ | Expands search boundary to include all descendant Contexts. |
| **Write (Hierarchical Distribution)** | `PUT /instances/{type}/{instance-uuid}` (Create/Update)<br>`POST /instances/{type}` (Create) | ✅ | With `hierarchical=true`, applies the creation/update of a Resource to the current Context AND all descendant Contexts within the authorized subtree. Ignored with `X-Warning` for non-Resource instances (for roles allowed to use the parameter; any other role receives `403 Forbidden`). |
| **Membership Add** | `PUT /instances/{type}/{instance-uuid}/contexts/{new-context}` | ✅ | `IS-M`, `Infra-M`, and `IS-Admin` may atomically apply the source blueprint to the target Context and all descendants. Other roles receive `403 Forbidden` when requesting this write expansion. |
| **Membership Remove** | `DELETE /instances/{type}/{instance-uuid}/contexts/{context-uuid}` | ✅ | `IS-M`, `Infra-M`, and `IS-Admin` may atomically remove the instance from the named Context and all its descendants. Other roles receive `403 Forbidden` when requesting this write expansion. |
| **Membership Remove (current Context)** | `DELETE /instances/{type}/{instance-uuid}` | ❌ | Ignored (`X-Warning`) as not applicable, for roles allowed to use `hierarchical` on writes; any other role receives `403 Forbidden`. `Remove from Current Context` acts strictly on the token Context: hierarchical removal is `Remove from Context` with `hierarchical=true`. |
| **Raw Query** | `QUERY /admin/raw-query` | ✅ | Only for global admins (`IS-M / Infra-M`). Extends the underlying database session's visibility to the token Context's descendants. |

**Global Atomicity Guarantee for Mutations:** For all supported write operations (Create/Update, Add to Context, Remove from Context) where `hierarchical=true` modifies state across multiple Contexts, the entire distribution is executed as a single, atomic database transaction. If the payload violates a schema constraint or encounters a conflict in even one descendant Context, the entire global transaction fails and is rolled back entirely (no partial commits).

**Note for `HEAD` requests (`HEAD /instances/{type}/{instance-uuid}`):** Using `hierarchical=true` on a `HEAD` request will return `200 OK` if the instance exists *anywhere* in the requested subtree (for roles without the administrative state override, in an `active` part of it; see the lookup matrix below). Because `HEAD` requests do not return a body, this will not tell you *which* specific Context the instance is in; it only serves as a fast binary check ("does it exist in my tree?"). If you need to know exactly which Contexts the instance belongs to, you must use a `GET` read request with `contextsPolicy=root` or `contextsPolicy=all`.

To disambiguate existence and visibility without violating HTTP status code semantics, clients should rely on the following deterministic behavior matrix for instance lookups (evaluating the composite key `(type, instance-uuid)` on both `HEAD` and `GET`):

| Instance Location | Call *without* `hierarchical` | Call *with* `hierarchical=true` |
|-------------------|-------------------------------|---------------------------------|
| Exact `(type, instance-uuid)` key does not exist | `404 Not Found` | `404 Not Found` |
| Exists, but entirely outside the authorized subtree (e.g., parallel branch) | `403 Forbidden` | `403 Forbidden` |
| Exists in a child/descendant Context, but **not** directly in the current Context | `403 Forbidden` | `200 OK` |
| Exists only in non-`active` descendant Contexts (caller without administrative state override) | `403 Forbidden` | `403 Forbidden` |
| Exists directly in the current Context | `200 OK` | `200 OK` |

*Architectural Note:* Consistency between `HEAD` and `GET` requests is guaranteed only when using identical URLs. Because query parameters are an integral part of the HTTP URI identifier, a client must apply the exact same parameters to both calls. If you use `hierarchical=true` on a `HEAD` request to verify existence within the subtree, you must include `hierarchical=true` on the subsequent `GET` request to retrieve it. When the exact `(type, instance-uuid)` key exists only in a descendant, omitting the flag narrows the requested Context scope and deterministically returns `403 Forbidden`.

*Point-read symmetry note:* Support for `hierarchical` on point lookups (`HEAD` / `GET /instances/{type}/{instance-uuid}`) is intentional. It keeps discovery and fetch operations scope-coherent: if an instance is discovered through a hierarchical list/query call, the subsequent point read must preserve `hierarchical=true` to evaluate the same visibility domain.

> ⚠️ **Parameter Conflict:** The flags `hierarchical=true` and `syncExistingHierarchy=true` describe mutually exclusive topological propagation strategies. Passing both flags simultaneously in a `PUT` operation is strictly forbidden and will result in a `400 Bad Request`.

### Hierarchical Operations over Mixed-State Subtrees

When a client executes a hierarchical operation (`hierarchical=true`) starting from a valid `active` Context, the target subtree might contain descendant Contexts with a mix of non-`active` operational states (e.g., `suspended`, `created`). To guarantee robust execution and avoid breaking entire subtree operations due to a single locked child Context, the system adopts a **strict fail-safe filtering contract**.

**Hierarchical Operation × `effectiveState` Matrix:**

| Operation Type | Subtree descendants behavior | Emits `X-Result-Scope` |
|----------------|------------------------------|------------------------|
| **Reads & Queries** (e.g., `GET`, `HEAD`) | **Filtered.** Instances located only within non-`active` descendant Contexts are left out of lists and query results. A point lookup (`HEAD` / `GET`) of such an instance returns `403 Forbidden`, as for any instance that exists outside the requested scope. Furthermore, memberships in non-`active` Contexts are omitted from every `contexts` map, with or without `hierarchical=true` (the default `membershipScope=subtree` already covers the descendants). | Yes (`state-filtered`) |
| **Hierarchical Writes** (`hierarchical=true` on `POST`/`PUT`, `syncExistingHierarchy=true` on `PUT`, `IS-Editor`) | **Skipped.** Non-`active` descendant Contexts are left untouched, and the payload is synchronized over every `active` one, exactly as hierarchical reads omit them. | Yes (`state-filtered`) |
| **Administrative Overrides** (`IS-Admin`, `Ctx-M`, or higher) | **Applied.** Administrative roles bypass operational locks within the scope granted by their role. Their hierarchical writes reach `suspended` and `created` descendants. | No `state-filtered` (the `hierarchical` token is still emitted) |

*Note on Client Observability:* When the system filters out instances during a hierarchical read/query, or Context memberships from a `contexts` map in any read, for a standard user, it explicitly returns the `X-Result-Scope: state-filtered` HTTP header. This provides essential observability, signaling to the client that the returned payload is structurally sound but operationally incomplete relative to the physical graph. The two cases are reported differently. For the selection of instances, the header is returned whenever the requested subtree contains a non-`active` descendant Context, whether or not that Context holds a matching instance: the header depends only on the states of the Contexts, which the caller can read, so it cannot be used to find out, one predicate at a time, what a hidden Context contains. It is therefore the same on every page of a paginated result. For a `contexts` map, the header is returned only when a membership is actually omitted from it.

## `syncExistingHierarchy`

**Purpose:** Modifies an update operation to synchronize structural changes across the hierarchical subtree, but *only* in Contexts where the instance is already present.

| Parameter | Type | Default | Required |
|-----------|------|---------|:--------:|
| `syncExistingHierarchy` | boolean | `false` | ❌ |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | Token Context + all descendants |
| IS-Admin | ✅ | Token Context + all descendants |
| Ctx-M | ✅ | Token Context + all descendants |
| IS-Editor | ✅ | Token Context + all descendants. **Non-`active`** descendant Contexts are skipped. |
| IS-Contrib | ❌ | Hierarchical writes forbidden |
| IS-Member | ❌ | Write operations forbidden |

**Applicable endpoints:**

- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`

**Behavior:**
This parameter is designed explicitly to safely synchronize updates across shared instances. When passed on a `PUT /instances/{type}/{instance-uuid}` update request:

- It **does not** distribute the instance to new descendant Contexts (unlike `hierarchical=true`).
- It syncs the structural changes (like **Facet** instance addition/removal) *only in the descendant Contexts where the instance is already present*.
- On a creation request via `PUT /instances/{type}/{instance-uuid}`, this flag is intrinsically ignored. This parameter is **not applicable** to `POST /instances/{type}`; passing it will be ignored and trigger an `X-Warning` header. Both cases apply to roles allowed to use the flag; any other role receives `403 Forbidden` (see [Parameter Value Handling](#parameter-value-handling)).
- **Atomicity Guarantee:** Like `hierarchical=true`, the entire synchronization across all applicable Contexts is executed as a single, atomic database transaction. If the update fails in any single Context (e.g., due to a local schema violation or a concurrent modification conflict), the entire global transaction is rolled back, guaranteeing absolute state consistency without partial updates.

> ⚠️ **Parameter Conflict:** The flags `hierarchical=true` and `syncExistingHierarchy=true` describe mutually exclusive topological propagation strategies. Passing both flags simultaneously in a `PUT` operation is strictly forbidden and will result in a `400 Bad Request`.

## `propagationMode`

**Purpose:** Controls the depth of the avalanche graph traversal during `Add to Context` (`PUT`) and `Remove from Current Context` (`DELETE`) operations.

**Cross-Reference Mode Availability:**

| Mode | Add to Context | Remove from Context | Roles |
|------|:--------------:|:-------------------:|-------|
| `surgical` | ✅ (privileged roles only) | ✅ (All write roles) | See per-operation table |
| `shallow` | ✅ (Default) | ✅ (Default) | Every role permitted to call the operation |
| `deep` | ✅ | ❌ (falls back to `shallow`, `X-Warning`) | Every role permitted to call the operation |

### `propagationMode` (Add to Context)

**Purpose:** Controls the depth of the avalanche graph traversal during `Add to Context` operations (`PUT`).

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `propagationMode` | string | `shallow` | `surgical` (`IS-M`, `Infra-M`, or `IS-Admin` only for Add), `shallow`, `deep` |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | `surgical`, `shallow`, `deep` |
| IS-Admin | ✅ | `surgical`, `shallow`, `deep` |
| Ctx-M | ✅ | `shallow`, `deep` only |
| IS-Editor | ✅ | `shallow`, `deep` only |
| IS-Contrib | ❌ | N/A (Cannot perform Add to Context) |
| IS-Member | ❌ | N/A (Write operations forbidden) |

**Applicable endpoints:**

- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`

**Behavior:**

- **`surgical` (Precise Injection):** Restricted to `IS-M`, `Infra-M`, and `IS-Admin` on the standard Add to Context endpoint. It adds the explicitly targeted instance; what else it adds depends on the type of the targeted instance:
  - **Resource instance:** The system adds the targeted **Resource** instance and its **ConsistsOf**/**Facet** instances according to the `add` constraint of each **ConsistsOf** instance; a mandatory **Facet** instance left behind makes the operation fail schema validation. It explicitly ignores all outgoing **IsRelatedTo** instances, and consequently the downstream linked **Resource** instances.
  - **Facet instance:** Behaves identically to `shallow` and `deep`: a **Facet** instance has no outgoing relations to propagate, and in every mode it is added together with the **ConsistsOf** instance pointing to it, whose source **Resource** instance must already be in the target Context. The parameter is safely ignored and the system emits an `X-Warning` header.
  - **IsRelatedTo instance:** Adds the targeted **IsRelatedTo** instance. This requires the source **Resource** instance to already exist in the target Context. The target **Resource** instance is always pulled into the Context, because an **IsRelatedTo** instance cannot exist without its target, whatever the `add` constraint of the **IsRelatedTo** instance. The pulled **Resource** instance brings its **ConsistsOf**/**Facet** instances according to the `add` constraint of each **ConsistsOf** instance, and none of its own **IsRelatedTo** instances.
  - **ConsistsOf instance:** Behaves identically to `shallow` and `deep` because adding a **ConsistsOf** instance inherently requires adding its target **Facet** instance. The parameter is safely ignored and the system emits an `X-Warning` header.
- **`shallow` (Standard Default):** The traversal halts the avalanche path if it encounters a target **Entity** instance that is already present in the destination Context, assuming its downstream dependencies are satisfied.
- **`deep` (Full Transitive Closure):** The system ignores whether an intermediate **Entity** instance is already present in the target Context and continues evaluating its outgoing **Relation** instances to ensure the entire dependency chain is fully propagated. To prevent infinite loops in cyclic topologies, the system relies on a Modified Depth-First Search algorithm with a Visited Set, halting recursion if an instance has already been evaluated during the current transaction (see [Complex Topology Scenarios](appendix/03-complex-topology-scenarios.md)).

**Propagation Scenarios: Surgical vs Shallow vs Deep**

> **Visual Disclaimer (Infrastructure Topology Focus):** To avoid unreadable diagrams, the following simplified scenarios focus exclusively on the Infrastructure Topology (the graph of **Resource** instances and **IsRelatedTo** instances). While omitted from these didactic diagrams to reduce noise, it is strictly understood that every valid **Resource** instance must encapsulate its own Descriptive Topology (its attached **Facet** instances).

To understand the difference, consider a topology involving four **Resource** instances (`R1`, `R2`, `R3`, `R4`):

**Initial State:**

The scenario contains the following **Resource** instances:

- **Resource** instance `R1` exists in Context `C1`.
- **Resource** instance `R2` exists in Context `C1`.
- **Resource** instance `R3` exists in Contexts `C1` and `C2`.
- **Resource** instance `R4` exists in Context `C1`.

The scenario contains the following **IsRelatedTo** instances:

- `R1` is linked to `R2` via **IsRelatedTo** instance `IRT12`, which exists in Context `C1` and is configured with `add: propagate`.
- `R2` is linked to `R3` via **IsRelatedTo** instance `IRT23`, which exists in Context `C1` and is configured with `add: propagate`.
- `R3` is linked to `R4` via **IsRelatedTo** instance `IRT34`, which exists in Context `C1` and is configured with `add: propagate`.

```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```

When an admin executes an `Add to Context` operation to add `R1` to Context `C2`:

- **Scenario A: Surgical (Precise Injection)**
  The algorithm adds `R1` to `C2` but explicitly ignores the `add: propagate` constraints on outgoing **IsRelatedTo** instances. `R2`, `R3`, and `R4` are not evaluated.
  *(Note: While `R1` is injected alone regarding **IsRelatedTo** instances, each of its **ConsistsOf** instances possessing an `add: propagate` constraint is pulled into `C2` together with its target **Facet** instance.)*

```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```
```eval_rst
- **Scenario B: Shallow (Stop on Existing)**
  The algorithm stops as soon as it encounters an instance that is **already present** in the target Context.
  ``R1`` enters ``C2`` :math:`\rightarrow` ``R2`` enters ``C2`` :math:`\rightarrow` ``R3`` **is already in ``C2`` (STOP)**.
  ``R4`` is never evaluated and remains exclusively in Context ``C1``.
```
```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```
```eval_rst
- **Scenario C: Deep (Full Traversal)**
  The algorithm calculates the **complete transitive closure**, continuing to traverse outgoing **Relation** instances even if an intermediate instance is already in the target Context.
  ``R1`` enters ``C2`` :math:`\rightarrow` ``R2`` enters ``C2`` :math:`\rightarrow` ``R3`` is already in ``C2``, but the algorithm *continues* evaluating its outgoing **Relation** instances :math:`\rightarrow` the ``IRT34`` **Relation** instance pushes ``R4`` into ``C2``.
```
```mermaid
---
config:
  theme: neutral
  flowchart:
    edgeLabelBackground: "#ffffff"
---
graph LR
    R1("<b>R1</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R2("<b>R2</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R3("<b>R3</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource
    R4("<b>R4</b> <br/> <sub>[<i>C1, C2</i>]</sub>"):::resource

    R1 -->|"<b>IRT12</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R2
    R2 -->|"<b>IRT23</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R3
    R3 -->|"<b>IRT34</b> <br/> add: propagate <br/> <sub>[<i>C1, C2</i>]</sub>"| R4

    classDef resource fill:#4f81bd,stroke:#385d8a,stroke-width:3px,color:#fff;
    linkStyle default stroke:#385d8a,stroke-width:3px;
```

### `propagationMode` (Remove from Context)

**Purpose:** Controls whether the deletion of an instance triggers propagation constraints on its connected **Relation** instances during `Remove from Current Context` operations (`DELETE`).

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `propagationMode` | string | `shallow` | `surgical`, `shallow` (`deep` is a valid value that does not apply to removal: it is ignored with `X-Warning`) |

| Role | Available | Scope |
|------|:---------:|-------|
| IS-M / Infra-M | ✅ | Yes |
| IS-Admin | ✅ | Yes |
| Ctx-M | ✅ | Yes |
| IS-Editor | ✅ | Yes |
| IS-Contrib | ✅ | Yes |
| IS-Member | ❌ | N/A (Write operations forbidden) |

**Applicable endpoints:**

- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}`
- **Remove from Context:** `DELETE /instances/{type}/{instance-uuid}/contexts/{context-uuid}`

*(Note: `dryRun` is strictly reserved for orchestrating topological membership operations and avalanche previews. It is not supported for `PUT /instances/{type}/{instance-uuid}` instance replacement or `syncExistingHierarchy` operations. To preview the scope of a hierarchical synchronization before committing, consider performing a `hierarchical=true` `GET` read to enumerate the descendant Contexts where the instance is already present).*

**Behavior:**

- **In every mode:** the **Relation** instances pointing to a removed **Resource** or **Facet** instance leave the Context with it. This is the consistency of the model, not part of the avalanche: a **Relation** instance cannot stay in a Context where one of its endpoints is absent, so no `remove` constraint of those **Relation** instances is evaluated and their sources are untouched.
- **`surgical` (Safe Undo):** It restricts the operation to the explicitly targeted instance and its strictly required topological dependencies. This acts as a safe override and is available to all roles permitted to delete.
  - **Resource instance:** The system removes the targeted **Resource** instance. Because a **Facet** instance cannot exist without its parent, all its attached **Facet** instances (and the **ConsistsOf** instances attaching them) are necessarily removed as well. All outgoing **IsRelatedTo** instances are also removed, but the system explicitly ignores their `remove` constraints, preventing the avalanche from removing downstream target **Resource** instances.
  - **Facet instance:** Behaves identically to `shallow` because **Facet** instances possess no outgoing relations to propagate. The parameter is safely ignored and the system emits an `X-Warning` header.
  - **IsRelatedTo instance:** Removes only the targeted **IsRelatedTo** instance. The target **Resource** instance is completely ignored, regardless of the `remove` constraint value on that **IsRelatedTo** instance. This acts as a safe "undo" facility to remove an accidental link without collateral damage.
  - **ConsistsOf instance:** Behaves identically to `shallow` because removing a **ConsistsOf** instance inherently mandates the removal of its target **Facet** instance. The parameter is safely ignored and the system emits an `X-Warning` header.
- **`shallow` (Standard Default):** The standard cascading removal. The traversal evaluates all `remove` constraints (`cascade`, `keep`, `cascadeWhenOrphan`). The avalanche stops naturally along any path where an **Entity** instance survives. *(Note: If the directly targeted instance of the `DELETE` operation is a **Relation** instance, its `remove` propagation constraint is still evaluated, and the avalanche propagates downstream to its target exactly as if the removal had originated from the source **Resource** instance).*

*(Note: The value `deep` is not semantically applicable to DELETE operations. Deletion evaluates constraints directly; ignoring a survival condition would bypass model integrity. If `deep` is passed, it is a valid but inapplicable value: the system emits an `X-Warning` header and falls back to `shallow` (rule 2 of [Parameter Value Handling](#parameter-value-handling)).)*

> **Advanced Topologies:** To see exactly how propagation constraints behave in advanced graph topologies (such as cyclic dependencies and diamond patterns) during both Add and Remove operations, refer to [Complex Topology Scenarios](appendix/03-complex-topology-scenarios.md).

## `dryRun`

**Purpose:** Simulate the execution of operations that trigger complex cascading effects (avalanche effect) without persisting any changes.

| Parameter | Type | Default |
|-----------|------|---------|
| `dryRun` | boolean | `false` |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin | ✅ |
| Ctx-M | ✅ |
| IS-Editor | ✅ |
| IS-Contrib | ✅ |
| IS-Member | ❌ |

**Applicable endpoints:**

- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`
- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}`
- **Remove from Context:** `DELETE /instances/{type}/{instance-uuid}/contexts/{context-uuid}`

*(Note: `dryRun` is strictly reserved for orchestrating topological membership operations and avalanche previews. It is not supported for `PUT /instances/{type}/{instance-uuid}` instance replacement or `syncExistingHierarchy` operations. To preview the scope of a hierarchical synchronization before committing, consider performing a `hierarchical=true` `GET` read to enumerate the descendant Contexts where the instance is already present).*

**Behavior:**
When `dryRun=true`, the service traverses the graph, evaluates all propagation constraints (e.g., `add: propagate`, `remove: cascade`), applies validation, and returns the complete set of affected instances exactly as it would during a real execution, but performs a rollback before committing to the database. This allows clients to preview the impact of a destructive or wide-reaching operation. **Validation Parity:** If the simulated operation violates any schema constraint or topological rule (e.g., it would result in a missing mandatory **Facet** instance), the endpoint strictly rejects the request exactly as a real execution would (returning `409 Conflict` with the validation error message). It does **not** return a `200 OK` containing a simulated broken graph.

`dryRun` never expands permissions: the same authorization checks and role constraints of the corresponding real operation are applied before simulation.

> ⚠️ **Concurrency and State Mutation Risk:** `dryRun` is a non-binding simulation snapshot: it does not reserve state, does not acquire distributed locks up to a later confirm call, and does not provide cross-request serializability. Between the `check` (`dryRun=true`) and the subsequent `confirm` (real execution) of the [Try-Check-Confirm Pattern](09-api-instances-and-admin.html#try-check-confirm-pattern), concurrent writes by other users may fundamentally change the graph state. Therefore, a subsequent real execution can legitimately fail with a `409 Conflict` or result in a different avalanche even if the preview succeeded perfectly milliseconds before.

**Success-code matrix (normative):** For the definitive matrix combining `dryRun`, `Prefer: return`, Success HTTP Codes, and response payload shapes, see the [Operation Envelope and Parameter Matrix](09-api-instances-and-admin.html#operation-envelope-and-parameter-matrix).

## Inclusion Parameters

## `metadataPolicy`

**Purpose:** Control whether metadata is omitted, included only on the top-level response elements, or propagated to all nested elements when the endpoint returns nested graph structures.

| Parameter | Type | Default | Accepted Values |
|-----------|------|---------|-----------------|
| `metadataPolicy` | string | `none` | `none`, `root`, `all` |

| Role | Available | Metadata content |
|------|:---------:|-----------------|
| IS-M / Infra-M | ✅ | **Full:** all fields visible, no obfuscation |
| IS-Admin | ✅ | **Full:** all fields visible, no obfuscation |
| Ctx-M | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |
| IS-Editor | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |
| IS-Contrib | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |
| IS-Member | ✅ | **Filtered:** dates visible, `createdBy` and `lastUpdateBy` returned as `"[REDACTED]"` |

**Applicable endpoints:**

- **List Contexts:** `GET /contexts`
- **Execute Context JSON Query:** `QUERY /contexts`
- **Read Context:** `GET /contexts/{context-uuid}`
- **Read Current Context:** `GET /contexts/@current`
- **Create Context:** `PUT /contexts/{context-uuid}`
- **Tracked Update Context:** `PATCH /contexts/{context-uuid}`
- **Execute Type JSON Query:** `QUERY /types`
- **Read Type:** `GET /types/{type-name}`
- **Create Type:** `PUT /types/{type-name}`
- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Exists Instance:** `HEAD /instances/{type}/{instance-uuid}` *(same representation selection as Read; the body is omitted)*
- **Read Instance:** `GET /instances/{type}/{instance-uuid}`
- **Create Instance:** `POST /instances/{type}`
- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`
- **Merge Update Instance:** `PATCH /instances/{type}/{instance-uuid}`
- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` *(Note: Applicable only when the full response representation is returned, which is the default unless `Prefer: return=minimal` is specified).*
- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **List Query Templates:** `GET /query-templates`
- **Execute Query Template JSON Query:** `QUERY /query-templates`
- **Read Query Template:** `GET /query-templates/{name}`
- **Create/Update Query Template:** `PUT /query-templates/{name}`
- **Execute Query Template:** `QUERY /query-templates/{name}` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Remove from Context:** `DELETE /instances/{type}/{instance-uuid}/contexts/{context-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Execute Raw Query:** `QUERY /admin/raw-query` *(Note: Only when `rawResult=false`)*
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**

- `none` (default): omit metadata entirely.
- `root`: include metadata only on the top-level response elements.
- `all`: include metadata on the top-level response elements and on all nested elements returned by the endpoint.
- On endpoints that do not return nested graph elements (such as Contexts, Types, and Query Template definitions), `root` and `all` are equivalent in response shape.

> **Compatibility note for this version:** `metadataPolicy` is the canonical parameter. The legacy parameters `includeMeta` and `allMeta` have been consolidated into `metadataPolicy`, are still accepted server-side in this release for backward compatibility, and will be removed in the next major version. Clients should migrate now.

**Legacy-to-canonical mapping accepted by the server in this version:**

- `includeMeta` omitted/false and `allMeta` omitted/false -> `metadataPolicy=none`
- `includeMeta=true` and `allMeta` omitted/false -> `metadataPolicy=root`
- `includeMeta=true` and `allMeta=true` -> `metadataPolicy=all`
- Legacy `allMeta=true` without `includeMeta=true` remains invalid legacy input: it is ignored by the compatibility layer and triggers an `X-Warning` header.

## `contextsPolicy`

**Purpose:** Control whether the response includes the `contexts` membership map and whether that
map is added only to top-level response elements or also to their nested elements. This policy
controls representation depth only; role- and token-based visibility independently determine which
Context memberships each emitted map may contain.

| Parameter | Type | Default | Allowed Values |
|-----------|------|---------|----------------|
| `contextsPolicy` | string | `none` | `none`, `root`, `all` |

- `none` (default): omit `contexts` from every returned element.
- `root`: include `contexts` only on top-level response elements. In a list or operation envelope,
  every direct array item is a top-level element.
- `all`: include `contexts` on top-level and nested elements, including nested **Facet** and **ConsistsOf** instances, and the `source`/`target` endpoint references of Relations.

Wire values are lowercase. Supplying any other value returns `400 Bad Request` (see [Parameter Value Handling](#parameter-value-handling)).

**Applicable endpoints:**

- **List Instances:** `GET /instances/{type}`
- **Execute JSON Query:** `QUERY /instances` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Exists Instance:** `HEAD /instances/{type}/{instance-uuid}` *(same representation selection as Read; the body is omitted)*
- **Read Instance:** `GET /instances/{type}/{instance-uuid}`
- **Create Instance:** `POST /instances/{type}`
- **Create/Update Instance:** `PUT /instances/{type}/{instance-uuid}`
- **Merge Update Instance:** `PATCH /instances/{type}/{instance-uuid}`
- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}` *(Note: Applicable only when the full response representation is returned, which is the default unless `Prefer: return=minimal` is specified).*
- **Remove from Current Context:** `DELETE /instances/{type}/{instance-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Execute Query Template:** `QUERY /query-templates/{name}` *(Note: When `_emit` is used, apply the canonical rules in [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules))*
- **Remove from Context:** `DELETE /instances/{type}/{instance-uuid}/contexts/{context-uuid}` *(Note: Applicable only when the full response representation is returned).*
- **Execute Raw Query:** `QUERY /admin/raw-query` *(Note: Only when `rawResult=false`)*
- All applicable `/access` read-only mirror endpoints of the above.

**Behavior:**
**Not available for:** Context and Type endpoints (Contexts and Types are not Context-scoped in the same way).

**Context membership rule:**

- A **Resource** instance is present in all Contexts that form the union of the Contexts of all its **Facet** instances. By design (and strictly enforced by the IS-Model), it is physically impossible for a **Facet** instance to belong to a Context where its parent **Resource** instance does not exist.
- A **ConsistsOf** instance is present in all Contexts where its target **Facet** instance is present.
- An **IsRelatedTo** instance's membership is an explicitly maintained subset of the intersection of its source and target **Resource** Contexts. *(For the strict mathematical intersection rule governing general **Relation** instances across Contexts, see [Topological and Contextual Rules](03-is-model-core-topology.html#topological-and-contextual-rules)).*

## `membershipScope`

**Purpose:** Select the Context boundary used to populate every emitted `contexts` membership map.
This parameter is orthogonal to `contextsPolicy`, which controls where those maps appear, and to
`hierarchical`, which controls the Context boundary used to select or mutate instances.

| Parameter | Type | Default | Allowed Values |
|-----------|------|---------|----------------|
| `membershipScope` | string | `subtree` | `subtree`, `global` |

- `subtree` (default): include memberships in the token Context and its descendants. A token issued
  for the Root Context therefore covers the complete Context tree.
- `global`: include every Context membership independently of the token Context. This value is
  restricted to `IS-M`, `Infra-M`, and `IS-Admin`.

Wire values are lowercase. An unknown value returns `400 Bad Request`. A caller other than `IS-M`,
`Infra-M`, or `IS-Admin` requesting `global` receives `403 Forbidden`; the server never silently
downgrades it to `subtree`.

| Role | `subtree` | `global` |
|------|:---------:|:--------:|
| IS-M / Infra-M | ✅ | ✅ |
| IS-Admin | ✅ | ✅ |
| Ctx-M | ✅ | ❌ |
| IS-Editor | ✅ | ❌ |
| IS-Contrib | ✅ | ❌ |
| IS-Member | ✅ | ❌ |

**Applicable endpoints:**

- Every instance endpoint that supports `contextsPolicy`.
- **List Instance Contexts:** `GET /instances/{type}/{instance-uuid}/contexts` and its `/access`
  mirror. This endpoint always returns memberships, so `membershipScope` applies without a
  `contextsPolicy` parameter.
- **Execute Query Template:** `QUERY /query-templates/{name}` and its `/access` mirror when the
  returned representation includes membership maps.

**Interaction rules:**

- On ordinary instance representations, `membershipScope` does not cause a `contexts` map to
  appear; `contextsPolicy=root|all` remains necessary.
- `hierarchical=true&membershipScope=global` is valid and intentionally independent: instances are
  selected from the token Context subtree, while each emitted membership map is global.
- Omitting memberships outside an explicitly requested `subtree` is the requested base result and
  emits no `X-Result-Scope` token.
- State-based restrictions that further narrow the requested boundary still emit their
  applicable `X-Result-Scope` token.
- On `GET /instances/{type}/{instance-uuid}/contexts`, `membershipScope` does not affect how the
  instance is found: the lookup follows the same rule as `Read` (token Context, or its descendants
  with `hierarchical=true`) for every role, `global` included. A caller that knows only the UUID
  uses a token of a Context high enough in the tree, with `hierarchical=true`.

## Privileged Parameters

## `rawResult` — Raw Query only

**Purpose:** Returns the payload exactly as provided by the underlying database engine, bypassing the Information System model conversion.

| Parameter | Type | Default | Required |
|-----------|------|---------|:--------:|
| `rawResult` | boolean | `false` | ❌ |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin | ❌ |
| Ctx-M | ❌ |
| IS-Editor | ❌ |
| IS-Contrib | ❌ |
| IS-Member | ❌ |

**Applicable endpoints:**

- **Execute Raw Query:** `QUERY /admin/raw-query`

**Behavior:**
This parameter applies exclusively to `QUERY /admin/raw-query` (raw OrientDB SQL query). The query itself is expected in the request body (e.g. `{"query": "SELECT..."}`). It must be a read-only OrientDB SQL statement. As the endpoint uses a read-only database user, non-idempotent operations (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`) are automatically rejected. Any valid read-only statement is accepted (e.g. `SELECT`, `TRAVERSE`, `MATCH`).

- `false` (default): element rows are converted to the Information System model format and apply `metadataPolicy`, `contextsPolicy`, and `membershipScope`. Scalar and projection rows have no Information System representation, so they retain their backend-native JSON shape; explicitly requested enrichment parameters are ignored for those rows and emit `X-Warning`.
- `true`: every row is returned exactly as provided by the OrientDB backend, retaining backend-native field names; only `hierarchical` affects execution scope, while `metadataPolicy`, non-default `contextsPolicy`, and an explicit non-default `membershipScope` are ignored and emit `X-Warning` when requested.

> ⚠️ This endpoint is **NOT for production use**. The OrientDB SQL syntax may change or disappear without notice when the backend is replaced.
>
> **Scope guarantee (client-facing contract):** visibility and Context boundaries are enforced by the service implementation and data model, including when `hierarchical=true` is used where applicable. Backend storage/partitioning internals are intentionally out of scope for this reference because they are not required by API clients to invoke the contract correctly.
>
> **Note:** `polymorphic` does not apply to this endpoint. The raw OrientDB SQL query is executed as-is; polymorphic filtering must be expressed in the SQL itself.

## `bypassHierarchyCheck` — Cross-Boundary Membership

**Purpose:** Allows `IS-M`, `Infra-M`, and `IS-Admin` to explicitly bypass the boundary verification of the named Context when adding instances to Contexts or removing them from Contexts.

| Parameter | Type | Default | Required |
|-----------|------|---------|:--------:|
| `bypassHierarchyCheck` | boolean | `false` | ❌ |

| Role | Available |
|------|:---------:|
| IS-M / Infra-M | ✅ |
| IS-Admin | ✅ |
| Ctx-M | ❌ |
| IS-Editor | ❌ |
| IS-Contrib | ❌ |
| IS-Member | ❌ |

**Applicable endpoints:**

- **Add to Context:** `PUT /instances/{type}/{instance-uuid}/contexts/{new-context-uuid}`
- **Remove from Context:** `DELETE /instances/{type}/{instance-uuid}/contexts/{context-uuid}`

**Behavior:**
Add to Context normally restricts `Ctx-M` and `IS-Editor` to the token Context subtree and allows
`IS-M`, `Infra-M`, and `IS-Admin` to reach that subtree plus sibling Contexts. By passing
`bypassHierarchyCheck=true`, an `IS-M`, `Infra-M`, or `IS-Admin` explicitly declares the intent to
target a completely unrelated branch. The flag waives destination containment only: the exact token
Context remains the operation's source topology. Remove from Context follows the same rules on the
Context it names: with `bypassHierarchyCheck=true` an `IS-M`, `Infra-M`, or `IS-Admin` removes the
instance from any live Context, also under another Root, so that what was added across a boundary can be
removed the same way. Because this operation breaks standard boundaries, the bypass is never implicit.

> **⚠️ Warning on Recursive Propagation:** The `bypassHierarchyCheck` parameter applies **recursively** to the entire avalanche effect triggered by the `propagationMode`. For example, if combined with `propagationMode=deep`, the system will recursively import the initial instance *and all its transitively connected dependencies* into the new Context branch without enforcing hierarchy checks on any of the propagated nodes. This is an immensely powerful tool designed to migrate entire graph clusters across tenant boundaries, but it carries a severe risk of unintended cross-tenant contamination. Administrators are strongly advised to always run complex cross-boundary imports with `dryRun=true` first to inspect the blast radius.

## Parameter Conflicts

The API is strictly defensive against ambiguous or contradictory intents. The following query parameter combinations are mutually exclusive and will trigger an immediate `400 Bad Request` or an `X-Warning` header if submitted together.

| Query Parameter 1 | Query Parameter 2 | Resolution Rule | System Effect |
| :--- | :--- | :--- | :--- |
| `hierarchical=true` | `syncExistingHierarchy=true` | These represent two mutually exclusive distribution topologies for a `PUT` operation. | `400 Bad Request` |
| `rawResult=true` | `metadataPolicy=root` / `metadataPolicy=all` | `rawResult` takes precedence. `metadataPolicy` is ignored. | `X-Warning` Header |
| `rawResult=true` | `contextsPolicy=root` / `contextsPolicy=all` | `rawResult` takes precedence. `contextsPolicy` is ignored. | `X-Warning` Header |
| `rawResult=true` | `membershipScope=global` | `rawResult` takes precedence. `membershipScope` is ignored (for an authorized role; see [Parameter Value Handling](#parameter-value-handling)). | `X-Warning` Header |

In addition to parameter-to-parameter conflicts, the API enforces precedence rules when parameters conflict with HTTP Headers:

| HTTP Header | Query Parameter | Resolution Rule | System Effect |
| :--- | :--- | :--- | :--- |
| `Prefer: return=minimal` | `metadataPolicy=root` / `metadataPolicy=all` | `Prefer: return=minimal` takes precedence. `metadataPolicy` is ignored. | `X-Warning` Header |
| `Prefer: return=minimal` | `contextsPolicy=root` / `contextsPolicy=all` | `Prefer: return=minimal` takes precedence. `contextsPolicy` is ignored. | `X-Warning` Header |
| `Prefer: return=minimal` | `membershipScope=global` | No membership map is returned; `membershipScope` is ignored (for an authorized role; any other role receives `403 Forbidden`, see [Parameter Value Handling](#parameter-value-handling)). | `X-Warning` Header |

Finally, when the client submits a JSON Query Payload (via `QUERY /instances`) or executes a Query Template (via `QUERY /query-templates/{name}` and its `/access` mirror), internal query directives can override URL parameters:

| JSON Payload Directive | Query Parameter | Resolution Rule | System Effect |
| :--- | :--- | :--- | :--- |
| `_emit` | `metadataPolicy=root` / `metadataPolicy=all` | `_emit` takes precedence. `metadataPolicy` is ignored. | `X-Warning` Header |
| `_emit` | `contextsPolicy=root` / `contextsPolicy=all` | `_emit` takes precedence. `contextsPolicy` is ignored. | `X-Warning` Header |
| `_emit` | `membershipScope=global` | `_emit` returns no membership map; `membershipScope` is ignored (for an authorized role; any other role receives `403 Forbidden`). | `X-Warning` Header |

In all three cases (`rawResult=true`, `Prefer: return=minimal`, `_emit`), `metadataPolicy` is reported whenever it is supplied, whatever its value, while `contextsPolicy` and `membershipScope` are reported only when supplied with a non-default value.

*(Note on `_emit`: The resolution rules and precedence interactions for the `_emit` JSON query keyword are formally detailed in the [Canonical _emit precedence rules](appendix/07-json-query-syntax-reference.html#canonical-emit-precedence-rules) chapter).*
