Operation

This section is for operators running Synchronic Web infrastructure in real environments. It covers deployment, service roles, network API behavior, routine operations, and protocol specifications. Unless otherwise noted, examples target the sync-services/compose/general stack.

Deployment

This section describes how to bring up and manage the reference runtime stack used throughout the rest of this guide.

Docker Compose

The compose deployment is the baseline operating mode for local, staging, and many production-like environments. It provides a predictable process model so operators can troubleshoot behavior without guessing which component wiring changed.

Required/important environment variables:

SECRET (required): interface authentication secret
PORT (default 8192): published HTTP port
HTTPS_PORT (default 443): published HTTPS port
PERIOD (default 2): stepping cadence parameter passed to journal
WINDOW (default 1024): retention window for unpinned history
TLS_CERT_HOST_PATH (optional): host certificate file mounted into router
TLS_KEY_HOST_PATH (optional): host key file mounted into router
LOCAL_LISP_DIRECTORY (optional in test scripts): local override path for Lisp class files

Start:

SECRET=password ./tests/local-compose.sh up

Smoke validation:

./tests/local-compose.sh smoke

Direct HTTP deployment (no TLS):

SECRET=password PORT=80 \
docker compose -f compose/general/docker-compose.yml up -d

Optional TLS with the same compose file:

TLS_CERT_HOST_PATH=/absolute/path/to/fullchain.pem \
TLS_KEY_HOST_PATH=/absolute/path/to/privkey.pem \
SECRET=password PORT=80 \
HTTPS_PORT=443 \
docker compose -f compose/general/docker-compose.yml up -d

Stop (-v to delete volumes):

docker compose -f compose/general/docker-compose.yml down -v

The default stack includes:

journal runtime (general)
router/nginx entrypoint
gateway API service
explorer UI
workbench UI
file-system SMB service

Routing

The service split allows teams to scale or replace one layer at a time. For example, router behavior can be adjusted independently from journal runtime updates. The router service is the public nginx entry point for the deployment. It serves runtime query routes and UI routes:

Route	Purpose
`/interface`	Scheme request endpoint for direct evaluator and API calls.
`/interface/json`	JSON request endpoint for web and service integrations.
`/docs`	Gateway Swagger/OpenAPI documentation and route orientation.
`/api/v1/...`	Versioned gateway API endpoints proxied to gateway service.
`/explorer/`	Browser UI with dedicated `Ledger` and `Stage` modes for committed browsing and local staged editing.
`/workbench/`	Developer-oriented query workspace with API aids.
SMB share	File-system projection exposing `/stage`, `/ledger`, and `/control/pin`.

Router mode is selected at startup:

HTTP mode when TLS cert/key files are not found.
TLS mode when both cert/key files are present.

Network API

Implemented by sync-records/lisp/interface.scm on top of control.scm, standard.scm, and ledger.scm. Permission boundaries are central to safe operation, so operators should treat function families as security domains.

Function Families

Family	Description	Functions
Public (no authentication)	Read-mostly methods intended for external visibility without secrets.	`size`, `synchronize`, `info`, `config`, `get`, `trace`
Restricted (interface secret)	Stateful or sensitive operations that require interface authentication.	`resolve`, `set!`, `pin!`, `unpin!`, `bridge!`, `bridge-synchronize!`, `step!`, `secret`
Root/Admin control	Root control commands for runtime mutation and administrative lifecycle management.	`eval`, `call`, `step`, `set-secret`, `set-step`, `set-query`

Function Reference

Use this reference when building runbooks or on-call procedures. The same function names appear in Explorer/Workbench, automated scripts, and incident diagnostics.

Public Functions

Function	Purpose
`size`	Current permanent-chain size
`synchronize`	Serialize digest/proof data for bridge sync
`info`	Public node metadata (for example public key and window)
`config`	Full current config expression
`get`	Read staged state content
`trace`	Return serialized proof/path view rooted at an index

Restricted Functions

Function	Purpose
`resolve`	Resolve committed content, optionally with pin/proof detail
`set!`	Stage a write
`pin!`	Persist proof/data in permanent chain
`unpin!`	Remove persisted pin
`bridge!`	Register bridge with remote interface and optional prefetched info
`bridge-synchronize!`	Merge a prepared bridge synchronization response
`step!`	Run interface stepping, including bridge synchronization
`secret`	Rotate interface secret

Root/Admin Functions

Function	Purpose
`eval`	Evaluate arbitrary Scheme in admin context
`call`	Invoke function with root object
`step`	Execute full step cycle
`set-secret`	Rotate root/admin secret
`set-step`	Replace step handler
`set-query`	Replace query handler

Control Plane API

control.scm provides authentication of privileged operations, enforces root mutation/update discipline, and defines hook points for query and step behavior.

Root Object Methods

These are the public root methods exposed by the control module’s base record object.

Method	Signature	Description
`get`	`((root 'get) path)`	Read value at path; returns value, `(nothing)`, or directory metadata.
`set!`	`((root 'set!) path value)`	Write value at path; supports structured node/object values and deletion via `(nothing)`.
`copy!`	`((root 'copy!) source target)`	Copy value from `source` path to `target` path.
`equal?`	`((root 'equal?) source target)`	Exact structural equality check between two paths.
`equivalent?`	`((root 'equivalent?) source target)`	Digest-equivalence check between two paths.

Root Control Commands

These are public control commands handled by the transition function in control.scm.

Command	Signature	Description
`eval`	`(eval <admin-secret> <expression>)`	Evaluate expression in admin context.
`call`	`(call <admin-secret> <function>)`	Invoke function with `root` object and persist resulting state.
`step`	`(step <admin-secret>)`	Execute configured step handler pipeline.
`set-secret`	`(set-secret <old> <new>)`	Rotate admin secret used by control plane.
`set-step`	`(set-step <admin-secret> <step-function>)`	Replace step handler logic.
`set-query`	`(set-query <admin-secret> <query-function>)`	Replace query handler logic.

This API is intentionally powerful and low-level, so access should be tightly controlled and audited.

General API Bootstrap

interface.scm overlays the instantiated ledger object and dispatches ((function ...)) requests to ledger and bridge-helper methods, with permission checks on each call. It also handles remote bridge fetch/merge flows before handing the final operation to ledger.

General API Methods

Method	Permission	Description
`size`	Public	Return permanent chain size.
`synchronize`	Public	Return serialized sync proof at index.
`info`	Public	Return public node configuration.
`config`	Public	Return full inline ledger configuration.
`get`	Public	Read staged content.
`trace`	Public	Return serialized proof/path content rooted at an index.
`resolve`	Restricted	Return resolved path content, optionally with pin/proof detail.
`set!`	Restricted	Stage write to local state path.
`pin!`	Restricted	Persist selected path/proof in permanent chain.
`unpin!`	Restricted	Remove previously pinned path/proof.
`bridge!`	Restricted	Add bridge, fetching remote info when omitted.
`bridge-synchronize!`	Restricted	Synchronize a named bridge into local staged state.
`step!`	Restricted	Run bridge synchronization and local step progression.
`secret`	Restricted	Rotate interface secret used by interface API auth checks.

Root commands (*eval*, *call*, *step*, *set-secret*, *set-step*, *set-query*) are also callable, but remain part of the control-plane surface and should be treated as admin-level operations. This keeps externally visible behavior stable while allowing implementation details inside ledger classes to evolve.

Operations

This section provides common operational procedures. Each example includes both Lisp and JSON forms. These are direct calls that can be run manually, but they also serve as templates for operational automation.

Secret Rotation

Secret rotation is the minimum operational hygiene task for any deployed environment and should be part of regular runbooks.

((function *secret*)
 (arguments ((secret "new-password")))
 (authentication "old-password"))

{
  "function": "*secret*",
  "arguments": {
    "secret": {"*type/string*": "new-password"}
  },
  "authentication": {"*type/string*": "old-password"}
}

Rotate root/admin secret

Lisp
JSON

(*set-secret* "old-admin" "new-admin")

[
  "*set-secret*",
  {"*type/string*": "old-admin"},
  {"*type/string*": "new-admin"}
]

Updating Runtime Logic

Use root-level calls for controlled live updates. Typical update targets are: control hooks, standard, tree, chain, interface, and ledger. Because these changes alter live semantics, apply them in lower environments first and validate with smoke checks before promotion.

Update control hooks (`set-query`, `set-step`)

Lisp
JSON

(*set-query* "admin-password"
  (lambda (root query)
    (if (equal? query '(*ping*)) 'pong (error 'query-error "No handler"))))

[
  "*set-query*",
  {"*type/string*": "admin-password"},
  [
    "lambda",
    ["root", "query"],
    [
      "if",
      ["equal?", "query", {"*type/quoted*": ["*ping*"]}],
      {"*type/quoted*": "pong"},
      ["error", {"*type/quoted*": "query-error"}, {"*type/string*": "No handler"}]
    ]
  ]
]

For step hook updates, use the same pattern with *set-step*.

Update standard class

Lisp
JSON

(*call* "admin-password"
  (lambda (root)
    (define standard-cls '(define-class (standard) ...))
    ((root 'set!) '(control class standard) standard-cls)
    ((root 'set!) '(control object standard)
      (((eval (caddr standard-cls)) #f standard-cls)))))

[
  "*call*",
  {"*type/string*": "admin-password"},
  [
    "lambda",
    ["root"],
    [
      "begin",
      ["define", "standard-cls", {"*type/quoted*": ["define-class", ["standard"], "..."]}],
      [["root", {"*type/quoted*": "set!"}], {"*type/quoted*": ["control", "class", "standard"]}, "standard-cls"]
    ]
  ]
]

Inspect current config

Lisp
JSON

((function config)
 (authentication "password"))

{
  "function": "config",
  "authentication": {"*type/string*": "password"}
}

For in-place configuration mutation, use the interface *call*/*eval* control path or the ledger’s update-config! method from an authenticated admin flow.

Update tree/chain/ledger classes

Operational pattern:

Replace class definition under (control class <name>).
Rebuild affected object with standard.make.
Reinsert updated object under (control object ledger) or related path.
Validate with smoke tests.

Lisp
JSON

(*call* "admin-password"
  (lambda (root)
    (define ledger-cls '(define-class (ledger) ...))
    ((root 'set!) '(control class ledger) ledger-cls)
    ...))

[
  "*call*",
  {"*type/string*": "admin-password"},
  [
    "lambda",
    ["root"],
    ["begin", ["define", "ledger-cls", {"*type/quoted*": ["define-class", ["ledger"], "..."]}], "..."]
  ]
]