commit c27ad13561e7e6bc75559c0aec75a0fe8f59aeae
parent 06557f970e32aec1fe3ef32bcb25a055a0a77bb1
Author: James Eversole <james@eversole.co>
Date: Fri, 16 Oct 2026 14:30:12 -0500
Keep server inspection guide focused on usage and exact-tree semantics
Diffstat:
1 file changed, 24 insertions(+), 35 deletions(-)
diff --git a/docs/tri-tools.md b/docs/tri-tools.md
@@ -127,8 +127,8 @@ and inspecting it does not read `settings.txt`; running its IO tree would.
### Inspect the actual Arboricx server
[`demos/arboricx-inspection/main.tri`](../demos/arboricx-inspection/main.tri)
-reexports the application's exact `main` tree and adds a small inspection
-vocabulary. It does not modify the deployment module:
+reexports the application's exact `main` tree and adds named inspection views
+in a separate companion module:
```sh
result/bin/tricu arboricx compile --file demos/arboricx-inspection/main.tri \
@@ -155,45 +155,34 @@ main: tricuIO v1
finishStartup: continuation (not applied)
```
-These are export aliases, shown here instead of occurrence paths for readability.
-Four ordinary configured exports match without decomposing `main`: `storeRoot`,
-`createRootDirectory`, `ensureRootDirectory`, and `initializeStore`. General
-helpers such as `ensureStore`, `onOk_`, or `abortIO` do not identify their
-specialized uses in this outline. Even rebuilding an equivalent wrapper
-expression need not yield the same tree.
-
-The other labels deliberately export **structural projections of the actual
-materialized action**. The names are assigned by the demo author, not recovered
-source provenance. Projection extracts a continuation as data; it does not apply
-it. This is useful inspection vocabulary tied to the current action layout, not
-a general source debugger. The acceptance harness checks the expected roles and
-unchanged application identity.
-
-The separate `serveView` exposes a configured `serveRegistry` action, its
-`createSocket` action, and opaque `afterSocketResult` continuation. It does not
-reveal bind/listen/accept, which depend on the returned socket. Inspecting this
-view does not mean the inspector followed `main`'s continuation. `initializeView`
-similarly offers a shorter view of store initialization. Running these view
-exports with `--io`, unlike inspecting them, would perform effects.
-
-With the packaged stable compiler in the acceptance run, the main-only bundle
-was 271,426 bytes / 22,272 nodes; the named demo was 273,288 bytes / 22,341 nodes:
-1,862 additional bytes (about 0.69%). Aliased occurrences rose from 1/11 to 11/11;
-ordinary configured exports alone reached 5/11. These are measurements of this
-application/compiler, not format guarantees or a prediction of future control
-flow. All four displayed continuations remain opaque.
-
-Reproduce the comparison, including exact `main` identity, ordinary-export
-controls, separate views, and saved JSON/outlines, in a new directory:
+The outline uses export aliases in place of occurrence paths for readability.
+Four configured values match directly: `storeRoot`, `createRootDirectory`,
+`ensureRootDirectory`, and `initializeStore`. The remaining labels are
+**author-named structural projections** of the materialized action. Projection
+extracts existing subtrees as data; all four continuations remain opaque and
+unapplied. Aliases establish exact tree identity; their names convey the author's
+interpretation. Matching requires the specialized tree itself, rather than its
+general library helper or an observationally equivalent expression.
+
+The independently materialized `serveView` exposes `serveRegistry`, its
+`createSocket` action, and the opaque `afterSocketResult` continuation.
+Bind/listen/accept remain behind that continuation and depend on the returned
+socket. `initializeView` offers a shorter view of store initialization. Inspection
+reads these trees; running the view exports with `--io` performs their effects.
+
+Run the comparison in a new directory:
```sh
python3 test/arboricx_server_inspection.py result/bin/tricu \
--directory /tmp/server-inspection
```
-The harness compiles and imports artifacts for comparison but never executes
-application IO. Compile timings in its report include sequential cache reuse and
-are not cold-build performance comparisons.
+The harness checks exact `main` identity, compares ordinary exports with
+structural projections, and saves JSON reports and outlines for the separate
+views. It reports bundle bytes, stored nodes, alias coverage, and compilation
+timings for the selected compiler. Timings include sequential cache reuse.
+Validation consists of compilation, artifact import, and read-only inspection;
+application IO remains unexecuted.
### Identities, output, and limits
