route one many

Author: alexanderkirtzel

.changeset/route-one-many.md

@@ -0,0 +1,12 @@
+---
+'@walkeros/core': minor
+'@walkeros/collector': minor
+'@walkeros/cli': patch
+'@walkeros/mcp': patch
+---
+
+Route grammar: rename `case` to `one` (first-match dispatch) and add `many`
+(all-match parallel fan-out, pre-collector only). `many` terminates the main
+chain and is rejected at post-collector positions (`destination.before`,
+`destination.next`); use multiple destinations for post-collector fan-out.
+`RouteCaseConfig` is renamed to `RouteOneConfig`; no aliases.

.changeset/store-cache-and-memory-removal.md

@@ -0,0 +1,19 @@
+---
+'@walkeros/core': minor
+'@walkeros/collector': minor
+'@walkeros/mcp': minor
+'@walkeros/server-transformer-file': patch
+---
+
+Add `Flow.Store.cache` for store-level caching: read-through + write-through
+wrapper with single-flight dedup, recursive composition via `cache.store`, and
+per-wrapper counters. `CacheRule` is now a discriminated union
+(`EventCacheRule | StoreCacheRule`); schema rejects inert fields in store
+contexts.
+
+Built-in `__cache` upgraded with LRU, `maxEntries: 10000`, batched eviction, and
+active TTL sweep.
+
+**Breaking:** `@walkeros/store-memory` is removed. Its logic is absorbed into
+`__cache`. Migration: drop the store declaration, or omit `cache.store` to use
+the built-in tier. `flow_validate` flags legacy references.

.claude-plugin/plugin.json

@@ -31,6 +31,7 @@
     "skills/walkeros-understanding-development",
     "skills/walkeros-using-logger",
     "skills/walkeros-using-cli",
+    "skills/walkeros-using-store-cache",
     "skills/walkeros-using-transformer-ga4",
     "skills/walkeros-create-destination",
     "skills/walkeros-create-source",

AGENT.md

@@ -29,6 +29,7 @@ Learn the concepts before coding:
 | [understanding-stores](skills/understanding-stores/SKILL.md)             | Store interface, $store. wiring, lifecycle                                 |
 | [using-logger](skills/using-logger/SKILL.md)                             | Logger access, DRY principles, when to log                                 |
 | [using-step-examples](skills/using-step-examples/SKILL.md)               | Step examples lifecycle, Three Type Zones, testing                         |
+| [using-store-cache](skills/walkeros-using-store-cache/SKILL.md)          | Recipes for store-level cache, multi-tier composition                      |
 | [using-transformer-ga4](skills/walkeros-using-transformer-ga4/SKILL.md)  | Wire `@walkeros/transformer-ga4`, override mappings, troubleshoot decoding |
 
 ## Creating Things

packages/cli/src/commands/bundle/bundler.ts

@@ -108,7 +108,7 @@ function generateInlineCode(
   inline: Flow.Code,
   config: object,
   env?: object,
-  chains?: { before?: Transformer.RouteSpec; next?: Transformer.RouteSpec },
+  chains?: { before?: Transformer.Route; next?: Transformer.Route },
   isDestination?: boolean,
 ): string {
   const pushFn = inline.push.replace('$code:', '');

packages/cli/src/commands/push/__tests__/simulate-isolation.test.ts

@@ -4,36 +4,80 @@ import type {
   Transformer,
   WalkerOS,
 } from '@walkeros/core';
-import { createIngest, createMockLogger } from '@walkeros/core';
+import { createIngest, createMockLogger, getNextSteps } from '@walkeros/core';
 import {
   destinationInit,
   destinationPush,
   transformerInit,
   transformerPush,
   runTransformerChain,
-  walkChain,
-  extractTransformerNextMap,
 } from '@walkeros/collector';
-import { compileNext, resolveNext } from '@walkeros/core';
 
 /**
- * Resolve a `RouteSpec` to the static form expected by `walkChain` in these
- * fixture tests. Conditional shapes (`case` / `gate`) resolve through
- * `resolveNext` with an empty context, surfacing the result the engine would
- * compute for a request with no ingest or event.
+ * Local mirror of the collector's internal chain walker. The collector no
+ * longer exports `walkChain` from its public surface (Task 5.1 hard cut), so
+ * these fixture tests carry their own minimal walker for resolving before
+ * chains to ordered transformer-id arrays.
  */
-function staticChain(
-  spec: Transformer.RouteSpec | undefined,
-): string | string[] | undefined {
-  if (spec === undefined) return undefined;
-  return resolveNext(compileNext(spec)) ?? undefined;
+function localWalkChain(
+  startId: string | string[] | undefined,
+  transformers: Transformer.Transformers,
+): string[] {
+  if (!startId) return [];
+  if (Array.isArray(startId)) return startId;
+
+  const chain: string[] = [];
+  const visited = new Set<string>();
+  let current: string | undefined = startId;
+
+  while (current && transformers[current]) {
+    if (visited.has(current)) break;
+    visited.add(current);
+    chain.push(current);
+
+    const next: Transformer.Route | undefined =
+      transformers[current].config?.next;
+    if (typeof next === 'string') {
+      current = next;
+      continue;
+    }
+    if (
+      Array.isArray(next) &&
+      next.every((entry) => typeof entry === 'string')
+    ) {
+      for (const id of next) chain.push(id);
+      break;
+    }
+    break;
+  }
+
+  return chain;
+}
+
+/**
+ * Resolve a Route to an ordered chain of transformer ids. Uses the public
+ * `getNextSteps` to compute entry points, then walks `.next` links.
+ */
+function resolveChain(
+  spec: Transformer.Route | undefined,
+  transformers: Transformer.Transformers,
+): string[] {
+  if (spec === undefined) return [];
+  if (typeof spec === 'string') return localWalkChain(spec, transformers);
+  if (Array.isArray(spec) && spec.every((entry) => typeof entry === 'string')) {
+    return localWalkChain(spec, transformers);
+  }
+  const ids = getNextSteps(spec);
+  if (ids.length === 0) return [];
+  if (ids.length === 1) return localWalkChain(ids[0], transformers);
+  return ids;
 }
 
 /**
  * Tests for before-chain execution in transformer simulation.
  *
- * Validates the pattern: resolve before chain -> run via runTransformerChain
- * -> then call transformerPush on the main transformer.
+ * Validates the pattern: resolve before chain (via `resolveChain`) -> run via
+ * runTransformerChain -> then call transformerPush on the main transformer.
  *
  * This mirrors the logic in simulateTransformer without requiring
  * a real ESM bundle.
@@ -112,10 +156,7 @@ describe('transformer simulation isolation — before chain', () => {
 
     // Step 1: Resolve before chain
     const before = transformer.config.before;
-    const beforeChainIds = walkChain(
-      staticChain(before),
-      extractTransformerNextMap(transformers),
-    );
+    const beforeChainIds = resolveChain(before, transformers);
     expect(beforeChainIds).toEqual(['enrich']);
 
     // Step 2: Run before chain
@@ -242,10 +283,7 @@ describe('transformer simulation isolation — before chain', () => {
 
     // Resolve before chain
     const before = transformer.config.before;
-    const beforeChainIds = walkChain(
-      staticChain(before),
-      extractTransformerNextMap(transformers),
-    );
+    const beforeChainIds = resolveChain(before, transformers);
     expect(beforeChainIds).toEqual(['gate']);
 
     // Run before chain — gate drops the event
@@ -313,10 +351,7 @@ describe('transformer simulation isolation — before chain', () => {
 
     // Resolve before chain — should follow validate -> enrich via next link
     const before = transformer.config.before;
-    const beforeChainIds = walkChain(
-      staticChain(before),
-      extractTransformerNextMap(transformers),
-    );
+    const beforeChainIds = resolveChain(before, transformers);
     expect(beforeChainIds).toEqual(['validate', 'enrich']);
 
     // Run before chain
@@ -488,10 +523,7 @@ describe('destination simulation with before chain', () => {
     const before = destination.config.before;
     let processedEvent: WalkerOS.Event = inputEvent;
     if (before && collector.transformers) {
-      const beforeChainIds = walkChain(
-        staticChain(before),
-        extractTransformerNextMap(collector.transformers),
-      );
+      const beforeChainIds = resolveChain(before, collector.transformers);
       expect(beforeChainIds).toEqual(['enrich']);
 
       const beforeResult = await runTransformerChain(
@@ -564,10 +596,7 @@ describe('destination simulation with before chain', () => {
 
     // Resolve and run before chain
     const before = destination.config.before;
-    const beforeChainIds = walkChain(
-      staticChain(before),
-      extractTransformerNextMap(collector.transformers!),
-    );
+    const beforeChainIds = resolveChain(before, collector.transformers!);
     expect(beforeChainIds).toEqual(['gate']);
 
     const beforeResult = await runTransformerChain(

packages/cli/src/commands/push/index.ts

@@ -3,16 +3,13 @@ import fs from 'fs-extra';
 import {
   createIngest,
   getPlatform,
-  compileNext,
-  resolveNext,
+  getNextSteps,
   buildCacheContext,
 } from '@walkeros/core';
 import {
   transformerInit,
   transformerPush,
   runTransformerChain,
-  walkChain,
-  extractTransformerNextMap,
   wrapEnv,
 } from '@walkeros/collector';
 import { createCLILogger } from '../../core/cli-logger.js';
@@ -46,24 +43,66 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object';
 }
 
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+/**
+ * Walk a transformer chain via static `.next` links starting at `startId`.
+ * Mirrors the collector's internal `walkChain` for the case where the
+ * simulator already knows the entry-point id and the underlying chain is
+ * static. Conditional `.next` shapes terminate the walk at this hop.
+ */
+function walkStaticChain(
+  startId: string,
+  transformers: import('@walkeros/core').Transformer.Transformers,
+): string[] {
+  const chain: string[] = [];
+  const visited = new Set<string>();
+  let current: string | undefined = startId;
+
+  while (current && transformers[current]) {
+    if (visited.has(current)) break;
+    visited.add(current);
+    chain.push(current);
+
+    const next: import('@walkeros/core').Transformer.Route | undefined =
+      transformers[current].config?.next;
+    if (typeof next === 'string') {
+      current = next;
+      continue;
+    }
+    if (Array.isArray(next) && next.every(isString)) {
+      chain.push(...next);
+      break;
+    }
+    // Conditional / undefined → terminate walk.
+    break;
+  }
+
+  return chain;
+}
+
 /**
  * Resolve a before chain config to an ordered array of transformer IDs.
- * All Route shapes (string, sequence, RouteConfig) go through compileNext +
- * resolveNext; the engine handles narrowing.
+ * Uses `getNextSteps` for the entry points and follows static `.next`
+ * links via `walkStaticChain`.
  */
 function resolveBeforeChain(
-  before: import('@walkeros/core').Transformer.RouteSpec | undefined,
+  before: import('@walkeros/core').Transformer.Route | undefined,
   transformers: import('@walkeros/core').Transformer.Transformers,
   ingest?: import('@walkeros/core').Ingest,
   event?: WalkerOS.DeepPartialEvent,
 ): string[] {
   if (!before) return [];
-  const resolved = resolveNext(
-    compileNext(before),
-    buildCacheContext(ingest, event),
-  );
-  if (!resolved) return [];
-  return walkChain(resolved, extractTransformerNextMap(transformers));
+  // Explicit string[] chain — use as-is.
+  if (Array.isArray(before) && before.every(isString)) {
+    return before;
+  }
+  const ids = getNextSteps(before, buildCacheContext(ingest, event));
+  if (ids.length === 0) return [];
+  if (ids.length === 1) return walkStaticChain(ids[0], transformers);
+  return ids;
 }
 
 /**