# Response Shape Matrix

The following matrices provide a unified reference for how query parameters, HTTP headers, and JSON clauses alter the structural density and schema of the JSON response payload strictly for **Graph Element Instances** (**Resource**, **Facet**, **IsRelatedTo**, and **ConsistsOf**). 

To maximize clarity, the behavior is divided into two orthogonal dimensions: the **Base Response Shape** (the structural skeleton) and the **Payload Enrichment** (the dynamic injection of system fields).

### Base Response Shape

This table defines the fundamental architectural structure of the returned JSON payload.

| Operation Category | Shaping Directive | Output JSON Base Shape |
|--------------------|-------------------|------------------------|
| **Standard Operations**<br>*(Read, List, Create, Update)* | *None* | **Full Instance Representation**. The complete topological structure of the requested instance(s). |
| **Search / Query**<br>*(Execute JSON Query, Query Templates)* | `_emit` clause *(in JSON body)* | **Projected Record**. Flat dictionary matching the `_emit` aliases. Structural nesting is destroyed. |
| **Avalanche Operations**<br>*(Add/Remove Context, Admin overrides)* | `Prefer: return=minimal` | **Minimal Operation Envelope**. Flat array of affected elements containing strictly `type` and `id` (plus `source`/`target` for relations). |
| **Avalanche Operations**<br>*(Add/Remove Context, Admin overrides)* | `Prefer: return=representation`<br>*(or Header Missing)* | **Full Operation Envelope**. Top-level array of **Resource** and **IsRelatedTo** instances. **Resource** instances nest their full **Facet** representations. `propagationConstraint` is strictly included for relations. |

### Payload Enrichment Modifiers

This table defines how specific query parameters dynamically inject system-managed fields into the Base Response Shape. These modifiers can be combined freely (e.g., passing both `metadataPolicy=all` and `includeContexts=true`).

| Parameter | Combinatorial Constraint | Enrichment Effect on Base Shape |
|-----------|--------------------------|---------------------------------|
| `metadataPolicy=none` | None | No `metadata` object is injected. |
| `metadataPolicy=root` | None | Adds the `metadata` object (tracking timestamps and authors) to the **top-level** instance(s) only. |
| `metadataPolicy=all` | None | Adds the `metadata` object to the top-level instance(s) **AND** all nested elements. |
| `includeContexts=true` | None | Adds the `contexts` map (UUID → Path) to the top-level instance(s) **AND** all nested elements. |

> **⚠️ Extreme Overrides & Precedence Rules:**
> 1. **Projection Precedence:** If `_emit` is used during a query, all enrichment parameters (`metadataPolicy`, `includeContexts`) are strictly **ignored**. The response is exclusively bounded by the requested projection aliases.
> 2. **Minimal Envelope Precedence:** If an avalanche operation is executed with `Prefer: return=minimal`, all enrichment parameters are strictly **ignored** to honor the maximum bandwidth-optimization contract. The system emits an `X-Warning` header to notify the client.

*(Note: In the context of `metadataPolicy=root`, "top-level" refers to the outermost objects in the response array/payload. For Read/List, this is the requested instance. For Operation Envelopes, these are the **Resource** and **IsRelatedTo** instances forming the backbone of the avalanche result).*
