SY-3961: Arc Ranges RFC

[sy-nico]

Pull Request

SY-3961

Greptile Summary

This RFC defines the ranges module for the Arc language, exposing ranges.create and ranges.delete as dual-mode constructs (WASM host functions + Flow nodes). All concerns from the previous review round — color shadowing, non-transactional batch delete counter, missing type definitions for all three create variants, reportWarning/reportInfo signature ambiguity, Flow node Next() ignoring parent, and 3/4/5-arg dispatch description — have been addressed in this revision. The one remaining gap is the missing 4-arg create_with_color host function snippet in Section 5.1.0.

Confidence Score: 5/5

Documentation-only RFC; all previous blocking issues have been resolved and only a minor documentation gap remains.

All P0/P1 concerns from the prior round (color shadowing, non-transactional delete count, missing type definitions, reportWarning/reportInfo signatures, Flow node parent handling, dispatch arity description) have been addressed. The sole remaining finding is a P2 style gap (missing 4-arg snippet), which does not affect correctness.

No files require special attention beyond the minor snippet gap in Section 5.1.0.

Important Files Changed

Filename	Overview
docs/tech/rfc/0036-260427-arc-ranges.md	New RFC proposing the Arc ranges module (ranges.create / ranges.delete) with WASM host functions and Flow nodes; all prior review concerns resolved in this revision — one minor gap remains: the 4-arg create_with_color host function snippet is missing from Section 5.1.0.

Sequence Diagram

sequenceDiagram
    participant Arc as Arc Program (WASM)
    participant Host as Host Function (Go)
    participant RS as ranger.Service
    participant DB as Synnax Server

    Note over Arc,DB: ranges.create (3-arg)
    Arc->>Host: create(nameHandle, start, end)
    Host->>Host: strings.Get(nameHandle) → name
    Host->>Host: doCreate(name, start, end, "", zero ID)
    Host->>RS: w.Create(ctx, &rng)
    RS->>DB: persist range
    DB-->>RS: rng.Key (UUID)
    Host-->>Arc: strings.Create(key) → handle

    Note over Arc,DB: ranges.create (5-arg, with parent)
    Arc->>Host: create_with_color_parent(name,start,end,colorH,parentH)
    Host->>Host: resolveParent(parentStr)
    Host->>RS: NewRetrieve().WhereNames(parentStr)
    RS->>DB: query
    DB-->>RS: []ranger.Range
    Host->>RS: w.CreateWithParent(ctx, &rng, parentID)
    RS->>DB: persist range + ontology link
    DB-->>RS: rng.Key
    Host-->>Arc: handle

    Note over Arc,DB: ranges.delete (by name)
    Arc->>Host: delete(identifierHandle)
    Host->>RS: NewRetrieve().WhereNames(identifier)
    RS->>DB: query
    DB-->>RS: []ranger.Range
    loop for each matched range
        Host->>RS: w.Delete(ctx, rng.Key)
        RS->>DB: delete + cascade children
    end
    Host->>Host: reportInfo if deleted > 1

Loading

_{Reviews (5): Last reviewed commit: "SY-3961: Update RFC" | Re-trigger Greptile}

[pjdotson]

note: we should standardize on singular / plural for module names. Currently you have
status.set (singular) and ranges.create (plural). I think singular would make the
most sense here.

[pjdotson]

does this always have to be called in this exact order, even if i specify the arguments?

[pjdotson]

end should probably default to TimeStamp.MAX, which is what it would mean to create an
in-progress range

[pjdotson]

same comment as on statuses RFC: we should have same API for both Flow and WASM

[pjdotson]

why?

[pjdotson]

you shouldn't call these go if they use the Arc syntax

[pjdotson]

This is another place where you might want to think more about safety vs usability.
Warning / erroring when there are multiple ranges means that the user will have to
think and specify what they want to do upfront, which is generally safer and means we
won't be doing anything "magic". However, the user needs to think about it before they
call, or we make it a general pattern to use when using Arc (like how Go has if err :=
...; err != nil { ... } )

[pjdotson]

We might want to start thinking about how we could support an object / struct type in
Arc, especially for creating types like a range.Range type that we know has certain fields.

[pjdotson]

need C++ too

[pjdotson]

should consider a way to set the stage of a range as well