Class NuggetControl

java.lang.Object

org.j7m.middleware.operations.api.NuggetControl

public final class NuggetControl
extends Object

UI-neutral nugget drain, shutdown, and self-termination contracts.

The records in this class are immutable public DTOs used by the headless nugget administration service, CLI clients, deterministic tests, demos, and future web/API adapters. They describe nugget-level control of the current J7M runtime subject only; they are not an arbitrary operating system process-control API. Implementations must enforce PIN admission, authorization, exact self-target checks, confirmation, feature gates, deadline checks, audit, redaction, and bounded retention before returning a NuggetControl.Result. For accepted asynchronous shutdown or termination actions, the server owns the execution timeout and may retain a terminal degraded operation status so replay of the same operation id reports NuggetControl.Outcome.TIMED_OUT or NuggetControl.Outcome.OUTCOME_UNKNOWN instead of executing the callback again.

Confirmation challenges are sensitive operational credentials. A challenge may be present in a direct NuggetControl.Result only when NuggetControl.Outcome.CONFIRMATION_REQUIRED is returned so an operator can submit it on the next request. Challenges must not be copied to audit records, logs, demos, evidence reports, history, warnings, metadata, errors, or string representations. NuggetControl.Request.toString(), NuggetControl.Confirmation.toString(), and NuggetControl.Result.toString() redact confirmation material deliberately.

Instances are immutable and thread-safe. Construction performs bounded defensive copying of public metadata but does not grant admission or authorization.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	NuggetControl.Action	Nugget-level control action.
static final record	NuggetControl.Confirmation	Server-issued confirmation challenge metadata.
static enum	NuggetControl.Mode	Requested control mode.
static enum	NuggetControl.Outcome	Stable public nugget-control outcome vocabulary.
static final record	NuggetControl.Request	Nugget-control request metadata.
static final record	NuggetControl.Result	Safe nugget-control result.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MAX_METADATA	Maximum retained safe metadata entries.
static final int	MAX_WARNINGS	Maximum retained safe warning entries.

Method Summary

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAX_METADATA

public static final int MAX_METADATA

Maximum retained safe metadata entries.

See Also:

• Constant Field Values

MAX_WARNINGS

public static final int MAX_WARNINGS

Maximum retained safe warning entries.

See Also:

• Constant Field Values