An explicit node id colliding with a stored issue slipped through plan validation (which only caught intra-plan duplicates) into an insert path with upsert semantics — the atomic graph create silently rewrote the existing issue while reporting creation. The upsert behavior is inherited (bd create --id does the same today), but plans mint ids in bulk, so the exposure is much larger here. Add an explicit-ID collision preflight to the shared plan validation: - graphPlanConfig gains an issueExists probe; embedded supplies it from the store (GetIssue spans issues and wisps), proxied from the unit of work's per-table getters — bound to the caller's context, so the live proxied path probes inside the apply transaction and cannot race a concurrent create of the same id. Dry-run validates through the same probe. - Deliberately not overridable by --force: that flag vouches for a foreign prefix, not for destroying existing data. Also: reword the --mol-type rejection to point at the per-node mol_type field (the old text claimed plans don't carry molecule semantics, which the node field contradicts), and document the no-overwrite rule in the --graph plan supplement. Agent-Signature: claude-fable-5-xhigh on behalf of matt wilkie Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.2 KiB
4.2 KiB
Graph plan schema (--graph):
bd create --graph plan.json creates a whole issue graph atomically from a
JSON plan. Node field names follow the issue model's JSON tags (the same
names bd show --json emits), and every field single-issue bd create can
set is addressable from a plan — plus an initial status and pinned,
which bd create has no flags for:
{
"commit_message": "optional Dolt commit message",
"nodes": [
{
"key": "api",
"title": "Design the API",
"type": "task",
"description": "…", "design": "…", "acceptance_criteria": "…", "notes": "…",
"status": "in_progress",
"priority": 1,
"assignee": "alice", "assign_after_create": false,
"owner": "alice@example.com",
"labels": ["backend"],
"estimated_minutes": 45,
"due_at": "2030-01-02T15:04:05Z",
"defer_until": "2030-01-01T00:00:00Z",
"spec_id": "bd-spec1", "external_ref": "gh-42",
"metadata": {"any": "json", "count": 3},
"metadata_refs": {"tracker": "impl"},
"id": "bd-a1b2c3",
"ephemeral": false, "no_history": false,
"wisp_type": "heartbeat", "mol_type": "swarm",
"pinned": false
},
{ "key": "impl", "title": "Implement it", "parent_key": "api" },
{ "key": "gate", "title": "Fanout gate" },
{ "key": "launch", "title": "Launch announced", "type": "event",
"event_kind": "agent.started", "actor": "agent://a", "target": "bead://b", "payload": "{}" }
],
"edges": [
{ "from_key": "gate", "to_key": "api", "type": "blocks" },
{ "from_key": "gate", "to_key": "impl", "type": "waits-for",
"gate": "any-children", "spawner_key": "impl" }
]
}
Node notes:
keyis a plan-local symbolic name; the result maps each key to the minted issue ID.idoptionally pins an explicit issue ID instead (must match the database prefix, likebd create --id, and must not already exist — a plan never overwrites an existing issue).parent_key(a plan node key) orparent_id(an existing issue ID) adds aparent-childdependency on the created node.parentandestimateare accepted aliases forparent_keyandestimated_minutes; the canonical field wins when both spellings are set.statussets the initial status (defaultopen, ordeferredwhendefer_untilis in the future). Nodes createdclosedgetclosed_atauto-filled. Timestamps are RFC3339; relative forms like+6hare not accepted in plans.ephemeral/no_historyoverride the plan-wide--ephemeral/--no-historyflags per node (mutually exclusive per node; in proxied-server mode the effective storage class must be uniform across the plan).event_kind,actor,target, andpayloadrequire"type": "event".metadataaccepts arbitrary JSON values;metadata_refsvalues name other node keys and are replaced with their minted IDs after creation.- Unlike
bd create --parent, graph children do not inherit parent labels and receive flat (non-hierarchical) IDs; plans are explicit artifacts.
Edge notes:
typedefaults toblocks.parent_key/parent_idon nodes already createparent-childedges; don't repeat them inedges.gate(all-children|any-children) andspawner_key/spawner_idattach fanout-gate metadata towaits-foredges, mirroring--waits-for/--waits-for-gate. Thetoendpoint of awaits-foredge is the spawner (gate evaluation watches its children), sospawner_keymust matchto_keyandspawner_idmust matchto_id; they exist to make plans self-documenting. Since an explicitto_idoverridesto_keyas the target,spawner_keycannot be combined withto_id— usespawner_id.- Edges with ready-work-affecting types (
blocks,waits-for, …) may not duplicate or reverse aparent_key/parent_idrelationship, and a parent may not be connected to its own child through them. thread_idthreads conversation edges (e.g.replies-to).
Comments cannot be created from a plan; use bd comments add after creation.
Model fields without bd create flags (sender, work_type, is_template,
await_*, bonded_from, source_*) are likewise not settable from plans.