# ADR 0013: The public signature stays flat `run` and `estimate` take the source axis as seven flat keyword arguments -- `source_kind`, `split`, `delimiter`, `encoding`, `sheet`, `recursive`, `include_hidden` -- rather than the `ObjectSource` union that `damicore_normalizer` already defines. Since only a subset applies to each source, the aggregate maps the flat arguments back onto that union and rejects the ones that do not apply. That adapter reads as accidental accretion and gets proposed for removal, so this records why it is neither accidental nor removable. ## Why flat The shape is specified, not inherited. The 0.1 specification fixed `run(csv_path, split, delimiter, encoding, compressor, compression_level, num_clusters)` and stated the primary use case as Jupyter and Colab. Notebook developer experience is the fourth of eight prioritised quality drivers, above modularity at sixth, and a flat signature is what makes the primary call `run("dataset.csv", split="rows")`. Accepting the union instead would make that call `run("dataset.csv", source=DelimitedSource(split="rows"))`, which asks a notebook user to import a model from a *different distribution* to express what one keyword expresses today. It would also require `damicore` to re-export three models from `damicore_normalizer`, growing the public surface in order to shrink an internal adapter. Both move against the driver the signature exists to serve. Rejecting an argument that does not apply is a declared 0.2 contract, not an implementation detail: "A setting that does not apply raises `ConfigurationError` instead of being ignored." The adapter is where that contract is honoured. ## What was actually wrong Five lines, not the ninety a line count suggests. `_SOURCE_ARGUMENTS` restated the union's field names by hand, giving the axis two declarations that could disagree. Measured at the time of this decision they agreed exactly, and nothing compared them. Enumerating how they could diverge separates one real hazard from two harmless ones: | Divergence | Consequence | |---|---| | a source model gains a field with no matching keyword | **silent** -- the capability exists in the stage package and never reaches a `damicore` caller | | a keyword is added to `run` but not threaded into the adapter | **silent** -- the caller passes it and nothing rejects it, which is what the 0.2 contract forbids | | the hand-written table disagrees with the union | loud: either a rejection message that lies, or `extra="forbid"` at construction | Both silent cases are invisible because each surface is individually consistent. ## Decision The signature stays flat. Two changes close the hazard without touching it: - `_SOURCE_ARGUMENTS` is derived from `DelimitedSource`, `SpreadsheetSource` and `FileCorpusSource`, so the union is the one declaration and the third row above cannot occur; - `test_every_source_setting_is_reachable_and_threaded` asserts every union field appears as a parameter of `run`, `estimate` and the adapter, which closes the two silent rows. It was observed failing against both before being kept. Net effect is seven lines added, no public API change, no version bump. ## Revision condition Reopen if the source axis grows past roughly three variants or the per-source argument sets start overlapping in ways a flat signature cannot express without ambiguity -- at which point the union becomes the clearer public contract and the break is worth a major release. A larger line count in the adapter is not by itself a reason: it is the cost of the flat signature, which is a product decision recorded above. ## Note on the source The evidence for this decision came from `DAMICORE_IMPLEMENTATION_SPECIFICATION.md`, deleted in PR #16 and recoverable only from git history. Its section 5 prioritised eight quality drivers, and that ordering is what settles both this decision and ADR 0012; it had survived in no other file, so both decisions had to rediscover it. It is now [docs/quality-drivers.md](../quality-drivers.md).