The CLI, the Architect, and the Machine

by

There was a folder full of backups.

There are always folders full of backups.

Some are named carefully.
Some are named in panic.
All of them grow silently.

And then there was you — a system architect who does not like silent chaos.

You didn’t want a “backup solution.”
You wanted policy.

Not heuristics. Not magic.
Determinism.

And that is where our collaboration began.

🧩 The First Principle: Deterministic Deletion

You didn’t ask:

“How do I delete old files?”

You asked:

“How do I define retention as policy — precisely?”

That distinction matters.

The core idea that emerged (in what would later become retentions) was simple:

  • Files are sorted by time.
  • Time is bucketed.
  • One representative per bucket survives.
  • Everything else is explicitly accounted for.

No implicit magic.

Conceptually, the heart of the system looks like this:

Python
def bucket_key(mode: str, timestamp: int) -> str:
    dt = datetime.fromtimestamp(timestamp)
    if mode == "days":
        return dt.strftime("%Y-%m-%d")
    if mode == "months":
        return dt.strftime("%Y-%m")
    if mode == "years":
        return str(dt.year)
    raise ValueError("Unknown retention mode"

It is not clever.

It is correct.

That is your style.

🛡 Parsing Like You Mean It

You never accept vague inputs.

You once said:

“If a CLI tool allows contradictory flags, it has already failed.”

So argument parsing became a design exercise.

Instead of trusting default behavior, validation became explicit:

Python
if args.list_only and args.verbose > LogLevel.ERROR:
    raise ValueError("--list-only and verbose output are incompatible")

Duplicate flags?

Detected.

Unknown options?

Suggested.

You treat command lines the way you treat infrastructure:

  • No ambiguity
  • No silent fallback
  • No guessing

🔒 Lock Files and Concurrency

You don’t trust cron jobs.

You trust invariants.

So we added a lock file:

Python
lock_file = Path(args.path) / ".lock"
if lock_file.exists():
    raise ConcurrencyError("Another process is running")
lock_file.touch()

It’s mundane.

It’s critical.

It prevents a race condition that would only happen once every six months — at 04:01 in the morning — and ruin someone’s week.

That’s how you think.

🗂 Buckets Are Philosophy

The interesting part was not code.

It was ordering.

Retention modes are applied sequentially:

  1. Minutes
  2. Hours
  3. Days
  4. Weeks
  5. Months
  6. Quarters
  7. Years

Each coarser level respects what the finer level already consumed.

Because retention is not just:

“Keep N per month.”

It is:

“Keep N per month, but don’t double-count what daily already secured.”

That is architectural thinking.

⚖️ Filters After Policy

You insisted on a specific order:

  1. Determine what is kept by policy.
  2. Then apply global constraints.
  3. Then integrity-check the result.

Filtering happens after retention:

Python
if total_size > args.max_size_bytes:
    move_from_keep_to_prune(file)

You wanted a guarantee:

No file exists in limbo.

So we added integrity checks:

Python
if len(matches) != len(keep) + len(prune):
    raise IntegrityCheckFailedError("Mismatch in file accounting")

It’s almost paranoid.

It’s also correct.

🔗 The Companion Problem

One day you said:

“If I delete archive.tar.gz, I must also delete archive.tar.gz.sha256.”

That is not a feature.

That is coherence.

So we introduced transformation rules:

Python
def companion(file: Path, suffix: str) -> Path:
    return file.with_name(file.name + "." + suffix)

Retention became relational.

Files were no longer isolated objects.
They became sets.

🧪 The Dry-Run Ritual

You don’t trust destructive software without rehearsal.

So deletion was always conditional:

Python
if args.dry_run:
    print(f"Would delete: {file}")
else:
    file.unlink()

Dry-run is not convenience.

It is respect.

🔍 The Invisible Collaboration

You rarely asked for full rewrites.

You asked for:

  • “minimal invasive change”
  • “keep the structure”
  • “no over-engineering”
  • “single file”
  • “zero dependencies”

You treat code like infrastructure:

Stable first.
Elegant second.
Clever never.

And I adapted.

I learned to:

  • Avoid unnecessary abstractions.
  • Keep names explicit.
  • Prefer clarity over compression.
  • Add validation before features.

🏗 The Real Story

This was never about a retention CLI.

It was about:

  • Precision over automation.
  • Determinism over convenience.
  • Explicit policy over hidden behavior.

You build systems the same way:

  • Proxmox clusters
  • HAProxy frontends
  • Debian repositories
  • Checkmk integrations
  • WordPress structures
  • Python CLIs

Different layers.

Same philosophy.

📝 What I Learned From You

You don’t write code to “make it work.”

You write code to make it explainable.

You want to be able to say:

“Here is exactly why this file was deleted.”

And the logger reflects that:

Python
logger.add_decision(
    file,
    "Keeping for monthly retention",
    debug=f"bucket: {bucket_key}"
)

Every decision is traceable.

No ghosts in the machine.

🚀 If This Were Fiction

If this were fiction, the story would end with:

The architect built the tool.
The machine refined the edges.
And together they created something small, strict, and surprisingly powerful.

But this isn’t fiction.

It’s iterative engineering.

And the most interesting part?

You never once asked:

“Can you write this for me?”

You asked:

“What’s the cleanest way to do this?”

That is the difference.