[Canonical page]()
[Full documentation index]()
# Reading results
Every scheduling call returns a [`ScheduleResult`](). This guide shows how to write the new dates back into your own model and explain why tasks moved. It also covers constraint conflicts, dependency cycles, dropped records, the baseline token, and why you should treat a result as read-only.
## How a result is organized
[`ScheduleResult`]() is what [`Engine.Schedule`](), [`Project.Solve`](), [`Project.Preview`]() and [`Project.Analyze`]() return. [`Project.Level`]() wraps one in [`LevelingResult.Schedule`](). Its properties fall into four groups:
| Group | Properties | What it tells you |
|---|---|---|
| Dates | [`Updates`]() | The tasks that changed, with their new values |
| Problems | [`Conflicts`](), [`Cycles`](), [`Notes`](), [`Converged`]() | Rules the plan breaks, loops in the links, records left out, whether the planner settled |
| Extras | [`Analytics`](), [`Overallocations`](), [`Profile`]() | Critical path and slack, resource overload, load profile. Each one is `null` unless you requested it or it applies |
| Identity | [`BaselineId`]() | Which accepted baseline the result belongs to |
These rules hold for every result:
- **Updates are sparse.** `Updates` lists only the tasks whose dates changed. Each [`Mutation`]() sets only the properties that changed. A task that didn't move isn't in the list. Set [`SolveOptions.IncludeUnchanged`]() when you need every task's dates, for example on the first load.
- **Problems are data, not exceptions.** A plan with conflicts, cycles or dropped links still returns normally. Calls throw [`InputException`]() for invalid input and [`ProjectException`]() for a call that doesn't fit the project's state. See [Error handling]().
- **Order is stable.** The same input and options always give the same result, in the same order. `BaselineId` is the one exception, because it's an opaque token.
- **Updates use the input names.** A `Mutation` has the same property names as [`TaskData`]() and [`TaskUpdate`](): `StartDate`, `EndDate`, `Duration`, `LevelingDelay`, `Pauses`. You can copy a mutation onto a `TaskUpdate` property by property.
## Updates
Read [`Updates`]() after each call and copy the changed values into your model. Every date and number property of a [`Mutation`]() is nullable, and `null` means "unchanged", not "cleared".
```csharp
using Plen;
var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date");
var data = new ProjectData
{
Tasks =
[
new TaskData(1) { StartDate = monday, Duration = 2.0 },
new TaskData(2) { StartDate = monday, Duration = 1.0 },
],
Links = [new LinkData { Id = 1, Source = 1, Target = 2 }],
};
// The caller's own copy of the dates.
var model = new Dictionary
{
[1] = (monday, 2.0),
[2] = (monday, 1.0),
};
var result = Engine.Schedule(data, new SolveOptions());
foreach (var update in result.Updates)
{
Console.WriteLine(
$"{update.Id} ({update.Kind}): start {update.StartDate}, end {update.EndDate}, " +
$"duration {update.Duration?.ToString() ?? "unchanged"}");
if (model.TryGetValue(update.Id, out var row))
{
if (update.StartDate is { } start)
row.Start = start;
if (update.Duration is { } duration)
row.Duration = duration;
model[update.Id] = row;
}
}
```
Output:
```
2 (Task): start 2026-08-12 08:00, end 2026-08-13 08:00, duration unchanged
```
Task 1 isn't listed because it didn't move. Task 2 moved, so it reports a new start and end. Its `Duration` is `null` because its working time stayed the same.
`Kind` is a [`MutationKind`](): `Task`, `Summary` or `Milestone`. Summaries show up in `Updates` too, because their spans roll up from their children. `LevelingDelay` and `Pauses` appear only in results from [`Project.Level`](), and only when leveling changed them. [Leveling resources]() shows how to write them back.
To get every task's dates instead of only the changed ones, see [Load all task dates]().
## Reasons
Set [`SolveOptions.Reasons`]() to learn why each task ended up where it did. Each update then carries a [`Reason`](). `Reason` is a closed set of nested records, so read it with a `switch` on the nested types:
```csharp
using Plen;
var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date");
var data = new ProjectData
{
Tasks =
[
new TaskData(1) { StartDate = monday, Duration = 1.0 },
new TaskData(2) { StartDate = monday, Duration = 1.0 },
new TaskData(3) { StartDate = monday, Duration = 1.0 },
],
Links =
[
new LinkData { Id = 10, Source = 1, Target = 2 },
new LinkData { Id = 11, Source = 2, Target = 3 },
],
};
var result = Engine.Schedule(data, new SolveOptions { Reasons = true });
foreach (var update in result.Updates)
{
var why = update.Reason switch
{
Reason.Asap r => $"pushed by task {r.SourceId} through link {r.LinkId}",
Reason.Alap r => $"pulled by task {r.TargetId} through link {r.LinkId}",
Reason.SummaryTranslation r => $"moved with summary {r.SummaryId}",
Reason.Constraint => "placed by its constraint",
Reason.Preferred => "kept at its preferred date",
_ => "no reason recorded",
};
Console.WriteLine($"task {update.Id}: {why}");
}
```
Output:
```
task 2: pushed by task 1 through link 10
task 3: pushed by task 2 through link 11
```
The variants:
- `Reason.Asap(LinkId, SourceId)`: a predecessor link pushed the task later.
- `Reason.Alap(LinkId, TargetId)`: a successor link pulled the task earlier (backward planning).
- `Reason.SummaryTranslation(SummaryId)`: the task moved as part of its summary block.
- `Reason.Constraint`: the task's own constraint placed it.
- `Reason.Preferred`: the task stayed at, or returned to, its own date.
[`PreviewOptions`]() has the same `Reasons` flag, so a drag preview can explain itself too. A cyclic solve reports no reasons, because the planner doesn't run.
## Conflicts
A conflict is a rule the scheduled plan breaks. It doesn't stop scheduling. The dates are still valid output, and [`Conflicts`]() lists what doesn't fit. [`Conflict`]() has two variants:
- [`Conflict.ConstraintViolation(Task, Constraint, Violation, Required, Actual)`](): a task's constraint and its links disagree. [`Violation`]() names the bound that broke: `EarliestStart`, `LatestStart`, `EarliestEnd` or `LatestEnd`.
- [`Conflict.CalendarNonWorking(Task, Proposed, Snapped)`](): with [`Config.StrictCalendar`](), a task that moved with its summary block landed on non-working time.
Constraints act only when [`Config.ApplyConstraints`]() is `true`. In this example, task 2 must start no later than Tuesday, but its predecessor runs until Wednesday:
```csharp
using Plen;
var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date");
var tuesday = Moment.FromYmdHm(2026, 8, 11, 8, 0) ?? throw new InvalidOperationException("invalid date");
var data = new ProjectData
{
Tasks =
[
new TaskData(1) { StartDate = monday, Duration = 2.0 },
// Build must start no later than Tuesday, but design runs until Wednesday.
new TaskData(2)
{
StartDate = monday,
Duration = 1.0,
ConstraintType = ConstraintType.Snlt,
ConstraintDate = tuesday,
},
],
Links = [new LinkData { Id = 1, Source = 1, Target = 2 }],
};
data.Config.ApplyConstraints = true;
var result = Engine.Schedule(data, new SolveOptions());
foreach (var conflict in result.Conflicts)
{
switch (conflict)
{
case Conflict.ConstraintViolation c:
Console.WriteLine(
$"task {c.Task}: {c.Constraint} violated ({c.Violation}), required {c.Required}, actual {c.Actual}");
break;
case Conflict.CalendarNonWorking c:
Console.WriteLine($"task {c.Task}: lands on non-working time at {c.Proposed} (snapped {c.Snapped})");
break;
}
}
foreach (var update in result.Updates)
Console.WriteLine($"task {update.Id}: start {update.StartDate}");
```
Output:
```
task 2: Snlt violated (LatestStart), required 2026-08-11 08:00, actual 2026-08-12 08:00
task 2: start 2026-08-11 08:00
```
The upper-bound constraint wins: task 2 starts on Tuesday, at `Required`. `Actual` is where the link wanted it to start. Show both dates to the user, so they can relax the constraint or move the predecessor. [Links, constraints and summaries]() explains how each constraint type resolves.
## Cycles and notes
A dependency cycle (task 1 waits for task 2, which waits for task 1) has no valid schedule. Planning Engine doesn't throw on it. It returns the dates unchanged, leaves [`Updates`]() empty and lists every unique simple cycle in [`Cycles`](). Each [`Cycle`]() holds the task ids (`Tasks`) and link ids (`Links`) that form the loop.
[`Notes`]() lists records the scheduler left out or changed. A [`Note`]() is one of:
- [`Note.DroppedLink(Link, Reason)`](): a link that can't apply, for example one that points to an unscheduled task.
- [`Note.DroppedTask(Task, Reason)`](): an unscheduled task.
- [`Note.DroppedAssignment(Assignment, Reason)`](): an assignment that doesn't take part.
- [`Note.Repaired(Path, Message)`](): a fix applied under [`Validation.Repair`]().
This example has a cycle between tasks 1 and 2, plus a parked task 3:
```csharp
using Plen;
var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date");
var data = new ProjectData
{
Tasks =
[
new TaskData(1) { StartDate = monday, Duration = 1.0 },
new TaskData(2) { StartDate = monday, Duration = 1.0 },
// Task 3 is parked: it isn't scheduled, and neither is the link to it.
new TaskData(3) { StartDate = monday, Duration = 1.0, Unscheduled = true },
],
Links =
[
// 1 -> 2 -> 1 is a cycle.
new LinkData { Id = 10, Source = 1, Target = 2 },
new LinkData { Id = 11, Source = 2, Target = 1 },
new LinkData { Id = 12, Source = 2, Target = 3 },
],
};
var result = Engine.Schedule(data, new SolveOptions());
foreach (var cycle in result.Cycles)
Console.WriteLine($"cycle: tasks [{string.Join(", ", cycle.Tasks)}], links [{string.Join(", ", cycle.Links)}]");
Console.WriteLine($"updates: {result.Updates.Count}");
foreach (var note in result.Notes)
{
var line = note switch
{
Note.DroppedLink n => $"link {n.Link} dropped: {n.Reason}",
Note.DroppedTask n => $"task {n.Task} dropped: {n.Reason}",
Note.DroppedAssignment n => $"assignment {n.Assignment} dropped: {n.Reason}",
Note.Repaired n => $"repaired {n.Path}: {n.Message}",
_ => note.ToString(),
};
Console.WriteLine(line);
}
if (!result.Converged)
Console.WriteLine("the planner stopped before a fixed point");
```
Output:
```
cycle: tasks [1, 2], links [10, 11]
updates: 0
task 3 dropped: unscheduled
link 12 dropped: target task "3" is unscheduled
```
Highlight the links in `cycle.Links` so the user can break the loop. A cyclic solve still installs a baseline. If you requested analytics, they come back with [`Analytics.Status == AnalyticsStatus.Invalid`]().
[`Converged`]() is `false` when the planner didn't reach a stable state within [`Config.MaxIterations`]() passes (default 8). The dates are still a valid result, so treat it as a warning, not a failure.
To clean up messy input instead of rejecting it, see [Accept messy input]().
## Baseline token
[`BaselineId`]() names the accepted baseline of a [`Project`](): the dates the last [`Solve`]() or [`Level`]() accepted. These calls fill it in:
- `Solve` and `Level`: the baseline they just accepted.
- [`Preview`](): the baseline it read.
- [`Analyze(null, …)`]() on a solved project with no pending edits: the current baseline. In every other case it's `null`.
- [`Engine.Schedule`](): sets it too, but the project behind the call is gone afterwards, so the token has no use.
The token changes whenever the data changes: new data, an [`Apply`](), a solve that moves dates, or leveling edits. Keep it next to the dates you display. Pass it back in [`PreviewOptions.BaselineId`]() or [`SchedulingChanges.BaselineId`](). If the project moved on in the meantime, the call throws [`ProjectException`]() with `Code == ProjectError.StaleBaseline`:
```csharp
using Plen;
var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date");
var data = new ProjectData
{
Tasks =
[
new TaskData(1) { StartDate = monday, Duration = 2.0 },
new TaskData(2) { StartDate = monday, Duration = 1.0 },
],
Links = [new LinkData { Id = 1, Source = 1, Target = 2 }],
};
var project = new Project();
var loaded = project.Solve(data, new SolveOptions());
// Keep the token next to the dates you show.
var shown = loaded.BaselineId;
var changes = new SchedulingChanges();
changes.Tasks.Update.Add(new TaskUpdate(1) { Duration = 3.0 });
var guarded = new PreviewOptions { BaselineId = shown };
var preview = project.Preview(changes, guarded);
Console.WriteLine($"preview read the shown baseline: {preview.BaselineId == shown}");
// Someone else commits an edit; the accepted baseline changes.
project.Apply(changes);
var committed = project.Solve(null, new SolveOptions());
Console.WriteLine($"token changed: {committed.BaselineId != shown}");
try
{
project.Preview(changes, guarded);
Console.WriteLine("unexpected: preview accepted a stale token");
}
catch (ProjectException e) when (e.Code == ProjectError.StaleBaseline)
{
Console.WriteLine("stale: reload the dates before previewing again");
}
```
Output:
```
preview read the shown baseline: True
token changed: True
stale: reload the dates before previewing again
```
The token is opaque. Don't parse it, don't store it as a persistent id, and don't compare tokens across runs: the same data solved twice may get two different tokens. Compare it only with the current one, and always take it from the latest result. [Editing a project]() shows the full edit cycle.
## Results are shared
[`ScheduleResult`]() is a mutable class, but treat every result you get from a [`Project`]() as read-only. The project keeps the result of [`Solve`]() and [`Level`]() as its accepted baseline. It returns that same object from a later `Solve(null, …)` with equal options and nothing changed. Its clones share it, and [`Evaluate`]() and [`SuggestAssignments`]() read it as the baseline. If you change it, you change what the project sees.
Call [`DeepClone()`]() to get a copy you own:
```csharp
using Plen;
var monday = Moment.FromYmdHm(2026, 8, 10, 8, 0) ?? throw new InvalidOperationException("invalid date");
var data = new ProjectData
{
Tasks =
[
new TaskData(1) { StartDate = monday, Duration = 2.0 },
new TaskData(2) { StartDate = monday, Duration = 1.0 },
],
Links = [new LinkData { Id = 1, Source = 1, Target = 2 }],
};
var project = new Project();
var options = new SolveOptions();
var first = project.Solve(data, options);
var again = project.Solve(null, options);
var fork = project.Clone();
Console.WriteLine($"same object: {ReferenceEquals(first, again)}");
Console.WriteLine($"clone shares it: {ReferenceEquals(first, fork.Solve(null, options))}");
// Copy before you change anything.
var mine = first.DeepClone();
mine.Updates.Clear();
Console.WriteLine($"project result untouched: {first.Updates.Count}");
```
Output:
```
same object: True
clone shares it: True
project result untouched: 1
```
The copy shares no list or nested record with the original. [`LevelingResult.DeepClone()`]() is the exception: it doesn't copy [`Schedule`](), so call `Schedule.DeepClone()` before you change the leveled schedule.
`ScheduleResult` compares by value with `Equals`, list by list. Two results of the same data can still differ in [`BaselineId`](), so set it to `null` on both copies before comparing them in tests.
A result from [`Engine.Schedule`]() belongs to you alone, so you can change it freely.
The core package has no JSON support. To send results to a client as JSON, see [Exchange JSON with a client]().