packutils — design #

Status: the linking port (plan M2, 2026-10-15) and harvest (M3, 2026-10-16) implemented. AI-authored (Claude).

1. What it is #

packutils is the C++23 library behind Packwand's work on a game instance beside a pack:

• Linking (link, unlink, link --watch): a pack's content folders linked into a game directory, so the instance follows the pack. A symlink on Linux and macOS, a junction on Windows, and a copy kept in step by polling where neither works or --copy asks. Ported from Packwand's Zig engine (ledgers D-ZIG-LINK-1, D-ZIG-LINK-2) with its state files byte for byte.
• Harvesting (M3, experimental): the reverse, an instance's changes brought back into the pack, as a plan Packwand guards and commits.

Packwand stays one static binary: packutils is linked in, as packluau is. Packwand owns the pack's rules (which folders are linked, the inventory rules), the clock, the watch loop and every write to pack sources; packutils owns placing, recording, copying and removing links.

2. Architecture #

• include/packutils.h: the C ABI. Zig reads it through translate-c in apps/packwand/src/mpm_packutils (arch_check A10), and mpm_infra/files/PackutilsLinked.zig is the adapter the commands use.
• src/abi.cpp: the exported functions; every one is noexcept.
• src/links.cpp: the engine. src/launchers.cpp (instance folders), src/records.cpp (links.json), src/mirror.cpp (a copy's sync rules and manifest), src/json.cpp (strict reader, canonical writer), src/fs_*.cpp (POSIX and Win32, links never followed).
• No third-party code; hashing comes from the host (section 3).

3. The ABI (PACKUTILS_ABI 1) #

• packutils_create(host, host_abi, &rt, &err) checks the ABI, host->size and that every host function is set. pu_host carries:
  • cancel: a byte; nonzero stops the running operation at its next check (between files, and while waiting for the links lock).
  • sha256(ctx, bytes, out): names a copy's manifest file (hex(sha256(instance)[0..8])).
  • sha512_file(ctx, path, out): a file's SHA-512 read through. A copy's manifest records it, and harvest's plan carries it, so hashes compare directly with Packwand's own.
  • Hashing comes from the host by design: packutils carries no cryptography, and every digest is the one Packwand's std computes. Decided before ABI 1 shipped. ABI 1 is unreleased, so harvest's three functions joined it without a bump.
• Each operation takes one JSON request (UTF-8, an object) and answers one JSON document, valid until the next call or packutils_free_result. Every request names "pack" (the pack's real full path) and may set "lock_files" (default true; false only for Wine, which has no byte-range locks), "lock_timeout_ms" (default 10000) and "links_unavailable" (a test seam: no directory links, so copies).

Function	Request members	Answer
packutils_links_load	—	{"links":[Link]}
packutils_resolve_instance	instance	{"instance": real path, "launcher"?: {kind, minecraft, loader, loader_version}}
packutils_link_check	instance, folders	{"checks":[{folder, slot, path}]}
packutils_link	instance, checks, force, copy, now (Unix seconds)	{"placed":[{folder, mode, kept, backup?, blocked}]}
packutils_unlink	instance (or null for every instance)	{"removed":[{link, outcome, restored}]}
packutils_sync	link (a copy link)	{"copied","deleted","blocked","failed","kept","conflicts","unknown"}
packutils_harvest_plan	instance, pack_folders, never?, folders?, files?, mods?	{"findings":[{kind, path, sha512}],"candidates":[...]}
packutils_lock	—	{}; the runtime holds the links lock until packutils_unlock(rt)

resolve_instance takes a game directory or a launcher's instance folder. A Prism (MultiMC, PolyMC) folder holds instance.cfg; its game directory is .minecraft/ (older MultiMC: minecraft/), and one with neither has never been started and is refused. launcher reports what its mmc-pack.json names (kind is prism; a member it does not state is empty), and Packwand warns when that differs from the pack (src/launchers.cpp).

Link is {instance, folder, mode, backup?}, mode one of symlink, junction, copy; slot one of free, empty_directory, ours, taken; outcome one of removed, missing, left_in_place.

4. Failures #

pu_error carries a status (PU_FAILED, PU_INVALID for a malformed request, PU_CANCELED, PU_INTERNAL), and with PU_FAILED a kind (the host's error kinds), a stable code and a message:

Code	Kind	When
InstanceInvalid	invalid_request	the game directory is missing, not a directory, or overlaps the pack
LinksLockTimeout	conflict	another process held .packwand/lock for the whole timeout
LinkConflict	conflict	a slot holds a folder the pack did not link, or a copy is no longer one
NotALink	conflict	a recorded link was replaced by a real folder
LinkRetargeted	conflict	a recorded link points elsewhere now
LinksInvalid	invalid_request	links.json is not one this build writes
LinksTooNew	invalid_request	a newer build wrote links.json (upgrade is set)
MirrorManifestInvalid	invalid_request	a copy manifest is not one this build writes
MirrorManifestTooNew	invalid_request	a newer build wrote a copy manifest (upgrade is set)
HarvestFolderInvalid	invalid_request	a folders name the instance lacks, or the pack has
HarvestFileMissing	not_found	a files name that is no file at the instance's top
HarvestUnreadable	operation_failed	an instance file could not be read for its hash
FileSystem	operation_failed	the file system refused: path, cause (Zig's error name), directory

For FileSystem the host words the message, as .NET would have, from the cause and path.

5. State files #

From the Zig engine, unchanged: .packwand/links.json (version 1), .packwand/lock, .packwand/.gitignore (*), and backups in the instance's .packwand-backup/<folder>-<yyyyMMddTHHmmssZ>[-n].

A copy's manifest, .packwand/copies/<16 hex>-<folder>.json, is version 2 (ledger D-ZIG-HARVEST-1): each placed file maps to {"source":[size,mtime_ns],"target":[size,mtime_ns], "sha512":"<hex>"|null}, the source's stamp when copied, the copy's own stamp after, and the SHA-512 of the bytes placed. Version 1 ("<path>":[size,mtime_ns], the source's stamp alone) is still read; a newer version is refused with upgrade. Both files are written by the canonical JSON writer, whose bytes the tests pin.

What sync does with each file the source and the copy both hold (mirror::classify): stamps decide first, and a hash is read only when a stamp moved, so a pass reads no file that did not change.

The copy	The source	Sync
as placed	unchanged	nothing (a moved stamp with the same bytes is refreshed)
as placed	changed	copies
changed	unchanged	keeps it, reported once (kept)
changed	changed	keeps it (conflicts), unless both now hold the same bytes
version 1 entry	either	hashes both: the same becomes version 2; otherwise unknown, kept
never placed	—	keeps it, unless it is the same bytes, which are adopted
deleted	—	copies the pack's back

A placed file the source dropped is deleted only while it is as placed; a changed one becomes the instance's (it leaves the manifest), and a version 1 one is unknown. unlink follows the same rule, so an edited copy stays; it also removes any copy file whose bytes the pack's own file holds (as after a harvest), since nothing is lost.

6. Harvest #

packutils_harvest_plan reads only, holding the links lock for the whole scan. Per copy link into the instance it reports (mirror::findings): edited, conflict, unknown, added, deleted, and jar for a jar added at the top of the pack's mods folder; symlinked and junctioned folders are the pack's own and report nothing. candidates are the instance's top-level folders the pack does not link (not dot-folders, the backup folder, or never); folders takes one whole, and files names top-level files (file). Each finding but deleted carries the instance file's SHA-512 as read.

Packwand decides the rest (harvest_command.zig): what is taken (--prefer, --path, --deletions), jars identified into sidecars, destinations the pack cannot keep. Its apply holds the links lock through packutils_lock from reading the instance until the commit ends (lock order: the links lock, then the pack's write lock; sync never takes the write lock), re-hashes each instance file against the plan, and commits through commitSources guarded by each pack file's SHA-512 as planned.