@outbuild-company/schedule-core 1.10.3 → 1.10.4

package/README.md

@@ -1,21 +1,67 @@
-# @outbuild-company/schedule-core
+<div align="center">
 
-UI-agnostic schedule engine for activities, links, calendars, autoscheduling
-and critical-path calculation.
+# Schedule Core
 
-## Install
+**A UI-agnostic domain engine for project schedules.**
 
-```bash
-npm install @outbuild-company/schedule-core
-```
+Activities, dependencies, working calendars, constraints, autoscheduling, and critical path — behind one typed boundary.
 
-The package exposes a single public entry point:
+[![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)
 
-```ts
-import { ScheduleCore } from '@outbuild-company/schedule-core';
+</div>
+
+## Why Schedule Core?
+
+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.
+
+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
 ```
 
-## Quick start
+| Part | Contract |
+| --- | --- |
+| **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. |
+
+## Use it in 30 seconds
+
+```bash
+npm install @outbuild-company/schedule-core
+```
 
 ```ts
 import {
@@ -28,37 +74,142 @@ const input: ScheduleCoreInput = getScheduleInput();
 const core = new ScheduleCore(input);
 await core.ready;
 
-const result = await core.dispatch({
-  kind: 'inline-edit',
-  activityId,
-  column: COLUMN.TEXT,
-  newValue: 'Updated activity'
-});
+const activity = core.getAllActivitiesView()[0];
+if (activity) {
+  const result = await core.dispatch({
+    kind: 'inline-edit',
+    activityId: activity.id,
+    column: COLUMN.TEXT,
+    newValue: 'Updated activity'
+  });
 
-if (!result.ok) throw new Error(result.reason);
-applyChangeSet(result.changes);
+  if (!result.ok) throw new Error(result.reason);
+  applyChangeSet(result.changes);
+}
 
 core.destroy();
 ```
 
-`getScheduleInput`, `activityId`, and `applyChangeSet` are consumer-provided
-values.
+`getScheduleInput()` and `applyChangeSet()` belong to the consumer. The package exports one supported root entry point; deep imports are internal.
+
+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>;
+}
+```
+
+Changes are data, not side effects. A successful dispatch updates core state; consumers decide how to render, persist, report, or transmit the returned records.
+
+## Core invariants
+
+- **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.
+
+It does track dirty entities and persistence checkpoints, but the consumer performs the actual save.
+
+## Repository map
+
+```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
+```
+
+## Testing
+
+[Vitest](https://vitest.dev/) runs two explicit projects:
 
-Schedule Core owns domain state and mutations. Consumers provide normalized
-input, send commands through `dispatch()`, apply returned changes at the UI
-boundary, and persist them at the storage boundary.
+- **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.
 
-See the [complete API reference](docs/API.md) for initialization, every command,
-read APIs, persistence, history, critical path, helpers, constants, and types.
+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.
+
+```bash
+npm test                  # all Vitest projects
+npm run test:unit         # unit project
+npm run test:integration  # parity and session replays
+```
 
 ## Development
 
+Requires Node.js 20 or newer.
+
 ```bash
 npm ci
 npm run typecheck
+npm run typecheck:boundary
+npm run lint
 npm test
 npm run build
 ```
 
-The build produces ESM, CommonJS, type declarations and a browser IIFE under
-`dist/`.
+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.