framework

func (*App) AddCron ¶

func (a *App) AddCron(s *cron.Scheduler) *App

AddCron registers a Scheduler with the app's lifecycle: it starts when Start runs and stops when Stop runs. Returns the App for chaining so users can wire several schedulers in one expression.

The stop side drains through StopContext so in-flight job goroutines are joined before shutdown proceeds — bounded by the drain deadline, so a job that ignores its (already-cancelled) context can't hang SIGTERM forever.

Worker-scoped: under RoleServe this is a no-op — neither the start hook nor the drainer is registered, so a serve-only shutdown never waits on a scheduler that was never started.

func (*App) AddQueue ¶

func (a *App) AddQueue(q schedulerStartStop) *App

func (*App) CrudHandler ¶

func (a *App) CrudHandler(name string) (*crud.CrudHandler, error)

CrudHandler returns a fully-wired in-process CRUD handler for a registered entity — the same handler shape the HTTP routes use (hooks, events, storage, JSON casing, registry). Use it to call CreateOne/UpdateOne/DeleteOne/ListAll directly, e.g. to compose several writes inside App.InTx (pass the InTx ctx so they join the same transaction). Returns an error if no entity is registered under name or the app has no DB.

func (*App) DBContextMiddleware ¶ added in v0.3.2

func (a *App) DBContextMiddleware() router.Middleware

DBContextMiddleware returns middleware that stamps the App's *sql.DB onto every request context so downstream handlers and screens can retrieve it via DBFromContext. When the App has no DB, the returned middleware is a pass-through.

The App installs this automatically as part of the default middleware chain when a DB is configured, so most apps never call this directly. It's exposed for apps that opt out of the default chain (WithoutDefaultMiddleware) and want to wire DB-in-context into their own chain.

func (*App) Entity ¶

func (a *App) Entity(name string, config entity.EntityConfig) *App

Entity registers an entity with the given name and configuration. Returns the App for fluent chaining. Panics on any misconfiguration — convenient for static, hand-written declarations where a bad config is a programming error you want to fail fast on. For generated or untrusted configs (e.g. an AI-authored field, a dynamic schema) where one bad entity should not crash the process, use TryEntity, which returns the error.

func (*App) Events ¶

func (a *App) Events() *event.EventBus

Events returns the application's event bus.

func (*App) ExportData ¶ added in v0.20.0

func (a *App) ExportData(ctx context.Context, dir string, opts ...ExportOption) error

ExportData dumps every entity's rows plus every registered battery table to a portable archive under dir: one <name>.ndjson per source plus a manifest.json. Reads are raw (all physical columns, all rows including soft-deleted), paged by primary-key keyset. See the package comment for the fidelity and SQL-safety contracts.

func (*App) ExportStatic ¶ added in v0.8.0

func (a *App) ExportStatic(ctx context.Context, dir, basePath string) error

ExportStatic renders the app to a folder of static HTML + assets using the SSG Builder (framework/static). It locates the mounted UIHost and renders every declared route to a directory-style file, plus all /__gofastr assets the runtime needs to boot — runtime.js, the split runtime modules (themeswitch, shortcut, copy, widgets, …), app.css, and per-component CSS — with query-free filenames so the output serves correctly from any static host (GitHub Pages, S3, …).

basePath is the URL subpath the site is served under (e.g. "/gofastr" for a GitHub Pages project site at https://user.github.io/gofastr/); pass "" for an apex deploy. When set, the builder prefixes every root-absolute asset/nav URL in the HTML and bakes the prefix into runtime.js so dynamically-loaded modules resolve under the mount path.

This is the native replacement for the wget mirror the Pages deploy used to ship: declaration-driven (no crawling), and it dumps the split modules the crawl baked a "?v=" into and 404'd.

Returns an error if no uihost.UIHost is mounted.

func (*App) Flags ¶

func (a *App) Flags() *featureflag.Evaluator

Flags returns the app's feature-flag evaluator, creating one on first call. The default backing store is in-memory; for clustered deployments call SetFlagStore with a Redis- or DB-backed implementation BEFORE any caller invokes Flags — once the lazy default fires, subsequent SetFlagStore calls panic to avoid the silent race where some goroutines still hold a reference to the previous evaluator.

The evaluator is also installed as featureflag.Default() so package- level featureflag.Bool(ctx, "...") calls work from anywhere in the app.

func (*App) Group ¶

func (a *App) Group(prefix string, opts ...routegroup.GroupOption) *routegroup.RouteGroup

Group creates a route group with the given prefix and optional configuration. The group supports its own middleware stack, access policy, OpenAPI tags, and MCP namespacing. Nested groups compose prefixes and middleware.

api := app.Group("/api")
api.Use(authMiddleware)
api.Get("/health", healthHandler)

admin := app.Group("/admin", routegroup.WithAccess(access.RequirePermission("admin:access")))
admin.Entity("settings", settingsConfig)

func (*App) GroupEntity ¶

func (a *App) GroupEntity(g *routegroup.RouteGroup, name string, config entity.EntityConfig) *App

GroupEntity registers an entity with the given configuration inside a RouteGroup. CRUD routes mount at <group-prefix>/<entity-table>, MCP tools are namespaced under the group's MCPNamespace, and the OpenAPI tag reflects the group's OpenAPITag if set.

This is the group-scoped equivalent of App.Entity.

func (*App) HookRegistry ¶

func (a *App) HookRegistry(entityName string) *hook.HookRegistry

HookRegistry returns (or creates) the hook registry for a named entity.

func (*App) ImportData ¶ added in v0.20.0

func (a *App) ImportData(ctx context.Context, dir string) error

ImportData restores an archive written by ExportData into the live database. It validates the WHOLE archive before writing a single row (missing manifest, unknown source, incompatible columns, checksum mismatch are all rejected up front), then writes every source inside a single transaction — rolling back on any error. Original ids/timestamps/owner/tenant and soft-deleted rows are preserved verbatim.

func (*App) InTx ¶

func (a *App) InTx(ctx context.Context, fn func(ctx context.Context, tx *sql.Tx) error) error

InTx runs fn inside a database transaction opened on the App's DB. The inner context carries the *sql.Tx so any code path that calls TxFromContext (typed hooks, the various do* helpers, generated repo methods invoked via WithTx) participates atomically.

Convenience wrapper for callers that aren't already inside a CRUD hook — e.g. seeders, batch jobs, multi-entity write paths that need an explicit boundary. If fn returns an error, the tx rolls back and that error is returned unchanged.

func (*App) InitPlugins ¶

func (a *App) InitPlugins() error

InitPlugins initializes all registered plugins and batteries by calling their Init(app) method. Plugins go first (registration order), then batteries (dependency-resolved order). Each module does everything it needs from inside Init — register routes, add middleware, register MCP tools, attach hooks, swap the logger, etc.

Idempotent: the first successful call latches an internal flag so any later call returns nil without re-running plugin Inits. This lets tests call InitPlugins() manually pre-Start without colliding with the implicit call inside Start.

func (*App) IsEnabled ¶

func (a *App) IsEnabled(ctx context.Context, key string) bool

IsEnabled is a convenience wrapper that calls Flags().Bool with the supplied context. Use it from handler code that doesn't otherwise need a direct reference to the evaluator.

The context is expected to already carry an EvalContext (via featureflag.WithContext) when user/tenant gating matters; without one, the call still works but only the kill-switch (Flag.Enabled) and uniform rollout are consulted.

func (*App) JSONCasing ¶

func (a *App) JSONCasing() crud.JSONCase

JSONCasing returns the configured JSON casing strategy. Defaults to CaseCamel if not explicitly set.

func (*App) Lifecycle ¶

func (a *App) Lifecycle() *lifecycle.Lifecycle

Lifecycle returns the App's graceful-shutdown coordinator. Batteries and plugins use Lifecycle().RegisterDrainer / RegisterHealthChecker to participate in Shutdown beyond the simple OnStop hook.

func (*App) Logger ¶

func (a *App) Logger() *slog.Logger

Logger returns the App-local *slog.Logger. Middleware and plugins should call this — not slog.Default() — so that a logging plugin can replace the destination without rewiring globals.

Always non-nil. NewApp seeds the App with a JSON-to-stderr logger that is independent of slog.Default; an unrelated slog.SetDefault elsewhere in the process does not redirect this App's logs.

func (*App) Modules ¶ added in v0.17.0

func (a *App) Modules() *ModuleManager

Modules returns the app's module manager, through which callers can list modules, query enabled state, and toggle modules at runtime.

func (*App) Mount ¶

func (a *App) Mount(m Mountable) *App

Mount attaches a Mountable and registers its routes on the app's router immediately. The default middleware chain is already in place (committed during NewApp), so any handler the Mountable registers is wrapped with it. Returns the app for fluent chaining.

Mountables typically register a NotFound catch-all (e.g. a UI host that renders pages for any unrouted path), so call Mount AFTER any explicit routes you want to take precedence (entity CRUD, custom endpoints).

IMPORTANT — ordering with plugins/batteries: plugin.Init runs at App.Start (or InitPlugins), AFTER Mount has already registered the Mountable's routes. If a plugin's Init registers a more-specific route that overlaps with a Mountable's NotFound catch-all, the plugin's route still wins (ServeMux dispatches by specificity, not by registration order). But if a plugin registers a Mountable-style catch-all itself, it shadows any user routes added after Mount but before InitPlugins. Mount last unless you know what you're doing.

func (*App) Mountables ¶

func (a *App) Mountables() []Mountable

Mountables returns the Mountables registered via Mount, in registration order. Batteries use it to discover a mounted UI host (type-asserting to *uihost.Host) so they can register screens on the host's render pipeline rather than spinning up a second host. Returns a copy — callers must not mutate the App's internal slice.

func (*App) MustCrudHandler ¶

func (a *App) MustCrudHandler(name string) *crud.CrudHandler

MustCrudHandler is CrudHandler that panics on error — for app setup where a missing entity is a programming mistake.

func (*App) NewModuleMigrationCoordinator ¶ added in v0.31.0

func (a *App) NewModuleMigrationCoordinator(opts ...CoordinatorOption) (*MigrationCoordinator, error)

NewModuleMigrationCoordinator builds the short-lived migration coordinator for a process module (design §7). The operator (or a CLI / deploy job) calls it, runs MigrationCoordinator.Apply with the digest-verified migration set, and the coordinator provisions the per-module Postgres schema+role, runs Up authenticated as that role, and stamps MigrationsAppliedAt so the supervisor lets the module reach Ready. Returns an error if no process modules are registered.

For the Postgres path, pass WithCoordinatorAdminDSN with the host's URL-form DSN (the same one the app boots against). SQLite is trusted/dev-only — the coordinator rejects an untrusted module's migrations on SQLite (fail-closed, design §7 decision F).

func (*App) OnReady ¶ added in v0.5.0

func (a *App) OnReady(fn func(addr string)) *App

OnReady registers a function to run once the HTTP listener has bound successfully, just before the server begins accepting connections. The addr passed in is the listener's resolved address (a ":0" request arrives with the real port), so it is safe to print in a startup banner: every earlier phase — auto-migrate, seeds, plugin init, OnStart hooks, and the bind itself — has already succeeded. Hooks run in registration order and must not block.

func (*App) OnStart ¶

func (a *App) OnStart(fn func(ctx context.Context) error) *App

OnStart registers a function to run once during App.Start, before the HTTP server begins accepting connections. The context passed in is cancelled when Stop is called, so workers should respect it.

Hooks run in registration order; the first to return a non-nil error aborts Start.

func (*App) OnStop ¶

func (a *App) OnStop(fn func() error) *App

OnStop registers a function to run during App.Shutdown, after the HTTP server has shut down. Hooks run in reverse registration order — the last thing started is the first thing stopped. Internally the hook is wrapped as a lifecycle.Drainer so app-level cleanup and battery drains share one coordinator.

func (*App) OnStopFirst ¶

func (a *App) OnStopFirst(fn func() error) *App

OnStopFirst registers an OnStop hook that runs LAST under the reverse-order Stop iteration. Useful for plugins (battery/log especially) that must outlive every other shutdown step: their close hook needs to fire AFTER every other OnStop has had a chance to emit log entries.

Without this, a user that registers app.OnStop BEFORE RegisterPlugin(log) gets the order inverted on reverse iteration — log's close runs first, the user's OnStop logs into closed sinks.

func (*App) Outbox ¶ added in v0.15.0

func (a *App) Outbox() *outbox.Outbox

Outbox returns the transactional event outbox, or nil when the app was built without WithOutbox. Use it to stage your own events inside an App.InTx transaction (Append), inspect delivery state (List), or replay dead rows.

func (*App) ProcessModules ¶ added in v0.31.0

func (a *App) ProcessModules() *ProcessModuleSupervisor

ProcessModules returns the process-module supervisor, or nil when the app registered no process modules. Through it the operator enables / disables / revokes a module at runtime.

func (*App) RegisterBattery ¶

func (a *App) RegisterBattery(b Battery, deps ...string) *App

RegisterBattery registers a heavyweight, lifecycle-aware battery module (auth, search, cache, etc.) with the application. deps lists battery names that must be initialized before this one. Returns the App for chaining.

Batteries are initialized in dependency-resolved order during App.Start, before the HTTP server binds. Each battery's Init does whatever it needs by calling into the App (routes, middleware, hooks, MCP tools). Batteries that also implement BatteryLifecycle get their OnStart/OnStop fired by the App at the appropriate moment.

Example:

app.RegisterBattery(auth.New(auth.Config{...}), "search") // depends on search battery

func (*App) RegisterEntities ¶

func (a *App) RegisterEntities(entities map[string]entity.EntityConfig) *App

RegisterEntities registers each (name, config) pair via App.Entity in alphabetical-by-name order. Sorting matters: Entity has order-sensitive side effects — router registration, MCP tool list order, OpenAPI tag emission — and Go's map iteration is randomised, so unsorted iteration would mean non-deterministic /openapi.json bytes across restarts (breaking ETag caching) and non-deterministic MCP tools/list responses. FK relations stay safe because AutoMigrate also topologically sorts.

Returns the App for fluent chaining.

app.RegisterEntities(map[string]entity.EntityConfig{
    "foods":  foodsConfig,
    "meals":  mealsConfig,
    "users":  usersConfig,
})

func (*App) RegisterModule ¶ added in v0.17.0

func (a *App) RegisterModule(m Module) *App

RegisterModule validates the name, registers the module as a battery (with deps = Manifest().DependsOn so topo-sort orders module init), and records the manifest in the module manager.

app.RegisterModule(myModule) // registers as battery + records manifest

func (*App) RegisterPlugin ¶

func (a *App) RegisterPlugin(plugin Plugin) *App

RegisterPlugin registers a plugin with the application's plugin manager. Returns the App for fluent chaining.

Panics if InitPlugins has already run — plugins must be registered before App.Start (or the explicit InitPlugins call) so their Init fires. The panic is a clear contract violation rather than a silent no-op that would have the new plugin's routes / middleware vanish.

func (*App) RegisterProcessModule ¶ added in v0.31.0

func (a *App) RegisterProcessModule(desc ProcessModuleDescriptor, approved ApprovedGrants) *App

RegisterProcessModule installs a process-isolated third-party module (issue #37, wave 2a). It validates the descriptor, ensures the ProcessModuleStore schema, registers the module with the supervisor AND the in-process ModuleManager (so the route gate 404s when the module is disabled), mounts each declared route behind the gate, and wires the supervisor as the process-module coordinator for ModuleManager.List introspection.

Routes are attributed to the module name via setCurrent/clearCurrent so the existing route gate (Enabled → 404, indistinguishable from uninstalled) governs them. The Ready layer lives in the proxy handler (enabled-but-not-Ready → 503 + Retry-After). The supervisor's loops are started in [App.runStartHooks]; the drain drainer is registered via lifecycle.PrependDrainer so children drain first during shutdown.

Panics on validation or schema errors (caller-time misconfiguration — the descriptor is operator-supplied at install). Returns the App for chaining.

func (*App) RegisterReadiness ¶

func (a *App) RegisterReadiness(name string, check func(ctx context.Context) error) *App

RegisterReadiness adds a readiness check. Names are not required to be unique — duplicates surface in the /readyz response as repeated rows, which is occasionally useful (the same backend probed at two layers).

Pass a timeout on the context if your check could hang; /readyz also applies an overall deadline, but per-check timeouts give better signal in the response.

func (*App) Role ¶ added in v0.16.0

func (a *App) Role() Role

Role returns the resolved process role (all/serve/worker). It is set once in NewApp and never changes afterward, so OnStart hooks and other setup code can gate their own background work on it — e.g. skipping an expensive warm-up that only makes sense when serving HTTP:

app.OnStart(func(ctx context.Context) error {
    if app.Role() == framework.RoleWorker {
        return nil // the worker process doesn't serve this cache
    }
    return warmRenderCache(ctx)
})

Plain OnStart hooks are role-agnostic and run in every role; worker- scoped registration (cron/queue/outbox) is gated internally.

func (*App) Router ¶

func (a *App) Router() *router.Router

Router returns the App's *router.Router for advanced use (plugin authors, batteries that need to register routes with custom matching, sub-router construction). Application code should prefer the App-level helpers:

• App.Use(mw) — register middleware (instead of Router().Use)
• App.Get/Post/... — register routes (instead of Router().Handle)
• App.Group(prefix) — sub-routes (instead of Router().Group)

Both forms are functionally equivalent — App.Use forwards to Router().Use — but the App-level surface is the canonical one in docs and examples.

Exposed as a method (rather than a field) so plugins and batteries can swap or wrap the router during Init without callers depending on direct field assignment.

func (*App) Routine ¶

func (a *App) Routine(r migrate.Routine) *App

Routine registers a stored routine (function, procedure, trigger, or view) as a first-class migration object. Its Up runs on every boot (idempotent CREATE OR REPLACE) after tables are migrated, and `migrate generate` tracks it for reversible versioned migrations. Returns App for chaining.

func (*App) RoutinesFS ¶ added in v0.30.0

func (a *App) RoutinesFS(fsys fs.FS, dir string) *App

RoutinesFS loads routines authored as embedded SQL files via migrate.RoutinesFS and registers each one as if App.Routine had been called on it. This is the primary authoring path for stored procedures: an app writes `db/routines/compute_totals.pg.sql` containing `CREATE OR REPLACE FUNCTION …` and calls `app.RoutinesFS(embeddedFS, "db/routines")`. See migrate.RoutinesFS for the filename grammar (`<name>.sql`, `<name>.down.sql`, `<name>.pg.sql`, `<name>.sqlite.sql`) and the loud-rejection rules (empty file, empty dir, plain+dialect Up collision). A loader error panics at registration time — mirroring App.View's misconfig panic — so the exact embed-path/file error surfaces in the console instead of shipping a half-loaded routine set.

func (*App) RunReadinessChecks ¶ added in v0.17.0

func (a *App) RunReadinessChecks(ctx context.Context) ReadinessResponse

RunReadinessChecks executes all registered readiness checks in parallel and returns the structured response. Exported so batteries (e.g. battery/setup's HealthStep) can run the same checks /readyz does without going through HTTP.

func (*App) RunWithSignals ¶

func (a *App) RunWithSignals(ctx context.Context) error

RunWithSignals blocks until SIGINT or SIGTERM is received, then runs Shutdown. Returns Shutdown's error, or nil if ctx is cancelled before a signal arrives.

func (*App) SetFlagStore ¶

func (a *App) SetFlagStore(s featureflag.Store) *App

SetFlagStore swaps the underlying store. Must be called before any caller has triggered the lazy default; a second SetFlagStore call (or any call after Flags() / IsEnabled has already been used) panics to avoid the silent race where stale references to the previous evaluator persist in handler closures.

Useful for tests that want a preconfigured store, or for production wiring that uses a persistent backend — wire it during NewApp setup, before any request runs.

func (*App) SetLogger ¶

func (a *App) SetLogger(l *slog.Logger)

SetLogger replaces the App's logger. Atomic; safe to call concurrently with in-flight requests — atomic.Pointer.Store is race-free, and middleware reading via App.Logger() sees the new value on the next request.

Panics if l is nil — the App's logger is always non-nil; pass a discard logger (slog.New(slog.DiscardHandler)) to silence output.

func (*App) Shutdown ¶

func (a *App) Shutdown(ctx context.Context) error

Shutdown gracefully stops the HTTP server, stops every registered battery in reverse dependency order, then runs each OnStop hook in reverse registration order. Matches net/http.Server.Shutdown's signature (takes a deadline ctx) but does the FULL lifecycle teardown. Safe to call multiple times — subsequent calls are no-ops.

Call this from your signal handler.

func (*App) Start ¶

func (a *App) Start(addr string) error

Start starts the HTTP server on the given address.

func (*App) T ¶

func (a *App) T(ctx context.Context, key string, params ...map[string]any) string

T is a convenience wrapper around the app's Translator. Returns the bare key when no Translator has been wired via WithI18n.

The ctx is expected to already carry a Locale (the i18n middleware attaches one per request from Accept-Language); when it doesn't, the Translator's fallback locale is used.

func (*App) Table ¶

func (a *App) Table(t migrate.Table) *App

Table registers a raw, non-entity table for migration only — no CRUD, no HTTP routes, no validation, no auto-injected columns. The table participates in auto-migrate, diffing, and generation alongside entities (including foreign keys that cross between the two). For users who want migration coverage of a table without the entity machinery. Returns App for chaining.

func (*App) Translator ¶

func (a *App) Translator() *i18n.Translator

Translator returns the wired Translator, or nil if WithI18n was never called. Useful for handlers that need to drive locale-aware formatting beyond simple lookups.

func (*App) TryEntity ¶

func (a *App) TryEntity(name string, config entity.EntityConfig) (err error)

TryEntity is the error-returning variant of Entity: it registers an entity and returns an error on any misconfiguration instead of panicking. It also recovers panics from deeper validation (e.g. an invalid TenantField) and converts them to errors, so a single bad config can never take down the process — the property an agent-driven authoring loop needs.

func (*App) Use ¶

func (a *App) Use(mw ...router.Middleware) *App

Use appends middleware to the app's router chain. The default chain (installed by NewApp unless WithoutDefaultMiddleware is set) stays in place — Use adds to it, never silently replaces it. Plugins call Use from their Init to contribute middleware; router late-binding means these additions also wrap routes registered before the plugin loaded.

func (*App) View ¶

func (a *App) View(v migrate.View) *App

View registers a database view — a virtual table built from other entities. The view is created on boot after its source tables (and tracked reversibly by `migrate generate`), and, when it declares Columns, it is also exposed through the ORM as a READ-ONLY entity: List/Get and the query layer work, but no write routes are registered. Returns App for chaining.

func (*App) WithAuditLog ¶

func (a *App) WithAuditLog(cfg AuditConfig) *App

WithAuditLog enables audit logging on every entity registered on the app (or the subset named in cfg.Entities). Call AFTER Entity registrations.

Returns the app for fluent chaining. Panics if the audit table cannot be created — this is initialization-time work so loud failure is preferable to silent log loss.

func (*App) WithSeed ¶ added in v0.3.2

func (a *App) WithSeed(fn func(ctx context.Context) error) *App

WithSeed registers a seed function to run during App.Start AFTER auto-migration completes (so every entity table exists) and BEFORE the HTTP server accepts traffic. This is the documented fix for the common "no such table" footgun: calling db.Exec("INSERT …") from main() before Start() runs migrations fails, because the table isn't there yet.

Seed funcs run in registration order. The first to return a non-nil error aborts Start (the partial-startup teardown drains anything an earlier phase spawned). The context is the app's lifecycle context, so a long-running seed respects shutdown.

WithSeed composes with the per-entity EntityConfig.Seed callback: entity seeds (idempotent, ledger-tracked via _gofastr_seeded) run first as part of auto-migration's RunSeeds phase; WithSeed funcs run immediately after, in the order registered. Use WithSeed for cross-entity or app-level seed logic that doesn't belong to a single entity.

site := framework.NewApp(framework.WithDB(db))
site.Entity("foods", foodsConfig)
site.WithSeed(seedFoods) // runs after the foods table is migrated

Returns the App for fluent chaining.

func (*BatteryManager) All ¶

func (bm *BatteryManager) All() []Battery

All returns all registered batteries in dependency-resolved order.

func (*BatteryManager) Get ¶

func (bm *BatteryManager) Get(name string) (Battery, error)

Get retrieves a battery by name. Returns the Battery interface so callers can type-assert to the concrete type or any optional interface.

func (*BatteryManager) InitAll ¶

func (bm *BatteryManager) InitAll(app *App) error

InitAll initializes all batteries in dependency order. Called during App.Start before the HTTP server binds.

func (*BatteryManager) Names ¶

func (bm *BatteryManager) Names() []string

Names returns battery names in dependency-resolved order.

func (*BatteryManager) Register ¶

func (bm *BatteryManager) Register(b Battery, deps ...string) error

Register adds a battery with optional dependency declarations. Deps lists battery names that must be initialized before this one. Returns an error on duplicate name or unknown dependency.

func (*BatteryManager) StartAll ¶

func (bm *BatteryManager) StartAll(ctx context.Context) error

StartAll calls OnStart on batteries that implement BatteryLifecycle, in dependency order (dependencies first).

func (*BatteryManager) StopAll ¶

func (bm *BatteryManager) StopAll(ctx context.Context) error

StopAll calls OnStop on batteries that implement BatteryLifecycle, in reverse dependency order (dependents first, then dependencies).

func (*Broker) InstallHandlers ¶ added in v0.31.0

func (b *Broker) InstallHandlers(p *moduleproto.Peer, view ModuleGrantView)

InstallHandlers registers the six host.* reverse-request handlers (design §4.4) on p, each scoped to view. Handlers are registered once per child connection; the view captures the spawn's effective grant set + generation.

func (*Broker) MintDelegation ¶ added in v0.31.0

func (b *Broker) MintDelegation(r *http.Request, parentCallID uint64) (string, func())

MintDelegation stashes a snapshot of the originating request under a random opaque handle and returns it with a release func. The supervisor attaches the handle to module.http's Caller block; the child echoes it on reverse host.* calls so the broker can re-attach THIS request's caller context to the CRUD re-dispatch. release() MUST be called when the parent call returns (including buffered-503 crash paths) so the in-memory table does not leak. A nil r is the ambient (caller-less) path — MintDelegation is still legal but returns an empty handle the broker treats as ambient.

func (ConformanceReport) Conforms ¶ added in v0.31.0

func (r ConformanceReport) Conforms() bool

Conforms reports whether the backend qualifies for an untrusted module per design §6: Available AND every probe P1–P7 passed. Any failure or unreachable disqualifies — there is no partial conformance, and the supervisor fail-closes rather than silently downgrading to TrustedProcessRunner.

func (ConformanceReport) Result ¶ added in v0.31.0

func (r ConformanceReport) Result(id ProbeID) ProbeResult

Result returns the ProbeResult for id, or a zero-value result if the probe was not run.

func (ConformanceReport) Summary ¶ added in v0.31.0

func (r ConformanceReport) Summary() string

Summary renders the report as a multi-line human-readable string for logs / test output. One line per probe: "P1 pass Distinct OS principal".

func (*CoordinatorValidationError) Error ¶ added in v0.31.0

func (e *CoordinatorValidationError) Error() string

func (*CoordinatorValidationError) Is ¶ added in v0.31.0

func (e *CoordinatorValidationError) Is(target error) bool

Is lets callers errors.Is against the rule even when wrapped.

func (*DescriptorValidationError) Error ¶ added in v0.31.0

func (e *DescriptorValidationError) Error() string

func (*DescriptorValidationError) Is ¶ added in v0.31.0

func (e *DescriptorValidationError) Is(target error) bool

Is lets callers errors.Is against DescriptorValidationError if they wrap it.

func (*ExecutableSHAMismatchError) Error ¶ added in v0.31.0

func (e *ExecutableSHAMismatchError) Error() string

func (*InMemoryModuleStore) Load ¶ added in v0.17.0

func (s *InMemoryModuleStore) Load(_ context.Context) (map[string]bool, error)

Load returns the current enable/disable map (possibly empty).

func (*InMemoryModuleStore) SetEnabled ¶ added in v0.17.0

func (s *InMemoryModuleStore) SetEnabled(_ context.Context, name string, enabled bool) error

SetEnabled persists the enabled state in memory.

func (*MigrationCoordinator) Apply ¶ added in v0.31.0

func (c *MigrationCoordinator) Apply(ctx context.Context, desc ProcessModuleDescriptor, migs []ApprovedMigration) error

Apply validates the migration set (Plan), then runs it under the §7 isolation model. On success it stamps MigrationsAppliedAt and advances the store generation so the supervisor lets the module reach Ready.

Postgres: provisions a restricted per-module schema + role, opens a separate *sql.DB AUTHENTICATED AS that role (not SET ROLE down from a powerful session — design §7 load-bearing point 2), and runs Up under the advisory lock with the schema-local _migrations tracking table.

SQLite: there is no roles/GRANT/schemas boundary (design §7 / decision F). Untrusted modules are rejected loud (fail-closed). Trusted/dev-only modules run Up against the host pool — trusted-only, never a claim that groups make SQLite DDL safe.

func (*MigrationCoordinator) Dialect ¶ added in v0.31.0

func (c *MigrationCoordinator) Dialect() migrate.Dialect

Dialect reports the detected dialect (debug / introspection).

func (*MigrationCoordinator) Plan ¶ added in v0.31.0

func (c *MigrationCoordinator) Plan(desc ProcessModuleDescriptor, migs []ApprovedMigration) (*CoordinatorPlan, error)

Plan is the pure, DB-free validation of an approved migration set against the descriptor's group. It enforces (design §7):

• the descriptor MUST declare a named migration group (default-group migrations are rejected — a module cannot inject into the host's own group);
• every migration runs under that one group (group-equality);
• no duplicate (Version) within the set;
• each migration's computed SHA256(Up) matches its approved digest.

It also produces non-authoritative lint warnings (statements beyond plain CREATE TABLE / ALTER TABLE ADD COLUMN / CREATE INDEX) for operator review. The role is the real boundary; this lint never blocks (design §7 "no parse-allowlist").

func (*ModuleManager) Disable ¶ added in v0.17.0

func (mm *ModuleManager) Disable(ctx context.Context, name string) error

Disable persists the new state and flips the cache. Refuses (fail closed) if any currently-enabled module lists name in DependsOn — no cascade. Serialized by toggleMu alongside Enable.

func (*ModuleManager) Enable ¶ added in v0.17.0

func (mm *ModuleManager) Enable(ctx context.Context, name string) error

Enable persists the new state and flips the cache. Refuses if any of the module's DependsOn is disabled. The check-then-act sequence (dependency check → store write → cache flip) is serialized by toggleMu so concurrent toggles cannot interleave to a forbidden state.

func (*ModuleManager) Enabled ¶ added in v0.17.0

func (mm *ModuleManager) Enabled(name string) bool

Enabled is the hot-path read the dispatch gates use. A single map read under RLock; absent modules are enabled by default.

func (*ModuleManager) List ¶ added in v0.17.0

func (mm *ModuleManager) List() []ModuleInfo

List returns introspection info for every registered module.

func (*ModuleManager) SetProcessCoordinator ¶ added in v0.31.0

func (mm *ModuleManager) SetProcessCoordinator(pc processModuleCoordinator)

SetProcessCoordinator installs the process-module coordinator. Called once by App wiring (RegisterProcessModule / a With… option); subsequent calls overwrite the prior coordinator. Passing nil disables the hook.

func (*ModuleToolRegistry) GateForModule ¶ added in v0.31.0

func (r *ModuleToolRegistry) GateForModule(moduleName string) error

GateForModule is the module-tool half of the composite call gate. Disabled module → non-nil error (tool OMITTED from tools/list and refused by tools/call, indistinguishable from uninstalled — design §8 "not-enabled → omitted+refused"). Enabled module → nil (tool LISTED; the handler enforces the Ready layer and returns a retryable error when the child is not yet serving). This split mirrors the route gate's Enabled-only 404 vs the proxy handler's 503.

func (*ModuleToolRegistry) ModuleFor ¶ added in v0.31.0

func (r *ModuleToolRegistry) ModuleFor(toolName string) (string, bool)

ModuleFor reports which module owns a namespaced tool name (or "" / ok=false for a non-module tool). The composite call gate consults this to route module tools to [GateForModule] and leave everything else on the existing in-process gate.

func (*ModuleToolRegistry) RegisterTools ¶ added in v0.31.0

func (r *ModuleToolRegistry) RegisterTools(moduleName string, tools []moduleproto.Tool) error

RegisterTools installs each tool under `module.<name>.<tool>` after the supervisor has verified the tool list against the descriptor digests. Idempotent across respawns: a tool already tracked for THIS module is left in place (its MCP handler dispatches dynamically, so the stale handler is still correct). A name already owned by a DIFFERENT module, or shadowed by a non-module tool already in the server, is a hard collision and returns an error.

func (*ModuleToolRegistry) UnregisterTools ¶ added in v0.31.0

func (r *ModuleToolRegistry) UnregisterTools(moduleName string) error

UnregisterTools is a tracking-only no-op in v1: core/mcp has no tool-removal API, so the tool stays in the server. Visibility is gated by the composite call gate (a disabled/uninstalled module's tools are omitted + refused). owner[] is intentionally kept populated so GateForModule keeps refusing the tool until the module re-registers; clearing it here would let the tool leak back through the in-process gate's "no owner → pass" path. Documented as a known limitation for v1.

func (NopBroker) InstallHandlers ¶ added in v0.31.0

func (NopBroker) InstallHandlers(p *moduleproto.Peer, _ ModuleGrantView)

InstallHandlers registers deny-all handlers on p for every host.* method in the moduleproto catalog. The view is accepted but unused — a NopBroker grants nothing by construction.

func (NopBroker) MintDelegation ¶ added in v0.31.0

func (NopBroker) MintDelegation(_ *http.Request, _ uint64) (string, func())

MintDelegation returns an empty handle and a no-op release. Under NopBroker no reverse call can succeed anyway, so the handle is unused; the empty string is a legal Caller.Delegation value (omitted on the wire).

func (*PluginManager) All ¶

func (pm *PluginManager) All() []Plugin

All returns all registered plugins in order.

func (*PluginManager) Get ¶

func (pm *PluginManager) Get(name string) (Plugin, error)

Get retrieves a plugin by name.

func (*PluginManager) InitAll ¶

func (pm *PluginManager) InitAll(app *App) error

InitAll initializes all plugins in registration order.

Wraps each Init in a deferred recover so a panic — most commonly `http: multiple registrations for ...` from a duplicate route pattern — gets tagged with the offending plugin's name. Without this the panic surfaces deep in ServeMux with no context about which plugin registered the conflicting route.

Tracks per-plugin init state so that a retry after partial failure (App.InitPlugins rolls back its global latch on error) only re-runs plugins that haven't already applied side effects. Without this a retry would re-Register the routes the successful plugins already added and panic on the ServeMux duplicate-pattern check.

func (*PluginManager) Names ¶

func (pm *PluginManager) Names() []string

Names returns the names of all registered plugins in registration order.

func (*PluginManager) Register ¶

func (pm *PluginManager) Register(plugin Plugin) error

Register adds a plugin to the manager. Returns an error if a plugin with the same name is already registered, or if the name is invalid (empty, whitespace-only, contains a control character, or longer than maxModuleNameLen).

func (ProbeID) String ¶ added in v0.31.0

func (p ProbeID) String() string

String renders a ProbeID as its design-table label ("P1".."P7").

func (ProbeID) Title ¶ added in v0.31.0

func (p ProbeID) Title() string

Title is the human-readable property name from the §6 table.

func (ProbeStatus) String ¶ added in v0.31.0

func (s ProbeStatus) String() string

String renders a ProbeStatus for logs and test output.

func (*ProcessModuleSupervisor) BumpGeneration ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) BumpGeneration(ctx context.Context, name string) (uint64, error)

BumpGeneration is the upgrade lever (design §8): increments the desired generation and wakes every replica's reconcile loop. The supervisor will drain the old child and spawn a fresh one for the new generation.

func (*ProcessModuleSupervisor) Close ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Close(ctx context.Context) error

Close stops every supervise loop, drains every child with a short deadline, and waits for the loops to exit. Idempotent. It does NOT close the store (the store is shared across the app and closed elsewhere).

func (*ProcessModuleSupervisor) Closed ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Closed() bool

Closed reports whether Close has been called.

func (*ProcessModuleSupervisor) DeclaredRoutes ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) DeclaredRoutes(name string) []RouteDeclaration

DeclaredRoutes returns the descriptor's declared routes for the host wiring to iterate when registering proxy routes with the router.

func (*ProcessModuleSupervisor) Disable ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Disable(ctx context.Context, name string) error

Disable marks a module desired-disabled in the store and wakes its supervise loop (which drains the child).

func (*ProcessModuleSupervisor) Drain ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Drain(ctx context.Context) error

Drain is the lifecycle.Drainer entry point. It drains every child concurrently (design §8: a single shared 30s budget across the app, so a per-child 30s drain applied serially to N children would blow the budget). Each child gets min(DrainPerModule, remaining shared budget).

func (*ProcessModuleSupervisor) Enable ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Enable(ctx context.Context, name string) error

Enable marks a module desired-enabled in the store and wakes its supervise loop. Returns ErrNoDesiredRow (wrapped) if the module is not registered.

func (*ProcessModuleSupervisor) Info ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Info(name string) (ProcessModuleInfo, error)

Info returns the introspection snapshot for name, or ErrNoDesiredRow (wrapped) if the module is not registered.

func (*ProcessModuleSupervisor) List ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) List() []ProcessModuleInfo

List returns introspection for every registered process module, ordered by name.

func (*ProcessModuleSupervisor) ProxyHandler ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) ProxyHandler(name, routeID string) http.Handler

ProxyHandler returns the http.Handler the host router mounts for one declared route. The route gate (Enabled) has ALREADY run by the time this handler is invoked — if the module is disabled, the route 404'd upstream and this handler was never reached.

This handler implements the SECOND layer of the §8 two-layer gate: the Ready check. Enabled-but-not-Ready → 503 + Retry-After (design decision D). On Ready it proxies the request via module.http, FULLY BUFFERING the response before committing any headers (the buffered-503 guarantee: a child that dies mid-call yields a buffered 503, never a truncated 200).

name is the module name; routeID is the descriptor's stable route id.

func (*ProcessModuleSupervisor) Reconcile ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Reconcile(name string)

Reconcile pokes the named module's supervise loop. It is the single entry point the three reconcile sources funnel into (local enable/ disable, handleRemoteToggle after its store re-read, periodic generation poll — design §8). Safe to call for unknown names (no-op).

func (*ProcessModuleSupervisor) Register ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Register(ctx context.Context, d ProcessModuleDescriptor, approved ApprovedGrants) (RegisterResult, error)

Register validates the descriptor, installs a desired-state row in the store, and registers the module for supervision. It is idempotent on the descriptor — calling it twice for the same name returns ErrModuleInstalled (the store row already exists). The supervisor's per-module loop is started lazily by ProcessModuleSupervisor.StartLoops or implicitly by ProcessModuleSupervisor.Enable.

The caller is responsible for route registration (attributing routes to the module name so the existing route gate 404s when disabled). The supervisor exposes [ProcessModuleSupervisor.Routes] for the host wiring to iterate when it calls the router.

func (*ProcessModuleSupervisor) RevokeGrants ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) RevokeGrants(ctx context.Context, name string, grants []access.Permission) (uint64, error)

RevokeGrants replaces the effective grants AND bumps generation — every replica's next reconcile observes the higher generation and restarts the child with the narrowed view (design §5 "binding + revocation"). Returns the new generation.

func (*ProcessModuleSupervisor) Slot ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) Slot(name string) *moduleSlot

Slot returns the live slot for name, or nil if unregistered. Used by the host wiring to attribute routes / consult state.

func (*ProcessModuleSupervisor) StartLoops ¶ added in v0.31.0

func (s *ProcessModuleSupervisor) StartLoops()

StartLoops launches every registered module's supervise loop and the global periodic poll. Idempotent; called by the app wiring at Start. After StartLoops, a subsequently-Registered module has its loop started by Enable (which itself wakes the slot).

func (ProcessState) String ¶ added in v0.31.0

func (s ProcessState) String() string

String makes ProcessState log-friendly and operator-readable.

func (*Registry) All ¶

func (r *Registry) All() map[string]*entity.Entity

All returns a copy of the map of all registered entities. Map iteration order is randomised by Go; use AllSorted() for stable iteration in code paths that emit order-sensitive output.

func (*Registry) AllSorted ¶

func (r *Registry) AllSorted() []*entity.Entity

AllSorted returns every registered entity in alphabetical order by name. Use this whenever the iteration order affects bytes-on-the-wire (OpenAPI tag emission, LLM-markdown, codegen output) so the same registry produces the same artefact across restarts.

func (*Registry) Get ¶

func (r *Registry) Get(name string) (*entity.Entity, error)

Get retrieves an Entity by name. Returns an error if no entity with that name is registered.

func (*Registry) Register ¶

func (r *Registry) Register(ent *entity.Entity) error

Register adds an Entity to the registry. Returns an error if an entity with the same name already exists.

func (*Registry) SetDB ¶

func (r *Registry) SetDB(db *sql.DB)

SetDB sets the database connection on the registry and propagates it to all registered entities.

func (*SQLModuleStore) Load ¶ added in v0.17.0

func (s *SQLModuleStore) Load(ctx context.Context) (map[string]bool, error)

Load returns every persisted enable/disable row.

func (*SQLModuleStore) SetEnabled ¶ added in v0.17.0

func (s *SQLModuleStore) SetEnabled(ctx context.Context, name string, enabled bool) error

SetEnabled upserts a module's enabled state.

func (*SQLProcessModuleStore) BumpGeneration ¶ added in v0.31.0

func (s *SQLProcessModuleStore) BumpGeneration(ctx context.Context, module string) (uint64, error)

BumpGeneration atomically increments desired_generation and returns the new value.

func (*SQLProcessModuleStore) DeleteHeartbeat ¶ added in v0.31.0

func (s *SQLProcessModuleStore) DeleteHeartbeat(ctx context.Context, module, replicaID string) error

DeleteHeartbeat removes a replica's heartbeat row.

func (*SQLProcessModuleStore) Dialect ¶ added in v0.31.0

func (s *SQLProcessModuleStore) Dialect() migrate.Dialect

Dialect reports the detected dialect (debug / introspection).

func (*SQLProcessModuleStore) EnsureSchema ¶ added in v0.31.0

func (s *SQLProcessModuleStore) EnsureSchema(ctx context.Context) error

EnsureSchema creates the desired-state and heartbeat tables idempotently. DDL is dialect-aware (Postgres vs SQLite). The schema is intentionally narrow: no module-owned DDL touches this store (design §7 — host coordination state, NOT module bookkeeping).

func (*SQLProcessModuleStore) GetDesired ¶ added in v0.31.0

func (s *SQLProcessModuleStore) GetDesired(ctx context.Context, module string) (DesiredState, error)

GetDesired returns the desired-state row, or ErrNoDesiredRow if absent.

func (*SQLProcessModuleStore) Install ¶ added in v0.31.0

func (s *SQLProcessModuleStore) Install(ctx context.Context, d DesiredState) error

Install writes a new desired-state row. Returns ErrModuleInstalled if a row already exists for the module.

func (*SQLProcessModuleStore) ListDesired ¶ added in v0.31.0

func (s *SQLProcessModuleStore) ListDesired(ctx context.Context) ([]DesiredState, error)

ListDesired returns every desired-state row, ordered by module name.

func (*SQLProcessModuleStore) LiveReplicas ¶ added in v0.31.0

func (s *SQLProcessModuleStore) LiveReplicas(ctx context.Context, module string, ttl time.Duration) ([]ReplicaHeartbeat, error)

LiveReplicas returns heartbeat rows whose updated_at is within now-ttl..now.

func (*SQLProcessModuleStore) RecordHeartbeat ¶ added in v0.31.0

func (s *SQLProcessModuleStore) RecordHeartbeat(ctx context.Context, module, replicaID string, observedGen uint64, phase string) error

RecordHeartbeat upserts a replica heartbeat row.

func (*SQLProcessModuleStore) SetEffectiveGrants ¶ added in v0.31.0

func (s *SQLProcessModuleStore) SetEffectiveGrants(ctx context.Context, module string, grants []access.Permission) (uint64, error)

SetEffectiveGrants replaces the effective grant JSON AND bumps generation.

func (*SQLProcessModuleStore) SetEnabled ¶ added in v0.31.0

func (s *SQLProcessModuleStore) SetEnabled(ctx context.Context, module string, enabled bool) error

SetEnabled toggles enabled without bumping generation.

func (*SQLProcessModuleStore) SetMigrationsAppliedAt ¶ added in v0.31.0

func (s *SQLProcessModuleStore) SetMigrationsAppliedAt(ctx context.Context, module string, at *time.Time) error

SetMigrationsAppliedAt records (or clears) the migrations-applied timestamp.

func (*SandboxRunner) Backend ¶ added in v0.31.0

func (r *SandboxRunner) Backend() SandboxBackend

Backend returns the selected backend (for diagnostics / introspection).

func (*SandboxRunner) Conforms ¶ added in v0.31.0

func (r *SandboxRunner) Conforms() bool

Conforms reports whether the backend passed every probe P1–P7 at construction. The supervisor consults this at Register to fail-closed an untrusted module whose host lost conformance (e.g. the operator pointed NewSandboxRunner at a backend that was available at boot but is now not — belt-and-suspenders alongside the constructor's gate).

func (*SandboxRunner) Report ¶ added in v0.31.0

func (r *SandboxRunner) Report() ConformanceReport

Report returns the cached conformance report from construction. Operator-facing surfaces (introspection, install UI) read this to show WHY an untrusted module fail-closed on this host.

func (*SandboxRunner) Start ¶ added in v0.31.0

func (r *SandboxRunner) Start(ctx context.Context, spec ChildSpec) (RunningChild, error)

Start implements Runner.Start. It is the untrusted-tier spawn: baseline hygiene (shared [prepareChildForSpawn]) + backend.Wrap (the OS-enforced denials) + shared [startPreparedChild]. The backend.Wrap step is the ONLY difference from TrustedProcessRunner.Start — that is the design's point: the two runners are identical except for the OS-enforced denial layer.

func (*TestApp) AsUser ¶ added in v0.29.0

func (ta *TestApp) AsUser(user any) *TestApp

AsUser returns a copy of the harness whose Get/Post/Put/Delete/Request calls carry an authenticated caller in context (core/handler.SetUser). Needed because auto-CRUD is secure-by-default: an entity declaring neither OwnerField nor Access nor Public requires a session for every operation (see EntityConfig.Public, framework/docs/content/security.md "Default CRUD authentication"). user can be any non-nil value — a bare struct{ ID string }{ID: "u1"} is enough to pass the baseline gate; use a real user type when the test also needs battery/auth's owner extractor or an access.Policy to resolve roles from it.

ta := TestHarness(t, app).AsUser(struct{ ID string }{ID: "u1"})
ta.Post("/posts", body).AssertStatus(t, http.StatusCreated)

func (*TestApp) Close ¶

func (ta *TestApp) Close()

Close is a no-op for in-memory testing (provided for API consistency).

func (*TestApp) Delete ¶

func (ta *TestApp) Delete(path string) *TestResponse

Delete performs a DELETE request.

func (*TestApp) Get ¶

func (ta *TestApp) Get(path string) *TestResponse

Get performs a GET request and returns a TestResponse for assertions.

func (*TestApp) Post ¶

func (ta *TestApp) Post(path string, body any) *TestResponse

Post performs a POST request with a JSON body.

func (*TestApp) Put ¶

func (ta *TestApp) Put(path string, body any) *TestResponse

Put performs a PUT request with a JSON body.

func (*TestApp) Request ¶

func (ta *TestApp) Request(method, path string, body io.Reader) *TestRequest

Request creates a raw TestRequest for further customisation before Execute.

func (*TestRequest) Execute ¶

func (tr *TestRequest) Execute() *TestResponse

Execute sends the request and returns a TestResponse.

func (*TestRequest) WithBody ¶

func (tr *TestRequest) WithBody(body any) *TestRequest

WithBody sets the request body. Non-reader values are marshalled as JSON.

func (*TestRequest) WithHeader ¶

func (tr *TestRequest) WithHeader(key, value string) *TestRequest

WithHeader adds a header to the request.

func (*TestResponse) AssertBodyContains ¶

func (tr *TestResponse) AssertBodyContains(t testing.TB, substr string) *TestResponse

AssertBodyContains asserts the body contains the given substring.

func (*TestResponse) AssertHeader ¶

func (tr *TestResponse) AssertHeader(t testing.TB, key, expected string) *TestResponse

AssertHeader asserts a response header value. Chainable.

func (*TestResponse) AssertJSON ¶

func (tr *TestResponse) AssertJSON(t testing.TB, expected any) *TestResponse

AssertJSON asserts the response body equals expected after JSON normalisation. Compares decoded values (not raw strings) so key order and number types don't matter.

func (*TestResponse) AssertStatus ¶

func (tr *TestResponse) AssertStatus(t testing.TB, expected int) *TestResponse

AssertStatus asserts the HTTP status code. Chainable.

func (*TestResponse) Body ¶

func (tr *TestResponse) Body() string

Body returns the response body as a string.

func (*TestResponse) Close ¶

func (tr *TestResponse) Close()

Close is a no-op (API consistency).

func (*TestResponse) JSON ¶

func (tr *TestResponse) JSON(v any) error

JSON decodes the response body into v.

func (*TestResponse) Status ¶

func (tr *TestResponse) Status() int

Status returns the HTTP status code.

func (TrustTier) String ¶ added in v0.31.0

func (t TrustTier) String() string

String makes TrustTier log-friendly and operator-readable.

func (*TrustedProcessRunner) Start ¶ added in v0.31.0

func (r *TrustedProcessRunner) Start(ctx context.Context, spec ChildSpec) (RunningChild, error)

Start implements Runner.Start. It is the trusted-tier spawn: verify the SHA pin, build the exec.Cmd with baseline hygiene, wire stdio, exec. It is a thin composition of [prepareChildForSpawn] (verify + cmd + pipes) and [startPreparedChild] (exec + codec + stderr drain); SandboxRunner reuses both with a backend.Wrap step in between.

func (*UntrustedNoSandboxError) Error ¶ added in v0.31.0

func (e *UntrustedNoSandboxError) Error() string

func (*UntrustedNoSandboxError) Unwrap ¶ added in v0.31.0

func (e *UntrustedNoSandboxError) Unwrap() error

Unwrap allows errors.Is(err, ErrSandboxUnavailable) and errors.As on the wrapped probe/construction failure.