Root applies to every surface, and the rename plan says what is stale about it - #717

…alue (#726)

Closes #715.

+devlore:surface=graph produced RoleAction and +devlore:surface=module produced
RoleModule -- two vocabularies for one idea, connected only by a switch in generate.star.
An author wrote graph and the generated code said Action. The op->workflow rename forces
the issue: Graph becomes Definition, so surface=graph would name a type that no longer
exists, and module is starlark's word for a namespace rather than a term in the new
taxonomy. Neither word survives.

  +devlore:surface=script|workflow     a list; default both
  +devlore:placement=promoted          one value; default qualified

  type ProviderFlags uint16   packs both
  type Surfaces uint8         BIT FIELD -- SurfaceScript, SurfaceWorkflow
  type Placement uint8        VALUE -- PlacementQualified, PlacementPromoted

The zones are not the same kind of thing, and the design says so three ways
  PLURAL for the set, singular for the value. flags.Surfaces() returning
  SurfaceScript|SurfaceWorkflow reads correctly; flags.Surface() returning two things
  would read as a contradiction. The accessor signatures alone say which zone is which.

  DISTINCT TYPES per zone, following reflect, where flag.kind() returns Kind rather than
  another flag. flags.Placement() == SurfaceScript is now a compile error rather than
  nonsense that compiles. C# disagrees -- MethodAttributes packs a MemberAccessMask zone
  and flag bits in one enum -- and Go's answer was taken for the type safety.

  PlacementQualified = 0x00 is the zero VALUE of an enumeration, not an absent flag, so
  nothing can express "promoted and qualified" -- not because a check rejects it, but
  because the zone holds one value of a type with two.

Why ProviderFlags rather than something specific
  ProviderRole was specific and went stale: #677 changed the zone from invocation mode to
  surface eligibility, and RoleAction, Dispatch(), and ProviderRole all outlived what they
  named. Dispatch() -> Surfaces() for the same reason. A generic name cannot fail that
  way, and the accessors carry the meaning. Precedent: 14 *Flag/*Flags types in Go's
  stdlib, and C#'s BindingFlags.

The bootstrap had no two-pass escape
  generate.star emits the constant names into every .gen.go, so renaming them broke all 58
  generated references at once, the tree stopped compiling, star could not rebuild, and
  codegen -- the only thing that could rewrite those files -- could not run. Unlike #708
  no ordering avoids it: the constant name and its generated use must change together.

  make star-lkg first, so a prebuilt star could regenerate a tree it could not itself
  compile. It took five iterations of generate.star scope errors to get through, and the
  tree was uncompilable during all of them; each would have been unrecoverable without it.
  The LKG was then removed and a source-built star reproduced all 159 files identically,
  proving it was an escape hatch rather than load-bearing.

A property that was documented three times and tested zero times
  #717 established that ui, reaching both surfaces, promotes six names into plan.* as well
  as installing six globals. That claim lived in three doc comments and no test -- and it
  is the half of placement this rename routes through new code.
  TestProvider_ResolveAttr_Tier2_PromotedAcrossBothSurfaces now asserts it, with a
  negative case proving file.copy stays qualified. Without the negative half it would pass
  on a change that promoted everything.

Also: promoteRootMethods -> promoteMethods and rootNames -> promotedNames, resolving an
identifier that carried two words for one idea. Placement test functions renamed;
fsroot, run-root, scoped-root, and git-root names deliberately untouched -- a word-level
sweep over "root" would break their meaning without breaking the build (#725 tracks the
last two artifacts).

The accessors mask explicitly rather than relying on the conversion to truncate, which
gosec G115 caught: the bare form is correct only while both zones are a byte wide.

Co-authored-by: David Noble <[email protected]>