@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,517 @@
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 { jsonbParam } from '../json-param.js';
48
+ import { generateId, makeTextPart, nowISO } from '@itphx/synth-shared';
49
+ import { checkpointRow, deserializeMessage, deserializeReference, deserializeSession, deserializeSessionLight, emptySessionChildren, messageRow, referenceRow, serializeSession, stickyNoteRow, } from './sessions-mapping.js';
50
+ /**
51
+ * Колонки `sessions` (порядок — как в `001_init`).
52
+ *
53
+ * Экспортируется для unit-тестов сериализации (как `MESSAGE_MUTABLE_FIELDS`):
54
+ * тест проверяет, что новая колонка (`worktree`, ADR-114) реально попадает в
55
+ * `INSERT` и читается обратно.
56
+ */
57
+ export const SESSION_FIELDS = [
58
+ 'id',
59
+ 'title',
60
+ 'icon',
61
+ 'color',
62
+ 'session_origin',
63
+ 'parent_id',
64
+ 'branch_point',
65
+ 'plan_approved',
66
+ 'mode',
67
+ 'mode_by_principal',
68
+ 'user_id',
69
+ 'owner_id',
70
+ 'project_id',
71
+ // ADR-114: привязка сессии к worktree (jsonb, миграция 023).
72
+ 'worktree',
73
+ 'todos',
74
+ 'prompt_states',
75
+ 'obfuscation_map',
76
+ 'status',
77
+ 'settings',
78
+ 'mcp_servers',
79
+ 'pending_messages',
80
+ 'steer_inbox',
81
+ 'current_stream',
82
+ 'summarization_pending',
83
+ 'can_summarize',
84
+ 'created_at',
85
+ 'updated_at',
86
+ 'expires_at',
87
+ 'archived_at',
88
+ 'input_tokens',
89
+ 'output_tokens',
90
+ 'total_tokens',
91
+ 'cache_read_tokens',
92
+ 'cache_write_tokens',
93
+ 'reasoning_tokens',
94
+ 'input_cost',
95
+ 'output_cost',
96
+ 'cache_read_cost',
97
+ 'cache_write_cost',
98
+ 'cache_hit_rate',
99
+ ];
100
+ /** jsonb-колонки `sessions` (экспортируется для unit-тестов сериализации). */
101
+ export const SESSION_JSON_FIELDS = new Set([
102
+ 'mode_by_principal',
103
+ // ADR-114: привязка сессии к worktree (jsonb, миграция 023).
104
+ 'worktree',
105
+ 'todos',
106
+ 'prompt_states',
107
+ 'obfuscation_map',
108
+ 'status',
109
+ 'settings',
110
+ 'mcp_servers',
111
+ 'pending_messages',
112
+ 'steer_inbox',
113
+ 'current_stream',
114
+ ]);
115
+ /** Колонки `messages` (порядок — как в `001_init`). */
116
+ const MESSAGE_FIELDS = [
117
+ 'id',
118
+ 'session_id',
119
+ 'seq',
120
+ 'role',
121
+ 'origin',
122
+ 'source_msg_id',
123
+ 'content',
124
+ 'parts',
125
+ 'tool_calls',
126
+ 'tool_call_id',
127
+ 'usage',
128
+ 'metadata',
129
+ 'prompt_meta',
130
+ 'debug_data',
131
+ 'summary_of',
132
+ 'model',
133
+ 'provider',
134
+ 'provider_type',
135
+ 'reasoning',
136
+ 'source',
137
+ 'author',
138
+ 'agent_role',
139
+ 'qa_pass',
140
+ 'qa_reason',
141
+ 'disabled',
142
+ 'pinned',
143
+ 'hidden',
144
+ 'ephemeral',
145
+ 'created_at',
146
+ ];
147
+ const MESSAGE_JSON_FIELDS = new Set([
148
+ 'parts',
149
+ 'tool_calls',
150
+ 'usage',
151
+ 'metadata',
152
+ 'prompt_meta',
153
+ 'debug_data',
154
+ 'summary_of',
155
+ ]);
156
+ /**
157
+ * Колонки `messages`, которые заменяет `updateMessage`. Неизменяемые —
158
+ * суррогатный `message_uid` (PK), доменный `id`, `session_id`, позиционный
159
+ * `seq` и `created_at`: они сохраняются от исходной строки (цель ищется по
160
+ * `seq`, fallback по `id`).
161
+ */
162
+ export const MESSAGE_MUTABLE_FIELDS = MESSAGE_FIELDS.filter((field) => field !== 'id' && field !== 'session_id' && field !== 'seq' && field !== 'created_at');
163
+ /** Обязательные поля сообщения: безопасные дефолты (паритет с file/memory). */
164
+ function prepareMessage(message) {
165
+ return {
166
+ ...message,
167
+ id: message.id || generateId(),
168
+ origin: message.origin || 'local',
169
+ parts: message.parts && message.parts.length > 0
170
+ ? message.parts
171
+ : [makeTextPart(message.content ?? '')],
172
+ createdAt: message.createdAt || nowISO(),
173
+ };
174
+ }
175
+ const REFERENCE_FIELDS = [
176
+ 'id',
177
+ 'session_id',
178
+ 'ref_session_id',
179
+ 'label',
180
+ 'message_range',
181
+ 'auto_summary',
182
+ 'ordinal',
183
+ 'created_at',
184
+ ];
185
+ const REFERENCE_JSON_FIELDS = new Set(['message_range']);
186
+ const CHECKPOINT_FIELDS = ['id', 'session_id', 'messages', 'created_at'];
187
+ const CHECKPOINT_JSON_FIELDS = new Set(['messages']);
188
+ const NOTE_FIELDS = ['id', 'session_id', 'content', 'disabled', 'created_at', 'updated_at'];
189
+ const NOTE_JSON_FIELDS = new Set();
190
+ /** Размер пакета строк в одном `INSERT` (лимит параметров протокола — 65535). */
191
+ const INSERT_CHUNK_SIZE = 200;
192
+ /** Значение для jsonb-колонки: нативный объект/массив → JSON-строка (NUL — вычищены). */
193
+ export function jsonParam(value) {
194
+ return jsonbParam(value);
195
+ }
196
+ /**
197
+ * Значения строки в порядке колонок (jsonb — сериализуются, `undefined` → `NULL`).
198
+ * Экспортирован для unit-тестов сериализации (NUL не должен доходить до PG).
199
+ */
200
+ export function rowValues(row, fields, jsonFields) {
201
+ return fields.map((field) => (jsonFields.has(field) ? jsonParam(row[field]) : row[field] ?? null));
202
+ }
203
+ /** Экранирование спецсимволов `LIKE` — подстрока ищется буквально. */
204
+ function escapeLike(value) {
205
+ return value.replace(/[\\%_]/g, (char) => `\\${char}`);
206
+ }
207
+ /** Пакетный upsert строк (по частям, чтобы не упираться в лимит параметров). */
208
+ async function upsertRows(tx, table, fields, rows, jsonFields, conflictKey) {
209
+ if (rows.length === 0)
210
+ return;
211
+ const updatable = fields.filter((field) => !conflictKey.includes(field));
212
+ const conflictAction = updatable.length > 0
213
+ ? `DO UPDATE SET ${updatable.map((field) => `${field} = EXCLUDED.${field}`).join(', ')}`
214
+ : 'DO NOTHING';
215
+ for (let offset = 0; offset < rows.length; offset += INSERT_CHUNK_SIZE) {
216
+ const chunk = rows.slice(offset, offset + INSERT_CHUNK_SIZE);
217
+ const valuesSql = chunk
218
+ .map((_row, rowIndex) => `(${fields.map((_field, colIndex) => `$${rowIndex * fields.length + colIndex + 1}`).join(', ')})`)
219
+ .join(', ');
220
+ const params = chunk.flatMap((row) => rowValues(row, fields, jsonFields));
221
+ await tx.query(`INSERT INTO ${table} (${fields.join(', ')}) VALUES ${valuesSql} ` +
222
+ `ON CONFLICT (${conflictKey.join(', ')}) ${conflictAction}`, params);
223
+ }
224
+ }
225
+ /**
226
+ * Пакетный `INSERT` строк без `ON CONFLICT` (по частям, чтобы не упираться в
227
+ * лимит параметров). Вызывается после `DELETE … WHERE session_id` — полная
228
+ * замена child-строк в той же транзакции.
229
+ */
230
+ async function insertRows(tx, table, fields, rows, jsonFields) {
231
+ if (rows.length === 0)
232
+ return;
233
+ for (let offset = 0; offset < rows.length; offset += INSERT_CHUNK_SIZE) {
234
+ const chunk = rows.slice(offset, offset + INSERT_CHUNK_SIZE);
235
+ const valuesSql = chunk
236
+ .map((_row, rowIndex) => `(${fields.map((_field, colIndex) => `$${rowIndex * fields.length + colIndex + 1}`).join(', ')})`)
237
+ .join(', ');
238
+ const params = chunk.flatMap((row) => rowValues(row, fields, jsonFields));
239
+ await tx.query(`INSERT INTO ${table} (${fields.join(', ')}) VALUES ${valuesSql}`, params);
240
+ }
241
+ }
242
+ /** Полная замена child-строк сессии: `DELETE` + массовый `INSERT`. */
243
+ async function replaceRows(tx, table, fields, rows, jsonFields, sessionId) {
244
+ await tx.query(`DELETE FROM ${table} WHERE session_id = $1`, [sessionId]);
245
+ await insertRows(tx, table, fields, rows, jsonFields);
246
+ }
247
+ /** `WHERE` для `list`/`search` (фильтры — по колонкам `sessions`). */
248
+ function buildListWhere(filter) {
249
+ const conditions = [];
250
+ const params = [];
251
+ if (filter?.projectId) {
252
+ params.push(filter.projectId);
253
+ conditions.push(`s.project_id = $${params.length}`);
254
+ }
255
+ if (filter?.userId) {
256
+ params.push(filter.userId);
257
+ conditions.push(`s.user_id = $${params.length}`);
258
+ }
259
+ if (filter?.parentId !== undefined) {
260
+ if (filter.parentId === null) {
261
+ conditions.push('s.parent_id IS NULL');
262
+ }
263
+ else {
264
+ params.push(filter.parentId);
265
+ conditions.push(`s.parent_id = $${params.length}`);
266
+ }
267
+ }
268
+ if (filter?.search) {
269
+ params.push(`%${escapeLike(filter.search)}%`);
270
+ const pattern = `$${params.length}`;
271
+ conditions.push(`(s.title ILIKE ${pattern} OR EXISTS (` +
272
+ `SELECT 1 FROM messages m WHERE m.session_id = s.id AND m.content ILIKE ${pattern}))`);
273
+ }
274
+ return { sql: conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '', params };
275
+ }
276
+ /** `SessionRepository` поверх PostgreSQL. */
277
+ export class PostgresSessionRepository {
278
+ _connection;
279
+ constructor(_connection) {
280
+ this._connection = _connection;
281
+ }
282
+ async load(sessionId) {
283
+ const rows = await this._connection.query('SELECT * FROM sessions WHERE id = $1', [sessionId]);
284
+ const row = rows[0];
285
+ if (!row)
286
+ return null;
287
+ const children = await this._loadChildren([sessionId]);
288
+ return deserializeSession(row, children.get(sessionId) ?? emptySessionChildren());
289
+ }
290
+ /**
291
+ * Запись сессии: одна транзакция, per-session advisory-лок, **полная замена**
292
+ * истории и child-таблиц. `seq` сообщений нормализуется позиционно (`1..n`),
293
+ * дубликаты `id` сохраняются как есть.
294
+ */
295
+ async save(session) {
296
+ const sessionRow = serializeSession(session);
297
+ // `seq` — позиция сообщения в массиве (`1..n`): снимает legacy-коллизию
298
+ // `UNIQUE (session_id, seq)` (у старых сессий `seq = 0` у всех) и делает
299
+ // порядок однозначным. Дубликаты `id` сообщений сохраняются (PK — суррогатный).
300
+ const messageRows = (session.messages ?? []).map((msg, index) => messageRow(msg, session.id, index + 1));
301
+ const referenceRows = (session.references ?? []).map((ref, index) => referenceRow(session.id, ref, index));
302
+ const checkpointRows = (session.checkpoints ?? []).map(checkpointRow);
303
+ const noteRows = (session.stickyNotes ?? []).map((note) => stickyNoteRow(session.id, note));
304
+ await this._connection.withTransaction(async (tx) => {
305
+ await this._lockSession(tx, session.id);
306
+ await upsertRows(tx, 'sessions', SESSION_FIELDS, [sessionRow], SESSION_JSON_FIELDS, ['id']);
307
+ // Сообщения — полная замена в той же транзакции: `DELETE` + массовый
308
+ // `INSERT`. Дубликаты `id` допустимы (суррогатный PK `message_uid`);
309
+ // уникальность `(session_id, seq)` выполняется по построению (позиция).
310
+ await replaceRows(tx, 'messages', MESSAGE_FIELDS, messageRows, MESSAGE_JSON_FIELDS, session.id);
311
+ // Ссылки — полная замена (паритет с файловой реализацией: `save`
312
+ // перезаписывает `session.references` целиком); `id`/`ordinal` — свежие,
313
+ // дубликаты одной `ref_session_id` допустимы (разные диапазоны).
314
+ await replaceRows(tx, 'session_references', REFERENCE_FIELDS, referenceRows, REFERENCE_JSON_FIELDS, session.id);
315
+ await replaceRows(tx, 'checkpoints', CHECKPOINT_FIELDS, checkpointRows, CHECKPOINT_JSON_FIELDS, session.id);
316
+ await replaceRows(tx, 'sticky_notes', NOTE_FIELDS, noteRows, NOTE_JSON_FIELDS, session.id);
317
+ });
318
+ }
319
+ /**
320
+ * Точечная дозапись сообщения (`SessionRepository.appendMessage`): одна
321
+ * транзакция + per-session advisory-лок (как у `save`), `seq = MAX(seq)+1`
322
+ * вычисляется в той же транзакции, `INSERT` одной строки, обновление
323
+ * `sessions.updated_at`. Остальная история не перезаписывается.
324
+ */
325
+ async appendMessage(sessionId, message) {
326
+ const prepared = prepareMessage(message);
327
+ return this._connection.withTransaction(async (tx) => {
328
+ await this._lockSession(tx, sessionId);
329
+ const present = await tx.query('SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1) AS present', [sessionId]);
330
+ if (present[0]?.present !== true)
331
+ return null;
332
+ const next = await tx.query('SELECT COALESCE(MAX(seq), 0) + 1 AS seq FROM messages WHERE session_id = $1', [sessionId]);
333
+ const seq = Number(next[0]?.seq ?? 1);
334
+ const row = messageRow(prepared, sessionId, seq);
335
+ const placeholders = MESSAGE_FIELDS.map((_, index) => `$${index + 1}`).join(', ');
336
+ const inserted = await tx.query(`INSERT INTO messages (${MESSAGE_FIELDS.join(', ')}) VALUES (${placeholders}) RETURNING *`, rowValues(row, MESSAGE_FIELDS, MESSAGE_JSON_FIELDS));
337
+ await tx.query('UPDATE sessions SET updated_at = now() WHERE id = $1', [sessionId]);
338
+ const insertedRow = inserted[0];
339
+ return insertedRow ? deserializeMessage(insertedRow) : null;
340
+ });
341
+ }
342
+ /**
343
+ * Точечное обновление сообщения (`SessionRepository.updateMessage`): одна
344
+ * транзакция + per-session advisory-лок; цель — по `seq` (первая по
345
+ * `seq, created_at, id`), fallback по `id`. `message_uid`/`id`/`seq`/
346
+ * `created_at` исходной строки не меняются, `sessions.updated_at` обновляется.
347
+ */
348
+ async updateMessage(sessionId, message) {
349
+ const prepared = prepareMessage(message);
350
+ const row = messageRow(prepared, sessionId, prepared.seq);
351
+ const setSql = MESSAGE_MUTABLE_FIELDS
352
+ .map((field, index) => `${field} = $${index + 1}`)
353
+ .join(', ');
354
+ const params = rowValues(row, MESSAGE_MUTABLE_FIELDS, MESSAGE_JSON_FIELDS);
355
+ return this._connection.withTransaction(async (tx) => {
356
+ await this._lockSession(tx, sessionId);
357
+ const messageUid = await this._findMessageUid(tx, sessionId, prepared);
358
+ if (!messageUid)
359
+ return null;
360
+ const updated = await tx.query(`UPDATE messages SET ${setSql} WHERE message_uid = $${params.length + 1} RETURNING *`, [...params, messageUid]);
361
+ await tx.query('UPDATE sessions SET updated_at = now() WHERE id = $1', [sessionId]);
362
+ const updatedRow = updated[0];
363
+ return updatedRow ? deserializeMessage(updatedRow) : null;
364
+ });
365
+ }
366
+ /**
367
+ * Метаданные сессии без истории (`SessionRepository.loadLight`): одна
368
+ * выборка по PK, child-таблицы не читаются.
369
+ */
370
+ async loadLight(sessionId) {
371
+ const rows = await this._connection.query('SELECT * FROM sessions WHERE id = $1', [sessionId]);
372
+ const row = rows[0];
373
+ return row ? deserializeSessionLight(row) : null;
374
+ }
375
+ async delete(sessionId) {
376
+ await this._connection.withTransaction(async (tx) => {
377
+ await this._lockSession(tx, sessionId);
378
+ // Child-таблицы уходят каскадом (`ON DELETE CASCADE`).
379
+ await tx.query('DELETE FROM sessions WHERE id = $1', [sessionId]);
380
+ });
381
+ }
382
+ async exists(sessionId) {
383
+ const rows = await this._connection.query('SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1) AS present', [sessionId]);
384
+ return rows[0]?.present === true;
385
+ }
386
+ async list(filter) {
387
+ const { sql, params } = buildListWhere(filter);
388
+ return this._listByWhere(sql, params);
389
+ }
390
+ /**
391
+ * Лёгкий список (`SessionRepository.listLight`): тот же `WHERE`/порядок, что у
392
+ * `list`, но **без** батчевой подгрузки child-таблиц — сообщения/чекпоинты не
393
+ * читаются вовсе. SQL содержит только `FROM sessions` (для `filter.search`
394
+ * добавляется `EXISTS (SELECT 1 FROM messages …)` — подзапрос-предикат, не join).
395
+ */
396
+ async listLight(filter) {
397
+ const { sql, params } = buildListWhere(filter);
398
+ const rows = await this._connection.query(`SELECT s.* FROM sessions s ${sql} ORDER BY s.updated_at DESC, s.id ASC`, params);
399
+ return rows.map(deserializeSessionLight);
400
+ }
401
+ /** Поиск по содержимому — тот же скан, что у `list` (паритет с файловой реализацией). */
402
+ async search(query, filter) {
403
+ return this.list({ ...filter, search: query });
404
+ }
405
+ async listForUser(userId, ownerIds = []) {
406
+ // `ownerIds` — дополнительные id владельца (legacy-UUID профиля `local`, ADR-089).
407
+ const ids = [userId, ...ownerIds];
408
+ return this._listByWhere('WHERE (s.user_id = ANY($1::text[]) OR s.owner_id = ANY($1::text[]))', [ids]);
409
+ }
410
+ /** «Свои + сессии проектов участия» (ADR-089); пустой `projectIds` → `listForUser`. */
411
+ async listForUserScope(userId, projectIds, ownerIds = []) {
412
+ if (projectIds.length === 0)
413
+ return this.listForUser(userId, ownerIds);
414
+ const ids = [userId, ...ownerIds];
415
+ return this._listByWhere('WHERE ((s.user_id = ANY($1::text[]) OR s.owner_id = ANY($1::text[])) '
416
+ + 'OR s.project_id = ANY($2::text[]))', [ids, projectIds]);
417
+ }
418
+ async addReference(sessionId, ref) {
419
+ await this._connection.withTransaction(async (tx) => {
420
+ await this._lockSession(tx, sessionId);
421
+ await this._assertSessionExists(tx, sessionId);
422
+ // Append (дубликаты разрешены): новая ссылка получает следующий `ordinal`.
423
+ const next = await tx.query('SELECT COALESCE(MAX(ordinal), -1) + 1 AS ordinal FROM session_references WHERE session_id = $1', [sessionId]);
424
+ const ordinal = Number(next[0]?.ordinal ?? 0);
425
+ await tx.query(`INSERT INTO session_references
426
+ (${REFERENCE_FIELDS.join(', ')})
427
+ VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8)`, rowValues(referenceRow(sessionId, ref, ordinal), REFERENCE_FIELDS, REFERENCE_JSON_FIELDS));
428
+ });
429
+ }
430
+ async removeReference(sessionId, refSessionId) {
431
+ await this._connection.withTransaction(async (tx) => {
432
+ await this._lockSession(tx, sessionId);
433
+ await this._assertSessionExists(tx, sessionId);
434
+ // Удаляются **все** совпадения (паритет с file/memory: `filter` по refSessionId).
435
+ await tx.query('DELETE FROM session_references WHERE session_id = $1 AND ref_session_id = $2', [sessionId, refSessionId]);
436
+ });
437
+ }
438
+ async getReferences(sessionId) {
439
+ if (!(await this.exists(sessionId)))
440
+ return [];
441
+ const rows = await this._connection.query('SELECT * FROM session_references WHERE session_id = $1 ORDER BY ordinal', [sessionId]);
442
+ return rows.map(deserializeReference);
443
+ }
444
+ /** Список по готовому `WHERE` + батчевая подгрузка child-данных. */
445
+ async _listByWhere(whereSql, params) {
446
+ const rows = await this._connection.query(`SELECT s.* FROM sessions s ${whereSql} ORDER BY s.updated_at DESC, s.id ASC`, params);
447
+ if (rows.length === 0)
448
+ return [];
449
+ const children = await this._loadChildren(rows.map((row) => row.id));
450
+ return rows.map((row) => deserializeSession(row, children.get(row.id) ?? emptySessionChildren()));
451
+ }
452
+ /**
453
+ * Child-данные набора сессий — четыре запроса с `ANY($1)` (никакого N+1),
454
+ * `ORDER BY session_id, …` для стабильного порядка внутри каждой сессии.
455
+ */
456
+ async _loadChildren(sessionIds) {
457
+ const buckets = new Map();
458
+ for (const sessionId of sessionIds)
459
+ buckets.set(sessionId, emptySessionChildren());
460
+ if (sessionIds.length === 0)
461
+ return buckets;
462
+ const [messages, references, checkpoints, notes] = await Promise.all([
463
+ this._connection.query('SELECT * FROM messages WHERE session_id = ANY($1::text[]) '
464
+ + 'ORDER BY session_id, seq, created_at, id', [sessionIds]),
465
+ this._connection.query('SELECT * FROM session_references WHERE session_id = ANY($1::text[]) '
466
+ + 'ORDER BY session_id, ordinal', [sessionIds]),
467
+ this._connection.query('SELECT * FROM checkpoints WHERE session_id = ANY($1::text[]) '
468
+ + 'ORDER BY session_id, created_at, id', [sessionIds]),
469
+ this._connection.query('SELECT * FROM sticky_notes WHERE session_id = ANY($1::text[]) '
470
+ + 'ORDER BY session_id, created_at, id', [sessionIds]),
471
+ ]);
472
+ for (const row of messages)
473
+ buckets.get(row.session_id ?? '')?.messages.push(row);
474
+ for (const row of references)
475
+ buckets.get(row.session_id)?.references.push(row);
476
+ for (const row of checkpoints)
477
+ buckets.get(row.session_id)?.checkpoints.push(row);
478
+ for (const row of notes)
479
+ buckets.get(row.session_id)?.stickyNotes.push(row);
480
+ return buckets;
481
+ }
482
+ /**
483
+ * `message_uid` цели `updateMessage`: сначала по `seq` (при legacy-дублях —
484
+ * первая по `seq, created_at, id`), затем fallback по доменному `id`.
485
+ */
486
+ async _findMessageUid(tx, sessionId, message) {
487
+ if (Number.isFinite(message.seq)) {
488
+ const rows = await tx.query('SELECT message_uid FROM messages WHERE session_id = $1 AND seq = $2 '
489
+ + 'ORDER BY seq, created_at, id LIMIT 1', [sessionId, message.seq]);
490
+ if (rows[0])
491
+ return rows[0].message_uid;
492
+ }
493
+ if (message.id) {
494
+ const rows = await tx.query('SELECT message_uid FROM messages WHERE session_id = $1 AND id = $2 '
495
+ + 'ORDER BY seq, created_at, id LIMIT 1', [sessionId, message.id]);
496
+ if (rows[0])
497
+ return rows[0].message_uid;
498
+ }
499
+ return null;
500
+ }
501
+ /** ADR-097: per-session сериализация записи — транзакционный advisory-лок. */
502
+ async _lockSession(tx, sessionId) {
503
+ await tx.query('SELECT pg_advisory_xact_lock(hashtext($1::text)::bigint)', [sessionId]);
504
+ }
505
+ /** `addReference`/`removeReference` отсутствующей сессии → ошибка (как в file/memory). */
506
+ async _assertSessionExists(tx, sessionId) {
507
+ const rows = await tx.query('SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1) AS present', [sessionId]);
508
+ if (rows[0]?.present !== true)
509
+ throw new Error(`Session ${sessionId} not found`);
510
+ }
511
+ }
512
+ /** Собрать порты группы `sessions`. */
513
+ export function buildSessionPorts(deps) {
514
+ return {
515
+ sessions: new PostgresSessionRepository(deps.connection),
516
+ };
517
+ }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * PG-реализация порта **instance-скиллов** (ADR-046 §4, ADR-116, ADR-097).
3
+ *
4
+ * Разделение хранения (ADR-116 §«Что переводится»):
5
+ * - **метаданные** (заголовок `SKILL.md` — `name`/`description`/прочие ключи) —
6
+ * таблица `instance_skills` (миграция `026_instance_skills`): имя — ключ,
7
+ * `frontmatter` jsonb, `updated_at` — служебная метка записи;
8
+ * - **содержимое** (`SKILL.md` и supporting-файлы) — blob-стор под
9
+ * `skills/<name>/SKILL.md` и `skills/<name>/<relPath>` (`BlobStore` остаётся
10
+ * файловым по конструкции, ADR-116 §2).
11
+ *
12
+ * Порт не отдаёт путей (ADR-116): домен работает через `listFiles`/`readFile`/
13
+ * `writeFile`, раскладка blob-стора — деталь этой реализации.
14
+ *
15
+ * Семантика повторяет файловую реализацию core (`SkillStore`) и in-memory
16
+ * (`MemorySkillRepository`):
17
+ * - `create` — ошибка на дубль имени; `frontmatter` входа сохраняется, ключи
18
+ * `name`/`description` берутся из входа;
19
+ * - `updateMarkdown` — перезапись заголовка с сохранением прочих ключей;
20
+ * - `remove` — удаление записи и **всех** объектов скилла в blob-сторе;
21
+ * - `listFiles` — supporting-файлы (без `SKILL.md`), относительные пути, размеры
22
+ * в байтах, порядок по пути;
23
+ * - небезопасные относительные пути (`..`, абсолютные, `\`) не читаются и не
24
+ * пишутся.
25
+ *
26
+ * Порядок записи: сначала содержимое (`BlobStore`), затем метаданные — при сбое
27
+ * второй записи «висящих» записей в таблице не остаётся (лишние объекты
28
+ * blob-стора безвредны: их видно только через `listFiles` существующего скилла).
29
+ */
30
+ import type { BlobStore, CreateSkillInput, SkillRepository, StorageContext, UpdateSkillMarkdownInput } from '@itphx/synth-core';
31
+ import type { PortDeps } from './deps.js';
32
+ /** Часть `StorageContext`, которой владеет группа «skills». */
33
+ export type SkillPorts = Pick<StorageContext, 'skills'>;
34
+ /**
35
+ * ADR-116: instance-скиллы — метаданные в `instance_skills`, содержимое в
36
+ * `BlobStore`.
37
+ */
38
+ export declare class PgSkillRepository implements SkillRepository {
39
+ private readonly _deps;
40
+ private readonly _blobs;
41
+ constructor(_deps: PortDeps, _blobs: BlobStore);
42
+ exists(name: string): Promise<boolean>;
43
+ listNames(): Promise<string[]>;
44
+ readMarkdown(name: string): Promise<string | null>;
45
+ create(input: CreateSkillInput): Promise<void>;
46
+ updateMarkdown(name: string, patch: UpdateSkillMarkdownInput): Promise<void>;
47
+ remove(name: string): Promise<boolean>;
48
+ readFile(name: string, relPath: string): Promise<string | null>;
49
+ writeFile(name: string, relPath: string, content: string): Promise<void>;
50
+ deleteFile(name: string, relPath: string): Promise<boolean>;
51
+ listFiles(name: string): Promise<Array<{
52
+ path: string;
53
+ size: number;
54
+ }>>;
55
+ /** Upsert метаданных: заголовок скилла и служебная метка записи. */
56
+ private _upsertMetadata;
57
+ }
58
+ /** Собрать порт instance-скиллов (ADR-046 §4, ADR-116). */
59
+ export declare function buildSkillPorts(deps: PortDeps, blobs: BlobStore): SkillPorts;