hecks 5.0.0 → 7.0.0

data/lib/hecks/hecks/governance.world

@@ -1,7 +0,0 @@
-# The Governance chapter's connection when the Hecks domain attaches it: boot reads a world
-# named for the chapter, not for the consuming domain. It is the same database hecks.world
-# names, so one journal holds both; environments/memory.world swaps it to Memory too.
-Hecks.world "Governance" do
-  default_adapter "PostgresEra"
-  default_database ENV.fetch("HECKS_DATABASE", "postgres://hecks@localhost/hecks")
-end

data/lib/hecks/hecks/rehearsal.bluebook

@@ -1,471 +0,0 @@
-Hecks.bluebook "Hecks" do
-  # Rehearsal: operating a domain, in the Operations module (ADR 0096). Whether a domain at a pin
-  # would mint its next era against a copy of its real data, and what the mint would refuse.
-  #
-  # A rehearsal is a run like the Codebase `*Run`s: it is requested, the outside is asked, and the
-  # facts it brought back are judged by the givens and reactions below. It differs from them in
-  # two ways. It acts on a client's domain, not on this checkout, so it needs no hecks checkout
-  # and sits with Custodian, not Codebase. And it keeps nothing: the aggregate is bound to Memory
-  # in hecks.hecksagon, and what it found is its report, returned to the caller.
-  #
-  # Where the data it reads comes from is the subject's own `.world` (`rehearsed_by`), never an
-  # argument. The RehearsalStore port prepares that copy, loads the domain against it, runs the
-  # mint's audit over it without writing an era, and drops it, so the copy never outlives the run
-  # whichever way the chain of reactions ends.
-
-  aggregate "RehearsalRun" do
-    description "One rehearsal of a domain's next era against a copy of its data: what a mint would do, and what it would refuse."
-
-    attribute :run,            RunKey
-    attribute :domain,         DomainPath
-    attribute :pin,            Pin,         optional: true
-    attribute :host_version,   HostVersion, optional: true
-    attribute :store,          StoreKind,   optional: true
-    attribute :mode,           StoreMode,   optional: true
-    attribute :environment_loaded, EnvironmentLoaded, optional: true
-    attribute :schema_used,    SchemaRead,  optional: true
-    attribute :eras_held,      Count,       optional: true
-    attribute :journal_entries, Count,      optional: true
-    attribute :head_rows,      Count,       optional: true
-    attribute :census,         list_of(HeldCount), optional: true
-    attribute :copy_empty,     Switch,      optional: true
-    attribute :copy_note,      Report,      optional: true
-    attribute :booted,         Switch,      optional: true
-    attribute :before,         ShapeLabel,  optional: true
-    attribute :after,          ShapeLabel,  optional: true
-    attribute :minting,        Minting,     optional: true
-    attribute :edge_present,   Switch,      optional: true
-    attribute :refused_rows,   list_of(RefusedRow), optional: true
-    attribute :refusal_total,  Count,       optional: true
-    attribute :audited,        Switch,      optional: true
-    attribute :rows_examined,  Count,       optional: true
-    attribute :rust_rows_examined, Count,   optional: true
-    attribute :aggregates_examined, Count,  optional: true
-    attribute :reason,         Report,      optional: true
-    attribute :parity,         Parity,      optional: true
-    attribute :unchecked,      list_of(Limit), optional: true
-    attribute :verdict,        Verdict,     optional: true
-    attribute :released,       Switch,      optional: true
-    attribute :kept,           Report,      optional: true
-    attribute :boot_error,     Report,      optional: true
-    attribute :refusal,        Report,      optional: true
-    identified_by :run
-
-    value_object "RunKey" do
-      attribute :value, String, matches: :present
-
-      invariant("a rehearsal is named") { !value.to_s.empty? }
-    end
-
-    # The domain's directory: where its bluebooks and its `.world` stand.
-    value_object "DomainPath" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    # The Hecks the rehearsal must run on: a release (`3.9.0`) or a commit, whole or a prefix.
-    value_object "Pin" do
-      attribute :value, String, pattern: '^[0-9a-f]{7,40}$|^[0-9]+[.][0-9]+[.][0-9]+'
-    end
-
-    value_object "HostVersion" do
-      attribute :value, String, matches: :present
-    end
-
-    # Which strategy the subject's world named for the copy of its data.
-    value_object "StoreKind" do
-      attribute :value, String, one_of: ["memory", "postgres"]
-
-      invariant("a store is one the language names") { ["memory", "postgres"].include?(value) }
-    end
-
-    # What the copy holds: nothing, a restored dump, or a copy somebody else made, read as it is.
-    value_object "StoreMode" do
-      attribute :value, String, one_of: ["empty", "dump", "readonly_copy"]
-
-      invariant("a mode is empty, dump or readonly_copy") { ["empty", "dump", "readonly_copy"].include?(value) }
-    end
-
-    # The environment overlay the subject was loaded under and where that was decided: `world`
-    # (its `rehearsed_by` named one), `HECKS_PROJECT_ENVIRONMENT`, `default` (production, because
-    # its overlay exists, as the host build does) or `none`. A domain's binds are usually declared
-    # in that overlay, so a rehearsal that loaded another one rehearsed another domain.
-    value_object "EnvironmentLoaded" do
-      attribute :name,   String
-      attribute :source, String, pattern: '^(world|HECKS_PROJECT_ENVIRONMENT|default|none)$'
-      attribute :file,   String
-    end
-
-    # The Postgres schema the copy was read in, where that was decided (`world`, `HECKS_SCHEMA`,
-    # `derived` from the domain's name, `default` public, or `memory` for a document) and whether
-    # the copy has it.
-    value_object "SchemaRead" do
-      attribute :name,    String
-      attribute :source,  String, pattern: '^(world|HECKS_SCHEMA|derived|default|memory)$'
-      attribute :present, Boolean
-    end
-
-    # One aggregate's rows in the copy: what its head table holds and the records its journal's
-    # latest entries hold. The audit reads the journal, so a difference is shown, not refused.
-    value_object "HeldCount" do
-      attribute :aggregate, String
-      attribute :head,      Integer
-      attribute :journal,   Integer
-    end
-
-    value_object "Switch" do
-      attribute :value, Boolean
-    end
-
-    value_object "Count" do
-      attribute :value, Integer
-
-      invariant("a count is not negative") { value >= 0 }
-    end
-
-    # The first six hex digits of a storage shape's digest, or `none` when no era is held.
-    value_object "ShapeLabel" do
-      attribute :value, String, pattern: '^[0-9a-f]{6}$|^none$'
-    end
-
-    # Which era a mint would hold: none (the shape stands), the first, or the next.
-    value_object "Minting" do
-      attribute :value, String, one_of: ["none", "first", "next"]
-
-      invariant("a mint is none, first or next") { ["none", "first", "next"].include?(value) }
-    end
-
-    # One stored record the mint's audit would refuse, named `Aggregate#id`, with the rule that
-    # refused it (a value the new types or invariants refuse, a state the lifecycle never reaches,
-    # a reference the edge cannot carry) and the audit's own wording.
-    value_object "RefusedRow" do
-      attribute :aggregate, String
-      attribute :id,        String
-      attribute :rule,      String, pattern: '^(value|lifecycle|reference)$'
-      attribute :wording,   String
-    end
-
-    # How the other engine's audit stood: not run, in agreement with this one, or not.
-    value_object "Parity" do
-      attribute :engine, String
-      attribute :status, String, pattern: '^(not_run|agree|differ)$'
-      attribute :note,   String
-    end
-
-    # One thing a rehearsal did not check, and why. A rehearsal states its limits.
-    value_object "Limit" do
-      attribute :what, String
-      attribute :why,  String
-    end
-
-    # The five things a rehearsal can conclude. A would_mint of `minting: none` says the shape
-    # stands and nothing would be minted at all. `empty_copy` says the copy held no row of the
-    # domain, so nothing was rehearsed and no answer about the data is given.
-    value_object "Verdict" do
-      attribute :value, String, one_of: ["would_mint", "would_refuse", "needs_edge", "cannot_boot", "empty_copy"]
-
-      invariant("a verdict is one the rehearsal names") do
-        ["would_mint", "would_refuse", "needs_edge", "cannot_boot", "empty_copy"].include?(value)
-      end
-    end
-
-    value_object "Report" do
-      attribute :value, String
-    end
-
-    # Only the first rows are held, so a domain with a million stale rows is a report, not a
-    # flood; the total says how many there were.
-    invariant("no more than fifty refused rows are held") { refused_rows.unset? || refused_rows.size <= 50 }
-    invariant("the total counts at least the rows held") do
-      refused_rows.unset? || refusal_total.unset? || refusal_total.value >= refused_rows.size
-    end
-    invariant("a rehearsal that would mint holds no refused row") do
-      verdict.unset? || verdict.value != "would_mint" || refusal_total.unset? || refusal_total.value == 0
-    end
-    invariant("only a domain that booted would mint") do
-      verdict.unset? || verdict.value != "would_mint" || booted.unset? || booted.value
-    end
-    invariant("a copy that holds nothing is never judged to mint") do
-      verdict.unset? || verdict.value != "would_mint" || copy_empty.unset? || !copy_empty.value
-    end
-    invariant("an empty_copy verdict is given for a copy that holds nothing") do
-      verdict.unset? || verdict.value != "empty_copy" || (!copy_empty.unset? && copy_empty.value)
-    end
-    invariant("only a mint of the next era audits stored rows") do
-      audited.unset? || !audited.value || minting.unset? || minting.value == "next"
-    end
-    invariant("a mint of the next era that would go through states how many rows were examined") do
-      verdict.unset? || verdict.value != "would_mint" || minting.unset? || minting.value != "next" || !rows_examined.unset?
-    end
-    invariant("a clean verdict that examined no row says so in what it did not check") do
-      verdict.unset? || verdict.value != "would_mint" || audited.unset? || audited.value ||
-        (!unchecked.unset? && unchecked.any? { |limit| limit.what == "the stored rows" })
-    end
-
-    # `requested` is the rehearsal and its store being prepared; `booted` the domain loaded and
-    # its shape read; `audited` the mint's audit run over the data. `judged` is a rehearsal whose
-    # answer is that the mint would go through, `withheld` one whose answer is that it would not
-    # (the verdict says which way), `refused` one that was never run because the request or the
-    # store was not admitted, and `failed` one that broke after it began.
-    lifecycle :status, default: "requested" do
-      mark :failure, "withheld", "refused", "failed"
-      transition "Boot"     => "booted",   from: "requested"
-      transition "Audit"    => "audited",  from: "booted"
-      transition "Judge"    => "judged",   from: "audited"
-      transition "Withhold" => "withheld", from: %w[requested booted audited]
-      transition "Refuse"   => "refused",  from: "requested"
-      transition "Fail"     => "failed",   from: %w[requested booted audited]
-    end
-
-    command "Request" do
-      role "Operator"
-      goal "Rehearse a domain's next era against the copy of its data its world names, say whether a mint would go through, and print the whole outcome"
-
-      attribute :run,    RunKey
-      attribute :domain, DomainPath
-      attribute :pin,    Pin, optional: true
-
-      sets :run
-      sets :domain
-      sets :pin
-
-      emits RehearsalRequested
-    end
-
-    # What the subject reported once it was loaded against the prepared copy.
-    command "Boot" do
-      role "System"
-      goal "Record that the domain loaded, the shape it stands at and the era a mint would hold"
-
-      reference_to RehearsalRun
-      attribute :booted,       Switch
-      attribute :host_version, HostVersion
-      attribute :store,        StoreKind
-      attribute :mode,         StoreMode
-      attribute :before,       ShapeLabel
-      attribute :after,        ShapeLabel
-      attribute :minting,      Minting
-      attribute :environment_loaded, EnvironmentLoaded
-      attribute :schema_used,  SchemaRead
-      attribute :eras_held,    Count
-      attribute :journal_entries, Count
-      attribute :head_rows,    Count
-      attribute :census,       list_of(HeldCount)
-      attribute :copy_empty,   Switch
-      attribute :copy_note,    Report
-      attribute :released,     Switch, optional: true
-      attribute :kept,         Report, optional: true
-
-      given("the domain loaded") { booted.value }
-
-      sets :booted
-      sets :host_version
-      sets :store
-      sets :mode
-      sets :before
-      sets :after
-      sets :minting
-      sets :environment_loaded
-      sets :schema_used
-      sets :eras_held
-      sets :journal_entries
-      sets :head_rows
-      sets :census
-      sets :copy_empty
-      sets :copy_note
-      sets :released
-      sets :kept
-
-      emits RehearsalBooted
-    end
-
-    # The mint's own three layers and its edge and coverage rules, run over the copy.
-    command "Audit" do
-      role "System"
-      goal "Record whether an edge leads to the shape, and every row the mint's audit would refuse"
-
-      reference_to RehearsalRun
-      attribute :minting,       Minting
-      attribute :edge_present,  Switch
-      attribute :refused_rows,  list_of(RefusedRow), optional: true
-      attribute :refusal_total, Count
-      attribute :audited,       Switch
-      attribute :rows_examined, Count
-      attribute :rust_rows_examined, Count
-      attribute :aggregates_examined, Count
-      attribute :reason,        Report
-      attribute :parity,        Parity
-      attribute :unchecked,     list_of(Limit)
-      attribute :released,      Switch
-      attribute :kept,          Report, optional: true
-
-      sets :minting
-      sets :edge_present
-      sets :refused_rows
-      sets :refusal_total
-      sets :audited
-      sets :rows_examined
-      sets :rust_rows_examined
-      sets :aggregates_examined
-      sets :reason
-      sets :parity
-      sets :unchecked
-      sets :released
-      sets :kept
-
-      emits RehearsalAudited
-    end
-
-    command "Judge" do
-      role "System"
-      goal "Record that the mint would go through: the domain booted, an edge leads on where one is needed, and nothing is refused"
-
-      reference_to RehearsalRun
-      attribute :verdict,       Verdict
-      attribute :refusal_total, Count
-      attribute :edge_present,  Switch
-
-      given("a rehearsal that finds a refused row would not mint") { refusal_total.value == 0 }
-      given("a rehearsal judged to mint names that verdict") { verdict.value == "would_mint" }
-
-      sets :verdict
-
-      emits RehearsalJudged
-    end
-
-    command "Withhold" do
-      role "System"
-      goal "Record that the mint would not go through, which of the three ways, and what it would say"
-
-      reference_to RehearsalRun
-      attribute :verdict, Verdict
-      attribute :refusal, Report
-
-      given("a withheld rehearsal names how the mint would stop") { verdict.value != "would_mint" }
-
-      sets :verdict
-      sets :refusal
-
-      emits RehearsalWithheld
-    end
-
-    command "Refuse" do
-      role "System"
-      goal "Record that the rehearsal was not run: the subject, the pin or the store was not admitted, and why"
-
-      reference_to RehearsalRun
-      attribute :refusal, Report
-
-      sets :refusal
-
-      emits RehearsalRefused
-    end
-
-    command "Fail" do
-      role "System"
-      goal "Record that the rehearsal broke after it began, and why"
-
-      reference_to RehearsalRun
-      attribute :refusal, Report
-
-      sets :refusal
-
-      emits RehearsalFailed
-    end
-
-    query "RehearsalOutcome" do
-      description "How one rehearsal ended: its status and verdict, and every fact it brought back. A run is kept by the process that made it, so a run this process does not hold is refused as unknown; `request` waits for its reactions and prints the whole outcome."
-      attribute :run, RunKey
-      where(run: :run)
-      order_by :run
-    end
-
-    query "Withheld" do
-      description "Every rehearsal of this process whose answer was that the mint would not go through."
-      where(status: "withheld")
-      order_by :run
-    end
-  end
-
-  policy "SurveyWhenRehearsalRequested" do
-    on      "RehearsalRun.RehearsalRequested"
-    ask     :survey, with: { run: :run }
-  end
-
-  policy "RefuseWhenStoreNotAdmitted" do
-    on      "RehearsalRun.StoreRefused"
-    trigger RehearsalRun::Refuse, with: { refusal: :refusal }
-  end
-  policy "RecordBootWhenStoreSurveyed" do
-    on      "RehearsalRun.StoreSurveyed"
-    where   { booted.value }
-    trigger RehearsalRun::Boot, with: { booted: :booted, host_version: :host_version, store: :store, mode: :mode,
-                                         before: :before, after: :after, minting: :minting,
-                                         environment_loaded: :environment_loaded, schema_used: :schema_used,
-                                         eras_held: :eras_held, journal_entries: :journal_entries,
-                                         head_rows: :head_rows, census: :census, copy_empty: :copy_empty,
-                                         copy_note: :copy_note, released: :released, kept: :kept }
-  end
-
-  # A copy that holds none of the domain's rows is not rehearsed: there is nothing to audit, and a
-  # clean answer over it would be a confident wrong one. The survey has already dropped it.
-  policy "WithholdWhenTheCopyHoldsNothing" do
-    on      "RehearsalRun.RehearsalBooted"
-    where   { copy_empty.value }
-    trigger RehearsalRun::Withhold, with: { verdict: "empty_copy", refusal: :copy_note }
-  end
-
-  # A domain that does not load is an answer, not a breakdown: it is what the mint would be
-  # stopped by, so it is judged, not failed.
-  policy "WithholdWhenSubjectDoesNotBoot" do
-    on      "RehearsalRun.StoreSurveyed"
-    where   { !booted.value }
-    trigger RehearsalRun::Withhold, with: { verdict: "cannot_boot", refusal: :boot_error }
-  end
-
-  policy "FailWhenExaminationRefused" do
-    on      "RehearsalRun.ExamineRefused"
-    trigger RehearsalRun::Fail, with: { refusal: :refusal }
-  end
-
-  policy "ExamineWhenBooted" do
-    on      "RehearsalRun.RehearsalBooted"
-    where   { !copy_empty.value }
-    ask     :examine, with: { run: :run }
-  end
-
-  policy "RecordAuditWhenStoreExamined" do
-    on      "RehearsalRun.StoreExamined"
-    trigger RehearsalRun::Audit, with: { minting: :minting, edge_present: :edge_present,
-                                          refused_rows: :refused_rows, refusal_total: :refusal_total,
-                                          audited: :audited, rows_examined: :rows_examined,
-                                          rust_rows_examined: :rust_rows_examined,
-                                          aggregates_examined: :aggregates_examined, reason: :reason,
-                                          parity: :parity, unchecked: :unchecked,
-                                          released: :released, kept: :kept }
-  end
-
-  policy "JudgeWhenNothingWouldStopTheMint" do
-    on      "RehearsalRun.RehearsalAudited"
-    where do
-      (minting.value != "next" || edge_present.value) && refusal_total.value == 0
-    end
-    trigger RehearsalRun::Judge, with: { verdict: "would_mint", refusal_total: :refusal_total,
-                                          edge_present: :edge_present }
-  end
-
-  policy "WithholdWhenNoEdgeLeadsOn" do
-    on      "RehearsalRun.RehearsalAudited"
-    where   { minting.value == "next" && !edge_present.value }
-    trigger RehearsalRun::Withhold, with: { verdict: "needs_edge",
-                                             refusal: "no translation edge leads the held era to this shape" }
-  end
-
-  policy "WithholdWhenTheMintWouldRefuse" do
-    on      "RehearsalRun.RehearsalAudited"
-    where do
-      (minting.value != "next" || edge_present.value) && refusal_total.value > 0
-    end
-    trigger RehearsalRun::Withhold, with: { verdict: "would_refuse",
-                                             refusal: "the mint would refuse: see the refused rows" }
-  end
-end