@intentius/behold 0.19.0 → 0.21.0

package/AGENTS.md

@@ -14,6 +14,23 @@ apply creds.
   - Actions (delegated writes): `op-run` (start an `ApplyOp`/`ReconcileOp`),
     `op-signal` (approve a gate), `op-status` / `op-report` (watch it).
 
+## A declared workspace
+
+A directory with a `chant.workspace.json` is a chant workspace (chant ≥ 0.81.0,
+INTENTIUS/chant#2524). `behold serve <root>` serves it from chant's own member
+list (`chant workspace ls --json`, read contract 1; any other contract is
+refused), and reads each `chant` and `terraform` member through `chant
+workspace graph --member <name>`. A `choudoufu` member keeps behold's own
+reader, whose vocabulary (rungs, ownership, adoptable rows) chant's graph does
+not carry. Node ids are `<member>/<id>` with the declared member name, the same
+form chant composes. A member chant cannot read is drawn as one
+`UnreadableMember` node carrying `attrs._unreadable: {code, message}` with
+chant's reason code. An `other` member is listed on startup and in doctor and
+draws nothing. `.behold.json`'s `members` are ignored beside a declaration;
+`behold doctor --fix` writes the declaration for an estate that has only them.
+Several directories on the command line (`behold serve a b c`) stay the loose
+view behold composes itself.
+
 ## Getting a server
 
 ```sh
@@ -239,7 +256,8 @@ Two sources, in this order:
 1. `attrs._behaviour` on the nodes, as `chant graph --live --overlay` painted
    them, with `meta._behaviour` beside them for the graph-level half.
 2. `behaviour.<env>.json` at a member's root — `{meta, entities: {<address>:
-   block}}` — read **only** when no node of that member carries the attr, and
+   block}}` — read **only** when no node of that member carries the attr and
+   the member's read carried no `meta._behaviour` either (#402), and
    **only on the overlay** (`/api/graph` is the source graph; a prediction
    about a live account has no business on it). The file's keys are the
    member's own addresses; behold prefixes them to reach the composed id
@@ -261,6 +279,41 @@ overlay is untouched either way: nothing in this pass reads or writes
 `_status`. `?logical=1` projects a different picture and carries no behaviour
 block in M1.
 
+### Live versus declared (#402, M5)
+
+With a traffic level, `/api/overlay` predicts each member twice and carries
+both figures and their difference. The level is `?traffic=` on the request,
+else `.behold.json`'s `{"behaviour": {"traffic": "100 rps, p50"}}`, else none;
+with none nothing is asked for and the payload is exactly M1's. behold never
+defaults a level, because every figure is *at* one.
+
+`meta.behaviour` gains `live`, `declared` (each `{perHour, currency, basis}`,
+where `basis` is `total` for a figure the engine stated and `sum` for behold
+adding the engine's per-entity figures) and `delta` (`{perHour, currency}`,
+live minus declared), plus the same three per member under `members[<name>]`.
+A delta is only ever like with like: one currency, and two totals or two sums.
+Anything else yields no delta and a line in `diagnostics` saying why. A node
+also carries the file's block under `attrs._behaviourDeclared`, including a
+node the account no longer holds, which has no `_behaviour` at all.
+
+Who reads what is `src/behaviour-delta.ts`'s header. A chant member's live
+half is its own overlay read with `--traffic` added (sent only to a chant at
+0.75.0 or newer; an older one rejects the flag). A choudoufu member is not
+read by chant, so behold predicts it through a generated reader project with
+`binary: "choudoufu"` (the Terraform member's scratch project, under
+`behold-chdf-*`), which needs the optional terraform lexicon. A terraform
+member has no live half and so no delta.
+
+The declared half goes through `memberIr` and is cached under the member's
+source stamp plus the traffic level. The live half goes through `overlayIr`
+and is dropped by whatever drops the overlay. With a level set, the
+`behaviour.<env>.json` documents are not read at all: a fixture's figures
+beside a real prediction would be two answers to one question.
+
+`/api/graph?traffic=` (or the config default) paints the declared side alone
+as `attrs._behaviour` with `meta.behaviour.declared`. The file is the only
+estate that route has, so it carries no live half and no delta.
+
 ### Colour by drift, cost or headroom (#399, M2)
 
 The SPA colours the graph by one of three modes. The mode is **client-side
@@ -534,7 +587,17 @@ inside a project, and it does not weaken the invariant above:
 render with the deltas baked into the SVG, which is how `behold export` and
 static snapshots honour a hand layout.
 
-The second exception is the carve walkthrough's two steps above (#254), and it
+A declared workspace (#464) keeps that file in the workspace root, the
+directory holding `chant.workspace.json`, rather than in its first member.
+
+`behold doctor --fix` (#464, ws-015) is the third exception, and it runs only
+when you type the flag: for an estate root whose members are listed in
+`.behold.json`, it writes `chant.workspace.json` in that root (never over an
+existing one) and moves the saved `.behold/layout.json` from the first member to
+the root with its node ids rewritten. It then runs `chant workspace check`. The
+old layout file and `.behold.json` are left as they were.
+
+The fourth exception is the carve walkthrough's two steps above (#254), and it
 is narrower still: they exist only when behold booted a `behold demo carve`
 copy, they write only into `<copy>/app/carveout/`, and the directory they write
 into is a scratch dir behold created inside a directory it copied for you a
@@ -736,7 +799,7 @@ its own graph and overlay counts as it runs.
 | `terralith-1` | `terralith-gen` at scale 1 plus the `estate.chdf.hcl` sidecar it omits, applied by choudoufu from nothing: 79 cards, all 79 bound | docker, choudoufu, go |
 | `terralith-4` | the same at scale 4: 301 cards, all 301 bound. The estate behold is sized against | the same |
 | `terralith-4-adopt` | scale 4 again, but STOCK terraform applies it first, so nothing wears a marker: 301 cards — 85 UNOWNED, 84 bound by derived identity alone, 132 neutral. One `choudoufu live-import` line, which the up script prints and you run, and all 301 read bound | docker, choudoufu, go, terraform |
-| `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktf/hcl2json` beside behold — optional peers behold declares and does not install |
+| `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktn/hcl2json` beside behold — optional peers behold declares and does not install |
 
 **The scratch, by name and port.** Each emulator is the entry's own, booted by
 its up script and removed by the `scripts/down.sh` that script wrote into the
@@ -866,9 +929,9 @@ water park's `access/` before it was taken:
 
 1. **The lexicon is opt-in.** chant resolves the lexicon from the config file's
    own location, so the generated project has to see it, and making it a
-   dependency would put `@cdktf/hcl2json`, a ~1.8 MB wasm blob, in the install
+   dependency would put `@cdktn/hcl2json`, a ~1.8 MB wasm blob, in the install
    of every user who serves a chant project. `@intentius/chant-lexicon-terraform`
-   and `@cdktf/hcl2json` are therefore **optional peers**: declared in
+   and `@cdktn/hcl2json` are therefore **optional peers**: declared in
    package.json (the only place their versions are named, the refusal reads
    them from there), never installed by behold, probed at serve and doctor time,
    and refused with the one install line and where behold looked. The same gate
@@ -1001,6 +1064,28 @@ and marking every one of them would say nothing.
 This is presentation, not vocabulary. `statusVocabulary` gets no terraform row:
 there is no status to name. See #429 for the measurement that established it.
 
+### An adoptable row is painted like an unowned one, plus its evidence (#413)
+
+A `NEEDS_DISCOVERY` omission paired with an `adoptable[]` row at the same
+address paints `warn` with `ownership: "foreign"`, the same verdict the UNOWNED
+branch gives and for the same reason: the live object carries no marker for
+this estate. On its own, `NEEDS_DISCOVERY` stays neutral — the declaration
+names no identity, and with nothing found that is a "could not answer" rather
+than an action.
+
+The card leads with `attrs.adopt`, which is choudoufu's own `adopt_command`
+here rather than the marker pair an unowned row carries. `adoptLine`'s
+composed-command branch had no real caller until this. behold composes no
+command of its own: the API that writes a tag differs per resource type.
+
+`attrs.matchedOn` is the difference in kind. An unowned row needs no evidence
+because the identity IS the match; here choudoufu asserts that a live object is
+a declaration because their identity-bearing arguments agree, and a person
+about to stamp two tags onto somebody's resource is owed the list.
+
+`web/app.js` renders both through the one copyable row, and its tooltip says
+whether the line is a command or a pair of tags.
+
 ### The adoption sweep is off unless a serve asks (#412)
 
 `live-plan -json` carries `adoptable[]` (live resources the estate-wide sweep

package/README.md

@@ -310,6 +310,55 @@ behold shells the **project's own** chant (resolved from the project's
 `@intentius/chant ^0.18.1` or later for the live overlay; `graph --live` observed
 nothing before that fix.
 
+## Linking to a view, and framing behold in a host
+
+The view is in the URL. behold reads it at boot and writes it back as the view
+changes, so a reload keeps it and a link opens where the sender was:
+
+```
+http://localhost:4600/?member=delivery&zoom=components&env=prod&node=delivery/appService
+```
+
+`member`, `zoom`, `env`, `tier`, `lens` (the colour: `drift`, `cost` or
+`headroom`), `node` and `radial` (`1` or `0`). An empty `env=` is the source
+graph. A value the estate can't honour (a member it doesn't have, a zoom it
+doesn't offer) is named on the now line. A static export takes the same
+parameters against what it captured.
+
+A host pane, such as arugula's workspace block, frames behold with
+`?embed=1&host=<the host's origin>`, and optionally `theme=light`, `dark` or
+any theme name the picker lists:
+
+- the panel and the inspect pane start folded, and the Deploy tab and the theme
+  picker are gone
+- picking a card posts `{type: "behold:select", member, node}` to the parent at
+  `host`; picking a member's box posts the same with `node: null`
+- the parent moves the view with `{type: "behold:view", ...}`, carrying any of
+  the URL's fields (`member: null` is the whole estate). Messages from any
+  other origin are ignored
+- gates are the host's to approve: behold draws them and says so
+
+`gates=<env>` sets the env the gate strip reads, apart from the graph's, so a
+host can open behold on the source graph and still show the gates of the env
+it watches.
+
+behold binds 127.0.0.1 and answers only loopback names, since it runs writes
+with the credentials of whoever started it. A page from another site can't
+write to it. A host that frames behold through a proxy of its own passes the
+proxy's name with `--allow-host <name>` (or `BEHOLD_ALLOWED_HOSTS`); `--host`
+(or `BEHOLD_HOST`) binds another address, which then needs `--allow-host` for
+the names it is reached by.
+
+In a declared workspace, the gates waiting on a person come from
+`chant workspace status <env> --json`, keyed `member/op/gate` the way arugula's
+workspace block keys them, so the two show the same set. Standalone, a gate's
+button says who chant will record (the user running behold) before the click.
+Every approve route refuses in preview mode.
+
+A host that already watches the workspace tells behold it changed with
+`POST /api/refresh?notify=1`, instead of running behold with `--poll` beside
+it. behold drops its cached reads and every open page re-pulls.
+
 ## Terraform carve-out: `behold carve <report.json>`
 
 `chant carve advise` ranks a Terraform estate by **peelability**: how cleanly
@@ -375,7 +424,11 @@ config, kept separate from `chant.config.ts` so behold's concerns (like the
 tier picker) don't leak into chant's. Three keys: `tiers` below, `executor`
 (which forge deploys an environment), and `members`, spelled `[{ "dir": "x", "kind":
 "chant" | "choudoufu" | "terraform" }]`, how an estate root names what it
-composes, fail-closed on a kind behold has no reader for. First, the
+composes, fail-closed on a kind behold has no reader for. `members` is
+deprecated: a chant workspace declaration (`chant.workspace.json`) lists an
+estate's members for every reader, and beside one, `.behold.json`'s list is
+ignored. `behold doctor --fix` writes the declaration from it (see
+[Serve a chant workspace](https://intentius.io/behold/using/workspace/)). First, the
 project's deploy-**tier** axis, a dimension orthogonal to `environment` (chant
 has no native tier concept; it is entirely a project convention, e.g. Loom's
 components branching on an env-conditioned `namingParams.tier`):

package/demos.json

@@ -65,7 +65,7 @@
     },
     {
       "name": "terraform-estate",
-      "description": "A multi-root Terraform estate, declared only: two roots applied separately (envs/prod and platform) plus the shared module both are built on — 37 cards boxed by root, module calls expanded into their own contents, and the two look-alike versions.tf files told apart. Shows what behold does NOT infer as clearly as what it draws: platform declares the KMS key and prod reads it back by alias, and no edge is drawn between them, because both ends carry the same unresolved interpolation (#381). Needs chant's terraform lexicon beside behold, which behold does not install: npm install --no-save @intentius/chant-lexicon-terraform @cdktf/hcl2json (the refusal names the exact line). No cloud, no Docker, no terraform binary.",
+      "description": "A multi-root Terraform estate, declared only: two roots applied separately (envs/prod and platform) plus the shared module both are built on — 37 cards boxed by root, module calls expanded into their own contents, and the two look-alike versions.tf files told apart. Shows what behold does NOT infer as clearly as what it draws: platform declares the KMS key and prod reads it back by alias, and no edge is drawn between them, because both ends carry the same unresolved interpolation (#381). Needs chant's terraform lexicon beside behold, which behold does not install: npm install --no-save @intentius/chant-lexicon-terraform @cdktn/hcl2json (the refusal names the exact line). No cloud, no Docker, no terraform binary.",
       "source": "bundled",
       "dir": "example-terraform-estate",
       "requires": [],
@@ -109,7 +109,8 @@
           "AWS_ENDPOINT_URL": "http://127.0.0.1:4650",
           "AWS_ACCESS_KEY_ID": "test",
           "AWS_SECRET_ACCESS_KEY": "test",
-          "AWS_REGION": "us-east-1"
+          "AWS_REGION": "us-east-1",
+          "TOFU_LIVE_COLLECT_UNCLAIMED": "1"
         }
       }
     },