catalog

type AetherLiveBackend ¶ added in v0.0.2

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

AetherLiveBackend persists the current catalog state with Aether KV CAS and retains immutable snapshots as TTL keys. Protocol leases remain explicit in the publication state; snapshot retention additionally uses native KV TTL.

func NewAetherLiveBackend(kv *aether.KV, options AetherLiveBackendOptions) (*AetherLiveBackend, error)

func (b *AetherLiveBackend) CompareAndSwapState(ctx context.Context, current LiveStateRecord, next LiveState) (bool, error)

func (b *AetherLiveBackend) LoadSnapshot(ctx context.Context, snapshotID string) (RetainedSnapshot, bool, error)

func (b *AetherLiveBackend) LoadState(ctx context.Context) (LiveStateRecord, error)

func (b *AetherLiveBackend) StoreSnapshot(ctx context.Context, snapshot RetainedSnapshot, ttl time.Duration) (RetainedSnapshot, error)

type AetherLiveBackendOptions ¶ added in v0.0.2

type AetherLiveBackendOptions struct {
	KeyPrefix string
	Scope     aether.KVScope
	UserID    string
	Workspace string
	Timeout   time.Duration
}

AetherLiveBackendOptions binds operational catalog state to one Aether KV namespace. Workspace scope is the default so separate coding projects can have independent live catalogs while sharing the same Aether deployment.

type AllowAllEntryAuthorizer ¶ added in v0.0.2

type AllowAllEntryAuthorizer struct{}

AllowAllEntryAuthorizer is intended for the explicitly single-user standalone runtime. Distributed/enterprise composition should supply an Aether-backed authorizer instead.

func (AllowAllEntryAuthorizer) AuthorizeCatalogEntry(context.Context, string, QueryBinding, spec.ToolCatalogEntry) (bool, error)

type BatchEntryAuthorizer ¶ added in v0.0.2

type BatchEntryAuthorizer interface {
	AuthorizeCatalogEntries(ctx context.Context, action string, binding QueryBinding, entries []spec.ToolCatalogEntry) ([]bool, error)
}

BatchEntryAuthorizer lets distributed adapters evaluate catalog entries in bounded transport batches while preserving the per-entry allow/deny result. LiveService validates result cardinality and fails the whole operation on a malformed or failed batch. EntryAuthorizer remains the standalone seam.

type BoundWorkspaceProvider ¶ added in v0.0.2

type BoundWorkspaceProvider struct {
	Provider       WorkspaceProvider
	LogicalDefault string
	BackendDefault string
}

BoundWorkspaceProvider maps only the selected logical default workspace to a backend-specific default. Other explicit workspaces pass through unchanged, preventing one configured MemoryLayer workspace from becoming every logical workspace's catalog.

func (p BoundWorkspaceProvider) LoadWorkspace(ctx context.Context, workspaceID string) (Catalog, error)

type Catalog ¶

type Catalog struct {
	// Revision is the deterministic content identity of the enabled catalog
	// snapshot. Providers may supply it; hosts recompute it after local overlays.
	Revision   string          `json:"revision,omitempty"`
	Tools      []ToolSpec      `json:"tools"`
	Skills     []SkillSpec     `json:"skills"`
	MCPServers []MCPServerSpec `json:"mcp_servers"`
}

Catalog is the discovered set of tools, skills, and MCP servers.

func WithComputedRevision(value Catalog) (Catalog, error)

type CatalogError ¶ added in v0.0.2

type CatalogError struct {
	Protocol spec.ToolCatalogError
}

CatalogError projects a stable ecosystem catalog error while remaining a Go error suitable for errors.As.

func (e *CatalogError) Error() string

type EntryAuthorizer ¶ added in v0.0.2

type EntryAuthorizer interface {
	AuthorizeCatalogEntry(ctx context.Context, action string, binding QueryBinding, entry spec.ToolCatalogEntry) (bool, error)
}

EntryAuthorizer independently decides discovery and describe access for one exact provider-qualified entry. Enterprise adapters should delegate this to Aether decisions; standalone mode uses AllowAllEntryAuthorizer explicitly.

type EntryAuthorizerFunc ¶ added in v0.0.2

type EntryAuthorizerFunc func(context.Context, string, QueryBinding, spec.ToolCatalogEntry) (bool, error)

EntryAuthorizerFunc adapts a function to EntryAuthorizer.

func (f EntryAuthorizerFunc) AuthorizeCatalogEntry(ctx context.Context, action string, binding QueryBinding, entry spec.ToolCatalogEntry) (bool, error)

type GenerationTombstone ¶ added in v0.0.2

type GenerationTombstone struct {
	ProviderID     string `json:"provider_id"`
	RegistrationID string `json:"registration_id"`
	Generation     string `json:"generation"`
	ProviderRoute  string `json:"provider_route,omitempty"`
	Sequence       uint64 `json:"sequence"`
	RetainUntil    string `json:"retain_until"`
}

GenerationTombstone remembers the final accepted sequence for a generation after it is replaced, expires, or is revoked.

type InvocationAuthorityProfile ¶ added in v0.0.2

type InvocationAuthorityProfile struct {
	Mode           string                             `json:"mode"`
	ResourceScope  []InvocationAuthorityResourceScope `json:"resource_scope"`
	OperationScope []string                           `json:"operation_scope"`
	MaxAccessLevel int32                              `json:"max_access_level"`
}

InvocationAuthorityProfile is a server-owned maximum downstream authority for one exact catalog entry. Workspace scope is always the exact trusted ToolCatalogContext workspace and is therefore not provider-configurable.

func (p InvocationAuthorityProfile) Validate() error

type InvocationAuthorityResolver ¶ added in v0.0.2

type InvocationAuthorityResolver interface {
	ResolveInvocationAuthority(context.Context, spec.ToolCatalogContext, spec.ToolCatalogEntry) (*InvocationAuthorityProfile, error)
}

InvocationAuthorityResolver supplies trusted deployment policy for an exact live entry. nil means no forwarded caller authority.

type InvocationAuthorityResolverFunc ¶ added in v0.0.2

type InvocationAuthorityResolverFunc func(context.Context, spec.ToolCatalogContext, spec.ToolCatalogEntry) (*InvocationAuthorityProfile, error)

func (f InvocationAuthorityResolverFunc) ResolveInvocationAuthority(ctx context.Context, catalogContext spec.ToolCatalogContext, entry spec.ToolCatalogEntry) (*InvocationAuthorityProfile, error)

type InvocationAuthorityResourceScope ¶ added in v0.0.2

type InvocationAuthorityResourceScope struct {
	ResourceType string   `json:"resource_type"`
	Patterns     []string `json:"patterns"`
}

InvocationAuthorityResourceScope is the catalog-private projection of one Aether authority-grant resource family. It deliberately does not live in the portable tool descriptor or invocation envelope.

type InvocationAuthorityRule ¶ added in v0.0.2

type InvocationAuthorityRule struct {
	Ref     spec.ToolReference         `json:"ref"`
	Profile InvocationAuthorityProfile `json:"profile"`
}

InvocationAuthorityRule binds a profile to one exact immutable tool reference. Revisions or generations changing require an explicit policy update rather than silently carrying authority onto new provider code.

type LiveBackend ¶ added in v0.0.2

type LiveBackend interface {
	LoadState(ctx context.Context) (LiveStateRecord, error)
	CompareAndSwapState(ctx context.Context, current LiveStateRecord, next LiveState) (bool, error)
	StoreSnapshot(ctx context.Context, snapshot RetainedSnapshot, ttl time.Duration) (RetainedSnapshot, error)
	LoadSnapshot(ctx context.Context, snapshotID string) (RetainedSnapshot, bool, error)
}

LiveBackend is the complete storage contract needed by LiveService. State replacement is CAS-protected; snapshots are immutable by SnapshotID. If a snapshot with the same ID already exists, StoreSnapshot returns that existing record rather than replacing it.

type LiveService ¶ added in v0.0.2

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

LiveService implements the ecosystem tool-catalog publication, lease, deterministic query/cursor, and exact describe semantics over LiveBackend.

func NewLiveService(backend LiveBackend, options LiveServiceOptions) (*LiveService, error)

func NewStandaloneLiveService(options LiveServiceOptions) (*LiveService, error)

func (s *LiveService) Describe(ctx context.Context, binding QueryBinding, request spec.ToolCatalogDescribeRequest) (spec.ToolCatalogDescribeResult, error)

func (s *LiveService) DescribeResolved(ctx context.Context, binding QueryBinding, request spec.ToolCatalogDescribeRequest) (ResolvedCatalogDescribeResult, error)

func (s *LiveService) Publish(ctx context.Context, binding MutationBinding, publication spec.ToolCatalogPublication) (spec.ToolCatalogMutationResult, error)

func (s *LiveService) Query(ctx context.Context, binding QueryBinding, query spec.ToolCatalogQuery) (spec.ToolCatalogPage, error)

func (s *LiveService) QueryResolved(ctx context.Context, binding QueryBinding, query spec.ToolCatalogQuery) (ResolvedCatalogPage, error)

func (s *LiveService) Renew(ctx context.Context, binding MutationBinding, request spec.ToolCatalogRenewRequest) (spec.ToolCatalogMutationResult, error)

func (s *LiveService) ResolveInvocation(ctx context.Context, binding QueryBinding, ref spec.ToolReference) (spec.ToolCatalogEntry, error)

func (s *LiveService) ResolveInvocationRecord(ctx context.Context, binding QueryBinding, ref spec.ToolReference) (ResolvedCatalogEntry, error)

func (s *LiveService) Revoke(ctx context.Context, binding MutationBinding, request spec.ToolCatalogRevokeRequest) (spec.ToolCatalogMutationResult, error)

type LiveServiceOptions ¶ added in v0.0.2

type LiveServiceOptions struct {
	Authorizer          EntryAuthorizer
	Liveness            PublicationLiveness
	InvocationAuthority InvocationAuthorityResolver
	CursorKey           []byte
	MaxLease            time.Duration
	TombstoneRetention  time.Duration
	SnapshotRetention   time.Duration
	MaxCASRetries       int
	Now                 func() time.Time
}

LiveServiceOptions controls bounded leases, replay protection, retained snapshots, and cursor integrity. CursorKey should be stable across replicas; when omitted a process-local random key is generated (appropriate for standalone mode only).

type LiveState ¶ added in v0.0.2

type LiveState struct {
	SchemaVersion  string                        `json:"schema_version"`
	Publications   []spec.ToolCatalogPublication `json:"publications"`
	ProviderRoutes []ProviderRouteBinding        `json:"provider_routes,omitempty"`
	Tombstones     []GenerationTombstone         `json:"tombstones,omitempty"`
}

LiveState is the backend-neutral, CAS-protected operational catalog state. Publications contain only the current generation for each provider registration. Tombstones reject delayed messages from replaced or revoked generations during a bounded replay-retention window.

type LiveStateRecord ¶ added in v0.0.2

type LiveStateRecord struct {
	State  LiveState
	Token  []byte
	Exists bool
}

LiveStateRecord is one backend read. Token is opaque and must be passed back unchanged to CompareAndSwapState. Exists distinguishes an absent initial state from a stored state.

type MCPServerSpec ¶

type MCPServerSpec struct {
	Name           string            `json:"name"`
	Command        string            `json:"command"`
	Args           []string          `json:"args,omitempty"`
	Env            []string          `json:"env,omitempty"`
	IdleTTLSeconds int               `json:"idle_ttl_seconds,omitempty"`
	Tools          []MCPToolSpec     `json:"tools,omitempty"`
	Source         *ResourceRevision `json:"source,omitempty"`
}

func (s MCPServerSpec) IdleTTL() time.Duration

type MCPToolSpec ¶

type MCPToolSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"input_schema,omitempty"`
	Enabled     bool            `json:"enabled"`
}

type MemoryBackend ¶ added in v0.0.2

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

MemoryBackend is the dependency-free LiveBackend used by standalone Sahara. It is safe for concurrent use within one process.

func NewMemoryBackend() *MemoryBackend

func (b *MemoryBackend) CompareAndSwapState(_ context.Context, current LiveStateRecord, next LiveState) (bool, error)

func (b *MemoryBackend) LoadSnapshot(_ context.Context, snapshotID string) (RetainedSnapshot, bool, error)

func (b *MemoryBackend) LoadState(context.Context) (LiveStateRecord, error)

func (b *MemoryBackend) StoreSnapshot(_ context.Context, snapshot RetainedSnapshot, ttl time.Duration) (RetainedSnapshot, error)

type MutationBinding ¶ added in v0.0.2

type MutationBinding struct {
	ProviderID            string
	RegistrationID        string
	Generation            string
	ProviderRoute         string
	RequiredContext       spec.ToolCatalogContext
	GenerationReplacement bool
}

MutationBinding is trusted transport state for one provider registration. RequiredContext is an authenticated confinement boundary: every non-empty field must be present and equal in a publication. GenerationReplacement is set only for a trusted reconnect/registration transition.

type Provider ¶

type Provider interface {
	Load(ctx context.Context) (Catalog, error)
}

Provider supplies the catalog. Implementations include Static, filesystem discovery, and pkg/memorylayer.CatalogProvider.

func Static(c Catalog) Provider

type ProviderFunc ¶

type ProviderFunc func(ctx context.Context) (Catalog, error)

ProviderFunc adapts a function to Provider (e.g. a store's LoadCatalog).

func (f ProviderFunc) Load(ctx context.Context) (Catalog, error)

type ProviderRouteBinding ¶ added in v0.0.2

type ProviderRouteBinding struct {
	ProviderID     string `json:"provider_id"`
	RegistrationID string `json:"registration_id"`
	Generation     string `json:"generation"`
	ProviderRoute  string `json:"provider_route"`
}

ProviderRouteBinding is authenticated operational state for one live provider generation. It is deliberately separate from the portable ToolCatalogContext: availability selectors describe where a tool applies, while ProviderRoute identifies the exact Aether recipient that executes it.

type PublicationLiveness ¶ added in v0.0.2

type PublicationLiveness interface {
	CatalogPublicationRoutable(ctx context.Context, publication spec.ToolCatalogPublication) (bool, error)
}

PublicationLiveness lets an adapter add a trusted route/presence check on top of the protocol lease. nil means that the backend's live publication is routable, which is the correct standalone behavior.

type PublicationLivenessFunc ¶ added in v0.0.2

type PublicationLivenessFunc func(context.Context, spec.ToolCatalogPublication) (bool, error)

PublicationLivenessFunc adapts a function to PublicationLiveness.

func (f PublicationLivenessFunc) CatalogPublicationRoutable(ctx context.Context, publication spec.ToolCatalogPublication) (bool, error)

type QueryBinding ¶ added in v0.0.2

type QueryBinding struct {
	SubjectID          string
	PolicyEpoch        string
	AuthorityLineageID string
	Context            spec.ToolCatalogContext
}

QueryBinding is trusted edge state. SubjectID and PolicyEpoch are never copied from catalog payloads; they bind retained snapshots and cursors to the authenticated caller and current authorization epoch.

func StandaloneQueryBinding(c spec.ToolCatalogContext) QueryBinding

type ResolvedCatalogDescribeResult ¶ added in v0.0.2

type ResolvedCatalogDescribeResult struct {
	SchemaVersion   string               `json:"schema_version"`
	SnapshotID      string               `json:"snapshot_id"`
	CatalogRevision string               `json:"catalog_revision"`
	Record          ResolvedCatalogEntry `json:"record"`
}

ResolvedCatalogDescribeResult retains the trusted publication context for a service adapter while preserving Describe's independent authorization.

type ResolvedCatalogEntry ¶ added in v0.0.2

type ResolvedCatalogEntry struct {
	Entry               spec.ToolCatalogEntry       `json:"entry"`
	Context             spec.ToolCatalogContext     `json:"context"`
	ProviderRoute       string                      `json:"provider_route,omitempty"`
	InvocationAuthority *InvocationAuthorityProfile `json:"invocation_authority,omitempty"`
}

ResolvedCatalogEntry retains the authenticated publication context beside an ecosystem catalog entry. The portable query page intentionally carries only entries; service adapters need this backend-owned context to route an exact invocation without copying provider routes into model-owned arguments.

type ResolvedCatalogPage ¶ added in v0.0.2

type ResolvedCatalogPage struct {
	SchemaVersion   string                 `json:"schema_version"`
	SnapshotID      string                 `json:"snapshot_id"`
	CatalogRevision string                 `json:"catalog_revision"`
	Records         []ResolvedCatalogEntry `json:"records"`
	AmbiguousNames  []string               `json:"ambiguous_names,omitempty"`
	NextCursor      string                 `json:"next_cursor,omitempty"`
}

ResolvedCatalogPage is the service-private projection of one deterministic catalog page. AmbiguousNames is computed over the complete retained snapshot, not merely this page, so a same-name collision that straddles a cursor boundary can never be exposed as an apparently unique bare tool name.

type ResourceRevision ¶ added in v0.0.2

type ResourceRevision struct {
	System         string `json:"system"`
	ID             string `json:"id"`
	Revision       int    `json:"revision,omitempty"`
	ETag           string `json:"etag,omitempty"`
	ManifestDigest string `json:"manifest_digest,omitempty"`
	BundleDigest   string `json:"bundle_digest,omitempty"`
}

ResourceRevision identifies the authoritative catalog resource from which an executable descriptor was projected. The catalog digest includes these fields, so an ETag or artifact change rotates the admitted snapshot even when a projection happens to render the same prompt text.

type RetainedSnapshot ¶ added in v0.0.2

type RetainedSnapshot struct {
	SchemaVersion   string                 `json:"schema_version"`
	SnapshotID      string                 `json:"snapshot_id"`
	CatalogRevision string                 `json:"catalog_revision"`
	BindingDigest   string                 `json:"binding_digest"`
	QueryDigest     string                 `json:"query_digest"`
	Limit           uint32                 `json:"limit"`
	CreatedAt       string                 `json:"created_at"`
	ExpiresAt       string                 `json:"expires_at"`
	Records         []ResolvedCatalogEntry `json:"records"`
}

RetainedSnapshot is an immutable, authorization-bound query result retained long enough to serve deterministic continuation cursors.

type SkillSpec ¶

type SkillSpec struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Path        string `json:"path,omitempty"`
	Content     string `json:"content,omitempty"`
	Enabled     bool   `json:"enabled"`
	// AllowedTools is the skill's declared tool scope, parsed from an optional
	// `allowed-tools` SKILL.md frontmatter key (YAML list or comma-separated
	// string). Surfaced to the model only — enforcement is a turn-loop follow-up.
	AllowedTools []string `json:"allowed_tools,omitempty"`
	// Prereqs / PreferredModel carry metadata.scitrera.{prereq_skills,preferred_model}
	// when the SOURCE already has it structured (e.g. a MemoryLayer catalog, which
	// strips SKILL.md frontmatter into a metadata field and leaves Content
	// frontmatter-less). BuildRegistry prefers these; when empty it falls back to
	// parsing the body frontmatter (the on-disk SKILL.md path).
	Prereqs        []string          `json:"prereq_skills,omitempty"`
	PreferredModel string            `json:"preferred_model,omitempty"`
	Source         *ResourceRevision `json:"source,omitempty"`
}

func MergeSkills(base, override []SkillSpec) []SkillSpec

type StaticInvocationAuthorityPolicy ¶ added in v0.0.2

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

func NewStaticInvocationAuthorityPolicy(rules []InvocationAuthorityRule) (*StaticInvocationAuthorityPolicy, error)

func (p *StaticInvocationAuthorityPolicy) ResolveInvocationAuthority(_ context.Context, _ spec.ToolCatalogContext, entry spec.ToolCatalogEntry) (*InvocationAuthorityProfile, error)

type ToolSpec ¶

type ToolSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"input_schema,omitempty"`
	Enabled     bool            `json:"enabled"`
}

type WorkspaceProvider ¶ added in v0.0.2

type WorkspaceProvider interface {
	LoadWorkspace(ctx context.Context, workspaceID string) (Catalog, error)
}

WorkspaceProvider loads a catalog for one resolved logical workspace. Empty workspace identifiers select the provider's configured default.

func BindWorkspaceProvider(provider WorkspaceProvider, logicalDefault, backendDefault string) WorkspaceProvider

type WorkspaceProviderFunc ¶ added in v0.0.2

type WorkspaceProviderFunc func(ctx context.Context, workspaceID string) (Catalog, error)

WorkspaceProviderFunc adapts a function to WorkspaceProvider.

func (f WorkspaceProviderFunc) LoadWorkspace(ctx context.Context, workspaceID string) (Catalog, error)