@itphx/synth-storage-postgres 0.0.0-stage → 0.12.4

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 (150) hide show
  1. package/LICENSE +18 -0
  2. package/LICENSE.ru.md +31 -0
  3. package/dist/errors.d.ts +71 -0
  4. package/dist/errors.js +126 -0
  5. package/dist/index.d.ts +51 -0
  6. package/dist/index.js +56 -0
  7. package/dist/json-param.d.ts +14 -0
  8. package/dist/json-param.js +22 -0
  9. package/dist/locks.d.ts +104 -0
  10. package/dist/locks.js +201 -0
  11. package/dist/migrate.d.ts +58 -0
  12. package/dist/migrate.js +125 -0
  13. package/dist/migrations/001-init.d.ts +15 -0
  14. package/dist/migrations/001-init.js +457 -0
  15. package/dist/migrations/002-egress-audit.d.ts +12 -0
  16. package/dist/migrations/002-egress-audit.js +52 -0
  17. package/dist/migrations/003-analytics-rollups.d.ts +12 -0
  18. package/dist/migrations/003-analytics-rollups.js +21 -0
  19. package/dist/migrations/004-pipeline-engine.d.ts +19 -0
  20. package/dist/migrations/004-pipeline-engine.js +74 -0
  21. package/dist/migrations/005-pipeline-provenance.d.ts +12 -0
  22. package/dist/migrations/005-pipeline-provenance.js +15 -0
  23. package/dist/migrations/006-plugin-audit.d.ts +13 -0
  24. package/dist/migrations/006-plugin-audit.js +34 -0
  25. package/dist/migrations/007-plugin-lock.d.ts +10 -0
  26. package/dist/migrations/007-plugin-lock.js +25 -0
  27. package/dist/migrations/008-plugin-audit-scan.d.ts +11 -0
  28. package/dist/migrations/008-plugin-audit-scan.js +15 -0
  29. package/dist/migrations/009-plugin-lock-previous.d.ts +13 -0
  30. package/dist/migrations/009-plugin-lock-previous.js +16 -0
  31. package/dist/migrations/010-plugin-lock-mode.d.ts +16 -0
  32. package/dist/migrations/010-plugin-lock-mode.js +20 -0
  33. package/dist/migrations/011-session-steer-inbox.d.ts +11 -0
  34. package/dist/migrations/011-session-steer-inbox.js +14 -0
  35. package/dist/migrations/012-external-credentials.d.ts +15 -0
  36. package/dist/migrations/012-external-credentials.js +40 -0
  37. package/dist/migrations/013-service-key-plugin-id.d.ts +17 -0
  38. package/dist/migrations/013-service-key-plugin-id.js +20 -0
  39. package/dist/migrations/014-session-mode-by-principal.d.ts +12 -0
  40. package/dist/migrations/014-session-mode-by-principal.js +15 -0
  41. package/dist/migrations/015-authority.d.ts +17 -0
  42. package/dist/migrations/015-authority.js +43 -0
  43. package/dist/migrations/016-credential-audit.d.ts +17 -0
  44. package/dist/migrations/016-credential-audit.js +32 -0
  45. package/dist/migrations/017-memory.d.ts +29 -0
  46. package/dist/migrations/017-memory.js +95 -0
  47. package/dist/migrations/018-memory-index-scope.d.ts +14 -0
  48. package/dist/migrations/018-memory-index-scope.js +18 -0
  49. package/dist/migrations/019-memory-index-enabled.d.ts +11 -0
  50. package/dist/migrations/019-memory-index-enabled.js +14 -0
  51. package/dist/migrations/020-project-memory.d.ts +11 -0
  52. package/dist/migrations/020-project-memory.js +13 -0
  53. package/dist/migrations/021-background-runs.d.ts +17 -0
  54. package/dist/migrations/021-background-runs.js +67 -0
  55. package/dist/migrations/022-background-run-process-id.d.ts +14 -0
  56. package/dist/migrations/022-background-run-process-id.js +18 -0
  57. package/dist/migrations/023-session-worktree.d.ts +12 -0
  58. package/dist/migrations/023-session-worktree.js +16 -0
  59. package/dist/migrations/024-blob-refs.d.ts +15 -0
  60. package/dist/migrations/024-blob-refs.js +26 -0
  61. package/dist/migrations/025-packs-pipelines.d.ts +28 -0
  62. package/dist/migrations/025-packs-pipelines.js +82 -0
  63. package/dist/migrations/026-instance-skills.d.ts +17 -0
  64. package/dist/migrations/026-instance-skills.js +25 -0
  65. package/dist/migrations/027-context-files.d.ts +20 -0
  66. package/dist/migrations/027-context-files.js +30 -0
  67. package/dist/migrations/index.d.ts +23 -0
  68. package/dist/migrations/index.js +71 -0
  69. package/dist/pool.d.ts +178 -0
  70. package/dist/pool.js +382 -0
  71. package/dist/ports/analytics.d.ts +26 -0
  72. package/dist/ports/analytics.js +243 -0
  73. package/dist/ports/audit.d.ts +15 -0
  74. package/dist/ports/audit.js +192 -0
  75. package/dist/ports/authority.d.ts +27 -0
  76. package/dist/ports/authority.js +148 -0
  77. package/dist/ports/background-runs.d.ts +41 -0
  78. package/dist/ports/background-runs.js +179 -0
  79. package/dist/ports/blob-refs.d.ts +36 -0
  80. package/dist/ports/blob-refs.js +55 -0
  81. package/dist/ports/content.d.ts +41 -0
  82. package/dist/ports/content.js +1553 -0
  83. package/dist/ports/context-files.d.ts +145 -0
  84. package/dist/ports/context-files.js +279 -0
  85. package/dist/ports/core-sync.d.ts +31 -0
  86. package/dist/ports/core-sync.js +34 -0
  87. package/dist/ports/credential-audit.d.ts +19 -0
  88. package/dist/ports/credential-audit.js +96 -0
  89. package/dist/ports/deps.d.ts +63 -0
  90. package/dist/ports/deps.js +19 -0
  91. package/dist/ports/events-bindings.d.ts +77 -0
  92. package/dist/ports/events-bindings.js +356 -0
  93. package/dist/ports/events-core.d.ts +35 -0
  94. package/dist/ports/events-core.js +71 -0
  95. package/dist/ports/events-journal.d.ts +68 -0
  96. package/dist/ports/events-journal.js +211 -0
  97. package/dist/ports/events-scheduler.d.ts +49 -0
  98. package/dist/ports/events-scheduler.js +231 -0
  99. package/dist/ports/events-webhooks.d.ts +64 -0
  100. package/dist/ports/events-webhooks.js +268 -0
  101. package/dist/ports/events.d.ts +20 -0
  102. package/dist/ports/events.js +27 -0
  103. package/dist/ports/external-credentials.d.ts +6 -0
  104. package/dist/ports/external-credentials.js +363 -0
  105. package/dist/ports/legacy-pipelines.d.ts +50 -0
  106. package/dist/ports/legacy-pipelines.js +202 -0
  107. package/dist/ports/memory.d.ts +65 -0
  108. package/dist/ports/memory.js +471 -0
  109. package/dist/ports/packs.d.ts +32 -0
  110. package/dist/ports/packs.js +117 -0
  111. package/dist/ports/pipelines.d.ts +67 -0
  112. package/dist/ports/pipelines.js +297 -0
  113. package/dist/ports/plugin-audit.d.ts +14 -0
  114. package/dist/ports/plugin-audit.js +110 -0
  115. package/dist/ports/plugin-lock.d.ts +27 -0
  116. package/dist/ports/plugin-lock.js +145 -0
  117. package/dist/ports/principals-defaults.d.ts +21 -0
  118. package/dist/ports/principals-defaults.js +68 -0
  119. package/dist/ports/principals-documents.d.ts +23 -0
  120. package/dist/ports/principals-documents.js +38 -0
  121. package/dist/ports/principals-profiles.d.ts +21 -0
  122. package/dist/ports/principals-profiles.js +263 -0
  123. package/dist/ports/principals-projects.d.ts +19 -0
  124. package/dist/ports/principals-projects.js +161 -0
  125. package/dist/ports/principals-settings.d.ts +25 -0
  126. package/dist/ports/principals-settings.js +295 -0
  127. package/dist/ports/principals-shared.d.ts +33 -0
  128. package/dist/ports/principals-shared.js +44 -0
  129. package/dist/ports/principals.d.ts +27 -0
  130. package/dist/ports/principals.js +39 -0
  131. package/dist/ports/questions.d.ts +40 -0
  132. package/dist/ports/questions.js +135 -0
  133. package/dist/ports/sessions-mapping.d.ts +254 -0
  134. package/dist/ports/sessions-mapping.js +449 -0
  135. package/dist/ports/sessions.d.ts +143 -0
  136. package/dist/ports/sessions.js +517 -0
  137. package/dist/ports/skills.d.ts +59 -0
  138. package/dist/ports/skills.js +205 -0
  139. package/dist/ports/stub.d.ts +14 -0
  140. package/dist/ports/stub.js +32 -0
  141. package/dist/ports/worktrees.d.ts +41 -0
  142. package/dist/ports/worktrees.js +85 -0
  143. package/dist/postgres-storage.d.ts +58 -0
  144. package/dist/postgres-storage.js +110 -0
  145. package/dist/schema.d.ts +13 -0
  146. package/dist/schema.js +22 -0
  147. package/dist/storage-context.d.ts +80 -0
  148. package/dist/storage-context.js +238 -0
  149. package/package.json +40 -3
  150. package/README.md +0 -3
@@ -0,0 +1,449 @@
1
+ /**
2
+ * Отображение строк PostgreSQL ↔ доменных объектов порта `SessionRepository`
3
+ * (ADR-097, волна 3b).
4
+ *
5
+ * Эталон семантики — файловая реализация (`core/src/storage/file-store.ts`):
6
+ * `serializeSession`/`serializeMessage` и `deserializeSession`/`deserializeMessage`
7
+ * воспроизводятся здесь **дословно** (имена полей в snake_case — как в JSON
8
+ * файлового backend и как в колонках `001_init`). Это осознанная копия: домен и
9
+ * UI полагаются на конкретные детали чтения —
10
+ * - `normalizeIconKey`/`normalizeColorKey` (невалидные ключи → `undefined`);
11
+ * - `sessionOrigin || 'user'`;
12
+ * - числовые дефолты `0` (токены/стоимость), булевы `false`;
13
+ * - legacy-сообщение без `parts` восстанавливается из `content`/`reasoning`/
14
+ * `tool_calls`/`tool_call_id`;
15
+ * - `content` собирается из `parts` (`buildContentFromParts`).
16
+ *
17
+ * Типы домена и утилиты (`normalizeIconKey`/`normalizeColorKey`, `makeTextPart`,
18
+ * `buildContentFromParts`, `generateId`) берутся напрямую из
19
+ * `@itphx/synth-shared` — обычной зависимости драйвера (ADR-097).
20
+ */
21
+ import { buildContentFromParts, generateId, makeTextPart, normalizeColorKey, normalizeIconKey, } from '@itphx/synth-shared';
22
+ /** Пустой набор child-данных (сессия без сообщений/ссылок/чекпоинтов). */
23
+ export function emptySessionChildren() {
24
+ return { messages: [], references: [], checkpoints: [], stickyNotes: [] };
25
+ }
26
+ // ── Вспомогательные преобразования значений ─────────────────────────────────
27
+ /** `timestamptz` (Date) либо уже готовую строку → ISO-строку. */
28
+ export function toIso(value) {
29
+ if (value instanceof Date)
30
+ return Number.isNaN(value.getTime()) ? '' : value.toISOString();
31
+ if (typeof value === 'string')
32
+ return value;
33
+ return '';
34
+ }
35
+ /** Необязательное время: `null`/пусто → `undefined`. */
36
+ export function toIsoOrUndefined(value) {
37
+ if (value === null || value === undefined)
38
+ return undefined;
39
+ const iso = toIso(value);
40
+ return iso === '' ? undefined : iso;
41
+ }
42
+ /** `bigint`/`double precision` (число или строка) → число; `null`/NaN → `fallback`. */
43
+ export function toNumber(value, fallback = 0) {
44
+ if (value === null || value === undefined)
45
+ return fallback;
46
+ const num = typeof value === 'number' ? value : Number(value);
47
+ return Number.isFinite(num) ? num : fallback;
48
+ }
49
+ /** Необязательное число (nullable-колонка). */
50
+ export function toNumberOrUndefined(value) {
51
+ if (value === null || value === undefined)
52
+ return undefined;
53
+ const num = typeof value === 'number' ? value : Number(value);
54
+ return Number.isFinite(num) ? num : undefined;
55
+ }
56
+ function serializePart(part) {
57
+ return { id: part.id, type: part.type, data: part.data };
58
+ }
59
+ function deserializePart(data) {
60
+ return { id: data.id, type: data.type, data: data.data };
61
+ }
62
+ // ── Сообщения ───────────────────────────────────────────────────────────────
63
+ /** Сообщение → форма хранения (дословно `serializeMessage` файловой реализации). */
64
+ export function serializeMessage(msg) {
65
+ return {
66
+ id: msg.id,
67
+ role: msg.role,
68
+ seq: msg.seq,
69
+ origin: msg.origin,
70
+ source_msg_id: msg.sourceMsgId,
71
+ parts: (msg.parts ?? []).map(serializePart),
72
+ content: msg.content,
73
+ tool_calls: msg.toolCalls,
74
+ tool_call_id: msg.toolCallId,
75
+ created_at: msg.createdAt,
76
+ disabled: msg.disabled,
77
+ pinned: msg.pinned,
78
+ hidden: msg.hidden,
79
+ ephemeral: msg.ephemeral,
80
+ debug_data: msg.debugData,
81
+ model: msg.model,
82
+ provider: msg.provider,
83
+ provider_type: msg.providerType,
84
+ usage: msg.usage
85
+ ? {
86
+ input_tokens: msg.usage.inputTokens,
87
+ output_tokens: msg.usage.outputTokens,
88
+ total_tokens: msg.usage.totalTokens,
89
+ cache_read_tokens: msg.usage.cacheReadTokens,
90
+ cache_write_tokens: msg.usage.cacheWriteTokens,
91
+ reasoning_tokens: msg.usage.reasoningTokens,
92
+ }
93
+ : undefined,
94
+ reasoning: msg.reasoning,
95
+ source: msg.source,
96
+ author: msg.author,
97
+ agent_role: msg.agentRole,
98
+ metadata: msg.metadata,
99
+ prompt_meta: msg.promptMeta,
100
+ summary_of: msg.summaryOf,
101
+ qa_pass: msg.qa_pass,
102
+ qa_reason: msg.qa_reason,
103
+ };
104
+ }
105
+ /**
106
+ * Сообщение → строка `messages`: к сериализованной форме добавляются обязательные
107
+ * колонки (`session_id`, дефолты NOT NULL-полей, `id`). Значения `undefined` для
108
+ * nullable-колонок остаются как есть — их приводит к `NULL` слой параметров.
109
+ *
110
+ * `seq` — **позиционный**: драйвер передаёт номер сообщения в массиве (`1..n`),
111
+ * поэтому порядок сообщений в БД однозначен даже для legacy-сессий, где у всех
112
+ * сообщений исторически `seq = 0` (снятие коллизии `UNIQUE (session_id, seq)`).
113
+ * Без явного `seq` используется значение домена (или `0`).
114
+ */
115
+ export function messageRow(msg, sessionId, seq) {
116
+ const serialized = serializeMessage(msg);
117
+ return {
118
+ ...serialized,
119
+ id: serialized.id ?? generateId(),
120
+ session_id: sessionId,
121
+ seq: seq ?? serialized.seq ?? 0,
122
+ role: serialized.role ?? 'user',
123
+ origin: serialized.origin ?? 'local',
124
+ content: serialized.content ?? '',
125
+ created_at: serialized.created_at ?? new Date().toISOString(),
126
+ disabled: serialized.disabled ?? false,
127
+ pinned: serialized.pinned ?? false,
128
+ hidden: serialized.hidden ?? false,
129
+ ephemeral: serialized.ephemeral ?? false,
130
+ };
131
+ }
132
+ /**
133
+ * Строка `messages` (или jsonb-элемент) → доменное сообщение: дословный
134
+ * `deserializeMessage` файловой реализации, включая legacy-ветку без `parts`.
135
+ */
136
+ export function deserializeMessage(row) {
137
+ const hasParts = Array.isArray(row.parts) && row.parts.length > 0;
138
+ let parts;
139
+ if (hasParts) {
140
+ parts = row.parts.map(deserializePart);
141
+ }
142
+ else {
143
+ parts = [];
144
+ if (row.content)
145
+ parts.push(makeTextPart(row.content));
146
+ if (row.reasoning) {
147
+ parts.push({ id: generateId(), type: 'reasoning', data: row.reasoning });
148
+ }
149
+ const toolCalls = row.tool_calls;
150
+ if (toolCalls && toolCalls.length > 0) {
151
+ for (const tc of toolCalls) {
152
+ const func = tc.function;
153
+ parts.push({
154
+ id: generateId(),
155
+ type: 'tool_use',
156
+ data: { name: func?.name ?? 'unknown', args: func?.arguments ?? {} },
157
+ });
158
+ }
159
+ }
160
+ if (row.role === 'tool' && row.tool_call_id) {
161
+ parts.push({
162
+ id: generateId(),
163
+ type: 'tool_result',
164
+ data: { content: row.content, isError: false },
165
+ });
166
+ }
167
+ }
168
+ const content = buildContentFromParts(parts);
169
+ const usage = row.usage;
170
+ return {
171
+ id: row.id || generateId(),
172
+ role: row.role,
173
+ seq: row.seq ?? 0,
174
+ origin: (row.origin || 'local'),
175
+ sourceMsgId: row.source_msg_id ?? undefined,
176
+ parts,
177
+ content,
178
+ toolCalls: (row.tool_calls ?? undefined),
179
+ toolCallId: row.tool_call_id ?? undefined,
180
+ createdAt: toIso(row.created_at),
181
+ disabled: row.disabled ?? false,
182
+ pinned: row.pinned ?? false,
183
+ hidden: row.hidden ?? false,
184
+ ephemeral: row.ephemeral ?? undefined,
185
+ debugData: (row.debug_data ?? undefined),
186
+ model: row.model ?? undefined,
187
+ provider: row.provider ?? undefined,
188
+ providerType: row.provider_type ?? undefined,
189
+ usage: usage
190
+ ? {
191
+ inputTokens: usage.input_tokens,
192
+ outputTokens: usage.output_tokens,
193
+ totalTokens: usage.total_tokens,
194
+ cacheReadTokens: usage.cache_read_tokens,
195
+ cacheWriteTokens: usage.cache_write_tokens,
196
+ reasoningTokens: usage.reasoning_tokens,
197
+ }
198
+ : undefined,
199
+ reasoning: row.reasoning ?? undefined,
200
+ source: (row.source ?? undefined),
201
+ author: row.author ?? undefined,
202
+ agentRole: row.agent_role ?? undefined,
203
+ metadata: (row.metadata ?? undefined),
204
+ promptMeta: (row.prompt_meta ?? undefined),
205
+ summaryOf: (row.summary_of ?? undefined),
206
+ // Обратная совместимость: legacy-сессии без полей → undefined (без дефолтов).
207
+ qa_pass: row.qa_pass ?? undefined,
208
+ qa_reason: row.qa_reason ?? undefined,
209
+ };
210
+ }
211
+ // ── Сессия ──────────────────────────────────────────────────────────────────
212
+ /**
213
+ * Сессия → строка `sessions` (колонки — как в `serializeSession` файловой
214
+ * реализации; jsonb-поля остаются нативными значениями, их сериализует слой
215
+ * параметров `jsonParam`).
216
+ */
217
+ export function serializeSession(session) {
218
+ return {
219
+ id: session.id,
220
+ title: session.title ?? null,
221
+ icon: session.icon ?? null,
222
+ color: session.color ?? null,
223
+ session_origin: session.sessionOrigin || 'user',
224
+ parent_id: session.parentId ?? null,
225
+ branch_point: session.branchPoint ?? null,
226
+ plan_approved: session.planApproved ?? null,
227
+ mode: session.mode ?? null,
228
+ mode_by_principal: session.modeByPrincipal ?? null,
229
+ user_id: session.userId ?? null,
230
+ owner_id: session.ownerId ?? null,
231
+ project_id: session.projectId ?? null,
232
+ // ADR-114: привязка к worktree (объект в snake_case — как в JSON-файле).
233
+ worktree: session.worktree
234
+ ? {
235
+ worktree_id: session.worktree.worktreeId,
236
+ project_id: session.worktree.projectId,
237
+ ...(session.worktree.repoPath !== undefined ? { repo_path: session.worktree.repoPath } : {}),
238
+ directory: session.worktree.directory,
239
+ branch: session.worktree.branch,
240
+ }
241
+ : null,
242
+ todos: session.todos ?? null,
243
+ prompt_states: session.promptStates ?? null,
244
+ obfuscation_map: session.obfuscationMap ?? null,
245
+ status: session.status ?? {},
246
+ settings: session.settings ?? {},
247
+ mcp_servers: session.mcpServers ?? null,
248
+ pending_messages: (session.pendingMessages ?? []).map((msg) => serializeMessage(msg)),
249
+ steer_inbox: (session.steerInbox ?? []).map((msg) => serializeMessage(msg)),
250
+ current_stream: session.currentStream
251
+ ? {
252
+ stream_id: session.currentStream.streamId,
253
+ message: session.currentStream.message,
254
+ agent_role: session.currentStream.agentRole,
255
+ started_at: session.currentStream.startedAt,
256
+ cancelled: session.currentStream.cancelled,
257
+ }
258
+ : null,
259
+ summarization_pending: session.summarizationPending ?? false,
260
+ can_summarize: session.canSummarize ?? false,
261
+ created_at: session.createdAt,
262
+ updated_at: session.updatedAt,
263
+ expires_at: session.expiresAt ?? null,
264
+ archived_at: session.archivedAt ?? null,
265
+ input_tokens: session.inputTokens ?? 0,
266
+ output_tokens: session.outputTokens ?? 0,
267
+ total_tokens: session.totalTokens ?? 0,
268
+ cache_read_tokens: session.cacheReadTokens ?? 0,
269
+ cache_write_tokens: session.cacheWriteTokens ?? 0,
270
+ reasoning_tokens: session.reasoningTokens ?? 0,
271
+ input_cost: session.inputCost ?? 0,
272
+ output_cost: session.outputCost ?? 0,
273
+ cache_read_cost: session.cacheReadCost ?? 0,
274
+ cache_write_cost: session.cacheWriteCost ?? 0,
275
+ cache_hit_rate: session.cacheHitRate ?? null,
276
+ };
277
+ }
278
+ /**
279
+ * Строка `session_references` ← доменная ссылка. `id` — суррогатный
280
+ * (генерируется при записи), `ordinal` — позиция в списке ссылок сессии
281
+ * (порядок добавления, `addReference` — append; дубликаты разрешены).
282
+ */
283
+ export function referenceRow(sessionId, ref, ordinal) {
284
+ return {
285
+ id: generateId(),
286
+ session_id: sessionId,
287
+ ref_session_id: ref.sessionId,
288
+ label: ref.label,
289
+ message_range: ref.messageRange,
290
+ auto_summary: ref.autoSummary ?? null,
291
+ ordinal,
292
+ created_at: ref.createdAt,
293
+ };
294
+ }
295
+ /** Строка `session_references` → доменная ссылка. */
296
+ export function deserializeReference(row) {
297
+ return {
298
+ type: 'session_reference',
299
+ sessionId: row.ref_session_id,
300
+ label: row.label,
301
+ messageRange: row.message_range,
302
+ autoSummary: row.auto_summary ?? undefined,
303
+ createdAt: toIso(row.created_at),
304
+ };
305
+ }
306
+ /** Строка `checkpoints` ← доменный чекпоинт (сообщения — jsonb-массив). */
307
+ export function checkpointRow(cp) {
308
+ return {
309
+ id: cp.id,
310
+ session_id: cp.sessionId,
311
+ messages: cp.messages.map((msg) => serializeMessage(msg)),
312
+ created_at: cp.createdAt,
313
+ };
314
+ }
315
+ /** Строка `checkpoints` → доменный чекпоинт. */
316
+ export function deserializeCheckpoint(row) {
317
+ return {
318
+ id: row.id,
319
+ sessionId: row.session_id,
320
+ messages: (row.messages ?? []).map(deserializeMessage),
321
+ createdAt: toIso(row.created_at),
322
+ };
323
+ }
324
+ /** Строка `sticky_notes` ← доменная заметка. */
325
+ export function stickyNoteRow(sessionId, note) {
326
+ return {
327
+ id: note.id,
328
+ session_id: sessionId,
329
+ content: note.content,
330
+ disabled: note.disabled,
331
+ created_at: note.createdAt,
332
+ updated_at: note.updatedAt,
333
+ };
334
+ }
335
+ /** Строка `sticky_notes` → доменная заметка. */
336
+ export function deserializeStickyNote(row) {
337
+ return {
338
+ id: row.id,
339
+ content: row.content,
340
+ createdAt: toIso(row.created_at),
341
+ updatedAt: toIso(row.updated_at),
342
+ disabled: row.disabled,
343
+ };
344
+ }
345
+ /**
346
+ * ADR-114: привязка сессии к worktree из jsonb-колонки `sessions.worktree`.
347
+ *
348
+ * Терпима к отсутствию поля (записи до миграции `023`) и к частичным
349
+ * значениям: привязка без `worktree_id`/`directory` бессмысленна — она
350
+ * игнорируется, сессия работает как прежде.
351
+ */
352
+ export function deserializeSessionWorktree(data) {
353
+ if (typeof data !== 'object' || data === null)
354
+ return undefined;
355
+ const raw = data;
356
+ const worktreeId = typeof raw.worktree_id === 'string' ? raw.worktree_id : '';
357
+ const directory = typeof raw.directory === 'string' ? raw.directory : '';
358
+ if (!worktreeId || !directory)
359
+ return undefined;
360
+ return {
361
+ worktreeId,
362
+ projectId: typeof raw.project_id === 'string' ? raw.project_id : '',
363
+ ...(typeof raw.repo_path === 'string' ? { repoPath: raw.repo_path } : {}),
364
+ directory,
365
+ branch: typeof raw.branch === 'string' ? raw.branch : '',
366
+ };
367
+ }
368
+ /**
369
+ * Строка `sessions` + child-данные → доменная сессия: дословный
370
+ * `deserializeSession` файловой реализации (нормализация иконки/цвета,
371
+ * `sessionOrigin || 'user'`, числовые/булевы дефолты, сборка
372
+ * `references`/`checkpoints`/`stickyNotes`).
373
+ */
374
+ export function deserializeSession(row, children) {
375
+ const currentStream = row.current_stream;
376
+ // ADR-114: привязка к worktree (legacy-записи без поля → undefined).
377
+ const worktree = deserializeSessionWorktree(row.worktree);
378
+ return {
379
+ id: row.id,
380
+ title: row.title ?? undefined,
381
+ icon: normalizeIconKey(row.icon),
382
+ color: normalizeColorKey(row.color),
383
+ parentId: row.parent_id ?? undefined,
384
+ branchPoint: row.branch_point ?? undefined,
385
+ planApproved: row.plan_approved ?? undefined,
386
+ mode: (row.mode ?? undefined),
387
+ // ADR-106 Ф4 (шаг C): режим по принципалу.
388
+ ...(row.mode_by_principal && Object.keys(row.mode_by_principal).length > 0
389
+ ? { modeByPrincipal: row.mode_by_principal }
390
+ : {}),
391
+ todos: (row.todos ?? undefined),
392
+ promptStates: (row.prompt_states ?? undefined),
393
+ obfuscationMap: (row.obfuscation_map ?? undefined),
394
+ sessionOrigin: row.session_origin || 'user',
395
+ userId: row.user_id ?? undefined,
396
+ ownerId: row.owner_id ?? undefined,
397
+ projectId: row.project_id ?? undefined,
398
+ // ADR-114: привязка к worktree (legacy-записи без поля → undefined).
399
+ ...(worktree ? { worktree } : {}),
400
+ messages: children.messages.map(deserializeMessage),
401
+ pendingMessages: (row.pending_messages ?? []).map(deserializeMessage),
402
+ steerInbox: (row.steer_inbox ?? []).map(deserializeMessage),
403
+ status: (row.status ?? {}),
404
+ settings: (row.settings ?? {}),
405
+ mcpServers: (row.mcp_servers ?? undefined),
406
+ checkpoints: children.checkpoints.map(deserializeCheckpoint),
407
+ stickyNotes: children.stickyNotes.map(deserializeStickyNote),
408
+ references: children.references.map(deserializeReference),
409
+ currentStream: currentStream
410
+ ? {
411
+ streamId: currentStream.stream_id,
412
+ message: currentStream.message,
413
+ agentRole: currentStream.agent_role,
414
+ startedAt: currentStream.started_at,
415
+ cancelled: currentStream.cancelled,
416
+ }
417
+ : undefined,
418
+ summarizationPending: row.summarization_pending ?? false,
419
+ canSummarize: row.can_summarize ?? false,
420
+ createdAt: toIso(row.created_at),
421
+ updatedAt: toIso(row.updated_at),
422
+ expiresAt: toIsoOrUndefined(row.expires_at),
423
+ archivedAt: toIsoOrUndefined(row.archived_at),
424
+ inputTokens: toNumber(row.input_tokens),
425
+ outputTokens: toNumber(row.output_tokens),
426
+ totalTokens: toNumber(row.total_tokens),
427
+ cacheReadTokens: toNumber(row.cache_read_tokens),
428
+ cacheWriteTokens: toNumber(row.cache_write_tokens),
429
+ reasoningTokens: toNumber(row.reasoning_tokens),
430
+ inputCost: toNumber(row.input_cost),
431
+ outputCost: toNumber(row.output_cost),
432
+ cacheReadCost: toNumber(row.cache_read_cost),
433
+ cacheWriteCost: toNumber(row.cache_write_cost),
434
+ cacheHitRate: toNumberOrUndefined(row.cache_hit_rate),
435
+ };
436
+ }
437
+ /**
438
+ * Строка `sessions` → доменная сессия **без истории** (`SessionRepository.listLight`,
439
+ * ADR-097): `messages`/`pendingMessages`/`checkpoints` пусты, child-таблицы не
440
+ * читаются. Метаданные (id/статус/settings/projectId/expiresAt/…) идентичны
441
+ * `deserializeSession` — механика переиспользуется.
442
+ */
443
+ export function deserializeSessionLight(row) {
444
+ const session = deserializeSession(row, emptySessionChildren());
445
+ session.messages = [];
446
+ session.pendingMessages = [];
447
+ session.checkpoints = [];
448
+ return session;
449
+ }
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Порт `SessionRepository` поверх PostgreSQL (ADR-097, волна 3b).
3
+ *
4
+ * Группа портов **сессий** PostgreSQL-драйвера: единственная фабрика
5
+ * `buildSessionPorts(deps)` собирает `StorageContext['sessions']`.
6
+ *
7
+ * Семантика — паритет с файловой (`FileStore`) и in-memory
8
+ * (`MemorySessionRepository`) реализациями:
9
+ * - `save` — **одна транзакция**: upsert строки `sessions` + **полная замена**
10
+ * child-таблиц (`messages`/`session_references`/`checkpoints`/`sticky_notes`):
11
+ * `DELETE … WHERE session_id` + массовый `INSERT` (по чанкам);
12
+ * - `appendMessage`/`updateMessage` — **точечные** операции над одной строкой
13
+ * `messages` в транзакции под тем же per-session advisory-локом, без
14
+ * перезаписи истории: append берёт `seq = MAX(seq)+1`, update целится по
15
+ * `seq` (fallback — `id`) и не меняет `id`/`seq`/`created_at`; обе операции
16
+ * обновляют `sessions.updated_at`;
17
+ * - `seq` сообщений — **позиционный**: при записи драйвер нормализует его по
18
+ * порядку массива `1..n`. Это снимает legacy-коллизию `UNIQUE (session_id, seq)`
19
+ * (у старых сессий у всех сообщений `seq = 0`) и делает порядок однозначным;
20
+ * домен и так переставляет `seq = i+1` при ветвлении/merge — приведение к
21
+ * позиции смысла не меняет;
22
+ * - `id` сообщения **не уникален** в пределах сессии (legacy-дубликаты):
23
+ * PK `messages` — суррогатный `message_uid`, поэтому дубликаты `id`
24
+ * сохраняются без потерь (upsert по `id` их молча схлопывал);
25
+ * - per-session сериализация записи — транзакционный `pg_advisory_xact_lock`
26
+ * (держится до `COMMIT`; аналог per-session `AsyncLock` файловой реализации);
27
+ * - чтения (`load`/`list`/`listForUser`/`listForUserScope`/`search`) отдают
28
+ * **полную** `Session`; сообщения/child-строки подгружаются **батчем**
29
+ * (`WHERE session_id = ANY($1)`, без N+1); порядок сообщений — по `seq` с
30
+ * тайбрейкером `created_at`, затем `id` (детерминированное чтение);
31
+ * - `listLight` — метаданные без истории (`messages`/`pendingMessages`/
32
+ * `checkpoints` пусты, child-таблицы не читаются): одна выборка из `sessions`
33
+ * тем же `WHERE`/порядком, что у `list`; `loadLight` — та же проекция по
34
+ * одному id (одна выборка по PK);
35
+ * - `list`/`listForUser*` сортируют `updated_at DESC`; архивированные сессии
36
+ * **не** отфильтровываются — это ответственность менеджера
37
+ * (`SessionManager.listSessions`, как и у файловой/memory реализаций);
38
+ * - `delete` отсутствующей — не ошибка; `load` отсутствующей → `null`;
39
+ * `list` пустого → `[]`; `addReference`/`removeReference` отсутствующей
40
+ * сессии → `throw`; `getReferences` отсутствующей → `[]`.
41
+ *
42
+ * `search` — подстрока без учёта регистра (`ILIKE`) по `title` и `content`
43
+ * сообщений; индекс `messages_content_trgm_idx` (`pg_trgm`) уже заведён в
44
+ * `001_init`. Символы `%`/`_`/`\` экранируются — семантика «подстрока», как у
45
+ * `includes` файловой/memory реализаций.
46
+ */
47
+ import type { PostgresConnection } from '../pool.js';
48
+ import type { Message, Session, SessionReference } from '@itphx/synth-shared';
49
+ import type { SessionFilter, SessionRepository, StorageContext } from '@itphx/synth-core';
50
+ import type { PortDeps } from './deps.js';
51
+ /** Часть `StorageContext`, которой владеет группа `sessions`. */
52
+ export type SessionPorts = Pick<StorageContext, 'sessions'>;
53
+ /**
54
+ * Колонки `sessions` (порядок — как в `001_init`).
55
+ *
56
+ * Экспортируется для unit-тестов сериализации (как `MESSAGE_MUTABLE_FIELDS`):
57
+ * тест проверяет, что новая колонка (`worktree`, ADR-114) реально попадает в
58
+ * `INSERT` и читается обратно.
59
+ */
60
+ 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", "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"];
61
+ /** jsonb-колонки `sessions` (экспортируется для unit-тестов сериализации). */
62
+ export declare const SESSION_JSON_FIELDS: ReadonlySet<string>;
63
+ /**
64
+ * Колонки `messages`, которые заменяет `updateMessage`. Неизменяемые —
65
+ * суррогатный `message_uid` (PK), доменный `id`, `session_id`, позиционный
66
+ * `seq` и `created_at`: они сохраняются от исходной строки (цель ищется по
67
+ * `seq`, fallback по `id`).
68
+ */
69
+ export declare const MESSAGE_MUTABLE_FIELDS: ("origin" | "author" | "source" | "usage" | "model" | "provider" | "metadata" | "ephemeral" | "disabled" | "content" | "role" | "reasoning" | "pinned" | "hidden" | "agent_role" | "source_msg_id" | "parts" | "tool_calls" | "tool_call_id" | "prompt_meta" | "debug_data" | "summary_of" | "provider_type" | "qa_pass" | "qa_reason")[];
70
+ /** Значение для jsonb-колонки: нативный объект/массив → JSON-строка (NUL — вычищены). */
71
+ export declare function jsonParam(value: unknown): string | null;
72
+ /**
73
+ * Значения строки в порядке колонок (jsonb — сериализуются, `undefined` → `NULL`).
74
+ * Экспортирован для unit-тестов сериализации (NUL не должен доходить до PG).
75
+ */
76
+ export declare function rowValues(row: Record<string, unknown>, fields: readonly string[], jsonFields: ReadonlySet<string>): unknown[];
77
+ /** `SessionRepository` поверх PostgreSQL. */
78
+ export declare class PostgresSessionRepository implements SessionRepository {
79
+ private readonly _connection;
80
+ constructor(_connection: PostgresConnection);
81
+ load(sessionId: string): Promise<Session | null>;
82
+ /**
83
+ * Запись сессии: одна транзакция, per-session advisory-лок, **полная замена**
84
+ * истории и child-таблиц. `seq` сообщений нормализуется позиционно (`1..n`),
85
+ * дубликаты `id` сохраняются как есть.
86
+ */
87
+ save(session: Session): Promise<void>;
88
+ /**
89
+ * Точечная дозапись сообщения (`SessionRepository.appendMessage`): одна
90
+ * транзакция + per-session advisory-лок (как у `save`), `seq = MAX(seq)+1`
91
+ * вычисляется в той же транзакции, `INSERT` одной строки, обновление
92
+ * `sessions.updated_at`. Остальная история не перезаписывается.
93
+ */
94
+ appendMessage(sessionId: string, message: Message): Promise<Message | null>;
95
+ /**
96
+ * Точечное обновление сообщения (`SessionRepository.updateMessage`): одна
97
+ * транзакция + per-session advisory-лок; цель — по `seq` (первая по
98
+ * `seq, created_at, id`), fallback по `id`. `message_uid`/`id`/`seq`/
99
+ * `created_at` исходной строки не меняются, `sessions.updated_at` обновляется.
100
+ */
101
+ updateMessage(sessionId: string, message: Message): Promise<Message | null>;
102
+ /**
103
+ * Метаданные сессии без истории (`SessionRepository.loadLight`): одна
104
+ * выборка по PK, child-таблицы не читаются.
105
+ */
106
+ loadLight(sessionId: string): Promise<Session | null>;
107
+ delete(sessionId: string): Promise<void>;
108
+ exists(sessionId: string): Promise<boolean>;
109
+ list(filter?: SessionFilter): Promise<Session[]>;
110
+ /**
111
+ * Лёгкий список (`SessionRepository.listLight`): тот же `WHERE`/порядок, что у
112
+ * `list`, но **без** батчевой подгрузки child-таблиц — сообщения/чекпоинты не
113
+ * читаются вовсе. SQL содержит только `FROM sessions` (для `filter.search`
114
+ * добавляется `EXISTS (SELECT 1 FROM messages …)` — подзапрос-предикат, не join).
115
+ */
116
+ listLight(filter?: SessionFilter): Promise<Session[]>;
117
+ /** Поиск по содержимому — тот же скан, что у `list` (паритет с файловой реализацией). */
118
+ search(query: string, filter?: SessionFilter): Promise<Session[]>;
119
+ listForUser(userId: string, ownerIds?: string[]): Promise<Session[]>;
120
+ /** «Свои + сессии проектов участия» (ADR-089); пустой `projectIds` → `listForUser`. */
121
+ listForUserScope(userId: string, projectIds: string[], ownerIds?: string[]): Promise<Session[]>;
122
+ addReference(sessionId: string, ref: SessionReference): Promise<void>;
123
+ removeReference(sessionId: string, refSessionId: string): Promise<void>;
124
+ getReferences(sessionId: string): Promise<SessionReference[]>;
125
+ /** Список по готовому `WHERE` + батчевая подгрузка child-данных. */
126
+ private _listByWhere;
127
+ /**
128
+ * Child-данные набора сессий — четыре запроса с `ANY($1)` (никакого N+1),
129
+ * `ORDER BY session_id, …` для стабильного порядка внутри каждой сессии.
130
+ */
131
+ private _loadChildren;
132
+ /**
133
+ * `message_uid` цели `updateMessage`: сначала по `seq` (при legacy-дублях —
134
+ * первая по `seq, created_at, id`), затем fallback по доменному `id`.
135
+ */
136
+ private _findMessageUid;
137
+ /** ADR-097: per-session сериализация записи — транзакционный advisory-лок. */
138
+ private _lockSession;
139
+ /** `addReference`/`removeReference` отсутствующей сессии → ошибка (как в file/memory). */
140
+ private _assertSessionExists;
141
+ }
142
+ /** Собрать порты группы `sessions`. */
143
+ export declare function buildSessionPorts(deps: PortDeps): SessionPorts;