Usage

This section covers day-to-day interaction patterns for users who need to read, write, pin, and synchronize state. It focuses on the currently deployed general interface shape used by sync-services.

Graphical Interface

The general compose network exposes three primary web clients and one filesystem-oriented service: Explorer (/explorer/), Workbench (/workbench/), Gateway (/docs plus /api/v1/...), and File System (SMB). Together they cover the full operator/developer loop: inspect data, make changes, verify outcomes, mount journal state into ordinary file tools, and convert successful workflows into repeatable API calls.

Explorer

The Explorer is the state-navigation and content-management interface. It now has two explicit modes:

• Ledger
  • the default landing mode
  • route-based browsing of committed state across bridges and snapshots
• Stage
  • local editable staged state
  • file and directory oriented editing actions

Typical Explorer workflow:

1. Start in Ledger and synchronize to the latest committed root.
2. Use the route strip to browse from Self through bridges and historical snapshots.
3. Select a ledger file to switch between content and proof views or pin/unpin it.
4. Switch to Stage when you want to edit local staged files and directories.
5. Use stage actions to create documents/directories, upload files, edit content, and download files.

The Explorer is best for operational tasks and data exploration because it separates committed ledger inspection from local staged editing while keeping both in one UI.

Workbench

The Workbench is the API-oriented query environment. Use it when you want precise control over requests, fast iteration on payload shape, and direct inspection of results.

Typical Workbench workflow:

1. Start from a known request pattern (for example get, set!, pin!, or bridge!).
2. Run the request in Scheme or JSON form and inspect the returned value.
3. Iterate on arguments/authentication until behavior matches intent.
4. Use the final request as a template for automation or service integration.

The Workbench is best for debugging and integration development because it exposes the request/response layer directly.

Gateway

The Gateway is the web-facing API surface for journal operations. Use it when clients should call stable, versioned HTTP routes instead of direct function-shaped interface requests.

Typical Gateway workflow:

1. Start with GET /docs to review request and response schemas.
2. Use GET /api/v1/general/size or another stable route to validate connectivity.
3. Execute public general operations through GET routes (for example size, info, and trace).
4. Execute restricted general and optional control operations through authenticated POST routes.
5. Move validated requests into application clients or automation scripts using the same gateway contracts.

The Gateway is best for service integration because it standardizes journal calls into HTTP endpoints with explicit request validation.

File System

The File System service projects journal state into a mounted SMB share. Use it when existing tools should interact with Synchronic Web data through ordinary file and directory operations instead of direct API calls.

Typical File System workflow:

1. Mount the share and work in /stage for ordinary mutable file operations.
2. Browse /ledger/state for current committed content.
3. Traverse /ledger/previous/<index>/state for prior committed states.
4. Traverse /ledger/bridge/<name>/... for recursively bridged ledger state.
5. Use /control/pin for explicit pin and unpin directives on discovered ledger paths.

The File System service is best for shell tools, editors, archives, source trees, and other workflows that already expect a hierarchical filesystem.

Filesystem projection overview:

/
├── stage/
│   └── ...
├── ledger/
│   ├── state/
│   │   └── ...
│   ├── previous/
│   │   └── <index>/
│   │       ├── state/
│   │       ├── bridge/
│   │       └── previous/
│   └── bridge/
│       └── <name>/
│           ├── state/
│           ├── bridge/
│           └── previous/
└── control/
    └── pin

Key semantics:

• /stage is mutable.
• /ledger/... is readable but content-immutable.
• once you enter any state/ subtree, remaining path segments are ordinary file and directory names.
• /control/pin is a synthetic UTF-8 control file for pin and unpin directives against discovered /ledger/... paths.

Programmatic API

Programmatic access is typically where teams standardize integrations across multiple services. The sections below focus on stable request patterns that are easy to lint, test, and automate.

Endpoint Catalog

Use this catalog as a quick orientation map. The two execution endpoints (/interface, /interface/json) are for runtime calls, while the conversion endpoints are for debugging and payload authoring.

Endpoint	Description
POST /interface	Executes Scheme requests directly against the interface runtime.
POST /interface/json	Executes JSON requests using the object-shaped API envelope.
POST /interface/scheme-to-json	Converts Scheme expressions into JSON payload representations.
POST /interface/json-to-scheme	Converts JSON payloads back into Scheme forms for debugging and validation.

Request Envelope

Most JSON integrations can standardize on this envelope and only vary function and arguments. That keeps client implementations simple and makes troubleshooting easier across services.

Field	Type	Required	Notes
function	symbol/string	Yes	API function name
arguments	object / association list	Usually	Keyword-style fields for ledger calls
authentication	string / *type/string*	Restricted calls	Interface secret

Note:

In Scheme form, API queries are association lists. In JSON form, they are objects with equivalent fields.

Operation Examples

These examples are intentionally minimal and map directly to frequently used workflows. You can copy them into Workbench first, then move them into automation once validated.

Read (get)

Lisp

((function get)
 (arguments ((path ((*state* docs article hash)))
             (pinned? #t)
             (proof? #t)))
 (authentication "password"))

JSON

{
  "function": "get",
  "arguments": {
    "path": [["*state*", "docs", "article", "hash"]],
    "pinned?": true,
    "proof?": true
  },
  "authentication": {"*type/string*": "password"}
}

Info: When to use pinned? and proof?

Use pinned? when you want to know whether a historical path remains pinned, and use proof? when you need the proof payload itself.

Write (set!)

Lisp

((function set!)
 (arguments ((path ((*state* docs article hash)))
             (value "0xabc123")))
 (authentication "password"))

JSON

{
  "function": "set!",
  "arguments": {
    "path": [["*state*", "docs", "article", "hash"]],
    "value": {"*type/string*": "0xabc123"}
  },
  "authentication": {"*type/string*": "password"}
}

Pin (pin!)

Lisp

((function pin!)
 (arguments ((path (-1 (*state* docs article hash)))))
 (authentication "password"))

JSON

{
  "function": "pin!",
  "arguments": {"path": [-1, ["*state*", "docs", "article", "hash"]]},
  "authentication": {"*type/string*": "password"}
}

Bridge (bridge!)

Lisp

((function bridge!)
 (arguments ((name journal_b)
             (interface "http://journal-b.example.org/interface")))
 (authentication "password"))

JSON

{
  "function": "bridge!",
  "arguments": {
    "name": "journal_b",
    "interface": {"*type/string*": "http://journal-b.example.org/interface"}
  },
  "authentication": {"*type/string*": "password"}
}

JSON/Scheme Conversion

The converter treats JSON and Scheme as structurally equivalent where possible.

Core Mapping

This mapping is the key mental model for moving between web client payloads and Scheme-native request forms. Once this is clear, advanced payloads become much easier to reason about.

Scheme	JSON
symbol	string
list	array
association list ((k v) ...)	object { "k": v, ... }
object-shaped assoc list	object

Special Types

Special type wrappers are only needed where plain JSON cannot preserve Lisp/runtime semantics. If a payload seems unexpectedly interpreted, check whether a special type marker is required.

JSON marker	Scheme value
{"*type/string*": "text"}	string
{"*type/quoted*": ...}	(quote ...)
{"*type/byte-vector*": "deadbeef"}	byte-vector
{"*type/vector*": [...]}	vector
{"*type/pair*": [a, b]}	dotted pair (a . b)
{"*type/rational*": "1/3"}	rational
{"*type/complex*": "1+2i"}	complex

Practical Guidance

Use /interface/scheme-to-json to generate exact JSON for complex expressions, and use /interface/json-to-scheme when debugging client payloads or validating round-trip conversions. For web clients, prefer object-shaped API queries (function, arguments, authentication) because they remain easier to read and diff than raw array forms, and reserve array-shaped JSON for raw root command calls. Prefer *type/string* for literal strings in JSON payloads whenever you need to avoid ambiguity in type conversion.

A common workflow is: prototype in Scheme, convert to JSON, integrate in client code, then round-trip with json-to-scheme during debugging. Teams that include conversion checks in their release process generally catch payload-shape regressions earlier.