# StellaOps Contracts

This directory contains formal contract specifications for cross-module interfaces. These contracts define the data models, APIs, and integration points used throughout StellaOps.

## Purpose

Contracts serve as the authoritative source for:
- Data model definitions (request/response shapes)
- API endpoint specifications
- Integration requirements between modules
- Dependency documentation for sprint planning

## Contract Index

| Contract | ID | Unblocks | Status |
|----------|-----|----------|--------|
| [Advisory Key](./advisory-key.md) | CONTRACT-ADVISORY-KEY-001 | 6+ tasks | Published |
| [Risk Scoring](./risk-scoring.md) | CONTRACT-RISK-SCORING-002 | 5+ tasks | Published |
| [Mirror Bundle](./mirror-bundle.md) | CONTRACT-MIRROR-BUNDLE-003 | 8+ tasks | Published |
| [Sealed Mode](./sealed-mode.md) | CONTRACT-SEALED-MODE-004 | 4+ tasks | Published |
| [VEX Lens](./vex-lens.md) | CONTRACT-VEX-LENS-005 | 2+ tasks | Published |
| [Verification Policy](./verification-policy.md) | CONTRACT-VERIFICATION-POLICY-006 | 4+ tasks | Published |
| [Policy Studio](./policy-studio.md) | CONTRACT-POLICY-STUDIO-007 | 3+ tasks | Published |
| [Authority Effective Write](./authority-effective-write.md) | CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008 | 2+ tasks | Published |
| [Export Bundle](./export-bundle.md) | CONTRACT-EXPORT-BUNDLE-009 | 1+ tasks | Published |
| [Crypto Provider Registry](./crypto-provider-registry.md) | CONTRACT-CRYPTO-PROVIDER-REGISTRY-010 | 1+ tasks | Published |
| [Findings Ledger RLS](./findings-ledger-rls.md) | CONTRACT-FINDINGS-LEDGER-RLS-011 | 2 tasks | Published |
| [API Governance Baseline](./api-governance-baseline.md) | CONTRACT-API-GOVERNANCE-BASELINE-012 | 10+ tasks | Published |
| [Scanner PHP Analyzer](./scanner-php-analyzer.md) | CONTRACT-SCANNER-PHP-ANALYZER-013 | 1 task | Published |
| [Scanner Surface](./scanner-surface.md) | CONTRACT-SCANNER-SURFACE-014 | 1 task | Published |
| [RichGraph v1](./richgraph-v1.md) | CONTRACT-RICHGRAPH-V1-015 | 40+ tasks | Published |

## Contract Categories

### Core Data Models
- [Advisory Key](./advisory-key.md) - Vulnerability ID canonicalization
- [VEX Lens](./vex-lens.md) - VEX observation correlation
- [Risk Scoring](./risk-scoring.md) - Finding prioritization

### Air-Gap / Offline
- [Mirror Bundle](./mirror-bundle.md) - Bundle format for offline transport
- [Sealed Mode](./sealed-mode.md) - Sealed environment operation

### Security / Attestation
- [Verification Policy](./verification-policy.md) - Attestation verification rules
- [Crypto Provider Registry](./crypto-provider-registry.md) - Pluggable crypto

### Policy Management
- [Policy Studio](./policy-studio.md) - Policy editing and compilation
- [Authority Effective Write](./authority-effective-write.md) - Policy attachment

### Export
- [Export Bundle](./export-bundle.md) - Scheduled export jobs

### Tenancy / Database
- [Findings Ledger RLS](./findings-ledger-rls.md) - Row-Level Security and partitioning

### SDK & API Governance
- [API Governance Baseline](./api-governance-baseline.md) - OpenAPI freeze and SDK generation

### Scanner
- [Scanner PHP Analyzer](./scanner-php-analyzer.md) - PHP language analyzer bootstrap
- [Scanner Surface](./scanner-surface.md) - Surface analysis framework

### Reachability / Evidence
- [RichGraph v1](./richgraph-v1.md) - Function-level reachability graph schema

## Related Resources

### API Documentation
- [Policy API](../api/policy.md)
- [Graph API](../api/graph.md)

### Module Architecture
- [Excititor Architecture](../modules/excititor/architecture.md)
- [Policy Engine Architecture](../modules/policy/architecture.md)
- [Attestor Architecture](../modules/attestor/architecture.md)
- [AirGap Documentation](../airgap/README.md)

### JSON Schemas
- [Mirror Bundle Schema](../schemas/mirror-bundle.schema.json)
- [Verification Policy Schema](../../src/Attestor/StellaOps.Attestor.Types/schemas/verification-policy.v1.schema.json)
- [Risk Profile Schema](../../src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-risk-profile.v1.schema.json)

## Contract Lifecycle

1. **Draft** - Contract under development
2. **Published** - Contract is stable and ready for implementation
3. **Deprecated** - Contract is being phased out
4. **Retired** - Contract is no longer valid

## Contributing

When updating contracts:
1. Increment version number
2. Update `Last Updated` date
3. Document breaking changes
4. Update `Unblocks` section if tasks change
5. Add cross-references to related contracts

## Sprint Integration

Contracts unblock BLOCKED tasks in sprint files. When a contract is published:
1. Update the sprint file task status from `BLOCKED` to `TODO`
2. Add note: `Unblocked by CONTRACT-xxx (docs/contracts/xxx.md)`
3. Remove the blocked reason