Module sync 

Sharing the seat’s memory across machines through the tracker repository that already travels between them.

Each tracker repository names one or more scopes in .ljos/sync.toml. The primary scope keeps the legacy keys (name, recipients), and optional [scopes] entries add named scopes with their own recipients. Every machine writes only its own log for each configured scope under .ljos/atoms/, so two machines never touch one file and git never has to merge a log. A log carries the machine’s live atoms of that scope without their vectors; the receiving pack encodes them again. An atom’s scope is its scope:NAME entity. An atom with none stays on the primary scope. A machine default_scope that names an extra scope is refused, so an unscoped box atom is never sealed into that shared log.

Import posts every atom of every other machine’s log to this seat’s pack, which answers a text it already holds with the claim it has, so an import twice is an import once. Retirement travels by difference: the texts an import took from a host are remembered, and a text that host no longer sends retires the local copy that came from it, never a claim this machine wrote itself. Every log is retired before any log is posted. A text that moved scopes would otherwise be answered with the old claim, and the old scope’s retirement would delete that answer.

--adopt HOST posts that host’s live atoms as this machine’s own, with origin peer and each log’s scope, then deletes every log of that host. The deletion is one commit, made only after every post and forget has landed. Its subject chore(sync): adopt HOST SCOPE atoms names the primary scope; a host+scope file in that commit is an extra scope. Another machine’s import reads the subject and retires that host’s copies in each scope whose log the commit removed.

Structs

Incoming

What one host’s log asks of this pack: the atoms to post, and the memories it sent last time and sends no longer.

Scope

The scope a tracker repository shares: .ljos/sync.toml.

Constants

CLOUD_SCOPE

The shared scope a box and its VMs use. It is an extra scope under [scopes]. A primary named this would send unscoped atoms and every finish lesson into the shared log.

SYNC_HOST_KEY

Set by ljos cloud up to the seat, in the process and in ~/.config/ljos/env. Every cloud VM has the same host name, so logs named by it would overwrite each other, and each VM would skip the others’ logs as its own.

WRITE_SCOPE_KEY

Set by ljos cloud up in ~/.config/ljos/env. Writers tag memory and lessons scope:<value> explicitly. This is not default_scope: an unscoped atom still stays on the primary scope.

Functions

adopt

Fold one gone host’s atoms into this host’s logs and drop that host’s log files from each configured tracker repository.

adopt_legacy

Read target’s logs from before the scope header as target’s, in each configured tracker repository.

atom_scope

The scope an atom belongs to: its scope:NAME entity, else default.

cloud_identity_path

The age identity for scope cloud, written by ljos cloud up from a named secret. It is not identity_path: that key is this machine’s own. Scope cloud is sealed to one shared recipient, and the private key is not in the tracker, so a VM cannot read the scope without this file.

exchange_user_rules

Share user rules through a tracker checkout. Nothing leaves this machine unless the tracker’s .ljos/sync.toml names a scope: then the tracker is fetched, every host’s rules are merged with the local file by id, and this machine’s rules are sealed with age to the scope’s recipients, committed as .ljos/user-rules/<host>.json.age and pushed. A plaintext <host>.json this machine wrote before is removed in the same commit. Plaintext files from other hosts are still read. With no scope, or LJOS_TRACKER_GIT=off in passing, the rules already in the checkout are read and the tracker is not touched. LJOS_TRACKER_GIT=commit commits and pushes nothing. asked is ljos prefer --user --sync, which pushes whatever LJOS_TRACKER_GIT says. budget bounds every git call. A fetch that does not return leaves the local file as it was.

export

Write this machine’s log for the repository’s scope when its atoms changed since the last write. Returns the line that says what happened. A missing age skips the seal and is not an error.

host

This machine’s short host name, as [machine_name] folds it. Export, adopt and every log path use this one name, so the log an export writes is the one an adopt commit stages.

identity_path

This machine’s age identity, made on first use.

import

Import every other machine’s log of the repository’s scope into this seat’s pack. Returns one line per host and scope.

incoming

Read one host’s log against the memories taken from it last time (before, for what it retired) and the memories from it this pack already holds (held, which are not posted again). Both are [memory_key]s, so the same words on another ticket are not held.

is_own

Whether this machine holds an atom as its own rather than as an import.

log_plaintext

The plaintext of this machine’s log for a scope: its own live atoms of that scope, sorted by id, one JSON object a line.

machine_write_scope

The scope this machine’s memory and lessons are tagged with.

public_key

The public key of this machine’s identity, making the identity first when there is none. This is what goes into a scope’s recipients.

scope_for_issue

The scope of the repository that holds an issue, when it declares one.

scope_for_lesson

Scope tag for a finish lesson. A VM tags cloud explicitly so the lesson does not follow the repository’s primary scope into the box log.

scope_of_repo

The scope a tracker repository declares, when it declares one.

sender_entity

The entity an imported atom carries: which machine sent it.

sync_repo

One pass over the tracker repository’s scope: pull, take every other machine’s log, write and push this machine’s. pull_import and export pick the halves; the sitting takes the first, finish the second.

sync_repo_in_passing

sync_repo as the sitting and finish run it: a repository with no scope file is skipped without a word. Sync is opt-in, and a hint on every sitting pointed agents at a remote the person had not asked for. ljos sync by hand still names the missing file.

travelling

An atom as it travels: without its vector, and without a sender tag of another machine, since a host sends only what it holds as its own.

user_rule_trackers

Tracker checkouts that carry user rules. A guessed working directory is not one: that is the tree the seat was started in, not the repository that travels between machines. LJOS_USER_RULES_SYNC=off names none. In tests the variable has to be set to something other than off before a tracker is read, so an unset shell does not sync the login’s rules.