Skip to content

bruce48x/Lakona / skills/lakona-implement-component

lakona-implement-component

Verified

Implement HotfixComponent tools and resource lifecycles in Server.Hotfix, with optional stable ComponentState in Server.App. Use for resource initialization, constructor dependency ordering, NodeRole selection, State ownership, readiness failures, and migration of application resource logic.

Implement a Lakona Hotfix Component

Keep business logic in Hotfix and stable data/resource handles in App. Reuse DI, role discovery and generation ownership; do not add an Actor, anonymous State, background-task framework or extra container.

Workflow

  1. Read project instructions, relevant README sections, and neighboring components. Inspect installed framework APIs and project roles (ServerApp for App, Hotfix for Hotfix); do not assume this framework's source checkout or contributor docs are present.
  2. Identify consumers, resource ownership and node roles. Consumers inject the concrete component; State has one owner and must not escape it.
  3. Declare a top-level public sealed non-generic component with one public constructor. Keep injected fields private and readonly. If needed, add ComponentState in App: top-level, public, sealed, non-generic, with a public parameterless constructor initializing basic structures only. Do not register State manually or add empty State to stateless tools. State is optional, but its [ComponentState] marker is mandatory for every custom ServerApp dependency injected into a component, including read-only or method-only use. Manual Singleton registration, App interfaces/wrappers and object/dynamic injection do not bypass this rule (LAKONA20061). Keep resource/business APIs in Hotfix; framework services, generated ActorAccess and third-party clients remain valid. State declares fields/auto-properties and basic initialization; ordinary methods, computed properties, indexers and operators belong in Hotfix (LAKONA20062). Only actual IDisposable/IAsyncDisposable implementations may perform mechanical release; inline that release rather than adding State helper methods. Inject at most one State directly by its concrete type, with a required, unkeyed, by-value parameter. Retain it in one private readonly field or private get-only auto-property, or use the primary-constructor capture directly; do not retain both. Do not erase State to object/interfaces or wrap it in arrays, collections, factories or nested generics (LAKONA20061). One State type has one component owner even when NodeRole differs. This restriction also covers unmarked custom App types; external resource interfaces/wrappers and ILogger categories remain valid. App DTO method arguments are unaffected.
  4. Read resource-patterns.md for initialization and disposal. Put optional stable resource registration on the HotfixComponent: [ComponentConfigureServices] public static void ConfigureServices(IServiceCollection services, IConfiguration configuration). Framework discovery invokes it before root Build. Do not add a State solely for registration. This entry accepts unkeyed singletons of closed stable types using types or factories. Root DI materializes resources once; the framework then clears the Hotfix factory delegates, while resources remain alive until node disposal. No Hotfix objects/callbacks may survive in a resource. Constructors and registration do no I/O. Keep client-library dependencies in the App deployment closure.
  5. Add optional ComponentStart/ComponentStop methods: public instance non-generic ValueTask(CancellationToken), with one mandatory by-value token. Each kind occurs at most once; the attribute binds the method, not its name.
  6. Declare component dependencies with required unkeyed concrete parameters. Component interfaces, collections, factories, overrides and service locators are unsupported. Stable infrastructure interfaces remain supported.
  7. Add NodeRole for a role-specific component; no marker means all nodes. Its NodeRole filters registration before requiring data-only configuration. Registration has deterministic component-name ordering, not constructor dependency ordering. Normal DI and TryAdd semantics apply.
  8. Verify changed contracts with focused tests. Resource/readiness changes need real dependency startup or the project's integration/E2E check, including explicit failures. Reuse existing coverage rather than running every scenario below for every edit.

Lifecycle and reload

Start runs once in dependency order before consumers. Final Stop uses the latest generation in recorded reverse order. Reload replaces logic with the same State and runs neither hook. Component full names, effective set and State binding are fixed until restart; dependency changes must preserve the recorded order. Start edits do not reinitialize a running node. State layout changes require restart.

Components allow concurrent ordinary calls without a mailbox or automatic call drain. Use stable synchronization or immutable snapshots. Custom caller owners stop and await them before shutdown. Managed generation execution and ActorStop finish before component Stop; provider/root disposal follows. V1 Start and V3 Stop may run on different instances.

No detached tasks, timers, recurring loops or long-lived Hotfix callbacks belong in components. Use Actor + Behavior and ActorTimer for scheduled work; await finite component I/O. Never retain Hotfix objects, delegates, tasks, providers or collectible metadata in State.

Validation

Cover affected ordering, State identity across real DLL reload, role filtering, illegal registration, failed-candidate cleanup and final disposal. Validate does not run Start. Startup failure keeps readiness closed and preserves the original error. Cleanup failures do not skip other owners; cancellation is not forced interruption. Stop after relevant checks pass and report unverified outcomes.

Select checks for the application's changed resource behavior:

  • Initialization failure keeps the node NotReady and releases failed candidates; successful Start proves the resource usable before Ready.
  • A reload reuses stable State/resources and runs neither lifecycle hook.
  • Custom callers finish before Stop; a failed graceful close does not prevent final disposal or skip other cleanup.
  • Enabled nodes provide the required dependencies/configuration; other nodes do not construct role-specific components or register their resources.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall