@intentius/behold 0.29.40 → 0.29.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/AGENTS.md +148 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +15965 -13076
  4. package/example-writes/README.md +1 -1
  5. package/example-writes/chant.config.ts +0 -6
  6. package/package.json +5 -2
  7. package/web/app.js +327 -21
  8. package/web/carve-export.js +142 -0
  9. package/web/carve-narration.js +268 -0
  10. package/web/carve-narration.test.js +18 -0
  11. package/web/change-set-overlay.js +147 -0
  12. package/web/change-set-overlay.test.js +83 -0
  13. package/web/dots-border.js +66 -0
  14. package/web/dots-border.test.js +27 -0
  15. package/web/dots-kiosk.js +279 -0
  16. package/web/dots-kiosk.test.js +60 -0
  17. package/web/dots-layout.d.ts +10 -0
  18. package/web/dots-layout.js +201 -0
  19. package/web/dots-live.js +316 -0
  20. package/web/dots-live.test.js +220 -0
  21. package/web/dots-lod.js +122 -0
  22. package/web/dots-lod.test.js +78 -0
  23. package/web/dots-recording.d.ts +7 -0
  24. package/web/dots-recording.js +247 -0
  25. package/web/dots-recording.test.js +71 -0
  26. package/web/dots-scene.js +294 -0
  27. package/web/dots-scene.test.js +118 -0
  28. package/web/dots-timeline.js +128 -0
  29. package/web/dots-timeline.test.js +83 -0
  30. package/web/dots-tour.js +153 -0
  31. package/web/dots.js +2124 -0
  32. package/web/dots.test.js +15 -0
  33. package/web/index.html +29 -0
  34. package/web/kiosk-carve.js +219 -0
  35. package/web/kiosk-carve.test.js +26 -0
  36. package/web/kiosk-event-help-ui.js +6 -0
  37. package/web/kiosk.js +21 -6
  38. package/web/operator.js +1 -1
  39. package/web/run-playhead.js +102 -19
  40. package/web/run-playhead.test.js +81 -11
  41. package/web/tour-player.js +204 -0
  42. package/web/tour-player.test.js +115 -0
  43. package/web/tours/behold.tour.v1.schema.json +182 -0
  44. package/web/tours/terralith.json +330 -0
  45. package/web/trunk-lane.js +254 -0
  46. package/web/trunk-lane.test.js +117 -0
  47. package/web/workspace-gates.js +29 -4
  48. package/web/workspace-gates.test.js +23 -2
package/AGENTS.md CHANGED
@@ -59,6 +59,27 @@ a scheduled read: it holds a slot in the read budget, has the read deadline,
59
59
  and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
60
60
  links a proposed decision to its review in hud.
61
61
 
62
+ ## Chant version floors (behold#691)
63
+
64
+ behold shells each project's own chant, so a read can reach a chant that
65
+ predates it. Every read has one floor, and every floor lives in
66
+ `src/chant-floors.ts`:
67
+
68
+ - one constant per read, named after the read (`WHY_CHANT_FLOOR`) and set to the
69
+ chant release that adds it;
70
+ - one entry in `CHANT_FLOORS` (the read in words, the floor, what adds it in
71
+ chant), which is what `behold doctor` lists with the project's chant version
72
+ and whether the floor is met;
73
+ - the code that makes the read checks the project's chant first (`floorMet`,
74
+ `floorRefusal`) and never sends the read to a chant that would reject it.
75
+
76
+ On an older chant the pane that needs the read shows `floorRefusal`'s words
77
+ (the read, the chant that adds it, the project's version) and the rest of
78
+ behold works. The why route does this: `GET /api/workspace/why` refuses before
79
+ spawning the read. A new read adds its constant and entry in the issue that
80
+ adds the read, once the chant release is known, and reads through the read
81
+ contract (`src/workspace-reader.ts`), never chant's library.
82
+
62
83
  ## A pipeline's numbers, from Prometheus (behold#571)
63
84
 
64
85
  `behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
@@ -296,7 +317,13 @@ checkout declares no Terraform root (`controlRepo` in
296
317
  `GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
297
318
  `<env>/releases.jsonl` on the served checkout's `chant/lifecycle` with chant's
298
319
  own reader (`listReleaseEnvironments`, `readReleaseLedger`,
299
- `latestPerComponent`, `recordsForDigest`). The branch is fetched into the
320
+ `latestPerComponent`, `recordsForDigest`). This one still imports
321
+ `@intentius/chant/lifecycle/release-ledger`: no read-contract command lists a
322
+ project's per-environment ledger outside a declared workspace (`workspace
323
+ status` needs a declaration, and `release list` lists cut releases, not the
324
+ `components release` records SQL Yodeler writes), so dropping the import would
325
+ blank the tab for every SQL Yodeler project. The trunk lane (#680) reads
326
+ releases through the contract only. The branch is fetched into the
300
327
  same bare cache the terragucci lane uses (`fetchIntoCache` in
301
328
  src/terragucci-lifecycle.ts). When that fetch fails, the checkout's
302
329
  `refs/remotes/origin/chant/lifecycle` is fetched into a second cache of
@@ -816,13 +843,41 @@ behold does not apply. To change the estate:
816
843
  Every mutation is a gated, durable Temporal workflow with a human-confirmable gate
817
844
  and saga rollback. There is no behold endpoint that mutates the cloud.
818
845
 
819
- A run behold triggered is asked for structured per-step records (chant#1676:
820
- `--progress-json` on the durable path, `--json` on the local one), so the ops
821
- lens paints the run over the declared track and a pending gate renders as a card
822
- with an Approve button. That button is `op-signal`, the same delegated write —
823
- and nothing else about the run is behold's to decide: a stream that dies leaves
824
- the playhead at the last settled step and says so, and a gate paints as pending
825
- only when chant's `gateState` query named it.
846
+ A run behold triggered is asked for chant's run events (#679, chant#4019:
847
+ `chant run <op> --events-json`, `chant run <target> --components --env <env>
848
+ --events-json`), so the ops lens and the dial show each step's start and settle,
849
+ a skip with chant's reason, a cache hit, and the gate or decision point a run
850
+ waits on, as they happen, and a pending gate renders as a card with an Approve
851
+ button. That button is `op-signal`, the same delegated write, and nothing else
852
+ about the run is behold's to decide: the verdict is the stream's own
853
+ `run-settle`, a stream that ends without one leaves the playhead at the last
854
+ settled step and says it was lost, and a gate paints as pending only when chant
855
+ named it (`gate-waiting`, or `chant run status`).
856
+
857
+ `src/run-events.ts` is the one boundary every run line crosses. It validates
858
+ each line against chant's `run-event.schema.json` (vendored in
859
+ `src/run-event-schema/` from @intentius/chant 0.124.28, its source commit in
860
+ `RUN_EVENT_SCHEMA_SOURCE`), since the line comes from the project's chant,
861
+ not behold's, and refuses a line that fails it; it folds the stream into what
862
+ the dial and the ops lens render. The event types are chant's own `RunEvent`
863
+ and `RunEventBody`, imported as types only. `src/run-events-chant.test.ts`
864
+ runs the whole path against a real chant when `BEHOLD_TEST_CHANT_BIN` is set.
865
+
866
+ A run behold did not start is followed when the status read names it: `chant
867
+ run events <run> --json --follow` replays what chant kept on this host and tails
868
+ it to `run-settle`. A run killed outright writes no settle, so a follow that is
869
+ silent for `BEHOLD_RUN_EVENTS_IDLE_MS` (60 s) asks `chant run status` whether it
870
+ still runs, and ends as lost when it does not or after
871
+ `BEHOLD_RUN_EVENTS_MAX_IDLE_MS` (30 min) of silence. A steward run keeps no
872
+ events here, and the playhead says so.
873
+
874
+ The read has a floor, `RUN_EVENTS_CHANT_FLOOR` (0.124.28). Below it behold
875
+ starts runs with the older `--progress-json` (degraded mode: settled steps
876
+ only, no skip reasons, cache hits or gate events, and no follow), translates
877
+ those lines at the same boundary, and the dial and the playhead say they are
878
+ degraded. A local pipeline run (gitlab-ci-local, a forgejo runner) is the one
879
+ path that still reads a log, because chant does not run it; the dial labels it
880
+ best-effort, and only its exit code is certain (src/ci-run.ts).
826
881
 
827
882
  ### The executor contract (#165, #61)
828
883
 
@@ -905,8 +960,8 @@ Two gate cards exist and they are **different acts**:
905
960
  - The **run gate** — `POST /api/ops/:name/signal/:gate` → `chant run approve
906
961
  <op> <gate>` (chant#2121 renamed `chant run signal`, #459). Records the
907
962
  resolution; a runtime that parks a run is woken, and the local one reads it
908
- when the Op runs again (behold runs `chant run <op> --progress-json`, which
909
- exits 3 at a gate and shows as `gated`).
963
+ when the Op runs again (behold runs `chant run <op> --events-json`, which
964
+ says `gate-waiting`, settles `gated` and exits 3).
910
965
  - The **converge gate** — `POST /api/operator/approve/:op/:gate` →
911
966
  `chant approve <op> <gate>`. **Records a fact and unblocks nothing.** chant's
912
967
  gate ledger says it outright: the local executor still refuses a gated op,
@@ -929,6 +984,89 @@ appears in the entity graph. behold names it there, the Namespace as the loop's
929
984
  home, each CronJob as a converge tick — off chant's own
930
985
  `app.kubernetes.io/component: converge-tick` labels, never a naming convention.
931
986
 
987
+ ## Who an approval is recorded as (#690)
988
+
989
+ chant never signs a person in (ws-052); the surface that does passes the person
990
+ to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
991
+ the person for each request, in this order:
992
+
993
+ - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, `.behold.json`
994
+ `approver.header`): behold sits behind a proxy that signed the person in
995
+ through the forge or OIDC, and the header names them. A bare login is an
996
+ account on `--identity-forge` (github unless set). A request without the
997
+ header approves nothing (`403 no-identity`). Refused at startup with a
998
+ `--host` other than loopback, since anyone reaching the port could send it.
999
+ - `--as <principal>` (BEHOLD_APPROVER, `.behold.json` `approver.as`): one
1000
+ person runs behold and names themselves, `github:<login>` or a principal the
1001
+ signers file lists.
1002
+ - Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
1003
+ behold passes no `--actor`.
1004
+
1005
+ Without a trusted header, a request carrying a usual proxy identity header
1006
+ (`PROXY_IDENTITY_HEADERS`, such as `X-Forwarded-User`) is refused with `403
1007
+ identity-header` on every approve route, rather than recorded as someone else.
1008
+ Every approve route (`/api/workspace/gates/approve`, the converge gate's
1009
+ `/api/operator/approve`, the run gate's `/api/ops/:name/signal`) adds
1010
+ `--actor` (`--approver` on `chant run approve`) and `--note "approved in
1011
+ behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
1012
+ `mcp` or `acp`), so the note is where behold is named. A workspace gate that
1013
+ status marks `signed` is approved with `--sign <key>` when behold holds the
1014
+ person's key (`--signing-key` beside `--as`, or `.behold.json`'s
1015
+ `approver.keys` by principal) and refused `422 signed` with the line to run
1016
+ otherwise. The key path never reaches a page: `GET /api/workspace/gates`
1017
+ carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
1018
+ null` and `approverRefusal`. `src/approver-chant.test.ts` runs the whole path
1019
+ against chant with a throwaway key and workspace.
1020
+
1021
+ ## The trunk lane (#680)
1022
+
1023
+ `GET /api/workspace/lane` (src/trunk-lane.ts) answers "what is in flight and
1024
+ where is it?" for a served workspace, read through the reader on every request
1025
+ and kept nowhere:
1026
+
1027
+ - `chant ci list --json` at the root: the trunk's commits within ci.green's
1028
+ window, each `green`, `revoked` or `undecided`, with its phases and runs
1029
+ and its work items (`work`, chant#4029). It reads local tags only, so a
1030
+ commit that failed without ever being green reads `undecided`.
1031
+ - `chant workspace status <env> --json` once per environment, in the order the
1032
+ members' `promotionOrder` gives (merged in member order): the gates with
1033
+ `env` equal to that environment, with `gitSha`, `runId` and `changeSet`, and
1034
+ the deploy records.
1035
+ - `chant release list --json` in each member whose promotion order is not
1036
+ empty: the releases, each with its commit and the environments that run it.
1037
+
1038
+ The answer: `trunk` (or `trunkRefusal`), `commits[]` with `where` (`runs` or
1039
+ `waits` per environment), `environments[]` with `releases`, `deploys` (records
1040
+ no release covers) and `waiting` (each gate with `commitState`),
1041
+ `order` (`promotion`, or `env` when no member declares one), `releaseRefusals`,
1042
+ and the gate strip's approver fields. Gates with no environment stay in the
1043
+ gate strip. The three reads are `ci list` and `release list` through
1044
+ `readTrunk` on the reader (they are contract 1 documents outside `chant
1045
+ workspace`) and `status` through `read`; each has its floor in
1046
+ src/chant-floors.ts (0.124.28), and the route refuses a chant below any of them
1047
+ before spawning. The panel's Trunk tab (web/trunk-lane.js) reads it when opened
1048
+ and approves through `POST /api/workspace/gates/approve`.
1049
+
1050
+ ## A gate's change set on the graph (#681)
1051
+
1052
+ `GET /api/workspace/change-set?gate=<member>/<op>/<gate>&env=<env>`
1053
+ (src/change-set-overlay.ts) reads the gate from `chant workspace status <env>
1054
+ --json`, never from the page, and the change set it binds (`changeSet`,
1055
+ chant#4022) from `chant change-set show <digest> --member <member> --json`
1056
+ (`readChangeSet` on the reader, floor `CHANGE_SET_SHOW_CHANT_FLOOR`,
1057
+ 0.124.28). The answer is that document keyed by graph node: `entries` (those
1058
+ that change something, each with `bucket` create, change or delete and `node`,
1059
+ or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
1060
+ bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
1061
+ failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
1062
+ `planned` (a release gate's release and environment, chant#4045). An entry
1063
+ with no node is kept and listed in the Change set tab, never dropped. The page
1064
+ (web/change-set-overlay.js) outlines each card in the drift legend's tokens
1065
+ (managed for create, foreign for update or replace, degraded for delete or
1066
+ forget) with a tag above it, never a fill; it is opened from the "change set"
1067
+ link on a Trunk tab gate card and turned off from its tab. A public view
1068
+ refuses the route, as it refuses the lane.
1069
+
932
1070
  ## Invariant
933
1071
 
934
1072
  If a request would have behold write to a cloud or to source directly, it's wrong.
package/README.md CHANGED
@@ -456,8 +456,12 @@ a banner. Any other short path answers 404 with a link to `/kiosk`.
456
456
  In a declared workspace, the gates waiting on a person come from
457
457
  `chant workspace status <env> --json`, keyed `member/op/gate` the way arugula's
458
458
  workspace block keys them, so the two show the same set. Standalone, a gate's
459
- button says who chant will record (the user running behold) before the click.
460
- Every approve route refuses in preview mode.
459
+ button says who chant will record before the click: the person `--as` names
460
+ (`--as github:<login>`), the person an authenticating proxy names in the header
461
+ `--identity-header` trusts, or else the user running behold. A gate the
462
+ workspace names in `identity.gates` is signed with that person's key when
463
+ `--signing-key` (or `.behold.json`'s `approver.keys`) gives one, and sent to the
464
+ command line otherwise (#690). Every approve route refuses in preview mode.
461
465
 
462
466
  In a declared workspace, the inspect pane of a member's box or a card has a
463
467
  "why" section. "Read why" asks `chant workspace graph --intent <member dir or