cloudstore

package
v1.8.1 Latest Latest
Warning

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

 Go to latest Published: Mar 8, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package cloudstore implements the Postgres-backed storage layer for Engram Cloud.

It mirrors the local SQLite store but uses Postgres with row-level user isolation, full-text search via tsvector, and chunk-based sync storage.

Package cloudstore implements the Postgres-backed storage layer for Engram Cloud.

It mirrors the local SQLite store but uses Postgres with row-level user isolation, full-text search via tsvector, and chunk-based sync storage.

Index

Constants

This section is empty.

Variables

View Source 
var ErrProjectSyncPaused = errors.New("cloudstore: project sync paused")

Functions

This section is empty.

Types

type AddCloudObservationParams 

type AddCloudObservationParams struct {
	SessionID string `json:"session_id"`
	Type      string `json:"type"`
	Title     string `json:"title"`
	Content   string `json:"content"`
	ToolName  string `json:"tool_name,omitempty"`
	Project   string `json:"project,omitempty"`
	Scope     string `json:"scope,omitempty"`
	TopicKey  string `json:"topic_key,omitempty"`
}

AddCloudObservationParams holds parameters for creating a new observation.

type AddCloudPromptParams 

type AddCloudPromptParams struct {
	SessionID string `json:"session_id"`
	Content   string `json:"content"`
	Project   string `json:"project,omitempty"`
}

AddCloudPromptParams holds parameters for creating a new prompt.

type CloudChunkEntry 

type CloudChunkEntry struct {
	ChunkID    string `json:"chunk_id"`
	UserID     string `json:"user_id"`
	CreatedBy  string `json:"created_by"`
	Sessions   int    `json:"sessions"`
	Memories   int    `json:"memories"`
	Prompts    int    `json:"prompts"`
	ImportedAt string `json:"imported_at"`
}

CloudChunkEntry describes a sync chunk stored in the cloud.

type CloudMutation 

type CloudMutation struct {
	Seq        int64           `json:"seq"`
	UserID     string          `json:"user_id"`
	Entity     string          `json:"entity"`
	EntityKey  string          `json:"entity_key"`
	Op         string          `json:"op"`
	Payload    json.RawMessage `json:"payload"`
	OccurredAt string          `json:"occurred_at"`
}

CloudMutation represents a single append-only mutation in the cloud ledger.

type CloudObservation 

type CloudObservation struct {
	ID             int64   `json:"id"`
	UserID         string  `json:"user_id"`
	SessionID      string  `json:"session_id"`
	Type           string  `json:"type"`
	Title          string  `json:"title"`
	Content        string  `json:"content"`
	ToolName       *string `json:"tool_name,omitempty"`
	Project        *string `json:"project,omitempty"`
	Scope          string  `json:"scope"`
	TopicKey       *string `json:"topic_key,omitempty"`
	RevisionCount  int     `json:"revision_count"`
	DuplicateCount int     `json:"duplicate_count"`
	LastSeenAt     *string `json:"last_seen_at,omitempty"`
	CreatedAt      string  `json:"created_at"`
	UpdatedAt      string  `json:"updated_at"`
	DeletedAt      *string `json:"deleted_at,omitempty"`
}

CloudObservation represents an observation scoped to a user.

type CloudPrompt 

type CloudPrompt struct {
	ID        int64  `json:"id"`
	UserID    string `json:"user_id"`
	SessionID string `json:"session_id"`
	Content   string `json:"content"`
	Project   string `json:"project,omitempty"`
	CreatedAt string `json:"created_at"`
}

CloudPrompt represents a user prompt scoped to a user.

type CloudSearchOptions 

type CloudSearchOptions struct {
	Type    string // Filter by observation type (e.g. "decision", "note")
	Project string // Filter by project name
	Scope   string // Filter by scope ("project", "personal", "global")
	Limit   int    // Max results to return (default 20)
}

CloudSearchOptions configures observation search filters.

type CloudSearchResult 

type CloudSearchResult struct {
	CloudObservation
	Rank float64 `json:"rank"` // ts_rank_cd score
}

CloudSearchResult holds a single search result with relevance ranking.

type CloudSession 

type CloudSession struct {
	ID        string  `json:"id"`
	UserID    string  `json:"user_id"`
	Project   string  `json:"project"`
	Directory string  `json:"directory"`
	StartedAt string  `json:"started_at"`
	EndedAt   *string `json:"ended_at,omitempty"`
	Summary   *string `json:"summary,omitempty"`
}

CloudSession represents a session record scoped to a user.

type CloudSessionSummary 

type CloudSessionSummary struct {
	ID               string  `json:"id"`
	Project          string  `json:"project"`
	StartedAt        string  `json:"started_at"`
	EndedAt          *string `json:"ended_at,omitempty"`
	Summary          *string `json:"summary,omitempty"`
	ObservationCount int     `json:"observation_count"`
}

CloudSessionSummary holds session info with an observation count.

type CloudStats 

type CloudStats struct {
	TotalSessions     int      `json:"total_sessions"`
	TotalObservations int      `json:"total_observations"`
	TotalPrompts      int      `json:"total_prompts"`
	Projects          []string `json:"projects"`
}

CloudStats holds aggregate statistics for a user.

type CloudStore 

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

CloudStore provides Postgres-backed storage for Engram Cloud.

func New 

func New(cfg cloud.Config) (*CloudStore, error)

New creates a new CloudStore. It opens a Postgres connection using the DSN from cfg, configures the connection pool, and runs schema initialization inside a single transaction.

func (*CloudStore) AddObservation 

func (cs *CloudStore) AddObservation(userID string, p AddCloudObservationParams) (int64, error)

AddObservation creates a new observation for the given user.

func (*CloudStore) AddPrompt 

func (cs *CloudStore) AddPrompt(userID string, p AddCloudPromptParams) (int64, error)

AddPrompt creates a new prompt for the given user.

func (*CloudStore) AppendMutation 

func (cs *CloudStore) AppendMutation(userID, entity, entityKey, op string, payload json.RawMessage) (int64, error)

AppendMutation inserts a mutation into the cloud ledger for a user. Returns the assigned sequence number.

func (*CloudStore) AppendMutationBatch 

func (cs *CloudStore) AppendMutationBatch(userID string, entries []PushMutationEntry) (*PushMutationsResult, error)

AppendMutationBatch inserts multiple mutations atomically. Returns the number accepted and the last assigned sequence.

func (*CloudStore) ApplyMutationPayload 

func (cs *CloudStore) ApplyMutationPayload(userID, entity, op string, payload json.RawMessage) error

ApplyMutationPayload dispatches a mutation to the appropriate entity handler. This enables the cloud to materialize pushed mutations into the relational tables.

func (*CloudStore) Close 

func (cs *CloudStore) Close() error

Close closes the underlying database connection.

func (*CloudStore) ContributorStats 

func (cs *CloudStore) ContributorStats() ([]ContributorStat, error)

ContributorStats returns per-user statistics across the whole system. This is an admin/org-level query (Phase 7).

func (*CloudStore) CreateSession 

func (cs *CloudStore) CreateSession(userID, sessionID, project, directory string) error

CreateSession creates a new session for the given user.

func (*CloudStore) CreateUser 

func (cs *CloudStore) CreateUser(username, email, password string) (*CloudUser, error)

CreateUser creates a new user with a bcrypt-hashed password (cost >= 10). Returns an error if the username or email already exists.

func (*CloudStore) DB 

func (cs *CloudStore) DB() *sql.DB

DB returns the underlying *sql.DB for advanced use cases (e.g. testing).

func (*CloudStore) DeleteObservation 

func (cs *CloudStore) DeleteObservation(userID string, id int64, hard bool) error

DeleteObservation soft-deletes or hard-deletes an observation, scoped to user_id.

func (*CloudStore) DeleteObservationByPayload 

func (cs *CloudStore) DeleteObservationByPayload(userID string, payload json.RawMessage) error

DeleteObservationByPayload applies a soft/hard delete from a sync mutation payload.

func (*CloudStore) EndSession 

func (cs *CloudStore) EndSession(userID, sessionID, summary string) error

EndSession ends a session by setting ended_at and an optional summary. Filters by user_id to ensure data isolation.

func (*CloudStore) FilterObservations 

func (cs *CloudStore) FilterObservations(userID, project, scope, obsType string, limit int) ([]CloudObservation, error)

FilterObservations returns recent observations filtered by project, scope, and type.

func (*CloudStore) FormatContext 

func (cs *CloudStore) FormatContext(userID, project, scope string) (string, error)

FormatContext produces a formatted context string for a user, matching the output format of internal/store/store.go's FormatContext method.

func (*CloudStore) GetChunk 

func (cs *CloudStore) GetChunk(userID, chunkID string) ([]byte, error)

GetChunk retrieves the raw data for a chunk, scoped to user_id.

func (*CloudStore) GetObservation 

func (cs *CloudStore) GetObservation(userID string, id int64) (*CloudObservation, error)

GetObservation retrieves a single observation by ID, scoped to user_id.

func (*CloudStore) GetProjectSyncControl 

func (cs *CloudStore) GetProjectSyncControl(project string) (*ProjectSyncControl, error)

func (*CloudStore) GetPrompt 

func (cs *CloudStore) GetPrompt(userID string, id int64) (*CloudPrompt, error)

GetPrompt retrieves a single prompt by id, scoped to user_id.

func (*CloudStore) GetSession 

func (cs *CloudStore) GetSession(userID, sessionID string) (*CloudSession, error)

GetSession retrieves a single session by ID, scoped to user_id.

func (*CloudStore) GetSyncedChunks 

func (cs *CloudStore) GetSyncedChunks(userID string) (map[string]bool, error)

GetSyncedChunks returns a set of chunk IDs that have been synced for a user.

func (*CloudStore) GetUserByAPIKeyHash 

func (cs *CloudStore) GetUserByAPIKeyHash(hash string) (*CloudUser, error)

GetUserByAPIKeyHash retrieves a user by their API key hash.

func (*CloudStore) GetUserByEmail 

func (cs *CloudStore) GetUserByEmail(email string) (*CloudUser, error)

GetUserByEmail retrieves a user by email address.

func (*CloudStore) GetUserByID 

func (cs *CloudStore) GetUserByID(userID string) (*CloudUser, error)

GetUserByID retrieves a user by id.

func (*CloudStore) GetUserByUsername 

func (cs *CloudStore) GetUserByUsername(username string) (*CloudUser, error)

GetUserByUsername retrieves a user by username.

func (*CloudStore) IsProjectSyncEnabled 

func (cs *CloudStore) IsProjectSyncEnabled(project string) (bool, error)

func (*CloudStore) ListAllUsers 

func (cs *CloudStore) ListAllUsers() ([]CloudUser, error)

ListAllUsers returns all registered users with their API key status. Used by the admin user management view (Phase 8).

func (*CloudStore) ListChunks 

func (cs *CloudStore) ListChunks(userID string) ([]CloudChunkEntry, error)

ListChunks returns all chunk entries for a user.

func (*CloudStore) ListProjectSyncControls 

func (cs *CloudStore) ListProjectSyncControls() ([]ProjectSyncControl, error)

func (*CloudStore) ObservationTypes 

func (cs *CloudStore) ObservationTypes(userID, project string) ([]string, error)

ObservationTypes returns the distinct observation types currently present for a user, optionally filtered by project, ordered by frequency and then name.

func (*CloudStore) Ping 

func (cs *CloudStore) Ping() error

Ping checks whether the underlying database connection is currently healthy.

func (*CloudStore) ProjectStats 

func (cs *CloudStore) ProjectStats(userID string) ([]ProjectStat, error)

ProjectStats returns per-project statistics for a user, ordered by most recent activity. Used by the dashboard overview (Phase 4).

func (*CloudStore) PullMutations 

func (cs *CloudStore) PullMutations(userID string, sinceSeq int64, limit int) (*PullMutationsResult, error)

PullMutations returns mutations for a user with seq > sinceSeq, ordered ASC.

func (*CloudStore) RecentObservations 

func (cs *CloudStore) RecentObservations(userID, project, scope string, limit int) ([]CloudObservation, error)

RecentObservations returns recent observations for a user, optionally filtered by project and scope.

func (*CloudStore) RecentPrompts 

func (cs *CloudStore) RecentPrompts(userID, project string, limit int) ([]CloudPrompt, error)

RecentPrompts returns recent prompts for a user, optionally filtered by project.

func (*CloudStore) RecentSessions 

func (cs *CloudStore) RecentSessions(userID, project string, limit int) ([]CloudSessionSummary, error)

RecentSessions returns the most recent sessions for a user, optionally filtered by project, with observation counts.

func (*CloudStore) RecordSyncedChunk 

func (cs *CloudStore) RecordSyncedChunk(userID, chunkID string) error

RecordSyncedChunk records that a chunk has been synced for a user. Uses INSERT ON CONFLICT DO NOTHING for idempotency.

func (*CloudStore) Search 

func (cs *CloudStore) Search(userID, query string, opts CloudSearchOptions) ([]CloudSearchResult, error)

Search performs a full-text search over cloud_observations for the given user. Results are ranked by ts_rank_cd using the tsv GENERATED STORED column. Title matches (weight A) rank higher than content matches (B) which rank higher than type/project matches (C).

The query is processed by plainto_tsquery('english', $N) which safely handles multi-word input by ANDing terms. All filtering uses parameterized placeholders -- no string concatenation touches SQL.

Covers: CLOUD-SRV-06, FTS-01, FTS-03, NFR-01, NFR-02.

func (*CloudStore) SearchPrompts 

func (cs *CloudStore) SearchPrompts(userID, query, project string, limit int) ([]CloudPrompt, error)

SearchPrompts performs a full-text search over cloud_prompts for the given user. It uses the tsv GENERATED STORED column with plainto_tsquery. Results are ordered by rank descending, then created_at descending.

Covers: FTS-02.

func (*CloudStore) SessionObservations 

func (cs *CloudStore) SessionObservations(userID, sessionID string, limit int) ([]CloudObservation, error)

SessionObservations returns all live observations for a single session.

func (*CloudStore) SessionPrompts 

func (cs *CloudStore) SessionPrompts(userID, sessionID string, limit int) ([]CloudPrompt, error)

SessionPrompts returns prompts captured during a single session.

func (*CloudStore) SetAPIKeyHash 

func (cs *CloudStore) SetAPIKeyHash(userID, hash string) error

SetAPIKeyHash sets the API key hash for a user. Pass an empty string to revoke.

func (*CloudStore) SetProjectSyncEnabled 

func (cs *CloudStore) SetProjectSyncEnabled(project string, enabled bool, updatedBy, reason string) error

func (*CloudStore) Stats 

func (cs *CloudStore) Stats(userID string) (*CloudStats, error)

Stats returns aggregate statistics for a user.

func (*CloudStore) StoreChunk 

func (cs *CloudStore) StoreChunk(userID, chunkID, createdBy string, data []byte, sessions, memories, prompts int) error

StoreChunk stores a sync chunk. Uses INSERT ON CONFLICT DO NOTHING for idempotency.

func (*CloudStore) SystemHealth 

func (cs *CloudStore) SystemHealth() (*SystemHealthInfo, error)

SystemHealth returns system-wide health metrics for admin views (Phase 8).

func (*CloudStore) UpsertObservationByPayload 

func (cs *CloudStore) UpsertObservationByPayload(userID string, payload json.RawMessage) error

UpsertObservationByPayload applies an observation upsert from a sync mutation payload. Uses sync_id as the stable cross-device identity for upserts.

func (*CloudStore) UpsertPromptByPayload 

func (cs *CloudStore) UpsertPromptByPayload(userID string, payload json.RawMessage) error

UpsertPromptByPayload applies a prompt upsert from a sync mutation payload.

func (*CloudStore) UpsertSessionByPayload 

func (cs *CloudStore) UpsertSessionByPayload(userID string, payload json.RawMessage) error

UpsertSessionByPayload applies a session upsert from a sync mutation payload.

func (*CloudStore) UserProjects 

func (cs *CloudStore) UserProjects(userID string) ([]string, error)

UserProjects returns distinct project names for a user.

type CloudUser 

type CloudUser struct {
	ID           string  `json:"id"`
	Username     string  `json:"username"`
	Email        string  `json:"email"`
	PasswordHash string  `json:"-"`
	APIKeyHash   *string `json:"-"`
	CreatedAt    string  `json:"created_at"`
	UpdatedAt    string  `json:"updated_at"`
}

CloudUser represents a registered user in the cloud system.

type ContributorStat 

type ContributorStat struct {
	UserID           string  `json:"user_id"`
	Username         string  `json:"username"`
	Email            string  `json:"email"`
	SessionCount     int     `json:"session_count"`
	ObservationCount int     `json:"observation_count"`
	LastSync         *string `json:"last_sync,omitempty"`
}

ContributorStat holds per-user aggregate data for the contributors view.

type ProjectStat 

type ProjectStat struct {
	Project          string  `json:"project"`
	SessionCount     int     `json:"session_count"`
	ObservationCount int     `json:"observation_count"`
	PromptCount      int     `json:"prompt_count"`
	LastActivity     *string `json:"last_activity,omitempty"`
}

ProjectStat holds per-project aggregate data for the dashboard overview.

type ProjectSyncControl 

type ProjectSyncControl struct {
	Project      string  `json:"project"`
	SyncEnabled  bool    `json:"sync_enabled"`
	PausedReason *string `json:"paused_reason,omitempty"`
	UpdatedAt    string  `json:"updated_at"`
	UpdatedBy    *string `json:"updated_by,omitempty"`
}

type PullMutationsResult 

type PullMutationsResult struct {
	Mutations []CloudMutation `json:"mutations"`
	HasMore   bool            `json:"has_more"`
}

PullMutationsResult holds the response for a mutation pull.

type PushMutationEntry 

type PushMutationEntry struct {
	Entity    string          `json:"entity"`
	EntityKey string          `json:"entity_key"`
	Op        string          `json:"op"`
	Payload   json.RawMessage `json:"payload"`
}

PushMutationEntry is a single mutation in a push request. The shape mirrors the local sync_mutations.payload contract.

type PushMutationsRequest 

type PushMutationsRequest struct {
	Mutations []PushMutationEntry `json:"mutations"`
}

PushMutationsRequest holds the JSON body for POST /sync/mutations/push.

type PushMutationsResult 

type PushMutationsResult struct {
	Accepted int   `json:"accepted"`
	LastSeq  int64 `json:"last_seq"`
}

PushMutationsResult holds the response for a mutation push.

type SystemHealthInfo 

type SystemHealthInfo struct {
	DBConnected    bool   `json:"db_connected"`
	TotalUsers     int    `json:"total_users"`
	TotalSessions  int    `json:"total_sessions"`
	TotalMemories  int    `json:"total_memories"`
	TotalPrompts   int    `json:"total_prompts"`
	TotalMutations int    `json:"total_mutations"`
	DBVersion      string `json:"db_version"`
}

SystemHealthInfo holds system health metrics for admin views.

Source Files

View all Source files

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.