<!-- Generated from sources/conventions/v1/aeon-gp-temporal-v1.aeon; do not edit. -->

<a id="aeon-gp-temporal-v1"></a>
# AEON GP Temporal v1

Convention identifier: `aeon.gp.temporal.v1`

---

<a id="purpose"></a>
## 1. Purpose

`aeon.gp.temporal.v1` defines a standard interpretation vocabulary for AEON temporal literals and the temporal-reference payload carried by Core `wtc` literals.

It applies to ordinary Core temporal literal families such as:

- `date`
- `time`
- `datetime`
- `wtc`
- convention- or profile-defined duration representations

The convention separates:

| Concern | Responsibility |
| :--- | :--- |
| Temporal literal form | AEON Core value syntax |
| WTC temporal-reference form and preservation | AEON Core value syntax |
| Temporal interpretation policy | `aeon.gp.temporal.v1` metadata |
| Materialization and execution | Tonics, profiles, processors, or host runtimes |

*Temporal convention responsibilities*

This convention does not extend AEON Core syntax and does not make runtime scheduling, timezone conversion, geographic resolution, or calendar conversion behavior mandatory.

Documents using this convention should declare it in the header:

```aeon
aeon:header = {
  conventions = [
    "aeon.gp.temporal.v1"
  ]
}
```

---

<a id="design-intent"></a>
## 2. Design Intent

Modern temporal data often combines several independent concerns:

- UTC instants
- floating or local civil times
- geopolitical time zones
- daylight-saving ambiguity
- historical timezone database drift
- calendar systems
- offset conflict handling
- named, resolver-local, and geographic WTC references

`aeon.gp.temporal.v1` represents those concerns structurally with metadata rather than overloading timestamp punctuation.

Example:

```aeon
meeting@{
  target = "zone"
  zone = "Australia/Melbourne"
  calendar = "iso8601"
  tzdbDatum:date = 2026-05-10
  tzdbVersion = "2026b"
  disambiguation = "reject"
}:datetime = 2026-06-06T10:10:00
```

The literal remains an ordinary `datetime`; the convention metadata states how a cooperating consumer should interpret it.

WTC can instead carry temporal context directly in the Core value:

```aeon
localMeeting:wtc = 2026-06-06T10:10:00&local
zonedMeeting:wtc = 2026-06-06T10:10:00+10:00&Australia/Melbourne
observedAt:wtc = 2026-06-06T00:10:00Z&-37.8136/144.9631/31
```

The temporal-value form and temporal-reference payload are independent preserved inputs. Resolution and conflict decisions belong to the consumer.

---

<a id="scope"></a>
## 3. Scope

This convention defines temporal interpretation metadata.

It does not define:

- new Core temporal literal syntax
- a new Core `duration` literal
- timezone database contents
- canonical temporal serialization
- runtime scheduling behavior
- host-language temporal object materialization
- timezone or geographic-reference resolution
- civil-time jurisdiction selection from coordinates
- geodetic transformation

Consumers that do not understand this convention should preserve the attributes as ordinary AEON metadata or fail according to their convention-adoption policy.

---

<a id="fields"></a>
## 4. Fields

The following attribute keys are defined by `aeon.gp.temporal.v1`.

<a id="target"></a>
### 4.1 `target`

`target` identifies the intended temporal interpretation mode for temporal values that do not already carry an intrinsic WTC reference.

Allowed values:

| Value | Meaning |
| :--- | :--- |
| `"utc"` | Interpret as a universal instant |
| `"local"` | Interpret as a floating/local civil time |
| `"zone"` | Interpret as a regional civil time in a named zone |

*Temporal target values*

Examples:

```aeon
created@{
  target = "utc"
}:datetime = 2026-06-06T10:10:00Z
```

```aeon
alarm@{
  target = "local"
}:datetime = 2026-06-06T09:00:00
```

```aeon
meeting@{
  target = "zone"
  zone = "Australia/Melbourne"
}:datetime = 2026-06-06T10:10:00
```

For `wtc`, the intrinsic reference remains authoritative input. Consumers MUST NOT silently replace it with `target` metadata.

<a id="zone"></a>
### 4.2 `zone`

`zone` identifies an authoritative regional timezone supplied as metadata.

```aeon
zone = "Australia/Melbourne"
```

Rules:

- values SHOULD be IANA timezone database identifiers;
- consumers applying `zone` MUST fail if the zone is unknown;
- consumers MUST NOT silently substitute an equivalent or nearby zone.

When a `wtc` literal also carries a temporal reference, any disagreement between `zone` and that reference is a conflict governed by the consumer's `conflictAuthority` policy.

<a id="calendar"></a>
### 4.3 `calendar`

`calendar` identifies the calendar system used to interpret the temporal value.

Examples:

```aeon
calendar = "iso8601"
calendar = "gregorian"
calendar = "japanese"
calendar = "hebrew"
```

If omitted, consumers MAY assume `iso8601`. A profile or schema MAY require explicit calendar metadata.

<a id="tzdbdatum"></a>
### 4.4 `tzdbDatum`

`tzdbDatum` records the date of timezone database assumptions used by the producer.

```aeon
tzdbDatum:date = 2026-05-10
```

This field improves reproducibility and helps future processors detect possible timezone rule drift. It does not pin an exact timezone database version.

<a id="tzdbversion"></a>
### 4.5 `tzdbVersion`

`tzdbVersion` records the timezone database release identifier used by the producer.

```aeon
tzdbVersion = "2026b"
```

Values SHOULD use IANA Time Zone Database release labels when the producer can identify the source rule set. This field improves reproducibility when timezone rules change after the document is produced.

<a id="disambiguation"></a>
### 4.6 `disambiguation`

`disambiguation` states how ambiguous or invalid local times should be handled.

Allowed values:

| Value | Meaning |
| :--- | :--- |
| `"earlier"` | Choose the earlier valid instant |
| `"later"` | Choose the later valid instant |
| `"reject"` | Fail on ambiguity or invalid local time |

*Temporal disambiguation values*

Example:

```aeon
event@{
  target = "zone"
  zone = "Australia/Melbourne"
  disambiguation = "reject"
}:datetime = 2025-04-06T02:30:00
```

<a id="offset"></a>
### 4.7 `offset`

`offset` records an offset associated with the value.

```aeon
offset = "+10:00"
```

This field is informational unless another selected profile, schema, or tonic defines stronger behavior.

An explicit numeric offset or `Z` embedded in a `wtc` temporal value is intrinsic representation, not this metadata field. A disagreement between intrinsic and supplemental offset inputs is governed by the consumer's `conflictAuthority` policy.

<a id="apply"></a>
### 4.8 `apply`

`apply` lists target projection zones for display or transformation workflows.

```aeon
apply = [
  "Australia/Perth"
  "Europe/Paris"
]
```

This field does not define execution semantics.

<a id="consumer-conflict-policy"></a>
## 5. Consumer Conflict Policy

`conflictAuthority` is a consumer policy for handling inconsistent temporal inputs. It is not an AEON attribute defined by this convention and is not document-controlled execution authority.

Allowed values:

| Value | Meaning |
| :--- | :--- |
| `"reject"` | Reject inconsistent inputs. |
| `"temporal"` | Treat the temporal value, including an intrinsic offset or `Z`, as authoritative. |
| `"reference"` | Treat the WTC temporal reference or convention metadata selected by the consumer as authoritative. |
| `"preserve"` | Preserve the conflict without resolving it. |

*Temporal conflict-authority values*

A consumer performing authoritative temporal resolution MUST default to `"reject"` unless trusted host, profile, schema, or runtime configuration selects another value. Parsing, canonicalization, forwarding, and other preservation-only operations MAY retain conflicting inputs without selecting an authority. An arbitrary document MUST NOT grant itself conflict-resolution authority merely by carrying an attribute with this name.

---

<a id="fail-closed-guidance"></a>
## 6. Fail-Closed Guidance

Consumers applying this convention SHOULD fail when:

- timezone identifiers are unknown;
- ambiguous or invalid local times violate the selected policy;
- required metadata is missing;
- calendar systems are unsupported;
- temporal inputs conflict under `conflictAuthority = "reject"`.

Consumers MUST NOT silently reinterpret temporal intent.

---

<a id="relationship-to-core-temporal-types"></a>
## 7. Relationship to Core Temporal Types

AEON Core v1 owns the literal syntax for `date`, `time`, `datetime`, and `wtc`.

`aeon.gp.temporal.v1` does not change those literal forms. It defines shared interpretation defaults around them.

A Core `wtc` value is a temporal value followed by `&` and a temporal reference. The reserved resolver-local reference is exactly lowercase `local`; case variants such as `Local` and `LOCAL` are invalid. Other named references retain their authored case.

WTC preserves three temporal-value forms:

- civil-anchored: no offset designator, for example `2026-06-06T10:10:00&local`;
- offset-qualified: an explicit numeric offset, for example `2026-06-06T10:10:00+10:00&Australia/Melbourne`;
- UTC-qualified: uppercase `Z`, for example `2026-06-06T00:10:00Z&Australia/Melbourne`.

Offset-qualified and UTC-qualified forms identify exact instants, but they remain lexically distinct and MUST NOT be rewritten merely because they resolve to the same instant.

A WTC temporal reference may be:

- exact lowercase `local`;
- a named reference such as `Australia/Melbourne`;
- a geographic reference in `latitude/longitude` or `latitude/longitude/height` component order.

Unless an active trusted convention or profile overrides the interpretation, geographic components use WGS 84 latitude and longitude in decimal degrees and optional WGS 84 ellipsoidal height in metres. Core recognizes and preserves the component payload but does not validate coordinate ranges, perform geodetic resolution, or select a civil-time jurisdiction. Specialized coordinate reference systems, coordinate epochs, and vertical references require a separate spatial convention or profile.

Parsers, canonicalizers, and preservation-only processors MUST preserve both the authored temporal-value form and the temporal-reference payload. Consumers may interpret or resolve them only under an explicit policy.

Duration semantics remain outside AEON Core v1. When duration-like values are needed, they are schema-, profile-, convention-, or consumer-defined.

---

<a id="relationship-to-future-zdt"></a>
## 8. Relationship to Future `zdt`

The datatype label `zdt` is reserved for a possible future zoned datetime type.

`zdt` is not operational in AEON Core v1. This convention does not require processors to accept `:zdt`, and it does not define bracketed zoned-datetime lexical syntax.

Future AEON versions or profiles may define a transport-oriented `zdt` type. It would not replace Core `wtc` or authorize rewriting preserved WTC forms. The temporal convention remains orthogonal to that possibility because it represents timezone, calendar, ambiguity, and projection metadata structurally.

Possible future example:

```aeon
created:zdt = 2025-01-01T12:00:00+11:00[Australia/Melbourne][u-ca=japanese]
```

The example above is reserved future syntax, not AEON Core v1 syntax.

---

<a id="related-standards"></a>
## 9. Related Standards

This convention is conceptually compatible with:

- RFC 3339
- RFC 9557
- Java `ZonedDateTime`
- JavaScript `Temporal`

It does not require AEON Core to adopt bracketed zone annotations, inline calendar annotations, or any specific host-runtime temporal object model.

---

## Related documents

- [AEON Conventions Overview](./aeon-conventions-overview.md)
- [AEON v1 Value Types Reference](./aeon-core-v1-value-types.md)