@logistics-ts/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,423 @@
+/**
+ * The {@link Explained} result wrapper — the cross-cutting contract that every
+ * numeric output in logistics-ts returns. Instead of a bare number, callers get
+ * the value alongside a machine-readable account of how it was derived, so that
+ * humans and AI agents can inspect the method, the inputs, and the reasoning.
+ */
+/**
+ * A computed result paired with a machine-readable explanation of how it was
+ * derived.
+ *
+ * @typeParam T - The type of the computed value.
+ */
+interface Explained<T> {
+    /** The computed value. */
+    value: T;
+    /** Identifier of the method used, e.g. `"king-formula"`. */
+    method: string;
+    /** Every input value that fed the computation, keyed by name. */
+    inputs: Record<string, number | string>;
+    /** Human- and agent-readable bullet points explaining the result. */
+    reasoning: string[];
+    /** Optional literature citations backing the method. */
+    citations?: string[];
+    /** Optional caveats, e.g. low sample size or an undefined-metric condition. */
+    warnings?: string[];
+}
+/** The explanation metadata of an {@link Explained} result, without its value. */
+type Explanation<T> = Omit<Explained<T>, 'value'>;
+/**
+ * Constructs an {@link Explained} result from a value and its explanation.
+ *
+ * @example
+ * ```ts
+ * explain(120, {
+ *   method: 'king-formula',
+ *   inputs: { serviceLevel: 0.95, leadTimeDays: 14 },
+ *   reasoning: ['95% service level', 'demand variability dominates'],
+ * })
+ * ```
+ */
+declare function explain<T>(value: T, explanation: Explanation<T>): Explained<T>;
+
+/**
+ * The canonical record types every logistics-ts analysis speaks. Loaders map
+ * arbitrary user data onto these shapes (see {@link ./table/loader}); all
+ * algorithms consume them rather than raw user objects.
+ *
+ * Dates are treated as **calendar dates**, never instants. A `Date` or an ISO
+ * date string (`"2026-01-31"`) is accepted for a record's date field. Records
+ * preserve whatever `DateInput` you pass; date arithmetic (bucketization,
+ * lead-time spans) converts to an integer epoch-day at computation time — it
+ * does not rewrite the stored value (see {@link ./time/epoch-day}).
+ */
+/** A date at the API boundary: a `Date` or an ISO `YYYY-MM-DD` string. */
+type DateInput = Date | string;
+/**
+ * A quantity of an item demanded (sold/shipped/consumed) on a date. The atomic
+ * input to forecasting and demand classification.
+ */
+interface DemandRecord {
+    /** Stable identifier of the item (SKU). */
+    itemId: string;
+    /** Calendar date the demand occurred. */
+    date: DateInput;
+    /** Quantity demanded. Must be finite and non-negative. */
+    quantity: number;
+    /** Optional stocking location, for location-aware analysis. */
+    locationId?: string;
+    /** Optional unit price at the time, used for value-based ABC classification. */
+    unitPrice?: number;
+}
+/** A snapshot of on-hand stock for an item. */
+interface StockRecord {
+    /** Stable identifier of the item (SKU). */
+    itemId: string;
+    /** Quantity on hand. Must be finite and non-negative. */
+    quantity: number;
+    /** Optional stocking location. */
+    locationId?: string;
+    /** Optional unit cost, used for value-based classification and coverage. */
+    unitCost?: number;
+    /** Optional time the snapshot was taken. */
+    timestamp?: DateInput;
+}
+/**
+ * An observed replenishment lead time for an item — one record per receipt or
+ * purchase order — so that lead-time variability (σ_LT) can be estimated.
+ */
+interface LeadTimeRecord {
+    /** Stable identifier of the item (SKU). */
+    itemId: string;
+    /** Observed lead time in days. Must be finite and non-negative. */
+    leadTimeDays: number;
+    /** Optional date the receipt/order was observed. */
+    date?: DateInput;
+}
+
+/**
+ * Input abstractions for the loaders. logistics-ts accepts three shapes of
+ * tabular input and normalises them to a single row reader:
+ *
+ * - **row input** — an array of plain objects (`{ sku, qty, ... }[]`);
+ * - **columnar input** — an object of parallel arrays (`{ sku: [...], qty: [...] }`);
+ * - **{@link TableSource}** — the seam a future DuckDB/Parquet adapter implements
+ *   to hand column-oriented data to the loaders without materialising objects.
+ */
+/** A column-oriented source of tabular data. The adapter seam. */
+interface TableSource {
+    /** Number of rows. */
+    readonly numRows: number;
+    /** Names of the available columns. */
+    readonly columnNames: readonly string[];
+    /** Returns the values of a column as an indexable, row-aligned sequence. */
+    getColumn(name: string): ArrayLike<unknown>;
+}
+/**
+ * An array of row objects keyed by column name. Typed to `object` so that
+ * typed record arrays (interfaces, which TypeScript does not consider
+ * assignable to an index signature) are accepted without a cast.
+ */
+type RowInput = ReadonlyArray<object>;
+/** An object of parallel, row-aligned column arrays. */
+type ColumnarInput = Record<string, ArrayLike<unknown>>;
+/** Any accepted tabular input. */
+type TableInput = RowInput | ColumnarInput | TableSource;
+
+/**
+ * Loaders that map arbitrary tabular input onto the canonical record types via a
+ * column mapping, coercing CSV-style string cells and collecting per-row
+ * validation issues rather than throwing on the first bad row.
+ *
+ * Structural problems throw immediately — that is a configuration mistake. A
+ * structural problem is a required column missing entirely, or a column the
+ * caller explicitly named in the mapping that does not exist in the input.
+ * (Empty input is not structural: it loads as zero records.)
+ *
+ * Per-row data problems are collected as {@link LoadIssue}s, unless
+ * `throwOnIssue` is set. An invalid **required** field (a non-numeric quantity,
+ * an unparseable date) skips the row; an invalid **optional** field (a
+ * non-numeric unit price) keeps the row and omits the field — but is still
+ * recorded as an issue. A genuinely absent optional cell is not an issue.
+ */
+
+/** A single per-row validation problem. */
+interface LoadIssue {
+    /** Zero-based row index in the input. */
+    row: number;
+    /** The source column the problem concerns. */
+    column: string;
+    /** Human- and agent-readable description of the problem. */
+    problem: string;
+}
+/** The result of a load: the valid records plus any collected issues. */
+interface LoadResult<T> {
+    records: T[];
+    issues: LoadIssue[];
+}
+interface LoadOptions {
+    /** Throw on the first data issue instead of collecting it and skipping the row. */
+    throwOnIssue?: boolean;
+}
+/** Maps canonical {@link DemandRecord} fields to source column names. */
+interface DemandColumnMap {
+    itemId?: string;
+    date?: string;
+    quantity?: string;
+    locationId?: string;
+    unitPrice?: string;
+}
+/** Maps canonical {@link StockRecord} fields to source column names. */
+interface StockColumnMap {
+    itemId?: string;
+    quantity?: string;
+    locationId?: string;
+    unitCost?: string;
+    timestamp?: string;
+}
+/** Maps canonical {@link LeadTimeRecord} fields to source column names. */
+interface LeadTimeColumnMap {
+    itemId?: string;
+    leadTimeDays?: string;
+    date?: string;
+}
+/** Loads and validates {@link DemandRecord}s from tabular input. */
+declare function loadDemand(input: TableInput, mapping?: DemandColumnMap, options?: LoadOptions): LoadResult<DemandRecord>;
+/** Loads and validates {@link StockRecord}s from tabular input. */
+declare function loadStock(input: TableInput, mapping?: StockColumnMap, options?: LoadOptions): LoadResult<StockRecord>;
+/** Loads and validates {@link LeadTimeRecord}s from tabular input. */
+declare function loadLeadTimes(input: TableInput, mapping?: LeadTimeColumnMap, options?: LoadOptions): LoadResult<LeadTimeRecord>;
+
+/**
+ * Calendar-date handling. logistics-ts treats every date as a **calendar date**
+ * (never an instant with a timezone), represented internally as an integer
+ * "epoch day" — the number of whole days since 1970-01-01 in UTC. This keeps
+ * bucketization deterministic and free of daylight-saving/timezone drift, with
+ * no date-library dependency.
+ */
+
+/**
+ * Converts a {@link DateInput} to an integer epoch day (days since 1970-01-01,
+ * UTC). ISO strings are read by their calendar `YYYY-MM-DD` part (a trailing
+ * time part is accepted and ignored); `Date` values are read by their UTC
+ * year/month/day. Throws on an unparseable value.
+ */
+declare function toEpochDay(input: DateInput): number;
+/**
+ * Converts an epoch day back to a UTC-midnight `Date`. An epoch day is an
+ * integer count of days; a non-integer input is rejected so the midnight
+ * contract holds.
+ */
+declare function fromEpochDay(epochDay: number): Date;
+/** Formats an epoch day as an ISO `YYYY-MM-DD` calendar date. */
+declare function formatEpochDay(epochDay: number): string;
+/** ISO weekday of an epoch day, Monday = 0 … Sunday = 6. */
+declare function isoWeekday(epochDay: number): number;
+
+/**
+ * Aggregates raw demand records into dense, chronological, **zero-filled** time
+ * series per item. Zero-filling is essential: intermittent-demand statistics
+ * (ADI, CV²) and forecasting models are only meaningful when the periods with no
+ * demand are present as explicit zeros rather than missing rows.
+ */
+
+/** Time granularity for bucketization. */
+type Granularity = 'day' | 'week' | 'month';
+/** A single dense time bucket. */
+interface DemandBucket {
+    /**
+     * Canonical period label: `YYYY-MM-DD` for `day`, the Monday's `YYYY-MM-DD`
+     * for `week`, and `YYYY-MM` for `month`.
+     */
+    period: string;
+    /** Total demand in the period (0 for zero-filled gaps). */
+    quantity: number;
+}
+/** A dense, chronological, zero-filled demand series for one item. */
+interface DemandSeries {
+    itemId: string;
+    granularity: Granularity;
+    buckets: DemandBucket[];
+}
+interface BucketizeOptions {
+    /**
+     * Inclusive range start. When omitted, each item's series starts at its own
+     * earliest demand. Provide this to align every item to a common calendar.
+     */
+    start?: DateInput;
+    /** Inclusive range end. When omitted, each item's series ends at its latest demand. */
+    end?: DateInput;
+}
+/**
+ * Buckets demand records into dense, zero-filled series — one per item, sorted
+ * by `itemId`, each chronologically ordered.
+ *
+ * @param records - Raw demand records; multiple records in the same period are summed.
+ * @param granularity - `day`, `week`, or `month`.
+ * @param options - Optional common calendar range (see {@link BucketizeOptions}).
+ */
+declare function bucketize(records: readonly DemandRecord[], granularity: Granularity, options?: BucketizeOptions): DemandSeries[];
+
+/**
+ * Descriptive statistics used throughout logistics-ts. Sample statistics use the
+ * unbiased (n − 1) denominator by default; pass `population: true` for the
+ * biased (n) form where the data is the whole population.
+ */
+/** Arithmetic mean. Returns `NaN` for an empty input. */
+declare function mean(values: readonly number[]): number;
+/**
+ * Variance. Sample (n − 1) by default; population (n) when `population` is true.
+ * Returns `NaN` for the sample form given fewer than two values, and for the
+ * population form given an empty input.
+ */
+declare function variance(values: readonly number[], population?: boolean): number;
+/** Standard deviation — the square root of {@link variance}. */
+declare function standardDeviation(values: readonly number[], population?: boolean): number;
+/**
+ * Coefficient of variation: standard deviation divided by the mean. A unitless
+ * measure of relative dispersion. Returns `NaN` when the mean is zero.
+ */
+declare function coefficientOfVariation(values: readonly number[], population?: boolean): number;
+/**
+ * Squared coefficient of variation (CV²) of the **non-zero** values only.
+ *
+ * This is the demand-lumpiness axis of the Syntetos–Boylan–Croston
+ * classification: CV² is computed over demand *sizes* (the periods with demand),
+ * ignoring the zero periods. Returns `NaN` when there are fewer than two
+ * non-zero values.
+ *
+ * @see Syntetos, A.A., Boylan, J.E. & Croston, J.D. (2005). On the categorization
+ *   of demand patterns. Journal of the Operational Research Society, 56(5).
+ */
+declare function squaredCvOfNonZero(values: readonly number[]): number;
+/**
+ * Average Demand Interval (ADI): the mean number of periods between consecutive
+ * non-zero demands, measured across the full series length.
+ *
+ * Defined as `periods / numberOfNonZeroDemands`. This is the demand-intermittence
+ * axis of the Syntetos–Boylan–Croston classification. Returns `NaN` when there
+ * are no non-zero demands.
+ *
+ * @param series - Demand per period, including zero periods.
+ * @see Syntetos, Boylan & Croston (2005).
+ */
+declare function averageDemandInterval(series: readonly number[]): number;
+
+/**
+ * Standard-normal distribution helpers. These back service-level → z-score
+ * conversions (safety stock) and the unit normal loss integral (fill-rate).
+ */
+/** Standard-normal probability density function, φ(z). */
+declare function normalPdf(z: number): number;
+/**
+ * Standard-normal cumulative distribution function, Φ(z). Accuracy follows the
+ * underlying erf approximation — absolute error ≈ 1.5 × 10⁻⁷, coarser than
+ * {@link inverseNormalCdf}'s 1.15 × 10⁻⁹ and inherited by
+ * {@link normalLossFunction}.
+ */
+declare function normalCdf(z: number): number;
+/**
+ * Inverse standard-normal CDF (the quantile / probit function): returns the z
+ * such that Φ(z) = p.
+ *
+ * Uses Acklam's rational approximation, with a relative error below
+ * 1.15 × 10⁻⁹ across the open interval (0, 1). Returns `-Infinity` at p = 0,
+ * `+Infinity` at p = 1, and `NaN` outside [0, 1].
+ *
+ * @example
+ * ```ts
+ * inverseNormalCdf(0.95)  // ≈ 1.6448536  (95% service level)
+ * inverseNormalCdf(0.975) // ≈ 1.9599640
+ * ```
+ * @see Acklam, P.J. (2003). An algorithm for computing the inverse normal
+ *   cumulative distribution function.
+ */
+declare function inverseNormalCdf(p: number): number;
+/**
+ * Unit normal loss function, E(z) = φ(z) − z · (1 − Φ(z)): the expected shortfall
+ * per unit of standard deviation for a standard-normal demand. Used to translate
+ * a target **fill rate** (units satisfied) into safety stock — as distinct from
+ * a cycle service level (order cycles without stockout).
+ *
+ * @see Silver, E.A., Pyke, D.F. & Thomas, D.J. (2017). Inventory and Production
+ *   Management in Supply Chains, 4th ed.
+ */
+declare function normalLossFunction(z: number): number;
+
+/**
+ * Nelder–Mead simplex minimiser — a derivative-free optimiser used to fit
+ * smoothing parameters (e.g. α, β, γ for exponential smoothing) by minimising a
+ * sum-of-squared-errors objective. Dependency-free.
+ *
+ * The search is unconstrained; to impose bounds (such as 0 ≤ α ≤ 1), have the
+ * objective return a large penalty outside the feasible region.
+ *
+ * @see Nelder, J.A. & Mead, R. (1965). A simplex method for function
+ *   minimization. The Computer Journal, 7(4), 308–313.
+ */
+/** A scalar objective over an n-dimensional parameter vector. */
+type Objective = (x: readonly number[]) => number;
+interface NelderMeadOptions {
+    /** Initial simplex edge length per dimension. Default 0.1. */
+    step?: number;
+    /** Maximum iterations before giving up. Default 200. */
+    maxIterations?: number;
+    /**
+     * Convergence tolerance on the spread of objective values across the simplex.
+     * Default 1e-8.
+     */
+    tolerance?: number;
+}
+interface NelderMeadResult {
+    /** The best parameter vector found. */
+    x: number[];
+    /** The objective value at {@link NelderMeadResult.x}. */
+    fx: number;
+    /** Iterations performed. */
+    iterations: number;
+    /** Whether the tolerance was met before `maxIterations`. */
+    converged: boolean;
+}
+/** Minimises `f` starting from `x0` using the Nelder–Mead simplex method. */
+declare function nelderMead(f: Objective, x0: readonly number[], options?: NelderMeadOptions): NelderMeadResult;
+
+/**
+ * Deterministic synthetic supply-chain data. Given a seed, this produces a
+ * repeatable catalogue of demand history, on-hand stock, and observed lead
+ * times — so that examples, demos, and AI agents can exercise the library with
+ * zero setup and realistic demand shapes.
+ */
+
+/** The statistical character of an item's demand. */
+type DemandProfile = 'smooth' | 'seasonal' | 'trending' | 'intermittent' | 'lumpy' | 'mixed';
+interface GenerateOptions {
+    /** Number of items (SKUs) to generate. Default 10. */
+    items?: number;
+    /** Number of periods of history per item. Default 24. */
+    periods?: number;
+    /** Demand profile applied to every item, or `'mixed'` to vary it. Default `'mixed'`. */
+    profile?: DemandProfile;
+    /** Spacing between periods. Default `'month'`. */
+    granularity?: Granularity;
+    /** Date of the first period. Default `'2024-01-01'`. */
+    startDate?: DateInput;
+    /** Seed for the PRNG. The same seed always yields the same dataset. Default 1. */
+    seed?: number;
+}
+/** A self-contained synthetic dataset. */
+interface ExampleDataset {
+    demand: DemandRecord[];
+    stock: StockRecord[];
+    leadTimes: LeadTimeRecord[];
+}
+/**
+ * Generates a deterministic synthetic dataset.
+ *
+ * @example
+ * ```ts
+ * const { demand, stock, leadTimes } = generateExampleData({ items: 20, periods: 36 })
+ * ```
+ */
+declare function generateExampleData(options?: GenerateOptions): ExampleDataset;
+
+export { type BucketizeOptions, type ColumnarInput, type DateInput, type DemandBucket, type DemandColumnMap, type DemandProfile, type DemandRecord, type DemandSeries, type ExampleDataset, type Explained, type Explanation, type GenerateOptions, type Granularity, type LeadTimeColumnMap, type LeadTimeRecord, type LoadIssue, type LoadOptions, type LoadResult, type NelderMeadOptions, type NelderMeadResult, type Objective, type RowInput, type StockColumnMap, type StockRecord, type TableInput, type TableSource, averageDemandInterval, bucketize, coefficientOfVariation, explain, formatEpochDay, fromEpochDay, generateExampleData, inverseNormalCdf, isoWeekday, loadDemand, loadLeadTimes, loadStock, mean, nelderMead, normalCdf, normalLossFunction, normalPdf, squaredCvOfNonZero, standardDeviation, toEpochDay, variance };

package/dist/index.js

@@ -0,0 +1,602 @@
+// src/explained.ts
+function explain(value, explanation) {
+  return { value, ...explanation };
+}
+
+// src/time/epoch-day.ts
+var MS_PER_DAY = 864e5;
+var ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+function toEpochDay(input) {
+  if (input instanceof Date) {
+    if (Number.isNaN(input.getTime())) throw new RangeError("Invalid Date");
+    return Math.floor(
+      Date.UTC(input.getUTCFullYear(), input.getUTCMonth(), input.getUTCDate()) / MS_PER_DAY
+    );
+  }
+  const match = ISO_DATE.exec(input);
+  if (!match) throw new RangeError(`Unparseable date: ${JSON.stringify(input)}`);
+  const year = Number(match[1]);
+  const month = Number(match[2]) - 1;
+  const day = Number(match[3]);
+  const utc = Date.UTC(year, month, day);
+  const d = new Date(utc);
+  if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month || d.getUTCDate() !== day) {
+    throw new RangeError(`Invalid calendar date: ${input}`);
+  }
+  return Math.floor(utc / MS_PER_DAY);
+}
+function fromEpochDay(epochDay) {
+  if (!Number.isInteger(epochDay)) {
+    throw new RangeError(`Epoch day must be an integer, got ${epochDay}`);
+  }
+  return new Date(epochDay * MS_PER_DAY);
+}
+function formatEpochDay(epochDay) {
+  return fromEpochDay(epochDay).toISOString().slice(0, 10);
+}
+function isoWeekday(epochDay) {
+  return ((epochDay % 7 + 4) % 7 + 6) % 7;
+}
+
+// src/table/table-source.ts
+function isTableSource(input) {
+  const candidate = input;
+  return !Array.isArray(input) && typeof candidate.getColumn === "function" && typeof candidate.numRows === "number" && Array.isArray(candidate.columnNames);
+}
+function normalizeInput(input) {
+  if (Array.isArray(input)) {
+    const rows = input;
+    return {
+      numRows: rows.length,
+      // Scan for the column rather than trusting the first row — rows may be
+      // sparse. `some` short-circuits, so the homogeneous case stays O(1). Use an
+      // own-property check so inherited members (`toString`, …) are not columns.
+      hasColumn: (name) => rows.some((r) => Object.hasOwn(r, name)),
+      getCell: (row, column) => rows[row]?.[column]
+    };
+  }
+  if (isTableSource(input)) {
+    const columns2 = new Set(input.columnNames);
+    const cache = /* @__PURE__ */ new Map();
+    const column = (name) => {
+      let col = cache.get(name);
+      if (!col) {
+        col = input.getColumn(name);
+        cache.set(name, col);
+      }
+      return col;
+    };
+    return {
+      numRows: input.numRows,
+      hasColumn: (name) => columns2.has(name),
+      getCell: (row, name) => columns2.has(name) ? column(name)[row] : void 0
+    };
+  }
+  const columnar = input;
+  const names = Object.keys(columnar);
+  let numRows = 0;
+  for (const name of names) numRows = Math.max(numRows, columnar[name]?.length ?? 0);
+  const columns = new Set(names);
+  return {
+    numRows,
+    hasColumn: (name) => columns.has(name),
+    getCell: (row, name) => columnar[name]?.[row]
+  };
+}
+
+// src/table/loader.ts
+function toStringCell(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed === "" ? null : trimmed;
+  }
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return null;
+}
+function toNumberCell(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed === "") return null;
+    const n = Number(trimmed);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+function toDateCell(value) {
+  if (!(value instanceof Date) && typeof value !== "string") return null;
+  try {
+    toEpochDay(value);
+    return value;
+  } catch {
+    return null;
+  }
+}
+function raise(ctx, column, problem) {
+  const issue = { row: ctx.row, column, problem };
+  if (ctx.throwOnIssue) {
+    throw new Error(`Row ${ctx.row}, column "${column}": ${problem}`);
+  }
+  ctx.issues.push(issue);
+  return void 0;
+}
+function isAbsent(value) {
+  return value === null || value === void 0 || typeof value === "string" && value.trim() === "";
+}
+function requireQuantity(value, column, ctx) {
+  const n = toNumberCell(value);
+  if (n === null) return raise(ctx, column, "expected a finite number");
+  if (n < 0) return raise(ctx, column, "must not be negative");
+  return n;
+}
+function optionalNumber(value, column, ctx) {
+  if (isAbsent(value)) return void 0;
+  return requireQuantity(value, column, ctx);
+}
+function optionalDate(value, column, ctx) {
+  if (isAbsent(value)) return void 0;
+  const date = toDateCell(value);
+  if (date === null) return raise(ctx, column, "expected a calendar date (Date or ISO YYYY-MM-DD)");
+  return date;
+}
+function optionalString(value, column, ctx) {
+  if (isAbsent(value)) return void 0;
+  const s = toStringCell(value);
+  if (s === null) return raise(ctx, column, "expected a string");
+  return s;
+}
+function requireColumns(reader, columns) {
+  if (reader.numRows === 0) return;
+  const missing = columns.filter((c) => c !== void 0 && !reader.hasColumn(c));
+  if (missing.length > 0) {
+    throw new Error(`Input is missing expected column(s): ${missing.join(", ")}`);
+  }
+}
+function loadDemand(input, mapping = {}, options = {}) {
+  const reader = normalizeInput(input);
+  const col = {
+    itemId: mapping.itemId ?? "itemId",
+    date: mapping.date ?? "date",
+    quantity: mapping.quantity ?? "quantity",
+    locationId: mapping.locationId ?? "locationId",
+    unitPrice: mapping.unitPrice ?? "unitPrice"
+  };
+  requireColumns(reader, [
+    col.itemId,
+    col.date,
+    col.quantity,
+    mapping.locationId,
+    mapping.unitPrice
+  ]);
+  const throwOnIssue = options.throwOnIssue ?? false;
+  const records = [];
+  const issues = [];
+  for (let row = 0; row < reader.numRows; row++) {
+    const ctx = { row, issues, throwOnIssue };
+    const itemId = toStringCell(reader.getCell(row, col.itemId));
+    if (itemId === null) {
+      raise(ctx, col.itemId, "expected a non-empty item id");
+      continue;
+    }
+    const date = toDateCell(reader.getCell(row, col.date));
+    if (date === null) {
+      raise(ctx, col.date, "expected a calendar date (Date or ISO YYYY-MM-DD)");
+      continue;
+    }
+    const quantity = requireQuantity(reader.getCell(row, col.quantity), col.quantity, ctx);
+    if (quantity === void 0) continue;
+    const record = { itemId, date, quantity };
+    const locationId = optionalString(reader.getCell(row, col.locationId), col.locationId, ctx);
+    if (locationId !== void 0) record.locationId = locationId;
+    const unitPrice = optionalNumber(reader.getCell(row, col.unitPrice), col.unitPrice, ctx);
+    if (unitPrice !== void 0) record.unitPrice = unitPrice;
+    records.push(record);
+  }
+  return { records, issues };
+}
+function loadStock(input, mapping = {}, options = {}) {
+  const reader = normalizeInput(input);
+  const col = {
+    itemId: mapping.itemId ?? "itemId",
+    quantity: mapping.quantity ?? "quantity",
+    locationId: mapping.locationId ?? "locationId",
+    unitCost: mapping.unitCost ?? "unitCost",
+    timestamp: mapping.timestamp ?? "timestamp"
+  };
+  requireColumns(reader, [
+    col.itemId,
+    col.quantity,
+    mapping.locationId,
+    mapping.unitCost,
+    mapping.timestamp
+  ]);
+  const throwOnIssue = options.throwOnIssue ?? false;
+  const records = [];
+  const issues = [];
+  for (let row = 0; row < reader.numRows; row++) {
+    const ctx = { row, issues, throwOnIssue };
+    const itemId = toStringCell(reader.getCell(row, col.itemId));
+    if (itemId === null) {
+      raise(ctx, col.itemId, "expected a non-empty item id");
+      continue;
+    }
+    const quantity = requireQuantity(reader.getCell(row, col.quantity), col.quantity, ctx);
+    if (quantity === void 0) continue;
+    const record = { itemId, quantity };
+    const locationId = optionalString(reader.getCell(row, col.locationId), col.locationId, ctx);
+    if (locationId !== void 0) record.locationId = locationId;
+    const unitCost = optionalNumber(reader.getCell(row, col.unitCost), col.unitCost, ctx);
+    if (unitCost !== void 0) record.unitCost = unitCost;
+    const timestamp = optionalDate(reader.getCell(row, col.timestamp), col.timestamp, ctx);
+    if (timestamp !== void 0) record.timestamp = timestamp;
+    records.push(record);
+  }
+  return { records, issues };
+}
+function loadLeadTimes(input, mapping = {}, options = {}) {
+  const reader = normalizeInput(input);
+  const col = {
+    itemId: mapping.itemId ?? "itemId",
+    leadTimeDays: mapping.leadTimeDays ?? "leadTimeDays",
+    date: mapping.date ?? "date"
+  };
+  requireColumns(reader, [col.itemId, col.leadTimeDays, mapping.date]);
+  const throwOnIssue = options.throwOnIssue ?? false;
+  const records = [];
+  const issues = [];
+  for (let row = 0; row < reader.numRows; row++) {
+    const ctx = { row, issues, throwOnIssue };
+    const itemId = toStringCell(reader.getCell(row, col.itemId));
+    if (itemId === null) {
+      raise(ctx, col.itemId, "expected a non-empty item id");
+      continue;
+    }
+    const leadTimeDays = requireQuantity(
+      reader.getCell(row, col.leadTimeDays),
+      col.leadTimeDays,
+      ctx
+    );
+    if (leadTimeDays === void 0) continue;
+    const record = { itemId, leadTimeDays };
+    const date = optionalDate(reader.getCell(row, col.date), col.date, ctx);
+    if (date !== void 0) record.date = date;
+    records.push(record);
+  }
+  return { records, issues };
+}
+
+// src/time/bucketize.ts
+function bucketKey(epochDay, granularity) {
+  switch (granularity) {
+    case "day":
+      return epochDay;
+    case "week":
+      return epochDay - isoWeekday(epochDay);
+    case "month": {
+      const d = fromEpochDay(epochDay);
+      return d.getUTCFullYear() * 12 + d.getUTCMonth();
+    }
+  }
+}
+function keyStep(granularity) {
+  return granularity === "week" ? 7 : 1;
+}
+function keyToLabel(key, granularity) {
+  if (granularity === "month") {
+    const year = Math.floor(key / 12);
+    const month = key % 12;
+    return `${year}-${String(month + 1).padStart(2, "0")}`;
+  }
+  return formatEpochDay(key);
+}
+function bucketize(records, granularity, options = {}) {
+  const step = keyStep(granularity);
+  const rangeStart = options.start !== void 0 ? bucketKey(toEpochDay(options.start), granularity) : void 0;
+  const rangeEnd = options.end !== void 0 ? bucketKey(toEpochDay(options.end), granularity) : void 0;
+  if (rangeStart !== void 0 && rangeEnd !== void 0 && rangeStart > rangeEnd) {
+    throw new RangeError(
+      `bucketize range start (${String(options.start)}) must not be after end (${String(options.end)})`
+    );
+  }
+  const perItem = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const key = bucketKey(toEpochDay(record.date), granularity);
+    let entry = perItem.get(record.itemId);
+    if (!entry) {
+      entry = { totals: /* @__PURE__ */ new Map(), min: key, max: key };
+      perItem.set(record.itemId, entry);
+    }
+    entry.totals.set(key, (entry.totals.get(key) ?? 0) + record.quantity);
+    if (key < entry.min) entry.min = key;
+    if (key > entry.max) entry.max = key;
+  }
+  const series = [];
+  for (const itemId of [...perItem.keys()].sort()) {
+    const entry = perItem.get(itemId);
+    const from = rangeStart ?? entry.min;
+    const to = rangeEnd ?? entry.max;
+    const buckets = [];
+    for (let key = from; key <= to; key += step) {
+      buckets.push({ period: keyToLabel(key, granularity), quantity: entry.totals.get(key) ?? 0 });
+    }
+    series.push({ itemId, granularity, buckets });
+  }
+  return series;
+}
+
+// src/numerics/stats.ts
+function mean(values) {
+  if (values.length === 0) return Number.NaN;
+  let sum = 0;
+  for (const v of values) sum += v;
+  return sum / values.length;
+}
+function variance(values, population = false) {
+  const n = values.length;
+  if (population ? n === 0 : n < 2) return Number.NaN;
+  const m = mean(values);
+  let sumSq = 0;
+  for (const v of values) {
+    const d = v - m;
+    sumSq += d * d;
+  }
+  return sumSq / (population ? n : n - 1);
+}
+function standardDeviation(values, population = false) {
+  return Math.sqrt(variance(values, population));
+}
+function coefficientOfVariation(values, population = false) {
+  const m = mean(values);
+  if (m === 0) return Number.NaN;
+  return standardDeviation(values, population) / m;
+}
+function squaredCvOfNonZero(values) {
+  const nonZero = values.filter((v) => v !== 0);
+  const cv = coefficientOfVariation(nonZero);
+  return cv * cv;
+}
+function averageDemandInterval(series) {
+  if (series.length === 0) return Number.NaN;
+  let nonZeroCount = 0;
+  for (const v of series) if (v !== 0) nonZeroCount++;
+  if (nonZeroCount === 0) return Number.NaN;
+  return series.length / nonZeroCount;
+}
+
+// src/numerics/normal.ts
+function normalPdf(z) {
+  return Math.exp(-0.5 * z * z) / Math.sqrt(2 * Math.PI);
+}
+function erf(x) {
+  const sign = Math.sign(x);
+  const ax = Math.abs(x);
+  const t = 1 / (1 + 0.3275911 * ax);
+  const y = 1 - ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * Math.exp(-ax * ax);
+  return sign * y;
+}
+function normalCdf(z) {
+  return 0.5 * (1 + erf(z / Math.SQRT2));
+}
+function inverseNormalCdf(p) {
+  if (Number.isNaN(p) || p < 0 || p > 1) return Number.NaN;
+  if (p === 0) return Number.NEGATIVE_INFINITY;
+  if (p === 1) return Number.POSITIVE_INFINITY;
+  const [a1, a2, a3, a4, a5, a6] = [
+    -39.69683028665376,
+    220.9460984245205,
+    -275.9285104469687,
+    138.357751867269,
+    -30.66479806614716,
+    2.506628277459239
+  ];
+  const [b1, b2, b3, b4, b5] = [
+    -54.47609879822406,
+    161.5858368580409,
+    -155.6989798598866,
+    66.80131188771972,
+    -13.28068155288572
+  ];
+  const [c1, c2, c3, c4, c5, c6] = [
+    -0.007784894002430293,
+    -0.3223964580411365,
+    -2.400758277161838,
+    -2.549732539343734,
+    4.374664141464968,
+    2.938163982698783
+  ];
+  const [d1, d2, d3, d4] = [
+    0.007784695709041462,
+    0.3224671290700398,
+    2.445134137142996,
+    3.754408661907416
+  ];
+  const pLow = 0.02425;
+  const pHigh = 1 - pLow;
+  if (p < pLow) {
+    const q2 = Math.sqrt(-2 * Math.log(p));
+    return (((((c1 * q2 + c2) * q2 + c3) * q2 + c4) * q2 + c5) * q2 + c6) / ((((d1 * q2 + d2) * q2 + d3) * q2 + d4) * q2 + 1);
+  }
+  if (p <= pHigh) {
+    const q2 = p - 0.5;
+    const r = q2 * q2;
+    return (((((a1 * r + a2) * r + a3) * r + a4) * r + a5) * r + a6) * q2 / (((((b1 * r + b2) * r + b3) * r + b4) * r + b5) * r + 1);
+  }
+  const q = Math.sqrt(-2 * Math.log(1 - p));
+  return -(((((c1 * q + c2) * q + c3) * q + c4) * q + c5) * q + c6) / ((((d1 * q + d2) * q + d3) * q + d4) * q + 1);
+}
+function normalLossFunction(z) {
+  return normalPdf(z) - z * (1 - normalCdf(z));
+}
+
+// src/numerics/optimize.ts
+function nelderMead(f, x0, options = {}) {
+  const { step = 0.1, maxIterations = 200, tolerance = 1e-8 } = options;
+  const n = x0.length;
+  if (n === 0) throw new Error("nelderMead requires a non-empty initial vector");
+  const alpha = 1;
+  const gamma = 2;
+  const rho = 0.5;
+  const sigma = 0.5;
+  const simplex = [{ x: [...x0], fx: f(x0) }];
+  for (let i = 0; i < n; i++) {
+    const x = [...x0];
+    x[i] = (x[i] ?? 0) + step;
+    simplex.push({ x, fx: f(x) });
+  }
+  const shrink = () => {
+    const best2 = simplex[0];
+    for (let i = 1; i <= n; i++) {
+      const v = simplex[i];
+      const x = v.x.map((xi, j) => best2.x[j] + sigma * (xi - best2.x[j]));
+      simplex[i] = evaluate(f, x);
+    }
+  };
+  let iterations = 0;
+  let converged = false;
+  for (; iterations < maxIterations; iterations++) {
+    simplex.sort((p, q) => p.fx - q.fx);
+    const best2 = simplex[0];
+    const worst = simplex[n];
+    const secondWorst = simplex[n - 1];
+    if (Math.abs(worst.fx - best2.fx) <= tolerance) {
+      converged = true;
+      break;
+    }
+    const centroid = new Array(n).fill(0);
+    for (let i = 0; i < n; i++) {
+      const v = simplex[i];
+      for (let j = 0; j < n; j++) centroid[j] = centroid[j] + v.x[j];
+    }
+    for (let j = 0; j < n; j++) centroid[j] = centroid[j] / n;
+    const reflected = evaluate(f, combine(centroid, worst.x, alpha));
+    if (reflected.fx < best2.fx) {
+      const expanded = evaluate(f, combine(centroid, worst.x, alpha * gamma));
+      simplex[n] = expanded.fx < reflected.fx ? expanded : reflected;
+    } else if (reflected.fx < secondWorst.fx) {
+      simplex[n] = reflected;
+    } else if (reflected.fx < worst.fx) {
+      const contracted = evaluate(f, combine(centroid, worst.x, rho));
+      if (contracted.fx <= reflected.fx) simplex[n] = contracted;
+      else shrink();
+    } else {
+      const contracted = evaluate(f, combine(centroid, worst.x, -rho));
+      if (contracted.fx < worst.fx) simplex[n] = contracted;
+      else shrink();
+    }
+  }
+  simplex.sort((p, q) => p.fx - q.fx);
+  const best = simplex[0];
+  return { x: best.x, fx: best.fx, iterations, converged };
+}
+function combine(centroid, worst, coefficient) {
+  return centroid.map((c, j) => c + coefficient * (c - worst[j]));
+}
+function evaluate(f, x) {
+  return { x, fx: f(x) };
+}
+
+// src/synthetic/generate.ts
+var BASE_PROFILES = [
+  "smooth",
+  "seasonal",
+  "trending",
+  "intermittent",
+  "lumpy"
+];
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 | 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function gaussian(rng) {
+  let u = 0;
+  while (u === 0) u = rng();
+  const v = rng();
+  return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+function periodDate(startEpochDay, index, granularity) {
+  if (granularity !== "month") {
+    const step = granularity === "week" ? 7 : 1;
+    return formatEpochDay(startEpochDay + index * step);
+  }
+  const start = fromEpochDay(startEpochDay);
+  const monthOrdinal = start.getUTCFullYear() * 12 + start.getUTCMonth() + index;
+  const year = Math.floor(monthOrdinal / 12);
+  const month = monthOrdinal % 12;
+  const daysInMonth = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+  const day = Math.min(start.getUTCDate(), daysInMonth);
+  return `${year}-${String(month + 1).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+function demandForPeriod(profile, level, period, periods, rng) {
+  switch (profile) {
+    case "smooth":
+      return Math.max(0, Math.round(level + gaussian(rng) * level * 0.1));
+    case "seasonal": {
+      const seasonal = 1 + 0.5 * Math.sin(2 * Math.PI * period / 12);
+      return Math.max(0, Math.round(level * seasonal + gaussian(rng) * level * 0.1));
+    }
+    case "trending": {
+      const growth = 1 + 0.8 * period / Math.max(1, periods - 1);
+      return Math.max(0, Math.round(level * growth + gaussian(rng) * level * 0.1));
+    }
+    case "intermittent":
+      return rng() < 0.3 ? Math.max(1, Math.round(level + gaussian(rng) * level * 0.15)) : 0;
+    case "lumpy":
+      return rng() < 0.25 ? Math.max(1, Math.round(level * (0.2 + rng() * 2.8))) : 0;
+    case "mixed":
+      return demandForPeriod("smooth", level, period, periods, rng);
+  }
+}
+function generateExampleData(options = {}) {
+  const {
+    items = 10,
+    periods = 24,
+    profile = "mixed",
+    granularity = "month",
+    startDate = "2024-01-01",
+    seed = 1
+  } = options;
+  const rng = mulberry32(seed);
+  const startEpochDay = toEpochDay(startDate);
+  const demand = [];
+  const stock = [];
+  const leadTimes = [];
+  for (let i = 0; i < items; i++) {
+    const itemId = `SKU-${String(i + 1).padStart(4, "0")}`;
+    const itemProfile = profile === "mixed" ? BASE_PROFILES[i % BASE_PROFILES.length] : profile;
+    const level = Math.round(20 + rng() * 180);
+    const unitPrice = Math.round((5 + rng() * 95) * 100) / 100;
+    const unitCost = Math.round(unitPrice * (0.4 + rng() * 0.3) * 100) / 100;
+    for (let period = 0; period < periods; period++) {
+      const quantity = demandForPeriod(itemProfile, level, period, periods, rng);
+      if (quantity > 0) {
+        demand.push({
+          itemId,
+          date: periodDate(startEpochDay, period, granularity),
+          quantity,
+          unitPrice
+        });
+      }
+    }
+    stock.push({
+      itemId,
+      quantity: Math.round(level * (0.5 + rng() * 2.5)),
+      unitCost
+    });
+    const leadTimeMean = Math.round(7 + rng() * 23);
+    for (let k = 0; k < 5; k++) {
+      leadTimes.push({
+        itemId,
+        leadTimeDays: Math.max(1, Math.round(leadTimeMean + gaussian(rng) * leadTimeMean * 0.2))
+      });
+    }
+  }
+  return { demand, stock, leadTimes };
+}
+
+export { averageDemandInterval, bucketize, coefficientOfVariation, explain, formatEpochDay, fromEpochDay, generateExampleData, inverseNormalCdf, isoWeekday, loadDemand, loadLeadTimes, loadStock, mean, nelderMead, normalCdf, normalLossFunction, normalPdf, squaredCvOfNonZero, standardDeviation, toEpochDay, variance };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@logistics-ts/core",
+  "version": "0.0.1",
+  "description": "Core types, column store, data loading, and shared numerics for logistics-ts.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adam-drag/logistics-ts.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/adam-drag/logistics-ts/tree/main/packages/core",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}