Home /Modules/advantage/SLClockConnector.sleela

SLClockConnector.sleela

lib/advantage/connect/SLClockConnector.sleela · 168 line(s) · sleela

<< lib/advantage/connect/SLClockConnector.sleela
   SLeeLa Standard Library Definition.
   Definition: The national-clock / NTP connector of the CONNECT medium. It
   models a disciplined time source: a named authority (e.g. a national
   metrology institute time service), an NTP stratum, a clock offset estimate,
   and a validity window. The live sync defers to a host adapter (slntp_*). >>
#sleela 3.0
material;
artifact;
pure;
gasoline;
<< NATIVE BRIDGE (documented, not dialed).
   open  -> slntp_open(authorityHost) : handle
   sync  -> slntp_sync(handle) : {offsetMillis, stratum, roundTripMillis}
   now   -> slntp_now(handle) : epochMillis (disciplined)
   close -> slntp_close(handle)
   A "national clock" is just an authoritative stratum-1/2 NTP server operated
   by a metrology authority; the connector does not endorse any particular
   authority, it only records which one was configured. Offset is the estimated
   correction local - true, in milliseconds. No apostrophes in comments. >>
class SLClockConnector {
  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  String metaVersion = "1.0.0";
  int metaId = 10643;
  String metaAuthor = "Kiro Agent";
  String metaDate = "2026-11-08";
  String metaCopyright = "SLeeLa project";
  String metaTrademark = "Advantage";
  String metaCorporation = "SLeeLa project";
  < metaOrigin: National | <nation> | International | Galactic >
  String metaOrigin = "International";
  String metaBirthDate = "2026-11-08";
  int metaScienceRating = 7;
  << metaNationalSchedule: NTPv4 is IETF RFC 5905; the referenced time scale is
     UTC as maintained by the BIPM and disseminated by national metrology
     institutes. >>
  String metaNationalSchedule = "IETF RFC 5905 (NTPv4)";

  String getMetaVersion() { return metaVersion; }
  void setMetaVersion(String v) { metaVersion = v; }
  int getMetaId() { return metaId; }
  void setMetaId(int v) { metaId = v; }
  String getAuthor() { return metaAuthor; }
  void setAuthor(String v) { metaAuthor = v; }
  String getDate() { return metaDate; }
  void setDate(String v) { metaDate = v; }
  String getCopyright() { return metaCopyright; }
  void setCopyright(String v) { metaCopyright = v; }
  String getTrademark() { return metaTrademark; }
  void setTrademark(String v) { metaTrademark = v; }
  String getCorporation() { return metaCorporation; }
  void setCorporation(String v) { metaCorporation = v; }
  String getOrigin() { return metaOrigin; }
  void setOrigin(String v) { metaOrigin = v; }
  String getBirthDate() { return metaBirthDate; }
  void setBirthDate(String v) { metaBirthDate = v; }
  int getScienceRating() { return metaScienceRating; }
  void setScienceRating(int v) { metaScienceRating = v; }
  String getNationalSchedule() { return metaNationalSchedule; }
  void setNationalSchedule(String v) { metaNationalSchedule = v; }

  < ---- Shared medium plumbing ---- >
  SLConnectStatus vocab;
  SLConnectFault fault;

  < ---- Clock state ---- >
  String authority = "";
  boolean configured = false;
  boolean open = false;
  boolean synced = false;
  < last estimated offset (local - true) in milliseconds >
  double offsetMillis = 0.0;
  < NTP stratum of the authority (1 best; 16 unsynchronized) >
  int stratum = 16;
  int syncCount = 0;

  void init() {
    vocab = new SLConnectStatus();
    fault = new SLConnectFault();
  }

  int configure(String authorityHost) {
    if (vocab == null) { init(); }
    fault.clear();
    if (authorityHost == null || authorityHost == "") {
      fault.raise(vocab, vocab.invalidArgument(), "clock", "configure", "no authority");
      return vocab.invalidArgument();
    }
    authority = authorityHost;
    configured = true;
    return vocab.ok();
  }

  int openLink() {
    if (vocab == null) { init(); }
    fault.clear();
    if (!configured) {
      fault.raise(vocab, vocab.notConfigured(), "clock", "openLink", "configure first");
      return vocab.notConfigured();
    }
    open = true;
    return vocab.ok();
  }

  << Discipline the clock (native: slntp_sync). In the VM a sync cannot measure
     a real offset, so it defers to the adapter and returns
     NATIVE_ADAPTER_REQUIRED, leaving stratum at its unsynchronized value. A
     host adapter fills offsetMillis / stratum from slntp_sync and calls
     acceptSync(). >>
  int sync() {
    if (vocab == null) { init(); }
    fault.clear();
    if (!open) {
      fault.raise(vocab, vocab.invalidState(), "clock", "sync", "link not open");
      return vocab.invalidState();
    }
    syncCount = syncCount + 1;
    fault.raise(vocab, vocab.nativeAdapterRequired(), "clock", "sync", "adapter runs slntp_sync");
    return vocab.nativeAdapterRequired();
  }

  < Host-adapter callback: record a measured discipline result. >
  int acceptSync(double offset, int str) {
    if (vocab == null) { init(); }
    fault.clear();
    if (str < 1 || str > 16) {
      fault.raise(vocab, vocab.protocol(), "clock", "acceptSync", "stratum out of range");
      return vocab.protocol();
    }
    offsetMillis = offset;
    stratum = str;
    synced = true;
    return vocab.ok();
  }

  < Correct a local epoch-millis reading by the last measured offset. >
  double discipline(double localEpochMillis) {
    return localEpochMillis - offsetMillis;
  }

  < True when the authority is trustworthy enough to rely on (synced and a >
  < stratum at or below the accepted ceiling). >
  boolean trusted(int stratumCeiling) {
    if (!synced) { return false; }
    return stratum <= stratumCeiling;
  }

  int closeLink() {
    if (vocab == null) { init(); }
    fault.clear();
    open = false;
    return vocab.ok();
  }

  boolean active() { return open; }
  boolean isSynced() { return synced; }
  int getStratum() { return stratum; }
  double getOffsetMillis() { return offsetMillis; }
  boolean isNativeReady() { return false; }
  SLConnectFault lastFault() { if (vocab == null) { init(); } return fault; }

  String describe() {
    return "ClockConnector[" + authority + "] open=" + open
         + " synced=" + synced + " stratum=" + stratum
         + " offsetMs=" + offsetMillis;
  }
}