@outbuild-company/schedule-core 1.1.1 → 1.2.0

package/dist/index.d.cts

@@ -29,26 +29,37 @@ interface LinkSnapshot {
      * duration (`_targetLag = -summary.duration`) and the per-leaf offset from
      * the summary's start (`_trueLag = userLag + off_tgt(leaf)`), matching legacy
      * `_getImplicitLinks`/`_convertToFinishToStartLink` under
-     * `auto_scheduling_move_projects`. Computed ONCE at expansion time
-     * (`parent-link-expansion.ts`), never per scheduling tick.
+     * `auto_scheduling_move_projects`. `_targetLag`/`_trueLag` are computed once
+     * at expansion time, matching legacy relations frozen per run, and the
+     * per-leaf offset in `_trueLag` applies only to leaves with no incoming
+     * links (legacy `!c.$target.length` — a leaf with its own driver keeps
+     * offset 0, otherwise the frozen offset compounds on every settle).
+     * `_sourceLag` is the expansion-time fallback: when `_summarySourceId` is
+     * present (SS/SF out of a summary), the ASAP calculator re-derives it at
+     * evaluation time from the summary's CURRENT derived bounds so the virtual
+     * constraint stays anchored at the summary start even after the anchor leaf
+     * moves within the same run.
      *
-     * All three must be set together (or none): a half-populated link would mix
-     * precomputed and derived components. Only the FF/SF-into-summary path emits
-     * them; every other link leaves them undefined and hits the fast path.
+     * `_summaryTargetId` marks a virtual link whose `_trueLag` bakes a NON-ZERO
+     * leaf offset measured from the target summary's expansion-time bounds: the
+     * ASAP pass refuses to pull the leaf back through such a link unless the
+     * predecessor itself moved in the run (a stale frozen offset must never
+     * drag its own leaf earlier — that is the summary-link drift bug).
+     *
+     * The three lag components must be set together (or none): a half-populated
+     * link would mix precomputed and derived components. Every non-virtual link
+     * leaves them undefined and hits the fast path.
      */
     _sourceLag?: number;
     _targetLag?: number;
     _trueLag?: number;
+    _summarySourceId?: ActivityId$1;
+    _summaryTargetId?: ActivityId$1;
     ganttId?: number;
     sectorId?: number;
     /** 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 +234,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;
@@ -272,17 +285,6 @@ interface CoreActivity {
     expectedProgressBaseline: number | null;
     status: ActivityStatus | null;
     criticalPath: CriticalPathResult | null;
-    /** Internal reversible leaf→project promotion state; never serialized. */
-    promotionRestore: {
-        type: 'task' | 'milestone';
-        startDate: Date;
-        endDate: Date;
-        durationHours: number;
-        expectedProgressBaseline: number | null;
-        constraintType: ConstraintType;
-        constraintDate: Date | null;
-        progress: number;
-    } | null;
 }
 interface Link {
     id: LinkId;
@@ -523,8 +525,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;
@@ -874,6 +893,8 @@ type DispatchResult = {
      * rechazados.
      */
     verdicts?: ReadonlyArray<DatesBatchVerdict>;
+    activityVerdicts?: ReadonlyArray<DatesBatchVerdict>;
+    linkVerdicts?: ReadonlyArray<LinkBatchVerdict>;
     /**
      * INTERNAL (undo / B4). Full pre-mutation snapshot of every
      * deleted/structurally-removed activity row, keyed by STRING id. The
@@ -903,6 +924,17 @@ type DatesBatchVerdict = {
     reason: string;
     alertKey?: string | undefined;
 };
+type LinkBatchVerdict = {
+    operationIndex: number;
+    kind: LinksBatchOperation['kind'];
+    ok: true;
+    linkId: string;
+} | {
+    operationIndex: number;
+    kind: LinksBatchOperation['kind'];
+    ok: false;
+    reason: string;
+};
 
 interface TrackingEvent {
     name: string;
@@ -1086,56 +1118,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,20 +1217,8 @@ 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;
@@ -1259,7 +1229,7 @@ declare class ScheduleCore {
     get ready(): Promise<void>;
     get criticalPathReady(): Promise<{
         changes: ChangeSet;
-    }>;
+    } | null>;
     get status(): ScheduleCoreStatus;
     getSector(): Readonly<SectorMetadata>;
     getActivityView(id: ActivityId): Readonly<CoreActivity> | null;
@@ -1287,51 +1257,7 @@ 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;
@@ -1350,16 +1276,27 @@ declare class ScheduleCore {
     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;
     private readonly _initPromise;
-    private readonly _criticalPathReady;
+    private _criticalPathReady;
     private readonly _ready;
     private readonly _saveTracker;
     private assertReady;
@@ -1409,25 +1346,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;
 }
@@ -1458,67 +1376,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>;
 
@@ -1568,9 +1425,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;
 
@@ -1673,6 +1530,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";
@@ -1767,4 +1628,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 };