Wire format#

This guide covers the conventions every raw Planning Engine call shares: how you pass JSON in, how you read the envelope that comes back, and how ids, dates, numbers, null and unknown fields are read. Reference pages for each export link here instead of repeating these rules.

Strings in, strings out#

The raw module has two exports, the JsonProject class and the schedule function. Every argument is JSON text and every return value is JSON text. Nothing native crosses the boundary: no objects, no Dates, no exceptions for bad input.

Each call follows the same four steps:

1. Serialize the request and options with JSON.stringify.
2. Call the export.
3. Parse the returned string with JSON.parse.
4. Check ok, then read result or error.

The plen CLI speaks the same wire format, byte for byte.

Here's the full loop in a browser or ES module host, with a stateful project:

import init, { JsonProject } from "./pkg/plen_wasm.js";

await init();

const data = {
  config: { use_calendars: false },
  tasks: [
    { id: "a", start_date: "2026-01-01", duration: 2 },
    { id: "b", start_date: "2026-01-01", duration: 1 },
  ],
  links: [{ id: "ab", source: "a", target: "b" }],
};

const project = new JsonProject("{}");
try {
  const text = project.solve(JSON.stringify(data), JSON.stringify({}));
  const envelope = JSON.parse(text);

  if (envelope.ok) {
    for (const update of envelope.result.updates) {
      console.log(update.id, update.start_date, update.end_date);
    }
  } else {
    const { kind, code, message, path } = envelope.error;
    console.error(kind, code, message, path);
  }
} finally {
  project.free();
}

In Node, the CommonJS build loads synchronously, so there's no init(). The stateless schedule export needs no handle to free:

const { schedule } = require("./pkg-node/plen_wasm.js");

const data = {
  tasks: [{ id: 1, start_date: "2026-01-05", duration: 3 }],
};

const envelope = JSON.parse(schedule(JSON.stringify(data), "{}"));
if (!envelope.ok) {
  throw new Error(`${envelope.error.kind}: ${envelope.error.message}`);
}
console.log(envelope.result.updates);

Every export is synchronous. Only module instantiation is async in the browser build. How to load each build, and how to create, clone and free handles, is in Module and handles.

Envelope#

Every export returns one of two shapes.

Success wraps the payload in result:

{
  "ok": true,
  "result": {
    "baselineId": "<opaque token>",
    "updates": [
      { "id": "b", "kind": "task", "start_date": "2026-01-03 00:00", "end_date": "2026-01-04 00:00" }
    ],
    "cycles": [],
    "conflicts": [],
    "notes": [],
    "converged": true
  }
}

That's the response to the browser example above: task b moved after a, and a didn't move, so only b is listed. The result payload depends on the export. Each reference page names its payload type.

Failure carries an error object with four fields, always all present:

{
  "ok": false,
  "error": {
    "kind": "parse",
    "code": null,
    "message": "missing field `tasks`",
    "path": null
  }
}

baselineId values are opaque tokens. Don't compare them across runs: the same data can get a new token on a repeat run.

Error table#

Errors come at two levels. Most failures arrive in the envelope. A short list of failures throws in the host instead.

Errors in the envelope#

For project errors, message holds the same string as code.

An input error before solving leaves the project as it was: the previous accepted state and cached result are kept.

Some outcomes look like failures but come back with ok: true, as data in the result: scheduling conflicts, dependency cycles, failure to converge, rejected apply operations, per-candidate evaluate failures, and unfilled or invalid assignment slots. Check the result fields for them.

Host-level failures#

The constructor is the only export that throws for bad input. Parse what it throws:

import init, { JsonProject } from "./pkg/plen_wasm.js";

await init();

let project;
try {
  project = new JsonProject(JSON.stringify({ validation: "lenient" }));
} catch (thrown) {
  const envelope = JSON.parse(thrown);
  console.error(envelope.error.kind, envelope.error.message);
  // validation unknown validation mode
}

Recovery for each error kind is in Error handling.

Field spelling#

Two naming styles meet on the wire, and which one applies depends on what the object is:

Task and link types are both spelled type.

Update entries reuse the task-data names on purpose. A result entry decodes as a valid task update, so you can send it back in tasks.update as is. Its extra kind and reason fields are ignored there.

Getting the style wrong fails in different ways:

• In call options, a wrongly spelled field is an unknown field, so the call fails with parse. {"clear_first": true} in evaluate options is rejected.
• In project data and change-set records, unknown fields are ignored. A task with "startDate" decodes as a task with no start date, and the error (if any) comes later from validation.

Ids, dates and numbers#

Ids#

An id is a JSON number or a string. Ids are compared like JavaScript object keys, so 1 and "1" name the same task. Numeric ids are double-precision floats, like JavaScript numbers; send ids beyond Number.MAX_SAFE_INTEGER as strings. Whole-number ids come back as JSON integers.

A task parent of "", or equal to config.root_id (default 0), means the task has no parent.

Dates#

Dates are strings: a naive local date-time at minute precision. There's no timezone, no daylight saving and no "today". Convert to local wall-clock time before you send dates in.

So "2026-01-01T08:00:59" comes back as "2026-01-01 08:00". An unparsable date fails with validation, message invalid date, path: null.

Calendar exception keys in worktime.dates are YYYY-MM-DD only. Hour ranges in worktime.hours are "H:MM-H:MM" strings, "24:00" is the only accepted hour-24 value, and a range that ends before it starts crosses midnight.

The generated type files type dates as string | Date. Date objects are a convenience of the JS glue only; on the raw surface you send strings.

Numbers#

Numbers are plain JSON numbers, and fractions are allowed where the field allows them. Whole-valued results come back as integers: 5, not 5.0.

Some fields take integers only:

• priority - integer 0..1000.
• max_iterations, requirement count, suggest passes - non-negative integers. 8.0 is accepted; 8.5 fails with validation.

JSON can't carry NaN or Infinity. JSON.stringify turns them into null, and null then reads as "use the default" or "clear the field" (see the next section). Check that numbers are finite before you serialize.

Enum values#

Enum fields are strings. A few accept extra input forms:

Any other string fails with validation and no path. The full lists of enum values are in Common types.

Omitted, null and unknown fields#

Input: omitted and null#

In project data and in options, an omitted field and a null field mean the same thing: use the default. {"includeUnchanged": null} is the same as {}. A null config gives the default config.

Update records (update entries of a change set) are the exception. There, omitted and null differ:

{
  "tasks": {
    "update": [
      { "id": 1, "start_date": null, "constraint_type": "", "progress": 0.5 }
    ]
  }
}

This update clears the start date and the constraint, sets progress, and leaves every other field of task 1 alone. For constraint_type, an empty string also clears. pauses: null clears the list, and a new pauses list replaces the whole list. The full list of update fields is on TaskUpdate.

Input: unknown fields#

Whether an unknown field is ignored or rejected depends on the object:

Records ignore unknown fields so you can pass UI data with its own extras (text, open, custom columns) and feed result entries back as updates. Options and change-set containers are strict, so a typo like {"tasks": {"rename": []}} or {"maxRounds": 5} fails loudly instead of being dropped.

Output: absent fields#

Optional result fields are omitted when they don't apply, not set to null. baselineId is missing when there's no baseline. An update entry lists only the fields that changed. analytics appears only when you asked for it.

A few result fields use null as a real value, and their reference pages say so: for example fromResource: null in a suggest step means the slot was filled, not moved.

Required fields#

A required field must be present and non-null. A missing or null required field fails the call with parse and no path. For example, {"tasks": null} as project data is a parse error.

The main required fields:

Assignments also accept task_id and resource_id as aliases of task and resource. When both spellings are present, the primary name wins. In an assignment update, setting task or resource to null is rejected: a required endpoint can't be cleared.

Records must be JSON objects. A positional array such as [1, "2026-01-05", 3] in place of a task is a parse error.

Required fields only cover the shape. The engine checks the content next: for example, a leaf task needs at least two of start_date, end_date and duration, and an entirely undated project is rejected. Those checks fail with validation and a path. The rules are in Project data.

For every request and response type, field by field, see the types overview.