@outbuild-company/schedule-core 1.1.0 → 1.1.2

package/dist/index.d.cts

@@ -44,11 +44,6 @@ interface LinkSnapshot {
     /** BE row id (distinct from the schedule-level `id`). */
     proplannerId?: number;
 }
-/**
- * Gantt-wide flags that influence scheduling decisions.  Captured at the
- * boundary of every scheduling run.
- */
-type MutableLinkField = 'lag' | 'type';
 
 /**
  * Constraint Rules — single source of truth.
@@ -223,6 +218,8 @@ interface CoreBaselinePoint {
     workHours: number;
     versionId: number | null;
     isActiveVersion: boolean;
+    /** Whether this version is the one selected for visual comparison. */
+    isVisibleVersion: boolean;
     baseCalendarId: CalendarId | null;
     hoursPerDay: number | null;
     hoursPerWeek: number | null;
@@ -523,8 +520,25 @@ type LinksBatchOperation = {
     kind: 'delete';
     linkId: LinkId;
 };
+interface PersistedEntityIdentity {
+    readonly id: string;
+    readonly proplannerId: number;
+}
 
 type DispatchAction = {
+    kind: 'persistence-acknowledge';
+    activities?: ReadonlyArray<PersistedEntityIdentity>;
+    links?: ReadonlyArray<PersistedEntityIdentity>;
+} | {
+    kind: 'baseline-apply';
+    points: ReadonlyArray<BaselinePoint>;
+} | {
+    kind: 'ponderator-criterion-set';
+    criterion: ActivityCreter;
+} | {
+    kind: 'status-criteria-set';
+    criteria: StatusCriteria;
+} | {
     kind: 'inline-edit';
     activityId: ActivityId;
     column: string;
@@ -1086,56 +1100,6 @@ interface BackendScheduleInput {
     baseCalendars?: BackendCalendarInput[] | undefined;
 }
 
-/**
- * Role interfaces (Interface Segregation).
- *
- * Consumers receive the smallest role they need instead of the whole
- * `ScheduleState`. A pure-read consumer takes `ActivityReader`; a
- * read+write consumer takes `ActivityWriter`; a consumer that drives the
- * per-dispatch write journal takes `WriteJournal`. `ScheduleState`
- * implements all of them, so passing it anywhere a role is expected is
- * still valid — the role just narrows what the callee is allowed to touch.
- *
- * Signatures here are copied verbatim from `ScheduleState`; the class is
- * the source of truth. If the class changes a member, change the role to
- * match (not the other way around).
- */
-
-/** READ surface over the activity/link store and the hierarchy index. */
-interface ActivityReader {
-    getActivity(activityId: ActivityId$1): CoreActivity | null;
-    getLastStartDate(activityId: ActivityId$1): Date | null;
-    getAllActivities(): ReadonlyArray<CoreActivity>;
-    getAllLinks(): LinkSnapshot[];
-    getLink(linkId: LinkId$1): LinkSnapshot | null;
-    activityExists(activityId: ActivityId$1): boolean;
-    getChildren(parentId: ActivityId$1): ActivityId$1[];
-    hasChildren(parentId: ActivityId$1): boolean;
-    getParent(activityId: ActivityId$1): CoreActivity | null;
-    getParentId(activityId: ActivityId$1): ActivityId$1 | null;
-    getRootIds(): ReadonlyArray<ActivityId$1>;
-    isChildOf(childId: ActivityId$1, parentId: ActivityId$1): boolean;
-    getOutgoingLinkIds(activityId: ActivityId$1): ReadonlyArray<LinkId$1>;
-    getIncomingLinkIds(activityId: ActivityId$1): ReadonlyArray<LinkId$1>;
-    getAllIds(): readonly ActivityId$1[];
-    activityCount(): number;
-    forEachActivity(visit: (activity: CoreActivity, id: ActivityId$1) => void): void;
-}
-/** READ + WRITE surface over the store. */
-interface ActivityWriter extends ActivityReader {
-    setActivityField<Field extends keyof CoreActivity>(activityId: ActivityId$1, field: Field, value: CoreActivity[Field]): void;
-    setActivityFieldDynamic(activityId: ActivityId$1, field: string, value: unknown): void;
-    /** Bulk write of several fields of one activity in a single getActivity +
-     * write-capture note (vs N setActivityField calls). */
-    setActivityFields(activityId: ActivityId$1, fields: Partial<CoreActivity>): void;
-    addLink(link: LinkSnapshot): void;
-    removeLink(linkId: LinkId$1): void;
-    setLinkField<Field extends MutableLinkField>(linkId: LinkId$1, field: Field, value: LinkSnapshot[Field]): void;
-    setLinkFieldDynamic(linkId: LinkId$1, field: string, value: unknown): void;
-    addActivity(activity: CoreActivity): void;
-    removeActivity(activityId: ActivityId$1): void;
-}
-
 /**
  * Injected reporting port. The core is UI-agnostic: it cannot `console.*`,
  * show UI, or know about Sentry. When it hits a recoverable data-quality
@@ -1235,25 +1199,14 @@ interface ScheduleCoreInput extends BackendScheduleInput {
     reporter?: ScheduleCoreReporter;
 }
 
-interface PersistedEntityIdentity {
-    readonly id: string;
-    readonly proplannerId: number;
-}
-interface PersistenceAcknowledgement {
-    readonly activities?: ReadonlyArray<PersistedEntityIdentity>;
-    readonly links?: ReadonlyArray<PersistedEntityIdentity>;
-}
 declare class ScheduleCore {
     private _status;
-    /** True while an async dispatch is suspended inside the write-capture window.
-     * A sync facade mutation running in that gap would corrupt the in-flight
-     * journal, so sync mutators refuse to run while it is set. */
-    private _dispatchInFlight;
     private readonly coreRuntime;
     private readonly _undo;
     private _opQueue;
-    private _mutationEpoch;
-    private _cpComputedEpoch;
+    private _scheduleRevision;
+    private _criticalPathRevision;
+    private _activeCriticalPath;
     constructor(input: ScheduleCoreInput);
     get ready(): Promise<void>;
     get criticalPathReady(): Promise<{
@@ -1286,76 +1239,41 @@ declare class ScheduleCore {
     isCustomIdInUse(customId: string, currentCustomId?: string | null): boolean;
     getProjectWorkHours(): ProjectWorkHours | null;
     getModifiedLinks(): ReadonlyArray<Readonly<Link>>;
-    markLinksPersisted(): void;
     getModifiedActivities(): ReadonlyArray<Readonly<CoreActivity>>;
-    markActivitiesPersisted(): void;
-    /**
-     * Reconciles the backend identities returned by a successful schedule save.
-     *
-     * This is an application-boundary acknowledgement, not an editable schedule
-     * gesture: it does not autoschedule, recompute, emit an undo entry, or invent
-     * domain changes. Every assignment is validated before the first mutation so
-     * a malformed/partial response cannot leave the core half-reconciled. Once
-     * applied, the complete live graph becomes the new save-tracker baseline.
-     */
-    acknowledgePersistence(acknowledgement: PersistenceAcknowledgement): void;
-    applyBaselines(points: readonly BaselinePoint[]): ReadonlyArray<Readonly<CoreActivity>>;
-    /**
-     * Whole-tree ponderator recompute (zeroes, then redistributes 100 within
-     * each parent from its children's active baselines, weighted by `criterion`).
-     * Returns the activities whose `ponderator` changed, for a prop-only repaint.
-     * The base rollup (`applyBaselines`) depends on fresh ponderators, so callers
-     * run this before it on a criterion change or baseline save.
-     */
-    recomputeAllPonderators(criterion: ActivityCreter): ReadonlyArray<Readonly<CoreActivity>>;
-    /**
-     * Recompute the weighted-progress rollup of every parent, bottom-up.
-     * Returns the activities whose `progress` changed, for a prop-only repaint.
-     */
-    recomputeAllProgressRollup(): ReadonlyArray<Readonly<CoreActivity>>;
-    /**
-     * Set the project's status criterion (the Baseline↔Actual toggle) and
-     * recompute every activity's `status` against it. Stores the criterion so
-     * future dispatches keep deriving status with it. Returns the activities
-     * whose `status` changed, for a prop-only repaint.
-     */
-    setStatusCriteria(criteria: StatusCriteria): ReadonlyArray<Readonly<CoreActivity>>;
-    allocateActivityId(): ActivityId;
-    createActivity(input: Omit<Extract<DispatchAction, {
-        kind: 'activity-create';
-    }>, 'kind'>): {
-        ok: true;
-        activity: Readonly<CoreActivity>;
-        changes: ChangeSet;
-    } | {
-        ok: false;
-        reason: string;
-    };
     private _enqueue;
     dispatch(action: DispatchAction, options?: DispatchOptions): Promise<DispatchResult>;
     private _dispatchInner;
     /**
-     * Recompute the critical path OUT of band and return a repaintable ChangeSet
-     * of the 7 CP fields, or null when the CP is already fresh for the current
-     * state (coalesced). Enqueued on `_opQueue` so it runs serialized against
-     * dispatches — it reads/writes the live tree only when no mutation is in
-     * flight.
-     *
-     * Deferred-CP flow: dispatch with `{ skipCriticalPath: true }` (paints
-     * without the heavy CP pass), then call this after the paint. Bursts
-     * coalesce: only the first enqueued recompute after the last mutation does
-     * the work; later ones see `_cpComputedEpoch === _mutationEpoch` and no-op.
+     * Starts or joins the Critical Path calculation for the current schedule
+     * revision. Snapshot capture and the final commit are serialized with user
+     * mutations, but the expensive calculation runs outside `_opQueue` against
+     * an isolated state. A newer revision aborts this job and makes its result
+     * ineligible to commit.
      */
     recomputeCriticalPath(): Promise<{
         changes: ChangeSet;
     } | null>;
-    private _recomputeCriticalPathIfStale;
+    isCriticalPathSettled(): boolean;
+    whenCriticalPathSettled(): Promise<void>;
+    private _recordScheduleMutation;
+    private _startCriticalPathForCurrentRevision;
     private _runCriticalPathAndCapture;
+    /**
+     * Undo/Redo restores the user's historical mutation while retaining current
+     * non-historical truth (for example a refreshed baseline). Re-derive every
+     * value that depends on both so the restored model is immediately coherent.
+     */
+    private _recomputeAfterHistoryRestore;
     undo(): Promise<ChangeSet | null>;
     redo(): Promise<ChangeSet | null>;
-    clearHistory(): void;
     canUndo(): boolean;
     canRedo(): boolean;
+    /**
+     * Establishes a new persistence boundary without mutating schedule state.
+     * Completed saves call this synchronously so neither prior undo entries nor
+     * their redo branch can cross the persisted boundary.
+     */
+    clearHistory(): void;
     undoDepth(): number;
     private _resyncCustomIdTrackerFromModel;
     destroy(): void;
@@ -1410,25 +1328,6 @@ declare function getActiveBaseline(activity: {
     baselinePoints?: readonly CoreBaselinePoint[];
 } | null | undefined): CoreBaselinePoint | null;
 
-/**
- * Surface this function needs from ScheduleState — kept structural so the
- * function is unit-testable with a plain in-memory adapter.
- */
-interface BaselineApplyAdapter {
-    forEachActivity(visit: (a: Record<string, unknown>, id: string) => void): void;
-    getActivity(id: string): Record<string, unknown> | null;
-    setActivityField(id: string, field: string, value: unknown): void;
-}
-/**
- * Overlay baseline points onto activities, matching `point.activityId`
- * (backend DB id) against `activity.proplannerId`. Writes the full group of
- * points (all versions) onto `baseline_points`; the active one is selected
- * downstream by `getActiveBaseline`. Activities absent from the new set get
- * `baseline_points` reset to `[]`. Returns the ids of activities whose
- * `baseline_points` changed (so the caller can repaint just those).
- */
-declare function applyBaselinePoints(adapter: BaselineApplyAdapter, points: readonly BaselinePoint[], reporter: ScheduleCoreReporter): string[];
-
 interface CalendarLike {
     calculateDuration(start: Date, end: Date): number;
 }
@@ -1459,67 +1358,6 @@ interface ExpectedProgressAdapter {
  */
 declare function computeExpectedProgress(rootIds: readonly string[], now: Date, adapter: ExpectedProgressAdapter, defaultBaseCalendarId?: string | null): string[];
 
-/**
- * Recompute the `ponderator` of EVERY activity in the schedule, in bulk.
- *
- * Faithful port of `goCalculatePonderators` in
- * `react_client/src/views/ganttContainer/gantt/index.js:2008-2038` (the
- * ponderator part — the progress rollup and save are separate concerns the
- * caller wires). Two passes, mirroring the legacy:
- *   1. Zero EVERY activity's ponderator.
- *   2. For each parent (activity with children), redistribute 100 among its
- *      children via `recomputePonderatorsForParent` (baseline-only).
- *
- * IMPORTANT — this is the ONLY ponderator recompute the schedule performs.
- * Verified against the legacy (2026-06-04): the masterplan does NOT recompute
- * ponderators on add / delete / move / inline-edit. `goCalculatePonderators`
- * runs ONLY on two events (see index.js:395/443/625):
- *   - the project criterion (`activity_creter`) changed
- *     (`sectorObject.update_ponderators_masterplan`), or
- *   - a baseline was created / saved.
- * Both events otherwise reload the schedule. So there is intentionally NO
- * per-mutation cascade and NO dispatch hook — adding one would diverge from
- * production (a baselined child's siblings stay as the backend computed them
- * until the next of those two events). See
- * [[PONDERATOR_BASELINE_MIGRATION_PLAN]].
- *
- * Order-independent: a project child's weight derives from descendant
- * BASELINES (`getDurationRecursively`), never from other ponderators, so the
- * order parents are visited in does not affect the result.
- */
-
-declare function recomputeAllPonderators(criterion: ActivityCreter, adapter: ActivityWriter): void;
-
-/**
- * Recompute the weighted-progress rollup of EVERY parent in the schedule,
- * bottom-up. `parent.progress = Σ(child.progress × child.ponderator / 100)`.
- *
- * Faithful port of legacy `check_progress` (editing-flow.js:154-197) — the
- * second half of `goCalculatePonderators`. After a ponderator recompute
- * (baseline create/save, see `recomputeAllPonderators`), parent progress is
- * stale w.r.t. the new weights; this repropagates it.
- *
- * PROGRESS-ONLY by design: unlike the dispatch post-processor
- * `recomputeParentFromChildren` (post-processors/parent-bounds.ts), this does NOT
- * touch parent start/end/duration — only `progress`. That keeps it testable
- * in isolation (no calendars/dates needed) and matches what `check_progress`
- * actually did.
- *
- * Order is load-bearing (unlike ponderators, which are order-independent): a
- * grandparent's rollup consumes its children-parents' ALREADY rolled-up
- * progress, so parents are visited deepest-first.
- *
- * Parity rules:
- *   - child with no/zero ponderator does not contribute;
- *   - a parent whose children contribute nothing keeps its progress frozen;
- *   - `progress` is kept a NUMBER but rounded per level to 2 decimals
- *     (`roundProgressPerLevel`) — legacy `check_progress` recurses on
- *     `toFixed(2)`, so each ancestor consumes its children's 2-decimal value
- *     (MORNING_QUEUE.md — JUN-02).
- */
-
-declare function recomputeAllProgressRollup(adapter: ActivityWriter): void;
-
 type StaticActivityDefaults = Omit<CoreActivity, 'id' | 'parentId' | 'name' | 'startDate' | 'endDate' | 'durationHours' | 'calendarId' | 'uniqueCorrelativeId'>;
 declare const NEW_ACTIVITY_DEFAULTS: Readonly<StaticActivityDefaults>;
 
@@ -1569,9 +1407,9 @@ declare function yieldToBrowser(): Promise<void>;
  * Does this dispatch recompute the critical path? The single authority for the
  * question, shared by the dispatch gate (`resolveDerivedPasses`) and the
  * bridge, which reads it to defer the CP out of the paint. Mirrors legacy: the
- * CP re-derives on any scheduling change, and is left STALE for prop-only
- * intents, the structural reparents (indent/outdent), and edits that touch only
- * non-scheduling columns.
+ * CP re-derives on every scheduling change. Prop-only/administrative intents
+ * and edits that touch only non-scheduling columns leave the current CP
+ * revision intact; structural reparents are never exempt.
  */
 declare function willRunCriticalPath(action: DispatchAction): boolean;
 
@@ -1674,6 +1512,10 @@ declare const DEFAULT_HOURS_PER_DAY = 8;
 
 type DispatchActionKind = DispatchAction['kind'];
 declare const DISPATCH_ACTION_KIND: {
+    readonly PERSISTENCE_ACKNOWLEDGE: "persistence-acknowledge";
+    readonly BASELINE_APPLY: "baseline-apply";
+    readonly PONDERATOR_CRITERION_SET: "ponderator-criterion-set";
+    readonly STATUS_CRITERIA_SET: "status-criteria-set";
     readonly INLINE_EDIT: "inline-edit";
     readonly DATES_BATCH: "dates-batch";
     readonly BULK_EDIT: "bulk-edit";
@@ -1768,4 +1610,4 @@ declare const DISPATCH_TRACK_EVENT: {
 };
 type DispatchTrackEvent = (typeof DISPATCH_TRACK_EVENT)[keyof typeof DISPATCH_TRACK_EVENT];
 
-export { ACTIVITY_TYPE, type ActivityCreter, type ActivityId, type ActivityType, type BackendActivityInput, type BackendCalendarInput, type BackendLinkInput, type BackendScheduleInput, type BackendSectorInput, type BaselinePoint, type BaselineVersion, CALENDAR_UNIT, COLUMN, CONSTRAINT_TYPE, CONSTRAINT_TYPE_TO_LABEL, CREATION_KIND, type Calendar, type CalendarId, type CalendarUnit, type CalendarWorktime, type ChangeSet, type ColumnName, type ConstraintType, type ConstraintWarning, type CoreActivity, type CreationKind, DEFAULT_HOURS_PER_DAY, DISPATCH_ACTION_KIND, DISPATCH_ACTION_KINDS, DISPATCH_TRACK_EVENT, type DispatchAction, type DispatchActionKind, type DispatchOptions, type DispatchRejectReason, type DispatchResult, type DispatchTrackEvent, type EntityChange, LINK_CODE_TO_TYPE, LINK_TYPE, LINK_TYPE_CODE, type Link, type LinkId, type LinkType, type LinkTypeCode, type LinksBatchOperation, NEW_ACTIVITY_DEFAULTS, type ParsedInput, type PastedActivityInput, type PastedLinkInput, type PendingRequest, type PersistedEntityIdentity, type PersistenceAcknowledgement, REJECTION_REASON, ROOT_PARENT_ID, ScheduleCore, type ScheduleCoreInput, type ScheduleCoreReporter, type ScheduleCoreStatus, type ScheduleEffect, type SectorMetadata, type StatusCriteria, type TrackingEvent, WORK_TIME_DIRECTION, type WorkTimeDirection, applyBaselinePoints, checkNoUpdatedLinks, computeExpectedProgress, expectedProgressFromBaseline, getActiveBaseline, getUnsavedActivities, isRootParent, normalizeParentKey, parseFromBackend, recomputeAllPonderators, recomputeAllProgressRollup, willRunCriticalPath, yieldToBrowser };
+export { ACTIVITY_TYPE, type ActivityCreter, type ActivityId, type ActivityType, type BackendActivityInput, type BackendCalendarInput, type BackendLinkInput, type BackendScheduleInput, type BackendSectorInput, type BaselinePoint, type BaselineVersion, CALENDAR_UNIT, COLUMN, CONSTRAINT_TYPE, CONSTRAINT_TYPE_TO_LABEL, CREATION_KIND, type Calendar, type CalendarId, type CalendarUnit, type CalendarWorktime, type ChangeSet, type ColumnName, type ConstraintType, type ConstraintWarning, type CoreActivity, type CreationKind, DEFAULT_HOURS_PER_DAY, DISPATCH_ACTION_KIND, DISPATCH_ACTION_KINDS, DISPATCH_TRACK_EVENT, type DispatchAction, type DispatchActionKind, type DispatchOptions, type DispatchRejectReason, type DispatchResult, type DispatchTrackEvent, type EntityChange, LINK_CODE_TO_TYPE, LINK_TYPE, LINK_TYPE_CODE, type Link, type LinkId, type LinkType, type LinkTypeCode, type LinksBatchOperation, NEW_ACTIVITY_DEFAULTS, type ParsedInput, type PastedActivityInput, type PastedLinkInput, type PendingRequest, type PersistedEntityIdentity, REJECTION_REASON, ROOT_PARENT_ID, ScheduleCore, type ScheduleCoreInput, type ScheduleCoreReporter, type ScheduleCoreStatus, type ScheduleEffect, type SectorMetadata, type StatusCriteria, type TrackingEvent, WORK_TIME_DIRECTION, type WorkTimeDirection, checkNoUpdatedLinks, computeExpectedProgress, expectedProgressFromBaseline, getActiveBaseline, getUnsavedActivities, isRootParent, normalizeParentKey, parseFromBackend, willRunCriticalPath, yieldToBrowser };