@itphx/synth-storage-postgres 0.13.4 → 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.
Files changed (44) hide show
  1. package/dist/index.d.ts +2 -0
  2. package/dist/index.js +3 -0
  3. package/dist/migrations/026-instance-skills.d.ts +1 -1
  4. package/dist/migrations/026-instance-skills.js +1 -1
  5. package/dist/migrations/031-ssh-key-policy.d.ts +13 -0
  6. package/dist/migrations/031-ssh-key-policy.js +25 -0
  7. package/dist/migrations/032-mcp-remote-mode.d.ts +14 -0
  8. package/dist/migrations/032-mcp-remote-mode.js +18 -0
  9. package/dist/migrations/033-session-source-id.d.ts +16 -0
  10. package/dist/migrations/033-session-source-id.js +21 -0
  11. package/dist/migrations/034-pending-approvals.d.ts +18 -0
  12. package/dist/migrations/034-pending-approvals.js +35 -0
  13. package/dist/migrations/035-project-access.d.ts +16 -0
  14. package/dist/migrations/035-project-access.js +22 -0
  15. package/dist/migrations/036-message-mentions.d.ts +8 -0
  16. package/dist/migrations/036-message-mentions.js +12 -0
  17. package/dist/migrations/037-timers.d.ts +19 -0
  18. package/dist/migrations/037-timers.js +60 -0
  19. package/dist/migrations/038-schedule-project-id.d.ts +18 -0
  20. package/dist/migrations/038-schedule-project-id.js +38 -0
  21. package/dist/migrations/index.js +16 -0
  22. package/dist/ports/content.js +80 -9
  23. package/dist/ports/context-files.d.ts +6 -0
  24. package/dist/ports/context-files.js +13 -0
  25. package/dist/ports/events-scheduler.js +19 -4
  26. package/dist/ports/pending-approvals.d.ts +32 -0
  27. package/dist/ports/pending-approvals.js +108 -0
  28. package/dist/ports/principals-defaults.js +10 -0
  29. package/dist/ports/principals-projects.d.ts +7 -1
  30. package/dist/ports/principals-projects.js +66 -11
  31. package/dist/ports/principals-settings.js +80 -0
  32. package/dist/ports/sessions-mapping.d.ts +36 -5
  33. package/dist/ports/sessions-mapping.js +32 -4
  34. package/dist/ports/sessions.d.ts +55 -8
  35. package/dist/ports/sessions.js +285 -37
  36. package/dist/ports/skills.d.ts +2 -2
  37. package/dist/ports/skills.js +2 -2
  38. package/dist/ports/timers.d.ts +54 -0
  39. package/dist/ports/timers.js +247 -0
  40. package/dist/ports/worktrees.d.ts +3 -3
  41. package/dist/ports/worktrees.js +3 -3
  42. package/dist/storage-context.d.ts +4 -2
  43. package/dist/storage-context.js +17 -3
  44. package/package.json +5 -5
@@ -4,15 +4,21 @@
4
4
  * Эталон семантики — `ProjectStore`/`MemoryProjectRepository`:
5
5
  * - `create()` — синхронная чистая фабрика (id, `members`, 4 дефолтные колонки
6
6
  * плана, пустые `statusMessages`/`log`, `version: 1`, таймстемпы);
7
- * - `list(userId)` — владелец **или** участник, сортировка `updated_at DESC`;
7
+ * - `list(viewer)` — владелец, участник, грант по группе или режим «всем
8
+ * пользователям» (PROP-133); без `viewer` — все проекты, сортировка
9
+ * `updated_at DESC`;
8
10
  * - `delete` отсутствующего — не ошибка; `load` отсутствующего — `null`.
9
11
  *
10
12
  * `members` — child-таблица `project_members` (PK `(project_id,user_id)`,
11
13
  * индекс `(user_id)`): `save` заменяет набор участий в той же транзакции, что и
12
14
  * строку проекта. `plan`/`log`/`status_messages`/`repos`/`mcp`/`skills` — `jsonb`.
15
+ * PROP-133: `group_members` (`jsonb`) и `everyone_role` (`text`) — состояние
16
+ * списка доступа; `list` сначала сужает выборку SQL'ем (оптимизация), затем
17
+ * **обязательно** проверяет каждую строку резолвером `resolveProjectAccess`
18
+ * (истина — резолвер, не SQL).
13
19
  */
14
20
  import { randomUUID } from 'node:crypto';
15
- import { normalizeColorKey, normalizeIconKey } from '@itphx/synth-shared';
21
+ import { ProjectRole, normalizeColorKey, normalizeIconKey, normalizeProjectEveryoneRole, normalizeProjectMemberRoles, resolveProjectAccess, } from '@itphx/synth-shared';
16
22
  import { jsonbParam, requiredIso } from './principals-shared.js';
17
23
  /** Проекции проекта + json-агрегация участий одним запросом (без N+1). */
18
24
  const SELECT_PROJECT = `
@@ -24,11 +30,27 @@ const SELECT_PROJECT = `
24
30
  WHERE pm.project_id = p.id
25
31
  ) m ON true`;
26
32
  function rowToProject(row) {
33
+ // PROP-133: нормализация состояния доступа при чтении (битые роли →
34
+ // `viewer`, `everyone_role` — только `owner|editor|viewer`/`null`).
35
+ //
36
+ // Паритет с `ProjectStore`/`MemoryProjectRepository`: «нет грантов» — это
37
+ // **отсутствие поля**, а не пустой объект/`null`:
38
+ // - `group_members` в БД — `jsonb`, «нет грантов» записан как `{}`
39
+ // (нормальное представление в БД) → наружу поле не отдаём;
40
+ // - `everyone_role` в БД — `text`, «не опубликован» записан как `NULL` →
41
+ // `null` → `undefined` (поле отсутствует), потому что в БД `NULL` и
42
+ // «явный `null`» неразличимы, а эталон (file/memory) при создании
43
+ // оставляет поле **отсутствующим**;
44
+ // - DTO всё равно отдаёт `?? null`, поэтому наружу контракт не меняется.
45
+ const groupMembers = normalizeProjectMemberRoles(row.group_members);
46
+ const everyoneRole = normalizeProjectEveryoneRole(row.everyone_role ?? undefined);
27
47
  return {
28
48
  id: row.id,
29
49
  name: row.name,
30
50
  ownerId: row.owner_id,
31
- members: (row.members ?? {}),
51
+ members: normalizeProjectMemberRoles(row.members),
52
+ ...(Object.keys(groupMembers).length > 0 ? { groupMembers } : {}),
53
+ ...(everyoneRole !== undefined && everyoneRole !== null ? { everyoneRole } : {}),
32
54
  description: row.description ?? '',
33
55
  currentTask: row.current_task ?? '',
34
56
  invariants: row.invariants ?? '',
@@ -56,10 +78,12 @@ function rowToProject(row) {
56
78
  async function writeProject(tx, project) {
57
79
  await tx.query(`INSERT INTO projects (
58
80
  id, name, owner_id, description, current_task, invariants, icon, color,
59
- workspace, plan, log, status_messages, repos, mcp, skills, memory, created_at, updated_at
81
+ workspace, plan, log, status_messages, repos, mcp, skills, memory,
82
+ group_members, everyone_role, created_at, updated_at
60
83
  ) VALUES (
61
84
  $1, $2, $3, $4, $5, $6, $7, $8,
62
- $9, $10::jsonb, $11::jsonb, $12::jsonb, $13::jsonb, $14::jsonb, $15::jsonb, $16::jsonb, $17, $18
85
+ $9, $10::jsonb, $11::jsonb, $12::jsonb, $13::jsonb, $14::jsonb, $15::jsonb, $16::jsonb,
86
+ $17::jsonb, $18, $19, $20
63
87
  )
64
88
  ON CONFLICT (id) DO UPDATE SET
65
89
  name = EXCLUDED.name,
@@ -77,6 +101,8 @@ async function writeProject(tx, project) {
77
101
  mcp = EXCLUDED.mcp,
78
102
  skills = EXCLUDED.skills,
79
103
  memory = EXCLUDED.memory,
104
+ group_members = EXCLUDED.group_members,
105
+ everyone_role = EXCLUDED.everyone_role,
80
106
  updated_at = EXCLUDED.updated_at`, [
81
107
  project.id,
82
108
  project.name,
@@ -94,6 +120,9 @@ async function writeProject(tx, project) {
94
120
  jsonbParam(project.mcp ?? null),
95
121
  jsonbParam(project.skills ?? null),
96
122
  jsonbParam(project.memory ?? null),
123
+ // PROP-133: состояние списка доступа (гранты группам, режим «всем»).
124
+ jsonbParam(project.groupMembers ?? {}),
125
+ project.everyoneRole ?? null,
97
126
  project.createdAt,
98
127
  project.updatedAt,
99
128
  ]);
@@ -143,25 +172,51 @@ export function createPrincipalProjectsPort(conn) {
143
172
  async delete(id) {
144
173
  await conn.query('DELETE FROM projects WHERE id = $1', [id]);
145
174
  },
146
- async list(userId) {
147
- const rows = userId
175
+ /**
176
+ * Список проектов (PROP-133).
177
+ *
178
+ * Без `viewer` — все проекты (ADMIN/LEAD и внутренние задачи). С
179
+ * `viewer` — SQL сужает выборку (владелец/участник/«всем»/грант по
180
+ * группе) — это **оптимизация**; истина — резолвер `resolveProjectAccess`,
181
+ * поэтому каждая загруженная строка проверяется им (битая роль в данных не
182
+ * выдаёт лишний доступ).
183
+ */
184
+ async list(viewer) {
185
+ const rows = viewer
148
186
  ? await conn.query(`${SELECT_PROJECT}
149
187
  WHERE p.owner_id = $1
150
188
  OR EXISTS (
151
189
  SELECT 1 FROM project_members pm2
152
190
  WHERE pm2.project_id = p.id AND pm2.user_id = $1
153
191
  )
154
- ORDER BY p.updated_at DESC`, [userId])
192
+ OR p.everyone_role IS NOT NULL
193
+ OR (
194
+ jsonb_typeof(p.group_members) = 'object'
195
+ AND p.group_members ?| $2::text[]
196
+ )
197
+ ORDER BY p.updated_at DESC`, [viewer.userId, viewer.groups ?? []])
155
198
  : await conn.query(`${SELECT_PROJECT} ORDER BY p.updated_at DESC`);
156
- return rows.map(rowToProject);
199
+ const projects = rows.map(rowToProject);
200
+ if (!viewer)
201
+ return projects;
202
+ return projects.filter((project) => resolveProjectAccess(project, viewer).read);
157
203
  },
158
204
  create(name, ownerId, data) {
159
205
  const now = new Date().toISOString();
206
+ // PROP-133: роль владельца всегда `owner` (понизить её нельзя).
207
+ const members = normalizeProjectMemberRoles(data?.members);
208
+ members[ownerId] = ProjectRole.OWNER;
209
+ const groupMembers = data?.groupMembers
210
+ ? normalizeProjectMemberRoles(data.groupMembers)
211
+ : undefined;
212
+ const everyoneRole = normalizeProjectEveryoneRole(data?.everyoneRole);
160
213
  return {
161
214
  id: randomUUID(),
162
215
  name,
163
216
  ownerId,
164
- members: { [ownerId]: 'owner' },
217
+ members,
218
+ ...(groupMembers ? { groupMembers } : {}),
219
+ ...(everyoneRole !== undefined ? { everyoneRole } : {}),
165
220
  description: data?.description || '',
166
221
  currentTask: '',
167
222
  invariants: '',
@@ -169,7 +224,7 @@ export function createPrincipalProjectsPort(conn) {
169
224
  color: data?.color,
170
225
  workspace: data?.workspace,
171
226
  repos: data?.repos,
172
- // ADR-071 §2.4 / ADR-046 §4.5: сид скоупа новых проектов (снимок системных дефолтов).
227
+ // ADR-071 §2.4 / ADR-126 §11: сид скоупа новых проектов (снимок системных дефолтов).
173
228
  ...(data?.mcp ? { mcp: data.mcp } : {}),
174
229
  ...(data?.skills ? { skills: data.skills } : {}),
175
230
  statusMessages: [],
@@ -30,6 +30,7 @@ const SECTION_KEYS = [
30
30
  'skillsDisabled',
31
31
  'skillsDisabledForNewProjects',
32
32
  'skillsPolicy',
33
+ 'skillsTrustedProjectDirs',
33
34
  'mcpNetworkPolicy',
34
35
  'egress',
35
36
  'defaultAgent',
@@ -40,6 +41,13 @@ const SECTION_KEYS = [
40
41
  'proxy',
41
42
  'plugins',
42
43
  'attachments',
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',
43
51
  ];
44
52
  const SECTION_KEY_SET = new Set(SECTION_KEYS);
45
53
  /** Собрать порт runtime-настроек поверх SQL. */
@@ -167,6 +175,15 @@ export function createPrincipalSettingsPort(conn) {
167
175
  async clearSkillsPolicy() {
168
176
  await deleteSetting(conn, 'skillsPolicy');
169
177
  },
178
+ async getSkillsTrustedProjectDirs() {
179
+ return readSetting(conn, 'skillsTrustedProjectDirs');
180
+ },
181
+ async setSkillsTrustedProjectDirs(dirs) {
182
+ await writeSetting(conn, 'skillsTrustedProjectDirs', dirs);
183
+ },
184
+ async clearSkillsTrustedProjectDirs() {
185
+ await deleteSetting(conn, 'skillsTrustedProjectDirs');
186
+ },
170
187
  async getTokenRatio(model) {
171
188
  const rows = await conn.query('SELECT ratio FROM token_ratios WHERE model = $1', [model]);
172
189
  return rows[0]?.ratio;
@@ -264,6 +281,16 @@ export function createPrincipalSettingsPort(conn) {
264
281
  async clearMetrics() {
265
282
  await deleteSetting(conn, 'metrics');
266
283
  },
284
+ // ADR-133: runtime-тумблер автоматической проверки обновлений.
285
+ async getUpdates() {
286
+ return (await readSetting(conn, 'updates')) ?? {};
287
+ },
288
+ async setUpdates(config) {
289
+ await writeSetting(conn, 'updates', config);
290
+ },
291
+ async clearUpdates() {
292
+ await deleteSetting(conn, 'updates');
293
+ },
267
294
  async getPlugins() {
268
295
  return (await readSetting(conn, 'plugins')) ?? {};
269
296
  },
@@ -291,6 +318,18 @@ export function createPrincipalSettingsPort(conn) {
291
318
  async clearAttachments() {
292
319
  await deleteSetting(conn, 'attachments');
293
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
+ },
294
333
  async getContextWindowPolicy() {
295
334
  return readSetting(conn, 'contextWindowPolicy');
296
335
  },
@@ -309,6 +348,15 @@ export function createPrincipalSettingsPort(conn) {
309
348
  async clearSubagentMaxInputTokens() {
310
349
  await deleteSetting(conn, 'subagentMaxInputTokens');
311
350
  },
351
+ async getSessionOpsPerMinute() {
352
+ return readSetting(conn, 'sessionOpsPerMinute');
353
+ },
354
+ async setSessionOpsPerMinute(value) {
355
+ await writeSetting(conn, 'sessionOpsPerMinute', value);
356
+ },
357
+ async clearSessionOpsPerMinute() {
358
+ await deleteSetting(conn, 'sessionOpsPerMinute');
359
+ },
312
360
  async getContextDefaults() {
313
361
  return readSetting(conn, 'contextDefaults');
314
362
  },
@@ -327,5 +375,37 @@ export function createPrincipalSettingsPort(conn) {
327
375
  async clearStickyNotesLimits() {
328
376
  await deleteSetting(conn, 'stickyNotesLimits');
329
377
  },
378
+ // PROP-124: режим инстанса для SSH-ключей (`ssh.mode`).
379
+ async getSshMode() {
380
+ return readSetting(conn, 'sshMode');
381
+ },
382
+ async setSshMode(mode) {
383
+ await writeSetting(conn, 'sshMode', mode);
384
+ },
385
+ async clearSshMode() {
386
+ await deleteSetting(conn, 'sshMode');
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
+ },
330
410
  };
331
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;
@@ -35,6 +35,12 @@ export interface SessionRow {
35
35
  user_id: string | null;
36
36
  owner_id: string | null;
37
37
  project_id: string | null;
38
+ /**
39
+ * Маркер источника при переносе между инстансами (`Session.sourceSessionId`),
40
+ * ключ дедупликации повторного импорта (миграция `033`). В записях, созданных
41
+ * до миграции, поля нет — чтение даёт `undefined`.
42
+ */
43
+ source_session_id?: string | null;
38
44
  /**
39
45
  * ADR-114: привязка сессии к worktree (jsonb). В записях, созданных до
40
46
  * миграции `023`, поля нет — чтение даёт `undefined`.
@@ -75,6 +81,11 @@ export interface SessionRow {
75
81
  }
76
82
  /** Строка `messages` (или элемент jsonb-массива `pending_messages`/`checkpoints.messages`). */
77
83
  export interface MessageRow {
84
+ /**
85
+ * Суррогатный PK `messages` (bigserial). Нужен точечным операциям
86
+ * (`updateMessage`/`mutateMessage`): доменный `id` не уникален (legacy-дубли).
87
+ */
88
+ message_uid?: string | number;
78
89
  id: string;
79
90
  session_id?: string;
80
91
  seq: number;
@@ -112,6 +123,8 @@ export interface MessageRow {
112
123
  source?: string | null;
113
124
  author?: string | null;
114
125
  agent_role?: string | null;
126
+ /** ADR-126 §2: `@`-упоминания сообщения (jsonb, миграция `036`). */
127
+ mentions?: unknown;
115
128
  qa_pass?: boolean | null;
116
129
  qa_reason?: string | null;
117
130
  disabled?: boolean | null;
@@ -212,6 +225,8 @@ export interface SerializedMessage {
212
225
  source?: string;
213
226
  author?: string;
214
227
  agent_role?: string;
228
+ /** ADR-126 §2: `@`-упоминания (jsonb, миграция `036`). */
229
+ mentions?: unknown;
215
230
  metadata?: Record<string, unknown>;
216
231
  prompt_meta?: unknown;
217
232
  summary_of?: number[];
@@ -226,6 +241,8 @@ export declare function toIsoOrUndefined(value: unknown): string | undefined;
226
241
  export declare function toNumber(value: unknown, fallback?: number): number;
227
242
  /** Необязательное число (nullable-колонка). */
228
243
  export declare function toNumberOrUndefined(value: unknown): number | undefined;
244
+ /** Статус сообщения из колонки `status` (неизвестное значение → `undefined`). */
245
+ export declare function toMessageStatus(value: unknown): Message['status'];
229
246
  /** Сообщение → форма хранения (дословно `serializeMessage` файловой реализации). */
230
247
  export declare function serializeMessage(msg: Message): SerializedMessage;
231
248
  /**
@@ -245,11 +262,14 @@ export declare function messageRow(msg: Message, sessionId: string, seq?: number
245
262
  */
246
263
  export declare function deserializeMessage(row: MessageRow): Message;
247
264
  /**
248
- * Сессия → строка `sessions` (колонки — как в `serializeSession` файловой
249
- * реализации; jsonb-поля остаются нативными значениями, их сериализует слой
250
- * параметров `jsonParam`).
265
+ * Сессия (её метаданные) → строка `sessions` (колонки — как в `serializeSession`
266
+ * файловой реализации; jsonb-поля остаются нативными значениями, их
267
+ * сериализует слой параметров `jsonParam`).
268
+ *
269
+ * Принимает `SessionMeta`: история/child-наборы в строку `sessions` не входят
270
+ * (они пишутся отдельными таблицами). Полная `Session` структурно совместима.
251
271
  */
252
- export declare function serializeSession(session: Session): Record<string, unknown>;
272
+ export declare function serializeSession(session: SessionMeta): Record<string, unknown>;
253
273
  /**
254
274
  * Строка `session_references` ← доменная ссылка. `id` — суррогатный
255
275
  * (генерируется при записи), `ordinal` — позиция в списке ссылок сессии
@@ -309,3 +329,14 @@ export declare function deserializeSessionLight(row: SessionRow): Session;
309
329
  * остальные поля идентичны `deserializeSession`; отличается только очередь.
310
330
  */
311
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;
@@ -78,7 +78,7 @@ function deserializePart(data) {
78
78
  */
79
79
  const MESSAGE_STATUSES = ['streaming', 'completed', 'cancelled', 'error'];
80
80
  /** Статус сообщения из колонки `status` (неизвестное значение → `undefined`). */
81
- function toMessageStatus(value) {
81
+ export function toMessageStatus(value) {
82
82
  return typeof value === 'string' && MESSAGE_STATUSES.includes(value)
83
83
  ? value
84
84
  : undefined;
@@ -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 {
@@ -280,6 +289,8 @@ export function serializeSession(session) {
280
289
  user_id: session.userId ?? null,
281
290
  owner_id: session.ownerId ?? null,
282
291
  project_id: session.projectId ?? null,
292
+ // Маркер источника переноса (ключ дедупликации повторного импорта).
293
+ source_session_id: session.sourceSessionId ?? null,
283
294
  // ADR-114: привязка к worktree (объект в snake_case — как в JSON-файле).
284
295
  worktree: session.worktree
285
296
  ? {
@@ -486,6 +497,8 @@ export function deserializeSession(row, children) {
486
497
  userId: row.user_id ?? undefined,
487
498
  ownerId: row.owner_id ?? undefined,
488
499
  projectId: row.project_id ?? undefined,
500
+ // Маркер источника переноса (legacy-записи без поля → undefined).
501
+ ...(row.source_session_id ? { sourceSessionId: row.source_session_id } : {}),
489
502
  // ADR-114: привязка к worktree (legacy-записи без поля → undefined).
490
503
  ...(worktree ? { worktree } : {}),
491
504
  messages: children.messages.map(deserializeMessage),
@@ -560,3 +573,18 @@ export function deserializeSessionMeta(row) {
560
573
  session.steerInbox = [];
561
574
  return session;
562
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'>;
@@ -68,11 +68,11 @@ export type SessionPorts = Pick<StorageContext, 'sessions'>;
68
68
  * тест проверяет, что новая колонка (`worktree`, ADR-114) реально попадает в
69
69
  * `INSERT` и читается обратно.
70
70
  */
71
- export declare const SESSION_FIELDS: readonly ["id", "title", "icon", "color", "session_origin", "parent_id", "branch_point", "plan_approved", "mode", "mode_by_principal", "user_id", "owner_id", "project_id", "worktree", "todos", "prompt_states", "obfuscation_map", "status", "settings", "mcp_servers", "pending_messages", "steer_inbox", "current_stream", "retry", "summarization_pending", "can_summarize", "created_at", "updated_at", "expires_at", "archived_at", "input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "cache_write_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_read_cost", "cache_write_cost", "cache_hit_rate"];
71
+ export declare const SESSION_FIELDS: readonly ["id", "title", "icon", "color", "session_origin", "parent_id", "branch_point", "plan_approved", "mode", "mode_by_principal", "user_id", "owner_id", "project_id", "source_session_id", "worktree", "todos", "prompt_states", "obfuscation_map", "status", "settings", "mcp_servers", "pending_messages", "steer_inbox", "current_stream", "retry", "summarization_pending", "can_summarize", "created_at", "updated_at", "expires_at", "archived_at", "input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "cache_write_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_read_cost", "cache_write_cost", "cache_hit_rate"];
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,16 +203,28 @@ 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
  /**
177
- * `message_uid` цели `updateMessage`: сначала по `seq` (при legacy-дублях —
178
- * первая по `seq, created_at, id`), затем fallback по доменному `id`.
222
+ * Цель `updateMessage`: `message_uid` строки + её текущий `status`
223
+ * (ADR-118 §5 — для проверки «поздняя запись черновика поверх закрытого
224
+ * шага»). Сначала по `seq` (при legacy-дублях — первая по
225
+ * `seq, created_at, id`), затем fallback по доменному `id`.
179
226
  */
180
- private _findMessageUid;
227
+ private _findMessageTarget;
181
228
  /** ADR-097: per-session сериализация записи — транзакционный advisory-лок. */
182
229
  private _lockSession;
183
230
  /** `addReference`/`removeReference` отсутствующей сессии → ошибка (как в file/memory). */