copilotz 1.0.0-rc.20 → 1.0.0-rc.21

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 (340) hide show
  1. package/CHANGELOG.md +417 -0
  2. package/README.md +295 -19
  3. package/hosts/orgs/mod.d.ts +4 -1
  4. package/hosts/orgs/mod.js +2 -2
  5. package/hosts/web/files.d.ts +6 -2
  6. package/hosts/web/files.js +36 -3
  7. package/hosts/web/node/mod.d.ts +1 -1
  8. package/hosts/web/node/mod.js +1 -1
  9. package/hosts/web/node/serve.d.ts +26 -0
  10. package/hosts/web/node/serve.js +23 -1
  11. package/hosts/web/routes.d.ts +28 -1
  12. package/hosts/web/routes.js +65 -10
  13. package/hosts/web/server.d.ts +5 -4
  14. package/hosts/web/server.js +1 -1
  15. package/package.json +2 -2
  16. package/plugins/access/accounts/collections/account.d.ts +2 -2
  17. package/plugins/access/contacts/actions/chat.d.ts +1 -0
  18. package/plugins/access/contacts/actions/chat.js +45 -0
  19. package/plugins/access/contacts/actions/forget.d.ts +1 -0
  20. package/plugins/access/contacts/actions/forget.js +56 -0
  21. package/plugins/access/contacts/actions/start.d.ts +1 -0
  22. package/plugins/access/contacts/actions/start.js +50 -0
  23. package/plugins/access/contacts/collections/contact.d.ts +81 -0
  24. package/plugins/access/contacts/collections/contact.js +58 -0
  25. package/plugins/access/contacts/contract.d.ts +10 -0
  26. package/plugins/access/contacts/contract.js +10 -0
  27. package/plugins/access/contacts/mod.d.ts +27 -0
  28. package/plugins/access/contacts/mod.js +49 -0
  29. package/plugins/access/contacts/views/contact.d.ts +8 -0
  30. package/plugins/access/contacts/views/contact.js +25 -0
  31. package/plugins/access/contacts/web.d.ts +7 -0
  32. package/plugins/access/contacts/web.js +11 -0
  33. package/plugins/access/directory/collections/credit-code.d.ts +1 -1
  34. package/plugins/access/directory/collections/invite.d.ts +1 -1
  35. package/plugins/access/identity/mod.js +8 -6
  36. package/plugins/access/mod.d.ts +7 -1
  37. package/plugins/access/mod.js +7 -2
  38. package/plugins/access/spaces/actions/agents.js +12 -6
  39. package/plugins/access/spaces/actions/create.js +10 -1
  40. package/plugins/access/spaces/actions/invitation.js +5 -2
  41. package/plugins/access/spaces/actions/keep.d.ts +1 -0
  42. package/plugins/access/spaces/actions/keep.js +55 -0
  43. package/plugins/access/spaces/actions/member.js +17 -4
  44. package/plugins/access/spaces/actions/rename.js +4 -0
  45. package/plugins/access/spaces/collections/member.d.ts +1 -1
  46. package/plugins/access/spaces/collections/request.d.ts +1 -1
  47. package/plugins/access/spaces/collections/space.d.ts +9 -0
  48. package/plugins/access/spaces/collections/space.js +2 -0
  49. package/plugins/access/spaces/contract.d.ts +4 -3
  50. package/plugins/access/spaces/contract.js +1 -1
  51. package/plugins/access/spaces/mod.d.ts +7 -1
  52. package/plugins/access/spaces/mod.js +8 -1
  53. package/plugins/access/spaces/resources/tools.d.ts +0 -5
  54. package/plugins/access/spaces/resources/tools.js +11 -1
  55. package/plugins/access/spaces/shared/agents.js +2 -2
  56. package/plugins/access/spaces/shared/can.d.ts +18 -3
  57. package/plugins/access/spaces/shared/can.js +32 -5
  58. package/plugins/access/spaces/shared/declared.d.ts +21 -0
  59. package/plugins/access/spaces/shared/declared.js +8 -0
  60. package/plugins/access/spaces/shared/labels.d.ts +7 -1
  61. package/plugins/access/spaces/shared/labels.js +56 -8
  62. package/plugins/access/spaces/shared/managers.js +2 -2
  63. package/plugins/access/spaces/shared/names.d.ts +9 -5
  64. package/plugins/access/spaces/shared/names.js +36 -19
  65. package/plugins/access/spaces/shared/reach.d.ts +20 -6
  66. package/plugins/access/spaces/shared/reach.js +62 -20
  67. package/plugins/access/spaces/shared/rules.d.ts +10 -5
  68. package/plugins/access/spaces/shared/rules.js +35 -10
  69. package/plugins/access/spaces/shared/seat.d.ts +3 -2
  70. package/plugins/access/spaces/shared/seat.js +9 -2
  71. package/plugins/access/spaces/views/where.d.ts +4 -2
  72. package/plugins/access/spaces/views/where.js +9 -0
  73. package/plugins/access/spaces/web.js +1 -1
  74. package/plugins/access/web.d.ts +1 -0
  75. package/plugins/access/web.js +1 -0
  76. package/plugins/agents/chat/actions/erase.d.ts +1 -0
  77. package/plugins/agents/chat/actions/erase.js +51 -0
  78. package/plugins/agents/chat/actions/open.d.ts +1 -0
  79. package/plugins/agents/chat/actions/open.js +49 -0
  80. package/plugins/agents/chat/actions/quiet.d.ts +1 -0
  81. package/plugins/agents/chat/actions/quiet.js +33 -0
  82. package/plugins/agents/chat/actions/say.d.ts +1 -0
  83. package/plugins/agents/chat/actions/say.js +82 -0
  84. package/plugins/agents/chat/actions/send.js +57 -19
  85. package/plugins/agents/chat/actions/shown.d.ts +1 -0
  86. package/plugins/agents/chat/actions/shown.js +35 -0
  87. package/plugins/agents/chat/collections/intent.d.ts +124 -0
  88. package/plugins/agents/chat/collections/intent.js +52 -0
  89. package/plugins/agents/chat/collections/message.d.ts +74 -1
  90. package/plugins/agents/chat/collections/message.js +23 -1
  91. package/plugins/agents/chat/collections/shown.d.ts +105 -0
  92. package/plugins/agents/chat/collections/shown.js +34 -0
  93. package/plugins/agents/chat/contract.d.ts +15 -7
  94. package/plugins/agents/chat/contract.js +7 -1
  95. package/plugins/agents/chat/mod.d.ts +20 -2
  96. package/plugins/agents/chat/mod.js +43 -4
  97. package/plugins/agents/chat/processors/failed.js +15 -5
  98. package/plugins/agents/chat/processors/turn.d.ts +1 -1
  99. package/plugins/agents/chat/processors/turn.js +95 -35
  100. package/plugins/agents/chat/shared/delivery.d.ts +16 -2
  101. package/plugins/agents/chat/shared/delivery.js +62 -7
  102. package/plugins/agents/chat/shared/send.d.ts +1 -3
  103. package/plugins/agents/chat/shared/send.js +2 -9
  104. package/plugins/agents/chat/shared/tools.d.ts +33 -0
  105. package/plugins/agents/chat/shared/tools.js +28 -0
  106. package/plugins/agents/chat/shared/types.d.ts +59 -1
  107. package/plugins/agents/chat/views/message.d.ts +4 -2
  108. package/plugins/agents/chat/views/message.js +22 -4
  109. package/plugins/agents/chat/views/prompt.js +38 -4
  110. package/plugins/agents/history/collections/outline.d.ts +1 -1
  111. package/plugins/agents/history/collections/summary.d.ts +1 -1
  112. package/plugins/agents/history/mod.js +2 -1
  113. package/plugins/agents/history/processors/erase.d.ts +3 -0
  114. package/plugins/agents/history/processors/erase.js +11 -0
  115. package/plugins/agents/memory/mod.js +2 -1
  116. package/plugins/agents/memory/processors/extract.d.ts +1 -1
  117. package/plugins/agents/memory/processors/extract.js +5 -0
  118. package/plugins/agents/memory/resources/tools.js +1 -1
  119. package/plugins/agents/memory/shared/settings.d.ts +7 -2
  120. package/plugins/agents/memory/shared/settings.js +9 -1
  121. package/plugins/agents/routines/collections/routine.d.ts +1 -1
  122. package/plugins/agents/routines/collections/run.d.ts +1 -1
  123. package/plugins/compute/apps/collections/app.d.ts +2 -2
  124. package/plugins/compute/cloud/resources/tools.js +3 -3
  125. package/plugins/compute/computers/collections/approval.d.ts +2 -2
  126. package/plugins/compute/computers/collections/grant.d.ts +1 -1
  127. package/plugins/compute/computers/collections/preview.d.ts +2 -2
  128. package/plugins/compute/computers/program/version.d.ts +1 -1
  129. package/plugins/compute/computers/program/version.js +1 -1
  130. package/plugins/compute/computers/resources/downloads.js +1 -1
  131. package/plugins/compute/computers/shared/wake.d.ts +1 -1
  132. package/plugins/compute/computers/shared/wake.js +17 -0
  133. package/plugins/interfaces/api/collections/key.d.ts +1 -1
  134. package/plugins/interfaces/api/shared/events.js +5 -4
  135. package/plugins/interfaces/maintenance/actions/read.d.ts +4 -0
  136. package/plugins/interfaces/maintenance/actions/read.js +76 -0
  137. package/plugins/interfaces/maintenance/actions/write.d.ts +4 -0
  138. package/plugins/interfaces/maintenance/actions/write.js +64 -0
  139. package/plugins/interfaces/maintenance/contract.d.ts +60 -0
  140. package/plugins/interfaces/maintenance/contract.js +2 -0
  141. package/plugins/interfaces/maintenance/mod.d.ts +52 -0
  142. package/plugins/interfaces/maintenance/mod.js +66 -0
  143. package/plugins/interfaces/maintenance/resources/routes.d.ts +71 -0
  144. package/plugins/interfaces/maintenance/resources/routes.js +457 -0
  145. package/plugins/interfaces/maintenance/shared/ops.d.ts +4 -0
  146. package/plugins/interfaces/maintenance/shared/ops.js +19 -0
  147. package/plugins/interfaces/mcp/actions/call.d.ts +11 -0
  148. package/plugins/interfaces/mcp/actions/call.js +304 -0
  149. package/plugins/interfaces/mcp/actions/prune.d.ts +1 -0
  150. package/plugins/interfaces/mcp/actions/prune.js +18 -0
  151. package/plugins/interfaces/mcp/collections/closed.d.ts +23 -0
  152. package/plugins/interfaces/mcp/collections/closed.js +17 -0
  153. package/plugins/interfaces/mcp/collections/rate.d.ts +27 -0
  154. package/plugins/interfaces/mcp/collections/rate.js +18 -0
  155. package/plugins/interfaces/mcp/collections/receipt.d.ts +46 -0
  156. package/plugins/interfaces/mcp/collections/receipt.js +46 -0
  157. package/plugins/interfaces/mcp/contract.d.ts +9 -0
  158. package/plugins/interfaces/mcp/contract.js +9 -0
  159. package/plugins/interfaces/mcp/mod.d.ts +84 -0
  160. package/plugins/interfaces/mcp/mod.js +122 -0
  161. package/plugins/interfaces/mcp/processors/closed.d.ts +13 -0
  162. package/plugins/interfaces/mcp/processors/closed.js +16 -0
  163. package/plugins/interfaces/mcp/resources/running.d.ts +21 -0
  164. package/plugins/interfaces/mcp/resources/running.js +36 -0
  165. package/plugins/interfaces/mcp/resources/server.d.ts +54 -0
  166. package/plugins/interfaces/mcp/resources/server.js +423 -0
  167. package/plugins/interfaces/mcp/resources/tools.d.ts +114 -0
  168. package/plugins/interfaces/mcp/resources/tools.js +324 -0
  169. package/plugins/interfaces/mcp/shared/caller.d.ts +45 -0
  170. package/plugins/interfaces/mcp/shared/caller.js +99 -0
  171. package/plugins/interfaces/mcp/shared/keys.d.ts +50 -0
  172. package/plugins/interfaces/mcp/shared/keys.js +53 -0
  173. package/plugins/interfaces/mcp/shared/settings.d.ts +187 -0
  174. package/plugins/interfaces/mcp/shared/settings.js +176 -0
  175. package/plugins/interfaces/mcp/views/offered.d.ts +20 -0
  176. package/plugins/interfaces/mcp/views/offered.js +20 -0
  177. package/plugins/interfaces/mod.d.ts +5 -1
  178. package/plugins/interfaces/mod.js +5 -1
  179. package/plugins/interfaces/terminal/actions/print.js +1 -1
  180. package/plugins/interfaces/terminal/actions/set.js +1 -1
  181. package/plugins/interfaces/terminal/collections/output.d.ts +1 -1
  182. package/plugins/interfaces/terminal/collections/shell.js +1 -1
  183. package/plugins/interfaces/voice/actions/block.d.ts +2 -0
  184. package/plugins/interfaces/voice/actions/block.js +74 -0
  185. package/plugins/interfaces/voice/actions/call.d.ts +19 -0
  186. package/plugins/interfaces/voice/actions/call.js +253 -0
  187. package/plugins/interfaces/voice/actions/hook.d.ts +5 -0
  188. package/plugins/interfaces/voice/actions/hook.js +225 -0
  189. package/plugins/interfaces/voice/actions/prune.d.ts +1 -0
  190. package/plugins/interfaces/voice/actions/prune.js +35 -0
  191. package/plugins/interfaces/voice/collections/blocked.d.ts +87 -0
  192. package/plugins/interfaces/voice/collections/blocked.js +34 -0
  193. package/plugins/interfaces/voice/collections/call.d.ts +279 -0
  194. package/plugins/interfaces/voice/collections/call.js +77 -0
  195. package/plugins/interfaces/voice/collections/phone.d.ts +74 -0
  196. package/plugins/interfaces/voice/collections/phone.js +26 -0
  197. package/plugins/interfaces/voice/contract.d.ts +14 -0
  198. package/plugins/interfaces/voice/contract.js +2 -0
  199. package/plugins/interfaces/voice/mod.d.ts +57 -0
  200. package/plugins/interfaces/voice/mod.js +118 -0
  201. package/plugins/interfaces/voice/processors/forget.d.ts +13 -0
  202. package/plugins/interfaces/voice/processors/forget.js +27 -0
  203. package/plugins/interfaces/voice/resources/relay.d.ts +77 -0
  204. package/plugins/interfaces/voice/resources/relay.js +428 -0
  205. package/plugins/interfaces/voice/resources/tools.d.ts +1 -0
  206. package/plugins/interfaces/voice/resources/tools.js +25 -0
  207. package/plugins/interfaces/voice/shared/caller.d.ts +27 -0
  208. package/plugins/interfaces/voice/shared/caller.js +38 -0
  209. package/plugins/interfaces/voice/shared/settings.d.ts +136 -0
  210. package/plugins/interfaces/voice/shared/settings.js +121 -0
  211. package/plugins/interfaces/voice/shared/signature.d.ts +11 -0
  212. package/plugins/interfaces/voice/shared/signature.js +34 -0
  213. package/plugins/interfaces/voice/views/call.d.ts +41 -0
  214. package/plugins/interfaces/voice/views/call.js +30 -0
  215. package/plugins/interfaces/voice/views/context.d.ts +9 -0
  216. package/plugins/interfaces/voice/views/context.js +14 -0
  217. package/plugins/interfaces/voice/views/message.d.ts +17 -0
  218. package/plugins/interfaces/voice/views/message.js +41 -0
  219. package/plugins/interfaces/whatsapp/actions/connect.js +3 -0
  220. package/plugins/interfaces/whatsapp/actions/disconnect.js +4 -1
  221. package/plugins/interfaces/whatsapp/actions/hook.js +27 -11
  222. package/plugins/interfaces/whatsapp/actions/set.d.ts +8 -0
  223. package/plugins/interfaces/whatsapp/actions/set.js +121 -0
  224. package/plugins/interfaces/whatsapp/collections/blocked.d.ts +29 -0
  225. package/plugins/interfaces/whatsapp/collections/blocked.js +22 -0
  226. package/plugins/interfaces/whatsapp/collections/code.d.ts +1 -1
  227. package/plugins/interfaces/whatsapp/collections/number.d.ts +90 -4
  228. package/plugins/interfaces/whatsapp/collections/number.js +36 -4
  229. package/plugins/interfaces/whatsapp/collections/phone.d.ts +13 -3
  230. package/plugins/interfaces/whatsapp/collections/phone.js +9 -3
  231. package/plugins/interfaces/whatsapp/collections/rate.d.ts +27 -0
  232. package/plugins/interfaces/whatsapp/collections/rate.js +13 -0
  233. package/plugins/interfaces/whatsapp/collections/sent.d.ts +24 -12
  234. package/plugins/interfaces/whatsapp/collections/sent.js +11 -7
  235. package/plugins/interfaces/whatsapp/collections/thread.d.ts +14 -6
  236. package/plugins/interfaces/whatsapp/collections/thread.js +7 -5
  237. package/plugins/interfaces/whatsapp/collections/typing.d.ts +70 -0
  238. package/plugins/interfaces/whatsapp/collections/typing.js +21 -0
  239. package/plugins/interfaces/whatsapp/contract.d.ts +27 -4
  240. package/plugins/interfaces/whatsapp/contract.js +34 -1
  241. package/plugins/interfaces/whatsapp/events/undelivered.d.ts +8 -0
  242. package/plugins/interfaces/whatsapp/events/undelivered.js +17 -0
  243. package/plugins/interfaces/whatsapp/mod.d.ts +28 -2
  244. package/plugins/interfaces/whatsapp/mod.js +65 -6
  245. package/plugins/interfaces/whatsapp/processors/forget.d.ts +6 -0
  246. package/plugins/interfaces/whatsapp/processors/forget.js +11 -0
  247. package/plugins/interfaces/whatsapp/processors/receive.d.ts +17 -3
  248. package/plugins/interfaces/whatsapp/processors/receive.js +264 -81
  249. package/plugins/interfaces/whatsapp/processors/reply.d.ts +25 -5
  250. package/plugins/interfaces/whatsapp/processors/reply.js +216 -20
  251. package/plugins/interfaces/whatsapp/processors/typing.d.ts +8 -0
  252. package/plugins/interfaces/whatsapp/processors/typing.js +25 -0
  253. package/plugins/interfaces/whatsapp/shared/customers.d.ts +13 -0
  254. package/plugins/interfaces/whatsapp/shared/customers.js +16 -0
  255. package/plugins/interfaces/whatsapp/shared/graph.d.ts +31 -6
  256. package/plugins/interfaces/whatsapp/shared/graph.js +117 -10
  257. package/plugins/interfaces/whatsapp/shared/media.d.ts +23 -0
  258. package/plugins/interfaces/whatsapp/shared/media.js +46 -0
  259. package/plugins/interfaces/whatsapp/shared/number.d.ts +19 -8
  260. package/plugins/interfaces/whatsapp/shared/number.js +64 -7
  261. package/plugins/interfaces/whatsapp/shared/parts.d.ts +94 -0
  262. package/plugins/interfaces/whatsapp/shared/parts.js +184 -0
  263. package/plugins/interfaces/whatsapp/shared/payload.d.ts +27 -1
  264. package/plugins/interfaces/whatsapp/shared/payload.js +36 -1
  265. package/plugins/interfaces/whatsapp/shared/settings.d.ts +49 -1
  266. package/plugins/interfaces/whatsapp/shared/settings.js +11 -0
  267. package/plugins/interfaces/whatsapp/views/message.d.ts +13 -0
  268. package/plugins/interfaces/whatsapp/views/message.js +13 -0
  269. package/plugins/interfaces/whatsapp/views/web/line.d.ts +24 -0
  270. package/plugins/interfaces/whatsapp/views/web/line.js +44 -0
  271. package/plugins/interfaces/whatsapp/views/web/space.d.ts +7 -5
  272. package/plugins/interfaces/whatsapp/views/web/space.js +17 -10
  273. package/plugins/interfaces/whatsapp/views/web/style.d.ts +1 -1
  274. package/plugins/interfaces/whatsapp/views/web/style.js +8 -0
  275. package/plugins/models/adapters/llm/anthropic.d.ts +1 -1
  276. package/plugins/models/adapters/llm/anthropic.js +28 -15
  277. package/plugins/models/adapters/llm/gemini.d.ts +1 -1
  278. package/plugins/models/adapters/llm/gemini.js +2 -1
  279. package/plugins/models/adapters/llm/openai-compatible.d.ts +1 -1
  280. package/plugins/models/adapters/llm/openai-compatible.js +2 -1
  281. package/plugins/models/adapters/llm/openai.d.ts +1 -1
  282. package/plugins/models/adapters/llm/openai.js +16 -4
  283. package/plugins/models/shared/types.d.ts +8 -0
  284. package/plugins/models/shared/types.js +10 -0
  285. package/runtime/actor.d.ts +6 -0
  286. package/runtime/actor.js +9 -4
  287. package/runtime/aggregate.js +8 -2
  288. package/runtime/blobs.d.ts +15 -12
  289. package/runtime/blobs.js +58 -11
  290. package/runtime/cache.d.ts +6 -0
  291. package/runtime/cache.js +19 -1
  292. package/runtime/define.d.ts +10 -0
  293. package/runtime/errors.d.ts +20 -2
  294. package/runtime/errors.js +7 -1
  295. package/runtime/executor.js +27 -11
  296. package/runtime/links.d.ts +31 -0
  297. package/runtime/links.js +60 -0
  298. package/runtime/maintain.d.ts +88 -0
  299. package/runtime/maintain.js +120 -0
  300. package/runtime/memory.js +7 -4
  301. package/runtime/mod.d.ts +6 -4
  302. package/runtime/mod.js +5 -2
  303. package/runtime/mongo.d.ts +13 -0
  304. package/runtime/mongo.js +39 -8
  305. package/runtime/observe.d.ts +2 -0
  306. package/runtime/observe.js +14 -10
  307. package/runtime/ops.d.ts +5 -0
  308. package/runtime/ops.js +10 -1
  309. package/runtime/owner.d.ts +18 -1
  310. package/runtime/owner.js +127 -61
  311. package/runtime/presence.d.ts +18 -0
  312. package/runtime/presence.js +25 -0
  313. package/runtime/registry.d.ts +5 -0
  314. package/runtime/registry.js +18 -0
  315. package/runtime/runtime.js +9 -3
  316. package/runtime/store.d.ts +48 -1
  317. package/runtime/wire.d.ts +1 -0
  318. package/runtime/wire.js +3 -1
  319. package/stores/blobs/files/mod.js +4 -2
  320. package/stores/blobs/gcs/mod.d.ts +3 -0
  321. package/stores/blobs/gcs/mod.js +6 -5
  322. package/stores/blobs/http/mod.d.ts +1 -1
  323. package/stores/blobs/http/mod.js +2 -1
  324. package/stores/latency/mod.js +5 -1
  325. package/stores/sql/postgres/maintenance.d.ts +24 -0
  326. package/stores/sql/postgres/maintenance.js +258 -0
  327. package/stores/sql/postgres/mod.d.ts +20 -4
  328. package/stores/sql/postgres/mod.js +363 -96
  329. package/stores/sql/postgres/update.js +3 -1
  330. package/stores/sql/shared/capped.d.ts +2 -0
  331. package/stores/sql/shared/capped.js +22 -0
  332. package/stores/sql/shared/rows.d.ts +14 -0
  333. package/stores/sql/shared/rows.js +29 -0
  334. package/stores/sql/shared/statement.d.ts +12 -0
  335. package/stores/sql/shared/statement.js +244 -0
  336. package/stores/sql/sqlite/apart.d.ts +11 -0
  337. package/stores/sql/sqlite/apart.js +219 -0
  338. package/stores/sql/sqlite/mod.d.ts +16 -2
  339. package/stores/sql/sqlite/mod.js +246 -51
  340. package/testing/mod.js +1 -1
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Which workers of plugins' kinds (computers…) are connected: by kind and id, the worker and
3
+ * the connection it's on. A worker can move to a fresh connection while its old one is still
4
+ * open (Oxian's handoff, before a connection's streams run out): the new one is ready first,
5
+ * then the old one closes. That's no arrival and no departure, so its kind hears neither.
6
+ */
7
+ export type Presence = ReturnType<typeof workerPresence>;
8
+ export declare function workerPresence(): {
9
+ /** A worker's connection is ready. True when the worker is new here, not just moving. */
10
+ arrived(kind: string, id: string, workerId: string, connectionId: string): boolean;
11
+ /** A worker's connection closed. True when it was the one it's on: the worker is gone. */
12
+ left(kind: string, id: string, workerId: string, connectionId: string): boolean;
13
+ /** The worker connected as `kind`/`id`, if one is. */
14
+ workerOf: (kind: string, id: string) => string | undefined;
15
+ /** Everyone connected, as `[kind, id]`. */
16
+ all: () => [string, string][];
17
+ clear: () => void;
18
+ };
@@ -0,0 +1,25 @@
1
+ export function workerPresence() {
2
+ const at = new Map();
3
+ const key = (kind, id) => `${kind}\u0000${id}`;
4
+ return {
5
+ /** A worker's connection is ready. True when the worker is new here, not just moving. */
6
+ arrived(kind, id, workerId, connectionId) {
7
+ const was = at.get(key(kind, id));
8
+ at.set(key(kind, id), { workerId, connectionId });
9
+ return was?.workerId !== workerId;
10
+ },
11
+ /** A worker's connection closed. True when it was the one it's on: the worker is gone. */
12
+ left(kind, id, workerId, connectionId) {
13
+ const now = at.get(key(kind, id));
14
+ if (now?.workerId !== workerId || now.connectionId !== connectionId)
15
+ return false;
16
+ at.delete(key(kind, id));
17
+ return true;
18
+ },
19
+ /** The worker connected as `kind`/`id`, if one is. */
20
+ workerOf: (kind, id) => at.get(key(kind, id))?.workerId,
21
+ /** Everyone connected, as `[kind, id]`. */
22
+ all: () => [...at.keys()].map((k) => k.split("\u0000")),
23
+ clear: () => at.clear(),
24
+ };
25
+ }
@@ -7,6 +7,11 @@ export declare const invalid: (message: string) => Error & {
7
7
  };
8
8
  /** JSON with object keys sorted, so equal values serialize equally. */
9
9
  export declare const canonical: (value: unknown) => string;
10
+ /**
11
+ * A copy of `value` without the private fields at these (dotted) paths: a
12
+ * collection's (see `CollectionDef.private`) or an Action's (`ActionDef.private`).
13
+ */
14
+ export declare function unprivate<T>(value: T, fields: string[]): T;
10
15
  /** A short hash identifying an action call by what it does: its action and input. */
11
16
  export declare function fingerprint(action: string, input: unknown): Promise<string>;
12
17
  export declare function compile(schema: unknown, label: string): (value: unknown) => void;
@@ -10,6 +10,24 @@ export const invalid = (message) => Object.assign(new Error(message), { code: "i
10
10
  export const canonical = (value) => JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v)
11
11
  ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
12
12
  : v);
13
+ /**
14
+ * A copy of `value` without the private fields at these (dotted) paths: a
15
+ * collection's (see `CollectionDef.private`) or an Action's (`ActionDef.private`).
16
+ */
17
+ export function unprivate(value, fields) {
18
+ if (!fields.length || !value || typeof value !== "object")
19
+ return value;
20
+ const copy = structuredClone(value);
21
+ for (const path of fields) {
22
+ const keys = path.split(".");
23
+ let at = copy;
24
+ for (const key of keys.slice(0, -1))
25
+ at = at?.[key];
26
+ if (at && typeof at === "object")
27
+ delete at[keys.at(-1)];
28
+ }
29
+ return copy;
30
+ }
13
31
  /** A short hash identifying an action call by what it does: its action and input. */
14
32
  export async function fingerprint(action, input) {
15
33
  const data = new TextEncoder().encode(canonical([action, input ?? null]));
@@ -36,9 +36,15 @@ export async function createRuntime(options) {
36
36
  await Promise.all(executors.map((executor) => executor.ready));
37
37
  return {
38
38
  ...owner,
39
- async close() {
40
- await owner.close();
41
- await Promise.all(executors.map((executor) => executor.stop()));
39
+ async close(options) {
40
+ // The executors stop even when the owner's close fails (a fenced owner's last save):
41
+ // left running, they'd keep the process alive.
42
+ try {
43
+ await owner.close(options);
44
+ }
45
+ finally {
46
+ await Promise.all(executors.map((executor) => executor.stop()));
47
+ }
42
48
  },
43
49
  };
44
50
  }
@@ -147,6 +147,34 @@ export type Transaction = Reader & {
147
147
  deleteVectors(collection: string, docs: string[], field?: string): Promise<void>;
148
148
  /** Appends an event; it gets its `seq` when the transaction commits. */
149
149
  emit(event: Emitted): void;
150
+ /**
151
+ * Optional, for maintenance only (runtime/maintain.ts): runs one SQL
152
+ * statement as it is, in this transaction, and says how many rows it
153
+ * changed. It bypasses schemas and per-document events, so it runs only in
154
+ * a `maintenance` transaction, and a statement that changes the store's own
155
+ * state (its fencing epoch, Processors' positions) is refused. A SQL store
156
+ * has it, where SQL can reach nothing but this store's own data.
157
+ */
158
+ execute?(sql: string, params?: unknown[], options?: {
159
+ timeout?: number;
160
+ }): Promise<Executed>;
161
+ };
162
+ /** A row a SQL statement returned, as the database driver gives it. */
163
+ export type Row = Record<string, unknown>;
164
+ /**
165
+ * What a maintenance read returned: its rows; `cut` when it stopped before
166
+ * a row that would pass its bytes (more may follow); `inline` when it ran on
167
+ * the store's own connection, with no timeout (a SQLite store that can't
168
+ * read apart).
169
+ */
170
+ export type Inspected = Row[] & {
171
+ cut?: true;
172
+ inline?: true;
173
+ };
174
+ /** What a maintenance statement did: rows it returned (`RETURNING`), and rows it changed. */
175
+ export type Executed = {
176
+ rows: Row[];
177
+ changed: number;
150
178
  };
151
179
  /** A declared index: its fields, each a scalar of one type. */
152
180
  export type IndexSpec = {
@@ -173,11 +201,13 @@ export type Command = {
173
201
  * Each write is validated, with large values already offloaded to `blobs`.
174
202
  * With `record`, it records `<collection>.created/updated/deleted` for each
175
203
  * document it changes, right after it: `{ _id, doc }`, plus `changed` and
176
- * `removed` (sorted) for updates.
204
+ * `removed` (sorted) for updates. The documents it records go without the
205
+ * collection's `private` fields (dot paths), as the log always does.
177
206
  */
178
207
  steps: ({
179
208
  write: WriteOp;
180
209
  record: boolean;
210
+ private?: string[];
181
211
  } | {
182
212
  emit: Emitted;
183
213
  })[];
@@ -197,9 +227,13 @@ export type Store = Reader & {
197
227
  * Runs `work` as one atomic, fenced transaction and returns its result with
198
228
  * the committed events. Throws `fenced` if another owner claimed the store.
199
229
  * `positions` (Processor positions) are saved with the commit.
230
+ * `maintenance`: a transaction for maintenance SQL (`execute`). It runs
231
+ * alone (the writes running end first, and the next wait for it), and a
232
+ * store may run it on a connection of its own.
200
233
  */
201
234
  transaction<T>(epoch: number, work: (tx: Transaction) => Promise<T>, options?: {
202
235
  positions?: Record<string, number>;
236
+ maintenance?: boolean;
203
237
  }): Promise<{
204
238
  result: T;
205
239
  events: Event[];
@@ -220,6 +254,19 @@ export type Store = Reader & {
220
254
  }> | undefined;
221
255
  /** Optional: lets an adapter present each collection natively, for example as a SQL view. */
222
256
  describe?(collections: Record<string, JSONSchema>): void | Promise<void>;
257
+ /**
258
+ * Optional, for maintenance and inspection tools: runs one read-only SQL
259
+ * statement on committed state, with `params` bound ($1, ?1…), and returns
260
+ * at most `limit` rows, fetching none that would pass `bytes`; `timeout`
261
+ * (ms) cancels it.
262
+ * A SQL store has it, refusing it where SQL could reach other tenants' data,
263
+ * and leaving nothing of it on a connection the store's other work shares.
264
+ */
265
+ inspect?(sql: string, params?: unknown[], options?: {
266
+ limit?: number;
267
+ timeout?: number;
268
+ bytes?: number;
269
+ }): Promise<Inspected>;
223
270
  /**
224
271
  * Makes the declared indexes (and drops ones no longer declared). A field's
225
272
  * type is what its schema guarantees, so a filter on it may compare it as
package/runtime/wire.d.ts CHANGED
@@ -60,6 +60,7 @@ export type Failure = {
60
60
  message: string;
61
61
  code?: string;
62
62
  final?: true;
63
+ public?: true;
63
64
  };
64
65
  export type Line = {
65
66
  frame: {
package/runtime/wire.js CHANGED
@@ -15,8 +15,10 @@ export const failure = (error) => ({
15
15
  ? { code: error.code }
16
16
  : {}),
17
17
  ...(error?.final === true ? { final: true } : {}),
18
+ // A message for any caller stays one from job to job (see errors.ts).
19
+ ...(error?.public === true ? { public: true } : {}),
18
20
  });
19
- export const raise = (failure) => Object.assign(new Error(failure.message), failure.code ? { code: failure.code } : {}, failure.final ? { final: true } : {});
21
+ export const raise = (failure) => Object.assign(new Error(failure.message), failure.code ? { code: failure.code } : {}, failure.final ? { final: true } : {}, failure.public ? { public: true } : {});
20
22
  /**
21
23
  * Output lines are newline-delimited JSON. Read with a reader, not `for await`:
22
24
  * Safari can't iterate a stream (this runs in browsers too).
@@ -1,11 +1,13 @@
1
1
  /**
2
2
  * Blobs as files in a directory, sharded by the first two hex digits of the
3
- * hash. Uses `node:fs`, which Node, Deno and Bun all provide.
3
+ * hash. Uses `node:fs`, which Node, Deno and Bun all provide. An id is only
4
+ * ever a blob's (`sha256-` and hex), so a path never leaves the directory.
4
5
  */
5
6
  import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
7
+ import { checkBlobId } from "../../../runtime/blobs.js";
6
8
  const missing = (error) => error.code === "ENOENT";
7
9
  export function fileBlobs(options) {
8
- const path = (id) => `${options.dir}/${id.slice(7, 9)}/${id}`;
10
+ const path = (id) => `${options.dir}/${id.slice(7, 9)}/${checkBlobId(id)}`;
9
11
  return {
10
12
  async put({ id, data }) {
11
13
  const file = path(id);
@@ -12,6 +12,9 @@
12
12
  * Application Default Credentials). Each try may take `timeout` ms; a request the
13
13
  * network, a timeout, 429 or a 5xx breaks is tried twice more, waiting a
14
14
  * little longer each time. Other 4xx fail at once. Web standards only.
15
+ *
16
+ * An id is only ever a blob's (`sha256-` and hex): never the name of another
17
+ * object in the bucket.
15
18
  */
16
19
  import type { Blobs } from "../../../runtime/mod.js";
17
20
  export declare function gcsBlobs(options: {
@@ -1,3 +1,4 @@
1
+ import { checkBlobId } from "../../../runtime/blobs.js";
1
2
  /** GCS's JSON API. */
2
3
  const API = "https://storage.googleapis.com";
3
4
  /** The token of the instance's service account, on Cloud Run and Compute Engine. */
@@ -51,7 +52,7 @@ export function gcsBlobs(options) {
51
52
  const token = options.token ?? metadataToken(go, timeout);
52
53
  const bucket = encodeURIComponent(options.bucket);
53
54
  const prefix = (options.prefix ?? "").replace(/^\/+|\/+$/g, "");
54
- const name = (id) => prefix ? `${prefix}/${id}` : id;
55
+ const name = (id) => prefix ? `${prefix}/${checkBlobId(id)}` : checkBlobId(id);
55
56
  /** A request, tried again while it breaks in passing; `read` takes its answer. */
56
57
  const request = async (url, init, read) => {
57
58
  for (let n = 1;; n++) {
@@ -74,13 +75,13 @@ export function gcsBlobs(options) {
74
75
  }
75
76
  };
76
77
  return {
77
- put({ id, data, type }) {
78
+ async put({ id, data, type }) {
78
79
  const query = new URLSearchParams({
79
80
  uploadType: "media",
80
81
  name: name(id),
81
82
  ifGenerationMatch: "0",
82
83
  });
83
- return request(`${API}/upload/storage/v1/b/${bucket}/o?${query}`, {
84
+ return await request(`${API}/upload/storage/v1/b/${bucket}/o?${query}`, {
84
85
  method: "POST",
85
86
  headers: { "content-type": type ?? "application/octet-stream" },
86
87
  body: data,
@@ -91,8 +92,8 @@ export function gcsBlobs(options) {
91
92
  throw await failure(response, `putting blob ${id}`);
92
93
  });
93
94
  },
94
- get(id) {
95
- return request(`${API}/storage/v1/b/${bucket}/o/${encodeURIComponent(name(id))}?alt=media`, {}, async (response) => {
95
+ async get(id) {
96
+ return await request(`${API}/storage/v1/b/${bucket}/o/${encodeURIComponent(name(id))}?alt=media`, {}, async (response) => {
96
97
  if (response.status === 404)
97
98
  return (await response.body?.cancel(), null);
98
99
  if (!response.ok)
@@ -3,7 +3,7 @@
3
3
  * stores serve (S3, GCS, R2, MinIO), directly or through a signing proxy.
4
4
  * `headers` adds what a request needs (an Authorization, say), per request.
5
5
  * Content-addressed: an id that exists is the same content, so putting it
6
- * again is harmless.
6
+ * again is harmless. An id is only ever a blob's (`sha256-` and hex).
7
7
  */
8
8
  import type { Blobs } from "../../../runtime/mod.js";
9
9
  export declare function httpBlobs(options: {
@@ -1,6 +1,7 @@
1
+ import { checkBlobId } from "../../../runtime/blobs.js";
1
2
  export function httpBlobs(options) {
2
3
  const go = options.fetch ?? fetch;
3
- const at = (id) => `${options.url.replace(/\/$/, "")}/${encodeURIComponent(id)}`;
4
+ const at = (id) => `${options.url.replace(/\/$/, "")}/${encodeURIComponent(checkBlobId(id))}`;
4
5
  return {
5
6
  async put({ id, data, type }) {
6
7
  const response = await go(at(id), {
@@ -35,7 +35,11 @@ export function withLatency(store, ms) {
35
35
  : {}),
36
36
  describe: store.describe?.bind(store),
37
37
  index: store.index?.bind(store),
38
- ...("inspect" in store ? { inspect: store.inspect } : {}),
38
+ ...(store.inspect
39
+ ? {
40
+ inspect: async (...args) => (await trip(), store.inspect(...args)),
41
+ }
42
+ : {}),
39
43
  roundTrips: () => trips,
40
44
  close: () => store.close(),
41
45
  };
@@ -0,0 +1,24 @@
1
+ import { type Session } from "./layout.js";
2
+ /** A new connection for one maintenance statement: a `Session`, and `end` to close it. */
3
+ export declare function connect(url: string, trace?: (sql: string) => void): Promise<Session & {
4
+ end(): Promise<void>;
5
+ }>;
6
+ /** Refuses raw SQL on a server whose store names no maintenance role. */
7
+ export declare const noRole: () => Error & {
8
+ code: string;
9
+ public?: true;
10
+ };
11
+ /**
12
+ * Refuses maintenance SQL when the role on `db` (the session's own, the
13
+ * login's), or a Cloud SQL marker it's a member of, holds anything beyond
14
+ * the allowlist.
15
+ */
16
+ export declare function allowed(db: Session, schema: string): Promise<void>;
17
+ /**
18
+ * PGlite's check, its one session being the store's: no other schema's
19
+ * tables within reach (another store's, in this process), and no remote
20
+ * databases.
21
+ */
22
+ export declare function alone(db: Session, schema: string): Promise<void>;
23
+ /** Triggers on the store's tables: none of the store's making, so none at all. */
24
+ export declare const triggers: (schema: string) => string;
@@ -0,0 +1,258 @@
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
4
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
5
+ });
6
+ }
7
+ return path;
8
+ };
9
+ /**
10
+ * Maintenance SQL's connection to a PostgreSQL server, and the role it runs
11
+ * as (runtime/maintain.ts; the store's `inspect` and `execute`).
12
+ *
13
+ * - **A role of its own, required on a server**
14
+ * (`postgresStore({ maintenance: { url } })`): the store's own role owns
15
+ * the tables, may stop the app's connections, and is whatever the
16
+ * deployment made it (a superuser, even). Without one, raw SQL is
17
+ * refused; the collections' operations, named queries and blobs don't
18
+ * need it. PGlite, in this process, runs it as its one session.
19
+ * - **Exactly the grants maintenance needs, checked before every
20
+ * statement** (`allowed`), on the connection that runs it: an allowlist,
21
+ * not a list of what's refused. The role has no attribute beyond LOGIN,
22
+ * is a member of no role at all (so `SET ROLE` reaches nothing, whatever
23
+ * INHERIT says), owns nothing, may create nothing anywhere, and holds no
24
+ * privilege on any table or column outside the store's schema; inside
25
+ * it, SELECT on everything, INSERT, UPDATE and DELETE on documents,
26
+ * edges, vectors and blobs, INSERT on the log, UPDATE of meta's `value`
27
+ * (to hold the fence), and nothing more. It may run no SECURITY DEFINER
28
+ * function (one runs as its owner: revoke EXECUTE from PUBLIC), and the
29
+ * database has no `dblink` or `postgres_fdw`. The store makes no
30
+ * triggers: one on its tables means someone else did, and nothing runs.
31
+ * - **A connection of its own for each statement, closed after:** whatever
32
+ * the statement leaves on its session goes with it. It speaks `pg`
33
+ * itself, the driver Ominipg loads, so every query goes over the
34
+ * extended protocol, where the server refuses more than one statement.
35
+ * - **At most `connections` at once** (2 by default; ../shared/capped.ts).
36
+ */
37
+ import { failure } from "../../../runtime/errors.js";
38
+ import { ident } from "./layout.js";
39
+ /** Not literal, so no bundler resolves it where only PGlite is used. */
40
+ const PG = "pg";
41
+ let driver;
42
+ /** Bytes as plain `Uint8Array`s (`pg` gives Buffers, whose `toJSON` says something else). */
43
+ const plain = (row) => {
44
+ for (const [key, value] of Object.entries(row)) {
45
+ if (value instanceof Uint8Array && value.constructor !== Uint8Array) {
46
+ row[key] = new Uint8Array(value);
47
+ }
48
+ }
49
+ return row;
50
+ };
51
+ /** A new connection for one maintenance statement: a `Session`, and `end` to close it. */
52
+ export async function connect(url, trace) {
53
+ const pg = await (driver ??= import(__rewriteRelativeImportExtension(PG)).then((m) => (m.default ?? m)));
54
+ const client = new pg.Client({ connectionString: url, application_name: "copilotz maintenance" });
55
+ // A connection the server drops fails the query running on it: nothing else to say.
56
+ client.on("error", () => { });
57
+ await client.connect();
58
+ return {
59
+ async query(text, params = []) {
60
+ trace?.(text);
61
+ const { rows } = await client.query({ text, values: params, queryMode: "extended" });
62
+ return { rows: rows.map(plain) };
63
+ },
64
+ end: () => client.end().catch(() => { }),
65
+ };
66
+ }
67
+ const unsafe = (message) => failure("unsafe_role", message);
68
+ /** Refuses raw SQL on a server whose store names no maintenance role. */
69
+ export const noRole = () => unsafe("Raw SQL on a PostgreSQL server runs only as a maintenance role of its own: " +
70
+ "postgresStore({ maintenance: { url } }), set up as the README's Maintenance says. " +
71
+ "The collections' operations, named queries and blobs work without it.");
72
+ /**
73
+ * Cloud SQL's markers of an IAM database user (a role made by `gcloud sql
74
+ * users create … --type=cloud_iam_*`): such a role is a member of one. Every
75
+ * IAM user is, so a marker is held to an empty allowlist (it may hold
76
+ * nothing at all, not even on the store's schema), and the membership may
77
+ * not carry ADMIN OPTION (the role could hand the marker to anyone).
78
+ */
79
+ const MARKERS = ["cloudsqliamuser", "cloudsqliamserviceaccount", "cloudsqliamgroup"];
80
+ /**
81
+ * What role `$2` holds beyond the allowlist above, for schema `$1`, one line
82
+ * for each, none when it holds exactly that; `$3` are the roles it may be a
83
+ * member of (Cloud SQL's markers). With no schema (`''`), the allowlist is
84
+ * empty: anything at all granted to it is beyond it. Every catalog name is
85
+ * `pg_catalog`'s: after a statement, in its transaction, a temporary table
86
+ * could stand in for one.
87
+ */
88
+ const BEYOND = `
89
+ WITH me AS (
90
+ SELECT oid, rolsuper, rolcreaterole, rolcreatedb, rolreplication, rolbypassrls
91
+ FROM pg_catalog.pg_roles WHERE rolname = $2::pg_catalog.name
92
+ ), own AS (
93
+ SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1::pg_catalog.name
94
+ ), here AS (
95
+ SELECT oid FROM pg_catalog.pg_database WHERE datname = pg_catalog.current_database()
96
+ ), catalogs AS (
97
+ SELECT oid FROM pg_catalog.pg_namespace WHERE nspname IN ('pg_catalog', 'information_schema')
98
+ ), privileges AS (
99
+ SELECT pg_catalog.unnest(ARRAY['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'TRUNCATE', 'REFERENCES',
100
+ 'TRIGGER'] || CASE WHEN pg_catalog.current_setting('server_version_num')::pg_catalog.int4 >=
101
+ 170000 THEN ARRAY['MAINTAIN'] ELSE ARRAY[]::pg_catalog.text[] END) AS privilege
102
+ ), temporary AS (
103
+ SELECT oid FROM pg_catalog.pg_namespace WHERE nspname ~ '^pg_(toast_)?temp_'
104
+ ), extension AS (
105
+ SELECT objid FROM pg_catalog.pg_depend
106
+ WHERE deptype = 'e' AND classid = 'pg_catalog.pg_class'::pg_catalog.regclass
107
+ )
108
+ SELECT DISTINCT problem FROM (
109
+ SELECT 'is a superuser' AS problem FROM me WHERE rolsuper
110
+ UNION ALL SELECT 'may create roles' FROM me WHERE rolcreaterole
111
+ UNION ALL SELECT 'may create databases' FROM me WHERE rolcreatedb
112
+ UNION ALL SELECT 'may replicate' FROM me WHERE rolreplication
113
+ UNION ALL SELECT 'bypasses row security' FROM me WHERE rolbypassrls
114
+ UNION ALL SELECT 'is a member of ' || r.rolname::pg_catalog.text
115
+ FROM pg_catalog.pg_auth_members m JOIN pg_catalog.pg_roles r ON r.oid = m.roleid, me
116
+ WHERE m.member = me.oid AND r.rolname::pg_catalog.text <> ALL ($3::pg_catalog.text[])
117
+ UNION ALL SELECT 'has settings of its own (' ||
118
+ pg_catalog.array_to_string(s.setconfig, ', ') || ')'
119
+ FROM pg_catalog.pg_db_role_setting s, me WHERE s.setrole = me.oid
120
+ UNION ALL SELECT 'owns the database' FROM pg_catalog.pg_database d, me, here
121
+ WHERE d.oid = here.oid AND d.datdba = me.oid
122
+ UNION ALL SELECT 'may create schemas'
123
+ WHERE pg_catalog.has_database_privilege($2::pg_catalog.name, pg_catalog.current_database(),
124
+ 'CREATE')
125
+ UNION ALL SELECT 'owns ' || pg_catalog.pg_describe_object(d.classid, d.objid, d.objsubid)
126
+ FROM pg_catalog.pg_shdepend d, me, here
127
+ WHERE d.refclassid = 'pg_catalog.pg_authid'::pg_catalog.regclass AND d.refobjid = me.oid
128
+ AND d.deptype = 'o' AND d.dbid IN (0, here.oid)
129
+ -- What it made for this session alone goes with its connection, closed after.
130
+ AND NOT (d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass AND d.objid IN
131
+ (SELECT oid FROM pg_catalog.pg_class WHERE relnamespace IN (SELECT oid FROM temporary)))
132
+ AND NOT (d.classid = 'pg_catalog.pg_type'::pg_catalog.regclass AND d.objid IN
133
+ (SELECT oid FROM pg_catalog.pg_type WHERE typnamespace IN (SELECT oid FROM temporary)))
134
+ AND NOT (d.classid = 'pg_catalog.pg_proc'::pg_catalog.regclass AND d.objid IN
135
+ (SELECT oid FROM pg_catalog.pg_proc WHERE pronamespace IN (SELECT oid FROM temporary)))
136
+ UNION ALL SELECT 'owns a database elsewhere' FROM pg_catalog.pg_shdepend d, me, here
137
+ WHERE d.refclassid = 'pg_catalog.pg_authid'::pg_catalog.regclass AND d.refobjid = me.oid
138
+ AND d.deptype = 'o' AND d.dbid NOT IN (0, here.oid)
139
+ UNION ALL SELECT 'is granted something on ' ||
140
+ pg_catalog.pg_describe_object(d.classid, d.objid, d.objsubid)
141
+ FROM pg_catalog.pg_shdepend d, me, here
142
+ WHERE d.refclassid = 'pg_catalog.pg_authid'::pg_catalog.regclass AND d.refobjid = me.oid
143
+ AND d.deptype = 'a' AND d.dbid IN (0, here.oid) AND NOT (
144
+ (d.classid = 'pg_catalog.pg_class'::pg_catalog.regclass AND d.objid IN
145
+ (SELECT oid FROM pg_catalog.pg_class WHERE relnamespace IN (SELECT oid FROM own)))
146
+ OR (d.classid = 'pg_catalog.pg_namespace'::pg_catalog.regclass
147
+ AND d.objid IN (SELECT oid FROM own))
148
+ OR (d.classid = 'pg_catalog.pg_default_acl'::pg_catalog.regclass AND d.objid IN
149
+ (SELECT oid FROM pg_catalog.pg_default_acl WHERE defaclnamespace IN (SELECT oid FROM own)))
150
+ OR (d.classid = 'pg_catalog.pg_database'::pg_catalog.regclass
151
+ AND d.objid IN (SELECT oid FROM here) AND EXISTS (SELECT 1 FROM own)))
152
+ UNION ALL SELECT 'owns large object ' || m.oid::pg_catalog.text
153
+ FROM pg_catalog.pg_largeobject_metadata m, me WHERE m.lomowner = me.oid
154
+ UNION ALL SELECT 'may read large object ' || m.oid::pg_catalog.text
155
+ FROM pg_catalog.pg_largeobject_metadata m, me
156
+ WHERE EXISTS (SELECT 1 FROM pg_catalog.aclexplode(m.lomacl) a WHERE a.grantee IN (0, me.oid))
157
+ UNION ALL SELECT 'may read every large object (lo_compat_privileges)'
158
+ WHERE pg_catalog.current_setting('lo_compat_privileges') = 'on'
159
+ UNION ALL SELECT 'may create in schema ' || n.nspname::pg_catalog.text
160
+ FROM pg_catalog.pg_namespace n
161
+ WHERE pg_catalog.has_schema_privilege($2::pg_catalog.name, n.oid, 'CREATE')
162
+ AND n.oid NOT IN (SELECT oid FROM temporary)
163
+ UNION ALL SELECT 'may use ' || c.oid::pg_catalog.regclass::pg_catalog.text
164
+ FROM pg_catalog.pg_class c
165
+ WHERE c.relnamespace NOT IN (SELECT oid FROM own) AND c.relnamespace NOT IN
166
+ (SELECT oid FROM catalogs) AND c.relnamespace NOT IN (SELECT oid FROM temporary)
167
+ AND c.oid NOT IN (SELECT objid FROM extension) AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
168
+ AND (pg_catalog.has_table_privilege($2::pg_catalog.name, c.oid,
169
+ (SELECT pg_catalog.string_agg(privilege, ', ') FROM privileges))
170
+ OR pg_catalog.has_any_column_privilege($2::pg_catalog.name, c.oid,
171
+ 'SELECT, INSERT, UPDATE, REFERENCES'))
172
+ UNION ALL SELECT 'may use sequence ' || c.oid::pg_catalog.regclass::pg_catalog.text
173
+ FROM pg_catalog.pg_class c
174
+ WHERE c.relkind = 'S' AND c.relnamespace NOT IN (SELECT oid FROM catalogs)
175
+ AND c.relnamespace NOT IN (SELECT oid FROM temporary)
176
+ AND c.oid NOT IN (SELECT objid FROM extension)
177
+ AND CASE WHEN c.relkind = 'S' THEN pg_catalog.has_sequence_privilege($2::pg_catalog.name,
178
+ c.oid, 'USAGE, SELECT, UPDATE') ELSE false END
179
+ UNION ALL SELECT 'may ' || p.privilege || ' ' || c.oid::pg_catalog.regclass::pg_catalog.text
180
+ FROM pg_catalog.pg_class c, privileges p
181
+ WHERE c.relnamespace IN (SELECT oid FROM own) AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
182
+ AND p.privilege <> 'SELECT'
183
+ AND pg_catalog.has_table_privilege($2::pg_catalog.name, c.oid, p.privilege) AND NOT (
184
+ (c.relname IN ('nodes', 'edges', 'vectors', 'blobs')
185
+ AND p.privilege IN ('INSERT', 'UPDATE', 'DELETE'))
186
+ OR (c.relname = 'events' AND p.privilege = 'INSERT'))
187
+ UNION ALL SELECT 'may ' || p.privilege || ' ' || c.oid::pg_catalog.regclass::pg_catalog.text ||
188
+ '.' || a.attname::pg_catalog.text
189
+ FROM pg_catalog.pg_class c JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid,
190
+ (VALUES ('INSERT'), ('UPDATE'), ('REFERENCES')) p(privilege)
191
+ WHERE c.relnamespace IN (SELECT oid FROM own) AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
192
+ AND a.attnum > 0 AND NOT a.attisdropped
193
+ AND pg_catalog.has_column_privilege($2::pg_catalog.name, c.oid, a.attnum, p.privilege)
194
+ AND NOT (
195
+ (c.relname IN ('nodes', 'edges', 'vectors', 'blobs')
196
+ AND p.privilege IN ('INSERT', 'UPDATE'))
197
+ OR (c.relname = 'events' AND p.privilege = 'INSERT')
198
+ OR (c.relname = 'meta' AND a.attname = 'value' AND p.privilege = 'UPDATE'))
199
+ UNION ALL SELECT 'may run ' || p.oid::pg_catalog.regprocedure::pg_catalog.text ||
200
+ ' as its owner (SECURITY DEFINER)'
201
+ FROM pg_catalog.pg_proc p WHERE p.prosecdef AND p.pronamespace NOT IN (SELECT oid FROM catalogs)
202
+ AND pg_catalog.has_function_privilege($2::pg_catalog.name, p.oid, 'EXECUTE')
203
+ UNION ALL SELECT 'the database has ' || extname::pg_catalog.text FROM pg_catalog.pg_extension
204
+ WHERE extname IN ('dblink', 'postgres_fdw')
205
+ UNION ALL SELECT 'a trigger the store didn''t make: ' || t.tgname::pg_catalog.text || ' on ' ||
206
+ c.relname::pg_catalog.text
207
+ FROM pg_catalog.pg_trigger t JOIN pg_catalog.pg_class c ON c.oid = t.tgrelid
208
+ WHERE c.relnamespace IN (SELECT oid FROM own) AND NOT t.tgisinternal
209
+ ) beyond ORDER BY problem`;
210
+ /**
211
+ * Refuses maintenance SQL when the role on `db` (the session's own, the
212
+ * login's), or a Cloud SQL marker it's a member of, holds anything beyond
213
+ * the allowlist.
214
+ */
215
+ export async function allowed(db, schema) {
216
+ const [{ role, markers, admin }] = (await db.query(`WITH mine AS (SELECT r.rolname::pg_catalog.text AS marker, m.admin_option FROM ` +
217
+ `pg_catalog.pg_auth_members m JOIN pg_catalog.pg_roles r ON r.oid = m.roleid WHERE ` +
218
+ `m.member = (SELECT oid FROM pg_catalog.pg_roles WHERE rolname = session_user) AND ` +
219
+ `r.rolname::pg_catalog.text = ANY ($1::pg_catalog.text[])) SELECT ` +
220
+ `session_user::pg_catalog.text AS role, (SELECT pg_catalog.array_agg(marker) FROM mine) ` +
221
+ `AS markers, (SELECT pg_catalog.array_agg(marker) FROM mine WHERE admin_option) AS admin`, [MARKERS])).rows;
222
+ const problems = (admin ?? []).map((marker) => `may grant ${marker} to others (ADMIN OPTION), and so every IAM user's reach`);
223
+ // The role holds the allowlist; a marker, every IAM user's, holds nothing at all.
224
+ for (const [who, scope, member] of [
225
+ [role, schema, MARKERS],
226
+ ...(markers ?? []).map((marker) => [marker, "", []]),
227
+ ]) {
228
+ const found = (await db.query(BEYOND, [scope, who, member])).rows;
229
+ problems.push(...found.map((row) => (who === role ? "" : `(as ${who}) `) + row.problem));
230
+ }
231
+ if (!problems.length)
232
+ return;
233
+ const shown = problems.slice(0, 8).join("; ") +
234
+ (problems.length > 8 ? `; and ${problems.length - 8} more` : "");
235
+ throw unsafe(`The maintenance role holds more than maintenance needs: it ${shown}. It must hold the ` +
236
+ `README's grants on "${schema}" and nothing else.`);
237
+ }
238
+ /**
239
+ * PGlite's check, its one session being the store's: no other schema's
240
+ * tables within reach (another store's, in this process), and no remote
241
+ * databases.
242
+ */
243
+ export async function alone(db, schema) {
244
+ const [found] = (await db.query(`SELECT (SELECT pg_catalog.array_agg(n.nspname::pg_catalog.text ORDER BY n.nspname) FROM ` +
245
+ `pg_catalog.pg_namespace n WHERE n.nspname <> $1::pg_catalog.name AND n.nspname NOT IN ` +
246
+ `('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg\\_%' AND EXISTS (SELECT ` +
247
+ `1 FROM pg_catalog.pg_class c WHERE c.relnamespace = n.oid AND c.relkind IN ('r', 'p', ` +
248
+ `'v', 'm', 'f'))) AS others, (SELECT pg_catalog.array_agg(extname::pg_catalog.text) FROM ` +
249
+ `pg_catalog.pg_extension WHERE extname IN ('dblink', 'postgres_fdw')) AS remote`, [schema])).rows;
250
+ const names = (value) => value ?? [];
251
+ if (names(found.others).length || names(found.remote).length) {
252
+ throw unsafe(`SQL here would reach beyond "${schema}" (${[...names(found.others), ...names(found.remote)].join(", ")}).`);
253
+ }
254
+ }
255
+ /** Triggers on the store's tables: none of the store's making, so none at all. */
256
+ export const triggers = (schema) => `(SELECT pg_catalog.count(*) FROM pg_catalog.pg_trigger t JOIN pg_catalog.pg_class c ON ` +
257
+ `c.oid = t.tgrelid WHERE c.relnamespace = ${`'${ident(schema).replaceAll("'", "''")}'`}::` +
258
+ `pg_catalog.regnamespace AND NOT t.tgisinternal)::pg_catalog.int4`;
@@ -22,8 +22,7 @@
22
22
  * PGlite has a single connection, so its reads wait for an open transaction.
23
23
  */
24
24
  import type { JSONSchema } from "../../../runtime/define.js";
25
- import { type IndexSpec, type Store } from "../../../runtime/store.js";
26
- import { type Row } from "./layout.js";
25
+ import { type IndexSpec, type Inspected, type Store } from "../../../runtime/store.js";
27
26
  import { type PostgresPool } from "./pool.js";
28
27
  export { type PostgresPool, postgresPool } from "./pool.js";
29
28
  export { copyTenant, dropTenant, exportTenant, type Location } from "./tenants.js";
@@ -37,12 +36,29 @@ export declare function postgresStore(options: {
37
36
  tenant?: string;
38
37
  /** Hears every SQL statement sent, for debugging. */
39
38
  trace?: (sql: string) => void;
39
+ /**
40
+ * Where maintenance SQL connects (`inspect`, a transaction's `execute`;
41
+ * see maintenance.ts): a role of its own, holding exactly maintenance's
42
+ * grants on this schema. A new connection for each statement, closed
43
+ * after, `connections` at most at once (2). On a server, raw SQL needs it.
44
+ */
45
+ maintenance?: {
46
+ url: string;
47
+ connections?: number;
48
+ };
40
49
  }): Promise<Store & {
41
50
  /** Exposes each collection as a SQL view of its schema's top-level fields. */
42
51
  describe(collections: Record<string, JSONSchema>): Promise<void>;
43
52
  index(collections: Record<string, IndexSpec[]>): Promise<void>;
44
- /** Runs a read-only query, for inspection tools; in a schema of its own only. */
45
- inspect(sql: string): Promise<Row[]>;
53
+ /**
54
+ * Runs one read-only statement, for inspection and maintenance tools; in
55
+ * a schema of its own only.
56
+ */
57
+ inspect(sql: string, params?: unknown[], options?: {
58
+ limit?: number;
59
+ timeout?: number;
60
+ bytes?: number;
61
+ }): Promise<Inspected>;
46
62
  /** Deletes everything this store holds, then closes: a tenant gone for good. */
47
63
  drop(): Promise<void>;
48
64
  }>;