@skygraph/core 0.0.0-placeholder.0 → 0.4.0

package/dist/calendar.d.cts

@@ -0,0 +1,209 @@
+import { C as Core } from './types-B-rKQJ4R.cjs';
+
+/**
+ * Resource Calendar — engine domain types.
+ *
+ * The engine works with `number` (epoch ms) timestamps internally so the
+ * full state can round-trip through `core.snapshot()` / `core.restore()`
+ * without any custom (de)serialization. The React adapter accepts both
+ * `Date` and `number` on the public surface and normalizes on input.
+ */
+type CalendarScale = 'day' | 'week' | 'month';
+type AssignmentStatus = 'tentative' | 'confirmed' | 'conflict';
+type ConflictReason = 'overlap' | 'over-capacity' | 'outside-availability';
+type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+interface Resource {
+    id: string;
+    name: string;
+    /** Optional accent colour rendered alongside the resource label. */
+    color?: string;
+    /**
+     * Maximum number of simultaneous assignments tolerated on this resource
+     * within the same scale-step. `undefined` ≡ no concurrency limit
+     * (overlaps still count as `overlap` conflicts but never as
+     * `over-capacity`). When set, every slot whose concurrent count exceeds
+     * `capacityPerSlot` produces an `over-capacity` conflict containing
+     * exactly the assignments that touch that slot.
+     */
+    capacityPerSlot?: number;
+    /** Free-form metadata. The engine ignores this and round-trips it as-is. */
+    meta?: unknown;
+}
+/**
+ * A single booking on the timeline.
+ *
+ * `start` / `end` are stored as epoch milliseconds. `start` is inclusive,
+ * `end` is exclusive — same convention as `GanttTask` and the JS `Date`
+ * arithmetic the engine uses internally.
+ */
+interface Assignment {
+    id: string;
+    resourceId: string;
+    start: number;
+    end: number;
+    title: string;
+    /**
+     * `'conflict'` is set automatically by the engine after every mutation
+     * for assignments that participate in at least one detected conflict;
+     * consumers may pass `'tentative'` / `'confirmed'` to label the
+     * underlying intent, those values are preserved and only escalated to
+     * `'conflict'` when a conflict actually exists.
+     */
+    status?: AssignmentStatus;
+    meta?: unknown;
+}
+interface Conflict {
+    id: string;
+    /** Assignments involved, sorted ascending by id for stable equality. */
+    assignmentIds: string[];
+    reason: ConflictReason;
+}
+/**
+ * Availability rule.
+ *
+ * v0 keeps the rule shape minimal — `dayOfWeek` plus an `HH:MM` window.
+ * One rule = one window. Multiple windows on the same day = multiple
+ * rules. A resource with NO rules is considered always available.
+ *
+ * TODO(round-10): exception dates (`exception: { date, kind }`) for
+ * one-off blackouts / additions are explicitly out of scope for v0 — the
+ * spec calls them out but the use-cases (PTO calendars, holiday packs)
+ * are not finalised yet. Add them once a production consumer needs
+ * either kind so we don't bake the wrong shape in.
+ */
+interface AvailabilityRule {
+    resourceId: string;
+    /** 0 = Sunday … 6 = Saturday. Omitted ≡ rule applies every day. */
+    dayOfWeek?: DayOfWeek;
+    /** `HH:MM` (24h, UTC). Omitted ≡ open from 00:00. */
+    from?: string;
+    /** `HH:MM` (24h, UTC). Omitted ≡ open until 24:00. */
+    to?: string;
+}
+interface CalendarState {
+    resources: Resource[];
+    assignments: Assignment[];
+    conflicts: Conflict[];
+}
+interface DetectConflictsOptions {
+    scale?: CalendarScale;
+    rules?: readonly AvailabilityRule[];
+}
+interface CalendarEngineOptions {
+    /** Optional debug name appended to the generated engine id. */
+    name?: string;
+    /** Default scale used for capacity slot computation. @default 'day' */
+    scale?: CalendarScale;
+    /** Initial availability rules. Can be replaced via `setRules` later. */
+    rules?: readonly AvailabilityRule[];
+}
+interface CalendarEngine {
+    /** Stable engine id. Used as the suffix on the `$calendar.<id>.*` paths. */
+    readonly id: string;
+    addResource(resource: Resource): void;
+    removeResource(id: string): void;
+    updateResource(id: string, patch: Partial<Resource>): void;
+    getResource(id: string): Resource | undefined;
+    getResources(): Resource[];
+    addAssignment(assignment: Assignment): void;
+    updateAssignment(id: string, patch: Partial<Assignment>): void;
+    removeAssignment(id: string): void;
+    /** Shifts both `start` and `end` by `deltaMs`. */
+    moveAssignment(id: string, deltaMs: number): void;
+    /**
+     * Resizes one side. `'end'` shifts only the end timestamp;
+     * `'start'` shifts only the start. The opposite side stays put.
+     * The engine clamps the result so the assignment never inverts —
+     * minimum width is `1` ms (the React adapter additionally enforces
+     * a per-scale step in its drag handler).
+     */
+    resizeAssignment(id: string, side: 'start' | 'end', deltaMs: number): void;
+    getAssignment(id: string): Assignment | undefined;
+    getAssignments(): Assignment[];
+    setRules(rules: readonly AvailabilityRule[]): void;
+    getRules(): AvailabilityRule[];
+    /** Latest computed conflicts; refreshed automatically on mutations. */
+    getConflicts(): Conflict[];
+    setScale(scale: CalendarScale): void;
+    getScale(): CalendarScale;
+    getState(): CalendarState;
+    /** Subscribe to ANY engine mutation. Returns an unsubscribe fn. */
+    subscribe(cb: () => void): () => void;
+    /** Reset the engine — drops resources, assignments, rules, conflicts. */
+    clear(): void;
+}
+
+/**
+ * Resource Calendar engine — the sixth member of the
+ * form / table / tree / virtual / graph / **calendar** family.
+ *
+ * The in-memory maps are the source of truth and the public read API;
+ * snapshots are mirrored to the Core store under
+ * `$calendar.<id>.{resources,assignments,conflicts,view}` so other
+ * engines / external observers can react via `core.subscribe(...)`.
+ *
+ * v0 scope:
+ *   - addResource / removeResource / updateResource
+ *   - addAssignment / updateAssignment / removeAssignment
+ *   - moveAssignment(id, deltaMs) — shifts both ends together
+ *   - resizeAssignment(id, side, deltaMs) — clamps so width >= 1ms
+ *   - setRules / setScale — re-compute conflicts on change
+ *   - detectConflicts under the hood; status of involved assignments
+ *     is auto-promoted to `'conflict'` so the React adapter can render
+ *     without re-running the algorithm.
+ *
+ * NOT in v0 (deferred to round-10):
+ *   - exception dates on `AvailabilityRule`
+ *   - full per-engine undo/redo (use `core.snapshot/restore` instead)
+ *   - aggregate read APIs over a sub-range
+ */
+declare function createCalendar(core: Core, options?: CalendarEngineOptions): CalendarEngine;
+
+interface DetectConflictsArgs {
+    scale?: CalendarScale;
+    rules?: readonly AvailabilityRule[];
+}
+/**
+ * Find all conflicts in `state`.
+ *
+ * Algorithm — three independent passes, results de-duplicated by
+ * `(reason, sorted-ids)` so the same overlapping pair is never reported
+ * twice as `overlap`:
+ *
+ *   1. **overlap** (per resource): sort assignments by `start` and sweep.
+ *      Keep an active set ordered by `end` ASC; whenever a new
+ *      assignment opens, every still-active assignment forms a pairwise
+ *      `overlap` conflict with it. O(n log n + k) where k = total
+ *      overlapping pairs.
+ *
+ *   2. **over-capacity** (per resource with `capacityPerSlot`): bucket
+ *      every assignment into the slots it touches (1 slot = 1 scale
+ *      step). For each slot whose concurrent count exceeds capacity,
+ *      emit one `over-capacity` conflict naming exactly the assignments
+ *      that touch that slot. This is the simple counter approach (no
+ *      interval tree) — fine up to ~10⁵ assignments per resource.
+ *
+ *   3. **outside-availability**: per-assignment check via
+ *      `isAvailable`. Each violation becomes its own one-element
+ *      conflict.
+ */
+declare function detectConflicts(state: Pick<CalendarState, 'resources' | 'assignments'>, opts?: DetectConflictsArgs): Conflict[];
+
+/**
+ * `true` ⇔ the entire `[start, end)` interval falls inside at least one
+ * availability window for `resource`. A resource without any matching
+ * rule (or without any rules at all) is considered always available —
+ * unconfigured calendars stay friendly.
+ *
+ * Implementation: walk one UTC day at a time and check that the slice of
+ * `[start, end)` intersected with that day is fully covered by the union
+ * of windows attached to that day. The union is built by sorting rule
+ * windows by `from` and merging overlaps in O(k log k) where k = rules
+ * for that day (typically 1–3).
+ */
+declare function isAvailable(resource: Resource, range: {
+    start: number;
+    end: number;
+}, rules: readonly AvailabilityRule[]): boolean;
+
+export { type Assignment, type AssignmentStatus, type AvailabilityRule, type CalendarEngine, type CalendarEngineOptions, type CalendarScale, type CalendarState, type Conflict, type ConflictReason, type DayOfWeek, type DetectConflictsOptions, type Resource, createCalendar, detectConflicts, isAvailable };

package/dist/calendar.d.ts

@@ -0,0 +1,209 @@
+import { C as Core } from './types-B-rKQJ4R.js';
+
+/**
+ * Resource Calendar — engine domain types.
+ *
+ * The engine works with `number` (epoch ms) timestamps internally so the
+ * full state can round-trip through `core.snapshot()` / `core.restore()`
+ * without any custom (de)serialization. The React adapter accepts both
+ * `Date` and `number` on the public surface and normalizes on input.
+ */
+type CalendarScale = 'day' | 'week' | 'month';
+type AssignmentStatus = 'tentative' | 'confirmed' | 'conflict';
+type ConflictReason = 'overlap' | 'over-capacity' | 'outside-availability';
+type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+interface Resource {
+    id: string;
+    name: string;
+    /** Optional accent colour rendered alongside the resource label. */
+    color?: string;
+    /**
+     * Maximum number of simultaneous assignments tolerated on this resource
+     * within the same scale-step. `undefined` ≡ no concurrency limit
+     * (overlaps still count as `overlap` conflicts but never as
+     * `over-capacity`). When set, every slot whose concurrent count exceeds
+     * `capacityPerSlot` produces an `over-capacity` conflict containing
+     * exactly the assignments that touch that slot.
+     */
+    capacityPerSlot?: number;
+    /** Free-form metadata. The engine ignores this and round-trips it as-is. */
+    meta?: unknown;
+}
+/**
+ * A single booking on the timeline.
+ *
+ * `start` / `end` are stored as epoch milliseconds. `start` is inclusive,
+ * `end` is exclusive — same convention as `GanttTask` and the JS `Date`
+ * arithmetic the engine uses internally.
+ */
+interface Assignment {
+    id: string;
+    resourceId: string;
+    start: number;
+    end: number;
+    title: string;
+    /**
+     * `'conflict'` is set automatically by the engine after every mutation
+     * for assignments that participate in at least one detected conflict;
+     * consumers may pass `'tentative'` / `'confirmed'` to label the
+     * underlying intent, those values are preserved and only escalated to
+     * `'conflict'` when a conflict actually exists.
+     */
+    status?: AssignmentStatus;
+    meta?: unknown;
+}
+interface Conflict {
+    id: string;
+    /** Assignments involved, sorted ascending by id for stable equality. */
+    assignmentIds: string[];
+    reason: ConflictReason;
+}
+/**
+ * Availability rule.
+ *
+ * v0 keeps the rule shape minimal — `dayOfWeek` plus an `HH:MM` window.
+ * One rule = one window. Multiple windows on the same day = multiple
+ * rules. A resource with NO rules is considered always available.
+ *
+ * TODO(round-10): exception dates (`exception: { date, kind }`) for
+ * one-off blackouts / additions are explicitly out of scope for v0 — the
+ * spec calls them out but the use-cases (PTO calendars, holiday packs)
+ * are not finalised yet. Add them once a production consumer needs
+ * either kind so we don't bake the wrong shape in.
+ */
+interface AvailabilityRule {
+    resourceId: string;
+    /** 0 = Sunday … 6 = Saturday. Omitted ≡ rule applies every day. */
+    dayOfWeek?: DayOfWeek;
+    /** `HH:MM` (24h, UTC). Omitted ≡ open from 00:00. */
+    from?: string;
+    /** `HH:MM` (24h, UTC). Omitted ≡ open until 24:00. */
+    to?: string;
+}
+interface CalendarState {
+    resources: Resource[];
+    assignments: Assignment[];
+    conflicts: Conflict[];
+}
+interface DetectConflictsOptions {
+    scale?: CalendarScale;
+    rules?: readonly AvailabilityRule[];
+}
+interface CalendarEngineOptions {
+    /** Optional debug name appended to the generated engine id. */
+    name?: string;
+    /** Default scale used for capacity slot computation. @default 'day' */
+    scale?: CalendarScale;
+    /** Initial availability rules. Can be replaced via `setRules` later. */
+    rules?: readonly AvailabilityRule[];
+}
+interface CalendarEngine {
+    /** Stable engine id. Used as the suffix on the `$calendar.<id>.*` paths. */
+    readonly id: string;
+    addResource(resource: Resource): void;
+    removeResource(id: string): void;
+    updateResource(id: string, patch: Partial<Resource>): void;
+    getResource(id: string): Resource | undefined;
+    getResources(): Resource[];
+    addAssignment(assignment: Assignment): void;
+    updateAssignment(id: string, patch: Partial<Assignment>): void;
+    removeAssignment(id: string): void;
+    /** Shifts both `start` and `end` by `deltaMs`. */
+    moveAssignment(id: string, deltaMs: number): void;
+    /**
+     * Resizes one side. `'end'` shifts only the end timestamp;
+     * `'start'` shifts only the start. The opposite side stays put.
+     * The engine clamps the result so the assignment never inverts —
+     * minimum width is `1` ms (the React adapter additionally enforces
+     * a per-scale step in its drag handler).
+     */
+    resizeAssignment(id: string, side: 'start' | 'end', deltaMs: number): void;
+    getAssignment(id: string): Assignment | undefined;
+    getAssignments(): Assignment[];
+    setRules(rules: readonly AvailabilityRule[]): void;
+    getRules(): AvailabilityRule[];
+    /** Latest computed conflicts; refreshed automatically on mutations. */
+    getConflicts(): Conflict[];
+    setScale(scale: CalendarScale): void;
+    getScale(): CalendarScale;
+    getState(): CalendarState;
+    /** Subscribe to ANY engine mutation. Returns an unsubscribe fn. */
+    subscribe(cb: () => void): () => void;
+    /** Reset the engine — drops resources, assignments, rules, conflicts. */
+    clear(): void;
+}
+
+/**
+ * Resource Calendar engine — the sixth member of the
+ * form / table / tree / virtual / graph / **calendar** family.
+ *
+ * The in-memory maps are the source of truth and the public read API;
+ * snapshots are mirrored to the Core store under
+ * `$calendar.<id>.{resources,assignments,conflicts,view}` so other
+ * engines / external observers can react via `core.subscribe(...)`.
+ *
+ * v0 scope:
+ *   - addResource / removeResource / updateResource
+ *   - addAssignment / updateAssignment / removeAssignment
+ *   - moveAssignment(id, deltaMs) — shifts both ends together
+ *   - resizeAssignment(id, side, deltaMs) — clamps so width >= 1ms
+ *   - setRules / setScale — re-compute conflicts on change
+ *   - detectConflicts under the hood; status of involved assignments
+ *     is auto-promoted to `'conflict'` so the React adapter can render
+ *     without re-running the algorithm.
+ *
+ * NOT in v0 (deferred to round-10):
+ *   - exception dates on `AvailabilityRule`
+ *   - full per-engine undo/redo (use `core.snapshot/restore` instead)
+ *   - aggregate read APIs over a sub-range
+ */
+declare function createCalendar(core: Core, options?: CalendarEngineOptions): CalendarEngine;
+
+interface DetectConflictsArgs {
+    scale?: CalendarScale;
+    rules?: readonly AvailabilityRule[];
+}
+/**
+ * Find all conflicts in `state`.
+ *
+ * Algorithm — three independent passes, results de-duplicated by
+ * `(reason, sorted-ids)` so the same overlapping pair is never reported
+ * twice as `overlap`:
+ *
+ *   1. **overlap** (per resource): sort assignments by `start` and sweep.
+ *      Keep an active set ordered by `end` ASC; whenever a new
+ *      assignment opens, every still-active assignment forms a pairwise
+ *      `overlap` conflict with it. O(n log n + k) where k = total
+ *      overlapping pairs.
+ *
+ *   2. **over-capacity** (per resource with `capacityPerSlot`): bucket
+ *      every assignment into the slots it touches (1 slot = 1 scale
+ *      step). For each slot whose concurrent count exceeds capacity,
+ *      emit one `over-capacity` conflict naming exactly the assignments
+ *      that touch that slot. This is the simple counter approach (no
+ *      interval tree) — fine up to ~10⁵ assignments per resource.
+ *
+ *   3. **outside-availability**: per-assignment check via
+ *      `isAvailable`. Each violation becomes its own one-element
+ *      conflict.
+ */
+declare function detectConflicts(state: Pick<CalendarState, 'resources' | 'assignments'>, opts?: DetectConflictsArgs): Conflict[];
+
+/**
+ * `true` ⇔ the entire `[start, end)` interval falls inside at least one
+ * availability window for `resource`. A resource without any matching
+ * rule (or without any rules at all) is considered always available —
+ * unconfigured calendars stay friendly.
+ *
+ * Implementation: walk one UTC day at a time and check that the slice of
+ * `[start, end)` intersected with that day is fully covered by the union
+ * of windows attached to that day. The union is built by sorting rule
+ * windows by `from` and merging overlaps in O(k log k) where k = rules
+ * for that day (typically 1–3).
+ */
+declare function isAvailable(resource: Resource, range: {
+    start: number;
+    end: number;
+}, rules: readonly AvailabilityRule[]): boolean;
+
+export { type Assignment, type AssignmentStatus, type AvailabilityRule, type CalendarEngine, type CalendarEngineOptions, type CalendarScale, type CalendarState, type Conflict, type ConflictReason, type DayOfWeek, type DetectConflictsOptions, type Resource, createCalendar, detectConflicts, isAvailable };

package/dist/calendar.js

@@ -0,0 +1,12 @@
+import {
+  createCalendar,
+  detectConflicts,
+  isAvailable
+} from "./chunk-AB3RLBLW.js";
+import "./chunk-5CCD5Q4B.js";
+export {
+  createCalendar,
+  detectConflicts,
+  isAvailable
+};
+//# sourceMappingURL=calendar.js.map

package/dist/calendar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-5CCD5Q4B.js

@@ -0,0 +1,36 @@
+// src/engines/namespaces.ts
+var reserved = /* @__PURE__ */ new Map();
+function reservePrefix(engine, prefix) {
+  if (!prefix.startsWith("$") || !prefix.endsWith(".")) {
+    throw new Error(
+      `[skygraph] engine "${engine}" tried to reserve invalid prefix "${prefix}". Engine prefixes must start with "$" and end with ".".`
+    );
+  }
+  const existing = reserved.get(prefix);
+  if (existing !== void 0 && existing !== engine) {
+    throw new Error(
+      `[skygraph] prefix "${prefix}" is already owned by engine "${existing}", cannot reserve it for "${engine}". Pick a different prefix or update the registry.`
+    );
+  }
+  reserved.set(prefix, engine);
+  return prefix;
+}
+function listReservedPrefixes() {
+  return new Map(reserved);
+}
+var FORM_META_PREFIX = reservePrefix("form", "$meta.");
+var TABLE_PREFIX = reservePrefix("table", "$table.");
+var TREE_PREFIX = reservePrefix("tree", "$tree.");
+var GRAPH_PREFIX = reservePrefix("graph", "$graph.");
+var CALENDAR_PREFIX = reservePrefix("calendar", "$calendar.");
+
+export {
+  reservePrefix,
+  listReservedPrefixes,
+  FORM_META_PREFIX,
+  TABLE_PREFIX,
+  TREE_PREFIX,
+  GRAPH_PREFIX,
+  CALENDAR_PREFIX
+};
+//# sourceMappingURL=chunk-5CCD5Q4B.js.map

package/dist/chunk-5CCD5Q4B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engines/namespaces.ts"],"sourcesContent":["/**\n * Engine path namespace registry\n *\n * Every engine that stores state in the Core store under a `$`-prefixed\n * namespace MUST register its prefix here. This prevents two engines from\n * silently colliding on the same root path (e.g. two engines both writing\n * under `$meta.`).\n *\n * Rules:\n *   1. Prefixes MUST start with `$` and end with `.`.\n *   2. Prefixes MUST be unique across all engines.\n *   3. An engine MUST use `reservedPrefix(name)` at module load so\n *      collisions surface at import time during dev/test.\n *   4. User data MUST NOT live under `$` prefixes — reserve them for engines.\n */\n\nconst reserved = new Map<string, string>()\n\n/**\n * Reserve (or look up) a prefix for an engine. Throws synchronously if the\n * same prefix is already owned by a different engine.\n */\nexport function reservePrefix(engine: string, prefix: string): string {\n  if (!prefix.startsWith('$') || !prefix.endsWith('.')) {\n    throw new Error(\n      `[skygraph] engine \"${engine}\" tried to reserve invalid prefix \"${prefix}\". ` +\n        `Engine prefixes must start with \"$\" and end with \".\".`,\n    )\n  }\n\n  const existing = reserved.get(prefix)\n  if (existing !== undefined && existing !== engine) {\n    throw new Error(\n      `[skygraph] prefix \"${prefix}\" is already owned by engine \"${existing}\", ` +\n        `cannot reserve it for \"${engine}\". ` +\n        `Pick a different prefix or update the registry.`,\n    )\n  }\n\n  reserved.set(prefix, engine)\n  return prefix\n}\n\n/** Snapshot of registered engine prefixes (debug / introspection). */\nexport function listReservedPrefixes(): ReadonlyMap<string, string> {\n  return new Map(reserved)\n}\n\n/** Test-only helper. DO NOT call from engine code. */\nexport function __resetPrefixes(): void {\n  reserved.clear()\n}\n\n// ── Canonical in-tree reservations ─────────────────────────────────────────\n//\n// Listed here so they are reserved even if the engine module is not loaded.\n// New engines must add their entry here and reference it from their\n// implementation via `reservePrefix(...)`.\n\nexport const FORM_META_PREFIX = reservePrefix('form', '$meta.')\nexport const TABLE_PREFIX = reservePrefix('table', '$table.')\nexport const TREE_PREFIX = reservePrefix('tree', '$tree.')\nexport const GRAPH_PREFIX = reservePrefix('graph', '$graph.')\nexport const CALENDAR_PREFIX = reservePrefix('calendar', '$calendar.')\n"],"mappings":";AAgBA,IAAM,WAAW,oBAAI,IAAoB;AAMlC,SAAS,cAAc,QAAgB,QAAwB;AACpE,MAAI,CAAC,OAAO,WAAW,GAAG,KAAK,CAAC,OAAO,SAAS,GAAG,GAAG;AACpD,UAAM,IAAI;AAAA,MACR,sBAAsB,MAAM,sCAAsC,MAAM;AAAA,IAE1E;AAAA,EACF;AAEA,QAAM,WAAW,SAAS,IAAI,MAAM;AACpC,MAAI,aAAa,UAAa,aAAa,QAAQ;AACjD,UAAM,IAAI;AAAA,MACR,sBAAsB,MAAM,iCAAiC,QAAQ,6BACzC,MAAM;AAAA,IAEpC;AAAA,EACF;AAEA,WAAS,IAAI,QAAQ,MAAM;AAC3B,SAAO;AACT;AAGO,SAAS,uBAAoD;AAClE,SAAO,IAAI,IAAI,QAAQ;AACzB;AAaO,IAAM,mBAAmB,cAAc,QAAQ,QAAQ;AACvD,IAAM,eAAe,cAAc,SAAS,SAAS;AACrD,IAAM,cAAc,cAAc,QAAQ,QAAQ;AAClD,IAAM,eAAe,cAAc,SAAS,SAAS;AACrD,IAAM,kBAAkB,cAAc,YAAY,YAAY;","names":[]}