@vibesdotdev/runnable 0.0.0-stage → 1.0.0-rc.1

package/dist/docs/runnable.context.docs.descriptor.js

@@ -0,0 +1,419 @@
+const contextMarkdown = `---
+title: Runnable Context
+summary: Context passing, state management, caching, and telemetry integration
+tags: [runnable, context, state, caching, telemetry]
+parent: runnable
+order: 3
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Runnable Context
+
+Context management enables stateful computation across node executions. The context system provides:
+
+- **State propagation** — Pass data between nodes without explicit edges
+- **Caching** — Memoize expensive computations across runs
+- **Telemetry integration** — Stream metrics, logs, and artifacts
+- **Cancellation** — Graceful shutdown of long-running operations
+
+## Context structure
+
+Each node execution receives a context object:
+
+\`\`\`ts
+interface NodeExecutionContext {
+  // Identification
+  runId: string;
+  nodeId: string;
+  graphId: string;
+  attempt: number;  // Retry attempt count
+
+  // Data flow
+  inputs: Record<string, unknown>;
+  sharedState: Map<string, unknown>;
+
+  // Configuration
+  config: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+
+  // Telemetry
+  telemetry: TelemetryClient;
+
+  // Lifecycle
+  cancellation: AbortSignal;
+  signal: AbortSignal;  // Alias for cancellation
+}
+\`\`\`
+
+## Shared state
+
+Shared state enables implicit data passing between nodes without explicit edge definitions:
+
+\`\`\`ts
+// Node A: Write to shared state
+async function execute(inputs, context) {
+  const result = await expensiveComputation(inputs.data);
+  context.sharedState.set('computation-result', result);
+  context.sharedState.set('metadata', { timestamp: Date.now() });
+  return { success: true };
+}
+
+// Node B: Read from shared state
+async function execute(inputs, context) {
+  const cachedResult = context.sharedState.get('computation-result');
+  if (!cachedResult) {
+    throw new Error('Expected computation-result in shared state');
+  }
+  return { cached: cachedResult };
+}
+\`\`\`
+
+### State isolation
+
+Shared state is scoped to a single run. Different runs have isolated state:
+
+\`\`\`ts
+// Run 1
+const run1 = createRunner({ url, runId: 'run-1' });
+await executor.execute({ runId: 'run-1' });
+
+// Run 2 — starts with fresh state
+const run2 = createRunner({ url, runId: 'run-2' });
+await executor.execute({ runId: 'run-2' });
+
+// run1.sharedState !== run2.sharedState
+\`\`\`
+
+## Caching
+
+The context system supports memoization of expensive operations:
+
+### Cache keys
+
+\`\`\`ts
+interface CacheKey {
+  nodeId: string;
+  configHash: string;  // Hash of node config
+  inputHash: string;   // Hash of resolved inputs
+}
+\`\`\`
+
+### Cache strategies
+
+\`\`\`ts
+interface CacheConfig {
+  enabled: boolean;
+  ttl?: number;           // Time-to-live in ms
+  maxSize?: number;       // Max entries per run
+  invalidateOn?: string[]; // Config keys that invalidate cache
+}
+\`\`\`
+
+### Example: Cached API call
+
+\`\`\`ts
+async function execute(inputs, context) {
+  const cacheKey = \`api-call:\${inputs.endpoint}:\${JSON.stringify(inputs.params)}\`;
+  
+  // Check cache
+  const cached = context.sharedState.get(cacheKey);
+  if (cached && !isExpired(cached, context.config.ttl)) {
+    context.telemetry.log('info', 'Cache hit', { cacheKey });
+    return cached.data;
+  }
+
+  // Execute and cache
+  context.telemetry.log('info', 'Cache miss', { cacheKey });
+  const result = await fetch(inputs.endpoint, { params: inputs.params });
+  
+  context.sharedState.set(cacheKey, {
+    data: result,
+    cachedAt: Date.now()
+  });
+  
+  return result;
+}
+\`\`\`
+
+## Telemetry client
+
+The telemetry client streams events to the runnable ingest endpoint:
+
+\`\`\`ts
+interface TelemetryClient {
+  // Metrics — numeric time series
+  metric(
+    key: string,
+    value: number,
+    dimensions?: Record<string, string>
+  ): void;
+
+  // Logs — structured logging
+  log(
+    level: 'debug' | 'info' | 'warn' | 'error',
+    message: string,
+    data?: unknown
+  ): void;
+
+  // Artifacts — files, models, checkpoints
+  artifact(
+    name: string,
+    mimeType: string,
+    data: string  // Base64-encoded or URL
+  ): void;
+
+  // Status updates
+  status(
+    status: 'running' | 'paused' | 'completed' | 'failed',
+    message?: string
+  ): void;
+
+  // Progress — 0.0 to 1.0
+  progress(
+    fraction: number,
+    message?: string
+  ): void;
+
+  // Custom events
+  event(
+    type: string,
+    payload?: Record<string, unknown>
+  ): void;
+}
+\`\`\`
+
+### Example: Training telemetry
+
+\`\`\`ts
+async function trainModel(inputs, context) {
+  const { epochs, lr } = context.config;
+  
+  context.telemetry.status('running', 'Starting training');
+  context.telemetry.progress(0.0, 'Initializing');
+
+  for (let epoch = 0; epoch < epochs; epoch++) {
+    // Check for cancellation
+    if (context.cancellation.aborted) {
+      context.telemetry.log('warn', 'Training cancelled');
+      return { cancelled: true };
+    }
+
+    const loss = await trainEpoch(epoch);
+    const accuracy = await evaluate();
+
+    // Stream metrics
+    context.telemetry.metric('training/loss', loss, { epoch: String(epoch) });
+    context.telemetry.metric('training/accuracy', accuracy, { epoch: String(epoch) });
+    context.telemetry.log('info', \`Epoch \${epoch} complete\`, { loss, accuracy });
+    
+    // Progress update
+    context.telemetry.progress((epoch + 1) / epochs, \`Epoch \${epoch + 1}/\${epochs}\`);
+
+    // Save checkpoint artifact
+    if (epoch % 10 === 0) {
+      const checkpoint = await serializeModel();
+      context.telemetry.artifact(
+        \`checkpoint-epoch-\${epoch}.bin\`,
+        'application/octet-stream',
+        checkpoint
+      );
+    }
+  }
+
+  context.telemetry.status('completed', 'Training complete');
+  context.telemetry.progress(1.0, 'Done');
+  
+  return { epochs, finalLoss: loss, finalAccuracy: accuracy };
+}
+\`\`\`
+
+## State persistence
+
+The \`GenericRunStateManager\` interface maintains in-memory state for SSE streaming:
+
+\`\`\`ts
+interface GenericRunStateManager {
+  // Lifecycle
+  recordStart(fields: RecordStartFields): void;
+  markDone(runId: string, ts?: number): void;
+  
+  // State updates
+  applyDispatch(runId: string, writes: GenericWrite[]): void;
+  setStatus(runId: string, status: string): void;
+  
+  // Queries
+  getRunById(runId: string): RunStateEntry | null;
+  getSnapshot(runId: string): RunStateSnapshot | null;
+  getAllRuns(): RunStateListEntry[];
+  
+  // Cache management
+  injectRun(entry: RunStateEntry): void;
+  reset(): void;
+}
+\`\`\`
+
+### Run state entry
+
+\`\`\`ts
+interface RunStateEntry {
+  id: string;
+  runnableType: string;
+  runnableId: string;
+  name: string;
+  status: string;
+  startedAt: number;
+  endedAt: number | null;
+  lastEventAt: number;
+  progress: number;
+  config: Record<string, unknown>;
+  metadata: Record<string, unknown>;
+  metrics: Map<string, TieredTimeSeries<{ value: number }>>;
+  logs: RunLogEntry[];
+  artifactCount: number;
+  done: boolean;
+}
+\`\`\`
+
+### Tiered time series
+
+Metrics use tiered aggregation for efficient long-term storage:
+
+\`\`\`ts
+const TIME_SERIES_TIERS: TierSpec[] = [
+  { intervalMs: 250, maxPoints: 10 },      // 2.5 seconds of sub-second data
+  { intervalMs: 1_000, maxPoints: 100 },   // 100 seconds of secondly data
+  { intervalMs: 10_000, maxPoints: 1_000 }, // ~2.8 hours of 10-secondly data
+  { intervalMs: 30_000, maxPoints: 10_000 }, // ~3.5 days of 30-secondly data
+  { intervalMs: 60_000, maxPoints: 100_000 }, // ~69 days of minutely data
+  { intervalMs: 600_000, maxPoints: Infinity } // 10-minutely, unbounded
+];
+\`\`\`
+
+## Cancellation
+
+Long-running nodes should respect cancellation signals:
+
+\`\`\`ts
+async function longRunningTask(inputs, context) {
+  const { signal } = context;
+  
+  for (let i = 0; i < 1000; i++) {
+    // Check cancellation before each iteration
+    if (signal.aborted) {
+      context.telemetry.log('info', 'Task cancelled');
+      return { cancelled: true, reason: signal.reason };
+    }
+    
+    await doWork(i);
+  }
+  
+  return { completed: true };
+}
+
+// External cancellation
+const controller = new AbortController();
+setTimeout(() => controller.abort('Timeout'), 30000);
+
+await executor.execute({ 
+  runId: 'run-1',
+  signal: controller.signal 
+});
+\`\`\`
+
+## WRONG patterns
+
+:::card{title="Common mistakes"}
+- ❌ **Mutating inputs** — Inputs are immutable; clone before modification
+- ❌ **Blocking the event loop** — Use async operations; don't block with sync computation
+- ❌ **Ignoring cancellation** — Always check \`signal.aborted\` in loops
+- ❌ **Unbounded state** — Don't store large objects in shared state; use artifacts
+- ❌ **Synchronous telemetry** — Telemetry calls are fire-and-forget; don't await
+:::
+
+## Example: Stateful aggregation
+
+\`\`\`ts
+async function aggregateMetrics(inputs, context) {
+  const { metricKey } = context.config;
+  
+  // Get or initialize accumulator
+  let accumulator = context.sharedState.get(\`agg:\${metricKey}\`) as {
+    sum: number;
+    count: number;
+    values: number[];
+  } || { sum: 0, count: 0, values: [] };
+  
+  // Accumulate
+  const newValue = inputs.value;
+  accumulator.sum += newValue;
+  accumulator.count += 1;
+  accumulator.values.push(newValue);
+  
+  // Keep bounded ring buffer
+  if (accumulator.values.length > 1000) {
+    accumulator.values.shift();
+  }
+  
+  // Store back
+  context.sharedState.set(\`agg:\${metricKey}\`, accumulator);
+  
+  // Emit running statistics
+  const mean = accumulator.sum / accumulator.count;
+  context.telemetry.metric(\`\${metricKey}/mean\`, mean);
+  context.telemetry.metric(\`\${metricKey}/count\`, accumulator.count);
+  
+  return { mean, count: accumulator.count };
+}
+\`\`\`
+
+## Related
+
+:::card{title="See also"}
+- [\`runnable.graphs\`](runnable.graphs) — Graph definitions, nodes, edges
+- [\`runnable.nodes\`](runnable.nodes) — Node types, execution, context, outputs
+- [\`state.ts\`](https://git.vibes.dev/vibesdotdev/framework/tree/cutover/workers/src/runnable/state.ts) — Generic run state manager
+:::
+
+## Code paths
+
+- State types: [\`runnable/src/state.ts\`](https://git.vibes.dev/vibesdotdev/framework/tree/cutover/workers/src/runnable/state.ts)
+- Runner harness: [\`runnable/src/runner.ts\`](https://git.vibes.dev/vibesdotdev/framework/tree/cutover/workers/src/runnable/runner.ts)
+- Client implementation: [\`runnable/src/client.ts\`](https://git.vibes.dev/vibesdotdev/framework/tree/cutover/workers/src/runnable/client.ts)
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'runnable.context',
+    title: 'Runnable Context',
+    summary: 'Context passing, state management, caching, and telemetry integration',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: contextMarkdown
+    },
+    parent: 'runnable',
+    order: 3,
+    tags: ['runnable', 'context', 'state', 'caching', 'telemetry'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    man: {
+        name: 'runnable.context — state and telemetry management',
+        section: 1,
+        synopsis: 'vibes man runnable.context',
+        options: [],
+        examples: [
+            {
+                description: 'Access shared state',
+                command: 'context.sharedState.get("key")'
+            },
+            {
+                description: 'Stream telemetry',
+                command: 'context.telemetry.metric("loss", 0.42)'
+            }
+        ],
+        seeAlso: ['runnable.graphs', 'runnable.nodes']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=runnable.context.docs.descriptor.js.map

package/dist/docs/runnable.context.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnable.context.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/runnable.context.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8XvB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,kBAAkB;IACtB,KAAK,EAAE,kBAAkB;IACzB,OAAO,EAAE,uEAAuE;IAChF,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,eAAe;KACvB;IACD,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC;IAC9D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;IACb,GAAG,EAAE;QACJ,IAAI,EAAE,mDAAmD;QACzD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,qBAAqB;gBAClC,OAAO,EAAE,gCAAgC;aACzC;YACD;gBACC,WAAW,EAAE,kBAAkB;gBAC/B,OAAO,EAAE,wCAAwC;aACjD;SACD;QACD,OAAO,EAAE,CAAC,iBAAiB,EAAE,gBAAgB,CAAC;KAC9C;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/runnable.graphs.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=runnable.graphs.docs.descriptor.d.ts.map

package/dist/docs/runnable.graphs.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnable.graphs.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/runnable.graphs.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAsBvE,QAAA,MAAM,UAAU,EAAE,mBA6BjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/runnable.graphs.docs.descriptor.js

@@ -0,0 +1,51 @@
+const graphsMarkdown = `---
+title: Runnable Graphs
+summary: Job graphs live in Workers; see workers.graphs
+tags: [runnable, graphs, workflows, execution, orchestration]
+parent: runnable
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Runnable Graphs
+
+Graphs of jobs are a Workers capability, not a runnable one. \`WorkersClient.runGraph\` and \`runGraphStreaming\` run \`workers/job\` nodes in dependency order with data edges, conditions, a concurrency cap and a failure policy. The earlier \`runtime.query("runnable/graph")\` executor never existed.
+
+:::card{title="See also"}
+- [\`workers.graphs\`](workers.graphs) — the graph definition, events, cancellation and refusals
+- [\`runnable.nodes\`](runnable.nodes) — Node types, execution, context, outputs
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'runnable.graphs',
+    title: 'Runnable Graphs',
+    summary: 'Job graphs live in Workers; see workers.graphs',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: graphsMarkdown
+    },
+    parent: 'runnable',
+    order: 1,
+    tags: ['runnable', 'graphs', 'workflows', 'execution', 'orchestration'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    man: {
+        name: 'runnable.graphs — moved to workers.graphs',
+        section: 1,
+        synopsis: 'vibes man runnable.graphs',
+        options: [],
+        examples: [
+            {
+                description: 'Run a job graph',
+                command: 'await workers.runGraph(definition)'
+            }
+        ],
+        seeAlso: ['workers.graphs', 'runnable.nodes']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=runnable.graphs.docs.descriptor.js.map

package/dist/docs/runnable.graphs.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnable.graphs.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/runnable.graphs.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;CAkBtB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,iBAAiB;IACrB,KAAK,EAAE,iBAAiB;IACxB,OAAO,EAAE,gDAAgD;IACzD,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,cAAc;KACtB;IACD,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,CAAC;IACvE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;IACb,GAAG,EAAE;QACJ,IAAI,EAAE,2CAA2C;QACjD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,2BAA2B;QACrC,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,iBAAiB;gBAC9B,OAAO,EAAE,oCAAoC;aAC7C;SACD;QACD,OAAO,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;KAC7C;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/runnable.nodes.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=runnable.nodes.docs.descriptor.d.ts.map

package/dist/docs/runnable.nodes.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnable.nodes.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/runnable.nodes.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAsSvE,QAAA,MAAM,UAAU,EAAE,mBAiCjB,CAAC;AAEF,eAAe,UAAU,CAAC"}