beads/examples/bd-example-extension-go
Julian Knutsen d594092ebb
security: v1.3.0 dependency + toolchain bumps (7 reachable stdlib advisories, criticals triaged) (#6047)
* security: pin build toolchain to go1.26.7

go1.26.5 carries 8 stdlib advisories, 7 of them reachable from the shipped
bd binary. Verified with govulncheck in call-graph mode against ./cmd/bd,
toolchain pinned so the analysis cannot drift:

  GO-2026-6218  net/url        quadratic resolvePath
  GO-2026-6091  html/template  JS-regexp context tracking
  GO-2026-6090  crypto/tls     post-handshake message flood
  GO-2026-6089  net/http       ReadHeaderTimeout on the h2c check
  GO-2026-6088  encoding/xml   recursion depth
  GO-2026-5972  encoding/asn1  recursion depth
  GO-2026-5026  net/http       vendored x/net/idna punycode
  GO-2026-5942  net            dnsmessage SVCB/HTTPS RR (linked, uncalled)

`bd serve` is a real HTTP server and bd makes TLS client connections, so
these are live paths rather than dead weight: httpapi.Serve reaches four of
them directly. go1.26.6 fixes all eight; 1.26.7 adds one more net/http fix.
After the bump the same scan reports zero.

The `go` directive stays at 1.26.5 so importers of the module keep their
current floor; `toolchain` is what we actually build with. release.yml
builds the shipped binaries with a bare `go build` under the default
GOTOOLCHAIN=auto, which honors the toolchain line.

The Makefile needed the second half of this. It pinned GOTOOLCHAIN from the
`go` directive, which is the importer floor, not the build version - left
alone it would have held every make target (the test suite, the npm and MCP
package gates, local `make build`) at 1.26.5 while the release binaries
moved to 1.26.7, which is both a silent downgrade and a split between what
CI tests and what we ship. It now reads `toolchain` first and falls back to
`go` when there is no toolchain directive, preserving the original reason
for pinning: one exact version so the compile tools and coverage
instrumentation cannot disagree.

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

* security: bump x/crypto, x/mod, klauspost/compress, moby/go-archive

Four advisories, none reachable from the shipped bd binary; these are
hygiene bumps that also clear the Dependabot board.

  golang.org/x/crypto           v0.54.0 -> v0.55.0   GO-2026-6303
  golang.org/x/mod              v0.37.0 -> v0.40.0   GO-2026-6179/6180
  github.com/klauspost/compress v1.18.5 -> v1.18.7   GO-2026-5841
  github.com/moby/go-archive     v0.2.0 -> v0.3.3    CVE-2026-17106 (#140)

Reachability, from `go list -deps ./cmd/bd` plus govulncheck call-graph mode:
x/crypto/ssh proper enters only through testcontainers (test-only); the
compress advisory is in the s2 codec, which is not linked into bd at all
(bd links zstd/gzip/flate/huff0 via dolt); the x/mod sumdb/tlog code is
required but never called; go-archive is testcontainers-only and absent
from the binary's package graph entirely.

go-archive goes to v0.3.3, not the advisory's minimum v0.3.0: v0.3.0's
hardened extraction rejected absolute symlinks and hardlinks and broke
device nodes and implied directories, all fixed across v0.3.1-v0.3.3.

MVS carries x/net, x/text, x/tools and x/telemetry along. No replace
directives, and the dolt pin is untouched - dolt requires older versions of
all three x/ modules, so beads' go.mod already wins the version selection.

The examples/ modules reach the parent through a `replace` directive, so
their recorded graph goes stale on any root go.mod change and both failed
scripts/build-examples.sh with the documented "updates to go.mod needed".
Re-tidied here rather than left for the advisory job to warn about; the
diff is purely the mirror of the bumps above.

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

* security: bump oapi-codegen to v2.7.1 and kin-openapi to v0.144.0

Clears the board's one critical (#133, GHSA-r277-6w6q-xmqw, CVSS 9.1) plus
#142, #141, #134 and the low #132. All five are codegen-tool-only:
kin-openapi reaches the module graph solely through the go.mod `tool`
directive for oapi-codegen, no beads source file imports kin-openapi,
oapi-codegen or openapi3filter, and `go list -deps ./cmd/bd` contains none
of them. The critical is a fail-open bug in openapi3filter's
ValidationHandler.Load(), middleware this repo never runs - request
validation in internal/httpapi is hand-rolled. Dependabot scopes the alert
"runtime" because it cannot model Go tool-directive semantics.

Both must move together: oapi-codegen v2.6.0 does not compile against
kin-openapi v0.144.0 (pkg/codegen/schema.go:909, openapi3.MappingRef vs
string). v2.7.1 is the minimum-fix pair, chosen over the latest 2.8.0/0.149.0
to keep codegen churn off a release branch.

The `make api-gen` regen diff is two lines of real change: the generated
BearerTokenScopes constant picks up a generated named context-key type
instead of being an untyped string. The identifier has no references outside
types.gen.go. `make api-check` is green - regeneration is idempotent,
pinning.go's compile-time welds hold, and TestWireTagBijection passes.

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

* security: refresh beads-mcp uv.lock (clears all 19 pip alerts)

`uv lock --upgrade` with fastmcp still pinned ==3.4.5. Every one of the 19
Dependabot alerts on integrations/beads-mcp/uv.lock is a fastmcp transitive,
and each lands at or above its first-patched version:

  mcp              1.25.0 -> 1.29.1   #129 #128 #127 (high)
  cryptography     48.0.0 -> 50.0.1   #137 #138 #82 #139
  pyjwt             2.12.1 -> 2.13.0  #79 #136 #81 #78 #135
  joserfc            1.6.5 -> 1.7.4   #113 #109
  python-multipart 0.0.27 -> 0.0.32   #88 #87 #86 #85
  idna                3.11 -> 3.19    #68

Real exposure was already low: beads-mcp runs stdio transport only
(server.py's mcp.run_async(transport="stdio")), so the three high mcp-SDK
alerts - WebSocket Host/Origin validation, HTTP session principal handling,
task-handler cross-access - are all HTTP/WS-transport bugs this server never
reaches, and the auth libraries ride along with fastmcp's extras rather than
being used by beads-mcp's own code. The lock governs dev and CI installs;
PyPI users resolve fresh and already get patched versions.

mcp 1.25 -> 1.29 is the only behaviorally interesting jump. The full package
gate is green: uv sync --locked, ruff, mypy, 228 passed / 5 skipped, uv build.
The resolved lock is byte-identical under uv 0.9.5 and CI's uv 0.11.16.

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

* chore(nix): update vendorHash for go.sum changes

The go.mod/go.sum bumps in this branch invalidate the proxyVendor
fixed-output hash in default.nix, which fails the nix-build gate. The
workflow that repairs this automatically only fires for dependabot PRs
targeting main, so it does not cover this branch.

Recomputed with scripts/update-nix-vendorhash.sh's flow and verified:
`nix build .#default` completes green, which also confirms the new
`toolchain go1.26.7` directive is compatible with default.nix's
GOTOOLCHAIN = "local".

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-28 23:26:04 -07:00
..
.gitignore examples: Add complete Go extension example with documentation (#15) 2025-10-14 01:08:00 -07:00
go.mod security: v1.3.0 dependency + toolchain bumps (7 reachable stdlib advisories, criticals triaged) (#6047) 2026-08-28 23:26:04 -07:00
go.sum security: v1.3.0 dependency + toolchain bumps (7 reachable stdlib advisories, criticals triaged) (#6047) 2026-08-28 23:26:04 -07:00
main.go Dolt-native cleanup: remove legacy code, rename API, add server watchdog 2026-02-15 23:43:20 -08:00
README.md docs: canonical concept page, section overviews, and concept diagrams 2026-07-12 10:37:07 -07:00
schema.sql examples: Add complete Go extension example with documentation (#15) 2025-10-14 01:08:00 -07:00

BD Extension Example (Go)

This legacy example demonstrates how to extend SQLite-backed bd databases with custom tables for application-specific orchestration.

Note: Custom SQLite table extensions are a legacy pattern. Current Dolt-backed beads workflows should prefer standalone integration tools that call bd --json commands or use bd query for SQL access. See Extensible Database for the current guidance.

What This Example Shows

  1. Schema Extension: Adding custom tables (example_executions, example_checkpoints) to bd's SQLite database
  2. Foreign Key Integration: Linking extension tables to bd's issues table with proper cascading
  3. Dual-Layer Access: Using bd's Go API for issue management while directly querying extension tables
  4. Complex Queries: Joining bd's issues with extension tables for powerful insights
  5. Execution Tracking: Implementing agent assignment, checkpointing, and crash recovery patterns

Key Patterns Illustrated

Pattern 1: Namespace Your Tables

All tables are prefixed with example_ to avoid conflicts:

CREATE TABLE example_executions (...)
CREATE TABLE example_checkpoints (...)

Pattern 2: Foreign Key Relationships

Extension tables link to bd's issues with cascading deletes:

FOREIGN KEY (issue_id) REFERENCES issues(id) ON DELETE CASCADE

Pattern 3: Index Common Queries

Indexes are created for frequent query patterns:

CREATE INDEX idx_executions_status ON example_executions(status);
CREATE INDEX idx_executions_issue ON example_executions(issue_id);

Pattern 4: Layer Separation

  • bd layer: Issue tracking, dependencies, ready work
  • Extension layer: Execution state, agent assignments, checkpoints

Pattern 5: Join Queries

Powerful queries join both layers:

SELECT i.id, i.title, i.priority, e.status, e.agent_id, COUNT(c.id)
FROM issues i
LEFT JOIN example_executions e ON i.id = e.issue_id
LEFT JOIN example_checkpoints c ON e.id = c.execution_id
GROUP BY i.id, e.id

Building and Running

Prerequisites

  • Go 1.24 or later
  • bd initialized in a directory (run bd init --prefix demo)

Install

# Install from the repository
go install github.com/steveyegge/beads/examples/bd-example-extension-go@latest

# Or install from local source
cd examples/bd-example-extension-go
go install .

The binary will be installed as bd-example-extension-go in your $GOPATH/bin (or $GOBIN if set).

Running

# Auto-discover database and run
bd-example-extension-go

# Or specify database path
bd-example-extension-go -db .beads/demo.db

Output:

Claiming: demo-5
  ✓ assess
  ✓ implement
  ✓ test

Status:
  demo-4: Fix memory leak [closed] agent=agent-demo checkpoints=3
  demo-1: Implement auth [in_progress] agent=agent-alice checkpoints=0
  demo-5: Test minimized [closed] agent=demo-agent checkpoints=3

Code Structure

Just 116 lines total - minimal, focused extension example.

  • main.go (93 lines): Complete workflow with embedded schema
  • schema.sql (23 lines): Extension tables (example_executions, example_checkpoints) with foreign keys and indexes

Demonstrates:

  1. Auto-discover database (beads.FindDatabasePath)
  2. Dual-layer access (bd API + direct SQL)
  3. Execution tracking with checkpoints
  4. Complex joined queries across layers

Example Queries

Find Running Executions with Checkpoint Count

query := `
    SELECT i.id, i.title, e.status, e.agent_id, COUNT(c.id) as checkpoints
    FROM issues i
    INNER JOIN example_executions e ON i.id = e.issue_id
    LEFT JOIN example_checkpoints c ON e.id = c.execution_id
    WHERE e.status = 'running'
    GROUP BY i.id, e.id
`

Find Failed Executions

query := `
    SELECT i.id, i.title, e.error, e.completed_at
    FROM issues i
    INNER JOIN example_executions e ON i.id = e.issue_id
    WHERE e.status = 'failed'
    ORDER BY e.completed_at DESC
`

Get Latest Checkpoint for Recovery

query := `
    SELECT checkpoint_data
    FROM example_checkpoints
    WHERE execution_id = ?
    ORDER BY created_at DESC
    LIMIT 1
`

Integration with bd

Using bd's Go API

// Auto-discover database path
dbPath := beads.FindDatabasePath()
if dbPath == "" {
    log.Fatal("No bd database found")
}

// Open bd storage
store, err := beads.Open(ctx, dbPath)

// Find ready work
readyIssues, err := store.GetReadyWork(ctx, beads.WorkFilter{Limit: 10})

// Update issue status
updates := map[string]interface{}{"status": beads.StatusInProgress}
err = store.UpdateIssue(ctx, issueID, updates, "agent-name")

// Close issue
err = store.CloseIssue(ctx, issueID, "Completed", "agent-name")

// Find corresponding JSONL path (for git hooks, monitoring, etc.)
jsonlPath := beads.FindJSONLPath(dbPath)

Direct Database Access

// Open same database for extension tables
db, err := sql.Open("sqlite3", dbPath)

// Initialize extension schema
_, err = db.Exec(Schema)

// Query extension tables
rows, err := db.Query("SELECT * FROM example_executions WHERE status = ?", "running")

Testing the Example

  1. Initialize bd:

    bd init --prefix demo
    
  2. Create some test issues:

    bd create "Implement authentication" -p 1 -t feature
    bd create "Add API documentation" -p 1 -t task
    bd create "Refactor database layer" -p 2 -t task
    
  3. Run the demo:

    bd-example-extension-go -cmd demo
    
  4. Check the results:

    bd list
    sqlite3 .beads/demo.db "SELECT * FROM example_executions"
    

Real-World Usage

This pattern is used in production by:

  • VC (VibeCoder): Multi-agent orchestration with state machines
  • CI/CD Systems: Build tracking and artifact management
  • Task Runners: Parallel execution with dependency resolution

Next Steps

  1. Add Your Own Tables: Extend the schema with application-specific tables
  2. Implement State Machines: Use checkpoints for resumable workflows
  3. Add Metrics: Track execution times, retry counts, success rates
  4. Build Dashboards: Query joined data for visibility
  5. Integrate with Agents: Use bd's ready work queue for agent orchestration

See Also