feat(ecosystem): compliant Praxis/Hexis integration + vendored build

Bring the Nexus/Praxis/Hexis integration in line with
MAVEN_ECOSYSTEM_ARCHITECTURE.md:

- Praxis over HTTP: drop the in-process praxis.db open (praxisstore/
  praxistools) and call praxisd's /api/v1/tools/* API via a new praxisClient.
  Honors the "no component reads another's DB" invariant (AC#12).
  PraxisConfig.DBPath -> URL.
- Hexis confirmation gate: mutating capabilities (ReadOnly=false) now park a
  bound pendingHexis confirmation and require a spoken "да" before executing;
  read-only run immediately (AC#7, no auto attention->action).
- Capability safety: >1 verb match is ambiguous -> ask instead of firing the
  first; ambiguous Nexus resolution asks for clarification (AC#2).
- Correlation IDs on Hexis execute, recorded in the cross-service trace.
- Bug: importance arrives as JSON float64 over HTTP, not int.
- Tests: confirm-gate, decline, read-only, and ambiguity paths.

Build: vendor/ bakes in the hexis client (replace-directed at a sibling repo
outside the Docker context); Dockerfile builds from vendor and no longer
`go mod download`s the unreachable replace paths.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
kami
2026-07-19 19:32:05 +04:00
parent 0c65387a5f
commit 6c92f85d10
2071 changed files with 3915438 additions and 61 deletions
+59
View File
@@ -0,0 +1,59 @@
// Package vtab defines a Go-facing API for implementing SQLite virtual table
// modules on top of the modernc.org/sqlite driver.
//
// It is intentionally small and generic so that external projects can
// implement virtual tables without depending on the translated C internals.
package vtab
// API notes
//
// - Schema declaration: Modules must call Context.Declare from within Create
// or Connect to declare the virtual table schema (a CREATE TABLE statement).
// The driver no longer auto-declares based on USING(...) args to support
// dynamic schemas (e.g., CSV headers).
//
// - Constraint support: Modules that want MATCH/other constraints must call
// Context.EnableConstraintSupport from within Create or Connect.
//
// - Vtab config: Modules can call Context.Config to pass sqlite3_vtab_config
// options (e.g., INNOCUOUS, DIRECTONLY) from within Create or Connect.
//
// - Constraint operators: ConstraintOp includes OpUnknown for operators that
// are not recognized. The driver maps common SQLite operators including EQ,
// NE, GT, GE, LT, LE, MATCH, IS/ISNOT, ISNULL/ISNOTNULL, LIKE, GLOB, REGEXP,
// FUNCTION, LIMIT, and OFFSET.
//
// - ArgIndex: Set as 0-based in Go to indicate which position in argv[] should
// receive a constraint value. The driver adds +1 when communicating with
// SQLite (which is 1-based). Use -1 (default) to ignore.
//
// - Omit: Set Constraint.Omit to ask SQLite to not re-evaluate that constraint
// in the parent query if the virtual table fully handles it.
//
// - ColUsed: IndexInfo.ColUsed provides a bitmask of columns referenced by the
// query. Bit N indicates column N is used.
//
// - IdxFlags: IndexInfo.IdxFlags allows modules to set planning flags.
// Currently, IndexScanUnique (mirrors SQLITE_INDEX_SCAN_UNIQUE) indicates
// the plan will visit at most one row. This can help the optimizer.
//
// Optional interfaces
//
// - Updater: Implement on your Table to support writes via xUpdate.
// Insert(cols, *rowid), Update(oldRowid, cols, *newRowid), Delete(oldRowid).
// The trampoline maps SQLite xUpdates calling convention to these methods.
//
// - Renamer: Implement Rename(newName string) on your Table to handle xRename.
// If unimplemented, rename is treated as a no-op.
//
// - Transactional: Implement Begin/Sync/Commit/Rollback/Savepoint/Release/
// RollbackTo as needed. Unimplemented methods are treated as no-ops.
// These callbacks let writable or advanced modules coordinate with SQLite
// transaction boundaries.
//
// Re-entrancy cautions
// - Avoid executing SQL on the same connection from within vtab methods
// (Create/Connect/BestIndex/Filter/etc.). SQLite virtual table callbacks run
// inside the engine and issuing re-entrant SQL on the same connection can
// lead to deadlocks or undefined behavior. If a module requires issuing SQL,
// consider using a separate connection and document the concurrency model.