chuvsu-js 5.1.1 → 5.2.0

package/README.md

@@ -181,7 +181,11 @@ const client = new TimetableClient({
 
 `TimetableRepositoryAdapter` можно реализовать поверх БД, KV-хранилища или
 файлового сервиса. Запись использует ревизии compare-and-set, чтобы параллельные
-процессы не перезаписывали установленные ID.
+процессы не перезаписывали установленные ID. Для БД реализуйте
+`compareAndSetPatch`: обычное обновление передает только измененные сущности и
+полные замены затронутых источников. `compareAndSet` с полным снимком оставлен
+как совместимый fallback; его не следует использовать на горячем пути большого
+репозитория.
 
 ```ts
 const snapshot = await client.exportRepository();

package/dist/tt/client.js

@@ -122,10 +122,23 @@ export class TimetableClient {
         await this.ensureRepository();
         for (let attempt = 0; attempt < 4; attempt++) {
             const expectedRevision = this._repository.revision;
-            const result = mutate(this._repository);
+            const mutation = this._repository.capturePatch(() => mutate(this._repository));
+            const result = mutation.result;
+            if (!mutation.patch)
+                return result;
             if (!this.repositoryAdapter)
                 return result;
-            if (await this.repositoryAdapter.compareAndSet(expectedRevision, this._repository.export())) {
+            let saved;
+            if (this.repositoryAdapter.compareAndSetPatch) {
+                saved = await this.repositoryAdapter.compareAndSetPatch(expectedRevision, mutation.patch);
+            }
+            else if (this.repositoryAdapter.compareAndSet) {
+                saved = await this.repositoryAdapter.compareAndSet(expectedRevision, this._repository.export());
+            }
+            else {
+                throw new Error("Timetable repository adapter cannot persist changes");
+            }
+            if (saved) {
                 return result;
             }
             const latest = await this.repositoryAdapter.load();
@@ -363,17 +376,18 @@ export class TimetableClient {
             period,
             days: await this.fetchOwnerSchedule(resolvedOwner, period, context.academicYearStartYear),
         })));
-        for (const result of results) {
-            const currentOwner = this.resolveOwner(resolvedOwner);
-            const snapshot = createScheduleSourceSnapshot({
-                sourceKey: this.sourceKey(currentOwner, result.period, context.academicYearStartYear),
-                owner: currentOwner,
-                academicYearStartYear: context.academicYearStartYear,
-                period: result.period,
-                days: result.days,
-            });
-            await this.mutateRepository((repository) => repository.ingest(snapshot));
-        }
+        await this.mutateRepository((repository) => {
+            for (const result of results) {
+                const currentOwner = this.resolveOwner(resolvedOwner);
+                repository.ingest(createScheduleSourceSnapshot({
+                    sourceKey: this.sourceKey(currentOwner, result.period, context.academicYearStartYear),
+                    owner: currentOwner,
+                    academicYearStartYear: context.academicYearStartYear,
+                    period: result.period,
+                    days: result.days,
+                }));
+            }
+        });
         return new Schedule(this._repository, this.resolveOwner(resolvedOwner), context.academicYearStartYear, { period: periods.length === 1 ? periods[0] : context.period });
     }
     async getGroupSchedule(groupId, options) {

package/dist/tt/domain/directory.d.ts

@@ -1,8 +1,8 @@
 import type { GroupRef, RoomRef, TeacherRef, TimetableDirectorySnapshot } from "./types.js";
 export declare class TimetableDirectory {
-    private groups;
-    private teachers;
-    private rooms;
+    private readonly groups;
+    private readonly teachers;
+    private readonly rooms;
     constructor(snapshot?: TimetableDirectorySnapshot);
     rememberGroups(values: GroupRef[]): boolean;
     rememberTeachers(values: TeacherRef[]): boolean;

package/dist/tt/domain/directory.js

@@ -1,4 +1,4 @@
-import { mergeEntityRefs, normalizeScheduleText, } from "./normalize.js";
+import { entityKey, mergeEntityRefs, normalizeScheduleText, } from "./normalize.js";
 function personKey(name) {
     const words = normalizeScheduleText(name)
         .replace(/[.,]/gu, " ")
@@ -11,106 +11,167 @@ function personKey(name) {
         .join("");
     return `${surname}|${initials}`;
 }
-function exactKey(name) {
-    return normalizeScheduleText(name);
-}
 function validateRefs(values, label) {
     for (const value of values) {
         if (!value.name.trim())
             throw new TypeError(`${label} name is empty`);
-        if (value.id != null &&
-            (!Number.isInteger(value.id) || value.id < 1)) {
+        if (value.id != null && (!Number.isInteger(value.id) || value.id < 1)) {
             throw new RangeError(`${label} ID must be a positive integer`);
         }
     }
 }
-function mergeByIdAndName(current, incoming) {
-    const values = mergeEntityRefs([...current, ...incoming]);
-    const before = JSON.stringify(current);
-    const after = JSON.stringify(values);
-    return { values, changed: before !== after };
-}
-function mergeTeachersByIdentity(current, incoming) {
-    const merged = mergeEntityRefs([...current, ...incoming]);
-    const identified = merged.filter((value) => value.id != null);
-    const unresolved = [];
-    for (const alias of merged.filter((value) => value.id == null)) {
-        const matches = identified
-            .map((value, index) => ({ value, index }))
-            .filter(({ value }) => personKey(value.name) === personKey(alias.name));
-        const ids = new Set(matches.map(({ value }) => value.id));
-        if (ids.size === 1) {
-            const match = matches[0];
-            identified[match.index] = { ...alias, ...match.value };
+class EntityIndex {
+    teacherIdentity;
+    records = new Set();
+    byId = new Map();
+    byName = new Map();
+    byPerson = new Map();
+    constructor(values, teacherIdentity = false) {
+        this.teacherIdentity = teacherIdentity;
+        for (const value of values)
+            this.rememberOne(structuredClone(value));
+    }
+    remember(values) {
+        let changed = false;
+        for (const value of values) {
+            if (this.rememberOne(structuredClone(value)))
+                changed = true;
+        }
+        return changed;
+    }
+    resolve(value) {
+        const exact = value.id == null
+            ? this.byName.get(normalizeScheduleText(value.name))
+            : this.byId.get(value.id);
+        if (exact)
+            return mergeEntityRefs([value, exact.value])[0];
+        if (!this.teacherIdentity)
+            return structuredClone(value);
+        const candidates = this.byPerson.get(personKey(value.name)) ?? new Set();
+        const identified = [...candidates].filter((candidate) => candidate.value.id != null);
+        const ids = new Set(identified.map((candidate) => candidate.value.id));
+        return ids.size === 1
+            ? mergeEntityRefs([value, identified[0].value])[0]
+            : structuredClone(value);
+    }
+    export() {
+        return [...this.records]
+            .map((record) => structuredClone(record.value))
+            .sort((a, b) => entityKey(a).localeCompare(entityKey(b)));
+    }
+    rememberOne(value) {
+        const name = normalizeScheduleText(value.name);
+        const person = this.teacherIdentity ? personKey(value.name) : "";
+        let record = value.id == null ? undefined : this.byId.get(value.id);
+        record ??= this.byName.get(name);
+        if (!record && this.teacherIdentity) {
+            const identified = [...(this.byPerson.get(person) ?? [])]
+                .filter((candidate) => candidate.value.id != null);
+            const ids = new Set(identified.map((candidate) => candidate.value.id));
+            if (ids.size === 1)
+                record = identified[0];
         }
-        else {
-            unresolved.push(alias);
+        if (!record) {
+            record = { value, ids: new Set(), names: new Set(), people: new Set() };
+            this.records.add(record);
+            this.index(record, value);
+            if (this.teacherIdentity && value.id != null)
+                this.mergeTeacherAliases(record, person);
+            return true;
         }
+        const before = JSON.stringify(record.value);
+        record.value = mergeEntityRefs([record.value, value])[0];
+        this.index(record, value);
+        this.index(record, record.value);
+        if (this.teacherIdentity && record.value.id != null)
+            this.mergeTeacherAliases(record, person);
+        return before !== JSON.stringify(record.value);
+    }
+    index(record, value) {
+        if (value.id != null) {
+            record.ids.add(value.id);
+            this.byId.set(value.id, record);
+        }
+        const name = normalizeScheduleText(value.name);
+        if (name) {
+            record.names.add(name);
+            this.byName.set(name, record);
+        }
+        if (this.teacherIdentity) {
+            const person = personKey(value.name);
+            record.people.add(person);
+            let records = this.byPerson.get(person);
+            if (!records) {
+                records = new Set();
+                this.byPerson.set(person, records);
+            }
+            records.add(record);
+        }
+    }
+    mergeTeacherAliases(target, person) {
+        const aliases = [...(this.byPerson.get(person) ?? [])]
+            .filter((candidate) => candidate !== target && candidate.value.id == null);
+        for (const alias of aliases)
+            this.mergeRecords(target, alias);
+    }
+    mergeRecords(target, source) {
+        target.value = mergeEntityRefs([source.value, target.value])[0];
+        for (const id of source.ids) {
+            target.ids.add(id);
+            this.byId.set(id, target);
+        }
+        for (const name of source.names) {
+            target.names.add(name);
+            this.byName.set(name, target);
+        }
+        for (const person of source.people) {
+            target.people.add(person);
+            const records = this.byPerson.get(person);
+            records?.delete(source);
+            records?.add(target);
+        }
+        this.records.delete(source);
     }
-    const values = mergeEntityRefs([...identified, ...unresolved]);
-    return {
-        values,
-        changed: JSON.stringify(current) !== JSON.stringify(values),
-    };
-}
-function resolveUnique(value, known, key) {
-    if (value.id != null) {
-        const byId = known.find((candidate) => candidate.id === value.id);
-        return byId ? mergeEntityRefs([value, byId])[0] : value;
-    }
-    const lookup = key(value.name);
-    const candidates = known.filter((candidate) => candidate.id != null && key(candidate.name) === lookup);
-    const ids = new Set(candidates.map((candidate) => candidate.id));
-    if (ids.size !== 1)
-        return value;
-    return mergeEntityRefs([value, candidates[0]])[0];
 }
 export class TimetableDirectory {
-    groups = [];
-    teachers = [];
-    rooms = [];
+    groups;
+    teachers;
+    rooms;
     constructor(snapshot) {
-        if (snapshot) {
-            validateRefs(snapshot.groups, "Group");
-            validateRefs(snapshot.teachers, "Teacher");
-            validateRefs(snapshot.rooms, "Room");
-            this.groups = mergeEntityRefs(structuredClone(snapshot.groups));
-            this.teachers = mergeTeachersByIdentity([], structuredClone(snapshot.teachers)).values;
-            this.rooms = mergeEntityRefs(structuredClone(snapshot.rooms));
-        }
+        const initial = snapshot ?? { groups: [], teachers: [], rooms: [] };
+        validateRefs(initial.groups, "Group");
+        validateRefs(initial.teachers, "Teacher");
+        validateRefs(initial.rooms, "Room");
+        this.groups = new EntityIndex(initial.groups);
+        this.teachers = new EntityIndex(initial.teachers, true);
+        this.rooms = new EntityIndex(initial.rooms);
     }
     rememberGroups(values) {
         validateRefs(values, "Group");
-        const result = mergeByIdAndName(this.groups, values);
-        this.groups = result.values;
-        return result.changed;
+        return this.groups.remember(values);
     }
     rememberTeachers(values) {
         validateRefs(values, "Teacher");
-        const result = mergeTeachersByIdentity(this.teachers, values);
-        this.teachers = result.values;
-        return result.changed;
+        return this.teachers.remember(values);
     }
     rememberRooms(values) {
         validateRefs(values, "Room");
-        const result = mergeByIdAndName(this.rooms, values);
-        this.rooms = result.values;
-        return result.changed;
+        return this.rooms.remember(values);
     }
     resolveGroup(value) {
-        return resolveUnique(value, this.groups, exactKey);
+        return this.groups.resolve(value);
     }
     resolveTeacher(value) {
-        return resolveUnique(value, this.teachers, personKey);
+        return this.teachers.resolve(value);
     }
     resolveRoom(value) {
-        return resolveUnique(value, this.rooms, exactKey);
+        return this.rooms.resolve(value);
     }
     export() {
         return {
-            groups: structuredClone(this.groups),
-            teachers: structuredClone(this.teachers),
-            rooms: structuredClone(this.rooms),
+            groups: this.groups.export(),
+            teachers: this.teachers.export(),
+            rooms: this.rooms.export(),
         };
     }
 }

package/dist/tt/domain/index.d.ts

@@ -6,4 +6,4 @@ export { Schedule } from "./schedule.js";
 export { MaterializedSchedule, materializeSchedule, materializeScheduleSnapshot, } from "./materialized-schedule.js";
 export type { ScheduleQueryOptions, ScheduleOptions, ScheduleWeekdayOptions, } from "./schedule.js";
 export type { MaterializeScheduleOptions, MaterializedScheduleSnapshot, SerializedLessonOccurrence, SerializedLessonSourceRef, } from "./materialized-schedule.js";
-export type { GroupAttendance, GroupRef, IngestResult, LessonId, LessonIdGenerator, LessonOccurrence, LessonRecurrence, LessonSeries, LessonSeriesId, RelationCompleteness, RelationSet, LessonSourceRef, LessonStatus, LessonSubstitution, LessonTransfer, NamedEntityRef, OccurrenceObservation, RoomRef, ScheduleObservation, ScheduleOwner, ScheduleSourceSnapshot, SeriesObservation, TeacherRef, TimetableDirectorySnapshot, TimetableRepositoryAdapter, TimetableRepositorySnapshot, } from "./types.js";
+export type { GroupAttendance, GroupRef, IngestResult, LessonId, LessonIdGenerator, LessonOccurrence, LessonRecurrence, LessonSeries, LessonSeriesId, RelationCompleteness, RelationSet, LessonSourceRef, LessonStatus, LessonSubstitution, LessonTransfer, NamedEntityRef, OccurrenceObservation, RoomRef, ScheduleObservation, ScheduleOwner, ScheduleSourceSnapshot, SeriesObservation, TeacherRef, TimetableDirectorySnapshot, TimetableRepositoryAdapter, TimetableRepositoryPatch, TimetableRepositorySnapshot, } from "./types.js";

package/dist/tt/domain/repository.d.ts

@@ -1,6 +1,6 @@
 import type { AcademicPeriod } from "../../common/types.js";
 import { TimetableDirectory } from "./directory.js";
-import type { IngestResult, LessonIdGenerator, LessonOccurrence, LessonSeries, ScheduleOwner, ScheduleSourceSnapshot, TimetableRepositoryAdapter, TimetableRepositorySnapshot } from "./types.js";
+import type { IngestResult, LessonIdGenerator, LessonOccurrence, LessonSeries, ScheduleOwner, ScheduleSourceSnapshot, TimetableRepositoryAdapter, TimetableRepositoryPatch, TimetableRepositorySnapshot } from "./types.js";
 export declare class TimetableRepository {
     private readonly idGenerator;
     private _directory;
@@ -8,6 +8,9 @@ export declare class TimetableRepository {
     private readonly links;
     private readonly seriesRecords;
     private readonly occurrenceRecords;
+    private readonly recordIdsByBucket;
+    private readonly recordIdsByOwner;
+    private patchTracker;
     private _revision;
     constructor(opts?: {
         idGenerator?: LessonIdGenerator;
@@ -18,6 +21,10 @@ export declare class TimetableRepository {
     rememberGroups(values: Parameters<TimetableDirectory["rememberGroups"]>[0]): void;
     rememberTeachers(values: Parameters<TimetableDirectory["rememberTeachers"]>[0]): void;
     rememberRooms(values: Parameters<TimetableDirectory["rememberRooms"]>[0]): void;
+    capturePatch<T>(mutate: () => T): {
+        result: T;
+        patch: TimetableRepositoryPatch | null;
+    };
     ingest(snapshot: ScheduleSourceSnapshot): IngestResult;
     getSeries(opts?: {
         owner?: ScheduleOwner;
@@ -30,15 +37,23 @@ export declare class TimetableRepository {
         periods?: readonly AcademicPeriod[];
     }): LessonOccurrence[];
     export(): TimetableRepositorySnapshot;
+    private buildPatch;
     replaceSnapshot(snapshot: TimetableRepositorySnapshot): void;
     private restore;
     private validateSource;
     private rememberSourceEntities;
-    private pruneEmptyRecords;
     private removeClaim;
     private addClaim;
     private findPriorTarget;
     private findCanonicalTarget;
+    private addRecordToBucket;
+    private ownerReferenceKeys;
+    private claimOwnerKeys;
+    private addClaimOwnerKeys;
+    private removeRecordOwnerIndex;
+    private rebuildRecordOwnerIndex;
+    private removeRecordIndexes;
+    private recordsForOwner;
     private aggregateSubstitutions;
     private aggregateSeries;
     private aggregateOccurrence;

package/dist/tt/domain/repository.js

@@ -1,13 +1,19 @@
 import { isLocalDate } from "../utils/date.js";
 import { TimetableDirectory } from "./directory.js";
 import { RandomLessonIdGenerator } from "./ids.js";
-import { entityKey, mergeGroups, mergeRooms, mergeTeachers, normalizeScheduleText, } from "./normalize.js";
+import { entityKey, mergeEntityRefs, mergeGroups, mergeRooms, mergeTeachers, normalizeScheduleText, } from "./normalize.js";
 function claimKey(sourceKey, observationKey) {
     return `${sourceKey}\u0000${observationKey}`;
 }
 function sourceObservationKey(sourceKey, observationKey) {
     return claimKey(sourceKey, observationKey);
 }
+function canonicalBucketKey(observation, source) {
+    const prefix = `${source.academicYearStartYear}:${source.period}:${observation.kind}:${normalizeScheduleText(observation.subject)}`;
+    return observation.kind === "series"
+        ? `${prefix}:${observation.recurrence.weekday}:${recurrenceWeeks(observation)}`
+        : `${prefix}:${observation.date}`;
+}
 function sameDate(a, b) {
     return a === b;
 }
@@ -144,6 +150,13 @@ function deserializeSource(source) {
         observations: source.observations.map(deserializeObservation),
     };
 }
+function sameSourceContent(left, right) {
+    return left.sourceKey === right.sourceKey &&
+        left.academicYearStartYear === right.academicYearStartYear &&
+        left.period === right.period &&
+        JSON.stringify(left.owner) === JSON.stringify(right.owner) &&
+        JSON.stringify(left.observations) === JSON.stringify(right.observations);
+}
 function sourceRef(claim) {
     return {
         sourceKey: claim.source.sourceKey,
@@ -267,6 +280,9 @@ export class TimetableRepository {
     links = new Map();
     seriesRecords = new Map();
     occurrenceRecords = new Map();
+    recordIdsByBucket = new Map();
+    recordIdsByOwner = new Map();
+    patchTracker = null;
     _revision = 0;
     constructor(opts) {
         this.idGenerator = opts?.idGenerator ?? new RandomLessonIdGenerator();
@@ -281,22 +297,63 @@ export class TimetableRepository {
         return this._revision;
     }
     rememberGroups(values) {
-        if (this.directory.rememberGroups(values))
+        if (this.directory.rememberGroups(values)) {
+            this.patchTracker?.groups.push(...structuredClone(values));
             this._revision++;
+        }
     }
     rememberTeachers(values) {
-        if (this.directory.rememberTeachers(values))
+        if (this.directory.rememberTeachers(values)) {
+            this.patchTracker?.teachers.push(...structuredClone(values));
             this._revision++;
+        }
     }
     rememberRooms(values) {
-        if (this.directory.rememberRooms(values))
+        if (this.directory.rememberRooms(values)) {
+            this.patchTracker?.rooms.push(...structuredClone(values));
             this._revision++;
+        }
+    }
+    capturePatch(mutate) {
+        if (this.patchTracker)
+            throw new Error("Nested timetable repository mutation");
+        const expectedRevision = this._revision;
+        const tracker = {
+            sourceKeys: new Set(),
+            groups: [],
+            teachers: [],
+            rooms: [],
+        };
+        this.patchTracker = tracker;
+        try {
+            const result = mutate();
+            return {
+                result,
+                patch: this._revision === expectedRevision ? null : this.buildPatch(tracker),
+            };
+        }
+        finally {
+            this.patchTracker = null;
+        }
     }
     ingest(snapshot) {
         const incoming = structuredClone(snapshot);
         this.validateSource(incoming);
-        this.rememberSourceEntities(incoming);
+        const directoryChanged = this.rememberSourceEntities(incoming);
         const prior = this.sources.get(incoming.sourceKey);
+        if (prior && sameSourceContent(prior, incoming)) {
+            const links = incoming.observations.map((observation) => this.links.get(sourceObservationKey(incoming.sourceKey, observation.key)));
+            if (directoryChanged)
+                this._revision++;
+            return {
+                revision: this._revision,
+                seriesIds: links.flatMap((link) => link?.kind === "series" ? [link.id] : []),
+                lessonIds: links.flatMap((link) => link?.kind === "occurrence" ? [link.id] : []),
+                created: 0,
+                updated: incoming.observations.length,
+                removedObservations: 0,
+            };
+        }
         const priorClaims = new Map();
         if (prior) {
             for (const observation of prior.observations) {
@@ -305,6 +362,7 @@ export class TimetableRepository {
             }
         }
         this.sources.set(incoming.sourceKey, incoming);
+        this.patchTracker?.sourceKeys.add(incoming.sourceKey);
         const usedTargets = new Set();
         const seriesIds = [];
         const lessonIds = [];
@@ -352,7 +410,6 @@ export class TimetableRepository {
                 }
             }
         }
-        this.pruneEmptyRecords();
         this._revision++;
         return {
             revision: this._revision,
@@ -365,7 +422,7 @@ export class TimetableRepository {
     }
     getSeries(opts) {
         const values = [];
-        for (const record of this.seriesRecords.values()) {
+        for (const record of this.recordsForOwner(this.seriesRecords, opts?.owner)) {
             if (record.claims.size === 0)
                 continue;
             const value = this.aggregateSeries(record);
@@ -387,7 +444,7 @@ export class TimetableRepository {
     }
     getDirectOccurrences(opts) {
         const values = [];
-        for (const record of this.occurrenceRecords.values()) {
+        for (const record of this.recordsForOwner(this.occurrenceRecords, opts?.owner)) {
             if (record.claims.size === 0)
                 continue;
             const value = this.aggregateOccurrence(record);
@@ -427,6 +484,32 @@ export class TimetableRepository {
                 a.observationKey.localeCompare(b.observationKey)),
         };
     }
+    buildPatch(tracker) {
+        return {
+            schemaVersion: 5,
+            revision: this._revision,
+            directoryUpserts: {
+                groups: mergeEntityRefs(tracker.groups),
+                teachers: mergeTeachers(tracker.teachers),
+                rooms: mergeRooms(tracker.rooms),
+            },
+            sourceReplacements: [...tracker.sourceKeys].sort().flatMap((sourceKey) => {
+                const source = this.sources.get(sourceKey);
+                if (!source)
+                    return [];
+                return [{
+                        source: serializeSource(source),
+                        links: source.observations.map((observation) => {
+                            const link = this.links.get(sourceObservationKey(sourceKey, observation.key));
+                            if (!link) {
+                                throw new Error(`Missing timetable link: ${sourceKey}/${observation.key}`);
+                            }
+                            return { observationKey: observation.key, ...link };
+                        }),
+                    }];
+            }),
+        };
+    }
     replaceSnapshot(snapshot) {
         this.restore(snapshot);
     }
@@ -450,6 +533,8 @@ export class TimetableRepository {
         this.links.clear();
         this.seriesRecords.clear();
         this.occurrenceRecords.clear();
+        this.recordIdsByBucket.clear();
+        this.recordIdsByOwner.clear();
         this._directory = new TimetableDirectory(snapshot.directory);
         this._revision = snapshot.revision;
         for (const source of sources) {
@@ -595,19 +680,16 @@ export class TimetableRepository {
                 rooms.push(...(substitution.rooms ?? []));
             }
         }
-        this.directory.rememberGroups(groups);
-        this.directory.rememberTeachers(teachers);
-        this.directory.rememberRooms(rooms);
-    }
-    pruneEmptyRecords() {
-        for (const [id, record] of this.seriesRecords) {
-            if (record.claims.size === 0)
-                this.seriesRecords.delete(id);
-        }
-        for (const [id, record] of this.occurrenceRecords) {
-            if (record.claims.size === 0)
-                this.occurrenceRecords.delete(id);
-        }
+        const groupsChanged = this.directory.rememberGroups(groups);
+        const teachersChanged = this.directory.rememberTeachers(teachers);
+        const roomsChanged = this.directory.rememberRooms(rooms);
+        if (groupsChanged)
+            this.patchTracker?.groups.push(...structuredClone(groups));
+        if (teachersChanged)
+            this.patchTracker?.teachers.push(...structuredClone(teachers));
+        if (roomsChanged)
+            this.patchTracker?.rooms.push(...structuredClone(rooms));
+        return groupsChanged || teachersChanged || roomsChanged;
     }
     removeClaim(sourceKey, observationKey) {
         const link = this.links.get(sourceObservationKey(sourceKey, observationKey));
@@ -616,25 +698,47 @@ export class TimetableRepository {
         const record = link.kind === "series"
             ? this.seriesRecords.get(link.id)
             : this.occurrenceRecords.get(link.id);
-        record?.claims.delete(claimKey(sourceKey, observationKey));
+        if (!record)
+            return;
+        record.claims.delete(claimKey(sourceKey, observationKey));
+        if (record.claims.size === 0) {
+            this.removeRecordIndexes(record);
+            if (link.kind === "series")
+                this.seriesRecords.delete(link.id);
+            else
+                this.occurrenceRecords.delete(link.id);
+            return;
+        }
+        this.rebuildRecordOwnerIndex(record);
     }
     addClaim(link, source, observation) {
         const key = claimKey(source.sourceKey, observation.key);
+        const bucketKey = canonicalBucketKey(observation, source);
         if (link.kind === "series" && observation.kind === "series") {
             let record = this.seriesRecords.get(link.id);
             if (!record) {
-                record = { id: link.id, claims: new Map() };
+                record = { id: link.id, claims: new Map(), bucketKey, ownerKeys: new Set() };
                 this.seriesRecords.set(link.id, record);
+                this.addRecordToBucket(record);
+            }
+            if (record.bucketKey !== bucketKey) {
+                throw new Error(`Incompatible timetable series link: ${link.id}`);
             }
             record.claims.set(key, { source, observation });
+            this.addClaimOwnerKeys(record, source, observation);
         }
         if (link.kind === "occurrence" && observation.kind === "occurrence") {
             let record = this.occurrenceRecords.get(link.id);
             if (!record) {
-                record = { id: link.id, claims: new Map() };
+                record = { id: link.id, claims: new Map(), bucketKey, ownerKeys: new Set() };
                 this.occurrenceRecords.set(link.id, record);
+                this.addRecordToBucket(record);
+            }
+            if (record.bucketKey !== bucketKey) {
+                throw new Error(`Incompatible timetable occurrence link: ${link.id}`);
             }
             record.claims.set(key, { source, observation });
+            this.addClaimOwnerKeys(record, source, observation);
         }
     }
     findPriorTarget(observation, prior, usedTargets) {
@@ -657,12 +761,18 @@ export class TimetableRepository {
         return best && best.score >= 55 && !tied ? best.link : undefined;
     }
     findCanonicalTarget(observation, source, usedTargets) {
-        const records = observation.kind === "series"
-            ? this.seriesRecords.values()
-            : this.occurrenceRecords.values();
+        const recordMap = observation.kind === "series"
+            ? this.seriesRecords
+            : this.occurrenceRecords;
+        const candidateIds = this.recordIdsByBucket.get(canonicalBucketKey(observation, source));
+        if (!candidateIds)
+            return undefined;
         let best;
         let second = Number.NEGATIVE_INFINITY;
-        for (const record of records) {
+        for (const id of candidateIds) {
+            const record = recordMap.get(id);
+            if (!record)
+                continue;
             if (usedTargets.has(record.id) || record.claims.size === 0)
                 continue;
             let recordScore = Number.NEGATIVE_INFINITY;
@@ -686,6 +796,102 @@ export class TimetableRepository {
             return undefined;
         return { kind: observation.kind, id: best.id };
     }
+    addRecordToBucket(record) {
+        let ids = this.recordIdsByBucket.get(record.bucketKey);
+        if (!ids) {
+            ids = new Set();
+            this.recordIdsByBucket.set(record.bucketKey, ids);
+        }
+        ids.add(record.id);
+    }
+    ownerReferenceKeys(kind, value) {
+        const resolved = kind === "group"
+            ? this.directory.resolveGroup(value)
+            : kind === "teacher"
+                ? this.directory.resolveTeacher(value)
+                : this.directory.resolveRoom(value);
+        const keys = new Set();
+        for (const reference of [value, resolved]) {
+            if (reference.id != null)
+                keys.add(`${kind}:id:${reference.id}`);
+            const name = normalizeScheduleText(reference.name);
+            if (name)
+                keys.add(`${kind}:name:${name}`);
+        }
+        return [...keys];
+    }
+    claimOwnerKeys(source, observation) {
+        const keys = new Set();
+        const add = (kind, value) => {
+            for (const key of this.ownerReferenceKeys(kind, value))
+                keys.add(key);
+        };
+        if (source.owner.type === "group")
+            add("group", source.owner.group);
+        if (source.owner.type === "teacher")
+            add("teacher", source.owner.teacher);
+        if (source.owner.type === "room")
+            add("room", source.owner.room);
+        for (const value of observation.groups.values)
+            add("group", value.group);
+        for (const value of observation.teachers.values)
+            add("teacher", value);
+        for (const value of observation.rooms.values)
+            add("room", value);
+        return keys;
+    }
+    addClaimOwnerKeys(record, source, observation) {
+        for (const key of this.claimOwnerKeys(source, observation)) {
+            record.ownerKeys.add(key);
+            let ids = this.recordIdsByOwner.get(key);
+            if (!ids) {
+                ids = new Set();
+                this.recordIdsByOwner.set(key, ids);
+            }
+            ids.add(record.id);
+        }
+    }
+    removeRecordOwnerIndex(record) {
+        for (const key of record.ownerKeys) {
+            const ids = this.recordIdsByOwner.get(key);
+            ids?.delete(record.id);
+            if (ids?.size === 0)
+                this.recordIdsByOwner.delete(key);
+        }
+        record.ownerKeys.clear();
+    }
+    rebuildRecordOwnerIndex(record) {
+        this.removeRecordOwnerIndex(record);
+        for (const claim of record.claims.values()) {
+            this.addClaimOwnerKeys(record, claim.source, claim.observation);
+        }
+    }
+    removeRecordIndexes(record) {
+        const bucketIds = this.recordIdsByBucket.get(record.bucketKey);
+        bucketIds?.delete(record.id);
+        if (bucketIds?.size === 0)
+            this.recordIdsByBucket.delete(record.bucketKey);
+        this.removeRecordOwnerIndex(record);
+    }
+    recordsForOwner(records, owner) {
+        if (!owner)
+            return records.values();
+        const kind = owner.type;
+        const reference = owner.type === "group"
+            ? owner.group
+            : owner.type === "teacher"
+                ? owner.teacher
+                : owner.room;
+        const ids = new Set();
+        for (const key of this.ownerReferenceKeys(kind, reference)) {
+            for (const id of this.recordIdsByOwner.get(key) ?? [])
+                ids.add(id);
+        }
+        return [...ids].flatMap((id) => {
+            const record = records.get(id);
+            return record ? [record] : [];
+        });
+    }
     aggregateSubstitutions(claims) {
         const byDate = new Map();
         for (const substitution of claims.flatMap((value) => value.observation.substitutions ?? [])) {

package/dist/tt/domain/types.d.ts

@@ -158,6 +158,21 @@ export interface TimetableRepositorySnapshot {
         id: string;
     }>;
 }
+export interface TimetableRepositoryPatch {
+    schemaVersion: 5;
+    revision: number;
+    /** Entity rows changed by this mutation. Merge them into persistent directory storage. */
+    directoryUpserts: TimetableDirectorySnapshot;
+    /** Complete replacements for touched sources. Untouched source rows stay unchanged. */
+    sourceReplacements: Array<{
+        source: SerializedScheduleSourceSnapshot;
+        links: Array<{
+            observationKey: string;
+            kind: "series" | "occurrence";
+            id: string;
+        }>;
+    }>;
+}
 export interface TimetableDirectorySnapshot {
     groups: GroupRef[];
     teachers: TeacherRef[];
@@ -165,7 +180,10 @@ export interface TimetableDirectorySnapshot {
 }
 export interface TimetableRepositoryAdapter {
     load(): Promise<TimetableRepositorySnapshot | null>;
-    compareAndSet(expectedRevision: number, snapshot: TimetableRepositorySnapshot): Promise<boolean>;
+    /** Legacy full-snapshot CAS fallback. Prefer compareAndSetPatch for persistent storage. */
+    compareAndSet?(expectedRevision: number, snapshot: TimetableRepositorySnapshot): Promise<boolean>;
+    /** Incremental CAS: persist only supplied entity upserts and source replacements. */
+    compareAndSetPatch?(expectedRevision: number, patch: TimetableRepositoryPatch): Promise<boolean>;
     clear?(): Promise<void>;
 }
 export interface LessonIdGenerator {

package/docs/v5-architecture.md

@@ -117,7 +117,11 @@ ID серии создается генератором и хранится в
 3. Производные представления запросов, инвалидируемые ревизией.
 
 Снимок репозитория имеет `schemaVersion: 5`. Адаптер постоянного хранилища
-использует compare-and-set по ревизии.
+использует compare-and-set по ревизии. Предпочтительный метод
+`compareAndSetPatch` атомарно применяет только измененные строки справочника и
+полностью заменяет затронутые источники со связями. Обычная мутация не экспортирует
+и не обходит весь репозиторий; полный снимок остается форматом загрузки, переноса и
+резервного копирования.
 
 ## Запросы
 

package/docs/v5-migration.md

@@ -281,6 +281,17 @@ const snapshot = await client.exportRepository();
 вместе со всеми когда-либо загруженными расписаниями, а восстановление требует
 повторной агрегации связей.
 
+Начиная с 5.2.0 поиск совпадающих занятий, справочник сущностей и удаление пустых
+канонических записей используют локальные индексы. Одинаковые повторные снимки не
+меняют ревизию. `compareAndSetPatch` получает только `directoryUpserts` и
+`sourceReplacements`, затронутые одной мутацией. Поэтому размер записи и обычное
+время обновления не растут вместе со всем репозиторием. Старый `compareAndSet`
+поддерживается как fallback, но сериализует полный снимок.
+
+`exportRepository()` по-прежнему имеет цену, пропорциональную размеру полного
+снимка. Используйте его для экспорта, резервной копии или миграции, не на пути
+каждого запроса.
+
 Для API, SSR и офлайн-кеша материализуйте только готовое расписание владельца:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chuvsu-js",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "description": "Библиотека для расписания и личного кабинета ЧГУ им. И. Н. Ульянова",
   "type": "module",
   "main": "dist/index.js",