@llblab/pi-kit 0.27.6 → 0.28.0

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 (182) hide show
  1. package/BACKLOG.md +2 -5
  2. package/CHANGELOG.md +5 -0
  3. package/README.md +2 -2
  4. package/node_modules/@llblab/pi-telegram/AGENTS.md +10 -8
  5. package/node_modules/@llblab/pi-telegram/BACKLOG.md +1 -9
  6. package/node_modules/@llblab/pi-telegram/CHANGELOG.md +13 -0
  7. package/node_modules/@llblab/pi-telegram/LICENSE +21 -0
  8. package/node_modules/@llblab/pi-telegram/README.md +15 -5
  9. package/node_modules/@llblab/pi-telegram/dist/lib/activity-verbosity.d.ts +1 -5
  10. package/node_modules/@llblab/pi-telegram/dist/lib/activity-verbosity.js +5 -7
  11. package/node_modules/@llblab/pi-telegram/dist/lib/bindings.d.ts +5 -1
  12. package/node_modules/@llblab/pi-telegram/dist/lib/bindings.js +6 -1
  13. package/node_modules/@llblab/pi-telegram/dist/lib/bus-api.js +4 -2
  14. package/node_modules/@llblab/pi-telegram/dist/lib/bus-follower.d.ts +54 -56
  15. package/node_modules/@llblab/pi-telegram/dist/lib/bus-follower.js +206 -139
  16. package/node_modules/@llblab/pi-telegram/dist/lib/bus-leader.d.ts +21 -2
  17. package/node_modules/@llblab/pi-telegram/dist/lib/bus-leader.js +181 -25
  18. package/node_modules/@llblab/pi-telegram/dist/lib/bus-transport.d.ts +4 -1
  19. package/node_modules/@llblab/pi-telegram/dist/lib/bus-transport.js +28 -4
  20. package/node_modules/@llblab/pi-telegram/dist/lib/bus.d.ts +52 -56
  21. package/node_modules/@llblab/pi-telegram/dist/lib/bus.js +78 -246
  22. package/node_modules/@llblab/pi-telegram/dist/lib/channel-posts.d.ts +1 -3
  23. package/node_modules/@llblab/pi-telegram/dist/lib/channel-posts.js +23 -26
  24. package/node_modules/@llblab/pi-telegram/dist/lib/command-templates.d.ts +0 -5
  25. package/node_modules/@llblab/pi-telegram/dist/lib/command-templates.js +5 -5
  26. package/node_modules/@llblab/pi-telegram/dist/lib/commands.d.ts +0 -23
  27. package/node_modules/@llblab/pi-telegram/dist/lib/commands.js +15 -15
  28. package/node_modules/@llblab/pi-telegram/dist/lib/config.d.ts +0 -17
  29. package/node_modules/@llblab/pi-telegram/dist/lib/config.js +12 -14
  30. package/node_modules/@llblab/pi-telegram/dist/lib/delivery.d.ts +0 -4
  31. package/node_modules/@llblab/pi-telegram/dist/lib/delivery.js +2 -5
  32. package/node_modules/@llblab/pi-telegram/dist/lib/extension.js +255 -61
  33. package/node_modules/@llblab/pi-telegram/dist/lib/generative-apps.d.ts +0 -19
  34. package/node_modules/@llblab/pi-telegram/dist/lib/inbound.d.ts +0 -2
  35. package/node_modules/@llblab/pi-telegram/dist/lib/inbound.js +2 -2
  36. package/node_modules/@llblab/pi-telegram/dist/lib/journal.d.ts +177 -16
  37. package/node_modules/@llblab/pi-telegram/dist/lib/journal.js +1115 -249
  38. package/node_modules/@llblab/pi-telegram/dist/lib/keyboard.d.ts +0 -2
  39. package/node_modules/@llblab/pi-telegram/dist/lib/keyboard.js +2 -2
  40. package/node_modules/@llblab/pi-telegram/dist/lib/lifecycle.js +1 -1
  41. package/node_modules/@llblab/pi-telegram/dist/lib/locks.d.ts +100 -12
  42. package/node_modules/@llblab/pi-telegram/dist/lib/locks.js +380 -14
  43. package/node_modules/@llblab/pi-telegram/dist/lib/logging.d.ts +30 -12
  44. package/node_modules/@llblab/pi-telegram/dist/lib/logging.js +129 -72
  45. package/node_modules/@llblab/pi-telegram/dist/lib/media.d.ts +28 -5
  46. package/node_modules/@llblab/pi-telegram/dist/lib/media.js +26 -8
  47. package/node_modules/@llblab/pi-telegram/dist/lib/menu-model.d.ts +0 -11
  48. package/node_modules/@llblab/pi-telegram/dist/lib/menu-model.js +8 -8
  49. package/node_modules/@llblab/pi-telegram/dist/lib/menu-settings.d.ts +0 -18
  50. package/node_modules/@llblab/pi-telegram/dist/lib/menu-settings.js +18 -18
  51. package/node_modules/@llblab/pi-telegram/dist/lib/menu-status.d.ts +4 -4
  52. package/node_modules/@llblab/pi-telegram/dist/lib/menu-status.js +12 -7
  53. package/node_modules/@llblab/pi-telegram/dist/lib/menu-thinking.d.ts +1 -1
  54. package/node_modules/@llblab/pi-telegram/dist/lib/menu-thinking.js +1 -1
  55. package/node_modules/@llblab/pi-telegram/dist/lib/menu.d.ts +1 -0
  56. package/node_modules/@llblab/pi-telegram/dist/lib/menu.js +4 -3
  57. package/node_modules/@llblab/pi-telegram/dist/lib/outbound-attachments.d.ts +0 -1
  58. package/node_modules/@llblab/pi-telegram/dist/lib/outbound-attachments.js +1 -1
  59. package/node_modules/@llblab/pi-telegram/dist/lib/outbound-buttons.js +1 -8
  60. package/node_modules/@llblab/pi-telegram/dist/lib/outbound-markup.d.ts +1 -6
  61. package/node_modules/@llblab/pi-telegram/dist/lib/outbound-markup.js +4 -21
  62. package/node_modules/@llblab/pi-telegram/dist/lib/outbound.d.ts +0 -8
  63. package/node_modules/@llblab/pi-telegram/dist/lib/outbound.js +5 -5
  64. package/node_modules/@llblab/pi-telegram/dist/lib/paths.d.ts +50 -7
  65. package/node_modules/@llblab/pi-telegram/dist/lib/paths.js +155 -17
  66. package/node_modules/@llblab/pi-telegram/dist/lib/pi.d.ts +1 -0
  67. package/node_modules/@llblab/pi-telegram/dist/lib/pi.js +2 -1
  68. package/node_modules/@llblab/pi-telegram/dist/lib/polling.d.ts +0 -5
  69. package/node_modules/@llblab/pi-telegram/dist/lib/polling.js +5 -5
  70. package/node_modules/@llblab/pi-telegram/dist/lib/preview.d.ts +0 -3
  71. package/node_modules/@llblab/pi-telegram/dist/lib/preview.js +3 -3
  72. package/node_modules/@llblab/pi-telegram/dist/lib/prompt-templates.d.ts +0 -1
  73. package/node_modules/@llblab/pi-telegram/dist/lib/prompt-templates.js +1 -1
  74. package/node_modules/@llblab/pi-telegram/dist/lib/queue.d.ts +3 -15
  75. package/node_modules/@llblab/pi-telegram/dist/lib/queue.js +69 -8
  76. package/node_modules/@llblab/pi-telegram/dist/lib/recovery.d.ts +29 -9
  77. package/node_modules/@llblab/pi-telegram/dist/lib/recovery.js +104 -33
  78. package/node_modules/@llblab/pi-telegram/dist/lib/replies.d.ts +0 -4
  79. package/node_modules/@llblab/pi-telegram/dist/lib/replies.js +1 -1
  80. package/node_modules/@llblab/pi-telegram/dist/lib/routing.d.ts +73 -8
  81. package/node_modules/@llblab/pi-telegram/dist/lib/routing.js +2206 -307
  82. package/node_modules/@llblab/pi-telegram/dist/lib/sections.d.ts +0 -2
  83. package/node_modules/@llblab/pi-telegram/dist/lib/sections.js +1 -1
  84. package/node_modules/@llblab/pi-telegram/dist/lib/status.d.ts +44 -9
  85. package/node_modules/@llblab/pi-telegram/dist/lib/status.js +149 -27
  86. package/node_modules/@llblab/pi-telegram/dist/lib/sync.d.ts +0 -5
  87. package/node_modules/@llblab/pi-telegram/dist/lib/sync.js +5 -4
  88. package/node_modules/@llblab/pi-telegram/dist/lib/telegram-api.d.ts +11 -3
  89. package/node_modules/@llblab/pi-telegram/dist/lib/telegram-api.js +34 -23
  90. package/node_modules/@llblab/pi-telegram/dist/lib/thread-cleanup-manager.d.ts +1 -0
  91. package/node_modules/@llblab/pi-telegram/dist/lib/thread-cleanup-manager.js +18 -21
  92. package/node_modules/@llblab/pi-telegram/dist/lib/thread-naming.d.ts +32 -5
  93. package/node_modules/@llblab/pi-telegram/dist/lib/thread-naming.js +191 -7
  94. package/node_modules/@llblab/pi-telegram/dist/lib/thread-reconciler.d.ts +2 -0
  95. package/node_modules/@llblab/pi-telegram/dist/lib/thread-reconciler.js +1 -1
  96. package/node_modules/@llblab/pi-telegram/dist/lib/threads.d.ts +291 -59
  97. package/node_modules/@llblab/pi-telegram/dist/lib/threads.js +1647 -369
  98. package/node_modules/@llblab/pi-telegram/dist/lib/turns.d.ts +0 -1
  99. package/node_modules/@llblab/pi-telegram/dist/lib/turns.js +1 -1
  100. package/node_modules/@llblab/pi-telegram/dist/lib/updates.d.ts +184 -28
  101. package/node_modules/@llblab/pi-telegram/dist/lib/updates.js +1032 -114
  102. package/node_modules/@llblab/pi-telegram/dist/lib/wire.d.ts +12 -0
  103. package/node_modules/@llblab/pi-telegram/dist/lib/wire.js +21 -0
  104. package/node_modules/@llblab/pi-telegram/dist/lib/workspace-admission.d.ts +25 -17
  105. package/node_modules/@llblab/pi-telegram/dist/lib/workspace-admission.js +95 -20
  106. package/node_modules/@llblab/pi-telegram/dist/lib/workspace-identity.d.ts +20 -0
  107. package/node_modules/@llblab/pi-telegram/dist/lib/workspace-identity.js +103 -0
  108. package/node_modules/@llblab/pi-telegram/dist/lib/workspace-retirement.d.ts +43 -8
  109. package/node_modules/@llblab/pi-telegram/dist/lib/workspace-retirement.js +148 -52
  110. package/node_modules/@llblab/pi-telegram/dist/package.json +6 -6
  111. package/node_modules/@llblab/pi-telegram/dist/skills/generated-control-surface/SKILL.md +3 -3
  112. package/node_modules/@llblab/pi-telegram/dist/skills/telegram-bridge/references/diagnosis.md +3 -3
  113. package/node_modules/@llblab/pi-telegram/docs/README.md +1 -1
  114. package/node_modules/@llblab/pi-telegram/docs/activity.md +1 -1
  115. package/node_modules/@llblab/pi-telegram/docs/architecture.md +152 -34
  116. package/node_modules/@llblab/pi-telegram/docs/callback-namespaces.md +1 -1
  117. package/node_modules/@llblab/pi-telegram/docs/delivery.md +1 -1
  118. package/node_modules/@llblab/pi-telegram/docs/generative-apps.md +2 -2
  119. package/node_modules/@llblab/pi-telegram/docs/inbound.md +1 -1
  120. package/node_modules/@llblab/pi-telegram/docs/multi-instance-bus.md +125 -19
  121. package/node_modules/@llblab/pi-telegram/docs/public-api.md +3 -1
  122. package/node_modules/@llblab/pi-telegram/docs/ui-style.md +22 -8
  123. package/node_modules/@llblab/pi-telegram/docs/updates.md +1 -1
  124. package/node_modules/@llblab/pi-telegram/lib/activity-verbosity.ts +5 -9
  125. package/node_modules/@llblab/pi-telegram/lib/bindings.ts +6 -0
  126. package/node_modules/@llblab/pi-telegram/lib/bus-api.ts +5 -2
  127. package/node_modules/@llblab/pi-telegram/lib/bus-follower.ts +243 -224
  128. package/node_modules/@llblab/pi-telegram/lib/bus-leader.ts +178 -31
  129. package/node_modules/@llblab/pi-telegram/lib/bus-transport.ts +30 -8
  130. package/node_modules/@llblab/pi-telegram/lib/bus.ts +110 -334
  131. package/node_modules/@llblab/pi-telegram/lib/channel-posts.ts +29 -29
  132. package/node_modules/@llblab/pi-telegram/lib/command-templates.ts +5 -5
  133. package/node_modules/@llblab/pi-telegram/lib/commands.ts +15 -15
  134. package/node_modules/@llblab/pi-telegram/lib/config.ts +12 -17
  135. package/node_modules/@llblab/pi-telegram/lib/delivery.ts +2 -8
  136. package/node_modules/@llblab/pi-telegram/lib/extension.ts +257 -72
  137. package/node_modules/@llblab/pi-telegram/lib/generative-apps.ts +0 -22
  138. package/node_modules/@llblab/pi-telegram/lib/inbound.ts +2 -2
  139. package/node_modules/@llblab/pi-telegram/lib/journal.ts +1182 -326
  140. package/node_modules/@llblab/pi-telegram/lib/keyboard.ts +2 -2
  141. package/node_modules/@llblab/pi-telegram/lib/lifecycle.ts +1 -1
  142. package/node_modules/@llblab/pi-telegram/lib/locks.ts +402 -23
  143. package/node_modules/@llblab/pi-telegram/lib/logging.ts +151 -101
  144. package/node_modules/@llblab/pi-telegram/lib/media.ts +51 -9
  145. package/node_modules/@llblab/pi-telegram/lib/menu-model.ts +8 -8
  146. package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts +18 -18
  147. package/node_modules/@llblab/pi-telegram/lib/menu-status.ts +11 -0
  148. package/node_modules/@llblab/pi-telegram/lib/menu-thinking.ts +2 -2
  149. package/node_modules/@llblab/pi-telegram/lib/menu.ts +5 -1
  150. package/node_modules/@llblab/pi-telegram/lib/outbound-attachments.ts +1 -1
  151. package/node_modules/@llblab/pi-telegram/lib/outbound-buttons.ts +1 -10
  152. package/node_modules/@llblab/pi-telegram/lib/outbound-markup.ts +5 -24
  153. package/node_modules/@llblab/pi-telegram/lib/outbound.ts +5 -5
  154. package/node_modules/@llblab/pi-telegram/lib/paths.ts +177 -17
  155. package/node_modules/@llblab/pi-telegram/lib/pi.ts +5 -2
  156. package/node_modules/@llblab/pi-telegram/lib/polling.ts +5 -5
  157. package/node_modules/@llblab/pi-telegram/lib/preview.ts +3 -3
  158. package/node_modules/@llblab/pi-telegram/lib/prompt-templates.ts +1 -1
  159. package/node_modules/@llblab/pi-telegram/lib/queue.ts +67 -9
  160. package/node_modules/@llblab/pi-telegram/lib/recovery.ts +104 -44
  161. package/node_modules/@llblab/pi-telegram/lib/replies.ts +1 -1
  162. package/node_modules/@llblab/pi-telegram/lib/routing.ts +1955 -375
  163. package/node_modules/@llblab/pi-telegram/lib/sections.ts +1 -1
  164. package/node_modules/@llblab/pi-telegram/lib/status.ts +156 -36
  165. package/node_modules/@llblab/pi-telegram/lib/sync.ts +4 -4
  166. package/node_modules/@llblab/pi-telegram/lib/telegram-api.ts +48 -33
  167. package/node_modules/@llblab/pi-telegram/lib/thread-cleanup-manager.ts +24 -21
  168. package/node_modules/@llblab/pi-telegram/lib/thread-naming.ts +267 -9
  169. package/node_modules/@llblab/pi-telegram/lib/thread-reconciler.ts +3 -1
  170. package/node_modules/@llblab/pi-telegram/lib/threads.ts +1697 -488
  171. package/node_modules/@llblab/pi-telegram/lib/turns.ts +1 -1
  172. package/node_modules/@llblab/pi-telegram/lib/updates.ts +1072 -151
  173. package/node_modules/@llblab/pi-telegram/lib/wire.ts +28 -0
  174. package/node_modules/@llblab/pi-telegram/lib/workspace-admission.ts +97 -47
  175. package/node_modules/@llblab/pi-telegram/lib/workspace-identity.ts +147 -0
  176. package/node_modules/@llblab/pi-telegram/lib/workspace-retirement.ts +188 -89
  177. package/node_modules/@llblab/pi-telegram/package.json +6 -6
  178. package/node_modules/@llblab/pi-telegram/scripts/audit-exports.mjs +100 -0
  179. package/node_modules/@llblab/pi-telegram/scripts/check-downgrade.mjs +80 -43
  180. package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/SKILL.md +3 -3
  181. package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/references/diagnosis.md +3 -3
  182. package/package.json +2 -2
@@ -1,36 +1,94 @@
1
1
  /**
2
2
  * Telegram thread binding helpers
3
- * Zones: multi-instance bus, Telegram UI threads, volatile extension state
4
- * Owns current live instance-binding to Telegram UI thread mappings backed by Bot API ForumTopic/message_thread_id transport
3
+ * Zones: multi-instance bus, Telegram UI threads, durable Workspace state
4
+ * Owns live mappings, Workspace bindings and guarded Restore transitions; routing and transport effects stay outside.
5
5
  */
6
6
 
7
7
  import { createHash, randomUUID } from "node:crypto";
8
8
  import {
9
9
  chmodSync,
10
+ closeSync,
11
+ constants,
10
12
  existsSync,
13
+ fstatSync,
14
+ lstatSync,
15
+ mkdirSync,
16
+ openSync,
17
+ readFile as readFileCallback,
11
18
  readFileSync,
12
19
  renameSync,
20
+ unlinkSync,
13
21
  writeFileSync,
14
22
  } from "node:fs";
15
23
  import {
16
24
  chmod,
17
25
  mkdir,
18
- readFile,
19
- rename,
20
26
  unlink,
21
27
  writeFile,
22
28
  } from "node:fs/promises";
23
- import { dirname, posix, resolve } from "node:path";
24
- import { isDeepStrictEqual } from "node:util";
29
+ import { basename, dirname, join } from "node:path";
30
+ import { isDeepStrictEqual, promisify } from "node:util";
25
31
 
26
32
  import {
27
33
  isTelegramApiCommitUnknownError,
28
34
  TelegramApiCommitUnknownError,
29
35
  type TelegramApiCallOptions,
30
36
  } from "./telegram-api.ts";
31
- import type { TelegramTarget } from "./target.ts";
32
- import { withTelegramFileTransaction } from "./locks.ts";
37
+ import {
38
+ areTelegramTargetsEqual as targetMatches,
39
+ getTelegramTargetKey as getTargetRecoveryHintKey,
40
+ type TelegramTarget,
41
+ } from "./target.ts";
42
+ import { isWireRecord as restoreObject, isNonEmptyWireString as restoreText } from "./wire.ts";
43
+ import {
44
+ chooseTelegramThreadName,
45
+ getTelegramManualThreadDisplayNameValidationError,
46
+ getTelegramThreadNameLeadingSlot,
47
+ getTelegramTopicIdentityName,
48
+ getTelegramTopicName as buildTelegramTopicName,
49
+ getTelegramTopicTitleForThreadName,
50
+ isTelegramTopicThreadNameValidForSlot,
51
+ normalizeTelegramTopicTargetThreadName,
52
+ } from "./thread-naming.ts";
53
+ export {
54
+ chooseTelegramThreadName,
55
+ createTelegramThreadName,
56
+ getTelegramManualThreadDisplayNameValidationError,
57
+ getTelegramTopicIdentityName,
58
+ getTelegramTopicThreadNameValidationError,
59
+ getTelegramTopicTitleForThreadName,
60
+ isTelegramTopicThreadNameValidForSlot,
61
+ type TelegramThreadNameInput,
62
+ } from "./thread-naming.ts";
63
+
64
+ // Preserve the legacy provision-request signature without a runtime wrapper.
65
+ export const getTelegramTopicName: (
66
+ request: TelegramTopicTargetProvisionRequest,
67
+ template?: string,
68
+ slot?: string,
69
+ ) => string = buildTelegramTopicName;
70
+ import {
71
+ TELEGRAM_WORKSPACE_KEY_MAX_LENGTH,
72
+ createTelegramSessionKey,
73
+ createTelegramWorkspaceBindingIdentityWithKey,
74
+ createTelegramWorkspaceDirectoryKey,
75
+ normalizeTelegramSessionId,
76
+ normalizeTelegramWorkspacePath,
77
+ type TelegramWorkspaceBindingIdentity,
78
+ } from "./workspace-identity.ts";
79
+ export {
80
+ createTelegramWorkspaceBindingIdentity,
81
+ createTelegramWorkspaceDirectoryKey,
82
+ normalizeTelegramSessionId,
83
+ normalizeTelegramWorkspacePath,
84
+ type TelegramWorkspaceBindingIdentity,
85
+ } from "./workspace-identity.ts";
86
+ import { withTelegramFileTransaction, readTelegramRuntimeState,
87
+ type TelegramLockRuntime, type TelegramLockContext, type TelegramRuntimeStateMutation,
88
+ type TelegramOwnedStatePublicationOptions, type TelegramOwnedStatePublicationResult,
89
+ } from "./locks.ts";
33
90
  import * as ThreadReconciler from "./thread-reconciler.ts";
91
+ import { createTelegramRuntimeProjectionStore } from "./status.ts";
34
92
  import {
35
93
  planTelegramWorkspaceSlotAllocation,
36
94
  TELEGRAM_WORKSPACE_SLOTS,
@@ -42,153 +100,6 @@ import {
42
100
  resolveTelegramProfileTempFilePath,
43
101
  } from "./paths.ts";
44
102
 
45
- export interface TelegramThreadNameInput {
46
- seed: string;
47
- cwd?: string;
48
- role?: "leader" | "follower";
49
- peers?: readonly string[];
50
- slot?: string;
51
- }
52
-
53
- export interface TelegramWorkspaceBindingIdentity {
54
- cwd: string;
55
- workspaceKey: string;
56
- /** Exact durable Pi session identity; absent only on legacy cwd-only bindings. */
57
- sessionId?: string;
58
- /** Full SHA-256 index component for session-qualified bindings. */
59
- sessionKey?: string;
60
- /** Immutable legacy binding-key component, not the displayed global letter. */
61
- instanceSlot: string;
62
- bindingKey: string;
63
- /** Profile-wide letter reserved by the transient claim. */
64
- slot?: string;
65
- }
66
-
67
- const TELEGRAM_WORKSPACE_KEY_MAX_LENGTH = 180;
68
- const TELEGRAM_SESSION_ID_MAX_LENGTH = 256;
69
-
70
- export function normalizeTelegramSessionId(
71
- sessionId: string,
72
- ): string | undefined {
73
- if (typeof sessionId !== "string") return undefined;
74
- const normalized = sessionId.trim();
75
- return normalized && Buffer.byteLength(normalized, "utf8") <=
76
- TELEGRAM_SESSION_ID_MAX_LENGTH
77
- ? normalized
78
- : undefined;
79
- }
80
-
81
- export function createTelegramSessionKey(
82
- sessionId: string,
83
- ): string | undefined {
84
- const normalized = normalizeTelegramSessionId(sessionId);
85
- return normalized
86
- ? createHash("sha256").update(normalized).digest("hex")
87
- : undefined;
88
- }
89
-
90
- export function normalizeTelegramWorkspacePath(
91
- cwd: string,
92
- ): string | undefined {
93
- const trimmed = cwd.trim();
94
- if (!trimmed) return undefined;
95
- const normalized = (trimmed.startsWith("/")
96
- ? posix.normalize(trimmed)
97
- : resolve(trimmed).replaceAll("\\", "/"));
98
- const withoutTrailingSeparators =
99
- normalized.length > 1 ? normalized.replace(/\/+$/u, "") : normalized;
100
- return process.platform === "win32"
101
- ? withoutTrailingSeparators.replace(/^([A-Z]):/u, (_, drive: string) =>
102
- `${drive.toLowerCase()}:`,
103
- )
104
- : withoutTrailingSeparators;
105
- }
106
-
107
- export function createTelegramWorkspaceDirectoryKey(
108
- cwd: string,
109
- ): string | undefined {
110
- const normalized = normalizeTelegramWorkspacePath(cwd);
111
- if (!normalized) return undefined;
112
- const readable =
113
- normalized
114
- .replace(/[^\p{L}\p{N}._-]+/gu, "-")
115
- .replace(/^-+|-+$/gu, "") || "root";
116
- const candidate = `--${readable}--`;
117
- if (candidate.length <= TELEGRAM_WORKSPACE_KEY_MAX_LENGTH) return candidate;
118
- const digest = createHash("sha256")
119
- .update(normalized)
120
- .digest("hex")
121
- .slice(0, 12);
122
- const prefixLength =
123
- TELEGRAM_WORKSPACE_KEY_MAX_LENGTH - digest.length - 5;
124
- return `--${readable.slice(0, prefixLength)}-${digest}--`;
125
- }
126
-
127
- function createTelegramWorkspaceInstanceSlot(
128
- ordinal: number,
129
- ): string | undefined {
130
- if (!Number.isSafeInteger(ordinal) || ordinal < 0) return undefined;
131
- let value = ordinal + 1;
132
- let slot = "";
133
- while (value > 0) {
134
- value -= 1;
135
- slot = String.fromCharCode(97 + (value % 26)) + slot;
136
- value = Math.floor(value / 26);
137
- }
138
- return slot;
139
- }
140
-
141
- function createTelegramWorkspaceBindingIdentityWithKey(
142
- cwd: string,
143
- workspaceKey: string,
144
- ordinal: number,
145
- sessionId?: string,
146
- ): TelegramWorkspaceBindingIdentity | undefined {
147
- const instanceSlot = createTelegramWorkspaceInstanceSlot(ordinal);
148
- if (!instanceSlot) return undefined;
149
- const normalizedSessionId = sessionId === undefined
150
- ? undefined
151
- : normalizeTelegramSessionId(sessionId);
152
- const sessionKey = normalizedSessionId
153
- ? createTelegramSessionKey(normalizedSessionId)
154
- : undefined;
155
- if (sessionId !== undefined && (!normalizedSessionId || !sessionKey)) {
156
- return undefined;
157
- }
158
- const legacyBindingKey = instanceSlot === "a"
159
- ? workspaceKey
160
- : `${workspaceKey}${instanceSlot}`;
161
- return {
162
- cwd,
163
- workspaceKey,
164
- ...(normalizedSessionId && sessionKey
165
- ? { sessionId: normalizedSessionId, sessionKey }
166
- : {}),
167
- instanceSlot,
168
- bindingKey: sessionKey
169
- ? `${legacyBindingKey}-s-${sessionKey}`
170
- : legacyBindingKey,
171
- };
172
- }
173
-
174
- export function createTelegramWorkspaceBindingIdentity(
175
- cwd: string,
176
- ordinal = 0,
177
- sessionId?: string,
178
- ): TelegramWorkspaceBindingIdentity | undefined {
179
- const normalized = normalizeTelegramWorkspacePath(cwd);
180
- const workspaceKey = normalized
181
- ? createTelegramWorkspaceDirectoryKey(normalized)
182
- : undefined;
183
- if (!normalized || !workspaceKey) return undefined;
184
- return createTelegramWorkspaceBindingIdentityWithKey(
185
- normalized,
186
- workspaceKey,
187
- ordinal,
188
- sessionId,
189
- );
190
- }
191
-
192
103
  export type TelegramTopicTargetStatus =
193
104
  | "active"
194
105
  | "offline"
@@ -243,7 +154,7 @@ export interface TelegramThreadPendingProvision {
243
154
  export type TelegramThreadCleanupIntent =
244
155
  ThreadReconciler.TelegramThreadCleanupIntent;
245
156
 
246
- type TelegramProvisionRecoveryFile = Record<
157
+ export type TelegramProvisionRecoveryFile = Record<
247
158
  string,
248
159
  {
249
160
  instanceId: string;
@@ -292,6 +203,11 @@ export interface TelegramThreadIdentityRecord {
292
203
  updatedAtMs: number;
293
204
  }
294
205
 
206
+ export interface TelegramWorkspaceJournalSource {
207
+ sessionId: string;
208
+ recipientBindingKey: string;
209
+ }
210
+
295
211
  export interface TelegramWorkspaceThreadBinding {
296
212
  cwd: string;
297
213
  workspaceKey: string;
@@ -311,6 +227,8 @@ export interface TelegramWorkspaceThreadBinding {
311
227
  displayTitle?: string;
312
228
  /** Historical follower-journal routing keys that may retain accepted work. */
313
229
  journalBindingKeys?: string[];
230
+ /** Exact session-qualified journal addresses; retained across session re-key. */
231
+ journalSources?: TelegramWorkspaceJournalSource[];
314
232
  /** True only when the historical journal-key set is proven complete. */
315
233
  journalBindingsComplete?: true;
316
234
  /** Sticky once this directory has multiple retained bindings. */
@@ -360,6 +278,164 @@ export interface TelegramBotStateSnapshot {
360
278
  lastReconcileAction?: string;
361
279
  }
362
280
 
281
+ export interface TelegramWorkspaceRelocationRequest {
282
+ operationId: string;
283
+ binding: TelegramWorkspaceThreadBinding;
284
+ owner: TelegramTopicTargetRecord;
285
+ target: TelegramTarget & { threadId: number };
286
+ }
287
+
288
+ export interface TelegramWorkspaceRestoreRequest extends TelegramWorkspaceRelocationRequest {
289
+ source: { journalBindingKey: string; updateIds: number[] };
290
+ }
291
+ export interface TelegramWorkspaceRestoreExecutor { instanceId: string; leaderEpoch: string }
292
+ export interface TelegramWorkspaceRestoreAuthority {
293
+ executor: TelegramWorkspaceRestoreExecutor;
294
+ operatorUserId: number;
295
+ /** Exact profile, transport, session, source and Workspace-admission authority. */
296
+ isCurrent: () => boolean;
297
+ }
298
+ export type TelegramWorkspaceRestoreRecipient = {
299
+ kind: "leader" | "follower"; instanceId: string; sessionId: string; generation: string;
300
+ };
301
+ /** Retained queue admission is nonterminal; queue-completed requires positive journal-owner disposition. */
302
+ export type TelegramWorkspaceRestoreSourceSettlement = {
303
+ journalBindingKey: string; updateIds: number[];
304
+ } & ({ kind: "completed" } |
305
+ { kind: "queued" | "queue-completed"; receiptId: string; queueKind: "prompt" | "control" });
306
+ /** Positive execution/recipient acceptance, retained before source disposition; never a source-removal ACK. */
307
+ export type TelegramWorkspaceRestoreSourceAcceptance = {
308
+ journalBindingKey: string;
309
+ updateId: number;
310
+ /** SHA-256 of the exact journal entry captured by its worker owner, not a routed message projection. */
311
+ sourceSha256: string;
312
+ recipient: TelegramWorkspaceRestoreRecipient;
313
+ } & ({ kind: "completed" } |
314
+ { kind: "forwarded"; deliveryId: string; recipientBindingKey: string } |
315
+ { kind: "queued"; receiptId: string; queueKind: "prompt" | "control"; queueOwnerSha256: string });
316
+ export interface TelegramWorkspaceRestoreIntent {
317
+ request: TelegramWorkspaceRestoreRequest;
318
+ operatorUserId: number;
319
+ executor: TelegramWorkspaceRestoreExecutor;
320
+ revision: number;
321
+ createdAtMs: number;
322
+ updatedAtMs: number;
323
+ phase: "relocated" | "recipient-issued" | "ready";
324
+ committedAtMs: number;
325
+ recipient?: TelegramWorkspaceRestoreRecipient;
326
+ readyRecipient?: TelegramWorkspaceRestoreRecipient;
327
+ routing?: { acceptances?: TelegramWorkspaceRestoreSourceAcceptance[];
328
+ settlements: TelegramWorkspaceRestoreSourceSettlement[]; cleanup?: "issued" | "completed" | "not-issued" };
329
+ }
330
+ /** Immutable source membership, not readiness, cancellation, or proof of complete Thread coverage. */
331
+ export interface TelegramTemporaryThreadInput {
332
+ journalBindingKey: string;
333
+ updateIds: number[];
334
+ }
335
+ /** A strict journal observation of committed cancellation plus matching private retention. */
336
+ export interface TelegramTemporaryThreadCancellationEvidence {
337
+ journalBindingKey: string;
338
+ updateId: number;
339
+ operatorAuthorityId: string;
340
+ }
341
+ /** A bot-created routing tab with an exact creation source; it owns no Pi binding or slot. */
342
+ export interface TelegramTemporaryThreadEntry {
343
+ source: { journalBindingKey: string; updateId: number };
344
+ /** Append-only known source groups. Missing legacy metadata never proves that the creation source was alone. */
345
+ inputs?: TelegramTemporaryThreadInput[];
346
+ /** Whole known groups with positively observed cancellation; never proof that deletion may be issued. */
347
+ cancelledInputs?: TelegramTemporaryThreadInput[];
348
+ /** Whole known groups whose Forward was positively completed by the journal owner; never deletion authority alone. */
349
+ completedInputs?: TelegramTemporaryThreadInput[];
350
+ /** Whole known groups whose Forward was durably issued before local handling/queueing or follower RPC; never delivery proof or a retry grant. */
351
+ forwardedInputs?: TelegramTemporaryThreadInput[];
352
+ /** Published at creation only: every subsequent Forward path must record issuance; missing legacy coverage stays unknown. */
353
+ forwardProtocol?: "one-shot-v1";
354
+ /** Published before the sole cleanup attempt; uncertainty survives executor adoption and restart. */
355
+ cleanupIssued?: true;
356
+ operatorUserId: number;
357
+ executor: TelegramWorkspaceRestoreExecutor;
358
+ /** Unique title token; the only identity an unacknowledged creation may later be matched by. */
359
+ token: string;
360
+ /** `creating` is published before the one creation request, so after a crash its outcome is unknown. */
361
+ phase: "creating" | "created";
362
+ target?: TelegramTarget & { threadId: number };
363
+ revision: number;
364
+ createdAtMs: number;
365
+ updatedAtMs: number;
366
+ }
367
+ /** Canonical target classification only; a bound target still needs live same-session readiness proof. */
368
+ export type TelegramTemporaryThreadTargetObservation =
369
+ | { kind: "bound"; binding: TelegramWorkspaceThreadBinding }
370
+ | { kind: "temporary" }
371
+ | { kind: "unknown" };
372
+ interface TelegramWorkspaceRestoreSnapshot {
373
+ version: 1; profileName: string; tokenSha256: string; revision: number;
374
+ operations: TelegramWorkspaceRestoreIntent[];
375
+ temporaryThreads?: TelegramTemporaryThreadEntry[];
376
+ }
377
+ /** Scope-bound Workspace operations; raw snapshot mutation is private to the store. */
378
+ export interface TelegramWorkspaceRestore {
379
+ list(): TelegramWorkspaceRestoreIntent[];
380
+ commit(request: TelegramWorkspaceRestoreRequest, authority: TelegramWorkspaceRestoreAuthority): Promise<TelegramWorkspaceRestoreIntent | undefined>;
381
+ adopt(expected: TelegramWorkspaceRestoreIntent, authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
382
+ issueRecipient(expected: TelegramWorkspaceRestoreIntent, recipient: TelegramWorkspaceRestoreRecipient, authority: TelegramWorkspaceRestoreAuthority): { issued: true; intent: TelegramWorkspaceRestoreIntent } | undefined;
383
+ confirmReady(expected: TelegramWorkspaceRestoreIntent, acknowledged: TelegramWorkspaceRestoreRecipient, authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
384
+ confirmInspectedReady(expected: TelegramWorkspaceRestoreIntent, observed: TelegramWorkspaceRestoreRecipient, authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
385
+ issueRouting(expected: TelegramWorkspaceRestoreIntent, authority: TelegramWorkspaceRestoreAuthority): { issued: true; intent: TelegramWorkspaceRestoreIntent } | undefined;
386
+ recordSourceAcceptance(expected: TelegramWorkspaceRestoreIntent, evidence: TelegramWorkspaceRestoreSourceAcceptance, authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
387
+ recordSourceSettlement(expected: TelegramWorkspaceRestoreIntent, evidence: TelegramWorkspaceRestoreSourceSettlement, authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
388
+ issueCleanup(expected: TelegramWorkspaceRestoreIntent, authority: TelegramWorkspaceRestoreAuthority): { issued: true; intent: TelegramWorkspaceRestoreIntent } | undefined;
389
+ recordCleanup(expected: TelegramWorkspaceRestoreIntent, result: { target: TelegramWorkspaceRestoreRequest["target"]; kind: "completed" | "not-issued" }, authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
390
+ retire(expected: TelegramWorkspaceRestoreIntent, authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
391
+ /** Caller proves exact operator abandonment of every original; no dispatch grant may exist. */
392
+ retireAbandoned(expected: TelegramWorkspaceRestoreIntent, abandonedUpdateIds: readonly number[], authority: TelegramWorkspaceRestoreAuthority): TelegramWorkspaceRestoreIntent | undefined;
393
+ listTemporaryThreads(): TelegramTemporaryThreadEntry[];
394
+ /** Caller holds admission for effectful use. Fresh exact read grants no adoption, routing, disposition or deletion. */
395
+ inspectTemporaryThreadTarget(expected: TelegramTemporaryThreadEntry, authority: TelegramWorkspaceRestoreAuthority): TelegramTemporaryThreadTargetObservation | undefined;
396
+ /** Read-only veto for an already-granted in-flight attempt; never another grant, disposable classification or deletion ACK. */
397
+ isTemporaryThreadCleanupCurrent(expected: TelegramTemporaryThreadEntry, authority: TelegramWorkspaceRestoreAuthority): boolean;
398
+ /** Publishes `creating` before the caller's single creation request; an existing source entry is returned, never recreated. */
399
+ reserveTemporaryThread(source: TelegramTemporaryThreadEntry["source"], token: string, authority: TelegramWorkspaceRestoreAuthority): { reserved: boolean; entry: TelegramTemporaryThreadEntry } | undefined;
400
+ /** Caller proves a fresh owner-authenticated implicit Telegram creation and exact live source under profile admission.
401
+ * Registers that observed unbound target without issuing or fabricating a Bot API creation. */
402
+ registerImplicitTemporaryThread(input: TelegramTemporaryThreadInput, target: TelegramTarget & { threadId: number }, token: string,
403
+ authority: TelegramWorkspaceRestoreAuthority): TelegramTemporaryThreadEntry | undefined;
404
+ /** Records the exact acknowledged creation target; it never reopens a created entry. */
405
+ acknowledgeTemporaryThread(expected: TelegramTemporaryThreadEntry, target: TelegramTarget & { threadId: number }, authority: TelegramWorkspaceRestoreAuthority): TelegramTemporaryThreadEntry | undefined;
406
+ adoptTemporaryThread(expected: TelegramTemporaryThreadEntry, authority: TelegramWorkspaceRestoreAuthority): TelegramTemporaryThreadEntry | undefined;
407
+ /** Caller supplies exact live source/group authority; duplicate membership is read-only, never a new dispatch grant. */
408
+ recordTemporaryThreadInput(expected: TelegramTemporaryThreadEntry, input: TelegramTemporaryThreadInput, authority: TelegramWorkspaceRestoreAuthority): TelegramTemporaryThreadEntry | undefined;
409
+ /** Records a positively completed Forward group; the caller proves every source of the group completed. */
410
+ /** Publishes the one-time Forward issuance fact before any RPC; a duplicate, cancelled, completed or Restore-owned group is refused. */
411
+ recordTemporaryThreadForwardIssued(expected: TelegramTemporaryThreadEntry, input: TelegramTemporaryThreadInput,
412
+ authority: TelegramWorkspaceRestoreAuthority): TelegramTemporaryThreadEntry | undefined;
413
+ recordTemporaryThreadInputCompletion(expected: TelegramTemporaryThreadEntry, input: TelegramTemporaryThreadInput,
414
+ authority: TelegramWorkspaceRestoreAuthority): TelegramTemporaryThreadEntry | undefined;
415
+ recordTemporaryThreadInputCancellation(expected: TelegramTemporaryThreadEntry, input: TelegramTemporaryThreadInput,
416
+ authority: TelegramWorkspaceRestoreAuthority,
417
+ inspect: (updateId: number) => TelegramTemporaryThreadCancellationEvidence | undefined): TelegramTemporaryThreadEntry | undefined;
418
+ /** Caller holds profile admission and proves fresh source/protection clearance; publication grants one attempt, never retry. */
419
+ issueTemporaryThreadCleanup(expected: TelegramTemporaryThreadEntry, authority: TelegramWorkspaceRestoreAuthority):
420
+ { issued: true; entry: TelegramTemporaryThreadEntry } | undefined;
421
+ /** Caller proves source settlement or cancellation and target disposition; this releases protection only. */
422
+ /** `completed` names one newly completed group; every other known group must already be cancelled or completed. */
423
+ retireTemporaryThread(expected: TelegramTemporaryThreadEntry, authority: TelegramWorkspaceRestoreAuthority,
424
+ completed?: TelegramTemporaryThreadInput): TelegramTemporaryThreadEntry | undefined;
425
+ /** New-world restart: atomically forgets this operator's Restore intents and temporary entries from previous runtime instances.
426
+ * Committed bindings stay; nothing is rolled back, replayed or deleted here. */
427
+ forgetPreviousWorld(authority: TelegramWorkspaceRestoreAuthority):
428
+ { operations: TelegramWorkspaceRestoreIntent[]; temporaryThreads: TelegramTemporaryThreadEntry[] } | undefined;
429
+ }
430
+ export interface TelegramWorkspaceRestoreOptions {
431
+ profileName: string; tokenSha256: string;
432
+ isCurrentScope?: () => boolean;
433
+ maxBytes?: number;
434
+ getNowMs?: () => number;
435
+ legacyPath?: string;
436
+ onPublicationBoundary?: (boundary: "after-write-before-rename" | "after-rename") => void;
437
+ }
438
+
363
439
  export interface TelegramSessionReplacementIntent {
364
440
  continuity: "workspace-thread" | "classic-chat";
365
441
  cwd: string;
@@ -385,13 +461,11 @@ export interface TelegramTopicTargetFile {
385
461
  source: "snapshot";
386
462
  writtenAtMs: number;
387
463
  bot: TelegramBotStateSnapshot;
388
- runtime?: Record<string, unknown>;
389
- liveRoster?: Record<string, unknown>;
390
- diagnostics?: Record<string, unknown>;
391
464
  threads: TelegramTopicTargetRecord[];
392
465
  identities?: TelegramThreadIdentityRecord[];
393
466
  workspaceBindings?: TelegramWorkspaceThreadBinding[];
394
467
  workspaceRetirements?: TelegramWorkspaceRetirementIntent[];
468
+ workspaceRestore?: TelegramWorkspaceRestoreSnapshot;
395
469
  sessionReplacement?: TelegramSessionReplacementIntent;
396
470
  reservations?: TelegramThreadReservation[];
397
471
  pendingProvisions?: TelegramThreadPendingProvision[];
@@ -471,6 +545,17 @@ export interface TelegramTopicTargetStore {
471
545
  expected: TelegramTopicTargetRecord,
472
546
  isCurrent: () => boolean,
473
547
  ) => Promise<boolean>;
548
+ /** Caller holds Workspace admission; publication uses this store's exact transport-owner fence. */
549
+ workspaceRestore: (options: TelegramWorkspaceRestoreOptions) => TelegramWorkspaceRestore;
550
+ /** Read-only precondition under caller-owned admission; not registration or transport authority. */
551
+ assertWorkspaceRestoreRegistration: (candidate: { target: TelegramTarget; bindingKey?: string; slot?: string }) => void;
552
+ /** Runs synchronous live publication under the same evidence transaction; caller retains authentication/admission. */
553
+ commitWorkspaceRestoreRegistration: (candidate: Parameters<TelegramTopicTargetStore["assertWorkspaceRestoreRegistration"]>[0], publish: () => void) => void;
554
+ /** Read-only canonical observation; the callback must finish synchronously under the snapshot transaction. */
555
+ withWorkspaceRestoreSnapshot: (expected: TelegramWorkspaceRestoreIntent,
556
+ observe: (snapshot: Readonly<Pick<TelegramTopicTargetFile, "threads" | "workspaceBindings">>) => undefined) => void;
557
+ /** Fresh strict disk read of acknowledged temporary-tab targets; throws rather than guessing absence. */
558
+ listTemporaryThreadTargets: () => TelegramTarget[];
474
559
  list: () => TelegramTopicTargetRecord[];
475
560
  getFollowerRecoveryHintByTarget?: (
476
561
  target: TelegramTarget,
@@ -495,6 +580,8 @@ export interface TelegramTopicTargetStore {
495
580
  liveRoster?: Record<string, unknown>;
496
581
  diagnostics?: Record<string, unknown>;
497
582
  }) => void;
583
+ /** Writes the non-canonical status projection to its own file; it never touches canonical state or grants authority. */
584
+ persistStatus: () => Promise<void>;
498
585
  getByProfileKey: (
499
586
  profileKey: string,
500
587
  ) => TelegramTopicTargetRecord | undefined;
@@ -520,11 +607,18 @@ export interface TelegramTopicTargetStore {
520
607
  isCurrent: () => boolean,
521
608
  ) => Promise<boolean>;
522
609
  listWorkspaceRetirementIntents: () => TelegramWorkspaceRetirementIntent[];
610
+ /** Metadata subset CAS only: callers prove exact-source/writer evidence; independent snapshot roots are untouched. */
523
611
  commitWorkspaceJournalEvidence: (
524
612
  expected: TelegramWorkspaceThreadBinding,
525
613
  journalBindingKeys: readonly string[],
526
614
  complete: boolean,
615
+ journalSources?: readonly TelegramWorkspaceJournalSource[],
527
616
  ) => TelegramWorkspaceThreadBinding | undefined;
617
+ /** Acknowledge publication of the exact current metadata frame; never roll it back after an uncertain write. */
618
+ persistWorkspaceJournalEvidence: (
619
+ expected: TelegramWorkspaceThreadBinding,
620
+ isCurrent: () => boolean,
621
+ ) => Promise<boolean>;
528
622
  upsertWorkspaceRetirementIntent: (
529
623
  intent: TelegramWorkspaceRetirementIntent,
530
624
  ) => boolean;
@@ -646,7 +740,7 @@ export function reconcileTelegramFreshAllocationCursor(
646
740
  }
647
741
 
648
742
  export function createTelegramCleanupTargetProtection(
649
- store: Pick<TelegramTopicTargetStore, "list"> & Partial<Pick<TelegramTopicTargetStore, "listReservations" | "listPendingProvisions" | "listPendingCleanups">>,
743
+ store: Pick<TelegramTopicTargetStore, "list"> & Partial<Pick<TelegramTopicTargetStore, "listReservations" | "listPendingProvisions" | "listPendingCleanups" | "listTemporaryThreadTargets">>,
650
744
  departingRecord?: TelegramTopicTargetRecord,
651
745
  ): NonNullable<ThreadReconciler.ThreadReconciliationApplyPorts["isCleanupTargetProtected"]> {
652
746
  const records = store.list();
@@ -658,6 +752,11 @@ export function createTelegramCleanupTargetProtection(
658
752
  const sameSnapshot = (left: unknown, right: unknown): boolean =>
659
753
  isDeepStrictEqual(JSON.parse(JSON.stringify(left)), JSON.parse(JSON.stringify(right)));
660
754
  return (target, action) => {
755
+ // A source-bound temporary tab is removed only by its own Forward/Cancel, never by generic reconciliation.
756
+ if (store.listTemporaryThreadTargets) {
757
+ try { if (store.listTemporaryThreadTargets().some(candidate => targetMatches(candidate, target))) return true; }
758
+ catch { return true; }
759
+ }
661
760
  for (const record of store.list()) {
662
761
  if (!targetMatches(record.target, target)) continue;
663
762
  // A persisted shutdown intent may retire only its original pre-intent
@@ -698,6 +797,7 @@ export interface TelegramTopicTargetStoreOptions {
698
797
  getNowMs?: () => number;
699
798
  canPersist?: () => boolean;
700
799
  commitPersist?: (commit: () => void) => boolean;
800
+ consolidated?: Pick<TelegramConsolidatedWorkspaceStorageOptions, "captureAuthority" | "publishIfOwned">;
701
801
  getExternalReservedSlots?: () => readonly string[];
702
802
  }
703
803
 
@@ -832,51 +932,6 @@ interface TelegramTopicResult {
832
932
  message_thread_id?: number;
833
933
  }
834
934
 
835
- function hashString(value: string): number {
836
- let hash = 2166136261;
837
- for (let index = 0; index < value.length; index += 1) {
838
- hash ^= value.charCodeAt(index);
839
- hash = Math.imul(hash, 16777619);
840
- }
841
- return hash >>> 0;
842
- }
843
-
844
- function getWorkspaceHint(cwd: string | undefined): string | undefined {
845
- if (!cwd) return undefined;
846
- const parts = cwd.split("/").filter(Boolean);
847
- const last = parts.at(-1)?.trim();
848
- if (!last) return undefined;
849
- return (
850
- last
851
- .replace(/[^\p{L}\p{N}._-]+/gu, " ")
852
- .trim()
853
- .slice(0, 32) || undefined
854
- );
855
- }
856
-
857
- export function createTelegramThreadName(
858
- input: TelegramThreadNameInput,
859
- ): string {
860
- const workspace = getWorkspaceHint(input.cwd);
861
- const roleMark =
862
- input.role === "leader"
863
- ? "Leader"
864
- : input.role === "follower"
865
- ? "Follower"
866
- : undefined;
867
- const slot = input.slot ? `Thread ${input.slot}` : undefined;
868
- const peerSalt = input.peers?.slice().sort().join("|") ?? "";
869
- const fallback = `Instance ${hashString(
870
- `${input.seed}|${input.cwd ?? ""}|${input.role ?? ""}|${peerSalt}|${input.slot ?? ""}`,
871
- )
872
- .toString(36)
873
- .slice(0, 4)}`;
874
- return (
875
- [slot, workspace, roleMark].filter(Boolean).join(" ").slice(0, 96) ||
876
- fallback
877
- );
878
- }
879
-
880
935
  export function getTelegramStatePath(
881
936
  agentDir = resolveAgentDir(),
882
937
  profileName?: string,
@@ -937,7 +992,7 @@ export function setTelegramLeaderSessionHandoff(
937
992
  else store[TELEGRAM_LEADER_SESSION_HANDOFF_KEY] = handoff;
938
993
  }
939
994
 
940
- export function isTelegramLeaderSessionHandoffFresh(
995
+ function isTelegramLeaderSessionHandoffFresh(
941
996
  handoff: TelegramLeaderSessionHandoff | undefined,
942
997
  options: { pid?: number; nowMs?: number; ttlMs?: number } = {},
943
998
  ): handoff is TelegramLeaderSessionHandoff {
@@ -1121,6 +1176,7 @@ function normalizeRecord(
1121
1176
  typeof record.updatedAtMs !== "number"
1122
1177
  )
1123
1178
  return undefined;
1179
+ const threadName = getPersistedThreadName(record);
1124
1180
  const normalized: TelegramTopicTargetRecord = {
1125
1181
  profileKey: getTelegramThreadOwnerKey(owner),
1126
1182
  owner,
@@ -1128,7 +1184,7 @@ function normalizeRecord(
1128
1184
  status,
1129
1185
  createdAtMs: record.createdAtMs,
1130
1186
  updatedAtMs: record.updatedAtMs,
1131
- threadName: getPersistedThreadName(record),
1187
+ ...(threadName !== undefined ? { threadName } : {}),
1132
1188
  ...(typeof record.manualThreadName === "string" &&
1133
1189
  normalizeTelegramTopicTargetThreadName(record.manualThreadName)
1134
1190
  ? { manualThreadName:
@@ -1224,6 +1280,21 @@ function getWorkspaceBindingMapKey(
1224
1280
  return `${binding.cwd}\u0000${binding.sessionId ?? ""}\u0000${binding.instanceSlot}`;
1225
1281
  }
1226
1282
 
1283
+ function normalizeWorkspaceJournalSources(value: unknown): TelegramWorkspaceJournalSource[] | undefined {
1284
+ if (!Array.isArray(value) || value.length > 256) return undefined;
1285
+ const sources = new Map<string, TelegramWorkspaceJournalSource>();
1286
+ for (const entry of value) {
1287
+ if (!entry || typeof entry !== "object" || Array.isArray(entry)) return undefined;
1288
+ const source = entry as Record<string, unknown>;
1289
+ if (Object.keys(source).some(key => key !== "sessionId" && key !== "recipientBindingKey") ||
1290
+ typeof source.sessionId !== "string" || normalizeTelegramSessionId(source.sessionId) !== source.sessionId ||
1291
+ typeof source.recipientBindingKey !== "string" || !source.recipientBindingKey || source.recipientBindingKey.length > 512) return undefined;
1292
+ const normalized = { sessionId: source.sessionId, recipientBindingKey: source.recipientBindingKey };
1293
+ sources.set(JSON.stringify(normalized), normalized);
1294
+ }
1295
+ return Array.from(sources.values());
1296
+ }
1297
+
1227
1298
  function normalizeWorkspaceBindingRecord(
1228
1299
  value: unknown,
1229
1300
  ): TelegramWorkspaceThreadBinding | undefined {
@@ -1298,6 +1369,8 @@ function normalizeWorkspaceBindingRecord(
1298
1369
  )
1299
1370
  ? Array.from(new Set(record.journalBindingKeys as string[]))
1300
1371
  : undefined;
1372
+ const journalSources = record.journalSources === undefined ? undefined : normalizeWorkspaceJournalSources(record.journalSources);
1373
+ if (record.journalSources !== undefined && !journalSources) return undefined;
1301
1374
  return {
1302
1375
  cwd,
1303
1376
  workspaceKey: record.workspaceKey,
@@ -1313,7 +1386,8 @@ function normalizeWorkspaceBindingRecord(
1313
1386
  ? { inactiveSinceMs: record.inactiveSinceMs }
1314
1387
  : {}),
1315
1388
  ...(journalBindingKeys ? { journalBindingKeys } : {}),
1316
- ...(record.journalBindingsComplete === true && journalBindingKeys
1389
+ ...(journalSources ? { journalSources } : {}),
1390
+ ...(record.journalBindingsComplete === true && (journalBindingKeys || journalSources)
1317
1391
  ? { journalBindingsComplete: true as const }
1318
1392
  : {}),
1319
1393
  target: { chatId: target.chatId, threadId: target.threadId },
@@ -1327,7 +1401,9 @@ function normalizeWorkspaceBindingRecord(
1327
1401
  function cloneWorkspaceBinding(
1328
1402
  binding: TelegramWorkspaceThreadBinding,
1329
1403
  ): TelegramWorkspaceThreadBinding {
1330
- return { ...binding, target: { ...binding.target } };
1404
+ return { ...binding, target: { ...binding.target },
1405
+ ...(binding.journalBindingKeys ? { journalBindingKeys: [...binding.journalBindingKeys] } : {}),
1406
+ ...(binding.journalSources ? { journalSources: binding.journalSources.map(source => ({ ...source })) } : {}) };
1331
1407
  }
1332
1408
 
1333
1409
  function cloneSessionReplacementIntent(
@@ -1644,6 +1720,325 @@ function normalizeReservation(
1644
1720
  };
1645
1721
  }
1646
1722
 
1723
+ function normalizeTelegramWorkspaceRelocationRequest(value: unknown): TelegramWorkspaceRelocationRequest | undefined {
1724
+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
1725
+ const request = value as TelegramWorkspaceRelocationRequest;
1726
+ const binding = normalizeWorkspaceBindingRecord(request.binding);
1727
+ const owner = normalizeRecord(request.owner);
1728
+ const target = request.target;
1729
+ if (typeof request.operationId !== "string" || !request.operationId ||
1730
+ !binding?.sessionId || !binding.slot || !/^[A-Z]$/.test(binding.slot) || binding.inactiveSinceMs !== undefined ||
1731
+ !owner || owner.status !== "active" || !owner.instanceId || owner.slot !== binding.slot ||
1732
+ !["leader", "manual-follower"].includes(owner.owner?.kind ?? "") ||
1733
+ (owner.owner?.kind === "leader" &&
1734
+ (owner.owner.cwd !== binding.cwd || owner.owner.instanceId !== owner.instanceId)) ||
1735
+ !targetMatches(binding.target, owner.target) ||
1736
+ !Number.isSafeInteger(binding.target.chatId) || binding.target.chatId === 0 ||
1737
+ !Number.isSafeInteger(binding.target.threadId) || binding.target.threadId <= 0 ||
1738
+ !target || target.chatId !== binding.target.chatId ||
1739
+ !Number.isSafeInteger(target.threadId) || target.threadId <= 0 ||
1740
+ targetMatches(target, binding.target)) return undefined;
1741
+ const normalized = { operationId: request.operationId, binding, owner,
1742
+ target: { chatId: target.chatId, threadId: target.threadId } };
1743
+ return isDeepStrictEqual(value, normalized) ? normalized : undefined;
1744
+ }
1745
+
1746
+ const restoreInteger = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
1747
+ const restoreKeys = (value: Record<string, unknown>, allowed: string[]): boolean => Object.keys(value).every(key => allowed.includes(key));
1748
+ const isTelegramWorkspaceRestoreExecutor = (value: unknown): value is TelegramWorkspaceRestoreExecutor => restoreObject(value) &&
1749
+ restoreKeys(value, ["instanceId", "leaderEpoch"]) && restoreText(value.instanceId) && restoreText(value.leaderEpoch);
1750
+ export const isTelegramWorkspaceRestoreRecipient = (value: unknown): value is TelegramWorkspaceRestoreRecipient => restoreObject(value) &&
1751
+ restoreKeys(value, ["kind", "instanceId", "sessionId", "generation"]) &&
1752
+ (value.kind === "leader" || value.kind === "follower") && restoreText(value.instanceId) && restoreText(value.sessionId) && restoreText(value.generation);
1753
+ export function isTelegramWorkspaceRestoreRequest(value: unknown): value is TelegramWorkspaceRestoreRequest {
1754
+ if (!restoreObject(value)) return false;
1755
+ const { source, ...relocation } = value;
1756
+ return !!normalizeTelegramWorkspaceRelocationRequest(relocation) && restoreObject(source) &&
1757
+ restoreKeys(source, ["journalBindingKey", "updateIds"]) && restoreText(source.journalBindingKey) &&
1758
+ Array.isArray(source.updateIds) && source.updateIds.length > 0 &&
1759
+ source.updateIds.every((id, index, ids) => restoreInteger(id) && (index === 0 || id > ids[index - 1]));
1760
+ }
1761
+ function isTelegramWorkspaceRestoreSettlement(value: unknown, source: TelegramWorkspaceRestoreRequest["source"]): value is TelegramWorkspaceRestoreSourceSettlement {
1762
+ if (!restoreObject(value) || value.journalBindingKey !== source.journalBindingKey || !Array.isArray(value.updateIds) ||
1763
+ value.updateIds.length === 0 || !value.updateIds.every((id, index, ids) => restoreInteger(id) && source.updateIds.includes(id) &&
1764
+ (index === 0 || id > ids[index - 1]))) return false;
1765
+ return value.kind === "completed" ? restoreKeys(value, ["journalBindingKey", "updateIds", "kind"]) :
1766
+ (value.kind === "queued" || value.kind === "queue-completed") && restoreKeys(value, ["journalBindingKey", "updateIds", "kind", "receiptId", "queueKind"]) &&
1767
+ restoreText(value.receiptId) && (value.queueKind === "prompt" || value.queueKind === "control");
1768
+ }
1769
+ function isWorkspaceRestoreSourceAcceptance(value: unknown, operation: TelegramWorkspaceRestoreIntent): value is TelegramWorkspaceRestoreSourceAcceptance {
1770
+ if (!restoreObject(value) || value.journalBindingKey !== operation.request.source.journalBindingKey || !restoreInteger(value.updateId) ||
1771
+ !operation.request.source.updateIds.includes(value.updateId) || typeof value.sourceSha256 !== "string" ||
1772
+ !/^[a-f0-9]{64}$/u.test(value.sourceSha256) || !isTelegramWorkspaceRestoreRecipient(value.recipient) ||
1773
+ value.recipient.sessionId !== operation.request.binding.sessionId || value.recipient.kind !== operation.recipient?.kind) return false;
1774
+ const keys = ["journalBindingKey", "updateId", "sourceSha256", "recipient", "kind"];
1775
+ if (value.kind === "completed") return value.recipient.kind === "leader" && restoreKeys(value, keys);
1776
+ if (value.kind === "forwarded") return value.recipient.kind === "follower" &&
1777
+ restoreKeys(value, [...keys, "deliveryId", "recipientBindingKey"]) && typeof value.deliveryId === "string" &&
1778
+ /^telegram-follower-v1-[a-f0-9]{64}$/u.test(value.deliveryId) && restoreText(value.recipientBindingKey);
1779
+ return value.kind === "queued" && value.recipient.kind === "leader" &&
1780
+ restoreKeys(value, [...keys, "receiptId", "queueKind", "queueOwnerSha256"]) && restoreText(value.receiptId) &&
1781
+ (value.queueKind === "prompt" || value.queueKind === "control") && typeof value.queueOwnerSha256 === "string" &&
1782
+ /^[a-f0-9]{64}$/u.test(value.queueOwnerSha256);
1783
+ }
1784
+ /** Stable acceptance scope, not a removal ACK; adoption and mutable progress cannot change it. */
1785
+ export function getTelegramWorkspaceRestoreSourceCompletionSha256(operation: TelegramWorkspaceRestoreIntent,
1786
+ acceptance: TelegramWorkspaceRestoreSourceAcceptance): string {
1787
+ if (!isTelegramWorkspaceRestoreRequest(operation.request) || operation.operatorUserId !== operation.request.target.chatId ||
1788
+ !isWorkspaceRestoreSourceAcceptance(acceptance, operation) ||
1789
+ !operation.routing?.acceptances?.some(value => isDeepStrictEqual(value, acceptance))) {
1790
+ throw new Error("Workspace Restore retained acceptance scope is unavailable.");
1791
+ }
1792
+ const frame = { kind: "workspace-restore-source-completion-v1", request: operation.request,
1793
+ operatorUserId: operation.operatorUserId, acceptance };
1794
+ return createHash("sha256").update(JSON.stringify(frame, function (_key, value: unknown) {
1795
+ return restoreObject(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, value[key]])) : value;
1796
+ })).digest("hex");
1797
+ }
1798
+
1799
+ function workspaceRestoreAcceptancesConsistent(acceptances: readonly TelegramWorkspaceRestoreSourceAcceptance[]): boolean {
1800
+ return acceptances.every((value, index) => (index === 0 || value.updateId > acceptances[index - 1]!.updateId) &&
1801
+ acceptances.slice(0, index).every(previous => {
1802
+ if (value.kind === "forwarded" && previous.kind === "forwarded") return value.deliveryId !== previous.deliveryId;
1803
+ if (value.kind !== "queued" || previous.kind !== "queued" || value.receiptId !== previous.receiptId) return true;
1804
+ return value.queueKind === previous.queueKind && value.queueOwnerSha256 === previous.queueOwnerSha256 &&
1805
+ isDeepStrictEqual(value.recipient, previous.recipient);
1806
+ }));
1807
+ }
1808
+ function workspaceRestoreSettlementMatchesAcceptance(evidence: TelegramWorkspaceRestoreSourceSettlement,
1809
+ acceptances: readonly TelegramWorkspaceRestoreSourceAcceptance[]): boolean {
1810
+ return evidence.updateIds.every(id => {
1811
+ const accepted = acceptances.find(value => value.updateId === id);
1812
+ if (!accepted) return evidence.kind !== "queue-completed"; // Legacy admission is retained, never terminal receipt proof.
1813
+ return evidence.kind === "completed" ? accepted.kind !== "queued" : accepted.kind === "queued" &&
1814
+ evidence.receiptId === accepted.receiptId && evidence.queueKind === accepted.queueKind;
1815
+ });
1816
+ }
1817
+ function workspaceRestoreSourcesSettled(operation: TelegramWorkspaceRestoreIntent): boolean {
1818
+ const settled = new Set(operation.routing?.settlements.filter(value => value.kind !== "queued").flatMap(value => value.updateIds));
1819
+ return operation.request.source.updateIds.every(id => settled.has(id));
1820
+ }
1821
+ function isWorkspaceRestoreIntent(value: unknown): value is TelegramWorkspaceRestoreIntent {
1822
+ if (!restoreObject(value) || !restoreKeys(value, ["request", "operatorUserId", "executor", "revision", "createdAtMs",
1823
+ "updatedAtMs", "phase", "committedAtMs", "recipient", "readyRecipient", "routing"]) || !isTelegramWorkspaceRestoreRequest(value.request) ||
1824
+ !restoreInteger(value.operatorUserId) || value.operatorUserId !== value.request.target.chatId ||
1825
+ !isTelegramWorkspaceRestoreExecutor(value.executor) || !restoreInteger(value.revision) || !restoreInteger(value.createdAtMs) ||
1826
+ !restoreInteger(value.updatedAtMs) || value.updatedAtMs < value.createdAtMs ||
1827
+ !restoreInteger(value.committedAtMs)) return false;
1828
+ const source = value.request.source;
1829
+ if (value.routing !== undefined) {
1830
+ if (value.phase !== "ready" || !restoreObject(value.routing) || !restoreKeys(value.routing, ["acceptances", "settlements", "cleanup"]) ||
1831
+ !Array.isArray(value.routing.settlements) || !value.routing.settlements.every(item => isTelegramWorkspaceRestoreSettlement(item, source))) return false;
1832
+ if (value.routing.acceptances !== undefined) {
1833
+ const acceptances = value.routing.acceptances;
1834
+ if (!Array.isArray(acceptances) || !acceptances.length ||
1835
+ !acceptances.every(item => isWorkspaceRestoreSourceAcceptance(item, value as unknown as TelegramWorkspaceRestoreIntent)) ||
1836
+ !workspaceRestoreAcceptancesConsistent(acceptances)) return false;
1837
+ }
1838
+ const acceptances = (value.routing.acceptances ?? []) as TelegramWorkspaceRestoreSourceAcceptance[];
1839
+ if (!value.routing.settlements.every(item => workspaceRestoreSettlementMatchesAcceptance(item, acceptances))) return false;
1840
+ const ids = value.routing.settlements.flatMap(item => item.updateIds);
1841
+ if (new Set(ids).size !== ids.length || (value.routing.cleanup !== undefined &&
1842
+ (!["issued", "completed", "not-issued"].includes(value.routing.cleanup as string) ||
1843
+ !workspaceRestoreSourcesSettled(value as unknown as TelegramWorkspaceRestoreIntent)))) return false;
1844
+ }
1845
+ if (value.readyRecipient !== undefined && (value.phase !== "ready" || !isTelegramWorkspaceRestoreRecipient(value.readyRecipient) ||
1846
+ value.readyRecipient.sessionId !== value.request.binding.sessionId)) return false;
1847
+ if (value.phase === "relocated") return value.recipient === undefined;
1848
+ return (value.phase === "recipient-issued" || value.phase === "ready") && isTelegramWorkspaceRestoreRecipient(value.recipient) &&
1849
+ value.recipient.sessionId === value.request.binding.sessionId;
1850
+ }
1851
+ function isTemporaryThreadInput(value: unknown): value is TelegramTemporaryThreadInput {
1852
+ return restoreObject(value) && restoreKeys(value, ["journalBindingKey", "updateIds"]) && restoreText(value.journalBindingKey) &&
1853
+ Array.isArray(value.updateIds) && value.updateIds.length > 0 && value.updateIds.length <= TEMPORARY_THREAD_INPUT_CAPACITY &&
1854
+ value.updateIds.every((id, index, ids) => restoreInteger(id) && (index === 0 || id > ids[index - 1]));
1855
+ }
1856
+ export function getTelegramTemporaryThreadInputs(entry: TelegramTemporaryThreadEntry): TelegramTemporaryThreadInput[] {
1857
+ return structuredClone(entry.inputs ?? [{ journalBindingKey: entry.source.journalBindingKey, updateIds: [entry.source.updateId] }]);
1858
+ }
1859
+ /** Every known group is durably cancelled or Forward-completed; still not deletion authority by itself. */
1860
+ export function isTelegramTemporaryThreadFullyResolved(entry: TelegramTemporaryThreadEntry): boolean {
1861
+ const inputs = getTelegramTemporaryThreadInputs(entry), resolved = [...(entry.cancelledInputs ?? []), ...(entry.completedInputs ?? [])];
1862
+ return resolved.length > 0 && inputs.every(input => resolved.some(other => isDeepStrictEqual(other, input)));
1863
+ }
1864
+ /** One unresolved group may release protection after completion when every other group has a durable terminal fact. */
1865
+ function isTemporaryThreadReleasedByCompletion(entry: TelegramTemporaryThreadEntry, completed: TelegramTemporaryThreadInput | undefined): boolean {
1866
+ if (!completed || !isTemporaryThreadInput(completed)) return false;
1867
+ const inputs = getTelegramTemporaryThreadInputs(entry), cancelled = [...(entry.cancelledInputs ?? []), ...(entry.completedInputs ?? [])];
1868
+ const same = (left: TelegramTemporaryThreadInput, right: TelegramTemporaryThreadInput): boolean => isDeepStrictEqual(left, right);
1869
+ return inputs.some(input => same(input, completed)) && !cancelled.some(input => same(input, completed)) &&
1870
+ inputs.every(input => same(input, completed) || cancelled.some(other => same(other, input)));
1871
+ }
1872
+ function isTemporaryThreadEntry(value: unknown): value is TelegramTemporaryThreadEntry {
1873
+ if (!restoreObject(value) || !restoreKeys(value, ["source", "inputs", "cancelledInputs", "completedInputs", "forwardedInputs", "forwardProtocol", "cleanupIssued", "operatorUserId", "executor", "token", "phase", "target", "revision",
1874
+ "createdAtMs", "updatedAtMs"]) || !restoreObject(value.source) || !restoreKeys(value.source, ["journalBindingKey", "updateId"]) ||
1875
+ !restoreText(value.source.journalBindingKey) || !restoreInteger(value.source.updateId) ||
1876
+ !restoreInteger(value.operatorUserId) || value.operatorUserId === 0 || !isTelegramWorkspaceRestoreExecutor(value.executor) ||
1877
+ typeof value.token !== "string" || !/^[a-f0-9]{32}$/u.test(value.token) || !restoreInteger(value.revision) ||
1878
+ !restoreInteger(value.createdAtMs) || !restoreInteger(value.updatedAtMs) || value.updatedAtMs < value.createdAtMs) return false;
1879
+ const source = value.source;
1880
+ if (value.forwardProtocol !== undefined && (value.forwardProtocol !== "one-shot-v1" || value.inputs === undefined)) return false;
1881
+ if (value.inputs !== undefined) {
1882
+ const inputs = value.inputs;
1883
+ if (!Array.isArray(inputs) || inputs.length === 0 || inputs.length > TEMPORARY_THREAD_INPUT_CAPACITY ||
1884
+ !inputs.every(isTemporaryThreadInput) || !isDeepStrictEqual(inputs[0],
1885
+ { journalBindingKey: source.journalBindingKey, updateIds: [source.updateId] }) ||
1886
+ inputs.some((input, index) => input.journalBindingKey !== source.journalBindingKey ||
1887
+ inputs.slice(index + 1).some(other => other.updateIds.some(id => input.updateIds.includes(id))))) return false;
1888
+ }
1889
+ if (value.cancelledInputs !== undefined) {
1890
+ const cancelled = value.cancelledInputs;
1891
+ const inputs = Array.isArray(value.inputs) ? value.inputs : [{ journalBindingKey: source.journalBindingKey, updateIds: [source.updateId] }];
1892
+ if (!Array.isArray(cancelled) || cancelled.length === 0 || cancelled.length > TEMPORARY_THREAD_INPUT_CAPACITY ||
1893
+ !cancelled.every(isTemporaryThreadInput) || cancelled.some((input, index) =>
1894
+ !inputs.some(candidate => isDeepStrictEqual(candidate, input)) || cancelled.slice(index + 1).some(other => isDeepStrictEqual(other, input)))) return false;
1895
+ }
1896
+ if (value.completedInputs !== undefined) {
1897
+ const completed = value.completedInputs;
1898
+ const inputs = Array.isArray(value.inputs) ? value.inputs : [{ journalBindingKey: source.journalBindingKey, updateIds: [source.updateId] }];
1899
+ const cancelled = Array.isArray(value.cancelledInputs) ? value.cancelledInputs : [];
1900
+ if (!Array.isArray(completed) || completed.length === 0 || completed.length > TEMPORARY_THREAD_INPUT_CAPACITY ||
1901
+ !completed.every(isTemporaryThreadInput) || completed.some((input, index) =>
1902
+ !inputs.some(candidate => isDeepStrictEqual(candidate, input)) || cancelled.some(other => isDeepStrictEqual(other, input)) ||
1903
+ completed.slice(index + 1).some(other => isDeepStrictEqual(other, input)))) return false;
1904
+ }
1905
+ if (value.forwardedInputs !== undefined) {
1906
+ const forwarded = value.forwardedInputs;
1907
+ const inputs = Array.isArray(value.inputs) ? value.inputs : [{ journalBindingKey: source.journalBindingKey, updateIds: [source.updateId] }];
1908
+ const cancelled = Array.isArray(value.cancelledInputs) ? value.cancelledInputs : [];
1909
+ if (!Array.isArray(forwarded) || forwarded.length === 0 || forwarded.length > TEMPORARY_THREAD_INPUT_CAPACITY ||
1910
+ !forwarded.every(isTemporaryThreadInput) || forwarded.some((input, index) =>
1911
+ !inputs.some(candidate => isDeepStrictEqual(candidate, input)) || cancelled.some(other => isDeepStrictEqual(other, input)) ||
1912
+ forwarded.slice(index + 1).some(other => isDeepStrictEqual(other, input)))) return false;
1913
+ }
1914
+ if (value.cleanupIssued !== undefined && (value.cleanupIssued !== true ||
1915
+ !isTelegramTemporaryThreadFullyResolved(value as unknown as TelegramTemporaryThreadEntry))) return false;
1916
+ if (value.phase === "creating") return value.target === undefined && value.cancelledInputs === undefined && value.completedInputs === undefined && value.forwardedInputs === undefined && value.cleanupIssued === undefined &&
1917
+ (!Array.isArray(value.inputs) || value.inputs.length === 1);
1918
+ const target = value.target;
1919
+ return value.phase === "created" && restoreObject(target) && restoreKeys(target, ["chatId", "threadId"]) &&
1920
+ target.chatId === value.operatorUserId && Number.isSafeInteger(target.threadId) && (target.threadId as number) > 0;
1921
+ }
1922
+ /** Only an exact recorded source group may Restore into its temporary tab. */
1923
+ function isTemporaryThreadRestore(entry: TelegramTemporaryThreadEntry, operations: readonly TelegramWorkspaceRestoreIntent[]): boolean {
1924
+ return operations.some(({ request }) => !!entry.target && targetMatches(request.target, entry.target) &&
1925
+ ![...(entry.cancelledInputs ?? []), ...(entry.completedInputs ?? []), ...(entry.forwardedInputs ?? [])].some(input => input.journalBindingKey === request.source.journalBindingKey &&
1926
+ input.updateIds.some(id => request.source.updateIds.includes(id))) &&
1927
+ (entry.inputs ? entry.inputs.some(input => isDeepStrictEqual(input, request.source)) :
1928
+ request.source.journalBindingKey === entry.source.journalBindingKey && request.source.updateIds.includes(entry.source.updateId)));
1929
+ }
1930
+ function conflictsWithTemporaryThread(snapshot: TelegramWorkspaceRestoreSnapshot | undefined, target: TelegramTarget | undefined): boolean {
1931
+ return !!target && !!snapshot?.temporaryThreads?.some(entry => !!entry.target && targetMatches(entry.target, target));
1932
+ }
1933
+ function conflictsWithWorkspaceRestoreProvision(request: TelegramWorkspaceRestoreRequest,
1934
+ provision: TelegramThreadPendingProvision | TelegramThreadReservation): boolean {
1935
+ if ("owner" in provision && !provision.workspaceBindingKey &&
1936
+ (provision.profileKey === request.owner.profileKey || provision.instanceId === request.owner.instanceId)) return true;
1937
+ return ("workspaceBindingKey" in provision && provision.workspaceBindingKey === request.binding.bindingKey) || provision.slot === request.binding.slot ||
1938
+ !!provision.target && (targetMatches(provision.target, request.binding.target) || targetMatches(provision.target, request.target));
1939
+ }
1940
+
1941
+ function assertWorkspaceRestoreBindingProtection(file: Pick<TelegramTopicTargetFile, "workspaceBindings" | "workspaceRestore" | "pendingProvisions" | "reservations"> & {
1942
+ threads?: readonly Pick<TelegramTopicTargetRecord, "target" | "slot">[];
1943
+ }): void {
1944
+ for (const { request } of file.workspaceRestore?.operations ?? []) {
1945
+ if (file.pendingProvisions?.some(value => conflictsWithWorkspaceRestoreProvision(request, value)) ||
1946
+ file.reservations?.some(value => conflictsWithWorkspaceRestoreProvision(request, value))) {
1947
+ throw new Error("Protected Workspace Restore provisioning conflict.");
1948
+ }
1949
+ const bindings = file.workspaceBindings ?? [];
1950
+ const retained = bindings.filter(value => value.bindingKey === request.binding.bindingKey);
1951
+ const current = retained[0];
1952
+ const identity = ["bindingKey", "cwd", "workspaceKey", "instanceSlot", "sessionId", "sessionKey", "slot"] as const;
1953
+ if (retained.length !== 1 || !current || identity.some(key => current[key] !== request.binding[key]) ||
1954
+ !targetMatches(current.target, request.target) || bindings.some(value => value !== current &&
1955
+ (value.slot === current.slot || targetMatches(value.target, request.binding.target) || targetMatches(value.target, request.target)))) {
1956
+ throw new Error("Protected Workspace Restore binding changed.");
1957
+ }
1958
+ const owners = (file.threads ?? []).filter(value => value.slot === current.slot ||
1959
+ targetMatches(value.target, request.binding.target) || targetMatches(value.target, request.target));
1960
+ if (owners.length > 1 || owners.some(value => value.slot !== current.slot || !targetMatches(value.target, request.target))) {
1961
+ throw new Error("Protected Workspace Restore owner target changed.");
1962
+ }
1963
+ }
1964
+ const operations = file.workspaceRestore?.operations ?? [];
1965
+ for (const entry of file.workspaceRestore?.temporaryThreads ?? []) {
1966
+ const target = entry.target;
1967
+ if (!target) continue;
1968
+ const claimed = [...(file.workspaceBindings ?? []), ...(file.threads ?? [])].some(value => targetMatches(value.target, target));
1969
+ if (file.pendingProvisions?.some(value => !!value.target && targetMatches(value.target, target)) ||
1970
+ file.reservations?.some(value => targetMatches(value.target, target)) ||
1971
+ (claimed && !isTemporaryThreadRestore(entry, operations))) {
1972
+ throw new Error("Protected temporary Thread target conflict.");
1973
+ }
1974
+ }
1975
+ }
1976
+
1977
+ function workspaceRestoresConflict(left: TelegramWorkspaceRestoreRequest, right: TelegramWorkspaceRestoreRequest): boolean {
1978
+ const targets = [left.binding.target, left.target];
1979
+ return left.operationId === right.operationId || left.binding.bindingKey === right.binding.bindingKey ||
1980
+ left.binding.slot === right.binding.slot || targets.some(target => targetMatches(target, right.binding.target) || targetMatches(target, right.target)) ||
1981
+ (left.source.journalBindingKey === right.source.journalBindingKey && right.source.updateIds.some(id => left.source.updateIds.includes(id)));
1982
+ }
1983
+ const WORKSPACE_RESTORE_MAX_BYTES = 1024 * 1024;
1984
+ const TEMPORARY_THREAD_CAPACITY = 26;
1985
+ const TEMPORARY_THREAD_INPUT_CAPACITY = 100;
1986
+ const WORKSPACE_SNAPSHOT_MAX_BYTES = 8 * WORKSPACE_RESTORE_MAX_BYTES;
1987
+ function parseWorkspaceRestore(value: unknown): TelegramWorkspaceRestoreSnapshot | undefined {
1988
+ if (value === undefined) return undefined;
1989
+ const temporary = restoreObject(value) ? value.temporaryThreads : undefined;
1990
+ if (!restoreObject(value) || !restoreKeys(value, ["version", "profileName", "tokenSha256", "revision", "operations", "temporaryThreads"]) ||
1991
+ value.version !== 1 || !restoreText(value.profileName) || typeof value.tokenSha256 !== "string" || !/^[a-f0-9]{64}$/u.test(value.tokenSha256) ||
1992
+ !restoreInteger(value.revision) || !Array.isArray(value.operations) || value.operations.length > 26 ||
1993
+ (temporary !== undefined && (!Array.isArray(temporary) || temporary.length === 0 ||
1994
+ temporary.length > TEMPORARY_THREAD_CAPACITY || !temporary.every(isTemporaryThreadEntry))) ||
1995
+ ((value.operations.length > 0 || temporary !== undefined) && value.revision === 0) || !value.operations.every(isWorkspaceRestoreIntent) ||
1996
+ Buffer.byteLength(JSON.stringify(value)) > WORKSPACE_RESTORE_MAX_BYTES) throw new Error("Invalid Workspace Restore evidence.");
1997
+ const snapshot = value as unknown as TelegramWorkspaceRestoreSnapshot;
1998
+ if (snapshot.operations.some((operation, index) => snapshot.operations.slice(index + 1).some(other => workspaceRestoresConflict(operation.request, other.request))))
1999
+ throw new Error("Conflicting Workspace Restore evidence.");
2000
+ const entries = snapshot.temporaryThreads ?? [];
2001
+ if (entries.some((entry, index) => entries.slice(index + 1).some(other => other.token === entry.token ||
2002
+ getTelegramTemporaryThreadInputs(entry).some(input => getTelegramTemporaryThreadInputs(other).some(candidate =>
2003
+ input.journalBindingKey === candidate.journalBindingKey && input.updateIds.some(id => candidate.updateIds.includes(id)))) ||
2004
+ (!!entry.target && !!other.target && targetMatches(entry.target, other.target)))) ||
2005
+ entries.some(entry => !!entry.target && snapshot.operations.some(({ request }) => targetMatches(request.binding.target, entry.target!) ||
2006
+ (targetMatches(request.target, entry.target!) && !isTemporaryThreadRestore(entry, [{ request } as TelegramWorkspaceRestoreIntent])))))
2007
+ throw new Error("Conflicting Workspace Restore evidence.");
2008
+ return snapshot;
2009
+ }
2010
+ /** All Restore reads and publishers share these physical-file checks; there is no repairing read. */
2011
+ const readWorkspaceDescriptor = promisify(readFileCallback);
2012
+ function readWorkspaceSnapshot(path: string, requirePrivate = true, asynchronous = false): unknown {
2013
+ let before;
2014
+ try { before = lstatSync(path, { bigint: true }); }
2015
+ catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
2016
+ const uid = process.getuid?.();
2017
+ const privateFile = uid === undefined || (before.uid === BigInt(uid) && (before.mode & 0o077n) === 0n);
2018
+ if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.size > BigInt(WORKSPACE_SNAPSHOT_MAX_BYTES) ||
2019
+ (requirePrivate && !privateFile)) throw new Error("Workspace snapshot must be a bounded private regular file.");
2020
+ const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
2021
+ let closeImmediately = true;
2022
+ try {
2023
+ const opened = fstatSync(fd, { bigint: true });
2024
+ if (opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size || opened.mtimeNs !== before.mtimeNs)
2025
+ throw new Error("Workspace snapshot changed during inspection.");
2026
+ const decode = (content: string): unknown => {
2027
+ const value: unknown = JSON.parse(content);
2028
+ // Legacy metadata may predate private storage; a Restore-bearing snapshot never may.
2029
+ if (!privateFile && restoreObject(value) && value.workspaceRestore !== undefined)
2030
+ throw new Error("Workspace snapshot must be a bounded private regular file.");
2031
+ return value;
2032
+ };
2033
+ if (asynchronous) {
2034
+ const reading = readWorkspaceDescriptor(fd, "utf8").then(decode);
2035
+ closeImmediately = false;
2036
+ return reading.finally(() => closeSync(fd));
2037
+ }
2038
+ return decode(readFileSync(fd, "utf8"));
2039
+ } finally { if (closeImmediately) closeSync(fd); }
2040
+ }
2041
+
1647
2042
  function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
1648
2043
  if (!value || typeof value !== "object" || Array.isArray(value)) {
1649
2044
  return {
@@ -1655,6 +2050,12 @@ function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
1655
2050
  };
1656
2051
  }
1657
2052
  const file = value as Record<string, unknown>;
2053
+ // The unpublished two-file draft is not migration or source-reconstruction authority.
2054
+ if ((file.workspaceRelocations !== undefined && (!Array.isArray(file.workspaceRelocations) || file.workspaceRelocations.length !== 0)) ||
2055
+ (file.workspaceRelocationRevision !== undefined && file.workspaceRelocationRevision !== 0))
2056
+ throw new Error("Unmigrated Workspace relocation evidence.");
2057
+ const workspaceRestore = parseWorkspaceRestore(file.workspaceRestore);
2058
+ if (file.version !== 1 && workspaceRestore) throw new Error("Unsupported Workspace Restore snapshot.");
1658
2059
  if (file.version !== 1) {
1659
2060
  return {
1660
2061
  version: 1,
@@ -1686,6 +2087,8 @@ function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
1686
2087
  workspaceBindings: Array.isArray(file.workspaceBindings)
1687
2088
  ? file.workspaceBindings.flatMap((binding) => {
1688
2089
  const normalized = normalizeWorkspaceBindingRecord(binding);
2090
+ if (!normalized && binding && typeof binding === "object" && "journalSources" in binding)
2091
+ throw new Error("Invalid Workspace session journal evidence.");
1689
2092
  return normalized ? [normalized] : [];
1690
2093
  })
1691
2094
  : [],
@@ -1695,6 +2098,7 @@ function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
1695
2098
  return normalized ? [normalized] : [];
1696
2099
  })
1697
2100
  : [],
2101
+ ...(workspaceRestore ? { workspaceRestore } : {}),
1698
2102
  sessionReplacement: normalizeTelegramSessionReplacementIntent(file.sessionReplacement),
1699
2103
  reservations: Array.isArray(file.reservations)
1700
2104
  ? file.reservations.flatMap((reservation) => {
@@ -1723,6 +2127,92 @@ function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
1723
2127
  };
1724
2128
  }
1725
2129
 
2130
+ /** The unified section accepts only lossless current-format Workspace evidence, never tolerant legacy repair. */
2131
+ export function parseTelegramWorkspaceStateSection(value: unknown, profile: string): TelegramTopicTargetFile | undefined {
2132
+ if (value === undefined) return undefined;
2133
+ if (!restoreObject(value) || value.version !== 1 || value.source !== "snapshot" ||
2134
+ !Number.isSafeInteger(value.writtenAtMs) || (value.writtenAtMs as number) < 0 ||
2135
+ !restoreObject(value.bot) || !Array.isArray(value.threads))
2136
+ throw new Error("Invalid consolidated Workspace section.");
2137
+ if (Buffer.byteLength(JSON.stringify(value)) > WORKSPACE_SNAPSHOT_MAX_BYTES)
2138
+ throw new Error("Workspace snapshot byte capacity reached.");
2139
+ const parsed = parseTopicTargetFile(value), rawThreads = value.threads;
2140
+ const wire = JSON.parse(JSON.stringify(parsed)) as Record<string, unknown>;
2141
+ wire.threads = (wire.threads as Record<string, unknown>[]).map((record, index) => {
2142
+ const copied = { ...record };
2143
+ const original = rawThreads[index];
2144
+ if (!restoreObject(original)) throw new Error("Invalid consolidated Workspace thread evidence.");
2145
+ if (!Object.hasOwn(original, "profileKey")) delete copied.profileKey;
2146
+ return copied;
2147
+ });
2148
+ for (const key of Object.keys(value)) {
2149
+ if (!Object.hasOwn(wire, key) || !isDeepStrictEqual(value[key], wire[key]))
2150
+ throw new Error("Consolidated Workspace evidence cannot drop or normalize unknown facts.");
2151
+ }
2152
+ if ((parsed.workspaceRestore && parsed.workspaceRestore.profileName !== profile) ||
2153
+ (parsed.sessionReplacement && parsed.sessionReplacement.profileName !== profile) ||
2154
+ parsed.threads.some(record => record.owner && "telegramProfile" in record.owner &&
2155
+ record.owner.telegramProfile !== undefined && record.owner.telegramProfile !== profile))
2156
+ throw new Error("Foreign consolidated Workspace profile evidence.");
2157
+ assertWorkspaceRestoreBindingProtection(parsed);
2158
+ return parsed;
2159
+ }
2160
+
2161
+ export function resolveTelegramWorkspaceProvisionRecoveryPath(statePath: string, profileName = "default", layout?: "consolidated"): string {
2162
+ if (layout !== undefined && layout !== "consolidated") throw new Error("Invalid Workspace provisioning recovery layout.");
2163
+ return layout === "consolidated"
2164
+ ? join(dirname(statePath), "runtime", `${basename(statePath)}.provision-recovery.${createHash("sha256").update(profileName).digest("hex").slice(0, 16)}.json`)
2165
+ : `${statePath}.provision-recovery.json`;
2166
+ }
2167
+
2168
+ export interface TelegramConsolidatedWorkspaceStorageOptions {
2169
+ getPath: () => string;
2170
+ getProfile: () => string | undefined;
2171
+ /** Exact owner/context/session grant captured before the caller's first await. */
2172
+ captureAuthority: () => (() => boolean) | undefined;
2173
+ publishIfOwned: NonNullable<TelegramLockRuntime<TelegramLockContext>["publishStateSectionIfOwned"]>;
2174
+ }
2175
+ export type TelegramWorkspaceStatePublication = <T>(
2176
+ mutate: (current: unknown) => TelegramRuntimeStateMutation<T>,
2177
+ publication?: Partial<Pick<TelegramOwnedStatePublicationOptions, "onPublicationBoundary" | "publishRename" | "isCurrent">>,
2178
+ ) => TelegramOwnedStatePublicationResult<T>;
2179
+
2180
+ /** Prepared Workspace IO adapter; transition/CAS policy remains with the existing Threads owner. */
2181
+ export function createTelegramConsolidatedWorkspaceStorage(options: TelegramConsolidatedWorkspaceStorageOptions) {
2182
+ const { getPath, getProfile, captureAuthority, publishIfOwned } = options;
2183
+ const profileName = (): string => getProfile() ?? "default";
2184
+ const readRaw = (): unknown => {
2185
+ const path = getPath(), profile = profileName(), root = readTelegramRuntimeState(path);
2186
+ const raw = Object.hasOwn(root.profiles, profile) ? root.profiles[profile]?.workspace : undefined;
2187
+ parseTelegramWorkspaceStateSection(raw, profile);
2188
+ if (path !== getPath() || profile !== profileName()) throw new Error("Workspace storage scope changed during observation.");
2189
+ return raw;
2190
+ };
2191
+ return {
2192
+ readRaw,
2193
+ read: () => parseTelegramWorkspaceStateSection(readRaw(), profileName()),
2194
+ capturePublication(): TelegramWorkspaceStatePublication | undefined {
2195
+ const path = getPath(), profile = profileName(), authority = captureAuthority();
2196
+ if (!authority) return undefined;
2197
+ const isCurrent = (): boolean => path === getPath() && profile === profileName() && authority() === true;
2198
+ if (!isCurrent()) return undefined;
2199
+ return <T>(mutate: (current: unknown) => TelegramRuntimeStateMutation<T>,
2200
+ publication?: Partial<Pick<TelegramOwnedStatePublicationOptions, "onPublicationBoundary" | "publishRename" | "isCurrent">>) => {
2201
+ const sourceCurrent = publication?.isCurrent;
2202
+ const currentGrant = () => isCurrent() && (sourceCurrent?.() ?? true);
2203
+ if (!currentGrant()) return { committed: false };
2204
+ return publishIfOwned<T>("workspace", current => {
2205
+ parseTelegramWorkspaceStateSection(current, profile);
2206
+ const next = mutate(current);
2207
+ if (next.value === undefined && current !== undefined) throw new Error("Consolidated Workspace section removal is not authorized.");
2208
+ parseTelegramWorkspaceStateSection(next.value, profile);
2209
+ return next;
2210
+ }, { ...publication, isCurrent: currentGrant, expectedScope: { path, profile } });
2211
+ };
2212
+ },
2213
+ };
2214
+ }
2215
+
1726
2216
  function getTelegramStateSemanticSnapshot(
1727
2217
  value: unknown,
1728
2218
  ): Record<string, unknown> | undefined {
@@ -1735,14 +2225,6 @@ function getTelegramStateSemanticSnapshot(
1735
2225
  return semantic;
1736
2226
  }
1737
2227
 
1738
- function targetMatches(left: TelegramTarget, right: TelegramTarget): boolean {
1739
- return left.chatId === right.chatId && left.threadId === right.threadId;
1740
- }
1741
-
1742
- function getTargetRecoveryHintKey(target: TelegramTarget): string {
1743
- return `${target.chatId}:${target.threadId ?? "private"}`;
1744
- }
1745
-
1746
2228
  function parseFollowerRecoveryHints(
1747
2229
  value: unknown,
1748
2230
  ): Map<string, { slot?: string; threadName?: string }> {
@@ -1819,9 +2301,37 @@ function isPendingProvisionLiveOrTargeted(
1819
2301
  return !!provision.target;
1820
2302
  }
1821
2303
 
2304
+ /** Resolving selects a scope-bound view of the existing Workspace owner; it creates no files. */
2305
+ export function createTelegramWorkspaceRestoreResolver(deps: {
2306
+ getProfileName: () => string | undefined;
2307
+ getBotToken: () => string | undefined;
2308
+ threadStore: Pick<TelegramTopicTargetStore, "workspaceRestore">;
2309
+ agentDir?: string;
2310
+ }) {
2311
+ const { getProfileName, getBotToken, threadStore, agentDir } = deps;
2312
+ let active: { profileName: string; tokenSha256: string; store: TelegramWorkspaceRestore } | undefined;
2313
+ return () => {
2314
+ const profile = getProfileName();
2315
+ const profileName = profile ?? "default";
2316
+ const token = getBotToken();
2317
+ if (!token) return undefined;
2318
+ const tokenSha256 = createHash("sha256").update(token).digest("hex");
2319
+ if (active?.profileName === profileName && active.tokenSha256 === tokenSha256) return active.store;
2320
+ const store = threadStore.workspaceRestore({ profileName, tokenSha256,
2321
+ legacyPath: resolveTelegramProfileTempFilePath("workspace-restore", "json", agentDir, profile),
2322
+ isCurrentScope: () => (getProfileName() ?? "default") === profileName &&
2323
+ createHash("sha256").update(getBotToken() ?? "").digest("hex") === tokenSha256 });
2324
+ active = { profileName, tokenSha256, store };
2325
+ return store;
2326
+ };
2327
+ }
2328
+
1822
2329
  export function createTelegramTopicTargetStore(
1823
2330
  options: TelegramTopicTargetStoreOptions,
1824
2331
  ): TelegramTopicTargetStore {
2332
+ if (options.consolidated && options.commitPersist) throw new Error("Workspace must select one publication backend.");
2333
+ const consolidated = options.consolidated ? { ...options.consolidated } : undefined;
2334
+ const commitPersist = options.commitPersist?.bind(options);
1825
2335
  const getNowMs = options.getNowMs ?? Date.now;
1826
2336
  const captureExternalReservedSlots = (): string[] | undefined => {
1827
2337
  try {
@@ -1840,6 +2350,7 @@ export function createTelegramTopicTargetStore(
1840
2350
  let identities = new Map<string, TelegramThreadIdentityRecord>();
1841
2351
  let workspaceBindings = new Map<string, TelegramWorkspaceThreadBinding>();
1842
2352
  let workspaceRetirements: TelegramWorkspaceRetirementIntent[] = [];
2353
+ let workspaceRestore: TelegramWorkspaceRestoreSnapshot | undefined;
1843
2354
  let sessionReplacement: TelegramSessionReplacementIntent | undefined;
1844
2355
  let workspaceRetirementCommitInFlight = false;
1845
2356
  const hasWorkspaceRetirementConflict = (input: {
@@ -1870,10 +2381,14 @@ export function createTelegramTopicTargetStore(
1870
2381
  >();
1871
2382
  let loaded = false;
1872
2383
  let loadedPath: string | undefined;
2384
+ let loadedProfile: string | undefined;
2385
+ let observedWorkspaceSemantic: Record<string, unknown> | undefined;
1873
2386
  let dirty = false;
1874
2387
  let mutationRevision = 0;
1875
- let statusRevision = 0;
1876
2388
  let persistQueue: Promise<void> = Promise.resolve();
2389
+ let statusQueue: Promise<void> = Promise.resolve();
2390
+ let lastStatusSemantic: Record<string, unknown> | undefined;
2391
+ let lastStatusPath: string | undefined;
1877
2392
  let statusSnapshot: {
1878
2393
  runtime?: Record<string, unknown>;
1879
2394
  liveRoster?: Record<string, unknown>;
@@ -1967,6 +2482,11 @@ export function createTelegramTopicTargetStore(
1967
2482
 
1968
2483
  const getPath = () =>
1969
2484
  typeof options.path === "function" ? options.path() : options.path;
2485
+ /** The non-canonical projection sits beside canonical state (`state*.json` → `status*.json`). */
2486
+ const getStatusPath = (): string => {
2487
+ const statePath = getPath(), name = basename(statePath);
2488
+ return join(dirname(statePath), /^state/u.test(name) ? name.replace(/^state/u, "status") : `${name}.status`);
2489
+ };
1970
2490
  const getTelegramProfile = () =>
1971
2491
  typeof options.telegramProfile === "function"
1972
2492
  ? options.telegramProfile()
@@ -1985,11 +2505,61 @@ export function createTelegramTopicTargetStore(
1985
2505
  }
1986
2506
  return { ...owner, telegramProfile };
1987
2507
  };
1988
- const getRecoveryPath = (path: string) => `${path}.provision-recovery.json`;
2508
+ const activeProfile = () => getTelegramProfile() ?? "default";
2509
+ const scopeMatches = (path: string, profile: string) => getPath() === path && activeProfile() === profile;
2510
+ const loadedScopeMatches = (path: string) => loadedPath === path && (!consolidated || loadedProfile === activeProfile());
2511
+ const workspaceIO = consolidated ? createTelegramConsolidatedWorkspaceStorage({ getPath, getProfile: getTelegramProfile, ...consolidated }) : undefined;
2512
+ const runtimeProjection = consolidated ? createTelegramRuntimeProjectionStore({ getPath, getProfile: getTelegramProfile,
2513
+ captureAuthority: consolidated.captureAuthority, getNowMs,
2514
+ storage: {
2515
+ read({ path, profile }) { const root = readTelegramRuntimeState(path); return Object.hasOwn(root.profiles, profile) ? root.profiles[profile]?.runtime : undefined; },
2516
+ publish(expectedScope, mutate, isCurrent) {
2517
+ const outcome = consolidated.publishIfOwned("runtime", current => {
2518
+ const next = mutate(current);
2519
+ return { value: next.value, result: next.changed };
2520
+ }, { isCurrent, expectedScope });
2521
+ return outcome.committed && outcome.result;
2522
+ },
2523
+ },
2524
+ }) : undefined;
2525
+ let workspaceFrame: { path: string; profile: string; value: unknown } | undefined;
2526
+ const readStoreSnapshot = (path: string, requirePrivate = true, asynchronous = false): unknown => {
2527
+ if (!workspaceIO) return readWorkspaceSnapshot(path, requirePrivate, asynchronous);
2528
+ if (path !== getPath()) throw new Error("Workspace storage scope changed during observation.");
2529
+ if (workspaceFrame) {
2530
+ if (!scopeMatches(workspaceFrame.path, workspaceFrame.profile)) throw new Error("Workspace transaction scope changed.");
2531
+ return workspaceFrame.value;
2532
+ }
2533
+ const value = workspaceIO.readRaw();
2534
+ return asynchronous ? Promise.resolve(value) : value;
2535
+ };
2536
+ const withStoreTransaction = <T>(path: string, operation: () => T,
2537
+ publication?: Parameters<TelegramWorkspaceStatePublication>[1]): T => {
2538
+ if (!workspaceIO) return withTelegramFileTransaction(`${path}.transaction`, operation);
2539
+ if (workspaceFrame) throw new Error("Nested Workspace transaction is not allowed.");
2540
+ const profile = activeProfile(), publish = workspaceIO.capturePublication();
2541
+ if (!publish || path !== getPath()) throw new Error("Workspace publication authority changed.");
2542
+ const outcome = publish(value => {
2543
+ workspaceFrame = { path, profile, value };
2544
+ try { const result = operation(); return { value: workspaceFrame.value, result }; }
2545
+ finally { workspaceFrame = undefined; }
2546
+ }, publication);
2547
+ if (!outcome.committed) throw new Error("Workspace publication authority changed.");
2548
+ return outcome.result;
2549
+ };
2550
+ const getRecoveryPath = (path: string) => consolidated
2551
+ ? resolveTelegramWorkspaceProvisionRecoveryPath(path, activeProfile(), "consolidated")
2552
+ : resolveTelegramWorkspaceProvisionRecoveryPath(path);
1989
2553
  const readProvisionRecoveries = (
1990
- path: string,
2554
+ path: string, strict = false,
1991
2555
  ): TelegramProvisionRecoveryFile => {
1992
2556
  const recoveryPath = getRecoveryPath(path);
2557
+ if (strict) {
2558
+ const value = readWorkspaceSnapshot(recoveryPath);
2559
+ if (value === undefined) return {};
2560
+ if (!restoreObject(value)) throw new Error("Invalid Workspace provisioning recovery evidence.");
2561
+ return value as TelegramProvisionRecoveryFile;
2562
+ }
1993
2563
  if (!existsSync(recoveryPath)) return {};
1994
2564
  try {
1995
2565
  const value = JSON.parse(readFileSync(recoveryPath, "utf8")) as unknown;
@@ -2000,13 +2570,39 @@ export function createTelegramTopicTargetStore(
2000
2570
  return {};
2001
2571
  }
2002
2572
  };
2573
+ const assertRestoreRecoveryProtection = (path: string, operations: readonly TelegramWorkspaceRestoreIntent[],
2574
+ provisions: readonly TelegramThreadPendingProvision[], requireKnownTargets = false,
2575
+ recoveryEvidence?: TelegramProvisionRecoveryFile): void => {
2576
+ if (!operations.length) return;
2577
+ const recoveries = recoveryEvidence ?? readProvisionRecoveries(path, true);
2578
+ for (const provision of provisions) {
2579
+ let target = provision.target;
2580
+ if (Object.hasOwn(recoveries, provision.id)) {
2581
+ const recovery = recoveries[provision.id];
2582
+ if (!restoreObject(recovery)) throw new Error("Invalid Workspace provisioning recovery evidence.");
2583
+ if (recovery.instanceId === provision.instanceId && recovery.profileKey === provision.profileKey &&
2584
+ recovery.leaderEpoch === provision.leaderEpoch) {
2585
+ const observed = recovery.target;
2586
+ if (!restoreObject(observed) || typeof observed.chatId !== "number" || !Number.isSafeInteger(observed.chatId) ||
2587
+ !restoreInteger(observed.threadId) || observed.threadId === 0) throw new Error("Invalid Workspace provisioning recovery evidence.");
2588
+ const recovered = { chatId: observed.chatId, threadId: observed.threadId };
2589
+ if (target && !targetMatches(target, recovered)) throw new Error("Conflicting Workspace provisioning target evidence.");
2590
+ target = recovered;
2591
+ }
2592
+ }
2593
+ if (requireKnownTargets && !target) throw new Error("Workspace Restore target availability is unknown during unfinished creation.");
2594
+ if (operations.some(({ request }) => conflictsWithWorkspaceRestoreProvision(request, { ...provision, target })))
2595
+ throw new Error("Protected Workspace Restore provisioning recovery conflict.");
2596
+ }
2597
+ };
2003
2598
  const resetForPath = (path: string) => {
2004
- if (loadedPath === path) return;
2599
+ if (loadedScopeMatches(path)) return;
2005
2600
  botState = { threadMode: "unknown" };
2006
2601
  records = new Map();
2007
2602
  identities = new Map();
2008
2603
  workspaceBindings = new Map();
2009
2604
  workspaceRetirements = [];
2605
+ workspaceRestore = undefined;
2010
2606
  sessionReplacement = undefined;
2011
2607
  workspaceRetirementCommitInFlight = false;
2012
2608
  workspaceClaims = new Map();
@@ -2019,17 +2615,60 @@ export function createTelegramTopicTargetStore(
2019
2615
  loaded = false;
2020
2616
  dirty = false;
2021
2617
  loadedPath = path;
2618
+ loadedProfile = activeProfile();
2619
+ observedWorkspaceSemantic = undefined;
2022
2620
  };
2023
2621
 
2024
- const loadFromDisk = async () => {
2622
+ const observeWorkspaceRestore = (incoming: TelegramWorkspaceRestoreSnapshot | undefined): void => {
2623
+ if (workspaceRestore && (!incoming || incoming.profileName !== workspaceRestore.profileName ||
2624
+ incoming.tokenSha256 !== workspaceRestore.tokenSha256 || incoming.revision < workspaceRestore.revision ||
2625
+ (incoming.revision === workspaceRestore.revision && !isDeepStrictEqual(incoming, workspaceRestore))))
2626
+ throw new Error("Workspace Restore evidence moved backwards or changed without revision.");
2627
+ };
2628
+ const withRestoreRegistration = (candidate: Parameters<TelegramTopicTargetStore["assertWorkspaceRestoreRegistration"]>[0], publish?: () => void): void => {
2025
2629
  const path = getPath();
2630
+ withStoreTransaction(path, () => {
2631
+ const file = parseTopicTargetFile(readStoreSnapshot(path, false));
2632
+ observeWorkspaceRestore(file.workspaceRestore);
2633
+ const operations = file.workspaceRestore?.operations ?? [];
2634
+ if (operations.length) {
2635
+ if ((options.canPersist && !options.canPersist()) || getPath() !== path)
2636
+ throw new Error("Workspace Restore registration authority changed.");
2637
+ assertWorkspaceRestoreBindingProtection(file);
2638
+ assertRestoreRecoveryProtection(path, operations, file.pendingProvisions ?? []);
2639
+ for (const { request } of operations) {
2640
+ if (targetMatches(candidate.target, request.binding.target) ||
2641
+ ((candidate.bindingKey === request.binding.bindingKey || candidate.slot === request.binding.slot ||
2642
+ targetMatches(candidate.target, request.target)) &&
2643
+ (candidate.bindingKey !== request.binding.bindingKey || candidate.slot !== request.binding.slot ||
2644
+ !targetMatches(candidate.target, request.target))))
2645
+ throw new Error("Protected Workspace Restore registration conflicts with its binding or target.");
2646
+ }
2647
+ }
2648
+ if (publish && candidate.bindingKey !== undefined) {
2649
+ const bindings = (file.workspaceBindings ?? []).filter(binding => binding.bindingKey === candidate.bindingKey);
2650
+ if (bindings.length !== 1 || bindings[0]?.slot !== candidate.slot || !targetMatches(bindings[0].target, candidate.target))
2651
+ throw new Error("Workspace registration binding changed before publication.");
2652
+ }
2653
+ publish?.();
2654
+ });
2655
+ };
2656
+ const loadFromDisk = async () => {
2657
+ const path = getPath(), profile = activeProfile();
2026
2658
  resetForPath(path);
2027
- if (!existsSync(path)) {
2659
+ const revision = mutationRevision;
2660
+ const rawFile = await readStoreSnapshot(path, !!workspaceRestore, true);
2661
+ // A read begun before a local mutation cannot replace the newly admitted projection.
2662
+ if (mutationRevision !== revision || getPath() !== path || (consolidated && !scopeMatches(path, profile))) return;
2663
+ if (consolidated) observedWorkspaceSemantic = getTelegramStateSemanticSnapshot(rawFile);
2664
+ if (rawFile === undefined) {
2665
+ if (workspaceRestore?.revision) throw new Error("Workspace Restore evidence disappeared.");
2028
2666
  botState = { threadMode: "unknown" };
2029
2667
  records = new Map();
2030
2668
  identities = new Map();
2031
2669
  workspaceBindings = new Map();
2032
2670
  workspaceRetirements = [];
2671
+ workspaceRestore = undefined;
2033
2672
  sessionReplacement = undefined;
2034
2673
  workspaceRetirementCommitInFlight = false;
2035
2674
  reservations = [];
@@ -2040,14 +2679,14 @@ export function createTelegramTopicTargetStore(
2040
2679
  loaded = true;
2041
2680
  return;
2042
2681
  }
2043
- const revision = mutationRevision;
2044
- const content = await readFile(path, "utf8");
2045
- // A read begun before a local mutation must not replace the newly admitted
2046
- // binding/cleanup state with its older disk snapshot.
2047
- if (mutationRevision !== revision || getPath() !== path) return;
2048
- const rawFile: unknown = JSON.parse(content);
2049
2682
  const file = parseTopicTargetFile(rawFile);
2050
- followerRecoveryHints = parseFollowerRecoveryHints(rawFile);
2683
+ observeWorkspaceRestore(file.workspaceRestore);
2684
+ const recoveries = readProvisionRecoveries(path, !!file.workspaceRestore?.operations.length);
2685
+ assertRestoreRecoveryProtection(path, file.workspaceRestore?.operations ?? [], file.pendingProvisions ?? [], false, recoveries);
2686
+ try { followerRecoveryHints = parseFollowerRecoveryHints(consolidated
2687
+ ? runtimeProjection?.read()
2688
+ : JSON.parse(readFileSync(getStatusPath(), "utf8"))); }
2689
+ catch { followerRecoveryHints = new Map(); }
2051
2690
  botState = file.bot;
2052
2691
  const scopedRecords = file.threads.map((record) =>
2053
2692
  cloneRecord({
@@ -2079,6 +2718,7 @@ export function createTelegramTopicTargetStore(
2079
2718
  workspaceRetirements = (file.workspaceRetirements ?? []).map(
2080
2719
  cloneWorkspaceRetirementIntent,
2081
2720
  );
2721
+ workspaceRestore = structuredClone(file.workspaceRestore);
2082
2722
  sessionReplacement = file.sessionReplacement
2083
2723
  ? cloneSessionReplacementIntent(file.sessionReplacement)
2084
2724
  : undefined;
@@ -2092,9 +2732,7 @@ export function createTelegramTopicTargetStore(
2092
2732
  reservation.expiresAtMs > nowMs,
2093
2733
  )
2094
2734
  .map((reservation) => ({ ...reservation }));
2095
- const recoveries = readProvisionRecoveries(path);
2096
2735
  pendingProvisions = (file.pendingProvisions ?? [])
2097
- .filter((provision) => isPendingProvisionLiveOrTargeted(provision, nowMs))
2098
2736
  .map((provision) => {
2099
2737
  const recovery = recoveries[provision.id];
2100
2738
  const recoveryMatches =
@@ -2110,7 +2748,8 @@ export function createTelegramTopicTargetStore(
2110
2748
  ? { target: { ...provision.target } }
2111
2749
  : {}),
2112
2750
  };
2113
- });
2751
+ })
2752
+ .filter((provision) => isPendingProvisionLiveOrTargeted(provision, nowMs));
2114
2753
  pendingCleanups = (file.pendingCleanups ?? []).map((intent) => ({
2115
2754
  ...intent,
2116
2755
  target: { ...intent.target },
@@ -2124,6 +2763,10 @@ export function createTelegramTopicTargetStore(
2124
2763
  };
2125
2764
 
2126
2765
  const markDirty = (): void => {
2766
+ if (consolidated && !loadedScopeMatches(getPath())) {
2767
+ if (loadedPath !== undefined) throw new Error("Workspace projection must refresh after scope change.");
2768
+ loadedPath = getPath(); loadedProfile = activeProfile();
2769
+ }
2127
2770
  loaded = true;
2128
2771
  dirty = true;
2129
2772
  mutationRevision += 1;
@@ -2146,15 +2789,24 @@ export function createTelegramTopicTargetStore(
2146
2789
  } & (
2147
2790
  | { kind: "invalidate"; lastSyncError: string }
2148
2791
  | { kind: "detach"; owner: TelegramTopicTargetRecord }
2149
- )): Promise<boolean> => {
2792
+ | { kind: "relocate"; operationId: string; owner: TelegramTopicTargetRecord;
2793
+ binding: TelegramWorkspaceThreadBinding;
2794
+ nextTarget: TelegramTarget & { threadId: number };
2795
+ restore: TelegramWorkspaceRestoreSnapshot; maxBytes: number;
2796
+ onPublicationBoundary?: TelegramWorkspaceRestoreOptions["onPublicationBoundary"] }
2797
+ ), isExactJournalFrame?: () => boolean): Promise<boolean> => {
2798
+ const submittedPath = getPath(), submittedProfile = activeProfile();
2799
+ const publishWorkspace = workspaceIO?.capturePublication();
2150
2800
  const persist = persistQueue.then(async () => {
2151
2801
  const path = getPath();
2152
- if (loadedPath !== path && !dirty) resetForPath(path);
2802
+ if (workspaceIO && (!publishWorkspace || !scopeMatches(submittedPath, submittedProfile) || (dirty && !loadedScopeMatches(path)))) return false;
2803
+ if (!loadedScopeMatches(path) && !dirty) resetForPath(path);
2153
2804
  if (options.canPersist && !options.canPersist()) {
2154
2805
  if (!transition) await loadFromDisk();
2155
2806
  return false;
2156
2807
  }
2157
2808
  if (!dirty || !loaded) await loadFromDisk();
2809
+ if (workspaceIO && (!scopeMatches(submittedPath, submittedProfile) || !loadedScopeMatches(path))) return false;
2158
2810
  if (transition && !transition.isCurrent()) return false;
2159
2811
  const nowMs = getNowMs();
2160
2812
  reservations = reservations.filter(
@@ -2172,6 +2824,47 @@ export function createTelegramTopicTargetStore(
2172
2824
  const owners = currentRecords.filter((record) => targetMatches(record.target, transition.target));
2173
2825
  if (owners.length !== 1 || !isDeepStrictEqual(normalizeRecord(owners[0]), transition.owner)) return false;
2174
2826
  }
2827
+ if (transition?.kind === "relocate") {
2828
+ const { binding, owner, nextTarget } = transition;
2829
+ const slots = captureExternalReservedSlots();
2830
+ const sourceBindings = Array.from(workspaceBindings.values())
2831
+ .filter((value) => targetMatches(value.target, binding.target));
2832
+ const sourceOwners = currentRecords.filter((value) => targetMatches(value.target, binding.target));
2833
+ if ((workspaceRestore?.operations ?? []).some((operation) =>
2834
+ workspaceRestoresConflict(operation.request, transition.restore.operations.at(-1)!.request)) ||
2835
+ !binding.sessionId || !binding.slot || !/^[A-Z]$/.test(binding.slot) ||
2836
+ binding.inactiveSinceMs !== undefined || owner.status !== "active" ||
2837
+ !owner.instanceId || owner.slot !== binding.slot ||
2838
+ !["leader", "manual-follower"].includes(owner.owner?.kind ?? "") ||
2839
+ (owner.owner?.kind === "leader" &&
2840
+ (owner.owner.cwd !== binding.cwd || owner.owner.instanceId !== owner.instanceId)) ||
2841
+ !targetMatches(owner.target, binding.target) ||
2842
+ sourceBindings.length !== 1 || !isDeepStrictEqual(sourceBindings[0], binding) ||
2843
+ sourceOwners.length !== 1 || !isDeepStrictEqual(sourceOwners[0], owner) ||
2844
+ !slots || slots.includes(binding.slot) || workspaceRetirementCommitInFlight ||
2845
+ hasWorkspaceRetirementConflict(binding) || hasWorkspaceRetirementConflict({ target: nextTarget }) ||
2846
+ Array.from(workspaceBindings.values()).some((value) =>
2847
+ value.bindingKey !== binding.bindingKey &&
2848
+ (value.slot === binding.slot || targetMatches(value.target, nextTarget))) ||
2849
+ currentRecords.some((value) => targetMatches(value.target, nextTarget) ||
2850
+ (!targetMatches(value.target, binding.target) && value.slot === binding.slot)) ||
2851
+ Array.from(workspaceClaims.values()).some((value) =>
2852
+ value.identity.bindingKey === binding.bindingKey || value.identity.slot === binding.slot) ||
2853
+ reservations.some((value) => value.slot === binding.slot ||
2854
+ targetMatches(value.target, binding.target) || targetMatches(value.target, nextTarget)) ||
2855
+ pendingProvisions.some((value) => value.workspaceBindingKey === binding.bindingKey ||
2856
+ value.instanceId === owner.instanceId || value.profileKey === owner.profileKey ||
2857
+ value.slot === binding.slot || (value.target &&
2858
+ (targetMatches(value.target, binding.target) || targetMatches(value.target, nextTarget)))) ||
2859
+ pendingCleanups.some((value) => targetMatches(value.target, binding.target) ||
2860
+ targetMatches(value.target, nextTarget)) ||
2861
+ syncObservations.some((value) => targetMatches(value.target, nextTarget) &&
2862
+ (value.syncStatus === "deleted" || value.syncStatus === "closed")) ||
2863
+ (sessionReplacement && ((sessionReplacement.cwd === binding.cwd &&
2864
+ sessionReplacement.sourceSessionId === binding.sessionId) ||
2865
+ targetMatches(sessionReplacement.target, binding.target) ||
2866
+ targetMatches(sessionReplacement.target, nextTarget)))) return false;
2867
+ }
2175
2868
  records = new Map(
2176
2869
  currentRecords.map((record) => [
2177
2870
  getRecordOwnerKey(record),
@@ -2179,13 +2872,23 @@ export function createTelegramTopicTargetStore(
2179
2872
  ]),
2180
2873
  );
2181
2874
  const persistedRevision = mutationRevision;
2182
- const persistedStatusRevision = statusRevision;
2875
+ const expectedRestore = structuredClone(workspaceRestore);
2876
+ const assertRestoreEvidenceCurrent = (raw?: unknown, fromTransaction = false): void => {
2877
+ if (isExactJournalFrame?.() === false) throw new Error("Telegram Workspace journal evidence publication lost its exact frame or authority.");
2878
+ const disk = parseTopicTargetFile(fromTransaction ? raw : readStoreSnapshot(path, transition?.kind === "relocate" || !!expectedRestore));
2879
+ if (!isDeepStrictEqual(disk.workspaceRestore, expectedRestore)) throw new Error("Workspace Restore evidence changed before publication.");
2880
+ assertWorkspaceRestoreBindingProtection(disk);
2881
+ assertRestoreRecoveryProtection(path, [...(disk.workspaceRestore?.operations ?? []), ...(file.workspaceRestore?.operations ?? [])],
2882
+ [...(disk.pendingProvisions ?? []), ...(file.pendingProvisions ?? [])]);
2883
+ const additions = (file.workspaceRestore?.operations ?? []).filter(operation =>
2884
+ !disk.workspaceRestore?.operations.some(retained => retained.request.operationId === operation.request.operationId));
2885
+ assertRestoreRecoveryProtection(path, additions, disk.pendingProvisions ?? [], true);
2886
+ };
2183
2887
  const file = {
2184
2888
  version: 1,
2185
2889
  source: "snapshot",
2186
2890
  writtenAtMs: nowMs,
2187
2891
  bot: botState,
2188
- ...statusSnapshot,
2189
2892
  identities: Array.from(identities.values()).map(cloneIdentityRecord),
2190
2893
  workspaceBindings: Array.from(workspaceBindings.values()).map(
2191
2894
  cloneWorkspaceBinding,
@@ -2193,6 +2896,7 @@ export function createTelegramTopicTargetStore(
2193
2896
  workspaceRetirements: workspaceRetirements.map(
2194
2897
  cloneWorkspaceRetirementIntent,
2195
2898
  ),
2899
+ ...(workspaceRestore ? { workspaceRestore: structuredClone(workspaceRestore) } : {}),
2196
2900
  ...(sessionReplacement
2197
2901
  ? { sessionReplacement: cloneSessionReplacementIntent(sessionReplacement) }
2198
2902
  : {}),
@@ -2222,32 +2926,98 @@ export function createTelegramTopicTargetStore(
2222
2926
  if (bindings.length !== 1 || !/^[A-Z]$/.test(record.slot ?? "") ||
2223
2927
  bindings[0]!.slot !== record.slot) return false;
2224
2928
  }
2225
- file.threads = file.threads.filter((candidate) => candidate !== record);
2226
- for (const binding of file.workspaceBindings) {
2227
- if (targetMatches(binding.target, transition.target) && binding.inactiveSinceMs === undefined) {
2228
- binding.inactiveSinceMs = nowMs;
2929
+ if (transition.kind === "relocate") {
2930
+ if (transition.restore.revision !== (workspaceRestore?.revision ?? 0) + 1 ||
2931
+ !isDeepStrictEqual(transition.restore.operations.slice(0, -1), workspaceRestore?.operations ?? [])) return false;
2932
+ file.workspaceRestore = structuredClone(transition.restore);
2933
+ parseWorkspaceRestore(file.workspaceRestore);
2934
+ if (Buffer.byteLength(JSON.stringify(file.workspaceRestore)) > transition.maxBytes)
2935
+ throw new Error("Workspace Restore byte capacity reached.");
2936
+ const binding = file.workspaceBindings.find((value) =>
2937
+ value.bindingKey === transition.binding.bindingKey)!;
2938
+ binding.target = { ...transition.nextTarget };
2939
+ binding.updatedAtMs = nowMs;
2940
+ delete binding.displayTitle;
2941
+ record.target = { ...transition.nextTarget };
2942
+ record.updatedAtMs = nowMs;
2943
+ record.rerouteConfirmedAtMs = nowMs;
2944
+ record.syncStatus = "unknown";
2945
+ record.lastReconcileAction = "workspace-restore";
2946
+ delete record.lastError;
2947
+ delete record.lastSyncError;
2948
+ delete record.lastSyncObservedAtMs;
2949
+ delete record.lastSyncProbeAtMs;
2950
+ } else {
2951
+ file.threads = file.threads.filter((candidate) => candidate !== record);
2952
+ for (const binding of file.workspaceBindings) {
2953
+ if (targetMatches(binding.target, transition.target) && binding.inactiveSinceMs === undefined) {
2954
+ binding.inactiveSinceMs = nowMs;
2955
+ }
2956
+ }
2957
+ if (transition.kind === "invalidate") {
2958
+ file.syncObservations = file.syncObservations.filter((observation) => !targetMatches(observation.target, record.target));
2959
+ file.syncObservations.push({
2960
+ target: { ...record.target },
2961
+ syncStatus: "deleted",
2962
+ observedAtMs: nowMs,
2963
+ ...(record.instanceId ? { instanceId: record.instanceId } : {}),
2964
+ ...(record.slot ? { slot: record.slot } : {}),
2965
+ lastSyncError: transition.lastSyncError,
2966
+ lastReconcileAction: "mark-stale",
2967
+ });
2229
2968
  }
2230
2969
  }
2231
- if (transition.kind === "invalidate") {
2232
- file.syncObservations = file.syncObservations.filter((observation) => !targetMatches(observation.target, record.target));
2233
- file.syncObservations.push({
2234
- target: { ...record.target },
2235
- syncStatus: "deleted",
2236
- observedAtMs: nowMs,
2237
- ...(record.instanceId ? { instanceId: record.instanceId } : {}),
2238
- ...(record.slot ? { slot: record.slot } : {}),
2239
- lastSyncError: transition.lastSyncError,
2240
- lastReconcileAction: "mark-stale",
2241
- });
2970
+ }
2971
+ assertWorkspaceRestoreBindingProtection(file);
2972
+ assertRestoreRecoveryProtection(path, file.workspaceRestore?.operations ?? [], file.pendingProvisions ?? []);
2973
+ if (publishWorkspace) {
2974
+ const wire = JSON.parse(JSON.stringify(file));
2975
+ const outcome = publishWorkspace(current => {
2976
+ if (!scopeMatches(submittedPath, submittedProfile) || mutationRevision !== persistedRevision ||
2977
+ transition?.isCurrent() === false || isExactJournalFrame?.() === false) return { value: current, result: false };
2978
+ const semanticCurrent = getTelegramStateSemanticSnapshot(current);
2979
+ if (!isDeepStrictEqual(semanticCurrent, observedWorkspaceSemantic))
2980
+ throw new Error("Workspace canonical snapshot changed before publication.");
2981
+ // A late whole-Workspace replacement cannot erase a concurrent canonical mutation.
2982
+ if (workspaceRestore && !isDeepStrictEqual(parseTopicTargetFile(current).workspaceRestore, expectedRestore))
2983
+ throw new Error("Workspace Restore evidence changed before publication.");
2984
+ assertRestoreEvidenceCurrent(current, true);
2985
+ if (transition?.kind === "relocate") {
2986
+ const slots = captureExternalReservedSlots();
2987
+ if (!slots || slots.includes(transition.binding.slot!) || workspaceRetirementCommitInFlight ||
2988
+ Array.from(workspaceClaims.values()).some(value => value.identity.bindingKey === transition.binding.bindingKey || value.identity.slot === transition.binding.slot))
2989
+ return { value: current, result: false };
2990
+ }
2991
+ const unchanged = !transition && isDeepStrictEqual(semanticCurrent, getTelegramStateSemanticSnapshot(wire));
2992
+ return { value: unchanged ? current : wire, result: true };
2993
+ }, { isCurrent: () => scopeMatches(submittedPath, submittedProfile) && mutationRevision === persistedRevision &&
2994
+ (transition?.isCurrent() ?? true) && (isExactJournalFrame?.() ?? true),
2995
+ onPublicationBoundary: transition?.kind === "relocate" ? boundary => {
2996
+ if (boundary !== "before-write") transition.onPublicationBoundary?.(boundary);
2997
+ } : undefined });
2998
+ if (!outcome.committed || !outcome.result) return false;
2999
+ loadedPath = path; loadedProfile = submittedProfile; loaded = true;
3000
+ observedWorkspaceSemantic = getTelegramStateSemanticSnapshot(wire);
3001
+ if (transition) {
3002
+ records = new Map(file.threads.map(record => {
3003
+ const normalized = normalizeRecord(record)!;
3004
+ return [getRecordOwnerKey(normalized), cloneRecord(normalized)];
3005
+ }));
3006
+ workspaceRestore = structuredClone(file.workspaceRestore);
3007
+ syncObservations = file.syncObservations;
3008
+ workspaceBindings = new Map(file.workspaceBindings.map(binding => [getWorkspaceBindingMapKey(binding), cloneWorkspaceBinding(binding)]));
3009
+ mutationRevision += 1;
2242
3010
  }
3011
+ dirty = false;
3012
+ return true;
2243
3013
  }
2244
3014
  let persistedSemanticSnapshot: Record<string, unknown> | undefined;
2245
3015
  try {
2246
3016
  persistedSemanticSnapshot = getTelegramStateSemanticSnapshot(
2247
- JSON.parse(await readFile(path, "utf8")),
3017
+ await readStoreSnapshot(path, !!workspaceRestore, true),
2248
3018
  );
2249
3019
  } catch {
2250
- /* missing or invalid snapshots must be replaced */
3020
+ /* Final Restore validation fences missing or unverifiable snapshots before publication. */
2251
3021
  }
2252
3022
  // Normalize optional fields to wire JSON; object key order is not a state change.
2253
3023
  if (
@@ -2255,32 +3025,49 @@ export function createTelegramTopicTargetStore(
2255
3025
  persistedSemanticSnapshot,
2256
3026
  getTelegramStateSemanticSnapshot(JSON.parse(JSON.stringify(file))),
2257
3027
  ) &&
2258
- mutationRevision === persistedRevision &&
2259
- statusRevision === persistedStatusRevision
3028
+ mutationRevision === persistedRevision
2260
3029
  ) {
2261
3030
  loadedPath = path;
2262
3031
  loaded = true;
2263
3032
  dirty = false;
2264
3033
  return true;
2265
3034
  }
3035
+ const serialized = `${JSON.stringify(file, null, 2)}\n`;
3036
+ if (file.workspaceRestore && Buffer.byteLength(serialized) > WORKSPACE_SNAPSHOT_MAX_BYTES)
3037
+ throw new Error("Workspace snapshot byte capacity reached.");
2266
3038
  await mkdir(dirname(path), { recursive: true });
2267
3039
  const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
2268
- await writeFile(tempPath, `${JSON.stringify(file, null, 2)}\n`, {
2269
- encoding: "utf8",
2270
- mode: 0o600,
2271
- });
3040
+ await writeFile(tempPath, serialized, { encoding: "utf8", flag: "wx", mode: 0o600 });
2272
3041
  await chmod(tempPath, 0o600);
2273
3042
  try {
2274
3043
  if (transition) {
3044
+ if (transition.kind === "relocate") transition.onPublicationBoundary?.("after-write-before-rename");
2275
3045
  let applied = false;
2276
3046
  const commit = () => {
2277
- if (getPath() !== path || mutationRevision !== persistedRevision ||
2278
- statusRevision !== persistedStatusRevision || !transition.isCurrent()) return;
2279
- // Fence and rename share one synchronous commit boundary. No stale
2280
- // transition enters the live projection before durable commit.
3047
+ if (!transition.isCurrent()) return;
3048
+ if (transition.kind === "relocate") {
3049
+ // Transient claims and external fences do not advance snapshot revisions.
3050
+ const slots = captureExternalReservedSlots();
3051
+ if (!slots || slots.includes(transition.binding.slot!) || workspaceRetirementCommitInFlight ||
3052
+ Array.from(workspaceClaims.values()).some((value) =>
3053
+ value.identity.bindingKey === transition.binding.bindingKey ||
3054
+ value.identity.slot === transition.binding.slot)) return;
3055
+ }
3056
+ if (getPath() !== path || mutationRevision !== persistedRevision) return;
3057
+ // All publishers fence the same retained operation, including after its terminal removal.
3058
+ assertRestoreEvidenceCurrent();
3059
+ if (!transition.isCurrent() || getPath() !== path || mutationRevision !== persistedRevision) return;
2281
3060
  renameSync(tempPath, path);
2282
3061
  loadedPath = path;
2283
- records = new Map(Array.from(records).filter(([, record]) => !targetMatches(record.target, transition.target)));
3062
+ if (transition.kind === "relocate") {
3063
+ const relocated = file.threads.find((record) => targetMatches(record.target, transition.nextTarget))!;
3064
+ records.set(getRecordOwnerKey(transition.owner), {
3065
+ ...relocated, profileKey: transition.owner.profileKey,
3066
+ });
3067
+ } else {
3068
+ records = new Map(Array.from(records).filter(([, record]) => !targetMatches(record.target, transition.target)));
3069
+ }
3070
+ workspaceRestore = structuredClone(file.workspaceRestore);
2284
3071
  syncObservations = file.syncObservations;
2285
3072
  workspaceBindings = new Map(file.workspaceBindings.map((binding) => [
2286
3073
  getWorkspaceBindingMapKey(binding), cloneWorkspaceBinding(binding),
@@ -2288,17 +3075,21 @@ export function createTelegramTopicTargetStore(
2288
3075
  mutationRevision += 1;
2289
3076
  dirty = false;
2290
3077
  applied = true;
3078
+ if (transition.kind === "relocate") transition.onPublicationBoundary?.("after-rename");
2291
3079
  };
2292
- if (options.commitPersist) options.commitPersist(commit);
2293
- else if (!options.canPersist || options.canPersist()) commit();
3080
+ withTelegramFileTransaction(`${path}.transaction`, () => {
3081
+ if (commitPersist) commitPersist(commit);
3082
+ else if (!options.canPersist || options.canPersist()) commit();
3083
+ });
2294
3084
  if (!applied) await unlink(tempPath).catch(() => undefined);
2295
3085
  return applied;
2296
3086
  }
2297
- if (options.commitPersist) {
2298
- const committed = options.commitPersist(() => {
3087
+ if (commitPersist) {
3088
+ const committed = withTelegramFileTransaction(`${path}.transaction`, () => commitPersist(() => {
3089
+ assertRestoreEvidenceCurrent();
2299
3090
  renameSync(tempPath, path);
2300
3091
  chmodSync(path, 0o600);
2301
- });
3092
+ }));
2302
3093
  if (!committed) {
2303
3094
  await loadFromDisk();
2304
3095
  throw new Error(
@@ -2306,8 +3097,11 @@ export function createTelegramTopicTargetStore(
2306
3097
  );
2307
3098
  }
2308
3099
  } else {
2309
- await rename(tempPath, path);
2310
- await chmod(path, 0o600);
3100
+ withTelegramFileTransaction(`${path}.transaction`, () => {
3101
+ assertRestoreEvidenceCurrent();
3102
+ renameSync(tempPath, path);
3103
+ chmodSync(path, 0o600);
3104
+ });
2311
3105
  }
2312
3106
  } catch (error) {
2313
3107
  await unlink(tempPath).catch(() => undefined);
@@ -2324,6 +3118,7 @@ export function createTelegramTopicTargetStore(
2324
3118
 
2325
3119
  return {
2326
3120
  async load() {
3121
+ if (workspaceIO && dirty && !loadedScopeMatches(getPath())) throw new Error("Workspace projection must refresh after scope change.");
2327
3122
  if (dirty) return;
2328
3123
  await loadFromDisk();
2329
3124
  },
@@ -2333,7 +3128,8 @@ export function createTelegramTopicTargetStore(
2333
3128
  return refresh;
2334
3129
  },
2335
3130
  async persist() {
2336
- await persistSnapshot();
3131
+ const committed = await persistSnapshot();
3132
+ if (workspaceIO && !committed) throw new Error("Workspace snapshot lost captured publication authority.");
2337
3133
  },
2338
3134
  invalidateTarget(target, isCurrent, lastSyncError) {
2339
3135
  return persistSnapshot({ kind: "invalidate", target, isCurrent, lastSyncError });
@@ -2343,6 +3139,563 @@ export function createTelegramTopicTargetStore(
2343
3139
  if (!owner) return Promise.resolve(false);
2344
3140
  return persistSnapshot({ kind: "detach", owner, target: owner.target, isCurrent });
2345
3141
  },
3142
+ assertWorkspaceRestoreRegistration(candidate) {
3143
+ withRestoreRegistration(candidate);
3144
+ },
3145
+ commitWorkspaceRestoreRegistration: withRestoreRegistration,
3146
+ listTemporaryThreadTargets() {
3147
+ const file = parseTopicTargetFile(readStoreSnapshot(getPath(), false) ?? { version: 1, records: [] });
3148
+ return (file.workspaceRestore?.temporaryThreads ?? []).flatMap(entry => entry.target ? [{ ...entry.target }] : []);
3149
+ },
3150
+ withWorkspaceRestoreSnapshot(expected, observe) {
3151
+ const path = getPath();
3152
+ withStoreTransaction(path, () => {
3153
+ const file = parseTopicTargetFile(readStoreSnapshot(path, false));
3154
+ observeWorkspaceRestore(file.workspaceRestore);
3155
+ if (getPath() !== path || !isDeepStrictEqual(file.workspaceRestore?.operations.find(
3156
+ intent => intent.request.operationId === expected.request.operationId), expected))
3157
+ throw new Error("Workspace Restore observation changed.");
3158
+ assertWorkspaceRestoreBindingProtection(file);
3159
+ assertRestoreRecoveryProtection(path, file.workspaceRestore!.operations, file.pendingProvisions ?? []);
3160
+ observe({ threads: file.threads, workspaceBindings: file.workspaceBindings });
3161
+ });
3162
+ },
3163
+ workspaceRestore(storageOptions) {
3164
+ const path = getPath(), profile = activeProfile();
3165
+ const now = storageOptions.getNowMs ?? Date.now;
3166
+ const { profileName, tokenSha256, isCurrentScope, legacyPath, onPublicationBoundary } = storageOptions;
3167
+ if (consolidated && profileName !== profile) throw new Error("Foreign Workspace Restore storage scope.");
3168
+ const maxBytes = Math.min(storageOptions.maxBytes ?? WORKSPACE_RESTORE_MAX_BYTES, WORKSPACE_RESTORE_MAX_BYTES);
3169
+ if (!restoreText(profileName) || !/^[a-f0-9]{64}$/u.test(tokenSha256) || !Number.isSafeInteger(maxBytes) || maxBytes <= 0)
3170
+ throw new Error("Invalid Workspace Restore storage scope.");
3171
+ const empty: TelegramWorkspaceRestoreSnapshot = { version: 1, profileName, tokenSha256, revision: 0, operations: [] };
3172
+ let observed: TelegramWorkspaceRestoreSnapshot | undefined;
3173
+ const currentScope = () => getPath() === path && (!consolidated || scopeMatches(path, profile)) && (isCurrentScope?.() ?? true) && (options.canPersist?.() ?? true);
3174
+ const read = (): { file: Record<string, unknown>; state: TelegramWorkspaceRestoreSnapshot } => {
3175
+ if (legacyPath) {
3176
+ try { lstatSync(legacyPath); throw new Error("Unmigrated Workspace Restore file."); }
3177
+ catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
3178
+ }
3179
+ const raw = readStoreSnapshot(path);
3180
+ if (raw !== undefined && (!restoreObject(raw) || raw.version !== 1)) throw new Error("Invalid Workspace snapshot.");
3181
+ const file = (raw ?? (consolidated ? { version: 1, source: "snapshot", writtenAtMs: 0, bot: { threadMode: "unknown" }, threads: [] }
3182
+ : { version: 1, records: [] })) as Record<string, unknown>;
3183
+ const state = parseTopicTargetFile(file).workspaceRestore;
3184
+ if (state && (state.profileName !== profileName || state.tokenSha256 !== tokenSha256))
3185
+ throw new Error("Invalid or foreign Workspace Restore evidence.");
3186
+ if (observed && (!state || state.revision < observed.revision ||
3187
+ (state.revision === observed.revision && !isDeepStrictEqual(state, observed))))
3188
+ throw new Error("Workspace Restore evidence moved backwards or changed without revision.");
3189
+ if (state && Buffer.byteLength(JSON.stringify(state)) > maxBytes) throw new Error("Workspace Restore byte capacity reached.");
3190
+ observed = structuredClone(state);
3191
+ if (loadedScopeMatches(path)) observeWorkspaceRestore(state);
3192
+ return { file, state: structuredClone(state ?? empty) };
3193
+ };
3194
+ const inspectTemporaryOwnership = (before: ReturnType<typeof read>, entry: TelegramTemporaryThreadEntry): TelegramTemporaryThreadTargetObservation => {
3195
+ if (entry.phase !== "created" || !entry.target) return { kind: "unknown" };
3196
+ const file = parseTopicTargetFile(before.file);
3197
+ // Normalization omissions never prove an unbound target.
3198
+ for (const key of ["threads", "workspaceBindings", "reservations", "pendingProvisions", "pendingCleanups", "workspaceRetirements"] as const) {
3199
+ const raw = before.file[key];
3200
+ if ((key === "threads" && raw === undefined) || (raw !== undefined &&
3201
+ (!Array.isArray(raw) || raw.length !== (file[key]?.length ?? 0))))
3202
+ throw new Error("Invalid temporary Thread target evidence.");
3203
+ }
3204
+ assertWorkspaceRestoreBindingProtection(file);
3205
+ assertRestoreRecoveryProtection(path, before.state.operations, file.pendingProvisions ?? [], true);
3206
+ const target = entry.target;
3207
+ const bindings = (file.workspaceBindings ?? []).filter(value => targetMatches(value.target, target));
3208
+ if (bindings.length === 1) return { kind: "bound", binding: structuredClone(bindings[0]!) };
3209
+ if (bindings.length > 1 || file.threads.some(value => targetMatches(value.target, target)) ||
3210
+ file.reservations?.some(value => targetMatches(value.target, target)) ||
3211
+ file.pendingProvisions?.some(value => !value.target || targetMatches(value.target, target)) ||
3212
+ file.pendingCleanups?.some(value => targetMatches(value.target, target)) ||
3213
+ file.workspaceRetirements?.some(value => targetMatches(value.binding.target, target)) ||
3214
+ before.state.operations.some(value => targetMatches(value.request.target, target))) return { kind: "unknown" };
3215
+ return { kind: "temporary" };
3216
+ };
3217
+ const classifyTemporaryTarget = (before: ReturnType<typeof read>, entry: TelegramTemporaryThreadEntry): TelegramTemporaryThreadTargetObservation =>
3218
+ entry.cleanupIssued ? { kind: "unknown" } : inspectTemporaryOwnership(before, entry);
3219
+ const storage = {
3220
+ read: () => read().state,
3221
+ async relocate(input: TelegramWorkspaceRestoreIntent, isCurrent: () => boolean) {
3222
+ if (!currentScope() || !isCurrent()) return false;
3223
+ const intent = structuredClone(input);
3224
+ if (!currentScope() || !isCurrent() || !isWorkspaceRestoreIntent(intent) || intent.phase !== "relocated" || intent.revision !== 0 ||
3225
+ intent.recipient !== undefined || intent.routing !== undefined) return false;
3226
+ const state = read().state;
3227
+ if (state.operations.some(operation => workspaceRestoresConflict(operation.request, intent.request))) return false;
3228
+ if (state.revision === Number.MAX_SAFE_INTEGER) throw new Error("Workspace Restore revision exhausted.");
3229
+ if (state.operations.length >= 26) throw new Error("Workspace Restore operation capacity reached.");
3230
+ const restore = { ...state, revision: state.revision + 1, operations: [...state.operations, intent] };
3231
+ const request = intent.request;
3232
+ return persistSnapshot({ kind: "relocate", operationId: request.operationId, binding: request.binding, owner: request.owner,
3233
+ target: { ...request.binding.target }, nextTarget: { ...request.target }, restore, maxBytes, onPublicationBoundary,
3234
+ isCurrent: () => currentScope() && isCurrent() });
3235
+ },
3236
+ update(expectedInput: TelegramWorkspaceRestoreSnapshot, nextInput: TelegramWorkspaceRestoreSnapshot, isCurrent: () => boolean) {
3237
+ const expected = structuredClone(expectedInput), next = structuredClone(nextInput);
3238
+ if (!currentScope() || !isCurrent()) return false;
3239
+ if (expected.revision === Number.MAX_SAFE_INTEGER) throw new Error("Workspace Restore revision exhausted.");
3240
+ if (next.profileName !== profileName || next.tokenSha256 !== tokenSha256 || next.revision !== expected.revision + 1 || !parseWorkspaceRestore(next))
3241
+ throw new Error("Invalid Workspace Restore publication.");
3242
+ if (Buffer.byteLength(JSON.stringify(next)) > maxBytes) throw new Error("Workspace Restore byte capacity reached.");
3243
+ if (!workspaceIO) mkdirSync(dirname(path), { recursive: true });
3244
+ let committedBefore: ReturnType<typeof read> | undefined;
3245
+ let committedAfter: Record<string, unknown> | undefined;
3246
+ const committed = withStoreTransaction(path, () => {
3247
+ const before = read();
3248
+ if (!isDeepStrictEqual(before.state, expected) || !currentScope() || !isCurrent()) return false;
3249
+ for (const entry of next.temporaryThreads ?? []) {
3250
+ const prior = expected.temporaryThreads?.find(value => value.token === entry.token);
3251
+ if (!prior && entry.phase === "created" && classifyTemporaryTarget(before, entry).kind !== "temporary") return false;
3252
+ if (!entry.cleanupIssued) continue;
3253
+ if (!prior?.cleanupIssued && (!prior || classifyTemporaryTarget(before, prior).kind !== "temporary")) return false;
3254
+ }
3255
+ assertWorkspaceRestoreBindingProtection(before.file);
3256
+ const provisions = parseTopicTargetFile(before.file).pendingProvisions ?? [];
3257
+ assertRestoreRecoveryProtection(path, before.state.operations, provisions);
3258
+ const after = { ...before.file, workspaceRestore: next };
3259
+ // New temporary targets must be checked against the file they will be published into.
3260
+ assertWorkspaceRestoreBindingProtection(parseTopicTargetFile(after));
3261
+ const content = JSON.stringify(after);
3262
+ if (Buffer.byteLength(content) > WORKSPACE_SNAPSHOT_MAX_BYTES) throw new Error("Workspace snapshot byte capacity reached.");
3263
+ if (workspaceIO) {
3264
+ if (!workspaceFrame || !currentScope() || !isCurrent()) return false;
3265
+ assertRestoreRecoveryProtection(path, [...before.state.operations, ...next.operations], provisions);
3266
+ committedBefore = before;
3267
+ committedAfter = JSON.parse(content);
3268
+ workspaceFrame.value = committedAfter;
3269
+ return true;
3270
+ }
3271
+ const temporary = `${path}.${randomUUID()}.tmp`;
3272
+ try {
3273
+ writeFileSync(temporary, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
3274
+ onPublicationBoundary?.("after-write-before-rename");
3275
+ let published = false;
3276
+ const publish = (): void => {
3277
+ if (!currentScope() || !isCurrent()) return;
3278
+ if (!isDeepStrictEqual(read().file, before.file)) throw new Error("Workspace Restore evidence changed before publication.");
3279
+ assertRestoreRecoveryProtection(path, [...before.state.operations, ...next.operations], provisions);
3280
+ if (!currentScope() || !isCurrent()) return;
3281
+ renameSync(temporary, path);
3282
+ observed = structuredClone(next);
3283
+ // A read-only Restore view must never bless a stale binding/owner projection.
3284
+ if (loadedPath === path && isDeepStrictEqual(workspaceRestore, before.file.workspaceRestore)) workspaceRestore = structuredClone(next);
3285
+ mutationRevision += 1;
3286
+ published = true;
3287
+ onPublicationBoundary?.("after-rename");
3288
+ };
3289
+ const owned = commitPersist ? commitPersist(publish) : (publish(), true);
3290
+ return owned && published;
3291
+ } finally { try { unlinkSync(temporary); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } }
3292
+ }, { isCurrent: () => currentScope() && isCurrent(), onPublicationBoundary: boundary => {
3293
+ if (boundary !== "before-write") onPublicationBoundary?.(boundary);
3294
+ } });
3295
+ if (workspaceIO && committed && committedBefore && committedAfter) {
3296
+ observed = structuredClone(next);
3297
+ if (loadedScopeMatches(path) && isDeepStrictEqual(workspaceRestore, committedBefore.file.workspaceRestore)) workspaceRestore = structuredClone(next);
3298
+ if (isDeepStrictEqual(observedWorkspaceSemantic, getTelegramStateSemanticSnapshot(committedBefore.file)))
3299
+ observedWorkspaceSemantic = getTelegramStateSemanticSnapshot(committedAfter);
3300
+ mutationRevision += 1;
3301
+ }
3302
+ return committed;
3303
+ },
3304
+ };
3305
+ const mutate = <T extends TelegramWorkspaceRestoreIntent | TelegramTemporaryThreadEntry>(authority: TelegramWorkspaceRestoreAuthority,
3306
+ change: (file: TelegramWorkspaceRestoreSnapshot, executor: TelegramWorkspaceRestoreExecutor, operatorUserId: number) => T | undefined,
3307
+ ): T | undefined => {
3308
+ if (!authority.isCurrent()) return undefined;
3309
+ const executor = structuredClone(authority.executor);
3310
+ const operator = authority.operatorUserId;
3311
+ if (!isTelegramWorkspaceRestoreExecutor(executor) || !restoreInteger(operator)) return undefined;
3312
+ const current = (): boolean => authority.isCurrent() && authority.operatorUserId === operator && isDeepStrictEqual(authority.executor, executor);
3313
+ const before = storage.read();
3314
+ const file = structuredClone(before);
3315
+ const operation = change(file, executor, operator);
3316
+ if (!operation || !current()) return undefined;
3317
+ if (isDeepStrictEqual(file, before)) return structuredClone(operation);
3318
+ if (file.revision === Number.MAX_SAFE_INTEGER) throw new Error("Workspace Restore revision exhausted.");
3319
+ file.revision += 1;
3320
+ return storage.update(before, file, current) ? structuredClone(operation) : undefined;
3321
+ };
3322
+ const advance = (expected: TelegramWorkspaceRestoreIntent, authority: TelegramWorkspaceRestoreAuthority,
3323
+ change: (operation: TelegramWorkspaceRestoreIntent) => boolean | "unchanged", adopt = false): TelegramWorkspaceRestoreIntent | undefined =>
3324
+ mutate(authority, (file, executor, operator) => {
3325
+ const operation = file.operations.find(candidate => candidate.request.operationId === expected.request.operationId);
3326
+ if (!operation || !isDeepStrictEqual(operation, expected) || operation.operatorUserId !== operator ||
3327
+ (!adopt && !isDeepStrictEqual(operation.executor, executor))) return undefined;
3328
+ const changed = change(operation);
3329
+ if (!changed) return undefined;
3330
+ if (changed === "unchanged") return operation;
3331
+ if (operation.revision === Number.MAX_SAFE_INTEGER) throw new Error("Workspace Restore operation revision exhausted.");
3332
+ const at = now();
3333
+ if (!restoreInteger(at)) throw new Error("Invalid Workspace Restore clock.");
3334
+ operation.executor = executor;
3335
+ operation.revision += 1;
3336
+ operation.updatedAtMs = Math.max(at, operation.updatedAtMs);
3337
+ return operation;
3338
+ });
3339
+ const advanceTemporary = (expected: TelegramTemporaryThreadEntry, authority: TelegramWorkspaceRestoreAuthority,
3340
+ change: (entry: TelegramTemporaryThreadEntry, file: TelegramWorkspaceRestoreSnapshot, executor: TelegramWorkspaceRestoreExecutor) => boolean | "unchanged",
3341
+ adopt = false): TelegramTemporaryThreadEntry | undefined =>
3342
+ mutate<TelegramTemporaryThreadEntry>(authority, (file, executor, operator) => {
3343
+ const entry = file.temporaryThreads?.find(value => isDeepStrictEqual(value, expected));
3344
+ if (!entry || entry.operatorUserId !== operator || (!adopt && !isDeepStrictEqual(entry.executor, executor))) return undefined;
3345
+ const changed = change(entry, file, executor);
3346
+ if (!changed) return undefined;
3347
+ if (changed === "unchanged") return entry;
3348
+ if (entry.revision === Number.MAX_SAFE_INTEGER) throw new Error("Workspace Restore operation revision exhausted.");
3349
+ const at = now();
3350
+ if (!restoreInteger(at)) throw new Error("Invalid Workspace Restore clock.");
3351
+ entry.executor = executor;
3352
+ entry.revision += 1;
3353
+ entry.updatedAtMs = Math.max(at, entry.updatedAtMs);
3354
+ return entry;
3355
+ });
3356
+ return {
3357
+ list: () => structuredClone(storage.read().operations),
3358
+ inspectTemporaryThreadTarget(expected, authority) {
3359
+ const executor = structuredClone(authority.executor), operator = authority.operatorUserId;
3360
+ const current = () => currentScope() && authority.isCurrent() && authority.operatorUserId === operator &&
3361
+ isDeepStrictEqual(authority.executor, executor);
3362
+ if (!isTelegramWorkspaceRestoreExecutor(executor) || !restoreInteger(operator) || !current()) return undefined;
3363
+ return withStoreTransaction(path, () => {
3364
+ if (!current()) return undefined;
3365
+ const before = read(), entry = before.state.temporaryThreads?.find(value => isDeepStrictEqual(value, expected));
3366
+ if (!entry || entry.operatorUserId !== operator || !current()) return undefined;
3367
+ const result = classifyTemporaryTarget(before, entry);
3368
+ return current() ? result : undefined;
3369
+ });
3370
+ },
3371
+ isTemporaryThreadCleanupCurrent(expected, authority) {
3372
+ const executor = structuredClone(authority.executor), operator = authority.operatorUserId;
3373
+ const current = () => currentScope() && authority.isCurrent() && authority.operatorUserId === operator &&
3374
+ isDeepStrictEqual(authority.executor, executor);
3375
+ if (!expected.cleanupIssued || expected.operatorUserId !== operator || !isDeepStrictEqual(expected.executor, executor) ||
3376
+ !isTelegramWorkspaceRestoreExecutor(executor) || !restoreInteger(operator) || !current()) return false;
3377
+ return withStoreTransaction(path, () => {
3378
+ if (!current()) return false;
3379
+ const before = read(), entry = before.state.temporaryThreads?.find(value => isDeepStrictEqual(value, expected));
3380
+ return !!entry && inspectTemporaryOwnership(before, entry).kind === "temporary" && current();
3381
+ });
3382
+ },
3383
+ /** The first durable state already includes both relocation and exact original references. */
3384
+ async commit(requestInput, authority) {
3385
+ if (!authority.isCurrent()) return undefined;
3386
+ const request = structuredClone(requestInput), executor = structuredClone(authority.executor), operatorUserId = authority.operatorUserId;
3387
+ const current = () => authority.isCurrent() && authority.operatorUserId === operatorUserId && isDeepStrictEqual(authority.executor, executor);
3388
+ if (!current() || !isTelegramWorkspaceRestoreRequest(request) || !isTelegramWorkspaceRestoreExecutor(executor) ||
3389
+ !restoreInteger(operatorUserId) || request.target.chatId !== operatorUserId) return undefined;
3390
+ const retained = (): TelegramWorkspaceRestoreIntent | undefined => {
3391
+ if (!current()) return undefined;
3392
+ const operation = storage.read().operations.find(value => value.request.operationId === request.operationId);
3393
+ return current() && operation?.phase === "relocated" && isDeepStrictEqual(operation.request, request) &&
3394
+ operation.operatorUserId === operatorUserId && isDeepStrictEqual(operation.executor, executor) ? operation : undefined;
3395
+ };
3396
+ const existing = retained();
3397
+ if (existing) return existing;
3398
+ await (dirty ? undefined : loadFromDisk());
3399
+ if (!current()) return undefined;
3400
+ const at = now();
3401
+ if (!restoreInteger(at)) throw new Error("Invalid Workspace Restore clock.");
3402
+ const intent: TelegramWorkspaceRestoreIntent = { request, executor, operatorUserId, revision: 0,
3403
+ createdAtMs: at, updatedAtMs: at, committedAtMs: at, phase: "relocated" };
3404
+ let failure: { error: unknown } | undefined;
3405
+ try { await storage.relocate(intent, current); } catch (error) { failure = { error }; }
3406
+ if (!current()) return undefined;
3407
+ // A lost rename reply is reconciled from the complete operation, never target equality.
3408
+ const committed = retained();
3409
+ if (!committed && failure) throw failure.error;
3410
+ return committed;
3411
+ },
3412
+ adopt(expected, authority) {
3413
+ return advance(expected, authority, () => !isDeepStrictEqual(expected.executor, authority.executor), true);
3414
+ },
3415
+ /** Caller validates the live recipient under admission. Only this fresh result grants one RPC issuance. */
3416
+ issueRecipient(expected, recipient, authority) {
3417
+ const intent = advance(expected, authority, operation => {
3418
+ if (operation.phase !== "relocated" || !isTelegramWorkspaceRestoreRecipient(recipient) || recipient.sessionId !== operation.request.binding.sessionId) return false;
3419
+ operation.phase = "recipient-issued";
3420
+ operation.recipient = structuredClone(recipient);
3421
+ return true;
3422
+ });
3423
+ return intent ? { issued: true, intent } : undefined;
3424
+ },
3425
+ /** One source-dispatch grant; uncertainty never resets it. Caller retains the original carriers. */
3426
+ issueRouting(expected, authority) {
3427
+ const intent = advance(expected, authority, operation => {
3428
+ if (operation.phase !== "ready" || operation.routing) return false;
3429
+ operation.routing = { settlements: [] };
3430
+ return true;
3431
+ });
3432
+ return intent ? { issued: true, intent } : undefined;
3433
+ },
3434
+ /** Caller owns the positive result and exact source hash; this grants neither source removal nor cleanup. */
3435
+ recordSourceAcceptance(expected, evidenceInput, authority) {
3436
+ if (!authority.isCurrent()) return undefined;
3437
+ const evidence = structuredClone(evidenceInput);
3438
+ return advance(expected, authority, operation => {
3439
+ if (!operation.routing || !isWorkspaceRestoreSourceAcceptance(evidence, operation)) return false;
3440
+ const existing = operation.routing.acceptances?.find(value => value.updateId === evidence.updateId);
3441
+ if (existing) return isDeepStrictEqual(existing, evidence) ? "unchanged" : false;
3442
+ if (operation.routing.cleanup !== undefined ||
3443
+ operation.routing.settlements.some(value => value.updateIds.includes(evidence.updateId)) ||
3444
+ !isDeepStrictEqual(evidence.recipient, operation.readyRecipient ?? operation.recipient)) return false;
3445
+ const acceptances = [...operation.routing.acceptances ?? [], evidence].sort((a, b) => a.updateId - b.updateId);
3446
+ if (!workspaceRestoreAcceptancesConsistent(acceptances)) return false;
3447
+ operation.routing.acceptances = acceptances;
3448
+ return true;
3449
+ });
3450
+ },
3451
+ /** Queue admission is nonterminal; only its exact journal-owner completion ACK may upgrade it. */
3452
+ recordSourceSettlement(expected, evidenceInput, authority) {
3453
+ const evidence = structuredClone(evidenceInput);
3454
+ return advance(expected, authority, operation => {
3455
+ if (!operation.routing || !isTelegramWorkspaceRestoreSettlement(evidence, operation.request.source) ||
3456
+ !workspaceRestoreSettlementMatchesAcceptance(evidence, operation.routing.acceptances ?? [])) return false;
3457
+ const overlaps = operation.routing.settlements.filter(value => value.updateIds.some(id => evidence.updateIds.includes(id)));
3458
+ if (overlaps.some(value => evidence.kind !== "queue-completed" || value.kind !== "queued" ||
3459
+ value.receiptId !== evidence.receiptId || value.queueKind !== evidence.queueKind)) return false;
3460
+ operation.routing.settlements = operation.routing.settlements.flatMap(value => {
3461
+ const updateIds = value.updateIds.filter(id => !evidence.updateIds.includes(id));
3462
+ return updateIds.length ? [{ ...value, updateIds }] : [];
3463
+ });
3464
+ operation.routing.settlements.push(evidence);
3465
+ return true;
3466
+ });
3467
+ },
3468
+ /** Existing cleanup owner retains deletion authority; this merely fences one invocation. */
3469
+ issueCleanup(expected, authority) {
3470
+ const intent = advance(expected, authority, operation => {
3471
+ if (!operation.routing || !workspaceRestoreSourcesSettled(operation) || operation.routing.cleanup !== undefined) return false;
3472
+ operation.routing.cleanup = "issued";
3473
+ return true;
3474
+ });
3475
+ return intent ? { issued: true, intent } : undefined;
3476
+ },
3477
+ recordCleanup(expected, result, authority) {
3478
+ return advance(expected, authority, operation => {
3479
+ if (!operation.routing || !workspaceRestoreSourcesSettled(operation) || !isDeepStrictEqual(result.target, operation.request.binding.target) ||
3480
+ (result.kind === "completed" ? operation.routing.cleanup !== "issued" :
3481
+ result.kind !== "not-issued" || operation.routing.cleanup !== undefined)) return false;
3482
+ operation.routing.cleanup = result.kind;
3483
+ return true;
3484
+ });
3485
+ },
3486
+ /** Exact terminal CAS releases Restore protection only; it cannot settle or cancel recipient queue work. */
3487
+ retire(expected, authority) {
3488
+ return mutate(authority, (file, executor, operator) => {
3489
+ const index = file.operations.findIndex(value => value.request.operationId === expected.request.operationId);
3490
+ const operation = file.operations[index];
3491
+ if (!operation || !isDeepStrictEqual(operation, expected) || operation.operatorUserId !== operator ||
3492
+ !isDeepStrictEqual(operation.executor, executor) || !workspaceRestoreSourcesSettled(operation) ||
3493
+ !["completed", "not-issued"].includes(operation.routing?.cleanup ?? "")) return undefined;
3494
+ file.operations.splice(index, 1);
3495
+ return operation;
3496
+ });
3497
+ },
3498
+ listTemporaryThreads: () => structuredClone(storage.read().temporaryThreads ?? []),
3499
+ reserveTemporaryThread(sourceInput, token, authority) {
3500
+ const source = structuredClone(sourceInput);
3501
+ let reserved = false;
3502
+ const entry = mutate<TelegramTemporaryThreadEntry>(authority, (file, executor, operator) => {
3503
+ const entries = file.temporaryThreads ?? [];
3504
+ const existing = entries.find(value => value.source.journalBindingKey === source.journalBindingKey &&
3505
+ value.source.updateId === source.updateId);
3506
+ // A retained entry proves an earlier attempt; it is never a license for another creation.
3507
+ if (existing) return existing.operatorUserId === operator ? existing : undefined;
3508
+ const at = now();
3509
+ if (!restoreInteger(at)) throw new Error("Invalid Workspace Restore clock.");
3510
+ const next: TelegramTemporaryThreadEntry = { source,
3511
+ inputs: [{ journalBindingKey: source.journalBindingKey, updateIds: [source.updateId] }],
3512
+ operatorUserId: operator, executor, token, phase: "creating", forwardProtocol: "one-shot-v1",
3513
+ revision: 0, createdAtMs: at, updatedAtMs: at };
3514
+ if (!isTemporaryThreadEntry(next) || entries.some(value => value.token === token ||
3515
+ getTelegramTemporaryThreadInputs(value).some(input => input.journalBindingKey === source.journalBindingKey &&
3516
+ input.updateIds.includes(source.updateId)))) return undefined;
3517
+ if (entries.length >= TEMPORARY_THREAD_CAPACITY) throw new Error("Temporary Thread capacity reached.");
3518
+ file.temporaryThreads = [...entries, next];
3519
+ reserved = true;
3520
+ return next;
3521
+ });
3522
+ return entry ? { reserved, entry } : undefined;
3523
+ },
3524
+ registerImplicitTemporaryThread(inputValue, targetInput, token, authority) {
3525
+ const input = structuredClone(inputValue), target = { chatId: targetInput.chatId, threadId: targetInput.threadId };
3526
+ if (!isTemporaryThreadInput(input) || input.updateIds.length !== 1 || !Number.isSafeInteger(target.threadId) || target.threadId <= 0) return undefined;
3527
+ return mutate<TelegramTemporaryThreadEntry>(authority, (file, executor, operator) => {
3528
+ const entries = file.temporaryThreads ?? [];
3529
+ if (target.chatId !== operator || entries.some(value => value.token === token ||
3530
+ (value.target && targetMatches(value.target, target)) || getTelegramTemporaryThreadInputs(value).some(other =>
3531
+ other.journalBindingKey === input.journalBindingKey && other.updateIds.some(id => input.updateIds.includes(id))))) return undefined;
3532
+ const at = now();
3533
+ if (!restoreInteger(at)) throw new Error("Invalid Workspace Restore clock.");
3534
+ const entry: TelegramTemporaryThreadEntry = { source: { journalBindingKey: input.journalBindingKey, updateId: input.updateIds[0]! },
3535
+ inputs: [input], target, operatorUserId: operator, executor, token, phase: "created", forwardProtocol: "one-shot-v1",
3536
+ revision: 0, createdAtMs: at, updatedAtMs: at };
3537
+ if (!isTemporaryThreadEntry(entry)) return undefined;
3538
+ if (entries.length >= TEMPORARY_THREAD_CAPACITY) throw new Error("Temporary Thread capacity reached.");
3539
+ file.temporaryThreads = [...entries, entry];
3540
+ return entry;
3541
+ });
3542
+ },
3543
+ acknowledgeTemporaryThread(expected, targetInput, authority) {
3544
+ const target = { chatId: targetInput.chatId, threadId: targetInput.threadId };
3545
+ return advanceTemporary(expected, authority, (entry, file) => {
3546
+ if (entry.phase !== "creating" || target.chatId !== entry.operatorUserId || !Number.isSafeInteger(target.threadId) ||
3547
+ target.threadId <= 0 || file.temporaryThreads!.some(value => !!value.target && targetMatches(value.target, target)) ||
3548
+ file.operations.some(({ request }) => targetMatches(request.target, target) || targetMatches(request.binding.target, target))) return false;
3549
+ entry.phase = "created";
3550
+ entry.target = target;
3551
+ return true;
3552
+ });
3553
+ },
3554
+ adoptTemporaryThread(expected, authority) {
3555
+ return advanceTemporary(expected, authority, (entry, _file, executor) => !isDeepStrictEqual(entry.executor, executor), true);
3556
+ },
3557
+ recordTemporaryThreadInput(expected, inputValue, authority) {
3558
+ const input = structuredClone(inputValue);
3559
+ if (!isTemporaryThreadInput(input)) return undefined;
3560
+ return advanceTemporary(expected, authority, (entry, file) => {
3561
+ if (entry.phase !== "created" || input.journalBindingKey !== entry.source.journalBindingKey ||
3562
+ file.operations.some(({ request }) => targetMatches(request.target, entry.target!))) return false;
3563
+ const inputs = getTelegramTemporaryThreadInputs(entry);
3564
+ if (inputs.some(value => isDeepStrictEqual(value, input))) return "unchanged";
3565
+ if (entry.cleanupIssued || inputs.some(value => value.updateIds.some(id => input.updateIds.includes(id))) ||
3566
+ file.temporaryThreads!.some(value => value !== entry && getTelegramTemporaryThreadInputs(value).some(other =>
3567
+ other.journalBindingKey === input.journalBindingKey && other.updateIds.some(id => input.updateIds.includes(id))))) return false;
3568
+ if (inputs.length >= TEMPORARY_THREAD_INPUT_CAPACITY) throw new Error("Temporary Thread input capacity reached.");
3569
+ entry.inputs = [...inputs, input];
3570
+ return true;
3571
+ });
3572
+ },
3573
+ recordTemporaryThreadInputCancellation(expected, inputValue, authority, inspect) {
3574
+ const input = structuredClone(inputValue);
3575
+ if (!isTemporaryThreadInput(input) || typeof inspect !== "function") return undefined;
3576
+ const operatorUserId = authority.operatorUserId, executor = structuredClone(authority.executor);
3577
+ const owned = (): boolean => authority.isCurrent() && authority.operatorUserId === operatorUserId &&
3578
+ isDeepStrictEqual(authority.executor, executor);
3579
+ // Every publication fence observes retained proof again; neither cached cancellation nor absence suffices.
3580
+ const current = (): boolean => owned() && input.updateIds.every(updateId => {
3581
+ const evidence = inspect(updateId);
3582
+ return evidence?.journalBindingKey === input.journalBindingKey && evidence.updateId === updateId &&
3583
+ evidence.operatorAuthorityId === `telegram-owner:${operatorUserId}`;
3584
+ }) && owned();
3585
+ const recorded = advanceTemporary(expected, { ...authority, isCurrent: current }, (entry, file) => {
3586
+ if (entry.phase !== "created" || !getTelegramTemporaryThreadInputs(entry).some(candidate => isDeepStrictEqual(candidate, input)) ||
3587
+ file.operations.some(({ request }) => request.source.journalBindingKey === input.journalBindingKey &&
3588
+ request.source.updateIds.some(id => input.updateIds.includes(id)))) return false;
3589
+ const cancelled = entry.cancelledInputs ?? [];
3590
+ if (cancelled.some(candidate => isDeepStrictEqual(candidate, input))) return "unchanged";
3591
+ if (entry.completedInputs?.some(candidate => isDeepStrictEqual(candidate, input)) ||
3592
+ entry.forwardedInputs?.some(candidate => isDeepStrictEqual(candidate, input))) return false;
3593
+ entry.cancelledInputs = [...cancelled, input];
3594
+ return true;
3595
+ });
3596
+ return recorded && current() ? recorded : undefined;
3597
+ },
3598
+ recordTemporaryThreadForwardIssued(expected, inputValue, authority) {
3599
+ const input = structuredClone(inputValue);
3600
+ if (!isTemporaryThreadInput(input)) return undefined;
3601
+ return advanceTemporary(expected, authority, (entry, file) => {
3602
+ if (entry.phase !== "created" || !getTelegramTemporaryThreadInputs(entry).some(candidate => isDeepStrictEqual(candidate, input)) ||
3603
+ [...(entry.cancelledInputs ?? []), ...(entry.completedInputs ?? []), ...(entry.forwardedInputs ?? [])]
3604
+ .some(candidate => isDeepStrictEqual(candidate, input)) ||
3605
+ file.operations.some(({ request }) => request.source.journalBindingKey === input.journalBindingKey &&
3606
+ request.source.updateIds.some(id => input.updateIds.includes(id)))) return false;
3607
+ entry.forwardedInputs = [...(entry.forwardedInputs ?? []), input];
3608
+ return true;
3609
+ });
3610
+ },
3611
+ recordTemporaryThreadInputCompletion(expected, inputValue, authority) {
3612
+ const input = structuredClone(inputValue);
3613
+ if (!isTemporaryThreadInput(input)) return undefined;
3614
+ return advanceTemporary(expected, authority, (entry, file) => {
3615
+ if (entry.phase !== "created" || !getTelegramTemporaryThreadInputs(entry).some(candidate => isDeepStrictEqual(candidate, input)) ||
3616
+ entry.cancelledInputs?.some(candidate => isDeepStrictEqual(candidate, input)) ||
3617
+ file.operations.some(({ request }) => request.source.journalBindingKey === input.journalBindingKey &&
3618
+ request.source.updateIds.some(id => input.updateIds.includes(id)))) return false;
3619
+ const completed = entry.completedInputs ?? [];
3620
+ if (completed.some(candidate => isDeepStrictEqual(candidate, input))) return "unchanged";
3621
+ entry.completedInputs = [...completed, input];
3622
+ return true;
3623
+ });
3624
+ },
3625
+ issueTemporaryThreadCleanup(expected, authority) {
3626
+ const entry = advanceTemporary(expected, authority, value => {
3627
+ if (value.phase !== "created" || value.cleanupIssued || !isTelegramTemporaryThreadFullyResolved(value)) return false;
3628
+ value.cleanupIssued = true;
3629
+ return true;
3630
+ });
3631
+ return entry ? { issued: true, entry } : undefined;
3632
+ },
3633
+ retireTemporaryThread(expected, authority, completed) {
3634
+ return mutate<TelegramTemporaryThreadEntry>(authority, (file, executor, operator) => {
3635
+ const entries = file.temporaryThreads ?? [];
3636
+ const index = entries.findIndex(value => isDeepStrictEqual(value, expected));
3637
+ const entry = entries[index];
3638
+ if (!entry || entry.operatorUserId !== operator || !isDeepStrictEqual(entry.executor, executor) ||
3639
+ (getTelegramTemporaryThreadInputs(entry).length > 1 && !isTelegramTemporaryThreadFullyResolved(entry) &&
3640
+ !isTemporaryThreadReleasedByCompletion(entry, completed))) return undefined;
3641
+ const remaining = entries.filter((_value, position) => position !== index);
3642
+ if (remaining.length) file.temporaryThreads = remaining;
3643
+ else delete file.temporaryThreads;
3644
+ return entry;
3645
+ });
3646
+ },
3647
+ forgetPreviousWorld(authority) {
3648
+ if (!authority.isCurrent()) return undefined;
3649
+ const executor = structuredClone(authority.executor), operator = authority.operatorUserId;
3650
+ if (!isTelegramWorkspaceRestoreExecutor(executor) || !restoreInteger(operator)) return undefined;
3651
+ const current = (): boolean => authority.isCurrent() && authority.operatorUserId === operator && isDeepStrictEqual(authority.executor, executor);
3652
+ const previous = (value: { operatorUserId: number; executor: TelegramWorkspaceRestoreExecutor }) =>
3653
+ value.operatorUserId === operator && value.executor.instanceId !== executor.instanceId;
3654
+ const before = storage.read(), file = structuredClone(before);
3655
+ const operations = file.operations.filter(previous), temporaryThreads = (file.temporaryThreads ?? []).filter(previous);
3656
+ if (!current()) return undefined;
3657
+ if (!operations.length && !temporaryThreads.length) return { operations, temporaryThreads };
3658
+ file.operations = file.operations.filter(value => !previous(value));
3659
+ const remaining = (file.temporaryThreads ?? []).filter(value => !previous(value));
3660
+ if (remaining.length) file.temporaryThreads = remaining;
3661
+ else delete file.temporaryThreads;
3662
+ if (file.revision === Number.MAX_SAFE_INTEGER) throw new Error("Workspace Restore revision exhausted.");
3663
+ file.revision += 1;
3664
+ return storage.update(before, file, current) ? structuredClone({ operations, temporaryThreads }) : undefined;
3665
+ },
3666
+ /** Ends protection without cleanup: the old Thread is kept, and no source was ever dispatched. */
3667
+ retireAbandoned(expected, abandonedUpdateIds, authority) {
3668
+ const abandoned = [...new Set(abandonedUpdateIds)].sort((left, right) => left - right);
3669
+ return mutate(authority, (file, executor, operator) => {
3670
+ const index = file.operations.findIndex(value => value.request.operationId === expected.request.operationId);
3671
+ const operation = file.operations[index];
3672
+ if (!operation || !isDeepStrictEqual(operation, expected) || operation.operatorUserId !== operator ||
3673
+ !isDeepStrictEqual(operation.executor, executor) || operation.phase !== "ready" || operation.routing !== undefined ||
3674
+ !isDeepStrictEqual(abandoned, operation.request.source.updateIds)) return undefined;
3675
+ file.operations.splice(index, 1);
3676
+ return operation;
3677
+ });
3678
+ },
3679
+ /** Caller proves current canonical ownership and authenticates a read-only observation, including successors. */
3680
+ confirmInspectedReady(expected, observed, authority) {
3681
+ return advance(expected, authority, operation => {
3682
+ if ((operation.phase !== "recipient-issued" && operation.phase !== "ready") || !isTelegramWorkspaceRestoreRecipient(observed) ||
3683
+ observed.sessionId !== operation.request.binding.sessionId) return false;
3684
+ operation.phase = "ready";
3685
+ operation.readyRecipient = structuredClone(observed);
3686
+ return true;
3687
+ });
3688
+ },
3689
+ /** Caller authenticates the exact-generation ACK; stored metadata alone is never readiness proof. */
3690
+ confirmReady(expected, acknowledged, authority) {
3691
+ return advance(expected, authority, operation => {
3692
+ if (operation.phase !== "recipient-issued" || !isDeepStrictEqual(operation.recipient, acknowledged)) return false;
3693
+ operation.phase = "ready";
3694
+ return true;
3695
+ });
3696
+ },
3697
+ };
3698
+ },
2346
3699
  list() {
2347
3700
  return Array.from(records.values()).map(cloneRecord);
2348
3701
  },
@@ -2384,6 +3737,10 @@ export function createTelegramTopicTargetStore(
2384
3737
  }));
2385
3738
  },
2386
3739
  reserveThread(reservation) {
3740
+ if (workspaceRestore?.operations.some(({ request }) => conflictsWithWorkspaceRestoreProvision(request, reservation)) ||
3741
+ conflictsWithTemporaryThread(workspaceRestore, reservation.target)) {
3742
+ throw new Error("Protected Workspace Restore provisioning conflict.");
3743
+ }
2387
3744
  const next = { ...reservation };
2388
3745
  reservations = reservations.filter(
2389
3746
  (existing) =>
@@ -2394,6 +3751,10 @@ export function createTelegramTopicTargetStore(
2394
3751
  markDirty();
2395
3752
  },
2396
3753
  upsertPendingProvision(provision) {
3754
+ if (workspaceRestore?.operations.some(({ request }) => conflictsWithWorkspaceRestoreProvision(request, provision)) ||
3755
+ conflictsWithTemporaryThread(workspaceRestore, provision.target)) {
3756
+ throw new Error("Protected Workspace Restore provisioning conflict.");
3757
+ }
2397
3758
  const next = {
2398
3759
  ...provision,
2399
3760
  ...(provision.target ? { target: { ...provision.target } } : {}),
@@ -2408,9 +3769,9 @@ export function createTelegramTopicTargetStore(
2408
3769
  const path = getPath();
2409
3770
  const recoveryPath = getRecoveryPath(path);
2410
3771
  await mkdir(dirname(recoveryPath), { recursive: true });
2411
- withTelegramFileTransaction(`${recoveryPath}.transaction`, () => {
2412
- const recoveries = readProvisionRecoveries(path);
2413
- recoveries[provision.id] = {
3772
+ withStoreTransaction(path, () => {
3773
+ const recoveries = readProvisionRecoveries(path, true);
3774
+ const recovery = {
2414
3775
  instanceId: provision.instanceId,
2415
3776
  ...(provision.profileKey ? { profileKey: provision.profileKey } : {}),
2416
3777
  ...(provision.leaderEpoch !== undefined
@@ -2418,6 +3779,11 @@ export function createTelegramTopicTargetStore(
2418
3779
  : {}),
2419
3780
  target: { ...target },
2420
3781
  };
3782
+ if (Object.hasOwn(recoveries, provision.id)) {
3783
+ if (!isDeepStrictEqual(recoveries[provision.id], recovery)) throw new Error("Conflicting Workspace provisioning recovery evidence.");
3784
+ return;
3785
+ }
3786
+ recoveries[provision.id] = recovery;
2421
3787
  const tempPath = `${recoveryPath}.${process.pid}.${randomUUID()}.tmp`;
2422
3788
  writeFileSync(tempPath, `${JSON.stringify(recoveries, null, 2)}\n`, {
2423
3789
  encoding: "utf8",
@@ -2472,9 +3838,29 @@ export function createTelegramTopicTargetStore(
2472
3838
  markDirty();
2473
3839
  },
2474
3840
  setStatusSnapshot(snapshot) {
2475
- if (!loadedPath) loadedPath = getPath();
3841
+ if (!loadedPath) { loadedPath = getPath(); loadedProfile = activeProfile(); }
2476
3842
  statusSnapshot = { ...snapshot };
2477
- statusRevision += 1;
3843
+ },
3844
+ persistStatus() {
3845
+ if (runtimeProjection) return runtimeProjection.persist({ runtime: statusSnapshot.runtime ?? {},
3846
+ liveRoster: statusSnapshot.liveRoster ?? {}, diagnostics: statusSnapshot.diagnostics ?? {} }).then(() => undefined);
3847
+ const write = statusQueue.then(async () => {
3848
+ if (options.canPersist && !options.canPersist()) return;
3849
+ const body = { version: 1, source: "snapshot", ...statusSnapshot };
3850
+ // Normalize to wire JSON; object key order and omitted undefined are not changes.
3851
+ const semantic = JSON.parse(JSON.stringify(body)) as Record<string, unknown>;
3852
+ const statusPath = getStatusPath();
3853
+ if (isDeepStrictEqual(semantic, lastStatusSemantic) && statusPath === lastStatusPath) return;
3854
+ await mkdir(dirname(statusPath), { recursive: true });
3855
+ const tempPath = `${statusPath}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
3856
+ await writeFile(tempPath, `${JSON.stringify({ ...body, writtenAtMs: (options.getNowMs ?? Date.now)() }, null, 2)}\n`,
3857
+ { encoding: "utf8", flag: "wx", mode: 0o600 });
3858
+ try { renameSync(tempPath, statusPath); chmodSync(statusPath, 0o600); }
3859
+ catch (error) { await unlink(tempPath).catch(() => undefined); throw error; }
3860
+ lastStatusSemantic = semantic; lastStatusPath = statusPath;
3861
+ });
3862
+ statusQueue = write.then(() => undefined, () => undefined);
3863
+ return write;
2478
3864
  },
2479
3865
  getByProfileKey(profileKey) {
2480
3866
  const ownerKey = getTelegramThreadOwnerKey(
@@ -2547,7 +3933,7 @@ export function createTelegramTopicTargetStore(
2547
3933
  listWorkspaceRetirementIntents() {
2548
3934
  return workspaceRetirements.map(cloneWorkspaceRetirementIntent);
2549
3935
  },
2550
- commitWorkspaceJournalEvidence(expected, journalBindingKeys, complete) {
3936
+ commitWorkspaceJournalEvidence(expected, journalBindingKeys, complete, journalSources) {
2551
3937
  if (workspaceRetirementCommitInFlight || hasWorkspaceRetirementConflict(expected)) {
2552
3938
  return undefined;
2553
3939
  }
@@ -2558,19 +3944,34 @@ export function createTelegramTopicTargetStore(
2558
3944
  typeof bindingKey === "string" && bindingKey.length > 0 && bindingKey.length <= 512,
2559
3945
  )) return undefined;
2560
3946
  const keys = Array.from(new Set(journalBindingKeys));
3947
+ const sources = journalSources === undefined ? current.journalSources ?? [] : normalizeWorkspaceJournalSources(journalSources);
3948
+ if (!sources || sources.some(source => !(current.journalSources ?? []).some(retained => isDeepStrictEqual(retained, source)))) return undefined;
2561
3949
  if ((current.journalBindingsComplete === true) === complete &&
2562
- isDeepStrictEqual(current.journalBindingKeys ?? [], keys)) {
3950
+ isDeepStrictEqual(current.journalBindingKeys ?? [], keys) && isDeepStrictEqual(current.journalSources ?? [], sources)) {
2563
3951
  return cloneWorkspaceBinding(current);
2564
3952
  }
2565
3953
  const next = { ...current, updatedAtMs: getNowMs() };
2566
- if (keys.length) next.journalBindingKeys = keys;
3954
+ // A complete empty set stays explicit so persisted completeness survives a lossless reload.
3955
+ if (keys.length || complete) next.journalBindingKeys = keys;
2567
3956
  else delete next.journalBindingKeys;
3957
+ if (sources.length) next.journalSources = sources.map(source => ({ ...source }));
3958
+ else delete next.journalSources;
2568
3959
  if (complete) next.journalBindingsComplete = true;
2569
3960
  else delete next.journalBindingsComplete;
2570
3961
  workspaceBindings.set(key, next);
2571
3962
  markDirty();
2572
3963
  return cloneWorkspaceBinding(next);
2573
3964
  },
3965
+ async persistWorkspaceJournalEvidence(expected, isCurrent) {
3966
+ const path = getPath();
3967
+ const frameCurrent = () => getPath() === path && isCurrent() && isDeepStrictEqual(
3968
+ workspaceBindings.get(getWorkspaceBindingMapKey(expected)), expected,
3969
+ );
3970
+ if (!frameCurrent()) return false;
3971
+ const current = () => frameCurrent() && options.canPersist?.() !== false;
3972
+ const published = await persistSnapshot(undefined, current);
3973
+ return published && current();
3974
+ },
2574
3975
  upsertWorkspaceRetirementIntent(intent) {
2575
3976
  const next = normalizeWorkspaceRetirementIntent(intent);
2576
3977
  if (!next) return false;
@@ -3188,6 +4589,17 @@ export function createTelegramTopicTargetStore(
3188
4589
  existing.bindingKey !== next.bindingKey &&
3189
4590
  targetMatches(existing.target, next.target),
3190
4591
  );
4592
+ const retainedSources = [
4593
+ ...(workspaceBindings.get(nextMapKey)?.journalSources ?? []),
4594
+ ...(replacedTargetBinding?.journalSources ?? []),
4595
+ ...(next.journalSources ?? []),
4596
+ ];
4597
+ if (retainedSources.length) {
4598
+ const uniqueSources = Array.from(new Map(retainedSources.map(source => [JSON.stringify(source), source])).values());
4599
+ const journalSources = normalizeWorkspaceJournalSources(uniqueSources);
4600
+ if (!journalSources) return undefined;
4601
+ next.journalSources = journalSources;
4602
+ }
3191
4603
  if (
3192
4604
  claimInstanceId && claim?.instanceId === claimInstanceId &&
3193
4605
  replacedTargetBinding?.slot
@@ -3233,7 +4645,7 @@ export function createTelegramTopicTargetStore(
3233
4645
  ...(previous.journalBindingKeys ?? []),
3234
4646
  ...(next.journalBindingKeys ?? []),
3235
4647
  ]));
3236
- if (journalBindingKeys.length) next.journalBindingKeys = journalBindingKeys;
4648
+ if (journalBindingKeys.length || previous.journalBindingsComplete) next.journalBindingKeys = journalBindingKeys;
3237
4649
  else delete next.journalBindingKeys;
3238
4650
  if (previous.journalBindingsComplete) next.journalBindingsComplete = true;
3239
4651
  else delete next.journalBindingsComplete;
@@ -3568,64 +4980,7 @@ function isTelegramTopicTargetSlotOccupied(
3568
4980
  return false;
3569
4981
  }
3570
4982
 
3571
- export function normalizeTelegramTopicTargetThreadName(
3572
- threadName: string,
3573
- ): string {
3574
- return threadName.replace(/\s+/g, " ").trim().slice(0, 96);
3575
- }
3576
-
3577
- function getGraphemeSegments(value: string): string[] {
3578
- const segmenter = (
3579
- Intl as unknown as {
3580
- Segmenter?: new (
3581
- locale?: string,
3582
- options?: { granularity: "grapheme" },
3583
- ) => { segment(input: string): Iterable<{ segment: string }> };
3584
- }
3585
- ).Segmenter;
3586
- if (!segmenter) return Array.from(value);
3587
- return Array.from(
3588
- new segmenter(undefined, { granularity: "grapheme" }).segment(value),
3589
- (part) => part.segment,
3590
- );
3591
- }
3592
-
3593
- export function getTelegramTopicIdentityName(threadName: string): string {
3594
- return getGraphemeSegments(normalizeTelegramTopicTargetThreadName(threadName))
3595
- .join("")
3596
- .trim();
3597
- }
3598
-
3599
- const TELEGRAM_THREAD_NAME_PALETTE: Record<string, readonly string[]> = {
3600
- A: ["Atlas", "Aster", "Aurora", "Anchor", "Ashen"],
3601
- B: ["Beacon", "Briar", "Boreal", "Birch", "Bison"],
3602
- C: ["Cedar", "Comet", "Cipher", "Coral", "Cinder"],
3603
- D: ["Delta", "Dawn", "Drift", "Dune", "Dagger"],
3604
- E: ["Ember", "Echo", "Eagle", "Eden", "Elder"],
3605
- F: ["Falcon", "Fjord", "Flint", "Forest", "Fable"],
3606
- G: ["Grove", "Glade", "Glyph", "Garnet", "Gale"],
3607
- H: ["Harbor", "Hawk", "Hazel", "Helix", "Haven"],
3608
- I: ["Iris", "Ivory", "Iron", "Isle", "Idea"],
3609
- J: ["Jade", "Juno", "Jolt", "Jewel", "Jasper"],
3610
- K: ["Kite", "Karma", "Kernel", "Kodiak", "Kelp"],
3611
- L: ["Lumen", "Laurel", "Lynx", "Lotus", "Lagoon"],
3612
- M: ["Maple", "Meteor", "Meadow", "Marble", "Moss"],
3613
- N: ["Nimbus", "Nova", "Nectar", "North", "Noble"],
3614
- O: ["Orion", "Onyx", "Opal", "Orbit", "Olive"],
3615
- P: ["Pine", "Pulse", "Praxis", "Pebble", "Prism"],
3616
- Q: ["Quartz", "Quill", "Quasar", "Quest", "Quiver"],
3617
- R: ["River", "Raven", "Rune", "Reef", "Ridge"],
3618
- S: ["Spruce", "Solar", "Signal", "Stone", "Sable"],
3619
- T: ["Timber", "Talon", "Terra", "Torch", "Tide"],
3620
- U: ["Umber", "Unity", "Ursa", "Uplink", "Ulmus"],
3621
- V: ["Violet", "Vector", "Vista", "Vale", "Vortex"],
3622
- W: ["Willow", "Warden", "Wave", "Winter", "Wisp"],
3623
- X: ["Xenon", "Xylem", "Xavier", "Xylo", "Xerus"],
3624
- Y: ["Yarrow", "Yonder", "Yukon", "Yale", "Yogi"],
3625
- Z: ["Zenith", "Zephyr", "Zircon", "Zebra", "Zion"],
3626
- };
3627
-
3628
- export function listOccupiedTelegramThreadIdentities(input: {
4983
+ function listOccupiedTelegramThreadIdentities(input: {
3629
4984
  records: readonly TelegramTopicTargetRecord[];
3630
4985
  workspaceBindings?: readonly TelegramWorkspaceThreadBinding[];
3631
4986
  pendingProvisions?: readonly TelegramThreadPendingProvision[];
@@ -3664,47 +5019,6 @@ export function listOccupiedTelegramThreadIdentities(input: {
3664
5019
  return Array.from(occupied);
3665
5020
  }
3666
5021
 
3667
- export function chooseTelegramThreadName(input: {
3668
- slot: string | undefined;
3669
- entropy?: number | string;
3670
- getRandom?: () => number;
3671
- occupied?: readonly string[];
3672
- }): string | undefined {
3673
- if (!input.slot || !/^[A-Z]$/.test(input.slot)) return undefined;
3674
- const names = TELEGRAM_THREAD_NAME_PALETTE[input.slot];
3675
- if (!names || names.length === 0) return undefined;
3676
- const occupied = new Set(
3677
- (input.occupied ?? []).map((name) => getTelegramTopicIdentityName(name)),
3678
- );
3679
- const start = input.getRandom
3680
- ? Math.max(
3681
- 0,
3682
- Math.min(
3683
- names.length - 1,
3684
- Math.floor(input.getRandom() * names.length),
3685
- ),
3686
- )
3687
- : getTelegramThreadNameEntropyIndex(input.entropy, names.length);
3688
- for (let offset = 0; offset < names.length; offset += 1) {
3689
- const name = names[(start + offset) % names.length];
3690
- if (!occupied.has(getTelegramTopicIdentityName(name))) return name;
3691
- }
3692
- for (const paletteSlot of "ABCDEFGHIJKLMNOPQRSTUVWXYZ") {
3693
- for (const name of TELEGRAM_THREAD_NAME_PALETTE[paletteSlot] ?? []) {
3694
- if (!occupied.has(getTelegramTopicIdentityName(name))) return name;
3695
- }
3696
- }
3697
- return undefined;
3698
- }
3699
-
3700
- function getTelegramThreadNameLeadingSlot(
3701
- threadName: string | undefined,
3702
- ): string | undefined {
3703
- if (!threadName) return undefined;
3704
- const first = getTelegramTopicIdentityName(threadName)[0];
3705
- return first && /^[A-Z]$/.test(first) ? first : undefined;
3706
- }
3707
-
3708
5022
  function getNextTelegramThreadNamePaletteSlot(
3709
5023
  records: readonly TelegramTopicTargetRecord[],
3710
5024
  fallbackSlot: string | undefined,
@@ -3723,95 +5037,6 @@ function getNextTelegramThreadNamePaletteSlot(
3723
5037
  return String.fromCharCode(code);
3724
5038
  }
3725
5039
 
3726
- function getTelegramThreadNameEntropyIndex(
3727
- entropy: number | string | undefined,
3728
- length: number,
3729
- ): number {
3730
- if (length <= 1) return 0;
3731
- if (typeof entropy === "number" && entropy < 1_000_000_000_000) return 0;
3732
- const value = entropy === undefined ? "0" : String(entropy);
3733
- let hash = 2166136261;
3734
- for (const char of value) {
3735
- hash ^= char.codePointAt(0) ?? 0;
3736
- hash = Math.imul(hash, 16777619) >>> 0;
3737
- }
3738
- return hash % length;
3739
- }
3740
-
3741
- export function getTelegramTopicThreadNameValidationError(
3742
- threadName: string,
3743
- _slot: string | undefined,
3744
- ): string | undefined {
3745
- const identity = getTelegramTopicIdentityName(threadName);
3746
- const reasons: string[] = [];
3747
- if (!identity) reasons.push("it is empty after trimming");
3748
- if (/\s/.test(identity)) reasons.push("it contains spaces");
3749
- if (/[^A-Za-z]/.test(identity)) {
3750
- reasons.push("it contains characters outside Latin A-Z letters");
3751
- }
3752
- if (!/^[A-Z]/.test(identity)) {
3753
- reasons.push("it does not start with an uppercase Latin letter");
3754
- }
3755
- const genericLabels = new Set(["telegram", "leader", "follower"]);
3756
- if (genericLabels.has(identity.toLowerCase())) {
3757
- reasons.push("it is a generic role label");
3758
- }
3759
- if (/^[A-Z]$/.test(identity)) reasons.push("it is only a bare slot letter");
3760
- if (reasons.length === 0) return undefined;
3761
- return `Invalid Telegram instance name: ${reasons.join("; ")}. Use exactly one capitalized Latin word with no spaces, punctuation, emoji, non-Latin letters, or digits; it must not be a generic role label or only a bare slot letter.`;
3762
- }
3763
-
3764
- export function getTelegramManualThreadDisplayNameValidationError(
3765
- threadName: string,
3766
- ): string | undefined {
3767
- const trimmed = threadName.trim();
3768
- const normalized = trimmed.replace(/\s+/g, " ");
3769
- const reasons: string[] = [];
3770
- if (!trimmed) reasons.push("it is empty after trimming");
3771
- if (trimmed && /[^\x20-\x7E]/.test(trimmed)) {
3772
- reasons.push("it contains characters outside printable ASCII");
3773
- }
3774
- if (normalized.length > 96) reasons.push("it is longer than 96 characters");
3775
- if (/^[A-Z]$/.test(normalized)) {
3776
- reasons.push("a bare slot letter is reserved for reset to automatic");
3777
- }
3778
- if (reasons.length === 0) return undefined;
3779
- return `Invalid Telegram Thread display name: ${reasons.join("; ")}. Use 1–96 printable ASCII characters.`;
3780
- }
3781
-
3782
- export function isTelegramTopicThreadNameValidForSlot(
3783
- threadName: string,
3784
- slot: string | undefined,
3785
- ): boolean {
3786
- return !getTelegramTopicThreadNameValidationError(threadName, slot);
3787
- }
3788
-
3789
- function applyTopicNameTemplate(
3790
- template: string,
3791
- request: TelegramTopicTargetProvisionRequest,
3792
- slot?: string,
3793
- ): string {
3794
- const threadName =
3795
- request.threadName?.replace(/\s+/g, " ").trim() || request.profileKey;
3796
- let result = template
3797
- .replaceAll("{threadName}", threadName)
3798
- .replaceAll("{profileKey}", request.profileKey)
3799
- .replaceAll("{instanceId}", request.instanceId);
3800
- if (slot) result = result.replaceAll("{slot}", slot);
3801
- return result;
3802
- }
3803
-
3804
- export function getTelegramTopicName(
3805
- request: TelegramTopicTargetProvisionRequest,
3806
- template = "{slot}",
3807
- slot?: string,
3808
- ): string {
3809
- const name = applyTopicNameTemplate(template, request, slot)
3810
- .replace(/\s+/g, " ")
3811
- .trim();
3812
- return (name || slot || "Pi").slice(0, 128);
3813
- }
3814
-
3815
5040
  function asInteger(value: unknown): number | undefined {
3816
5041
  if (typeof value === "number" && Number.isInteger(value)) return value;
3817
5042
  if (typeof value !== "string" || value.trim() === "") return undefined;
@@ -4832,22 +6057,6 @@ export function isTelegramTopicModeUnavailableError(error: unknown): boolean {
4832
6057
  );
4833
6058
  }
4834
6059
 
4835
- export function getTelegramTopicTitleForThreadName(
4836
- threadName: string,
4837
- slot: string,
4838
- template = "{threadName}",
4839
- ): string {
4840
- return getTelegramTopicName(
4841
- {
4842
- instanceId: "",
4843
- profileKey: normalizeTelegramTopicTargetThreadName(threadName) || "Pi",
4844
- threadName,
4845
- },
4846
- template,
4847
- slot,
4848
- );
4849
- }
4850
-
4851
6060
  export function createTelegramTopicTargetRenamer(
4852
6061
  deps: TelegramTopicTargetRenamerDeps,
4853
6062
  ): (
@@ -5109,7 +6318,7 @@ export function createTelegramTopicTargetProvisioner(
5109
6318
  if (!projectedTitle?.trim()) {
5110
6319
  throw new Error("Telegram Thread display identity is missing or ambiguous.");
5111
6320
  }
5112
- displayTitle = getTelegramTopicName(
6321
+ displayTitle = buildTelegramTopicName(
5113
6322
  { ...request, threadName: projectedTitle },
5114
6323
  "{threadName}",
5115
6324
  slot,
@@ -5141,7 +6350,7 @@ export function createTelegramTopicTargetProvisioner(
5141
6350
  "createForumTopic",
5142
6351
  {
5143
6352
  chat_id: deps.topicChatId,
5144
- name: displayTitle ?? getTelegramTopicName(
6353
+ name: displayTitle ?? buildTelegramTopicName(
5145
6354
  {
5146
6355
  ...request,
5147
6356
  ...(requestThreadName ? { threadName: requestThreadName } : {}),