# ADR-009: Canonical Resource Identifier Format

## Status
Accepted

## Date
2026-03-02

## Author
GPUaaS Core Team

## Context
The platform currently uses UUIDs and local identifiers across APIs, logs, and
events. Without one canonical identifier shape, cross-service correlation,
policy matching, and incident tooling become inconsistent and fragile.

We need a stable identifier model that:
- is machine-friendly,
- preserves tenant/project ownership context,
- scales across products under Core42 AI Cloud.

## Decision
Adopt one canonical resource identifier format:

```
core42:aicloud:{region}:{tenant_id}:{project_id}:{resource_type}:{resource_id}
```

With these constraints:
1. Namespace is `core42`.
2. Platform is `aicloud`.
3. `tenant_id` and `project_id` are mandatory for tenant-owned resources.
4. `resource_type` is service-qualified (`gpuaas/allocation`, etc.).
5. Identifier is external-facing and immutable, but not used as primary DB key.
6. Parser/formatter behavior is centralized in a shared library to avoid drift.

## Consequences
### Positive
- Unified addressing across API, events, audit, and policy inputs.
- Cleaner incident triage and automation by deterministic ID shape.
- Future OPA/policy integration can match on canonical strings and structured fields.

### Tradeoffs
- Requires service boundary updates to emit the canonical identifier.
- Requires type-registry discipline for `resource_type` growth.
- Requires encoding rules for path-like IDs.

## Alternatives Considered
1. Keep per-service local IDs only:
   - rejected; increases cross-service ambiguity and policy coupling.
2. AWS ARN clone:
   - rejected; shape inspiration is useful, but platform namespace should remain
     first-party (`core42:aicloud`) and semantics should match our ownership model.
3. Opaque random global IDs:
   - rejected; loses tenant/project context and weakens policy/debug utility.

## References
- `doc/architecture/Resource_Identifier_Spec.md`
- `doc/architecture/Tenant_Project_Ownership_Baseline.md`
- `doc/architecture/adrs/ADR-008-tenant-project-ownership-baseline.md`