feat: add runtime interface and fake implementation

[feloy]

fixes #46
fixes #52

[coderabbitai]

📝 Walkthrough

Walkthrough

A new runtime package is introduced with a pluggable Runtime interface defining lifecycle methods, data structures for creation parameters and runtime metadata, and standard error definitions. A fake in-memory runtime implementation and a thread-safe registry system for managing runtime instances complete the foundation.

Changes

Cohort / File(s)	Summary
Core Runtime Abstraction pkg/runtime/runtime.go, pkg/runtime/errors.go	Introduces Runtime interface with six lifecycle methods (Type, Create, Start, Stop, Remove, Info), CreateParams struct with Name/SourcePath/ConfigPath fields, and RuntimeInfo struct with ID/State/Info map. Defines four exported error variables for common runtime conditions: ErrRuntimeNotFound, ErrInstanceNotFound, ErrRuntimeUnavailable, ErrInvalidParams.
Fake Runtime Implementation pkg/runtime/fake/fake.go, pkg/runtime/fake/fake_test.go	Implements Runtime interface as thread-safe in-memory fake with RWMutex-guarded state. Supports full lifecycle: Create validates params and assigns sequential IDs, Start/Stop manage state transitions, Remove deletes instances, Info retrieves metadata. Comprehensive tests cover lifecycle, error paths, state validation, sequential IDs, and concurrent access.
Runtime Registry System pkg/runtime/registry.go, pkg/runtime/registry_test.go	Introduces Registry interface with Register, Get, and List methods. Thread-safe concrete implementation uses RWMutex-protected map. Validates inputs (rejects nil runtimes and empty types), prevents duplicate registrations, and provides lookup by type with error wrapping. Tests validate registration flow, duplicate detection, listing behavior, nil/empty validation, and concurrent operations.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.79% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding a runtime interface and its fake implementation.
Description check	✅ Passed	The description references the linked issues (#46 and #52) that the PR aims to fix, which is appropriate and related to the changeset.
Linked Issues check	✅ Passed	The PR fully addresses both linked issues: it defines the Runtime interface [#46] and implements a fake runtime with comprehensive tests [#52].
Out of Scope Changes check	✅ Passed	All changes are within scope: runtime interface definition, fake implementation, registry system, and comprehensive tests directly support the linked issue objectives.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[feloy]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[feloy]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

pkg/runtime/fake/fake_test.go (1)

255-262: Add t.Parallel() to subtests for parallel execution.

Per coding guidelines, subtests should also call t.Parallel(). Since subtests share the rt instance, each subtest should create its own runtime to enable safe parallel execution.

♻️ Suggested fix

 	for _, tt := range tests {
+		tt := tt // capture range variable for parallel subtests
 		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			rt := New()
+			ctx := context.Background()
 			_, err := rt.Create(ctx, tt.params)
 			if !errors.Is(err, runtime.ErrInvalidParams) {
 				t.Errorf("Expected ErrInvalidParams, got %v", err)
 			}
 		})
 	}

As per coding guidelines: "All Go test functions must call t.Parallel() as the first line of the test function".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkg/runtime/fake/fake_test.go` around lines 255 - 262, The subtests need to
call t.Parallel() and must not share the parent rt instance: inside the t.Run
callback for each loop iteration, add t.Parallel() as the first statement and
initialize a fresh runtime (instead of using the outer shared rt) so each
subtest uses its own runtime before calling rt.Create(ctx, tt.params); ensure
the parent test also calls t.Parallel() at its start if applicable.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@pkg/runtime/fake/fake_test.go`:
- Around line 255-262: The subtests need to call t.Parallel() and must not share
the parent rt instance: inside the t.Run callback for each loop iteration, add
t.Parallel() as the first statement and initialize a fresh runtime (instead of
using the outer shared rt) so each subtest uses its own runtime before calling
rt.Create(ctx, tt.params); ensure the parent test also calls t.Parallel() at its
start if applicable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8af42093-654b-47f8-afbb-a0405ecdca0a

📥 Commits

Reviewing files that changed from the base of the PR and between 6ac3c35 and 7d16ec7.

📒 Files selected for processing (6)

• pkg/runtime/errors.go
• pkg/runtime/fake/fake.go
• pkg/runtime/fake/fake_test.go
• pkg/runtime/registry.go
• pkg/runtime/registry_test.go
• pkg/runtime/runtime.go