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

Class NaruPlan

java.lang.Object
net.thevpc.naru.ext.tools.plan.NaruPlan
public class NaruPlan extends Object
A durable execution plan: a directed acyclic graph of NaruPlanItems.

Plans are owned by the session, not by a task. A plan is keyed by its own UUID and referenced explicitly, because the tasks that build it, execute it and validate it are all different tasks; keying by task id (as an earlier revision did) made the plan vanish the moment execution moved to a spawned child.

The plan knows nothing about activation, scheduling or spawning. It is a pure data structure plus the derived status(); deciding which plan runs and when belongs to NaruPlanManager.

  • Field Details

    • SCHEMA_VERSION

      public static final int SCHEMA_VERSION
      Bumped when the persisted shape changes incompatibly. Plans written by an older build are skipped on load rather than misread.
      See Also:

  • Constructor Details

    • NaruPlan

      public NaruPlan(String goal)

    • NaruPlan

      public NaruPlan(String id, String goal)

    • NaruPlan

      public NaruPlan(net.thevpc.nuts.elem.NElement element)

  • Method Details

    • keyOf

      public String keyOf(String itemId)
      The declaration key of an item, or null when it was declared without one.

    • id

      public String id()

    • goal

      public String goal()

    • setGoal

      public NaruPlan setGoal(String goal)

    • creationInstant

      public Instant creationInstant()

    • modificationInstant

      public Instant modificationInstant()

    • items

      public List<NaruPlanItem> items()

    • item

      public NaruPlanItem item(String itemId)

    • findItemByPrefix

      public NaruPlanItem findItemByPrefix(String prefix)
      Resolves an item by full id or by unique id prefix.

      render() prints 8-character prefixes because full UUIDs in a system prompt are unreadable, so a model quoting the plan back at us will hand us a prefix. An ambiguous prefix resolves to nothing rather than to an arbitrary item: silently picking one of several matches would corrupt the wrong item.

    • addItems

      public NaruPlan addItems(List<NaruPlanItemSpec> specs)
      Appends items, resolving NaruPlanItemSpec.dependsOn() keys against the keys declared in this same batch and against the keys of items added by earlier batches. A dependency may also name an item id directly.
      Throws:
      IllegalArgumentException - if a key is unknown or duplicated, or if the resulting graph would contain a cycle

    • removeItem

      public boolean removeItem(String itemId)
      Removes an item and every dependency edge pointing at it. Items that depended on the removed item become unblocked only if they had no other unsatisfied edge; NaruPlanManager.recomputeAndFill(String) decides that.

    • addDependency

      public NaruPlan addDependency(String itemId, String dependsOnItemId)
      Adds a dependency edge. The target must already exist and the edge must not create a cycle.
      Throws:
      IllegalArgumentException - if the target is unknown or would create a cycle

    • assertAcyclic

      public void assertAcyclic()
      Depth-first cycle check over the whole graph. Cheap enough to run on every structural edit, which is the point: a cycle would otherwise strand the plan with no runnable item and no obvious cause.

    • itemsWithSatisfiedDependencies

      public List<NaruPlanItem> itemsWithSatisfiedDependencies()
      Items with no unsatisfied dependency, in declaration order. This is the candidate set a selector draws from; it does not consider status, activation or concurrency.

    • isComplete

      public boolean isComplete()
      Whether every item is finished. An empty plan is not complete.

    • status

      public NaruPlanStatus status()
      Aggregate state, derived from the items on every call.

    • touch

      public NaruPlan touch()

    • render

      public net.thevpc.nuts.text.NText render()
      Compact rendering for prompt injection and /plan show.

      Dependency ids are rendered as short prefixes because full UUIDs in a system prompt are both unreadable and easy for a model to mistype back.

    • toElement

      public net.thevpc.nuts.elem.NElement toElement()