> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Module lifecycle

> Start and stop Neuron extensions safely through runtime inventory

Assembly packages expose long-lived behavior through `Waher.Runtime.Inventory.IModule`. Runtime inventory finds concrete implementations, creates them, calls `Start()`, and later calls `Stop()` during shutdown.

```csharp theme={null}
public interface IModule
{
    Task Start();
    Task Stop();
}
```

Use `IConfigurableModule` when the assembly also contributes setup pages:

```csharp theme={null}
public interface IConfigurableModule : IModule
{
    Task<IConfigurablePage[]> GetConfigurablePages();
}
```

## Ownership rule

Every resource acquired or registered in `Start()` must have one clear owner and a matching release in `Stop()`. Store the exact instance/delegate; many unregister operations require identity equality.

```csharp theme={null}
[Singleton]
public sealed class ExampleModule : IModule
{
    private QueueWebService? endpoint;

    public Task Start()
    {
        HttpAuthenticationScheme[] schemes = HttpModule.GetAuthenticationSchemes();
        this.endpoint = new QueueWebService("/ExampleQueues", schemes);
        Gateway.HttpServer?.Register(this.endpoint);
        return Task.CompletedTask;
    }

    public Task Stop()
    {
        if (this.endpoint is not null && Gateway.HttpServer is not null)
            Gateway.HttpServer.Unregister(this.endpoint);

        this.endpoint = null;
        return Task.CompletedTask;
    }
}
```

The example reuses the queue resource to show the lifecycle. A real package normally registers its own `HttpResource` or a controller router.

## Start safely

1. Validate configuration without logging secrets.
2. Create dependencies that do not publish work.
3. Register routes, stanza handlers, event sinks, and runtime services.
4. Start background loops last.
5. If any step fails, unwind already-created resources before rethrowing.

Do not use fire-and-forget tasks from `Start()`. Keep a cancellation token source and task, surface unexpected termination to the event log, and await the task during `Stop()`.

## Stop safely

1. Stop accepting new work or unregister ingress.
2. Cancel background loops.
3. Await in-flight tasks with a bounded policy.
4. Flush durable state and queues.
5. Unregister handlers, routes, event sinks, and timers.
6. Dispose owned dependencies.

Make `Stop()` safe after a partial start and safe if called once more. Do not dispose gateway-owned singletons such as `Gateway.HttpServer` or the global database provider.

## Runtime inventory

`Types.GetTypesImplementingInterface(...)` and `Types.Instantiate(...)` are used throughout Neuron to discover endpoints, handlers, Script functions, MCP tools, converters, and other extensions. Consequences:

* avoid two discoverable implementations claiming the same route/name/namespace;
* make discovered types concrete and constructible according to the consuming subsystem;
* use `[Singleton]` only when one shared instance is correct;
* expect adding an assembly to change inventory results globally;
* test startup with the same assembly set as production.

## Failure visibility

Log the module/type name and stable event ID. Throwing from `Start()` should prevent a falsely healthy deployment; swallowing registration failures can leave only part of a package active.