Skip to content

[lore 1/7] repo scaffold and core types#1

Merged
kunallanjewar merged 1 commit into
mainfrom
quest-1-scaffold
Apr 28, 2026
Merged

[lore 1/7] repo scaffold and core types#1
kunallanjewar merged 1 commit into
mainfrom
quest-1-scaffold

Conversation

@kunallanjewar
Copy link
Copy Markdown
Contributor

Summary

Bootstraps mathomhaus/lore with the type surface every later quest in the
v0.1.1 series builds on. Library-only scope: no CLI, no MCP server, no
service.

  • go.mod at module path github.com/mathomhaus/lore, Go 1.23 minimum, no
    external dependencies yet (interfaces and reference impls land in
    subsequent quests, which is when OpenTelemetry and modernc.org/sqlite
    enter the require block).
  • pkg/lore/doc.go: package doc that frames the library scope and the three
    pluggable interfaces (Store, Embedder, VectorStore) that compose a
    Retriever and an optional Ingester.
  • pkg/lore/kind.go: Kind typed string with the eight canonical constants
    (decision, principle, procedure, reference, explanation,
    observation, research, idea), AllKinds(), and Validate() that
    wraps ErrInvalidKind.
  • pkg/lore/errors.go: sentinel errors (ErrNotFound, ErrDuplicate,
    ErrInvalidKind, ErrInvalidArgument, ErrConflict, ErrUnsupported,
    ErrClosed). Distinct so callers can errors.Is without ambiguity.
  • pkg/lore/lore.go: Entry, Edge, SearchHit, ListOpts, SearchOpts.
    Each field documents nullable / slice / map semantics so Store
    implementations can persist them consistently.
  • README.md: positioning paragraph, install hint, pre-v1.0 stability
    disclaimer, attribution to mathomhaus/guild, link to the spec.
  • .gitignore tuned for Go.
  • .github/workflows/ci.yml: matrix on Go 1.23 and 1.24 across Ubuntu and
    macOS, runs go vet, go build, and go test -race -count=1.

Acceptance criteria addressed

  • go.mod at github.com/mathomhaus/lore, Go 1.23+
  • LICENSE Apache 2.0 verified at root (untouched from gh repo create)
  • .gitignore for Go projects
  • README scaffold with positioning, install hint, pre-v1.0 disclaimer,
    attribution to mathomhaus/guild, link to spec doc
  • pkg/lore/lore.go: Entry, Edge, SearchHit, common opts types
  • pkg/lore/kind.go: Kind typed string + 8 canonical constants +
    Validate()
  • pkg/lore/errors.go: sentinel errors using errors.New and
    fmt.Errorf wrap-friendly
  • pkg/lore/doc.go: package-level godoc explaining scope and the three
    swap points
  • .github/workflows/ci.yml: Go matrix 1.23+, runs vet, test, build
  • All files Apache 2 compatible (no per-file headers required)
  • Branch quest-1-scaffold, PR opened

Test plan

  • go vet ./... clean
  • go build ./... clean
  • go test -race -count=1 ./... passes (16 tests, including 8
    canonical-kind subtests)
  • gofmt -l . reports no diffs
  • CI green on Ubuntu and macOS, Go 1.23 and 1.24

Notes

  • go.mod deliberately has no require block at this point. Adding
    unused deps (OpenTelemetry, etc.) just to satisfy a future need would be
    scrubbed by go mod tidy. They land in quest 2 (sqlite) and quest 3 (BGE)
    when actually imported.
  • The kind taxonomy uses 8 values immediately, not the legacy 5. The spec
    note about "5 kinds for fork-and-strip speed" is moot here since this is
    a clean rewrite, not a fork.
  • errors.go is hand-written so errors.Is and fmt.Errorf("%w") work
    cleanly across all callers; tests prove distinctness and wrap behavior.

Bootstraps the mathomhaus/lore Go module with the type surface every later
quest in the v0.1.1 series builds on:

- go.mod at module path github.com/mathomhaus/lore, Go 1.23 minimum, no
  external dependencies yet (interfaces and reference impls land in
  subsequent quests).
- pkg/lore/doc.go: package doc explaining library scope (no CLI, no MCP
  server, no service) and the three pluggable interfaces (Store, Embedder,
  VectorStore) that compose a Retriever and an optional Ingester.
- pkg/lore/kind.go: Kind typed string with the eight canonical constants
  (decision, principle, procedure, reference, explanation, observation,
  research, idea), AllKinds, and Validate that wraps ErrInvalidKind.
- pkg/lore/errors.go: sentinel errors (ErrNotFound, ErrDuplicate,
  ErrInvalidKind, ErrInvalidArgument, ErrConflict, ErrUnsupported,
  ErrClosed) intended to be wrapped with fmt.Errorf %w.
- pkg/lore/lore.go: Entry, Edge, SearchHit, ListOpts, SearchOpts. Each
  field documents nullable and slice semantics so Store implementations
  can persist them consistently.
- README.md: positioning paragraph, install hint, pre-v1.0 stability
  disclaimer, attribution to mathomhaus/guild, link to the spec doc.
- .gitignore tuned for Go projects.
- .github/workflows/ci.yml: matrix on go 1.23 and 1.24 across Ubuntu and
  macOS, runs go vet, go build, and go test -race -count=1.

Tests cover Kind validation (canonical and rejected inputs), AllKinds
size and membership, sentinel-error distinctness and wrap-preservation,
and zero-value sanity for the public structs.
@kunallanjewar kunallanjewar merged commit 7a9fd77 into main Apr 28, 2026
4 checks passed
@kunallanjewar kunallanjewar deleted the quest-1-scaffold branch April 28, 2026 15:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant