# Identifiers and Versioning Schema Contract

**Status:** Approved target-state baseline  
**First realization:** I0.

## Target State

All first-class AWP primitives have opaque stable IDs and explicit revisions/versioning where mutable state or serialized contracts require it.

## ID Contract

Conceptually:

```text
ProjectId
RepositoryId
PlanId
PlanRevisionId
TaskId
FactoryRunId
AgentRunId
AttemptId
WorkspaceId
ChangeSetId
ReviewId
CIExecutionId
EvidenceId
DecisionId
ApprovalId
ArtifactId
ReleaseId
EnvironmentId
DeploymentId
ClusterId
MachineId
IncidentId
ConnectionId
...
```

IDs are nominal/typed in TypeScript contracts to prevent accidental cross-primitive substitution. Exact encoding (UUIDv7/ULID/etc.) may be selected at implementation if ordering/security/DB needs do not change semantics.

## Provider References

Provider-native IDs are stored separately:

```text
ProviderReference {
  providerId
  accountId?
  resourceType
  nativeId
  nativeRevision?
  url?
  observedAt
}
```

No provider native ID becomes sole primary identity.

## Revision Types

Distinguish:

```text
resourceRevision      optimistic concurrency / mutable aggregate revision
schemaVersion         serialized DTO/event/config schema format
contentDigest         immutable source/artifact/candidate identity
providerRevision      provider-specific observed version/etag/sha
planRevisionId        semantic accepted Plan snapshot identity
```

Do not overload one `version` field for all meanings.

## Correlation / Causation

Lifecycle commands/workflows/events use correlation IDs and, when useful, causation IDs. Attempts/CI/Deployments have their own stable IDs even when sharing one high-level correlation.

## Idempotency

Retriable externally initiated mutations accept or derive an idempotency operation key. Idempotency scope is documented per command and cannot silently coalesce two different desired operations.

## Time

Persist timestamps as timezone-unambiguous UTC instants plus user timezone/local scheduling intent where relevant. Scheduled Plan launches retain timezone/owner intent, not only converted UTC.

## Compatibility

Typed ID meanings are stable. Encoding changes require migration/versioning and cannot break external contracts once declared stable. Additive fields follow schema-family compatibility policy.

## Increment Realization

I0 implements ID/revision/correlation conventions. Later domains add typed IDs without changing base rules.

## Acceptance

No API/database/provider adapter confuses a mutable ref, provider ID, resource revision or immutable digest with AWP primitive identity.