# GAL-2 Daemon Time Contract v1 Specification Draft

Date: 2026-04-30
Status: Draft
Product surface: GAL-2 local daemon
Endpoint target: /contract
Core principle: Do not modify the production GAL-2 API or protected AWS core.

## 1. Purpose

The GAL-2 Daemon Time Contract v1 defines a local application-facing contract that tells software whether GAL-2-derived time is safe to consume.

This contract does not replace the GAL-2 API. The daemon must continue consuming and reconciling with the GAL-2 API because the protected GAL-2 core and fractal logic live there.

The daemon wraps the API output locally and exposes operational state, safety, continuity, validity, and policy metadata to applications.

Core thesis:

Separate the clock from the permission to use the clock.

Canonical framing:

Precision protects the reference.
GAL-2 protects the consumer.
IXOYE witnesses the governed layer.
UTC remains civil.
Digital systems operate on governed time.

## 2. Architecture

Current safe architecture:

GAL-2 API / protected core
↓
local GAL-2 daemon
↓
local Time Contract endpoint
↓
applications / legacy systems

The daemon must:

1. Use the GAL-2 API as the primary upstream source when available.
2. Store the last good API-derived state.
3. Continue locally during holdover using persisted API-derived state.
4. Reconcile with the API when connectivity returns.
5. Avoid backward movement in the application-facing path.
6. Expose contract state to consumers before they act.

## 3. Non-goals for v1

This v1 does not claim:

1. Replacement for UTC.
2. Replacement for GNSS, PTP, NTP, OCP TAP, chrony, Timebeat, OSA, atomic clocks, or hardware references.
3. Formal metrological traceability.
4. Nanosecond uncertainty.
5. Fully cryptographic IXOYE proof.
6. Public verifier tooling.
7. A complete Cloud API v2.
8. A universal solution to all Y2038 systems.

This v1 claims only:

A local daemon can expose governed application-facing time using API-derived GAL-2 state, local continuity, monotonic sequence, validity windows, and explicit safety semantics.

## 4. Existing daemon foundation observed

Current installed daemon:

version: 1.0.3-rc3
active local port: 9095
existing endpoints: /health, /now, /status

Observed current fields:

daemon_mode
daemon_cache_age_sec
daemon_last_ok
daemon_slew_remaining_sec
confidence
quota_status
requests_used
requests_limit
gal2_time
utc_time
source

Observed internal state fields:

last_ok
last_error
backoff
cache
anchor_gal2_epoch
anchor_utc_epoch
anchor_mono
last_served_epoch
slew_total_sec
slew_start_mono
slew_end_mono
slew_rate
last_live_gal2_epoch
last_live_utc_epoch
last_client_hit_monotonic
quota_status
quota_exhausted

Observed internal modes:

warming
live
holdover
slewing

## 5. Contract endpoint

New local endpoint:

/contract

Existing endpoints must remain compatible:

/now
/health
/status

/contract must return an atomic snapshot of daemon state.

Consumers should treat each /contract response as a single contract decision at local_serve_time.

## 6. Contract modes

Contract v1 modes:

WARMING
LIVE
DEGRADED
HOLDOVER
REJOIN
FAIL_CLOSED

Mapping from existing daemon modes:

warming  -> WARMING
live     -> LIVE
holdover -> HOLDOVER
slewing  -> REJOIN

DEGRADED and FAIL_CLOSED may be introduced as explicit contract-level modes even if the current daemon does not yet expose them as internal modes.

## 7. Field definitions

Minimum /contract response fields:

schema
version
mode
safe_to_consume
reason
health
gal2_time
utc_time
monotonic_sequence
last_good_sync
cache_age_seconds
api_latency_ms
local_receive_time
local_serve_time
valid_until
operational_bound_ms
rejoin_state
request_id
quota_status
source_lineage

### schema

String.

Example:

gal2-daemon-time-contract-v1

### version

Daemon contract version.

Example:

1.0.0-contract-draft

### mode

One of:

WARMING
LIVE
DEGRADED
HOLDOVER
REJOIN
FAIL_CLOSED

### safe_to_consume

Boolean.

Important:

safe_to_consume is not a raw claim from the API.
safe_to_consume is derived locally by the daemon.

It must be computed from:

mode
cache_age_seconds
api_latency_ms
last_good_sync
monotonic continuity
discontinuity detection
rejoin/slew state
valid_until
operational_bound_ms
quota_status
policy thresholds

### reason

Machine-readable reason code.

Examples:

fresh_api_sync
warming_no_cache
api_unreachable_holdover_within_policy
api_unreachable_holdover_expired
controlled_rejoin_slew_active
quota_exhausted
invalid_api_response
backward_step_blocked
contract_expired
latency_exceeded_policy
state_inconsistent

### health

One of:

green
yellow
red

Suggested interpretation:

green: contract is fresh and safe
yellow: contract is degraded or holdover but still inside policy
red: contract is unsafe or fail-closed

### gal2_time

The GAL-2 governed time exposed to the consumer.

Derived from API seed plus local daemon model.

### utc_time

UTC-equivalent or API-provided UTC comparison field.

UTC remains civil/reference comparison, not the sovereign operational layer.

### monotonic_sequence

Strictly increasing local sequence number for every /contract snapshot.

Purpose:

1. Consumers can detect replay, reset, repeated stale contracts, or gaps.
2. Logs can reconstruct ordering of contract decisions.
3. Contract-aware applications can fence operations.

v1 implementation note:

If current daemon does not yet persist a sequence counter, add contract_sequence to local state and persist it with the cache.

### last_good_sync

Timestamp of last successful GAL-2 API synchronization.

Current source:

_state["last_ok"]

### cache_age_seconds

Age in seconds since last_good_sync.

Current source:

cache_age_sec_unlocked()

### api_latency_ms

Measured round-trip latency for the most recent API fetch.

v1 implementation note:

Current daemon does not appear to persist API latency explicitly.
Add last_api_latency_ms to state during fetch_once().

### local_receive_time

Local UTC timestamp when the daemon received the API response.

v1 implementation note:

Add last_api_receive_time to state during fetch_once().

### local_serve_time

Local UTC timestamp when /contract was served.

### valid_until

Timestamp after which the contract must be considered invalid by consumers.

v1 semantics:

If local time is greater than valid_until, consumers must treat the contract as unsafe, regardless of gal2_time value.

### operational_bound_ms

Daemon-estimated operational bound in milliseconds.

This is not a formal metrology uncertainty claim.

It is an operational estimate based on policy, cache age, latency, holdover duration, rejoin state, and daemon health.

Avoid using uncertainty_ns in v1.

### rejoin_state

One of:

none
slewing
stable
blocked

Current source:

slew_start_mono, slew_end_mono, slew_remaining_sec

### request_id

Unique local contract response ID.

Example:

local-00000000000018422

### quota_status

Current API quota status.

Existing values:

ok
warning
critical
exhausted

### source_lineage

Human-readable lineage.

Example:

gal2_api -> local_daemon -> contract_v1

In v1, this is informational only.
Future versions may include signatures, IXOYE proof, or verifier references.

## 8. safe_to_consume v1 logic

safe_to_consume must be derived, not manually asserted.

### WARMING

Condition:

No cache or no anchor available.

Output:

safe_to_consume = false
health = red
reason = warming_no_cache

### LIVE

Conditions:

API has synchronized recently.
Cache is fresh according to policy.
No quota exhaustion.
No last_error.
No backward step required.
No invalid response.
No active severe discontinuity.

Output:

safe_to_consume = true
health = green
reason = fresh_api_sync

### DEGRADED

Conditions may include:

High API latency but still inside policy.
Jitter warning.
Cache approaching holdover threshold.
Non-fatal last_error with valid cache.
Quota warning or quota critical.

Output:

safe_to_consume may be true or false depending on policy.
health = yellow or red
reason must explain condition.

### HOLDOVER

Condition:

API unavailable or sync stale, but daemon has valid last good API-derived state.

Output while inside policy:

safe_to_consume = true
health = yellow
reason = api_unreachable_holdover_within_policy

Output after policy expires:

mode = FAIL_CLOSED
safe_to_consume = false
health = red
reason = api_unreachable_holdover_expired

### REJOIN

Condition:

API returns after holdover or after a discontinuity and daemon is reconciling through controlled slew.

Output:

safe_to_consume = true only if controlled slew is within policy.
Otherwise safe_to_consume = false.

reason examples:

controlled_rejoin_slew_active
rejoin_delta_exceeded_policy
rejoin_blocked

### FAIL_CLOSED

Conditions:

No valid cache.
Cache expired beyond hard policy.
Quota exhausted.
Backward movement would occur and cannot be safely clamped.
Invalid API response.
State inconsistency.
Contract expired.
Operational bound exceeds policy.

Output:

safe_to_consume = false
health = red

## 9. Policy parameters

Policy should be explicit and configurable.

Initial policy fields to define:

contract_live_valid_sec
contract_holdover_soft_sec
contract_holdover_hard_sec
contract_rejoin_max_delta_sec
contract_max_api_latency_ms
contract_operational_bound_green_ms
contract_operational_bound_yellow_ms
contract_operational_bound_red_ms

v1 default values must be conservative and documented before release.

Important:

Do not hide policy inside the binary without documentation.

## 10. Consumer obligations

A contract-aware consumer must:

1. Check safe_to_consume before critical time-dependent action.
2. Reject or pause critical action if safe_to_consume is false.
3. Treat expired valid_until as unsafe.
4. Track monotonic_sequence.
5. Record request_id in logs when using GAL-2 time.
6. Treat health=red as unsafe.
7. Decide application-specific behavior for health=yellow.

Suggested actions when unsafe:

pause
retry
degrade
fail closed
use approved fallback
alert operator

## 11. Evidence goal for v1

The first evidence package must prove this claim:

A consumer that respects the GAL-2 Time Contract behaves more safely than a consumer that blindly consumes raw time during a controlled timing failure.

Required first test:

LIVE -> HOLDOVER -> REJOIN -> FAIL_CLOSED

Required logs:

contract mode timeline
safe_to_consume timeline
monotonic_sequence
valid_until
cache_age_seconds
last_good_sync
api_latency_ms
local_receive_time
local_serve_time
operational_bound_ms
consumer behavior
raw consumer comparison

## 12. Red Light Test

Purpose:

Show that GAL-2 can tell software when not to consume time.

Test shape:

1. Start daemon in LIVE.
2. Run contract-aware consumer.
3. Run raw-time consumer.
4. Introduce controlled upstream/API failure or simulated stale condition.
5. Observe HOLDOVER.
6. Allow valid_until or hard policy to expire.
7. Observe FAIL_CLOSED.
8. Contract-aware consumer pauses or rejects action.
9. Raw-time consumer continues and demonstrates unsafe behavior.

Success criteria:

safe_to_consume transitions correctly.
monotonic_sequence never decreases.
valid_until is respected.
FAIL_CLOSED occurs when policy requires it.
Contract-aware consumer behaves safer than raw consumer.

## 13. Positioning

Safe public phrase:

Precision protects the reference. GAL-2 protects the consumer.

Safe technical phrase:

GAL-2 separates reference precision from application-facing trust.

Safe OCP/TAP phrase:

OCP/TAP protects reference-grade time to the host. GAL-2 exposes that quality and risk as a readable contract to applications before they act.

Safe commercial phrase:

Keep your timing stack. Add GAL-2.

## 14. Evidence positioning

Y2038 DOI:

Use as application-facing continuity evidence.
Do not claim it proves metrology or complete Y2038 remediation.

Mac bridge:

Use as architecture and legacy compatibility precedent.
Do not claim it proves formal accuracy or traceability.

IXOYE:

Use as live public witness surface today.
Cryptographic proof, public verifier, anchoring, and independent witness posture are roadmap.

## 15. Implementation rule

Do not modify the production GAL-2 API or protected AWS core for v1.

Implement /contract in the daemon first.

The daemon must continue consuming and reconciling with the GAL-2 API.

