@itphx/synth-storage-postgres 0.13.8 → 0.13.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -42,6 +42,12 @@ const SECTION_KEYS = [
42
42
  'plugins',
43
43
  'attachments',
44
44
  'sessionOpsPerMinute',
45
+ // ADR-135: runtime-каталог профилей исполнения (`execution`).
46
+ 'execution',
47
+ // PROP-132: runtime-выключатель терминалов (`terminal.enabled`).
48
+ 'terminal',
49
+ // Этап 1 roadmap 0.13 (блок 4): runtime-патч секции `background`.
50
+ 'background',
45
51
  ];
46
52
  const SECTION_KEY_SET = new Set(SECTION_KEYS);
47
53
  /** Собрать порт runtime-настроек поверх SQL. */
@@ -312,6 +318,18 @@ export function createPrincipalSettingsPort(conn) {
312
318
  async clearAttachments() {
313
319
  await deleteSetting(conn, 'attachments');
314
320
  },
321
+ // Этап 1 roadmap 0.13 (блок 4): runtime-патч секции `background`
322
+ // (реестр фоновых прогонов). Хранится тем же JSON-документом настроек —
323
+ // отдельной миграции не требуется.
324
+ async getBackground() {
325
+ return (await readSetting(conn, 'background')) ?? {};
326
+ },
327
+ async setBackground(config) {
328
+ await writeSetting(conn, 'background', config);
329
+ },
330
+ async clearBackground() {
331
+ await deleteSetting(conn, 'background');
332
+ },
315
333
  async getContextWindowPolicy() {
316
334
  return readSetting(conn, 'contextWindowPolicy');
317
335
  },
@@ -367,5 +385,27 @@ export function createPrincipalSettingsPort(conn) {
367
385
  async clearSshMode() {
368
386
  await deleteSetting(conn, 'sshMode');
369
387
  },
388
+ // ADR-135: runtime-каталог профилей исполнения (`execution`).
389
+ async getExecution() {
390
+ return readSetting(conn, 'execution');
391
+ },
392
+ async setExecution(execution) {
393
+ await writeSetting(conn, 'execution', execution);
394
+ },
395
+ async clearExecution() {
396
+ await deleteSetting(conn, 'execution');
397
+ },
398
+ // PROP-132: runtime-выключатель терминалов (`terminal.enabled` +
399
+ // `terminal.autoRestore`). Секция пишется **целиком** (JSONB), поэтому
400
+ // новое поле `autoRestore` сохраняется без изменений схемы.
401
+ async getTerminal() {
402
+ return (await readSetting(conn, 'terminal')) ?? {};
403
+ },
404
+ async setTerminal(terminal) {
405
+ await writeSetting(conn, 'terminal', terminal);
406
+ },
407
+ async clearTerminal() {
408
+ await deleteSetting(conn, 'terminal');
409
+ },
370
410
  };
371
411
  }
@@ -18,7 +18,7 @@
18
18
  * `buildContentFromParts`, `generateId`) берутся напрямую из
19
19
  * `@itphx/synth-shared` — обычной зависимости драйвера (ADR-097).
20
20
  */
21
- import { type Checkpoint, type Message, type Part, type Session, type SessionReference, type SessionRetryState, type SessionWorktree, type StickyNote } from '@itphx/synth-shared';
21
+ import { type Checkpoint, type Message, type Part, type Session, type SessionMeta, type SessionReference, type SessionRetryState, type SessionWorktree, type StickyNote } from '@itphx/synth-shared';
22
22
  /** Строка `sessions` (jsonb — уже разобранные значения; `bigint` — строка). */
23
23
  export interface SessionRow {
24
24
  id: string;
@@ -81,6 +81,11 @@ export interface SessionRow {
81
81
  }
82
82
  /** Строка `messages` (или элемент jsonb-массива `pending_messages`/`checkpoints.messages`). */
83
83
  export interface MessageRow {
84
+ /**
85
+ * Суррогатный PK `messages` (bigserial). Нужен точечным операциям
86
+ * (`updateMessage`/`mutateMessage`): доменный `id` не уникален (legacy-дубли).
87
+ */
88
+ message_uid?: string | number;
84
89
  id: string;
85
90
  session_id?: string;
86
91
  seq: number;
@@ -118,6 +123,8 @@ export interface MessageRow {
118
123
  source?: string | null;
119
124
  author?: string | null;
120
125
  agent_role?: string | null;
126
+ /** ADR-126 §2: `@`-упоминания сообщения (jsonb, миграция `036`). */
127
+ mentions?: unknown;
121
128
  qa_pass?: boolean | null;
122
129
  qa_reason?: string | null;
123
130
  disabled?: boolean | null;
@@ -218,6 +225,8 @@ export interface SerializedMessage {
218
225
  source?: string;
219
226
  author?: string;
220
227
  agent_role?: string;
228
+ /** ADR-126 §2: `@`-упоминания (jsonb, миграция `036`). */
229
+ mentions?: unknown;
221
230
  metadata?: Record<string, unknown>;
222
231
  prompt_meta?: unknown;
223
232
  summary_of?: number[];
@@ -253,11 +262,14 @@ export declare function messageRow(msg: Message, sessionId: string, seq?: number
253
262
  */
254
263
  export declare function deserializeMessage(row: MessageRow): Message;
255
264
  /**
256
- * Сессия → строка `sessions` (колонки — как в `serializeSession` файловой
257
- * реализации; jsonb-поля остаются нативными значениями, их сериализует слой
258
- * параметров `jsonParam`).
265
+ * Сессия (её метаданные) → строка `sessions` (колонки — как в `serializeSession`
266
+ * файловой реализации; jsonb-поля остаются нативными значениями, их
267
+ * сериализует слой параметров `jsonParam`).
268
+ *
269
+ * Принимает `SessionMeta`: история/child-наборы в строку `sessions` не входят
270
+ * (они пишутся отдельными таблицами). Полная `Session` структурно совместима.
259
271
  */
260
- export declare function serializeSession(session: Session): Record<string, unknown>;
272
+ export declare function serializeSession(session: SessionMeta): Record<string, unknown>;
261
273
  /**
262
274
  * Строка `session_references` ← доменная ссылка. `id` — суррогатный
263
275
  * (генерируется при записи), `ordinal` — позиция в списке ссылок сессии
@@ -317,3 +329,14 @@ export declare function deserializeSessionLight(row: SessionRow): Session;
317
329
  * остальные поля идентичны `deserializeSession`; отличается только очередь.
318
330
  */
319
331
  export declare function deserializeSessionMeta(row: SessionRow): Session;
332
+ /**
333
+ * Строка `sessions` → **снимок метаданных** для `SessionRepository.mutateMeta`:
334
+ * без истории и child-наборов (`messages`/`checkpoints`/`references`/
335
+ * `stickyNotes`), но **с очередью** (`pendingMessages`/`steerInbox` — jsonb-колонки
336
+ * самой записи, мутатор вправе их менять).
337
+ *
338
+ * В отличие от `deserializeSessionMeta` (loadLight) очередь здесь сохраняется:
339
+ * `mutateMeta` пишет `pending_messages`/`steer_inbox` обратно, и очистка
340
+ * очереди молча потеряла бы in-flight сообщения.
341
+ */
342
+ export declare function deserializeSessionMetaDocument(row: SessionRow): SessionMeta;
@@ -128,6 +128,8 @@ export function serializeMessage(msg) {
128
128
  source: msg.source,
129
129
  author: msg.author,
130
130
  agent_role: msg.agentRole,
131
+ // ADR-126 §2: `@`-упоминания (jsonb, миграция `036`).
132
+ mentions: msg.mentions,
131
133
  metadata: msg.metadata,
132
134
  prompt_meta: msg.promptMeta,
133
135
  summary_of: msg.summaryOf,
@@ -251,6 +253,10 @@ export function deserializeMessage(row) {
251
253
  source: (row.source ?? undefined),
252
254
  author: row.author ?? undefined,
253
255
  agentRole: row.agent_role ?? undefined,
256
+ // ADR-126 §2: legacy-строки без колонки → `undefined`.
257
+ mentions: Array.isArray(row.mentions)
258
+ ? row.mentions
259
+ : undefined,
254
260
  metadata: (row.metadata ?? undefined),
255
261
  promptMeta: (row.prompt_meta ?? undefined),
256
262
  summaryOf: (row.summary_of ?? undefined),
@@ -261,9 +267,12 @@ export function deserializeMessage(row) {
261
267
  }
262
268
  // ── Сессия ──────────────────────────────────────────────────────────────────
263
269
  /**
264
- * Сессия → строка `sessions` (колонки — как в `serializeSession` файловой
265
- * реализации; jsonb-поля остаются нативными значениями, их сериализует слой
266
- * параметров `jsonParam`).
270
+ * Сессия (её метаданные) → строка `sessions` (колонки — как в `serializeSession`
271
+ * файловой реализации; jsonb-поля остаются нативными значениями, их
272
+ * сериализует слой параметров `jsonParam`).
273
+ *
274
+ * Принимает `SessionMeta`: история/child-наборы в строку `sessions` не входят
275
+ * (они пишутся отдельными таблицами). Полная `Session` структурно совместима.
267
276
  */
268
277
  export function serializeSession(session) {
269
278
  return {
@@ -564,3 +573,18 @@ export function deserializeSessionMeta(row) {
564
573
  session.steerInbox = [];
565
574
  return session;
566
575
  }
576
+ /**
577
+ * Строка `sessions` → **снимок метаданных** для `SessionRepository.mutateMeta`:
578
+ * без истории и child-наборов (`messages`/`checkpoints`/`references`/
579
+ * `stickyNotes`), но **с очередью** (`pendingMessages`/`steerInbox` — jsonb-колонки
580
+ * самой записи, мутатор вправе их менять).
581
+ *
582
+ * В отличие от `deserializeSessionMeta` (loadLight) очередь здесь сохраняется:
583
+ * `mutateMeta` пишет `pending_messages`/`steer_inbox` обратно, и очистка
584
+ * очереди молча потеряла бы in-flight сообщения.
585
+ */
586
+ export function deserializeSessionMetaDocument(row) {
587
+ const session = deserializeSessionLight(row);
588
+ const { messages: _messages, checkpoints: _checkpoints, references: _references, stickyNotes: _stickyNotes, ...meta } = session;
589
+ return meta;
590
+ }
@@ -56,8 +56,8 @@
56
56
  * `includes` файловой/memory реализаций.
57
57
  */
58
58
  import type { PostgresConnection } from '../pool.js';
59
- import type { Message, Session, SessionReference } from '@itphx/synth-shared';
60
- import type { SessionFilter, SessionRepository, StorageContext } from '@itphx/synth-core';
59
+ import type { Message, Session, SessionMeta, SessionReference } from '@itphx/synth-shared';
60
+ import type { MutateHistoryOptions, MutateHistoryResult, MutateMessageOptions, MutateMessageResult, MutateMetaOptions, MutateMetaResult, SessionFilter, SessionRepository, StorageContext } from '@itphx/synth-core';
61
61
  import type { PortDeps } from './deps.js';
62
62
  /** Часть `StorageContext`, которой владеет группа `sessions`. */
63
63
  export type SessionPorts = Pick<StorageContext, 'sessions'>;
@@ -72,7 +72,7 @@ export declare const SESSION_FIELDS: readonly ["id", "title", "icon", "color", "
72
72
  /** jsonb-колонки `sessions` (экспортируется для unit-тестов сериализации). */
73
73
  export declare const SESSION_JSON_FIELDS: ReadonlySet<string>;
74
74
  /** Колонки `messages` (порядок — как в `001_init`; `028` — reasoning-подпись). */
75
- export declare const MESSAGE_FIELDS: readonly ["id", "session_id", "seq", "ord", "role", "origin", "source_msg_id", "content", "parts", "tool_calls", "tool_call_id", "usage", "metadata", "prompt_meta", "debug_data", "summary_of", "model", "provider", "provider_type", "reasoning", "reasoning_signature", "reasoning_redacted", "source", "author", "agent_role", "qa_pass", "qa_reason", "disabled", "pinned", "hidden", "ephemeral", "turn_id", "step_index", "status", "created_at"];
75
+ export declare const MESSAGE_FIELDS: readonly ["id", "session_id", "seq", "ord", "role", "origin", "source_msg_id", "content", "parts", "tool_calls", "tool_call_id", "usage", "metadata", "prompt_meta", "debug_data", "summary_of", "model", "provider", "provider_type", "reasoning", "reasoning_signature", "reasoning_redacted", "source", "author", "agent_role", "mentions", "qa_pass", "qa_reason", "disabled", "pinned", "hidden", "ephemeral", "turn_id", "step_index", "status", "created_at"];
76
76
  export declare const MESSAGE_JSON_FIELDS: ReadonlySet<string>;
77
77
  /**
78
78
  * Колонки `messages`, которые заменяет `updateMessage`. Неизменяемые —
@@ -86,7 +86,7 @@ export declare const MESSAGE_JSON_FIELDS: ReadonlySet<string>;
86
86
  * уже выданное значение сохраняется, а ещё не выданное (legacy-строка) может
87
87
  * получить его (так проставляет `ord` миграция данных ядра).
88
88
  */
89
- export declare const MESSAGE_MUTABLE_FIELDS: ("origin" | "author" | "status" | "source" | "usage" | "model" | "provider" | "metadata" | "ephemeral" | "disabled" | "content" | "role" | "reasoning" | "pinned" | "hidden" | "agent_role" | "turn_id" | "source_msg_id" | "parts" | "tool_calls" | "tool_call_id" | "prompt_meta" | "debug_data" | "summary_of" | "provider_type" | "reasoning_signature" | "reasoning_redacted" | "qa_pass" | "qa_reason" | "step_index")[];
89
+ export declare const MESSAGE_MUTABLE_FIELDS: ("origin" | "author" | "status" | "source" | "usage" | "model" | "provider" | "metadata" | "ephemeral" | "disabled" | "content" | "role" | "reasoning" | "pinned" | "hidden" | "mentions" | "agent_role" | "turn_id" | "source_msg_id" | "parts" | "tool_calls" | "tool_call_id" | "prompt_meta" | "debug_data" | "summary_of" | "provider_type" | "reasoning_signature" | "reasoning_redacted" | "qa_pass" | "qa_reason" | "step_index")[];
90
90
  /**
91
91
  * ADR-118 §2: `ord` — **монотонный** счётчик порядка записи в историю
92
92
  * сессии (выдаётся при материализации, ранее выданные значения не
@@ -118,6 +118,12 @@ export declare class PostgresSessionRepository implements SessionRepository {
118
118
  * дубликаты `id` сохраняются как есть.
119
119
  */
120
120
  save(session: Session): Promise<void>;
121
+ /**
122
+ * Запись полного документа сессии под уже взятым advisory-локом: upsert
123
+ * строки `sessions` + **полная замена** child-таблиц. Общий помощник `save`
124
+ * и `mutateHistory` (одна семантика, один код).
125
+ */
126
+ private _writeSession;
121
127
  /**
122
128
  * Точечная дозапись сообщения (`SessionRepository.appendMessage`): одна
123
129
  * транзакция + per-session advisory-лок (как у `save`), `seq = MAX(seq)+1`
@@ -142,6 +148,35 @@ export declare class PostgresSessionRepository implements SessionRepository {
142
148
  * `ord`) может быть проставлено (миграция данных ядра).
143
149
  */
144
150
  updateMessage(sessionId: string, message: Message): Promise<Message | null>;
151
+ /**
152
+ * Атомарная правка метаданных (порт `SessionRepository.mutateMeta`): одна
153
+ * транзакция, `pg_advisory_xact_lock` **до** чтения строки `sessions`.
154
+ *
155
+ * Пишется только строка `sessions` (`UPDATE` по `SESSION_FIELDS`); child-таблицы
156
+ * (`messages`/`session_references`/`checkpoints`/`sticky_notes`) не трогаются —
157
+ * параллельный `appendMessage` не теряется. Очередь (`pending_messages`/
158
+ * `steer_inbox`) — колонки самой записи, читаются свежими и пишутся обратно.
159
+ */
160
+ mutateMeta<T>(sessionId: string, mutator: (meta: SessionMeta) => T, opts?: MutateMetaOptions<T>): Promise<MutateMetaResult<T>>;
161
+ /**
162
+ * Атомарная правка истории (порт `SessionRepository.mutateHistory`): свежий
163
+ * полный документ читается **внутри транзакции** под advisory-локом, затем
164
+ * синхронный мутатор и полная замена child-наборов (как `save`).
165
+ *
166
+ * `seq` нормализуется позиционно `1..n`; `ord` не перенумеровывается.
167
+ * `expectMaxOrd` проверяется по свежему снимку; `shouldWrite === false` —
168
+ * запись не выполняется (транзакция завершается без изменений);
169
+ * `touchUpdatedAt === false` — запись есть, `sessions.updated_at` не меняется.
170
+ */
171
+ mutateHistory<T>(sessionId: string, mutator: (session: Session) => T, opts?: MutateHistoryOptions<T>): Promise<MutateHistoryResult<T>>;
172
+ /**
173
+ * Атомарная правка одного сообщения по `id` (порт
174
+ * `SessionRepository.mutateMessage`): одна транзакция + advisory-лок; цель —
175
+ * по доменному `id` (при legacy-дублях — первая по `seq, created_at, id`).
176
+ * `id`/`seq`/`created_at`/`ord` исходной строки сохраняются, поздняя запись
177
+ * черновика поверх терминального сообщения не применяется.
178
+ */
179
+ mutateMessage<T>(sessionId: string, messageId: string, mutator: (message: Message) => T, opts?: MutateMessageOptions): Promise<MutateMessageResult<T>>;
145
180
  /**
146
181
  * Метаданные сессии без истории и без очереди (`SessionRepository.loadLight`):
147
182
  * одна выборка по PK, child-таблицы не читаются, `pendingMessages`/`steerInbox`
@@ -168,9 +203,19 @@ export declare class PostgresSessionRepository implements SessionRepository {
168
203
  getReferences(sessionId: string): Promise<SessionReference[]>;
169
204
  /** Список по готовому `WHERE` + батчевая подгрузка child-данных. */
170
205
  private _listByWhere;
206
+ /**
207
+ * Полный документ сессии внутри готовой транзакции (для `mutateHistory`).
208
+ * Чтение — тем же кодом, что у `load`; лок уже держит вызывающий.
209
+ */
210
+ private _loadSessionInTx;
171
211
  /**
172
212
  * Child-данные набора сессий — четыре запроса с `ANY($1)` (никакого N+1),
173
213
  * `ORDER BY session_id, …` для стабильного порядка внутри каждой сессии.
214
+ *
215
+ * `db` — исполнитель запросов: соединение (обычное чтение) либо транзакция
216
+ * (`mutateHistory` — читать нужно в той же транзакции, что и запись).
217
+ * `sequential` обязателен для транзакции: `pg` запрещает параллельные запросы
218
+ * на одном клиенте (пул — можно, транзакция — один клиент).
174
219
  */
175
220
  private _loadChildren;
176
221
  /**
@@ -56,8 +56,8 @@
56
56
  * `includes` файловой/memory реализаций.
57
57
  */
58
58
  import { jsonbParam } from '../json-param.js';
59
- import { generateId, makeTextPart, nowISO } from '@itphx/synth-shared';
60
- import { checkpointRow, deserializeMessage, deserializeReference, deserializeSession, deserializeSessionLight, deserializeSessionMeta, emptySessionChildren, messageRow, referenceRow, serializeSession, stickyNoteRow, toMessageStatus, } from './sessions-mapping.js';
59
+ import { generateId, makeTextPart, nowISO, stripNullBytesDeep } from '@itphx/synth-shared';
60
+ import { checkpointRow, deserializeMessage, deserializeReference, deserializeSession, deserializeSessionLight, deserializeSessionMeta, deserializeSessionMetaDocument, emptySessionChildren, messageRow, referenceRow, serializeSession, stickyNoteRow, toMessageStatus, } from './sessions-mapping.js';
61
61
  /**
62
62
  * Колонки `sessions` (порядок — как в `001_init`).
63
63
  *
@@ -157,6 +157,7 @@ export const MESSAGE_FIELDS = [
157
157
  'source',
158
158
  'author',
159
159
  'agent_role',
160
+ 'mentions',
160
161
  'qa_pass',
161
162
  'qa_reason',
162
163
  'disabled',
@@ -177,6 +178,7 @@ export const MESSAGE_JSON_FIELDS = new Set([
177
178
  'debug_data',
178
179
  'summary_of',
179
180
  'reasoning_redacted',
181
+ 'mentions',
180
182
  ]);
181
183
  /**
182
184
  * Колонки `messages`, которые заменяет `updateMessage`. Неизменяемые —
@@ -234,6 +236,43 @@ function isStaleDraftWrite(target, incoming) {
234
236
  || target.status === 'error';
235
237
  return terminal && isDraftMessageWrite(incoming);
236
238
  }
239
+ /**
240
+ * Максимальный выданный `ord` в истории (`0`, если `ord` ни у кого нет).
241
+ * Нужен оптимистичной проверке `mutateHistory({ expectMaxOrd })`; считается по
242
+ * свежему снимку в той же транзакции (отдельный `MAX(ord)` не требуется).
243
+ */
244
+ function maxOrdOf(messages) {
245
+ return messages.reduce((acc, message) => {
246
+ const ord = Number.isFinite(message.ord) ? message.ord : 0;
247
+ return ord > acc ? ord : acc;
248
+ }, 0);
249
+ }
250
+ /**
251
+ * `seq` — позиционный (порядок массива истории), нормализация `1..n`.
252
+ * `ord` не трогается: монотонный и иммутабельный после выдачи (ADR-118 §2).
253
+ */
254
+ function normalizeMessageSeq(messages) {
255
+ messages.forEach((message, index) => {
256
+ message.seq = index + 1;
257
+ });
258
+ }
259
+ /**
260
+ * Выдать `ord` сообщениям без него (`mutateHistory`: добавление
261
+ * мутатором/импортом) — подряд в порядке массива, от `max(ord)+1`. Ранее
262
+ * выданные значения не перенумеровываются; иначе новые записи сортировались бы
263
+ * в начало истории. Возвращает число выданных `ord`.
264
+ */
265
+ function assignMissingOrd(messages) {
266
+ let next = maxOrdOf(messages) + 1;
267
+ let assigned = 0;
268
+ for (const message of messages) {
269
+ if (Number.isFinite(message.ord))
270
+ continue;
271
+ message.ord = next++;
272
+ assigned++;
273
+ }
274
+ return assigned;
275
+ }
237
276
  /**
238
277
  * ADR-118 §2: `ord` — **монотонный** счётчик порядка записи в историю
239
278
  * сессии (выдаётся при материализации, ранее выданные значения не
@@ -370,6 +409,17 @@ export class PostgresSessionRepository {
370
409
  * дубликаты `id` сохраняются как есть.
371
410
  */
372
411
  async save(session) {
412
+ await this._connection.withTransaction(async (tx) => {
413
+ await this._lockSession(tx, session.id);
414
+ await this._writeSession(tx, session);
415
+ });
416
+ }
417
+ /**
418
+ * Запись полного документа сессии под уже взятым advisory-локом: upsert
419
+ * строки `sessions` + **полная замена** child-таблиц. Общий помощник `save`
420
+ * и `mutateHistory` (одна семантика, один код).
421
+ */
422
+ async _writeSession(tx, session) {
373
423
  const sessionRow = serializeSession(session);
374
424
  // `seq` — позиция сообщения в массиве (`1..n`): снимает legacy-коллизию
375
425
  // `UNIQUE (session_id, seq)` (у старых сессий `seq = 0` у всех) и делает
@@ -378,20 +428,17 @@ export class PostgresSessionRepository {
378
428
  const referenceRows = (session.references ?? []).map((ref, index) => referenceRow(session.id, ref, index));
379
429
  const checkpointRows = (session.checkpoints ?? []).map(checkpointRow);
380
430
  const noteRows = (session.stickyNotes ?? []).map((note) => stickyNoteRow(session.id, note));
381
- await this._connection.withTransaction(async (tx) => {
382
- await this._lockSession(tx, session.id);
383
- await upsertRows(tx, 'sessions', SESSION_FIELDS, [sessionRow], SESSION_JSON_FIELDS, ['id']);
384
- // Сообщения — полная замена в той же транзакции: `DELETE` + массовый
385
- // `INSERT`. Дубликаты `id` допустимы (суррогатный PK `message_uid`);
386
- // уникальность `(session_id, seq)` выполняется по построению (позиция).
387
- await replaceRows(tx, 'messages', MESSAGE_FIELDS, messageRows, MESSAGE_JSON_FIELDS, session.id);
388
- // Ссылки — полная замена (паритет с файловой реализацией: `save`
389
- // перезаписывает `session.references` целиком); `id`/`ordinal` — свежие,
390
- // дубликаты одной `ref_session_id` допустимы (разные диапазоны).
391
- await replaceRows(tx, 'session_references', REFERENCE_FIELDS, referenceRows, REFERENCE_JSON_FIELDS, session.id);
392
- await replaceRows(tx, 'checkpoints', CHECKPOINT_FIELDS, checkpointRows, CHECKPOINT_JSON_FIELDS, session.id);
393
- await replaceRows(tx, 'sticky_notes', NOTE_FIELDS, noteRows, NOTE_JSON_FIELDS, session.id);
394
- });
431
+ await upsertRows(tx, 'sessions', SESSION_FIELDS, [sessionRow], SESSION_JSON_FIELDS, ['id']);
432
+ // Сообщения — полная замена в той же транзакции: `DELETE` + массовый
433
+ // `INSERT`. Дубликаты `id` допустимы (суррогатный PK `message_uid`);
434
+ // уникальность `(session_id, seq)` выполняется по построению (позиция).
435
+ await replaceRows(tx, 'messages', MESSAGE_FIELDS, messageRows, MESSAGE_JSON_FIELDS, session.id);
436
+ // Ссылки — полная замена (паритет с файловой реализацией: `save`
437
+ // перезаписывает `session.references` целиком); `id`/`ordinal` — свежие,
438
+ // дубликаты одной `ref_session_id` допустимы (разные диапазоны).
439
+ await replaceRows(tx, 'session_references', REFERENCE_FIELDS, referenceRows, REFERENCE_JSON_FIELDS, session.id);
440
+ await replaceRows(tx, 'checkpoints', CHECKPOINT_FIELDS, checkpointRows, CHECKPOINT_JSON_FIELDS, session.id);
441
+ await replaceRows(tx, 'sticky_notes', NOTE_FIELDS, noteRows, NOTE_JSON_FIELDS, session.id);
395
442
  }
396
443
  /**
397
444
  * Точечная дозапись сообщения (`SessionRepository.appendMessage`): одна
@@ -462,6 +509,133 @@ export class PostgresSessionRepository {
462
509
  return updatedRow ? deserializeMessage(updatedRow) : null;
463
510
  });
464
511
  }
512
+ /**
513
+ * Атомарная правка метаданных (порт `SessionRepository.mutateMeta`): одна
514
+ * транзакция, `pg_advisory_xact_lock` **до** чтения строки `sessions`.
515
+ *
516
+ * Пишется только строка `sessions` (`UPDATE` по `SESSION_FIELDS`); child-таблицы
517
+ * (`messages`/`session_references`/`checkpoints`/`sticky_notes`) не трогаются —
518
+ * параллельный `appendMessage` не теряется. Очередь (`pending_messages`/
519
+ * `steer_inbox`) — колонки самой записи, читаются свежими и пишутся обратно.
520
+ */
521
+ async mutateMeta(sessionId, mutator, opts) {
522
+ return this._connection.withTransaction(async (tx) => {
523
+ await this._lockSession(tx, sessionId);
524
+ const rows = await tx.query('SELECT * FROM sessions WHERE id = $1', [sessionId]);
525
+ const row = rows[0];
526
+ if (!row)
527
+ return { found: false };
528
+ // `shouldWrite`: мутатор работает с клоном; при отказе от записи `UPDATE`
529
+ // не выполняется, а `session` — снимок **до** мутатора (без алиасинга).
530
+ const snapshot = deserializeSessionMetaDocument(row);
531
+ const baseline = opts?.shouldWrite ? structuredClone(snapshot) : undefined;
532
+ const meta = opts?.shouldWrite ? structuredClone(snapshot) : snapshot;
533
+ const value = mutator(meta);
534
+ if (opts?.shouldWrite && !opts.shouldWrite(value)) {
535
+ return { found: true, value, session: baseline };
536
+ }
537
+ // Идентичность сессии неизменяема (строку адресует `id`).
538
+ meta.id = sessionId;
539
+ if (opts?.touchUpdatedAt !== false)
540
+ meta.updatedAt = nowISO();
541
+ // Паритет с file/memory: возврат — санитизированное значение (NUL-байты
542
+ // несовместимы с PostgreSQL; так же их чистит `jsonParam` при записи).
543
+ const sanitized = stripNullBytesDeep(meta);
544
+ // `serializeSession` строит значения по колонкам `sessions`; child-наборы
545
+ // сюда не входят. `id` в SET — то же значение (строку уже заблокировали).
546
+ const values = rowValues(serializeSession(sanitized), SESSION_FIELDS, SESSION_JSON_FIELDS);
547
+ const setClauses = SESSION_FIELDS.map((field, index) => `${field} = $${index + 1}`);
548
+ await tx.query(`UPDATE sessions SET ${setClauses.join(', ')} WHERE id = $${SESSION_FIELDS.length + 1}`, [...values, sessionId]);
549
+ return { found: true, value, session: sanitized };
550
+ });
551
+ }
552
+ /**
553
+ * Атомарная правка истории (порт `SessionRepository.mutateHistory`): свежий
554
+ * полный документ читается **внутри транзакции** под advisory-локом, затем
555
+ * синхронный мутатор и полная замена child-наборов (как `save`).
556
+ *
557
+ * `seq` нормализуется позиционно `1..n`; `ord` не перенумеровывается.
558
+ * `expectMaxOrd` проверяется по свежему снимку; `shouldWrite === false` —
559
+ * запись не выполняется (транзакция завершается без изменений);
560
+ * `touchUpdatedAt === false` — запись есть, `sessions.updated_at` не меняется.
561
+ */
562
+ async mutateHistory(sessionId, mutator, opts) {
563
+ return this._connection.withTransaction(async (tx) => {
564
+ await this._lockSession(tx, sessionId);
565
+ const session = await this._loadSessionInTx(tx, sessionId);
566
+ if (!session)
567
+ return { ok: false, reason: 'not_found' };
568
+ if (opts?.expectMaxOrd !== undefined && maxOrdOf(session.messages) > opts.expectMaxOrd) {
569
+ return { ok: false, reason: 'stale' };
570
+ }
571
+ const value = mutator(session);
572
+ if (opts?.shouldWrite && !opts.shouldWrite(value))
573
+ return { ok: true, value };
574
+ session.id = sessionId;
575
+ // Новым записям (добавлены мутатором/импортом) порт выдаёт `ord` сам:
576
+ // без него сортировка по `ord` поставила бы их в начало истории.
577
+ assignMissingOrd(session.messages);
578
+ normalizeMessageSeq(session.messages);
579
+ // `touchUpdatedAt:false` — служебная запись истории не «оживляет» сессию:
580
+ // `updated_at` пишется как прочитан (паритет с file/memory).
581
+ if (opts?.touchUpdatedAt !== false)
582
+ session.updatedAt = nowISO();
583
+ await this._writeSession(tx, session);
584
+ return { ok: true, value };
585
+ });
586
+ }
587
+ /**
588
+ * Атомарная правка одного сообщения по `id` (порт
589
+ * `SessionRepository.mutateMessage`): одна транзакция + advisory-лок; цель —
590
+ * по доменному `id` (при legacy-дублях — первая по `seq, created_at, id`).
591
+ * `id`/`seq`/`created_at`/`ord` исходной строки сохраняются, поздняя запись
592
+ * черновика поверх терминального сообщения не применяется.
593
+ */
594
+ async mutateMessage(sessionId, messageId, mutator, opts) {
595
+ return this._connection.withTransaction(async (tx) => {
596
+ await this._lockSession(tx, sessionId);
597
+ const rows = await tx.query('SELECT * FROM messages WHERE session_id = $1 AND id = $2 '
598
+ + 'ORDER BY seq, created_at, id LIMIT 1', [sessionId, messageId]);
599
+ const row = rows[0];
600
+ if (!row)
601
+ return { found: false };
602
+ const original = deserializeMessage(row);
603
+ const target = structuredClone(original);
604
+ const value = mutator(target);
605
+ // ADR-118 §5: поздняя запись черновика не «воскрешает» закрытый шаг.
606
+ if (isStaleDraftWrite({ status: toMessageStatus(row.status) ?? null }, target)) {
607
+ return { found: true, value, message: original };
608
+ }
609
+ // Иммутабельные поля берутся из исходной строки, изменяются только
610
+ // `MESSAGE_MUTABLE_FIELDS`; `ord` — `COALESCE` (уже выданный не перебить).
611
+ const prepared = prepareMessage({
612
+ ...target,
613
+ id: original.id,
614
+ seq: original.seq,
615
+ createdAt: original.createdAt,
616
+ ord: original.ord,
617
+ });
618
+ const updatedRow = messageRow(prepared, sessionId, original.seq);
619
+ const setClauses = MESSAGE_MUTABLE_FIELDS.map((field, index) => `${field} = $${index + 1}`);
620
+ const params = rowValues(updatedRow, MESSAGE_MUTABLE_FIELDS, MESSAGE_JSON_FIELDS);
621
+ if (prepared.ord !== undefined && prepared.ord !== null) {
622
+ params.push(prepared.ord);
623
+ setClauses.push(`ord = COALESCE(messages.ord, $${params.length})`);
624
+ }
625
+ const updated = await tx.query(`UPDATE messages SET ${setClauses.join(', ')} WHERE message_uid = $${params.length + 1} RETURNING *`, [...params, row.message_uid]);
626
+ // `touchUpdatedAt:false` — служебные метки (`turnId`/`last_error`) не
627
+ // «оживляют» сессию: строка `sessions` не трогается.
628
+ if (opts?.touchUpdatedAt !== false) {
629
+ await tx.query('UPDATE sessions SET updated_at = now() WHERE id = $1', [sessionId]);
630
+ }
631
+ const updatedRowResult = updated[0];
632
+ return {
633
+ found: true,
634
+ value,
635
+ message: updatedRowResult ? deserializeMessage(updatedRowResult) : original,
636
+ };
637
+ });
638
+ }
465
639
  /**
466
640
  * Метаданные сессии без истории и без очереди (`SessionRepository.loadLight`):
467
641
  * одна выборка по PK, child-таблицы не читаются, `pendingMessages`/`steerInbox`
@@ -549,26 +723,59 @@ export class PostgresSessionRepository {
549
723
  const children = await this._loadChildren(rows.map((row) => row.id));
550
724
  return rows.map((row) => deserializeSession(row, children.get(row.id) ?? emptySessionChildren()));
551
725
  }
726
+ /**
727
+ * Полный документ сессии внутри готовой транзакции (для `mutateHistory`).
728
+ * Чтение — тем же кодом, что у `load`; лок уже держит вызывающий.
729
+ */
730
+ async _loadSessionInTx(tx, sessionId) {
731
+ const rows = await tx.query('SELECT * FROM sessions WHERE id = $1', [sessionId]);
732
+ const row = rows[0];
733
+ if (!row)
734
+ return null;
735
+ const children = await this._loadChildren([sessionId], tx, true);
736
+ return deserializeSession(row, children.get(sessionId) ?? emptySessionChildren());
737
+ }
552
738
  /**
553
739
  * Child-данные набора сессий — четыре запроса с `ANY($1)` (никакого N+1),
554
740
  * `ORDER BY session_id, …` для стабильного порядка внутри каждой сессии.
741
+ *
742
+ * `db` — исполнитель запросов: соединение (обычное чтение) либо транзакция
743
+ * (`mutateHistory` — читать нужно в той же транзакции, что и запись).
744
+ * `sequential` обязателен для транзакции: `pg` запрещает параллельные запросы
745
+ * на одном клиенте (пул — можно, транзакция — один клиент).
555
746
  */
556
- async _loadChildren(sessionIds) {
747
+ async _loadChildren(sessionIds, db = this._connection, sequential = false) {
557
748
  const buckets = new Map();
558
749
  for (const sessionId of sessionIds)
559
750
  buckets.set(sessionId, emptySessionChildren());
560
751
  if (sessionIds.length === 0)
561
752
  return buckets;
562
- const [messages, references, checkpoints, notes] = await Promise.all([
563
- this._connection.query('SELECT * FROM messages WHERE session_id = ANY($1::text[]) '
564
- + 'ORDER BY session_id, seq, created_at, id', [sessionIds]),
565
- this._connection.query('SELECT * FROM session_references WHERE session_id = ANY($1::text[]) '
566
- + 'ORDER BY session_id, ordinal', [sessionIds]),
567
- this._connection.query('SELECT * FROM checkpoints WHERE session_id = ANY($1::text[]) '
568
- + 'ORDER BY session_id, created_at, id', [sessionIds]),
569
- this._connection.query('SELECT * FROM sticky_notes WHERE session_id = ANY($1::text[]) '
570
- + 'ORDER BY session_id, created_at, id', [sessionIds]),
571
- ]);
753
+ const loadMessages = () => db.query('SELECT * FROM messages WHERE session_id = ANY($1::text[]) '
754
+ + 'ORDER BY session_id, seq, created_at, id', [sessionIds]);
755
+ const loadReferences = () => db.query('SELECT * FROM session_references WHERE session_id = ANY($1::text[]) '
756
+ + 'ORDER BY session_id, ordinal', [sessionIds]);
757
+ const loadCheckpoints = () => db.query('SELECT * FROM checkpoints WHERE session_id = ANY($1::text[]) '
758
+ + 'ORDER BY session_id, created_at, id', [sessionIds]);
759
+ const loadNotes = () => db.query('SELECT * FROM sticky_notes WHERE session_id = ANY($1::text[]) '
760
+ + 'ORDER BY session_id, created_at, id', [sessionIds]);
761
+ let messages;
762
+ let references;
763
+ let checkpoints;
764
+ let notes;
765
+ if (sequential) {
766
+ messages = await loadMessages();
767
+ references = await loadReferences();
768
+ checkpoints = await loadCheckpoints();
769
+ notes = await loadNotes();
770
+ }
771
+ else {
772
+ [messages, references, checkpoints, notes] = await Promise.all([
773
+ loadMessages(),
774
+ loadReferences(),
775
+ loadCheckpoints(),
776
+ loadNotes(),
777
+ ]);
778
+ }
572
779
  for (const row of messages)
573
780
  buckets.get(row.session_id ?? '')?.messages.push(row);
574
781
  for (const row of references)
@@ -1,5 +1,5 @@
1
1
  /**
2
- * PG-реализация порта **instance-скиллов** (ADR-046 §4, ADR-116, ADR-097).
2
+ * PG-реализация порта **instance-скиллов** (ADR-126 §9, ADR-116, ADR-097).
3
3
  *
4
4
  * Разделение хранения (ADR-116 §«Что переводится»):
5
5
  * - **метаданные** (заголовок `SKILL.md` — `name`/`description`/прочие ключи) —
@@ -55,5 +55,5 @@ export declare class PgSkillRepository implements SkillRepository {
55
55
  /** Upsert метаданных: заголовок скилла и служебная метка записи. */
56
56
  private _upsertMetadata;
57
57
  }
58
- /** Собрать порт instance-скиллов (ADR-046 §4, ADR-116). */
58
+ /** Собрать порт instance-скиллов (ADR-126 §9, ADR-116). */
59
59
  export declare function buildSkillPorts(deps: PortDeps, blobs: BlobStore): SkillPorts;