Custom operators

A custom operator is a function the kernel didn't ship with that you've taught the framework to call. After derivation it sits in the same catalogue as QM1 (Schrödinger), NM19 (Newton's second law) and GR32 (Einstein tensor) — addressable by ID, callable from /api/zeq/compute, referenceable from any state contract.

The 5-step DERIVE → VERIFY → REGISTER protocol

POST /api/zeq/agent/operators/derive runs the framework's canonical 5-step protocol. Every step has a literal kernel meaning — this is not bureaucracy.

Step	What happens
1. DECOMPOSE	Break the desired computation into terms expressible in existing operators. The kernel walks the catalogue for matches.
2. MAP	Bind each term to a parent operator. The new operator inherits its parents' precision bounds and unit dimensions.
3. DERIVE	Compose the formula. KO42 (the metric tensioner) is auto-applied as the carrier — your operator is phase-locked to the 1.287 Hz HulyaPulse from the moment it exists.
4. VERIFY	Run ≥3 reference cases. If any case exceeds the precision bound (0.001 = 0.1%) the operator is rejected; nothing persists.
5. REGISTER	The verified operator is written to `derived_operators` with its proof digest, the cases that verified it, the achieved precision, and the parent-operator graph.

Calling derive

The request:

curl -X POST https://zeqapi.com/api/zeq/agent/operators/derive \
  -H "Authorization: Bearer zeq_ak_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "computation_needed": "Convert BTU to kWh with kernel-grade precision",
    "domain": "thermodynamics",
    "parent_operators": ["NM23"],
    "hulyas_coupling": true,
    "generation": 1
  }'

computation_needed is plain-language — the framework's wizard runs over it to pick a formula shape. domain aligns the new operator to one of the 64 catalogue domains. parent_operators is an array of existing operator IDs whose precision bounds the new operator must respect. hulyas_coupling: true enables the HulyaPulse term in the master equation — recommended for any operator that should phase-lock to the framework clock.

The response:

{
  "operator_id": "BTU2KWH",
  "name": "BTU2KWH · BTU → kWh conversion",
  "formula": "E_kWh = E_BTU · 2.93071e-4 · (1 + α sin(2π·1.287·t))",
  "domain": "thermodynamics",
  "parent_operators": ["NM23"],
  "hulyas_terms_active": ["sin(2π·1.287·t)"],
  "verification": {
    "passed": true,
    "precision": 0.00008,
    "test_cases": [
      { "input": { "E_BTU": 1000 }, "expected": 0.293071, "got": 0.29307123, "err": 0.0000079 },
      { "input": { "E_BTU": 50000 }, "expected": 14.6536, "got": 14.6535912, "err": 0.0000060 },
      { "input": { "E_BTU": 1 }, "expected": 0.000293071, "got": 0.000293074, "err": 0.0000102 }
    ]
  },
  "proof_digest": "sha256:7c4a8d09ca3762af61e59520943dc26494f8941b",
  "registered": true,
  "zeqond": 2289379200
}

The ZEQ cost is 50 — derivation runs real verification work and pays for itself out of your balance. If the precision gate fails, registered: false is returned and nothing persists; you can adjust computation_needed and try again without spending more.

Promotion

A derived operator is callable from your machine's compute calls immediately. To become part of the public catalogue (so other state machines can use it too) it must be promoted:

curl -X POST https://zeqapi.com/api/zeq/agent/operators/promote \
  -H "Authorization: Bearer zeq_ak_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "operator_id": "BTU2KWH" }'

The promote endpoint enforces a fitness criterion: the operator must have run successfully ≥3 times at ≤0.1% precision since registration. Once promoted it shows up in GET /api/operators and the wizard's operator picker.

Calling a custom operator

After promotion (or directly, from the owning state machine) the operator behaves exactly like a built-in:

curl -X POST https://zeqapi.com/api/zeq/compute \
  -H "Authorization: Bearer zeq_ak_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "thermodynamics",
    "ops": ["KO42", "BTU2KWH"],
    "inputs": { "E_BTU": 1000 }
  }'

The response carries the same CKO envelope (compliance, kernel URL, explorer URL, zeq-proof) that built-in operator calls return. Your custom operator is now indistinguishable from QM1 to anything downstream.

The precision gate is not optional

KO42 is locked at the top of every derived operator's parent set. The master equation's Σ C_k(φ) term sums kinematic operators with the metric tensioner as the carrier — this is what makes the precision bound enforceable. You cannot derive an operator that bypasses KO42; the protocol rejects it.

This is also why precision is the only verification gate. The framework doesn't ask whether your operator is "useful" or "novel" — those are subjective. It asks whether the math runs at ≤0.1% error against the reference cases you supplied. Subjective questions live outside the kernel; objective ones live inside it.

Querying your derived operators

GET /api/zeq/agent/operators?agent_id=<your-agent-uuid>

Returns the full list of operators derived under one agent, with proof digests and promotion status. The kernel never garbage-collects derived operators — they're part of your machine's audit trail.

Continue to Custom protocols to wire external data sources, or jump straight to Wiring to a state machine to use your new operator in a contract.

The 5-step DERIVE → VERIFY → REGISTER protocol​

Calling derive​

Promotion​

Calling a custom operator​

The precision gate is not optional​

Querying your derived operators​

Next​