db

func AssertEmbeddingDimension ¶

func AssertEmbeddingDimension(ctx context.Context, pool *Pool, table, column string, wantDim int) error

AssertEmbeddingDimension is the G10 boot-time safety guard (§11.4.201): it reads the REAL pgvector dimension declared on table.column from the live database (via QueryColumnVectorDimension — the authoritative source) and asserts it equals wantDim, the configured embedder's OWN declared/output dimension (Embedder.Dimensions()). A mismatch returns a FAIL-CLOSED error naming BOTH dimensions and the source of each, so a misconfigured embedder can never silently corrupt every StoreSkillEmbedding/StoreEvidenceEmbedding insert and every KNN search (VectorSearch/HybridSearch) against a column sized for a different provider. Callers (cmd/server, cmd/worker) MUST treat a non-nil return as fatal — this is a hard stop, never a warn-and-continue (research/g10_embedding_provider_design.md §2.2 point 3).

func BatchEmbedAllSkills ¶

func BatchEmbedAllSkills(
	ctx context.Context,
	pool *Pool,
	provider EmbeddingProvider,
	cfg BatchEmbedConfig,
) error

BatchEmbedAllSkills finds all skills without embeddings and generates them using the provided provider. This is useful for initial population or after a provider/model change.

func BatchEmbedSkills ¶

func BatchEmbedSkills(
	ctx context.Context,
	pool *Pool,
	skillIDs []uuid.UUID,
	provider EmbeddingProvider,
	cfg BatchEmbedConfig,
) error

BatchEmbedSkills generates and stores embeddings for the given skill IDs. Skills are processed in configurable batches with rate limiting to avoid overwhelming the embedding provider.

Partial failures are tolerated: individual skill embedding errors are logged and the function continues with remaining skills. The returned error is non-nil only if the entire operation is aborted (e.g. context cancellation).

The provider is called with each skill's content (name + description + content concatenated) to generate the embedding vector.

func ClearSkillEmbedding ¶

func ClearSkillEmbedding(
	ctx context.Context,
	pool *Pool,
	skillID uuid.UUID,
) error

ClearSkillEmbedding sets a skill's embedding column to NULL. This is the honest-degrade counterpart to StoreSkillEmbedding, used by internal/skill.Store's embedWriteThrough (§G59 F3, code-review remediation) on ALL FOUR of its embed failure/skip paths -- empty embed text, an Embed() error, Embed() returning an empty/unusable vector, and (F3 round-2 remediation) Embed() succeeding but the subsequent StoreSkillEmbedding call itself failing (e.g. a dimension mismatch between the returned vector and this table's `embedding vector(768)` column) -- so a re-embed attempted during an ON CONFLICT (name) DO UPDATE never leaves a STALE vector -- one computed from the skill's PREVIOUS content -- silently serving vector-KNN matches against content that no longer exists. "A failed store means the clear would fail too" does NOT generally hold: this UPDATE writes a literal NULL, which has no dimension (or other content-shaped constraint) to violate, so it succeeds independently of why the preceding store failed. Called unconditionally on every one of those four paths regardless of whether the skill was freshly inserted or updated: on a fresh insert the column is already NULL by column default, so this is a harmless no-op there.

func CurrentMigrationVersion ¶

func CurrentMigrationVersion(ctx context.Context, pool *Pool) (int64, error)

CurrentMigrationVersion returns the highest applied migration version, or -1 if no migrations have been applied.

func EmbedAsync ¶

func EmbedAsync(
	ctx context.Context,
	embedder Embedder,
	texts []string,
	maxConcurrency int,
) <-chan AsyncEmbedResult

EmbedAsync embeds each text in a separate goroutine (up to maxConcurrency at a time) and returns the results via a channel. The channel is closed when all work is complete.

Callers should range over the returned channel until closed.

func EmbedBatch ¶

func EmbedBatch(
	ctx context.Context,
	embedder Embedder,
	texts []string,
	batchSize int,
) ([][]float32, error)

EmbedBatch breaks a large text slice into smaller batches and embeds them sequentially. If a single batch fails the entire operation fails.

func LogDependencyChange ¶

func LogDependencyChange(
	ctx context.Context,
	pool *Pool,
	event string,
	skillID uuid.UUID,
	dependsOn uuid.UUID,
	relationType string,
) error

LogDependencyChange records a dependency addition or removal.

func LogEvent ¶

func LogEvent(
	ctx context.Context,
	pool *Pool,
	event string,
	skillID *uuid.UUID,
	details json.RawMessage,
) error

LogEvent inserts a single event into the audit_log table.

event should be one of the AuditEvent* constants. skillID may be nil for system-level events. details may be nil if no extra JSON data is associated with the event.

func LogEventWithDetails ¶

func LogEventWithDetails(
	ctx context.Context,
	pool *Pool,
	event string,
	skillID *uuid.UUID,
	details map[string]interface{},
) error

LogEventWithDetails is a convenience helper that marshals a details map into JSON and then calls LogEvent.

func LogEvidenceChange ¶

func LogEvidenceChange(
	ctx context.Context,
	pool *Pool,
	event string,
	skillID uuid.UUID,
	evidenceID uuid.UUID,
	extra map[string]interface{},
) error

LogEvidenceChange records evidence addition or validation.

func LogSkillChange ¶

func LogSkillChange(
	ctx context.Context,
	pool *Pool,
	event string,
	skillID uuid.UUID,
	changes map[string]interface{},
) error

LogSkillChange records a skill create/update/delete event.

func LogSystemEvent ¶

func LogSystemEvent(
	ctx context.Context,
	pool *Pool,
	event string,
	details map[string]interface{},
) error

LogSystemEvent records a system-level event with no associated skill.

func Migrate ¶

func Migrate(ctx context.Context, pool *Pool, migrationsDir string) error

Migrate runs all pending "up" migrations found in migrationsDir. It tracks applied versions in the schema_migrations table (created automatically).

Migration files must be named as NNN_description.up.sql and NNN_description.down.sql where NNN is a zero-padded version number. Migrations are executed in version order inside transactions.

Migrate is a thin wrapper over MigrateFS that reads the migrations from an on-disk directory (os.DirFS). Production startup (cmd/server) uses MigrateFS with the embedded migrations FS so migrations apply independently of the process working directory (§G23); this string-path form is retained for the test suites that drive a controlled on-disk migration subset.

func MigrateDown ¶

func MigrateDown(ctx context.Context, pool *Pool, migrationsDir string, n int) error

MigrateDown rolls back the last n applied migrations. Use with caution; in production prefer targeted down migrations during maintenance windows.

Like Migrate, this is a thin wrapper over MigrateDownFS reading from an on-disk directory (os.DirFS); the string-path form is retained for the test suites.

func MigrateDownFS ¶

func MigrateDownFS(ctx context.Context, pool *Pool, fsys fs.FS, n int) error

MigrateDownFS rolls back the last n applied migrations, reading the down migrations from fsys (an io/fs.FS rooted at the migrations directory). See MigrateFS for the FS-shape contract.

func MigrateFS ¶

func MigrateFS(ctx context.Context, pool *Pool, fsys fs.FS) error

MigrateFS runs all pending "up" migrations discovered in fsys (an io/fs.FS). Both an embed.FS (the compiled-in migrations, cwd-independent) and os.DirFS(dir) (an on-disk directory) satisfy fs.FS, so the same discovery and apply logic serves the production embedded path AND the on-disk test path.

fsys MUST be rooted at the migrations directory itself, so its entries are the bare NNN_description.{up,down}.sql filenames (skillsystem.MigrationsFS and os.DirFS(dir) both satisfy this).

It tracks applied versions in the schema_migrations table (created automatically) and applies each pending migration in version order inside a transaction. Any discovery, read, or apply failure is returned to the caller UNMODIFIED-in-severity: it is a hard error, never swallowed — cmd/server treats it as fatal and refuses to bind the port (§G23 fail-closed).

func PruneAuditLog ¶

func PruneAuditLog(ctx context.Context, pool *Pool, olderThan time.Duration) (int64, error)

PruneAuditLog deletes audit log entries older than the given duration.

func QueryColumnVectorDimension ¶

func QueryColumnVectorDimension(ctx context.Context, pool *Pool, table, column string) (int, error)

QueryColumnVectorDimension reads the ACTUAL pgvector dimension declared on table.column from the live database's system catalog (pg_attribute joined to pg_class, rendered via format_type) — the single authoritative source of truth for "what dimension is this column really sized for" (§11.4.201). It is NEVER derived from a hardcoded Go constant or from the embedding provider's own configuration.

Returns an error if the column does not exist (or has been dropped), or if it exists but is not a dimensioned pgvector column: a bare "vector" with no typmod accepts a vector of ANY length, which would defeat the entire purpose of a boot-time dimension assertion, so that case is rejected rather than silently treated as "no constraint" (§11.4.201: an unresolvable/ambiguous signal refuses, it never assumes OK).

func StoreEvidenceEmbedding ¶

func StoreEvidenceEmbedding(
	ctx context.Context,
	pool *Pool,
	evidenceID uuid.UUID,
	embedding pgvector.Vector,
) error

StoreEvidenceEmbedding updates the embedding vector for a specific evidence record.

func StoreSkillEmbedding ¶

func StoreSkillEmbedding(
	ctx context.Context,
	pool *Pool,
	skillID uuid.UUID,
	embedding pgvector.Vector,
) error

StoreEmbedding updates the embedding vector for a specific skill.

func VectorIndexStats ¶

func VectorIndexStats(
	ctx context.Context,
	pool *Pool,
	table string,
) (indexedCount int64, indexSizeBytes int64, err error)

VectorIndexStats returns the number of indexed vectors and index size for the given table's embedding column.

func WaitForVectorIndexReady ¶

func WaitForVectorIndexReady(
	ctx context.Context,
	pool *Pool,
	table string,
	timeout time.Duration,
) error

WaitForVectorIndexReady polls until the pgvector HNSW index for the given table is ready (indisvalid = true), or until the timeout.

Error handling distinguishes the two cases the previous swallow-everything `continue` conflated (§11.4.201 — a guard must assert the real condition, not a proxy that any failure satisfies): pgx.ErrNoRows means the index does not exist yet and polling should continue, whereas any OTHER query error means the query itself (or the connection) is broken and is surfaced immediately rather than silently spun on until the deadline. A per-iteration query cancelled by this function's own deadline is not a broken query — it is deferred to the ctx.Done() branch so the timeout is reported once, with its clearer message.