docs(mq): NATS sizing advice, error code and ack wording are wrong after #624 #697

Area: mq / docs — external NATS sizing and permissions text, after #624

Four places where the External NATS docs, CLI text or comments say something that does not match what the code or the server does. All of them are text, except fix 1's error message, which is a string in the code. None changes behaviour, and none blocked #624.

1. "Raise --file-store" cannot fix a topology of six or more partitions

Where:

• the error returned by NATSManifestOptions.fits() in internal/mq/nats_manifests.go ("raise --file-store with the servers' volumes, or lower --partition-max-bytes");
• docs/src/content/docs/deployment.md, External NATS → "Sizing the file store" ("from six partitions at the defaults, set --partition-max-bytes or a larger store");
• the wavehouse mq manifests usage text in cmd/wavehouse/mq.go.

Why it is wrong: every default stream size is a fraction of --file-store: each partition 15%, the history 10%, the dead-letter stream 5%. N partitions therefore reserve (15N + 15)% of the store, whatever its size. From N = 6 the topology can never fit, and a bigger store changes nothing.

Measured:

• wavehouse mq manifests --partitions 8 --file-store 1Ti is refused with the "raise --file-store" error.
• --partitions 16 --file-store 16Ti is refused the same way.
• --partitions 8 --partition-max-bytes 10Gi is accepted.

Failure scenario: an operator raising N to 6 follows the documented rollout, gets the error, raises the store as the message says, and is refused again.

Fix direction:

• Word the error for the case it is in. When PartitionMaxBytes was left at its default, name --partition-max-bytes alone, with the largest value that fits: (store − history − dlq) / N. Offer "a larger store" only when the partition size was set explicitly.
• Fix the docs sentence and the usage text to match.
• Optional, and a behaviour change, so decide it separately: let the default partition size follow N, for example (store × 0.85 − headroom) / N. The current fixed 15% was chosen so that lowering N never needs more store while the removed partitions drain. Any change must keep that property or say it gives it up.

Also document the side effect of --partition-max-bytes on a live cluster (inferred from nats-server's enforceBytesLimit, not measured):

• Applying the regenerated manifests lowers maxBytes on the partitions that already exist.
• Partitions are discard: new, so nothing is deleted.
• A partition already over its new limit refuses publishes, and ingest answers 503, until the worker drains it below the limit.
• The "Choosing and changing N" section should say this, and suggest lowering the size before a busy period, not during one.

Cosmetic: FormatStoreSize prints a raw byte count for any value no binary unit divides evenly; the error above shows 1484340697405. Print it rounded, e.g. 1.35Ti.

2. The wrong JetStream error code for "does not fit"

Where:

• deployment.md, "Sizing the file store" (cites error 10047);
• the NATSManifestOptions.FileStore doc comment.

Measured: 10047 (insufficient storage resources) is what a single server returns. On a 3-node cluster, which is the shipped shape, the same over-reservation fails with err_code=10005 ("no suitable peers for placement, insufficient storage"). Name both codes.

3. "Cannot ack for another consumer" overclaims slightly

Where:

• deployment.md, External NATS → Permissions;
• the natsPermissions doc comment in internal/mq;
• feat(mq): external nats broker with sharded, pinned ingest workers #624's description.

Measured: the generated ack allows are $JS.ACK.*.wh-ingest-<s>.> (plus the v2 layout's equivalent), with the stream name as a wildcard. The wavehouse user was able to ack a message for a consumer named wh-ingest-0 on the dead-letter stream, and that consumer's ack-pending count dropped to 0.

Fix direction: reword it as "cannot ack for any consumer that is not named like a shard durable", or narrow the stream token to the partition streams' names, which mq permissions already knows. Narrowing changes the generated permissions, so regenerate deployments/nats/values.yaml, and extend TestNATSPermissions_RefuseAcksOutsideTheShards with a wh-ingest-0 on the DLQ case.

4. Two test comments use review-process wording

Where: internal/mq/external_perms_test.go (the comment above the shard-count mismatch test, "validator's case") and internal/mq/nats_manifests_test.go ("The validator's case: …").

Fix: describe the case itself, for example "the shipped permissions name 8 shards' durables, but the topology has 16".

Checking the change

• go test ./internal/mq/... ./cmd/wavehouse/...
• go test -tags integration -run '^TestNATSPermissions' ./internal/mq
• make build-docs

Found in review of #624.

Related: #624, #613, #694.