# GCAP reference

> Clearing inputs, headroom-then-buffers-then-tiered-curtailment, per-class commit outputs, identical-input determinism, and pool and ramp-safety bounds.

- Repository: g2tf-org/g2tf-standards
- GitHub: https://github.com/g2tf-org/g2tf-standards
- Human docs: https://grok-wiki.com/public/docs/g2tf-org-g2tf-standards-436ba3f3e0ff
- Complete Markdown: https://grok-wiki.com/public/docs/g2tf-org-g2tf-standards-436ba3f3e0ff/llms-full.txt

## Source Files

- `specs/gcap/spec.md`
- `specs/desp/spec.md`
- `specs/g2p/spec.md`
- `members/allocator.md`
- `architecture/failsafe-model.md`
- `members/buffer.md`

---

---
title: "GCAP reference"
description: "Clearing inputs, headroom-then-buffers-then-tiered-curtailment, per-class commit outputs, identical-input determinism, and pool and ramp-safety bounds."
---

**GCAP** (Grid Capacity Allocation Protocol), version **26.0-draft**, is the Allocator clearing specification in `specs/gcap/spec.md`. Each one-minute interval the Allocator computes per-class allocations from Member Service Descriptors and Grid 1 constraints, then publishes interval-only commitments over [G2P](/g2p-reference). Given identical inputs, any conformant implementation **MUST** produce identical allocations. The Allocator holds **no internal intelligence or discretion**; intelligence stays at the edge in Member Elements.

<Info>
Status is **Draft — seeking input**. RFC 2119 / RFC 8174 keywords in `specs/gcap/spec.md` are normative. Wire format, exact proportionality weights, and intra-interval timing budgets are not specified in v26.0-draft.
</Info>

## Stack position

GCAP is the middle protocol of the Grid 2 stack. It does not define identity, messages, or class names; it consumes them.

| Layer | Spec | GCAP relationship |
|---|---|---|
| Classes | DESP `26.0-draft` | Curtailment order **C → B → A**; Grid 1 Firm is never cut by GCAP |
| Clearing | GCAP `26.0-draft` | Deterministic allocation each interval |
| Transport | G2P `26.0-draft` | Carries Service Descriptors, Commitments, federation announcements, telemetry |

Allocations apply to **whole one-minute intervals**. Clearing **MUST** finish so Members receive `commit-%` with time to self-dispatch **before** the interval opens. Where a Grid 1 dispatch instruction conflicts with a Grid 2 allocation, **Grid 1 prevails**. Positions are **units of energy within the interval** (v26.0 scope).

## Inputs

Each interval the Allocator clears against exactly these three input families.

<ParamField body="Grid 1 constraints" type="custodian-provisioned set" required>
Zone power production capacity, transmission constraints, and target reserves. Optionally power distribution factors and Dynamic Line Rating dynamics. The utility transmission owner **MUST** provision local and regional constraints. A regional system operator **MAY** add capacity constraints. The Allocator **MUST NOT** clear on stale constraint inputs.
</ParamField>

<ParamField body="Member Service Descriptors" type="G2P §3.1, signed" required>
In-zone descriptors: Use per-class request to consume (`+`); Buffer offer to source or use (`−` discharge / `+` charge); Source offer to supply (`−`). Each position **MUST** be signed by the originating Member. A descriptor **MAY** be reissued each interval; DESP classes **MAY** change per interval.
</ParamField>

<ParamField body="Peer-Allocator announcements" type="G2P §3.3" required>
Announce-and-listen quantities across coupled zones. **MAY** add boundary headroom. **MUST NOT** relax local constraints. If a required peer announcement is missing, clear conservatively as if that boundary contributes **no additional headroom**. Partition from a peer **MUST NOT** block local clearing in an unaffected domain.
</ParamField>

<Warning>
Peer announcements inform local clearing; they never override constraints provisioned by the domain's own Grid 1 custodians.
</Warning>

```text
Allocator input set (interval N)
├── Grid 1 constraints          (TO required; RSO optional extras)
│   ├── zone production capacity
│   ├── transmission constraints
│   ├── target reserves
│   └── optional DLR / distribution factors
├── in-zone Service Descriptors (signed; energy in the interval)
│   ├── Use:    {A, B, C} request to consume (+)
│   ├── Buffer: charge (+) / discharge (−)
│   └── Source: offer to supply (−)
└── peer announcements          (boundary headroom only; never relax local)
```

## Clearing algorithm

The Allocator redispatches deterministically and proportionally in **strict order**. Buffers are a shock absorber, not a later residual.

```mermaid
flowchart TD
  subgraph inputs [Inputs]
    G1[Grid 1 constraints]
    SD[Service Descriptors]
    FA[Peer announcements]
  end

  stale{Stale constraints or domain partition?}

  subgraph steps [GCAP §3]
    H[1 Headroom]
    B[2 Buffer committed dispatch]
    T[3 Ramp down C then B then A]
  end

  subgraph out [Outputs]
    U[Use commit-%]
    BF[Buffer committed dispatch]
    S[Source committed take]
  end

  G1 --> stale
  SD --> stale
  FA --> stale
  stale -->|yes| W[MUST NOT clear]
  W --> FB[Members fall back to Grid 1]
  stale -->|no| H --> B --> T --> U
  T --> BF
  T --> S
```

| Step | Name | Rule |
|---|---|---|
| 1 | **Headroom first** | Compute surplus network capability (grid capacity headroom) available to the domain for the interval. |
| 2 | **Buffers second** | Clear Buffer **committed dispatch** to absorb shortfall or surplus. **Buffers are cleared before any load is curtailed.** |
| 3 | **Tiered ramp-down** | If relief is still required, reduce Use allocations by DESP class: **Best Efforts (C)**, then **Preferred (B)**, then **Assured (A)**. Never touch traditional **Firm (Grid 1)** service. |

Within a class, curtailment **MUST** be **proportional**: equitable dispatch proportional to **connection size** and **differential request size**. The exact weighting formula is an open item.

<Note>
GCAP never inspects facility-internal workloads. Use Members map jobs onto class positions at the edge; the Allocator clears class-level signed positions only.
</Note>

### Class order GCAP honors

| Class | DESP name | GCAP treatment |
|---|---|---|
| — | Traditional Firm (Grid 1) | Outside Grid 2. Never curtailed by GCAP. |
| A | Assured | Curtailed last among Grid 2 classes. |
| B | Preferred | Curtailed after C, before A. |
| C | Best Efforts | Curtailed first. |

G2P interaction-table aliases Firm / Semi-Firm / Flex map to A / B / C; naming reconciliation is open in DESP.

## Outputs

Commitments are G2P §3.2 messages. They apply to the **coming interval only** and expire with it.

<ResponseField name="commit-%" type="per class, per Use Member">
Per-class committed share of the Use Member's requested consume position. The Use Member **MUST** self-dispatch within this `commit-%` and agreed host-utility parameters.
</ResponseField>

<ResponseField name="committed dispatch" type="per Buffer">
Signed charge or discharge the Buffer **MUST** honor within agreed ramp rates. Cleared in algorithm step 2, before any Use class is cut.
</ResponseField>

<ResponseField name="committed take" type="per Source">
Supply the Source **MUST** self-dispatch to within agreed ramp rates. v26.0 treats supply as a single class.
</ResponseField>

<ResponseField name="commitment envelope" type="required G2P fields">
A Commitment **MUST** identify the **interval**, the **domain**, and the **clearing inputs version** it was computed against.
</ResponseField>

<RequestExample>
```text
G2P Service Descriptor  Member → Allocator
  element_id:  domain-scoped POI id
  interval:    one-minute forward vector
  positions:   signed energy-in-interval
    Use:    A+, B+, C+
    Buffer: charge+ or discharge−
    Source: supply−
```
</RequestExample>

<ResponseExample>
```text
G2P Commitment  Allocator → Member
  interval:          coming one-minute window
  domain:            allocation domain id
  inputs_version:    digest of the input set
  Use:               commit-% per class
  Buffer:            committed dispatch
  Source:            committed take
```
</ResponseExample>

A Member that has not received a Commitment for the current interval **MUST** treat itself as in fallback.

## Determinism and verifiability

| Rule | Normative text |
|---|---|
| Identical inputs | Any conformant implementation **MUST** produce identical allocations. |
| No discretion | The Allocator **MUST NOT** apply internal intelligence or operator judgment. |
| Reproducibility | Any party holding the same inputs **MUST** be able to reproduce the computation. |
| Input digest | Allocators **SHOULD** publish, within the domain, the input digest each Commitment was computed against. |
| Stale inputs | The Allocator **MUST NOT** clear on stale constraint inputs. |

Publication of that digest is listed as an Allocator open item; G2P already requires Commitments to carry the clearing-inputs version.

## Pool and ramp safety

GCAP bounds both **who may be in the pool** and **how far one interval may move a member**.

- The Allocator **MUST** bound total cleared participation so that **simultaneous member fallback** stays within manageable aggregate ramp limits for the domain. Failsafe-model language: the total participating pool **MUST** be sized so whole-pool fallback produces aggregate ramps within manageable Grid 1 system ramp limits. That bound is the binding constraint on domain growth; sizing methodology is open.
- Per-member allocation **deltas between consecutive intervals MUST** respect each member's agreed ramp rates.
- All transitions — into fallback, out of fallback, and between interval allocations — **MUST** respect ramp rates agreed with the host utility.

## Failsafe and withhold

On **stale constraint inputs** or **domain partition**, the Allocator **MUST withhold clearing**. Members detecting a missed or stale Commitment fall back locally. Fallback **MUST** be determinable from the Member's own state and last-known configuration; it **MUST NOT** depend on reaching a remote peer.

| Element | Fallback when GCAP does not commit |
|---|---|
| Use | Grid 1 baseline (firm load limit) or manual curtailment; follow allowed ramps. |
| Buffer | Standalone Grid 1 schedule; **no Grid 2 support commitment** while in fallback. |
| Source | Grid 1 baseline interconnection behavior; follow allowed ramps. |
| Allocator | **MUST NOT** clear. |

<Warning>
Missing peer announcements are not the same as domain partition. Conservative local clearing (zero extra boundary headroom) continues. Only stale **local** constraint inputs or partition of the **local** domain withhold the entire clear.
</Warning>

## Open items in v26.0-draft

These affect implementers; they are not implied defaults.

<AccordionGroup>
<Accordion title="Proportionality and load shape">
Exact connection-size vs. request-size weights; treatment of indivisible loads; multi-constraint (nodal) allocation vs. single-zone headroom.
</Accordion>
<Accordion title="Cross-interval fairness">
Whether deferred Class C accrues priority in later intervals.
</Accordion>
<Accordion title="Markets and mid-interval dispatch">
Interaction with market dispatch instructions that arrive mid-interval. Grid 1 still prevails on conflict.
</Accordion>
<Accordion title="Buffers">
How much state-of-charge the Allocator needs for step 2; priority among multiple Buffers (proportional vs. merit order by round-trip efficiency).
</Accordion>
<Accordion title="Sources">
How forecast error interacts with headroom; whether curtailed Source energy can move to a co-located Buffer in the same interval.
</Accordion>
<Accordion title="Operations">
Allocator redundancy (active/standby); who hosts the Allocator; digest publication practice.
</Accordion>
</AccordionGroup>

## Related pages

<CardGroup>
<Card title="Allocator" href="/allocator">
No-discretion execution of this algorithm, constraint-authority inputs, withhold-on-stale, and whole-pool ramp sizing.
</Card>
<Card title="DESP reference" href="/desp-reference">
Class table, mandatory C-B-A order, and domain class-policy limits GCAP consumes.
</Card>
<Card title="G2P reference" href="/g2p-reference">
Service Descriptor, Commitment, federation announcement, and telemetry families that carry GCAP I/O.
</Card>
<Card title="Failsafe model" href="/failsafe-model">
Interval-only commitments, locally determinable fallback, and pool ramp limits.
</Card>
<Card title="Provision constraint inputs" href="/provision-constraint-inputs">
Required Grid 1 set, optional DLR and distribution factors, and the no-relax-from-peers rule.
</Card>
<Card title="Buffer Member" href="/buffer-member">
Signed charge/discharge offers and step-2 committed dispatch before any load curtailment.
</Card>
</CardGroup>