cherry

package module
v0.0.0-...-e49540b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 16, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

Cherry

Cherry is a compact packed-configuration reader and writer for enforcement points. It is designed for a control plane to deliver one immutable bundle, and for an enforcement point to load that bundle into memory and query it without inflating one Go object per key, route, or MCP profile.

The public API is the root Go package:

import cherry "github.com/dio/cherry"

Repository Layout

go.mod
go.sum
README.md
pack.go
pack_bundle.go
pack_test.go
pack_bench_test.go
example/
  README.md
  main.go
  source/
  transform/

pack.go contains the compact table format and query engine. pack_bundle.go adds the zstd bundle envelope used for control-plane to enforcement-point delivery.

DESIGN.md summarizes the stable mapped-split delivery design for high-churn user-key and MCP profile policy.

Producing A Bundle

The producer is the control-plane-side code that owns source selection and turns already-normalized external records into cherry.Input. It decides which scopes belong in the bundle and which principal slugs, models, MCP servers, and MCP profiles are valid in each scope.

Cherry expects that work to be done before BuildWithManifest:

source records
  -> external transformer
  -> cherry.Input
  -> BuildWithManifest
  -> NewBundle
  -> EncodeBundleZstd
  -> delivery bytes

Minimal shape (open catalog objects use encoding/json.RawMessage):

input := cherry.Input{
    Providers: []cherry.Provider{
        {
            ID:        "openai",
            Kind:      "openai",
            Endpoint:  "https://api.openai.com",
            SecretRef: "env://OPENAI_API_KEY",
        },
    },
    Models: []cherry.Model{
        {
            ID:           "gpt-4o-mini",
            Provider:     "openai",
            Name:         "gpt-4o-mini",
            Mode:         "chat",
            Capabilities: []string{"vision", "tool_choice"},
            Modalities: cherry.ModelModalities{
                Input:  []string{"text", "image"},
                Output: []string{"text"},
            },
            Limits: cherry.ModelCatalogObject{
                "max_output_tokens": json.RawMessage(`16384`),
            },
            MetadataJSON: `{"model":"gpt-4o-mini","inputTokensPricePerMillion":"0.15","capabilities":["vision","tool_choice"]}`,
        },
    },
    MCPServers: []cherry.MCPServer{
        {
            ID:        "github",
            Endpoint:  "https://api.github.com",
            AuthType:  "bearer",
            SecretRef: "env://GITHUB_TOKEN",
        },
    },
    Scopes: []cherry.Scope{
        {
            ID: "workspace1",
            Principals: []cherry.Principal{
                {
                    Slug: "slug:project1",
                    ModelRoutes: map[string]cherry.RoutePlan{
                        "gpt-4o-mini": {
                            Provider:  "openai",
                            Model:     "gpt-4o-mini",
                            SecretRef: "env://OPENAI_API_KEY",
                        },
                    },
                    Rate: cherry.RatePolicy{
                        USDPerDayCents: 5000,
                        RPM:            60,
                        OnExceed:       "reject",
                    },
                },
            },
            MCPProfiles: []cherry.MCPProfile{
                {
                    Path: "profile-dev-tools",
                    Tools: []cherry.MCPToolBinding{
                        {
                            ExposedName: "github__list-repos",
                            Server:      "github",
                            Tool:        "list-repos",
                            AuthType:    "bearer",
                            SecretRef:   "env://GITHUB_TOKEN",
                        },
                    },
                },
            },
        },
    },
}

blob, manifest, err := cherry.BuildWithManifest(input)
if err != nil {
    return err
}

bundle := cherry.NewBundle(
    "workspace",
    "workspace1",
    []string{"workspace1"},
    blob,
    manifest,
)

bundleBytes, err := cherry.EncodeBundleZstd(bundle)
if err != nil {
    return err
}

The resulting bundleBytes are what the control plane stores or serves to an enforcement point.

For production delivery, Cherry recommends mapped split when route/profile churn or bundle size makes full-generation rebuilds too expensive. A mapped split generation publishes a small control map plus normal zstd Cherry bundles:

llm-generic                  low-churn providers, models, default routes
mcp-servers                  low-churn MCP server catalog and s/<server> paths
llm-user-key-{000..N}        partitioned principal routes, BYOK, rate policy
mcp-user-profile-{000..N}    partitioned MCP profile paths and tool bindings

Use MappedSplitSpec to keep producer and enforcement-point code on the same stable lane names and partition math:

spec := cherry.MappedSplitSpec{
    LLMUserKeyPartitions:     64,
    MCPUserProfilePartitions: 64,
}

affected, err := spec.AffectedBundle(cherry.MappedSplitChange{
    Kind:          cherry.MappedSplitChangeLLMUserKey,
    PrincipalSlug: "slug:project1",
})
if err != nil {
    return err
}

// Rebuild affected.Component(), for example llm-user-key-003.

Cherry does not infer source-record diffs. The control plane classifies whether a change belongs to generic LLM policy, MCP servers, a key-specific LLM route, or an MCP profile, then MappedSplitSpec computes the exact component. See DESIGN.md and go run ./example mapped-split-demo ... for the producer and EP shape. On the EP side, compare each new map ref with the active view by generation, URL, checksum, and size; fetch only missing or stale refs and reuse unchanged opened readers.

If the control plane normally publishes bundles on a periodic cadence, use SnapshotPolicy to decide which normalized mutable changes should interrupt that cadence and publish a fresh immutable snapshot immediately. External key watching and verification stay outside Cherry; after that system observes a key change, it can map the event to a normalized principal or secret-ref change:

decision := cherry.DefaultSnapshotPolicy().Decide([]cherry.SnapshotChange{
    {
        Kind:          cherry.SnapshotChangePrincipalBinding,
        ScopeID:       "workspace1",
        PrincipalSlug: "slug:project1",
        Reason:        "key binding changed",
    },
})
if decision.TakeSnapshot {
    // Rebuild the affected bundle or scope overlay, encode it, open it, and
    // publish it with the normal atomic generation swap.
}

Model catalog records can carry opaque normalized metadata. A producer can read its raw model catalog, promote fields Cherry needs for stable query semantics, and keep the full normalized row in Model.MetadataJSON.

For a seed row such as gpt-image-2, the field boundary is:

Source field Cherry field Notes
model Model.ID, Model.Name Logical requested model ID and upstream model name.
provider Model.Provider Must reference an Input.Providers entry.
mode Model.Mode First-class catalog metadata, e.g. chat, responses, image_generation.
capabilities Model.Capabilities First-class capability list used by ModelCapability.
modalities Model.Modalities First-class input/output modality lists for request shaping and diagnostics.
additionalPricePerMillion Model.AdditionalPricePerMillion First-class open catalog object for provider- and mode-specific price dimensions.
limits Model.Limits First-class open catalog object for provider- and mode-specific request limits.
Full enabled row Model.MetadataJSON Opaque JSON for source-specific fields and future catalog changes.

Fields such as backendUrls, metadata.aliases, metadata.options, metadata.source_url, metadata.description, and metadata.display_name are preserved in Model.MetadataJSON. They are not first-class pack fields today because Cherry does not make routing or compatibility decisions from them.

AdditionalPricePerMillion and Limits intentionally use open JSON objects: the seed schema allows provider- and mode-specific keys such as image_tokens, image_generation, max_edge_px, edge_multiple_px, max_total_pixels, or max_long_edge_to_short_edge_ratio. This keeps those objects queryable without hard-coding every provider-specific nested shape. V1ModelsJSON uses the typed Limits object for max_output_tokens and still uses MetadataJSON for source pricing fields needed by the OpenAI-compatible model-list projection.

Enforcement Point Consumption

The enforcement point fetches bytes from the control plane, opens the bundle, and stores the returned reader behind its active generation pointer.

bundleBytes, err := fetchCurrentBundle()
if err != nil {
    return err
}

opened, err := cherry.OpenBundleZstd(bundleBytes)
if err != nil {
    return err
}

reader := opened.Reader

LLM request resolution after an external verifier has produced a principal slug. Use ResolveLLMPlanIDs when the enforcement point needs to execute fallback chains or weighted splits:

plan, ok := reader.ResolveLLMPlanIDs("workspace1", "slug:project1", "claude-haiku-4-5")
if !ok {
    // reject: no route for this scope, principal, and requested model
}

// plan.Plan is target, chain, or split. Target children contain provider,
// model, endpoint, and effective secret-ref IDs.

ResolveLLMIDs remains available for callers that only need the first executable target from the compiled route tree.

MCP tool resolution:

tool, ok := reader.ResolveMCPToolIDs("workspace1", "profile-dev-tools", "github__list-repos")
if !ok {
    // reject: no tool binding for this scope, path, and exposed tool name
}

server := reader.String(tool.ServerSID)
upstreamTool := reader.String(tool.ToolSID)
authType := reader.String(tool.AuthTypeSID)
secretRef := reader.String(tool.SecretSID)

MCP initialize resolution:

init, ok := reader.ResolveMCPInitialize("workspace1", "profile-dev-tools")
if !ok {
    // reject: no MCP path for this scope
}

for _, server := range init.Servers {
    connect(server.Endpoint, server.AuthType, server.SecretRef)
}

For diagnostics and admin surfaces, the reader also exposes inspector methods:

scopes := reader.ScopeIDs()
llmPrincipals, ok := reader.Principals("workspace1")
principals, ok := reader.PrincipalRoutes("workspace1")
mcpPaths, ok := reader.MCPPaths("workspace1")

Model catalog and MCP server queries are available from the same loaded bundle:

model, ok := reader.ResolveModel("gpt-4o-mini")
supportsImages := reader.ModelCapability("gpt-5", "image_generation")
providers := reader.Providers()
providerDescriptions := reader.ProviderDescriptions()
provider, ok := reader.ResolveProvider("openai")
modelsJSON, err := reader.V1ModelsJSON()
openAIModelsJSON, err := reader.V1ModelsJSONForProvider("openai")
servers := reader.MCPServers()
server, ok := reader.ResolveMCPServer("github")

V1ModelsJSON renders the packed catalog in a /v1/models response shape while preserving pricing and capability-derived fields from the normalized metadata.

The example directory includes fixture loaders for seed-style model/provider catalogs and MCP catalogs. Those loaders are example producer code, not root package schema contracts.

Provider source schemas should be normalized before calling Build. For example, a source provider with nested auth.type, auth.secret_ref, and provider-specific extra fields maps to Provider.AuthType, Provider.SecretRef, and Provider.Extra. Cherry stores auth types as open strings so bundles can describe providers such as bearer, anthropic, gemini, gcp, and aws without hard-coding a provider registry in the root package. ProviderDescriptions lists all packed providers, their effective auth types, and the model IDs attached to each provider.

Boundary

Cherry does not own tenancy joins, key verification, ownership checks, rule authoring, or project/workspace fanout. Those belong to the external system.

The intended pipeline is:

source records -> transformer -> normalized pack input -> pack bundle -> EP reader

See example/README.md for the source-to-pack example, walkthrough, and CLI commands.

Documentation

Overview

Package cherry contains a compact enforcement bundle writer and reader.

A control plane uses Build or BuildWithManifest to turn normalized routing rows into one immutable byte blob. An enforcement point uses Open, OpenWithManifest, or OpenBundleZstd to validate that blob and query it in place. Reader intentionally does not inflate the pack into one Go map/object per principal, MCP profile, or rate-limit rule. Its hot-path methods binary search fixed-width indexes and return integer IDs into shared tables.

The package starts at the normalized-data boundary. It does not perform tenancy joins, key verification, ownership checks, or rule merging. Those decisions belong to the system that prepares Input.

Example (MappedSplitMapShape) 
splitMap := testSplitMap{
	FormatVersion:           "mapped-split-v1",
	ScopeKind:               "project",
	ScopeID:                 "project1",
	Scopes:                  []string{"workspace1", "workspace2"},
	GenerationID:            "gen42",
	MapRevision:             1,
	LLMDefaultPrincipalSlug: "slug:default",
	Partitioning: map[string]testPartitionSpec{
		"llm-user-key": {
			Algorithm:  "fnv1a64",
			Key:        "principal_slug",
			Partitions: 64,
		},
		"mcp-user-profile": {
			Algorithm:  "fnv1a64",
			Key:        "path_suffix",
			Partitions: 64,
		},
	},
	Bundles: map[string]testBundleRef{
		"llm-generic": {
			URL:      "/cherry/v1/bundles/project/project1/gen42/llm-generic.zst",
			Checksum: 1001,
			Size:     4096,
		},
		"mcp-servers": {
			URL:      "/cherry/v1/bundles/project/project1/gen42/mcp-servers.zst",
			Checksum: 1002,
			Size:     2048,
		},
	},
	PartitionBundles: map[string][]testPartitionBundleRef{
		"llm-user-key": {
			{
				Partition: 0,
				URL:       "/cherry/v1/bundles/project/project1/gen42/llm-user-key-000.zst",
				Checksum:  2000,
				Size:      1024,
			},
		},
		"mcp-user-profile": {
			{
				Partition: 0,
				URL:       "/cherry/v1/bundles/project/project1/gen42/mcp-user-profile-000.zst",
				Checksum:  3000,
				Size:      1024,
			},
		},
	},
}
data, _ := json.Marshal(splitMap)
fmt.Println(len(data) > 0)

Output:
true

Index

Examples

Constants

View Source 
const (
	// BundleFormatVersion identifies the zstd bundle envelope format. It is
	// separate from the binary pack format version stored in Manifest.
	BundleFormatVersion = "pack-v1"
)
View Source 
const MappedSplitCatalogPartition = -1

MappedSplitCatalogPartition marks a non-partitioned catalog/default mapped split bundle key.

Variables

This section is empty.

Functions

func Build 

func Build(input Input) ([]byte, error)

Build encodes normalized enforcement data into a compact immutable pack blob.

The input must already be scoped and compiled by the caller. Build validates table references, rejects unknown providers/models/MCP servers, interns shared strings, and writes fixed-width indexes for LLM and MCP lookups.

The returned blob can be opened with Open. Use BuildWithManifest when the blob will be delivered across a control-plane/enforcement-point boundary and the receiver should validate size, checksum, and format version before use.

func EncodeBundle 

func EncodeBundle(bundle Bundle) ([]byte, error)

EncodeBundle serializes bundle metadata and the raw pack blob without compression. The payload is intended as the inner format used by EncodeBundleZstd.

func EncodeBundleZstd 

func EncodeBundleZstd(bundle Bundle) ([]byte, error)

EncodeBundleZstd serializes bundle metadata plus blob and compresses the result with zstd. The returned bytes are the delivery artifact consumed by OpenBundleZstd.

func ValidateManifest 

func ValidateManifest(blob []byte, manifest Manifest) error

ValidateManifest checks whether manifest describes blob. It verifies the pack format version, byte size, and checksum over the content after the fixed header. It does not validate table offsets; Open performs that structural validation.

func ValidateSplitBundleCompatibility 

func ValidateSplitBundleCompatibility(llm BundleMetadata, mcp BundleMetadata) error

ValidateSplitBundleCompatibility verifies that paired LLM and MCP bundles can be composed as one SplitView generation. It intentionally does not require matching pack manifests: independent policy clusters are expected to have different blobs, checksums, and sizes.

Types

type Bundle 

type Bundle struct {
	Metadata BundleMetadata
	Blob     []byte
}

Bundle combines delivery metadata with an uncompressed pack blob. Use EncodeBundleZstd to serialize it for transport or storage.

func DecodeBundle 

func DecodeBundle(payload []byte) (Bundle, error)

DecodeBundle parses an uncompressed bundle payload produced by EncodeBundle. It validates the bundle envelope version but does not open the embedded pack.

func DecodeBundleZstd 

func DecodeBundleZstd(compressed []byte) (Bundle, error)

DecodeBundleZstd decompresses a zstd bundle artifact and decodes its metadata and embedded pack blob. It does not open or validate the embedded pack; use OpenBundleZstd for the enforcement-point load path.

func NewBundle 

func NewBundle(scopeKind string, scopeID string, scopes []string, blob []byte, manifest Manifest) Bundle

NewBundle constructs a bundle envelope for an already-built pack blob. scopeKind and scopeID describe the requested control-plane selection, while scopes lists the concrete enforcement scopes contained in the blob.

type BundleMetadata 

type BundleMetadata struct {
	FormatVersion string   `json:"format_version"`
	ScopeKind     string   `json:"scope_kind"`
	ScopeID       string   `json:"scope_id"`
	Scopes        []string `json:"scopes"`
	GenerationID  string   `json:"generation_id,omitempty"`
	PackManifest  Manifest `json:"pack_manifest"`
}

BundleMetadata is the small delivery envelope around a compact pack blob. It tells an enforcement point what scope selection the bundle represents and carries the manifest used to validate the embedded pack.

type Input 

type Input struct {
	Providers  []Provider
	Models     []Model
	MCPServers []MCPServer
	Scopes     []Scope
}

Input is the normalized data accepted by Build. Callers are responsible for preparing only the providers, models, servers, scopes, principals, and profiles that are valid for the bundle being built.

type LLMIDs 

type LLMIDs struct {
	PrincipalSID      uint32
	ProviderID        uint32
	ProviderSID       uint32
	ParentProviderSID uint32
	KindSID           uint32
	BackendSchemaSID  uint32
	EndpointSID       uint32
	ModelID           uint32
	ModelSID          uint32
	ModelNameSID      uint32
	SecretSID         uint32
	RouteID           uint32
	RateID            uint32
	Rate              RatePolicyIDs
}

LLMIDs is the allocation-minimizing data-path result. It returns integer IDs into the pack tables and string table. Callers that only need to dispatch to an already-interned provider/model can avoid materializing strings entirely.

type LLMPlan 

type LLMPlan struct {
	PrincipalSlug  string
	RequestedModel string
	Plan           LLMRoutePlan
	Rate           RatePolicy
}

LLMPlan is the string-materialized complete route plan for an LLM lookup.

type LLMPlanIDs 

type LLMPlanIDs struct {
	PrincipalSID      uint32
	RequestedModelID  uint32
	RequestedModelSID uint32
	RouteID           uint32
	RateID            uint32
	Rate              RatePolicyIDs
	Plan              LLMRoutePlanIDs
}

LLMPlanIDs is the complete ID-returning result for an LLM lookup, including the requested principal/model index entry, immutable rate-limit metadata, and the route tree selected for enforcement.

type LLMResult 

type LLMResult struct {
	PrincipalSlug  string
	Provider       string
	ParentProvider string
	ProviderKind   string
	BackendSchema  string
	Endpoint       string
	Model          string
	ModelName      string
	SecretRef      string
	Rate           RatePolicy
}

LLMResult is the string-materialized form of an LLM lookup. It is convenient for tests, CLIs, and diagnostics; hot paths should prefer LLMIDs.

type LLMRouteChild 

type LLMRouteChild struct {
	Weight uint32
	Plan   LLMRoutePlan
}

LLMRouteChild is one materialized route-plan child. Weight is zero for chain children and non-zero for split children.

type LLMRouteChildIDs 

type LLMRouteChildIDs struct {
	Weight uint32
	Plan   LLMRoutePlanIDs
}

LLMRouteChildIDs is one child of a materialized route-plan node. Weight is zero for ordered chain children and non-zero for split children.

type LLMRoutePlan 

type LLMRoutePlan struct {
	Kind            RouteKind
	Provider        string
	ParentProvider  string
	ProviderKind    string
	BackendSchema   string
	Endpoint        string
	Model           string
	ModelName       string
	SecretRef       string
	RetryOn         string
	Metadata        map[string]string
	PerTryTimeoutMS uint32
	Children        []LLMRouteChild
}

LLMRoutePlan is the string-materialized representation of an LLM route tree. Target nodes populate Provider/Model/SecretRef fields. Chain and split nodes populate Children.

type LLMRoutePlanIDs 

type LLMRoutePlanIDs struct {
	RouteID           uint32
	Kind              RouteKind
	ProviderID        uint32
	ProviderSID       uint32
	ParentProviderSID uint32
	KindSID           uint32
	BackendSchemaSID  uint32
	EndpointSID       uint32
	ModelID           uint32
	ModelSID          uint32
	ModelNameSID      uint32
	SecretSID         uint32
	RetryOnSID        uint32
	MetadataSID       uint32
	PerTryTimeoutMS   uint32
	Children          []LLMRouteChildIDs
}

LLMRoutePlanIDs is the ID-returning representation of an LLM route tree. It is the preferred data-path API when the enforcement point needs fallback or weighted split behavior without string materialization.

type LayeredLLMIDs 

type LayeredLLMIDs struct {
	LLMIDs
	Source                LayeredLLMSource
	ResolvedPrincipalSlug string
}

LayeredLLMIDs is an executable LLM target result plus the reader layer that owns its string IDs.

type LayeredLLMPlanIDs 

type LayeredLLMPlanIDs struct {
	LLMPlanIDs
	Source                LayeredLLMSource
	ResolvedPrincipalSlug string
}

LayeredLLMPlanIDs is an LLM plan result plus the reader layer that owns its string IDs.

type LayeredLLMSource 

type LayeredLLMSource string

LayeredLLMSource identifies which LLM reader produced a layered split result. 

const (
	// LayeredLLMSourceGeneric identifies the mostly static generic/default LLM
	// reader.
	LayeredLLMSourceGeneric LayeredLLMSource = "llm_generic"
	// LayeredLLMSourceKey identifies the per-key LLM override reader.
	LayeredLLMSourceKey LayeredLLMSource = "llm_key"
)

type LayeredMCPInitializeIDs 

type LayeredMCPInitializeIDs struct {
	MCPInitializeIDs
	Source LayeredMCPSource
}

LayeredMCPInitializeIDs is an MCP initialize result plus the reader layer that owns its string IDs.

type LayeredMCPResultIDs 

type LayeredMCPResultIDs struct {
	MCPResultIDs
	Source LayeredMCPSource
}

LayeredMCPResultIDs is an MCP path result plus the reader layer that owns its string IDs.

type LayeredMCPSource 

type LayeredMCPSource string

LayeredMCPSource identifies which MCP reader produced a layered split result. 

const (
	// LayeredMCPSourceServers identifies the mostly static direct MCP server
	// reader for paths such as "s/github".
	LayeredMCPSourceServers LayeredMCPSource = "mcp_servers"
	// LayeredMCPSourceProfiles identifies the MCP profile reader for paths such
	// as "profile-dev-tools".
	LayeredMCPSourceProfiles LayeredMCPSource = "mcp_profiles"
)

type LayeredMCPToolIDs 

type LayeredMCPToolIDs struct {
	MCPToolIDs
	Source LayeredMCPSource
}

LayeredMCPToolIDs is an MCP tool result plus the reader layer that owns its string IDs.

type LayeredSplitBundleOptions 

type LayeredSplitBundleOptions struct {
	GenerationID            string
	LLMGenericPackChecksum  uint64
	LLMKeysPackChecksum     uint64
	MCPServersPackChecksum  uint64
	MCPProfilesPackChecksum uint64
	LLMDefaultPrincipalSlug string
	RequiredLLMProviders    []string
	RequiredLLMModels       []string
	RequiredMCPServers      []string
}

LayeredSplitBundleOptions are optional compatibility requirements checked while opening a four-layer split.

type LayeredSplitView 

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

LayeredSplitView composes four independently rebuilt readers: generic/default LLM policy, per-key LLM overrides, direct MCP server paths, and MCP profiles. It does not change the pack format; each layer remains a normal immutable Reader.

func NewLayeredSplitView 

func NewLayeredSplitView(
	llmGeneric Reader,
	llmKeys Reader,
	mcpServers Reader,
	mcpProfiles Reader,
	options LayeredSplitViewOptions,
) LayeredSplitView

NewLayeredSplitView returns an immutable four-layer view. The readers are copied by value and still reference their original immutable blobs.

func (LayeredSplitView) LLMGenericReader 

func (v LayeredSplitView) LLMGenericReader() Reader

LLMGenericReader returns the generic/default LLM reader.

func (LayeredSplitView) LLMKeysReader 

func (v LayeredSplitView) LLMKeysReader() Reader

LLMKeysReader returns the per-key LLM override reader.

func (LayeredSplitView) LLMString 

func (v LayeredSplitView) LLMString(source LayeredLLMSource, id uint32) string

LLMString returns an LLM string-table value from the reader that produced a layered LLM result.

func (LayeredSplitView) MCPProfilesReader 

func (v LayeredSplitView) MCPProfilesReader() Reader

MCPProfilesReader returns the MCP profile reader.

func (LayeredSplitView) MCPServers 

func (v LayeredSplitView) MCPServers() []MCPServerInfo

MCPServers returns MCP server catalog metadata from the static MCP server reader.

func (LayeredSplitView) MCPServersReader 

func (v LayeredSplitView) MCPServersReader() Reader

MCPServersReader returns the direct MCP server path reader.

func (LayeredSplitView) MCPString 

func (v LayeredSplitView) MCPString(source LayeredMCPSource, id uint32) string

MCPString returns an MCP string-table value from the reader that produced a layered MCP result.

func (LayeredSplitView) ModelCapability 

func (v LayeredSplitView) ModelCapability(modelID string, capability string) bool

ModelCapability reports model capability from the generic LLM reader.

func (LayeredSplitView) Models 

func (v LayeredSplitView) Models() []ModelInfo

Models returns model catalog metadata from the generic LLM reader.

func (LayeredSplitView) ProviderDescriptions 

func (v LayeredSplitView) ProviderDescriptions() []ProviderDescription

ProviderDescriptions returns provider descriptions from the generic LLM reader.

func (LayeredSplitView) Providers 

func (v LayeredSplitView) Providers() []ProviderInfo

Providers returns provider catalog metadata from the generic LLM reader.

func (LayeredSplitView) ResolveLLM 

func (v LayeredSplitView) ResolveLLM(scopeID string, principalSlug string, modelID string) (LLMResult, bool)

ResolveLLM materializes an LLM target from the reader layer that resolved it.

func (LayeredSplitView) ResolveLLMIDs 

func (v LayeredSplitView) ResolveLLMIDs(scopeID string, principalSlug string, modelID string) (LayeredLLMIDs, bool)

ResolveLLMIDs resolves a per-key LLM override first, then falls back to the first executable target in the generic LLM route.

func (LayeredSplitView) ResolveLLMPlan 

func (v LayeredSplitView) ResolveLLMPlan(scopeID string, principalSlug string, modelID string) (LLMPlan, bool)

ResolveLLMPlan materializes a complete LLM route tree from the reader layer that resolved it.

func (LayeredSplitView) ResolveLLMPlanIDs 

func (v LayeredSplitView) ResolveLLMPlanIDs(
	scopeID string,
	principalSlug string,
	modelID string,
) (LayeredLLMPlanIDs, bool)

ResolveLLMPlanIDs resolves a per-key LLM override first, then falls back to the generic LLM reader.

func (LayeredSplitView) ResolveMCP 

func (v LayeredSplitView) ResolveMCP(scopeID string, pathSuffix string) (MCPResult, bool)

ResolveMCP materializes an MCP path lookup from the selected MCP reader layer.

func (LayeredSplitView) ResolveMCPIDs 

func (v LayeredSplitView) ResolveMCPIDs(scopeID string, pathSuffix string) (LayeredMCPResultIDs, bool)

ResolveMCPIDs resolves direct server paths from the MCP server reader and profile paths from the MCP profile reader.

func (LayeredSplitView) ResolveMCPInitialize 

func (v LayeredSplitView) ResolveMCPInitialize(
	scopeID string,
	pathSuffix string,
) (MCPInitializeResult, bool)

ResolveMCPInitialize materializes MCP initialize servers from the selected MCP reader layer.

func (LayeredSplitView) ResolveMCPInitializeIDs 

func (v LayeredSplitView) ResolveMCPInitializeIDs(scopeID string, pathSuffix string) (LayeredMCPInitializeIDs, bool)

ResolveMCPInitializeIDs resolves MCP initialize servers from the selected MCP reader layer.

func (LayeredSplitView) ResolveMCPServer 

func (v LayeredSplitView) ResolveMCPServer(serverID string) (MCPServerInfo, bool)

ResolveMCPServer returns MCP server catalog metadata from the static MCP server reader.

func (LayeredSplitView) ResolveMCPToolIDs 

func (v LayeredSplitView) ResolveMCPToolIDs(
	scopeID string,
	pathSuffix string,
	exposedTool string,
) (LayeredMCPToolIDs, bool)

ResolveMCPToolIDs resolves one MCP tool from the selected MCP reader layer.

func (LayeredSplitView) ResolveModel 

func (v LayeredSplitView) ResolveModel(modelID string) (ModelInfo, bool)

ResolveModel returns model catalog metadata from the generic LLM reader.

func (LayeredSplitView) ResolveProvider 

func (v LayeredSplitView) ResolveProvider(providerID string) (ProviderInfo, bool)

ResolveProvider returns provider catalog metadata from the generic LLM reader.

func (LayeredSplitView) V1ModelsJSON 

func (v LayeredSplitView) V1ModelsJSON() ([]byte, error)

V1ModelsJSON renders model catalog metadata from the generic LLM reader.

func (LayeredSplitView) V1ModelsJSONForProvider 

func (v LayeredSplitView) V1ModelsJSONForProvider(providerID string) ([]byte, error)

V1ModelsJSONForProvider renders provider-filtered model catalog metadata from the generic LLM reader.

type LayeredSplitViewOptions 

type LayeredSplitViewOptions struct {
	// LLMDefaultPrincipalSlug is used in the generic LLM reader when the per-key
	// reader has no route for the verified principal. When empty, the generic
	// reader is queried with the verified principal slug.
	LLMDefaultPrincipalSlug string
}

LayeredSplitViewOptions configure fallback behavior for a four-layer split view.

type MCPInitializeIDs 

type MCPInitializeIDs struct {
	PathSID uint32
	Auth    MCPProfileAuthIDs
	Servers []MCPUpstreamServerIDs
}

MCPInitializeIDs is the allocation-minimizing result for MCP initialize. It contains the upstream servers behind a path, including the effective auth and secret refs selected for that path.

type MCPInitializeResult 

type MCPInitializeResult struct {
	Path    string
	Auth    MCPProfileAuth
	Servers []MCPUpstreamServer
}

MCPInitializeResult is the string-materialized result for MCP initialize.

type MCPOAuthConfig 

type MCPOAuthConfig struct {
	TokenEndpoint string
	ClientID      string
	Audience      string
	Scopes        []string
}

MCPOAuthConfig stores normalized OAuth settings for MCP profile auth. Secret material is still represented only by SecretRef on the containing profile auth record.

type MCPOAuthConfigIDs 

type MCPOAuthConfigIDs struct {
	TokenEndpointSID uint32
	ClientIDSID      uint32
	AudienceSID      uint32
	ScopesSID        uint32
}

MCPOAuthConfigIDs is the string-table ID form of MCPOAuthConfig.

type MCPPath 

type MCPPath struct {
	ScopeID string
	Path    string
	Auth    MCPProfileAuth
	Tools   []MCPTool
}

MCPPath is an inspector record for one MCP path and its effective tool bindings in a scope.

type MCPProfile 

type MCPProfile struct {
	Path  string
	Auth  MCPProfileAuth
	Tools []MCPToolBinding
}

MCPProfile describes one MCP path suffix within a scope and the tools exposed through that path. Path is the normalized suffix after the HTTP layer strips the MCP prefix.

type MCPProfileAuth 

type MCPProfileAuth struct {
	Type      string
	Provider  string
	SecretRef string
	OAuth     MCPOAuthConfig
}

MCPProfileAuth describes the client-facing authentication required before a request may use an MCP profile path. Type is a normalized mode such as "none", "api-key", or "oauth-token"; Provider optionally selects the Plum auth provider implementation for that type, such as "builtin" or "custom". SecretRef is a reference only and must never contain secret material.

type MCPProfileAuthIDs 

type MCPProfileAuthIDs struct {
	TypeSID     uint32
	ProviderSID uint32
	SecretSID   uint32
	OAuth       MCPOAuthConfigIDs
}

MCPProfileAuthIDs is the string-table ID form of MCPProfileAuth.

type MCPResult 

type MCPResult struct {
	Path  string
	Auth  MCPProfileAuth
	Tools []MCPTool
}

MCPResult is the string-materialized form of an MCP path lookup.

type MCPResultIDs 

type MCPResultIDs struct {
	PathSID   uint32
	ToolsetID uint32
	Auth      MCPProfileAuthIDs
	Tools     []MCPToolIDs
}

MCPResultIDs is the allocation-minimizing representation of an MCP path lookup. Tools contains the precomputed effective allowset for the resolved path.

type MCPServer 

type MCPServer struct {
	ID        string
	Endpoint  string
	SecretRef string
	AuthType  string
}

MCPServer describes an upstream MCP server that can be referenced by profile tool bindings. SecretRef and AuthType are defaults that a profile binding may override before data reaches this package.

type MCPServerInfo 

type MCPServerInfo struct {
	ID        string
	Endpoint  string
	SecretRef string
	AuthType  string
}

MCPServerInfo is the string-materialized metadata for one upstream MCP server stored in the pack. It is intended for diagnostics and EP setup inspection. SecretRef is a ref only; secret material is never stored in the pack.

type MCPTool 

type MCPTool struct {
	ExposedName    string
	Server         string
	ServerEndpoint string
	Tool           string
	SecretRef      string
	AuthType       string
}

MCPTool is the string-materialized form of one MCP tool binding.

type MCPToolBinding 

type MCPToolBinding struct {
	ExposedName string
	Server      string
	Tool        string
	SecretRef   string
	AuthType    string
}

MCPToolBinding maps an exposed tool name to an upstream MCP server/tool pair. Profile routes with multiple servers typically expose names such as "github__list-repos" to keep the upstream identity unambiguous.

type MCPToolIDs 

type MCPToolIDs struct {
	ExposedNameSID    uint32
	ServerID          uint32
	ServerSID         uint32
	ServerEndpointSID uint32
	ToolSID           uint32
	SecretSID         uint32
	AuthTypeSID       uint32
}

MCPToolIDs is the allocation-minimizing representation of one MCP tool binding. String fields are returned as string-table IDs and can be materialized with Reader.String when needed.

type MCPUpstreamServer 

type MCPUpstreamServer struct {
	Server    string
	Endpoint  string
	SecretRef string
	AuthType  string
}

MCPUpstreamServer is the string-materialized form of one upstream server needed to initialize a resolved MCP path.

type MCPUpstreamServerIDs 

type MCPUpstreamServerIDs struct {
	ServerID    uint32
	ServerSID   uint32
	EndpointSID uint32
	SecretSID   uint32
	AuthTypeSID uint32
}

MCPUpstreamServerIDs is the allocation-minimizing representation of one upstream MCP server needed to initialize a resolved MCP path.

type Manifest 

type Manifest struct {
	FormatVersion uint32
	Checksum      uint64
	SizeBytes     uint64
}

Manifest is the minimal external metadata needed to reject stale or corrupted blobs before the reader is made visible to the enforcement data path. A real CP envelope would add generation IDs, project/workspace labels, timestamps, and a signature. The pack package keeps only the fields it can validate locally.

func BuildWithManifest 

func BuildWithManifest(input Input) ([]byte, Manifest, error)

BuildWithManifest builds a pack blob and returns the metadata needed to validate that exact blob before opening it in an enforcement point.

func ReadManifest 

func ReadManifest(blob []byte) (Manifest, error)

ReadManifest extracts the self-describing metadata from a complete pack blob. It reads only the pack header and does not perform a full Open validation.

type MappedSplitBundleKey 

type MappedSplitBundleKey struct {
	Lane      MappedSplitLane
	Partition int
}

MappedSplitBundleKey identifies one bundle component in the mapped-split layout.

func (MappedSplitBundleKey) Component 

func (k MappedSplitBundleKey) Component() string

Component returns the component name used in split-map bundle URLs.

func (MappedSplitBundleKey) IsPartitioned 

func (k MappedSplitBundleKey) IsPartitioned() bool

IsPartitioned reports whether the bundle key points at a partitioned lane.

type MappedSplitChange 

type MappedSplitChange struct {
	Kind          MappedSplitChangeKind
	PrincipalSlug string
	PathSuffix    string
}

MappedSplitChange describes an already-classified producer change. Cherry uses it only to compute the affected bundle; source-record inference remains outside the root package.

type MappedSplitChangeKind 

type MappedSplitChangeKind string

MappedSplitChangeKind identifies the explicitly classified change lane for affected-bundle planning. 

const (
	// MappedSplitChangeLLMGeneric means default LLM routing, providers, models,
	// or platform LLM secret refs changed.
	MappedSplitChangeLLMGeneric MappedSplitChangeKind = "llm-generic"
	// MappedSplitChangeMCPServers means direct MCP server catalog/path policy or
	// platform MCP secret refs changed.
	MappedSplitChangeMCPServers MappedSplitChangeKind = "mcp-servers"
	// MappedSplitChangeLLMUserKey means a principal/key-specific LLM route,
	// secret ref, or rate policy changed.
	MappedSplitChangeLLMUserKey MappedSplitChangeKind = "llm-user-key"
	// MappedSplitChangeMCPUserProfile means a user/profile MCP path or selected
	// tool binding changed.
	MappedSplitChangeMCPUserProfile MappedSplitChangeKind = "mcp-user-profile"
)

type MappedSplitLane 

type MappedSplitLane string

MappedSplitLane identifies a stable mapped-split delivery lane. 

const (
	// MappedSplitLaneLLMGeneric is the low-churn lane for default LLM routing,
	// providers, models, and platform secret refs.
	MappedSplitLaneLLMGeneric MappedSplitLane = "llm-generic"
	// MappedSplitLaneMCPServers is the low-churn lane for direct MCP server
	// paths such as /mcp/s/<server> and platform secret refs.
	MappedSplitLaneMCPServers MappedSplitLane = "mcp-servers"
	// MappedSplitLaneLLMUserKey is the partitioned lane for key-specific LLM
	// routes, BYOK secret refs, and rate policies.
	MappedSplitLaneLLMUserKey MappedSplitLane = "llm-user-key"
	// MappedSplitLaneMCPUserProfile is the partitioned lane for user/profile MCP
	// paths and selected tools.
	MappedSplitLaneMCPUserProfile MappedSplitLane = "mcp-user-profile"
)

type MappedSplitSpec 

type MappedSplitSpec struct {
	LLMUserKeyPartitions     int
	MCPUserProfilePartitions int
}

MappedSplitSpec holds the partition counts for the mapped-split layout.

func (MappedSplitSpec) AffectedBundle 

func (s MappedSplitSpec) AffectedBundle(change MappedSplitChange) (MappedSplitBundleKey, error)

AffectedBundle returns the mapped split bundle touched by an explicitly classified producer change.

func (MappedSplitSpec) CatalogBundle 

func (s MappedSplitSpec) CatalogBundle(lane MappedSplitLane) (MappedSplitBundleKey, error)

CatalogBundle returns a bundle key for a low-churn catalog/default lane.

func (MappedSplitSpec) LLMUserKeyBundle 

func (s MappedSplitSpec) LLMUserKeyBundle(principalSlug string) (MappedSplitBundleKey, error)

LLMUserKeyBundle returns the partitioned bundle key for a principal slug.

func (MappedSplitSpec) LLMUserKeyPartition 

func (s MappedSplitSpec) LLMUserKeyPartition(principalSlug string) (int, error)

LLMUserKeyPartition returns the deterministic partition for a principal slug.

func (MappedSplitSpec) MCPUserProfileBundle 

func (s MappedSplitSpec) MCPUserProfileBundle(pathSuffix string) (MappedSplitBundleKey, error)

MCPUserProfileBundle returns the partitioned bundle key for an MCP path suffix.

func (MappedSplitSpec) MCPUserProfilePartition 

func (s MappedSplitSpec) MCPUserProfilePartition(pathSuffix string) (int, error)

MCPUserProfilePartition returns the deterministic partition for an MCP path suffix.

func (MappedSplitSpec) Validate 

func (s MappedSplitSpec) Validate() error

Validate verifies that configured partitioned lanes can be addressed.

type Model 

type Model struct {
	ID                        string
	Provider                  string
	Name                      string
	Mode                      string
	Capabilities              []string
	Modalities                ModelModalities
	AdditionalPricePerMillion ModelCatalogObject
	Limits                    ModelCatalogObject
	MetadataJSON              string
}

Model describes a logical model name accepted by enforcement requests. Provider must reference an entry in Input.Providers. Name is the upstream model name sent to the selected provider after routing has been resolved.

Mode, Capabilities, Modalities, AdditionalPricePerMillion, and Limits preserve normalized catalog data for model listing, capability checks, request shaping, and cost calculation. MetadataJSON is intentionally opaque to Cherry so producers can retain aliases, options, descriptions, source URLs, and future provider-specific fields without forcing those fields into the binary schema.

type ModelCatalogObject 

type ModelCatalogObject map[string]json.RawMessage

ModelCatalogObject is an open normalized model-catalog object. It is used for source fields whose key sets vary by provider or mode, such as limits and additional price dimensions.

type ModelInfo 

type ModelInfo struct {
	ID                        string
	Provider                  string
	Name                      string
	Mode                      string
	Capabilities              []string
	Modalities                ModelModalities
	AdditionalPricePerMillion ModelCatalogObject
	Limits                    ModelCatalogObject
	MetadataJSON              string
}

ModelInfo is the string-materialized metadata for one model stored in the pack. MetadataJSON is the raw normalized catalog object supplied by the producer.

type ModelModalities 

type ModelModalities struct {
	Input  []string `json:"input,omitempty"`
	Output []string `json:"output,omitempty"`
}

ModelModalities describes the input and output modalities supported by a model catalog entry.

type OpenedBundle 

type OpenedBundle struct {
	Metadata BundleMetadata
	Blob     []byte
	Reader   Reader
}

OpenedBundle is the result of opening a delivered bundle. Reader is validated and ready for enforcement queries; Blob is retained because Reader references that immutable byte slice.

func OpenBundleZstd 

func OpenBundleZstd(compressed []byte) (OpenedBundle, error)

OpenBundleZstd decodes a zstd bundle artifact, validates the embedded pack against the bundle manifest, and returns a ready-to-query Reader.

type OpenedLayeredSplitBundle 

type OpenedLayeredSplitBundle struct {
	LLMGeneric  OpenedBundle
	LLMKeys     OpenedBundle
	MCPServers  OpenedBundle
	MCPProfiles OpenedBundle
	View        LayeredSplitView
}

OpenedLayeredSplitBundle is the result of opening four independently rebuilt bundle artifacts for generic LLM policy, per-key LLM overrides, direct MCP server paths, and MCP profile paths.

func OpenLayeredSplitBundleZstd 

func OpenLayeredSplitBundleZstd(
	llmGenericCompressed []byte,
	llmKeysCompressed []byte,
	mcpServersCompressed []byte,
	mcpProfilesCompressed []byte,
) (OpenedLayeredSplitBundle, error)

OpenLayeredSplitBundleZstd opens four split bundle artifacts using default compatibility checks.

func OpenLayeredSplitBundleZstdWithOptions 

func OpenLayeredSplitBundleZstdWithOptions(
	llmGenericCompressed []byte,
	llmKeysCompressed []byte,
	mcpServersCompressed []byte,
	mcpProfilesCompressed []byte,
	options LayeredSplitBundleOptions,
) (OpenedLayeredSplitBundle, error)

OpenLayeredSplitBundleZstdWithOptions opens four split bundle artifacts and validates optional generation, checksum, and catalog expectations.

type OpenedSplitBundle 

type OpenedSplitBundle struct {
	LLM  OpenedBundle
	MCP  OpenedBundle
	View SplitView
}

OpenedSplitBundle is the result of opening paired LLM and MCP bundle artifacts. It retains each opened component bundle and exposes the composed immutable SplitView for enforcement queries.

func OpenSplitBundleZstd 

func OpenSplitBundleZstd(llmCompressed []byte, mcpCompressed []byte) (OpenedSplitBundle, error)

OpenSplitBundleZstd opens paired LLM and MCP bundle artifacts using the existing single-bundle envelope and validates that they describe the same control-plane selection and concrete scope set.

func OpenSplitBundleZstdWithOptions 

func OpenSplitBundleZstdWithOptions(
	llmCompressed []byte,
	mcpCompressed []byte,
	options SplitBundleOptions,
) (OpenedSplitBundle, error)

OpenSplitBundleZstdWithOptions opens paired LLM and MCP bundle artifacts and validates optional generation, checksum, and catalog expectations.

type Principal 

type Principal struct {
	Slug string
	// ModelRoutes maps requested model ID to the already-compiled final target
	// route for that request. Route is kept as a compatibility/default helper for
	// small tests and synthetic inputs that only need one model route.
	ModelRoutes map[string]RoutePlan
	Route       RoutePlan
	Rate        RatePolicy
}

Principal describes the compiled LLM routes for one verified principal slug in one scope. The verifier that turns key or token material into Slug is outside this package.

type PrincipalInfo 

type PrincipalInfo struct {
	ScopeID         string
	PrincipalSlug   string
	RequestedModels []string
}

PrincipalInfo is an inspector record for one principal slug in a scope and the requested model IDs it can route.

type PrincipalRoute 

type PrincipalRoute struct {
	ScopeID        string
	PrincipalSlug  string
	RequestedModel string
	RouteKind      RouteKind
	Provider       string
	Model          string
	SecretRef      string
	Rate           RatePolicy
}

PrincipalRoute is an inspector record for one principal/requested-model route stored in a scope. It is derived from the packed indexes and is not used by the hot request path.

type Provider 

type Provider struct {
	ID               string
	ParentProviderID string
	Kind             string
	BackendSchema    string
	Endpoint         string
	SecretRef        string
	AuthType         string
	PathPrefix       string
	Extra            map[string]string
}

Provider describes an upstream LLM provider available to compiled LLM routes. BackendSchema is required and identifies the request/response adapter schema an enforcement point should use for this provider, such as "openai", "anthropic", "gcpvertexai", "gcpanthropic", or "awsbedrock". Kind is the higher-level provider family, while BackendSchema may select a more specific compatibility or hosting backend within that family.

SecretRef is a reference to secret material, not the secret material itself. AuthType identifies the credential scheme used to authenticate requests to this provider (e.g. "bearer"). Empty string is treated as "bearer" by enforcement points for backwards compatibility.

type ProviderDescription 

type ProviderDescription struct {
	ID               string
	ParentProviderID string
	Kind             string
	BackendSchema    string
	Endpoint         string
	AuthSecretRef    string
	AuthType         string
	PathPrefix       string
	ModelIDs         []string
	Extra            map[string]string
}

ProviderDescription describes one provider available from the loaded bundle. It is intended for diagnostics and admin UIs that need to list possible LLM providers and the normalized model IDs routed through each provider.

AuthType is the effective provider auth scheme. An empty provider AuthType is reported as "bearer" for backwards compatibility with enforcement points.

type ProviderInfo 

type ProviderInfo struct {
	ID               string
	ParentProviderID string
	Kind             string
	BackendSchema    string
	Endpoint         string
	SecretRef        string
	AuthType         string
	PathPrefix       string
	Extra            map[string]string
}

ProviderInfo is the string-materialized metadata for one provider stored in the pack. It is intended for diagnostics and EP setup inspection.

type RatePolicy 

type RatePolicy struct {
	USDPerDayCents uint64
	RPM            uint32
	OnExceed       string
}

RatePolicy is immutable rate-limit metadata attached to a principal route. Mutable counters are intentionally not stored in the pack.

type RatePolicyIDs 

type RatePolicyIDs struct {
	USDPerDayCents uint64
	RPM            uint32
	OnExceedSID    uint32
}

type Reader 

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

Reader is an immutable, in-place view of a validated pack blob. A Reader is safe to share between goroutines as long as callers do not mutate the underlying blob slice passed to Open.

func Open 

func Open(blob []byte) (Reader, error)

Open validates a pack blob and returns an immutable Reader over the same byte slice. The caller must keep blob alive and must not mutate it while any Reader is in use.

Open checks the magic header, format version, checksum, and section offsets. It does not validate an external envelope; use OpenWithManifest for delivered bundles that carry manifest metadata.

func OpenWithManifest 

func OpenWithManifest(blob []byte, manifest Manifest) (Reader, error)

OpenWithManifest validates externally delivered manifest metadata before opening the blob itself. This mirrors the enforcement-point load path where the control plane sends both the compact content and an envelope describing it.

func (Reader) BlobSize 

func (r Reader) BlobSize() int

BlobSize reports the number of bytes retained by this Reader.

func (Reader) MCPPaths 

func (r Reader) MCPPaths(scopeID string) ([]MCPPath, bool)

MCPPaths returns inspector records for every MCP path in scopeID. The boolean is false when the scope is not present.

func (Reader) MCPServers 

func (r Reader) MCPServers() []MCPServerInfo

MCPServers returns all upstream MCP server catalog entries in deterministic order by server ID.

func (Reader) ModelCapability 

func (r Reader) ModelCapability(modelID string, capability string) bool

ModelCapability reports whether a model has capability in its normalized catalog metadata.

func (Reader) Models 

func (r Reader) Models() []ModelInfo

Models returns all model catalog entries in deterministic order by model ID.

func (Reader) PrincipalRoutes 

func (r Reader) PrincipalRoutes(scopeID string) ([]PrincipalRoute, bool)

PrincipalRoutes returns inspector records for every principal/requested-model route in scopeID. The boolean is false when the scope is not present.

func (Reader) Principals 

func (r Reader) Principals(scopeID string) ([]PrincipalInfo, bool)

Principals returns unique principal slugs in scopeID with their requested model allowsets. The boolean is false when the scope is not present.

func (Reader) ProviderDescriptions 

func (r Reader) ProviderDescriptions() []ProviderDescription

ProviderDescriptions returns every LLM provider available in this bundle, including its effective auth type and the model IDs attached to it.

func (Reader) Providers 

func (r Reader) Providers() []ProviderInfo

Providers returns all provider catalog entries in deterministic order by provider ID.

func (Reader) ResolveLLM 

func (r Reader) ResolveLLM(scopeID string, principalSlug string, modelID string) (LLMResult, bool)

ResolveLLM resolves an LLM request and materializes the result as strings. It is easier to inspect than ResolveLLMIDs but allocates for string results and is therefore better suited to diagnostics, tests, and CLIs than the hot path.

func (Reader) ResolveLLMIDs 

func (r Reader) ResolveLLMIDs(scopeID string, principalSlug string, modelID string) (LLMIDs, bool)

ResolveLLMIDs resolves an LLM request to the first executable target in the compiled route tree. It is retained for callers that only understand a single provider/model target. Enforcement points that implement fallback or weighted split behavior should use ResolveLLMPlanIDs instead.

func (Reader) ResolveLLMPlan 

func (r Reader) ResolveLLMPlan(scopeID string, principalSlug string, modelID string) (LLMPlan, bool)

ResolveLLMPlan resolves an LLM request and materializes the complete compiled route tree as strings. It is intended for diagnostics and example code; hot paths should prefer ResolveLLMPlanIDs.

func (Reader) ResolveLLMPlanIDs 

func (r Reader) ResolveLLMPlanIDs(scopeID string, principalSlug string, modelID string) (LLMPlanIDs, bool)

ResolveLLMPlanIDs resolves an LLM request to the compiled route tree as integer IDs into pack tables.

scopeID identifies the enforcement scope, principalSlug is the verified principal produced by an external verifier, and modelID is the requested model from the LLM request body. Target nodes in the returned plan can be dereferenced with String or used directly by callers that intern provider, model, endpoint, and secret-ref tables elsewhere.

The boolean is false when the scope, principal/model route, or requested model is not present in the pack.

func (Reader) ResolveMCP 

func (r Reader) ResolveMCP(scopeID string, pathSuffix string) (MCPResult, bool)

ResolveMCP materializes an MCP path lookup as strings. It is intended for diagnostics and control surfaces; use ResolveMCPIDs or ResolveMCPToolIDs for lower-allocation data paths.

func (Reader) ResolveMCPIDs 

func (r Reader) ResolveMCPIDs(scopeID string, pathSuffix string) (MCPResultIDs, bool)

ResolveMCPIDs resolves an MCP path suffix to the effective toolset IDs for a scope. Use this when the caller needs to list or inspect the whole MCP profile. Use ResolveMCPToolIDs when forwarding a single tool call.

func (Reader) ResolveMCPInitialize 

func (r Reader) ResolveMCPInitialize(scopeID string, pathSuffix string) (MCPInitializeResult, bool)

ResolveMCPInitialize materializes the upstream server set needed for MCP initialize. Use ResolveMCPInitializeIDs on lower-allocation data paths.

func (Reader) ResolveMCPInitializeIDs 

func (r Reader) ResolveMCPInitializeIDs(scopeID string, pathSuffix string) (MCPInitializeIDs, bool)

ResolveMCPInitializeIDs resolves an MCP path to the upstream server set needed for MCP initialize. Each server appears once with the effective auth and secret ref selected for that path.

func (Reader) ResolveMCPServer 

func (r Reader) ResolveMCPServer(serverID string) (MCPServerInfo, bool)

ResolveMCPServer returns catalog metadata for one MCP server ID.

func (Reader) ResolveMCPToolIDs 

func (r Reader) ResolveMCPToolIDs(scopeID string, pathSuffix string, exposedTool string) (MCPToolIDs, bool)

ResolveMCPToolIDs resolves one exposed tool name without materializing the whole profile toolset. Use ResolveMCPIDs when the caller needs to list a profile; use this method on the MCP forwarding path.

func (Reader) ResolveModel 

func (r Reader) ResolveModel(modelID string) (ModelInfo, bool)

ResolveModel returns catalog metadata for one model ID.

func (Reader) ResolveProvider 

func (r Reader) ResolveProvider(providerID string) (ProviderInfo, bool)

ResolveProvider returns catalog metadata for one provider ID.

func (Reader) ScopeIDs 

func (r Reader) ScopeIDs() []string

ScopeIDs returns all scope IDs stored in the pack in sorted order.

func (Reader) String 

func (r Reader) String(id uint32) string

String returns the string-table value for id. It returns an empty string for an invalid string ID, matching the internal reader behavior.

func (Reader) V1ModelsJSON 

func (r Reader) V1ModelsJSON() ([]byte, error)

V1ModelsJSON renders the loaded model catalog in an OpenAI-compatible /v1/models response shape. It is derived from Model.MetadataJSON when present and falls back to the indexed model fields otherwise.

func (Reader) V1ModelsJSONForProvider 

func (r Reader) V1ModelsJSONForProvider(providerID string) ([]byte, error)

V1ModelsJSONForProvider renders a /v1/models response shape containing only models whose base provider matches providerID.

type RetryPolicy 

type RetryPolicy struct {
	RetryOn         string
	PerTryTimeoutMS uint32
}

RetryPolicy describes retry/fallback behavior attached to a chain route node. Cherry stores this metadata verbatim; the enforcement point decides how to interpret RetryOn values such as "401" or "connect-failure,reset,5xx".

type RouteKind 

type RouteKind string

RouteKind identifies the shape of an LLM route plan node. 

const (
	// RouteKindTarget sends the request to one concrete provider/model target.
	RouteKindTarget RouteKind = "target"
	// RouteKindChain tries child route plans in order. Retry describes when the
	// next child should be attempted by the enforcement point.
	RouteKindChain RouteKind = "chain"
	// RouteKindSplit chooses among weighted child route plans.
	RouteKindSplit RouteKind = "split"
)

type RoutePlan 

type RoutePlan struct {
	Kind     RouteKind
	Provider string
	Model    string
	// SecretRef overrides the selected provider default for target nodes. It is
	// always a reference to secret material, never the material itself.
	SecretRef string
	Retry     *RetryPolicy
	Children  []RoutePlan
	Split     []WeightedRoutePlan
	Metadata  map[string]string
}

RoutePlan is a compiled LLM route tree for a principal and requested model. A zero Kind with Provider/Model set is treated as a target for compatibility with simple callers. The route must already reflect external rule precedence and overrides.

type Scope 

type Scope struct {
	ID          string
	Principals  []Principal
	MCPProfiles []MCPProfile
}

Scope is one enforcement partition in the pack, commonly a workspace. A project bundle can contain multiple workspace scopes.

type SnapshotCadence 

type SnapshotCadence string

SnapshotCadence describes how a caller normally publishes new immutable bundle generations. 

const (
	// SnapshotCadencePeriodic means the caller normally publishes snapshots on a
	// timer or poll loop, while selected high-priority changes may still request
	// an immediate snapshot.
	SnapshotCadencePeriodic SnapshotCadence = "periodic"
	// SnapshotCadenceReactive means every observed change should request an
	// immediate snapshot.
	SnapshotCadenceReactive SnapshotCadence = "reactive"
)

type SnapshotChange 

type SnapshotChange struct {
	Kind          SnapshotChangeKind
	ScopeID       string
	PrincipalSlug string
	MCPPath       string
	Reason        string
}

SnapshotChange is a normalized change signal that can be used to decide whether to publish an immutable snapshot before the next periodic cadence.

ScopeID, PrincipalSlug, and MCPPath are optional routing labels for callers that maintain scope-sharded overlays. They are not used for verification.

type SnapshotChangeKind 

type SnapshotChangeKind string

SnapshotChangeKind classifies a normalized change after the external system has already handled source records, tenancy, key verification, and rule merge. 

const (
	// SnapshotChangeUnknown is for callers that cannot classify the change.
	SnapshotChangeUnknown SnapshotChangeKind = "unknown"
	// SnapshotChangeStaticCatalog covers mostly static provider, model, or MCP
	// server catalog metadata.
	SnapshotChangeStaticCatalog SnapshotChangeKind = "static_catalog"
	// SnapshotChangeScope covers adding or removing an enforcement scope.
	SnapshotChangeScope SnapshotChangeKind = "scope"
	// SnapshotChangePrincipalBinding covers verifier-visible principal
	// membership or reachability changes. A changed external key should usually
	// be mapped to this kind after verification and normalization.
	SnapshotChangePrincipalBinding SnapshotChangeKind = "principal_binding"
	// SnapshotChangePrincipalRoute covers an LLM route change for a principal.
	SnapshotChangePrincipalRoute SnapshotChangeKind = "principal_route"
	// SnapshotChangeRatePolicy covers immutable rate policy metadata changes.
	SnapshotChangeRatePolicy SnapshotChangeKind = "rate_policy"
	// SnapshotChangeSecretRef covers effective provider, route, MCP server, or
	// MCP tool secret-ref changes. It must never carry secret material.
	SnapshotChangeSecretRef SnapshotChangeKind = "secret_ref"
	// SnapshotChangeMCPProfile covers adding or removing an MCP path/profile.
	SnapshotChangeMCPProfile SnapshotChangeKind = "mcp_profile"
	// SnapshotChangeMCPToolBinding covers the tool bindings under an MCP profile.
	SnapshotChangeMCPToolBinding SnapshotChangeKind = "mcp_tool_binding"
)

func DefaultReactiveSnapshotKinds 

func DefaultReactiveSnapshotKinds() []SnapshotChangeKind

DefaultReactiveSnapshotKinds returns mutable policy/profile change kinds that should normally interrupt a periodic snapshot cadence.

type SnapshotDecision 

type SnapshotDecision struct {
	TakeSnapshot  bool
	Reason        string
	ChangedScopes []string
}

SnapshotDecision is the result of evaluating observed changes against a SnapshotPolicy.

type SnapshotPolicy 

type SnapshotPolicy struct {
	// Cadence defaults to SnapshotCadencePeriodic when empty.
	Cadence SnapshotCadence
	// ReactiveKinds lists changes that should interrupt a periodic cadence. A nil
	// slice uses DefaultReactiveSnapshotKinds. An empty non-nil slice disables
	// reactive interrupts under SnapshotCadencePeriodic.
	ReactiveKinds []SnapshotChangeKind
}

SnapshotPolicy decides when observed normalized changes should request a new immutable snapshot generation.

func DefaultSnapshotPolicy 

func DefaultSnapshotPolicy() SnapshotPolicy

DefaultSnapshotPolicy returns Cherry's recommended starting point for V2-style incremental update planning: keep a periodic cadence for static catalog churn, but react immediately to mutable policy/profile surfaces.

func (SnapshotPolicy) Decide 

func (p SnapshotPolicy) Decide(changes []SnapshotChange) SnapshotDecision

Decide evaluates whether the observed changes should trigger a new immutable snapshot before the next periodic cadence.

type SplitBundleOptions 

type SplitBundleOptions struct {
	GenerationID         string
	LLMPackChecksum      uint64
	MCPPackChecksum      uint64
	RequiredLLMProviders []string
	RequiredLLMModels    []string
	RequiredMCPServers   []string
}

SplitBundleOptions are optional compatibility requirements checked while opening paired LLM/MCP bundles. Zero values keep the default behavior: validate each bundle's own manifest plus the shared scope selection.

type SplitView 

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

SplitView composes independently built LLM and MCP readers into one immutable enforcement-point view. It does not change the pack format; callers can swap a new SplitView atomically while in-flight requests continue using the previous readers.

String IDs returned by LLM methods belong to the LLM reader, and string IDs returned by MCP methods belong to the MCP reader. Use LLMString and MCPString to materialize IDs from the correct string table.

func NewSplitView 

func NewSplitView(llm Reader, mcp Reader) SplitView

NewSplitView returns an immutable view over independently opened LLM and MCP readers. The readers are copied by value and still reference their original immutable blobs.

func (SplitView) LLMReader 

func (v SplitView) LLMReader() Reader

LLMReader returns the underlying LLM reader for inspector APIs not mirrored by SplitView.

func (SplitView) LLMString 

func (v SplitView) LLMString(id uint32) string

LLMString returns an LLM-reader string-table value.

func (SplitView) MCPReader 

func (v SplitView) MCPReader() Reader

MCPReader returns the underlying MCP reader for inspector APIs not mirrored by SplitView.

func (SplitView) MCPServers 

func (v SplitView) MCPServers() []MCPServerInfo

MCPServers returns MCP server catalog metadata from the MCP reader.

func (SplitView) MCPString 

func (v SplitView) MCPString(id uint32) string

MCPString returns an MCP-reader string-table value.

func (SplitView) ModelCapability 

func (v SplitView) ModelCapability(modelID string, capability string) bool

ModelCapability reports model capability from the LLM reader.

func (SplitView) Models 

func (v SplitView) Models() []ModelInfo

Models returns model catalog metadata from the LLM reader.

func (SplitView) ProviderDescriptions 

func (v SplitView) ProviderDescriptions() []ProviderDescription

ProviderDescriptions returns provider descriptions from the LLM reader.

func (SplitView) Providers 

func (v SplitView) Providers() []ProviderInfo

Providers returns provider catalog metadata from the LLM reader.

func (SplitView) ResolveLLM 

func (v SplitView) ResolveLLM(scopeID string, principalSlug string, modelID string) (LLMResult, bool)

ResolveLLM resolves and materializes an LLM request against the LLM reader.

func (SplitView) ResolveLLMIDs 

func (v SplitView) ResolveLLMIDs(scopeID string, principalSlug string, modelID string) (LLMIDs, bool)

ResolveLLMIDs resolves an LLM request against the LLM reader.

func (SplitView) ResolveLLMPlan 

func (v SplitView) ResolveLLMPlan(scopeID string, principalSlug string, modelID string) (LLMPlan, bool)

ResolveLLMPlan resolves and materializes an LLM route plan against the LLM reader.

func (SplitView) ResolveLLMPlanIDs 

func (v SplitView) ResolveLLMPlanIDs(scopeID string, principalSlug string, modelID string) (LLMPlanIDs, bool)

ResolveLLMPlanIDs resolves an LLM request against the LLM reader.

func (SplitView) ResolveMCP 

func (v SplitView) ResolveMCP(scopeID string, pathSuffix string) (MCPResult, bool)

ResolveMCP materializes an MCP path lookup from the MCP reader.

func (SplitView) ResolveMCPIDs 

func (v SplitView) ResolveMCPIDs(scopeID string, pathSuffix string) (MCPResultIDs, bool)

ResolveMCPIDs resolves an MCP path against the MCP reader.

func (SplitView) ResolveMCPInitialize 

func (v SplitView) ResolveMCPInitialize(scopeID string, pathSuffix string) (MCPInitializeResult, bool)

ResolveMCPInitialize materializes MCP initialize servers from the MCP reader.

func (SplitView) ResolveMCPInitializeIDs 

func (v SplitView) ResolveMCPInitializeIDs(scopeID string, pathSuffix string) (MCPInitializeIDs, bool)

ResolveMCPInitializeIDs resolves MCP initialize servers against the MCP reader.

func (SplitView) ResolveMCPServer 

func (v SplitView) ResolveMCPServer(serverID string) (MCPServerInfo, bool)

ResolveMCPServer returns MCP server catalog metadata from the MCP reader.

func (SplitView) ResolveMCPToolIDs 

func (v SplitView) ResolveMCPToolIDs(scopeID string, pathSuffix string, exposedTool string) (MCPToolIDs, bool)

ResolveMCPToolIDs resolves one MCP tool against the MCP reader.

func (SplitView) ResolveModel 

func (v SplitView) ResolveModel(modelID string) (ModelInfo, bool)

ResolveModel returns model catalog metadata from the LLM reader.

func (SplitView) ResolveProvider 

func (v SplitView) ResolveProvider(providerID string) (ProviderInfo, bool)

ResolveProvider returns provider catalog metadata from the LLM reader.

func (SplitView) V1ModelsJSON 

func (v SplitView) V1ModelsJSON() ([]byte, error)

V1ModelsJSON renders model catalog metadata from the LLM reader.

func (SplitView) V1ModelsJSONForProvider 

func (v SplitView) V1ModelsJSONForProvider(providerID string) ([]byte, error)

V1ModelsJSONForProvider renders provider-filtered model catalog metadata from the LLM reader.

type WeightedRoutePlan 

type WeightedRoutePlan struct {
	Weight uint32
	Plan   RoutePlan
}

WeightedRoutePlan is one weighted child under a split route node.

Source Files

View all Source files

Directories

Path Synopsis
source
transform
Package repl provides an embeddable diagnostic command executor for opened Cherry bundles.
 Package repl provides an embeddable diagnostic command executor for opened Cherry bundles.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.