beads/website/docs/cli-reference/import.md
Julian Knutsen e8ae7a291a
feat(count): add --include-infra for exact bd list cardinality parity (#4389)
* feat(count): add --include-infra for exact bd list cardinality parity

bd count hardcoded filter.SkipWisps=true (9a29a158f, Q2 SQL-COUNT rewrite),
so it only counted the durable issues table. bd list --include-infra merges
the wisps table — including no_history beads, which are durable work — so no
count invocation could match a list cardinality. On the production gascity
rig store that meant bd count --type task = 23,777 vs a list --include-infra
cardinality of 33,601: a 29% undercount that blocks Gas City from
implementing an exact Counter over the bd CLI (its bounded-read pagination
needs Total to be exact).

Changes:

- cmd/bd/count.go: new --include-infra flag mirroring bd list's flag.
  applyCountIncludeInfra reproduces the buildListFilter defaults that
  determine list's cardinality under --include-infra: wisps merge
  (SkipWisps=false), template exclusion (IsTemplate=false), default gate
  exclusion unless --type gate, and infra-type routing to the ephemeral
  tier using the store-configured infra set. Without the flag the filter
  construction is unchanged (SkipWisps=true), keeping the widely-scripted
  default byte-identical.
- internal/storage/{dolt,embeddeddolt}/counts.go: CountIssues now delegates
  to issueops.CountIssuesInTx (extended with the query param) instead of a
  hardcoded SELECT COUNT(*) FROM issues, so SkipWisps/Ephemeral routing
  matches SearchIssuesInTx. CountIssuesInTx previously had no production
  callers.
- internal/storage/issueops/count.go: CountIssuesByGroupInTx now honors
  SkipWisps/Ephemeral with the same merge semantics, so --by-* grouped
  counts under --include-infra report merged buckets instead of
  silently-wrong durable-only numbers.
- Tests (TDD): cmd/bd/count_filter_test.go pins the count filter against
  buildListFilter field-by-field; internal/storage/dolt/
  count_include_wisps_test.go asserts CountIssues == len(SearchIssues) for
  the trap filters (templates, no_history, ephemeral) and merged grouped
  counts; cmd/bd/count_embedded_test.go adds CLI-level count==list parity.
- Docs: regenerated CLI reference (also picks up pre-existing dep/import
  help-text drift so scripts/check-doc-flags.sh passes) and one pre-existing
  gofmt fix in issueops/search.go for ci-pr-lint.

Verification on the production gascity rig store (read-only):

  bd count --include-infra --type task  = 33,601
  bd list  --include-infra --type task --all --json --limit 0 | len = 33,601
  bd count --include-infra              = 42,631  (list equivalent: 42,631)
  bd count --include-infra --status open = 1,969  (list equivalent: 1,969)
  bd count --include-infra --by-type    : total 42,631, task bucket 33,601
  bd count --type task (no flag)        = 23,777  (stock bd 1.0.5: 23,777)

Gates: make ci-pr-core (go test -race -short), ci-pr-policy, ci-pr-lint,
go vet ./..., embedded count/list suites, full dolt + embeddeddolt
storage packages.

Fixes #4387

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(cli): write-intent routing for all mutating commands; count ephemeral parity; pin bulk dep cycle gate

Adopt-PR review fixes for PR #4389 on top of the pre-review CI repair.

Routed write surface (#4141, bd-6dnrw.32, GH#3231): bd-6dnrw.32 gave
read-only opens a real read-only path, which silently broke routed sibling
writes -- prefix-routed resolution opened the target read-only, so a mutating
command on a routes.jsonl-routed ID failed with "store is read-only". The
earlier CI repair restored update/comment/comments add/note/reopen; review
found the rest of the mutating surface still broken. Write intent now covers
every prefix-routed mutating command: assign, priority, tag, edit, delete
(single + batch), close (resolveCloseTargets), human respond/dismiss, link,
and dep add/--blocks/remove/bulk (via a new resolveIDWithRoutingForWrite).
The source issue's store opens writable so the write commits on the target
head; read paths, dependency-target ID resolution, dep tree, and contributor
auto-routing stay read-only, preserving the bd-6dnrw.32/GH#3231 guarantee
that routed reads never mutate a foreign project's history. Regression test
TestEmbeddedRoutedMutatingSiblingWritesCommitTargetHead pins assign/tag/
dep add/delete/close routed writes committing on the target head.

Count ephemeral parity (GH#4387): CountIssuesInTx returned the wisps count
unconditionally for an Ephemeral=true filter, while SearchIssuesInTx falls
through to the durable issues table when the wisps tier is empty. The scalar
fall-through landed first, but review (attempt 2) found the same fall-through
missing from the two sibling functions, so grouped counts and count-projection
searches still dropped a durable issues-table row flagged ephemeral=1:
CountIssuesByGroupInTx returned empty buckets while the scalar Total fell
through (sum(groups) != Total), and SearchIssuesWithCountsInTx returned nil
where SearchIssues returned the row. CountIssuesByGroupInTx and
SearchIssuesWithCountsInTx now mirror the scalar/list fall-through, so
bd count --include-infra --by-* and bd search --counts --include-infra match
bd list cardinality when only durable rows match. The scalar fall-through
comment is corrected to describe the durable ephemeral=1 defensive state
(a promoted bead carries ephemeral=0, so it never reaches this branch).
Regression tests TestCountIssuesEphemeralFallsThroughToDurable (scalar),
TestCountIssuesByGroupEphemeralFallsThroughToDurable (grouped), and
TestSearchIssuesWithCountsEphemeralFallsThroughToDurable (counts projection)
pin count==len(list) for that case; the merge path documents that list is the
disjoint-table corruption detector.

Bulk dep cycle gate (bd-6dnrw.8): unchanged from the pre-review repair --
TestEmbeddedDepBulkNoCycleCheckKeepsWholeGraphGate pins the whole-graph
cycle gate on bulk --no-cycle-check adds.

Validation (worktree, BEADS_TEST_EMBEDDED_DOLT=1, -tags gms_pure_go):
routed-write and count-parity regression tests pass; TestEmbeddedDep*,
cross-rig routing, dep/close/delete/link CLI suites, and the count
CLI/issueops suites pass; go build, go vet, gofmt, git diff --check clean.

Validation (attempt 2, grouped + counts-projection fall-through): go build
(issueops, dolt, cmd/bd) and go vet (issueops, dolt) clean; git diff --check
clean. The Dolt count/list parity suite passes against an isolated Dolt test
container (TestCountIssuesMergedMatchesSearch, the three ephemeral
fall-through regressions, TestCountIssuesByGroupIncludesWisps,
TestPR4107SearchIssuesWithCountsEphemeralFalseIncludesNoHistoryOnly); all
three fall-through regressions were verified failing on the pre-fix tree.
Embedded-engine fixtures that need the CGO/ICU build are exercised by the
GitHub PR workflow.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-06-13 04:14:28 -07:00

87 lines
3.8 KiB
Markdown

---
id: import
title: bd import
slug: /cli-reference/import
sidebar_position: 210
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc import`
## bd import
Import issues from a JSONL file (newline-delimited JSON) into the database.
If no file is specified, imports from the configured import.path under .beads/
(default: issues.jsonl). Use "-" to read from stdin. This is the incremental counterpart to
'bd export': new issues are created and existing issues are updated (upsert
semantics).
Memory records (lines with "_type":"memory") are automatically detected and
imported as persistent memories (equivalent to 'bd remember'). This makes
'bd export | bd import' a full round-trip for both issues and memories.
Each JSONL line should map to an issue. The importer accepts every field
'bd export' emits — see 'bd export' output for the canonical schema. Only
"title" is required; everything else is optional.
Common fields:
title Required. Short summary.
description Long-form body.
design, notes, Additional content sections.
acceptance_criteria
issue_type bug | feature | task | epic | chore | ...
priority 0-4 (0 = critical). 0 is preserved (no omitempty).
status open | in_progress | blocked | closed | ...
(rows with status "tombstone" are skipped)
assignee, owner, Ownership metadata.
created_by
labels Array of strings.
dependencies Array of &#123;issue_id, depends_on_id, type, ...&#125;.
comments Array of comment objects.
external_ref, Cross-system identifiers (e.g. "gh-9").
source_system
due_at, defer_until RFC3339 timestamps for scheduling.
metadata Arbitrary JSON object preserved verbatim.
Timestamps (created_at, updated_at, started_at, closed_at) are preserved
when present in the JSONL and otherwise filled in by the importer. The
legacy "wisp" boolean is accepted as an alias for "ephemeral".
By default a row only rewrites an existing local issue when its
updated_at is strictly newer. Older rows are skipped (reported as
stale_skipped_ids) and rows with the same updated_at keep every local
column — updated_at has second granularity, so a timestamp tie can be
two distinct same-second updates, and the local row wins the tie
(reported as tie_kept_local_ids; the row's labels/comments/dependencies
still merge). The guard is also enforced inside the upsert itself, so a
local update that lands while the import is running is preserved rather
than overwritten. Existing issues that the import did rewrite are listed
with a field-level summary (updated_issues), so local state changed by
an import is visible. To deliberately restore an older snapshot, pass
--allow-stale, which imports every row even when it overwrites newer
local state.
EXAMPLES:
bd import # Import from configured import.path
bd import backup.jsonl # Import from a specific file
bd import -i backup.jsonl # Legacy alias for a specific file
bd import - # Read JSONL from stdin
cat issues.jsonl | bd import - # Pipe JSONL from another tool
bd import --dry-run # Show what would be imported
bd import --dedup # Skip issues with duplicate titles
bd import --allow-stale old.jsonl # Restore an older snapshot (overwrites newer local rows)
bd import --json # Structured output with created and skipped IDs
```
bd import [file|-] [flags]
```
**Flags:**
```
--allow-stale Import rows even when older than the local issue (required to restore an older snapshot)
--dedup Skip lines whose title matches an existing open issue
--dry-run Show what would be imported without importing
-i, --input string Read JSONL from a specific file
```