Home /Modules/opcodes/SLGovernedExecution.sleela

SLGovernedExecution.sleela

lib/opcodes/governance/SLGovernedExecution.sleela · 180 line(s) · sleela

<< lib/opcodes/governance/SLGovernedExecution.sleela
   SLeeLa Standard Library Definition.
   Definition: Defines SLGovernedExecution, the orchestrator that runs an opcode
     stream under the discretion of the Registrar, Listener, and EventObserver so
     that opcodes are not run raw into the VM without consideration.
   
   The discretion the user asked for, in one place:
     A developer MAY run opcodes raw via SLOpcodeStream.run(). Usually, though, a
     program is handed to a Registrar that considers it A -> B BEFORE running; a
     Listener watches the live VM code DURING; and an EventObserver judges the
     whole as a musical, ordered process AFTER. SLeeLa and the VM both know to
     listen for ordering at these three phases.
   
   Flow:
     BEFORE: Registrar.consider(stream)
             - REJECT  -> refuse, do not run.
             - PAUSE   -> hold as unrest, do not run (await resolution).
             - ADMIT   -> proceed to DURING.
     DURING: for each opcode as the VM reaches it:
               Listener.observe(op, liveIp, index)
               - REJECT -> stop and refuse.
               - PAUSE  -> stop and hold as unrest.
               - WARN   -> record and continue.
               - ADMIT  -> continue.
               then the opcode fires on the VM.
             Listener.settle() closes DURING.
     AFTER:  EventObserver.assess(stream, flaggedFlaw)
             - may ADMIT / WARN / PATCH / PAUSE / REJECT.
   
   Family: opcodes.governance. Native VM/OS work crosses an explicit bridge. >>
#sleela 2.5
material;
< Unified SLeeLa standard-library front-end object. >
class SLGovernedExecution {
  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  << Eleven catalogued attributes with getter/setter pairs, so a GUI, loader,
     or catalog can read and (where appropriate) override this record.
     Values are faithful to the subject's real origin where publicly known. >>
  String metaVersion = "1.0.0";
  int metaId = 10079;
  String metaAuthor = "Kiro Agent";
  String metaDate = "2026-10-16";
  String metaCopyright = "SLeeLa project";
  String metaTrademark = "none";
  String metaCorporation = "none";
  < metaOrigin: National | <nation> | International | Galactic >
  String metaOrigin = "International";
  String metaBirthDate = "2026-10-05";
  < metaScienceRating: maturity/robustness on a 1..10 scale >
  int metaScienceRating = 9;
  < metaNationalSchedule: a real, citable instrument or "none" >
  String metaNationalSchedule = "none";

  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; }
  SLOpcodeStream stream;
  SLOpcodeRegistrar registrar;
  SLOpcodeListener listener;
  SLOpcodeEventObserver observer;

  int state;
  int warnings;
  SLGovVerdict beforeVerdict;
  SLGovVerdict duringVerdict;
  SLGovVerdict afterVerdict;
  String haltReason;

  void configure(SLOpcodeStream program,
                 SLOpcodeRegistrar reg,
                 SLOpcodeListener lis,
                 SLOpcodeEventObserver obs) {
    stream = program;
    registrar = reg;
    listener = lis;
    observer = obs;
    state = 1;
    warnings = 0;
    haltReason = "";
  }

  boolean active() { return state == 1; }
  int warningCount() { return warnings; }

  < Notify both SLeeLa and the VM that a governance phase is beginning. The >
  < native bridge lets the VM register its interest so it, too, listens for >
  < ordering at BEFORE / DURING / AFTER. >
  void announce(int phase) {
    native sleela_gov_announce_phase(phase);
  }

  < Run the program under full governance. Returns the final VM instruction >
  < pointer on success, or a negative value when a phase blocked execution. >
  int run() {
    if (!active() || stream == null) { return -1; }

    < ---- BEFORE ---- >
    announce(SLGovPhase.BEFORE);
    beforeVerdict = registrar.consider(stream);
    if (beforeVerdict.blocks()) {
      haltReason = beforeVerdict.why();
      < rejected or paused as unrest; nothing runs >
      return -1;
    }

    < ---- DURING ---- >
    announce(SLGovPhase.DURING);
    int ip = 0;
    int n = stream.size();
    for (int i = 0; i < n; i = i + 1) {
      SLOpcodeBase op = stream.ops[i];

      < The Listener hears the live VM code before the opcode is allowed to fire. >
      int liveIp = native sleela_gov_live_ip(stream.frame, i);
      duringVerdict = listener.observe(op, liveIp, i);
      if (duringVerdict.blocks()) {
        haltReason = duringVerdict.why();
        return -1;
      }
      if (duringVerdict.value() == SLGovVerdict.WARN) { warnings = warnings + 1; }

      < Admitted: fire exactly this one opcode on the VM. >
      ip = op.step(stream.frame);
      < OP_HALT or VM rejection ends DURING >
      if (ip < 0) { break; }
    }

    SLGovVerdict settled = listener.settle();
    if (settled.blocks()) {
      haltReason = settled.why();
      return -1;
    }
    if (settled.value() == SLGovVerdict.WARN) { warnings = warnings + 1; }

    < ---- AFTER ---- >
    announce(SLGovPhase.AFTER);
    afterVerdict = observer.assess(stream, -1);
    if (afterVerdict.value() == SLGovVerdict.REJECT) {
      haltReason = afterVerdict.why();
      return -1;
    }
    if (afterVerdict.isUnrest()) {
      haltReason = afterVerdict.why();
      return -1;
    }
    if (afterVerdict.value() == SLGovVerdict.WARN) { warnings = warnings + 1; }

    return ip;
  }

  < True only when the program passed all three phases without being blocked. >
  boolean admitted() {
    if (beforeVerdict == null || afterVerdict == null) { return false; }
    if (beforeVerdict.blocks()) { return false; }
    if (afterVerdict.value() == SLGovVerdict.REJECT || afterVerdict.isUnrest()) { return false; }
    return true;
  }

  String reasonHalted() { return haltReason; }
}