Archive Package
link-archive reads and writes archives for every kind, knowing keys, owners and tables, never what an agent is. The archive module's lnk archive is its one user, and the agent module writes a deleted agent's archive through it.
What It Builds On
An archive carries a thing's state, its folders under ~/Link, and
nothing else. The package finds them through the layout that
link-files
declares: each owner in layout.toml's [owners] names its kind, the
word an archive selects its things by, and its state parts. The
owner's folder in each state part is a location with a stable key, such
as link.agents for ~/Link/Agents, and a thing's folder there is
<location>/<name>.
Selection
A selection is a kind and a name joined by a dot, agent.main
(Selection). Neither holds a dot, so it splits one way. Pick adds
the name an import takes, as agent.main=agent.work, refused when
the two kinds differ. Only the archive reads selections.
archive.toml
An archive's first entry is archive.toml (Manifest), a saved file
declared with link_files::specification!, so a change to its shape is
a schema step. It holds a description, the day a deletion made the
archive (deleted), a [map] of location keys to paths in the archive,
and an empty table per thing, keyed by its selection:
# archive.toml
schema = 1
description = "A coding agent that plans, reviews and commits its own changes"
[map]
"link.agents" = "Agents"
"link.agent-settings" = "Safe/Agents"
["agent.main"]The map gives each key its layout default, never this machine's path, so where you moved your folders never reaches the archive. Import follows whatever paths the map names, and refuses a key this Link doesn't know, a key outside the Link folder, a path outside the archive and two paths where one is inside the other.
Renamed Locations
A release that renames a location renames its key in the map with a
step in src/manifest.schema.toml, the key quoted since it holds a dot
('map."link.machines"' = 'map."link.boxes"'), so an archive made
before the rename reads under the current name.
Writing
Writer writes a gzip-compressed tar file: archive.toml first, then
each folder's plain files and folders sorted by name. Every entry has
mode 644 or 755, time zero and no owner, so the same state writes the
same archive on any machine. Each folder and file is opened by its
folder's handle, never through a link, so a link swapped in while it's
read isn't followed. A link, a device, a file with a second name (a hard
link), a name that isn't UTF-8, or a path or size the reader wouldn't
admit refuses the export, naming it.
Exporting
export checks every thing with its owner and refuses one running
before it writes anything. It writes beside the archive under a
temporary name and links it into place, so it never overwrites a file
and never leaves an archive written in part. pack writes an archive
kept as a folder, as Link keeps its own agents, by the same writer,
refusing a file in no thing's folder.
Packing a Prepared Folder
pack validates the manifest's layout and rejects files outside the named
state folders. Its state trees use Writer's handle-based reads, but root
archive.toml and README.md are read by path. Prepare and inspect those
root files yourself, rather than treating folder packing as an untrusted
archive-reader boundary.
Reading
stage reads an archive as untrusted data into a new folder under
~/.lnk/data/archives (lnk.archive-staging), removed when the
Staged value is dropped. It refuses, naming the entry:
- an archive whose first entry isn't
archive.toml; - a long name longer than its path limit, and any header but a GNU long name, such as a PAX one;
- a path that's absolute, holds
.., or is longer thanlimits.tomlallows; - a link, hard link, device, named pipe or any entry but a plain file or folder;
- an entry twice;
- an entry outside the folders
archive.tomlnames, butREADME.mdat its root; - more entries or bytes than
limits.tomlallows, or than the space free here; - a thing whose folders aren't all in the archive.
Staged files are only the user's (600, folders 700), whatever modes the archive says. However small the file, it never decompresses to more than the most an archive may hold. Nothing in an archive is ever run.
Importing
import stages the whole archive and selects the requested things. Each
selected owner checks its staged files before anything is asked or moved,
then the importer settles each name
(names::choose).
Names and Placing
A name taken here, in any of its owner's parts, is
never overwritten, and neither is a name the layout keeps in its
owner's folders: in a terminal you're asked for another, and without one
the import is refused, naming --names. Each thing's folders move into
place together or not at all. When staging is on another disk, a folder
is copied beside its place under a temporary name and renamed into it.
Its owner then adopts it, and a failed adoption removes what was placed.
When a later thing fails, the things already imported stay, and the
error names them.
Owners
Owner is what only a kind's module knows, answered from files alone:
check reads its files with their owning types, running says whether
export must refuse it, missing lists what it needs here with each
setup command, and adopt writes the owner's records in ~/.lnk for a
thing under the name chosen. The archive module answers Owner by
asking the owner's module questions. Tests answer it with a fake owner,
so every kind shares one suite.
Expiry
expired selects a readable archive only when its manifest records a deletion
older than the retention limit and its filename still matches the deletion's
<name>-<date>.tar.gz or numbered form. Renaming it prevents expiry. A normal
export has no deletion marker, and unreadable archives are left alone.