Rename root-facing downstream services and files (#29)

Update compose/general to load root.scm and pin the merged sync-records root rename.

Rename gateway admin routes and configuration from /api/v1/control/* and CONTROL_* to /api/v1/root/* and ROOT_*.

Rename the file-system operational namespace from /control/pin to /root/pin, including the SMB projection, tests, and smoke script.

Refresh downstream docs and workbench examples so the root terminology matches the merged sync-records runtime layout.

Author: thiennamdinh

README.md

@@ -6,7 +6,7 @@ Monorepo for the Synchronic journal compose stack plus two web UIs:
 - `workbench` for developer-oriented journal queries
 - `gateway` for versioned web-native API routes and Swagger docs over journal interfaces
 - `router` for edge routing and optional TLS termination
-- `file-system` for SMB projection of `/stage`, `/ledger`, and `/control`
+- `file-system` for SMB projection of `/stage`, `/ledger`, and `/root`
 
 ## Quick Start
 

compose/general/Dockerfile

@@ -1,6 +1,6 @@
 FROM ghcr.io/sandialabs/sync-journal/journal-sdk:1.2.0
 
-ARG LISP_REPOSITORY=https://raw.githubusercontent.com/sandialabs/sync-records/dfc252b60778946e20105f01af551d8c43b60b3e/lisp/
+ARG LISP_REPOSITORY=https://raw.githubusercontent.com/sandialabs/sync-records/e40403783592c09ffa31a7af63d2838b72bfcc31/lisp/
 ARG CUSTOM_SETUP=""
 
 RUN set -eu; \
@@ -11,7 +11,7 @@ RUN set -eu; \
       rm -f /tmp/custom-setup.sh; \
     fi
 
-RUN wget "${LISP_REPOSITORY}/control.scm"
+RUN wget "${LISP_REPOSITORY}/root.scm"
 RUN wget "${LISP_REPOSITORY}/standard.scm"
 RUN wget "${LISP_REPOSITORY}/log-chain.scm"
 RUN wget "${LISP_REPOSITORY}/linear-chain.scm"

compose/general/README.md

@@ -27,9 +27,9 @@ This compose stack runs one journal with gateway, explorer, workbench, router, a
 
 Gateway note:
 - `ALLOW_ADMIN_ROUTES` is enabled by default in `compose/general/docker-compose.yml`.
-- Public/client-facing API traffic should go to `gateway` under `/api/v1/general/*` and `/api/v1/control/*`.
+- Public/client-facing API traffic should go to `gateway` under `/api/v1/general/*` and `/api/v1/root/*`.
 - The raw `/interface` endpoint is still present for direct journal transport use and bridge-oriented internals.
-- The journal's periodic scheduler uses the raw control-step call `(*step* "<secret>")`, which depends on the merged `sync-records` control-step pipeline.
+- The journal's periodic scheduler uses the raw root-step call `(*step* "<secret>")`, which depends on the merged `sync-records` root-step pipeline.
 
 ## TLS Behavior
 
@@ -104,7 +104,7 @@ LOCAL_LISP_DIRECTORY=/absolute/path/to/lisp ./tests/local-compose.sh smoke
 ```
 
 `LOCAL_LISP_DIRECTORY` must contain:
-- `control.scm`
+- `root.scm`
 - `standard.scm`
 - `log-chain.scm`
 - `linear-chain.scm`

compose/general/docker-compose.yml

@@ -4,7 +4,7 @@ networks:
 
 services:
   journal:
-    image: ghcr.io/sandialabs/sync-services/general:1.2.2
+    image: ghcr.io/sandialabs/sync-services/general:1.2.3
     container_name: journal
     networks:
       - docker
@@ -34,7 +34,7 @@ services:
       SYNC_WORKBENCH_ENDPOINT: /interface
 
   gateway:
-    image: ghcr.io/sandialabs/sync-services/gateway:1.1.1
+    image: ghcr.io/sandialabs/sync-services/gateway:1.1.2
     container_name: gateway
     networks:
       - docker
@@ -45,8 +45,8 @@ services:
       PORT: 80
       JOURNAL_JSON_ENDPOINT: http://journal/interface/json
       JOURNAL_SCHEME_ENDPOINT: http://journal/interface
-      CONTROL_JSON_ENDPOINT: http://journal/interface/json
-      CONTROL_SCHEME_ENDPOINT: http://journal/interface
+      ROOT_JSON_ENDPOINT: http://journal/interface/json
+      ROOT_SCHEME_ENDPOINT: http://journal/interface
       REQUEST_TIMEOUT_MS: ${REQUEST_TIMEOUT_MS:-30000}
       ALLOW_ADMIN_ROUTES: "1"
 
@@ -72,7 +72,7 @@ services:
       - "${HTTPS_PORT:-443}:443"
 
   file-system:
-    image: ${FILE_SYSTEM_IMAGE:-ghcr.io/sandialabs/sync-services/file-system:1.1.1}
+    image: ${FILE_SYSTEM_IMAGE:-ghcr.io/sandialabs/sync-services/file-system:1.1.2}
     container_name: file-system
     depends_on:
       - journal

compose/general/run.sh

@@ -35,13 +35,13 @@ resolve_lisp_file() {
 
 run_startup() {
     clear_flag="$1"
-    control=$( cat "$(resolve_lisp_file control.scm)" )
+    root=$( cat "$(resolve_lisp_file root.scm)" )
     standard=$( cat "$(resolve_lisp_file standard.scm)" )
     chain=$( cat "$(resolve_lisp_file log-chain.scm)" )
     tree=$( cat "$(resolve_lisp_file tree.scm)" )
     ledger=$( cat "$(resolve_lisp_file ledger.scm)" )
     interface=$( cat "$(resolve_lisp_file interface.scm)" )
-    expr="($interface $clear_flag \"$SECRET\" \"$SECRET\" $WINDOW $control '$standard '$chain '$tree '$ledger)"
+    expr="($interface $clear_flag \"$SECRET\" \"$SECRET\" $WINDOW $root '$standard '$chain '$tree '$ledger)"
     if [ "$clear_flag" = "#f" ]; then
         expr="(*eval* \"$SECRET\" $expr)"
     fi

compose/general/version.txt

@@ -1 +1 @@
-1.2.2
+1.2.3

services/explorer/change.md

@@ -30,8 +30,8 @@ The explorer UI should be organized around:
 - `stage`
 - `ledger`
 
-There should be no explorer-side `control` namespace.
-In the file-system service, `control` exists as a workaround for non-filesystem operations.
+There should be no explorer-side `root` namespace.
+In the file-system service, `root` exists as a workaround for non-filesystem operations.
 In the explorer, those behaviors already belong in explicit UI actions such as pin/unpin, so they should not be represented as a browsable tree.
 
 This stage/ledger split should become the primary browsing model in the UI.
@@ -143,7 +143,7 @@ This should follow the same semantics already used by the file-system layer in:
 - `services/file-system/src/FileSystem.Server/JournalPathMapper.cs`
 
 The explorer should not literally call the file-system service, but it should mimic its namespace and path semantics.
-It should also intentionally omit the file-system service's `control` namespace.
+It should also intentionally omit the file-system service's `root` namespace.
 
 ### 5. Internal Representation Boundary
 

services/file-system/README.md

@@ -46,11 +46,11 @@ The loader now supports journal-style entries for:
 The projected namespace now exposes three top-level areas:
 - `/stage`
 - `/ledger`
-- `/control`
+- `/root`
 
-The current control-plane feature is:
-- `/control/pin`
-  - a single synthetic UTF-8 text control file
+The current root-plane feature is:
+- `/root/pin`
+  - a single synthetic UTF-8 text root file
   - reads are discovery-based and render lines like `pinned /ledger/...` or `unpinned /ledger/...`
   - writes accept explicit directives in the same form
   - only `/ledger/...` paths are valid in this file
@@ -79,7 +79,7 @@ The fixture model now also supports symlink entries:
 
 Directory metadata lives behind the scenes on hidden `*directory*` marker entries in the backing model. That marker is not exposed to filesystem users as a projected `.directory` file.
 Projected writes are currently allowed only under `/stage`; `/ledger/...` is treated as read-only in the local mock model.
-Pin/unpin is the current exception: it is exposed through `/control/pin`, not through file metadata or sidecars in the content tree.
+Pin/unpin is the current exception: it is exposed through `/root/pin`, not through file metadata or sidecars in the content tree.
 The current `json` backend now runs through a mock gateway abstraction shaped like `POST /api/v1/general/get` and `POST /api/v1/general/set`, so the SMB projection path already matches the real gateway contract more closely.
 
 Try connecting with `smbclient` after the container starts:
@@ -111,7 +111,7 @@ Targeted local SMB integration checks:
 ./tests/smbclient-smoke.sh
 ./tests/json-projection-smoke.sh
 ./tests/symlink-smoke.sh
-./tests/pin-control-smoke.sh
+./tests/pin-root-smoke.sh
 ./tests/symlink-smoke.sh
 ```
 

services/file-system/ai-spec.md

@@ -7,7 +7,7 @@ Expose journal-backed records as a network-mounted filesystem using a native SMB
 
 ### Authority and persistence
 - Journal is authoritative.
-- SMB service is a projection/control layer.
+- SMB service is a projection/root layer.
 - No local durable mirror of journal content.
 
 ### Access path
@@ -18,7 +18,7 @@ Expose journal-backed records as a network-mounted filesystem using a native SMB
 - Root exposes exactly three top-level namespaces:
   - `/stage`: local mutable working tree
   - `/ledger`: immutable recursive committed-ledger view
-  - `/control`: explicit non-content operational surface
+  - `/root`: explicit non-content operational surface
 - Any ledger peer view exposes exactly three structural children:
   - `/state`: committed document tree for that ledger peer view
   - `/peer/<name>`: related ledger peer
@@ -31,8 +31,8 @@ Expose journal-backed records as a network-mounted filesystem using a native SMB
   - Everything under `/ledger` is immutable for content mutation.
   - Immutable ledger paths may still expose first-class journal properties such as pin state where supported.
   - Pin/unpin is in-scope for MVP as a first-class filesystem capability, but it must map directly to journal pin state rather than any synthetic metadata sidecar.
-- Control namespace:
-- `/control/pin` is a synthetic control file for pin/unpin.
+- Root namespace:
+- `/root/pin` is a synthetic root file for pin/unpin.
 - `/stage` is never pinnable through the filesystem surface.
 
 ### Empty directory convention
@@ -66,7 +66,7 @@ Expose journal-backed records as a network-mounted filesystem using a native SMB
 - `*file-system/file*` should only be introduced when non-default file metadata must be persisted.
 
 ### Content-kind derivation
-- `content-kind` is not stored as separate filesystem control metadata.
+- `content-kind` is not stored as separate filesystem root metadata.
 - It is derived from the actual journal content representation:
   - byte-vector payload => `bytes`
   - any non-byte typed value => `expression`
@@ -149,13 +149,13 @@ Expose journal-backed records as a network-mounted filesystem using a native SMB
 - Delete => `set!(..., ["nothing"])`.
 - `mkdir` => create `*directory*` marker value.
 - Pin/unpin, where exposed, must map directly to first-class journal pin/unpin behavior.
-- `/control/pin` writes map to gateway `pin` / `unpin`, not `set!`.
+- `/root/pin` writes map to gateway `pin` / `unpin`, not `set!`.
 
 ### Read-only rules
 - Content mutation outside `/stage` => `EROFS`.
 - First-class journal properties such as pin state are not mutated through any directory sidecar.
 - Pin/unpin may still be supported on immutable ledger paths because it is not a content mutation.
-- `/control/pin` is writable only as a whole-file control surface for replacing the desired pinned set.
+- `/root/pin` is writable only as a whole-file root surface for replacing the desired pinned set.
 
 ### Write buffering
 - Per-handle in-memory buffer for `/stage` writes.
@@ -210,32 +210,32 @@ Write rules:
 ## 6) Pin Control Namespace
 
 ### Namespace shape
-- `/control/pin` is a single synthetic UTF-8 text file.
+- `/root/pin` is a single synthetic UTF-8 text file.
 - It is the only user-facing pin/unpin surface in the filesystem.
 - The pin namespace must never mirror `/stage/...`.
 
 ### Read behavior
-- Reading `/control/pin` returns newline-delimited pin-state records for ledger paths the filesystem has already discovered by reading those ledger entries.
+- Reading `/root/pin` returns newline-delimited pin-state records for ledger paths the filesystem has already discovered by reading those ledger entries.
 - Each line is one canonical projected ledger path prefixed by either `pinned` or `unpinned`.
 - The file is discovery-based rather than globally complete:
   - reading ledger files and directories may add entries to the current rendered view
-  - directory listing alone does not need to enumerate the full ledger into `/control/pin`
+  - directory listing alone does not need to enumerate the full ledger into `/root/pin`
 - Blank lines are allowed but ignored on parse.
 - The rendered file should be canonicalized:
   - normalized projected `/ledger/...` paths only
   - sorted deterministically
   - duplicates removed
 
 ### Write behavior
-- Writing `/control/pin` applies explicit pin-state directives rather than replacing a globally complete set.
+- Writing `/root/pin` applies explicit pin-state directives rather than replacing a globally complete set.
 - The file content is parsed as UTF-8 newline-delimited directives:
   - `pinned /ledger/...`
   - `unpinned /ledger/...`
 - Only canonical `/ledger/...` paths are allowed.
 - `/stage/...` paths are invalid in this file.
 - Invalid lines reject the whole write with `EINVAL`.
 - Repeated directives for the same path are resolved by last-line-wins within that write.
-- Rename and sidecar control files are not part of the pin UX.
+- Rename and sidecar root files are not part of the pin UX.
 
 ### Journal mapping
 - Each listed projected `/ledger/...` path decompiles to the corresponding canonical ledger journal path.
@@ -266,8 +266,8 @@ Write rules:
 - invalid path/envelope/value => `EINVAL`
 - invalid hidden directory-marker data => `EINVAL`
 - read-only content mutation => `EROFS`
-- unsupported/disallowed control metadata op => `EOPNOTSUPP`
-- unsupported operation inside `/control/pin/...` (for example rename or file-content write) => `EOPNOTSUPP`
+- unsupported/disallowed root metadata op => `EOPNOTSUPP`
+- unsupported operation inside `/root/pin/...` (for example rename or file-content write) => `EOPNOTSUPP`
 - upstream timeout/transport failure => `EIO`
 
 ## 9) Deployment and Runtime
@@ -356,7 +356,7 @@ No secrets or full payload content by default.
 
 ### Interop expectations
 - `/ledger/...` content remains read-only.
-- Directory metadata is stored behind the scenes on hidden `*directory*` marker entries rather than projected control files.
+- Directory metadata is stored behind the scenes on hidden `*directory*` marker entries rather than projected root files.
 - Case sensitivity rules must avoid ambiguous collisions.
 - Hidden directory markers do not mirror first-class journal properties like pin state or derived content classification.
 - Hidden directory markers do not mirror metadata about child entries.