feat: release Sync Web 1.3.0 (#22)

Summary
- Release Sync Web 1.3.0.
- Add the document record abstraction and integrate document metadata through ledger/interface reads, writes, resolves, traces, slices, and prunes.
- Migrate public record paths to flat staged/indexed/bridge traversal forms across records, gateway clients, Explorer, tests, and examples.
- Replace the old file-system adapter with a gateway-backed WebDAV service, including navigable ledger index paths, WebDAV directory markers, `/control/pin`, and updated local/API smoke coverage.
- Move user document payloads to byte-vector-only storage, with explicit `expression? #t` boundary codecs for expression-oriented API calls.
- Align Explorer, WebDAV, gateway/workbench examples, locust, and social-agent workloads with byte-vector documents and metadata-aware access.
- Add gateway-local SSE change hints and Explorer stale-while-revalidate refreshes for live staged/admin/ledger views.
- Add the static router journal-node splash page and WebDAV guide, served by the router without a new service.
- Harden local/network operations: isolated Compose stack names, safer teardown docs, runtime-neutral Docker/Podman helpers, healthchecks, development check docs, and screenshot helper updates.
- Improve bridge workflows: negotiated bridge modes, journal peer identity defaults, JSON batch normalization/decoding, content-only directory discovery, accurate local `pinned?` semantics, and historical multi-hop bridge proof resolution.
- Stabilize Explorer/network behavior: preserve active staged edits during refresh, fix bridged pin/unpin display, show node loading feedback, default Explorer stage to user home, and write social-agent documents as plain UTF-8 byte-vectors.

Testing
- `git diff --check`
- `./records/tests/test.sh ./journal/target/release/journal-sdk`
- `cd services/explorer && npm test -- --watchAll=false`
- `cd tests/network/common/social-agent && python -m unittest discover -s tests`
- `cd services/gateway && npm test` (run earlier in branch)
- `cd services/file-system && go test ./...` (run earlier in branch)
- `cd tests/load/locust && python -m unittest discover -s tests` (run earlier in branch)
- Local 8-node Podman compose smoke: router health, splash/WebDAV guide, raw byte-vector social-agent documents, bridged pin/unpin sibling behavior, and historical multi-hop bridge resolve.

Notes/Risks
- Durable document payloads are now byte-vector-only. Use `expression? #t` for public API calls that intentionally encode/decode Scheme expressions.
- Public path syntax is now the flat path shape; older nested public path shapes are intentionally not preserved.
- `pinned?` now means local permanent proof can resolve the value: confirmed values, including `(nothing)`, are pinned; `(unknown)` is not pinned. The check does not perform remote bridge fetches.
- Chain `get` returns `(unknown)` for unavailable pruned proof paths instead of leaking low-level sync-node access errors, allowing bridge fallback fetch/merge to continue.
- WebDAV is a protocol endpoint; browser users should use the new router WebDAV guide instead of opening `/webdav/` directly.

Author: thiennamdinh

.github/workflows/journal.yml

@@ -97,13 +97,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install smbclient
-        run: sudo apt-get update && sudo apt-get install -y smbclient
       - name: Run compose smoke test
         run: |
           SECRET=password \
           PORT=8192 \
-          SMB_PORT=1445 \
           tests/api/local-compose.sh smoke
 
   tag-version:

AGENTS.md

@@ -0,0 +1,45 @@
+# Agent Guidance
+
+## Git
+
+- Do all work on separate branches, never push or otherwise edit `main` directly.
+- Do not push any branch unless explicitly asked.
+- All pull requests to `main` should consist of a single squashed commit with a detailed markdown message.
+
+## Versioning
+
+- The platform version in `/VERSION` and the journal-sdk crate version is in `journal/Cargo.toml`.
+  - Platform version should be updated for all pull requests
+  - Crate version should only be updated for pull requests that affect the journal-sdk
+- For both notions of version:
+  - Bump the relevant version for every pull request. Confirm the type first: patch, minor, or (rarely) major.
+  - When bumping version, update all deployment configurations to reference the latest version.
+  - When bumping minor or major versions, update the changelog if one already exists.
+
+## Documentation
+- Before final pull requests, ensure that documentation in `/docs` track the implementation
+- Before final pull requests, ensure that README.md and other repo-level documents track the implementation.
+- When adding or changing modules, classes, or functions, ensure that docstrings are correct and consistent.
+
+## Deployment
+
+- Preserve both deployment paths:
+  - `deploy/compose/general/compose.yaml` is the primary single-node deployment path.
+  - `tests/api/local-compose.sh` is the primary local smoke-test path.
+- Preserve both TLS and plaintext deployment paths
+  - HTTP-only deployment must keep working for internal networks.
+  - TLS deployment must keep working with host-provided certificate/key paths.
+- Preserve both Docker, Podman, and other standard container runtimes where possible.
+- Consider Windows, macOS, and Linux (Ubuntu and Fedora SELinux) compatibility posture where possible.
+
+## Testing
+
+- Before submitting pull requests, identify and run Github Actions locally where relevant and possible.
+  - Relevant actions are in .github/workflows/*.yml.
+
+## Development
+
+- When working with s7 scheme/lisp code, consult `/records/LANGUAGE.md`
+- In Scheme, avoid polluting local namespaces with low-value intermediate variables when collection references are short and explicit.
+- Prefer exact expected data shapes that fail quickly when malformed over networks of ad hoc fallbacks that become hard to reason about.
+- For high-blast-radius changes, roll out from lower layers to higher layers in separate commits/PR slices where practical: Rust/journal changes first, then Scheme record changes, then service/UI changes. Run/update relevant tests incrementally with each slice.

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.3.0
+
+### Added
+
+- **Document records** — Added byte-vector-only document payloads with metadata support and explicit `expression?` public I/O codec for expression-oriented callers.
+- **WebDAV file-system service** — Replaced the previous file-system adapter with a gateway-backed WebDAV service and navigable ledger index paths.
+- **Gateway events** — Added authenticated Server-Sent Events change hints and Explorer live refresh integration.
+- **Router splash page** — Added a static journal node home page and WebDAV guide served directly by the router.
+
+### Changed
+
+- **Record paths** — Public ledger/interface paths now use flat path syntax for staged, indexed, and bridge traversal paths.
+- **Document adapters** — Explorer, WebDAV, gateway examples, social-agent, and load workloads now write normal document content as byte-vectors unless explicitly using `expression?`.
+- **Pinned state** — `pinned?` now reports local permanent proof value availability; confirmed values including `(nothing)` are pinned, while `(unknown)` is not.
+- **Compose defaults** — All service image tags default to `1.3.0`.
+
+### Fixed
+
+- **Bridge resolution** — Historical multi-hop bridge paths now return semantic values/unknowns instead of low-level sync-node access errors.
+- **Explorer stability** — Preserved active staged edits during background refreshes and fixed bridged file pin/unpin display.
+- **Batch JSON** — Normalized JSON batch subqueries and decoded batch results consistently.
+- **Directory discovery** — Explorer directory discovery uses content-only reads to avoid unnecessary proof/pin coupling.
+
 ## 1.2.0
 
 ### Added

README.md

@@ -11,7 +11,7 @@ Full documentation: [sandialabs.github.io/sync-web](https://sandialabs.github.io
 | `journal/` | Rust journal-sdk: HTTP server, S7 Scheme evaluator, RocksDB persistence |
 | `records/` | Scheme record logic: `root`, `standard`, `tree`, `chain`, `ledger`, `interface` |
 | `services/` | Web services: `gateway`, `router`, `explorer`, `workbench`, `file-system` |
-| `deploy/` | Single-node Docker Compose deployment |
+| `deploy/` | Single-node Compose-compatible container deployment |
 | `tests/` | API smoke tests, load tests, multi-node network tests |
 | `docs/` | Documentation site (Astro/Starlight) |
 
@@ -20,11 +20,12 @@ Full documentation: [sandialabs.github.io/sync-web](https://sandialabs.github.io
 The fastest way to run a local stack:
 
 ```sh
-cd deploy/compose/general
-SECRET=yourpassword docker compose up
+COMPOSE_PROJECT_NAME=sync-local SECRET=yourpassword \
+HTTP_PORT=8192 HTTPS_PORT=8193 \
+docker compose -f deploy/compose/general/compose.yaml up
 ```
 
-See `deploy/compose/general/README.md` for full configuration options.
+Use `podman-compose` or `podman compose` instead of `docker compose` if that is your container runtime. See `deploy/compose/general/README.md` for full configuration options and `docs/development-checks.md` for validation commands and tool dependencies.
 
 ## License
 

VERSION

@@ -1 +1 @@
-1.2.2
+1.3.0

deploy/compose/general/README.md

@@ -1,31 +1,62 @@
 # Synchronic Web Ledger Compose Network
 
-This compose stack runs one journal with gateway, explorer, workbench, router, and the `file-system` SMB service.
+This compose stack runs one journal with gateway, explorer, workbench, router, identity-provider, and the WebDAV `file-system` service.
 
-The journal service uses the generic `journal-sdk` image directly. The general
-interface is assembled at startup from mounted deployment inputs:
+The journal service uses the generic `journal-sdk` image directly. The general interface is assembled at startup from mounted deployment inputs:
 
 - `records/lisp/*.scm`
 - `deploy/compose/general/run.sh`
 - the persistent `database` volume
 
-For a fresh database, `run.sh` installs the general interface from the mounted Lisp
-files. For an existing database, mounted Lisp files are only applied when
-`JOURNAL_UPDATE=1`; otherwise the durable journal state continues from the database.
+For a fresh database, `run.sh` installs the general interface from the mounted Lisp files. For an existing database, mounted Lisp files are only applied when `JOURNAL_UPDATE=1`; otherwise the durable journal state continues from the database.
 
 ## Requirements
 
-- Docker
-- Docker Compose
-- Podman Compose on Fedora is also supported. The bind mounts use SELinux
-  relabel flags so rootless Podman can read the mounted startup script and Lisp
-  files.
+- A Compose-compatible container runtime: Docker Compose, Podman Compose, or `podman-compose`
+- `curl` for the local smoke helper
+
+The bind mounts use SELinux relabel flags (`:Z`) so rootless Podman can read the mounted startup script and Lisp files.
+
+## Stack identity and ports
+
+Use `COMPOSE_PROJECT_NAME` to isolate local, public, and experimental stacks. Container and network names are prefixed from this value, for example `sync-dev-journal` and `sync-prod-gateway`.
+
+Default local ports are adjacent and non-privileged:
+
+- `HTTP_PORT` default `8192`
+- `HTTPS_PORT` default `8193`
+
+Example local stack:
+
+```bash
+COMPOSE_PROJECT_NAME=sync-dev SECRET=password \
+HTTP_PORT=8192 HTTPS_PORT=8193 \
+docker compose -f deploy/compose/general/compose.yaml up -d
+```
+
+Example public stack using standard ports:
+
+```bash
+COMPOSE_PROJECT_NAME=sync-prod SECRET=password \
+ORIGIN=https://example.com HTTP_PORT=80 HTTPS_PORT=443 \
+docker compose -f deploy/compose/general/compose.yaml up -d
+```
+
+With Podman Compose:
+
+```bash
+COMPOSE_PROJECT_NAME=sync-dev SECRET=password \
+HTTP_PORT=8192 HTTPS_PORT=8193 \
+podman-compose -f deploy/compose/general/compose.yaml up -d
+```
 
 ## Configuration
 
+- `COMPOSE_PROJECT_NAME` (recommended): stack/project identity used for generated volumes and parameterized container/network names
 - `SECRET` (required): authentication secret for restricted journal/gateway operations
-- `PORT` (default `8192`): host HTTP port exposed by router
-- `HTTPS_PORT` (default `443`): host TLS port exposed by router
+- `HTTP_PORT` (default `8192`): host HTTP port exposed by router
+- `HTTPS_PORT` (default `8193`): host TLS port exposed by router
+- `ORIGIN` (default `http://localhost:8192`): public origin used by the identity provider; set this explicitly when using non-default/public ports or hostnames
 - `PERIOD` (default `2`): journal periodicity exponent
 - `WINDOW` (default `1024`): retained historical state window
 - `JOURNAL_UPDATE` (default empty): set to `1` to update an existing journal database from the mounted Lisp files before serving
@@ -34,79 +65,59 @@ files. For an existing database, mounted Lisp files are only applied when
 - `ACME_WEBROOT_HOST_PATH` (default `./acme-challenge`): host directory mounted at `/var/www/acme-challenge` for HTTP-01 challenge files
 - `TLS_CERT_FILE` (default `/etc/nginx/certs/tls.crt`): in-container certificate path used by router
 - `TLS_KEY_FILE` (default `/etc/nginx/certs/tls.key`): in-container key path used by router
-- `SMB_PORT` (default `445`): host port exposed by the `file-system` service
-- `FILE_SYSTEM_IMAGE` (default `ghcr.io/sandialabs/sync-web/file-system:1.2.2`): image used by the optional `file-system` service
-- `SYNC_FS_Backend` (default `http-journal-stage`): file-system backend override
-- `SYNC_FS_JournalJsonUrl` (default `http://journal/interface`): direct journal JSON endpoint used by the default file-system backend
-- `SYNC_FS_GatewayBaseUrl` (default `http://gateway/api/v1`): gateway endpoint used only when gateway-backed file-system modes are selected
+- `FILE_SYSTEM_IMAGE` (default `ghcr.io/sandialabs/sync-web/file-system:1.3.0`): image used by the `file-system` service
+- `SYNC_FS_MAX_OBJECT_BYTES` (default `1048576`): maximum WebDAV object size
 
 Gateway note:
+
 - `ALLOW_ADMIN_ROUTES` is enabled by default in `deploy/compose/general/compose.yaml`.
 - Gateway landing page is exposed through the router at `/gateway`.
 - Public/client-facing API traffic should go to `gateway` under `/api/v1/general/*` and `/api/v1/root/*`.
+- WebDAV traffic is exposed through the router under `/webdav/`.
 - The raw `/interface` endpoint is still present for direct journal transport use and bridge-oriented internals.
 - The journal's periodic scheduler uses the raw root-step call `(*step* "<secret>")`, which depends on the merged `records/` root-step pipeline.
 
-## TLS Behavior
+## TLS behavior
 
 This stack uses one compose file. Router auto-selects mode at startup:
 
 - HTTP mode: if TLS cert/key files are not present
 - TLS mode: if both `TLS_CERT_FILE` and `TLS_KEY_FILE` exist
 
-`tests/api/local-compose.sh` forces HTTP mode by default (`LOCAL_COMPOSE_FORCE_HTTP=1`) for predictable local smoke runs.
-Set `LOCAL_COMPOSE_FORCE_HTTP=0` if you explicitly want TLS behavior during local-compose execution.
+`tests/api/local-compose.sh` forces HTTP mode by default (`LOCAL_COMPOSE_FORCE_HTTP=1`) for predictable local smoke runs. Set `LOCAL_COMPOSE_FORCE_HTTP=0` if you explicitly want TLS behavior during local-compose execution.
 
 In TLS mode, router serves:
-- `80` for ACME HTTP-01 challenge path and HTTPS redirects
-- `443` for proxied application routes
 
-This is certificate-provider agnostic. Only file paths are required.
+- container port `80` for ACME HTTP-01 challenge path and HTTPS redirects
+- container port `443` for proxied application routes
 
-HTTP-only deployment (no TLS files configured):
+The host ports are controlled by `HTTP_PORT` and `HTTPS_PORT`.
 
-```bash
-SECRET=password PORT=8192 \
-docker compose -f deploy/compose/general/compose.yaml up -d
-```
+The default compose stack mounts ACME webroot to `/var/www/acme-challenge`. Use `ACME_WEBROOT_HOST_PATH` to override where challenge files come from on the host.
 
-With Podman Compose:
-
-```bash
-SECRET=password PORT=8192 \
-podman-compose -f deploy/compose/general/compose.yaml up -d
-```
-
-The default compose stack now mounts ACME webroot to `/var/www/acme-challenge`.
-Use `ACME_WEBROOT_HOST_PATH` to override where challenge files come from on the host.
-
-Example:
+Example TLS-backed public stack:
 
 ```bash
+COMPOSE_PROJECT_NAME=sync-prod \
 TLS_CERT_HOST_PATH=/absolute/path/to/fullchain.pem \
 TLS_KEY_HOST_PATH=/absolute/path/to/privkey.pem \
-SECRET=password PORT=8192 \
-HTTPS_PORT=443 \
+SECRET=password ORIGIN=https://example.com HTTP_PORT=80 HTTPS_PORT=443 \
 docker compose -f deploy/compose/general/compose.yaml up -d
 ```
 
-## Local Runner
+## Local runner
 
 Use the local helper from repository root:
 
 ```bash
 # Interactive run
-tests/api/local-compose.sh up
+COMPOSE_PROJECT_NAME=sync-local tests/api/local-compose.sh up
 
 # Smoke test
-tests/api/local-compose.sh smoke
+COMPOSE_PROJECT_NAME=sync-local tests/api/local-compose.sh smoke
 ```
 
-The local compose helper enables the SMB file-system service by default.
-
-The helper builds a local `journal-sdk` image and uses the same mounted Lisp/runtime
-script layout as the reference compose stack. It no longer builds a separate
-`general` image.
+The local compose helper defaults to `COMPOSE_PROJECT_NAME=sync-local`, `HTTP_PORT=8192`, and `HTTPS_PORT=8193`. It builds local service images, enables the WebDAV file-system service by default, and uses the same mounted Lisp/runtime script layout as the reference compose stack.
 
 To override the file-system image during local development:
 
@@ -115,8 +126,18 @@ FILE_SYSTEM_IMAGE=sync-web/local-file-system:1.0.0 tests/api/local-compose.sh up
 FILE_SYSTEM_IMAGE=sync-web/local-file-system:1.0.0 tests/api/local-compose.sh smoke
 ```
 
-## Manual Teardown
+## Teardown
+
+Stop a stack without deleting data:
 
 ```bash
-docker compose -f deploy/compose/general/compose.yaml down -v
+COMPOSE_PROJECT_NAME=sync-dev docker compose -f deploy/compose/general/compose.yaml down
 ```
+
+Delete stack volumes only when you intentionally want to remove the journal database and identity-provider state:
+
+```bash
+COMPOSE_PROJECT_NAME=sync-dev docker compose -f deploy/compose/general/compose.yaml down -v
+```
+
+Do not run `down -v` against a public/prod `COMPOSE_PROJECT_NAME` unless you intend to destroy that stack's persisted data.