specs/024-verified-archive-repair/contracts/archive-repair.md

Rama main · réplica de lectura del repositorio original.

# Verified archive repair contract v1

## Diagnostic boundary

Ordinary inventory runs first. Only its direct `Unavailable` triggers bounded diagnosis of the same canonical regular source. Bind complete source SHA-256/full signature and canonical ancestor identities before/after. Size, deadline or drift failure returns retained review. Expose only fixed status/reason, with false grants. Never stage, rename, delete, submit or acknowledge import from diagnostics. Catalog/admission failures cannot become archive diagnoses.

## Pure repair

Require a closed ZIP32 archive, one empty stored Unix directory with consistent flag and missing slash, supported flags/compression/extras and no prefix, gaps, overlaps, descriptors, encryption, aliases or unsafe names. Completely verify every member with CRC and normal inventory/metadata bounds. Unsupported cases retain review or their separately verified decoder/conversion path.

Insert one slash in each local/central name and adjust only necessary lengths/offsets/footer fields. Compare complete member/page/root-metadata vectors to virtual original inventory. Independently undo declared edits and reconstruct every original record, including compressed content, timestamps, extras and comments. Pure returned bytes confer no permission.

## Native preparation

The existing authenticated primary-key POST `publicationControl` adapter accepts `prepare-archive-repair` or `archive-repair-status` with exactly `version`, `action`, `owner` and a lowercase SHA-shaped `operation_id`. The current native catalog supplies the sole confined source. Requests cannot provide a path, witness, receipt or adoption flag. Under existing-only Writer and Controller, resolve actual current catalog ownership and generate the exceptional witness from real bytes; bind full correction census and every matched current owner. Exactly one captured original may use exceptional inventory inside this operation; all other archives retain ordinary checks.

Write exclusive private staged bytes and distinct preservation/restore custody outside scanned roots, fsync and independently verify every readback and physical fact. Seal source/stage/custody/catalog/census/writer facts before returning immutable non-executable preparation. Missing/linked/aliased/stale state stays held; no caller receipt creates authority.

Complete source attributes include the raw NFS `system.nfs4_acl`. A private local
copy may lack only that attribute after its exact destination write returns
`EOPNOTSUPP`; every other attribute or error remains strict. The second private
copy reproduces the first copy's verified attributes, while source metadata,
both copies' original physical/hash facts and their exact actual attributes
remain retained. Reconstruction and terminal verification check that same finite
projection. This is byte/portable-attribute custody, not proof of ACL restoration
on a local filesystem. Canonical NFS derivative publication and reversal still
require complete original ACL application and readback. Exercise both the actual
NFS-to-local boundary and same-NFS ACL readback before a new configured attempt.

### Preparation/status source integration

Preparation creates an exclusive private operation directory with intent, original,
independently restored original, repaired bytes and immutable preparation. Status
recomputes current source/catalog/census, original/restore custody, member CRCs and
exact derivative bytes. Missing operations return missing; partial retained evidence
returns review without a token, completion, overwrite or replay. Both actions use
an ordinary existing-only Writer. Every native, adoption, publication and reader
grant remains false.

The managed namespace is bounded to eight operations and 4 GiB retained bytes,
with 512 MiB per source and existing archive member/expanded/deadline limits.
Bind admitted directory/file descriptors for reads, exclusive private creation and
readback. Any negative-retirement pending marker holds these purposes, including
malformed, aliased or inaccessible state. No serialized proof or recovery flag
bypasses ordinary admission. Preparation/status source installation does not install
the dedicated consumer described below.

## Dedicated consumer

Consume only that preparation at the exact current owner/catalog/census with typed reader/custody scope. Equal payload is expected for this repair but cannot waive rejected-owner policy. Never widen `prepare-lineage`, `adopt-derivative`, `commitReviewedDerivative`, ordinary `require`, worker `import_check` or generic imports.

No remote calls under Writer. Reader preparation/acknowledgement follows writer release and complete local revalidation; HTTP success is not reader continuity. Preserve exact affected book/page references and unrelated records before retiring an original name. Journal exact predecessor/phase before dispatch or filesystem transition. Lost responses, partial transitions or contradictory state hold without replay. Native/reader acceptance precedes import/cleanup completion.

## Backup and rollout

Measure, consistently back up and independently restore all affected application state and specific originals before live adoption. Retain compatible rollback image/configuration. Compare actual files, catalog/census and reader behavior against baseline; retain custody on inconclusive results. Prune only conclusively superseded operation-owned copies after required acceptance and the one-verified-backup retention rule.

The stopped-reader backup scope is the full inspected `/config` Source. Require
one writable config mount, either a bind or a named volume using Docker's
`local` driver, and reject nested config shadows. Keep the runtime DTO intact.
Configured helper plans must bind that exact Source read-only at an explicit
child path before Parent entry. Both projection directions and original root
identity must match. Child manifest scope paths stay original; host proof
consumers map them through the checked binding instead of rewriting receipts.
The Parent verifies the original volume Name, Driver, Scope, Mountpoint and empty driver options before reader stop. Driver-mounted backends remain held because they may detach at last-consumer stop. Ordinary backup retains identity mapping; configured backup uses the explicit projection. Both reject helper subtree shadows before stop.

Measure this actual reader tree and the owning forbidden-directory census before
reader stop. Bounds must fit the existing helper maxima and both copy-space
requirements with its reserve. This measurement is advisory. The stopped source
inventory, complete backup, isolated restore and database proofs remain strict.

Install exact native/worker diagnostic modules and verify selected runtimes. Advertise diagnostics separately from preparation/adoption and only when actually installed. Features 022/023 still gate general writer release on complete current-library acceptance. A new process does not inherit a process-local startup hold.

## Existing completed preparation factory

`mylar.publication_archive_preparation_existing.from_existing(controller, writer,
owner, operation_id, custody)` accepts only exact installed Controller, held
Writer and stopped-reader custody types. It derives the fixed completed stage;
no caller path or saved receipt can select or authorize reads. Original custody
must retain both `preparation.json` full9 and completed stage directory full9.
Historical stages lacking either original vector remain held.

The factory checks every original control, ancestor, claim, source attribute,
catalog/census, policy, exceptional witness, derivative and independent restore
against the canonical saved metadata before creating the actual owning typed
preparation. Constructor and custody callbacks precede the last raw closure.
Same-byte replacement, new pending state, partial or unknown state remains held.
It does not rerun exclusive preparation, create an operation, bypass the Writer,
add an API replay action or grant reader/publication acceptance. Actual installed
custody production and namespace compatibility require separate runtime evidence.

## Independent terminal facts

The forward and rollback verifier vector APIs return the existing factual
summary plus original full file and ancestor signatures, catalog claims, closed
namespace membership and required absences. Retain all other-owner sources
examined by policy, including their original content hashes and full signatures.
A consumer must carry the original vectors across later report, custody and
watch callbacks and close them again before acknowledgement. These facts do not
construct adoption, authorize replay or prove reader indexing or ordinary import.

The configured host mount observer executes only admitted `findmnt --json`
commands in a new fixed UID1000/GID1000 child with no supplementary groups. It
preserves private staging modes, Root Parent identity, exact original intents,
Writer-window restrictions and physical same-mount checks. Identity options
are not caller input; observation failure supplies no fallback or grant.

## Prospective NFS rename/link purpose

Plan13 and action input v3 explicitly select `rename-link-v1` before any pending
marker. This is not an exchange-errno fallback. Source/stage share one actual
writable NFS4 mount ID and original export/device geometry. The sole transient
common-root bind G→G contains exactly direct children library L and retention R;
G/L/R are distinct UID/GID1000 mode0700 directories held by original FDs. G
full9 and exact `{L,R}` namespace never refresh; only descendant L/R effects are
expected. Extra entries, nested binds, aliases, role overlaps or mount shadows
refuse. Native/reader configuration, DATA, scratch and operation output remain
outside G. The canary owns an absent child below R and cleans it before retention
admission; it cannot use G as the neutral grandparent.

Configured geometry v3, `configured-common-root-nfs`, is a separate alternative
to the disposable private/searchable geometry. Its G is the exact original native
writable bind source and its CHILD destination is the original configured
mapping. L is the whole configured library, R is a distinct private direct child
outside every library root, and all three share one filesystem. G/L retain their
actual owners, groups and modes. R remains UID/GID1000 mode0700. The complete
original G namespace and every child identity replace the disposable two-entry
namespace. Original FDs, G full9, canonical paths, aliases/shadows, same actual
NFS mount ID/export/device and late closure remain required. Existing native and
inactive-worker media binds may overlap G only as their original inspected
profiles. No extra ancestor or new service mount gains authority.

The selected child receives projected paths with the original physical facts,
not HOST path strings relabelled as CHILD paths. Its original host bind remains
in geometry for the export-subtree join. The NFS probe uses its separate original
HOST retention binding at birth, observation and cleanup. Backup input v2 carries
an explicit config projection and original directory9 while retaining the
stopped reader's runtime DTO verbatim. Neither observer nor backup grants repair.

Plan13 configured geometry requires an immutable `configured_original` full9/SHA
reference. Action input v5 carries its exact CHILD projection. Under the original
Writer, the action resolves the requested primary-key owner through the actual
catalog and compares that source before preparation. The owning preparation must
retain the identical original before adoption. A different same-library file,
changed hash or replaced inode refuses. Public requests remain primary-key-only.

Configured G exposes existing unrelated siblings to the restricted repair child.
Namespace sealing detects drift but is not a kernel write sandbox. The operator
must exclude noncooperating writers for the whole existing operation. The child
is writable at G only during execute and retains the fixed six mutation steps.
It cannot use a captured source reference to choose a different catalog owner,
reconstruct a live capability from receipts or replay an uncertain outcome.

Original NFS-ready facts travel over the existing bound Parent pipe before
Writer. They remain sealed separately from ordinary native observation fields.
The one-use typed selection joins original owner/operation/configured paths,
actual mountinfo, retained source/stage identities and stopped-reader custody.
A ready receipt never sets `actual_library_platform_verified` or grants mutation.

The export join accepts either the existing export-plus-fsroot form or the
source-suffix form with both roots `/` and the exact authenticated host-relative
bind subtree appended to the original export. Actual target, device, access,
same-mount identity and nested-mount refusals remain required. A changed native
adoption module requires matching installed image/SDK proof.

Under stopped reader, inactive worker and exclusive original Writer, each
install/reverse records intent then completion for retain-displaced hardlink,
source unlink, no-clobber publication hardlink, stage unlink, original-retention
hardlink and displaced unlink. Original source/stage identities, streaming hashes
with monotonic deadlines, attributes and finite nlink1→2→1 transitions remain
bound. Before each unlink, close only the affected inode's owned FD after
hash/alias validation. After all callbacks, inline original pathname, remaining
FD, ancestor, namespace and absence CAS immediately precedes each syscall.
Reopen the affected inode through its predetermined surviving hardlink with
no-follow semantics and verify its original identity, bytes and metadata before
any callback or completion receipt. The other inode and directory FDs remain
held. This avoids NFS open-file silly-renames without admitting hidden aliases
or refreshing expectations. Original and repaired revisions remain held through
every uncertain boundary. Close/reopen uncertainty and other unknown outcomes
grant no replay, automatic restoration, cleanup or reader restart.

This requires no independent actor writing the selected names throughout the
operation. Writer excludes cooperating applications; UID1000/mode0700 do not
exclude another same-UID process or root. NFS offers no inode-conditional unlink.
Replacement observed before the final syscall boundary refuses with the foreign
file retained. Preservation against a non-cooperating post-CAS actor is outside
this explicit exclusion contract; tests demonstrate that limit.

Baseline v2 records the selected protocol and original geometry; the independent
verifier requires the exact twelve install phase receipts and, for rollback,
twelve reverse phase receipts, original G full9, both displaced absences, complete
native preimage/sole-size transition and all reader tables/pages. Baseline v1 and
legacy local exchange retain their exact schemas and direct NFS readiness
function body. Exact parent plan 13 alone selects `nfs_ready_archive_v13` and
admits private request v2 with `terminal=forward|rollback`; rollback reverses the same successfully installed
live capability before typed rollback completion. It is not recovery of an
uncertain operation and adds no public API or generic placement permission.

This transient mount-policy successor adds no permanent Compose mount, setting,
port, privilege or service lifecycle action. Genuine installed factories and
actual NFS/native/reader/worker terminal/ACK acceptance remain separate gates.