Below is a first-pass design document for the small commands layer, written for humans, not the compiler. It is intentionally concrete but language-agnostic enough that we can still tweak it before coding.

1. Goals and scope

The commands layer sits between:

• Command emitters:
  • Player characters (PCs) via remote clients.
  • Non-player characters (NPCs) via agents/scripts.
  • Galaxy Managers (GMs, admin tools, batch scripts).
• The simulation core:
  • SimulationController, its event queue, and domain registries.[1][2][3][4]

Its responsibilities:

1. Accept command requests as JSON structures, regardless of origin.
2. Perform sanity checks and rule checks (including dice rolls, modifiers, resource pre-checks).
3. Decide whether the command is:
   • Rejected immediately, or
   • Accepted and translated into one or more SimEvents via SimulationController.enqueue*.[1]
4. Optionally schedule commands (and “macro” commands) into a command queue for future execution.
5. Persist:
   • Pending commands (queue).
   • Command history (for auditing).
   • Enough metadata to reconstruct the command queue and resume after a crash.

The commands layer does not:

• Replace the existing SimEvent mechanism.
• Own the simulation clock or tick loop (at least in this “small layer” phase).
• Directly mutate CrewRegistry, LocationGraph, etc., except through SimulationController or carefully defined service methods.[2][3][4][5][1]

2. Command lifecycle overview

2.1 Sources of commands

Commands can originate from:

• PC/NPC clients:
  • Via HTTP/websocket or other network protocol.
  • Usually tied to a particular actorId and possibly a connection/session.
• GalaxyManager / GM tools:
  • Admin UI or scripts emitting commands that may:
    • Affect many actors or vessels at once.
    • Be scheduled far into the future.
    • Bypass certain player-facing limitations (but still sanity-checked).
• Server-side systems:
  • Periodic tasks, triggers, or rule engines that decide to enqueue commands (e.g. “meteor shower in sector S01 at T+300”).

All of these flow through the same commands layer; the origin is recorded in metadata and can influence permissions but not core structure.

2.2 Processing stages

For each incoming JSON command request:

1. Ingress & parsing
   • Network or internal code passes a JSONValue to the commands layer.
   • The commands layer parses it into a CommandRequest object with a well-defined schema.
2. Static validation
   • Check request shape: required fields present, types correct, values in allowed ranges.
   • Resolve and normalize references (e.g. actor ids, location ids).
   • Reject malformed commands early.
3. Rule evaluation & dice
   • Based on current simulation state (via SimulationController queries), compute:
     • Legality (permissions, preconditions).
     • Difficulty modifiers.
     • Random outcomes (dice rolls).
   • Decide if the command:
     • Fails now (no SimEvent).
     • Partially succeeds.
     • Fully succeeds and needs SimEvents scheduled.
4. Enqueueing
   • For accepted commands, translate them into one or more SimEvents via SimulationController.enqueue*. These events will be processed on the next tick as usual.[1]
   • Optionally also insert a record into a CommandQueue (a higher-level queue that tracks pending commands for persistence and debugging).
5. Response
   • Produce a CommandResult with:
     • Final status (accepted/rejected/partial/error).
     • Timing (when effects start/end, in simulation time).
     • Dice details, resource changes, etc.
   • The network/agent layers use this to inform PCs, NPC controllers, or GM tools.
6. Persistence
   • Persist:
     • The original CommandRequest.
     • The CommandResult and dice rolls.
     • If the command scheduled future effects that depend on the command itself (not just SimEvents), persist the queued command as well.
   • The existing core state (galaxy, registries, etc.) continues to be persisted using your current Mongo layer.[4][6][7][8][9][1]

3. Command data model

3.1 CommandRequest (input)

A CommandRequest is the normalized, in-memory representation of what the caller asked for.

Key fields (conceptual):

• string id:
  • Unique command identifier, provided by client or generated on server.
• string originType:
  • "pc", "npc", "gm", "system", etc.
• string originId:
  • For "pc" and "npc", usually an actorId.
  • For "gm", a GM user id or tool id.
• string kind:
  • Command type, e.g. "moveActor", "setThrottle", "moveVessel", "assignStation".
• double requestTime (simulation time):
  • Time the server received the request / decided to process it.
• double desiredExecuteTime (simulation time, optional):
  • If specified, a requested scheduled time; otherwise “as soon as reasonable.”
• JSONValue payload:
  • Specific parameters for the command kind, e.g.:
    • Move: { "toLocationId": "...", "speed": "walk" }
    • Throttle: { "vesselId": "...", "systemId": "...", "value": 0.5 }

Constraints:

• JSON-first design: CommandRequest should be trivially serializable back to JSON for logging and persistence.
• Versionability: include an optional version field to allow changes to command format over time.

3.2 Command (internal)

We may distinguish:

• CommandRequest: what the client asked for.
• Command: a derived object created after static validation and rule evaluation.

A Command object could be:

• id: same as request.
• kind.
• actorId (normalized, even for GM commands that target an actor).
• executeAt (simulation time actually chosen by rules).
• payload (possibly augmented by rules: resolved location ids, computed path, etc.).
• metadata:
  • Dice results.
  • Applied modifiers.
  • Permission flags.

JSON persistence of Command remains straightforward; this supports crash recovery and debugging.

3.3 CommandResult (output)

Represents what the server decided about a command and is sent back to callers.

Fields:

• string commandId.
• string status:
  • "accepted", "rejected", "partial", "error".
• double requestTime.
• double effectiveStartTime (sim time when first effect happens).
• double effectiveEndTime (if known, e.g. duration of a macro).
• JSONValue details:
  • reason for rejection.
  • dice details (rolls, modifiers).
  • events summary (e.g., which SimEvent kinds were scheduled, at what times).
  • resourceChanges predictions or actual deltas.

This object is also kept JSON-friendly so it can be persisted in Mongo for audit and replay.[6]

4. Command handling architecture

4.1 CommandHandler interface

Define a polymorphic handler abstraction, but keep it small:

• CommandHandler responsibilities:
  • Static validation of CommandRequest for that kind.
  • State-based rule evaluation (permissions, preconditions, dice).
  • Construct Command (internal).
  • Schedule SimEvents via SimulationController.enqueue* as needed.[1]
  • Return CommandResult.

Handlers do not:

• Own their own time; they use the current simulation time from SimulationController.elapsedTime and its queues.[1]
• Directly mutate registries except via:
  • SimulationController methods.
  • Possibly a small set of well-defined domain services if we introduce those later.

4.2 Registry/dispatcher

A central CommandDispatcher:

• Holds mapping: kind → CommandHandler.
• For any incoming CommandRequest, does:
  1. Look up the handler by kind.
  2. Call handler.
  3. Return CommandResult.

This ensures extensibility:

• Adding a new command kind is:
  • Define payload schema.
  • Implement a handler.
  • Register it in the dispatcher.

No need to modify every caller.

5. Command queue and scheduling

In the “small layer” design, we do not create a new clock or independent loop. We keep a minimal CommandQueue that:

• Stores Command objects that:
  • Have been accepted but not yet fully enacted (e.g., macro commands that will emit future batches of SimEvents).
  • Or are scheduled for future processing (e.g., GM macros that expand into multiple actions at designated times).

Key design ideas:

• Command queue is a logical layer above SimEvent queue:
  • SimEvent is low-level, fully deterministic, and executed by SimulationController.tick.[1]
  • Command is higher-level, maybe multi-step, maybe depends on dice and rules.
• For the first version, we can adopt a simple policy:
  • Most commands are processed immediately when they arrive:
    • Their handler performs all dice and rule checks.
    • Immediately calls enqueue* to schedule SimEvents.
    • No long-lived Command remains in the queue.
  • Only macro/batch commands use the queue to track remaining work.

5.1 Queue structure

Conceptual fields per queued item:

• Command (internal form).
• string state:
  • "pending", "inProgress", "completed", "cancelled".
• double nextActionTime:
  • When this command should next be processed (for multi-step macros).
• Optional JSONValue macroState:
  • For macros: index of current step, partial outcomes, etc.

The queue itself is:

• Time-ordered (by nextActionTime).
• Persisted to Mongo as a collection (commandsQueue).
• A helper periodic process (e.g., part of app.d main loop) can:
  • Query for items with nextActionTime <= currentSimTime and state = "pending" or "inProgress".
  • Invoke their handler in “continue” mode to emit more SimEvents or mark them completed.

This is incremental: we can start without macros and only add the macroState aspects once needed.

6. Command macros

Macros are commands that expand into sequences or trees of other commands.

Examples:

• “Move actor from bridge to engineering”:
  • Macro computes path via LocationGraph.findPath.
  • Schedules several lower-level moveActorStep events or one high-level moveActor event.[3]
• “Prepare for warp”:
  • Raise shields, set engine throttle, assign crew to stations, start power routing.

Design decisions:

• Represent macros as special command kinds whose handlers:
  • Generate sub-commands or directly enqueue multiple SimEvents.
  • Optionally maintain macroState in the queue if the macro is long-lived.
• Macros should be definable:
  • In code (OO handlers).
  • Potentially in JSON scripts later (if we want a data-driven macro language), but that’s future work.

Important constraint: macros should still have a single CommandResult visible to the caller, summarizing success/failure and key timings.

7. Persistence strategy

We already have Mongo infrastructure. The commands layer should use it to persist:[6]

7.1 Collections

1. commands_requests
   • Documents representing CommandRequest as received.
   • Fields:
     • commandId, originType, originId, kind, requestTime, desiredExecuteTime, payload, version.
2. commands_results
   • Documents representing CommandResult.
   • Fields:
     • commandId, status, requestTime, effectiveStartTime, effectiveEndTime, details.
3. commands_queue (optional at first)
   • Only for commands that have ongoing macro state.
   • Fields:
     • commandId, kind, state, nextActionTime, macroState, lastUpdated.

The galaxy state (entities, vessels, resources, crew, sectors) and the simulation time are persisted via your core layer’s mechanisms as you already plan.[7][8][9][2][3][4][1]

7.2 Crash and restart

On restart:

• Restore the core world state and SimulationController.elapsedTime via your usual persistence.[1]
• Rebuild any necessary SimEvents or rely on the persisted commands_queue:
  • For each queued command with state != completed:
    • Re-run its handler in a “resume” mode, using macroState and current time, to re-emit any missing SimEvents.

This design assumes that SimEvents themselves are either:

• Reconstructed from higher-level state (preferred), or
• Persisted separately if you want strict replay (optional, maybe overkill early on).

8. Integration with existing core

Key integration points:

• Handlers must be able to:
  • Read from:
    • SimulationController.galaxyView, crewView, and other query APIs.[2][1]
    • Additional read methods we can add to SimulationController (e.g., getters for LocationGraph).[3][1]
  • Write via:
    • SimulationController.enqueueSetThrottle, enqueueMoveActor, enqueueMoveVessel, etc.[1]
    • Possibly new enqueue* methods as more command kinds appear.
• No external code (outside commands/core) should mutate:
  • CrewRegistry, LocationGraph, ResourceRegistry, SystemRegistry directly.
  • Instead, it should:
    • Send JSON command → commands layer → handlers → SimulationController.[5][4][2][3][1]

This keeps OO boundaries clear:

• core: deterministic state + events.
• commands: intent-level rules + dice + mapping to core events.
• app/server: IO, networking, and orchestration.

9. Open design questions

Before we move to code, I’d like your preferences on a few points:

1. Macro complexity, phase 1
   • Do you want macros in the initial implementation, or should we first only support single-step commands that immediately generate SimEvents?
   • If yes to macros now: is a macro more like “a list of child commands” or like “a state machine with steps”?
2. Where should the command queue live?
   • Only as an in-memory structure around SimulationController (and serialized occasionally)?
   • Or as a Mongo-backed queue that app.d polls and updates each tick?
3. Command schema style
   • Do you prefer commands be:
     • Very explicit per-kind (each kind has its own JSON schema), or
     • More generic with a few standard fields plus a payload blob?
   • The design above leans to “thin generic shell + per-kind payload”, but we can tighten this if you like stronger typing.
4. Permission model / originType
   • Do you want the commands layer itself to enforce “PCs can’t do GM things”, or should that be done one layer up (e.g., networking/HTTP layer), with commands being trusted that they’re already permission-filtered?

Once we settle these, we can:

• Refine this document into a shorter “spec”.
• Then design the exact D module layout (e.g., commands/request.d, commands/handler.d, commands/persistence.d) and start implementing.

Sources [1] controller.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/30070de6-50df-460f-b02c-2a9cd68e6c9a/controller.d [2] crew.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/794663ff-d875-49a3-a1c1-ce265991ed36/crew.d [3] location.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/80ddf50c-7272-434d-bd62-ef1664b18fda/location.d [4] resource.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/4fccda02-b426-497f-a2a7-e2bc96f6880e/resource.d [5] system.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/61f75032-a0aa-4045-a886-95657f8543fa/system.d [6] mongoClient.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/28aa99b4-3c99-4894-ad79-71638b111e61/mongoClient.d [7] entity.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/8ed0db1a-fa9b-43b9-aa4f-a2ec4f274a42/entity.d [8] vessel.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/1ad364aa-3c6e-4e56-bcc1-fccc120f24f0/vessel.d [9] sector.d https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/attachments/15197330/78c63c35-c826-4c97-83c6-64e677f23f9b/sector.d [10] singleShipAgent.md https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/collection_06cc074f-93d4-4c2f-adcf-a637e908c6ce/4b377787-43a1-44a0-b4e2-2749e13f8588/singleShipAgent.md [11] dub.selections.json https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/collection_06cc074f-93d4-4c2f-adcf-a637e908c6ce/2c693b58-f401-467f-a3ce-6f059f6d6234/dub.selections.json [12] dub.json https://ppl-ai-file-upload.s3.amazonaws.com/web/direct-files/collection_06cc074f-93d4-4c2f-adcf-a637e908c6ce/085c0316-6f7d-44f9-aa11-4cab94022ee6/dub.json