@itphx/synth-storage-postgres 0.11.3 → 0.13.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 (147) hide show
  1. package/dist/errors.d.ts +1 -1
  2. package/dist/errors.js +2 -2
  3. package/dist/index.d.ts +15 -1
  4. package/dist/index.js +24 -2
  5. package/dist/locks.d.ts +4 -4
  6. package/dist/locks.js +4 -4
  7. package/dist/migrate.d.ts +1 -1
  8. package/dist/migrate.js +1 -1
  9. package/dist/migrations/001-init.d.ts +2 -2
  10. package/dist/migrations/001-init.js +2 -2
  11. package/dist/migrations/003-analytics-rollups.d.ts +1 -1
  12. package/dist/migrations/003-analytics-rollups.js +1 -1
  13. package/dist/migrations/004-pipeline-engine.d.ts +19 -0
  14. package/dist/migrations/004-pipeline-engine.js +74 -0
  15. package/dist/migrations/005-pipeline-provenance.d.ts +12 -0
  16. package/dist/migrations/005-pipeline-provenance.js +15 -0
  17. package/dist/migrations/006-plugin-audit.d.ts +13 -0
  18. package/dist/migrations/006-plugin-audit.js +34 -0
  19. package/dist/migrations/007-plugin-lock.d.ts +10 -0
  20. package/dist/migrations/007-plugin-lock.js +25 -0
  21. package/dist/migrations/008-plugin-audit-scan.d.ts +11 -0
  22. package/dist/migrations/008-plugin-audit-scan.js +15 -0
  23. package/dist/migrations/009-plugin-lock-previous.d.ts +13 -0
  24. package/dist/migrations/009-plugin-lock-previous.js +16 -0
  25. package/dist/migrations/010-plugin-lock-mode.d.ts +16 -0
  26. package/dist/migrations/010-plugin-lock-mode.js +20 -0
  27. package/dist/migrations/011-session-steer-inbox.d.ts +11 -0
  28. package/dist/migrations/011-session-steer-inbox.js +14 -0
  29. package/dist/migrations/012-external-credentials.d.ts +15 -0
  30. package/dist/migrations/012-external-credentials.js +40 -0
  31. package/dist/migrations/013-service-key-plugin-id.d.ts +17 -0
  32. package/dist/migrations/013-service-key-plugin-id.js +20 -0
  33. package/dist/migrations/014-session-mode-by-principal.d.ts +12 -0
  34. package/dist/migrations/014-session-mode-by-principal.js +15 -0
  35. package/dist/migrations/015-authority.d.ts +17 -0
  36. package/dist/migrations/015-authority.js +43 -0
  37. package/dist/migrations/016-credential-audit.d.ts +17 -0
  38. package/dist/migrations/016-credential-audit.js +32 -0
  39. package/dist/migrations/017-memory.d.ts +29 -0
  40. package/dist/migrations/017-memory.js +95 -0
  41. package/dist/migrations/018-memory-index-scope.d.ts +14 -0
  42. package/dist/migrations/018-memory-index-scope.js +18 -0
  43. package/dist/migrations/019-memory-index-enabled.d.ts +11 -0
  44. package/dist/migrations/019-memory-index-enabled.js +14 -0
  45. package/dist/migrations/020-project-memory.d.ts +11 -0
  46. package/dist/migrations/020-project-memory.js +13 -0
  47. package/dist/migrations/021-background-runs.d.ts +17 -0
  48. package/dist/migrations/021-background-runs.js +67 -0
  49. package/dist/migrations/022-background-run-process-id.d.ts +14 -0
  50. package/dist/migrations/022-background-run-process-id.js +18 -0
  51. package/dist/migrations/023-session-worktree.d.ts +12 -0
  52. package/dist/migrations/023-session-worktree.js +16 -0
  53. package/dist/migrations/024-blob-refs.d.ts +15 -0
  54. package/dist/migrations/024-blob-refs.js +26 -0
  55. package/dist/migrations/025-packs-pipelines.d.ts +28 -0
  56. package/dist/migrations/025-packs-pipelines.js +82 -0
  57. package/dist/migrations/026-instance-skills.d.ts +17 -0
  58. package/dist/migrations/026-instance-skills.js +25 -0
  59. package/dist/migrations/027-context-files.d.ts +20 -0
  60. package/dist/migrations/027-context-files.js +30 -0
  61. package/dist/migrations/028-message-reasoning-signature.d.ts +13 -0
  62. package/dist/migrations/028-message-reasoning-signature.js +19 -0
  63. package/dist/migrations/029-message-stream-v2.d.ts +22 -0
  64. package/dist/migrations/029-message-stream-v2.js +33 -0
  65. package/dist/migrations/030-session-retry.d.ts +12 -0
  66. package/dist/migrations/030-session-retry.js +16 -0
  67. package/dist/migrations/index.d.ts +1 -1
  68. package/dist/migrations/index.js +55 -1
  69. package/dist/pool.d.ts +6 -6
  70. package/dist/pool.js +8 -8
  71. package/dist/ports/analytics.d.ts +1 -1
  72. package/dist/ports/analytics.js +1 -1
  73. package/dist/ports/audit.d.ts +1 -1
  74. package/dist/ports/audit.js +3 -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 +1 -1
  82. package/dist/ports/content.js +21 -7
  83. package/dist/ports/context-files.d.ts +147 -0
  84. package/dist/ports/context-files.js +285 -0
  85. package/dist/ports/core-sync.d.ts +1 -1
  86. package/dist/ports/core-sync.js +1 -1
  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 +2 -2
  90. package/dist/ports/deps.js +1 -1
  91. package/dist/ports/events-bindings.d.ts +2 -2
  92. package/dist/ports/events-bindings.js +2 -2
  93. package/dist/ports/events-core.d.ts +1 -1
  94. package/dist/ports/events-core.js +1 -1
  95. package/dist/ports/events-journal.d.ts +1 -1
  96. package/dist/ports/events-journal.js +1 -1
  97. package/dist/ports/events-scheduler.d.ts +1 -1
  98. package/dist/ports/events-scheduler.js +20 -12
  99. package/dist/ports/events-webhooks.d.ts +1 -1
  100. package/dist/ports/events-webhooks.js +1 -1
  101. package/dist/ports/events.d.ts +1 -1
  102. package/dist/ports/events.js +1 -1
  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 +1 -1
  118. package/dist/ports/principals-defaults.js +21 -1
  119. package/dist/ports/principals-documents.d.ts +1 -1
  120. package/dist/ports/principals-documents.js +1 -1
  121. package/dist/ports/principals-profiles.d.ts +1 -1
  122. package/dist/ports/principals-profiles.js +1 -1
  123. package/dist/ports/principals-projects.d.ts +1 -1
  124. package/dist/ports/principals-projects.js +82 -47
  125. package/dist/ports/principals-settings.d.ts +1 -1
  126. package/dist/ports/principals-settings.js +57 -1
  127. package/dist/ports/principals-shared.d.ts +1 -1
  128. package/dist/ports/principals-shared.js +1 -1
  129. package/dist/ports/principals.d.ts +1 -1
  130. package/dist/ports/principals.js +1 -1
  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 +80 -6
  134. package/dist/ports/sessions-mapping.js +165 -8
  135. package/dist/ports/sessions.d.ts +62 -8
  136. package/dist/ports/sessions.js +96 -20
  137. package/dist/ports/skills.d.ts +59 -0
  138. package/dist/ports/skills.js +205 -0
  139. package/dist/ports/stub.d.ts +1 -1
  140. package/dist/ports/stub.js +2 -2
  141. package/dist/ports/worktrees.d.ts +41 -0
  142. package/dist/ports/worktrees.js +85 -0
  143. package/dist/postgres-storage.d.ts +4 -5
  144. package/dist/postgres-storage.js +5 -6
  145. package/dist/storage-context.d.ts +44 -15
  146. package/dist/storage-context.js +139 -31
  147. package/package.json +4 -4
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Порт `SessionRepository` поверх PostgreSQL (PROP-032, волна 3b).
2
+ * Порт `SessionRepository` поверх PostgreSQL (ADR-097, волна 3b).
3
3
  *
4
4
  * Группа портов **сессий** PostgreSQL-драйвера: единственная фабрика
5
5
  * `buildSessionPorts(deps)` собирает `StorageContext['sessions']`.
@@ -19,6 +19,14 @@
19
19
  * (у старых сессий у всех сообщений `seq = 0`) и делает порядок однозначным;
20
20
  * домен и так переставляет `seq = i+1` при ветвлении/merge — приведение к
21
21
  * позиции смысла не меняет;
22
+ * - ADR-118 §2: `ord` — **монотонный** счётчик порядка записи в историю
23
+ * (выдаётся портом при материализации: `MAX(ord)+1` по сессии, под тем же
24
+ * per-session advisory-локом). Ранее выданные значения **не
25
+ * перенумеровываются**: `save()` сохраняет `ord` сообщения как есть, а
26
+ * `updateMessage` пишет `ord = COALESCE(messages.ord, …)` (уже выданное
27
+ * значение сохраняется; ещё не выданное — legacy-строка — может его
28
+ * получить: так проставляет `ord` миграция данных ядра). Рядом живут
29
+ * аддитивные поля хода/шага/статуса (`turn_id`/`step_index`/`status`);
22
30
  * - `id` сообщения **не уникален** в пределах сессии (legacy-дубликаты):
23
31
  * PK `messages` — суррогатный `message_uid`, поэтому дубликаты `id`
24
32
  * сохраняются без потерь (upsert по `id` их молча схлопывал);
@@ -28,10 +36,13 @@
28
36
  * **полную** `Session`; сообщения/child-строки подгружаются **батчем**
29
37
  * (`WHERE session_id = ANY($1)`, без N+1); порядок сообщений — по `seq` с
30
38
  * тайбрейкером `created_at`, затем `id` (детерминированное чтение);
31
- * - `listLight` — метаданные без истории (`messages`/`pendingMessages`/
32
- * `checkpoints` пусты, child-таблицы не читаются): одна выборка из `sessions`
39
+ * - `listLight` — метаданные без истории (`messages`/`checkpoints` пусты,
40
+ * child-таблицы не читаются; очередь `pendingMessages`/`steerInbox` —
41
+ * jsonb-колонки самой `sessions` — сохраняется): одна выборка из `sessions`
33
42
  * тем же `WHERE`/порядком, что у `list`; `loadLight` — та же проекция по
34
- * одному id (одна выборка по PK);
43
+ * одному id (одна выборка по PK), но **без очереди** (`pendingMessages`/
44
+ * `steerInbox` пусты) — контракт порта: очередь нужна только recovery/
45
+ * автозапуску через `listLight`;
35
46
  * - `list`/`listForUser*` сортируют `updated_at DESC`; архивированные сессии
36
47
  * **не** отфильтровываются — это ответственность менеджера
37
48
  * (`SessionManager.listSessions`, как и у файловой/memory реализаций);
@@ -46,9 +57,15 @@
46
57
  */
47
58
  import { jsonbParam } from '../json-param.js';
48
59
  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
- /** Колонки `sessions` (порядок — как в `001_init`). */
51
- const SESSION_FIELDS = [
60
+ import { checkpointRow, deserializeMessage, deserializeReference, deserializeSession, deserializeSessionLight, deserializeSessionMeta, emptySessionChildren, messageRow, referenceRow, serializeSession, stickyNoteRow, } from './sessions-mapping.js';
61
+ /**
62
+ * Колонки `sessions` (порядок — как в `001_init`).
63
+ *
64
+ * Экспортируется для unit-тестов сериализации (как `MESSAGE_MUTABLE_FIELDS`):
65
+ * тест проверяет, что новая колонка (`worktree`, ADR-114) реально попадает в
66
+ * `INSERT` и читается обратно.
67
+ */
68
+ export const SESSION_FIELDS = [
52
69
  'id',
53
70
  'title',
54
71
  'icon',
@@ -58,9 +75,12 @@ const SESSION_FIELDS = [
58
75
  'branch_point',
59
76
  'plan_approved',
60
77
  'mode',
78
+ 'mode_by_principal',
61
79
  'user_id',
62
80
  'owner_id',
63
81
  'project_id',
82
+ // ADR-114: привязка сессии к worktree (jsonb, миграция 023).
83
+ 'worktree',
64
84
  'todos',
65
85
  'prompt_states',
66
86
  'obfuscation_map',
@@ -68,7 +88,10 @@ const SESSION_FIELDS = [
68
88
  'settings',
69
89
  'mcp_servers',
70
90
  'pending_messages',
91
+ 'steer_inbox',
71
92
  'current_stream',
93
+ // Персистентное состояние ретрая (jsonb, миграция 030).
94
+ 'retry',
72
95
  'summarization_pending',
73
96
  'can_summarize',
74
97
  'created_at',
@@ -87,7 +110,11 @@ const SESSION_FIELDS = [
87
110
  'cache_write_cost',
88
111
  'cache_hit_rate',
89
112
  ];
90
- const SESSION_JSON_FIELDS = new Set([
113
+ /** jsonb-колонки `sessions` (экспортируется для unit-тестов сериализации). */
114
+ export const SESSION_JSON_FIELDS = new Set([
115
+ 'mode_by_principal',
116
+ // ADR-114: привязка сессии к worktree (jsonb, миграция 023).
117
+ 'worktree',
91
118
  'todos',
92
119
  'prompt_states',
93
120
  'obfuscation_map',
@@ -95,13 +122,18 @@ const SESSION_JSON_FIELDS = new Set([
95
122
  'settings',
96
123
  'mcp_servers',
97
124
  'pending_messages',
125
+ 'steer_inbox',
98
126
  'current_stream',
127
+ // Персистентное состояние ретрая (jsonb, миграция 030).
128
+ 'retry',
99
129
  ]);
100
- /** Колонки `messages` (порядок — как в `001_init`). */
101
- const MESSAGE_FIELDS = [
130
+ /** Колонки `messages` (порядок — как в `001_init`; `028` — reasoning-подпись). */
131
+ export const MESSAGE_FIELDS = [
102
132
  'id',
103
133
  'session_id',
104
134
  'seq',
135
+ // ADR-118 (миграция `029`): монотонный порядок записи, ход, шаг, статус.
136
+ 'ord',
105
137
  'role',
106
138
  'origin',
107
139
  'source_msg_id',
@@ -118,6 +150,8 @@ const MESSAGE_FIELDS = [
118
150
  'provider',
119
151
  'provider_type',
120
152
  'reasoning',
153
+ 'reasoning_signature',
154
+ 'reasoning_redacted',
121
155
  'source',
122
156
  'author',
123
157
  'agent_role',
@@ -127,9 +161,12 @@ const MESSAGE_FIELDS = [
127
161
  'pinned',
128
162
  'hidden',
129
163
  'ephemeral',
164
+ 'turn_id',
165
+ 'step_index',
166
+ 'status',
130
167
  'created_at',
131
168
  ];
132
- const MESSAGE_JSON_FIELDS = new Set([
169
+ export const MESSAGE_JSON_FIELDS = new Set([
133
170
  'parts',
134
171
  'tool_calls',
135
172
  'usage',
@@ -137,14 +174,22 @@ const MESSAGE_JSON_FIELDS = new Set([
137
174
  'prompt_meta',
138
175
  'debug_data',
139
176
  'summary_of',
177
+ 'reasoning_redacted',
140
178
  ]);
141
179
  /**
142
180
  * Колонки `messages`, которые заменяет `updateMessage`. Неизменяемые —
143
181
  * суррогатный `message_uid` (PK), доменный `id`, `session_id`, позиционный
144
182
  * `seq` и `created_at`: они сохраняются от исходной строки (цель ищется по
145
183
  * `seq`, fallback по `id`).
184
+ *
185
+ * ADR-118: `ord` — **не** перенумеровывается обновлением (он иммутабелен
186
+ * после выдачи), поэтому в общий список изменяемых колонок он не входит:
187
+ * `updateMessage` пишет его отдельной фразой `COALESCE(messages.ord, …)` —
188
+ * уже выданное значение сохраняется, а ещё не выданное (legacy-строка) может
189
+ * получить его (так проставляет `ord` миграция данных ядра).
146
190
  */
147
- export const MESSAGE_MUTABLE_FIELDS = MESSAGE_FIELDS.filter((field) => field !== 'id' && field !== 'session_id' && field !== 'seq' && field !== 'created_at');
191
+ export const MESSAGE_MUTABLE_FIELDS = MESSAGE_FIELDS.filter((field) => field !== 'id' && field !== 'session_id' && field !== 'seq'
192
+ && field !== 'created_at' && field !== 'ord');
148
193
  /** Обязательные поля сообщения: безопасные дефолты (паритет с file/memory). */
149
194
  function prepareMessage(message) {
150
195
  return {
@@ -157,6 +202,21 @@ function prepareMessage(message) {
157
202
  createdAt: message.createdAt || nowISO(),
158
203
  };
159
204
  }
205
+ /**
206
+ * ADR-118 §2: `ord` — **монотонный** счётчик порядка записи в историю
207
+ * сессии (выдаётся при материализации, ранее выданные значения не
208
+ * перенумеровываются).
209
+ *
210
+ * Правило выдачи: уже проставленный вызывателем `ord` **не перетирается**
211
+ * (иначе порядок записей ездил бы); иначе берётся `max(ord)+1` по сессии —
212
+ * значение вычислено в той же транзакции (per-session advisory-лок), поэтому
213
+ * два параллельных append'а не получат один `ord`.
214
+ *
215
+ * Экспортируется для unit-тестов (живая БД не нужна).
216
+ */
217
+ export function resolveOrd(requested, nextOrd) {
218
+ return Number.isFinite(requested) ? requested : nextOrd;
219
+ }
160
220
  const REFERENCE_FIELDS = [
161
221
  'id',
162
222
  'session_id',
@@ -306,6 +366,12 @@ export class PostgresSessionRepository {
306
366
  * транзакция + per-session advisory-лок (как у `save`), `seq = MAX(seq)+1`
307
367
  * вычисляется в той же транзакции, `INSERT` одной строки, обновление
308
368
  * `sessions.updated_at`. Остальная история не перезаписывается.
369
+ *
370
+ * ADR-118 §2: `ord` — **монотонный** счётчик сессии (`MAX(ord)+1` по
371
+ * сессии), выдаётся в момент материализации записи в историю; ранее
372
+ * выданные значения не перенумеровываются. Если вызывающий уже проставил
373
+ * `ord` (например, перенос записи), его значение сохраняется — порт не
374
+ * перетирает выданный порядок.
309
375
  */
310
376
  async appendMessage(sessionId, message) {
311
377
  const prepared = prepareMessage(message);
@@ -314,8 +380,10 @@ export class PostgresSessionRepository {
314
380
  const present = await tx.query('SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1) AS present', [sessionId]);
315
381
  if (present[0]?.present !== true)
316
382
  return null;
317
- const next = await tx.query('SELECT COALESCE(MAX(seq), 0) + 1 AS seq FROM messages WHERE session_id = $1', [sessionId]);
383
+ const next = await tx.query('SELECT COALESCE(MAX(seq), 0) + 1 AS seq, COALESCE(MAX(ord), 0) + 1 AS ord '
384
+ + 'FROM messages WHERE session_id = $1', [sessionId]);
318
385
  const seq = Number(next[0]?.seq ?? 1);
386
+ prepared.ord = resolveOrd(prepared.ord, Number(next[0]?.ord ?? 1));
319
387
  const row = messageRow(prepared, sessionId, seq);
320
388
  const placeholders = MESSAGE_FIELDS.map((_, index) => `$${index + 1}`).join(', ');
321
389
  const inserted = await tx.query(`INSERT INTO messages (${MESSAGE_FIELDS.join(', ')}) VALUES (${placeholders}) RETURNING *`, rowValues(row, MESSAGE_FIELDS, MESSAGE_JSON_FIELDS));
@@ -329,14 +397,21 @@ export class PostgresSessionRepository {
329
397
  * транзакция + per-session advisory-лок; цель — по `seq` (первая по
330
398
  * `seq, created_at, id`), fallback по `id`. `message_uid`/`id`/`seq`/
331
399
  * `created_at` исходной строки не меняются, `sessions.updated_at` обновляется.
400
+ *
401
+ * ADR-118: `ord` не перенумеровывается — уже выданное значение сохраняется
402
+ * (`COALESCE(messages.ord, …)`), а ещё не выданное (legacy-строка без
403
+ * `ord`) может быть проставлено (миграция данных ядра).
332
404
  */
333
405
  async updateMessage(sessionId, message) {
334
406
  const prepared = prepareMessage(message);
335
407
  const row = messageRow(prepared, sessionId, prepared.seq);
336
- const setSql = MESSAGE_MUTABLE_FIELDS
337
- .map((field, index) => `${field} = $${index + 1}`)
338
- .join(', ');
408
+ const setClauses = MESSAGE_MUTABLE_FIELDS.map((field, index) => `${field} = $${index + 1}`);
339
409
  const params = rowValues(row, MESSAGE_MUTABLE_FIELDS, MESSAGE_JSON_FIELDS);
410
+ if (prepared.ord !== undefined && prepared.ord !== null) {
411
+ params.push(prepared.ord);
412
+ setClauses.push(`ord = COALESCE(messages.ord, $${params.length})`);
413
+ }
414
+ const setSql = setClauses.join(', ');
340
415
  return this._connection.withTransaction(async (tx) => {
341
416
  await this._lockSession(tx, sessionId);
342
417
  const messageUid = await this._findMessageUid(tx, sessionId, prepared);
@@ -349,13 +424,14 @@ export class PostgresSessionRepository {
349
424
  });
350
425
  }
351
426
  /**
352
- * Метаданные сессии без истории (`SessionRepository.loadLight`): одна
353
- * выборка по PK, child-таблицы не читаются.
427
+ * Метаданные сессии без истории и без очереди (`SessionRepository.loadLight`):
428
+ * одна выборка по PK, child-таблицы не читаются, `pendingMessages`/`steerInbox`
429
+ * пусты (очередь отдаёт только `listLight` — recovery/автозапуску).
354
430
  */
355
431
  async loadLight(sessionId) {
356
432
  const rows = await this._connection.query('SELECT * FROM sessions WHERE id = $1', [sessionId]);
357
433
  const row = rows[0];
358
- return row ? deserializeSessionLight(row) : null;
434
+ return row ? deserializeSessionMeta(row) : null;
359
435
  }
360
436
  async delete(sessionId) {
361
437
  await this._connection.withTransaction(async (tx) => {
@@ -483,7 +559,7 @@ export class PostgresSessionRepository {
483
559
  }
484
560
  return null;
485
561
  }
486
- /** PROP-032: per-session сериализация записи — транзакционный advisory-лок. */
562
+ /** ADR-097: per-session сериализация записи — транзакционный advisory-лок. */
487
563
  async _lockSession(tx, sessionId) {
488
564
  await tx.query('SELECT pg_advisory_xact_lock(hashtext($1::text)::bigint)', [sessionId]);
489
565
  }
@@ -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;
@@ -0,0 +1,205 @@
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 { SKILL_NAME_MAX, SKILL_NAME_REGEX, parseFrontmatter, stringifyFrontmatter, } from '@itphx/synth-shared';
31
+ import { jsonbParam } from '../json-param.js';
32
+ /** Корневой префикс скиллов в blob-сторе. */
33
+ const SKILLS_BLOB_PREFIX = 'skills';
34
+ /** Имя файла заголовка внутри каталога скилла. */
35
+ const SKILL_MARKDOWN_FILE = 'SKILL.md';
36
+ /** Проверка имени скилла (1–64, `^[a-z0-9]+(-[a-z0-9]+)*$`). */
37
+ function assertSkillName(name) {
38
+ if (!name || name.length > SKILL_NAME_MAX || !SKILL_NAME_REGEX.test(name)) {
39
+ throw new Error(`Недопустимое имя скилла: ${name}`);
40
+ }
41
+ }
42
+ /**
43
+ * Нормализованный относительный путь внутри скилла; `null` — путь небезопасен
44
+ * (абсолютный, с `..`, обратным слешем или NUL). Семантика — как у
45
+ * `MemorySkillRepository.safeRelPath`.
46
+ */
47
+ function safeRelPath(relPath) {
48
+ if (!relPath ||
49
+ relPath.startsWith('/') ||
50
+ relPath.includes('..') ||
51
+ relPath.includes('\\') ||
52
+ relPath.includes('\0')) {
53
+ return null;
54
+ }
55
+ const normalized = relPath.replace(/^\.\/+/, '').replace(/\/+$/, '');
56
+ if (!normalized)
57
+ return null;
58
+ return normalized;
59
+ }
60
+ /** Префикс каталога скилла в blob-сторе (`skills/<name>/`). */
61
+ function skillPrefix(name) {
62
+ return `${SKILLS_BLOB_PREFIX}/${name}/`;
63
+ }
64
+ /** Путь `SKILL.md` скилла в blob-сторе. */
65
+ function markdownPath(name) {
66
+ return `${skillPrefix(name)}${SKILL_MARKDOWN_FILE}`;
67
+ }
68
+ /**
69
+ * ADR-116: instance-скиллы — метаданные в `instance_skills`, содержимое в
70
+ * `BlobStore`.
71
+ */
72
+ export class PgSkillRepository {
73
+ _deps;
74
+ _blobs;
75
+ constructor(_deps, _blobs) {
76
+ this._deps = _deps;
77
+ this._blobs = _blobs;
78
+ }
79
+ async exists(name) {
80
+ // Невалидное имя не может быть в таблице — отвечаем `false`, а не ошибкой
81
+ // (паритет с file/memory: `exists` не бросает).
82
+ try {
83
+ assertSkillName(name);
84
+ }
85
+ catch {
86
+ return false;
87
+ }
88
+ const rows = await this._deps.connection.query('SELECT name FROM instance_skills WHERE name = $1 LIMIT 1', [name]);
89
+ return rows.length > 0;
90
+ }
91
+ async listNames() {
92
+ const rows = await this._deps.connection.query('SELECT name FROM instance_skills ORDER BY name ASC');
93
+ return rows.map((row) => row.name);
94
+ }
95
+ async readMarkdown(name) {
96
+ try {
97
+ assertSkillName(name);
98
+ }
99
+ catch {
100
+ return null;
101
+ }
102
+ const buffer = await this._blobs.read(markdownPath(name));
103
+ return buffer ? buffer.toString('utf-8') : null;
104
+ }
105
+ async create(input) {
106
+ assertSkillName(input.name);
107
+ if (await this.exists(input.name)) {
108
+ throw new Error(`Скилл "${input.name}" уже существует`);
109
+ }
110
+ const frontmatter = { ...(input.frontmatter ?? {}) };
111
+ frontmatter.name = input.name;
112
+ frontmatter.description = input.description;
113
+ const markdown = stringifyFrontmatter(frontmatter, input.body ?? '');
114
+ await this._blobs.write(markdownPath(input.name), markdown);
115
+ for (const [rel, content] of Object.entries(input.files ?? {})) {
116
+ const target = safeRelPath(rel);
117
+ if (!target)
118
+ throw new Error(`Небезопасный путь supporting-файла: ${rel}`);
119
+ await this._blobs.write(`${skillPrefix(input.name)}${target}`, content);
120
+ }
121
+ await this._upsertMetadata(input.name, frontmatter);
122
+ }
123
+ async updateMarkdown(name, patch) {
124
+ assertSkillName(name);
125
+ const raw = await this.readMarkdown(name);
126
+ if (raw === null) {
127
+ throw new Error(`Скилл "${name}" не найден`);
128
+ }
129
+ const frontmatter = parseFrontmatter(raw);
130
+ const data = { ...frontmatter.data, name };
131
+ if (patch.description !== undefined)
132
+ data.description = patch.description;
133
+ if (patch.metadata !== undefined) {
134
+ const existing = typeof data.metadata === 'object' && data.metadata !== null && !Array.isArray(data.metadata)
135
+ ? data.metadata
136
+ : {};
137
+ data.metadata = { ...existing, ...patch.metadata };
138
+ }
139
+ const body = patch.body !== undefined ? patch.body : frontmatter.body;
140
+ await this._blobs.write(markdownPath(name), stringifyFrontmatter(data, body));
141
+ await this._upsertMetadata(name, data);
142
+ }
143
+ async remove(name) {
144
+ assertSkillName(name);
145
+ if (!(await this.exists(name)))
146
+ return false;
147
+ // Содержимое: все объекты каталога скилла (`SKILL.md` + supporting).
148
+ const objects = await this._blobs.list(skillPrefix(name));
149
+ for (const object of objects) {
150
+ await this._blobs.delete(object.path);
151
+ }
152
+ await this._deps.connection.query('DELETE FROM instance_skills WHERE name = $1', [name]);
153
+ return true;
154
+ }
155
+ async readFile(name, relPath) {
156
+ const target = safeRelPath(relPath);
157
+ if (!target)
158
+ return null;
159
+ const buffer = await this._blobs.read(`${skillPrefix(name)}${target}`);
160
+ return buffer ? buffer.toString('utf-8') : null;
161
+ }
162
+ async writeFile(name, relPath, content) {
163
+ assertSkillName(name);
164
+ const target = safeRelPath(relPath);
165
+ if (!target)
166
+ throw new Error(`Небезопасный путь supporting-файла: ${relPath}`);
167
+ await this._blobs.write(`${skillPrefix(name)}${target}`, content);
168
+ }
169
+ async deleteFile(name, relPath) {
170
+ const target = safeRelPath(relPath);
171
+ if (!target)
172
+ return false;
173
+ // Удаление отсутствующего файла — не ошибка (паритет с file/memory).
174
+ await this._blobs.delete(`${skillPrefix(name)}${target}`);
175
+ return true;
176
+ }
177
+ async listFiles(name) {
178
+ const prefix = skillPrefix(name);
179
+ const objects = await this._blobs.list(prefix);
180
+ const files = [];
181
+ for (const object of objects) {
182
+ if (!object.path.startsWith(prefix))
183
+ continue;
184
+ const rel = object.path.slice(prefix.length);
185
+ if (!rel || rel === SKILL_MARKDOWN_FILE)
186
+ continue;
187
+ files.push({ path: rel, size: object.size });
188
+ }
189
+ return files.sort((a, b) => a.path.localeCompare(b.path));
190
+ }
191
+ /** Upsert метаданных: заголовок скилла и служебная метка записи. */
192
+ async _upsertMetadata(name, frontmatter) {
193
+ await this._deps.connection.query(`INSERT INTO instance_skills (name, frontmatter, updated_at)
194
+ VALUES ($1, $2::jsonb, now())
195
+ ON CONFLICT (name) DO UPDATE SET
196
+ frontmatter = EXCLUDED.frontmatter,
197
+ updated_at = now()`, [name, jsonbParam(frontmatter)]);
198
+ }
199
+ }
200
+ /** Собрать порт instance-скиллов (ADR-046 §4, ADR-116). */
201
+ export function buildSkillPorts(deps, blobs) {
202
+ return {
203
+ skills: new PgSkillRepository(deps, blobs),
204
+ };
205
+ }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Общая заглушка портов PostgreSQL-драйвера (PROP-032, волна 3b).
2
+ * Общая заглушка портов PostgreSQL-драйвера (ADR-097, волна 3b).
3
3
  *
4
4
  * Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
5
5
  * (прокси, любой доступ к методу которого бросает
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Общая заглушка портов PostgreSQL-драйвера (PROP-032, волна 3b).
2
+ * Общая заглушка портов PostgreSQL-драйвера (ADR-097, волна 3b).
3
3
  *
4
4
  * Пока доменный порт не реализован поверх SQL, драйвер отдаёт `notImplementedPort`
5
5
  * (прокси, любой доступ к методу которого бросает
@@ -21,7 +21,7 @@ export function notImplementedPort(port) {
21
21
  let method = methods.get(prop);
22
22
  if (!method) {
23
23
  method = () => {
24
- throw new PostgresStorageNotImplementedError(`Порт '${port}' ещё не реализован в PostgreSQL-драйвере (PROP-032, волна реализации портов).`);
24
+ throw new PostgresStorageNotImplementedError(`Порт '${port}' ещё не реализован в PostgreSQL-драйвере (ADR-097, волна реализации портов).`);
25
25
  };
26
26
  methods.set(prop, method);
27
27
  }
@@ -0,0 +1,41 @@
1
+ /**
2
+ * PG-реализация порта **инвентаря git-worktree'ов** (ADR-114, ADR-097).
3
+ *
4
+ * Хранение — **существующий** generic-слой `documents(kind, key, value jsonb)`
5
+ * (миграция `001-init`): `kind = 'worktree'`, ключ документа — `id` записи,
6
+ * значение — сама запись (`WorktreeRecord`) целиком. Новая таблица и новая
7
+ * миграция **не нужны**: `kind` — свободный текст без CHECK-ограничений
8
+ * (ADR-114 §2.2), расширяется лишь список `kind` в драйвере.
9
+ *
10
+ * Семантика повторяет файловые реализации core (`FileWorktreeStore`) и
11
+ * in-memory (`MemoryWorktreeRepository`):
12
+ * - upsert по `id`: `createdAt` не перезаписывается (сохранённое значение
13
+ * приоритетно), `updatedAt` — метка вызывающего (драйвер не подставляет
14
+ * «сейчас»);
15
+ * - `list` — «свежие первыми» (`createdAt` убыв., тайбрейкер `id`), фильтр по
16
+ * проекту (поле записи);
17
+ * - `delete` — идемпотентно, `deleteByProject` — число удалённых записей.
18
+ *
19
+ * Порядок сортировки и фильтр считаются в драйвере (объём коллекции мал), а
20
+ * не SQL'ем: так семантика совпадает с файловым/в-памяти backend'ами
21
+ * байт-в-байт (сортировка по ISO-8601-метке, а не по тексту jsonb).
22
+ */
23
+ import type { StorageContext, WorktreeRepository } from '@itphx/synth-core';
24
+ import type { WorktreeRecord } from '@itphx/synth-shared';
25
+ import type { PortDeps } from './deps.js';
26
+ /** Часть `StorageContext`, которой владеет группа «worktrees». */
27
+ export type WorktreePorts = Pick<StorageContext, 'worktrees'>;
28
+ /** Порт инвентаря worktree'ов поверх таблицы `documents`. */
29
+ export declare class PgWorktreeRepository implements WorktreeRepository {
30
+ private readonly _deps;
31
+ constructor(_deps: PortDeps);
32
+ save(record: WorktreeRecord): Promise<void>;
33
+ get(id: string): Promise<WorktreeRecord | null>;
34
+ list(filter?: {
35
+ projectId?: string;
36
+ }): Promise<WorktreeRecord[]>;
37
+ delete(id: string): Promise<void>;
38
+ deleteByProject(projectId: string): Promise<number>;
39
+ }
40
+ /** Собрать порт инвентаря worktree'ов (ADR-114). */
41
+ export declare function buildWorktreePorts(deps: PortDeps): WorktreePorts;