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

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 (72) 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 +37 -0
  6. package/dist/index.js +34 -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/index.d.ts +23 -0
  20. package/dist/migrations/index.js +23 -0
  21. package/dist/pool.d.ts +178 -0
  22. package/dist/pool.js +382 -0
  23. package/dist/ports/analytics.d.ts +26 -0
  24. package/dist/ports/analytics.js +243 -0
  25. package/dist/ports/audit.d.ts +15 -0
  26. package/dist/ports/audit.js +189 -0
  27. package/dist/ports/content.d.ts +41 -0
  28. package/dist/ports/content.js +1539 -0
  29. package/dist/ports/core-sync.d.ts +31 -0
  30. package/dist/ports/core-sync.js +34 -0
  31. package/dist/ports/deps.d.ts +63 -0
  32. package/dist/ports/deps.js +19 -0
  33. package/dist/ports/events-bindings.d.ts +77 -0
  34. package/dist/ports/events-bindings.js +356 -0
  35. package/dist/ports/events-core.d.ts +35 -0
  36. package/dist/ports/events-core.js +71 -0
  37. package/dist/ports/events-journal.d.ts +68 -0
  38. package/dist/ports/events-journal.js +211 -0
  39. package/dist/ports/events-scheduler.d.ts +49 -0
  40. package/dist/ports/events-scheduler.js +231 -0
  41. package/dist/ports/events-webhooks.d.ts +64 -0
  42. package/dist/ports/events-webhooks.js +268 -0
  43. package/dist/ports/events.d.ts +20 -0
  44. package/dist/ports/events.js +27 -0
  45. package/dist/ports/principals-defaults.d.ts +21 -0
  46. package/dist/ports/principals-defaults.js +68 -0
  47. package/dist/ports/principals-documents.d.ts +23 -0
  48. package/dist/ports/principals-documents.js +38 -0
  49. package/dist/ports/principals-profiles.d.ts +21 -0
  50. package/dist/ports/principals-profiles.js +263 -0
  51. package/dist/ports/principals-projects.d.ts +19 -0
  52. package/dist/ports/principals-projects.js +158 -0
  53. package/dist/ports/principals-settings.d.ts +25 -0
  54. package/dist/ports/principals-settings.js +275 -0
  55. package/dist/ports/principals-shared.d.ts +33 -0
  56. package/dist/ports/principals-shared.js +44 -0
  57. package/dist/ports/principals.d.ts +27 -0
  58. package/dist/ports/principals.js +39 -0
  59. package/dist/ports/sessions-mapping.d.ts +237 -0
  60. package/dist/ports/sessions-mapping.js +405 -0
  61. package/dist/ports/sessions.d.ts +133 -0
  62. package/dist/ports/sessions.js +502 -0
  63. package/dist/ports/stub.d.ts +14 -0
  64. package/dist/ports/stub.js +32 -0
  65. package/dist/postgres-storage.d.ts +59 -0
  66. package/dist/postgres-storage.js +111 -0
  67. package/dist/schema.d.ts +13 -0
  68. package/dist/schema.js +22 -0
  69. package/dist/storage-context.d.ts +51 -0
  70. package/dist/storage-context.js +130 -0
  71. package/package.json +40 -3
  72. package/README.md +0 -3
@@ -0,0 +1,275 @@
1
+ /**
2
+ * Порт `settings` (runtime-настройки инстанса) PostgreSQL-драйвера
3
+ * (PROP-032, волна 3b).
4
+ *
5
+ * Эталон семантики — `RuntimeSettingsStore`/`MemorySettingsRepository`:
6
+ * - `load()` на пустом сторе — `{}` (не заданные секции в результат не попадают);
7
+ * - геттеры отдают `undefined`/`{}`/`false` для не заданных значений;
8
+ * - `clear*` убирает секцию (ключ удаляется, а не пишется `null`).
9
+ *
10
+ * Хранение разложено по таблицам `001_init`:
11
+ * - `settings(key PK, value jsonb)` — секции `RuntimeSettings` (по ключу на секцию);
12
+ * - `token_ratios(model PK, ratio)` — chars-per-token по модели;
13
+ * - `migration_markers(name PK)` — маркеры разовых миграций.
14
+ *
15
+ * Запись секции — upsert одного ключа. Read-modify-write файловой реализации для
16
+ * `migrations`/`tokenRatios` здесь отсутствует by design: они нормализованы в
17
+ * отдельные таблицы (строку за раз), поэтому гонки между обновлениями разных
18
+ * моделей/маркеров нет.
19
+ */
20
+ import { deleteSetting, readSetting, writeSetting } from './principals-shared.js';
21
+ /** Ключи секций, которые порт хранит в таблице `settings` (порядок стабилен). */
22
+ const SECTION_KEYS = [
23
+ 'workspace',
24
+ 'mcpServers',
25
+ 'llmGateway',
26
+ 'security',
27
+ 'toolsPolicy',
28
+ 'mcpPolicy',
29
+ 'toolsDisabled',
30
+ 'skillsDisabled',
31
+ 'skillsDisabledForNewProjects',
32
+ 'skillsPolicy',
33
+ 'mcpNetworkPolicy',
34
+ 'egress',
35
+ 'defaultAgent',
36
+ 'defaultModel',
37
+ 'workspacePolicy',
38
+ 'events',
39
+ 'decision',
40
+ 'proxy',
41
+ ];
42
+ const SECTION_KEY_SET = new Set(SECTION_KEYS);
43
+ /** Собрать порт runtime-настроек поверх SQL. */
44
+ export function createPrincipalSettingsPort(conn) {
45
+ return {
46
+ async load() {
47
+ const settings = {};
48
+ const rows = await conn.query('SELECT key, value FROM settings WHERE key = ANY($1::text[])', [[...SECTION_KEYS]]);
49
+ for (const row of rows) {
50
+ if (!SECTION_KEY_SET.has(row.key))
51
+ continue;
52
+ settings[row.key] = row.value;
53
+ }
54
+ const ratios = await conn.query('SELECT model, ratio FROM token_ratios');
55
+ if (ratios.length > 0) {
56
+ const tokenRatios = {};
57
+ for (const row of ratios)
58
+ tokenRatios[row.model] = row.ratio;
59
+ settings.tokenRatios = tokenRatios;
60
+ }
61
+ const markers = await conn.query('SELECT name FROM migration_markers');
62
+ if (markers.length > 0) {
63
+ const migrations = {};
64
+ for (const row of markers)
65
+ migrations[row.name] = true;
66
+ settings.migrations = migrations;
67
+ }
68
+ return settings;
69
+ },
70
+ async getWorkspace() {
71
+ return readSetting(conn, 'workspace');
72
+ },
73
+ async setWorkspace(workspace) {
74
+ await writeSetting(conn, 'workspace', workspace);
75
+ },
76
+ async clearWorkspace() {
77
+ await deleteSetting(conn, 'workspace');
78
+ },
79
+ async getMcpSettings() {
80
+ return (await readSetting(conn, 'mcpServers')) ?? {};
81
+ },
82
+ async setMcpSettings(servers) {
83
+ await writeSetting(conn, 'mcpServers', servers);
84
+ },
85
+ async clearMcpSettings() {
86
+ await deleteSetting(conn, 'mcpServers');
87
+ },
88
+ async getLlmGatewaySettings() {
89
+ return (await readSetting(conn, 'llmGateway')) ?? {};
90
+ },
91
+ async setLlmGatewaySettings(config) {
92
+ await writeSetting(conn, 'llmGateway', config);
93
+ },
94
+ async clearLlmGatewaySettings() {
95
+ await deleteSetting(conn, 'llmGateway');
96
+ },
97
+ async getSecuritySettings() {
98
+ return (await readSetting(conn, 'security')) ?? {};
99
+ },
100
+ async setSecuritySettings(config) {
101
+ await writeSetting(conn, 'security', config);
102
+ },
103
+ async clearSecuritySettings() {
104
+ await deleteSetting(conn, 'security');
105
+ },
106
+ async getToolsPolicy() {
107
+ return readSetting(conn, 'toolsPolicy');
108
+ },
109
+ async setToolsPolicy(policy) {
110
+ await writeSetting(conn, 'toolsPolicy', policy);
111
+ },
112
+ async clearToolsPolicy() {
113
+ await deleteSetting(conn, 'toolsPolicy');
114
+ },
115
+ async getMcpPolicy() {
116
+ return readSetting(conn, 'mcpPolicy');
117
+ },
118
+ async setMcpPolicy(policy) {
119
+ await writeSetting(conn, 'mcpPolicy', policy);
120
+ },
121
+ async clearMcpPolicy() {
122
+ await deleteSetting(conn, 'mcpPolicy');
123
+ },
124
+ async getToolsDisabled() {
125
+ return readSetting(conn, 'toolsDisabled');
126
+ },
127
+ async setToolsDisabled(config) {
128
+ await writeSetting(conn, 'toolsDisabled', config);
129
+ },
130
+ async clearToolsDisabled() {
131
+ await deleteSetting(conn, 'toolsDisabled');
132
+ },
133
+ async getSkillsDisabled() {
134
+ return readSetting(conn, 'skillsDisabled');
135
+ },
136
+ async setSkillsDisabled(config) {
137
+ await writeSetting(conn, 'skillsDisabled', config);
138
+ },
139
+ async clearSkillsDisabled() {
140
+ await deleteSetting(conn, 'skillsDisabled');
141
+ },
142
+ async getSkillsDisabledForNewProjects() {
143
+ return readSetting(conn, 'skillsDisabledForNewProjects');
144
+ },
145
+ async setSkillsDisabledForNewProjects(config) {
146
+ await writeSetting(conn, 'skillsDisabledForNewProjects', config);
147
+ },
148
+ async clearSkillsDisabledForNewProjects() {
149
+ await deleteSetting(conn, 'skillsDisabledForNewProjects');
150
+ },
151
+ async getMigrationMarker(name) {
152
+ const rows = await conn.query('SELECT name FROM migration_markers WHERE name = $1', [name]);
153
+ return rows.length > 0;
154
+ },
155
+ async setMigrationMarker(name) {
156
+ await conn.query(`INSERT INTO migration_markers (name) VALUES ($1)
157
+ ON CONFLICT (name) DO UPDATE SET applied_at = now()`, [name]);
158
+ },
159
+ async getSkillsPolicy() {
160
+ return readSetting(conn, 'skillsPolicy');
161
+ },
162
+ async setSkillsPolicy(policy) {
163
+ await writeSetting(conn, 'skillsPolicy', policy);
164
+ },
165
+ async clearSkillsPolicy() {
166
+ await deleteSetting(conn, 'skillsPolicy');
167
+ },
168
+ async getTokenRatio(model) {
169
+ const rows = await conn.query('SELECT ratio FROM token_ratios WHERE model = $1', [model]);
170
+ return rows[0]?.ratio;
171
+ },
172
+ async getTokenRatios() {
173
+ const rows = await conn.query('SELECT model, ratio FROM token_ratios');
174
+ const ratios = {};
175
+ for (const row of rows)
176
+ ratios[row.model] = row.ratio;
177
+ return ratios;
178
+ },
179
+ async setTokenRatio(model, ratio) {
180
+ await conn.query(`INSERT INTO token_ratios (model, ratio, updated_at) VALUES ($1, $2, now())
181
+ ON CONFLICT (model) DO UPDATE SET ratio = EXCLUDED.ratio, updated_at = now()`, [model, ratio]);
182
+ },
183
+ async getMcpNetworkPolicy() {
184
+ return readSetting(conn, 'mcpNetworkPolicy');
185
+ },
186
+ async setMcpNetworkPolicy(policy) {
187
+ await writeSetting(conn, 'mcpNetworkPolicy', policy);
188
+ },
189
+ async getEgressPolicy(scope) {
190
+ const all = await readSetting(conn, 'egress');
191
+ return all?.[scope];
192
+ },
193
+ async setEgressPolicy(scope, policy) {
194
+ const all = (await readSetting(conn, 'egress')) ?? {};
195
+ await writeSetting(conn, 'egress', { ...all, [scope]: policy });
196
+ },
197
+ async clearEgressPolicy(scope) {
198
+ const all = await readSetting(conn, 'egress');
199
+ if (!all)
200
+ return;
201
+ const next = { ...all };
202
+ delete next[scope];
203
+ if (Object.keys(next).length > 0)
204
+ await writeSetting(conn, 'egress', next);
205
+ else
206
+ await deleteSetting(conn, 'egress');
207
+ },
208
+ async clearMcpNetworkPolicy() {
209
+ await deleteSetting(conn, 'mcpNetworkPolicy');
210
+ },
211
+ async getDefaultAgent() {
212
+ return readSetting(conn, 'defaultAgent');
213
+ },
214
+ async setDefaultAgent(id) {
215
+ await writeSetting(conn, 'defaultAgent', id);
216
+ },
217
+ async clearDefaultAgent() {
218
+ await deleteSetting(conn, 'defaultAgent');
219
+ },
220
+ async getDefaultModel() {
221
+ return readSetting(conn, 'defaultModel');
222
+ },
223
+ async setDefaultModel(pair) {
224
+ await writeSetting(conn, 'defaultModel', pair);
225
+ },
226
+ async clearDefaultModel() {
227
+ await deleteSetting(conn, 'defaultModel');
228
+ },
229
+ async getWorkspacePolicy() {
230
+ return readSetting(conn, 'workspacePolicy');
231
+ },
232
+ async setWorkspacePolicy(policy) {
233
+ await writeSetting(conn, 'workspacePolicy', policy);
234
+ },
235
+ async clearWorkspacePolicy() {
236
+ await deleteSetting(conn, 'workspacePolicy');
237
+ },
238
+ async getEvents() {
239
+ return (await readSetting(conn, 'events')) ?? {};
240
+ },
241
+ async setEvents(config) {
242
+ await writeSetting(conn, 'events', config);
243
+ },
244
+ async clearEvents() {
245
+ await deleteSetting(conn, 'events');
246
+ },
247
+ async getDecision() {
248
+ return (await readSetting(conn, 'decision')) ?? {};
249
+ },
250
+ async setDecision(config) {
251
+ await writeSetting(conn, 'decision', config);
252
+ },
253
+ async clearDecision() {
254
+ await deleteSetting(conn, 'decision');
255
+ },
256
+ async getMetrics() {
257
+ return (await readSetting(conn, 'metrics')) ?? {};
258
+ },
259
+ async setMetrics(config) {
260
+ await writeSetting(conn, 'metrics', config);
261
+ },
262
+ async clearMetrics() {
263
+ await deleteSetting(conn, 'metrics');
264
+ },
265
+ async getProxySettings() {
266
+ return readSetting(conn, 'proxy');
267
+ },
268
+ async setProxySettings(config) {
269
+ await writeSetting(conn, 'proxy', config);
270
+ },
271
+ async clearProxySettings() {
272
+ await deleteSetting(conn, 'proxy');
273
+ },
274
+ };
275
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Общие утилиты группы портов `principals` PostgreSQL-драйвера
3
+ * (PROP-032, волна 3b).
4
+ *
5
+ * Драйвер объявляет `@itphx/synth-shared` обычной зависимостью, поэтому доменные
6
+ * типы сущностей берутся из неё напрямую (алиасы — для читаемости портов).
7
+ * Значения `jsonb`/`timestamptz` преобразуются здесь, чтобы все порты группы
8
+ * работали единообразно:
9
+ * - `jsonb` пишется явной JSON-строкой (`pg` иначе превратил бы JS-массив в
10
+ * Postgres-массив) с приведением `$n::jsonb`;
11
+ * - `timestamptz` читается как `Date` (`pg` парсит его в `Date`) и отдаётся
12
+ * домену ISO-строкой — как в файловой реализации (JSON round-trip).
13
+ */
14
+ import type { ExternalIdentity, ProfileData, Project } from '@itphx/synth-shared';
15
+ import type { PostgresExecutor } from '../pool.js';
16
+ /** Доменный проект. */
17
+ export type ProjectEntity = Project;
18
+ /** Доменный профиль. */
19
+ export type ProfileEntity = ProfileData;
20
+ /** Внешняя идентичность профиля (ADR-089). */
21
+ export type ExternalIdentityEntity = ExternalIdentity;
22
+ /** `timestamptz` (`Date` из `pg`) → ISO-строка; `NULL`/`undefined` → `undefined`. */
23
+ export declare function toIso(value: unknown): string | undefined;
24
+ /** `timestamptz NOT NULL` → ISO-строка (отсутствие — пустая строка, не бросаем). */
25
+ export declare function requiredIso(value: unknown): string;
26
+ /** Значение `jsonb`-параметра: JSON-строка либо `null` (NUL — вычищены). */
27
+ export declare function jsonbParam(value: unknown): string | null;
28
+ /** Прочитать `jsonb`-значение ключа таблицы `settings`. */
29
+ export declare function readSetting<T>(exec: PostgresExecutor, key: string): Promise<T | undefined>;
30
+ /** Записать (upsert) `jsonb`-значение ключа таблицы `settings`. */
31
+ export declare function writeSetting(exec: PostgresExecutor, key: string, value: unknown): Promise<void>;
32
+ /** Удалить ключ таблицы `settings` (отсутствие — не ошибка). */
33
+ export declare function deleteSetting(exec: PostgresExecutor, key: string): Promise<void>;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Общие утилиты группы портов `principals` PostgreSQL-драйвера
3
+ * (PROP-032, волна 3b).
4
+ *
5
+ * Драйвер объявляет `@itphx/synth-shared` обычной зависимостью, поэтому доменные
6
+ * типы сущностей берутся из неё напрямую (алиасы — для читаемости портов).
7
+ * Значения `jsonb`/`timestamptz` преобразуются здесь, чтобы все порты группы
8
+ * работали единообразно:
9
+ * - `jsonb` пишется явной JSON-строкой (`pg` иначе превратил бы JS-массив в
10
+ * Postgres-массив) с приведением `$n::jsonb`;
11
+ * - `timestamptz` читается как `Date` (`pg` парсит его в `Date`) и отдаётся
12
+ * домену ISO-строкой — как в файловой реализации (JSON round-trip).
13
+ */
14
+ import { jsonbParam as serializeJsonbParam } from '../json-param.js';
15
+ /** `timestamptz` (`Date` из `pg`) → ISO-строка; `NULL`/`undefined` → `undefined`. */
16
+ export function toIso(value) {
17
+ if (value === null || value === undefined)
18
+ return undefined;
19
+ if (value instanceof Date)
20
+ return value.toISOString();
21
+ return String(value);
22
+ }
23
+ /** `timestamptz NOT NULL` → ISO-строка (отсутствие — пустая строка, не бросаем). */
24
+ export function requiredIso(value) {
25
+ return toIso(value) ?? '';
26
+ }
27
+ /** Значение `jsonb`-параметра: JSON-строка либо `null` (NUL — вычищены). */
28
+ export function jsonbParam(value) {
29
+ return serializeJsonbParam(value);
30
+ }
31
+ /** Прочитать `jsonb`-значение ключа таблицы `settings`. */
32
+ export async function readSetting(exec, key) {
33
+ const rows = await exec.query('SELECT value FROM settings WHERE key = $1', [key]);
34
+ return rows[0]?.value;
35
+ }
36
+ /** Записать (upsert) `jsonb`-значение ключа таблицы `settings`. */
37
+ export async function writeSetting(exec, key, value) {
38
+ await exec.query(`INSERT INTO settings (key, value, updated_at) VALUES ($1, $2::jsonb, now())
39
+ ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()`, [key, jsonbParam(value)]);
40
+ }
41
+ /** Удалить ключ таблицы `settings` (отсутствие — не ошибка). */
42
+ export async function deleteSetting(exec, key) {
43
+ await exec.query('DELETE FROM settings WHERE key = $1', [key]);
44
+ }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Группа портов **принципалов и конфигурации** PostgreSQL-драйвера
3
+ * (PROP-032, волна 3b).
4
+ *
5
+ * Владелец файла — один агент волны реализации; правит `principals.ts` и
6
+ * `principals-*.ts`. Файл экспортирует единственную фабрику
7
+ * `buildPrincipalPorts(deps)`, возвращающую свою часть `StorageContext`:
8
+ * `projects`, `profiles`, `settings`, `defaults`, `providers`, `models`,
9
+ * `agents`.
10
+ *
11
+ * Реализация разложена по файлам (по одному ответственному порту/семейству):
12
+ * - `principals-projects.ts` → `projects` (projects + project_members);
13
+ * - `principals-profiles.ts` → `profiles` (profiles + profile_identities);
14
+ * - `principals-settings.ts` → `settings` (settings + token_ratios +
15
+ * migration_markers);
16
+ * - `principals-defaults.ts` → `defaults` (ключ в `settings`);
17
+ * - `principals-documents.ts` → `providers`/`models`/`agents` (documents).
18
+ *
19
+ * `deps.dataDir` этим портам не нужен: всё состояние — в БД (секции/документы),
20
+ * файловых путей у группы нет. Контракты — `packages/core/src/storage/contract/*`.
21
+ */
22
+ import type { StorageContext } from '@itphx/synth-core';
23
+ import type { PortDeps } from './deps.js';
24
+ /** Часть `StorageContext`, которой владеет группа `principals`. */
25
+ export type PrincipalPorts = Pick<StorageContext, 'projects' | 'profiles' | 'settings' | 'defaults' | 'providers' | 'models' | 'agents'>;
26
+ /** Собрать порты группы `principals`. */
27
+ export declare function buildPrincipalPorts(deps: PortDeps): PrincipalPorts;
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Группа портов **принципалов и конфигурации** PostgreSQL-драйвера
3
+ * (PROP-032, волна 3b).
4
+ *
5
+ * Владелец файла — один агент волны реализации; правит `principals.ts` и
6
+ * `principals-*.ts`. Файл экспортирует единственную фабрику
7
+ * `buildPrincipalPorts(deps)`, возвращающую свою часть `StorageContext`:
8
+ * `projects`, `profiles`, `settings`, `defaults`, `providers`, `models`,
9
+ * `agents`.
10
+ *
11
+ * Реализация разложена по файлам (по одному ответственному порту/семейству):
12
+ * - `principals-projects.ts` → `projects` (projects + project_members);
13
+ * - `principals-profiles.ts` → `profiles` (profiles + profile_identities);
14
+ * - `principals-settings.ts` → `settings` (settings + token_ratios +
15
+ * migration_markers);
16
+ * - `principals-defaults.ts` → `defaults` (ключ в `settings`);
17
+ * - `principals-documents.ts` → `providers`/`models`/`agents` (documents).
18
+ *
19
+ * `deps.dataDir` этим портам не нужен: всё состояние — в БД (секции/документы),
20
+ * файловых путей у группы нет. Контракты — `packages/core/src/storage/contract/*`.
21
+ */
22
+ import { createDocumentPort, } from './principals-documents.js';
23
+ import { createPrincipalDefaultsPort } from './principals-defaults.js';
24
+ import { createPrincipalProfilesPort } from './principals-profiles.js';
25
+ import { createPrincipalProjectsPort } from './principals-projects.js';
26
+ import { createPrincipalSettingsPort } from './principals-settings.js';
27
+ /** Собрать порты группы `principals`. */
28
+ export function buildPrincipalPorts(deps) {
29
+ const { connection } = deps;
30
+ return {
31
+ projects: createPrincipalProjectsPort(connection),
32
+ profiles: createPrincipalProfilesPort(connection),
33
+ settings: createPrincipalSettingsPort(connection),
34
+ defaults: createPrincipalDefaultsPort(connection),
35
+ providers: createDocumentPort(connection, 'provider'),
36
+ models: createDocumentPort(connection, 'model'),
37
+ agents: createDocumentPort(connection, 'agent'),
38
+ };
39
+ }
@@ -0,0 +1,237 @@
1
+ /**
2
+ * Отображение строк PostgreSQL ↔ доменных объектов порта `SessionRepository`
3
+ * (PROP-032, волна 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 { type Checkpoint, type Message, type Session, type SessionReference, type StickyNote } from '@itphx/synth-shared';
22
+ /** Строка `sessions` (jsonb — уже разобранные значения; `bigint` — строка). */
23
+ export interface SessionRow {
24
+ id: string;
25
+ title: string | null;
26
+ icon: string | null;
27
+ color: string | null;
28
+ session_origin: string;
29
+ parent_id: string | null;
30
+ branch_point: string | null;
31
+ plan_approved: boolean | null;
32
+ mode: string | null;
33
+ user_id: string | null;
34
+ owner_id: string | null;
35
+ project_id: string | null;
36
+ todos: unknown;
37
+ prompt_states: unknown;
38
+ obfuscation_map: unknown;
39
+ status: unknown;
40
+ settings: unknown;
41
+ mcp_servers: unknown;
42
+ pending_messages: unknown;
43
+ current_stream: unknown;
44
+ summarization_pending: boolean;
45
+ can_summarize: boolean;
46
+ created_at: string | Date;
47
+ updated_at: string | Date;
48
+ expires_at: string | Date | null;
49
+ archived_at: string | Date | null;
50
+ input_tokens: string | number;
51
+ output_tokens: string | number;
52
+ total_tokens: string | number;
53
+ cache_read_tokens: string | number;
54
+ cache_write_tokens: string | number;
55
+ reasoning_tokens: string | number;
56
+ input_cost: number | string;
57
+ output_cost: number | string;
58
+ cache_read_cost: number | string;
59
+ cache_write_cost: number | string;
60
+ cache_hit_rate: number | string | null;
61
+ }
62
+ /** Строка `messages` (или элемент jsonb-массива `pending_messages`/`checkpoints.messages`). */
63
+ export interface MessageRow {
64
+ id: string;
65
+ session_id?: string;
66
+ seq: number;
67
+ role: string;
68
+ origin: string;
69
+ source_msg_id?: string | null;
70
+ content: string;
71
+ parts: unknown;
72
+ tool_calls?: unknown;
73
+ tool_call_id?: string | null;
74
+ usage?: unknown;
75
+ metadata?: unknown;
76
+ prompt_meta?: unknown;
77
+ debug_data?: unknown;
78
+ summary_of?: unknown;
79
+ model?: string | null;
80
+ provider?: string | null;
81
+ provider_type?: string | null;
82
+ reasoning?: string | null;
83
+ source?: string | null;
84
+ author?: string | null;
85
+ agent_role?: string | null;
86
+ qa_pass?: boolean | null;
87
+ qa_reason?: string | null;
88
+ disabled?: boolean | null;
89
+ pinned?: boolean | null;
90
+ hidden?: boolean | null;
91
+ ephemeral?: boolean | null;
92
+ created_at: string | Date;
93
+ }
94
+ /** Строка `session_references` (суррогатный `id` + `ordinal` — порядок добавления). */
95
+ export interface SessionReferenceRow {
96
+ id: string;
97
+ session_id: string;
98
+ ref_session_id: string;
99
+ label: string;
100
+ message_range: unknown;
101
+ auto_summary: string | null;
102
+ ordinal: number;
103
+ created_at: string | Date;
104
+ }
105
+ /** Строка `checkpoints`. */
106
+ export interface CheckpointRow {
107
+ id: string;
108
+ session_id: string;
109
+ messages: unknown;
110
+ created_at: string | Date;
111
+ }
112
+ /** Строка `sticky_notes`. */
113
+ export interface StickyNoteRow {
114
+ id: string;
115
+ session_id: string;
116
+ content: string;
117
+ disabled: boolean;
118
+ created_at: string | Date;
119
+ updated_at: string | Date;
120
+ }
121
+ /** Child-данные одной сессии (загружаются батчем, отдельными запросами). */
122
+ export interface SessionChildren {
123
+ messages: MessageRow[];
124
+ references: SessionReferenceRow[];
125
+ checkpoints: CheckpointRow[];
126
+ stickyNotes: StickyNoteRow[];
127
+ }
128
+ /** Пустой набор child-данных (сессия без сообщений/ссылок/чекпоинтов). */
129
+ export declare function emptySessionChildren(): SessionChildren;
130
+ /** Часть сообщения в форме хранения (`{id, type, data}`). */
131
+ export interface SerializedPart {
132
+ id: string;
133
+ type: string;
134
+ data: unknown;
135
+ }
136
+ /** Usage сообщения в форме хранения (snake_case — как в файловом backend). */
137
+ export interface SerializedUsage {
138
+ input_tokens: number;
139
+ output_tokens: number;
140
+ total_tokens: number;
141
+ cache_read_tokens?: number;
142
+ cache_write_tokens?: number;
143
+ reasoning_tokens?: number;
144
+ }
145
+ /** Сообщение в форме файловой реализации (совпадает с колонками `messages`). */
146
+ export interface SerializedMessage {
147
+ id: string;
148
+ role: string;
149
+ seq: number;
150
+ origin: string;
151
+ source_msg_id?: string;
152
+ parts: SerializedPart[];
153
+ content: string;
154
+ tool_calls?: Record<string, unknown>[];
155
+ tool_call_id?: string;
156
+ created_at: string;
157
+ disabled: boolean;
158
+ pinned: boolean;
159
+ hidden: boolean;
160
+ ephemeral?: boolean;
161
+ debug_data?: Record<string, unknown>;
162
+ model?: string;
163
+ provider?: string;
164
+ provider_type?: string;
165
+ usage?: SerializedUsage;
166
+ reasoning?: string;
167
+ source?: string;
168
+ author?: string;
169
+ agent_role?: string;
170
+ metadata?: Record<string, unknown>;
171
+ prompt_meta?: unknown;
172
+ summary_of?: number[];
173
+ qa_pass?: boolean;
174
+ qa_reason?: string;
175
+ }
176
+ /** `timestamptz` (Date) либо уже готовую строку → ISO-строку. */
177
+ export declare function toIso(value: unknown): string;
178
+ /** Необязательное время: `null`/пусто → `undefined`. */
179
+ export declare function toIsoOrUndefined(value: unknown): string | undefined;
180
+ /** `bigint`/`double precision` (число или строка) → число; `null`/NaN → `fallback`. */
181
+ export declare function toNumber(value: unknown, fallback?: number): number;
182
+ /** Необязательное число (nullable-колонка). */
183
+ export declare function toNumberOrUndefined(value: unknown): number | undefined;
184
+ /** Сообщение → форма хранения (дословно `serializeMessage` файловой реализации). */
185
+ export declare function serializeMessage(msg: Message): SerializedMessage;
186
+ /**
187
+ * Сообщение → строка `messages`: к сериализованной форме добавляются обязательные
188
+ * колонки (`session_id`, дефолты NOT NULL-полей, `id`). Значения `undefined` для
189
+ * nullable-колонок остаются как есть — их приводит к `NULL` слой параметров.
190
+ *
191
+ * `seq` — **позиционный**: драйвер передаёт номер сообщения в массиве (`1..n`),
192
+ * поэтому порядок сообщений в БД однозначен даже для legacy-сессий, где у всех
193
+ * сообщений исторически `seq = 0` (снятие коллизии `UNIQUE (session_id, seq)`).
194
+ * Без явного `seq` используется значение домена (или `0`).
195
+ */
196
+ export declare function messageRow(msg: Message, sessionId: string, seq?: number): Record<string, unknown>;
197
+ /**
198
+ * Строка `messages` (или jsonb-элемент) → доменное сообщение: дословный
199
+ * `deserializeMessage` файловой реализации, включая legacy-ветку без `parts`.
200
+ */
201
+ export declare function deserializeMessage(row: MessageRow): Message;
202
+ /**
203
+ * Сессия → строка `sessions` (колонки — как в `serializeSession` файловой
204
+ * реализации; jsonb-поля остаются нативными значениями, их сериализует слой
205
+ * параметров `jsonParam`).
206
+ */
207
+ export declare function serializeSession(session: Session): Record<string, unknown>;
208
+ /**
209
+ * Строка `session_references` ← доменная ссылка. `id` — суррогатный
210
+ * (генерируется при записи), `ordinal` — позиция в списке ссылок сессии
211
+ * (порядок добавления, `addReference` — append; дубликаты разрешены).
212
+ */
213
+ export declare function referenceRow(sessionId: string, ref: SessionReference, ordinal: number): Record<string, unknown>;
214
+ /** Строка `session_references` → доменная ссылка. */
215
+ export declare function deserializeReference(row: SessionReferenceRow): SessionReference;
216
+ /** Строка `checkpoints` ← доменный чекпоинт (сообщения — jsonb-массив). */
217
+ export declare function checkpointRow(cp: Checkpoint): Record<string, unknown>;
218
+ /** Строка `checkpoints` → доменный чекпоинт. */
219
+ export declare function deserializeCheckpoint(row: CheckpointRow): Checkpoint;
220
+ /** Строка `sticky_notes` ← доменная заметка. */
221
+ export declare function stickyNoteRow(sessionId: string, note: StickyNote): Record<string, unknown>;
222
+ /** Строка `sticky_notes` → доменная заметка. */
223
+ export declare function deserializeStickyNote(row: StickyNoteRow): StickyNote;
224
+ /**
225
+ * Строка `sessions` + child-данные → доменная сессия: дословный
226
+ * `deserializeSession` файловой реализации (нормализация иконки/цвета,
227
+ * `sessionOrigin || 'user'`, числовые/булевы дефолты, сборка
228
+ * `references`/`checkpoints`/`stickyNotes`).
229
+ */
230
+ export declare function deserializeSession(row: SessionRow, children: SessionChildren): Session;
231
+ /**
232
+ * Строка `sessions` → доменная сессия **без истории** (`SessionRepository.listLight`,
233
+ * PROP-032): `messages`/`pendingMessages`/`checkpoints` пусты, child-таблицы не
234
+ * читаются. Метаданные (id/статус/settings/projectId/expiresAt/…) идентичны
235
+ * `deserializeSession` — механика переиспользуется.
236
+ */
237
+ export declare function deserializeSessionLight(row: SessionRow): Session;