Define index identity, catalog, cache layout, and selector resolution #4

New issue

Closed

opened 2026-09-03 14:22:17 +00:00 by JayKobe6k · 0 comments

JayKobe6k commented

2026-09-03 14:22:17 +00:00

Owner

Goal

Define how persisted indexes are named, located, versioned, and selected without coupling callers to LadybugDB paths.

Scope

Add typed project, index, and index-revision identities. Keep parser-local IR IDs distinct from durable persisted handles.
Define canonical project identity for local directories and Git origins, including normalized origins and optional revisions.
Store an index catalog in the user's platform cache directory. On Linux this must honor XDG_CACHE_HOME and otherwise use the standard user cache location; provide the corresponding Windows behavior.
Define collision, rename, stale-entry, schema-version, and multiple-worktree behavior.
Resolve <index-selector> deterministically:
- an existing directory selects by canonical project directory;
- a recognized Git URL/scp-like origin selects by normalized origin;
- any other string selects by project/index name.
Return an ambiguity error with candidates rather than silently choosing when more than one catalog entry matches.
Allow an explicit database path through typed application requests where a command supports it.

Acceptance criteria

Selector classification and normalization are deterministic and tested for Linux and Windows path forms, HTTPS/SSH origins, project names, missing paths, and ambiguous matches.
Catalog writes are atomic and do not expose incomplete index revisions.
Query callers receive a typed resolved index descriptor, not a raw Cypher connection string.
Cache paths use Path/PathBuf and no hard-coded Unix separators.
Identity and lifecycle behavior is documented.

Dependencies

Depends on #2. LadybugDB storage is implemented in #5.

## Goal Define how persisted indexes are named, located, versioned, and selected without coupling callers to LadybugDB paths. ## Scope - Add typed project, index, and index-revision identities. Keep parser-local IR IDs distinct from durable persisted handles. - Define canonical project identity for local directories and Git origins, including normalized origins and optional revisions. - Store an index catalog in the user's platform cache directory. On Linux this must honor `XDG_CACHE_HOME` and otherwise use the standard user cache location; provide the corresponding Windows behavior. - Define collision, rename, stale-entry, schema-version, and multiple-worktree behavior. - Resolve `<index-selector>` deterministically: - an existing directory selects by canonical project directory; - a recognized Git URL/scp-like origin selects by normalized origin; - any other string selects by project/index name. - Return an ambiguity error with candidates rather than silently choosing when more than one catalog entry matches. - Allow an explicit database path through typed application requests where a command supports it. ## Acceptance criteria - Selector classification and normalization are deterministic and tested for Linux and Windows path forms, HTTPS/SSH origins, project names, missing paths, and ambiguous matches. - Catalog writes are atomic and do not expose incomplete index revisions. - Query callers receive a typed resolved index descriptor, not a raw Cypher connection string. - Cache paths use `Path`/`PathBuf` and no hard-coded Unix separators. - Identity and lifecycle behavior is documented. ## Dependencies Depends on #2. LadybugDB storage is implemented in #5.

JayKobe6k added this to the CLI + Core MVP milestone

2026-09-03 14:22:17 +00:00

JayKobe6k added the

labels

2026-09-03 14:22:17 +00:00

JayKobe6k referenced this issue

2026-09-03 14:22:17 +00:00

Integrate LadybugDB behind typed schema and repository adapters #5