Create ADR-0001 Avoid primative constraint types

docs/decisions/0000-use-markdown-architectural-decision-records.md

@@ -0,0 +1,29 @@
+# Use Markdown Architectural Decision Records
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project independent
+whether decisions concern the architecture ("architectural decision record"),
+the code, or other fields.
+
+Which format and structure should these records follow?
+
+## Considered Options
+
+* [MADR](https://adr.github.io/madr/) 4.0.0 – The Markdown Architectural Decision Records
+* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+* Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 4.0.0", because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also ["A rational design process: How and why to fake it"](https://doi.org/10.1109/TSE.1986.6312940).
+* MADR allows for structured capturing of any decision.
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.

docs/decisions/0001-avoid-primative-constraint-types.md

@@ -0,0 +1,96 @@
+---
+status: accepted
+date: 2024-11-29
+decision-makers: eljobe@ plasmapower@
+---
+
+# Avoid primative constraint types
+
+## Context and Problem Statement
+
+When working on the go code for BoLD, we became slightly annoyed that several
+places in the history package were checking the constraint that the `virtual`
+argumet to a function was positive. One possible workaround would have been
+to create a constrained wrapper type around `uint64` which would only allow
+positive values. For example:
+
+```go
+// Pos64 is a type which represents a positive uint64.
+//
+// The "zero" value of Pos64 is 1.
+type Pos64 struct {
+	uint64
+}
+
+// NewPos64 returns a new Pos64 with the given value.
+//
+// errors if v is 0.
+func NewPos64(v uint64) (Pos64, error) {
+	if v == 0 {
+		return Pos64{}, errors.New("v must be positive. got: 0")
+	}
+	return Pos64{v}, nil
+}
+
+// MustPos64 returns a new Pos64 with the given value.
+//
+// panics if v is 0.
+func MustPos64(v uint64) Pos64 {
+	if v == 0 {
+		panic("v must be positive. got: 0")
+	}
+	return Pos64{v}
+}
+
+// Val returns the value of the Pos64.
+func (p Pos64) Val() uint64 {
+	// The zero value of Pos64 is 1.
+	if p.uint64 == 0 {
+		return 1
+	}
+	return p.uint64
+}
+```
+
+The idea being that within a package, all of the functions which needed to deal
+with a `virtual` argument, could take in a `Pos64` instead of a `uint64` and it
+would be up to clients of the package to ensure that they only passed in
+positive values.
+
+## Considered Options
+
+* New Package: `util/chk` for checking type constraint
+* Status Quo: check the constraint in multiple places
+* Minimize Checks: no check in package private functions
+
+## Decision Outcome
+
+Chosen option: "Status Quo", because the "New Package" option introduces a
+regression in being able to use type type with operators, and "Minimize Checks"
+is too prone to bugs introduced by refactoring.
+
+
+## Pros and Cons of the Options
+
+### New Pacakge: `util/chk` for checking type constraint
+
+* Good, because it is expressive
+* Good, because the constraint only needs to be checked during construction
+* Bad, because `Pos64` doesn't compile with operators like `+ * - /`
+
+### Status Quo: check the constraint in multiple places
+
+* Good, because it is what the code is already doing
+* Good, because when a funciton becomes public, the constraint holds
+* Good, because when a function moves to another file or package, the constraint holds
+* Bad, because it means the check may need to be repeated. DRY
+
+### Minimize Checks: no check in package private functions
+
+* Good, because it reduces the amount of times a constraint is checked
+* Bad, because the assumption might be violated if a private function becomes
+  public, or gains an additional caller.
+
+## More Information
+
+See the discussion on now-closed #2743

docs/decisions/README.md

@@ -0,0 +1,10 @@
+# Decisions
+
+For new Architectural Decision Records (ADRs), please use one of the following templates as a starting point:
+
+* [adr-template.md](adr-template.md) has all sections, with explanations about them.
+* [adr-template-minmal.md](adr-template-minimal.md) only contains mandatory sections, with explanations about them. <!-- ### Consequences also contained, though marked as "optional" -->
+* [adr-template-bare.md](adr-template-bare.md) has all sections, wich are empty (no explanations).
+* [adr-template-bare-minimal.md](adr-template-bare-minimal.md) has the mandatory sections, without explanations. <!-- ### Consequences also contained, though marked as "optional" -->
+
+The MADR documentation is available at <https://adr.github.io/madr/> while general information about ADRs is available at <https://adr.github.io/>.

docs/decisions/adr-template-bare-minimal.md

@@ -0,0 +1,16 @@
+# <!-- short title, representative of solved problem and found solution -->
+
+## Context and Problem Statement
+
+
+
+## Considered Options
+
+
+
+## Decision Outcome
+
+
+
+### Consequences
+

docs/decisions/adr-template-bare.md

@@ -0,0 +1,44 @@
+---
+status:
+date: 
+decision-makers: 
+consulted: 
+informed: 
+---
+
+# <!-- short title, representative of solved problem and found solution -->
+
+## Context and Problem Statement
+
+
+
+## Decision Drivers
+
+* <!-- decision driver -->
+
+## Considered Options
+
+* <!-- option -->
+
+## Decision Outcome
+
+Chosen option: "", because
+
+### Consequences
+
+* Good, because
+* Bad, because
+
+### Confirmation
+
+
+
+## Pros and Cons of the Options
+
+### <!-- title of option -->
+
+* Good, because
+* Neutral, because
+* Bad, because
+
+## More Information

docs/decisions/adr-template-minimal.md

@@ -0,0 +1,23 @@
+# {short title, representative of solved problem and found solution}
+
+## Context and Problem Statement
+
+{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
+
+## Considered Options
+
+* {title of option 1}
+* {title of option 2}
+* {title of option 3}
+* … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
+
+<!-- This is an optional element. Feel free to remove. -->
+### Consequences
+
+* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
+* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
+* … <!-- numbers of consequences can vary -->

docs/decisions/adr-template.md

@@ -0,0 +1,74 @@
+---
+# These are optional metadata elements. Feel free to remove any of them.
+status: "{proposed | rejected | accepted | deprecated | … | superseded by ADR-0123"
+date: {YYYY-MM-DD when the decision was last updated}
+decision-makers: {list everyone involved in the decision}
+consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
+informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
+---
+
+# {short title, representative of solved problem and found solution}
+
+## Context and Problem Statement
+
+{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Decision Drivers
+
+* {decision driver 1, e.g., a force, facing concern, …}
+* {decision driver 2, e.g., a force, facing concern, …}
+* … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+* {title of option 1}
+* {title of option 2}
+* {title of option 3}
+* … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
+
+<!-- This is an optional element. Feel free to remove. -->
+### Consequences
+
+* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
+* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
+* … <!-- numbers of consequences can vary -->
+
+<!-- This is an optional element. Feel free to remove. -->
+### Confirmation
+
+{Describe how the implementation of/compliance with the ADR can/will be confirmed. Are the design that was decided for and its implementation in line with the decision made? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Not that although we classify this element as optional, it is included in many ADRs.}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Pros and Cons of the Options
+
+### {title of option 1}
+
+<!-- This is an optional element. Feel free to remove. -->
+{example | description | pointer to more information | …}
+
+* Good, because {argument a}
+* Good, because {argument b}
+<!-- use "neutral" if the given argument weights neither for good nor bad -->
+* Neutral, because {argument c}
+* Bad, because {argument d}
+* … <!-- numbers of pros and cons can vary -->
+
+### {title of other option}
+
+{example | description | pointer to more information | …}
+
+* Good, because {argument a}
+* Good, because {argument b}
+* Neutral, because {argument c}
+* Bad, because {argument d}
+* …
+
+<!-- This is an optional element. Feel free to remove. -->
+## More Information
+
+{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}