CLI JSON schema compatibility causes valid records to be omitted and dependency state to be misreported

[craigk]

Summary

The utility consumes JSON from two related CLI clients, but currently assumes an older schema. Several valid fields are represented differently by newer client versions, causing records to be omitted or displayed incompletely.

The defects are related because they all occur at the same CLI JSON compatibility boundary and can be addressed through one backward-compatible normalization change.

Verified client versions

Client	Version	Observed behavior
bd	0.49.6	Emits object metadata, estimated_minutes, owner, and dependencies. Field compatibility is required, but this version is not fully compatible with current Dolt-backed projects or executor flags.
bd	1.2.2	Primary current target. Emits object metadata, estimated_minutes, owner, and dependencies.
br	0.1.33	Emits a paginated JSON envelope, estimated_minutes, and owner; observed output often omits metadata.
br	0.2.19	Current installed br version. Complete comparison requires clean JSONL data because one malformed record currently prevents full validation.

This is a schema-shape compatibility issue, not a claim that one particular minor-version transition caused the defect.

Affected use cases

1. Record listing

A valid record may contain metadata as an object:

"metadata": {
  "source": "example"
}

The utility currently expects a string. Deserialization can therefore fail for the entire record, causing the record to be omitted.

2. Metadata display

Metadata should remain available whether the client emits a legacy string or a JSON object.

3. Estimate display

Some clients emit:

"estimated_minutes": 45

The utility currently recognizes only estimate, so the value is silently discarded.

4. Owner display

Some clients emit owner, while the utility expects assignee. The record therefore appears unassigned.

5. Dependency-blocked state

A record may remain technically open while having one or more dependency blockers. The utility currently counts only records whose status is explicitly blocked.

This causes dependency-blocked records to be excluded from blocked summaries.

6. Dependency relationships

Dependency relationships may be emitted under a dependencies collection rather than direct blocked_by or blocks fields. Those relationships must remain available to consumers.

Root cause

The utility’s input contract does not accept all field names and JSON types emitted by the supported CLI clients.

A mismatch in one optional field can cause an otherwise valid record to be discarded instead of preserving the record and ignoring only the unsupported field.

Proposed fix

• Accept metadata as either a JSON object or a legacy string.
• Accept both estimate and estimated_minutes.
• Accept owner as an alternate ownership field.
• Preserve dependency relationships from the dependencies collection.
• Treat non-empty dependency blockers as blocked for summary calculations.
• Add regression fixtures for each verified client schema.
• Preserve compatibility with existing envelope formats and legacy fields.

Why these defects belong together

These are not unrelated display bugs. They are symptoms of one compatibility problem:

1. The CLI clients emit valid but different JSON shapes.
2. The utility uses one normalized internal representation.
3. The normalization boundary currently rejects or discards some valid fields.
4. Summary calculations depend on the normalized dependency state.

A single change can make the boundary tolerant while adding independent regression coverage for each affected use case.

Acceptance criteria

• Records containing object metadata are retained.
• Legacy string metadata remains supported.
• estimated_minutes is exposed as the normalized estimate.
• owner is exposed when assignee is absent.
• Dependency relationships are preserved.
• Dependency-blocked records are included in blocked summaries.
• Existing paginated and flat JSON formats remain supported.
• Valid records are not discarded solely because of these schema differences.
• Automated tests cover each verified client shape.

Out of scope

• Changes to either CLI client.
• Repairing invalid source data.
• Claiming support for untested versions.
• Making bd 0.49.6 fully compatible with current Dolt-backed projects.
• Resolving unrelated executor flag differences.
• Changing the underlying storage format.