@kindgi/agents 0.0.0-bootstrap.0 → 0.1.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 (240) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +131 -2
  3. package/dist/agent-turn-flow.d.ts +57 -0
  4. package/dist/agent-turn-flow.d.ts.map +1 -0
  5. package/dist/agent-turn-flow.js +172 -0
  6. package/dist/agent-turn-flow.js.map +1 -0
  7. package/dist/conversation-binding.d.ts +111 -0
  8. package/dist/conversation-binding.d.ts.map +1 -0
  9. package/dist/conversation-binding.js +4 -0
  10. package/dist/conversation-binding.js.map +1 -0
  11. package/dist/define.d.ts +180 -0
  12. package/dist/define.d.ts.map +1 -0
  13. package/dist/define.js +361 -0
  14. package/dist/define.js.map +1 -0
  15. package/dist/errors.d.ts +62 -0
  16. package/dist/errors.d.ts.map +1 -0
  17. package/dist/errors.js +4 -0
  18. package/dist/errors.js.map +1 -0
  19. package/dist/guardrails-gate.d.ts +169 -0
  20. package/dist/guardrails-gate.d.ts.map +1 -0
  21. package/dist/guardrails-gate.js +202 -0
  22. package/dist/guardrails-gate.js.map +1 -0
  23. package/dist/handlers/budget-check.d.ts +22 -0
  24. package/dist/handlers/budget-check.d.ts.map +1 -0
  25. package/dist/handlers/budget-check.js +109 -0
  26. package/dist/handlers/budget-check.js.map +1 -0
  27. package/dist/handlers/build-initial-messages.d.ts +17 -0
  28. package/dist/handlers/build-initial-messages.d.ts.map +1 -0
  29. package/dist/handlers/build-initial-messages.js +86 -0
  30. package/dist/handlers/build-initial-messages.js.map +1 -0
  31. package/dist/handlers/compose-result.d.ts +10 -0
  32. package/dist/handlers/compose-result.d.ts.map +1 -0
  33. package/dist/handlers/compose-result.js +79 -0
  34. package/dist/handlers/compose-result.js.map +1 -0
  35. package/dist/handlers/constants.d.ts +8 -0
  36. package/dist/handlers/constants.d.ts.map +1 -0
  37. package/dist/handlers/constants.js +10 -0
  38. package/dist/handlers/constants.js.map +1 -0
  39. package/dist/handlers/context.d.ts +210 -0
  40. package/dist/handlers/context.d.ts.map +1 -0
  41. package/dist/handlers/context.js +4 -0
  42. package/dist/handlers/context.js.map +1 -0
  43. package/dist/handlers/dispatch-tools.d.ts +15 -0
  44. package/dist/handlers/dispatch-tools.d.ts.map +1 -0
  45. package/dist/handlers/dispatch-tools.js +511 -0
  46. package/dist/handlers/dispatch-tools.js.map +1 -0
  47. package/dist/handlers/errors.d.ts +133 -0
  48. package/dist/handlers/errors.d.ts.map +1 -0
  49. package/dist/handlers/errors.js +134 -0
  50. package/dist/handlers/errors.js.map +1 -0
  51. package/dist/handlers/evaluate-guardrails.d.ts +14 -0
  52. package/dist/handlers/evaluate-guardrails.d.ts.map +1 -0
  53. package/dist/handlers/evaluate-guardrails.js +128 -0
  54. package/dist/handlers/evaluate-guardrails.js.map +1 -0
  55. package/dist/handlers/final-iteration.d.ts +7 -0
  56. package/dist/handlers/final-iteration.d.ts.map +1 -0
  57. package/dist/handlers/final-iteration.js +26 -0
  58. package/dist/handlers/final-iteration.js.map +1 -0
  59. package/dist/handlers/index.d.ts +5 -0
  60. package/dist/handlers/index.d.ts.map +1 -0
  61. package/dist/handlers/index.js +41 -0
  62. package/dist/handlers/index.js.map +1 -0
  63. package/dist/handlers/model-call.d.ts +13 -0
  64. package/dist/handlers/model-call.d.ts.map +1 -0
  65. package/dist/handlers/model-call.js +136 -0
  66. package/dist/handlers/model-call.js.map +1 -0
  67. package/dist/handlers/persist-final-message.d.ts +14 -0
  68. package/dist/handlers/persist-final-message.d.ts.map +1 -0
  69. package/dist/handlers/persist-final-message.js +54 -0
  70. package/dist/handlers/persist-final-message.js.map +1 -0
  71. package/dist/handlers/persist-provenance.d.ts +12 -0
  72. package/dist/handlers/persist-provenance.d.ts.map +1 -0
  73. package/dist/handlers/persist-provenance.js +34 -0
  74. package/dist/handlers/persist-provenance.js.map +1 -0
  75. package/dist/handlers/persist-user-message.d.ts +15 -0
  76. package/dist/handlers/persist-user-message.d.ts.map +1 -0
  77. package/dist/handlers/persist-user-message.js +59 -0
  78. package/dist/handlers/persist-user-message.js.map +1 -0
  79. package/dist/handlers/public-types.d.ts +201 -0
  80. package/dist/handlers/public-types.d.ts.map +1 -0
  81. package/dist/handlers/public-types.js +4 -0
  82. package/dist/handlers/public-types.js.map +1 -0
  83. package/dist/handlers/rehydrate.d.ts +8 -0
  84. package/dist/handlers/rehydrate.d.ts.map +1 -0
  85. package/dist/handlers/rehydrate.js +94 -0
  86. package/dist/handlers/rehydrate.js.map +1 -0
  87. package/dist/handlers/render-prompt.d.ts +12 -0
  88. package/dist/handlers/render-prompt.d.ts.map +1 -0
  89. package/dist/handlers/render-prompt.js +41 -0
  90. package/dist/handlers/render-prompt.js.map +1 -0
  91. package/dist/handlers/resolve-tools.d.ts +10 -0
  92. package/dist/handlers/resolve-tools.d.ts.map +1 -0
  93. package/dist/handlers/resolve-tools.js +55 -0
  94. package/dist/handlers/resolve-tools.js.map +1 -0
  95. package/dist/handlers/result-shape.d.ts +94 -0
  96. package/dist/handlers/result-shape.d.ts.map +1 -0
  97. package/dist/handlers/result-shape.js +19 -0
  98. package/dist/handlers/result-shape.js.map +1 -0
  99. package/dist/handlers/run-retrievals.d.ts +10 -0
  100. package/dist/handlers/run-retrievals.d.ts.map +1 -0
  101. package/dist/handlers/run-retrievals.js +64 -0
  102. package/dist/handlers/run-retrievals.js.map +1 -0
  103. package/dist/handlers/run-snapshot.d.ts +4 -0
  104. package/dist/handlers/run-snapshot.d.ts.map +1 -0
  105. package/dist/handlers/run-snapshot.js +26 -0
  106. package/dist/handlers/run-snapshot.js.map +1 -0
  107. package/dist/handlers/setup.d.ts +25 -0
  108. package/dist/handlers/setup.d.ts.map +1 -0
  109. package/dist/handlers/setup.js +231 -0
  110. package/dist/handlers/setup.js.map +1 -0
  111. package/dist/handlers/structured-output.d.ts +38 -0
  112. package/dist/handlers/structured-output.d.ts.map +1 -0
  113. package/dist/handlers/structured-output.js +89 -0
  114. package/dist/handlers/structured-output.js.map +1 -0
  115. package/dist/handlers/tool-errors.d.ts +56 -0
  116. package/dist/handlers/tool-errors.d.ts.map +1 -0
  117. package/dist/handlers/tool-errors.js +73 -0
  118. package/dist/handlers/tool-errors.js.map +1 -0
  119. package/dist/handlers/tool-hitl.d.ts +45 -0
  120. package/dist/handlers/tool-hitl.d.ts.map +1 -0
  121. package/dist/handlers/tool-hitl.js +81 -0
  122. package/dist/handlers/tool-hitl.js.map +1 -0
  123. package/dist/handlers/turn-environment.d.ts +26 -0
  124. package/dist/handlers/turn-environment.d.ts.map +1 -0
  125. package/dist/handlers/turn-environment.js +154 -0
  126. package/dist/handlers/turn-environment.js.map +1 -0
  127. package/dist/hitl-policy.d.ts +45 -0
  128. package/dist/hitl-policy.d.ts.map +1 -0
  129. package/dist/hitl-policy.js +74 -0
  130. package/dist/hitl-policy.js.map +1 -0
  131. package/dist/index.d.ts +31 -0
  132. package/dist/index.d.ts.map +1 -0
  133. package/dist/index.js +19 -0
  134. package/dist/index.js.map +1 -0
  135. package/dist/invoke.d.ts +36 -0
  136. package/dist/invoke.d.ts.map +1 -0
  137. package/dist/invoke.js +228 -0
  138. package/dist/invoke.js.map +1 -0
  139. package/dist/migrations-dir.d.ts +11 -0
  140. package/dist/migrations-dir.d.ts.map +1 -0
  141. package/dist/migrations-dir.js +14 -0
  142. package/dist/migrations-dir.js.map +1 -0
  143. package/dist/project-run-result.d.ts +23 -0
  144. package/dist/project-run-result.d.ts.map +1 -0
  145. package/dist/project-run-result.js +116 -0
  146. package/dist/project-run-result.js.map +1 -0
  147. package/dist/prompt.d.ts +83 -0
  148. package/dist/prompt.d.ts.map +1 -0
  149. package/dist/prompt.js +119 -0
  150. package/dist/prompt.js.map +1 -0
  151. package/dist/provenance-emit.d.ts +44 -0
  152. package/dist/provenance-emit.d.ts.map +1 -0
  153. package/dist/provenance-emit.js +51 -0
  154. package/dist/provenance-emit.js.map +1 -0
  155. package/dist/registry.d.ts +38 -0
  156. package/dist/registry.d.ts.map +1 -0
  157. package/dist/registry.js +125 -0
  158. package/dist/registry.js.map +1 -0
  159. package/dist/retrieval.d.ts +47 -0
  160. package/dist/retrieval.d.ts.map +1 -0
  161. package/dist/retrieval.js +155 -0
  162. package/dist/retrieval.js.map +1 -0
  163. package/dist/run-snapshot-binding.d.ts +77 -0
  164. package/dist/run-snapshot-binding.d.ts.map +1 -0
  165. package/dist/run-snapshot-binding.js +4 -0
  166. package/dist/run-snapshot-binding.js.map +1 -0
  167. package/dist/schema.d.ts +497 -0
  168. package/dist/schema.d.ts.map +1 -0
  169. package/dist/schema.js +133 -0
  170. package/dist/schema.js.map +1 -0
  171. package/dist/streaming.d.ts +118 -0
  172. package/dist/streaming.d.ts.map +1 -0
  173. package/dist/streaming.js +17 -0
  174. package/dist/streaming.js.map +1 -0
  175. package/dist/tenant-policy.d.ts +16 -0
  176. package/dist/tenant-policy.d.ts.map +1 -0
  177. package/dist/tenant-policy.js +77 -0
  178. package/dist/tenant-policy.js.map +1 -0
  179. package/dist/types.d.ts +435 -0
  180. package/dist/types.d.ts.map +1 -0
  181. package/dist/types.js +4 -0
  182. package/dist/types.js.map +1 -0
  183. package/dist/versioning.d.ts +29 -0
  184. package/dist/versioning.d.ts.map +1 -0
  185. package/dist/versioning.js +58 -0
  186. package/dist/versioning.js.map +1 -0
  187. package/migrations/0000_sparkling_talkback.sql +18 -0
  188. package/migrations/0001_tired_warhawk.sql +16 -0
  189. package/migrations/0002_violet_ezekiel.sql +2 -0
  190. package/migrations/meta/0000_snapshot.json +172 -0
  191. package/migrations/meta/0001_snapshot.json +275 -0
  192. package/migrations/meta/0002_snapshot.json +287 -0
  193. package/migrations/meta/_journal.json +27 -0
  194. package/package.json +76 -4
  195. package/src/agent-turn-flow.ts +183 -0
  196. package/src/conversation-binding.ts +147 -0
  197. package/src/define.ts +572 -0
  198. package/src/errors.ts +80 -0
  199. package/src/guardrails-gate.ts +342 -0
  200. package/src/handlers/budget-check.ts +143 -0
  201. package/src/handlers/build-initial-messages.ts +103 -0
  202. package/src/handlers/compose-result.ts +90 -0
  203. package/src/handlers/constants.ts +10 -0
  204. package/src/handlers/context.ts +226 -0
  205. package/src/handlers/dispatch-tools.ts +633 -0
  206. package/src/handlers/errors.ts +282 -0
  207. package/src/handlers/evaluate-guardrails.ts +153 -0
  208. package/src/handlers/final-iteration.ts +30 -0
  209. package/src/handlers/index.ts +63 -0
  210. package/src/handlers/model-call.ts +151 -0
  211. package/src/handlers/persist-final-message.ts +67 -0
  212. package/src/handlers/persist-provenance.ts +39 -0
  213. package/src/handlers/persist-user-message.ts +70 -0
  214. package/src/handlers/public-types.ts +209 -0
  215. package/src/handlers/rehydrate.ts +161 -0
  216. package/src/handlers/render-prompt.ts +46 -0
  217. package/src/handlers/resolve-tools.ts +68 -0
  218. package/src/handlers/result-shape.ts +113 -0
  219. package/src/handlers/run-retrievals.ts +77 -0
  220. package/src/handlers/run-snapshot.ts +44 -0
  221. package/src/handlers/setup.ts +269 -0
  222. package/src/handlers/structured-output.ts +117 -0
  223. package/src/handlers/tool-errors.ts +122 -0
  224. package/src/handlers/tool-hitl.ts +126 -0
  225. package/src/handlers/turn-environment.ts +191 -0
  226. package/src/hitl-policy.ts +128 -0
  227. package/src/index.ts +154 -0
  228. package/src/invoke.ts +299 -0
  229. package/src/migrations-dir.ts +17 -0
  230. package/src/project-run-result.ts +131 -0
  231. package/src/prompt.ts +185 -0
  232. package/src/provenance-emit.ts +100 -0
  233. package/src/registry.ts +164 -0
  234. package/src/retrieval.ts +219 -0
  235. package/src/run-snapshot-binding.ts +87 -0
  236. package/src/schema.ts +154 -0
  237. package/src/streaming.ts +153 -0
  238. package/src/tenant-policy.ts +78 -0
  239. package/src/types.ts +453 -0
  240. package/src/versioning.ts +77 -0
@@ -0,0 +1,155 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (C) 2026 Kindgi Inc.
3
+ /**
4
+ * Execute every retrieval intent declared on the agent against the
5
+ * current conversation's scope. Returns retrieved facts paired with
6
+ * the intent that pulled them, so downstream provenance can attribute
7
+ * each fact to its retrieval declaration.
8
+ *
9
+ * Retrieval modes:
10
+ * - `mode: 'keyword'` — `searchByKeyword` with the user's message
11
+ * as the query (full-text search in the memory implementation).
12
+ * - `mode: 'semantic'` — `searchBySemantic` with the user's message
13
+ * embedded. Requires `bindings.embeddingRegistry`; without one,
14
+ * the semantic search is silently skipped.
15
+ * - `mode: 'both'` — run both, merge results, dedup by fact id
16
+ * with keyword score preserved.
17
+ * - `mode` omitted — `listFacts` scoped + typed, latest-first.
18
+ * No query needed; useful for "always pull the current
19
+ * working-memory snapshot."
20
+ */
21
+ export async function runRetrievals(agent, conversation, conversationId, userMessage, bindings) {
22
+ const out = [];
23
+ for (const intent of agent.retrieval) {
24
+ for (const type of intent.types) {
25
+ const one = await runOneIntent(conversation, conversationId, userMessage, intent, type, bindings);
26
+ if (one.kind === 'err')
27
+ return one;
28
+ out.push(...one.value);
29
+ }
30
+ }
31
+ return { kind: 'ok', value: out };
32
+ }
33
+ /**
34
+ * Format retrieved facts as a system-role message the model can read
35
+ * as background context. Kept structural (fact headers + JSON content)
36
+ * rather than freeform prose — models handle discriminable fact
37
+ * boundaries better than blended narrative.
38
+ */
39
+ export function formatRetrievedForPrompt(facts) {
40
+ if (facts.length === 0)
41
+ return '';
42
+ const parts = ['[Retrieved context — background facts for this turn]', ''];
43
+ for (const { fact, intent, score } of facts) {
44
+ const header = `## Fact type=${fact.type} id=${fact.id} version=${fact.version}${score !== undefined ? ` score=${score.toFixed(3)}` : ''} scope=${intent.scope}`;
45
+ parts.push(header);
46
+ parts.push(stringifyContent(fact.content));
47
+ parts.push('');
48
+ }
49
+ return parts.join('\n').trim();
50
+ }
51
+ // ============ internals ============
52
+ async function runOneIntent(conversation, conversationId, userMessage, intent, type, bindings) {
53
+ const limit = intent.limit ?? 10;
54
+ const tenantId = conversation.tenantId;
55
+ const scope = scopeFilter(intent, conversation, conversationId);
56
+ if (intent.mode === undefined) {
57
+ return await listMode(bindings.memory, tenantId, type, scope, limit, intent);
58
+ }
59
+ const doKeyword = intent.mode === 'keyword' || intent.mode === 'both';
60
+ const doSemantic = (intent.mode === 'semantic' || intent.mode === 'both') &&
61
+ bindings.embeddingRegistry !== undefined;
62
+ const results = [];
63
+ if (doKeyword) {
64
+ const kw = await bindings.memory.searchByKeyword({
65
+ tenantId,
66
+ query: userMessage,
67
+ type,
68
+ ...(scope !== undefined && { scope }),
69
+ topK: limit,
70
+ });
71
+ if (kw.kind === 'err')
72
+ return persistErr('runOneIntent.keyword', kw.error);
73
+ results.push(...kw.value.map((h) => hitToRetrieved(h, intent)));
74
+ }
75
+ if (doSemantic && bindings.embeddingRegistry !== undefined) {
76
+ const sem = await bindings.memory.searchBySemantic({
77
+ tenantId,
78
+ query: userMessage,
79
+ embeddingRegistry: bindings.embeddingRegistry,
80
+ ...(bindings.embeddingModel !== undefined && { embeddingModel: bindings.embeddingModel }),
81
+ type,
82
+ ...(scope !== undefined && { scope }),
83
+ topK: limit,
84
+ });
85
+ if (sem.kind === 'err')
86
+ return persistErr('runOneIntent.semantic', sem.error);
87
+ results.push(...sem.value.map((h) => hitToRetrieved(h, intent)));
88
+ }
89
+ return { kind: 'ok', value: dedupById(results).slice(0, limit) };
90
+ }
91
+ async function listMode(memory, tenantId, type, scope, limit, intent) {
92
+ const listed = await memory.listFacts({
93
+ tenantId,
94
+ type,
95
+ ...(scope !== undefined && { scope }),
96
+ limit,
97
+ latestOnly: true,
98
+ });
99
+ if (listed.kind === 'err')
100
+ return persistErr('runOneIntent.list', listed.error);
101
+ return {
102
+ kind: 'ok',
103
+ value: listed.value.map((f) => ({ fact: f, intent })),
104
+ };
105
+ }
106
+ function scopeFilter(intent, conversation, conversationId) {
107
+ if (intent.scope === 'same-conversation') {
108
+ return { threadId: conversationId };
109
+ }
110
+ if (intent.scope === 'same-project') {
111
+ const projectId = conversation.scope.projectId;
112
+ // If the conversation has no project scope, treat as tenant-wide
113
+ // rather than empty-result — the intent still applies conceptually.
114
+ if (projectId === undefined)
115
+ return undefined;
116
+ return { projectId: projectId };
117
+ }
118
+ return undefined;
119
+ }
120
+ function hitToRetrieved(hit, intent) {
121
+ return {
122
+ fact: hit.fact,
123
+ intent,
124
+ score: hit.score,
125
+ };
126
+ }
127
+ function dedupById(facts) {
128
+ const seen = new Set();
129
+ const out = [];
130
+ for (const f of facts) {
131
+ if (seen.has(f.fact.id))
132
+ continue;
133
+ seen.add(f.fact.id);
134
+ out.push(f);
135
+ }
136
+ return out;
137
+ }
138
+ function stringifyContent(content) {
139
+ if (content === undefined)
140
+ return '(no content)';
141
+ if (typeof content === 'string')
142
+ return content;
143
+ return JSON.stringify(content, null, 2);
144
+ }
145
+ function persistErr(step, cause) {
146
+ return {
147
+ kind: 'err',
148
+ error: {
149
+ code: 'persistence-error',
150
+ message: `Agents operation "${step}" failed`,
151
+ cause,
152
+ },
153
+ };
154
+ }
155
+ //# sourceMappingURL=retrieval.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"retrieval.js","sourceRoot":"","sources":["../src/retrieval.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,77 @@
1
+ import type { ProjectId, Result, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
2
+ import type { PersistenceError } from './errors.js';
3
+ import type { AgentId, ConversationId } from './types.js';
4
+ /**
5
+ * Input for `RunSnapshotBinding.write` — the InvokeAgentInput envelope
6
+ * captured at run-start so `resumeAgentTurn(runId)` can rebuild the
7
+ * same TurnContext after a kernel waitpoint resolves. Idempotent under
8
+ * flow replay via the runId primary key.
9
+ */
10
+ export interface RunSnapshotWriteInput {
11
+ readonly runId: RunId;
12
+ readonly tenantId: TenantId;
13
+ readonly projectId: ProjectId;
14
+ readonly agentId: AgentId;
15
+ readonly agentVersion: Semver;
16
+ readonly conversationId: ConversationId;
17
+ readonly userMessage: string;
18
+ /** The turn's prompt parameters — a resumed turn renders its instructions with them. */
19
+ readonly parameters?: Readonly<Record<string, string | number | boolean>>;
20
+ /** The turn's structured input (`InvokeAgentInput.input`); same persistence contract. */
21
+ readonly input?: unknown;
22
+ readonly participantId?: string;
23
+ readonly dryRun?: boolean;
24
+ /**
25
+ * Optional serialized Principal (authorization). Impls MUST persist
26
+ * unchanged and return it verbatim from `read` so resumed turns get
27
+ * the same enforcement context. Wire shape is opaque to this layer.
28
+ */
29
+ readonly principal?: unknown;
30
+ /**
31
+ * Optional authz config (`{ fgaApiUrl }`). Same persistence contract
32
+ * as `principal`.
33
+ */
34
+ readonly authz?: unknown;
35
+ }
36
+ /**
37
+ * Persisted run-snapshot row returned by `RunSnapshotBinding.read`.
38
+ * Field shape mirrors the `agent_run_snapshots` table but is expressed
39
+ * as a plain interface so alternative impls (non-Postgres) match the
40
+ * same contract.
41
+ */
42
+ export interface RunSnapshotRecord {
43
+ readonly runId: RunId;
44
+ readonly tenantId: TenantId;
45
+ readonly projectId: ProjectId;
46
+ readonly agentId: AgentId;
47
+ readonly agentVersion: Semver;
48
+ readonly conversationId: ConversationId;
49
+ readonly userMessage: string;
50
+ readonly parameters?: Readonly<Record<string, string | number | boolean>>;
51
+ readonly input?: unknown;
52
+ readonly participantId?: string;
53
+ readonly dryRun: boolean;
54
+ readonly principal?: unknown;
55
+ readonly authz?: unknown;
56
+ readonly createdAt: Timestamp;
57
+ }
58
+ /**
59
+ * `RunSnapshotBinding` — the public seam between @kindgi/agents and
60
+ * whatever run-snapshot store a deployment plugs in (the Kindgi
61
+ * runtime ships a Postgres-backed one; alternatives possible).
62
+ *
63
+ * Ownership: @kindgi/agents (not the kernel). Kernel schemas stay
64
+ * generic across all flow runners; agent-specific reconstruction
65
+ * context lives at this layer.
66
+ *
67
+ * `write` is best-effort — a failure does NOT fail the turn (the run
68
+ * already started; snapshot-write hiccups shouldn't block execution).
69
+ * Callers of a resumed turn get `run-snapshot-missing` and know the
70
+ * run is unrecoverable. Impls MUST be idempotent under kernel replay
71
+ * (ON CONFLICT DO NOTHING on the runId PK, or equivalent).
72
+ */
73
+ export interface RunSnapshotBinding {
74
+ write(input: RunSnapshotWriteInput): Promise<Result<void, PersistenceError>>;
75
+ read(tenantId: TenantId, runId: RunId): Promise<Result<RunSnapshotRecord | null, PersistenceError>>;
76
+ }
77
+ //# sourceMappingURL=run-snapshot-binding.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run-snapshot-binding.d.ts","sourceRoot":"","sources":["../src/run-snapshot-binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAC1E,yFAAyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAE7E,IAAI,CACF,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,MAAM,CAAC,iBAAiB,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;CAChE"}
@@ -0,0 +1,4 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // Copyright (C) 2026 Kindgi Inc.
3
+ export {};
4
+ //# sourceMappingURL=run-snapshot-binding.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run-snapshot-binding.js","sourceRoot":"","sources":["../src/run-snapshot-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}