kb

type Bubble struct {
	// KBID is the immutable kb identifier from /api/v1/kb. Empty for
	// legacy rows that haven't been migrated into the kb table yet.
	KBID string

	// Type is the kb_type bucket. Legacy team rows synthesize KBTypeTeam;
	// legacy ledger rows synthesize KBTypeRepo. Unknown server values are
	// already collapsed to KBTypeUnknown by the kb client.
	Type api.KBType

	// Slug is the human-readable slug (kebab-case). Used as the secondary
	// dedup key together with Endpoint when neither KBID nor RepoID matches.
	Slug string

	// Name is the display name.
	Name string

	// ViewerRole is the caller's role on this bubble ("owner", "member",
	// "viewer"). Only kb-API rows populate this today.
	ViewerRole string

	// LocalPath is the on-disk checkout path. For kb-API rows this is the
	// canonical KBDir(kb_id); for legacy rows it's whatever path the
	// synthesizer reports (team context dir or ledger dir).
	LocalPath string

	// RepoURL is the git clone URL when known.
	RepoURL string

	// RepoID is the SageOx repo_id, populated for legacy ledger rows and
	// for kb-API rows when the server supplies it. Used as the secondary
	// dedup key.
	RepoID string

	// Endpoint is the SageOx API endpoint this row belongs to (normalized
	// via endpoint.NormalizeEndpoint). Used together with Slug as the
	// tertiary dedup key.
	Endpoint string

	// Source identifies which fan-out branch produced this row.
	Source Source

	// Legacy is true for synthesized rows from /api/v1/cli/repos and the
	// local ledger registry. kb-API rows have Legacy=false.
	Legacy bool
}

type EffectiveValue struct {
	Key             string
	Effective       string
	Layers          []LayerValue
	SafetyInversion bool
}

type KBBinding struct {
	// KBID is the immutable kb identifier (kb_xxx) from the binding file.
	// Required; empty values are treated as "no binding".
	KBID string

	// KBType is the kb_type bucket (personal|profile|team|repo|custom|channel).
	// The resolver does NOT populate this — it requires a kb-API lookup or
	// merge.go output to determine type from kb_id. Callers enrich as needed;
	// the field exists on the struct so the resolver's return value can carry
	// it once enrichment has happened.
	KBType string

	// Source is the relative path of the marker file that produced this
	// binding, either ".sageox/config.yaml" (current) or ".sageox/config.json"
	// (legacy). Used by doctor and `ox kb config --show-origin` to attribute
	// values to their on-disk source.
	Source string

	// Anchor is the absolute path of the directory containing the .sageox/
	// marker — i.e. the workspace root, not the marker file itself.
	Anchor string

	// Scope is "exclusive" (default) for now. ADR-017 §6 reserves "subtree"
	// for nested overrides; the v1 resolver rejects nested markers entirely.
	Scope string

	// Endpoint is the SageOx API endpoint this binding belongs to (normalized
	// via endpoint.NormalizeEndpoint). If the binding file carries an explicit
	// `endpoint:` field, that value is used; otherwise the resolver falls back
	// to endpoint.Get() so callers always have a non-empty value.
	//
	// Note: this field is not in ADR-017 §1's struct diagram but the bead
	// description (ox-z526) requires it for downstream consumers (doctor's
	// kb-binding-endpoint-mismatch check, multi-endpoint dispatch). It is
	// always populated by ResolveCurrentKB.
	Endpoint string
}

type KBSource interface {
	ListBubbles(ctx context.Context) ([]api.KB, error)
}

type LayerValue struct {
	Scope   string // "env" | "kb" | "user" | "default"
	Source  string // human label e.g. "OX_SESSION_RECORDING", ".sageox/config.yaml"
	Value   string // empty if unset at this layer
	Trigger bool   // true when safety-inversion fired *because of* this layer
}

type LedgerSource interface {
	ListLedgers(ctx context.Context) ([]LegacyLedgerRow, error)
}

type LegacyLedgerRow struct {
	RepoID   string // SageOx repo_id (extracted from path or project config)
	Name     string // display name (typically the host repo's name)
	Slug     string // optional kebab-case slug
	LocalDir string // on-disk ledger checkout path
	Endpoint string // SageOx API endpoint this ledger is bound to
	URL      string // git clone URL when known (rare for legacy ledgers)
}

type LegacyTeamRow struct {
	TeamID   string // team_xxx — used as RepoID-equivalent for dedup
	Name     string
	Slug     string
	URL      string // git clone URL
	LocalDir string // on-disk team-context checkout (may be empty if not yet cloned)
}

type LegacyTeamSource interface {
	ListTeamContexts(ctx context.Context) (rows []LegacyTeamRow, endpoint string, err error)
}

type MergeResult struct {
	Bubbles  []Bubble
	Warnings []SourceWarning
}

type Merger struct {
	// contains filtered or unexported fields
}

type Source string

type SourceWarning struct {
	Source Source
	Err    string
}