DSH config dumps: default, effective and JSON schema

The first move in a DeepSeek Harness config problem is not editing a file; it is dumping the effective tree. The official CLI gives three mutually exclusive modes: --dump-default-config shows the bundle baseline, --dump-config adds the profile, home, and command-line patches, and --dump-config-schema prints field declarations. None starts the app or evaluates config expressions.

DeepSeek Harness: Which dump answers which question

Pick the wrong mode and you are looking at a different tree than the one the process uses. Compare:(source)

The three are mutually exclusive and reject application arguments. dsh --profile web --port 8080 --dump-config will not behave as a dump of the port change, because --port belongs to the application and dump shows the tree before application arguments are parsed.

DeepSeek Harness: Reading provenance in --dump-config

The value of --dump-config is not only “what”, but “who wrote it”. The output annotates each row with its source file and the overlays that modified it. Read in three passes:(source)

1. Find the target row — search by plugin name or field. Expected: land on the exact entry.
2. Read the source comment — it names bundle, profile patch, home patch, or command-line patch. Expected: know which file to edit.
3. Check who overrode it — later layers win. Expected: do not edit an old layer that is already shadowed.

A common mistake is editing the profile cordis.patch.yml while a home-level patch overrides it. The home patch wins over the per-profile layer, and command-line --patch wins last. Dump is the fastest evidence when the order is unclear.

DeepSeek Harness: What schema dump can answer

--dump-config-schema answers “which fields does this plugin support?”, not “what am I currently using?”. It provides:(source)

1. Fields and types — inline fields plus $ref for shared Config. Expected: know whether a value is a string, number, or array.
2. Defaults and required fields — defaults are annotations, not applied values; required fields consider nullable fallback. Expected: know what happens when a field is omitted.
3. Roles and constraints — secret, credential-ref, ms, and similar roles stay in x-cordis. Expected: recognize credential or time-unit semantics.
4. Partial markers — callback validation and unsupported regex are marked partial. Expected: do not treat the schema as a full runtime validator.

The output is JSON, suitable for scripts and field checks, but not a configuration template to paste back.

DeepSeek Harness: Three practical uses

Dump is useful beyond debugging: config review, upgrade comparison, and plugin development all benefit. Three uses:(source)

1. Locate an override conflict — dump the effective config and inspect the source comments. Expected: identify the layer that wins.
2. Check plugin fields — dump the schema before writing a new plugin config. Expected: no guessing field names or defaults.
3. Keep an upgrade baseline — dump before and after an upgrade, then diff. Expected: see default, field, and layer-order changes.

The third use is especially effective when behavior changes after an upgrade but no one edited the config.

DeepSeek Harness: Output size, exit codes, and limits

Dump is a read-only inspection tool with explicit failure modes. Keep these in mind:(source)

• Too much output — search by plugin name, use schema for field names, and diff the default baseline first. Expected: narrow the tree before reading it.
• Preparation or patch failure — exits non-zero and may not print a usable document. Expected: scripts treat non-zero as failure.
• Partial schema projection — may keep partial output and exit 1 with diagnostics on stderr. Expected: use it as reference, not a complete schema.
• Missing patch target — reported on stderr and not always fatal. Expected: read stderr before editing.
• Imports and handles — dump may import modules and retain process handles. Expected: set an external timeout for automation.

The three modes are mutually exclusive; do not try to get YAML and schema from one command.

DeepSeek Harness: A minimal troubleshooting sequence

When a change does not take effect, follow this order instead of editing files by guesswork. Five steps:(source)

1. Dump the effective tree — --dump-config, not the default dump. Expected: the tree the process actually uses.
2. Search the target row — use the plugin name or field. Expected: land on the exact entry.
3. Read the source comment — identify the file and overlays that wrote it. Expected: know which layer wins.
4. Dump the schema — confirm the field name, type, and default. Expected: rule out a typo or wrong type.
5. Compare the default baseline — dump defaults and diff. Expected: separate “template changed” from “my patch changed”.

If step 1 fails, stop and fix the patch or dependency. If step 1 succeeds but the value is still wrong, the answer is in steps 3 and 4, not in restarting the process.

Save each dump with the DSH version in the filename. That one habit makes later comparisons self-describing and prevents the “which file belongs to which release?” question.

Keep the dump outside the profile directory as well. A rebuild or cleanup that removes the profile should not remove the evidence you need to debug it.

Name the files with the version tag and the date; future you will not remember which dump came from which release.

DeepSeek Harness FAQ

The dump does not show my change; was it not saved? Check the profile and home, and use --dump-config rather than --dump-default-config. The default mode does not apply user patches.

Why are some schema entries marked partial? Some constraints cannot be projected into JSON Schema, such as callback validation or unsupported regex. Runtime validation still uses native Schemastery; schema is reference only.

Can I use dump for CI validation? Yes, but remember that it imports modules, may retain handles, and schema output is not a stable versioned catalog. Regenerate after every DSH or plugin upgrade.

The short version: decide whether you need the baseline, the effective value, or field declarations first; choosing the wrong dump makes the tree look wrong.