From 0c8312cbe104e169744a8211463bdbb445ac0ab1 Mon Sep 17 00:00:00 2001 From: Quodss Date: Tue, 21 Oct 2025 11:28:44 +0200 Subject: [PATCH 1/5] ford mark uip draft --- UIPS/uip-draft-ford-mark.md | 50 +++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 UIPS/uip-draft-ford-mark.md diff --git a/UIPS/uip-draft-ford-mark.md b/UIPS/uip-draft-ford-mark.md new file mode 100644 index 0000000..d26c242 --- /dev/null +++ b/UIPS/uip-draft-ford-mark.md @@ -0,0 +1,50 @@ +--- +title: Ford rune for +grad arm inheritance in marks +description: Delegation of mark revision control is done with a new Ford rune, making the dependency tree discoverable by parsing only Ford headers. +author: ~dozreg-toplud (@quodss), ~midden-fabler (midden-fabler) +status: Draft +type: Standards Track +category: Kernel +created: 2025-10-21 +--- + +## Abstract + +We propose moving revision control core delegation in marks from the product of the `+grad` arm of a mark core to the Ford header by declaring the delegation with a new Ford rune. Doing so would allow the build system to discover the dependency graph of a file by parsing static Ford declarations, without having to build the file or its dependencies. + +## Motivation + +Current work on Ford refactoring to use persistent memoization instead of the explicit Ford cache (Ford Lightning) hit a roadblock in mark build process. In the current Ford Lightning design when a file is built its Ford header is parsed first, finding its dependencies. If the file has no dependencies, it forms a leaf of a dependency graph, otherwise the process is applied recursively to all dependencies while checking for recursion. What is left is a dependency graph with Hoon content, which would be then built into a vase with a persistently memoized function. + +When a mark is built as a mark core, and not as a file, this design breaks down due to `+grad` arm treatment by the build system. If the product of that arm is an atom, Ford treats it as a mark name, and tries to build that mark together with mark conversion gates between the marks. To know the dependency graph of a mark we would have to build it as a file, and doing so requires having to build all its dependencies, ruining the one directional dependency graph -> vase approach. If the `+grad` arm delegation was declared statically in the Ford header instead of dynamically as a product of `+grad` arm, this would not be an issue. + +## Specification + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. + +The UIP proposes a new Ford rune (provisionally `/#`) to declare `+grad` arm delegation in a mark file. + +`/#` rune MUST be followed by Hoon gap, followed by a term to indicate to which mark the revision control is delegated. + +If the file with `/#` rune is built as a regular file, `/#` rune MUST NOT have any effect. + +If the file with `/#` rune is built as a mark file, the core which is produced by the Hoon contents of the file MUST NOT have a `++grad` arm. + +If a file is built as a mark file and it does not have a `/#` rune, the core which is produced by the Hoon contents of the file MUST have a `++grad` arm, and the product of that arm MUST NOT be an atom. + +## Rationale + +`/#` rune not having an effect is necessary for mark-conversion gate builds, which build mark files as regular files, avoiding a cycle in mark file builds with `+grad` delegation. + +## Backwards Compatibility + +This UIP would require a change to all mark files that use `+grad` delegation. Even though neither Clay nor Ford are Kelvin-versioned, the change is disruptive enough to be included into a Kelvin-versioned update. + + +## Security Considerations + +Needs discussion. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE.md). From 5743d02befd6725e7282cf99e642392a0d8eb7e4 Mon Sep 17 00:00:00 2001 From: Quodss Date: Tue, 21 Oct 2025 13:21:20 +0200 Subject: [PATCH 2/5] duplicate fashax --- UIPS/uip-draft-ford-mark.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/UIPS/uip-draft-ford-mark.md b/UIPS/uip-draft-ford-mark.md index d26c242..9f7849f 100644 --- a/UIPS/uip-draft-ford-mark.md +++ b/UIPS/uip-draft-ford-mark.md @@ -26,9 +26,11 @@ The UIP proposes a new Ford rune (provisionally `/#`) to declare `+grad` arm del `/#` rune MUST be followed by Hoon gap, followed by a term to indicate to which mark the revision control is delegated. +There MUST NOT be two or more `/#` runes in the Ford header of a Hoon file. + If the file with `/#` rune is built as a regular file, `/#` rune MUST NOT have any effect. -If the file with `/#` rune is built as a mark file, the core which is produced by the Hoon contents of the file MUST NOT have a `++grad` arm. +If the file with `/#` rune is built as a mark file, the core to which the Hoon contents of the file is evaluated MUST NOT have a `++grad` arm. If a file is built as a mark file and it does not have a `/#` rune, the core which is produced by the Hoon contents of the file MUST have a `++grad` arm, and the product of that arm MUST NOT be an atom. @@ -40,7 +42,6 @@ If a file is built as a mark file and it does not have a `/#` rune, the core whi This UIP would require a change to all mark files that use `+grad` delegation. Even though neither Clay nor Ford are Kelvin-versioned, the change is disruptive enough to be included into a Kelvin-versioned update. - ## Security Considerations Needs discussion. From d98535818f53cdebb157d224270b27d2be78e672 Mon Sep 17 00:00:00 2001 From: Quodss Date: Tue, 21 Oct 2025 13:23:36 +0200 Subject: [PATCH 3/5] fashax noop clarification --- UIPS/uip-draft-ford-mark.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/UIPS/uip-draft-ford-mark.md b/UIPS/uip-draft-ford-mark.md index 9f7849f..db7d13a 100644 --- a/UIPS/uip-draft-ford-mark.md +++ b/UIPS/uip-draft-ford-mark.md @@ -36,7 +36,7 @@ If a file is built as a mark file and it does not have a `/#` rune, the core whi ## Rationale -`/#` rune not having an effect is necessary for mark-conversion gate builds, which build mark files as regular files, avoiding a cycle in mark file builds with `+grad` delegation. +`/#` rune not having an effect if the file is built as a regular Hoon file is necessary for mark-conversion gate builds, which build mark files as regular files, avoiding a cycle in mark file builds with `+grad` delegation. ## Backwards Compatibility From 2e2b5cce90fcc99eb307b1049c9fc12cb41e6590 Mon Sep 17 00:00:00 2001 From: Quodss Date: Tue, 21 Oct 2025 15:28:32 +0200 Subject: [PATCH 4/5] typo --- UIPS/uip-draft-ford-mark.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/UIPS/uip-draft-ford-mark.md b/UIPS/uip-draft-ford-mark.md index db7d13a..506fe4e 100644 --- a/UIPS/uip-draft-ford-mark.md +++ b/UIPS/uip-draft-ford-mark.md @@ -1,7 +1,7 @@ --- title: Ford rune for +grad arm inheritance in marks description: Delegation of mark revision control is done with a new Ford rune, making the dependency tree discoverable by parsing only Ford headers. -author: ~dozreg-toplud (@quodss), ~midden-fabler (midden-fabler) +author: ~dozreg-toplud (@quodss), ~midden-fabler (@midden-fabler) status: Draft type: Standards Track category: Kernel From 9f0639152e1443b6bc67f5cb592e12eeef8d0fa1 Mon Sep 17 00:00:00 2001 From: Quodss Date: Sun, 2 Nov 2025 16:54:05 +0100 Subject: [PATCH 5/5] mark interface simplification proposal, `/#` ergonomics rationale --- UIPS/uip-draft-ford-mark.md | 75 +++++++++++++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 8 deletions(-) diff --git a/UIPS/uip-draft-ford-mark.md b/UIPS/uip-draft-ford-mark.md index 506fe4e..5f7896b 100644 --- a/UIPS/uip-draft-ford-mark.md +++ b/UIPS/uip-draft-ford-mark.md @@ -10,37 +10,96 @@ created: 2025-10-21 ## Abstract -We propose moving revision control core delegation in marks from the product of the `+grad` arm of a mark core to the Ford header by declaring the delegation with a new Ford rune. Doing so would allow the build system to discover the dependency graph of a file by parsing static Ford declarations, without having to build the file or its dependencies. +We propose moving revision control core delegation in marks from the product of a given arm of a mark core to the Ford header by declaring the delegation with a new Ford rune. Doing so would allow the build system to discover the dependency graph of a file by parsing static Ford declarations, without having to build the file or its dependencies. We also propose to remove some unused mark definition features to simplify the build system. ## Motivation Current work on Ford refactoring to use persistent memoization instead of the explicit Ford cache (Ford Lightning) hit a roadblock in mark build process. In the current Ford Lightning design when a file is built its Ford header is parsed first, finding its dependencies. If the file has no dependencies, it forms a leaf of a dependency graph, otherwise the process is applied recursively to all dependencies while checking for recursion. What is left is a dependency graph with Hoon content, which would be then built into a vase with a persistently memoized function. -When a mark is built as a mark core, and not as a file, this design breaks down due to `+grad` arm treatment by the build system. If the product of that arm is an atom, Ford treats it as a mark name, and tries to build that mark together with mark conversion gates between the marks. To know the dependency graph of a mark we would have to build it as a file, and doing so requires having to build all its dependencies, ruining the one directional dependency graph -> vase approach. If the `+grad` arm delegation was declared statically in the Ford header instead of dynamically as a product of `+grad` arm, this would not be an issue. +When a mark is built as a mark core, and not as a file, this design breaks down due to the treatment of some arms by the build system, e.g. `+grad` arm. If the product of that arm is an atom, Ford treats it as a mark name, and tries to build that mark together with mark conversion gates between the marks. To know the dependency graph of a mark we would have to build it as a file, and doing so requires having to build all its dependencies, ruining the one directional `dependency graph -> vase` approach. This may cause an infinite loop if a file that specifies a mark also has the same mark, a case which would be correctly recognized as an infinite loop in the current design of Ford. If the `+grad` arm delegation was declared statically in the Ford header instead of dynamically as a product of `+grad` arm, this would not be an issue. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. +### Delegation rune + The UIP proposes a new Ford rune (provisionally `/#`) to declare `+grad` arm delegation in a mark file. -`/#` rune MUST be followed by Hoon gap, followed by a term to indicate to which mark the revision control is delegated. +`/#` rune MUST be followed by Hoon gap, followed by a term to indicate which arm is being delegated, followed by a gap, `%` and a term to indicate to which mark the revision control is delegated: + +```hoon +:: example: +grad arm delegation +/# grad %mime +``` -There MUST NOT be two or more `/#` runes in the Ford header of a Hoon file. +There MUST NOT be two or more `/#` runes in the Ford header of a Hoon file with the same arm specifier. If the file with `/#` rune is built as a regular file, `/#` rune MUST NOT have any effect. -If the file with `/#` rune is built as a mark file, the core to which the Hoon contents of the file is evaluated MUST NOT have a `++grad` arm. +If the file with `/#` rune is built as a mark file, the core to which the Hoon contents of the file is evaluated MUST NOT have an arm specified in the first child of the `/#` rune. + +The set of arm names that MUST be recognized by `/#` rune are: +- `grad` + +### Mark specification changes + +In addition to the proposal above, this UIP also proposes changing the mark core definition interface: -If a file is built as a mark file and it does not have a `/#` rune, the core which is produced by the Hoon contents of the file MUST have a `++grad` arm, and the product of that arm MUST NOT be an atom. +- The product of `+grab` arm MUST NOT be an atom +- `+jump` arm SHOULD NOT be present in the definition ## Rationale -`/#` rune not having an effect if the file is built as a regular Hoon file is necessary for mark-conversion gate builds, which build mark files as regular files, avoiding a cycle in mark file builds with `+grad` delegation. +In addition to simply removing arm delegation via mark arm magic, the proposal also adds `/#` rune for ergonomics. It is possible to use existing Ford runes in order to achieve the same effect as arm delegation, but it requires nontrivial amount of boilerplate, for example in `/mar/atom/hoon`: + +```hoon +:: +:::: /hoon/atom/mar + :: +/? 310 +/% deg %mime :: import the mark to delegate to +/$ tub %atom %mime :: mark conversion to delegated mark +/$ but %mime %atom :: mark conversion from delegated mark +:: +:::: A minimal atom mark + :: +=, mimes:html +|_ ato=@ +++ grab |% + ++ noun @ + ++ mime |=([* p=octs] q.p) + -- +++ grow |% + ++ mime [/application/x-urb-unknown (as-octs ato)] + -- +++ grad + |% + ++ form form:grad:deg :: simply delegated: diff definition + ++ join join:grad:deg :: diff merge + ++ mash mash:grad:deg :: diff force merge + :: + ++ diff :: diff computation: convert operands + |= ota=atom :: to delegated mark + (diff:~(grad deg (tub ato)) (tub ota)) + :: + ++ pact :: diff application: convert operand + |= dif=mime :: to delegated mark, convert result + (but (pact:~(grad deg (tub ato)) dif)) + :: + -- +-- +``` + +`/#` rune not having an effect if the file is built as a regular Hoon file is necessary for mark-conversion gate builds, which build mark files as regular files, avoiding a cycle in mark file builds with arm delegation. + +The purpose of the [Mark specification changes](#mark-specification-changes) proposal is to simplify the build process of marks by removing mark build features that are not used anywhere to the authors' knowledge. + +Together with the [Mark specification changes](#mark-specification-changes) proposal only `+grad` arm can be recognized by `/#` rune. The arm specifier argument of the rune is added for forward-compatibility purposes. ## Backwards Compatibility -This UIP would require a change to all mark files that use `+grad` delegation. Even though neither Clay nor Ford are Kelvin-versioned, the change is disruptive enough to be included into a Kelvin-versioned update. +This UIP would require a change to all mark files that use arm delegation. Even though neither Clay nor Ford are Kelvin-versioned, the change is disruptive enough to be included into a Kelvin-versioned update. ## Security Considerations