@outbuild-company/schedule-core 1.10.4 → 1.12.0

package/README.md

@@ -1,61 +1,32 @@
-<div align="center">
-
-# Schedule Core
-
-**A UI-agnostic domain engine for project schedules.**
-
-Activities, dependencies, working calendars, constraints, autoscheduling, and critical path — behind one typed boundary.
+<div class="ob-hero">
+  <img src="docs/api/assets/outbuild-mark.svg" alt="Outbuild" class="ob-hero-mark" width="96" />
+  <div>
+    <p class="ob-eyebrow">OUTBUILD DEVELOPER PLATFORM</p>
+    <h1>Schedule Core</h1>
+    <p class="ob-hero-copy">The shared scheduling engine used by Outbuild across frontend, backend, tests and background jobs.</p>
+  </div>
+</div>
 
 [![CI](https://github.com/OutBuild-Construction-Software/schedule-core/actions/workflows/ci.yml/badge.svg)](https://github.com/OutBuild-Construction-Software/schedule-core/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/%40outbuild-company%2Fschedule-core)](https://www.npmjs.com/package/@outbuild-company/schedule-core)
+[![Documentation](https://img.shields.io/badge/docs-Schedule_Core-7DFF8A?labelColor=121212)](https://outbuild-construction-software.github.io/schedule-core/)
 
-</div>
-
-## Why Schedule Core?
+Schedule Core centralizes Outbuild's scheduling calculations and business rules
+so every consumer produces the same result. It owns canonical schedule state;
+rendering, HTTP requests and database writes remain outside the library.
 
-Scheduling behavior needs one authority. If dates, dependency cascades, calendar math, and summary rollups are split between a Gantt widget and application code, the same edit can acquire different meanings in different consumers.
+## What it handles
 
-Schedule Core owns normalized schedule state and its mutations. A consumer supplies backend data, sends typed commands, and projects the resulting changes. Rendering and storage stay at the boundary.
-
-## Mental model
-
-```mermaid
-flowchart LR
-  Payload["Backend payload"] --> Normalize["Parse + normalize"]
-  Normalize --> Core
-  Command["DispatchAction"] --> Core
-
-  subgraph Engine["Schedule Core"]
-    Core["Canonical state"] --> Pipeline["Validate · mutate · derive"]
-    Pipeline --> Core
-  end
-
-  Pipeline --> Changes["ChangeSet"]
-  Core --> Reads["Read-only snapshots"]
-  Changes --> Consumers["UI · persistence · analytics"]
-  Reads --> Consumers
-```
-
-| Part | Contract |
+| Capability | What the engine owns |
 | --- | --- |
-| **Input** | Backend-shaped sector, activities, links, and calendars. Construction parses and normalizes them. |
-| **State** | `ScheduleCore` owns the live activity, link, calendar, hierarchy, view-state, and history model. |
-| **Command** | A `DispatchAction` expresses an edit, structural operation, dependency change, or synchronization event. |
-| **Result** | Accepted commands return a `ChangeSet`; expected validation failures return `{ ok: false, reason }`. |
-| **Consumer** | Applies projections, presents warnings, sends analytics, and performs I/O. |
-
-## Core concepts
-
-| Concept | Role in the engine |
-| --- | --- |
-| **Activities** | Tasks, milestones, and summary projects in a hierarchical schedule. |
-| **Links** | Typed dependencies with working-time lag and effective-graph cycle guards. |
-| **Calendars** | Working days, shifts, exceptions, and date/duration calculations. |
-| **Constraints** | ASAP, ALAP, start-based, finish-based, and fixed-date scheduling rules. |
-| **Autoscheduler** | Applies dependency, constraint, calendar, and parent-bound rules after relevant mutations. |
-| **Critical path** | Computes early/late dates, slack, and critical flags through an asynchronous job. |
-| **ChangeSet** | Entity diffs plus view state, ordering, tracking events, effects, and constraint warnings. |
-| **History** | Undo/redo state and persistence checkpoints owned by the core instance. |
+| Automatic scheduling | Dependency, constraint and hierarchy propagation. |
+| Critical Path | Early and late dates, slack and critical activities. |
+| Working calendars | Calendar-aware dates, durations and working-time lag. |
+| Activities and dependencies | Validated creation, edits, hierarchy and links. |
+| Baselines and filtering | Shared derived state for every consumer. |
+| Undo and redo | Reversible commands with recalculated dependent state. |
+| Fork and projection | Isolated scenarios without changing official state. |
+| UTC-safe calculations | Scheduling behavior independent from local time zones. |
 
 ## Use it in 30 seconds
 
@@ -65,125 +36,94 @@ npm install @outbuild-company/schedule-core
 
 ```ts
 import {
-  COLUMN,
-  ScheduleCore,
-  type ScheduleCoreInput
+  ACTIVITY_TYPE,
+  ROOT_PARENT_ID,
+  createSchedule
 } from '@outbuild-company/schedule-core';
 
-const input: ScheduleCoreInput = getScheduleInput();
-const core = new ScheduleCore(input);
-await core.ready;
-
-const activity = core.getAllActivitiesView()[0];
-if (activity) {
-  const result = await core.dispatch({
-    kind: 'inline-edit',
-    activityId: activity.id,
-    column: COLUMN.TEXT,
-    newValue: 'Updated activity'
+const backend = await fetch('/api/schedules/42').then((response) =>
+  response.json()
+);
+
+const schedule = await createSchedule({
+  sector: backend.sector,
+  activities: backend.activities ?? [],
+  links: backend.links ?? [],
+  calendars: backend.calendars ?? [],
+  baseCalendars: backend.baseCalendars ?? []
+});
+
+try {
+  const result = await schedule.activities.create({
+    activityId: 'A1',
+    parentId: ROOT_PARENT_ID,
+    overrides: {
+      name: 'Excavation',
+      type: ACTIVITY_TYPE.TASK,
+      durationDays: 3
+    }
   });
 
-  if (!result.ok) throw new Error(result.reason);
-  applyChangeSet(result.changes);
+  console.log(result.ok);
+  console.log(schedule.activities.get('A1')?.name);
+} finally {
+  schedule.destroy();
 }
-
-core.destroy();
 ```
 
-`getScheduleInput()` and `applyChangeSet()` belong to the consumer. The package exports one supported root entry point; deep imports are internal.
+Output:
 
-See the [API reference](docs/API.md) for initialization, commands, read APIs, persistence, undo/redo, forks, critical path, constants, and exported types.
-
-## What a change contains
-
-```ts
-interface ChangeSet {
-  source: ChangeSetSource;
-  activities: ReadonlyArray<EntityChange<CoreActivity>>;
-  links: ReadonlyArray<EntityChange<Link>>;
-  calendars: ReadonlyArray<EntityChange<Calendar>>;
-  trackingEvents: ReadonlyArray<TrackingEvent>;
-  viewState?: ReadonlyArray<ViewStateChange>;
-  order?: ReadonlyArray<BranchOrderChange>;
-  effects?: ReadonlyArray<ScheduleEffect>;
-  warnings?: ReadonlyArray<ConstraintWarning>;
-}
+```text
+true
+Excavation
 ```
 
-Changes are data, not side effects. A successful dispatch updates core state; consumers decide how to render, persist, report, or transmit the returned records.
+The library accepts backend-shaped schedule data, normalizes it internally and
+returns a ready instance. A successful mutation updates core state and returns
+the complete `ChangeSet`; a rejected mutation leaves state untouched.
 
-## Core invariants
+## One engine, two public entry points
 
-- **Serialized writes.** State-changing operations on one `ScheduleCore` instance run through a single operation queue.
-- **Isolated reads.** Public read methods return cloned snapshots or read-only collections; mutating a returned value cannot mutate core state.
-- **Guarded commits.** A rejected dispatch restores captured mutations. A failed rollback poisons the instance instead of continuing with uncertain state.
-- **Cycle-safe graph edits.** New dependency and hierarchy mutations are checked against the effective dependency graph. Pre-existing cycles can be inspected with `auditEffectiveGraph()`.
-- **Explicit time units.** Duration commands accept working days; domain snapshots expose `durationHours`, and link lag is stored and exposed in working hours.
-- **Persistence is acknowledged.** Storage remains external; a successful `persistence-acknowledge` establishes the saved checkpoint and history boundary.
-
-The complete, code-linked contract lives in [INVARIANTS.md](INVARIANTS.md).
-
-## Architecture principles
-
-### One mutation boundary
-
-Domain writes enter through `dispatch()` or `applyActivityBatch()`. Handlers validate commands, update the canonical state, run the required derived passes, and assemble one result for the consumer.
-
-### Explicit ownership
-
-The core owns schedule entities, temporal calculations, dependency semantics, derived fields, and change tracking. Consumers own transport, persistence execution, UI projection, and presentation of rejected commands.
-
-### Narrow internal roles
-
-`ScheduleState` is the store, but subsystems depend on smaller capabilities such as activity readers/writers, calendar operations, the write journal, and the autoscheduler port. Architecture tests ratchet layer boundaries and public-entry reachability.
-
-### Legacy engines behind adapters
-
-The package has no runtime dependency on React or the DHTMLX package. Its calendar and critical-path implementations do retain adapted legacy engine code and Gantt-shaped internal contracts. The application-side bridge projects `ChangeSet` data into DHTMLX; that bridge remains outside this package.
-
-## What Schedule Core is not
-
-Schedule Core does not:
-
-- render a Gantt chart or React component;
-- own a browser application's component state;
-- fetch schedule data or make HTTP requests;
-- write to a database or storage service;
-- decide how warnings, analytics, or rejected commands are presented.
+| Consumer | Entry point |
+| --- | --- |
+| Backend, worker, script or test | `await createSchedule(input)` |
+| Outbuild frontend | The active `scheduleActions` bridge |
+| Low-level integration | `new ScheduleCore(input)` and `await schedule.ready` |
 
-It does track dirty entities and persistence checkpoints, but the consumer performs the actual save.
+The bridge and programmatic API use the same engine, validations and scheduling
+rules. The frontend bridge additionally owns the live DHTMLX projection;
+DHTMLX is a UI layer, not the scheduling authority.
 
-## Repository map
+## API model
 
 ```text
-src/
-├── index.ts          public package contract
-├── init/             facade, initialization, read API
-├── dispatch/         commands, handlers, ChangeSets, undo/redo
-├── internal/         state, hierarchy, ordering, dependency graph
-├── autoscheduler/    ASAP/ALAP scheduling and link propagation
-├── calendar/         working-time API and engine adapter
-├── columns/          typed field mutation pipelines
-├── propagations/     parent and derived-field propagation
-├── critical-path/    critical-path facade and legacy adapter
-├── constraints/      constraint vocabulary and date semantics
-├── boundary/         backend normalization and save tracking
-└── testing/          fixtures, scenarios, recordings, and parity harnesses
+backend data → ready schedule → validated action → result + updated state
 ```
 
-## Testing
+| Namespace | Responsibility |
+| --- | --- |
+| `schedule.activities` | Read and mutate activities and hierarchy. |
+| `schedule.links` | Read and mutate dependencies. |
+| `schedule.calendars` | Read calendars and reconcile dates. |
+| `schedule.selection` | Own selected activity IDs. |
+| `schedule.view` | Filter, order and visibility. |
+| `schedule.baselines` | Apply and read baseline state. |
+| `schedule.persistence` | Read dirty state and acknowledge saved checkpoints. |
+| `schedule.history` | Undo and redo. |
+| `schedule.projection` | Compare official and forked schedules. |
+| `schedule.criticalPath` | Recompute and await Critical Path work. |
+| `schedule.diagnostics` | Audit graphs, revisions and canonical state. |
 
-[Vitest](https://vitest.dev/) runs two explicit projects:
+## Documentation
 
-- **Unit** — sibling tests for domain modules, mutation pipelines, calendars, scheduling, graph rules, history, and architecture gates.
-- **Integration** — parity suites and recorded sessions over captured project data.
+- [Start with the visual API guide](https://outbuild-construction-software.github.io/schedule-core/documents/Schedule_Core.html)
+- [Read the guide in this repository](docs/api/index.md)
+- [Find every namespace and method](docs/api/reference.md)
 
-The repository also contains Gherkin behavior scenarios, production-derived recordings, undo/redo corpus checks, large-project regression cases, and compile-time boundary tests. These are verification strategies, not a published coverage or benchmark claim.
+Every guide uses the same format:
 
-```bash
-npm test                  # all Vitest projects
-npm run test:unit         # unit project
-npm run test:integration  # parity and session replays
+```text
+state before → API call → returned result → state after
 ```
 
 ## Development
@@ -197,19 +137,8 @@ npm run typecheck:boundary
 npm run lint
 npm test
 npm run build
+npm run docs:check
 ```
 
-The build emits ESM, CommonJS, type declarations, source maps, and a browser IIFE under `dist/`. The package declares no runtime dependencies.
-
-## Documentation
-
-- [Public API](docs/API.md) — supported entry point, lifecycle, commands, reads, persistence, and types.
-- [Model invariants](INVARIANTS.md) — verified units, dates, queueing, write capture, persistence, and graph rules.
-- [Domain and architecture index](docs/domain/README.md) — canonical map of the detailed domain documentation.
-- [State roles](docs/domain/STATE_ROLES.md) — internal capability boundaries around `ScheduleState`.
-- [Activity ownership](docs/domain/model/SCHEDULE_CORE_OWNERSHIP.md) — current core/render authority by field category.
-- [Temporal model](docs/domain/scheduling/temporal-model.md) — temporal vocabulary, policies, and known open decisions.
-- [Calendars](docs/domain/dates-calendars/CALENDARS.md) — working-time model, normalization, and engine boundary.
-- [Constraints](docs/domain/constraints/01-constraint-types-catalog.md) — supported constraint vocabulary and semantics.
-- [Architecture audit](docs/audit/README.md) — measured implementation map, findings, and unresolved questions.
-- [Changelog](CHANGELOG.md) — released behavior and package history.
+The package emits ESM, CommonJS, type declarations, source maps and a browser
+IIFE. It has no runtime dependencies.