Handler Scaffold Gen

Step-by-Step Process

Step 1: Register Generator

Self-register with PluginRegistry so KindSystem can track HandlerConfig → HandlerImpl transformations. Registration is also handled automatically by register-generator-kinds.sync.

Examples: Register the handler scaffold generator

const result = await handlerScaffoldGenHandler.register({}, storage);

Step 2: Preview Changes

Dry-run the generation using Emitter content-addressing to classify each output file as new, changed, or unchanged. No files are written.

Arguments: $0 conceptName (string), $1 actions (actiondef[])

Step 3: Generate Handler Implementation

Generate a handler implementation with typed action methods , input extraction , and storage patterns . Defaults to functional ( StorageProgram ) style ; pass style = imperative for the imperative fallback . Optionally generates a conformance test .

Arguments: $0 conceptName (string), $1 actions (actiondef[]), $2 style (string)

Checklist:

• Handler export name follows convention (camelCase + 'Handler')?
• register() returns correct name, inputKind, outputKind?
• Each action extracts input parameters with correct types?
• Each action returns all declared variants?
• Storage operations use correct relation names?
• No bindAs names referenced as JavaScript variables (must use bindings lambdas)?
• All storage-dependent values use *From variants (putFrom, mergeFrom, completeFrom)?
• All conditionals on storage data use branch() with bindings lambda (not if/else)?
• Error handling catches and wraps exceptions?
• Every error-case fixture in the spec has a matching validation guard in the handler?
• Empty/missing required params return error variant (not ok)?
• Conformance test covers register() and each action?
• All files written through Emitter (not directly to disk)?
• Source provenance attached to each file?
• Generation step recorded in GenerationPlan?

Examples: Generate a handler

clef scaffold handler --concept User --actions create,update,delete

Generate with test only

clef scaffold handler --concept Article

Step 4: Edit the Handler Implementation

Refine the generated handler. Default style is FUNCTIONAL (StorageProgram): 1. Each action returns a StorageProgram<A> built with DSL functions: createProgram(), get(), find(), put(), merge(), del(), branch(), complete(), pure(). 2. CRITICAL — put() vs putFrom(): Use put(p, rel, key, value) ONLY when value is fully known at construction time (static data, input parameters). Use putFrom(p, rel, key, (bindings) => value) when value depends on data read from storage via get()/find(). Same applies to merge() vs mergeFrom(), and complete() vs completeFrom(). The bindings parameter is a Record<string,unknown> containing all values bound by prior get()/find()/mapBindings() calls. Never reference a bindAs name as a direct variable — always access it through the bindings object. 3. Use mapBindings(p, (bindings) => derivedValue, 'bindAs') to derive new values from accumulated bindings (e.g. computing a count, filtering, sorting). 4. For external API calls (HTTP, gRPC, GraphQL, WebSocket): use perform(p, 'http', 'POST', { endpoint: 'name', path, body }, 'bindAs'). This routes through the execution layer: EffectHandler → ExternalCall → HttpProvider → instance endpoint. Create a Tier 3 instance provider concept (like OpenAiEndpoint, VercelApiEndpoint) for each specific API. 5. For local computation (ONNX, WASM, shell): use perform(p, 'onnx', 'infer', { session: 'name', inputs }, 'bindAs'). Routes through: EffectHandler → LocalProcess → OnnxProvider/WasmProvider → instance. Create a LocalModelInstance for each model. 6. NEVER use direct fetch(), execSync(), or other I/O. All external/internal calls go through perform() so they get: ConnectorCall tracking, RetryPolicy, CircuitBreaker, RateLimiter, PerformanceProfile, ErrorCorrelation, RuntimeCoverage — automatically via sync wiring. 7. Use branch() for conditionals (not if/else), complete() for terminal values. 8. Lens-based access with getLens(), putLens(), modifyLens() where possible. Imperative style (ConceptHandler with async methods) is ONLY for handlers requiring direct filesystem access (e.g. EmbeddingCache).

References

• Handler implementation patterns

Supporting Materials

• Handler implementation scaffolding walkthrough

Quick Reference

Anti-Patterns

Missing error variant

Handler doesn't return error variant on failure — caller gets an unstructured exception.

Bad:

async create(input, storage) {
  const id = crypto.randomUUID();
  await storage.put('items', id, { name: input.name });
  return { variant: 'ok', item: id };
  // Exception propagates raw if storage.put fails!
}

Good:

async create(input, storage) {
  try {
    const id = crypto.randomUUID();
    await storage.put('items', id, { name: input.name });
    return { variant: 'ok', item: id };
  } catch (err) {
    return { variant: 'error', message: String(err) };
  }
}

_variant convention (DOES NOT WORK)

Returning { _variant: 'notfound' } from a completeFrom callback does NOT change the variant. The variant is always the second argument to completeFrom. The _variant field is just ignored data in the output.

Bad:

return completeFrom(p, 'ok', (bindings) => {
  const entry = all.find(...);
  if (!entry) return { _variant: 'notfound' };  // BROKEN: variant is still 'ok'
  return { handler: entry.id };
});

Good:

p = mapBindings(p, (b) => (b.all as any[]).find(...) || null, '_found');
return branch(p,
  (b) => !!b._found,
  (b) => completeFrom(b, 'ok', (b) => ({ handler: (b._found as any).id })),
  (b) => complete(b, 'notfound', {}),
);

_puts convention (DOES NOT WORK)

Returning { _puts: [{ rel, key, value }] } from a completeFrom callback does NOT write to storage. The interpreter treats completeFrom results as terminal pure values — it never inspects _puts.

Bad:

return completeFrom(p, 'ok', (bindings) => ({
  variant: 'ok',
  _puts: [{ rel: 'items', key: 'abc', value: record }],
  item: id,
}));

Good:

let p2 = putFrom(p, 'items', 'abc', (b) => record);
return completeFrom(p2, 'ok', (b) => ({ item: id }));

Dynamic storage keys in functional style

putFrom(p, rel, key, fn) requires key to be a static string known at build time. If the key is computed at runtime (e.g., a generated UUID), you MUST use imperative style for that action. Mix functional and imperative via autoInterpret + override.

Bad:

// Cannot use a dynamic key with putFrom
p = putFrom(p, 'items', generatedId, (b) => record);

Good:

const baseHandler = autoInterpret(_handler);
const handler = { ...baseHandler,
  async myAction(input, storage) {
    const id = generateId();
    await storage.put('items', id, record);
    return { variant: 'ok', item: id };
  },
};

Actions requiring stateful engine calls

If an action needs to call methods on a stateful class instance (e.g. SyncEngine, Parser), it cannot be expressed as a pure StorageProgram. Use imperative style for those specific actions while keeping other actions functional.

Validation

Generate a handler scaffold:

npx tsx cli/src/index.ts scaffold handler --concept User --actions create,update,delete

Run generated conformance test:

npx vitest run tests/user.conformance.test.ts

Generate tests from invariants:

npx tsx cli/src/index.ts test-gen --concept User --language typescript

Run scaffold generator tests:

npx vitest run tests/scaffold-generators.test.ts

Related Skills