Rename token script to Update-SiteDeployToken with Declare-BashScript - #6

Capture two related architectural decisions worked out in conversation:

(1) ExecutableUnit.Parameters() is asymmetric by type. Node returns the
full Go-method signature (current Bind behavior, no code change).
Subgraph returns the bubble-up variable surface — the deduped,
type-checked set of VariableValue references walked across children's
slots, recursing into nested subgraphs. The topological-root union
framing is gone; the graph-walk over slot fills is the simpler primitive.
No separate UnboundSlots() accessor — variables ARE the bubble-up; that
abstraction collapsed once the binding layer existed.

(2) Execution model commitment: stack frames + subgraph ownership +
per-type executors. Every subgraph invocation pushes a frame carrying
its own Variables overlay (scope-chain to parent), Results map,
Attempts, and Status. Concurrent invocations of the same Subgraph
template (e.g., gather iterating 16 items) are isolated by frames, not
by cloning templates. Subgraphs own children via an explicit `parent
*Subgraph` pointer; per-type executors (root / gather / choose /
wait_until / plain) dispatch their own children's frames. The current
Subgraph.Branch boolean is deprecated by this model.

Doc changes:

  - D3 rewritten with the asymmetric Parameters() semantics. Note added
    about Gather's use of Subgraph.Parameters() as the discovery surface
    for per-iteration variable binding.

  - D11 inserted (forward-looking). Documents the Frame struct, what
    frames solve (per-iteration scoping, scope chain, concurrent
    isolation, compensation), what stays per-executor (retry policy,
    status emission, dispatch logic), the ownership pointer, and the
    Branch deprecation.

  - Phase 3 rewritten. Scope: Subgraph.Parameters() bubble-up via
    graph-walk + parent pointer + Subgraph.AddChild method + migration
    of the two direct Children-append sites in pkg/op/graph.go. Full
    frame plumbing and per-type executors stay downstream (Step
    13/14/15) — Phase 3 plants only the forward-compat scaffolding.

  - Locked decisions extended with #6 (execution model) and #7
    (Parameters() asymmetry).

D7 / D9 / D10 unchanged — they describe the current execution model
(env.variables-based, executor stores variable map on receiver) which
remains accurate for 13.0(n) Phases 1-6. D11 forecasts the model shift.

Issue: #283

…e model

Checkpoint of phase-8 step 21.4 — the op-free pkg/platform capability. NOT a green tree: the
pkg/op/provider/pkg consumer is still on the old platform API (the #6 veneer migration), so the
build is red pending that. pkg/platform itself and cmd/lore compile.

- pkg/platform: op-free Composite package-manager router + driver + native leaf families
  (apt/dnf/pacman, brew/port, snap/flatpak, winget); purl-typed routing with construction-time
  normalization; per-leaf state-query verification (bracket); named *Spec factories + Detect + the
  New seal. Imports nothing from pkg/op (same shape as pkg/result / pkg/status).
- Service managers: systemd + SysVinit, selected by runtime init detection (detectInit probes
  /run/systemd/system; the named factories declare systemd, Detect overrides on a live box).
  SysVinit Enable/Disable are honestly unsupported (boot-persistence is out of scope for the
  systemd-less boxes where SysVinit applies). WithServiceManager removed — the service manager is
  owned (factory-declared or detected), never injected.
- cmd/lore builder.go: seal the detected *Spec via platform.New before reading OS()/Distro().

Deferred (tree goes green when these land): the pkg.Provider veneer + pkg/op/provider/pkg
migration to PURL-based verbs and op.Receipt adaptation (#6), and the stale pkg/platform test
rewrites.

…sign (#6)

Rewrite the step-21.4/#6 plan to the Composite reality. pkg.Provider becomes a thin veneer:
Resource -> []PURL -> router.{Install,Remove,Upgrade}(kwargs) -> adapt []platform.Receipt;
convergence and verification live in the leaf. A materialized []PURL (not an iter.Seq) feeds
the batch-by-type router, which returns one receipt per package in input order. cask becomes a
kwarg (drops the cask positional and runBrewCask); no manager kwarg (routing is by PURL.Type).

Update is retained, two flavors: an automatic, staleness-gated per-leaf refresh (six rules), and
a manual force-refresh -- PackageManager.Update() fans out to every leaf, and the provider keeps
Update / pkg.update -> router.Update(). Neither is built yet (the manager.go "no public Update"
comment was aspirational); tracked as task #9, the prerequisite for the provider's Update verb.

Implementation order: #9 (platform Update + auto-refresh) then the #6 veneer migration, ending at
make check green for pkg/op/... and cmd/lore/...

…part A)

Add the manual force-refresh half of the index-update feature (#9) and harden the shell-out
against interactive hangs. NOT a green tree -- the #6 consumer migration and cmd/writ stale code
remain; pkg/platform itself compiles.

- manager.go: PackageManager gains Update() error -- the manual force-refresh (the automatic
  staleness gate is part B, still pending).
- composite.go: the router fans Update() out to every leaf concurrently and errors.Join's failures.
- driver.go: driver.Update() calls the optional refresher; refresher is the new optional interface
  (apt/dnf/pacman/brew/port implement it; live-store managers snap/flatpak/winget no-op).
- refresh() primitives: apt-get update, dnf makecache, pacman -Sy, brew update, port -N selfupdate
  (real *_os + fail-loud *_other stubs). Elevation follows each manager's ownership model: brew
  none; apt/dnf/pacman/port require sudo.
- helpers.go: runShellCommand made hang-proof -- a 30m timeout, sudo -n (fail fast, never prompt),
  an endless "y\n" stdin backstop for prompts the per-tool flags miss, and DEBIAN_FRONTEND=
  noninteractive. The scattered sudo is a stopgap; a TODO marks where it centralizes into the
  ElevationOffer/Elevator (one credential-cached, policy-governed, audited session).

Empirically: brew update run on a live mac (exit 0); the elevated commands are CI/box-verified.
Deferred: part B (the automatic staleness gate), and the pkg/platform test rewrites -- the test
package does not compile yet, so Update/refresh have no runnable coverage. That is next.

… the new API

Make the pkg/platform tests genuine -- compile and pass -- covering the #9 Part A index-update work.

- helpers.go: runShellCommand becomes an injectable package var (test seam), so tests assert the
  (command, sudo) each leaf's refresh issues without shelling out or needing root.
- update_test.go: composite.Update fan-out + failure aggregation (fake leaves).
- update_darwin_test.go / update_linux_test.go: per-leaf refresh command+sudo -- brew ("brew update",
  no sudo) and port ("port -N selfupdate", sudo) run on macOS; apt/dnf/pacman (sudo) are //go:build
  linux, CI-verified.
- Rewrote 12 stale test files (constructors / detect_* / platform / spec / defaults and the four
  *_managers_other) from the removed per-manager string API to the new factories + Composite router +
  PURL/Receipt contract; platform_test.go retargeted to ResolvePurlType / DefaultPurlType / fail-closed
  routing. pkg/platform tests: 52+ green (re-verified via make).

Docs: the 3.4 verb-surface section now documents Update (manual force-refresh + the in-progress
automatic staleness gate); 3.4 status + pkg-install-reconciler.md record Part A landed and the test
rewrite done.

Tree still red on out-of-scope consumers (#6 pkg/op/provider/pkg, cmd/writ); pkg/platform is green.

…queued plan)

Complete #9 with the automatic half of index update.

- driver.go: stalenessAware interface + driver.ensureFresh(), gating Install/Upgrade/Search/Available
  (never Remove/Installed/Version). A leaf is gated only when it is both a refresher and stalenessAware
  and its index age exceeds refreshTTL; refresh is best-effort (failure non-fatal).
- helpers.go: refreshTTL (24h knob), unknownIndexAge, indexAgeOf(path).
- linux_managers_linux.go: apt -> /var/lib/apt/lists mtime, pacman -> /var/lib/pacman/sync mtime. brew
  and dnf self-manage their freshness and port defers, so they are not stalenessAware (manual Update
  still force-refreshes all five). A successful refresh bumps the mtime, so a batch triggers one refresh.
- update_test.go: cross-platform gate tests (stale -> refresh, fresh -> skip, local ops -> no gate,
  index-consuming ops -> gate) via a fake rawDriver. pkg/platform green (gate mechanism + helpers run on
  macOS; apt/pacman indexAge bodies are _linux, CI-verified).

Docs: 3.4 verb-surface + status + pkg-install-reconciler now record #9 (manual force-refresh + the
automatic gate) implemented and tested.

Also queues the subgraph-result-flow concern as a plan: subgraph-result-flow.md (#10 investigate whether
subgraph executors toss results; #11 two verification tests, Go + Starlark, via flow.Provider.Completed),
referenced from 21-lore-migration.md.

Tree still red on out-of-scope consumers (#6 pkg/op/provider/pkg, cmd/writ); pkg/platform is green.

A subgraph run through the flow.subgraph verb threw away its children's output: dispatchWithRetry
(helpers.go) returned only an error, discarding DispatchChild's result, and flow.Provider.Subgraph
(provider.go) returned nil unconditionally. So a flow.subgraph-bound subgraph's terminal result never
reached GraphExecutor.Run. (#10 confirmed this; the structural op.Subgraph path, the executor, and
flow.Complete were already correct.)

Fix:
- helpers.go: dispatchWithRetry returns (any, error), capturing DispatchChild's result on the succeeding
  attempt (nil on cancel/exhaustion). This matches dispatchBodyChildren, which already returns `last`.
- provider.go: flow.Provider.Subgraph carries lastResult across the children loop and returns it instead
  of nil.

Tests (#11):
- result_flow_test.go: TestSubgraphBoundAction_FlowsLeafResult builds root → flow.subgraph subgraph →
  flow.complete leaf (output = sentinel), runs it, asserts Run returns the sentinel. RED before the fix
  (result = nil), GREEN after; logs the bubbled value. TestStructuralSubgraph_FlowsLeafResult is a control
  that passes throughout. integration_test.go's inventory import swapped to flow/gen to free the flow test
  binary from the #6-blocked inventory.
- result_flow_starlark_test.go: the Starlark mirror, t.Skip'd, gated on #12 (plan.Provider.Assemble nil-
  origin panic, an unrelated plan bug surfaced here).

TEMP mitigation: inventory.gen.go disables the provider/pkg/gen + provider/service/gen registrations (the
#6-broken packages) so the inventory + star build during the migration. Marked TEMP in-file; `make
generate` regenerates and restores them. The local build/star.lkg was refreshed off this state (reduced:
no pkg/service providers).

flow tests green; tree still red on out-of-scope consumers (#6).

….subgraph

Foundation (steps 1-2) of the unify-subgraph-execution plan. The root stops being a structural special
case: it is built by NewSubgraph from a shared spec and runs through flow.subgraph like any subgraph.

- executable_unit.go: actionName field + ActionName()/setActionName; ExecutableUnitSpec.WithActionNamed,
  which validates the name against the global receiver registry and PANICS if unannounced (fail-loud, the
  earliest announcement guard) -- the fluent counterpart to WithAction(action). Universal pattern: hold a
  resolved action -> WithAction; hold only a name -> WithActionNamed.
- node.go / subgraph.go: NewNode/NewSubgraph accept action-by-name; Execute resolves the name lazily at
  dispatch via RuntimeEnvironment.ActionByName (resolved action wins; both-empty falls through to the
  still-present structural path).
- subgraph.go: NewRootSubgraphSpec() names flow.subgraph; newRootSubgraph removed.
- graph.go / dependencyview.go / load.go: build the root via NewSubgraph + the shared root spec.
- receipt.go: Commit guards a nil Action() (by-name units) and stamps ActionName().
- flow_announce_test.go: announces flow into the pkg/op test binary (every graph now needs flow announced).

The action == nil structural path is kept as a fallback; deleting it (after auditing action-less
subgraphs) and converging the three child-walks are the remaining steps. pkg/op + flow tests green
(scoped; whole-tree build still red on #6). #11 guard still passes; its root now runs via flow.subgraph.

…ndencyView, approve #15 plan

Clears all outstanding work so the graph-assembler-convergence (#15) starts on a clean tree.

#13 unify-subgraph-execution — complete:
- subgraph.go: deleted the action == nil structural execution path (replaced by a no-action error guard
  mirroring Node.Execute); NewSubgraph rejects action-less specs.
- flow/helpers.go + flow/provider.go: converged the child-walks onto walkSubgraphChildren; flow.Subgraph
  and flow.Gather both use it.
- activation_record.go: retry is now intrinsic to the single dispatch primitive DispatchChild
  (policy-driven attempts + ctx-cancellable backoff + ErrPaused/ctx.Err() short-circuit);
  flow.dispatchWithRetry deleted. Retry is impossible to bypass; gather bodies honor RetryPolicy.
- result_flow_test.go: structural control retargeted to TestBareNodeUnderRoot_FlowsLeafResult.
- doc-comment cleanups (structural -> by-name) across executable_unit/node/receipt/graph_executor/
  activation_record/trace/validate.

Dead code:
- removed pkg/op/dependencyview.go + dependencyview_test.go (orphaned synthesizer; a real dependency
  view will later be a filter over a graph/trace, per subgraph-result-flow follow-ups).

Plans:
- graph-assembler-convergence.md: approved, with NewGraph + LoadGraph sequence diagrams (NewGraph the
  sole &Graph{} builder; LoadGraph decodes -> assembleGraph -> NewGraph; graphMetadata threads the
  document's checksum/signature/schemaVersion/timestamp).
- unify-subgraph-execution.md: status updated through #13 completion.

Also sweeps in pre-existing cmd/lore builder.go + builder_test.go (detectPlatform -> platform.New;
#6-blocked). pkg/op + flow green (scoped); whole-tree still red on #6.

Both were at status: draft despite shipped work; neither is complete (the #6 veneer remains):
- platform-unification.md (step 21.4): the op-free pkg/platform Composite reshape (#1-4) is committed;
  remaining are #5 (delete the redundant op managers) and #6 (the pkg.Provider veneer + consumer
  migration), both still scoped in its Work breakdown -> in-progress.
- pkg-install-reconciler.md (#9 + #6): #9 Update is complete (Part A manual + Part B auto-gate,
  committed cd92631); the stale "Remaining: #9 Part B" status line is corrected; #6 veneer remains
  -> in-progress.

NewGraph and the load path now both prepare a root + metadata and call one private buildGraph -- the sole
place that hand-builds &Graph{} (Option B from graph-assembler-convergence.md).

- graph.go: + graphMetadata + buildGraph (sets fields from metadata, derives unitsByID, recomputes the
  checksum from CanonicalContent). NewGraph builds the root (populate derives edges) + fresh metadata,
  calls buildGraph, then signs the canonical via spec.SopsClient. NewGraphSpec inlines the canonical root
  (ID "root", binds flow.subgraph by name) -- the single root call site. LoadGraph decodes -> assembleGraph;
  assembleGraph (renamed buildGraphFromPayload) builds the root preserving the document's edges + metadata
  and calls buildGraph.
- node.go: assembleNode (renamed buildNodeFromPayload), below NewNode.
- subgraph.go: assembleSubgraph (renamed buildSubgraphFromPayload) + (*Subgraph).linkChildren moved in;
  NewRootSubgraphSpec deleted.
- helpers.go: resolvePayloadAction moved in.
- load.go: deleted.
- marshalers_test.go: + TestGraph_SaveLoad_RoundTrip_ChecksumPreserved (round-trips a non-derivable hand
  edge; asserts recomputed checksum == document's, edges/schemaVersion/timestamp intact).
- comment-only: validate_test.go, flow_announce_test.go, provider/flow/result_flow_test.go (stale
  NewRootSubgraphSpec mentions).

Root call-sites: 3 -> 1 (NewGraphSpec). Only buildGraph hand-builds &Graph{}. Semantic shift: load now
recomputes the checksum (an implicit integrity check) instead of copying the document's stored one.
pkg/op + flow green (scoped); whole-tree red on the out-of-scope #6 consumers.

…e, reject)

The load path now recomputes the checksum from the canonical content and compares it against the document's
stored value, rejecting a mismatch ("op.LoadGraph: checksum mismatch") -- a real integrity check against
post-write alteration, replacing the recompute-only behavior.

- graph.go: assembleGraph captures buildGraph's result and errors when g.Checksum() != p.Checksum; doc
  updated from "implicit" to an explicit compare-and-reject.
- marshalers_test.go: + TestGraph_Load_ChecksumMismatch_Rejected (a tampered stored checksum is rejected);
  the round-trip test still passes (valid docs verify).
- graph-assembler-convergence.md: status -> complete; section 2 + Status reflect the real integrity check;
  records the decision to accept the root spec inlined in both NewGraphSpec and assembleGraph (contained,
  no shared helper).

pkg/op + flow green (scoped); whole-tree red on the out-of-scope #6 consumers.

… guard (#12)

plan.Provider.Assemble dereferenced a nil op.Origin (origin.Scope()/Annotations(), provider.go:176) when
plan.assemble is invoked from Starlark with the default origin=. Default a nil origin to the zero OriginBase
before the tool-stamping, so the scope/annotations read is safe.

- provider/plan/provider.go: `if origin == nil { origin = op.OriginBase{} }` ahead of the tool stamp.
- provider/flow/result_flow_starlark_test.go: removed the t.Skip; TestSubgraphBoundAction_FlowsLeafResult_Starlark
  now runs and passes -- the result-flow proven end to end through the Starlark plan path (plan.subgraph ->
  flow.subgraph -> plan.run).
- subgraph-result-flow.md: Resolution + Status record the Starlark guard green and #10/#11 fully closed.

pkg/op + flow + plan green (scoped); whole-tree still red on #6.

… commit 1 of 2)

Rewrite provider/pkg onto the new pkg/platform Composite API ([]PURL router verbs, per-package Receipt,
Update -> router.Update); regenerate provider/pkg/gen; re-enable provider/pkg/gen in the inventory.
provider/service/gen stays disabled until commit 2 (the provider/service migration).

- provider/pkg: resource.go (Version + Etag via PackageManager().Version), receipt.go (per-package shape:
  op.ReceiptBase + Manager + InstalledBefore + PreviousVersion), helpers.go (resolveType + toPURL[s]),
  provider.go (Install/Remove/Upgrade + Compensate* + Installed/NotInstalled/VersionGTE/Observe over []PURL;
  Update via the router). Tests updated.
- inventory.gen.go: provider/pkg/gen enabled; provider/service/gen kept disabled (TEMP, commit 2).
- cmd/lore/lore/builder.go: addNativeSoftwarePackages drops the cask positional, adopts kwargs; the gating
  test TestBuildPackage_NativePackageProducesParentedPhaseSubgraph passes.
- pkg-install-reconciler.md: #6 scoped to two commits (pkg, then service); status.

provider/pkg + cmd/lore + the gating test green; the full pkg/op tree greens after commit 2.

…ation (#6, commit 2 of 2)

Bring provider/service's test mockPlatform to the current platform.Platform (add DefaultPurlType /
ResolvePurlType / PackageManager; drop the 5 dead old-API methods) -- its production code already built on
the new API. Regenerate the inventory canonically via `make generate`, which re-enables provider/service/gen
and removes the service-only TEMP mitigation -- fully reverting the inventory workaround.

- provider/service/provider_test.go: mockPlatform now matches the new platform.Platform interface.
- inventory.gen.go (pkg/op + cmd/star): regenerated canonically; provider/service/gen re-enabled.
- pkg-install-reconciler.md: #6 COMPLETE (both commits); status.
- 21-lore-migration.md: recorded the remaining consumer migrations surfaced by the full-tree error scan
  (cmd/devlore-test, cmd/writ) so they're not lost.

The whole pkg/op tree is green and cmd/star builds. Remaining barriers to a fully-green whole tree, tracked
separately: cmd/writ + cmd/devlore-test (consumer migrations) and a fresh non-reduced build/star.lkg.

…rewritten to current entities

- The two 21-prefixed docs drop their dead numbers: 21-graph-immutability.md -> graph-immutability.md,
  21-lore-migration.md -> lore-migration.md (git mv; frontmatter titles and internal self-references rewritten
  name-based; all eleven referrer files updated).
- "step-21 seal" citations rewritten to "the graph-immutability seal": pkg/op node.go / planner.go / subgraph.go doc
  comments, lore-migration.md, lore-command-rewrites.md, 2.5, 5.2 (the latter two now link the doc by name).
- demo-milestone.md rewritten off its pre-renumber scheme by entity: assemble/orphan/type-check -> steps 13/14/16,
  function values -> step 25, PR gate -> step 24, the seal criteria -> name-based graph-immutability references.
- 3.4-platform-package-managers.status.md: 21.4/21.5/21.6 -> steps 19/20/21; platform-unification.md's internal
  header and pkg-install-reconciler.md's title likewise (step 19; step 20 / #6).
- eager-property-projection.md: "step 25 / F3" -> step 26 with a step-doc pointer; file/resource.go's "(step 22)"
  -> "(step 23)"; phase-8.md's historical test-triage aside -> step 18; graph-immutability.md's unresolvable
  pre-renumber "step 22" reference rewritten descriptively, its "step 24 (function values)" -> step 25.
- 13.0-n.md's internal sub-step numbering is intentionally untouched (its own scheme, not phase steps), as are
  former_step/formerly breadcrumbs -- those are the historical record.