@intentius/behold 0.29.40 → 0.29.42

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 (61) hide show
  1. package/AGENTS.md +180 -10
  2. package/README.md +6 -2
  3. package/dist/cli.js +16121 -13141
  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 +294 -0
  10. package/web/carve-narration.test.js +48 -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/event-help-modal.js +1 -1
  34. package/web/index.html +215 -121
  35. package/web/kiosk-carve.js +225 -0
  36. package/web/kiosk-carve.test.js +26 -0
  37. package/web/kiosk-event-help-ui.js +7 -1
  38. package/web/kiosk-link.js +68 -0
  39. package/web/kiosk-link.test.js +69 -0
  40. package/web/kiosk-metrics.js +2 -2
  41. package/web/kiosk-trace.js +1 -1
  42. package/web/kiosk.html +186 -135
  43. package/web/kiosk.js +65 -7
  44. package/web/motion.js +42 -0
  45. package/web/motion.test.js +64 -0
  46. package/web/operator.js +1 -1
  47. package/web/run-playhead.js +102 -19
  48. package/web/run-playhead.test.js +81 -11
  49. package/web/terralith.html +2 -2
  50. package/web/theme.js +99 -26
  51. package/web/theme.test.js +70 -6
  52. package/web/tooltip.js +212 -0
  53. package/web/tooltip.test.js +193 -0
  54. package/web/tour-player.js +204 -0
  55. package/web/tour-player.test.js +115 -0
  56. package/web/tours/behold.tour.v1.schema.json +182 -0
  57. package/web/tours/terralith.json +330 -0
  58. package/web/trunk-lane.js +406 -0
  59. package/web/trunk-lane.test.js +224 -0
  60. package/web/workspace-gates.js +29 -4
  61. 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,121 @@ 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
+ The release column (#692) sits between the commits and the environments:
1051
+ `releases[]`, every release `release list` names, newest first, each with its
1052
+ `commit`, `label` and digest, its newest `cut` (who, when, and chant's
1053
+ `signatureCheck`), `runs` (environments in promotion order, with components),
1054
+ `waits` (a release gate that binds it, or a gate of its member reached at its
1055
+ commit; `pending`, or `superseded`), and `next`, the environment its member's
1056
+ promotion order names after the last one that runs it (null in the last one,
1057
+ and for a revoked release, which chant never promotes). Each commit carries
1058
+ `cuts`, the releases cut from it.
1059
+
1060
+ `configOnly` is true when a release carries artifact digests and they equal
1061
+ its previous release's. The previous release is the one of the same member
1062
+ cut from the nearest older commit: releases are ordered by their commit's
1063
+ place in the trunk list (first-parent, newest first), a commit older than the
1064
+ list after every listed one, and ties (one commit, or commits outside the
1065
+ list) by `release list`'s order, newest cut first. That is how `release cut`
1066
+ reuses an unchanged artifact's digest. It is null for the oldest release and
1067
+ for a release with no artifact digests (a member with no components).
1068
+
1069
+ The revoked fields ship in chant 0.124.29 (`RELEASE_COLUMN_CHANT_FLOOR`,
1070
+ chant#4033, chant#4043): `revoked` on a `release list` release (the
1071
+ ci/revoked tag, with `rollback`, the lines status gives for each component
1072
+ running it), `superseded` on each environment (release gates chant reads as
1073
+ superseded, never approvable), `rollback` on an environment's releases, and
1074
+ `release` and `rollback` on a deploy record. `releaseColumn: {full, floor}`
1075
+ says whether they were read. Below the floor nothing is refused: the column
1076
+ comes from `release list` alone with no revoked mark, and the tab says which
1077
+ chant would add it. The fixtures in `src/__fixtures__/trunk-lane/` are
1078
+ recorded from chant main in the workspace `src/trunk-lane-fixture.ts` makes,
1079
+ and `src/trunk-lane-chant.test.ts` reads the same workspace through a real
1080
+ chant when `BEHOLD_TEST_CHANT_BIN` names one.
1081
+
1082
+ ## A gate's change set on the graph (#681)
1083
+
1084
+ `GET /api/workspace/change-set?gate=<member>/<op>/<gate>&env=<env>`
1085
+ (src/change-set-overlay.ts) reads the gate from `chant workspace status <env>
1086
+ --json`, never from the page, and the change set it binds (`changeSet`,
1087
+ chant#4022) from `chant change-set show <digest> --member <member> --json`
1088
+ (`readChangeSet` on the reader, floor `CHANGE_SET_SHOW_CHANT_FLOOR`,
1089
+ 0.124.28). The answer is that document keyed by graph node: `entries` (those
1090
+ that change something, each with `bucket` create, change or delete and `node`,
1091
+ or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
1092
+ bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
1093
+ failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
1094
+ `planned` (a release gate's release and environment, chant#4045). An entry
1095
+ with no node is kept and listed in the Change set tab, never dropped. The page
1096
+ (web/change-set-overlay.js) outlines each card in the drift legend's tokens
1097
+ (managed for create, foreign for update or replace, degraded for delete or
1098
+ forget) with a tag above it, never a fill; it is opened from the "change set"
1099
+ link on a Trunk tab gate card and turned off from its tab. A public view
1100
+ refuses the route, as it refuses the lane.
1101
+
932
1102
  ## Invariant
933
1103
 
934
1104
  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