feat(output-mapping): AJDA-2946 store description only when table flag is system-managed

[zajca]

Resolves AJDA-2946.

Why

Until now output mapping stored the description as KBC.description metadata and had no way to tell whether it may touch the description at all — writing it on every run would silently overwrite a description a user had set in the UI.

DMD-1662 (connection #7754) added the table-level isDescriptionSystemManaged flag exactly for this decision. This PR makes output mapping act on it and store the description in the native first-class description field, which is what Input Mapping now reads primarily (AJDA-2714).

This supersedes #525, which solved the same problem by guessing from the presence of a user provider KBC.description row. The flag replaces the heuristic.

Behaviour

Situation	Where	What happens
Table is created by this run	LoadTableQueue::waitForAll(), after a successful load	description is stored — a fresh table is system-managed by the Storage default
Table already existed	StoragePreparer, before the load	description is stored only when isDescriptionSystemManaged is true; otherwise it is discarded and an info message is logged

Both paths go through one flag-gated entry point (TableDescriptionModifier::updateDescriptions()) taking the table detail, so the guard cannot be bypassed on either.

Only real changes are sent: the current descriptions are read from the table definition and compared with what the configuration produced. When nothing changed, no API call is made at all — so a steady-state run costs zero extra calls.

Descriptions of newly created tables are applied after the load rather than embedded in the createTableDefinition payload. That is deliberate for two reasons: it is the only way to also cover tables output mapping does not create through a table definition (untyped tables, and tables with neither a manifest nor columns, created by the load job itself), and embedding would break FailedLoadTableDecider::decideTableDelete() — a description supplied at create time makes Storage write a metadata row immediately, so count($metadata) === 0 would no longer hold and empty tables would stop being dropped after a failed import.

KBC.description is no longer written as component metadata

Writing the native description makes Storage mirror it into a KBC.description metadata row under the storage provider — for the table and for every column (TableDefinitionUpdateService::persistTableDescription() and StorageColumnDefinitionSynchronizer::syncColumnDescriptions()). Output mapping's own componentId row was therefore a duplicate, and on a user-managed table it published a competing description while the user's value sat under storage — for anyone reading metadata, output mapping had overwritten the user's description. That failed the acceptance criterion, so the key is no longer written as component metadata. Resolution and stripping live in Writer/Helper/DescriptionHelper.

A column whose only metadata was the description is still reported by getColumnMetadata() with an empty metadata list, because the set of columns to add to an existing table is derived from those keys as well (TableStructureModifier); ColumnsMetadata now skips such empty entries instead of sending an empty metadata write.

BC note: consumers that read KBC.description and filter on provider == componentId will stop seeing it. The row under the storage provider remains, so consumers matching on the key are unaffected — including the input mapping manifest, which does not filter by provider.

Notes for review

• TableInfo::isDescriptionSystemManaged() defaults to true when the field is missing from the table detail, matching the platform default (and the DMD-1662 migration, where existing rows read as system-managed).
• An empty description is treated as no description, so it never clears a value stored in Storage.
• Column descriptions are filtered against the columns the table really has; skipped ones are logged as a warning rather than failing the request (Storage answers 404 for an unknown column and would reject the whole patch, table description included).
• A ClientException with a code >= 500 is propagated instead of being wrapped, so a Storage outage stays a retryable application error — consistent with the metadata path in LoadTableQueue.
• keboola/storage-api-client bumped ^18.5 → ^18.9 for updateTableDefinition().
• LoadTableQueue got a new optional 4th constructor argument, so it stays backwards compatible.
• The new functional test is excluded from the main-writer-tests-2 suite so it does not run in two CI jobs in parallel against the same project (bucket name collision).

Testing

• phpcs + phpstan (level max) clean; unit tests green.
• Functional test tests/Writer/TableDescriptionWriterTest.php covers the acceptance criteria against real Storage: a created table gets its description, a system-managed one is updated on the next run, a user-managed one is left alone, and a repeated run with an unchanged description succeeds.
• That last case is what caught the most serious defect of the first revision: Storage answers 400 No table definition changes were provided. for a patch with no effective change, so every second run would have killed output mapping — for an existing table before any data was loaded.

[linear-code]

AJDA-2946