Nomos OS Docs

Appearance

Nomos Core API Reference ​

The core packages define the immutable bedrock types, workspace context, configuration loaders, database pools, and AST analysis primitives used across the entire Nomos execution engine.

📦 Core Packages Catalog (12 Packages) ​

1. core/workspace ​

Environment inspection, root resolution, and multi-repo umbrella orchestration.

  • Key Structs: WorkspaceContext (RepoRoot, PrimaryWorktree, Hemisphere, IsUmbrella, ChildProjects).
  • Key Functions:
    • NewContext(cwd string) (*WorkspaceContext, error): Traverses parent directory tree safely (ignoring $HOME) and constructs isolated workspace context.
    • ResolveGoWorkPath(dir string, ctx *WorkspaceContext) string: Locates active go.work boundaries.
    • ExpandHomePath(p string) string: Expands ~ home directory aliases into absolute filesystem paths.

2. core/config ​

Deterministic, typed configuration loading and schema validation via Viper.

  • Key Structs: Config (Env, DbPath, Verify, MaxContextTokens, Provider, LocalModelURL, MaxDailySpend), ProviderSettings (URL, Model, Temperature, TopP, ReasoningEffort).
  • Key Functions:
    • LoadConfig(path string) (*Config, error): Parses and validates global or repository config.yaml.
    • LoadProjectSettings(repoRoot string) (*ProjectConfig, error): Loads local project overrides and cross-repo boundaries.

3. core/state ​

The formal 4-phase state machine and workspace phase discipline locks.

  • Key Types: WorkspacePhase (IDLE, PLAN, EDIT, REVIEW).
  • Key Functions:
    • GetWorkspacePhase(ctx *WorkspaceContext) (WorkspacePhase, error): Resolves current phase lock token from SQLite.
    • SetWorkspacePhase(ctx *WorkspaceContext, phase WorkspacePhase) error: Mutates workspace phase state machine.

4. core/ast ​

Go-native Abstract Syntax Tree analysis for code quality enforcement and dependency graph construction.

  • Key Structs: Symbol, FunctionComplexity, DependencyGraph.
  • Key Functions:
    • ExtractSymbols(filePath string) ([]Symbol, error): Extracts exported structs, functions, and interfaces.
    • CalculateComplexity(fnNode *ast.FuncDecl) int: Computes McCabe cyclomatic complexity.

5. core/db ​

Pooled, thread-safe SQLite connection management and PRAGMA configuration.

  • Key Functions:
    • GetDB(dbPath string) (*sql.DB, error): Opens or reuses pooled SQLite connection with WAL mode and busy timeout enabled.
    • CloseAll(): Safely closes all pooled SQLite connections during CLI teardown.

6. core/gitbrain ​

Subconscious memory subsystem leveraging vector embeddings and Git Notes.

  • Key Structs: MemoryRecord, EmbeddingVector.
  • Key Functions:
    • SaveNote(repoRoot, ref, commitHash, note string) error: Persists agent cognitive decisions to refs/notes/agent.
    • ReadNote(repoRoot, ref, commitHash string) (string, error): Retrieves agent context notes.

7. core/llm ​

Token counting heuristics and context budget estimation for LLM prompts.

  • Key Functions:
    • EstimateTokenCount(prompt string) int: Approximates token footprint to prevent context overflow.
    • OptimizeContextWindow(text string, maxTokens int) string: Truncates non-critical lines to respect cognitive thresholds.

8. core/plugin ​

Dynamic plugin discovery and JSON-RPC subprocess execution harness.

  • Key Functions:
    • DiscoverPlugins(dir string) ([]string, error): Scans $PATH and local workspace for nomos-plugin-* executables.
    • CallPlugin(pluginPath, action string, args []string) (string, error): Executes external plugin extensions.

9. core/release ​

SemVer calculation and structured release metadata management.

  • Key Structs: SemVer, ReleaseDelta.
  • Key Functions:
    • CalculateNextVersion(current string, bumpType string) (string, error): Increments SemVer patch, minor, or major.

10. core/synapse ​

Rich terminal HUD formatting, ANSI color pallets, and Cyberpunk ASCII rendering.

  • Key Functions:
    • Info(format string, a ...any): Emits styled cyan/blue log lines.
    • Success(format string, a ...any): Emits bold green completion notices.
    • Warn(format string, a ...any): Emits amber caution alerts.
    • Error(format string, a ...any): Emits red failure alerts.

11. core/telemetry ​

Internal event emitter and structured telemetry event aggregation.

  • Key Structs: TelemetryEvent (EventType, Timestamp, LatencyMs, Metadata).
  • Key Functions:
    • Emit(event TelemetryEvent): Records gate latencies and command durations to local SQLite telemetry cache.

12. core/assets ​

Embedded Source of Truth (SSoT) assets, JSON schemas, resident guidelines, and master workflows.

  • Key Functions:
    • GetCliSchemaJSON() []byte: Provides embedded fallback cli_schema.json.
    • GetWorkflowAsset(name string) ([]byte, error): Returns master workflow markdown definitions.

13. core/analysis ​

Automated AST self-healing and code rewrite engine.

  • Key Structs: FixerOptions (DryRun), FixResult (FilePath, Modified, Description).
  • Key Functions:
    • RunFixers(target string, opts FixerOptions) ([]FixResult, error): Applies deterministic AST transformations including filepath normalization and error wrapping.

14. core/license ​

Go-native Ed25519 cryptographic license verification, air-gapped signature validation, and offline grace period enforcement.

  • Key Structs: LicensePayload (ID, Subject, Email, Tier, IssuedAt, ExpiresAt, Metadata), SignedLicense (Payload, Signature).
  • Key Functions:
    • SignLicense(payload LicensePayload, privKey ed25519.PrivateKey) (*SignedLicense, error): Generates signed Ed25519 license tokens.
    • VerifyLicense(signed *SignedLicense, pubKey ed25519.PublicKey, now time.Time) (*LicensePayload, error): Verifies cryptographic license integrity against offline grace periods.
    • IsWithinGracePeriod(expiresAt time.Time, now time.Time, graceDuration time.Duration) (bool, time.Duration): Enforces 14-day offline grace period calculations.