Why operators (not custom code)

A Glyph flow is a graph of operators, not a graph of arbitrary user code. An operator is a typed unit declared by a JSON schema (/opt/glyph/schemas/operators/*.json) — its id, version, input ports, output ports, config schema, secret references, retry policy, idempotency. The backend implements each operator by id; the frontend renders each operator from the same schema.

What this buys

• Static graph validation. Every edge connects two known port types. Bad wiring is a build-time error in the canvas, not a runtime exception.
• Replay determinism. Operators declare their idempotency. The DAG executor can checkpoint after each operator and resume cleanly because operators are pure over their inputs (or explicit about their side effects via secretRefs).
• A single registry. Adding an operator is one schema file plus one Rust handler. The catalog page in these docs auto-renders from the same schemas, so what you see is what you can use.
• AI assistance is feasible. Because every operator carries semantic typing, graph-from-text generation can confidently emit correct flows. With arbitrary code there is no signal to ground the model.
• Versioning works. Each operator carries a version field. The compiler can refuse to run a graph if any operator has been bumped to a major version that breaks port shapes, and offers an automatic upgrade for safe bumps.

What this costs

• No escape hatch (yet). If a behaviour does not exist as an operator, you cannot just write a lambda. The escape hatch is the code.sandbox operator (schemas/operators/code.sandbox.json) — sandboxed JS in a worker — which is a pressure-release valve, not a primary tool.
• Adding a new operator is a backend change. It cannot be done from the canvas. By design — see “Versioning operators safely”.
• The operator surface has to grow with use cases. ~78 operators across 24 families ship today — every family declared under schemas/operators/ has a real handler in the executor. New use cases still require a backend change to add a schema + handler.

When this design is right

When the goal is correctness, replay, and AI assistance over freedom, this is the right design. When the goal is “Turing-complete IDE for power users,” it is not. Glyph commits to the first and is honest about the trade.

See The operator contract for the technical surface, and Operator families and naming for the taxonomy.