chore: terminology part 2 - requires/provides, Span, source-side rename, std.ref, descriptor and event consolidation

[pskry]

chore: terminology part 2 - one sweep over the naming thorns

Follow-up to the original terminology pass (TERMINOLOGY.md). Inventory
taken from the actual spec/engine/event symbols. One bucket issue;
commits reference this. Naming decisions marked [NAME] get decided
in-session as the work reaches them, not up front.

1. inputs/promises -> requires/provides (ruled)

The resource graph currently spells one concept five ways:

Current	Where
promises / inputs stub params	user configs, std stubs
spec.Promiser (Promises(), Inputs())	step-level interface
spec.StaticPromiseProvider / StaticInputProvider	deploy-level (cross-deploy graph)
spec.ResourceDeclarer (ResourceDeclarations())	config structs
spec.Resource / ResourceKind / RefResource	graph nodes (keep as-is)

• Language surface: provides = [...] / requires = [...] in stubs,
  configs, fixtures, site docs, TERMINOLOGY.md.
• Go surface: rename methods to Provides()/Requires();
  consolidate the three overlapping interfaces rather than
  renaming all in place. [NAME] the surviving interface(s).
• Test_Rule_*/goldens/e2e fixtures updated in the same commit.

2. SourceSpan -> Span (ruled)

"Source" means three things today: (a) content origin (SourceRef,
src params), (b) the machine running scampi (package source), (c)
code locations. Ruling: Source == content-origin, exclusively.

• spec.SourceSpan -> spec.Span; event.Template.Source ->
  .Span; review FieldSpan (likely stays).
• Sweep doc comments that say "source span".

3. Rename meaning (b): "the machine running scampi" (open)

Package source (configs, env, local cache; "never touches target")
needs a name that is not Source. [NAME] - candidates to discuss:
controller (Ansible: control node), host, origin, operator,
workstation (Chef), base. The interface it exports
(source.Source, MemSource, LocalPosixSource) renames with it.
Note the coupling: this package BACKS meaning (a) reads - naming must
keep "content origins are resolved controller-side" legible.

4. std.ln -> std.ref (ruled)

The posix-ln pun is cryptic. Barely used (no production step
implements the output side per #445), so the rename is nearly free.

• std.scampi decl + doc comment, spec.Ref stays, goldens.

5. Flatten the op-description chain (grown complexity)

Rendering one plan line takes three hops:
Op -> OpDescriber.OpDescription() -> OpDescription.PlanTemplate() -> PlanTemplate{ID, Text, Data}. The middle interface (OpDescription)
is a one-method pass-through; every op carries a <x>Desc struct just
to satisfy it. 30 files implement the chain.

• Investigate: can ops implement PlanTemplate() PlanTemplate
  directly (check the diagnostic.go consumer)? Do the *Desc
  structs earn their keep, or fold into the ops?
• Related audit while there: OpInspector/InspectField naming
  vs Diffable - consistent optional-interface vocabulary.

6. event.Change / event.Result / spec.Result.Changed (open)

Three "change/result" names in one pipeline: event.Change (live
drift/mutation event with ChangePhase), event.Result (step
verdict), spec.Result{Changed} (op outcome). Investigate fold or
rename - e.g. event.Change -> event.Drift/event.Mutation
[NAME]; check StepOutcome (StepUnchanged/StepChanged/
StepFailed) reads cleanly against whatever wins.

Order

1 -> 2 -> 4 (mechanical, ruled) then 5 -> 6 -> 3 (need discussion as
they are reached). Each item lands as its own gated commit referencing
this issue; the issue closes when the table above has no unchecked
rows.

[pskry]

7. res/rep naming consistency in the engine (added 2026-07-03)

The engine's convention: rep = report family (result.Execution, result.StepReport - the execution reports), res = result family (spec.Result, spec.CheckResult - op/step outcomes). Mostly held, but exec.go:390 does res, err := e.checkStep(...) where the value is a StepReport stored into rep.Steps - it should be rep-family. Audit the whole engine for res/rep drift and pin the convention in a comment near the scheduler (or TERMINOLOGY.md if it generalizes).

[pskry]

8. Lazy spans: store offsets, resolve line/col on the cold path (added 2026-07-03)

spec.Span currently materializes {Filename, StartLine, StartCol, EndLine, EndCol} eagerly - the linker runs offsetToLineCol for every step and field span at link time, on the hot path, for data only ever read when a diagnostic renders. Change to {Filename string; Start, End uint32} byte offsets and resolve line/col lazily at render time, mirroring lang/token.Span (2x uint32 -> Pos on demand).

• The renderer already holds file bytes (diagnostic.SourceStore, used for snippets) - resolution happens where the data is consumed, once, in one place.
• linker's offsetToLineCol + per-field eager conversion die; FieldSpan shrinks.
• Wrinkle: internal/mod builds spans from a line-oriented parser (knows lines, not offsets) - scampi.mod parsing needs offset tracking.
• Harness/goldens assert line/col today; resolution moves into the harness (it has the bytes). Diagnostics goldens regenerate.
• [NAME] check: resolved form could reuse/mirror lang's Pos vocabulary.

[pskry]

Item 4 (std.ln -> std.ref) is VOID: std.ln never existed. The builtin is already named std.ref (std.scampi: 'pub func ref(step: Step, expr: string) any', eval.callRef). The 'std.ln' in the original inventory was an artifact of a broken rg invocation - 'rg -rln' where -r is the REPLACE flag, which rewrote 'ref(' to 'ln' in the printed matches. Nothing to do; item closed as invalid.

[pskry]

Item 6 closed as ACCEPTED OVERLOAD (ruled 2026-07-03): event.Change (per-field mutation event), event.Result (step verdict), and spec.Result.Changed (op outcome flag) are three distinct concepts sharing a word stem. Rename candidates have worse warts - event.Drift stutters against its Drift field and 'DriftExecuted' misreads; event.Mutation buys too little for the churn. Leaving as is.

[pskry]

Item 3 RULED (2026-07-03): the machine that runs scampi is the galley (the ship's kitchen - Kombuese - where the scampi is prepared before service to targets). Rename plan:

• package internal/source -> internal/galley
• source.Source (the access interface: configs, env, cache reads) -> galley.Galley (context.Context stutter pattern)
• MemSource -> galley.Mem, LocalPosixSource -> galley.Local
• prose: 'source-side' -> 'galley-side' (CLAUDE.md boundaries, TERMINOLOGY.md, doc comments)
• spec.SourceReader and the content-origin Source vocabulary (SourceRef, source_local, ...) are UNTOUCHED - Source still means content-origin exclusively; the galley is where those origins get resolved.

Rejected along the way: controller (ansible PTSD), host (too broad), origin (git-ish), operator (human), workstation (anything), caboose (train car trails; galley IS the Kombuese translation), wheelhouse (pip wheels), bridge (network), kitchen (Chef Test Kitchen), cambusa (needs a footnote), pass (reads as verb/password).

Implementation after item 5 lands.

[pskry]

Item 3 addendum: when the galley rename lands, TERMINOLOGY.md gets the naming principle - whimsy below the waterline, plain words on deck. Themed names are fine for internal packages and codenames (galley); anything that surfaces in configs, stubs, errors, or CLI output stays the boring industry term (target, deploy, step). If a user ever types it or reads it in an error, it is not a pun candidate.