Smartstack: add lifecycle telemetry and the final architecture guide

[timbeccue]

Summary

This is PR 8 of 8 completing the v1 banzai implementation of Smartstacking at site.

PR1 (#469): combine math
PR2 (#470): JPEG utilities
PR3 (#471): DB updates
PR4 (#473): shipper contract
PR5 (#474): smartstack data products
PR6 (#475): stack worker polling
PR7 (#476): e2e tests, compose cleanup
PR8 (#477): logging      <-- you are here

PR1 combine math ───────┐
PR2 JPEG utilities ─────┤
PR3 DB updates ─────────┼──> PR5 data products --> PR6 stack workers --> PR7 E2E --> PR8 logs/docs
PR4 shipper contract ───┘

PRs 1–4 provide the independent foundations for combining images, rendering JPEGs, storing stack state, and shipper integration (this PR). PR5 builds the data products, this PR adds the polling worker, crash-only supervisor, and site deployment configuration. PR7 adds E2E and recovery proof; PR8 (this one) adds structured lifecycle telemetry and final documentation.

Structured lifecycle events

Smartstack logs now use a consistent smartstack_* namespace and can be grouped by smartstack_moluid:

Event	Emitted when
created	The first accepted member creates the parent stack
frame_reduced	A reduced member is accepted
finalize_failed	Product generation or publication fails after an attempt is claimed
terminal	A stack reaches complete, timeout, or exhausted-attempt error
frame_ignored	A late member is rejected by a timeout tombstone

Events include the relevant camera, stack number or filepath, lifecycle status, target status, and claimed attempt number. Successful previews remain debug-level messages rather than lifecycle events.

Unit tests pin the complete structured tag dictionaries for creation, accepted and ignored members, successful terminal transitions, failed attempts, and exhausted-attempt errors.

Site log shipping

The three Smartstack services opt into the existing site log pipeline:

• banzai-stackframe-listener
• banzai-stackframe-worker
• banzai-stacking-supervisor

Each receives the gtn.lco.logstash: "yes" label and TZ=UTC.

Documentation

docs/smartstacking_architecture.md is rewritten as the final code-oriented system map, covering:

• PostgreSQL control-plane and shared-file data-plane responsibilities.
• Ingestion, polling, products, and shipper flow.
• Lifecycle, timeout-tombstone, retry, and retention behavior.
• Product naming, metadata, and at-least-once delivery.
• Process recovery, operational settings, and code ownership.