add warn on dnssd name collision change spec

openspec/changes/warn-on-dnssd-name-collisions/proposal.md

@@ -0,0 +1,59 @@
+# Proposal
+
+## Why
+
+On the live deployment (`podp`), two queues ended up with the identical CUPS
+Description, so both derived the same DNS-SD instance name
+(`"<Description> @ <host>"`). Avahi can register only one of them and CUPS 2.4
+never resolves the collision (upstream `scheduler/dnssd.c` still has
+`/* TODO: Handle collisions with avahi_alternate_service_name */`), so one queue
+showed `printer-is-shared=true` but was never advertised. macOS pins the exact
+instance name into the queue's `dnssd://` device URI; when the pinned name stops
+being announced, the Mac reports the printer **offline**. Because the collision
+is deterministic, container restarts never helped and only remove/re-add on the
+client fixed it — hours of debugging with no server-side signal pointing at the
+cause.
+
+## What Changes
+
+- **`entrypoint.sh`**: after cupsd is up, derive the DNS-SD instance name of
+  every shared queue (`Description` if set, otherwise the queue name, plus
+  `@ <host>`) and log a prominent, non-fatal warning when two or more queues
+  derive the same instance name — naming the affected queues and the fix
+  (give each queue a unique Description, or delete the redundant queue).
+- **`README.md`**: new Troubleshooting entry "macOS shows the printer offline
+  after some time" documenting the symptom, root cause (client-side instance
+  name pinning + duplicate-Description collision), verification commands
+  (`dns-sd -B`, `lpstat -l -p`, `ipptool`), and the fix including the
+  remove/re-add step on macOS.
+- **Docs correction**: the `PRINTER_NAME` description in the `entrypoint.sh`
+  header and in the README currently claims it is the "advertised (DNS-SD)
+  name" — that is only true while no Description is set; the Description
+  overrides it. Correct both places, and clarify the matching requirement in
+  the `printserver/cups` spec (same claim).
+
+Out of scope: changing how queues are configured (no automatic renaming or
+de-duplication), and avoiding the `lpadmin` re-registration churn on restart.
+
+## Capabilities
+
+### New Capabilities
+
+(none)
+
+### Modified Capabilities
+
+- `printserver/cups`: adds a requirement that the container detects DNS-SD
+  instance-name collisions between shared queues at startup and reports them in
+  the container log, so a queue that silently loses its advertisement is visible
+  to the operator instead of surfacing as an "offline" client hours later.
+
+## Impact
+
+- `entrypoint.sh` — one additional startup diagnostic block (log output only;
+  no change to queue creation, advertisement, or exit behaviour).
+- `README.md` — one new Troubleshooting section; correction of the
+  `PRINTER_NAME` wording.
+- No changes to `cupsd.conf`, the `Containerfile`, or runtime behaviour seen by
+  clients; the fix for an existing collision is still a manual operator action
+  (documented in the README).