Package net.thevpc.naru.ext.tools.plan

Interface NaruPlanManager

All Known Implementing Classes:
NaruPlanManagerImpl
public interface NaruPlanManager
Manages durable execution plans for a session.

Plans persist with the session (as plans.tson) and survive crashes and reloads. A plan is addressed by its own id, never by the id of the task that happens to be working on it, so that the architect task, the executor tasks and the validator tasks can all reference the same plan.

This interface deliberately contains no scheduling policy. Deciding which ready item runs next, how many run at once, and when a plan is activated are all responsibilities of the layer above; the manager only owns the graph, its derived readiness, and the rules that keep a caller from recording unvalidated work as finished.

  • Method Details

    • createPlan

      NaruPlan createPlan(String goal, List<NaruPlanItemSpec> items)
      Creates a plan from declarative item specs and registers it under its generated id.
      Throws:
      IllegalArgumentException - if a dependency key is unknown or the graph would contain a cycle

    • findPlan

      net.thevpc.nuts.util.NOptional<NaruPlan> findPlan(String planId)

    • plans

      Map<String,NaruPlan> plans()
      All plans, in creation order.

    • findItem

      net.thevpc.nuts.util.NOptional<NaruPlanItem> findItem(String planId, String itemId)

    • addItems

      net.thevpc.nuts.util.NOptional<NaruPlan> addItems(String planId, List<NaruPlanItemSpec> items)
      Appends items to an existing plan, resolving dependency keys against existing items and against keys declared in the same batch.
      Throws:
      IllegalArgumentException - if a key is unknown, duplicated, or the graph would contain a cycle

    • reportItem

      net.thevpc.nuts.util.NOptional<NaruPlanItem> reportItem(String planId, String itemId, NaruPlanItemStatus status, String notes)
      Reports progress on an item.

      NaruPlanItemStatus.DONE is rejected here on purpose: completion must go through completeItem(String, String, boolean, String) so that a validator verdict always accompanies a finished item. Everything else the caller may set freely.

    • completeItem

      net.thevpc.nuts.util.NOptional<NaruPlanItem> completeItem(String planId, String itemId, boolean validationPassed, String notes)
      Records the outcome of an item's validator.

      A pass moves the item to NaruPlanItemStatus.DONE; a failure moves it to NaruPlanItemStatus.FAILED with notes kept as the reason. An item with no validator may be completed here too, but must pass true.

    • reopenItem

      net.thevpc.nuts.util.NOptional<List<NaruPlanItem>> reopenItem(String planId, String itemId, boolean cascade)
      Reopens a finished item, demoting it to NaruPlanItemStatus.PENDING and cascading the demotion to items that transitively depended on it.

      This is the destructive operation the human confirmation in the directive is for: cascading can undo validated work.

      Parameters:
      cascade - whether to demote dependents as well
      Returns:
      the demoted items, in demotion order

    • recomputeAndFill

      net.thevpc.nuts.util.NOptional<NaruPlan> recomputeAndFill(String planId)
      Recomputes NaruPlanItemStatus.READY for every non-terminal item whose dependencies are all NaruPlanItemStatus.DONE, and demotes items that are READY but no longer satisfied.

      Safe to call as often as you like; it never touches items that are running, validating or terminal.

    • removePlan

      boolean removePlan(String planId)

    • activePlan

      net.thevpc.nuts.util.NOptional<NaruPlan> activePlan()
      The plan currently marked for execution, if any. Activation is session state and is independent of the prompt mode of any task; only a human directive sets it.

    • activePlanId

      String activePlanId()

    • setActivePlanId

      void setActivePlanId(String planId)
      Records which plan is activated. Passing null or an unknown id deactivates.