@warpmetrics/warp 0.0.46 → 0.0.47

package/README.md

@@ -158,6 +158,123 @@ Manually flush pending events. Events are auto-flushed on an interval and on pro
 await flush();
 ```
 
+## Entity Model
+
+Six entity types form an execution DAG. Every entity is created client-side, batched, and sent atomically to `POST /v1/events`.
+
+### Entities
+
+| Entity | Prefix | Purpose |
+|--------|--------|---------|
+| **Run** | `wm_run_` | Top-level execution unit. Has a label, opts, and startedAt. |
+| **Group** | `wm_grp_` | Logical phase/step inside a run or group. Nestable. |
+| **Call** | `wm_call_` | Single LLM API call with tokens, cost, duration. Always a leaf node. Created by `call()` (intercepted) or `trace()` (manual) — same entity either way. |
+| **Link** | — | Parent→child edge. Connects runs/groups to their children. No ID of its own. |
+| **Outcome** | `wm_oc_` | Named result recorded on a run, group, or call. |
+| **Act** | `wm_act_` | Action taken on an outcome. Can trigger follow-up runs. |
+
+IDs are monotonic ULIDs: `wm_{prefix}_{ulid}`.
+
+### Hierarchy (Links)
+
+```
+Run ──→ Group ──→ Group  (nestable)
+ │        │
+ │        └──→ Call
+ └──→ Call
+```
+
+- Links are directional (parent → child)
+- A child has exactly one parent
+- Calls are always leaf nodes
+- Groups can nest arbitrarily
+
+### Outcome → Act → Run chain
+
+The mechanism for multi-step workflows:
+
+```
+Run / Group / Call
+     │
+     └─ outcome("Needs Review")     → Outcome  (refId = entity)
+              │
+              └─ act("Review")      → Act      (refId = outcome)
+                       │
+                       └─ run(act)  → Run      (refId = act)
+```
+
+- An outcome references exactly one entity (run, group, or call) via `refId`
+- An act references exactly one outcome via `refId`
+- A follow-up run references exactly one act via `refId`
+- Multiple outcomes can target the same entity
+- Multiple acts can target the same outcome
+- An act with a follow-up run is "resolved"; without one it's "pending"
+
+### Runner pattern
+
+A graph runner processes the entity model by declaring a workflow graph and walking it:
+
+```
+define graph:
+  ActName → {
+    executor: string | null     # null = phase group (auto-transition)
+    results: {
+      resultType → [{ outcome, on?, next? }]
+    }
+  }
+
+define states:
+  OutcomeName → BoardColumn
+
+algorithm processRun(run):
+  act = findPendingAct(run)
+  while act:
+    node = graph[act.name]
+
+    if node.executor == null:                    # phase group
+      group = createGroup(run, node.label)
+      result = { type: "created" }
+    else:                                        # work act
+      result = execute(node.executor, run, act)
+
+    edges = node.results[result.type]            # [{outcome, on?, next?}]
+    for edge in edges:
+      container = resolveContainer(edge.on, run) # run or phase group
+      oc = recordOutcome(container, edge.outcome)
+      if edge.next:
+        act = emitAct(oc, edge.next, result.nextActOpts)
+
+    syncBoard(run, states[lastOutcome])
+
+    if not edge.next:
+      break                                      # terminal
+```
+
+Key concepts:
+
+- **Phase groups** (`executor: null`): create a group, auto-resolve with `created`, and immediately transition to the next act. No external work.
+- **Work acts** (`executor: string`): call an executor, get a typed result, map it to graph edges.
+- **`findPendingAct`**: walk the run's outcomes and group outcomes (newest first) to find the last act with no follow-up run.
+- **`resolveContainer`**: outcomes target either the top-level run (for board tracking) or a phase group (for scoped tracking). A single result can produce outcomes on both.
+- **Board sync**: map the last outcome name to a board column via the `states` map.
+
+### Event batch format
+
+All entities are sent atomically in a single `POST /v1/events` payload:
+
+```json
+{
+  "runs":     [{ "id", "label", "opts", "refId", "startedAt" }],
+  "groups":   [{ "id", "label", "opts", "startedAt" }],
+  "calls":    [{ "id", "provider", "model", "messages", "response", "tokens", "duration", ... }],
+  "links":    [{ "parentId", "childId", "type", "timestamp" }],
+  "outcomes": [{ "id", "refId", "name", "opts", "timestamp" }],
+  "acts":     [{ "id", "refId", "name", "opts", "timestamp" }]
+}
+```
+
+The body is base64-encoded: `{ "d": "<base64>" }`.
+
 ## Supported providers
 
 - **OpenAI** — `client.chat.completions.create()` and `client.responses.create()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpmetrics/warp",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "description": "Measure your agents, not your LLM calls.",
   "type": "module",
   "main": "src/index.js",

package/src/core/query.js

@@ -0,0 +1,107 @@
+// Warpmetrics SDK — Query API
+// Read path: query runs and retrieve run details.
+
+import { getConfig } from './transport.js';
+
+function headers() {
+  const { apiKey } = getConfig();
+  return {
+    'Content-Type': 'application/json',
+    ...(apiKey && { Authorization: `Bearer ${apiKey}` }),
+  };
+}
+
+function projectHeader() {
+  const { projectId } = getConfig();
+  if (projectId) return { 'X-Project-Id': projectId };
+  return {};
+}
+
+/**
+ * Query runs with filters, sorting, and latest outcome resolution.
+ *
+ * @param {object} params
+ * @param {object} [params.filter]  - Filter conditions (opts.*, latest.*, column)
+ * @param {object} [params.sort]    - Sort order (field: "asc"|"desc")
+ * @param {boolean} [params.latest] - Include latest outcome per run
+ * @param {number} [params.limit]   - Max runs to return (default 50, max 200)
+ * @param {string} [params.since]   - ISO 8601 timestamp lower bound
+ * @returns {Promise<{ runs: object[], total: number, hasMore: boolean }>}
+ */
+export async function query(params) {
+  const { baseUrl } = getConfig();
+  const res = await fetch(`${baseUrl}/v1/query`, {
+    method: 'POST',
+    headers: { ...headers(), ...projectHeader() },
+    body: JSON.stringify(params),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: { message: res.statusText } }));
+    throw new Error(`warp.query failed: ${err.error?.message || res.status}`);
+  }
+  const json = await res.json();
+  return json.data || json;
+}
+
+/**
+ * Get a single run by ID with full history.
+ *
+ * @param {string} runId - The run ID (wm_run_*)
+ * @returns {Promise<object>} - Full run data with outcomes, acts, groups, calls, links
+ */
+export async function get(runId) {
+  const { baseUrl } = getConfig();
+  const res = await fetch(`${baseUrl}/v1/runs/${runId}?fields=full`, {
+    headers: { ...headers(), ...projectHeader() },
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: { message: res.statusText } }));
+    throw new Error(`warp.get failed: ${err.error?.message || res.status}`);
+  }
+  const json = await res.json();
+  return json.data || json;
+}
+
+/**
+ * Get all pending runs targeted at a specific graph, sorted by priority.
+ *
+ * @param {string} graphName - The graph name to query inbox for
+ * @returns {Promise<{ runs: object[], total: number, hasMore: boolean }>}
+ */
+export function inbox(graphName) {
+  return query({
+    filter: { 'opts.to': graphName, 'latest.status': 'pending' },
+    sort: { 'opts.priority': 'desc', created_at: 'asc' },
+    latest: true,
+  });
+}
+
+/**
+ * Check if an effect has been committed (for idempotency).
+ *
+ * @param {string} effectKey - The effect key to check
+ * @returns {Promise<object|null>} - The existing run or null
+ */
+export async function exists(effectKey) {
+  const result = await query({
+    filter: { 'opts.type': `effect.${effectKey}` },
+    latest: true,
+    limit: 1,
+  });
+  return result.runs.length > 0 ? result.runs[0] : null;
+}
+
+/**
+ * Get latest checkpoint for a run (for resume).
+ *
+ * @param {string} runId - The parent run ID
+ * @returns {Promise<object|null>} - The checkpoint outcome or null
+ */
+export async function checkpoint(runId) {
+  const result = await query({
+    filter: { 'opts.type': `${runId}.checkpoint` },
+    latest: true,
+    limit: 1,
+  });
+  return result.runs.length > 0 ? result.runs[0].latestOutcome : null;
+}

package/src/index.js

@@ -22,3 +22,4 @@ export { act } from './trace/act.js';
 export { reserve } from './core/reserve.js';
 export { ref } from './trace/ref.js';
 export { flush } from './core/transport.js';
+export { query, get, inbox, exists, checkpoint } from './core/query.js';