dbabrain 0.1.0__py3-none-any.whl

db_ops/__init__.py

@@ -0,0 +1,8 @@
+"""DB Ops Python helpers for ORD 46."""
+
+__all__ = ["__version__"]
+
+# Single source of truth for the db_ops version. Bump this on every fix/change;
+# the Docker build (docker/build_and_package.ps1) reads it to tag the image
+# (db_ops:<version>). Format: MAJOR.MINOR.PATCH (zero-padded).
+__version__ = "0.1.0"

db_ops/cli.py

@@ -0,0 +1,495 @@
+"""The root entry point: the logging/store smoke test, and the one command that spans apps.
+
+Everything else in this tree belongs to exactly one component. ``check-credentials`` does not —
+answering "does every configured target resolve to a real login" needs the *metrics* target
+loader (which attaches the resolved credential) and the *Telegram* SQL-command resolver (which
+owns its own lookup rules), and no component may import two apps: apps may not import each other,
+and ``common`` may not import any.
+
+It lived in ``db_ops.common.cli`` until 2026-08-15 behind the single entry in
+``ALLOWED_UPWARD_IMPORTS``. That entry was the shared layer's only upward edge in the whole tree,
+kept alive by one command that was never really shared-layer work. Here it costs no exception:
+``db_ops/cli.py`` is a root module, not a component, so it sits outside both import rules — which
+is exactly what a composition root is for.
+
+A config-only reimplementation was the obvious alternative and is the wrong one: it would answer a
+*different* question than the one the apps ask at runtime, which is the failure this command
+exists to catch.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import socket
+import sys
+from pathlib import Path
+
+from db_ops.config import DEFAULT_CONFIG_PATH, load_config
+from db_ops.db import DbOpsStore
+from db_ops.db.schema_export import export_sqlite_schema
+from db_ops.db.job_runs import JobRun
+from db_ops.levels import normalize_level
+from db_ops.logging_ops import log_event, log_function_call, log_function_error, setup_app_logger
+from db_ops.logging_ops.runtime_stdout import patch_stdout
+
+
+CHECK_CREDENTIALS_USAGE = (
+    "usage: python -m db_ops.cli check-credentials [<json>|@<file>|-]\n"
+    "\n"
+    "Verify every configured target resolves to a named credential. Exit 1 if any does not.\n"
+    "\n"
+    "Answers in the standard response envelope; the unresolvable targets are in data.problems.\n"
+    'Pass {"format": "txt"} for the old plain-text listing (problems on stderr, summary on\n'
+    "stdout), which is what pasted runbook lines expect.\n"
+    '  {"data_dir": "data"}\n'
+    "\n"
+    "Fields:\n"
+    "  data_dir   folder holding db_instances.json / users.json / sql_targets.json\n"
+    "             (default: the folder data_sources resolves)\n"
+    "\n"
+    "Legacy form (still accepted): check-credentials <data-dir>\n"
+)
+
+
+def _check_credentials_command(argv: list[str]) -> int:
+    """Verify every configured target resolves to a named credential. Exit 1 if any does not.
+
+    A credential is required, never inferred (see
+    :func:`db_ops.common.data_sources.find_database_credential`), so a config edit that drops
+    ``default_credential_name`` / ``credential_name`` now stops that target instead of quietly
+    connecting as whatever entry happened to come first. Run this after editing
+    ``db_instances.json`` / ``users.json`` / ``sql_targets.json`` and before a deploy.
+    """
+    from db_ops.common import data_sources
+    from db_ops.common.cli import _optional_json_request
+    from db_ops.metrics import targets as metric_targets
+    from db_ops.telegram import sql_commands
+
+    # The request parser stays in `common`: one JSON-object contract for the whole tool, not a
+    # second one here that would drift on `@file` or stdin handling.
+    request, code = _optional_json_request(argv, CHECK_CREDENTIALS_USAGE)
+    if request is None and code:
+        return code
+    requested_dir = str((request or {}).get("data_dir") or "") if request is not None else (argv[0] if argv else "")
+
+    # load_metric_targets needs a concrete folder; default to the one data_sources resolves.
+    data_dir = Path(requested_dir) if requested_dir else data_sources.users_path().parent
+    problems: list[str] = []
+    checked = 0
+
+    for target in metric_targets.load_metric_targets(data_dir=data_dir):
+        # Host-only entries (no db_type) and API-bridge targets carry no DB login by design.
+        if not target.db_type:
+            continue
+        if str((target.sql_access or {}).get("method") or "direct").lower() == "api":
+            continue
+        checked += 1
+        if not target.credential:
+            problems.append(
+                f"metrics target {target.target_id}: no credential "
+                f"(default_credential_name={target.credential_name or '<unset>'})"
+            )
+
+    groups = data_sources.load_all_credentials(data_dir)
+    targets_file = data_dir / "sql_targets.json"
+    if targets_file.exists():
+        entries = json.loads(targets_file.read_bytes().decode("utf-8-sig")).get("sql_targets", [])
+        for entry in entries:
+            if str(entry.get("active", 1)) in ("0", "false", "False"):
+                continue
+            checked += 1
+            db_type = str(entry.get("db_type") or "").lower()
+            try:
+                data_sources.find_database_credential(
+                    groups.get(db_type, []),
+                    server_id=str(entry.get("server_id") or ""),
+                    credential_name=str(entry.get("credential_name") or ""),
+                    db_type=db_type,
+                    service_name=str(entry.get("service_name") or ""),
+                    instance_name=str(entry.get("instance_name") or ""),
+                )
+            except data_sources.CredentialNotFound as exc:
+                problems.append(f"sql target {entry.get('sql_id')}/{entry.get('target_no')}: {exc}")
+
+    commands_file = data_dir / "telegram_support_commands.json"
+    if commands_file.exists():
+        commands = json.loads(commands_file.read_bytes().decode("utf-8-sig"))
+        for command in commands.get("telegram_support_commands", []):
+            if str(command.get("action_type")) != "sql_execute":
+                continue
+            checked += 1
+            try:
+                sql_commands.find_credential(command.get("action_config") or {})
+            except Exception as exc:  # noqa: BLE001 - report, do not abort the whole check.
+                problems.append(f"telegram command {command.get('command_text')}: {exc}")
+
+    # The answer, in the one response shape (2026-08-16). This command used to put its *finding*
+    # in the exit code and its detail on **stderr** — the precise split `lib/response.py`'s own
+    # docstring forbids, and it made this one of two commands in the tree a program could not
+    # consume at all. `success` is now "the check ran"; whether anything is wrong is
+    # `data.problems`, which is a fact about the estate rather than about this process.
+    from db_ops.lib import response
+
+    summary = f"checked {checked} target(s); {len(problems)} without a resolvable credential"
+    if str((request or {}).get("format") or "json").strip().lower() == "txt":
+        for problem in problems:
+            print(problem, file=sys.stderr)
+        print(summary)
+        return 1 if problems else 0
+    response.emit(response.ok(
+        "check-credentials", message=summary,
+        data={"checked": checked, "problems": problems},
+        metrics={"checked": checked, "problem_count": len(problems)},
+    ))
+    # The exit code still says "something is unresolvable", because a runbook and a scheduled
+    # caller both check `$?` — and it agrees with the response rather than replacing it.
+    return 1 if problems else 0
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="DB Ops logging and Telegram alert test.")
+    parser.add_argument("--config", default=str(DEFAULT_CONFIG_PATH), help="Path to config JSON.")
+    parser.add_argument("--level", default="logging", help="logging, warning, or error.")
+    parser.add_argument("--message", default="", help="Message to log and optionally alert.")
+    parser.add_argument("--job-code", default="", help="When set, also insert this event into SQLite job_runs.")
+    parser.add_argument("--status", default="done", help="Job status for SQLite job_runs.")
+    parser.add_argument("--duration-ms", type=int, default=None, help="Job duration in milliseconds.")
+    parser.add_argument("--error-text", default=None, help="Error text for SQLite job_runs.")
+    parser.add_argument("--recent", type=int, default=0, help="Print recent SQLite job_runs and exit.")
+    parser.add_argument("--export-sqlite-schema", action="store_true", help="Export SQLite schema JSON documentation and exit.")
+    parser.add_argument("--schema-output-dir", default="runtime", help="Output directory for SQLite structure JSON.")
+    return parser.parse_args(argv)
+
+
+#: Every app, by the name someone types. The value is the module holding that app's ``main`` —
+#: imported only when it is asked for, which is what lets ``--help`` and ``--version`` work on an
+#: install with no database driver at all. Importing all twelve up front would make the help text
+#: depend on having pyodbc.
+APPS: dict[str, str] = {
+    "metrics": "db_ops.metrics.cli",
+    "reports": "db_ops.reports.cli",
+    "telegram": "db_ops.telegram.cli",
+    "sla": "db_ops.sla.cli",
+    "backup-restore": "db_ops.backup_restore.cli",
+    "sql-tasks": "db_ops.sql_tasks.cli",
+    "sre": "db_ops.sre.cli",
+    "control": "db_ops.control.cli",
+    "webhost": "db_ops.webhost.cli",
+    "db": "db_ops.db.cli",
+    "common": "db_ops.common.cli",
+    "daemon": "db_ops.jobs.daemon",
+}
+
+
+INIT_USAGE = (
+    "usage: db-ops init [<directory>] [--force] [--app-name NAME]\n"
+    "\n"
+    "Turn a directory into a working tool root. Defaults to the current one.\n"
+    "\n"
+    "Writes the smallest tree that runs: config.json, a SQLite store declaration, an empty\n"
+    "inventory, a starter metric catalogue, and the Telegram and secret files, each carrying\n"
+    "notes that say what to put in it. Nothing is overwritten without --force, because the\n"
+    "files this writes are the ones you edit next.\n"
+    "\n"
+    "The store starts on SQLite in runtime/ - a first run has no PostgreSQL, and needing one\n"
+    "to hold the results of monitoring is a poor first request. data/store_config.json is\n"
+    "where you move to PostgreSQL later.\n"
+)
+
+
+def _init_command(argv: list[str]) -> int:
+    """``init`` — the first command anybody runs, and until 2026-08-22 it did not exist.
+
+    Measured on a real `pip install` into a clean virtualenv: from an empty directory the toolkit
+    resolved its configuration to `site-packages` and told the reader to create a file there from
+    an example that does not ship. Installable and unstartable.
+    """
+    from pathlib import Path
+
+    from db_ops import scaffold
+
+    target = "."
+    app_name = "dbabrain"
+    force = False
+    rest = list(argv)
+    while rest:
+        token = rest.pop(0)
+        if token in {"-h", "--help"}:
+            print(INIT_USAGE)
+            return 0
+        if token == "--force":
+            force = True
+        elif token == "--app-name":
+            app_name = rest.pop(0) if rest else app_name
+        elif token.startswith("-"):
+            print(f"init: unknown option {token}\n\n{INIT_USAGE}", file=sys.stderr)
+            return 2
+        else:
+            target = token
+
+    try:
+        result = scaffold.initialise(Path(target), app_name=app_name, force=force)
+    except scaffold.ScaffoldError as exc:
+        print(f"init refused: {exc}", file=sys.stderr)
+        return 1
+
+    for name in result.written:
+        print(f"  created  {name}")
+    for name in result.skipped:
+        print(f"  kept     {name} (already there; --force overwrites)")
+    print("")
+    print(scaffold.next_steps(result.root))
+    return 0
+
+
+ENCRYPT_SECRET_USAGE = (
+    "usage: db-ops encrypt-secret [--source PATH] [--dest PATH] --key-base64 B64 | --key TEXT\n"
+    "\n"
+    "Encrypt secrets/secret_text.json into data/encrypted_secret_text.json, which is the file\n"
+    "the toolkit actually reads. The plaintext source is never read at run time and must never\n"
+    "be committed.\n"
+    "\n"
+    "Run it again after every edit to the plaintext file - adding a secret does nothing until\n"
+    "it is encrypted.\n"
+    "\n"
+    "Keep the passphrase. Nothing else can decrypt the store, and there is no recovery.\n"
+)
+
+
+def _encrypt_secret_command(argv: list[str]) -> int:
+    """``encrypt-secret`` — turn the plaintext secret source into the store the toolkit reads.
+
+    This lived only in ``db_ops.control.cli`` until 2026-08-22, and `control` is master-side deploy
+    tooling that the public distribution does not ship. So the first-run instructions named a
+    command that did not exist in the distribution they were written for — found by running the
+    documented steps against a real SQL Server rather than by reading them.
+
+    It belongs here on two counts: every install needs it, and it is the secret *store*, which
+    ships, rather than the deploy tooling, which does not.
+    """
+    from pathlib import Path
+
+    from db_ops.lib.paths import TOOL_ROOT
+    from db_ops.lib.secret_text import encrypt_secret_text_file, resolve_cli_key
+
+    source = Path(TOOL_ROOT) / "secrets" / "secret_text.json"
+    dest = Path(TOOL_ROOT) / "data" / "encrypted_secret_text.json"
+    key = key_base64 = None
+    rest = list(argv)
+    while rest:
+        token = rest.pop(0)
+        if token in {"-h", "--help"}:
+            print(ENCRYPT_SECRET_USAGE)
+            return 0
+        if token == "--source":
+            source = Path(rest.pop(0)) if rest else source
+        elif token == "--dest":
+            dest = Path(rest.pop(0)) if rest else dest
+        elif token == "--key":
+            key = rest.pop(0) if rest else None
+        elif token in {"--key-base64", "--key_base64"}:
+            key_base64 = rest.pop(0) if rest else None
+        else:
+            print(f"encrypt-secret: unknown option {token}", file=sys.stderr)
+            print("", file=sys.stderr)
+            print(ENCRYPT_SECRET_USAGE, file=sys.stderr)
+            return 2
+
+    try:
+        resolved = resolve_cli_key(key, key_base64)
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    resolved = resolved or os.environ.get("DB_OPS_SECRET_KEY", "").strip()
+    if not resolved:
+        # Refuse rather than guess. Encrypting with the wrong passphrase produces a store that
+        # decrypts nowhere, and the round-trip check inside encrypt_secret_text_file cannot catch
+        # it, because it verifies against the same key it just used.
+        print("ERROR: no passphrase. Pass --key-base64 or --key, or set DB_OPS_SECRET_KEY.",
+              file=sys.stderr)
+        return 2
+
+    if not source.exists():
+        print(f"ERROR: {source} not found. `db-ops init` creates it.", file=sys.stderr)
+        return 1
+    try:
+        count = encrypt_secret_text_file(source, dest, resolved)
+    except Exception as exc:  # noqa: BLE001 - CLI failure path.
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+    print(f"Encrypted {count} secret(s) -> {dest}")
+    return 0
+
+
+def installed_apps() -> dict[str, str]:
+    """The entries of :data:`APPS` this installation actually has.
+
+    `v0.1.0` of the public distribution ships seven of the fourteen components
+    (:mod:`db_ops.lib.distribution`), so on an installed copy this table would otherwise advertise
+    seven commands that raise `ModuleNotFoundError` the moment somebody runs the line the help text
+    just offered them. Measured, not predicted: the first thin wheel built on 2026-08-22 listed all
+    twelve apps and could run five.
+
+    Detected rather than hardcoded, so one code path is right in both trees — the full checkout
+    lists twelve and the thin wheel lists five, and neither needs to know which it is.
+
+    `find_spec` **locates** a module without executing it, which is what keeps the dispatch lazy:
+    importing twelve apps to print a help message would make `--help` depend on having an ODBC
+    driver, so a slim install would crash while explaining how to use the tool.
+    """
+    import importlib.util
+
+    present: dict[str, str] = {}
+    for name, module in APPS.items():
+        try:
+            if importlib.util.find_spec(module) is not None:
+                present[name] = module
+        except (ImportError, ValueError):
+            # A parent package that is not installed raises rather than returning None.
+            continue
+    return present
+
+
+def _usage() -> str:
+    from db_ops import __version__
+
+    apps = installed_apps() or APPS
+    width = max(len(name) for name in apps)
+    lines = [
+        # ASCII only: this prints to whatever console the operator has, and the Windows one is
+        # cp1252. An em dash there arrives as a question mark at best.
+        f"db_ops {__version__} - database operations toolkit",
+        "",
+        "usage: db-ops <app> [args...]",
+        "",
+        "apps:",
+    ]
+    lines += [f"  {name.ljust(width)}  python -m {module}" for name, module in sorted(apps.items())]
+    lines += [
+        "",
+        "  init                   create a tool root here: config, a SQLite store, empty inventory",
+        "  encrypt-secret         encrypt secrets/secret_text.json into the store the tool reads",
+        "  check-credentials      does every configured target resolve to a real login",
+        "",
+        "Each app takes its own arguments; ask it directly, e.g. `db-ops metrics --help`.",
+        "Every app is also runnable as `python -m <module>`, which is what the daemon does.",
+    ]
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Dispatch to an app, or answer for the toolkit itself.
+
+    A console script is called with no arguments, so ``argv`` defaults to the real ones; the tests
+    pass a list instead, which is why it is a parameter at all.
+
+    Routing only. Every app owns its own parser and its own ``main``, and this must stay a lookup
+    — the moment it starts interpreting an app's arguments there are two parsers for one command
+    and they disagree the first time one of them changes.
+    """
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(_usage())
+        return 0
+    if argv[0] in ("-V", "--version"):
+        from db_ops import __version__
+
+        print(__version__)
+        return 0
+
+    # Underscores are what the module names use and what a reader may well type.
+    app = argv[0].replace("_", "-")
+    if app in APPS:
+        import importlib
+
+        # A name this build does not ship gets a sentence, not a traceback. `ModuleNotFoundError:
+        # db_ops.sre.cli` tells a reader their install is broken; it is not, and the difference
+        # matters because the next thing they do is reinstall.
+        #
+        # Asked through `installed_apps()` rather than with a bare `find_spec`, which *raises*
+        # `ModuleNotFoundError` when the parent package is the missing one — so checking for a
+        # missing app with it produced exactly the traceback this branch exists to prevent.
+        present = installed_apps()
+        if app not in present:
+            print(
+                f"db-ops: '{app}' is not in this build.\n"
+                f"This distribution ships: {', '.join(sorted(present))}.\n"
+                "The rest of the toolkit arrives in a later release.",
+                file=sys.stderr,
+            )
+            return 2
+        return int(importlib.import_module(present[app]).main(argv[1:]) or 0)
+
+    # `init` is deliberately first among the words: it is the only command that works before a
+    # tool root exists, so it must not be reachable only after one does.
+    if argv[0] == "init":
+        return _init_command(argv[1:])
+
+    if argv[0] in {"encrypt-secret", "encrypt-secret-text"}:
+        return _encrypt_secret_command(argv[1:])
+
+    # Subcommand first, flags second. `check-credentials` is a word, and every other form this
+    # entry point takes starts with `--`, so the two cannot be confused for one another.
+    if argv[0] == "check-credentials":
+        return _check_credentials_command(argv[1:])
+
+    if not argv[0].startswith("-"):
+        print(f"db-ops: unknown app {argv[0]!r}\n", file=sys.stderr)
+        print(_usage(), file=sys.stderr)
+        return 2
+
+    args = parse_args(argv)
+    logger = None
+    try:
+        level = normalize_level(args.level)
+        config = load_config(args.config)
+        patch_stdout(config.log_dir / "db_ops_runtime.log", app_name=config.app_name)
+        logger = setup_app_logger(config, enable_telegram_alerts=not (args.export_sqlite_schema or args.recent))
+        store = DbOpsStore.from_config(config)
+        if args.export_sqlite_schema:
+            log_function_call(logger, function_name="db.export_sqlite_schema")
+            result = export_sqlite_schema(sqlite_path=config.sqlite_path, output_dir=args.schema_output_dir)
+            print(result)
+            return 0
+        if args.recent:
+            log_function_call(logger, function_name="db.fetch_recent_job_runs")
+            for row in store.fetch_recent_job_runs(args.recent):
+                print(
+                    f"{row['log_id']} | {row['created_at']} | {row['job_code']} | "
+                    f"{row['level']} | {row['status']} | {row['message']}"
+                )
+            return 0
+
+        if not args.message:
+            raise ValueError("--message is required unless --recent is used.")
+
+        log_function_call(logger, function_name="logging_ops.log_event", text=args.message)
+        log_event(logger, level=level, message=args.message)
+        if args.job_code:
+            log_function_call(logger, function_name="db.insert_job_run", text=args.job_code)
+            log_id = store.insert_job_run(
+                JobRun(
+                    job_code=args.job_code,
+                    level=level,
+                    status=args.status,
+                    message=args.message,
+                    duration_ms=args.duration_ms,
+                    error_text=args.error_text,
+                    host_name=socket.gethostname(),
+                )
+            )
+            print(f"SQLite job_runs inserted: {log_id}")
+    except Exception as exc:  # noqa: BLE001 - command-line failure path.
+        if logger:
+            log_function_error(logger, function_name="db_ops.cli", error_text=str(exc))
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

db_ops/common/__init__.py

@@ -0,0 +1 @@
+"""App-neutral shared utilities for db_ops components."""

db_ops/common/backup/__init__.py

@@ -0,0 +1,129 @@
+"""Running one backup: ship the script to where the database lives, and judge the result honestly.
+
+The judging is the part with history behind it. ``exit 0`` means the shell finished, not that a
+backup happened — a script fed to ``bash -s`` can end early with a clean status and no output, and
+one did: a ``docker exec -i`` inside it read the rest of the script as its own stdin, so the shell
+ran out of work and reported success having backed up nothing. A backup that lies about succeeding
+is worse than one that fails, because the failure is only discovered by the restore that needed it.
+
+So every script ends by printing ``RESULT=ok``, and success here means **that receipt was seen**.
+Exit 0 without it is reported as an error naming exactly that, which is a sentence an operator can
+act on rather than a silent green run.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from db_ops.common.backup.spec import (
+    BACKUP_LEVEL_BY_ENGINE,
+    LEVEL_ENV,
+    RECEIPT,
+    BackupSpec,
+    BackupSpecError,
+    backup_level_for,
+    parse_backup_spec,
+)
+from db_ops.common.hostcmd import HostCommandError, run_script
+
+__all__ = [
+    "BACKUP_LEVEL_BY_ENGINE",
+    "LEVEL_ENV",
+    "RECEIPT",
+    "BackupSpec",
+    "BackupSpecError",
+    "backup_level_for",
+    "parse_backup_spec",
+    "plan_backup",
+    "run_backup",
+]
+
+#: How much of a script's output is worth carrying in an error. Enough to see what the engine said,
+#: bounded because this ends up in a Telegram message and a store row.
+EXCERPT = 2000
+
+
+def plan_backup(spec: BackupSpec) -> dict[str, Any]:
+    """What the run would do, without doing it. Also the dry-run answer.
+
+    Env **names** but never values: the whole point of the plan is that it can be shown to somebody,
+    and half of these are passphrases.
+    """
+    return {
+        "db_type": spec.db_type,
+        "label": spec.label,
+        "level": spec.level or "(the script decides)",
+        "script": spec.script_source,
+        "script_lines": len(spec.script.splitlines()),
+        "host": spec.host.host or "(this machine)",
+        "runtime": spec.host.runtime,
+        "container": spec.host.container,
+        "env_names": sorted(spec.env),
+        "timeout": spec.timeout,
+        "server_metadata": dict(spec.server_metadata) or None,
+    }
+
+
+def run_backup(spec: BackupSpec) -> dict[str, Any]:
+    """Run the backup and return what happened. Never raises for a backup that merely failed."""
+    planned = plan_backup(spec)
+    started = time.monotonic()
+    try:
+        result = run_script(spec.host, spec.script, env=spec.env, timeout=spec.timeout)
+    except HostCommandError as exc:
+        # Could not run at all - a host that refused the connection. Distinct from a backup that
+        # ran and failed, because the fix is somewhere else entirely.
+        return {**planned, "status": "error", "exit_code": None, "duration_ms": _ms(started),
+                "stdout": "", "stderr": "", "error": str(exc), "receipt": False}
+
+    out = result.get("stdout") or ""
+    err = result.get("stderr") or ""
+    exit_code = result.get("exit_code")
+    receipt = RECEIPT in out
+    status = "done" if exit_code == 0 and receipt else "error"
+
+    if status == "done":
+        error = None
+    elif exit_code == 0 and not receipt:
+        error = (
+            f"Backup script exited 0 without printing {RECEIPT} - it did not run to completion. "
+            f"stdout={out.strip()[-800:]!r} stderr={err.strip()[-800:]!r}"
+        )
+    else:
+        error = (err.strip() or out.strip())[-EXCERPT:] or f"exit {exit_code}"
+
+    result = {**planned, "status": status, "exit_code": exit_code, "duration_ms": _ms(started),
+              "stdout": out, "stderr": err, "error": error, "receipt": receipt}
+    if spec.server_metadata:
+        result["server_metadata_result"] = _export_server_metadata(spec, backup_ok=status == "done")
+    return result
+
+
+def _export_server_metadata(spec: BackupSpec, *, backup_ok: bool) -> dict[str, Any]:
+    """Export the instance's server-level metadata beside the backup. Read-only, and never fatal.
+
+    **A failure here does not fail the backup.** The data is the thing that must not be lost, and
+    losing it to a metadata step that could not read ``sys.credentials`` would be absurd — the
+    result is reported alongside so the gap is visible without being destructive.
+
+    Skipped when the backup itself failed: a bundle describing an instance whose backup did not
+    complete is a set of files that look like a matched pair and are not.
+    """
+    if not backup_ok:
+        return {"ok": False, "skipped": True,
+                "error": "backup did not complete; no metadata exported"}
+    from db_ops.common import sqlserver_instance
+
+    request = {"target": spec.server_metadata["target"],
+               "output_dir": spec.server_metadata["output_dir"]}
+    if spec.server_metadata.get("include"):
+        request["include"] = spec.server_metadata["include"]
+    try:
+        return sqlserver_instance.export_instance(request)
+    except Exception as exc:  # noqa: BLE001 - reported next to the backup, never fatal to it.
+        return {"ok": False, "error": str(exc), "operation": "sqlserver-export-instance"}
+
+
+def _ms(started: float) -> int:
+    return int((time.monotonic() - started) * 1000)