vvz-file-backup 0.1.1__tar.gz

vvz_file_backup-0.1.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include pyproject.toml README.md build.sh
+recursive-include examples *.py *.json *.md
+recursive-include pipeline *.py *.json
+recursive-include docs *.md *.json *.yaml
+prune pipeline/evidence
+global-exclude __pycache__ *.py[cod]

vvz_file_backup-0.1.1/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: vvz-file-backup
+Version: 0.1.1
+Summary: Independent incremental file backups with verified saved-point restoration
+Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+Requires-Python: >=3.11

vvz_file_backup-0.1.1/README.md

@@ -0,0 +1,31 @@
+# File Backup package
+
+`vvz-file-backup` backs up regular-file trees into immutable full and incremental points, lists and verifies saved data, and restores a whole tree or one selected file. The Python API is the primary interface. The installed `file-backup` command is a thin adapter for shell use.
+
+## Runnable examples
+
+Start with the [examples directory](examples/). Each script has a module docstring that explains when to use it, its inputs and filesystem effects, its results, expected errors, and an exact invocation. Every example is standalone: it imports the installed `file_backup` package, uses a private temporary workspace, and can be run from any current directory.
+
+| Example | Usage covered |
+| --- | --- |
+| [`01_backup_lifecycle.py`](examples/01_backup_lifecycle.py) | Full and incremental points, unchanged detection, deletions, previews, saved points, and full-base fallback |
+| [`02_catalog_browse.py`](examples/02_catalog_browse.py) | Listing points, inspecting lineage, and listing files |
+| [`03_restore_and_preview.py`](examples/03_restore_and_preview.py) | Full and selective restore, previews, overwrite, and destination conflicts |
+| [`04_verify_and_chain_failure.py`](examples/04_verify_and_chain_failure.py) | Integrity verification and a missing incremental dependency |
+| [`05_typed_errors_and_conflicts.py`](examples/05_typed_errors_and_conflicts.py) | Validation, missing point/file, conflict errors, and safe failure effects |
+| [`06_catalog_configuration.py`](examples/06_catalog_configuration.py) | Explicit catalog directory, config mapping, and default priority |
+| [`07_metadata_and_schemas.py`](examples/07_metadata_and_schemas.py) | Metadata and schema accessors for all public operation classes |
+| [`08_help_and_info.py`](examples/08_help_and_info.py) | Metadata-driven help and installed guide sections |
+| [`09_thin_cli.py`](examples/09_thin_cli.py) | JSON command-line results and typed CLI errors |
+| [`10_offline_installed_restore.py`](examples/10_offline_installed_restore.py) | Installed-package import and offline archive/restore flow |
+| [`11_recover_catalog.py`](examples/11_recover_catalog.py) | Preview and recover a validated catalog copy |
+
+Run an example from any directory after installing the package:
+
+```sh
+python /path/to/file-backup/examples/01_backup_lifecycle.py
+```
+
+The machine-readable [`manifest.json`](examples/manifest.json) maps each script to its public capability coverage. The package pipeline executes the listed scripts independently against a clean installed build. Distribution packaging must include this examples directory and manifest so the same guide remains available after installation.
+
+The normative method, parameter, result, relationship, and side-effect contract is in [`docs/package-api-matrix.json`](docs/package-api-matrix.json). Use it for exhaustive integration details; start with the runnable examples for practical usage.

vvz_file_backup-0.1.1/build.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Never trace credentials inherited from the caller, including with bash -x.
+set +x
+
+PACKAGE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PYTHON="${FILE_BACKUP_PYTHON:-python}"
+cd "$PACKAGE_ROOT"
+
+error() { echo "ERROR: $*" >&2; exit 1; }
+info() { echo "INFO: $*"; }
+
+[[ $# -eq 0 ]] || error "This command accepts no arguments; set FILE_BACKUP_VERSION for an explicit package version"
+[[ ! -L "$PACKAGE_ROOT/pyproject.toml" && -f "$PACKAGE_ROOT/pyproject.toml" ]] \
+    || error "Package pyproject.toml must be a regular file"
+command -v "$PYTHON" >/dev/null 2>&1 || error "Python is required: $PYTHON"
+
+VERSION="$($PYTHON - "$PACKAGE_ROOT/pyproject.toml" "${FILE_BACKUP_VERSION:-}" <<'PY'
+from pathlib import Path
+import re
+import sys
+import tomllib
+from packaging.version import InvalidVersion, Version
+
+path = Path(sys.argv[1])
+requested_text = sys.argv[2]
+project = tomllib.loads(path.read_text(encoding="utf-8"))["project"]
+if project.get("name") != "vvz-file-backup":
+    raise SystemExit("Package distribution name must be vvz-file-backup")
+current_text = project["version"]
+try:
+    current = Version(current_text)
+except InvalidVersion:
+    raise SystemExit(f"Current package version is not valid PEP 440: {current_text}")
+
+if requested_text:
+    try:
+        requested = Version(requested_text)
+    except InvalidVersion:
+        raise SystemExit(f"Requested package version is not valid PEP 440: {requested_text}")
+    if requested <= current:
+        raise SystemExit(
+            f"Requested package version {requested_text} must be greater than current version {current_text}"
+        )
+    target_text = requested_text
+else:
+    release = list(current.release)
+    if not release:
+        raise SystemExit(f"Current package version has no release numbers: {current_text}")
+    release[-1] += 1
+    epoch = f"{current.epoch}!" if current.epoch else ""
+    target_text = epoch + ".".join(str(number) for number in release)
+print(target_text)
+PY
+)" || error "Unable to select the file-backup package version"
+
+# Persist the selected independent package version before building so the
+# sdist and wheel metadata agree with the next root release state.
+"$PYTHON" - "$PACKAGE_ROOT/pyproject.toml" "$VERSION" <<'PY'
+import json
+from pathlib import Path
+import re
+import sys
+import tomllib
+
+path = Path(sys.argv[1])
+text = path.read_text(encoding="utf-8")
+project = tomllib.loads(text)["project"]
+updated, count = re.subn(
+    r'(?m)^(version\s*=\s*)"[^\"]+"$',
+    lambda match: f'{match.group(1)}"{sys.argv[2]}"',
+    text,
+    count=1,
+)
+if count != 1 or updated == text and project["version"] != sys.argv[2]:
+    raise SystemExit("Unable to update the package version in pyproject.toml")
+
+metadata_paths = sorted((path.parent / "src/file_backup/api").rglob("metadata.json"))
+if len(metadata_paths) != 30:
+    raise SystemExit(f"Expected 30 API metadata files, found {len(metadata_paths)}")
+metadata_updates = []
+for metadata_path in metadata_paths:
+    metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+    if not isinstance(metadata, dict) or "version" not in metadata:
+        raise SystemExit(f"API metadata has no version field: {metadata_path}")
+    metadata["version"] = sys.argv[2]
+    metadata_updates.append(
+        (metadata_path, json.dumps(metadata, ensure_ascii=False, indent=2) + "\n")
+    )
+
+path.write_text(updated, encoding="utf-8")
+for metadata_path, metadata_text in metadata_updates:
+    metadata_path.write_text(metadata_text, encoding="utf-8")
+PY
+
+if [[ -n "${PYPI_API_TOKEN:-}" ]]; then
+    export TWINE_USERNAME="__token__"
+    export TWINE_PASSWORD="$PYPI_API_TOKEN"
+elif [[ -z "${TWINE_USERNAME:-}" || -z "${TWINE_PASSWORD:-}" ]]; then
+    [[ -f "${HOME}/.pypirc" ]] \
+        || error "PyPI credentials are required: PYPI_API_TOKEN, TWINE_USERNAME/TWINE_PASSWORD, or ~/.pypirc"
+fi
+
+BUILD_DIR="$(mktemp -d "${TMPDIR:-/tmp}/vvz-file-backup-dist.XXXXXX")"
+cleanup() { rm -rf -- "$BUILD_DIR"; }
+trap cleanup EXIT
+
+info "Building vvz-file-backup $VERSION"
+"$PYTHON" -m build --sdist --wheel --outdir "$BUILD_DIR" "$PACKAGE_ROOT"
+
+WHEEL="vvz_file_backup-${VERSION}-py3-none-any.whl"
+SDIST="vvz_file_backup-${VERSION}.tar.gz"
+[[ -f "$BUILD_DIR/$WHEEL" && ! -L "$BUILD_DIR/$WHEEL" ]] \
+    || error "Expected wheel was not built: $WHEEL"
+[[ -f "$BUILD_DIR/$SDIST" && ! -L "$BUILD_DIR/$SDIST" ]] \
+    || error "Expected sdist was not built: $SDIST"
+shopt -s nullglob
+ARTIFACTS=("$BUILD_DIR"/*)
+[[ ${#ARTIFACTS[@]} -eq 2 ]] || error "Build produced unexpected artifacts for vvz-file-backup $VERSION"
+
+"$PYTHON" -m twine check "${ARTIFACTS[@]}"
+info "Running final package examples check"
+"$PYTHON" "$PACKAGE_ROOT/pipeline/run.py" package_examples
+info "Publishing vvz-file-backup $VERSION to PyPI"
+"$PYTHON" -m twine upload --non-interactive \
+    --repository-url https://upload.pypi.org/legacy/ "${ARTIFACTS[@]}"

vvz_file_backup-0.1.1/docs/CATALOG_DIRECTORY.md

@@ -0,0 +1,50 @@
+# Configurable SQLite catalog directory
+
+The eight repository operations (backup, list_points, inspect_point, list_files,
+restore, restore_file, verify, recover_catalog) accept two keyword-only arguments:
+`catalog_directory: str | None = None` and
+`config: Mapping[str, object] | None = None`.
+
+Resolution order is an explicit non-None argument, `config['catalog_directory']`,
+then the exported string constant `file_backup.DEFAULT_CATALOG_DIRECTORY = '.'`.
+The eight CLI commands accept `--catalog-directory DIR` and `--config JSONFILE`
+with the same priority. Config-file paths resolve from the process working
+directory; catalog paths resolve from the repository. No environment or ambient
+configuration source is introduced.
+
+Omitted/None config means an empty mapping. An empty mapping selects the default.
+Only the key `catalog_directory` is accepted; a present value must be a nonempty,
+NUL-free string. A present null, unknown key, wrong type, empty string or NUL is
+ArgumentError even when an explicit directory wins. The caller's mapping is not
+mutated. CLI JSON must be a UTF-8 object; missing/unreadable/malformed config is
+ArgumentError (exit 2, empty stdout, typed error on stderr).
+
+Relative catalog directory paths, including `..`, normalize against repository;
+absolute directories are accepted. Symlink components and an existing regular
+file in place of a directory are ArgumentError. The selected database is
+`<resolved-directory>/catalog.sqlite3`; SQLite temporary sidecars and lock files
+belong there. Archives remain at `<repository>/archives`. The default therefore
+keeps the catalog on the backup repository's volume. Reading and dry-run calls
+create no database, directory, archive or checkpoint.
+
+No implicit migration, fallback or active database replacement occurs. A missing
+selected database while archives exist raises CatalogError, including when a
+valid catalog remains at the old/default location. Recovery is the exception:
+recover_catalog accepts an absent active catalog with a valid supplied copy and
+writes only its new destination. An empty repository may be
+initialized at the selected directory. Selecting an already-placed valid copy
+for the same archive repository is supported; existing catalog/archive bytes
+remain unchanged. recover_catalog still writes its new destination only and does
+not install it. Backup's source and selected catalog directory must be disjoint;
+restore destinations must be outside the selected catalog directory. Recovery's
+destination cannot be the selected active database.
+
+The complete machine contract is `package-api-matrix.json`:
+`catalog_directory_contract`, updated input cells/schema/signatures and
+`catalog_directory_delta.new_case_ids`. All 40 original rows, 472 original cases,
+14 relation cases and four packaging scenarios are retained. 318 focused cases
+are appended, for 790 total. Existing service rows are separate and preserved.
+The native planner tables remain historical projections; the full JSON annex
+governs this TODO-only change. No PLAN/HRS/MRS/G/T/A/freeze operation is required
+or performed under the user's explicit boundary. Runtime acceptance remains the
+tester's matrix/check RED followed by the same mapped GREEN and full pipeline.

vvz_file_backup-0.1.1/docs/PIPELINE_STUB_MANIFEST.md

@@ -0,0 +1,65 @@
+# File Backup Pipeline Stub Manifest
+
+Status: **NOT_IMPLEMENTED**. These declarations do not execute checks and provide no product GREEN.
+
+## Source and scope
+
+- Source matrix: `docs/package-api-matrix.json` (mutable stage-0 design).
+- Mapping totals: 40 rows, 472 cases, 14 relation cases, 4 packaging scenarios, 490 mappings.
+- Declared checks: 44; each check function raises `NotImplementedError`.
+- Matrix mapping: `pipeline/matrix.json`; every mapping retains its scenario ID, future inputs and source expected result/error/side-effect contract where present. Packaging scenarios whose source defines assertions only are marked as lacking explicit error/side-effect contracts.
+- Runner, CLI entrypoint, fixtures and helpers are declarations that raise `NotImplementedError`; no parser, dispatch, coverage algorithm or test algorithm is present.
+
+## Check declarations
+
+- `package_backup` -> `pipeline/checks/check_package_backup.py`; `check_package_backup() -> None`; **NOT_IMPLEMENTED**.
+- `package_backup_get_schema` -> `pipeline/checks/check_package_backup_get_schema.py`; `check_package_backup_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_backup_metadata` -> `pipeline/checks/check_package_backup_metadata.py`; `check_package_backup_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_build_publication` -> `pipeline/checks/check_package_build_publication.py`; `check_package_build_publication() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_backup` -> `pipeline/checks/check_package_cli_backup.py`; `check_package_cli_backup() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_boundary` -> `pipeline/checks/check_package_cli_boundary.py`; `check_package_cli_boundary() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_help` -> `pipeline/checks/check_package_cli_help.py`; `check_package_cli_help() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_info` -> `pipeline/checks/check_package_cli_info.py`; `check_package_cli_info() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_inspect_point` -> `pipeline/checks/check_package_cli_inspect_point.py`; `check_package_cli_inspect_point() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_list_files` -> `pipeline/checks/check_package_cli_list_files.py`; `check_package_cli_list_files() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_list_points` -> `pipeline/checks/check_package_cli_list_points.py`; `check_package_cli_list_points() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_recover_catalog` -> `pipeline/checks/check_package_cli_recover_catalog.py`; `check_package_cli_recover_catalog() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_restore` -> `pipeline/checks/check_package_cli_restore.py`; `check_package_cli_restore() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_restore_file` -> `pipeline/checks/check_package_cli_restore_file.py`; `check_package_cli_restore_file() -> None`; **NOT_IMPLEMENTED**.
+- `package_cli_verify` -> `pipeline/checks/check_package_cli_verify.py`; `check_package_cli_verify() -> None`; **NOT_IMPLEMENTED**.
+- `package_distribution` -> `pipeline/checks/check_package_distribution.py`; `check_package_distribution() -> None`; **NOT_IMPLEMENTED**.
+- `package_help` -> `pipeline/checks/check_package_help.py`; `check_package_help() -> None`; **NOT_IMPLEMENTED**.
+- `package_help_get_schema` -> `pipeline/checks/check_package_help_get_schema.py`; `check_package_help_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_help_metadata` -> `pipeline/checks/check_package_help_metadata.py`; `check_package_help_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_info` -> `pipeline/checks/check_package_info.py`; `check_package_info() -> None`; **NOT_IMPLEMENTED**.
+- `package_info_get_schema` -> `pipeline/checks/check_package_info_get_schema.py`; `check_package_info_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_info_metadata` -> `pipeline/checks/check_package_info_metadata.py`; `check_package_info_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_inspect_point` -> `pipeline/checks/check_package_inspect_point.py`; `check_package_inspect_point() -> None`; **NOT_IMPLEMENTED**.
+- `package_inspect_point_get_schema` -> `pipeline/checks/check_package_inspect_point_get_schema.py`; `check_package_inspect_point_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_inspect_point_metadata` -> `pipeline/checks/check_package_inspect_point_metadata.py`; `check_package_inspect_point_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_list_files` -> `pipeline/checks/check_package_list_files.py`; `check_package_list_files() -> None`; **NOT_IMPLEMENTED**.
+- `package_list_files_get_schema` -> `pipeline/checks/check_package_list_files_get_schema.py`; `check_package_list_files_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_list_files_metadata` -> `pipeline/checks/check_package_list_files_metadata.py`; `check_package_list_files_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_list_points` -> `pipeline/checks/check_package_list_points.py`; `check_package_list_points() -> None`; **NOT_IMPLEMENTED**.
+- `package_list_points_get_schema` -> `pipeline/checks/check_package_list_points_get_schema.py`; `check_package_list_points_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_list_points_metadata` -> `pipeline/checks/check_package_list_points_metadata.py`; `check_package_list_points_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_published_artifact` -> `pipeline/checks/check_package_published_artifact.py`; `check_package_published_artifact() -> None`; **NOT_IMPLEMENTED**.
+- `package_recover_catalog` -> `pipeline/checks/check_package_recover_catalog.py`; `check_package_recover_catalog() -> None`; **NOT_IMPLEMENTED**.
+- `package_recover_catalog_get_schema` -> `pipeline/checks/check_package_recover_catalog_get_schema.py`; `check_package_recover_catalog_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_recover_catalog_metadata` -> `pipeline/checks/check_package_recover_catalog_metadata.py`; `check_package_recover_catalog_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_restore` -> `pipeline/checks/check_package_restore.py`; `check_package_restore() -> None`; **NOT_IMPLEMENTED**.
+- `package_restore_file` -> `pipeline/checks/check_package_restore_file.py`; `check_package_restore_file() -> None`; **NOT_IMPLEMENTED**.
+- `package_restore_file_get_schema` -> `pipeline/checks/check_package_restore_file_get_schema.py`; `check_package_restore_file_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_restore_file_metadata` -> `pipeline/checks/check_package_restore_file_metadata.py`; `check_package_restore_file_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_restore_get_schema` -> `pipeline/checks/check_package_restore_get_schema.py`; `check_package_restore_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_restore_metadata` -> `pipeline/checks/check_package_restore_metadata.py`; `check_package_restore_metadata() -> None`; **NOT_IMPLEMENTED**.
+- `package_verify` -> `pipeline/checks/check_package_verify.py`; `check_package_verify() -> None`; **NOT_IMPLEMENTED**.
+- `package_verify_get_schema` -> `pipeline/checks/check_package_verify_get_schema.py`; `check_package_verify_get_schema() -> None`; **NOT_IMPLEMENTED**.
+- `package_verify_metadata` -> `pipeline/checks/check_package_verify_metadata.py`; `check_package_verify_metadata() -> None`; **NOT_IMPLEMENTED**.
+
+## Boundaries
+
+- No `pipeline` command, test, build, install, publication, deployment, push or synchronization was run.
+- No product API, existing package asset, root build script or service pipeline was changed.
+- No PLAN/HRS/MRS/G/T/A or cascade artifact was read or changed.
+- All check bodies explicitly raise `NotImplementedError`; the mapping status is `NOT_IMPLEMENTED`.

vvz_file_backup-0.1.1/docs/STAGE0.md

@@ -0,0 +1,50 @@
+# Package matrix documentary handoff
+
+The current scope is TODO-only by explicit user instruction. Do not create, read,
+mutate, import, freeze or validate PLAN/HRS/MRS/G/T/A artifacts for this task.
+This document supersedes the original stage-0 candidate/skeleton handoff.
+
+The full authority is package-api-matrix.json, retained as backup_package_stage0
+in project matrix TODO 368a1d2b-5d42-419a-b50b-9f4f8e6e7f81. Project identity is
+ff997eab-d809-4cb9-b805-9dff4df60c6d. Root TODO is
+55bc5124-9708-46c3-b56c-fbc29ea239b1; execution map is
+c052cd96-0967-4842-8176-b598eab7354a. The separate 45 service rows are preserved.
+The examples requirement is root child 2ed43027-2943-4e29-a17c-bb01f1f27e34.
+
+The annex contains 40 call rows (30 Python methods, 10 CLI commands), 790 cases,
+8 parameter relations with 14 original relation cases, and 5 packaging scenarios:
+790 + 14 + 5 = 809 required executable mappings. The 318 catalog/config cases
+supplement all 472 original cases. PKG05 supplements the four original packaging
+scenarios. No original focused case, result assertion or server row is waived.
+
+The three planner/*.md files are documentary native-dialect projections. They
+retain required Russian headers/grammar and reserved {fb01} source tokens while
+their explanatory prose is English. They describe 40 rows, 76 relation entries
+and 262 shallow result cases. API config projects its JSON-object subset and
+catalog_directory its non-null string subset. Full Mapping/null/omission, config
+key validation, path semantics, typed errors, dynamic results, chains and file
+effects require the full annex. No runtime import/lint verdict is claimed.
+
+Catalog priority is explicit API/CLI > config > DEFAULT_CATALOG_DIRECTORY='.'.
+Default catalog.sqlite3 is on the repository volume. See CATALOG_DIRECTORY.md
+and the annex for validation, no-silent-migration and recovery exceptions.
+
+The tester owns executable matrix/checks and runtime evidence. Canonical
+examples acceptance is `python file-backup/pipeline/run.py package_examples`.
+The complete `python file-backup/pipeline/run.py --all` runs every other check
+first and package_examples LAST as its final stage. All examples must execute
+adequately; expected errors are caught and asserted; no skip/XFAIL. English
+module docstrings explain purpose, when/why, invocation, prerequisites, files,
+results, effects and errors. Documentation in examples and product code is
+English. build.sh must require successful current-candidate examples BEFORE
+twine upload; any failure is nonzero and blocks publication. Candidate example
+acceptance never depends on a prior publication.
+
+This update verifies documentary consistency only. It does not claim a current
+runtime pipeline GREEN, installed-package success or publication. Reuse the
+separate tester/build owner's exact evidence for those states; do not rerun them
+merely because these projections changed.
+
+Server obligations remain separate: latest-only document export, an hourly
+worker, a separately mounted backup volume, server API/matrix checks and deployed
+integration acceptance. The package matrix does not replace the server matrix.

vvz_file_backup-0.1.1/docs/USER_GUIDE.md

@@ -0,0 +1,101 @@
+# File Backup User Guide
+
+## Contents
+
+- [Overview](#overview) - `file-backup://info/overview`
+- [Backup](#backup) - `file-backup://info/backup`
+- [Restore](#restore) - `file-backup://info/restore`
+- [Catalog](#catalog) - `file-backup://info/catalog`
+- [Errors](#errors) - `file-backup://info/errors`
+- [Release](#release) - `file-backup://info/release`
+
+## Overview
+
+File Backup is a standalone Python package for saving completed filesystem slices and restoring
+them later. Its Python API is available from `file_backup`; its command-line program is
+`file-backup`. Both interfaces use the same operation methods and result contracts.
+
+The package stores its catalog and archives under the repository directory supplied to an
+operation. It reads regular files from the source tree and does not preserve ownership, modes,
+timestamps, symbolic links, or empty directories. Keep the source unchanged for the duration of a
+backup call.
+
+Use `file-backup help` for command and parameter guidance, or `file-backup info` to print this
+guide's table of contents. The Python equivalents are `Help.execute()` and `Info.execute()`.
+
+## Backup
+
+Call `Backup.execute(repository, source)` or `file-backup backup --repository PATH --source PATH`
+to save a completed source tree. The first saved point is full. Later calls save additions,
+changes, and deletion tombstones relative to the previous successful point. A byte-for-byte
+unchanged source creates no archive or saved point. If the full archive needed to continue a chain
+is missing, the next successful backup starts a new full chain.
+
+`dry_run=True` or `--dry-run` returns a preview without creating or changing the catalog, archive,
+or checkpoint. The result identifies whether the operation would create a full point, an
+incremental point, or no point.
+
+## Restore
+
+Use `Restore.execute(repository, point, destination)` to restore one exact saved point. The
+destination must be absent or empty. The package checks the complete required archive chain and
+content digests before publishing restored files. A missing or corrupt dependency fails the
+operation; it does not return a partial restore or substitute a nearby point.
+
+Use `RestoreFile.execute(repository, point, path, destination)` to restore one live relative path.
+The destination file is not replaced unless `overwrite=True` is supplied. A file deleted at the
+selected point is unavailable at that point, even if an older point contains it. Both restore
+operations support a no-write `dry_run` preview.
+
+The CLI forms are `file-backup restore --repository PATH --point UUID --destination PATH` and
+`file-backup restore-file --repository PATH --point UUID --path RELATIVE_PATH --destination PATH`.
+
+## Catalog
+
+`ListPoints.execute(repository)` lists committed saved points in completion order. Use
+`InspectPoint.execute(repository, point)` for one point's identity and chain, and
+`ListFiles.execute(repository, point)` for its live files. `Verify.execute(repository, point)`
+checks the catalog bindings, archive chain, manifest, and referenced file contents.
+
+All eight repository operations accept the keyword-only `catalog_directory` and `config`
+arguments. The selected SQLite file is `catalog.sqlite3` under the selected directory; archives
+remain under `<repository>/archives`. The default is the repository directory itself, exposed as
+`file_backup.DEFAULT_CATALOG_DIRECTORY == "."`. Relative catalog directory values, including
+`..`, resolve from the repository. An absolute catalog directory is also accepted.
+
+Selection priority is explicit `catalog_directory`, then `config["catalog_directory"]`, then the
+default constant. A `None` explicit value means unspecified. `config` may be omitted or `None`;
+otherwise it must contain only the nonempty, NUL-free string key `catalog_directory`. Config is
+validated even when an explicit directory takes priority. No environment or ambient config is
+read. The CLI forms are `--catalog-directory DIR` and `--config JSONFILE`; the JSON file path is
+relative to the process working directory, and its UTF-8 JSON object is decoded before the API
+call.
+
+The package does not migrate, copy, or fall back to another catalog. If the selected catalog is
+missing while archives exist, the operation fails even when another catalog file is present.
+Read-only operations and dry runs create no catalog directory or database.
+
+`RecoverCatalog.execute(repository, destination, catalog_copy)` validates a caller-supplied
+consistent SQLite backup against the repository archives and writes a validated copy to a new
+destination. It does not infer points from loose archive files and does not replace the active
+catalog. Switching an installation to a recovered catalog is a separate offline administrative
+operation.
+
+## Errors
+
+Operations raise typed `FileBackupError` subclasses. Each error has a stable `code`, a readable
+`message`, and a `context` mapping with operation-specific fields. Argument errors identify the
+parameter and violation. Missing points, files, archives, corrupt content, broken chains, I/O
+failures, catalog failures, and conflicts have distinct error types.
+
+The CLI catches package errors at its boundary. Argument, command-selection, and information
+section-selection errors exit with status 2. Other package errors exit with status 1. Errors are
+written to standard error with their stable code and context; standard output remains empty.
+
+## Release
+
+The `vvz-file-backup` distribution contains the importable `file_backup` package, its JSON schema
+and metadata resources, and the installed guide used by `Info.execute()`. It is designed to build
+and install independently of doc-store and adapter packages. Use the package's own build and
+release instructions when preparing a distribution; do not copy credentials into command output
+or logs.

vvz_file_backup-0.1.1/docs/catalog-directory-validation.json

@@ -0,0 +1,14 @@
+{
+  "status": "GREEN documentary only; runtime acceptance pending",
+  "rule": "CFG-CONTRACT immutable completion criterion",
+  "command": "python tmp/validate_catalog_matrix.py",
+  "exit_code": 0,
+  "matrix_sha256": "9bda0048146ac20520157f2a4cb98d47f3d306eae53d1fb9f059685125dd780d",
+  "rows": 40,
+  "cases": 790,
+  "new_cases": 318,
+  "original_cases_preserved": 472,
+  "original_result_contracts_preserved": 472,
+  "original_relation_cases_preserved": 14,
+  "original_packaging_scenarios_preserved": 4
+}