# Brief: project-guarantee

(`/kiro-discovery`, 2026-10-09, Path E "configuration layering". Backlog:
not started until `project-config` and `scheduler-preemption` land.)

## Problem
With `project-config`, projects can only be capped. Owners of a project (a
group that funded hardware, a department with a committed share) need a
**guarantee**: a minimum share or a pool of resources they get when they ask
for it, while idle capacity is still lent to others.

## Current State
- No guarantee, share or pool concept exists; fairshare is in the queue YAML
  schema only and dropped by `xceadmin` (`mapping.py:80-97`).
- Preemption is specified but not implemented (`scheduler-preemption`,
  requirements generated).

## Desired Outcome
- A project can own a guarantee: a resource amount (slots, hosts or any
  resource) or a pool of hosts.
- Idle guaranteed capacity may be borrowed by other projects' jobs.
- When an owner's pending job needs its guarantee back, borrowers are
  reclaimed (preempted, requeued or allowed to finish, by policy).
- Guarantee state and borrowing are visible (REST, `xcecli`, REPL).

## Approach
To be chosen in discovery when the spec starts. Candidates: LSF-style
guarantee service classes (`lsb.resources` GuaranteedResourcePool), or
guarantees as reserved virtual resources built on the limit/vres machinery
plus preemption.

## Scope
- **In**: guarantee model, borrowing, reclaim policy, visibility.
- **Out**: quotas (`project-config`), fairshare ordering, accounting/billing.

## Boundary Candidates
- Guarantee model and config.
- Scheduler accounting of owned vs borrowed usage.
- Reclaim through `scheduler-preemption`.

## Out of Boundary
- Project definitions and membership (`project-config`).

## Upstream / Downstream
- **Upstream**: `project-config`, `scheduler-preemption`, `job-config-merge`.
- **Downstream**: `lsf-config-migration` (guarantee pools).

## Existing Spec Touchpoints
- **Extends**: none.
- **Adjacent**: `scheduler-preemption`, `resource-distribution-mapping`.

## Constraints
- Scheduler driver equivalence (live and simulator identical).
- Touches scheduling policy and HA state: full 3-phase workflow.