---
layer: Tooling
---

# INTENT — Railiance Clock

Status: founding intent, adopted for repository development on 2026-09-14.
A private host deployment was recorded on 2026-09-15; broader cross-owner
security adoption remains gated by RCLK-WP-0002/0004/0005.

Layer declaration follows the NetKingdom owner review against accepted v0.7.
No Engine/PIP or PEP role is declared; a named decision consumer requires
gate-house review. See [owner rulings and remaining gates](docs/closeout-review-2026-09-28.md).

## Purpose

Railiance Clock provides an authenticated, uncertainty-aware estimate of Railiance
UTC to services and attached workstations without taking control of clocks owned
by another organization. It makes time-dependent operations explainable across
independently managed environments.

Railiance must work with corporate Windows hosts, Linux/WSL guests, roaming
laptops, suspended sessions and remote services. A workstation may be forbidden
or unable to synchronize its OS clock to Railiance. Requiring it to do so is not
a viable application contract.

## Intended outcome

A consumer can ask what time Railiance currently has reason to believe it is,
learn the estimate's uncertainty, freshness and authority, and use that evidence
under the consumer's own reviewed validity policy. A historical event can retain
its original local timestamp alongside a separately attributed Railiance receipt
or estimated event time. Uncertainty is visible rather than hidden in a timestamp.

The initial authority is intended to run on railiance01, disciplined to external
UTC sources. Railiance time is a trusted estimate of UTC, not a new time zone or
an arbitrary counter. Authority health, upstream independence and rollback must
be observed; a host name alone does not establish trustworthy time.

Forgejo is the durable home for reviewed source, policies, work records and
selected evidence. Forgejo commit dates, request headers and commit ordering do
not establish UTC accuracy, credential lifetime or the occurrence time of an event.
This distinction refines the founding idea of Forgejo as timekeeper.

## Principles

1. Preserve corporate OS time management. Offer a process-local clock interface;
   never silently set Windows, WSL or Linux wall clocks.
2. Report a time interval, provenance and quality state. Precision of formatting
   must not imply accuracy. Every claimed bound states its assumptions.
3. Anchor accepted time samples to a monotonic clock; use elapsed time for local
   durations. Detect or invalidate clock domains across restart and suspend.
4. Authenticate the authority and freshness of each sample. A signed old sample
   is not fresh time, and a valid TLS channel does not prove the server clock is right.
5. Preserve signed validity fields and original observations. Translation appends
   an estimate; it does not rewrite an artifact or retroactively make it valid.
6. Keep privileged validity decisions and execution on disciplined Railiance
   hosts where practical. Local consumer adoption is an explicit owner contract.
7. Never become an identity provider, policy decision point, approval issuer,
   credential broker, causal-order authority or a replacement for audit-core.
8. Respect independent authority: discovery, repository registration, deployment
   admission, authorization and proven operational readiness are different facts.

## Service boundaries

This repository owns the time-sample protocol, uncertainty semantics, application
clock interface, reference implementation and conformance tests. Host discipline
and networking remain with infrastructure owners. Keys and trust distribution
consume existing NetKingdom ownership. Deployment packaging and exposure follow
Railiance architecture. Security consumers own the decision to accept this clock
and the lifetime policy applied to artifacts.

## Success criteria

- Managed corporate workstation and deliberately skewed guest obtain a usable
  Railiance clock without any OS time change.
- Loss of authority, stale/replayed samples, uncertainty overflow, reboot,
  suspend/resume and authority clock discontinuities produce explicit states.
- A supported consumer accepts or refuses boundary cases conservatively under
  an adopted contract, while wrong signatures and expired artifacts still fail.
- Event records preserve local provenance and receipt time without inventing
  exact occurrence time or global ordering.
- A railiance01 pilot publishes measured behavior, authority health and recovery
  evidence; unresolved assumptions remain in live workplans.

## Non-goals

Changing corporate AD/NTP policy; bypassing TLS/Kerberos/browser checks; widening
JWT leeway to hide bad time; trusting a timestamp just because it came from
Forgejo; rewriting Git history; executing paid model trials; deploying a public
NTP reflector; inventing a new security engine or universal total event order.